mixdog 1.3.4 → 1.4.0

package/src/runtime/agent/orchestrator/mcp/oauth-provider.mjs

@@ -1,6 +1,6 @@
 import { normalizeMcpTransportUrl } from './client-config.mjs';
 import { withAccountParams } from './oauth-account.mjs';
-import { loginFailed, reauthenticationRequired } from './oauth-shared.mjs';
+import { loginFailed, missingScopes, reauthenticationRequired, scopeNotGranted } from './oauth-shared.mjs';
 
 /**
  * The SDK's OAuth client provider over one connection's credential `cache`
@@ -60,7 +60,17 @@ export function createOAuthProvider({ cache, flow, lifetimeSignal, client = null
       return creds.tokens;
     },
     saveTokens: async (value) => {
-      lifetimeSignal.throwIfAborted();
+      // The login's own deadline/cancel signal (oauth-login.mjs) when one runs.
+      const signal = flow.signal ?? lifetimeSignal;
+      signal.throwIfAborted();
+      // A browser sign-in of a client with its own scopes must be granted all
+      // of them (a granular consent screen lets the user uncheck some): nothing
+      // is stored, so the next connect asks again. A refresh is not checked.
+      if (flow.browserOpened && client?.scopes) {
+        const missing = missingScopes(client.scopes, value.scope);
+        if (missing.length) throw scopeNotGranted(missing);
+      }
+      const { tokens: priorTokens, identity: priorIdentity } = creds;
       await save(() => {
         creds.tokens = value;
         // A browser sign-in may be another account: its identity replaces the
@@ -69,6 +79,15 @@ export function createOAuthProvider({ cache, flow, lifetimeSignal, client = null
         if (flow.browserOpened) creds.identity = flow.identity ?? null;
         else if (flow.identity) creds.identity = flow.identity;
       });
+      // The login was reported failed while this write was outstanding: roll
+      // it back (same save path) so no tokens outlive the reported failure.
+      if (signal.aborted) {
+        await save(() => {
+          creds.tokens = priorTokens;
+          creds.identity = priorIdentity;
+        });
+        throw loginFailed();
+      }
     },
     saveCodeVerifier: (value) => {
       flow.verifier = value;

package/src/runtime/agent/orchestrator/mcp/oauth-shared.mjs

@@ -5,5 +5,28 @@ export const reauthenticationRequired = () =>
   });
 export const loginFailed = () => new Error('MCP OAuth login failed, cancelled, or timed out');
 
+// A sign-in whose token response lacks a requested scope (a provider's
+// granular consent let the user leave a box unchecked). The message names only
+// the scopes, never token data; callers match on the marker, which survives
+// the wrapping transports and connect paths apply to the message.
+export const SCOPE_NOT_GRANTED_MARKER = 'MCP OAuth scopeNotGranted';
+export const scopeNotGranted = (missing) =>
+  Object.assign(new Error(`${SCOPE_NOT_GRANTED_MARKER}: access not granted for ${missing.join(' ')}`), {
+    code: 'scopeNotGranted',
+    missingScopes: [...missing],
+  });
+
+// The basic identity scopes are never checked: Google answers a requested
+// `email` with its userinfo.email URL (likewise `profile`).
+const BASIC_SCOPES = new Set(['openid', 'email', 'profile']);
+
+/** The requested non-basic scopes a token response's `scope` leaves out. A
+ *  response without a `scope` field grants what was requested (RFC 6749). */
+export function missingScopes(requested, granted) {
+  if (typeof granted !== 'string') return [];
+  const have = new Set(granted.split(/\s+/).filter(Boolean));
+  return (requested || []).filter((scope) => !BASIC_SCOPES.has(scope) && !have.has(scope));
+}
+
 // `signal`, also aborted by the caller's optional `other` signal.
 export const anySignal = (signal, other) => AbortSignal.any(other ? [signal, other] : [signal]);

package/src/runtime/agent/orchestrator/mcp/oauth.mjs

