dsh-subscriptions 0.1.3 → 0.1.5

package/lib/providers/cursor-adapter.js

@@ -17,23 +17,264 @@ export function projectCursorMessages(messages) {
         }
         : message);
 }
+/**
+ * Vendor `LlmError` codes whose whole message is a local literal (no response
+ * header, trailer, body or end-stream text). Provider-derived failures can only
+ * carry a `classifyCursorError` code or `CURSOR_PROTOCOL`, never these, so the
+ * code is a sound discriminator for them.
+ */
+const LOCAL_VENDOR_CODES = new Set(['UNSUPPORTED_OPTION', 'UNSUPPORTED_CONTENT', 'TOOL_LIMIT']);
+/**
+ * Plain-error messages the vendor throws as fixed literals (`vendor/cursor/
+ * index.js`: `waitForResponse`, the request write, the tool-continuation write,
+ * the stream `close` handler, the frame reader, the stall watchdog and the
+ * settings validation). None
+ * interpolates response text, so they are matched by exact message, the same way
+ * the auth messages are. A provider that echoed one of these sentences would
+ * only make the user read a local literal.
+ */
+const LOCAL_VENDOR_MESSAGES = new Set([
+    'Cursor HTTP response timeout',
+    'Cursor HTTP stream closed before response',
+    'Cursor agent bridge closed before accepting the request',
+    'Cursor tool continuation bridge closed before accepting the result',
+    'Cursor sent an unreadable compressed frame',
+    'Cursor stream idle timeout',
+    // `resolveCursorSettings`, run at the top of every stream.
+    'cursor-subscription: maxToolRounds must be an integer between 1 and 1000',
+    'cursor-subscription: retryCount must be an integer between 0 and 10',
+    'cursor-subscription: retryIntervalMs must be an integer between 0 and 300000',
+    'cursor-subscription: retryHttpStatusCodes must contain only HTTP status integers from 400 to 599',
+    'cursor-subscription: retryHttpStatusCodes must not contain duplicates',
+    'cursor-subscription: replayHistoryEachStep must be a boolean',
+]);
+/**
+ * The same, for the two literals that embed a number the vendor computes: the
+ * response status (`Number(headers[':status'])`, so digits or `NaN`) and the
+ * configured progress timeout.
+ */
+const LOCAL_VENDOR_PATTERNS = [
+    /^Cursor agent returned HTTP \d{3}$/,
+    /^Cursor stream progress timeout: no content for \d+ms$/,
+];
+/**
+ * Operating-system network error codes. An `Error` carrying one of these on
+ * itself, or on its `cause` (Node wraps a refused connection in
+ * `ERR_HTTP2_STREAM_CANCEL`), was produced by the local socket layer, so its
+ * message is local: `connect ECONNREFUSED 127.0.0.1:443`, `getaddrinfo ENOTFOUND
+ * host`. This is a property of the thrown object, which a provider cannot
+ * forge. It is deliberately not a test on the vendor's `TRANSPORT` code: the
+ * vendor derives that code from message text, so a provider's end-stream
+ * message or `grpc-message` containing "connection" or "socket" gets it too.
+ * Transport failures with no such code (TLS and certificate errors, HTTP/2
+ * protocol errors) are not recognised and stay replaced.
+ */
+const LOCAL_SYSTEM_ERRNO = new Set([
+    'ECONNREFUSED', 'ECONNRESET', 'ECONNABORTED', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT',
+    'ENETUNREACH', 'ENETDOWN', 'EHOSTUNREACH', 'EHOSTDOWN', 'EPIPE',
+]);
+function errorCode(value) {
+    return typeof value === 'object' && value !== null ? value.code : undefined;
+}
+function isLocalSystemError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const own = errorCode(error);
+    const cause = errorCode(error.cause);
+    return (typeof own === 'string' && LOCAL_SYSTEM_ERRNO.has(own))
+        || (typeof cause === 'string' && LOCAL_SYSTEM_ERRNO.has(cause));
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Bound on remembered local failure messages; they are short and few. */
+const MAX_LOCAL_MESSAGES = 64;
+/**
+ * Remembers the messages of failures raised by this machine rather than read
+ * from the provider: whatever the auth service threw, whatever the host
+ * attachment store threw while reading an image, and a socket-layer network
+ * error seen on the run. The vendor stream turns each of these into
+ * `finish/error` carrying exactly `error.message`, so a failure whose message
+ * equals a remembered one originated locally and may keep its text. The match
+ * is by exact text: a provider that echoed a remembered message would only
+ * display a local literal.
+ */
+class LocalFailureMessages {
+    messages = new Set();
+    /** Wrap `auth` so its failures are remembered and rethrown unchanged. */
+    wrap(auth) {
+        return {
+            accessToken: async (options) => {
+                try {
+                    return await auth.accessToken(options);
+                }
+                catch (error) {
+                    this.remember(messageOf(error));
+                    throw error;
+                }
+            },
+        };
+    }
+    /**
+     * Wrap the host attachment store the vendor reads images through, so a read
+     * failure keeps its own message. The store is a local service; its errors
+     * carry no provider text. Anything that is not a store passes through.
+     */
+    wrapAttachments(resolve) {
+        return () => {
+            const store = resolve();
+            const readImage = store?.readImage;
+            if (typeof readImage !== 'function')
+                return store;
+            return Object.create(store, {
+                readImage: {
+                    value: async (...args) => {
+                        try {
+                            return await readImage.apply(store, args);
+                        }
+                        catch (error) {
+                            this.remember(messageOf(error));
+                            throw error;
+                        }
+                    },
+                },
+            });
+        };
+    }
+    /**
+     * Observe a vendor run's two failure channels, the response promise and the
+     * frame reader, and remember the message of an error the socket layer raised.
+     * The run's behavior is unchanged: the same error is rethrown.
+     */
+    observeRun(run) {
+        if (typeof run !== 'object' || run === null)
+            return run;
+        const target = run;
+        const observe = (error) => {
+            if (isLocalSystemError(error))
+                this.remember(messageOf(error));
+            throw error;
+        };
+        const wait = target.waitForResponse;
+        if (typeof wait === 'function') {
+            target.waitForResponse = (...args) => Promise.resolve(wait.apply(target, args)).catch(observe);
+        }
+        const frames = target.frames;
+        const next = frames?.next;
+        if (frames !== undefined && typeof next === 'function') {
+            frames.next = (...args) => Promise.resolve(next.apply(frames, args)).catch(observe);
+        }
+        return run;
+    }
+    has(message) {
+        return this.messages.has(message);
+    }
+    remember(message) {
+        // An empty message displays nothing; remembering it would exempt every
+        // empty failure from the boundary for no benefit.
+        if (message === '')
+            return;
+        this.messages.delete(message);
+        this.messages.add(message);
+        if (this.messages.size > MAX_LOCAL_MESSAGES) {
+            const oldest = this.messages.values().next().value;
+            if (oldest !== undefined)
+                this.messages.delete(oldest);
+        }
+    }
+}
+function isVendorLocalMessage(message) {
+    return LOCAL_VENDOR_MESSAGES.has(message) || LOCAL_VENDOR_PATTERNS.some(pattern => pattern.test(message));
+}
+/**
+ * Cursor adapter for the DSH host.
+ *
+ * Failure text contract: `finish/error` messages that originate from the
+ * vendor stream and can quote provider-controlled text (the response content
+ * type, trailers, end-stream errors, a frame-reader or other error whose message
+ * is not one of the literals below, and a transport-coded failure that is not a
+ * socket-layer error) are replaced by `<code> [provider response text omitted]`. Failures that are
+ * wholly local keep their own message and code:
+ *
+ * - anything the auth service threw (not signed in, sign-in expired, token
+ *   refresh status), and a host attachment read failure;
+ * - the vendor's own request validation, by code (`UNSUPPORTED_OPTION`,
+ *   `UNSUPPORTED_CONTENT`, `TOOL_LIMIT`);
+ * - the vendor's fixed-literal plain errors, by exact message: the HTTP status
+ *   (`Cursor agent returned HTTP 429`), the response, idle and progress
+ *   timeouts, a closed bridge or stream, an unreadable compressed frame, and
+ *   an invalid Cursor setting;
+ * - a network error raised by the operating system (`ECONNREFUSED`,
+ *   `ENOTFOUND`, ...), recognised from the thrown error's own code, not from
+ *   the vendor's classification.
+ *
+ * Not a provider-origin class: a network error such as `ECONNREFUSED` is a
+ * local failure (no network, daemon down, DNS), and is kept. What is still
+ * replaced although it is probably local is a transport failure with no
+ * socket-layer errno: a TLS or certificate failure and an HTTP/2 protocol
+ * error. The vendor's `TRANSPORT` code cannot decide those, because
+ * `classifyCursorError` derives it from message text (`network`, `connection`,
+ * `socket`, `fetch`, `ECONN`, `http2`) and a provider's end-stream message or
+ * `grpc-message` can contain any of them; so the code is never trusted alone.
+ * Telling these apart would need a check on the thrown error object, as the
+ * errno check above does, extended to the TLS and HTTP/2 error codes. That is
+ * not done here and is not verified.
+ */
 export class CursorCompatAdapter extends CursorAdapter {
     visibleModels;
+    localFailures;
     constructor(options) {
-        super(options);
+        const localFailures = new LocalFailureMessages();
+        super({
+            ...options,
+            auth: localFailures.wrap(options.auth),
+            ...(options.resolveAttachments === undefined
+                ? {}
+                : { resolveAttachments: localFailures.wrapAttachments(options.resolveAttachments) }),
+        });
+        this.localFailures = localFailures;
         this.visibleModels = options.visibleModels;
+        // The vendor assigns `createAgentRun` (the injected one, or its own
+        // `AgentRun` factory) in its constructor but does not type it as a member.
+        const vendor = this;
+        const createRun = vendor.createAgentRun;
+        vendor.createAgentRun = access => localFailures.observeRun(createRun(access));
     }
     async listModels(provider) {
         const models = await super.listModels(provider);
         const visible = this.visibleModels?.();
         return visible === undefined ? models : models.filter(model => visible.includes(model.id));
     }
-    stream(options) {
-        return super.stream({
+    async *stream(options) {
+        for await (const chunk of super.stream({
             ...options,
             // Existing DSH sessions may still hold this retired selection.
             model: options.model === 'composer-2' ? 'composer-2.5' : options.model,
             messages: projectCursorMessages(options.messages),
-        });
+        })) {
+            if (chunk.type === 'finish' && chunk.reason.kind === 'error'
+                && !LOCAL_VENDOR_CODES.has(chunk.reason.failure.code)
+                && !isVendorLocalMessage(chunk.reason.failure.message)
+                && !this.localFailures.has(chunk.reason.failure.message)) {
+                // The vendor uses raw headers, trailers and end-stream errors for protocol
+                // checks and classification before this boundary. Keep its code and retry
+                // decisions; do not reclassify the replacement text. "Safe" here means no
+                // provider-controlled free text is displayed in failures, not that no
+                // secret can exist anywhere internally.
+                yield {
+                    ...chunk,
+                    reason: {
+                        ...chunk.reason,
+                        failure: {
+                            ...chunk.reason.failure,
+                            message: `${chunk.reason.failure.code} [provider response text omitted]`,
+                        },
+                    },
+                };
+            }
+            else {
+                yield chunk;
+            }
+        }
     }
 }

package/lib/providers/cursor-auth.js

@@ -1,13 +1,20 @@
 /** Cursor OAuth session and browser-login lifecycle. Credentials stay in DSH. */
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { parseProviderJson } from './common.js';
 export const CURSOR_CREDENTIAL_REF = credentialRef('CURSOR_SUBSCRIPTION_OAUTH');
 const API_ORIGIN = 'https://api2.cursor.sh';
 const REFRESH_AHEAD_MS = 5 * 60_000;
-function parseCredential(value) {
+async function parseCredential(value) {
     if (value === undefined || value.length === 0)
         return undefined;
-    const parsed = JSON.parse(value);
+    // A parse failure here is a local shape error, not a provider signal. That is a
+    // deliberate change: the vendor classifies a stream failure from the message
+    // text, and the raw JSON.parse message used to carry a body excerpt, so a
+    // corrupt credential whose body happened to contain a word like `quota` was
+    // classified as a rate limit. Sanitising the message removes that accident, so
+    // a malformed credential now fails as a general provider error instead.
+    const parsed = await parseProviderJson(value, 'Cursor stored credential');
     if (parsed === null || typeof parsed !== 'object')
         throw new Error('Cursor credential is malformed');
     const item = parsed;
@@ -89,7 +96,7 @@ export class CursorAuth {
         });
         if (!response.ok)
             throw new Error(`Cursor token refresh failed (HTTP ${response.status})`);
-        const body = await response.json();
+        const body = await parseProviderJson(response, 'Cursor token refresh');
         if (typeof body.accessToken !== 'string' || body.accessToken.length === 0) {
             throw new Error('Cursor token refresh returned no access token');
         }
@@ -136,7 +143,7 @@ export class CursorAuth {
             }
             if (!response.ok)
                 throw new Error(`Cursor login failed (HTTP ${response.status})`);
-            const body = await response.json();
+            const body = await parseProviderJson(response, 'Cursor login poll');
             signal.throwIfAborted();
             if (typeof body.accessToken !== 'string' || body.accessToken.length === 0) {
                 throw new Error('Cursor login returned no access token');

package/lib/providers/cursor-usage.js

@@ -1,4 +1,5 @@
 /** Cursor individual-account quota projection from its dashboard endpoints. */
+import { parseProviderJson } from './common.js';
 const ORIGIN = 'https://cursor.com';
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -44,7 +45,7 @@ async function dashboardJson(url, cookie, http, signal) {
     });
     if (!response.ok)
         throw new Error(`Cursor usage endpoint returned HTTP ${response.status}`);
-    return response.json();
+    return parseProviderJson(response, 'Cursor usage');
 }
 function legacyRequestWindow(body, resetsAt) {
     const usage = record(body);

package/lib/providers/external-usage.js

@@ -1,4 +1,5 @@
 /** Usage readers for subscriptions whose model adapters are built into DSH. */
+import { parseProviderJson } from './common.js';
 function numeric(value) {
     const n = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
     return typeof n === 'number' && Number.isFinite(n) ? n : undefined;
@@ -39,7 +40,7 @@ async function getUsage(url, apiKey, http, signal) {
     });
     if (!response.ok)
         throw new Error(`Usage endpoint returned HTTP ${response.status}`);
-    return response.json();
+    return parseProviderJson(response, 'external usage');
 }
 /** Read the three account-wide OpenCode Go windows from its Go gateway. */
 export async function fetchOpenCodeGoUsage(apiKey, http = fetch, signal) {

package/lib/providers/grok.d.ts

@@ -25,8 +25,8 @@ export declare const GROK_PREEMPT_MS: number;
  * whose values are rollover durations (`6m0s`) present on every response, one
  * per bucket — on a 429 the earliest of them is usually a bucket with room
  * (`0s` for the request bucket while the token bucket is the one exhausted),
- * which would burn the whole retry budget in seconds. They reach the operator
- * through `rateLimitDiagnostics` instead.
+ * which would burn the whole retry budget in seconds. The parsed body reset
+ * supplies the retry hint; diagnostics omit raw provider headers and body text.
  */
 export declare const grokRateLimitReset: RateLimitResetReader;
 /** Discovered OIDC endpoints for the xAI authorization server. */

package/lib/providers/grok.js

@@ -7,7 +7,7 @@ import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmErr
 import { decodeJwtPayload } from '../auth/jwt.js';
 import { resolveImages } from '../translate/resolved.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
-import { httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, } from './common.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, parseProviderJson, oauthEndpointError, OAuthEndpointError, } from './common.js';
 import { AccountTokenManager, DISCOVERY_TIMEOUT_MS, unionAccountCatalogs } from './accounts.js';
 import { hostFetch } from '../http.js';
 import { DEFAULT_RATE_LIMIT_WAIT, DEFAULT_RETRY, jsonBody, resetFromFields, subscriptionRetryPolicy, } from './rate-limit.js';
@@ -29,11 +29,16 @@ const GROK_RESET_FIELDS = ['retry_after', 'retry_after_seconds', 'resets_at', 'r
  * whose values are rollover durations (`6m0s`) present on every response, one
  * per bucket — on a 429 the earliest of them is usually a bucket with room
  * (`0s` for the request bucket while the token bucket is the one exhausted),
- * which would burn the whole retry budget in seconds. They reach the operator
- * through `rateLimitDiagnostics` instead.
+ * which would burn the whole retry budget in seconds. The parsed body reset
+ * supplies the retry hint; diagnostics omit raw provider headers and body text.
  */
 export const grokRateLimitReset = (_response, body, now) => resetFromFields(jsonBody(body), GROK_RESET_FIELDS, now);
-/** A discovered URL must be https on x.ai or a subdomain; anything else is a hostile document. */
+/**
+ * A discovered URL must be https on x.ai or a subdomain; anything else is a
+ * hostile document. The rejection names the field and never the URL: the URL
+ * comes from the provider's discovery document, which is exactly the text a
+ * hostile document would choose.
+ */
 function assertXaiEndpoint(url, field) {
     let parsed;
     try {
@@ -44,7 +49,7 @@ function assertXaiEndpoint(url, field) {
     }
     if (parsed.protocol !== 'https:'
         || (parsed.hostname !== 'x.ai' && !parsed.hostname.endsWith('.x.ai'))) {
-        throw new Error(`grok OIDC discovery returned a non-x.ai ${field}: ${url}`);
+        throw new Error(`grok OIDC discovery returned a non-x.ai ${field}`);
     }
     return url;
 }
@@ -59,7 +64,7 @@ export async function grokDiscovery() {
     const response = await hostFetch(GROK_DISCOVERY_URL);
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok OIDC discovery');
-    const document = await response.json();
+    const document = await parseProviderJson(response, 'grok OIDC discovery');
     if (typeof document.authorization_endpoint !== 'string' || typeof document.token_endpoint !== 'string') {
         throw new Error('grok OIDC discovery document is missing endpoints');
     }
@@ -191,7 +196,7 @@ export async function exchangeGrokCode(code, verifier, redirectUri, challenge) {
     }
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok');
-    return grokSession(await response.json(), discovery.tokenEndpoint);
+    return grokSession(await parseProviderJson(response, 'grok token exchange'), discovery.tokenEndpoint);
 }
 /**
  * Refresh a grok session (form-encoded grant).
@@ -210,7 +215,7 @@ export async function refreshGrok(session) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok');
-    const next = grokSession(await response.json(), session.tokenEndpoint, session.refreshToken);
+    const next = grokSession(await parseProviderJson(response, 'grok token refresh'), session.tokenEndpoint, session.refreshToken);
     return {
         ...next,
         ...session.account === undefined ? {} : { account: session.account },
@@ -261,7 +266,7 @@ export async function fetchGrokUsage(session, fetchFn = hostFetch, signal) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok billing');
-    const payload = await response.json();
+    const payload = await parseProviderJson(response, 'grok billing');
     const config = typeof payload.config === 'object' && payload.config !== null ? payload.config : {};
     const windows = [];
     if (config.currentPeriod || (typeof config.creditUsagePercent === 'number' && Number.isFinite(config.creditUsagePercent))) {
@@ -357,7 +362,7 @@ export async function fetchGrokCliCatalog(session, fetchFn = hostFetch, signal)
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok CLI catalog');
-    const payload = await response.json();
+    const payload = await parseProviderJson(response, 'grok CLI catalog');
     if (!Array.isArray(payload.data))
         throw new Error('grok CLI catalog returned no data array');
     const catalog = new Map();
@@ -442,7 +447,7 @@ export async function fetchGrokModels(session, fetchFn = hostFetch, onWarn, prev
     ]);
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok models');
-    const payload = await response.json();
+    const payload = await parseProviderJson(response, 'grok models');
     if (!Array.isArray(payload.data))
         throw new Error('grok models endpoint returned no data array');
     const seen = new Set();

package/lib/providers/minimax-usage.js

@@ -1,3 +1,4 @@
+import { parseProviderJson } from './common.js';
 /**
  * Used percentage from the legacy counts, read as the official CLI does when no
  * explicit percentage exists: the count is the quota remaining. Undefined
@@ -40,7 +41,7 @@ export async function fetchMiniMaxUsage(key, region, http = fetch, signal) {
     });
     if (!response.ok)
         throw new Error(`MiniMax usage endpoint returned HTTP ${response.status}`);
-    const body = await response.json();
+    const body = await parseProviderJson(response, 'MiniMax usage');
     if ((body?.base_resp?.status_code !== undefined && body.base_resp.status_code !== 0) || !Array.isArray(body?.model_remains)) {
         throw new Error('MiniMax usage response failed or has no quota records');
     }

package/lib/providers/pool-health.d.ts

@@ -69,6 +69,8 @@ export declare class PoolHealthRegistry {
      * `providerRetryAfterMs`.
      */
     earliestRecovery(keys: ReadonlySet<string>, now?: number): number | undefined;
+    /** Active failure codes for the given keys; reading them does not change cooldowns. */
+    unavailableReasons(keys: ReadonlySet<string>, now?: number): string[];
     /** Drop records of one provider, or of a single account when given (auth changes). */
     clear(provider: ProviderId, account?: string): void;
 }

package/lib/providers/pool-health.js

@@ -139,6 +139,15 @@ export class PoolHealthRegistry {
         }
         return earliest;
     }
+    /** Active failure codes for the given keys; reading them does not change cooldowns. */
+    unavailableReasons(keys, now = Date.now()) {
+        const reasons = [];
+        for (const [key, record] of this.records) {
+            if (keys.has(key) && record.unavailableUntil > now)
+                reasons.push(record.reason);
+        }
+        return reasons;
+    }
     /** Drop records of one provider, or of a single account when given (auth changes). */
     clear(provider, account) {
         const prefix = account === undefined ? `${provider}/` : `${provider}/${account}/`;

package/lib/providers/pool-usage.d.ts

@@ -39,6 +39,11 @@ export declare class PoolUsageTracker {
     private readonly ttlMs;
     private readonly entries;
     private readonly inflight;
+    /** Bumped by {@link invalidate} so a fetch started before it cannot repopulate the cache. */
+    private readonly generation;
+    /** Monotonic per-key write order: only the newest settled fetch may cache. */
+    private nextSequence;
+    private readonly lastWritten;
     constructor(fetcherFor: (provider: ProviderId, account: string) => (() => Promise<ProviderUsage>) | undefined, ttlMs?: number);
     /**
      * The quota view of one member. A cold cache awaits the first fetch; a
@@ -70,7 +75,14 @@ export declare class PoolUsageTracker {
      * @returns `{ supported: false }` when the provider has no usage fetcher.
      */
     snapshotFor(provider: ProviderId, account: string, force?: boolean): Promise<ProviderUsage>;
-    /** Drop cached snapshots: one account, or a whole provider when `account` is omitted. */
+    /**
+     * Drop cached snapshots: one account, or a whole provider when `account` is
+     * omitted. A fetch already in flight is abandoned too. It was started against
+     * state the caller has just declared changed — a redeemed credit, a completed
+     * login — so joining it would return the pre-change numbers and cache them for
+     * the full freshness window. Its result is discarded on arrival by the
+     * generation check in {@link refresh}.
+     */
     invalidate(provider: ProviderId, account?: string): void;
     /**
      * Run (or join) the single in-flight fetch for one account key, caching

package/lib/providers/pool-usage.js

@@ -34,6 +34,11 @@ export class PoolUsageTracker {
     ttlMs;
     entries = new Map();
     inflight = new Map();
+    /** Bumped by {@link invalidate} so a fetch started before it cannot repopulate the cache. */
+    generation = new Map();
+    /** Monotonic per-key write order: only the newest settled fetch may cache. */
+    nextSequence = 0;
+    lastWritten = new Map();
     constructor(fetcherFor, ttlMs = USAGE_TTL_MS) {
         this.fetcherFor = fetcherFor;
         this.ttlMs = ttlMs;
@@ -126,15 +131,27 @@ export class PoolUsageTracker {
             throw error;
         }
     }
-    /** Drop cached snapshots: one account, or a whole provider when `account` is omitted. */
+    /**
+     * Drop cached snapshots: one account, or a whole provider when `account` is
+     * omitted. A fetch already in flight is abandoned too. It was started against
+     * state the caller has just declared changed — a redeemed credit, a completed
+     * login — so joining it would return the pre-change numbers and cache them for
+     * the full freshness window. Its result is discarded on arrival by the
+     * generation check in {@link refresh}.
+     */
     invalidate(provider, account) {
+        const drop = (key) => {
+            this.entries.delete(key);
+            this.inflight.delete(key);
+            this.generation.set(key, (this.generation.get(key) ?? 0) + 1);
+        };
         if (account !== undefined) {
-            this.entries.delete(`${provider}/${account}`);
+            drop(`${provider}/${account}`);
             return;
         }
-        for (const key of [...this.entries.keys()]) {
+        for (const key of [...this.entries.keys(), ...this.inflight.keys()]) {
             if (key.startsWith(`${provider}/`))
-                this.entries.delete(key);
+                drop(key);
         }
     }
     /**
@@ -155,13 +172,26 @@ export class PoolUsageTracker {
             // consecutive failure, even though nothing newer ever replaced it.
             const prior = this.entries.get(key);
             const lastSnapshot = prior?.snapshot ?? prior?.lastSnapshot;
+            const generation = this.generation.get(key) ?? 0;
+            // A newer fetch may settle before this one does. The generation only
+            // catches an invalidate; the sequence catches a plain race, where this
+            // fetch fails late and would otherwise cache a cooldown over a fresher
+            // success that already landed.
+            const sequence = ++this.nextSequence;
             pending = fetcher().then((value) => {
                 const at = Date.now();
                 const snapshot = { ...value, observedAt: at, stale: false };
-                this.entries.set(key, { snapshot, at });
+                // An invalidate() during the fetch means this result describes a world
+                // that has moved on; caching it would resurrect the old numbers.
+                if ((this.generation.get(key) ?? 0) === generation && (this.lastWritten.get(key) ?? 0) < sequence) {
+                    this.lastWritten.set(key, sequence);
+                    this.entries.set(key, { snapshot, at });
+                }
                 return snapshot;
             }, (error) => {
-                if (!isMissingOrInvalidCredential(error)) {
+                if (!isMissingOrInvalidCredential(error) && (this.generation.get(key) ?? 0) === generation
+                    && (this.lastWritten.get(key) ?? 0) < sequence) {
+                    this.lastWritten.set(key, sequence);
                     this.entries.set(key, {
                         error,
                         at: Date.now(),
@@ -171,7 +201,9 @@ export class PoolUsageTracker {
                 }
                 throw error;
             }).finally(() => {
-                this.inflight.delete(key);
+                // Only clear our own slot: an invalidate may have replaced it.
+                if (this.inflight.get(key) === pending)
+                    this.inflight.delete(key);
             });
             this.inflight.set(key, pending);
         }

package/lib/providers/pool.d.ts

@@ -87,6 +87,12 @@ export declare class PoolAdapter extends LlmAdapter {
      * metadata is account-specific, so every distinct member is resolved.
      */
     resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    /**
+     * Fail over before output. A single non-quota failure keeps its identity
+     * and shared provider message, with scoped pool recovery or its own hint as fallback.
+     * Multiple failures carry a bounded summary and all attempts in an AggregateError cause.
+     * Pure quota/rate exhaustion retains RATE_LIMIT and this pool's earliest recovery hint.
+     */
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
     /**
      * Order the candidates for one request. Health filters both strategies;
@@ -99,10 +105,6 @@ export declare class PoolAdapter extends LlmAdapter {
     private select;
     /** Pin the serving member to the session (with bounded memory). */
     private remember;
-    /**
-     * The error for an exhausted pool, carrying the earliest recovery hint of
-     * THIS pool's members (the health registry is shared across pools, so the
-     * hint is scoped to the keys this pool can actually recover through).
-     */
+    /** Report attempt failures or this pool's active cooldowns, never unrelated health records. */
     private exhausted;
 }