sidekick-shared 0.28.2 → 0.28.3

package/dist/esm/quota.js

@@ -18,6 +18,126 @@ export function classifyQuotaFreshness(ageMs) {
         return 'aging';
     return 'stale';
 }
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+/** Whether the provider reports this window for the account at all. */
+export function quotaWindowApplies(window) {
+    return Boolean(window) && window?.absent !== true;
+}
+/** Whether the window applies and carries a reading worth showing (a reset time or any usage). */
+export function quotaWindowHasData(window) {
+    if (!window || window.absent === true)
+        return false;
+    return Boolean(window.resetsAt) || window.utilization > 0;
+}
+function usableWindowMs(windowMs) {
+    return typeof windowMs === 'number' && Number.isFinite(windowMs) && windowMs > 0
+        ? windowMs
+        : undefined;
+}
+/**
+ * True when every window of a sample that has a known reset time has already
+ * reset by `nowMs`. Such a sample says nothing about current usage — showing
+ * it as live would print old percentages with "resets now". Samples without
+ * any reset time are never considered expired.
+ */
+export function quotaSampleExpired(quota, nowMs = Date.now()) {
+    const resets = [quota.fiveHour, quota.sevenDay]
+        .filter((window) => !window.absent && window.resetsAt)
+        .map((window) => Date.parse(window.resetsAt))
+        .filter((ms) => Number.isFinite(ms));
+    return resets.length > 0 && resets.every((ms) => ms <= nowMs);
+}
+/**
+ * Human label for a window length: `5-Hour`, `Daily`, `Weekly`, `30-Day`, …
+ * Returns `fallback` when the length is unknown or not a whole number of hours.
+ */
+export function quotaWindowLabel(windowMs, fallback) {
+    const ms = usableWindowMs(windowMs);
+    if (ms === undefined)
+        return fallback;
+    if (ms === DAY_MS)
+        return 'Daily';
+    if (ms === 7 * DAY_MS)
+        return 'Weekly';
+    if (ms % DAY_MS === 0)
+        return `${ms / DAY_MS}-Day`;
+    if (ms % HOUR_MS === 0)
+        return `${ms / HOUR_MS}-Hour`;
+    return fallback;
+}
+/** Compact label for a window length: `5h`, `1d`, `7d`. Returns `fallback` when unknown. */
+export function quotaWindowShortLabel(windowMs, fallback) {
+    const ms = usableWindowMs(windowMs);
+    if (ms === undefined)
+        return fallback;
+    if (ms % DAY_MS === 0)
+        return `${ms / DAY_MS}d`;
+    if (ms % HOUR_MS === 0)
+        return `${ms / HOUR_MS}h`;
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    return fallback;
+}
+/**
+ * The reported meters that `fiveHour` and `sevenDay` do not already show —
+ * per-model or per-surface weekly caps and any future meter kind.
+ */
+export function extraQuotaRows(quota) {
+    return (quota.limits ?? []).filter((row) => row.kind !== 'session' && row.kind !== 'weekly_all');
+}
+/**
+ * Display name for a Claude subscription. The 20× tier was renamed Ultra and
+ * the 5× tier Max on 2026-10-30; credentials keep the old tier ids.
+ */
+export function claudePlanLabel(plan) {
+    const tier = plan?.rateLimitTier?.trim().toLowerCase() ?? '';
+    if (tier.includes('ultra') || tier.includes('max_20x'))
+        return 'Ultra';
+    if (tier.includes('max_5x'))
+        return 'Max';
+    const subscription = plan?.subscriptionType?.trim().toLowerCase();
+    if (!subscription)
+        return undefined;
+    return subscription.charAt(0).toUpperCase() + subscription.slice(1);
+}
+function formatMinorUnits(amount, currency, decimals) {
+    const value = amount / 10 ** decimals;
+    if (currency) {
+        try {
+            return new Intl.NumberFormat('en-US', {
+                style: 'currency',
+                currency,
+                minimumFractionDigits: decimals,
+                maximumFractionDigits: decimals,
+            }).format(value);
+        }
+        catch {
+            return `${value.toFixed(decimals)} ${currency}`;
+        }
+    }
+    return value.toFixed(decimals);
+}
+/**
+ * One-line extra-usage summary, e.g. `$12.40 of $200.00 used` or
+ * `$0.00 of $200.00 used · off (out of credits)`.
+ */
+export function formatExtraUsage(extra) {
+    const decimals = typeof extra.decimalPlaces === 'number' &&
+        Number.isInteger(extra.decimalPlaces) &&
+        extra.decimalPlaces >= 0 &&
+        extra.decimalPlaces <= 6
+        ? extra.decimalPlaces
+        : 2;
+    const used = formatMinorUnits(extra.usedCredits ?? 0, extra.currency, decimals);
+    const amount = extra.monthlyLimit !== null
+        ? `${used} of ${formatMinorUnits(extra.monthlyLimit, extra.currency, decimals)} used`
+        : `${used} used`;
+    if (extra.enabled)
+        return amount;
+    const reason = extra.disabledReason ? ` (${extra.disabledReason.replace(/_/g, ' ')})` : '';
+    return `${amount} · off${reason}`;
+}
 /** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
 export function formatQuotaAge(ageMs) {
     if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
@@ -56,21 +176,21 @@ export function withQuotaProjections(state, options = {}) {
         return state;
     const next = { ...state };
     const capturedAt = options.capturedAt ?? state.capturedAt;
-    if (next.projectedFiveHour == null) {
+    if (next.projectedFiveHour == null && !next.fiveHour.absent) {
         const projected = projectQuotaWindow({
             utilization: next.fiveHour.utilization,
             resetsAt: next.fiveHour.resetsAt,
-            windowMs: options.fiveHourWindowMs ?? FIVE_HOUR_WINDOW_MS,
+            windowMs: options.fiveHourWindowMs ?? usableWindowMs(next.fiveHour.windowMs) ?? FIVE_HOUR_WINDOW_MS,
             capturedAt,
         });
         if (projected !== undefined)
             next.projectedFiveHour = projected;
     }
-    if (next.projectedSevenDay == null) {
+    if (next.projectedSevenDay == null && !next.sevenDay.absent) {
         const projected = projectQuotaWindow({
             utilization: next.sevenDay.utilization,
             resetsAt: next.sevenDay.resetsAt,
-            windowMs: options.sevenDayWindowMs ?? SEVEN_DAY_WINDOW_MS,
+            windowMs: options.sevenDayWindowMs ?? usableWindowMs(next.sevenDay.windowMs) ?? SEVEN_DAY_WINDOW_MS,
             capturedAt,
         });
         if (projected !== undefined)
@@ -78,6 +198,235 @@ export function withQuotaProjections(state, options = {}) {
     }
     return next;
 }
+// ── Claude usage endpoint payload ──
+/** Hard cap on parsed meter rows, matching Claude Code's own bound. */
+const MAX_LIMIT_ROWS = 64;
+const MAX_LABEL_LENGTH = 128;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nullableFiniteNumber(value) {
+    return finiteNumber(value) ?? null;
+}
+function shortString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed && trimmed.length <= MAX_LABEL_LENGTH ? trimmed : undefined;
+}
+function displayName(value) {
+    return isRecord(value) ? shortString(value.display_name) : undefined;
+}
+function usageWindow(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        utilization: finiteNumber(value.utilization) ?? 0,
+        resetsAt: typeof value.resets_at === 'string' ? value.resets_at : '',
+    };
+}
+function absentWindow() {
+    return { utilization: 0, resetsAt: '', absent: true };
+}
+function windowMsForMeter(kind, group) {
+    if (kind === 'session' || group === 'session')
+        return FIVE_HOUR_WINDOW_MS;
+    if (group === 'weekly' || kind.startsWith('weekly'))
+        return SEVEN_DAY_WINDOW_MS;
+    if (group === 'daily')
+        return DAY_MS;
+    return undefined;
+}
+function titleCase(value) {
+    return value
+        .split(/[_\s-]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+function meterLabel(kind, group, scope) {
+    let base;
+    if (kind === 'session' || group === 'session')
+        base = '5-Hour';
+    else if (group === 'weekly' || kind.startsWith('weekly'))
+        base = '7-Day';
+    else if (group === 'daily')
+        base = 'Daily';
+    else
+        base = titleCase(group || kind) || kind;
+    return scope ? `${base} (${scope})` : base;
+}
+function weeklySharesByIndex(value) {
+    const shares = new Map();
+    if (!Array.isArray(value))
+        return shares;
+    for (const entry of value.slice(0, MAX_LIMIT_ROWS)) {
+        if (!isRecord(entry))
+            continue;
+        const index = finiteNumber(entry.limit_index);
+        if (index === undefined || !Number.isInteger(index) || index < 0)
+            continue;
+        shares.set(index, {
+            allowance: finiteNumber(entry.allowance_percent_of_weekly),
+            used: finiteNumber(entry.used_percent_of_weekly),
+        });
+    }
+    return shares;
+}
+function buildMeterRow(input, capturedAt) {
+    const windowMs = windowMsForMeter(input.kind, input.group);
+    const projected = windowMs !== undefined
+        ? projectQuotaWindow({
+            utilization: input.utilization,
+            resetsAt: input.resetsAt,
+            windowMs,
+            capturedAt,
+        })
+        : undefined;
+    return {
+        kind: input.kind,
+        group: input.group,
+        label: meterLabel(input.kind, input.group, input.scopeModel ?? input.scopeSurface),
+        utilization: input.utilization,
+        resetsAt: input.resetsAt,
+        ...(windowMs !== undefined ? { windowMs } : {}),
+        ...(projected !== undefined ? { projected } : {}),
+        ...(input.scopeModel ? { scopeModel: input.scopeModel } : {}),
+        ...(input.scopeSurface ? { scopeSurface: input.scopeSurface } : {}),
+        ...(input.severity ? { severity: input.severity } : {}),
+        ...(input.isActive !== undefined ? { isActive: input.isActive } : {}),
+        ...(input.share?.allowance !== undefined
+            ? { allowancePercentOfWeekly: input.share.allowance }
+            : {}),
+        ...(input.share?.used !== undefined ? { usedPercentOfWeekly: input.share.used } : {}),
+    };
+}
+function parseLimitRows(value, sharesValue, capturedAt) {
+    if (!Array.isArray(value))
+        return undefined;
+    const shares = weeklySharesByIndex(sharesValue);
+    const rows = [];
+    value.slice(0, MAX_LIMIT_ROWS).forEach((raw, index) => {
+        if (!isRecord(raw))
+            return;
+        const kind = shortString(raw.kind);
+        const percent = finiteNumber(raw.percent);
+        if (!kind || percent === undefined)
+            return;
+        const scope = isRecord(raw.scope) ? raw.scope : undefined;
+        rows.push(buildMeterRow({
+            kind,
+            group: shortString(raw.group) ?? '',
+            utilization: Math.max(0, percent),
+            resetsAt: typeof raw.resets_at === 'string' ? raw.resets_at : '',
+            scopeModel: displayName(scope?.model),
+            scopeSurface: displayName(scope?.surface),
+            severity: shortString(raw.severity),
+            isActive: typeof raw.is_active === 'boolean' ? raw.is_active : undefined,
+            share: shares.get(index),
+        }, capturedAt));
+    });
+    return rows;
+}
+/** Pre-`limits[]` per-model weekly fields, read only when the server sends no `limits[]`. */
+const LEGACY_SCOPED_WEEKLY_FIELDS = [
+    ['seven_day_opus', 'Opus'],
+    ['seven_day_sonnet', 'Sonnet'],
+    ['seven_day_overage_included', 'Fable'],
+];
+function legacyScopedRows(data, capturedAt) {
+    const rows = [];
+    for (const [field, model] of LEGACY_SCOPED_WEEKLY_FIELDS) {
+        const window = usageWindow(data[field]);
+        if (!window)
+            continue;
+        rows.push(buildMeterRow({
+            kind: 'weekly_scoped',
+            group: 'weekly',
+            utilization: window.utilization,
+            resetsAt: window.resetsAt,
+            scopeModel: model,
+        }, capturedAt));
+    }
+    return rows;
+}
+function parseExtraUsage(value) {
+    if (!isRecord(value) || typeof value.is_enabled !== 'boolean')
+        return undefined;
+    const decimalPlaces = finiteNumber(value.decimal_places);
+    return {
+        enabled: value.is_enabled,
+        monthlyLimit: nullableFiniteNumber(value.monthly_limit),
+        usedCredits: nullableFiniteNumber(value.used_credits),
+        utilization: nullableFiniteNumber(value.utilization),
+        ...(shortString(value.currency) ? { currency: shortString(value.currency) } : {}),
+        ...(decimalPlaces !== undefined ? { decimalPlaces } : {}),
+        ...(shortString(value.disabled_reason)
+            ? { disabledReason: shortString(value.disabled_reason) }
+            : {}),
+    };
+}
+function windowFromMeter(row) {
+    return row ? { utilization: row.utilization, resetsAt: row.resetsAt } : null;
+}
+/**
+ * Normalize a Claude OAuth usage-endpoint body into a `QuotaState`.
+ *
+ * - `five_hour`/`seven_day` that are null or missing become `absent` windows
+ *   (Ultra plans have no five-hour session limit), unless `limits[]` carries
+ *   the matching `session`/`weekly_all` meter.
+ * - `limits[]` is kept verbatim as `limits` (with derived labels, window
+ *   lengths, and projections); older servers' `seven_day_opus` /
+ *   `seven_day_sonnet` / `seven_day_overage_included` fill it instead.
+ * - `extra_usage` becomes `extraUsage`.
+ *
+ * Bodies in the original two-window shape produce exactly the state they did
+ * before these fields existed.
+ */
+export function quotaStateFromClaudeUsagePayload(payload, options = {}) {
+    const data = isRecord(payload) ? payload : {};
+    const capturedAt = options.capturedAt;
+    const parsedLimits = parseLimitRows(data.limits, data.weekly_scoped_shares, capturedAt);
+    const legacyRows = parsedLimits === undefined ? legacyScopedRows(data, capturedAt) : [];
+    const limits = parsedLimits ?? (legacyRows.length > 0 ? legacyRows : undefined);
+    const fiveHour = usageWindow(data.five_hour) ??
+        windowFromMeter(parsedLimits?.find((row) => row.kind === 'session')) ??
+        absentWindow();
+    const sevenDay = usageWindow(data.seven_day) ??
+        windowFromMeter(parsedLimits?.find((row) => row.kind === 'weekly_all')) ??
+        absentWindow();
+    const extraUsage = parseExtraUsage(data.extra_usage);
+    const projectedFiveHour = fiveHour.absent
+        ? undefined
+        : projectQuotaWindow({ ...fiveHour, windowMs: FIVE_HOUR_WINDOW_MS, capturedAt });
+    const projectedSevenDay = sevenDay.absent
+        ? undefined
+        : projectQuotaWindow({ ...sevenDay, windowMs: SEVEN_DAY_WINDOW_MS, capturedAt });
+    return {
+        fiveHour,
+        sevenDay,
+        available: true,
+        projectedFiveHour,
+        projectedSevenDay,
+        ...(limits ? { limits } : {}),
+        ...(extraUsage ? { extraUsage } : {}),
+    };
+}
+/** Stamp `planType` / `planLabel` from Claude credential plan facts (no-op without them). */
+export function withClaudePlan(state, plan) {
+    const planLabel = claudePlanLabel(plan);
+    const planType = plan?.subscriptionType?.trim() || undefined;
+    if (!planLabel && !planType)
+        return state;
+    return {
+        ...state,
+        ...(planType ? { planType } : {}),
+        ...(planLabel ? { planLabel } : {}),
+    };
+}
 /**
  * Helper to build an unavailable QuotaState.
  */
@@ -110,6 +459,7 @@ function parseRetryAfterMs(retryAfter) {
  *
  * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
  * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
+ * @param options.plan - Plan facts from the same credentials; stamps `planType` and `planLabel`
  * @returns QuotaState with utilization data and elapsed-time projections
  */
 export async function fetchQuota(accessToken, options = {}) {
@@ -152,26 +502,8 @@ export async function fetchQuota(accessToken, options = {}) {
                 httpStatus: res.status,
             });
         }
-        const data = await res.json();
-        const fiveUtil = data.five_hour?.utilization ?? 0;
-        const sevenUtil = data.seven_day?.utilization ?? 0;
-        const fiveResetsAt = data.five_hour?.resets_at ?? '';
-        const sevenResetsAt = data.seven_day?.resets_at ?? '';
-        return {
-            fiveHour: { utilization: fiveUtil, resetsAt: fiveResetsAt },
-            sevenDay: { utilization: sevenUtil, resetsAt: sevenResetsAt },
-            available: true,
-            projectedFiveHour: projectQuotaWindow({
-                utilization: fiveUtil,
-                resetsAt: fiveResetsAt,
-                windowMs: FIVE_HOUR_WINDOW_MS,
-            }),
-            projectedSevenDay: projectQuotaWindow({
-                utilization: sevenUtil,
-                resetsAt: sevenResetsAt,
-                windowMs: SEVEN_DAY_WINDOW_MS,
-            }),
-        };
+        const state = quotaStateFromClaudeUsagePayload(await res.json());
+        return withClaudePlan(state, options.plan);
     }
     catch {
         return unavailableState('Network error', { failureKind: 'network' });

package/dist/esm/quotaHistory.js

@@ -159,11 +159,26 @@ function pruneFileSync(filePath, retentionDays) {
     }
     return { kept: keptLines.length, pruned };
 }
+function historyWindowToQuota(window) {
+    return {
+        utilization: window.utilization,
+        resetsAt: window.resetsAt,
+        ...(window.absent ? { absent: true } : {}),
+    };
+}
+/**
+ * Project a quota window onto the history-sample shape, keeping the `absent`
+ * marker so summaries and the derived snapshot do not mistake "no such
+ * window" for "0% used".
+ */
+export function quotaHistoryWindow(window) {
+    return historyWindowToQuota(window);
+}
 function sampleToQuotaState(sample) {
     const providerId = runtimeProviderToSnapshotProvider(sample.runtimeProvider);
     return {
-        fiveHour: { utilization: sample.fiveHour.utilization, resetsAt: sample.fiveHour.resetsAt },
-        sevenDay: { utilization: sample.sevenDay.utilization, resetsAt: sample.sevenDay.resetsAt },
+        fiveHour: historyWindowToQuota(sample.fiveHour),
+        sevenDay: historyWindowToQuota(sample.sevenDay),
         available: sample.available,
         error: sample.error,
         providerId,
@@ -329,12 +344,22 @@ export async function readQuotaHistoryDailyBuckets(options) {
             let maxSeven = 0;
             let sumFive = 0;
             let sumSeven = 0;
+            // Averages count only samples where the window exists, so a plan without
+            // a five-hour limit does not drag the five-hour average toward zero.
+            let fiveCount = 0;
+            let sevenCount = 0;
             let anyUnavailable = false;
             for (const s of daySamples) {
-                maxFive = Math.max(maxFive, s.fiveHour.utilization);
-                maxSeven = Math.max(maxSeven, s.sevenDay.utilization);
-                sumFive += s.fiveHour.utilization;
-                sumSeven += s.sevenDay.utilization;
+                if (!s.fiveHour.absent) {
+                    maxFive = Math.max(maxFive, s.fiveHour.utilization);
+                    sumFive += s.fiveHour.utilization;
+                    fiveCount += 1;
+                }
+                if (!s.sevenDay.absent) {
+                    maxSeven = Math.max(maxSeven, s.sevenDay.utilization);
+                    sumSeven += s.sevenDay.utilization;
+                    sevenCount += 1;
+                }
                 if (!s.available)
                     anyUnavailable = true;
             }
@@ -344,8 +369,8 @@ export async function readQuotaHistoryDailyBuckets(options) {
                 samples: n,
                 maxUtilizationFiveHour: maxFive,
                 maxUtilizationSevenDay: maxSeven,
-                avgUtilizationFiveHour: Math.round((sumFive / n) * 100) / 100,
-                avgUtilizationSevenDay: Math.round((sumSeven / n) * 100) / 100,
+                avgUtilizationFiveHour: fiveCount ? Math.round((sumFive / fiveCount) * 100) / 100 : 0,
+                avgUtilizationSevenDay: sevenCount ? Math.round((sumSeven / sevenCount) * 100) / 100 : 0,
                 anyUnavailable,
             });
         }

package/dist/esm/quotaPoller.js

@@ -125,7 +125,8 @@ export class QuotaPoller {
                 this.dormant = true;
                 return;
             }
-            const token = await this.getAccessToken();
+            const credentials = await this.getAccessToken();
+            const token = typeof credentials === 'string' ? credentials : credentials?.accessToken;
             if (!token) {
                 if (this.hasAccount) {
                     // The account exists but its token was unreadable (locked keychain,
@@ -141,7 +142,9 @@ export class QuotaPoller {
                 }
                 return;
             }
-            const state = await fetchQuota(token);
+            const state = await fetchQuota(token, {
+                plan: typeof credentials === 'object' && credentials !== null ? credentials : null,
+            });
             if (state.available) {
                 this.latest = state;
                 this.consecutiveFailures = 0;

package/dist/esm/quotaResolver.js

@@ -23,7 +23,7 @@ import { resolveActiveClaudeAccount } from './accounts';
 import { getActiveCodexAccount, resolveActiveCodexAccount } from './codexProfiles';
 import { enrichCodexQuota, fetchCodexQuotaFromApi, resolveCodexQuotaFromLocalSources, } from './codexQuota';
 import { readClaudeMaxCredentials } from './credentials';
-import { classifyQuotaFreshness, fetchQuota, withQuotaProjections } from './quota';
+import { classifyQuotaFreshness, fetchQuota, formatQuotaAge, quotaSampleExpired, withQuotaProjections, } from './quota';
 import { describeQuotaFailure } from './quotaPresentation';
 import { readQuotaSnapshot, writeQuotaSnapshot } from './quotaSnapshots';
 import { enrichZaiQuota, fetchZaiQuotaFromApi } from './zaiQuotaApi';
@@ -63,9 +63,18 @@ function resolveIdentity(options) {
             return { accountId: options.accountId ?? ZAI_DEFAULT_ACCOUNT_ID, codexAccount: null };
     }
 }
-async function defaultClaudeAccessToken() {
+/** Token plus the plan facts stored beside it (the plan label needs no extra read). */
+async function claudeTokenAndPlan(options) {
+    if (options.getClaudeAccessToken) {
+        return { token: await options.getClaudeAccessToken(), plan: null };
+    }
     const credentials = await readClaudeMaxCredentials();
-    return credentials?.accessToken ?? null;
+    return {
+        token: credentials?.accessToken ?? null,
+        plan: credentials
+            ? { subscriptionType: credentials.subscriptionType, rateLimitTier: credentials.rateLimitTier }
+            : null,
+    };
 }
 function zeroWindows() {
     return { fiveHour: { utilization: 0, resetsAt: '' }, sevenDay: { utilization: 0, resetsAt: '' } };
@@ -84,7 +93,7 @@ function unavailableState(providerId, error, capturedAt) {
 async function fetchFromApi(options, identity, capturedAt) {
     switch (options.providerId) {
         case 'claude-code': {
-            const token = await (options.getClaudeAccessToken ?? defaultClaudeAccessToken)();
+            const { token, plan } = await claudeTokenAndPlan(options);
             if (!token) {
                 return {
                     ...zeroWindows(),
@@ -96,7 +105,7 @@ async function fetchFromApi(options, identity, capturedAt) {
                     capturedAt,
                 };
             }
-            const state = await fetchQuota(token, { fetchImpl: options.fetchImpl });
+            const state = await fetchQuota(token, { fetchImpl: options.fetchImpl, plan });
             return { ...state, providerId: 'claude-code', source: 'api', capturedAt };
         }
         case 'codex':
@@ -178,7 +187,10 @@ export async function resolveQuota(options) {
     const stored = identity.accountId
         ? readSnapshot(snapshotProviderId(providerId), identity.accountId, now)
         : null;
-    const snapshot = stored?.available ? stored : null;
+    // A sample whose every window has reset since says nothing about current
+    // usage; it is reported as expired instead of being shown as live numbers.
+    const storedExpired = Boolean(stored?.available && quotaSampleExpired(stored, now.getTime()));
+    const snapshot = stored?.available && !storedExpired ? stored : null;
     if (preferFresh && snapshot && snapshot.freshness === 'fresh') {
         return finish(snapshot, 'snapshot-fresh');
     }
@@ -224,8 +236,21 @@ export async function resolveQuota(options) {
         const fallback = finish(snapshot, snapshotResolution(snapshot));
         return apiState ? { ...fallback, failure: describeQuotaFailure(apiState) } : fallback;
     }
+    if (storedExpired && stored) {
+        const expired = unavailableState(providerId, expiredSampleMessage(stored, now), capturedAt);
+        return apiState
+            ? { ...finish(expired, 'unavailable'), failure: describeQuotaFailure(apiState) }
+            : finish(expired, 'unavailable');
+    }
     return finish(apiState ??
         unavailableState(providerId, stored
             ? 'The last persisted quota sample was unavailable.'
             : 'No quota data is available yet; run the provider once so a sample can be recorded.', capturedAt), 'unavailable');
 }
+function expiredSampleMessage(stored, now) {
+    const capturedMs = stored.capturedAt ? Date.parse(stored.capturedAt) : NaN;
+    const when = Number.isFinite(capturedMs)
+        ? ` from ${new Date(capturedMs).toISOString().slice(0, 10)} (${formatQuotaAge(now.getTime() - capturedMs)})`
+        : '';
+    return `The last quota sample${when} has expired: every window has reset since. No current data.`;
+}