@cortexkit/anthropic-auth-core 1.15.1 → 1.17.0

package/dist/dump.js

@@ -1,9 +1,9 @@
-import { createHash } from 'node:crypto';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { createHash, randomBytes } from 'node:crypto';
+import { lstat, mkdir, readdir, rename, unlink, writeFile, } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { extractBillingHeaderCCH } from "./cch.js";
-import { isSecretKey, relayLog } from "./logger.js";
+import { isSecretKey, logger, relayLog } from "./logger.js";
 export const CLAUDE_DUMP_COMMAND_NAME = 'claude-dump';
 const DUMP_STATUS_TITLE = '## Claude Dump Status';
 const DUMP_ENABLED_TITLE = '## Claude Dump Enabled';
@@ -11,9 +11,21 @@ const DUMP_DISABLED_TITLE = '## Claude Dump Disabled';
 const DUMP_USAGE_TITLE = '## Claude Dump Usage';
 const DUMP_USAGE = 'Usage: `/claude-dump`, `/claude-dump on`, or `/claude-dump off`.';
 const DUMP_DIR_ENV = 'OPENCODE_ANTHROPIC_AUTH_DUMP_DIR';
+const DUMP_MAX_BYTES_ENV = 'OPENCODE_ANTHROPIC_AUTH_DUMP_MAX_BYTES';
 const DEFAULT_DUMP_DIR = join(tmpdir(), 'opencode-anthropic-auth-dumps');
+const DEFAULT_DUMP_MAX_BYTES = 512 * 1024 * 1024;
+const DUMP_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+const DUMP_SWEEP_NEWNESS_FLOOR_MS = 60 * 1000;
+const DUMP_PARTIAL_STALE_MS = 10 * 60 * 1000;
+const DUMP_ARTIFACT_SUFFIX_PATTERN = /\.(body|meta|relay|request)\.json$/;
+// Earlier builds emitted five-digit counters; current counters grow without truncation.
+const DUMP_ARTIFACT_ID_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-\d{5,}-(.+)$/;
+const DUMP_SEGMENT_PATTERN = '[a-zA-Z0-9._-]';
+const DIRECT_DUMP_PATTERN = new RegExp(`^${DUMP_SEGMENT_PATTERN}{1,80}-direct(?:-${DUMP_SEGMENT_PATTERN}{1,80})?$`);
+const RELAY_DUMP_PATTERN = new RegExp(`^${DUMP_SEGMENT_PATTERN}{1,80}-(?:http|websocket)-p[12]-(?:full_sync|patch)$`);
 let dumpEnabled = false;
 let nextDumpId = 0;
