@cortexkit/anthropic-auth-core 1.19.0 → 1.20.0

package/dist/accounts.js

@@ -2,10 +2,10 @@ import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { parseRetryAfterHeader, refreshClaudeOAuthToken } from "./auth.js";
-import { CACHE_1H_MODES, CLAUDE_CODE_VERSION, DEFAULT_CACHE_1H_MODE, } from "./constants.js";
-import { log, logger } from "./logger.js";
-import { tokenFingerprint } from "./token-fingerprint.js";
+import { parseRetryAfterHeader, refreshClaudeOAuthToken } from './auth.js';
+import { CACHE_1H_MODES, CLAUDE_CODE_VERSION, DEFAULT_CACHE_1H_MODE, } from './constants.js';
+import { log, logger } from './logger.js';
+import { tokenFingerprint } from './token-fingerprint.js';
 const setRefreshLockRenewalTimeout = globalThis.setTimeout.bind(globalThis);
 const clearRefreshLockRenewalTimeout = globalThis.clearTimeout.bind(globalThis);
 export const ACCOUNT_FILE_NAME = 'anthropic-auth.json';
@@ -116,6 +116,9 @@ function normalizeAccount(value) {
     return {
         ...normalizeAccountBase(value),
         type: 'oauth',
+        authLineageId: typeof value.authLineageId === 'string' && value.authLineageId.trim()
+            ? value.authLineageId
+            : undefined,
         access: typeof value.access === 'string' ? value.access : undefined,
         refresh: value.refresh,
         expires: typeof value.expires === 'number' ? value.expires : undefined,
@@ -126,6 +129,7 @@ function normalizeAccount(value) {
         lastQuotaRefreshError: normalizeOperationError(value.lastQuotaRefreshError),
         quota: normalizeQuota(value.quota),
         profile: normalizeOAuthAccountProfile(value.profile),
+        prime: normalizePrimeUsageCounters(value.prime),
     };
 }
 function normalizeOAuthAccountProfile(value) {
@@ -192,6 +196,27 @@ function normalizeQuotaWindow(value) {
         resetsAt: typeof value.resetsAt === 'string' ? value.resetsAt : undefined,
     };
 }
+function normalizePrimeUsageCounters(value) {
+    if (!isRecord(value))
+        return undefined;
+    const count = Number(value.count);
+    const inputTokens = Number(value.inputTokens);
+    const outputTokens = Number(value.outputTokens);
+    const since = Number(value.since);
+    if (![count, inputTokens, outputTokens, since].every(Number.isFinite) ||
+        count < 0 ||
+        inputTokens < 0 ||
+        outputTokens < 0 ||
+        since < 0) {
+        return undefined;
+    }
+    return {
+        count: Math.floor(count),
+        inputTokens: Math.floor(inputTokens),
+        outputTokens: Math.floor(outputTokens),
+        since: Math.floor(since),
+    };
+}
 function normalizeQuota(value) {
     if (!isRecord(value))
         return undefined;
@@ -326,6 +351,35 @@ function normalizeStorage(value) {
         relay: isRecord(value.relay) ? value.relay : undefined,
         logging: isRecord(value.logging) ? value.logging : undefined,
         killswitch: isRecord(value.killswitch) ? value.killswitch : undefined,
+        prime: (() => {
+            if (!isRecord(value.prime))
+                return undefined;
+            const enabled = typeof value.prime.enabled === 'boolean'
+                ? value.prime.enabled
+                : undefined;
+            const main = normalizePrimeUsageCounters(value.prime.main);
+            const mainAuthLineageId = typeof value.prime.mainAuthLineageId === 'string' &&
+                value.prime.mainAuthLineageId.trim()
+                ? value.prime.mainAuthLineageId
+                : undefined;
+            const mainAuthLineageRefreshTokenFingerprint = typeof value.prime.mainAuthLineageRefreshTokenFingerprint ===
+                'string' && value.prime.mainAuthLineageRefreshTokenFingerprint.trim()
+                ? value.prime.mainAuthLineageRefreshTokenFingerprint
+                : undefined;
+            if (enabled === undefined &&
+                !main &&
+                !mainAuthLineageId &&
+                !mainAuthLineageRefreshTokenFingerprint)
+                return undefined;
+            return {
+                ...(enabled !== undefined && { enabled }),
+                ...(main && { main }),
+                ...(mainAuthLineageId && { mainAuthLineageId }),
+                ...(mainAuthLineageRefreshTokenFingerprint && {
+                    mainAuthLineageRefreshTokenFingerprint,
+                }),
+            };
+        })(),
         accounts: value.accounts
             .map(normalizeAccount)
             .filter((account) => account != null),
@@ -424,6 +478,40 @@ function mergeConfigAndState(configValue, stateValue) {
             mainQuotaToken: mainQuotaSource.quotaToken,
             mainLastQuotaApiError: mainQuotaSource.lastQuotaApiError,
         }),
+        // Carry the main-side prime counters from the state file back into the
+        // merged storage so a subsequent read sees the cumulative counters. The
+        // `enabled` flag stays sourced from the config side; main-side counters
+        // live exclusively on the state file.
+        prime: (() => {
+            const configPrime = isRecord(configValue.prime)
+                ? configValue.prime
+                : undefined;
+            const mainCounters = normalizePrimeUsageCounters(mainState?.prime);
+            const mainAuthLineageId = typeof mainState?.primeAuthLineageId === 'string' &&
+                mainState.primeAuthLineageId.trim()
+                ? mainState.primeAuthLineageId
+                : undefined;
+            const mainAuthLineageRefreshTokenFingerprint = typeof mainState?.primeAuthLineageRefreshTokenFingerprint ===
+                'string' && mainState.primeAuthLineageRefreshTokenFingerprint.trim()
+                ? mainState.primeAuthLineageRefreshTokenFingerprint
+                : undefined;
+            if (!configPrime &&
+                !mainCounters &&
+                !mainAuthLineageId &&
+                !mainAuthLineageRefreshTokenFingerprint)
+                return undefined;
+            return {
+                ...(configPrime &&
+                    typeof configPrime.enabled === 'boolean' && {
+                    enabled: configPrime.enabled,
+                }),
+                ...(mainCounters && { main: mainCounters }),
+                ...(mainAuthLineageId && { mainAuthLineageId }),
+                ...(mainAuthLineageRefreshTokenFingerprint && {
+                    mainAuthLineageRefreshTokenFingerprint,
+                }),
+            };
+        })(),
         accounts,
     };
 }
