agl 40.4.0 → 40.5.1

package/ts/classes.inferencerouter.ts

@@ -2,6 +2,7 @@ import * as plugins from './plugins.js';
 import type { TInferenceCredential, TInferenceProvider } from './functions.proxycontract.js';
 import type { IGatewayAuthorityAccess } from './classes.flexaccountaccess.js';
 import { FlexServiceError } from './interfaces.flexipc.js';
+import type { IInferenceSpendRecord } from './classes.inferencespend.js';
 
 export type TInferenceModel = plugins.openAiProvider.IOpenAiChatGptModel;
 /** A model a Claude account or an Anthropic API key may use, as the Anthropic API lists it. */
@@ -57,31 +58,52 @@ export const inferenceRetryAfterSeconds = (valueArg: string | null, nowArg: numb
   return at === undefined ? undefined : Math.max(0, Math.ceil((at - nowArg) / 1000));
 };
 
+/**
+ * The credential tiers a pool is served from, best first: the one a policy names alone, or with none the provider's
+ * subscription sign-ins first and its API keys after them. A key takes a request only when no subscription can take it,
+ * for whatever reason, and a session placed on a key returns to a subscription at the next request one can take.
+ */
+export const inferenceCredentialTiers = (credentialArg: TInferenceCredential | undefined): readonly TInferenceCredential[] =>
+  credentialArg ? [credentialArg] : ['subscription', 'api_key'];
+
 export interface IInferenceAccount {
   id: string;
   label: string;
   revision: string;
   providerId: TInferenceProvider;
-  /** What the account authenticates with: a subscription sign-in, or an Anthropic API key. */
+  /** What the account authenticates with: a subscription sign-in, or an API key. */
   credential: TInferenceCredential;
   /** The account's usage threshold (`IAuthSwitchAccount.maxUsagePercent`); `null` when unset. */
   maxUsagePercent: number | null;
   reserveLiftUntil: string | null;
   /** When the account's subscription ends (`IAuthSwitchAccount.lapsesAt`); `null` while it renews. */
   lapsesAt: string | null;
+  /**
+   * An API key's monthly spend limit in micro-dollars (`IAuthSwitchAccount.spendLimitMicroUsd`); `null` without one,
+   * and for a sign-in. It decides only whether a key whose spend the proxy holds no reading of may take work: one with
+   * a limit may not (`spend_unread`). A spend reading carries the limit the key is judged against.
+   */
+  spendLimitMicroUsd: number | null;
+  /**
+   * The login the account's requests are served on (the account service's gateway login of it), as the pool was read;
+   * `null` when the account service names none. An API key's spend is reported on it.
+   */
+  loginId: string | null;
 }
 
 export interface IInferenceRoutingPolicy {
   /** The pool's provider; omitted means ChatGPT accounts (`openai`). */
   provider?: TInferenceProvider;
   /**
-   * What the pool's accounts authenticate with; omitted means subscription sign-ins. `api_key` is an Anthropic pool's
-   * alone: its Anthropic API keys, which Flex's Claude models run on, never a Claude account.
+   * What the pool's accounts authenticate with. Omitted, a Claude pool is served by its Claude accounts first and its
+   * Anthropic API keys when no Claude account can take a request (`inferenceCredentialTiers`), a ChatGPT pool by its
+   * ChatGPT accounts. `subscription` names the sign-ins alone; `api_key` is an Anthropic pool's alone: its Anthropic API
+   * keys, which Flex's Claude models run on, never a Claude account.
    */
   credential?: TInferenceCredential;
   /** Omitted means all eligible authority-owned accounts of the provider. */
   accountIds?: readonly string[];
-  /** Exact current provider plan names; omission accepts every entitled plan. */
+  /** Exact current provider plan names; omission accepts every entitled plan. A key has no plan, so this leaves keys out. */
   plans?: readonly string[];
 }
 
@@ -108,19 +130,61 @@ export interface IInferenceRouterOptions {
    */
   reportAccount?: (changeArg: IInferenceAccountChange) => void;
   /**
-   * Tells the account service that Anthropic refused a request on the Claude account with a billing error (HTTP 402
-   * `billing_error`) at `observedAtArg`; resolves once the service holds it, so the account's usage carries it from then
-   * on (`IAuthSwitchUsageSnapshot.paymentProblem`). Unset, the router holds the account out of rotation itself.
+   * Tells the account service that the provider refused a request on the account for a payment problem at
+   * `observedAtArg` -- a Claude account's billing error (HTTP 402 `billing_error`), or an API key's refusal for
+   * `causeArg` (`TInferencePaymentCause`); resolves once the service holds it, so the account's usage carries it from
+   * then on (`IAuthSwitchUsageSnapshot.paymentProblem`). Unset, the router holds the account out of rotation itself.
    */
-  reportPaymentProblem?: (accountIdArg: string, observedAtArg: string) => Promise<void>;
+  reportPaymentProblem?: (accountIdArg: string, observedAtArg: string, causeArg: TInferencePaymentCause) => Promise<void>;
   /**
    * Where a payment problem the account service could not be told of is reported: once per account, never per request.
    * One line on standard error, the proxy's journal, when unset.
    */
   reportPaymentFailure?: (failureArg: IInferencePaymentReportFailure) => void;
+  /**
+   * Where the spend of the answers relayed on API keys is kept until the accounts service acknowledged it
+   * (`InferenceSpendOutbox`). A key's usage arrives judged with that spend already (`InferenceUsageCache` `view`).
+   */
+  spend?: IInferenceSpendLedger;
   now?: () => number;
 }
 