+let lastDumpSweepAt = 0;
 const DIRECT_DUMP_PREVIOUS_BODY_LIMIT = 100;
 const directDumpPreviousBodies = new Map();
 export function isDumpEnabled() {
@@ -25,11 +37,150 @@ export function setDumpEnabled(enabled) {
 export function resetDumpState() {
     dumpEnabled = false;
     nextDumpId = 0;
+    lastDumpSweepAt = 0;
     directDumpPreviousBodies.clear();
 }
 export function getDumpDirectory() {
     return process.env[DUMP_DIR_ENV] || DEFAULT_DUMP_DIR;
 }
+function getDumpMaxBytes() {
+    const configured = Number(process.env[DUMP_MAX_BYTES_ENV]);
+    return Number.isFinite(configured) && configured >= 0
+        ? Math.floor(configured)
+        : DEFAULT_DUMP_MAX_BYTES;
+}
+function isConfiguredDumpDirectory(path) {
+    return resolve(path) === resolve(getDumpDirectory());
+}
+function isDumpArtifactFileName(name) {
+    const stem = name.replace(DUMP_ARTIFACT_SUFFIX_PATTERN, '');
+    if (stem === name)
+        return false;
+    const match = DUMP_ARTIFACT_ID_PATTERN.exec(stem);
+    const requestPath = match?.[1];
+    if (!requestPath)
+        return false;
+    return (DIRECT_DUMP_PATTERN.test(requestPath) ||
+        RELAY_DUMP_PATTERN.test(requestPath));
+}
+function isDumpPartialFileName(name) {
+    if (!name.endsWith('.partial'))
+        return false;
+    const partialStem = name.slice(0, -8);
+    if (isDumpArtifactFileName(partialStem))
+        return true;
+    const separator = partialStem.lastIndexOf('.');
+    if (separator < 0)
+        return false;
+    const nonce = partialStem.slice(separator + 1);
+    return (/^[a-f0-9]{24}$/.test(nonce) &&
+        isDumpArtifactFileName(partialStem.slice(0, separator)));
+}
+export async function writeDumpFile(path, contents) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const nonce = randomBytes(12).toString('hex');
+        const partialPath = `${path}.${nonce}.partial`;
+        let created = false;
+        try {
+            await writeFile(partialPath, contents, { encoding: 'utf8', flag: 'wx' });
+            created = true;
+            await rename(partialPath, path);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                continue;
+            if (created)
+                await unlink(partialPath).catch(() => { });
+            throw error;
+        }
+    }
+    return false;
+}
+/**
+ * Caps completed dump artifacts in the configured directory. A zero-byte cap
+ * disables sweeping. Custom directories may contain unrelated files: only
+ * recognized final artifact names and stale partials are eligible. Symlinks,
+ * fresh partial writes, and files younger than the newness floor remain
+ * protected.
+ */
+export async function sweepDumpDirectory(options) {
+    const dumpDir = options.dumpDir ?? getDumpDirectory();
+    const maxBytes = options.maxBytes ?? getDumpMaxBytes();
+    const now = options.now ?? Date.now();
+    const minAgeMs = options.minAgeMs ?? DUMP_SWEEP_NEWNESS_FLOOR_MS;
+    const partialStaleMs = options.partialStaleMs ?? DUMP_PARTIAL_STALE_MS;
+    const emptyResult = { removed: 0, freedBytes: 0 };
+    if (!isConfiguredDumpDirectory(dumpDir) || maxBytes <= 0)
+        return emptyResult;
+    try {
+        const dumpDirStats = await lstat(dumpDir);
+        if (dumpDirStats.isSymbolicLink())
+            return emptyResult;
+        const protectedPaths = new Set((options.protectedPaths ?? []).map((path) => resolve(path)));
+        const entries = await readdir(dumpDir, { withFileTypes: true });
+        const files = [];
+        await Promise.all(entries.map(async (entry) => {
+            if (!entry.isFile())
+                return;
+            const partial = isDumpPartialFileName(entry.name);
+            if (!partial && !isDumpArtifactFileName(entry.name))
+                return;
+            const path = join(dumpDir, entry.name);
+            try {
+                const stats = await lstat(path);
+                if (!stats.isFile() || stats.isSymbolicLink())
+                    return;
+                files.push({
+                    path,
+                    size: stats.size,
+                    mtimeMs: stats.mtimeMs,
+                    partial,
+                });
+            }
+            catch {
+                // Files can disappear while concurrent dump requests finish.
+            }
+        }));
+        let totalBytes = files.reduce((total, file) => total + file.size, 0);
+        files.sort((left, right) => left.mtimeMs - right.mtimeMs || left.path.localeCompare(right.path));
+        let removed = 0;
+        let freedBytes = 0;
+        for (const file of files) {
+            if (protectedPaths.has(resolve(file.path)))
+                continue;
+            const ageMs = now - file.mtimeMs;
+            const stalePartial = file.partial && ageMs >= partialStaleMs;
+            if (!stalePartial && totalBytes <= maxBytes)
+                continue;
+            if (file.partial ? !stalePartial : ageMs < minAgeMs)
+                continue;
+            try {
+                await unlink(file.path);
+                totalBytes -= file.size;
+                freedBytes += file.size;
+                removed += 1;
+            }
+            catch {
+                // Dump cleanup is best-effort and must not affect request handling.
+            }
+        }
+        if (removed > 0) {
+            logger.debug('dump', 'removed old dump files', { removed, freedBytes });
+        }
+        return { removed, freedBytes };
+    }
+    catch {
+        return emptyResult;
+    }
+}
+function scheduleDumpSweep(dumpDir, protectedPaths) {
+    const now = Date.now();
+    if (now - lastDumpSweepAt < DUMP_SWEEP_INTERVAL_MS)
+        return;
+    lastDumpSweepAt = now;
+    void sweepDumpDirectory({ dumpDir, protectedPaths }).catch(() => { });
+}
 export function parseDumpCommandAction(argumentsText) {
     const normalized = argumentsText.trim().split(/\s+/).filter(Boolean);
     if (normalized.length === 0)
@@ -228,7 +379,7 @@ async function dumpRequest(input) {
         return;
     nextDumpId += 1;
     const affinity = input.affinity?.trim() || 'session-unknown';
-    const id = `${new Date().toISOString().replace(/[:.]/g, '-')}-${String(nextDumpId).padStart(5, '0')}-${dumpFileSessionSegment(affinity)}-${dumpRequestSegment(input)}`;
+    const id = `${new Date().toISOString().replace(/[:.]/g, '-')}-${String(nextDumpId).padStart(6, '0')}-${dumpFileSessionSegment(affinity)}-${dumpRequestSegment(input)}`;
     const dumpDir = getDumpDirectory();
     const prefix = join(dumpDir, id);
     const files = {
@@ -259,19 +410,20 @@ async function dumpRequest(input) {
             files,
         };
         const writes = [
-            writeFile(files.body, input.bodyText, 'utf8'),
-            writeFile(files.metadata, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8'),
+            writeDumpFile(files.body, input.bodyText),
+            writeDumpFile(files.metadata, `${JSON.stringify(metadata, null, 2)}\n`),
         ];
         if (input.payload !== undefined && files.relay) {
-            writes.push(writeFile(files.relay, `${JSON.stringify(redactForDump(input.payload), null, 2)}\n`, 'utf8'));
+            writes.push(writeDumpFile(files.relay, `${JSON.stringify(redactForDump(input.payload), null, 2)}\n`));
         }
         if (input.request !== undefined && files.request) {
-            writes.push(writeFile(files.request, `${JSON.stringify(redactForDump({
+            writes.push(writeDumpFile(files.request, `${JSON.stringify(redactForDump({
                 ...input.request,
                 headers: headersToRecord(input.request.headers),
-            }), null, 2)}\n`, 'utf8'));
+            }), null, 2)}\n`));
         }
         await Promise.all(writes);
+        scheduleDumpSweep(dumpDir, Object.values(files));
         relayLog(`dumped request id=${id} session=${shortAffinity(affinity)} body=${files.body} meta=${files.metadata}`);
     }
     catch (error) {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './accounts.ts';
 export * from './auth.ts';
 export * from './cache1h.ts';
 export * from './cachekeep.ts';
+export * from './cachekeep-registry.ts';
 export * from './cch.ts';
 export * from './claude-code.ts';
 export * from './commands/account.ts';
@@ -12,9 +13,12 @@ export * from './killswitch.ts';
 export * from './logger.ts';
 export * from './logging.ts';
 export * from './models.ts';
+export * from './oauth-profile.ts';
 export * from './pkce.ts';
 export * from './provider.ts';
+export * from './quota-headers.ts';
 export * from './quota-manager.ts';
 export * from './quotas.ts';
 export * from './relay.ts';
 export * from './routing.ts';
+export * from './sticky-routing.ts';

package/dist/index.js

@@ -2,6 +2,7 @@ export * from "./accounts.js";
 export * from "./auth.js";
 export * from "./cache1h.js";
 export * from "./cachekeep.js";
+export * from "./cachekeep-registry.js";
 export * from "./cch.js";
 export * from "./claude-code.js";
 export * from "./commands/account.js";
@@ -12,9 +13,12 @@ export * from "./killswitch.js";
 export * from "./logger.js";
 export * from "./logging.js";
 export * from "./models.js";
+export * from "./oauth-profile.js";
 export * from "./pkce.js";
 export * from "./provider.js";
+export * from "./quota-headers.js";
 export * from "./quota-manager.js";
 export * from "./quotas.js";
 export * from "./relay.js";
 export * from "./routing.js";
+export * from "./sticky-routing.js";

package/dist/oauth-profile.d.ts

@@ -0,0 +1,11 @@
+import type { OAuthAccountProfile } from './accounts.ts';
+export declare const PROFILE_TTL_MS: number;
+export declare function fetchOAuthAccountProfile(input: {
+    accessToken: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    signal?: AbortSignal;
+}): Promise<OAuthAccountProfile>;
+export declare function oauthProfileMatchesToken(profile: OAuthAccountProfile | undefined, accessToken: string): boolean;
+export declare function oauthProfileIsFresh(profile: OAuthAccountProfile | undefined, now?: number): boolean;
+export declare function formatOAuthAccountTier(profile: OAuthAccountProfile | undefined): string | undefined;

package/dist/oauth-profile.js

@@ -0,0 +1,48 @@
+import { tokenFingerprint } from "./quota-manager.js";
+const PROFILE_URL = 'https://api.anthropic.com/api/oauth/profile';
+export const PROFILE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export async function fetchOAuthAccountProfile(input) {
+    const response = await (input.fetchImpl ?? fetch)(PROFILE_URL, {
+        method: 'GET',
+        signal: input.signal,
+        headers: {
+            Authorization: `Bearer ${input.accessToken}`,
+            Accept: 'application/json',
+            'anthropic-beta': 'oauth-2025-04-20',
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Claude profile check failed: ${response.status}`);
+    }
+    const value = (await response.json());
+    const tier = value.organization?.rate_limit_tier;
+    const orgType = value.organization?.organization_type;
+    if (typeof tier !== 'string' ||
+        tier.trim() === '' ||
+        typeof orgType !== 'string' ||
+        orgType.trim() === '') {
+        throw new Error('Claude profile response is missing account metadata');
+    }
+    return {
+        tier,
+        orgType,
+        checkedAt: input.now?.() ?? Date.now(),
+        tokenFingerprint: tokenFingerprint(input.accessToken),
+    };
+}
+export function oauthProfileMatchesToken(profile, accessToken) {
+    return profile?.tokenFingerprint === tokenFingerprint(accessToken);
+}
+export function oauthProfileIsFresh(profile, now = Date.now()) {
+    return Boolean(profile &&
+        Number.isFinite(profile.checkedAt) &&
+        now >= profile.checkedAt &&
+        now - profile.checkedAt < PROFILE_TTL_MS);
+}
+export function formatOAuthAccountTier(profile) {
+    const match = profile?.tier.match(/^default_claude_max_(\d+)x$/);
+    if (!match)
+        return undefined;
+    const label = `Max ${match[1]}x`;
+    return profile?.orgType === 'claude_team' ? `Team · ${label}` : label;
+}

package/dist/quota-headers.d.ts

@@ -0,0 +1,4 @@
+import type { OAuthQuotaSnapshot } from './accounts.ts';
+export declare function isQuotaBearingHeaderFrame(headers: Headers): boolean;
+export declare function normalizeQuotaHeaders(headers: Headers, now?: number): OAuthQuotaSnapshot;
+export declare function mergeHeaderQuotaSnapshot(existing: OAuthQuotaSnapshot | undefined, incoming: OAuthQuotaSnapshot): OAuthQuotaSnapshot;

package/dist/quota-headers.js

@@ -0,0 +1,66 @@
+const PREFIX = 'anthropic-ratelimit-unified-';
+const WINDOW_KEYS = {
+    '5h': 'five_hour',
+    '7d': 'seven_day',
+};
+export function isQuotaBearingHeaderFrame(headers) {
+    return Object.keys(WINDOW_KEYS).some((suffix) => Number.isFinite(finiteHeaderNumber(headers, `${PREFIX}${suffix}-utilization`)));
+}
+function finiteHeaderNumber(headers, name) {
+    const value = headers.get(name);
+    if (value == null || value.trim() === '')
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function normalizeWindow(headers, suffix, checkedAt) {
+    const utilization = finiteHeaderNumber(headers, `${PREFIX}${suffix}-utilization`);
+    if (utilization == null)
+        return undefined;
+    const usedPercent = Math.min(100, Math.max(0, Math.round(utilization * 100)));
+    const resetSeconds = finiteHeaderNumber(headers, `${PREFIX}${suffix}-reset`);
+    const resetDate = resetSeconds == null ? undefined : new Date(resetSeconds * 1000);
+    const resetsAt = resetDate && Number.isFinite(resetDate.getTime())
+        ? resetDate.toISOString()
+        : undefined;
+    return {
+        usedPercent,
+        remainingPercent: 100 - usedPercent,
+        ...(resetsAt && { resetsAt }),
+        checkedAt,
+    };
+}
+export function normalizeQuotaHeaders(headers, now = Date.now()) {
+    const snapshot = {
+        fallbackAdvised: headers.get(`${PREFIX}fallback`) === 'available',
+        source: 'headers',
+        checkedAt: now,
+    };
+    for (const [suffix, key] of Object.entries(WINDOW_KEYS)) {
+        const window = normalizeWindow(headers, suffix, now);
+        if (window)
+            snapshot[key] = window;
+    }
+    const representativeClaim = headers.get(`${PREFIX}representative-claim`);
+    if (representativeClaim) {
+        snapshot.bindingWindow = representativeClaim;
+        snapshot.bindingWindowSource = 'headers';
+    }
+    return snapshot;
+}
+export function mergeHeaderQuotaSnapshot(existing, incoming) {
+    return {
+        ...existing,
+        ...incoming,
+        scoped: existing && 'scoped' in existing ? existing.scoped : undefined,
+        extraUsage: existing?.extraUsage,
+        bindingWindow: existing?.bindingWindowSource === 'poll'
+            ? existing.bindingWindow
+            : (incoming.bindingWindow ?? existing?.bindingWindow),
+        bindingWindowSource: existing?.bindingWindowSource === 'poll'
+            ? 'poll'
+            : (incoming.bindingWindowSource ?? existing?.bindingWindowSource),
+        // Source tracks 5h/7d freshness; preserved scoped and credit fields remain poll-owned.
+        source: 'headers',
+    };
+}

package/dist/quota-manager.d.ts

@@ -6,12 +6,7 @@
  * Handles deduplication, rate-limiting (429 backoff), and staleness.
  */
 import type { AccountOperationError, AccountStorage, OAuthAccount, OAuthQuotaSnapshot } from './accounts.ts';
-/**
- * Stable, non-reversible fingerprint of an access token. Used to detect a
- * main-account switch so a different account's persisted/cached quota is never
- * reused. Not a secret — a truncated SHA-256, safe to persist alongside quota.
- */
-export declare function tokenFingerprint(token: string): string;
+export { tokenFingerprint } from './token-fingerprint.ts';
 export type QuotaEntry = {
     quota: OAuthQuotaSnapshot;
     refreshAfter: number;
@@ -60,6 +55,8 @@ export declare class QuotaManager {
     getAllFallbacks(): Map<string, QuotaEntry>;
     setMain(accessToken: string, entry: QuotaEntry): void;
     setFallback(accountId: string, entry: QuotaEntry, accessToken?: string): void;
+    pushMainFromHeaders(accessToken: string, incoming: OAuthQuotaSnapshot): QuotaEntry;
+    pushFallbackFromHeaders(accountId: string, accessToken: string, incoming: OAuthQuotaSnapshot): QuotaEntry;
     refreshMain(accessToken: string): Promise<OAuthQuotaSnapshot>;
     refreshFallback(accountId: string, accessToken: string): Promise<OAuthQuotaSnapshot>;
     refreshAllFallbacks(accounts: OAuthAccount[]): Promise<void>;
@@ -67,14 +64,15 @@ export declare class QuotaManager {
      * Fire-and-forget refresh. Does not await, swallows errors.
      */
     refreshMainInBackground(accessToken: string): void;
-    isMainStale(): boolean;
-    isFallbackStale(accountId: string, accessToken?: string): boolean;
+    private scopedWindowIsStale;
+    isMainStale(modelId?: string): boolean;
+    isFallbackStale(accountId: string, accessToken?: string, modelId?: string): boolean;
     shouldRefreshOnRequestCount(requestCount: number): boolean;
     /**
      * Combined check: should a refresh happen right now?
      * True if main is stale by time OR triggered by request count.
      */
-    needsRefresh(requestCount: number): boolean;
+    needsRefresh(requestCount: number, modelId?: string): boolean;
     updateStorage(storage: AccountStorage | null): void;
     /**
      * Seed/update the main quota cache from persisted state. This is deliberately

package/dist/quota-manager.js

@@ -5,17 +5,32 @@
  * share one QuotaManager instance so they see the same in-memory cache.
  * Handles deduplication, rate-limiting (429 backoff), and staleness.
  */
-import { createHash } from 'node:crypto';
-import { acquireRefreshFileLock, buildQuotaOperationError, fetchOAuthQuotaSnapshot, getPersistedMainQuota, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getQuotaRefreshEveryNRequests, isQuotaPolicyAuthError, quotaBackoffActive, } from "./accounts.js";
+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";
 // Capture real setTimeout before tests can mock globalThis.setTimeout
 const nativeSetTimeout = globalThis.setTimeout;
-/**
- * Stable, non-reversible fingerprint of an access token. Used to detect a
- * main-account switch so a different account's persisted/cached quota is never
- * reused. Not a secret — a truncated SHA-256, safe to persist alongside quota.
- */
-export function tokenFingerprint(token) {
-    return createHash('sha256').update(token).digest('hex').slice(0, 16);
+function mergePollCompletionWithNewerHeaders(current, polled) {
+    if (current?.source !== 'headers')
+        return polled;
+    const fiveHourIsNewer = Boolean(current.five_hour &&
+        current.five_hour.checkedAt > (polled.five_hour?.checkedAt ?? 0));
+    const sevenDayIsNewer = Boolean(current.seven_day &&
+        current.seven_day.checkedAt > (polled.seven_day?.checkedAt ?? 0));
+    if (!fiveHourIsNewer && !sevenDayIsNewer)
+        return polled;
+    return mergeHeaderQuotaSnapshot(polled, {
+        ...(fiveHourIsNewer && { five_hour: current.five_hour }),
+        ...(sevenDayIsNewer && { seven_day: current.seven_day }),
+        fallbackAdvised: current.fallbackAdvised,
+        ...(current.bindingWindowSource === 'headers' && {
+            bindingWindow: current.bindingWindow,
+            bindingWindowSource: current.bindingWindowSource,
+        }),
+        source: 'headers',
+        checkedAt: Math.max(fiveHourIsNewer ? (current.five_hour?.checkedAt ?? 0) : 0, sevenDayIsNewer ? (current.seven_day?.checkedAt ?? 0) : 0),
+    });
 }
 // ---------------------------------------------------------------------------
 // Class
@@ -116,6 +131,29 @@ export class QuotaManager {
             this.fallbackTokenFps.delete(accountId);
         }
     }
+    pushMainFromHeaders(accessToken, incoming) {
+        const checkedAt = incoming.checkedAt ?? this.now();
+        const accessTokenFp = tokenFingerprint(accessToken);
+        const quota = mergeHeaderQuotaSnapshot(this.mainTokenFp === accessTokenFp ? this.main?.quota : undefined, incoming);
+        const entry = {
+            quota,
+            checkedAt,
+            refreshAfter: getQuotaNextRefreshAt(quota, this.storage, checkedAt),
+        };
+        this.setMain(accessToken, entry);
+        return entry;
+    }
+    pushFallbackFromHeaders(accountId, accessToken, incoming) {
+        const checkedAt = incoming.checkedAt ?? this.now();
+        const quota = mergeHeaderQuotaSnapshot(this.getFallback(accountId, accessToken)?.quota, incoming);
+        const entry = {
+            quota,
+            checkedAt,
+            refreshAfter: getQuotaNextRefreshAt(quota, this.storage, checkedAt),
+        };
+        this.setFallback(accountId, entry, accessToken);
+        return entry;
+    }
     // =========================================================================
     // Refresh (async, deduplicated, rate-limited)
     // =========================================================================
@@ -190,17 +228,24 @@ export class QuotaManager {
     // =========================================================================
     // Staleness queries
     // =========================================================================
-    isMainStale() {
+    scopedWindowIsStale(entry, modelId) {
+        const scoped = getScopedQuotaWindowForModel(entry.quota, modelId);
+        return Boolean(scoped &&
+            this.now() - scoped.checkedAt >= getQuotaCheckIntervalMs(this.storage));
+    }
+    isMainStale(modelId) {
         if (!this.main)
             return true;
-        return this.now() >= this.main.refreshAfter;
+        return (this.now() >= this.main.refreshAfter ||
+            this.scopedWindowIsStale(this.main, modelId));
     }
-    isFallbackStale(accountId, accessToken) {
+    isFallbackStale(accountId, accessToken, modelId) {
         // Token-aware: a credential change invalidates the entry (treated as stale).
         const entry = this.getFallback(accountId, accessToken);
         if (!entry)
             return true;
-        return this.now() >= entry.refreshAfter;
+        return (this.now() >= entry.refreshAfter ||
+            this.scopedWindowIsStale(entry, modelId));
     }
     shouldRefreshOnRequestCount(requestCount) {
         const everyN = getQuotaRefreshEveryNRequests(this.storage);
@@ -212,8 +257,9 @@ export class QuotaManager {
      * Combined check: should a refresh happen right now?
      * True if main is stale by time OR triggered by request count.
      */
-    needsRefresh(requestCount) {
-        return this.isMainStale() || this.shouldRefreshOnRequestCount(requestCount);
+    needsRefresh(requestCount, modelId) {
+        return (this.isMainStale(modelId) ||
+            this.shouldRefreshOnRequestCount(requestCount));
     }
     // =========================================================================
     // Config
@@ -372,15 +418,16 @@ 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);
                     this.main = {
-                        quota,
-                        refreshAfter: getQuotaNextRefreshAt(quota, this.storage, now),
-                        checkedAt: now,
+                        quota: completedQuota,
+                        refreshAfter: getQuotaNextRefreshAt(completedQuota, this.storage, now),
+                        checkedAt: completedQuota.checkedAt ?? now,
                     };
                     this.mainLastApiError = undefined;
-                    this.onMainQuotaFetched?.(quota, now, this.mainTokenFp, fetchStartedAt);
-                    return quota;
+                    this.onMainQuotaFetched?.(completedQuota, now, this.mainTokenFp, fetchStartedAt);
+                    return completedQuota;
                 }
                 catch (error) {
                     this._handleMainFetchError(error);
@@ -425,14 +472,15 @@ export class QuotaManager {
                         now: this.now,
                     });
                     const now = this.now();
+                    const completedQuota = mergePollCompletionWithNewerHeaders(this.getFallback(accountId, accessToken)?.quota, quota);
                     this.setFallback(accountId, {
-                        quota,
-                        refreshAfter: now + getQuotaCheckIntervalMs(this.storage),
-                        checkedAt: now,
+                        quota: completedQuota,
+                        refreshAfter: getQuotaNextRefreshAt(completedQuota, this.storage, now),
+                        checkedAt: completedQuota.checkedAt ?? now,
                     }, accessToken);
                     this.fallbackApiErrors.delete(accountId);
                     this.fallbackErrorTokenFps.delete(accountId);
-                    return quota;
+                    return completedQuota;
                 }
                 finally {
                     await fileLock.release();

package/dist/quotas.d.ts

@@ -1,4 +1,4 @@
-import type { AccountStorage, OAuthQuotaSnapshot } from './accounts.ts';
+import type { AccountStorage, OAuthQuotaSnapshot, QuotaMoney } from './accounts.ts';
 export declare const CLAUDE_QUOTAS_COMMAND_NAME = "claude-quota";
 export type QuotaAccountSummary = {
     name: string;
@@ -7,14 +7,17 @@ export type QuotaAccountSummary = {
     quota?: OAuthQuotaSnapshot;
     lastRefreshedAt?: number;
     error?: string;
+    tierLabel?: string;
 };
+export declare function formatQuotaMoney(money: QuotaMoney): string;
 export declare function buildFallbackQuotaSummaries(storage: AccountStorage | null, errors?: ReadonlyMap<string, string>): {
     error?: string | undefined;
+    lastRefreshedAt: number | undefined;
+    tierLabel?: string | undefined;
     name: string;
     role: "fallback";
     enabled: boolean;
     quota: OAuthQuotaSnapshot | undefined;
-    lastRefreshedAt: number | undefined;
 }[];
 export declare function buildClaudeQuotaSummary(input: {
     accounts: QuotaAccountSummary[];