@@ -464,6 +552,7 @@ function accountRuntimeState(account) {
         });
     }
     return objectWithDefinedEntries({
+        authLineageId: account.authLineageId,
         access: account.access,
         refresh: account.refresh,
         expires: account.expires,
@@ -473,9 +562,11 @@ function accountRuntimeState(account) {
         lastQuotaRefreshError: account.lastQuotaRefreshError,
         quota: account.quota,
         profile: account.profile,
+        prime: account.prime,
     });
 }
-function quotaSnapshotCheckedAt(quota) {
+/** Returns the latest timestamp carried by any quota snapshot window. */
+export function quotaSnapshotCheckedAt(quota) {
     return Math.max(quota?.five_hour?.checkedAt ?? 0, quota?.seven_day?.checkedAt ?? 0, ...(quota?.scoped?.map((window) => window.checkedAt) ?? []), quota?.checkedAt ?? 0);
 }
 function quotaSourcePrecedence(quota) {
@@ -652,6 +743,15 @@ function configFromStorage(storage) {
         cacheKeep: storage.cacheKeep,
         relay: storage.relay,
         killswitch: storage.killswitch,
+        prime: (() => {
+            // Config side carries ONLY the `enabled` flag — runtime counters and
+            // lineage bindings stay on the state file. Write `enabled` whenever it was explicitly set so a
+            // toggle off persists `{ enabled: false }` and is visible to a stale
+            // reader that only inspects the config.
+            if (typeof storage.prime?.enabled !== 'boolean')
+                return undefined;
+            return { enabled: storage.prime.enabled };
+        })(),
         accounts: storage.accounts.map(accountConfig),
     });
 }
@@ -827,6 +927,29 @@ function applyMainRefreshStatePatch(state, storage) {
     state.main.refreshLeaseUntil = storage.refresh?.mainRefreshLeaseUntil;
     state.main.refreshLeaseTokenHash = storage.refresh?.mainRefreshLeaseTokenHash;
 }
