@cortexkit/anthropic-auth-core 1.19.1 → 1.21.0

package/dist/quota-manager.js

@@ -5,10 +5,11 @@
  * share one QuotaManager instance so they see the same in-memory cache.
  * Handles deduplication, rate-limiting (429 backoff), and staleness.
  */
-import { acquireRefreshFileLock, buildQuotaOperationError, fetchOAuthQuotaSnapshot, getPersistedMainQuota, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getQuotaRefreshEveryNRequests, getScopedQuotaWindowForModel, isQuotaPolicyAuthError, quotaBackoffActive, } from "./accounts.js";
-import { mergeHeaderQuotaSnapshot } from "./quota-headers.js";
-export { tokenFingerprint } from "./token-fingerprint.js";
-import { tokenFingerprint } from "./token-fingerprint.js";
+import { acquireRefreshFileLock, buildQuotaOperationError, fetchOAuthQuotaSnapshot, getPersistedMainQuota, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getQuotaRefreshEveryNRequests, getScopedQuotaWindowForModel, isQuotaPolicyAuthError, mergeMainQuotaErrorClearedAt, quotaBackoffActive, quotaSnapshotCheckedAt, } from './accounts.js';
+import { logger } from './logger.js';
+import { mergeHeaderQuotaSnapshot } from './quota-headers.js';
+export { tokenFingerprint } from './token-fingerprint.js';
+import { tokenFingerprint } from './token-fingerprint.js';
 // Capture real setTimeout before tests can mock globalThis.setTimeout
 const nativeSetTimeout = globalThis.setTimeout;
 function mergePollCompletionWithNewerHeaders(current, polled) {
@@ -38,21 +39,23 @@ function mergePollCompletionWithNewerHeaders(current, polled) {
 export class QuotaManager {
     // --- State ---
     main = null;
-    mainTokenFp = null;
+    mainAccountId;
+    mainQuotaIdentityKnown = false;
+    mainQuotaIdentityStrict = false;
+    mainGeneration = 0;
+    mainQuotaErrorGeneration = 0;
+    mainQuotaErrorClearedAt;
     fallbacks = new Map();
-    // Fingerprint of the access token that produced each fallback cache entry, so
-    // a re-login (credential change) for the same account id invalidates the
-    // stale entry instead of being treated as fresh.
-    fallbackTokenFps = new Map();
+    fallbackAuthLineages = new Map();
+    fallbackGenerations = new Map();
     // --- Inflight deduplication ---
     inflightMain = null;
-    inflightMainFp = null;
+    inflightMainAccountId;
     inflightFallbacks = new Map();
     // --- Rate-limiting (scoped per route so a fallback 429 never backs off the
     // main account or vice versa) ---
     mainLastApiError = undefined;
     fallbackApiErrors = new Map();
-    fallbackErrorTokenFps = new Map();
     // --- Serial API gate (prevents concurrent quota API calls) ---
     apiGate = Promise.resolve();
     lastApiCallAt = 0;
@@ -68,49 +71,33 @@ export class QuotaManager {
         this.now = opts.now ?? Date.now;
         this.onMainQuotaFetched = opts.onMainQuotaFetched;
         this.onApiError = opts.onApiError;
-        // Seed main quota from persisted storage, bound to the token fingerprint
-        // that produced it. refreshMain() drops this seed if the live token's
-        // fingerprint differs (main-account switch), preventing stale wrong-account
-        // quota from being served during backoff.
-        this.seedMainFromStorage(opts.storage);
+        this.seedMainFromStorage(opts.storage, opts.storage?.mainAccountId);
         this.seedMainBackoffFromStorage(opts.storage);
     }
     // =========================================================================
     // Get (synchronous, from cache)
     // =========================================================================
     /**
-     * Cached main quota entry. Pass the live access token to enforce token
-     * binding: if the cached entry was produced by a different token (main
-     * account switched), it is dropped and null is returned so the caller
-     * refetches for the current account. Called without a token (e.g. for
-     * display) it returns whatever is cached.
+     * Cached main quota entry, scoped to the account behind the main credential.
+     * An unresolved identity keeps a retained cache unverified rather than exposing it.
      */
-    getMain(accessToken) {
-        if (accessToken &&
-            this.main &&
-            this.mainTokenFp &&
-            this.mainTokenFp !== tokenFingerprint(accessToken)) {
-            this.main = null;
-            this.mainTokenFp = null;
+    getMain(mainAccountId) {
+        if (this.mainAccountId !== mainAccountId)
+            return null;
+        if (this.mainQuotaIdentityKnown &&
+            this.mainQuotaIdentityStrict &&
+            (mainAccountId === undefined ||
+                this.main?.quota.accountIdentity !== mainAccountId)) {
+            return null;
         }
         return this.main;
     }
     /**
-     * Cached fallback quota entry. Pass the live access token to enforce token
-     * binding: if the entry was produced by a different token (account re-login),
-     * it is dropped and null is returned so the caller refetches.
+     * Cached fallback quota entry, scoped to the configured account id.
      */
-    getFallback(accountId, accessToken) {
-        const entry = this.fallbacks.get(accountId) ?? null;
-        if (!accessToken || !entry)
-            return entry;
-        const fp = this.fallbackTokenFps.get(accountId);
-        if (fp !== tokenFingerprint(accessToken)) {
-            this.fallbacks.delete(accountId);
-            this.fallbackTokenFps.delete(accountId);
-            return null;
-        }
-        return entry;
+    getFallback(accountId, account) {
+        this.bindFallbackLineage(accountId, account);
+        return this.fallbacks.get(accountId) ?? null;
     }
     getAllFallbacks() {
         return this.fallbacks;
@@ -118,83 +105,154 @@ export class QuotaManager {
     // =========================================================================
     // Set (manual inject — seeding from persisted account.quota on boot)
     // =========================================================================
-    setMain(accessToken, entry) {
-        this.mainTokenFp = tokenFingerprint(accessToken);
+    setMain(mainAccountId, entry) {
+        this.mainAccountId = mainAccountId;
         this.main = entry;
     }
-    setFallback(accountId, entry, accessToken) {
-        this.fallbacks.set(accountId, entry);
-        if (accessToken) {
-            this.fallbackTokenFps.set(accountId, tokenFingerprint(accessToken));
+    /** Bind quota state to the account behind the current main credential. */
+    setMainQuotaAccountIdentity(accountIdentity, strict = true) {
+        const previousIdentityKnown = this.mainQuotaIdentityKnown;
+        const previousAccountIdentity = this.mainAccountId;
+        const changed = !previousIdentityKnown ||
+            this.mainAccountId !== accountIdentity ||
+            this.mainQuotaIdentityStrict !== strict;
+        this.mainQuotaIdentityKnown = true;
+        this.mainQuotaIdentityStrict = strict;
+        if (!changed)
+            return undefined;
+        this.mainGeneration += 1;
+        this.mainAccountId = accountIdentity;
+        if (accountIdentity !== undefined &&
+            this.main?.quota.accountIdentity !== accountIdentity) {
+            this.main = null;
         }
-        else {
-            this.fallbackTokenFps.delete(accountId);
+        if (accountIdentity !== undefined &&
+            this.mainLastApiError &&
+            (this.mainLastApiError.accountIdentity !== undefined
+                ? this.mainLastApiError.accountIdentity !== accountIdentity
+                : previousIdentityKnown &&
+                    previousAccountIdentity !== undefined &&
+                    previousAccountIdentity !== accountIdentity)) {
+            this.mainLastApiError = undefined;
+            this.mainQuotaErrorGeneration += 1;
+            this.mainQuotaErrorClearedAt = mergeMainQuotaErrorClearedAt(this.mainQuotaErrorClearedAt, this.now());
+            return this.mainQuotaErrorGeneration;
         }
+        return undefined;
     }
-    pushMainFromHeaders(accessToken, incoming) {
+    setFallback(accountId, entry, account) {
+        this.bindFallbackLineage(accountId, account);
+        this.fallbacks.set(accountId, entry);
+    }
+    clearFallback(accountId) {
+        this.fallbackGenerations.set(accountId, (this.fallbackGenerations.get(accountId) ?? 0) + 1);
+        this.fallbacks.delete(accountId);
+        this.fallbackApiErrors.delete(accountId);
+        this.inflightFallbacks.delete(QuotaManager.fallbackInflightKey(accountId));
+    }
+    pushMainFromHeaders(mainAccountId, incoming) {
         const checkedAt = incoming.checkedAt ?? this.now();
-        const accessTokenFp = tokenFingerprint(accessToken);
-        const quota = mergeHeaderQuotaSnapshot(this.mainTokenFp === accessTokenFp ? this.main?.quota : undefined, incoming);
+        const quota = mergeHeaderQuotaSnapshot(this.mainAccountId === mainAccountId &&
+            (!this.mainQuotaIdentityKnown ||
+                !this.mainQuotaIdentityStrict ||
+                this.main?.quota.accountIdentity === mainAccountId)
+            ? this.main?.quota
+            : undefined, {
+            ...incoming,
+            ...(mainAccountId !== undefined && { accountIdentity: mainAccountId }),
+        });
         const entry = {
             quota,
             checkedAt,
             refreshAfter: getQuotaNextRefreshAt(quota, this.storage, checkedAt),
         };
-        this.setMain(accessToken, entry);
+        this.setMain(mainAccountId, entry);
         return entry;
     }
-    pushFallbackFromHeaders(accountId, accessToken, incoming) {
+    pushFallbackFromHeaders(accountId, incoming, account) {
+        if (!this.acceptFallbackQuotaObservation(accountId, account))
+            return null;
         const checkedAt = incoming.checkedAt ?? this.now();
-        const quota = mergeHeaderQuotaSnapshot(this.getFallback(accountId, accessToken)?.quota, incoming);
+        const quota = mergeHeaderQuotaSnapshot(this.fallbacks.get(accountId)?.quota, {
+            ...incoming,
+            accountIdentity: accountId,
+        });
         const entry = {
             quota,
             checkedAt,
             refreshAfter: getQuotaNextRefreshAt(quota, this.storage, checkedAt),
         };
-        this.setFallback(accountId, entry, accessToken);
+        this.fallbacks.set(accountId, entry);
         return entry;
     }
     // =========================================================================
     // Refresh (async, deduplicated, rate-limited)
     // =========================================================================
-    async refreshMain(accessToken) {
-        // If the main account/token changed, invalidate the cache (including a
-        // persisted seed) BEFORE the backoff short-circuit so a different account's
-        // stale quota is never returned while the quota API is backed off.
-        const fp = tokenFingerprint(accessToken);
-        if (this.mainTokenFp && this.mainTokenFp !== fp) {
+    async refreshMain(mainAccountIdOrAccessToken, accessToken, expectedIdentityGeneration) {
+        const mainAccountId = mainAccountIdOrAccessToken;
+        const credential = accessToken ?? mainAccountIdOrAccessToken;
+        if (!credential)
+            throw new Error('Main OAuth access token is unavailable');
+        return (await this.refreshMainWithMetadata(mainAccountId, credential, expectedIdentityGeneration)).quota;
+    }
+    async refreshMainWithMetadata(mainAccountIdOrAccessToken, accessToken, expectedIdentityGeneration) {
+        const effectiveAccountId = mainAccountIdOrAccessToken;
+        const credential = accessToken ?? mainAccountIdOrAccessToken;
+        if (!credential)
+            throw new Error('Main OAuth access token is unavailable');
+        if (expectedIdentityGeneration !== undefined &&
+            (this.mainGeneration !== expectedIdentityGeneration ||
+                this.mainAccountId !== effectiveAccountId)) {
+            throw new Error('Main quota identity changed before refresh');
+        }
+        if (this.mainAccountId !== effectiveAccountId) {
             this.main = null;
-            this.mainTokenFp = null;
+            this.mainAccountId = effectiveAccountId;
+            if (this.mainQuotaIdentityKnown)
+                this.mainGeneration += 1;
         }
-        // Deduplicate — return in-flight promise only if same token fingerprint
-        if (this.inflightMain && this.inflightMainFp === fp)
+        if (this.inflightMain && this.inflightMainAccountId === effectiveAccountId)
             return this.inflightMain;
         // Rate-limit — if API recently 429'd, return stale or throw
         if (this.isBackedOff()) {
-            if (this.main)
-                return this.main.quota;
+            if (this.main && this.mainAccountId === effectiveAccountId) {
+                return { quota: this.main.quota, fetched: false };
+            }
             throw new Error('Quota API rate-limited — try again later');
         }
-        this.inflightMainFp = fp;
-        this.inflightMain = this._fetchMain(accessToken);
+        this.inflightMainAccountId = effectiveAccountId;
+        const generation = this.mainGeneration;
+        this.inflightMain = this._fetchMain(effectiveAccountId, credential, generation);
         return this.inflightMain;
     }
-    async refreshFallback(accountId, accessToken) {
-        // Deduplicate per account+token so a same-label re-login never joins a
-        // quota probe that was started with the previous credentials.
-        const inflightKey = QuotaManager.fallbackInflightKey(accountId, accessToken);
+    async refreshFallback(accountId, accessToken, account) {
+        return (await this.refreshFallbackWithMetadata(accountId, accessToken, account)).quota;
+    }
+    async refreshFallbackWithMetadata(accountId, accessToken, account) {
+        this.bindFallbackLineage(accountId, account);
+        const inflightKey = QuotaManager.fallbackInflightKey(accountId);
         const inflight = this.inflightFallbacks.get(inflightKey);
         if (inflight)
             return inflight;
         // Rate-limit — scoped to THIS fallback account only
-        if (this.isFallbackBackedOff(accountId, accessToken)) {
-            const cached = this.getFallback(accountId, accessToken);
+        if (this.isFallbackBackedOff(accountId)) {
+            const cached = this.getFallback(accountId);
             if (cached)
-                return cached.quota;
+                return { quota: cached.quota, fetched: false };
             throw new Error('Quota API rate-limited — try again later');
         }
-        const promise = this._fetchFallback(accountId, accessToken);
+        const generation = this.fallbackGenerations.get(accountId) ?? 0;
+        const promise = this._fetchFallback(accountId, accessToken, generation, account);
         this.inflightFallbacks.set(inflightKey, promise);
+        void promise.then(() => {
+            if (this.inflightFallbacks.get(inflightKey) === promise) {
+                this.inflightFallbacks.delete(inflightKey);
+            }
+        }, () => {
+            if (this.inflightFallbacks.get(inflightKey) === promise) {
+                this.inflightFallbacks.delete(inflightKey);
+            }
+        });
         return promise;
     }
     async refreshAllFallbacks(accounts) {
@@ -204,11 +262,12 @@ export class QuotaManager {
                 continue;
             if (!account.access)
                 continue;
-            const cached = this.getFallback(account.id, account.access);
+            this.bindFallbackLineage(account.id, account);
+            const cached = this.getFallback(account.id);
             if (cached && now < cached.refreshAfter)
                 continue;
             try {
-                await this.refreshFallback(account.id, account.access);
+                await this.refreshFallback(account.id, account.access, account);
             }
             catch {
                 // Best-effort — keep stale cache entry if fetch fails
@@ -223,7 +282,7 @@ export class QuotaManager {
             return;
         if (this.isBackedOff())
             return;
-        void this.refreshMain(accessToken).catch(() => { });
+        void this.refreshMain(this.mainAccountId, accessToken).catch(() => { });
     }
     // =========================================================================
     // Staleness queries
@@ -236,12 +295,19 @@ export class QuotaManager {
     isMainStale(modelId) {
         if (!this.main)
             return true;
+        if (this.mainQuotaIdentityKnown &&
+            this.mainQuotaIdentityStrict &&
+            (this.mainAccountId === undefined ||
+                this.main.quota.accountIdentity !== this.mainAccountId)) {
+            return true;
+        }
         return (this.now() >= this.main.refreshAfter ||
             this.scopedWindowIsStale(this.main, modelId));
     }
-    isFallbackStale(accountId, accessToken, modelId) {
-        // Token-aware: a credential change invalidates the entry (treated as stale).
-        const entry = this.getFallback(accountId, accessToken);
+    isFallbackStale(accountId, _accessToken, modelId, account) {
+        // Keep the unused slot to avoid breaking internal callers that pass modelId
+        // third; cached quota is scoped to stable account identity.
+        const entry = this.getFallback(accountId, account);
         if (!entry)
             return true;
         return (this.now() >= entry.refreshAfter ||
@@ -266,7 +332,7 @@ export class QuotaManager {
     // =========================================================================
     updateStorage(storage) {
         this.storage = storage;
-        this.seedMainFromStorage(storage);
+        this.seedMainFromStorage(storage, this.mainQuotaIdentityKnown ? this.mainAccountId : storage?.mainAccountId);
         this.seedMainBackoffFromStorage(storage);
     }
     /**
@@ -275,37 +341,106 @@ export class QuotaManager {
      * can stop this process from showing "checking…" or making a redundant quota
      * API call.
      */
-    seedMainFromStorage(storage, accessToken) {
+    seedMainFromStorage(storage, mainAccountId) {
         const persisted = getPersistedMainQuota(storage);
         if (!persisted)
             return;
-        const accessTokenFp = accessToken ? tokenFingerprint(accessToken) : null;
-        if (accessTokenFp &&
-            persisted.tokenFingerprint &&
-            persisted.tokenFingerprint !== accessTokenFp) {
-            return;
-        }
         const entry = {
-            quota: persisted.quota,
+            quota: {
+                ...persisted.quota,
+                ...((!this.mainQuotaIdentityKnown || !this.mainQuotaIdentityStrict) &&
+                    mainAccountId !== undefined &&
+                    persisted.accountIdentity === undefined && {
+                    accountIdentity: mainAccountId,
+                }),
+            },
             refreshAfter: getQuotaNextRefreshAt(persisted.quota, storage, persisted.checkedAt),
             checkedAt: persisted.checkedAt,
         };
+        const current = this.main &&
+            this.mainAccountId === mainAccountId &&
+            (!this.mainQuotaIdentityKnown ||
+                !this.mainQuotaIdentityStrict ||
+                this.main.quota.accountIdentity === mainAccountId)
+            ? this.main
+            : undefined;
+        if (current &&
+            current.checkedAt >= entry.checkedAt &&
+            current.quota.source === 'headers' &&
+            entry.quota.source === 'poll') {
+            const mergedQuota = mergeHeaderQuotaSnapshot(entry.quota, current.quota);
+            this.main = {
+                quota: mergedQuota,
+                refreshAfter: getQuotaNextRefreshAt(mergedQuota, storage, current.checkedAt),
+                checkedAt: current.checkedAt,
+            };
+            return;
+        }
         if (this.main &&
-            this.main.checkedAt >= entry.checkedAt &&
-            (!accessTokenFp ||
-                !this.mainTokenFp ||
-                this.mainTokenFp === accessTokenFp)) {
+            this.mainAccountId === mainAccountId &&
+            this.main.checkedAt >= entry.checkedAt) {
             return;
         }
         this.main = entry;
-        this.mainTokenFp = persisted.tokenFingerprint ?? null;
+        if (mainAccountId !== undefined)
+            this.mainAccountId = mainAccountId;
     }
     seedMainBackoffFromStorage(storage) {
         const persistedError = storage?.quota?.mainLastQuotaApiError;
-        this.mainLastApiError =
-            persistedError && quotaBackoffActive(persistedError, this.now())
-                ? persistedError
-                : undefined;
+        const persistedIdentity = persistedError?.accountIdentity;
+        const persistedGeneration = typeof storage?.quota?.mainQuotaErrorGeneration === 'number' &&
+            Number.isSafeInteger(storage.quota.mainQuotaErrorGeneration) &&
+            storage.quota.mainQuotaErrorGeneration >= 0
+            ? storage.quota.mainQuotaErrorGeneration
+            : undefined;
+        const persistedClearedAt = typeof storage?.quota?.mainQuotaErrorClearedAt === 'number' &&
+            Number.isFinite(storage.quota.mainQuotaErrorClearedAt) &&
+            storage.quota.mainQuotaErrorClearedAt >= 0
+            ? storage.quota.mainQuotaErrorClearedAt
+            : undefined;
+        if (persistedClearedAt !== undefined &&
+            (this.mainQuotaErrorClearedAt === undefined ||
+                persistedClearedAt > this.mainQuotaErrorClearedAt)) {
+            this.mainQuotaErrorClearedAt = mergeMainQuotaErrorClearedAt(this.mainQuotaErrorClearedAt, persistedClearedAt);
+            if ((!persistedError ||
+                (typeof persistedError.checkedAt === 'number' &&
+                    persistedError.checkedAt <= persistedClearedAt)) &&
+                (this.mainLastApiError?.checkedAt === undefined ||
+                    this.mainLastApiError.checkedAt <= persistedClearedAt)) {
+                this.mainLastApiError = undefined;
+            }
+        }
+        if (persistedGeneration !== undefined &&
+            persistedGeneration > this.mainQuotaErrorGeneration) {
+            this.mainQuotaErrorGeneration = persistedGeneration;
+            if (!persistedError &&
+                (this.mainLastApiError?.checkedAt === undefined ||
+                    this.mainQuotaErrorClearedAt === undefined ||
+                    this.mainLastApiError.checkedAt <= this.mainQuotaErrorClearedAt)) {
+                this.mainLastApiError = undefined;
+            }
+        }
+        if (persistedError &&
+            (!this.mainQuotaIdentityKnown ||
+                persistedIdentity === undefined ||
+                persistedIdentity === this.mainAccountId) &&
+            (this.mainQuotaErrorClearedAt === undefined ||
+                typeof persistedError.checkedAt !== 'number' ||
+                persistedError.checkedAt > this.mainQuotaErrorClearedAt) &&
+            (this.mainLastApiError?.checkedAt === undefined ||
+                persistedError.checkedAt >= this.mainLastApiError.checkedAt) &&
+            quotaBackoffActive(persistedError, this.now())) {
+            this.mainLastApiError = persistedError;
+            if (persistedGeneration !== undefined) {
+                this.mainQuotaErrorGeneration = persistedGeneration;
+            }
+            return;
+        }
+        if (this.mainAccountId !== undefined &&
+            this.mainLastApiError?.accountIdentity !== undefined &&
+            this.mainLastApiError.accountIdentity !== this.mainAccountId) {
+            this.mainLastApiError = undefined;
+        }
     }
     /**
      * Seed fallback cache entries from persisted account.quota data.
@@ -314,22 +449,32 @@ export class QuotaManager {
      */
     seedFallbacksFromAccounts(accounts) {
         const checkInterval = getQuotaCheckIntervalMs(this.storage);
+        const configuredIds = new Set(accounts.map((account) => account.id));
+        for (const accountId of this.fallbackAuthLineages.keys()) {
+            if (!configuredIds.has(accountId)) {
+                this.clearFallback(accountId);
+                this.fallbackAuthLineages.delete(accountId);
+            }
+        }
         for (const account of accounts) {
+            const lineageChanged = this.bindFallbackLineage(account.id, account);
+            if (lineageChanged)
+                continue;
             if (account.enabled === false)
                 continue;
             if (!account.quota)
                 continue;
-            const checkedAt = Math.max(account.quota.five_hour?.checkedAt ?? 0, account.quota.seven_day?.checkedAt ?? 0);
+            const checkedAt = quotaSnapshotCheckedAt(account.quota);
             if (checkedAt <= 0)
                 continue;
-            const existing = this.getFallback(account.id, account.access);
+            const existing = this.getFallback(account.id);
             if (existing && existing.checkedAt >= checkedAt)
                 continue;
             this.setFallback(account.id, {
-                quota: account.quota,
+                quota: { ...account.quota, accountIdentity: account.id },
                 refreshAfter: checkedAt + checkInterval,
                 checkedAt,
-            }, account.access);
+            }, account);
         }
     }
     /**
@@ -337,34 +482,77 @@ export class QuotaManager {
      * account — a fallback account's 429 never reports here.
      */
     isBackedOff() {
+        // Unlike cached numbers above, restrictions stay active while identity is
+        // ambiguous; only a confirmed account change may release an inherited guard.
         return quotaBackoffActive(this.mainLastApiError, this.now());
     }
     /**
      * Whether a specific fallback account's quota API is in backoff.
      */
-    isFallbackBackedOff(accountId, accessToken) {
-        if (accessToken) {
-            const errorFp = this.fallbackErrorTokenFps.get(accountId);
-            if (errorFp !== tokenFingerprint(accessToken))
-                return false;
-        }
+    isFallbackBackedOff(accountId) {
         return quotaBackoffActive(this.fallbackApiErrors.get(accountId), this.now());
     }
     getLastApiError() {
         return this.mainLastApiError;
     }
+    getMainQuotaErrorGeneration() {
+        return this.mainQuotaErrorGeneration;
+    }
+    getMainQuotaIdentityGeneration() {
+        return this.mainGeneration;
+    }
+    getMainQuotaErrorClearedAt() {
+        return this.mainQuotaErrorClearedAt;
+    }
+    clearMainBackoff() {
+        if (!this.mainLastApiError)
+            return undefined;
+        this.mainLastApiError = undefined;
+        this.mainQuotaErrorGeneration += 1;
+        this.mainQuotaErrorClearedAt = mergeMainQuotaErrorClearedAt(this.mainQuotaErrorClearedAt, this.now());
+        return this.mainQuotaErrorGeneration;
+    }
     // =========================================================================
     // Private
     // =========================================================================
     /** Minimum gap between consecutive quota API calls (ms). */
     static API_CALL_GAP_MS = 1_000;
-    static fallbackInflightKey(accountId, accessToken) {
-        return JSON.stringify([accountId, tokenFingerprint(accessToken)]);
+    static fallbackInflightKey(accountId) {
+        return accountId;
     }
     static quotaLockName(accountId) {
         const safeId = accountId.replace(/[^a-zA-Z0-9._-]+/g, '-');
         return `opencode-fallback-quota-refresh-${safeId || 'account'}`;
     }
+    bindFallbackLineage(accountId, account) {
+        if (!account)
+            return false;
+        const hadLineage = this.fallbackAuthLineages.has(accountId);
+        const previousLineage = this.fallbackAuthLineages.get(accountId);
+        const lineageChanged = hadLineage &&
+            account.authLineageId !== undefined &&
+            previousLineage !== account.authLineageId;
+        if (lineageChanged)
+            this.clearFallback(accountId);
+        this.fallbackAuthLineages.set(accountId, account.authLineageId);
+        return lineageChanged;
+    }
+    acceptFallbackQuotaObservation(accountId, account) {
+        const hasLineage = this.fallbackAuthLineages.has(accountId);
+        const currentLineage = this.fallbackAuthLineages.get(accountId);
+        const observedLineage = account?.authLineageId;
+        if (hasLineage && currentLineage !== observedLineage) {
+            logger.trace('quota', 'skipped stale fallback quota observation after lineage change', {
+                accountId,
+                storedLineage: currentLineage,
+                servedLineage: observedLineage,
+            });
+            return false;
+        }
+        if (!hasLineage)
+            this.fallbackAuthLineages.set(accountId, observedLineage);
+        return true;
+    }
     /**
      * Serialize API calls through a shared gate so only one
      * quota API request runs at a time, with a minimum gap
@@ -389,25 +577,36 @@ export class QuotaManager {
         this.apiGate = queued.catch(() => { });
         return queued;
     }
-    async _fetchMain(accessToken) {
-        const thisFetchFp = tokenFingerprint(accessToken);
+    async _fetchMain(mainAccountId, accessToken, generation) {
         return this._enqueueApiFetch(async () => {
             try {
                 // Re-check backoff inside gate — may have been set by
                 // a preceding queued call while we waited
                 if (this.isBackedOff()) {
-                    if (this.main)
-                        return this.main.quota;
+                    if (this.main && this.mainAccountId === mainAccountId) {
+                        return { quota: this.main.quota, fetched: false };
+                    }
                     throw new Error('Quota API rate-limited — try again later');
                 }
+                if (this.mainQuotaIdentityKnown &&
+                    this.mainQuotaIdentityStrict &&
+                    this.mainGeneration !== generation) {
+                    return {
+                        quota: { accountIdentity: mainAccountId },
+                        fetched: false,
+                    };
+                }
                 const fileLock = await acquireRefreshFileLock({
                     name: 'opencode-main-quota-refresh',
                     ttlMs: 30_000,
                 });
                 if (!fileLock) {
                     const cached = this.main;
-                    if (cached && this.now() < cached.refreshAfter)
-                        return cached.quota;
+                    if (cached &&
+                        this.mainAccountId === mainAccountId &&
+                        this.now() < cached.refreshAfter) {
+                        return { quota: cached.quota, fetched: false };
+                    }
                     throw new Error('Quota refresh is already in progress');
                 }
                 try {
@@ -418,19 +617,46 @@ export class QuotaManager {
                         now: this.now,
                     });
                     const now = this.now();
-                    const completedQuota = mergePollCompletionWithNewerHeaders(this.mainTokenFp === thisFetchFp ? this.main?.quota : undefined, quota);
-                    this.mainTokenFp = tokenFingerprint(accessToken);
+                    if (this.mainQuotaIdentityKnown &&
+                        this.mainQuotaIdentityStrict &&
+                        this.mainGeneration !== generation) {
+                        return {
+                            quota: {
+                                ...quota,
+                                ...(mainAccountId !== undefined && {
+                                    accountIdentity: mainAccountId,
+                                }),
+                            },
+                            fetched: true,
+                        };
+                    }
+                    const completedQuota = mergePollCompletionWithNewerHeaders(this.mainAccountId === mainAccountId &&
+                        (!this.mainQuotaIdentityKnown ||
+                            !this.mainQuotaIdentityStrict ||
+                            this.main?.quota.accountIdentity === mainAccountId)
+                        ? this.main?.quota
+                        : undefined, {
+                        ...quota,
+                        ...(mainAccountId !== undefined && {
+                            accountIdentity: mainAccountId,
+                        }),
+                    });
+                    this.mainAccountId = mainAccountId;
                     this.main = {
                         quota: completedQuota,
                         refreshAfter: getQuotaNextRefreshAt(completedQuota, this.storage, now),
                         checkedAt: completedQuota.checkedAt ?? now,
                     };
-                    this.mainLastApiError = undefined;
-                    this.onMainQuotaFetched?.(completedQuota, now, this.mainTokenFp, fetchStartedAt);
-                    return completedQuota;
+                    if (this.mainLastApiError) {
+                        this.mainLastApiError = undefined;
+                        this.mainQuotaErrorGeneration += 1;
+                        this.mainQuotaErrorClearedAt = mergeMainQuotaErrorClearedAt(this.mainQuotaErrorClearedAt, now);
+                    }
+                    this.onMainQuotaFetched?.(completedQuota, now, tokenFingerprint(accessToken), fetchStartedAt, this.mainQuotaErrorGeneration, this.mainQuotaErrorClearedAt);
+                    return { quota: completedQuota, fetched: true };
                 }
                 catch (error) {
-                    this._handleMainFetchError(error);
+                    this._handleMainFetchError(error, generation);
                     throw error;
                 }
                 finally {
@@ -438,21 +664,24 @@ export class QuotaManager {
                 }
             }
             finally {
-                if (this.inflightMainFp === thisFetchFp) {
+                if (this.inflightMainAccountId === mainAccountId) {
                     this.inflightMain = null;
-                    this.inflightMainFp = null;
+                    this.inflightMainAccountId = undefined;
                 }
             }
         });
     }
-    async _fetchFallback(accountId, accessToken) {
+    async _fetchFallback(accountId, accessToken, generation, account) {
         return this._enqueueApiFetch(async () => {
             try {
+                if ((this.fallbackGenerations.get(accountId) ?? 0) !== generation) {
+                    return { quota: { accountIdentity: accountId }, fetched: false };
+                }
                 // Re-check backoff inside gate — scoped to this fallback account
-                if (this.isFallbackBackedOff(accountId, accessToken)) {
-                    const cached = this.getFallback(accountId, accessToken);
+                if (this.isFallbackBackedOff(accountId)) {
+                    const cached = this.getFallback(accountId, account);
                     if (cached)
-                        return cached.quota;
+                        return { quota: cached.quota, fetched: false };
                     throw new Error('Quota API rate-limited — try again later');
                 }
                 const fileLock = await acquireRefreshFileLock({
@@ -460,9 +689,10 @@ export class QuotaManager {
                     ttlMs: 30_000,
                 });
                 if (!fileLock) {
-                    const cached = this.getFallback(accountId, accessToken);
-                    if (cached && this.now() < cached.refreshAfter)
-                        return cached.quota;
+                    const cached = this.getFallback(accountId, account);
+                    if (cached && this.now() < cached.refreshAfter) {
+                        return { quota: cached.quota, fetched: false };
+                    }
                     throw new Error('Quota refresh is already in progress');
                 }
                 try {
@@ -472,27 +702,29 @@ export class QuotaManager {
                         now: this.now,
                     });
                     const now = this.now();
-                    const completedQuota = mergePollCompletionWithNewerHeaders(this.getFallback(accountId, accessToken)?.quota, quota);
+                    if ((this.fallbackGenerations.get(accountId) ?? 0) !== generation) {
+                        return {
+                            quota: { ...quota, accountIdentity: accountId },
+                            fetched: true,
+                        };
+                    }
+                    const completedQuota = mergePollCompletionWithNewerHeaders(this.getFallback(accountId, account)?.quota, { ...quota, accountIdentity: accountId });
                     this.setFallback(accountId, {
                         quota: completedQuota,
                         refreshAfter: getQuotaNextRefreshAt(completedQuota, this.storage, now),
                         checkedAt: completedQuota.checkedAt ?? now,
-                    }, accessToken);
+                    }, account);
                     this.fallbackApiErrors.delete(accountId);
-                    this.fallbackErrorTokenFps.delete(accountId);
-                    return completedQuota;
+                    return { quota: completedQuota, fetched: true };
                 }
                 finally {
                     await fileLock.release();
                 }
             }
             catch (error) {
-                this._handleFallbackFetchError(accountId, accessToken, error);
+                this._handleFallbackFetchError(accountId, error, generation);
                 throw error;
             }
-            finally {
-                this.inflightFallbacks.delete(QuotaManager.fallbackInflightKey(accountId, accessToken));
-            }
         });
     }
     // A 401 is an auth/token problem and a 403 is an account/org policy problem,
@@ -506,15 +738,24 @@ export class QuotaManager {
         return /quota check failed: 401\b/.test(message);
     }
     /** Main quota failure: arms main-only backoff and persists via onApiError. */
-    _handleMainFetchError(error) {
+    _handleMainFetchError(error, generation) {
+        if (this.mainGeneration !== generation)
+            return;
+        if (this.mainQuotaIdentityKnown &&
+            this.mainQuotaIdentityStrict &&
+            this.mainAccountId === undefined) {
+            return;
+        }
         if (QuotaManager.isAuthError(error))
             return;
         this.mainLastApiError = buildQuotaOperationError({
             error,
             now: this.now(),
+            accountIdentity: this.mainAccountId,
             previous: this.mainLastApiError,
         });
-        this.onApiError?.(this.mainLastApiError);
+        this.mainQuotaErrorGeneration += 1;
+        this.onApiError?.(this.mainLastApiError, this.mainQuotaErrorGeneration);
     }
     /**
      * Fallback quota failure: arms backoff for THIS account only. Never touches
@@ -522,18 +763,17 @@ export class QuotaManager {
      * quota error) — the per-account error is recorded by the caller via the
      * account's lastQuotaRefreshError.
      */
-    _handleFallbackFetchError(accountId, accessToken, error) {
+    _handleFallbackFetchError(accountId, error, generation) {
+        if ((this.fallbackGenerations.get(accountId) ?? 0) !== generation)
+            return;
         if (QuotaManager.isAuthError(error))
             return;
-        const tokenFp = tokenFingerprint(accessToken);
-        const previous = this.fallbackErrorTokenFps.get(accountId) === tokenFp
-            ? this.fallbackApiErrors.get(accountId)
-            : undefined;
+        const previous = this.fallbackApiErrors.get(accountId);
         this.fallbackApiErrors.set(accountId, buildQuotaOperationError({
             error,
             now: this.now(),
             previous,
+            accountIdentity: accountId,
         }));
-        this.fallbackErrorTokenFps.set(accountId, tokenFp);
     }
 }