mixdog 1.3.5 → 1.4.0

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -2,10 +2,11 @@ import { reloadProviderApiKey, resolveProviderApiKey } from '../../../shared/pro
 import { sanitizeToolPairs } from '../session/context-utils.mjs';
 import { AnthropicFallbackTriggeredError } from './retry-classifier.mjs';
 import {
-  announceAnthropicModelFallback,
   createAnthropicOverloadTracker,
   isTerminalOverloadModel,
+  takeAnthropicModelFallback,
 } from './anthropic-overload-fallback.mjs';
+import { removeAbortListener } from './anthropic-oauth-request/abort-wiring.mjs';
 import { readStreamOutcome } from './lib/stream-outcome.mjs';
 import { createPassthroughSignal } from '../stall-policy.mjs';
 import { createAbortController } from '../../../shared/abort-controller.mjs';
@@ -18,6 +19,7 @@ import { ANTHROPIC_EFFORT_LEVELS, withEffortRejectionFallback } from './effort-r
 import { armFirstByteWatchdog, createAnthropicApiTransport } from './anthropic-api-transport.mjs';
 import { createAnthropicApiRecovery } from './anthropic-api-recovery.mjs';
 import { buildAnthropicTurnResult } from './anthropic-turn-result.mjs';
+import { sendAnthropicCacheWarm } from './anthropic-cache-warm.mjs';
 import {
   assertAnthropicStreamNotEmpty,
   createAnthropicMidState,
@@ -38,6 +40,29 @@ import { streamCallbacks } from './lib/send-callbacks.mjs';
 import { preparePdfTextForProvider } from './media-normalization.mjs';
 export { _test, _toAnthropicMessagesForTest } from './anthropic-messages.mjs';
 
+// One stream attempt's controller, aborted with the caller's reason when the
+// send's signal aborts. An already-aborted send fails before the attempt.
+function linkAttemptAbort(totalSignal) {
+  const streamController = createAbortController();
+  let cancelHandler = null;
+
+  if (totalSignal) {
+    if (totalSignal.aborted) {
+      const reason = totalSignal.reason;
+      throw reason instanceof Error ? reason : new Error('Anthropic request aborted');
+    }
+    cancelHandler = () => {
+      try {
+        streamController.abort(totalSignal.reason);
+      } catch {
+        // best-effort propagation of caller cancellation
+      }
+    };
+    totalSignal.addEventListener('abort', cancelHandler, { once: true });
+  }
+  return { streamController, cancelHandler };
+}
+
 export class AnthropicProvider {
   // Takes a PDF as a native document block (decided by this adapter's wire protocol).
   nativePdf = true;
@@ -143,6 +168,38 @@ export class AnthropicProvider {
       throw err;
     }
   }
+  /**
+   * Cache-warm mode (anthropic-cache-warm.mjs): the request `send` would
+   * build for these arguments, sent once on the retry-free client — no
+   * key reload, fallback model or re-send — and cut at the first content
+   * block. `onUsage` receives the reported usage as it arrives.
+   */
+  async sendCacheWarm(messages, model, tools, opts = {}, { onUsage, accountId = '' } = {}) {
+    const prepared = await preparePdfTextForProvider(sanitizeToolPairs(messages), this);
+    const { params, requestHeaders } = await buildAnthropicApiRequest({
+      name: this.name,
+      config: this.config,
+      messages: prepared,
+      useModel: model,
+      tools,
+      opts,
+      fastModeLatched: this.fastModeBetaHeaderLatched,
+      modelInfo: isCustomProviderName(this.name) ? this.getCachedModelInfo?.(model) || null : null,
+      capabilityModel: this._capabilityModel(model),
+    });
+    return sendAnthropicCacheWarm({
+      providerName: this.name,
+      instance: this,
+      accountId,
+      model,
+      opts,
+      onUsage,
+      post: (signal) =>
+        this._currentClient()
+          .messages.create(params, { signal, ...(requestHeaders ? { headers: requestHeaders } : {}) })
+          .asResponse(),
+    });
+  }
   // The `anthropic` API-key provider and every custom `anthropic`-protocol
   // provider (a subclass of this one) share this send path.
   async _doSend(messages, model, tools, sendOpts) {
@@ -188,89 +245,20 @@ export class AnthropicProvider {
     const totalTimeout = createPassthroughSignal(externalSignal);
     const totalSignal = totalTimeout.signal;
 
-    const cleanupCancelHandler = (handler) => {
-      if (!handler) return;
-      try {
-        totalSignal.removeEventListener('abort', handler);
-      } catch {}
-    };
-
-    // Request-loop 529s and SSE overload events share one counter; at the
-    // limit the configured fallback model takes over the whole send.
-    const overload = createAnthropicOverloadTracker({
-      model: useModel,
-      fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
-      terminalAtLimit: !isCustomProviderName(this.name) && isTerminalOverloadModel(useModel),
-    });
-    // The SDK calls and their initial-response retry policy
-    // (anthropic-api-transport.mjs).
-    const transport = createAnthropicApiTransport({
-      client: this._currentClient(),
-      label: this.name,
+    const { transport, buildTurnResult, recovery, midstream } = this._createSendRecovery({
       opts,
       useModel,
       params,
       requestHeaders,
       totalSignal,
-      overload,
-    });
-    // Usage accounting + caller-visible projection, shared by the streaming
-    // success path and the non-streaming fallback (anthropic-turn-result.mjs).
-    const buildTurnResult = (parseResult) =>
-      buildAnthropicTurnResult(parseResult, { provider: this.name, useModel, opts });
-    // Non-streaming re-issue of a dead stream, behind the transport-recovery
-    // budget and the exposed-output retraction handshake
-    // (anthropic-api-recovery.mjs).
-    const recovery = createAnthropicApiRecovery({
-      label: this.name,
-      opts,
-      useModel,
-      params,
-      totalSignal,
-      transport,
-      buildTurnResult,
       onStageChange,
       onTextReset,
     });
-    // Bounded mid-stream retries for transient stream loss; jittered backoff
-    // between attempts (anthropic-midstream-recovery.mjs, shared with
-    // anthropic-oauth).
-    const midstream = createAnthropicMidstreamRecovery({
-      label: this.name,
-      displayName: 'Anthropic',
-      outcomeProvider: 'anthropic',
-      midstreamOwner: `${this.name}-midstream`,
-      unreachableMessage: 'Anthropic mid-stream retry: unreachable',
-      // The transport's withRetry already exhausted the full request-level
-      // budget for a non-OK initial response, so it must not earn an
-      // additional SSE retry budget here.
-      initialResponseErrorTerminal: true,
-      maxRetries: ANTHROPIC_MAX_MIDSTREAM_RETRIES,
-      totalSignal,
-      recovery,
-      onStageChange,
-      retry529: opts.retry529 !== false,
-      overload,
-    });
 
     let streamingFallbackTried = false;
     try {
       for (let attemptIndex = 0; attemptIndex <= ANTHROPIC_MAX_MIDSTREAM_RETRIES; attemptIndex++) {
-        const streamController = createAbortController();
-        let cancelHandler = null;
-
-        if (totalSignal) {
-          if (totalSignal.aborted) {
-            const reason = totalSignal.reason;
-            throw reason instanceof Error ? reason : new Error('Anthropic request aborted');
-          }
-          cancelHandler = () => {
-            try {
-              streamController.abort(totalSignal.reason);
-            } catch {}
-          };
-          totalSignal.addEventListener('abort', cancelHandler, { once: true });
-        }
+        const { streamController, cancelHandler } = linkAttemptAbort(totalSignal);
 
         const midState = createAnthropicMidState(attemptIndex);
 
@@ -280,13 +268,17 @@ export class AnthropicProvider {
         try {
           try {
             onStageChange?.('requesting');
-          } catch {}
+          } catch {
+            // the stage observer is advisory
+          }
 
           response = await transport.requestStreamingResponse();
 
           try {
             onStageChange?.('streaming');
-          } catch {}
+          } catch {
+            // the stage observer is advisory
+          }
 
           firstByte = armFirstByteWatchdog(streamController, midState);
 
@@ -307,7 +299,9 @@ export class AnthropicProvider {
           );
           try {
             streamController.abort?.('Anthropic SSE complete');
-          } catch {}
+          } catch {
+            // the stream is complete; the controller may already be aborted
+          }
 
           firstByte.cleanup();
           assertAnthropicStreamNotEmpty(midState, parseResult, 'Anthropic');
@@ -336,26 +330,80 @@ export class AnthropicProvider {
           return decision.value;
         } finally {
           firstByte?.cleanup();
-          cleanupCancelHandler(cancelHandler);
+          removeAbortListener(totalSignal, cancelHandler);
         }
       }
       throw midstream.exhaustedError();
     } catch (err) {
-      // The fallback trigger can surface from the request loop, a mid-stream
-      // overload, or the non-streaming recovery: handle it around the whole
-      // operation, not just the first request.
-      if (!(err instanceof AnthropicFallbackTriggeredError)) throw err;
-      process.stderr.write(`[${this.name}] ${err.message}\n`);
-      announceAnthropicModelFallback(onStageChange, useModel, err.fallbackModel);
-      return await this._doSend(messages, err.fallbackModel, tools, {
-        ...opts,
-        fallbackModel: undefined,
-        _fallbackTriggered: true,
-      });
+      const fallbackOpts = takeAnthropicModelFallback(err, { tag: this.name, model: useModel, opts, onStageChange });
+      return await this._doSend(messages, err.fallbackModel, tools, fallbackOpts);
     } finally {
       totalTimeout.cleanup();
     }
   }
+  // The recovery pipeline of one send over its fixed request: the shared
+  // overload counter, the transport, the turn-result projection, the
+  // non-streaming recovery and the bounded mid-stream retries.
+  _createSendRecovery({ opts, useModel, params, requestHeaders, totalSignal, onStageChange, onTextReset }) {
+    // Request-loop 529s and SSE overload events share one counter; at the
+    // limit the configured fallback model takes over the whole send.
+    const overload = createAnthropicOverloadTracker({
+      model: useModel,
+      fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
+      terminalAtLimit: !isCustomProviderName(this.name) && isTerminalOverloadModel(useModel),
+    });
+    // The SDK calls and their initial-response retry policy
+    // (anthropic-api-transport.mjs).
+    const transport = createAnthropicApiTransport({
+      client: this._currentClient(),
+      label: this.name,
+      opts,
+      useModel,
+      params,
+      requestHeaders,
+      totalSignal,
+      overload,
+    });
+    // Usage accounting + caller-visible projection, shared by the streaming
+    // success path and the non-streaming fallback (anthropic-turn-result.mjs).
+    const buildTurnResult = (parseResult) =>
+      buildAnthropicTurnResult(parseResult, { provider: this.name, useModel, opts });
+    // Non-streaming re-issue of a dead stream, behind the transport-recovery
+    // budget and the exposed-output retraction handshake
+    // (anthropic-api-recovery.mjs).
+    const recovery = createAnthropicApiRecovery({
+      label: this.name,
+      opts,
+      useModel,
+      params,
+      totalSignal,
+      transport,
+      buildTurnResult,
+      onStageChange,
+      onTextReset,
+    });
+    // Bounded mid-stream retries for transient stream loss; jittered backoff
+    // between attempts (anthropic-midstream-recovery.mjs, shared with
+    // anthropic-oauth).
+    const midstream = createAnthropicMidstreamRecovery({
+      label: this.name,
+      displayName: 'Anthropic',
+      outcomeProvider: 'anthropic',
+      midstreamOwner: `${this.name}-midstream`,
+      unreachableMessage: 'Anthropic mid-stream retry: unreachable',
+      // The transport's withRetry already exhausted the full request-level
+      // budget for a non-OK initial response, so it must not earn an
+      // additional SSE retry budget here.
+      initialResponseErrorTerminal: true,
+      maxRetries: ANTHROPIC_MAX_MIDSTREAM_RETRIES,
+      totalSignal,
+      recovery,
+      onStageChange,
+      retry529: opts.retry529 !== false,
+      overload,
+    });
+    return { transport, buildTurnResult, recovery, midstream };
+  }
   async listModels() {
     const apiKey = resolveProviderApiKey(this.name, this.config);
     if (!apiKey) return MODELS;

package/src/runtime/agent/orchestrator/providers/antigravity-transport.mjs

@@ -132,103 +132,12 @@ export function createAntigravityRequest({
   firstByte = ANTIGRAVITY_UNCLASSED_FIRST_BYTE,
   afterToolResult = false,
 }) {
-  const log = (attempt, lastErr, delayMs) => {
-    // A first-byte timeout runs on its own, shorter retry budget.
-    const firstByteLimited = isFirstByteTimeout(lastErr) && firstByte.retries != null;
-    emitProviderRetryStage(opts.onStageChange, {
-      attempt: attempt + 1,
-      maxAttempts: firstByteLimited
-        ? Math.min(ANTIGRAVITY_RETRY.maxAttempts, firstByte.retries + 1)
-        : ANTIGRAVITY_RETRY.maxAttempts,
-      lastErr,
-      delayMs,
-    });
-    process.stderr.write(`[antigravity] retry ${attempt + 1} after ${lastErr?.message || 'transient error'}\n`);
-  };
-  // Stamps what the attempt tells the user: how many attempts ran and, for a
-  // first-byte timeout, how long the model was given in total. A timeout past
-  // the first-byte retry budget ends the ladder here. A caller's cancellation
-  // reason may be shared by other requests and is never stamped.
-  const noteFailure = (err, { attemptSignal, windowMs, send }) => {
-    if (!err || typeof err !== 'object' || attemptSignal?.aborted) return err;
-    send.attempts += 1;
-    err.attempts = send.attempts;
-    if (!isFirstByteTimeout(err)) return err;
-    send.firstByteTimeouts += 1;
-    send.firstByteWaitedMs += windowMs;
-    err.waitedMs = send.firstByteWaitedMs;
-    err.providerLabel = 'Antigravity';
-    if (firstByte.retries != null && send.firstByteTimeouts > firstByte.retries) {
-      markProviderRecoveryExhausted(err, { owner: 'antigravity-first-byte', attempts: send.attempts, terminal: true });
-    }
-    return err;
-  };
+  const log = (attempt, lastErr, delayMs) =>
+    logAntigravityRetry(opts.onStageChange, firstByte, attempt, lastErr, delayMs);
   const attemptOnce = (send) =>
     withRetry(
-      async ({ signal: attemptSignal }) => {
-        try {
-          opts.onStageChange?.('requesting');
-        } catch {
-          /* heartbeat */
-        }
-        const windowMs = firstByteWindowMs(firstByte, send.firstByteTimeouts);
-        try {
-          const firstByteTimer = createTimeoutSignal(attemptSignal, windowMs, 'Antigravity first byte');
-          let res;
-          try {
-            const response = fetchFn(`${endpoint}/v1internal:streamGenerateContent?alt=sse`, {
-              method: 'POST',
-              headers,
-              body,
-              signal: firstByteTimer.signal,
-              dispatcher: getLlmDispatcher(),
-            });
-            // The request is on the wire and its headers are pending: the
-            // gateway sends them only with the first chunk, so this wait is
-            // the model's queueing and thinking time.
-            try {
-              opts.onStageChange?.(MODEL_THINKING_STAGE);
-            } catch {
-              /* heartbeat */
-            }
-            res = await response;
-          } catch (err) {
-            // Fetch surfaces AbortError; rethrow the timer/parent
-            // reason so same-host retry sees EPROVIDERTIMEOUT and
-            // a caller cancel stays a cancel.
-            if (firstByteTimer.signal.aborted && firstByteTimer.signal.reason instanceof Error) {
-              const reason = firstByteTimer.signal.reason;
-              if (!attemptSignal?.aborted) reason.timeoutPhase = TIMEOUT_PHASE.HEADERS;
-              throw reason;
-            }
-            throw err;
-          } finally {
-            firstByteTimer.cleanup();
-          }
-          // Headers arrived: the connection is live even while the model
-          // has not produced its first chunk.
-          try {
-            opts.onStreamDelta?.('transport');
-          } catch {}
-          if (!res.ok) {
-            const text = await res.text().catch(() => '');
-            const failure = antigravityError(res, text, endpoint);
-            // Capacity is paced by the local schedule below; the generic loop
-            // would sleep whatever wait the server names.
-            if (isCapacityFailure(failure)) markProviderRecoveryExhausted(failure, { owner: 'antigravity-capacity' });
-            throw failure;
-          }
-          try {
-            opts.onStageChange?.('streaming');
-          } catch {
-            /* heartbeat */
-          }
-          collector.beginAttempt();
-          return await collector.consume(res, attemptSignal, { firstByteTimeoutMs: windowMs });
-        } catch (err) {
-          throw noteFailure(err, { attemptSignal, windowMs, send });
-        }
-      },
+      ({ signal: attemptSignal }) =>
+        streamAttempt({ fetchFn, endpoint, headers, body, opts, collector, firstByte, send, attemptSignal }),
       {
         ...ANTIGRAVITY_RETRY,
         finalOnExhaust: true,
@@ -261,16 +170,128 @@ export function createAntigravityRequest({
         streamAttempt += 1;
         await sleepWithAbort(reask.waitMs, signal, sleepFn, 'Antigravity retry wait aborted');
       } catch (err) {
-        const waitMs = antigravity429WaitMs(err, state);
-        if (waitMs == null) {
-          if (isCapacityFailure(err)) {
-            markProviderRecoveryExhausted(err, { owner: 'antigravity-capacity', attempts: tried });
-          }
-          throw err;
-        }
+        const waitMs = scheduledRetryWaitMs(err, state, tried);
         log(tried, err, waitMs);
         await sleepWithAbort(waitMs, signal, sleepFn, 'Antigravity retry wait aborted');
       }
     }
   };
 }
+
+// The retry status and log line of one scheduled retry. A first-byte timeout
+// runs on its own, shorter retry budget.
+function logAntigravityRetry(onStageChange, firstByte, attempt, lastErr, delayMs) {
+  const firstByteLimited = isFirstByteTimeout(lastErr) && firstByte.retries != null;
+  emitProviderRetryStage(onStageChange, {
+    attempt: attempt + 1,
+    maxAttempts: firstByteLimited
+      ? Math.min(ANTIGRAVITY_RETRY.maxAttempts, firstByte.retries + 1)
+      : ANTIGRAVITY_RETRY.maxAttempts,
+    lastErr,
+    delayMs,
+    providerLabel: 'Antigravity',
+  });
+  process.stderr.write(`[antigravity] retry ${attempt + 1} after ${lastErr?.message || 'transient error'}\n`);
+}
+
+// The local wait before re-sending a failed request (429 / capacity schedule);
+// a failure the schedule does not retry is rethrown, a capacity one marked
+// exhausted after `tried` sends.
+function scheduledRetryWaitMs(err, state, tried) {
+  const waitMs = antigravity429WaitMs(err, state);
+  if (waitMs == null) {
+    if (isCapacityFailure(err)) {
+      markProviderRecoveryExhausted(err, { owner: 'antigravity-capacity', attempts: tried });
+    }
+    throw err;
+  }
+  return waitMs;
+}
+
+// One POST under the first-byte window: headers pending is the model's
+// thinking time, a non-OK body becomes the typed error, and a live stream is
+// handed to the collector for this attempt.
+async function streamAttempt({ fetchFn, endpoint, headers, body, opts, collector, firstByte, send, attemptSignal }) {
+  try {
+    opts.onStageChange?.('requesting');
+  } catch {
+    /* heartbeat */
+  }
+  const windowMs = firstByteWindowMs(firstByte, send.firstByteTimeouts);
+  try {
+    const firstByteTimer = createTimeoutSignal(attemptSignal, windowMs, 'Antigravity first byte');
+    let res;
+    try {
+      const response = fetchFn(`${endpoint}/v1internal:streamGenerateContent?alt=sse`, {
+        method: 'POST',
+        headers,
+        body,
+        signal: firstByteTimer.signal,
+        dispatcher: getLlmDispatcher(),
+      });
+      // The request is on the wire and its headers are pending: the
+      // gateway sends them only with the first chunk, so this wait is
+      // the model's queueing and thinking time.
+      try {
+        opts.onStageChange?.(MODEL_THINKING_STAGE);
+      } catch {
+        /* heartbeat */
+      }
+      res = await response;
+    } catch (err) {
+      // Fetch surfaces AbortError; rethrow the timer/parent
+      // reason so same-host retry sees EPROVIDERTIMEOUT and
+      // a caller cancel stays a cancel.
+      if (firstByteTimer.signal.aborted && firstByteTimer.signal.reason instanceof Error) {
+        const reason = firstByteTimer.signal.reason;
+        if (!attemptSignal?.aborted) reason.timeoutPhase = TIMEOUT_PHASE.HEADERS;
+        throw reason;
+      }
+      throw err;
+    } finally {
+      firstByteTimer.cleanup();
+    }
+    // Headers arrived: the connection is live even while the model
+    // has not produced its first chunk.
+    try {
+      opts.onStreamDelta?.('transport');
+    } catch {
+      // the stream-delta observer is advisory
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      const failure = antigravityError(res, text, endpoint);
+      // Capacity is paced by the local schedule; the generic loop
+      // would sleep whatever wait the server names.
+      if (isCapacityFailure(failure)) markProviderRecoveryExhausted(failure, { owner: 'antigravity-capacity' });
+      throw failure;
+    }
+    try {
+      opts.onStageChange?.('streaming');
+    } catch {
+      /* heartbeat */
+    }
+    collector.beginAttempt();
+    return await collector.consume(res, attemptSignal, { firstByteTimeoutMs: windowMs });
+  } catch (err) {
+    throw noteAttemptFailure(err, { attemptSignal, windowMs, send, firstByte });
+  }
+}
+
+// Stamps what the attempt tells the user: how many attempts ran and, for a
+// first-byte timeout, how long the model was given in total. A timeout past
+// the first-byte retry budget ends the ladder here. A caller's cancellation
+// reason may be shared by other requests and is never stamped.
+function noteAttemptFailure(err, { attemptSignal, windowMs, send, firstByte }) {
+  if (!err || typeof err !== 'object' || attemptSignal?.aborted) return err;
+  send.attempts += 1;
+  err.attempts = send.attempts;
+  if (!isFirstByteTimeout(err)) return err;
+  send.firstByteTimeouts += 1;
+  send.firstByteWaitedMs += windowMs;
+  err.waitedMs = send.firstByteWaitedMs;
+  if (firstByte.retries != null && send.firstByteTimeouts > firstByte.retries) {
+    markProviderRecoveryExhausted(err, { owner: 'antigravity-first-byte', attempts: send.attempts, terminal: true });
+  }
+  return err;
+}

package/src/runtime/agent/orchestrator/providers/cache-warm-admission.mjs

@@ -0,0 +1,90 @@
+// cache-warm-admission.mjs — the account gate of a cache warm
+// (anthropic-cache-warm.mjs). A warm never waits, queues, rotates accounts or
+// retries: right before its POST it reads the state a normal send consults
+// for the account it goes to — the Developer option, the account's admission
+// lane (rate-limit cooldown, a lane throttled after a 429), the account
+// roster's blocks and quota windows, and the session's quota-resume pause —
+// and is skipped when any of them holds or when no fresh quota reading says
+// the account has room. A warm's own refusal is recorded like a send's: a 429
+// in the lane cooldown, and the roster's verdict through the account pool.
+import {
+  ACCOUNT_PROVIDERS,
+  providerAccountExhausted,
+  quotaReadingFresh,
+  readProviderAccountPool,
+  staleQuotaWindows,
+} from '../../../shared/provider-accounts.mjs';
+import { quotaResumeEntry } from '../../../shared/quota-resume-store.mjs';
+import { recordAccountRefusal } from './account-pool.mjs';
+import { providerAdmissionKey, providerAdmissionScheduler } from './admission-scheduler.mjs';
+import { readCachedOAuthUsageSnapshot } from './oauth-usage.mjs';
+import { providerAvailable } from './provider-availability.mjs';
+
+function readingBlock(providerName, windows, checkedAt, now, exhausted) {
+  if (!Array.isArray(windows) || !quotaReadingFresh(checkedAt, now)) return 'no fresh quota reading';
+  if (staleQuotaWindows(providerName, windows)) return 'no fresh quota reading';
+  return exhausted ? 'account blocked or quota exhausted' : null;
+}
+
+function rosterBlock(providerName, accountId, model, now) {
+  if (!ACCOUNT_PROVIDERS.includes(providerName)) return null;
+  const pool = readProviderAccountPool(providerName);
+  const useCredits = pool.useCredits === true;
+  if (!pool.accounts.length) {
+    if (useCredits) return null;
+    const stored = readCachedOAuthUsageSnapshot({ provider: providerName, model: '' });
+    const row = stored ? { usage: { windows: stored.quotaWindows, checkedAt: stored.cachedAt } } : null;
+    return readingBlock(
+      providerName,
+      stored?.quotaWindows,
+      stored?.cachedAt,
+      now,
+      row && providerAccountExhausted(row, now, model)
+    );
+  }
+  if (!accountId) return 'account holding the cache unknown';
+  const row = pool.accounts.find((entry) => entry.id === accountId);
+  if (!row) return 'account not connected';
+  const exhausted = providerAccountExhausted(row, now, model, { useCredits });
+  if (useCredits) return exhausted ? 'account blocked' : null;
+  return readingBlock(providerName, row.usage?.windows, row.usage?.checkedAt, now, exhausted);
+}
+
+/**
+ * Why a warm on `instance` (account `accountId` of `providerName`; no id for
+ * a provider without an account roster) may not be sent now, or null. The
+ * instance's admission lane — the one its ordinary sends are admitted on —
+ * cooling down or throttled blocks it. Never waits.
+ */
+export function cacheWarmAccountBlock(
+  providerName,
+  instance,
+  { accountId = '', model = '', sessionId = '', scheduler = providerAdmissionScheduler, now = Date.now() } = {}
+) {
+  if (!providerAvailable(providerName)) return 'provider disabled';
+  const lane = scheduler.immediateBlock(providerAdmissionKey(providerName, instance));
+  if (lane) return lane;
+  if (sessionId && quotaResumeEntry(sessionId)) return 'session paused until its quota resets';
+  return rosterBlock(providerName, accountId, model, now);
+}
+
+/** The error a skipped warm rejects with (nothing was sent or billed). */
+export function cacheWarmBlockedError(reason) {
+  return Object.assign(new Error(`cache warm skipped: ${reason}`), { code: 'ECACHEWARMBLOCKED', usage: null });
+}
+
+/** Feed a warm's refusal into the shared state a send's would reach (the
+ *  lane keeps 429s only; the roster judges every refusal as the pool's send
+ *  does). A warm the caller aborted is no refusal. */
+export async function recordCacheWarmRefusal(
+  providerName,
+  instance,
+  error,
+  { accountId = '', model = '', aborted = false, scheduler = providerAdmissionScheduler } = {}
+) {
+  if (aborted || error?.code === 'ECACHEWARMBLOCKED') return;
+  scheduler.recordRateLimit(providerAdmissionKey(providerName, instance), error);
+  if (accountId && ACCOUNT_PROVIDERS.includes(providerName)) {
+    await recordAccountRefusal(providerName, accountId, model, error, instance);
+  }
+}