@@ -21,7 +21,7 @@ import {
 import { createLoginFlow } from './oauth-login.mjs';
 import { createOAuthProvider } from './oauth-provider.mjs';
 import { createAuthorizedFetch } from './oauth-request.mjs';
-import { REAUTHENTICATION_REQUIRED_MESSAGE, anySignal } from './oauth-shared.mjs';
+import { REAUTHENTICATION_REQUIRED_MESSAGE, SCOPE_NOT_GRANTED_MARKER, anySignal } from './oauth-shared.mjs';
 
 export { MCP_OAUTH_CALLBACK_MAX_BYTES, MCP_OAUTH_CALLBACK_NOT_PENDING, parsePastedMcpOAuthCallback };
 
@@ -40,6 +40,16 @@ export function isMcpOAuthReauthenticationRequired(error) {
   return false;
 }
 
+/** Whether a sign-in failed because the provider did not grant a requested
+ *  scope (a real failure with its own message, not a plain "sign in"). */
+export function isMcpOAuthScopeNotGranted(error) {
+  for (let current = error, depth = 0; current && depth < 5; current = current.cause, depth++) {
+    if (current.code === 'scopeNotGranted') return true;
+    if (String(current.message ?? current).includes(SCOPE_NOT_GRANTED_MARKER)) return true;
+  }
+  return false;
+}
+
 // One keychain entry per exact server URL. Windows stores each account as a
 // file name, so the account is a hash of the URL and nothing else.
 export function mcpOAuthAccount(url) {

package/src/runtime/agent/orchestrator/providers/account-pool.mjs

@@ -1,5 +1,6 @@
 import {
   ACCOUNT_PROVIDERS,
+  MAX_ACCOUNTS,
   accountScopedSessionId,
   readProviderAccountPool,
   chooseProviderAccount,
@@ -9,11 +10,14 @@ import {
   providerAccountExhaustedForModelOnly,
   providerAccountPolicy,
   providerAccountsResetAt,
+  providerAccountWithBlocks,
+  providerAccountBlockedUntil,
+  staleQuotaWindows,
 } from '../../../shared/provider-accounts.mjs';
 import { withProviderAccount, hasExplicitProviderAuthBinding } from '../../../shared/provider-auth-binding.mjs';
 import { isExplicitUserAbortError, markProviderRecoveryExhausted } from './retry-classifier.mjs';
 import { sleepWithAbort } from './retry-backoff.mjs';
-import { QUOTA_KINDS, providerErrorKind } from './provider-error-kind.mjs';
+import { QUOTA_KINDS, boundedCauseChain, providerErrorKind } from './provider-error-kind.mjs';
 import { fetchOAuthUsageSnapshot, readCachedOAuthUsageSnapshot } from './oauth-usage.mjs';
 
 // Only an explicit quota / plan / billing refusal advances the roster as
@@ -124,15 +128,18 @@ function accountsExhaustedError(useCredits) {
 // evidence): a rate limit, advising the earliest cooldown end as the wait.
 // The pool already spent its cooldown wait, so this is a terminal verdict for
 // the loop, not an unclassified failure.
-function earliestCooldownMs(rows, now) {
-  const ends = rows.map((row) => Number(row.blockedUntil)).filter((until) => Number.isFinite(until) && until > now);
+// A row's cooldown for `model` ends when every block holding that model lifts.
+const coolingUntil = (row, model) => providerAccountBlockedUntil(row, model) ?? 0;
+
+function earliestCooldownMs(rows, now, model) {
+  const ends = rows.map((row) => coolingUntil(row, model)).filter((until) => until > now);
   return ends.length ? Math.min(...ends) - now : null;
 }
 
-function accountsCoolingDownError(rows, now) {
+function accountsCoolingDownError(rows, now, model) {
   const error = new Error('Every connected account is cooling down after a rate limit. Try again shortly.');
   error.code = 'rate_limited';
-  const wait = earliestCooldownMs(rows, now);
+  const wait = earliestCooldownMs(rows, now, model);
   if (wait != null) error.retryAfterMs = wait;
   return markProviderRecoveryExhausted(error, { owner: 'account-pool', terminal: true });
 }
@@ -258,6 +265,36 @@ function recordServingAccount(providerName, result, id, bindingId) {
   };
 }
 
+// A block covers the quota bucket of the model that failed, which only a usage
+// reading names. An account without a recorded reading is measured once before
+// it is blocked — once per account for this process, whatever the outcome,
+// through the ordinary cache (a fresh failed reading is not repeated) — and
+// again only after a reading has recorded windows and they were dropped.
+// Without a reading the block stays account-wide.
+const measureAttempted = new Set();
+
+async function measureOnce(providerName, row, account) {
+  const key = `${providerName}:${row.id}`;
+  if (row.usage?.windows?.length) {
+    measureAttempted.delete(key);
+    return;
+  }
+  if (measureAttempted.has(key)) return;
+  measureAttempted.add(key);
+  await fetchOAuthUsageSnapshot({ provider: providerName, accountId: row.id }, account(row.id), () => {}).catch(
+    () => null
+  );
+}
+
+// The server's id of the limit a refusal names (a Codex model-specific limit),
+// stamped on the error by the provider boundary.
+function quotaLimitOf(error) {
+  for (const item of boundedCauseChain(error)) {
+    if (typeof item?.quotaLimit === 'string' && item.quotaLimit) return item.quotaLimit;
+  }
+  return '';
+}
+
 // Whether the failed account's quota window is exhausted, plus the server's
 // retry delay. Anthropic and other subscriptions may use the same 429 code
 // for burst throttling and exhausted subscription windows, so the native
@@ -272,7 +309,7 @@ async function accountQuotaExhausted(providerName, row, model, error, account) {
   const policy = cooldownPolicyOf(account(row.id));
   const floorMs = policy ? finiteMs(policy.floorMs, 0) : 0;
   const blockUntil = (withReset, reason = 'unknown') => {
-    if (withReset && resetAt > now) return { until: resetAt, source: 'retry-after' };
+    if (withReset && resetAt > now) return { until: resetAt, source: 'retry-after', reset: true };
     if (delay > 0) return { until: now + Math.max(delay, floorMs), source: 'retry-after' };
     if (policy) {
       const ms = policyCooldownMs(policy, `${providerName}:${row.id}`, reason);
@@ -298,10 +335,14 @@ async function accountQuotaExhausted(providerName, row, model, error, account) {
     };
   }
   const typed = isAccountQuotaError(error);
-  if (typed) return { exhausted: true, delay, evidence: true, ...blockUntil(true, 'quota') };
+  if (typed) {
+    await measureOnce(providerName, row, account);
+    return { exhausted: true, delay, evidence: true, ...blockUntil(true, 'quota') };
+  }
   // A policy with rotateOnRateLimit rotates on a plain rate limit too (the
   // advice as its cooldown, else rateLimitedMs); never quota evidence.
   if (policy?.rotateOnRateLimit === true && kind === 'rate_limited' && status === 429) {
+    await measureOnce(providerName, row, account);
     return { exhausted: true, delay, evidence: false, ...blockUntil(false, 'rate_limited') };
   }
   let exhausted = status === 429 && delay > QUOTA_WINDOW_RETRY_AFTER_MS;
@@ -315,111 +356,185 @@ async function accountQuotaExhausted(providerName, row, model, error, account) {
     const pool = readProviderAccountPool(providerName);
     const entry = pool.accounts.find((item) => item.id === row.id);
     const options = { useCredits: pool.useCredits === true };
-    evidence = providerAccountExhausted({ ...entry, blockedUntil: 0 }, Date.now(), model, options);
+    evidence = providerAccountExhausted(providerAccountWithBlocks(entry), Date.now(), model, options);
     exhausted = exhausted || evidence || providerAccountExhausted(entry, Date.now(), model, options);
   }
-  return { exhausted, delay, evidence, ...(exhausted ? blockUntil(evidence, evidence ? 'quota' : 'unknown') : {}) };
+  const reason = evidence ? 'quota' : 'unknown';
+  return { exhausted, delay, evidence, ...(exhausted ? blockUntil(evidence, reason) : {}) };
+}
+
+// Record an exhausted verdict on the roster. An account-level block holds
+// every model, so it carries no model or limit scope.
+function blockRefusedAccount(providerName, accountId, model, error, verdict) {
+  const { evidence, until, source, reset, accountBlocked } = verdict;
+  return blockProviderAccount(providerName, accountId, until, accountBlocked ? '' : model, source, {
+    quota: evidence === true,
+    reset: reset === true,
+    limit: accountBlocked ? '' : quotaLimitOf(error),
+  });
+}
+
+/**
+ * A refusal `error` that account `accountId` gave outside the pool's send (a
+ * cache warm, which never rotates): judged and recorded on the roster exactly
+ * as the send would, with `instance` as that account's provider. Resolves
+ * whether the account was blocked.
+ */
+export async function recordAccountRefusal(providerName, accountId, model, error, instance) {
+  const row = readProviderAccountPool(providerName).accounts.find((entry) => entry.id === accountId);
+  if (!row) return false;
+  const verdict = await accountQuotaExhausted(providerName, row, model, error, () => instance);
+  if (!verdict.exhausted) return false;
+  await blockRefusedAccount(providerName, row.id, model, error, verdict);
+  return true;
+}
+
+// Whether every account in `ids` (default: the roster) is exhausted with quota
+// evidence: observed in this send (`evidenced`), or a full window.
+function rosterExhaustion(providerName, model, evidenced, ids) {
+  const pool = readProviderAccountPool(providerName);
+  // Manual policy: the eligible set is the selected account alone.
+  const scope = ids || (providerAccountPolicy(pool) === 'manual' ? [pool.selectedId] : null);
+  const rows = scope ? pool.accounts.filter((entry) => scope.includes(entry.id)) : pool.accounts;
+  const opts = { useCredits: pool.useCredits === true };
+  const now = Date.now();
+  const all =
+    rows.length > 0 &&
+    rows.every((entry) =>
+      providerAccountExhausted(
+        evidenced.has(entry.id) ? entry : providerAccountWithBlocks(entry, (block) => block.blockedQuota === true),
+        now,
+        model,
+        opts
+      )
+    );
+  return { rows, opts, now, all };
+}
+
+// Mark `error` only when every account in `ids` is exhausted with quota
+// evidence (`rosterExhaustion`). Without an error of its own, the send reports
+// quota exhaustion only on that evidence, and a rate-limit cooldown otherwise.
+function exhaustedSendError(providerName, model, evidenced, error, ids) {
+  const { rows, opts, now, all } = rosterExhaustion(providerName, model, evidenced, ids);
+  if (all) {
+    return quotaExhausted(error || accountsExhaustedError(opts.useCredits), providerName, model, rows, opts);
+  }
+  return error || accountsCoolingDownError(rows, now, model);
+}
+
+// The provider's bound on the time one send spends waiting for cooldowns.
+function cooldownWaitBoundMs(providerName, account, ids) {
+  const id = ids?.[0] || readProviderAccountPool(providerName).selectedId || 'default';
+  return finiteMs(cooldownPolicyOf(account(id))?.waitForCooldownMs, 0);
+}
+
+// A cooldown-only eligible set whose earliest cooldown ends inside the
+// remaining wait budget is waited out; otherwise the send fails as before.
+// `ledger` is the send's own record of the roster (see `poolSend`).
+async function waitOutCooldownOrThrow(request, ledger, error, ids) {
+  const { providerName, model, account, options } = request;
+  const { rows, now, all } = rosterExhaustion(providerName, model, ledger.evidenced, ids);
+  const bound = cooldownWaitBoundMs(providerName, account, ids);
+  // Persisting a short cooldown can outlast its deadline. Release only
+  // attempts cooled by this send, and only under an enabled wait policy.
+  const expired = bound > 0 && rows.some((row) => ledger.cooled.has(row.id) && !(coolingUntil(row, model) > now));
+  let wait = null;
+  if (!all) wait = expired ? 0 : earliestCooldownMs(rows, now, model);
+  if (wait == null || ledger.waitedMs + wait > bound) {
+    throw exhaustedSendError(providerName, model, ledger.evidenced, error, ids);
+  }
+  options.onStageChange?.('reconnecting', {
+    message: `Rate limited — every account is cooling down; retrying in ${Math.ceil(wait / 1000)}s`,
+    reason: 'rate_limited',
+    waitMs: wait,
+    retryAt: now + wait,
+  });
+  // A zero-duration sleep does not check cancellation, including on the
+  // final allowed send when no next loop iteration will check it either.
+  options.signal?.throwIfAborted();
+  await sleepWithAbort(wait, options.signal);
+  ledger.waitedMs += wait;
+  const lifted = Date.now();
+  for (const row of readProviderAccountPool(providerName).accounts) {
+    if (ledger.cooled.has(row.id) && !(coolingUntil(row, model) > lifted)) {
+      ledger.cooled.delete(row.id);
+      ledger.attempted.delete(row.id);
+    }
+  }
+}
+
+// No roster: with credit use off, a stored reading showing the plan's window
+// spent refuses before the implicit account sends.
+function throwIfPlanQuotaSpent(providerName, pool, model) {
+  if (pool.useCredits !== true) {
+    const stored = readCachedOAuthUsageSnapshot({ provider: providerName, model: '' });
+    // A snapshot cached before per-model gating is stale evidence.
+    if (stored?.quotaWindows?.length && !staleQuotaWindows(providerName, stored.quotaWindows)) {
+      const row = { usage: { windows: stored.quotaWindows, checkedAt: stored.cachedAt } };
+      if (providerAccountExhausted(row, Date.now(), model)) {
+        throw quotaExhausted(accountsExhaustedError(false), providerName, model, [row]);
+      }
+    }
+  }
+}
+
+// Headroom policy: a session's first pick, or its move off its account on a
+// limit, becomes the selection; continuing on its account does not, so
+// concurrent sessions never flip the selection back and forth. A move forced
+// by a model-scoped limit serves this request only (`scoped`). Stamps the
+// serving account on `result` and resolves whether the selection may commit.
+function bindServedAccount(providerName, result, rowId, model, binding) {
+  const { policy, boundId, sessionKey, switched, refusalScoped } = binding;
+  const leftBound = Boolean(boundId) && rowId !== boundId;
+  const scoped = switched
+    ? refusalScoped
+    : policy === 'headroom' && leftBound && accountExhaustedForModelOnly(providerName, boundId, model);
+  recordServingAccount(providerName, result, rowId, scoped && boundId ? boundId : rowId);
+  if (sessionKey && policy === 'headroom' && !scoped) rememberSessionAccount(sessionKey, rowId);
+  return { scoped, commit: policy !== 'headroom' || !boundId || leftBound };
+}
+
+// A failed attempt is never re-issued once output reached the caller or the
+// attempt was unsafe to retry (`unsafe`, judged by the caller and read only
+// when nothing was emitted).
+function attemptUnretryable(bound, error, unsafe) {
+  return Boolean(bound.emitted() || unsafe() || error.liveTextEmitted || error.emittedToolCall);
+}
+
+function rotationReason(evidence, accountBlocked) {
+  if (evidence) return 'Quota exhausted';
+  if (accountBlocked) return 'Account blocked';
+  return 'Rate limited (cooldown)';
 }
 
 // The pool's send: walks the eligible accounts until one answers, blocking
 // the ones whose quota window is exhausted along the way.
 function poolSend(providerName, account) {
   return async function send(messages, model, tools, options = {}) {
-    const attempted = new Set();
+    const request = { providerName, model, account, options };
+    // This send's record of the roster: the accounts it tried, those it found
+    // exhausted with quota evidence, those it blocked on a rate-limit
+    // cooldown, and the time it spent waiting for cooldowns.
+    const ledger = { attempted: new Set(), evidenced: new Set(), cooled: new Set(), waitedMs: 0 };
     let lastError;
     let probed = false;
-    const evidenced = new Set();
+    let sends = 0;
     const sessionKey = options.sessionId ? `${providerName}:${options.sessionId}` : null;
     const boundId = sessionAccountId(providerName, sessionKey, messages, options);
     // Whether this send already left an account, and whether the latest quota
     // refusal held only for this model's family.
     let switched = false;
     let refusalScoped = false;
-    // Mark `error` only when every account in `ids` (default: the roster) is
-    // exhausted with quota evidence: observed in this send, or a full window.
-    // Without an error of its own, the send reports quota exhaustion only on
-    // that evidence, and a rate-limit cooldown otherwise.
-    const exhaustion = (ids) => {
-      const pool = readProviderAccountPool(providerName);
-      // Manual policy: the eligible set is the selected account alone.
-      const scope = ids || (providerAccountPolicy(pool) === 'manual' ? [pool.selectedId] : null);
-      const rows = scope ? pool.accounts.filter((entry) => scope.includes(entry.id)) : pool.accounts;
-      const opts = { useCredits: pool.useCredits === true };
-      const now = Date.now();
-      const all =
-        rows.length > 0 &&
-        rows.every((entry) =>
-          providerAccountExhausted(
-            evidenced.has(entry.id) || entry.blockedQuota === true ? entry : { ...entry, blockedUntil: 0 },
-            now,
-            model,
-            opts
-          )
-        );
-      return { rows, opts, now, all };
-    };
-    const markExhausted = (error, ids) => {
-      const { rows, opts, now, all } = exhaustion(ids);
-      if (all) {
-        return quotaExhausted(error || accountsExhaustedError(opts.useCredits), providerName, model, rows, opts);
-      }
-      return error || accountsCoolingDownError(rows, now);
-    };
-    // Accounts this send blocked on a rate-limit cooldown, the time it spent
-    // waiting for cooldowns, and the provider's wait bound.
-    const cooled = new Set();
-    let waitedMs = 0;
-    let sends = 0;
-    const waitBoundMs = (ids) => {
-      const id = ids?.[0] || readProviderAccountPool(providerName).selectedId || 'default';
-      return finiteMs(cooldownPolicyOf(account(id))?.waitForCooldownMs, 0);
-    };
-    // A cooldown-only eligible set whose earliest cooldown ends inside the
-    // remaining wait budget is waited out; otherwise the send fails as before.
-    const waitOrThrow = async (error, ids) => {
-      const { rows, now, all } = exhaustion(ids);
-      const bound = waitBoundMs(ids);
-      // Persisting a short cooldown can outlast its deadline. Release only
-      // attempts cooled by this send, and only under an enabled wait policy.
-      const expired = bound > 0 && rows.some((row) => cooled.has(row.id) && !(Number(row.blockedUntil) > now));
-      const wait = all ? null : expired ? 0 : earliestCooldownMs(rows, now);
-      if (wait == null || waitedMs + wait > bound) throw markExhausted(error, ids);
-      options.onStageChange?.('reconnecting', {
-        message: `Rate limited — every account is cooling down; retrying in ${Math.ceil(wait / 1000)}s`,
-        reason: 'rate_limited',
-        waitMs: wait,
-        retryAt: now + wait,
-      });
-      // A zero-duration sleep does not check cancellation, including on the
-      // final allowed send when no next loop iteration will check it either.
-      options.signal?.throwIfAborted();
-      await sleepWithAbort(wait, options.signal);
-      waitedMs += wait;
-      const lifted = Date.now();
-      for (const row of readProviderAccountPool(providerName).accounts) {
-        if (cooled.has(row.id) && !(Number(row.blockedUntil) > lifted)) {
-          cooled.delete(row.id);
-          attempted.delete(row.id);
-        }
-      }
-    };
-    while (attempted.size < 20 && sends < 20) {
+    // One try per connectable account at most (provider-accounts.mjs MAX_ACCOUNTS).
+    while (ledger.attempted.size < MAX_ACCOUNTS && sends < MAX_ACCOUNTS) {
       options.signal?.throwIfAborted();
       const pool = readProviderAccountPool(providerName);
       if (!pool.accounts.length) {
-        if (pool.useCredits !== true) {
-          const stored = readCachedOAuthUsageSnapshot({ provider: providerName, model: '' });
-          if (stored?.quotaWindows?.length) {
-            const row = { usage: { windows: stored.quotaWindows, checkedAt: stored.cachedAt } };
-            if (providerAccountExhausted(row, Date.now(), model)) {
-              throw quotaExhausted(accountsExhaustedError(false), providerName, model, [row]);
-            }
-          }
-        }
+        throwIfPlanQuotaSpent(providerName, pool, model);
         return account('default').send(messages, model, tools, options);
       }
       const policy = providerAccountPolicy(pool);
-      const row = chooseProviderAccount(pool, attempted, Date.now(), model, { sessionAccountId: boundId });
+      const row = chooseProviderAccount(pool, ledger.attempted, Date.now(), model, { sessionAccountId: boundId });
       if (!row) {
         // Once per send: a refusal built on a stale meter must not outlive the
         // meter. Re-measuring can only widen the roster, so it is tried before
@@ -428,26 +543,22 @@ function poolSend(providerName, account) {
           probed = true;
           if (await probeRefusedAccounts(providerName, pool, model, account)) continue;
         }
-        await waitOrThrow(lastError);
+        await waitOutCooldownOrThrow(request, ledger, lastError);
         continue;
       }
-      attempted.add(row.id);
+      ledger.attempted.add(row.id);
       sends += 1;
       const bound = boundAccountSend(providerName, row, messages, options);
       try {
         const result = await account(row.id).send(bound.history, model, tools, bound.opts);
         quotaStrikes.delete(`${providerName}:${row.id}`);
-        // Headroom policy: a session's first pick, or its move off its account
-        // on a limit, becomes the selection; continuing on its account does
-        // not, so concurrent sessions never flip the selection back and forth.
-        // A move forced by a model-scoped limit serves this request only.
-        const leftBound = Boolean(boundId) && row.id !== boundId;
-        const scoped = switched
-          ? refusalScoped
-          : policy === 'headroom' && leftBound && accountExhaustedForModelOnly(providerName, boundId, model);
-        recordServingAccount(providerName, result, row.id, scoped && boundId ? boundId : row.id);
-        if (sessionKey && policy === 'headroom' && !scoped) rememberSessionAccount(sessionKey, row.id);
-        const commit = policy !== 'headroom' || !boundId || leftBound;
+        const { scoped, commit } = bindServedAccount(providerName, result, row.id, model, {
+          policy,
+          boundId,
+          sessionKey,
+          switched,
+          refusalScoped,
+        });
         if (commit && (await commitFallbackAccount(providerName, pool, row, model, scoped, policy))) {
           // Publish only a committed selection, never a speculative retry or
           // one superseded by a manual switch. The existing progress channel
@@ -466,59 +577,41 @@ function poolSend(providerName, account) {
       } catch (error) {
         if (options.signal?.aborted) throw error;
         if (error?.reauthRequired === true) {
-          if (
-            policy === 'manual' ||
-            bound.emitted() ||
-            error.unsafeToRetry ||
-            error.liveTextEmitted ||
-            error.emittedToolCall
-          )
-            throw error;
+          if (policy === 'manual' || attemptUnretryable(bound, error, () => error.unsafeToRetry)) throw error;
           lastError = error;
           switched = true;
           refusalScoped = false;
           options.onStageChange?.('reconnecting', { message: 'Sign-in expired — switching to the next account' });
           continue;
         }
-        const { exhausted, evidence, until, source, accountBlocked } = await accountQuotaExhausted(
-          providerName,
-          row,
-          model,
-          error,
-          account
-        );
+        const verdict = await accountQuotaExhausted(providerName, row, model, error, account);
+        const { exhausted, evidence, accountBlocked } = verdict;
         if (options.signal?.aborted || !exhausted) throw error;
-        if (evidence) evidenced.add(row.id);
-        else cooled.add(row.id);
-        await blockProviderAccount(providerName, row.id, until, model, source, { quota: evidence === true });
+        if (evidence) ledger.evidenced.add(row.id);
+        else ledger.cooled.add(row.id);
+        await blockRefusedAccount(providerName, row.id, model, error, verdict);
         // An account block is unsafe to re-issue on THAT account only; with no
         // output emitted, the next account may serve the same request.
-        if (
-          bound.emitted() ||
-          (error.unsafeToRetry && accountBlocked !== true) ||
-          error.liveTextEmitted ||
-          error.emittedToolCall
-        )
-          throw error;
+        if (attemptUnretryable(bound, error, () => error.unsafeToRetry && accountBlocked !== true)) throw error;
         // Manual policy: the eligible set is the selected account alone.
         if (policy === 'manual') {
-          await waitOrThrow(error, [row.id]);
+          await waitOutCooldownOrThrow(request, ledger, error, [row.id]);
           lastError = error;
           continue;
         }
         lastError = error;
         switched = true;
         refusalScoped = accountExhaustedForModelOnly(providerName, row.id, model);
-        options.onStageChange?.('reconnecting', {
-          message: evidence
-            ? 'Quota exhausted — switching to the next account'
-            : accountBlocked
-              ? 'Account blocked — switching to the next account'
-              : 'Rate limited (cooldown) — switching to the next account',
-        });
+        const reason = rotationReason(evidence, accountBlocked);
+        options.onStageChange?.('reconnecting', { message: `${reason} — switching to the next account` });
       }
     }
-    throw markExhausted(lastError || new Error('Provider account attempts exhausted.'));
+    throw exhaustedSendError(
+      providerName,
+      model,
+      ledger.evidenced,
+      lastError || new Error('Provider account attempts exhausted.')
+    );
   };
 }