+function applyMainPrimeStatePatch(state, storage) {
+    const incoming = storage.prime?.main;
+    const incomingAuthLineageId = storage.prime?.mainAuthLineageId;
+    const incomingAuthLineageRefreshTokenFingerprint = storage.prime?.mainAuthLineageRefreshTokenFingerprint;
+    if (!incoming &&
+        !incomingAuthLineageId &&
+        !incomingAuthLineageRefreshTokenFingerprint)
+        return;
+    state.main = state.main ?? {};
+    // Last-writer-wins on prime counters — the only writer is the prime manager
+    // itself, monotonically accumulating per success, so there is no race for an
+    // older write to overwrite a newer one within this process. Across processes
+    // the cross-process claim marker (#1247) keeps the fire exclusive.
+    if (incoming)
+        state.main.prime = incoming;
+    if (incomingAuthLineageId) {
+        state.main.primeAuthLineageId = incomingAuthLineageId;
+    }
+    if (incomingAuthLineageRefreshTokenFingerprint) {
+        state.main.primeAuthLineageRefreshTokenFingerprint =
+            incomingAuthLineageRefreshTokenFingerprint;
+    }
+}
 function pruneUndefined(value) {
     if (Array.isArray(value))
         return value.map(pruneUndefined);
@@ -941,6 +1064,8 @@ async function saveAccountStateUnlocked(storage, path, scope) {
         applyMainQuotaStatePatch(next, storage);
     if (scope.mainRefresh)
         applyMainRefreshStatePatch(next, storage);
+    if (scope.mainPrime)
+        applyMainPrimeStatePatch(next, storage);
     if (scope.accounts) {
         const ids = scope.accounts === true ? null : new Set(scope.accounts);
         next.accounts = { ...(isRecord(next.accounts) ? next.accounts : {}) };
@@ -1284,6 +1409,203 @@ export async function setCacheKeepSubagentsEnabled(enabled, path = getAccountSto
     await saveAccounts(storage, path);
     return storage;
 }
+export function isPrimePersistentlyEnabled(storage) {
+    return storage?.prime?.enabled === true;
+}
+export async function setPrimePersistentEnabled(enabled, path = getAccountStoragePath()) {
+    const storage = (await loadAccounts(path)) ?? createEmptyStorage();
+    storage.prime = {
+        ...(storage.prime ?? {}),
+        enabled,
+    };
+    await saveAccounts(storage, path);
+    return storage;
+}
+/**
+ * Return the stable prime marker identity for an OAuth account, seeding it in
+ * runtime state when older storage has no lineage yet. Main lookups return
+ * undefined when the live refresh token is unavailable and no lineage exists.
+ */
+export async function getOrCreatePrimeAuthLineageId(accountId, path = getAccountStoragePath(), mainRefreshToken) {
+    return enqueueSave(async () => {
+        const configLock = await acquireAccountConfigWriteLock(path);
+        try {
+            const stateLock = await acquireAccountStateWriteLock(path);
+            try {
+                const storage = (await loadAccounts(path)) ?? createEmptyStorage();
+                if (accountId === 'main') {
+                    const existing = storage.prime?.mainAuthLineageId;
+                    const observedFingerprint = mainRefreshToken
+                        ? tokenFingerprint(mainRefreshToken)
+                        : undefined;
+                    const boundFingerprint = storage.prime?.mainAuthLineageRefreshTokenFingerprint;
+                    if (existing) {
+                        if (!observedFingerprint ||
+                            boundFingerprint === observedFingerprint)
+                            return existing;
+                        if (boundFingerprint &&
+                            storage.refresh?.mainRefreshLeaseUntil &&
+                            storage.refresh.mainRefreshLeaseUntil > Date.now()) {
+                            // The owner binds before publishing its rotated credential. An
+                            // active lease makes either side of that handoff ambiguous, so
+                            // suppress this tick instead of classifying it as a re-login.
+                            return existing;
+                        }
+                        if (!boundFingerprint) {
+                            // Legacy lineages predate refresh-token binding. The first
+                            // observation attaches the credential without changing markers.
+                            storage.prime = {
+                                ...(storage.prime ?? {}),
+                                mainAuthLineageRefreshTokenFingerprint: observedFingerprint,
+                            };
+                            await saveAccountStateUnlocked(storage, path, {
+                                mainPrime: true,
+                            });
+                            return existing;
+                        }
+                    }
+                    // Without the live host credential there is no safe way to bind a
+                    // new identity. Skip this tick rather than creating an unbound
+                    // namespace that could churn or suppress another account.
+                    if (!observedFingerprint)
+                        return undefined;
+                    // A bound mismatch that did not pass through the owned refresh path
+                    // is a host credential replacement and needs a fresh marker identity.
+                    const authLineageId = randomUUID();
+                    storage.prime = {
+                        ...(storage.prime ?? {}),
+                        mainAuthLineageId: authLineageId,
+                        ...(observedFingerprint && {
+                            mainAuthLineageRefreshTokenFingerprint: observedFingerprint,
+                        }),
+                    };
+                    await saveAccountStateUnlocked(storage, path, { mainPrime: true });
+                    return authLineageId;
+                }
+                const account = storage.accounts.find((candidate) => candidate.id === accountId && isOAuthAccount(candidate));
+                if (!account) {
+                    throw new Error(`getOrCreatePrimeAuthLineageId: OAuth account "${accountId}" not found`);
+                }
+                if (account.authLineageId)
+                    return account.authLineageId;
+                // Upgrading changes the marker namespace once, so an already-primed
+                // window may fire again; persisting the seed prevents every later token
+                // rotation from repeating that migration cost.
+                const authLineageId = randomUUID();
+                account.authLineageId = authLineageId;
+                await saveAccountStateUnlocked(storage, path, {
+                    accounts: [accountId],
+                });
+                return authLineageId;
+            }
+            finally {
+                await stateLock.release();
+            }
+        }
+        finally {
+            await configLock.release();
+        }
+    });
+}
+/** Advance a main lineage across a refresh performed by this plugin. */
+export async function continueMainPrimeAuthLineageAfterRefresh(input, path = getAccountStoragePath()) {
+    return enqueueSave(async () => {
+        const configLock = await acquireAccountConfigWriteLock(path);
+        try {
+            const stateLock = await acquireAccountStateWriteLock(path);
+            try {
+                const storage = (await loadAccounts(path)) ?? createEmptyStorage();
+                const authLineageId = storage.prime?.mainAuthLineageId;
+                if (!authLineageId)
+                    return;
+                const previousFingerprint = tokenFingerprint(input.previousRefreshToken);
+                const currentFingerprint = tokenFingerprint(input.currentRefreshToken);
+                const boundFingerprint = storage.prime?.mainAuthLineageRefreshTokenFingerprint;
+                if (boundFingerprint &&
+                    boundFingerprint !== previousFingerprint &&
+                    boundFingerprint !== currentFingerprint) {
+                    // Another process observed a host replacement after this refresh
+                    // started; the stale rotation must not rebind that newer lineage.
+                    return;
+                }
+                storage.prime = {
+                    ...(storage.prime ?? {}),
+                    mainAuthLineageRefreshTokenFingerprint: currentFingerprint,
+                };
+                await saveAccountStateUnlocked(storage, path, { mainPrime: true });
+            }
+            finally {
+                await stateLock.release();
+            }
+        }
+        finally {
+            await configLock.release();
+        }
+    });
+}
+/**
+ * Atomically increment an account's cumulative prime counters and persist via
+ * the scoped runtime-state path. The `main` account lives at state.main.prime;
+ * every other account lives at state.accounts[id].prime. Config-side writes
+ * are intentionally NOT triggered so prime counters cannot leak into
+ * `anthropic-auth.json`. Callers should not depend on this function to mutate
+ * the caller's storage object.
+ */
+export async function incrementPrimeUsagePersistent(accountId, usage, path = getAccountStoragePath(), now = Date.now()) {
+    const inputTokens = Number.isFinite(usage?.inputTokens)
+        ? Math.max(0, Math.floor(usage.inputTokens))
+        : 0;
+    const outputTokens = Number.isFinite(usage?.outputTokens)
+        ? Math.max(0, Math.floor(usage.outputTokens))
+        : 0;
+    return enqueueSave(async () => {
+        // The config-write lock is the repository-wide outer lock for config and
+        // runtime-state RMW operations; taking it before the state write preserves
+        // saveAccountsLocked's config → state ordering across processes.
+        const lock = await acquireAccountConfigWriteLock(path);
+        try {
+            const stateLock = await acquireAccountStateWriteLock(path);
+            try {
+                const storage = (await loadAccounts(path)) ?? createEmptyStorage();
+                if (accountId === 'main') {
+                    const existing = storage.prime?.main;
+                    const next = {
+                        count: (existing?.count ?? 0) + 1,
+                        inputTokens: (existing?.inputTokens ?? 0) + inputTokens,
+                        outputTokens: (existing?.outputTokens ?? 0) + outputTokens,
+                        since: existing?.since ?? Math.floor(now),
+                    };
+                    storage.prime = { ...(storage.prime ?? {}), main: next };
+                    await saveAccountStateUnlocked(storage, path, { mainPrime: true });
+                    return next;
+                }
+                const index = storage.accounts.findIndex((account) => account.id === accountId);
+                if (index < 0) {
+                    throw new Error(`incrementPrimeUsagePersistent: account "${accountId}" not found`);
+                }
+                const account = storage.accounts[index];
+                const existing = account.prime;
+                const next = {
+                    count: (existing?.count ?? 0) + 1,
+                    inputTokens: (existing?.inputTokens ?? 0) + inputTokens,
+                    outputTokens: (existing?.outputTokens ?? 0) + outputTokens,
+                    since: existing?.since ?? Math.floor(now),
+                };
+                storage.accounts[index] = { ...account, prime: next };
+                await saveAccountStateUnlocked(storage, path, {
+                    accounts: [accountId],
+                });
+                return next;
+            }
+            finally {
+                await stateLock.release();
+            }
+        }
+        finally {
+            await lock.release();
+        }
+    });
+}
 function getFallbackStatuses(storage) {
     return storage?.fallbackOn?.length ? storage.fallbackOn : DEFAULT_FALLBACK_ON;
 }
@@ -1418,6 +1740,27 @@ export function formatRefreshBackoffMessage(error, now) {
     const seconds = Math.max(1, Math.ceil(((error.nextRetryAt ?? now) - now) / 1000));
     return `Claude OAuth refresh is backed off for ${seconds}s after: ${error.message}`;
 }
+function createRefreshBackoffActiveError(error, now) {
+    return Object.assign(new Error(formatRefreshBackoffMessage(error, now)), {
+        refreshBackoffError: error,
+    });
+}
+function existingRefreshBackoffError(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const existing = error
+        .refreshBackoffError;
+    return existing && typeof existing.message === 'string' ? existing : undefined;
+}
+export function getFallbackReauthLabels(storage) {
+    if (!storage)
+        return [];
+    return storage.accounts
+        .filter((account) => account.enabled !== false &&
+        isOAuthAccount(account) &&
+        isPermanentRefreshError(account.lastRefreshError))
+        .map((account) => account.label?.trim() || account.id);
+}
 export function isQuotaPolicyAuthError(error) {
     const status = error.status;
     if (status === 403)
@@ -1454,7 +1797,7 @@ export function getPersistedLogLevel(storage) {
     return storage?.logging?.level;
 }
 export async function setLogLevelPersistent(level, path = getAccountStoragePath()) {
-    const { setLogLevel } = await import("./logger.js");
+    const { setLogLevel } = await import('./logger.js');
     const storage = (await loadAccounts(path)) ?? createEmptyStorage();
     storage.logging = {
         ...(storage.logging ?? {}),
@@ -1486,15 +1829,18 @@ function failClosedOnUnknownQuota(storage) {
     return (storage?.quota?.failClosedOnUnknownQuota ??
         DEFAULT_FAIL_CLOSED_ON_UNKNOWN_QUOTA);
 }
+function normalizeScopedQuotaModel(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
 function scopedQuotaModelKey(model) {
     if (typeof model !== 'string')
         return null;
-    const normalized = model.toLowerCase();
+    const normalized = normalizeScopedQuotaModel(model);
     if (normalized.includes('fable'))
         return 'fable';
     if (normalized.includes('mythos'))
         return 'mythos';
-    return null;
+    return normalized;
 }
 export function getScopedQuotaWindowForModel(quota, model) {
     const key = scopedQuotaModelKey(model);
@@ -1503,8 +1849,8 @@ export function getScopedQuotaWindowForModel(quota, model) {
     return quota?.scoped?.find((window) => {
         const haystack = [window.modelId, window.modelName, window.title]
             .filter((value) => typeof value === 'string')
-            .join(' ')
-            .toLowerCase();
+            .map(normalizeScopedQuotaModel)
+            .join(' ');
         return haystack.includes(key);
     });
 }
@@ -1997,6 +2343,11 @@ function formatErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function recordRefreshError(account, error, now) {
+    const existing = existingRefreshBackoffError(error);
+    if (existing) {
+        account.lastRefreshError = existing;
+        return;
+    }
     account.lastRefreshError = buildRefreshOperationError({
         error,
         now,
@@ -2005,7 +2356,7 @@ function recordRefreshError(account, error, now) {
     });
 }
 function recordQuotaRefreshError(account, error, now) {
-    if (isQuotaPolicyAuthError(error))
+    if (isQuotaPolicyAuthError(error) || existingRefreshBackoffError(error))
         return;
     account.lastQuotaRefreshError = buildQuotaOperationError({
         error,
@@ -2031,12 +2382,17 @@ export class FallbackAccountManager {
     quotaTimer = null;
     quotaManager;
     onFallbackStorageChanged;
+    setIntervalImpl;
+    clearIntervalImpl;
     constructor(options = {}) {
         this.now = options.now ?? Date.now;
         this.fetchImpl = options.fetchImpl ?? fetch;
         this.configPath = options.configPath ?? getAccountStoragePath();
         this.quotaManager = options.quotaManager ?? null;
         this.onFallbackStorageChanged = options.onFallbackStorageChanged;
+        this.setIntervalImpl = options.setIntervalImpl ?? globalThis.setInterval;
+        this.clearIntervalImpl =
+            options.clearIntervalImpl ?? globalThis.clearInterval;
     }
     /**
      * Seed QuotaManager from persisted account.quota if no cache entry exists
@@ -2047,7 +2403,7 @@ export class FallbackAccountManager {
             return;
         if (!account.quota)
             return;
-        const checkedAt = Math.max(account.quota.five_hour?.checkedAt ?? 0, account.quota.seven_day?.checkedAt ?? 0);
+        const checkedAt = quotaSnapshotCheckedAt(account.quota);
         if (checkedAt <= 0)
             return;
         const existing = this.quotaManager.getFallback(account.id, account.access);
@@ -2075,7 +2431,7 @@ export class FallbackAccountManager {
         };
         void run().catch(() => { });
         if (!this.refreshTimer) {
-            this.refreshTimer = setInterval(() => {
+            this.refreshTimer = this.setIntervalImpl(() => {
                 void run().catch(() => { });
             }, BACKGROUND_TICK_MS + jitterMs(BACKGROUND_TICK_JITTER_MS));
             if ('unref' in this.refreshTimer)
@@ -2084,9 +2440,9 @@ export class FallbackAccountManager {
     }
     stopBackgroundRefresh() {
         if (this.refreshTimer)
-            clearInterval(this.refreshTimer);
+            this.clearIntervalImpl(this.refreshTimer);
         if (this.quotaTimer)
-            clearInterval(this.quotaTimer);
+            this.clearIntervalImpl(this.quotaTimer);
         this.refreshTimer = null;
         this.quotaTimer = null;
     }
@@ -2105,7 +2461,7 @@ export class FallbackAccountManager {
                     const refreshError = next.lastRefreshError;
                     if (refreshError &&
                         refreshBackoffActive(refreshError, next.refresh, this.now())) {
-                        throw new Error(formatRefreshBackoffMessage(refreshError, this.now()));
+                        throw createRefreshBackoffActiveError(refreshError, this.now());
                     }
                     next = await this.refreshAccount(next, storage);
                     changed = true;
@@ -2120,7 +2476,7 @@ export class FallbackAccountManager {
                 // the background refreshQuotaForDueAccounts() guard.
                 if (stale &&
                     !quotaBackoffActive(next.lastQuotaRefreshError, this.now())) {
-                    next = await this.refreshAccountQuota(next, storage);
+                    next = (await this.refreshAccountQuota(next, storage)).account;
                     changed = true;
                 }
                 // Single source of truth: evaluate quota policy from the unified
@@ -2280,7 +2636,7 @@ export class FallbackAccountManager {
                     const refreshError = next.lastRefreshError;
                     if (refreshError &&
                         refreshBackoffActive(refreshError, next.refresh, this.now())) {
-                        throw new Error(formatRefreshBackoffMessage(refreshError, this.now()));
+                        throw createRefreshBackoffActiveError(refreshError, this.now());
                     }
                     next = await this.refreshAccount(next, storage);
                     changed = true;
@@ -2355,7 +2711,7 @@ export class FallbackAccountManager {
             if (refreshError &&
                 refreshBackoffActive(refreshError, latestAccount.refresh, this.now())) {
                 updateStoredAccount(storage, latestAccount);
-                throw new Error(formatRefreshBackoffMessage(refreshError, this.now()));
+                throw createRefreshBackoffActiveError(refreshError, this.now());
             }
         }
         return null;
@@ -2406,11 +2762,14 @@ export class FallbackAccountManager {
             });
             const refreshed = await refreshClaudeOAuthToken({
                 refreshToken,
+                authLineageId: sourceAccount.authLineageId,
                 fetchImpl: this.fetchImpl,
                 now: this.now,
             });
             sourceAccount.access = refreshed.access;
             sourceAccount.refresh = refreshed.refresh;
+            sourceAccount.authLineageId =
+                refreshed.authLineageId ?? sourceAccount.authLineageId;
             sourceAccount.expires = refreshed.expires;
             sourceAccount.lastRefreshedAt =
                 refreshed.expires - refreshed.expiresIn * 1000;
@@ -2438,15 +2797,18 @@ export class FallbackAccountManager {
         // deduplication and 429 backoff gating around the same quota API. Fall back
         // to a direct fetch only when no QuotaManager is wired (e.g. in isolation).
         const fetchSnapshot = (accessToken) => this.quotaManager
-            ? this.quotaManager.refreshFallback(target.id, accessToken)
+            ? this.quotaManager.refreshFallbackWithMetadata(target.id, accessToken)
             : fetchOAuthQuotaSnapshot({
                 accessToken,
                 fetchImpl: this.fetchImpl,
                 now: this.now,
-            });
+            }).then((quota) => ({ quota, fetched: true }));
         const fetchStartedAt = this.now();
+        let fetched = false;
         try {
-            target.quota = await fetchSnapshot(target.access);
+            const result = await fetchSnapshot(target.access);
+            target.quota = result.quota;
+            fetched = result.fetched;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -2458,7 +2820,9 @@ export class FallbackAccountManager {
             if (!target.access)
                 throw error;
             // 401 does not arm QuotaManager backoff, so this retry proceeds.
-            target.quota = await fetchSnapshot(target.access);
+            const result = await fetchSnapshot(target.access);
+            target.quota = result.quota;
+            fetched = result.fetched;
         }
         const latestStorage = await this.load();
         const latestAccount = latestStorage?.accounts.find((candidate) => candidate.id === target.id && isOAuthAccount(candidate));
@@ -2467,7 +2831,7 @@ export class FallbackAccountManager {
             latestAccount.access !== target.access) {
             this.seedFallbackQuota(latestAccount, latestStorage);
             updateStoredAccount(storage, latestAccount);
-            return latestAccount;
+            return { account: latestAccount, fetched: false };
         }
         if (latestStorage &&
             latestAccount?.access === target.access &&
@@ -2476,7 +2840,7 @@ export class FallbackAccountManager {
             quotaSnapshotIsFresh(latestAccount.quota, latestStorage, this.now())) {
             this.seedFallbackQuota(latestAccount, latestStorage);
             updateStoredAccount(storage, latestAccount);
-            return latestAccount;
+            return { account: latestAccount, fetched };
         }
         target.lastQuotaRefreshError = undefined;
         updateStoredAccount(storage, target);
@@ -2491,6 +2855,6 @@ export class FallbackAccountManager {
                 checkedAt: now,
             }, target.access);
         }
-        return target;
+        return { account: target, fetched };
     }
 }

package/dist/auth.d.ts

@@ -18,13 +18,16 @@ export type ClaudeOAuthRefreshResult = {
     refresh: string;
     expires: number;
     expiresIn: number;
+    authLineageId?: string;
 };
 export declare function refreshClaudeOAuthToken(input: {
     refreshToken: string;
+    authLineageId?: string;
     fetchImpl?: typeof fetch;
     now?: () => number;
     maxRetries?: number;
     baseDelayMs?: number;
+    setTimeoutImpl?: typeof globalThis.setTimeout;
 }): Promise<ClaudeOAuthRefreshResult>;
 export type AuthorizationResult = {
     url: string;