+/** What the router asks of the proxy's spend outbox (`InferenceSpendOutbox`). */
+export interface IInferenceSpendLedger {
+  /**
+   * Counts a relayed answer's spend and keeps it until the accounts service acknowledged it, reported on the login the
+   * route was served on (`IInferenceClaudeRoute.loginId`); `null` when none could be named, which still counts.
+   */
+  record(accountIdArg: string, loginIdArg: string | null, recordArg: IInferenceSpendRecord): void;
+  /**
+   * Whether spend relayed on the key is recorded nowhere yet: the accounts service refused a report the outbox still
+   * holds, an answer is in neither the outbox's store, whose write failed, nor the ledger, or no login of the key could
+   * be named for an answer, so it cannot be reported.
+   */
+  held(accountIdArg: string): boolean;
+  /** Says that an answer relayed on the key ended before its provider stated its usage, so nothing of it is counted. */
+  uncounted(accountIdArg: string, modelArg: string): void;
+}
+
+/** A payment problem the router holds an account out of rotation for: since `at`, for `cause`, until `until` (`null`: no end). */
+interface IPaymentMark {
+  at: number;
+  cause: TInferencePaymentCause;
+  until: number | null;
+}
+
+/**
+ * What a payment problem's report adds for the account service (`IReq_AuthSwitchReportPaymentProblem`): the cause of an
+ * API key's spend cap or quota, nothing for a billing error, whose cause a missing one means -- so a Claude account's
+ * report is the one an accounts service of 40.3.0, which refuses a cause, takes.
+ */
+export const inferencePaymentReportOptions = (causeArg: TInferencePaymentCause):
+{ cause?: Exclude<TInferencePaymentCause, 'billing'> } => causeArg === 'billing' ? {} : { cause: causeArg };
+
+/** A payment mark as the refusal it makes. */
+const paymentUnavailable = (markArg: IPaymentMark): IInferenceAccountUnavailable => ({ reason: 'payment_problem',
+  cause: markArg.cause, ...(markArg.until === null ? {} : { retryAt: new Date(markArg.until).toISOString() }) });
+
 /** A payment problem the account service could not be told of, as the proxy reports it: the account by its id's digest. */
 export interface IInferencePaymentReportFailure {
   /** The first 12 hex characters of the SHA-256 digest of the account's id. */
@@ -131,27 +195,62 @@ export interface IInferencePaymentReportFailure {
 
 const writePaymentReportFailure = (failureArg: IInferencePaymentReportFailure): void => {
   process.stderr.write(`AGL proxy could not tell the account service of the payment problem of account `
-    + `${failureArg.account}, so it keeps the account out of rotation until it restarts: ${failureArg.error}\n`);
+    + `${failureArg.account}, so it keeps the account out of rotation until it restarts, or a spend cap ends: `
+    + `${failureArg.error}\n`);
 };
 
 /**
  * Why an account takes no request although no limit says so. `usage_unread`: the account service holds no usage reading
  * the proxy routes on. `catalog_failed`: the account's model list could not be read and none read before is held for its
  * revision. `needs_login`: its sign-in needs renewing. `access_failed`: the account service answered no access for it.
- * `model_missing`: its model list lacks the requested model. `payment_problem`: Anthropic refused a request on the Claude
- * account with a billing error (HTTP 402 `billing_error`); it takes none until a usage read or a re-check clears it.
+ * `model_missing`: its model list lacks the requested model. `payment_problem`: the provider refused a request on the
+ * account for a payment problem (`TInferencePaymentCause`); it takes none until a usage read or a re-check clears it, or
+ * a spend cap ends. `spend_unread`: an API key with a monthly spend limit whose spend the proxy holds no reading of --
+ * the account service could not read its ledger (`spend_unavailable`) or did not answer -- so it may be at its limit.
+ * `spend_unrecorded`: an API key with a monthly spend limit whose spend the proxy relayed is recorded nowhere yet --
+ * the account service refused its report, which the proxy holds to send again, an answer is held in neither the
+ * proxy's store, whose write failed, nor the account service's ledger, or no login of the key could be named for an
+ * answer to report it on (`InferenceSpendOutbox.held`). `model_unpriced`: an API key with a monthly spend limit, and a
+ * request whose model, service tier, speed, region or server tool the proxy's price table cannot price (`failure` names
+ * it), so its cost could not be counted against the limit.
  */
 export type TInferenceUnavailableReason = 'usage_unread' | 'catalog_failed' | 'needs_login' | 'access_failed'
-  | 'model_missing' | 'payment_problem';
+  | 'model_missing' | 'payment_problem' | 'spend_unread' | 'spend_unrecorded' | 'model_unpriced';
+
+/**
+ * Why a provider refused a request on an account for a payment problem, as the gateway reads the provider's answer.
+ * `billing`: Anthropic's billing error (HTTP 402 `billing_error`), on a Claude account's subscription or an Anthropic API
+ * key's organization. `spend_cap`: an Anthropic API key's organization reached its usage tier's monthly spend cap (HTTP
+ * 429 `rate_limit_error` with `error.details.error_code: "enforced_spend_limit_reached"`), which holds until 00:00 UTC on
+ * the first day of the next month. `quota`: OpenAI refused an API key for its quota (HTTP 429 `insufficient_quota`): no
+ * prepaid credit left, or an organization or project spend limit or the organization's usage limit reached.
+ */
+export type TInferencePaymentCause = plugins.authswitchAuthority.TAuthSwitchPaymentProblemCause;
 
 export interface IInferenceAccountUnavailable {
   reason: TInferenceUnavailableReason;
-  /** `usage_unread`: when the account service reads the account's usage next, or `null` when it does not say. */
+  /**
+   * `usage_unread`: when the account service reads the account's usage next, or `null` when it does not say.
+   * `payment_problem` of a spend cap: when the cap ends and the account takes requests again.
+   */
   retryAt?: string | null;
-  /** `catalog_failed`: the HTTP status the model list answered with (`HTTP 429`), or what failed instead. */
+  /**
+   * `catalog_failed`: the HTTP status the model list answered with (`HTTP 429`), or what failed instead.
+   * `model_unpriced`: what of the request the price table cannot price.
+   */
   failure?: string;
+  /** `payment_problem`: what the provider refused the account for. */
+  cause?: TInferencePaymentCause;
 }
 
+/** A payment problem in words, as the status, the journal line and a pinned refusal state it. */
+const paymentProblemText = (unavailableArg: IInferenceAccountUnavailable): string =>
+  unavailableArg.cause === 'spend_cap' ? 'Anthropic refused a request on it: its organization reached its usage tier\'s '
+    + `monthly spend cap (HTTP 429)${unavailableArg.retryAt ? `; it takes requests again at ${unavailableArg.retryAt}` : ''}`
+    : unavailableArg.cause === 'quota' ? 'OpenAI refused a request on it for its quota (HTTP 429 insufficient_quota): no '
+      + 'prepaid credit left, or a spend or usage limit reached'
+      : 'Anthropic refused a request on it with a billing error (HTTP 402), a payment problem';
+
 /** A change of why an account is refused, as the proxy reports it: the account by its id's digest, never its id. */
 export interface IInferenceAccountChange {
   /** The first 12 hex characters of the SHA-256 digest of the account's id. */
@@ -171,9 +270,16 @@ const unavailableText = (unavailableArg: IInferenceAccountUnavailable): string =
     : unavailableArg.reason === 'catalog_failed' ? `its model list could not be read (${unavailableArg.failure})`
       : unavailableArg.reason === 'needs_login' ? 'it needs a fresh sign-in'
         : unavailableArg.reason === 'access_failed' ? 'the account service answered no access for it'
-          : unavailableArg.reason === 'payment_problem'
-            ? 'Anthropic refused a request on it with a billing error (HTTP 402), a payment problem'
-            : 'its model list lacks the requested model';
+          : unavailableArg.reason === 'payment_problem' ? paymentProblemText(unavailableArg)
+            : unavailableArg.reason === 'spend_unread'
+              ? 'it has a monthly spend limit, and its spend could not be read, so it might be at it'
+              : unavailableArg.reason === 'spend_unrecorded'
+                ? 'it has a monthly spend limit, and spend the proxy relayed on it is not recorded yet -- the account service '
+                  + 'refused its report, or neither the proxy\'s store nor the account service took an answer -- so it might '
+                  + 'be at it'
+                : unavailableArg.reason === 'model_unpriced'
+                  ? `it has a monthly spend limit, and ${unavailableArg.failure ?? 'the request'} has no price`
+                  : 'its model list lacks the requested model';
 
 const writeAccountChange = (changeArg: IInferenceAccountChange): void => {
   process.stderr.write(`AGL proxy account ${changeArg.account}: ${changeArg.unavailable === null
@@ -213,6 +319,38 @@ const cooldownUntil = (cooldownArg: ICooldown | undefined,
  */
 export type TInferenceAccountLimit = 'exhausted' | 'reserved' | 'cooling';
 
+/** An API key a request found held by its monthly spend limit: the account, and its month as the account service read it. */
+export interface IInferenceSpendLimited {
+  accountId: string;
+  label: string;
+  spend: plugins.authswitchSpend.IAuthSwitchSpendReading;
+}
+
+/**
+ * A key's month in words, from its spend reading: `$12.40 of $50.00 this month`, or `$12.40 this month, no spend limit`,
+ * and how many answers could not be priced, when any.
+ */
+const spendText = (spendArg: plugins.authswitchSpend.IAuthSwitchSpendReading): string => {
+  const usd = plugins.authswitchSpend.authSwitchUsdText;
+  const unpriced = spendArg.unpricedAnswers === 0 ? ''
+    : `, ${spendArg.unpricedAnswers} ${spendArg.unpricedAnswers === 1 ? 'answer' : 'answers'} of it could not be priced`;
+  return `${usd(spendArg.spentMicroUsd)} ${spendArg.limitMicroUsd === null ? 'this month, no spend limit'
+    : `of ${usd(spendArg.limitMicroUsd)} this month`}${unpriced}`;
+};
+
+/**
+ * What a refusal says of the API keys it found held by their monthly spend limit: each key with its month, and when the
+ * first of them takes requests again. Empty without any.
+ */
+export const inferenceSpendLimitText = (keysArg: readonly IInferenceSpendLimited[]): string => {
+  const keys = [...new Map(keysArg.map((keyArg) => [keyArg.accountId, keyArg])).values()];
+  if (!keys.length) return '';
+  const resetAt = keys.map((keyArg) => keyArg.spend.resetAt).sort()[0];
+  const named = keys.map((keyArg) => `${keyArg.label} (${spendText(keyArg.spend)})`).join(', ');
+  return `${keys.length === 1 ? 'The API key' : 'The API keys'} ${named} ${keys.length === 1 ? 'is' : 'are'} held by the `
+    + `monthly spend limit set in AGL until ${resetAt}.`;
+};
+
 export class InferenceRoutingError extends Error {
   constructor(public readonly status: number, public readonly code: string, messageArg: string,
     public readonly retryAfterSeconds?: number,
@@ -222,11 +360,21 @@ export class InferenceRoutingError extends Error {
     public readonly accountLimit?: TInferenceAccountLimit,
     /** The account a refusal for a reason of its own (`reason`) names. */
     public readonly accountId?: string,
-    /** For `no_eligible_accounts` of a pinned account: why that account takes no request, though no limit says so. */
-    public readonly reason?: TInferenceUnavailableReason) {
+    /**
+     * For `no_eligible_accounts` of a pinned account: why that account takes no request though no limit says so, in
+     * full -- a payment problem's cause, say.
+     */
+    public readonly unavailable?: IInferenceAccountUnavailable,
+    /** For `accounts_exhausted`: the API keys found held by their monthly spend limit, which its message names. */
+    public readonly spendLimited: readonly IInferenceSpendLimited[] = []) {
     super(messageArg);
     this.name = 'InferenceRoutingError';
   }
+
+  /** The reason of `unavailable`: a refusal names a reason of its own only with the refusal in full. */
+  public get reason(): TInferenceUnavailableReason | undefined {
+    return this.unavailable?.reason;
+  }
 }
 
 /**
@@ -237,14 +385,29 @@ const needsSignIn = (errorArg: unknown): boolean =>
   (errorArg instanceof InferenceRoutingError && errorArg.code === 'account_needs_login')
   || (errorArg instanceof FlexServiceError && errorArg.code === 'PROVIDER_REAUTH_REQUIRED');
 
+/**
+ * A ChatGPT account or an OpenAI API key chosen for one request: a ChatGPT sign-in through the ChatGPT backend, a key
+ * through OpenAI's API (`OPENAI_API_BASE_URL`), each through `connection`.
+ */
 export interface IInferenceRoute {
   provider: 'openai';
+  /** What the chosen account authenticates with: a ChatGPT sign-in, or an OpenAI API key. */
+  credential: TInferenceCredential;
   accountId: string;
   plan: string;
   /** The account's placement score when it was chosen (`IAuthSwitchPlacement.score`). */
   score: number | null;
   model: TInferenceModel;
   connection: plugins.openAiProvider.IOpenAiModelConnection;
+  /** The session left its account on a later credential tier for one of a better tier (`returnToBetterTier`). */
+  returned: boolean;
+  /** The login the account was served on as the pool was read (`IInferenceAccount.loginId`): an answer's spend names it. */
+  loginId: string | null;
+  /**
+   * An OpenAI API key with a monthly spend limit: the request goes out as the price check read it, on the service tier it
+   * was checked for (`inferenceOpenAiCheckedBytes`).
+   */
+  spendLimit: boolean;
   release: () => void;
 }
 
@@ -261,6 +424,18 @@ export interface IInferenceClaudeRoute {
   score: number | null;
   model: TInferenceClaudeModel;
   connection: plugins.anthropicProvider.IAnthropicModelConnection;
+  /**
+   * The session's account is an Anthropic API key, and a Claude account of a better credential tier took the request
+   * instead (`returnToBetterTier`): the session returns to it.
+   */
+  returned: boolean;
+  /** The login the account was served on as the pool was read (`IInferenceAccount.loginId`): an answer's spend names it. */
+  loginId: string | null;
+  /**
+   * An Anthropic API key with a monthly spend limit: the request goes out as the price check read it, on the standard
+   * service tier only (`inferenceAnthropicCheckedBytes`), the one the price table prices.
+   */
+  spendLimit: boolean;
   release: () => void;
 }
 
@@ -271,55 +446,94 @@ interface ICatalog<TModel> {
 }
 
 /**
- * How long a Claude account's model list is used before it is read again, and how long a failed model-list read or a
- * failed sign-in holds before the next read: a sign-in does not heal itself, and a new one changes the account's revision.
+ * How long an account's model list -- a Claude account's, an Anthropic or an OpenAI API key's -- is used before it is read
+ * again, and how long a failed model-list read or a failed sign-in holds before the next read: a sign-in does not heal
+ * itself, and a new one changes the account's revision.
  */
-const claudeCatalogMs = 60_000;
+const modelListMs = 60_000;
 
 /**
- * How long a Claude account whose access failed for a reason other than sign-in is refused before access is tried again.
+ * How long an account whose access failed for a reason other than sign-in is refused before access is tried again.
  * Such a failure is usually a brief outage of the local account service: retries stay bounded to one per account per 5 s
  * without turning a short outage into a minute of refusals.
  */
-const claudeAccessRetryMs = 5_000;
+const modelListAccessRetryMs = 5_000;
 
 /**
- * A Claude account's model list for one revision of the account: the last one read, and why the latest read of it or of
- * the account's access failed, while it did. Neither is read again before `until`: a minute after the latest read,
- * failed or not, except 5 s after a failed access (`access_failed`), whose retry reads the list again with it.
+ * An account's model list for one revision of the account -- a Claude account's or an Anthropic API key's
+ * (`claudeCatalogs`), an OpenAI API key's (`keyCatalogs`): the last one read, and why the latest read of it or of the
+ * account's access failed, while it did. Neither is read again before `until`: a minute after the latest read, failed or
+ * not, except 5 s after a failed access (`access_failed`), whose retry reads the list again with it.
  */
-interface IClaudeCatalog {
+interface IHeldModelList<TModel> {
   revision: string;
   until: number;
   /** The last list read for the revision; `null` while no read of it succeeded. */
-  models: TInferenceClaudeModel[] | null;
+  models: TModel[] | null;
   failure: IInferenceAccountUnavailable | null;
 }
 
+/** Reads an account's model list with the access the account service answered for it. */
+type TModelLister<TModel> = (accessArg: IGatewayAuthorityAccess,
+  optionsArg: { signal: AbortSignal; fetch?: typeof fetch }) => Promise<TModel[]>;
+
 /**
- * Why a Claude account's held model list keeps it from routing: a failure of its access or sign-in always, a failed
+ * Why an account's held model list keeps it from routing: a failure of its access or sign-in always, a failed
  * model-list read (`catalog_failed`) only while no list is held -- the account routes on the last list meanwhile.
  */
-const claudeCatalogRefusal = (catalogArg: IClaudeCatalog): IInferenceAccountUnavailable | undefined =>
-  catalogArg.failure && (catalogArg.models === null || catalogArg.failure.reason !== 'catalog_failed')
-    ? catalogArg.failure : undefined;
+const heldListRefusal = <TModel>(listArg: IHeldModelList<TModel>): IInferenceAccountUnavailable | undefined =>
+  listArg.failure && (listArg.models === null || listArg.failure.reason !== 'catalog_failed')
+    ? listArg.failure : undefined;
 
-/** A Claude account's model list could not be read, and why (`InferenceRouter.readClaudeCatalog`). */
-class ClaudeCatalogError extends Error {
+/** An account's model list could not be read, and why (`InferenceRouter.readModelList`). */
+class ModelListError extends Error {
   constructor(public readonly unavailable: IInferenceAccountUnavailable) {
     super(unavailableText(unavailable));
-    this.name = 'ClaudeCatalogError';
+    this.name = 'ModelListError';
   }
 }
 
 /** A failed model list read in a few words: its HTTP status, or the kind of failure; never its message. */
 const catalogFailure = (errorArg: unknown): string => {
-  if (errorArg instanceof plugins.anthropicProvider.AnthropicOAuthModelListError) {
+  if (errorArg instanceof plugins.anthropicProvider.AnthropicOAuthModelListError
+    || errorArg instanceof plugins.openAiProvider.OpenAiApiModelListError) {
     return errorArg.code === 'HTTP_ERROR' && errorArg.status !== undefined ? `HTTP ${errorArg.status}` : errorArg.code;
   }
+  // An OpenAI key that may not read the model list (403) is refused like a list that cannot be read.
+  if (errorArg instanceof plugins.openAiProvider.OpenAiApiKeyAuthError && errorArg.status !== undefined) {
+    return `HTTP ${errorArg.status}`;
+  }
   return errorArg instanceof Error ? errorArg.name : typeof errorArg;
 };
 
+/** A provider's refusal of a key or sign-in it does not accept (401): renewed once for a sign-in, ended for a key. */
+const accessRejected = (errorArg: unknown): boolean => (errorArg instanceof plugins.anthropicProvider.AnthropicOAuthAuthError
+  || errorArg instanceof plugins.anthropicProvider.AnthropicApiKeyAuthError
+  || errorArg instanceof plugins.openAiProvider.OpenAiApiKeyAuthError) && errorArg.status === 401;
+
+/**
+ * A model an OpenAI API key lists (`GET /v1/models`), as a route and a catalog state it: what flexharness's
+ * `OPENAI_API_MODELS` describes of it -- efforts, service tiers, context window -- and nothing more. A model it does not
+ * describe stays routable, hidden from the model lists, as a ChatGPT catalog's hidden model is; its id is sent as it is
+ * listed.
+ */
+const openAiKeyModel = (modelIdArg: string): TInferenceModel => {
+  const described = plugins.openAiProvider.getOpenAiApiModel(modelIdArg);
+  return { providerId: 'openai', modelId: modelIdArg, wireModel: modelIdArg, displayName: described?.displayName ?? modelIdArg,
+    description: described?.description ?? '', hidden: described === undefined,
+    reasoningEfforts: described ? described.reasoningEfforts.map((effortArg) => ({ ...effortArg })) : [],
+    defaultReasoningEffort: described?.defaultReasoningEffort ?? '',
+    inputModalities: described ? [...described.inputModalities] : ['text'], supportsPersonality: false,
+    serviceTiers: described ? described.serviceTiers.map((tierArg) => ({ ...tierArg })) : [],
+    ...(described ? { contextWindow: described.contextWindow } : {}), isDefault: false };
+};
+
+/**
+ * Whether an account of a ChatGPT pool is a ChatGPT sign-in: only those reach the ChatGPT backend -- its Codex catalog,
+ * its model list and its Responses endpoint. An OpenAI API key is never sent there.
+ */
+const chatGptSignIn = (accountArg: IInferenceAccount): boolean => accountArg.credential === 'subscription';
+
 /** The headroom of an account whose provider reports no usage windows: below every known headroom. */
 const unknownHeadroom = -1;
 
@@ -370,11 +584,56 @@ const claudeLimits = (usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnap
 };
 
 /**
- * An Anthropic API key's limits. The account service reads no usage for a key -- its spend and rate limits are its
- * Claude Console organization's -- so a key routes with unknown headroom, as an account that reports no windows does,
- * and only a provider 429 rests it. A usage threshold has nothing to count against.
+ * An API key's limits, OpenAI's or Anthropic's, from its month's spend as the account service answers it (reading
+ * `kind: 'spend'`), by the shared rule (`authSwitchUsageLimit`): a key with a spend limit is exhausted while its month
+ * spent it or holds an answer that could not be priced, until the month ends, and its headroom is what is left of the
+ * limit; a key without one is never stopped by its spend and has no headroom to compare (`unknownHeadroom`). A reading
+ * whose month ended is the rule's as well: available, with all of the limit left. The account service answers a key's
+ * spend as current until its month ends, and the proxy asks again at every request, so no age is judged here.
+ *
+ * Without a spend reading -- the service could not read the key's ledger (`spend_unavailable`), or did not answer -- a
+ * key with a spend limit (`IInferenceAccount.spendLimitMicroUsd`) is refused (`undefined`, `spend_unread`), as it may be
+ * at its limit; one without a limit routes with unknown headroom. Rate limits are the provider's: a 429 rests a key.
+ */
+const keyLimits = (usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined,
+  accountArg: IInferenceAccount, nowArg: number): IAccountLimits | undefined => {
+  // The proxy hands a key's usage over judged (`InferenceSpendOutbox.judged`): its month's spend with the answers the
+  // account service has not acknowledged yet, in the month now falls in.
+  const reading = usageArg?.state === 'current' || usageArg?.state === 'stale' ? usageArg.reading : null;
+  if (reading?.kind === 'spend') return accountLimits(reading, '', accountArg, unknownHeadroom, nowArg);
+  return accountArg.spendLimitMicroUsd === null
+    ? { plan: '', state: 'available', headroom: unknownHeadroom, limit: null } : undefined;
+};
+
+/**
+ * Whether an API key has a monthly spend limit: by its spend reading's limit, which the account service answered with
+ * the reading, or without a reading by the limit the account carries.
  */
-const apiKeyLimits: IAccountLimits = { plan: '', state: 'available', headroom: unknownHeadroom, limit: null };
+const keyHasSpendLimit = (usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined,
+  accountArg: IInferenceAccount): boolean => usageArg?.reading?.kind === 'spend'
+  ? usageArg.reading.spend.limitMicroUsd !== null : accountArg.spendLimitMicroUsd !== null;
+
+/**
+ * An API key's state in words, as `agl proxy status` shows it on its limits (`keyLimits`), with its month: available, at
+ * its spend limit, or held below it until the month ends for an answer that could not be priced; available after its
+ * month ended with nothing relayed on it since, or without a limit and a spend reading.
+ */
+const keyStateText = (limitsArg: IAccountLimits,
+  usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined, nowArg: number): string => {
+  const readingArg = usageArg?.reading;
+  if (readingArg?.kind !== 'spend' || !limitsArg.limit) return 'available (no spend limit, and no spend reading)';
+  const spend = readingArg.spend;
+  // A reading the account service observed before the judged month began is last month's, judged as the new month's.
+  const newMonth = usageArg?.observedAt !== null && usageArg?.observedAt !== undefined
+    && Date.parse(usageArg.observedAt) < Date.parse(spend.periodStart);
+  if (plugins.authswitchSpend.authSwitchSpendMonthEnded(spend, nowArg) || (newMonth && spend.answers === 0)) {
+    return 'available (a new month began since its last spend reading)';
+  }
+  const state = limitsArg.state !== 'exhausted' ? 'available'
+    : spend.limitMicroUsd !== null && spend.spentMicroUsd < spend.limitMicroUsd ? 'held until its month ends'
+      : 'at its spend limit';
+  return `${state} (${spendText(spend)})`;
+};
 
 /**
  * A ChatGPT account's limits from its usage reading (see `authSwitchUsageLimit`): unset, the main limit decides --
@@ -516,14 +775,110 @@ interface ICandidate<TModel> {
   reading: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot['reading'];
   ignoreLimits: boolean;
   account: IInferenceAccount;
+  /** The account's credential tier in its pool, 0 the best (`inferenceCredentialTiers`): placement takes the best first. */
+  tier: number;
   model: TModel;
   plan: string;
   headroom: number;
   /** The account's placement score (`IAuthSwitchPlacement.score`). */
   score: number | null;
   lastResort: boolean;
+  /** An API key with a monthly spend limit. */
+  spendLimit: boolean;
+}
+
+/** How a request is placed on a Claude pool (`InferenceRouter.acquireClaude`). */
+export interface IInferenceClaudeAcquireOptions {
+  /** The session's account: the request is judged on it alone, unless `returnToBetterTier` finds a better one. */
+  accountId?: string;
+  /** The accounts this request left already; it never goes back to them. */
+  exclude?: ReadonlySet<string>;
+  /**
+   * The accounts of `exclude` the request left for a reason of their own, and that reason: each counts as its own
+   * judgement counts the reason, never as at its limit. An account of `exclude` it does not name counts as at its limit.
+   */
+  excludedBecause?: ReadonlyMap<string, IInferenceAccountUnavailable>;
+  /** A request that uses no quota (`count_tokens`): an account at its limit takes it as well. */
+  ignoreLimits?: boolean;
+  /**
+   * What of the request the proxy's price table cannot price (`inferenceAnthropicUnpricedRequest`): an API key with a
+   * monthly spend limit takes no such request (`model_unpriced`). A request that uses no quota ignores it.
+   */
+  unpriced?: string;
+  /**
+   * The session may move: when its account is of a later credential tier -- an Anthropic API key of a pool that names
+   * no credential -- a Claude account that can take the request takes it instead, and the route is `returned`.
+   */
+  returnToBetterTier?: boolean;
 }
 
+/** How a request is placed on a ChatGPT pool (`InferenceRouter.acquire`). */
+export interface IInferenceAcquireOptions {
+  /** The session's account: the request is judged on it alone, unless `returnToBetterTier` finds a better one. */
+  accountId?: string;
+  /** The accounts this request left already; it never goes back to them. */
+  exclude?: ReadonlySet<string>;
+  /** The accounts of `exclude` the request left for a reason of their own, as for a Claude pool (`IInferenceClaudeAcquireOptions`). */
+  excludedBecause?: ReadonlyMap<string, IInferenceAccountUnavailable>;
+  /** The request's `reasoning.effort`, which a ChatGPT account's model must accept; a key's model is OpenAI's to judge. */
+  reasoningEffort?: string;
+  /** The request's `service_tier`, which a ChatGPT account's model must offer (`auto` and `default` always). */
+  serviceTier?: string;
+  /** The Codex release the client read its catalog as: the model it names is checked against the catalog it was offered. */
+  clientVersion?: string;
+  /** A Responses request, which an OpenAI API key may take; a translated Messages request never goes to a key. */
+  apiKeys?: boolean;
+  /**
+   * What of the request the proxy's price table cannot price (`inferenceOpenAiUnpricedRequest`): an OpenAI API key with a
+   * monthly spend limit takes no such request (`model_unpriced`).
+   */
+  unpriced?: string;
+  /**
+   * The session may move: when its account is an OpenAI API key of a pool that names no credential, a ChatGPT account
+   * that can take the request takes it instead, and the route is `returned`. The gateway asks it only of a request that
+   * carries no account state, which never leaves its account.
+   */
+  returnToBetterTier?: boolean;
+}
+
+/** An account a request finds held with a payment problem, for the 402 that names it when nothing else is left. */
+interface IPaymentRefusal {
+  label: string;
+  credential: TInferenceCredential;
+  unavailable: IInferenceAccountUnavailable;
+}
+
+/**
+ * The 402 a request gets when the accounts it could go to are all held with payment problems: what each was refused for,
+ * and what ends it.
+ */
+const paymentRefusalText = (refusalsArg: readonly IPaymentRefusal[]): string => {
+  const named = (matchArg: (refusalArg: IPaymentRefusal) => boolean, nounArg: string): string | undefined => {
+    const labels = refusalsArg.filter(matchArg).map((refusalArg) => refusalArg.label);
+    return labels.length ? `${nounArg}${labels.length === 1 ? '' : 's'} ${labels.join(', ')}` : undefined;
+  };
+  const subscriptions = named((refusalArg) => refusalArg.unavailable.cause === 'billing'
+    && refusalArg.credential === 'subscription', 'Claude account');
+  const billedKeys = named((refusalArg) => refusalArg.unavailable.cause === 'billing' && refusalArg.credential === 'api_key',
+    'Anthropic API key');
+  const cappedKeys = named((refusalArg) => refusalArg.unavailable.cause === 'spend_cap', 'Anthropic API key');
+  const capEnds = refusalsArg.flatMap((refusalArg) => refusalArg.unavailable.cause === 'spend_cap'
+    && refusalArg.unavailable.retryAt ? [refusalArg.unavailable.retryAt] : []).sort()[0];
+  const quotaKeys = named((refusalArg) => refusalArg.unavailable.cause === 'quota', 'OpenAI API key');
+  return [
+    subscriptions && `Anthropic answered a billing error (HTTP 402) for the ${subscriptions}: a payment problem with the`
+      + ' subscription. Settle the billing, then re-check the account in AGL Accounts or with'
+      + ' `authswitch account recheck <account-id>`.',
+    billedKeys && `Anthropic answered a billing error (HTTP 402) for the ${billedKeys}: settle the billing of its`
+      + ' organization in the Claude Console, then re-check the key in AGL Accounts.',
+    cappedKeys && `The organization of the ${cappedKeys} reached its usage tier's monthly spend cap (HTTP 429)`
+      + `${capEnds ? `; it takes requests again at ${capEnds}` : ''}, or once Anthropic grants a higher tier and the key is`
+      + ' re-checked in AGL Accounts.',
+    quotaKeys && `OpenAI refused the ${quotaKeys} for its quota (HTTP 429 insufficient_quota): add credit or raise the`
+      + ' organization\'s or project\'s limit, then re-check the key in AGL Accounts.',
+  ].filter((sentenceArg): sentenceArg is string => !!sentenceArg).join(' ');
+};
+
 /** What judging a request's accounts found, for the refusal `InferenceRouter.select` answers when none is chosen. */
 interface ISelectionState {
   exhausted: boolean;
@@ -537,10 +892,28 @@ interface ISelectionState {
   accountLimit: TInferenceAccountLimit | undefined;
   /** A pinned account that takes no request for a reason of its own, and why. */
   refusal?: { accountId: string; unavailable: IInferenceAccountUnavailable };
-  /** The labels of the Claude accounts left out for a payment problem: never counted as at their limit. */
-  payment: string[];
+  /** The accounts left out for a payment problem, and why: never counted as at their limit. */
+  payment: IPaymentRefusal[];
+  /** The API keys at their monthly spend limit, which an `accounts_exhausted` refusal names. */
+  spendLimited: IInferenceSpendLimited[];
+  /** The labels of the API keys with a spend limit whose spend could not be read, which a `no_eligible_accounts` names. */
+  spendUnread: string[];
+  /**
+   * The labels of the API keys with a spend limit whose spend is recorded nowhere yet, which a `no_eligible_accounts`
+   * names: a report the account service refused, or an answer in neither the outbox's store, whose write failed, nor the
+   * ledger, or one no login of the key could be named for (`IInferenceSpendLedger.held`).
+   */
+  spendUnrecorded: string[];
+  /** The API keys with a spend limit the request was refused on for want of a price, and what lacked one. */
+  unpriced: { labels: string[]; what: string | undefined };
 }
 
+/** What judging a request's accounts finds before any account is judged: nothing yet. */
+const emptySelection = (accountsArg: number, pinnedArg: boolean): ISelectionState => ({ exhausted: false, reserved: false,
+  unavailable: false, modelKnown: false, earliestReset: Infinity, exhaustedPlans: new Set(), accounts: accountsArg,
+  pinned: pinnedArg, accountLimit: undefined, payment: [], spendLimited: [], spendUnread: [], spendUnrecorded: [],
+  unpriced: { labels: [], what: undefined } });
+
 /** An account's placement by the shared rule, on the reading the router holds for it. */
 const accountPlacement = (readingArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot['reading'],
   accountArg: IInferenceAccount, nowArg: number): plugins.authswitchPlacement.IAuthSwitchPlacement =>
@@ -551,21 +924,25 @@ export class InferenceRouter {
   /** ChatGPT catalogs by account and the Codex release they were read as. */
   private readonly catalogs = new Map<string, ICatalog<TInferenceModel>>();
   private readonly nativeCatalogs = new Map<string, INativeCatalog>();
-  private readonly claudeCatalogs = new Map<string, IClaudeCatalog>();
+  /** The model lists of the Claude accounts and the Anthropic API keys (`claudeCatalog`). */
+  private readonly claudeCatalogs = new Map<string, IHeldModelList<TInferenceClaudeModel>>();
+  /** The model lists of the OpenAI API keys (`keyCatalog`). */
+  private readonly keyCatalogs = new Map<string, IHeldModelList<TInferenceModel>>();
   /** Why each Claude account was last reported refused, or routed on its last model list (`noteAccount`). */
   private readonly noted = new Map<string, { unavailable: IInferenceAccountUnavailable; lastCatalog: boolean }>();
   private readonly active = new Map<string, number>();
   private readonly cooldowns = new Map<string, ICooldown>();
   /**
-   * The Claude accounts a billing error (HTTP 402) took out of rotation, by when it was seen, until the account service
-   * holds the problem; one it could not be told of stays here for the proxy's lifetime (`reportPaymentProblem`).
+   * The accounts a payment problem took out of rotation (`reportPaymentProblem`): a Claude account until the account
+   * service holds the problem -- one it could not be told of stays here for the proxy's lifetime -- and an API key until
+   * its spend cap ends, or for the proxy's lifetime.
    */
-  private readonly paymentMarks = new Map<string, number>();
+  private readonly paymentMarks = new Map<string, IPaymentMark>();
   /** The accounts whose payment problem the account service could not be told of, each reported once. */
   private readonly paymentReportsFailed = new Set<string>();
   /**
-   * The Anthropic API keys among the accounts the last pool read listed: the account service reads no usage for them,
-   * so nothing a request on one shows is handed to it.
+   * The API keys, Anthropic's and OpenAI's, among the accounts the last pool read listed: the account service reads no
+   * subscription usage for them, so no usage a request on one shows -- headers, tokens, a 429 -- is handed to it.
    */
   private apiKeyAccounts = new Set<string>();
   private readonly now: () => number;
@@ -579,21 +956,30 @@ export class InferenceRouter {
   }
 
   /**
-   * The policy's accounts of its provider and credential, and every eligible account's id of that pool: an account
-   * absent from both left the pool. An account whose lapse date passed is in neither -- it is never routed to again --
-   * and is named in `lapsed`. A Claude account and an Anthropic API key never share a pool, so a session placed on one
-   * kind never moves to the other.
+   * The credential tiers of the policy's pool, best first (`inferenceCredentialTiers`). A plan restriction leaves the
+   * API keys out, as a key has no plan, so a lease with `plans` never reaches a key.
+   */
+  private tiers(policyArg: IInferenceRoutingPolicy): readonly TInferenceCredential[] {
+    return inferenceCredentialTiers(policyArg.credential).filter((tierArg) => !policyArg.plans || tierArg !== 'api_key');
+  }
+
+  /**
+   * The policy's accounts of its provider and credential tiers (`tiers`), and every eligible account's id of that pool:
+   * an account absent from both left the pool. An account whose lapse date passed is in neither -- it is never routed to
+   * again -- and is named in `lapsed`. A pool that names its credential serves that kind alone: Flex's API-key pool
+   * never takes a Claude account. One that names none spans both, and a session placed on a key returns to a Claude
+   * account once one can take its request.
    */
   private async pool(policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal): Promise<{ accounts: IInferenceAccount[];
-    eligible: Set<string>; lapsed: Set<string> }> {
+    eligible: Set<string>; lapsed: Set<string>; tiers: readonly TInferenceCredential[] }> {
     const everyAccount = await this.options.accounts(signalArg);
     this.apiKeyAccounts = new Set(everyAccount.filter((account) => account.credential === 'api_key')
       .map((account) => account.id));
     const provider = policyArg.provider ?? 'openai';
-    const credential = policyArg.credential ?? 'subscription';
+    const tiers = this.tiers(policyArg);
     const now = this.now();
     const inPool = (accountArg: IInferenceAccount) => accountArg.providerId === provider
-      && accountArg.credential === credential;
+      && tiers.includes(accountArg.credential);
     const lapsed = new Set(everyAccount.filter((account) => inPool(account)
       && plugins.authswitchPlacement.authSwitchAccountLifecycle(account.lapsesAt, now) === 'lapsed').map((account) => account.id));
     const allAccounts = everyAccount.filter((account) => inPool(account) && !lapsed.has(account.id));
@@ -601,12 +987,12 @@ export class InferenceRouter {
     if (accounts.length > 64) throw new InferenceRoutingError(503, 'pool_too_large',
       'Select at most 64 accounts for this gateway.');
     const known = new Set(everyAccount.map((account) => account.id));
-    for (const cache of [this.catalogs, this.nativeCatalogs, this.claudeCatalogs]) {
+    for (const cache of [this.catalogs, this.nativeCatalogs, this.claudeCatalogs, this.keyCatalogs]) {
       for (const cacheKey of cache.keys()) if (!known.has(cacheKey.slice(0, 64))) cache.delete(cacheKey);
     }
     for (const id of this.cooldowns.keys()) if (!known.has(id)) this.cooldowns.delete(id);
     for (const id of this.noted.keys()) if (!known.has(id)) this.noted.delete(id);
-    return { accounts, eligible: new Set(allAccounts.map((account) => account.id)), lapsed };
+    return { accounts, eligible: new Set(allAccounts.map((account) => account.id)), lapsed, tiers };
   }
 
   /**
@@ -617,7 +1003,8 @@ export class InferenceRouter {
    * the session waiting.
    */
   private async sessionPool(policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal,
-    accountIdArg: string | undefined): Promise<{ accounts: IInferenceAccount[]; eligible: Set<string> }> {
+    accountIdArg: string | undefined): Promise<{ accounts: IInferenceAccount[]; eligible: Set<string>;
+      tiers: readonly TInferenceCredential[] }> {
     const pool = await this.pool(policyArg, signalArg);
     if (!accountIdArg) return pool;
     if (pool.lapsed.has(accountIdArg)) {
@@ -662,84 +1049,94 @@ export class InferenceRouter {
     return models;
   }
 
+  /** The models a Claude account or an Anthropic API key may use (`heldModels`). */
+  private claudeCatalog(accountArg: IInferenceAccount, signalArg: AbortSignal): Promise<TInferenceClaudeModel[]> {
+    return this.heldModels(this.claudeCatalogs, accountArg, signalArg, (accessArg, optionsArg) => accountArg.credential === 'api_key'
+      ? plugins.anthropicProvider.listAnthropicApiKeyModels({ apiKey: accessArg.accessToken }, optionsArg)
+      : plugins.anthropicProvider.listAnthropicOAuthModels(accessArg, optionsArg));
+  }
+
+  /** The models an OpenAI API key may use, as its `GET /v1/models` lists them (`heldModels`, `openAiKeyModel`). */
+  private keyCatalog(accountArg: IInferenceAccount, signalArg: AbortSignal): Promise<TInferenceModel[]> {
+    return this.heldModels(this.keyCatalogs, accountArg, signalArg, async (accessArg, optionsArg) =>
+      (await plugins.openAiProvider.listOpenAiApiKeyModels({ apiKey: accessArg.accessToken }, optionsArg))
+        .map((modelArg) => openAiKeyModel(modelArg.modelId)));
+  }
+
   /**
-   * The models a Claude account or an Anthropic API key may use: the list read within the last minute, else read now.
+   * The models an account may use, from its list in `listsArg`: the list read within the last minute, else read now.
    * A model-list read that fails keeps the list read before for the account's revision, which the account routes on
    * meanwhile; with none, the account is unavailable for the failure's reason. A failure of the account's access or
    * sign-in makes it unavailable whether a list is held or not. Either way the failure is noted and its account is not
-   * read again, however many requests ask, for a minute -- or 5 s after a failed access (`holdClaudeFailure`).
+   * read again, however many requests ask, for a minute -- or 5 s after a failed access (`holdListFailure`).
    */
-  private async claudeCatalog(accountArg: IInferenceAccount, signalArg: AbortSignal): Promise<TInferenceClaudeModel[]> {
-    const cached = this.claudeCatalogs.get(accountArg.id);
+  private async heldModels<TModel>(listsArg: Map<string, IHeldModelList<TModel>>, accountArg: IInferenceAccount,
+    signalArg: AbortSignal, listArg: TModelLister<TModel>): Promise<TModel[]> {
+    const cached = listsArg.get(accountArg.id);
     if (cached?.revision === accountArg.revision && cached.until > this.now()) {
-      const refusal = claudeCatalogRefusal(cached);
-      if (refusal) throw new ClaudeCatalogError(refusal);
+      const refusal = heldListRefusal(cached);
+      if (refusal) throw new ModelListError(refusal);
       return cached.models!;
     }
     try {
-      const models = await this.readClaudeCatalog(accountArg, signalArg);
-      this.claudeCatalogs.set(accountArg.id, { revision: accountArg.revision, until: this.now() + claudeCatalogMs, models,
-        failure: null });
+      const models = await this.readModelList(accountArg, signalArg, listArg);
+      listsArg.set(accountArg.id, { revision: accountArg.revision, until: this.now() + modelListMs, models, failure: null });
       this.noteAccount(accountArg.id, null);
       return models;
     } catch (errorArg) {
       signalArg.throwIfAborted();
-      const failure = errorArg instanceof ClaudeCatalogError ? errorArg.unavailable
+      const failure = errorArg instanceof ModelListError ? errorArg.unavailable
         : { reason: 'catalog_failed' as const, failure: catalogFailure(errorArg) };
-      const models = this.holdClaudeFailure(accountArg, failure);
+      const models = this.holdListFailure(listsArg, accountArg, failure);
       if (models) return models;
-      throw new ClaudeCatalogError(failure);
+      throw new ModelListError(failure);
     }
   }
 
   /**
-   * Records why a Claude account's model list or access failed, keeping the list held for its revision, and notes it:
+   * Records why an account's model list or access failed, keeping the list held for its revision, and notes it:
    * neither is read again for a minute after a failed model-list read or sign-in, or for 5 s after a failed access
    * (`access_failed`). The access is then tried again by reading the list again, even one read within the minute: a
    * single list read on recovery. Answers the held list when the account routes on it meanwhile -- only after a failed
-   * model-list read (`claudeCatalogRefusal`).
+   * model-list read (`heldListRefusal`).
    */
-  private holdClaudeFailure(accountArg: IInferenceAccount,
-    failureArg: IInferenceAccountUnavailable): TInferenceClaudeModel[] | undefined {
-    const catalog: IClaudeCatalog = { revision: accountArg.revision,
-      until: this.now() + (failureArg.reason === 'access_failed' ? claudeAccessRetryMs : claudeCatalogMs),
-      models: this.heldClaudeCatalog(accountArg) ?? null, failure: failureArg };
-    this.claudeCatalogs.set(accountArg.id, catalog);
-    const routed = claudeCatalogRefusal(catalog) ? undefined : catalog.models!;
+  private holdListFailure<TModel>(listsArg: Map<string, IHeldModelList<TModel>>, accountArg: IInferenceAccount,
+    failureArg: IInferenceAccountUnavailable): TModel[] | undefined {
+    const list: IHeldModelList<TModel> = { revision: accountArg.revision,
+      until: this.now() + (failureArg.reason === 'access_failed' ? modelListAccessRetryMs : modelListMs),
+      models: this.heldList(listsArg, accountArg) ?? null, failure: failureArg };
+    listsArg.set(accountArg.id, list);
+    const routed = heldListRefusal(list) ? undefined : list.models!;
     this.noteAccount(accountArg.id, failureArg, routed !== undefined);
     return routed;
   }
 
   /**
-   * Reads the models a Claude account or an Anthropic API key may use. A rejected access is reported once: a sign-in is
-   * renewed, while a key is ended, so the account service refuses the second read. Every failure but an abort is a
-   * `ClaudeCatalogError` naming its reason.
+   * Reads the models an account may use through `listArg`. A rejected access (`accessRejected`) is reported once: a
+   * sign-in is renewed, while a key is ended, so the account service refuses the second read. Every failure but an abort
+   * is a `ModelListError` naming its reason.
    */
-  private async readClaudeCatalog(accountArg: IInferenceAccount, signalArg: AbortSignal): Promise<TInferenceClaudeModel[]> {
-    const read = async (rejectedGenerationArg?: number) => {
+  private async readModelList<TModel>(accountArg: IInferenceAccount, signalArg: AbortSignal,
+    listArg: TModelLister<TModel>): Promise<TModel[]> {
+    const read = async (rejectedGenerationArg?: number): Promise<{ models?: TModel[]; rejected?: number }> => {
       let access: IGatewayAuthorityAccess;
       try {
         access = await this.options.resolveAccess(accountArg.id, signalArg, rejectedGenerationArg);
       } catch (errorArg) {
         signalArg.throwIfAborted();
-        throw new ClaudeCatalogError({ reason: needsSignIn(errorArg) ? 'needs_login' : 'access_failed' });
+        throw new ModelListError({ reason: needsSignIn(errorArg) ? 'needs_login' : 'access_failed' });
       }
-      const listOptions = { signal: signalArg, ...(this.options.providerFetch ? { fetch: this.options.providerFetch } : {}) };
       try {
-        return { models: accountArg.credential === 'api_key'
-          ? await plugins.anthropicProvider.listAnthropicApiKeyModels({ apiKey: access.accessToken }, listOptions)
-          : await plugins.anthropicProvider.listAnthropicOAuthModels(access, listOptions) };
+        return { models: await listArg(access, { signal: signalArg,
+          ...(this.options.providerFetch ? { fetch: this.options.providerFetch } : {}) }) };
       } catch (errorArg) {
-        if ((errorArg instanceof plugins.anthropicProvider.AnthropicOAuthAuthError
-          || errorArg instanceof plugins.anthropicProvider.AnthropicApiKeyAuthError) && errorArg.status === 401) {
-          return { rejected: access.generation };
-        }
+        if (accessRejected(errorArg)) return { rejected: access.generation };
         throw errorArg;
       }
     };
     let result = await read();
     if (result.rejected !== undefined) result = await read(result.rejected);
-    if (!result.models) throw new ClaudeCatalogError({ reason: 'needs_login' });
+    if (!result.models) throw new ModelListError({ reason: 'needs_login' });
     return result.models;
   }
 
@@ -750,7 +1147,8 @@ export class InferenceRouter {
   private noteAccount(accountIdArg: string, unavailableArg: IInferenceAccountUnavailable | null, lastCatalogArg = false): void {
     const previous = this.noted.get(accountIdArg);
     if (unavailableArg === null ? !previous : previous?.lastCatalog === lastCatalogArg
-      && previous.unavailable.reason === unavailableArg.reason && previous.unavailable.failure === unavailableArg.failure) return;
+      && previous.unavailable.reason === unavailableArg.reason && previous.unavailable.failure === unavailableArg.failure
+      && previous.unavailable.cause === unavailableArg.cause) return;
     if (unavailableArg === null) this.noted.delete(accountIdArg);
     else this.noted.set(accountIdArg, { unavailable: unavailableArg, lastCatalog: lastCatalogArg });
     try {
@@ -760,37 +1158,57 @@ export class InferenceRouter {
     } catch {}
   }
 
-  /** The model list a Claude account's revision was last read with, without reading it: `undefined` when none is held. */
-  private heldClaudeCatalog(accountArg: IInferenceAccount): TInferenceClaudeModel[] | undefined {
-    const cached = this.claudeCatalogs.get(accountArg.id);
+  /** The model list an account's revision was last read with, without reading it: `undefined` when none is held. */
+  private heldList<TModel>(listsArg: Map<string, IHeldModelList<TModel>>, accountArg: IInferenceAccount): TModel[] | undefined {
+    const cached = listsArg.get(accountArg.id);
     return cached?.revision === accountArg.revision ? cached.models ?? undefined : undefined;
   }
 
   /**
-   * Why a Claude account's model list or access keeps it from routing, as a request would find it now, before its next
-   * read is due: a failed access or sign-in, or a failed model-list read with no list held for its revision.
+   * Why an account's model list or access keeps it from routing, as a request would find it now, before its next read is
+   * due: a failed access or sign-in, or a failed model-list read with no list held for its revision. Only the accounts
+   * whose model list the router reads have one: Claude accounts and API keys.
    */
-  private catalogRefusal(accountArg: IInferenceAccount): IInferenceAccountUnavailable | undefined {
-    const cached = this.claudeCatalogs.get(accountArg.id);
-    return cached?.revision === accountArg.revision && cached.until > this.now() ? claudeCatalogRefusal(cached) : undefined;
+  private listRefusal(accountArg: IInferenceAccount): IInferenceAccountUnavailable | undefined {
+    const refusal = <TModel>(cachedArg: IHeldModelList<TModel> | undefined) => cachedArg?.revision === accountArg.revision
+      && cachedArg.until > this.now() ? heldListRefusal(cachedArg) : undefined;
+    return accountArg.providerId === 'anthropic' ? refusal(this.claudeCatalogs.get(accountArg.id))
+      : accountArg.credential === 'api_key' ? refusal(this.keyCatalogs.get(accountArg.id)) : undefined;
   }
 
   /**
-   * The models every readable account of the Claude pool -- its Claude accounts, or its Anthropic API keys -- offers: a
-   * session may move to any of them, so a model one account lacks is not offered. Limits are the smallest any of them
-   * states; efforts are those all of them accept, and adaptive thinking is offered when all of them accept it. What one
-   * account does not state, the pool does not state.
+   * The Claude pool's models, from its best credential tier with a readable account (`inferenceCredentialTiers`): the
+   * Claude accounts' while one of them can read its model list, else the Anthropic API keys'. Within the tier, the
+   * models every readable account offers: a session may move to any of them, so a model one account lacks is not
+   * offered. Limits are the smallest any of them states; efforts are those all of them accept, and adaptive thinking is
+   * offered when all of them accept it. What one account does not state, the pool does not state.
    */
   public async claudeModels(policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal): Promise<TInferenceClaudeModel[]> {
     if (policyArg.provider !== 'anthropic') throw new Error('The Claude catalog belongs to a Claude pool.');
-    const accounts = await this.accounts(policyArg, signalArg);
+    const { accounts, tiers } = await this.pool(policyArg, signalArg);
+    for (const tier of tiers) {
+      const models = await this.tierClaudeModels(accounts.filter((account) => account.credential === tier), policyArg,
+        signalArg);
+      if (models?.size) return [...models.values()];
+    }
+    throw new InferenceRoutingError(503, 'no_eligible_accounts', policyArg.credential === 'api_key'
+      ? 'No Anthropic API key could supply a model list. Add one with `authswitch account add anthropic-api-key`.'
+      : policyArg.credential === 'subscription' || policyArg.plans
+        ? 'No eligible Claude account could supply a model list. Check the AGL account service and sign-ins.'
+        : 'No eligible Claude account or Anthropic API key could supply a model list. Check the AGL account service and '
+          + 'sign-ins, or add a key with `authswitch account add anthropic-api-key`.');
+  }
+
+  /** The models every readable account of one credential tier of a Claude pool offers; `undefined` when none is readable. */
+  private async tierClaudeModels(accountsArg: readonly IInferenceAccount[], policyArg: IInferenceRoutingPolicy,
+    signalArg: AbortSignal): Promise<Map<string, TInferenceClaudeModel> | undefined> {
     let models: Map<string, TInferenceClaudeModel> | undefined;
-    for (const account of accounts) {
+    for (const account of accountsArg) {
       signalArg.throwIfAborted();
       try {
+        // A plan restriction leaves the keys out of the pool: only Claude accounts are judged on it.
         if (policyArg.plans) {
-          const limits = account.credential === 'api_key' ? apiKeyLimits
-            : claudeLimits(await this.options.usage(account.id, signalArg), account, this.now());
+          const limits = claudeLimits(await this.options.usage(account.id, signalArg), account, this.now());
           if (!limits || !policyArg.plans.includes(limits.plan)) continue;
         }
         const offered = new Map((await this.claudeCatalog(account, signalArg)).map((model) => [model.modelId, model]));
@@ -816,24 +1234,46 @@ export class InferenceRouter {
         // An unreadable account is unavailable; it never supplies guessed models.
       }
     }
-    if (!models?.size) throw new InferenceRoutingError(503, 'no_eligible_accounts', policyArg.credential === 'api_key'
-      ? 'No Anthropic API key could supply a model list. Add one with `authswitch account add anthropic-api-key`.'
-      : 'No eligible Claude account could supply a model list. Check the AGL account service and sign-ins.');
-    return [...models.values()];
+    return models;
   }
 
   /**
-   * Current model entitlements, merged conservatively across the account pool. A pool whose every account read needs a
-   * fresh sign-in -- ChatGPT rejected its access even when renewed, or the account service could not renew it -- answers
+   * The ChatGPT pool's models, from its best credential tier with a readable account (`inferenceCredentialTiers`): the
+   * ChatGPT sign-ins' current entitlements while one of them can read its catalog, else the OpenAI API keys' models
+   * (`keyTierModels`). A pool whose every ChatGPT account read needs a fresh sign-in -- ChatGPT rejected its access even
+   * when renewed, or the account service could not renew it -- and no key to fall back to answers
    * `account_needs_login`, so its caller asks for a sign-in rather than for the proxy.
    */
   public async models(policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal): Promise<TInferenceModel[]> {
     if ((policyArg.provider ?? 'openai') !== 'openai') throw new Error('The ChatGPT catalog belongs to a ChatGPT pool.');
-    const accounts = await this.accounts(policyArg, signalArg);
+    const { accounts, tiers } = await this.pool(policyArg, signalArg);
+    let signInNeeded = false;
+    for (const tier of tiers) {
+      if (tier === 'subscription') {
+        const read = await this.signInModels(accounts.filter(chatGptSignIn), policyArg, signalArg);
+        if (read.models.size) return [...read.models.values()];
+        signInNeeded = read.signInNeeded;
+      } else {
+        const models = await this.keyTierModels(accounts.filter((account) => !chatGptSignIn(account)), signalArg);
+        if (models?.size) return [...models.values()];
+      }
+    }
+    if (signInNeeded) throw new InferenceRoutingError(503, 'account_needs_login', 'An account needs a fresh sign-in.');
+    throw new InferenceRoutingError(503, 'no_eligible_accounts', policyArg.credential === 'api_key'
+      ? 'No OpenAI API key could supply a model list. Add one in AGL Accounts or with `authswitch account add openai-api-key`.'
+      : 'No eligible account could supply a model catalog. Check the AGL account service and sign-ins.');
+  }
+
+  /**
+   * Current model entitlements, merged conservatively across the pool's ChatGPT sign-ins, and whether every account read
+   * needed a fresh sign-in.
+   */
+  private async signInModels(accountsArg: readonly IInferenceAccount[], policyArg: IInferenceRoutingPolicy,
+    signalArg: AbortSignal): Promise<{ models: Map<string, TInferenceModel>; signInNeeded: boolean }> {
     const models = new Map<string, TInferenceModel>();
     let read = 0;
     let signInNeeded = 0;
-    for (const account of accounts) {
+    for (const account of accountsArg) {
       signalArg.throwIfAborted();
       try {
         if (policyArg.plans) {
@@ -859,22 +1299,44 @@ export class InferenceRouter {
         if (needsSignIn(errorArg)) signInNeeded += 1;
       }
     }
-    if (!models.size && read > 0 && signInNeeded === read) {
-      throw new InferenceRoutingError(503, 'account_needs_login', 'An account needs a fresh sign-in.');
+    return { models, signInNeeded: !models.size && read > 0 && signInNeeded === read };
+  }
+
+  /**
+   * The models every readable OpenAI API key of the pool lists and flexharness describes (`openAiKeyModel`), newest first
+   * as `OPENAI_API_MODELS` orders them, the first the default: a session may move to any of the keys, so a model one key
+   * lacks is not offered. `undefined` when no key is readable.
+   */
+  private async keyTierModels(accountsArg: readonly IInferenceAccount[],
+    signalArg: AbortSignal): Promise<Map<string, TInferenceModel> | undefined> {
+    let offered: Set<string> | undefined;
+    for (const account of accountsArg) {
+      signalArg.throwIfAborted();
+      try {
+        const listed = new Set((await this.keyCatalog(account, signalArg)).filter((model) => !model.hidden).map((model) => model.modelId));
+        offered = offered ? new Set([...offered].filter((modelId) => listed.has(modelId))) : listed;
+      } catch {
+        signalArg.throwIfAborted();
+        // An unreadable key is unavailable; it never supplies guessed models.
+      }
     }
-    if (!models.size) throw new InferenceRoutingError(503, 'no_eligible_accounts',
-      'No eligible account could supply a model catalog. Check the AGL account service and sign-ins.');
-    return [...models.values()];
+    if (!offered) return undefined;
+    const models = plugins.openAiProvider.OPENAI_API_MODELS.filter((model) => offered!.has(model.modelId))
+      .map((model, index) => ({ ...openAiKeyModel(model.modelId), isDefault: index === 0 }));
+    return new Map(models.map((model) => [model.modelId, model]));
   }
 
   /**
-   * The pool's Codex model catalog in the Codex backend's own entry shape, read for the client's version.
-   * An entry shared by several accounts keeps only what every one of them offers.
+   * The pool's Codex model catalog in the Codex backend's own entry shape, read for the client's version through its
+   * ChatGPT sign-ins alone: an OpenAI API key never reaches the ChatGPT catalog connection, so a pool of keys alone has
+   * no Codex catalog here (`no_eligible_accounts`; Codex then uses its bundled one). An entry shared by several
+   * accounts keeps only what every one of them offers.
    */
   public async nativeModels(policyArg: IInferenceRoutingPolicy, clientVersionArg: string,
     signalArg: AbortSignal): Promise<TInferenceNativeModel[]> {
     if ((policyArg.provider ?? 'openai') !== 'openai') throw new Error('The Codex catalog belongs to a ChatGPT pool.');
-    const accounts = await this.accounts(policyArg, signalArg);
+    // The Codex catalog is the ChatGPT backend's: only a ChatGPT sign-in reads it, whatever credential the policy names.
+    const accounts = (await this.accounts(policyArg, signalArg)).filter(chatGptSignIn);
     const models = new Map<string, TInferenceNativeModel>();
     for (const account of accounts) {
       signalArg.throwIfAborted();
@@ -927,92 +1389,162 @@ export class InferenceRouter {
   }
 
   /**
-   * A ChatGPT account for one request. `clientVersion` is the Codex release the client read its catalog as, so the
-   * model it names is checked against the catalog it was offered.
+   * A ChatGPT account or an OpenAI API key for one request, chosen as `acquireClaude` chooses: the pinned session account
+   * if it is still eligible, else the best credential tier's least busy account with the most headroom
+   * (`inferenceCredentialTiers`). A ChatGPT account is judged on its usage reading and the Codex catalog of the release
+   * the client read it as (`clientVersion`). An OpenAI API key takes only a Responses request (`apiKeys`), never a
+   * translated Messages request, and is judged as an Anthropic API key is (`judgeListed`): a payment problem -- OpenAI's
+   * quota refusal -- or its month's spend at its limit keeps it out, a key with a limit takes no request it cannot price
+   * (`unpriced`, `model_unpriced`), and its model list (`GET /v1/models`, held a minute) must list the model. The accounts
+   * of `exclude` count as `excludedBecause` says, as for a Claude pool. `returnToBetterTier`: a session pinned to a key
+   * goes back to a ChatGPT account as soon as one can take its request, and the route says so (`returned`).
    */
   public async acquire(modelIdArg: string, policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal,
-    optionsArg: { accountId?: string; exclude?: ReadonlySet<string>; reasoningEffort?: string; serviceTier?: string;
-      clientVersion?: string } = {}): Promise<IInferenceRoute> {
+    optionsArg: IInferenceAcquireOptions = {}): Promise<IInferenceRoute> {
     if ((policyArg.provider ?? 'openai') !== 'openai') throw new Error('A ChatGPT route belongs to a ChatGPT pool.');
+    const { accounts, tiers } = await this.sessionPool(policyArg, signalArg, optionsArg.accountId);
+    const pinned = accounts.find((account) => account.id === optionsArg.accountId);
+    if (pinned && optionsArg.returnToBetterTier) {
+      // The session's account is of a later tier: an account of a better one that can take the request takes it, as a
+      // new session would be placed. When none can, the session stays where it is, judged as before.
+      const better = accounts.filter((account) => tiers.indexOf(account.credential) < tiers.indexOf(pinned.credential));
+      if (better.length) {
+        try {
+          const { accountId: _pinned, ...unpinned } = optionsArg;
+          return { ...await this.routeOpenAi(modelIdArg, policyArg, better, tiers, signalArg, unpinned), returned: true };
+        } catch (errorArg) {
+          signalArg.throwIfAborted();
+          if (!(errorArg instanceof InferenceRoutingError)) throw errorArg;
+        }
+      }
+    }
+    return this.routeOpenAi(modelIdArg, policyArg, accounts, tiers, signalArg, optionsArg);
+  }
+
+  /** `acquire` among `accountsArg`, the pool's accounts or those of its better tiers. */
+  private async routeOpenAi(modelIdArg: string, policyArg: IInferenceRoutingPolicy, accountsArg: readonly IInferenceAccount[],
+    tiersArg: readonly TInferenceCredential[], signalArg: AbortSignal, optionsArg: IInferenceAcquireOptions): Promise<IInferenceRoute> {
     const candidates: ICandidate<TInferenceModel>[] = [];
-    let exhausted = false;
-    let reserved = false;
-    let modelKnown = false;
-    let unavailable = false;
-    let earliestReset = Infinity;
-    let accountLimit: TInferenceAccountLimit | undefined;
-    const exhaustedPlans = new Set<string>();
-    const { accounts } = await this.sessionPool(policyArg, signalArg, optionsArg.accountId);
-    for (const account of accounts) {
+    const state = emptySelection(accountsArg.length, optionsArg.accountId !== undefined);
+    /** Why the last account judged takes no request though no limit says so: a pinned refusal names it. */
+    let refusal: IInferenceAccountUnavailable | undefined;
+    for (const account of accountsArg) {
       signalArg.throwIfAborted();
       if (optionsArg.accountId && optionsArg.accountId !== account.id) continue;
-      if (optionsArg.exclude?.has(account.id)) {
-        exhausted = true;
-        const reset = this.cooldowns.get(account.id)?.until ?? 0;
-        if (reset > this.now()) earliestReset = Math.min(earliestReset, reset);
-        continue;
-      }
+      if (optionsArg.exclude?.has(account.id)) { this.countLeft(state, account, optionsArg.excludedBecause?.get(account.id)); continue; }
+      // A translated Messages request never goes to an OpenAI API key: only a Responses request does.
+      if (!chatGptSignIn(account) && !optionsArg.apiKeys) { state.unavailable = true; continue; }
       try {
+        if (!chatGptSignIn(account)) {
+          // A key's usage is its month's spend, with the payment problem the account service holds on it.
+          const usage = await this.options.usage(account.id, signalArg)
+            .catch(() => { signalArg.throwIfAborted(); return undefined; });
+          const judged = await this.judgeListed(state, account, usage, keyLimits(usage, account, this.now()), {
+            modelId: modelIdArg, lists: this.keyCatalogs, read: (accountArg, innerSignalArg) => this.keyCatalog(accountArg, innerSignalArg),
+            ...(optionsArg.unpriced === undefined ? {} : { unpriced: optionsArg.unpriced }) }, signalArg);
+          if (judged?.kind !== 'candidate') { if (judged) refusal = judged.unavailable; continue; }
+          // The request goes to OpenAI as the client sent it: its effort and service tier are OpenAI's to judge, a limited
+          // key's tier the price check's (`unpriced`).
+          const placement = accountPlacement(judged.limits.limit ? usage!.reading : null, account, this.now());
+          candidates.push({ account, tier: tiersArg.indexOf(account.credential), model: judged.model,
+            reading: judged.limits.limit ? usage!.reading : null, ignoreLimits: false, plan: judged.limits.plan,
+            headroom: judged.limits.headroom, score: placement.score, lastResort: placement.eligibility === 'last_resort',
+            spendLimit: judged.spendLimit });
+          continue;
+        }
         const usage = await this.options.usage(account.id, signalArg);
         if (!usableReading(usage, this.now()) || usage.reading?.kind !== 'openai') {
-          unavailable = true;
+          state.unavailable = true;
           continue;
         }
         const plan = usage.reading.rateLimits.plan;
         if (policyArg.plans && !policyArg.plans.includes(plan)) continue;
         const model = (await this.catalog(account, signalArg, optionsArg.clientVersion)).find((entry) => entry.modelId === modelIdArg);
         if (!model) continue;
-        modelKnown = true;
+        state.modelKnown = true;
         if (optionsArg.reasoningEffort && !model.reasoningEfforts.some((effort) => effort.effort === optionsArg.reasoningEffort)) continue;
         if (optionsArg.serviceTier && !['auto', 'default'].includes(optionsArg.serviceTier)
           && !model.serviceTiers.some((tier) => tier.id === optionsArg.serviceTier)) continue;
         const limits = chatGptLimits(usage, account, this.now());
-        if (!limits) { unavailable = true; continue; }
+        if (!limits) { state.unavailable = true; continue; }
         const cooldown = cooldownUntil(this.cooldowns.get(account.id), usage);
         if (limits.state !== 'available' || cooldown > this.now()) {
-          exhausted = true;
-          reserved ||= limits.state === 'reserved';
-          accountLimit = limits.state === 'available' ? 'cooling' : limits.state;
-          exhaustedPlans.add(limits.plan);
+          state.exhausted = true;
+          state.reserved ||= limits.state === 'reserved';
+          state.accountLimit = limits.state === 'available' ? 'cooling' : limits.state;
+          state.exhaustedPlans.add(limits.plan);
           const reset = Math.max(cooldown, limits.resetAt ?? 0);
-          if (reset > this.now()) earliestReset = Math.min(earliestReset, reset);
+          if (reset > this.now()) state.earliestReset = Math.min(state.earliestReset, reset);
           continue;
         }
         const placement = accountPlacement(usage.reading, account, this.now());
-        candidates.push({ account, model, reading: usage.reading, ignoreLimits: false, plan: limits.plan, headroom: limits.headroom, score: placement.score,
-          lastResort: placement.eligibility === 'last_resort' });
-      } catch {
+        candidates.push({ account, tier: tiersArg.indexOf(account.credential), model, reading: usage.reading, ignoreLimits: false,
+          plan: limits.plan, headroom: limits.headroom, score: placement.score, lastResort: placement.eligibility === 'last_resort',
+          spendLimit: false });
+      } catch (errorArg) {
+        signalArg.throwIfAborted();
+        state.unavailable = true;
+        if (errorArg instanceof ModelListError) refusal = errorArg.unavailable;
+      }
+    }
+    if (optionsArg.accountId !== undefined && refusal) state.refusal = { accountId: optionsArg.accountId, unavailable: refusal };
+    // The chosen account's access is resolved before anything is sent. An OpenAI API key whose access fails takes no
+    // request, as an Anthropic key's does (`routeClaude`): the failure is held for the key (`keyCatalogs`) and noted, and
+    // the request goes to the next candidate -- a pinned request has none, so it is refused naming the key and the reason.
+    // A ChatGPT account's failure fails the request.
+    let selected: ICandidate<TInferenceModel>;
+    let initial: IGatewayAuthorityAccess;
+    let release: () => void;
+    for (;;) {
+      selected = this.select(candidates, state);
+      release = this.reserve(selected.account.id);
+      try {
+        initial = await this.options.resolveAccess(selected.account.id, signalArg);
+        break;
+      } catch (errorArg) {
+        release();
+        if (chatGptSignIn(selected.account)) throw errorArg;
         signalArg.throwIfAborted();
-        unavailable = true;
+        const failure: IInferenceAccountUnavailable = { reason: needsSignIn(errorArg) ? 'needs_login' : 'access_failed' };
+        this.holdListFailure(this.keyCatalogs, selected.account, failure);
+        candidates.splice(candidates.indexOf(selected), 1);
+        state.unavailable = true;
+        if (state.pinned) state.refusal = { accountId: selected.account.id, unavailable: failure };
       }
     }
-    const selectionState: ISelectionState = { exhausted, reserved, unavailable, modelKnown, earliestReset, exhaustedPlans,
-      accounts: accounts.length, pinned: optionsArg.accountId !== undefined, accountLimit, payment: [] };
-    const selected = this.select(candidates, selectionState);
     const id = selected.account.id;
-    const release = this.reserve(id);
     try {
-      const initial = await this.options.resolveAccess(id, signalArg);
-      this.select([selected], selectionState);
-      const connection = plugins.openAiProvider.createOpenAiChatGptResolvingModelConnection({
-        expectedIdentity: initial,
-        resolveAccess: async ({ signal, rejectedGeneration }) => {
-          const access = await this.options.resolveAccess(id, signal, rejectedGeneration);
-          this.select([selected], selectionState);
-          return access;
-        },
-        fetch: async (inputArg, initArg) => {
-          const response = await (this.options.providerFetch ?? fetch)(inputArg, initArg);
-          this.observe(id, 'openai', response.headers, response.status);
-          if (response.status === 429) {
-            this.reportQuota(id, this.retryAfterSeconds(response.headers));
-          }
-          return response;
-        },
-        originator: 'agl',
-      });
-      return { provider: 'openai', accountId: id, plan: selected.plan, score: selected.score, model: selected.model,
-        connection, release };
+      this.select([selected], state);
+      const connection = chatGptSignIn(selected.account)
+        ? plugins.openAiProvider.createOpenAiChatGptResolvingModelConnection({
+          expectedIdentity: initial,
+          resolveAccess: async ({ signal, rejectedGeneration }) => {
+            const access = await this.options.resolveAccess(id, signal, rejectedGeneration);
+            this.select([selected], state);
+            return access;
+          },
+          fetch: async (inputArg, initArg) => {
+            const response = await (this.options.providerFetch ?? fetch)(inputArg, initArg);
+            this.observe(id, 'openai', response.headers, response.status);
+            if (response.status === 429) {
+              this.reportQuota(id, this.retryAfterSeconds(response.headers));
+            }
+            return response;
+          },
+          originator: 'agl',
+        })
+        : plugins.openAiProvider.createOpenAiApiKeyConnection({
+          apiKey: initial.accessToken,
+          // A key is never renewed: OpenAI's 401 is reported before the connection fails the request with it.
+          fetch: async (inputArg, initArg) => {
+            const response = await (this.options.providerFetch ?? fetch)(inputArg, initArg);
+            if (response.status === 401) await this.rejectApiKey(id, initial.generation, signalArg);
+            return response;
+          },
+        });
+      return { provider: 'openai', credential: selected.account.credential, accountId: id, plan: selected.plan,
+        score: selected.score, model: selected.model, connection, returned: false, loginId: selected.account.loginId,
+        spendLimit: selected.spendLimit, release };
     } catch (errorArg) {
       release();
       throw errorArg;
@@ -1020,106 +1552,229 @@ export class InferenceRouter {
   }
 
   /**
-   * A Claude account for one of Claude Code's requests, or an Anthropic API key for one of Flex's, chosen as `acquire`
-   * chooses: the pinned session account if it is still eligible, else the least busy account with the most headroom
-   * whose current reading shows it available -- every counted window under its threshold, no provider retry ahead --
-   * with no cooldown after a provider 429, and which lists the model. A key has no reading (`apiKeyLimits`): it is
-   * available unless it cools down after a 429.
+   * Counts an account the request left already (`exclude`) as its own judgement counts the reason the request left it
+   * for (`excludedBecause`): a payment problem joins the 402 list, a key whose spend could not be read or recorded is
+   * named in the 503, one that could not price the request joins the 400 list, one without the model leads to the 404,
+   * and every other reason to the 503 for want of an account. An account left for no reason of its own counts as at its
+   * limit (429). The switch is exhaustive: a new reason must be placed here.
+   */
+  private countLeft(stateArg: ISelectionState, accountArg: IInferenceAccount,
+    leftArg: IInferenceAccountUnavailable | undefined): void {
+    if (!leftArg) {
+      stateArg.exhausted = true;
+      const reset = this.cooldowns.get(accountArg.id)?.until ?? 0;
+      if (reset > this.now()) stateArg.earliestReset = Math.min(stateArg.earliestReset, reset);
+      return;
+    }
+    switch (leftArg.reason) {
+      case 'payment_problem':
+        stateArg.payment.push({ label: accountArg.label, credential: accountArg.credential, unavailable: leftArg });
+        return;
+      case 'model_missing':
+        return;
+      case 'model_unpriced':
+        stateArg.unpriced.labels.push(accountArg.label);
+        stateArg.unpriced.what ??= leftArg.failure;
+        return;
+      case 'spend_unread':
+        stateArg.unavailable = true;
+        stateArg.spendUnread.push(accountArg.label);
+        return;
+      case 'spend_unrecorded':
+        stateArg.unavailable = true;
+        stateArg.spendUnrecorded.push(accountArg.label);
+        return;
+      case 'usage_unread':
+      case 'catalog_failed':
+      case 'needs_login':
+      case 'access_failed':
+        stateArg.unavailable = true;
+        return;
+      default: {
+        const unhandledReason: never = leftArg.reason;
+        return unhandledReason;
+      }
+    }
+  }
+
+  /**
+   * Judges an account whose model list the router reads -- a Claude account, an Anthropic or an OpenAI API key -- for one
+   * request, as placement takes it, recording on `stateArg` what keeps it out. A payment problem refuses it before anything
+   * else; without limits to route on (`limitsArg`) it is unavailable (`usage_unread`, a key's `spend_unread`); a key with
+   * a spend limit whose spend is recorded nowhere yet is refused (`spend_unrecorded`). Limits and cool-down are judged
+   * before any model list is read: an account that cannot take the request now is never read for it, its held list says
+   * whether it would serve the model, and without one it counts as at its limit, so a session on it moves rather than
+   * waiting for a list. A key's spend reading says nothing of the provider's rate limits, so only its own end ends a key's
+   * cool-down. A key with a spend limit then takes no request whose cost the price table cannot count (`unpriced`,
+   * Decision Q4), and the model list (`read`) must list the model. Answers the candidate's model and limits, or the refusal
+   * of an account that takes no request for a reason of its own -- a pinned refusal names it -- or `undefined`.
+   */
+  private async judgeListed<TModel extends { modelId: string }>(stateArg: ISelectionState, accountArg: IInferenceAccount,
+    usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined, limitsArg: IAccountLimits | undefined,
+    optionsArg: { modelId: string; lists: Map<string, IHeldModelList<TModel>>;
+      read: (accountArg: IInferenceAccount, signalArg: AbortSignal) => Promise<TModel[]>; plans?: readonly string[];
+      unpriced?: string; ignoreLimits?: boolean },
+    signalArg: AbortSignal): Promise<{ kind: 'candidate'; model: TModel; limits: IAccountLimits; spendLimit: boolean }
+      | { kind: 'refused'; unavailable: IInferenceAccountUnavailable } | undefined> {
+    const apiKey = accountArg.credential === 'api_key';
+    const refused = (unavailableArg: IInferenceAccountUnavailable) => ({ kind: 'refused' as const, unavailable: unavailableArg });
+    // A payment problem refuses the account before anything else is judged, whatever limits a request ignores.
+    const problem = this.paymentProblem(accountArg.id, usageArg);
+    if (problem) {
+      stateArg.payment.push({ label: accountArg.label, credential: accountArg.credential, unavailable: problem });
+      this.noteAccount(accountArg.id, problem);
+      return refused(problem);
+    }
+    if (this.noted.get(accountArg.id)?.unavailable.reason === 'payment_problem') this.noteAccount(accountArg.id, null);
+    if (!limitsArg) {
+      stateArg.unavailable = true;
+      const unavailable: IInferenceAccountUnavailable = apiKey ? { reason: 'spend_unread' }
+        : { reason: 'usage_unread', retryAt: usageArg?.nextAttemptAt ?? null };
+      if (apiKey) stateArg.spendUnread.push(accountArg.label);
+      this.noteAccount(accountArg.id, unavailable);
+      return refused(unavailable);
+    }
+    // A key with a spend limit whose spend the proxy relayed is recorded nowhere yet takes nothing while it is not,
+    // whatever its spend: the account service's ledger lacks those answers.
+    const spendLimit = apiKey && keyHasSpendLimit(usageArg, accountArg);
+    if (spendLimit && this.options.spend?.held(accountArg.id)) {
+      stateArg.unavailable = true;
+      stateArg.spendUnrecorded.push(accountArg.label);
+      const unavailable: IInferenceAccountUnavailable = { reason: 'spend_unrecorded' };
+      this.noteAccount(accountArg.id, unavailable);
+      return refused(unavailable);
+    }
+    const notedReason = this.noted.get(accountArg.id)?.unavailable.reason;
+    if (notedReason === 'usage_unread' || notedReason === 'spend_unread' || notedReason === 'spend_unrecorded') {
+      this.noteAccount(accountArg.id, null);
+    }
+    if (optionsArg.plans && !optionsArg.plans.includes(limitsArg.plan)) return undefined;
+    const cooldown = cooldownUntil(this.cooldowns.get(accountArg.id), apiKey ? undefined : usageArg);
+    if (!optionsArg.ignoreLimits && (limitsArg.state !== 'available' || cooldown > this.now())) {
+      const held = this.heldList(optionsArg.lists, accountArg);
+      if (held && !held.some((entry) => entry.modelId === optionsArg.modelId)) return refused({ reason: 'model_missing' });
+      if (held) stateArg.modelKnown = true;
+      stateArg.exhausted = true;
+      stateArg.reserved ||= limitsArg.state === 'reserved';
+      stateArg.accountLimit = limitsArg.state === 'available' ? 'cooling' : limitsArg.state;
+      // A key has no plan to name.
+      if (limitsArg.plan) stateArg.exhaustedPlans.add(limitsArg.plan);
+      if (limitsArg.state === 'exhausted' && usageArg?.reading?.kind === 'spend') {
+        stateArg.spendLimited.push({ accountId: accountArg.id, label: accountArg.label, spend: usageArg.reading.spend });
+      }
+      const reset = Math.max(cooldown, limitsArg.resetAt ?? 0);
+      if (reset > this.now()) stateArg.earliestReset = Math.min(stateArg.earliestReset, reset);
+      return undefined;
+    }
+    if (spendLimit && optionsArg.unpriced !== undefined && !optionsArg.ignoreLimits) {
+      stateArg.unpriced.labels.push(accountArg.label);
+      stateArg.unpriced.what ??= optionsArg.unpriced;
+      return refused({ reason: 'model_unpriced', failure: optionsArg.unpriced });
+    }
+    const model = (await optionsArg.read(accountArg, signalArg)).find((entry) => entry.modelId === optionsArg.modelId);
+    if (!model) return refused({ reason: 'model_missing' });
+    stateArg.modelKnown = true;
+    return { kind: 'candidate', model, limits: limitsArg, spendLimit };
+  }
+
+  /**
+   * A Claude account or an Anthropic API key for one of Claude Code's requests, or an Anthropic API key for one of
+   * Flex's, chosen as `acquire` chooses: the pinned session account if it is still eligible, else the least busy account
+   * with the most headroom whose current reading shows it available -- every counted window under its threshold, no
+   * provider retry ahead -- with no cooldown after a provider 429, and which lists the model. A key is judged on its
+   * month's spend (`keyLimits`): at its spend limit it takes no request until the month ends, as an account at its limit,
+   * and a session on it moves; with a limit and no readable spend it is refused (`spend_unread`). A pool that names no
+   * credential places on its Claude accounts first and on its keys only when no Claude account can take the request, for
+   * whatever reason (`inferenceCredentialTiers`).
    * `ignoreLimits` serves a request that uses no quota (`count_tokens`) on an account at its limit as well. A pinned
    * account that takes no request for a reason of its own -- no usage reading, no model list, no access, or no such
    * model -- is refused naming the account and the reason (`InferenceRoutingError.reason`). An unpinned request whose
-   * chosen account's access fails goes to the next candidate.
+   * chosen account's access fails goes to the next candidate. `returnToBetterTier`: a session pinned to a key goes back
+   * to a Claude account as soon as one can take its request, and the route says so (`returned`).
    *
-   * A Claude account held with a payment problem -- Anthropic answered a request on it with a billing error (HTTP 402),
-   * as its usage reading says or this proxy saw (`reportPaymentProblem`) -- takes no request, `count_tokens` included,
-   * and is refused for the reason `payment_problem`. So is an account of `exclude` that `paymentExcluded` names: the
-   * request left it for a payment problem. Neither counts as at its limit: when such accounts are all that is left the
-   * refusal is a 402 `payment_problem` naming them, and while another account is merely at its limit the 429 stands.
+   * An account held with a payment problem -- Anthropic answered a request on it with a billing error (HTTP 402), or on
+   * a key with its organization's spend cap (HTTP 429 `enforced_spend_limit_reached`), as its usage reading says or this
+   * proxy saw (`reportPaymentProblem`) -- takes no request, `count_tokens` included, and is refused for the reason
+   * `payment_problem`. So is an account of `exclude` that `excludedBecause` names with a payment problem: the request
+   * left it for one. Neither counts as at its limit: when such accounts are all that is left the refusal is a 402
+   * `payment_problem` naming them, and while another account is merely at its limit the 429 stands. Any other account
+   * of `exclude` that `excludedBecause` names counts as its reason counts on the account's own judgement: a key whose
+   * spend could not be read is named in the 503, an account without the model leads to the 404, and every other reason
+   * to the 503 for want of an account -- never to the 429 of accounts at their limits.
    */
   public async acquireClaude(modelIdArg: string, policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal,
-    optionsArg: { accountId?: string; exclude?: ReadonlySet<string>; paymentExcluded?: ReadonlySet<string>;
-      ignoreLimits?: boolean } = {}): Promise<IInferenceClaudeRoute> {
+    optionsArg: IInferenceClaudeAcquireOptions = {}): Promise<IInferenceClaudeRoute> {
     if (policyArg.provider !== 'anthropic') throw new Error('A Claude route belongs to a Claude pool.');
-    const candidates: ICandidate<TInferenceClaudeModel>[] = [];
-    let exhausted = false;
-    let reserved = false;
-    let modelKnown = false;
-    let unavailable = false;
-    let earliestReset = Infinity;
-    let accountLimit: TInferenceAccountLimit | undefined;
-    /** Why the last account judged takes no request though no limit says so: a pinned refusal names it. */
-    let refusal: IInferenceAccountUnavailable | undefined;
-    const exhaustedPlans = new Set<string>();
-    const payment: string[] = [];
-    const { accounts } = await this.sessionPool(policyArg, signalArg, optionsArg.accountId);
+    const { accounts, tiers } = await this.sessionPool(policyArg, signalArg, optionsArg.accountId);
     if (policyArg.credential === 'api_key' && !accounts.length) throw new InferenceRoutingError(503, 'no_eligible_accounts',
       'No Anthropic API key is added, and this pool runs on API keys alone, never on a Claude sign-in. Add one with '
         + '`authswitch account add anthropic-api-key`.');
-    for (const account of accounts) {
+    const pinned = accounts.find((account) => account.id === optionsArg.accountId);
+    if (pinned && optionsArg.returnToBetterTier && !optionsArg.ignoreLimits) {
+      // The session's account is of a later tier: an account of a better one that can take the request takes it, as a
+      // new session would be placed. When none can, the session stays where it is, judged as before.
+      const better = accounts.filter((account) => tiers.indexOf(account.credential) < tiers.indexOf(pinned.credential));
+      if (better.length) {
+        try {
+          const route = await this.routeClaude(modelIdArg, policyArg, better, tiers, signalArg, {
+            ...(optionsArg.exclude ? { exclude: optionsArg.exclude } : {}),
+            ...(optionsArg.excludedBecause ? { excludedBecause: optionsArg.excludedBecause } : {}),
+            ...(optionsArg.unpriced === undefined ? {} : { unpriced: optionsArg.unpriced }) });
+          return { ...route, returned: true };
+        } catch (errorArg) {
+          signalArg.throwIfAborted();
+          if (!(errorArg instanceof InferenceRoutingError)) throw errorArg;
+        }
+      }
+    }
+    return this.routeClaude(modelIdArg, policyArg, accounts, tiers, signalArg, optionsArg);
+  }
+
+  /** `acquireClaude` among `accountsArg`, the pool's accounts or those of its better tiers. */
+  private async routeClaude(modelIdArg: string, policyArg: IInferenceRoutingPolicy, accountsArg: readonly IInferenceAccount[],
+    tiersArg: readonly TInferenceCredential[], signalArg: AbortSignal,
+    optionsArg: IInferenceClaudeAcquireOptions): Promise<IInferenceClaudeRoute> {
+    const candidates: ICandidate<TInferenceClaudeModel>[] = [];
+    const selectionState = emptySelection(accountsArg.length, optionsArg.accountId !== undefined);
+    /** Why the last account judged takes no request though no limit says so: a pinned refusal names it. */
+    let refusal: IInferenceAccountUnavailable | undefined;
+    for (const account of accountsArg) {
       signalArg.throwIfAborted();
       if (optionsArg.accountId && optionsArg.accountId !== account.id) continue;
       if (optionsArg.exclude?.has(account.id)) {
-        if (optionsArg.paymentExcluded?.has(account.id)) { payment.push(account.label); continue; }
-        exhausted = true;
-        const reset = this.cooldowns.get(account.id)?.until ?? 0;
-        if (reset > this.now()) earliestReset = Math.min(earliestReset, reset);
+        // An account left for a reason of its own counts as that reason counts on its own judgement.
+        this.countLeft(selectionState, account, optionsArg.excludedBecause?.get(account.id));
         continue;
       }
       try {
         // A usage read the account service did not answer leaves the account as unread as a reading it cannot route on.
-        const usage = account.credential === 'api_key' ? undefined : await this.options.usage(account.id, signalArg)
+        // A key's usage is its month's spend, with the payment problem the account service holds on it.
+        const usage = await this.options.usage(account.id, signalArg)
           .catch(() => { signalArg.throwIfAborted(); return undefined; });
-        // A payment problem refuses the account before anything else is judged, whatever limits a request ignores.
-        if (account.credential !== 'api_key' && this.paymentRefused(account.id, usage)) {
-          refusal = { reason: 'payment_problem' };
-          payment.push(account.label);
-          this.noteAccount(account.id, refusal);
-          continue;
-        }
-        if (this.noted.get(account.id)?.unavailable.reason === 'payment_problem') this.noteAccount(account.id, null);
-        const limits = account.credential === 'api_key' ? apiKeyLimits
-          : usage ? claudeLimits(usage, account, this.now()) : undefined;
-        if (!limits) {
-          unavailable = true;
-          refusal = { reason: 'usage_unread', retryAt: usage?.nextAttemptAt ?? null };
-          this.noteAccount(account.id, refusal);
-          continue;
-        }
-        if (this.noted.get(account.id)?.unavailable.reason === 'usage_unread') this.noteAccount(account.id, null);
-        if (policyArg.plans && !policyArg.plans.includes(limits.plan)) continue;
-        // Limits and cool-down are judged before any model list is read: an account that cannot take the request now
-        // is never read for it. Its last model list, if one is held, says whether it would serve the model; without
-        // one it counts as limited, so a session on it moves rather than waiting for a list.
-        const cooldown = cooldownUntil(this.cooldowns.get(account.id), usage);
-        if (!optionsArg.ignoreLimits && (limits.state !== 'available' || cooldown > this.now())) {
-          const held = this.heldClaudeCatalog(account);
-          if (held && !held.some((entry) => entry.modelId === modelIdArg)) { refusal = { reason: 'model_missing' }; continue; }
-          if (held) modelKnown = true;
-          exhausted = true;
-          reserved ||= limits.state === 'reserved';
-          accountLimit = limits.state === 'available' ? 'cooling' : limits.state;
-          exhaustedPlans.add(limits.plan);
-          const reset = Math.max(cooldown, limits.resetAt ?? 0);
-          if (reset > this.now()) earliestReset = Math.min(earliestReset, reset);
-          continue;
-        }
-        const model = (await this.claudeCatalog(account, signalArg)).find((entry) => entry.modelId === modelIdArg);
-        if (!model) { refusal = { reason: 'model_missing' }; continue; }
-        modelKnown = true;
-        // A reading the router does not route on (`usage_unavailable`), and a key's absent one, score nothing.
+        const apiKey = account.credential === 'api_key';
+        const judged = await this.judgeListed(selectionState, account, usage, apiKey ? keyLimits(usage, account, this.now())
+          : usage ? claudeLimits(usage, account, this.now()) : undefined, {
+          modelId: modelIdArg, lists: this.claudeCatalogs, read: (accountArg, innerSignalArg) => this.claudeCatalog(accountArg, innerSignalArg),
+          ...(policyArg.plans ? { plans: policyArg.plans } : {}),
+          ...(optionsArg.unpriced === undefined ? {} : { unpriced: optionsArg.unpriced }),
+          ...(optionsArg.ignoreLimits ? { ignoreLimits: true } : {}) }, signalArg);
+        if (judged?.kind !== 'candidate') { if (judged) refusal = judged.unavailable; continue; }
+        const { model, limits, spendLimit } = judged;
+        // A reading the router does not route on (`usage_unavailable`), and a key's without a spend reading, score nothing.
         const placement = accountPlacement(limits.limit ? usage!.reading : null, account, this.now());
-        candidates.push({ account, model, reading: usage?.reading ?? null, ignoreLimits: optionsArg.ignoreLimits === true,
-          plan: limits.plan, headroom: limits.headroom, score: placement.score,
-          lastResort: placement.eligibility === 'last_resort' });
+        candidates.push({ account, tier: tiersArg.indexOf(account.credential), model,
+          reading: apiKey ? (limits.limit ? usage!.reading : null) : usage?.reading ?? null,
+          ignoreLimits: optionsArg.ignoreLimits === true, plan: limits.plan, headroom: limits.headroom,
+          score: placement.score, lastResort: placement.eligibility === 'last_resort', spendLimit });
       } catch (errorArg) {
         signalArg.throwIfAborted();
-        unavailable = true;
-        if (errorArg instanceof ClaudeCatalogError) refusal = errorArg.unavailable;
+        selectionState.unavailable = true;
+        if (errorArg instanceof ModelListError) refusal = errorArg.unavailable;
       }
     }
-    const selectionState: ISelectionState = { exhausted, reserved, unavailable, modelKnown, payment,
-      earliestReset, exhaustedPlans, accounts: accounts.length, pinned: optionsArg.accountId !== undefined, accountLimit,
-      ...(optionsArg.accountId !== undefined && refusal ? { refusal: { accountId: optionsArg.accountId, unavailable: refusal } } : {}) };
+    if (optionsArg.accountId !== undefined && refusal) {
+      selectionState.refusal = { accountId: optionsArg.accountId, unavailable: refusal };
+    }
     // The chosen account's access is resolved before anything is sent. One that fails takes no request, as a failed
     // access found reading its model list does: it is recorded and noted for the account, and the request goes to the
     // next candidate -- a pinned request has none, so it is refused naming the account and the reason.
@@ -1136,7 +1791,7 @@ export class InferenceRouter {
         release();
         signalArg.throwIfAborted();
         const failure: IInferenceAccountUnavailable = { reason: needsSignIn(errorArg) ? 'needs_login' : 'access_failed' };
-        this.holdClaudeFailure(selected.account, failure);
+        this.holdListFailure(this.claudeCatalogs, selected.account, failure);
         candidates.splice(candidates.indexOf(selected), 1);
         selectionState.unavailable = true;
         if (selectionState.pinned) selectionState.refusal = { accountId: selected.account.id, unavailable: failure };
@@ -1167,7 +1822,8 @@ export class InferenceRouter {
           ...(this.options.providerFetch ? { fetch: this.options.providerFetch } : {}),
         });
       return { provider: 'anthropic', credential, accountId: id, plan: selected.plan, score: selected.score,
-        model: selected.model, connection, release };
+        model: selected.model, connection, returned: false, loginId: selected.account.loginId, spendLimit: selected.spendLimit,
+        release };
     } catch (errorArg) {
       release();
       throw errorArg;
@@ -1189,9 +1845,9 @@ export class InferenceRouter {
   }
 
   /**
-   * The candidate a request goes to by the placement order (`authSwitchPlacementOrder`), or the refusal that says why there is
-   * none. A pinned request has its session's account as its one candidate, so the order only ever places new sessions.
-   * An account at its reserve is refused like one at its limit, and the refusal names the reserve. A pinned account
+   * The candidate a request goes to -- of the best credential tier, then by the placement order
+   * (`authSwitchPlacementOrder`) -- or the refusal that says why there is none. A pinned request has its session's
+   * account as its one candidate, so the order only ever places new sessions. An account at its reserve is refused like one at its limit, and the refusal names the reserve. A pinned account
    * that takes no request for a reason of its own (`refusal`) is refused with that account and reason.
    */
   private select<TModel>(candidatesArg: ICandidate<TModel>[], stateArg: ISelectionState): ICandidate<TModel> {
@@ -1213,51 +1869,70 @@ export class InferenceRouter {
       candidate.score = placement.score;
       return true;
     });
+    // The best credential tier first, then the placement order within it.
     const order = plugins.authswitchPlacement.authSwitchPlacementOrder((accountIdArg) => this.active.get(accountIdArg) ?? 0);
-    candidatesArg.sort((left, right) => order({ id: left.account.id, score: left.score, lastResort: left.lastResort,
-      headroom: left.headroom }, { id: right.account.id, score: right.score, lastResort: right.lastResort,
-      headroom: right.headroom }));
+    candidatesArg.sort((left, right) => left.tier - right.tier || order({ id: left.account.id, score: left.score,
+      lastResort: left.lastResort, headroom: left.headroom }, { id: right.account.id, score: right.score,
+      lastResort: right.lastResort, headroom: right.headroom }));
     const selected = candidatesArg[0];
     if (selected) return selected;
-    if (stateArg.exhausted) throw new InferenceRoutingError(429, 'accounts_exhausted',
+    // A refusal names the API keys held by their spend limit, and those with a limit whose spend could not be read.
+    const named = (messageArg: string, sentenceArg: string) => sentenceArg ? `${messageArg} ${sentenceArg}` : messageArg;
+    if (stateArg.exhausted) throw new InferenceRoutingError(429, 'accounts_exhausted', named(
       stateArg.pinned
         ? `The account that owns this conversation state is at its ${stateArg.reserved ? 'reserve' : 'limit'}.`
         : `All eligible accounts are at their limits${stateArg.reserved ? ' or their reserve' : ''}.`,
+      inferenceSpendLimitText(stateArg.spendLimited)),
       Number.isFinite(stateArg.earliestReset) ? Math.max(1, Math.ceil((stateArg.earliestReset - this.now()) / 1000)) : undefined,
-      [...stateArg.exhaustedPlans], stateArg.pinned ? stateArg.accountLimit : undefined);
+      [...stateArg.exhaustedPlans], stateArg.pinned ? stateArg.accountLimit : undefined, undefined, undefined,
+      stateArg.spendLimited);
     if (stateArg.pinned && stateArg.refusal) {
       const { accountId, unavailable } = stateArg.refusal;
       throw new InferenceRoutingError(503, 'no_eligible_accounts',
         `The account that owns this conversation state (${accountId}) takes no request: ${unavailableText(unavailable)}.`,
-        undefined, [], undefined, accountId, unavailable.reason);
+        undefined, [], undefined, accountId, unavailable);
     }
     if (stateArg.payment.length && !stateArg.unavailable) {
-      throw new InferenceRoutingError(402, 'payment_problem', `Anthropic answered a billing error (HTTP 402) for the`
-        + ` Claude ${stateArg.payment.length === 1 ? 'account' : 'accounts'} ${stateArg.payment.join(', ')}: a payment`
-        + ' problem with the subscription. Settle the billing, then re-check the account in AGL Accounts or with'
-        + ' `authswitch account recheck <account-id>`.');
+      throw new InferenceRoutingError(402, 'payment_problem', paymentRefusalText(stateArg.payment));
     }
+    if (stateArg.unpriced.labels.length && !stateArg.unavailable) {
+      const keys = [...new Set(stateArg.unpriced.labels)];
+      throw new InferenceRoutingError(400, 'model_unpriced', `The API ${keys.length === 1 ? 'key' : 'keys'} ${keys.join(', ')} `
+        + `${keys.length === 1 ? 'has' : 'have'} a monthly spend limit set in AGL, and AGL's price table has no price for `
+        + `${stateArg.unpriced.what ?? 'this request'}, so the cost of the answer could not be counted against the limit. `
+        + 'Send it with a model, service tier, speed and tools the price table prices, or remove the spend limit in AGL '
+        + 'Accounts.');
+    }
+    const keysNamed = (labelsArg: readonly string[], whatArg: string): string => labelsArg.length
+      ? `The spend of the API ${labelsArg.length === 1 ? 'key' : 'keys'} ${labelsArg.join(', ')} ${whatArg}, and AGL `
+        + 'places nothing on a key with a monthly spend limit until it can.' : '';
     if (!stateArg.accounts || stateArg.unavailable || stateArg.pinned) throw new InferenceRoutingError(503, 'no_eligible_accounts',
-      'No eligible account has current usage, an available sign-in, and access to the requested model.');
+      named('No eligible account has current usage, an available sign-in, and access to the requested model.',
+        [keysNamed(stateArg.spendUnread, 'could not be read'),
+          keysNamed(stateArg.spendUnrecorded, 'could not be recorded')]
+          .filter(Boolean).join(' ')));
     throw new InferenceRoutingError(404, 'model_not_available', stateArg.modelKnown
       ? 'No eligible account supports the requested model options.' : 'The requested model is not available to this account pool.');
   }
 
   /**
    * The accounts as `agl proxy status` shows them: each judged as placement would judge it on the reading `heldArg`
-   * answers for it, which the caller read beforehand -- an Anthropic API key, which has none, as `apiKeyLimits` judges it -- with
+   * answers for it, which the caller read beforehand -- an API key on its month's spend (`keyLimits`), in dollars -- with
    * its cooldown, the requests it serves now, its lifecycle and where a new session of an unrestricted client of its
-   * pool would go (`placementRank`).
+   * provider would go (`placementRank`): a client that names no credential, so a provider's subscriptions rank before its
+   * keys (`inferenceCredentialTiers`).
    */
   public accountStatus(accountsArg: readonly IInferenceAccount[],
     heldArg: (accountIdArg: string) => plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined): IInferenceAccountStatus[] {
     const now = this.now();
     const statuses = accountsArg.map((account): IInferenceAccountStatus => {
       const apiKey = account.credential === 'api_key';
-      const held = apiKey ? undefined : heldArg(account.id);
-      const limits = apiKey ? apiKeyLimits
+      // A key's usage is its month's spend, with the payment problem the account service holds on it.
+      const held = heldArg(account.id);
+      const limits = apiKey ? keyLimits(held, account, now)
         : held ? (account.providerId === 'anthropic' ? claudeLimits : chatGptLimits)(held, account, now) : undefined;
-      const cooldown = cooldownUntil(this.cooldowns.get(account.id), held);
+      // A key's spend reading says nothing of the provider's rate limits, so only its own end ends a key's cool-down.
+      const cooldown = cooldownUntil(this.cooldowns.get(account.id), apiKey ? undefined : held);
       const placement = accountPlacement(limits?.limit ? held!.reading : null, account, now);
       const base = { id: account.id, label: account.label, provider: account.providerId, credential: account.credential,
         maxUsagePercent: account.maxUsagePercent, reserveLiftUntil: account.reserveLiftUntil, inFlight: this.active.get(account.id) ?? 0,
@@ -1270,39 +1945,43 @@ export class InferenceRouter {
           .some((windowArg) => windowArg.estimatedUsedPercent !== null),
         lastReadRateLimited: held?.lastReadError?.rateLimited ?? false };
       // A payment problem refuses the account whatever its reading says, as a request finds it.
-      if (!apiKey && account.providerId === 'anthropic' && this.paymentRefused(account.id, held)) {
-        const unavailable: IInferenceAccountUnavailable = { reason: 'payment_problem' };
-        return { ...base, state: 'unavailable', stateText: `unavailable (${unavailableText(unavailable)})`, unavailable,
+      const unpaid = this.paymentProblem(account.id, held);
+      if (unpaid) {
+        return { ...base, state: 'unavailable', stateText: `unavailable (${unavailableText(unpaid)})`, unavailable: unpaid,
           plan: limits?.plan || null, headroom: null, crossing: [], resetAt: null };
       }
-      if (!limits) {
-        const unavailable: IInferenceAccountUnavailable = { reason: 'usage_unread', retryAt: held?.nextAttemptAt ?? null };
+      const unrecorded = apiKey && limits && keyHasSpendLimit(held, account) && this.options.spend?.held(account.id) === true;
+      if (!limits || unrecorded) {
+        const unavailable: IInferenceAccountUnavailable = unrecorded ? { reason: 'spend_unrecorded' }
+          : apiKey ? { reason: 'spend_unread' } : { reason: 'usage_unread', retryAt: held?.nextAttemptAt ?? null };
         return { ...base, state: 'unavailable', stateText: `unavailable (${unavailableText(unavailable)})`, unavailable,
           plan: null, headroom: null, crossing: [], resetAt: null };
       }
       // An account whose model list a request could not read takes no request until it is read again; one at its limit
       // or cooling down is judged on that alone, as a request judges it.
-      const refusal = account.providerId === 'anthropic' ? this.catalogRefusal(account) : undefined;
+      const refusal = this.listRefusal(account);
       const state = limits.state === 'available' && cooldown > now ? 'cooling'
         : limits.state === 'available' && refusal ? 'unavailable' : limits.state;
       return { ...base, state, ...(state === 'unavailable' && refusal ? { unavailable: refusal } : {}),
         stateText: placement.lifecycle === 'lapsed' ? 'lapsed (its subscription ended; never routed to again)'
           : state === 'cooling' ? 'cooling down after a provider 429'
             : state === 'unavailable' && refusal ? `unavailable (${unavailableText(refusal)})`
-            : limits.limit ? plugins.authswitchUsageLimit.authSwitchUsageLimitText(limits.limit)
-              : apiKey ? 'available (an API key; no usage is read for it)' : 'available (no usage reported)',
+            : apiKey ? keyStateText(limits, held, now)
+              : limits.limit ? plugins.authswitchUsageLimit.authSwitchUsageLimitText(limits.limit)
+                : 'available (no usage reported)',
         plan: limits.plan || null, headroom: limits.limit?.headroom ?? null, crossing: limits.limit?.crossing ?? [],
         resetAt: state === 'cooling' ? new Date(cooldown).toISOString() : limits.limit?.resetAt ?? null };
     });
-    // Each pool's accounts that take a new session now, in the order placement takes them.
+    // Each provider's accounts that take a new session now, in the order placement takes them: the best credential tier
+    // first.
     const order = plugins.authswitchPlacement.authSwitchPlacementOrder((accountIdArg) => this.active.get(accountIdArg) ?? 0);
-    const poolOf = (statusArg: IInferenceAccountStatus) => `${statusArg.provider}:${statusArg.credential}`;
-    for (const pool of new Set(statuses.map(poolOf))) {
-      statuses.filter((statusArg) => poolOf(statusArg) === pool && statusArg.state === 'available'
+    const tiers = inferenceCredentialTiers(undefined);
+    for (const provider of new Set(statuses.map((statusArg) => statusArg.provider))) {
+      statuses.filter((statusArg) => statusArg.provider === provider && statusArg.state === 'available'
         && statusArg.lifecycle !== 'lapsed')
-        .map((statusArg) => ({ status: statusArg, rank: { id: statusArg.id, score: statusArg.placementScore,
-          lastResort: statusArg.lastResort, headroom: statusArg.headroom ?? unknownHeadroom } }))
-        .sort((left, right) => order(left.rank, right.rank))
+        .map((statusArg) => ({ status: statusArg, tier: tiers.indexOf(statusArg.credential), rank: { id: statusArg.id,
+          score: statusArg.placementScore, lastResort: statusArg.lastResort, headroom: statusArg.headroom ?? unknownHeadroom } }))
+        .sort((left, right) => left.tier - right.tier || order(left.rank, right.rank))
         .forEach((entryArg, indexArg) => { entryArg.status.placementRank = indexArg + 1; });
     }
     return statuses;
@@ -1333,21 +2012,25 @@ export class InferenceRouter {
   }
 
   /**
-   * Anthropic refused a request on the Claude account with a billing error (HTTP 402 `billing_error`): the account is out
-   * of rotation at once, and the account service is told (`reportPaymentProblem`). Once it holds the problem the
-   * account's usage carries it, and that decides from then on, so the router's own mark is dropped; when the service
-   * cannot be told -- it is not running, or an older release that does not know the report -- the mark holds for as long
-   * as the proxy runs, and the failure is reported once. An API key's 402 is no payment problem the service holds.
+   * A provider refused a request on the account for a payment problem (`TInferencePaymentCause`): the account is out of
+   * rotation at once, and the refusal it now carries is answered. The problem is reported to the account service
+   * (`reportPaymentProblem`); once it holds the problem the account's usage carries it, and that decides from then on --
+   * until a re-check clears it, or a spend cap's month ends -- so the router's own mark is dropped. When the service
+   * cannot be told -- it is not running, or an older release that does not know the report or the account's kind --
+   * the mark holds, a spend cap until 00:00 UTC on the first day of the next month (`authSwitchSpendPeriod`), anything
+   * else for as long as the proxy runs, and the failure is reported once.
    */
-  public reportPaymentProblem(accountIdArg: string): void {
-    if (this.apiKeyAccounts.has(accountIdArg)) return;
+  public reportPaymentProblem(accountIdArg: string, causeArg: TInferencePaymentCause): IInferenceAccountUnavailable {
     const at = this.now();
-    this.paymentMarks.set(accountIdArg, at);
-    this.noteAccount(accountIdArg, { reason: 'payment_problem' });
+    const mark: IPaymentMark = { at, cause: causeArg,
+      until: causeArg === 'spend_cap' ? Date.parse(plugins.authswitchSpend.authSwitchSpendPeriod(at).end) : null };
+    this.paymentMarks.set(accountIdArg, mark);
+    const unavailable = paymentUnavailable(mark);
+    this.noteAccount(accountIdArg, unavailable);
     const report = this.options.reportPaymentProblem;
-    if (!report) return;
-    void (async () => report(accountIdArg, new Date(at).toISOString()))().then(() => {
-      if (this.paymentMarks.get(accountIdArg) === at) this.paymentMarks.delete(accountIdArg);
+    if (!report) return unavailable;
+    void (async () => report(accountIdArg, new Date(at).toISOString(), causeArg))().then(() => {
+      if (this.paymentMarks.get(accountIdArg) === mark) this.paymentMarks.delete(accountIdArg);
     }, (errorArg: unknown) => {
       if (this.paymentReportsFailed.has(accountIdArg)) return;
       this.paymentReportsFailed.add(accountIdArg);
@@ -1357,12 +2040,24 @@ export class InferenceRouter {
           error: (errorArg instanceof Error ? `${errorArg.name}: ${errorArg.message}` : String(errorArg)).replace(/\s+/gu, ' ') });
       } catch {}
     });
+    return unavailable;
   }
 
-  /** Whether a Claude account is held with a payment problem: by its usage reading, or by this proxy's own mark. */
-  private paymentRefused(accountIdArg: string,
-    usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined): boolean {
-    return this.paymentMarks.has(accountIdArg) || usageArg?.paymentProblem !== undefined;
+  /**
+   * The payment problem an account is held with, as a refusal: by this proxy's own mark while it holds -- a spend cap's
+   * ends at its time -- or by the account's usage reading, which carries it once the account service holds it, with its
+   * cause (absent: `billing`) and, for a spend cap, when it ends; one whose spend cap ended holds nothing
+   * (`authSwitchPaymentProblemHeld`, the rule the account service holds it by).
+   */
+  private paymentProblem(accountIdArg: string,
+    usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined): IInferenceAccountUnavailable | undefined {
+    const now = this.now();
+    const mark = this.paymentMarks.get(accountIdArg);
+    if (mark && (mark.until === null || mark.until > now)) return paymentUnavailable(mark);
+    if (mark) this.paymentMarks.delete(accountIdArg);
+    const held = usageArg?.paymentProblem;
+    return held === undefined || !plugins.authswitchSubscription.authSwitchPaymentProblemHeld(held, now) ? undefined
+      : { reason: 'payment_problem', cause: held.cause ?? 'billing', ...(held.until === undefined ? {} : { retryAt: held.until }) };
   }
 
   /** A provider answer's `Retry-After`, in seconds from now, in either of its forms. */
@@ -1379,11 +2074,28 @@ export class InferenceRouter {
     this.options.tokens?.(accountIdArg, usageArg);
   }
 
+  /**
+   * Takes the spend of an answer an API key served on the login `loginIdArg` (`inferenceAnthropicSpend`): it counts
+   * against the key's limit from now on and is reported to the account service (`spend`).
+   */
+  public recordSpend(accountIdArg: string, loginIdArg: string | null, recordArg: IInferenceSpendRecord): void {
+    this.options.spend?.record(accountIdArg, loginIdArg, recordArg);
+  }
+
+  /**
+   * Says that an answer an API key served ended before its provider stated its usage, so nothing of it counts against
+   * the key's limit (`IInferenceSpendLedger.uncounted`).
+   */
+  public uncountedSpend(accountIdArg: string, modelArg: string): void {
+    this.options.spend?.uncounted(accountIdArg, modelArg);
+  }
+
   /**
    * A provider 429 on the account. Only a definitive pre-stream refusal permits another account to be tried. The
    * account cools down for the provider's `Retry-After`, at most a day; without one, or with one already due, for 60
    * seconds or until the account service holds a usage read made after the 429 (see `cooldownUntil`), which the 429
-   * asks it to make at once. An API key, whose usage the account service does not read, cools down the 60 seconds.
+   * asks it to make at once. An API key, whose spend reading says nothing of the provider's rate limits, cools down
+   * the 60 seconds.
    */
   public reportQuota(accountIdArg: string, retryAfterSecondsArg?: number): void {
     const explicit = Number.isFinite(retryAfterSecondsArg) && retryAfterSecondsArg! > 0;