sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/quotaPoller.js

@@ -0,0 +1,230 @@
+/**
+ * Quota poller with exponential backoff and cached fallback.
+ *
+ * Wraps fetchQuota() with automatic polling, retry logic,
+ * and cached state for transient failures.
+ *
+ * @module quotaPoller
+ */
+import { fetchQuota } from './quota';
+import { onAccountsChanged } from './accountChanges';
+/**
+ * Polls Claude Max quota usage with exponential backoff on transient errors,
+ * cached fallback, and configurable active/idle intervals.
+ *
+ * @example
+ * ```typescript
+ * const poller = new QuotaPoller({
+ *   getAccessToken: async () => readClaudeMaxAccessTokenSync()!,
+ *   activeIntervalMs: 30_000,
+ * });
+ *
+ * poller.onUpdate(state => {
+ *   console.log(`5h: ${state.fiveHour.utilization}%`);
+ * });
+ *
+ * poller.start();
+ * // later...
+ * poller.stop();
+ * ```
+ */
+export class QuotaPoller {
+    activeIntervalMs;
+    idleIntervalMs;
+    maxBackoffMs;
+    getAccessToken;
+    hasAccount;
+    subscribeAccountsChanged;
+    timer = null;
+    listeners = [];
+    latest = null;
+    isActive = false;
+    consecutiveFailures = 0;
+    stopped = false;
+    polling = false;
+    pendingWake = false;
+    dormant = false;
+    accountSubscription = null;
+    constructor(options) {
+        this.activeIntervalMs = options.activeIntervalMs ?? 60_000;
+        this.idleIntervalMs = options.idleIntervalMs ?? 300_000;
+        this.maxBackoffMs = options.maxBackoffMs ?? 120_000;
+        this.getAccessToken = options.getAccessToken;
+        this.hasAccount = options.hasAccount;
+        this.subscribeAccountsChanged = options.subscribeAccountsChanged ?? onAccountsChanged;
+    }
+    /**
+     * Starts polling. First poll is immediate.
+     */
+    start() {
+        this.stopped = false;
+        this.isActive = true;
+        this.accountSubscription ??= this.subscribeAccountsChanged(() => this.wake());
+        this.wake();
+    }
+    /**
+     * Stops polling and clears timers.
+     */
+    stop() {
+        this.stopped = true;
+        this.dormant = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.accountSubscription?.dispose();
+        this.accountSubscription = null;
+    }
+    /**
+     * Switches to active polling interval.
+     */
+    setActive() {
+        this.isActive = true;
+    }
+    /**
+     * Switches to idle polling interval.
+     */
+    setIdle() {
+        this.isActive = false;
+    }
+    /**
+     * Registers a callback for quota state updates.
+     *
+     * @param cb - Called with the latest QuotaState after each successful or cached poll
+     * @returns Disposable to unsubscribe
+     */
+    onUpdate(cb) {
+        this.listeners.push(cb);
+        return {
+            dispose: () => {
+                const idx = this.listeners.indexOf(cb);
+                if (idx >= 0)
+                    this.listeners.splice(idx, 1);
+            },
+        };
+    }
+    /**
+     * Returns the most recent quota state, or null if never fetched.
+     */
+    getLatest() {
+        return this.latest;
+    }
+    async poll() {
+        if (this.stopped)
+            return;
+        if (this.polling) {
+            this.pendingWake = true;
+            return;
+        }
+        this.polling = true;
+        this.pendingWake = false;
+        this.dormant = false;
+        let nextDelayOverride;
+        try {
+            if (this.hasAccount && !(await this.hasAccount())) {
+                this.dormant = true;
+                return;
+            }
+            const token = await this.getAccessToken();
+            if (!token) {
+                if (this.hasAccount) {
+                    // The account exists but its token was unreadable (locked keychain,
+                    // transient credential I/O). That never changes the account
+                    // fingerprint, so no wake would arrive — retry at the idle cadence
+                    // instead of parking forever.
+                    nextDelayOverride = this.idleIntervalMs;
+                }
+                else {
+                    // Without a hasAccount probe, a missing token is the no-account
+                    // signal; the account-change subscription wakes the poller on login.
+                    this.dormant = true;
+                }
+                return;
+            }
+            const state = await fetchQuota(token);
+            if (state.available) {
+                this.latest = state;
+                this.consecutiveFailures = 0;
+                this.notify(state);
+            }
+            else if (state.failureKind === 'auth') {
+                // Keep polling at the idle cadence so signing in again recovers
+                // without an extension/CLI restart.
+                this.latest = state;
+                this.notify(state);
+                this.consecutiveFailures = 0;
+                nextDelayOverride = this.idleIntervalMs;
+                return;
+            }
+            else {
+                // Transient error: increment backoff, use cached state
+                this.consecutiveFailures++;
+                if (this.latest) {
+                    // Serve cached value with the error info attached
+                    const cached = {
+                        ...this.latest,
+                        error: state.error,
+                        failureKind: state.failureKind,
+                    };
+                    this.notify(cached);
+                }
+                else {
+                    this.notify(state);
+                }
+            }
+        }
+        catch (error) {
+            this.consecutiveFailures++;
+            const state = {
+                fiveHour: { utilization: 0, resetsAt: '' },
+                sevenDay: { utilization: 0, resetsAt: '' },
+                available: false,
+                error: error instanceof Error ? error.message : String(error),
+                failureKind: 'auth',
+            };
+            this.latest = state;
+            this.notify(state);
+        }
+        finally {
+            this.polling = false;
+            if (this.pendingWake) {
+                this.pendingWake = false;
+                void this.poll();
+            }
+            else if (!this.dormant) {
+                this.scheduleNext(nextDelayOverride);
+            }
+        }
+    }
+    wake() {
+        if (this.stopped)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.polling) {
+            this.pendingWake = true;
+            return;
+        }
+        void this.poll();
+    }
+    scheduleNext(overrideMs) {
+        if (this.stopped)
+            return;
+        const baseInterval = this.isActive ? this.activeIntervalMs : this.idleIntervalMs;
+        const backoff = Math.min(baseInterval * Math.pow(2, this.consecutiveFailures), Math.max(this.maxBackoffMs, baseInterval));
+        const delay = overrideMs ?? (this.consecutiveFailures > 0 ? backoff : baseInterval);
+        this.timer = setTimeout(() => void this.poll(), delay);
+    }
+    notify(state) {
+        for (const cb of this.listeners) {
+            try {
+                cb(state);
+            }
+            catch {
+                // Listener errors should not break the poller
+            }
+        }
+    }
+}

package/dist/esm/quotaPresentation.js

@@ -0,0 +1,97 @@
+function formatRetryAfter(ms) {
+    if (ms <= 0)
+        return 'now';
+    const totalSeconds = Math.ceil(ms / 1000);
+    const days = Math.floor(totalSeconds / 86_400);
+    const hours = Math.floor((totalSeconds % 86_400) / 3_600);
+    const minutes = Math.floor((totalSeconds % 3_600) / 60);
+    const seconds = totalSeconds % 60;
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0 && days === 0)
+        parts.push(`${minutes}m`);
+    if (parts.length === 0)
+        parts.push(`${seconds}s`);
+    return parts.join(' ');
+}
+export function describeQuotaFailure(quota) {
+    if (!quota || quota.available || !quota.failureKind)
+        return null;
+    const isCodex = quota.providerId === 'codex';
+    const apiName = isCodex ? 'Codex' : 'Anthropic';
+    switch (quota.failureKind) {
+        case 'auth':
+            if (isCodex) {
+                return {
+                    severity: 'error',
+                    title: quota.httpStatus ? 'Codex sign-in expired' : 'Codex sign-in required',
+                    message: quota.error ?? 'The current Codex login could not be used.',
+                    detail: 'Run `codex login` to sign in, then retry quota refresh.',
+                    alertKey: `auth:${quota.httpStatus ?? 'no-credentials'}`,
+                    isRetryable: false,
+                };
+            }
+            if (quota.error === 'No OAuth token available') {
+                return {
+                    severity: 'error',
+                    title: 'Sign in required',
+                    message: 'No Claude Code credentials are available in this environment.',
+                    detail: 'Run `claude` to sign in, then retry quota refresh.',
+                    alertKey: 'auth:no-credentials',
+                    isRetryable: false,
+                };
+            }
+            return {
+                severity: 'error',
+                title: 'Claude Code sign-in expired',
+                message: 'The current Claude Code OAuth session was rejected.',
+                detail: 'Sign in again to refresh subscription quota.',
+                alertKey: `auth:${quota.httpStatus ?? 'unknown'}`,
+                isRetryable: false,
+            };
+        case 'network':
+            return {
+                severity: 'warning',
+                title: 'Quota API unreachable',
+                message: `Could not reach ${apiName} from the current environment.`,
+                detail: 'Check connectivity, proxy, or firewall settings, then retry.',
+                alertKey: 'network',
+                isRetryable: true,
+            };
+        case 'rate_limit':
+            return {
+                severity: 'warning',
+                title: 'Quota API rate limited',
+                message: quota.retryAfterMs != null
+                    ? `Retry in ${formatRetryAfter(quota.retryAfterMs)}.`
+                    : 'Retry shortly.',
+                detail: quota.httpStatus != null ? `${apiName} returned HTTP ${quota.httpStatus}.` : undefined,
+                alertKey: `rate_limit:${quota.httpStatus ?? 429}`,
+                isRetryable: true,
+            };
+        case 'server':
+            return {
+                severity: 'warning',
+                title: 'Quota API unavailable',
+                message: quota.httpStatus != null
+                    ? `${apiName} returned HTTP ${quota.httpStatus}. Try again shortly.`
+                    : `${apiName} quota data is temporarily unavailable.`,
+                alertKey: `server:${quota.httpStatus ?? 'unknown'}`,
+                isRetryable: true,
+            };
+        case 'unknown':
+            return {
+                severity: 'error',
+                title: 'Unexpected quota response',
+                message: quota.httpStatus != null
+                    ? `${apiName} returned HTTP ${quota.httpStatus}.`
+                    : (quota.error ?? 'Quota data could not be retrieved.'),
+                detail: 'This failure is not classified as retryable.',
+                alertKey: `unknown:${quota.httpStatus ?? 'none'}`,
+                isRetryable: false,
+            };
+    }
+}

package/dist/esm/quotaResolver.js

@@ -0,0 +1,231 @@
+/**
+ * One quota resolution path for every Sidekick surface.
+ *
+ * `sidekick quota`, `quota --all`, the MCP facts server, and both dashboards
+ * used to pick between the live API, session logs, and the persisted snapshot
+ * in four different orders. `resolveQuota()` defaults to this precedence:
+ *
+ * 1. a fresh persisted snapshot (younger than `QUOTA_FRESH_MAX_AGE_MS`, whatever
+ *    its origin: the official status-line sample, a session log, or an earlier
+ *    API call) — zero network;
+ * 2. a session-derived sample (Codex rollouts carry rate limits; Claude and
+ *    z.ai have no local equivalent);
+ * 3. the provider API, when `allowApi` is not disabled;
+ * 4. an aging or stale snapshot, labelled as such, with the API failure attached;
+ * 5. an unavailable state describing why nothing could be resolved.
+ *
+ * `preferFresh: false` asks the API first when allowed (the `--refresh` flag
+ * and one-shot Codex queries). On failure, the newer session or persisted
+ * sample wins, with ties going to the persisted sample. Every result carries
+ * `source`, `capturedSource`, `freshness`, `ageMs`, and a `resolution` tag.
+ */
+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 { describeQuotaFailure } from './quotaPresentation';
+import { readQuotaSnapshot, writeQuotaSnapshot } from './quotaSnapshots';
+import { enrichZaiQuota, fetchZaiQuotaFromApi } from './zaiQuotaApi';
+const ZAI_DEFAULT_ACCOUNT_ID = 'default';
+const CLAUDE_NO_CREDENTIALS_ERROR = 'No OAuth token available';
+function snapshotProviderId(providerId) {
+    return providerId;
+}
+function defaultResolveCodexAccount(options) {
+    // Self-heal the saved pointer to the live login first so the snapshot key and
+    // the display identity both track reality after a native `codex login`.
+    resolveActiveCodexAccount(options);
+    return getActiveCodexAccount();
+}
+function resolveIdentity(options) {
+    const selfHeal = options.selfHeal ?? true;
+    switch (options.providerId) {
+        case 'claude-code': {
+            const account = (options.resolveClaudeAccount ?? resolveActiveClaudeAccount)({ selfHeal });
+            return {
+                accountId: options.accountId ?? account.registryAccountId,
+                codexAccount: null,
+                accountLabel: account.label ?? account.email,
+                accountDetail: account.email,
+            };
+        }
+        case 'codex': {
+            const profile = (options.resolveCodexAccount ?? defaultResolveCodexAccount)({ selfHeal });
+            return {
+                accountId: options.accountId ?? profile?.id,
+                codexAccount: profile,
+                accountLabel: profile?.label,
+                accountDetail: profile?.email,
+            };
+        }
+        case 'zai':
+            return { accountId: options.accountId ?? ZAI_DEFAULT_ACCOUNT_ID, codexAccount: null };
+    }
+}
+async function defaultClaudeAccessToken() {
+    const credentials = await readClaudeMaxCredentials();
+    return credentials?.accessToken ?? null;
+}
+function zeroWindows() {
+    return { fiveHour: { utilization: 0, resetsAt: '' }, sevenDay: { utilization: 0, resetsAt: '' } };
+}
+function unavailableState(providerId, error, capturedAt) {
+    return {
+        ...zeroWindows(),
+        available: false,
+        error,
+        failureKind: 'unknown',
+        providerId,
+        capturedAt,
+        ...(providerId === 'codex' ? { fiveHourLabel: 'Primary', sevenDayLabel: 'Secondary' } : {}),
+    };
+}
+async function fetchFromApi(options, identity, capturedAt) {
+    switch (options.providerId) {
+        case 'claude-code': {
+            const token = await (options.getClaudeAccessToken ?? defaultClaudeAccessToken)();
+            if (!token) {
+                return {
+                    ...zeroWindows(),
+                    available: false,
+                    error: CLAUDE_NO_CREDENTIALS_ERROR,
+                    failureKind: 'auth',
+                    providerId: 'claude-code',
+                    source: 'api',
+                    capturedAt,
+                };
+            }
+            const state = await fetchQuota(token, { fetchImpl: options.fetchImpl });
+            return { ...state, providerId: 'claude-code', source: 'api', capturedAt };
+        }
+        case 'codex':
+            return fetchCodexQuotaFromApi({
+                codexHome: options.codexHome,
+                fetchImpl: options.fetchImpl,
+                accessToken: options.codexAccessToken,
+                accountId: identity.codexAccount?.providerAccountId,
+                capturedAt,
+            });
+        case 'zai':
+            return fetchZaiQuotaFromApi({ ...options.zai, fetchImpl: options.fetchImpl, capturedAt });
+    }
+}
+function withAge(state, now) {
+    if (state.ageMs !== undefined && state.freshness !== undefined)
+        return state;
+    const capturedMs = state.capturedAt ? Date.parse(state.capturedAt) : NaN;
+    const ageMs = Number.isFinite(capturedMs) ? Math.max(0, now.getTime() - capturedMs) : undefined;
+    return {
+        ...state,
+        ...(ageMs !== undefined ? { ageMs } : {}),
+        freshness: classifyQuotaFreshness(ageMs),
+    };
+}
+function enrich(providerId, state, identity) {
+    switch (providerId) {
+        case 'claude-code':
+            return {
+                ...withQuotaProjections(state),
+                runtimeProvider: 'claude',
+                providerId: 'claude-code',
+                accountLabel: identity.accountLabel,
+                accountDetail: identity.accountDetail,
+            };
+        case 'codex':
+            return enrichCodexQuota(state, identity.codexAccount);
+        default:
+            return enrichZaiQuota(state);
+    }
+}
+function snapshotResolution(state) {
+    if (state.freshness === 'fresh')
+        return 'snapshot-fresh';
+    if (state.freshness === 'aging')
+        return 'snapshot-aging';
+    return 'snapshot-stale';
+}
+function captureTimeMs(state) {
+    const capturedMs = state.capturedAt ? Date.parse(state.capturedAt) : NaN;
+    return Number.isFinite(capturedMs) ? capturedMs : Number.NEGATIVE_INFINITY;
+}
+/**
+ * Resolve the current quota for one provider with the shared precedence
+ * described at the top of this file.
+ *
+ * The result always has `runtimeProvider`, `resolution`, `freshness`, and
+ * (when a capture time is known) `ageMs`; `failure` describes an API failure
+ * even when older numbers were returned from a snapshot.
+ */
+export async function resolveQuota(options) {
+    const providerId = options.providerId;
+    const now = options.now ?? new Date();
+    const capturedAt = now.toISOString();
+    const preferFresh = options.preferFresh ?? true;
+    const allowApi = options.allowApi ?? true;
+    const apiFirst = !preferFresh && allowApi;
+    const readSnapshot = options.readSnapshot ?? readQuotaSnapshot;
+    const writeSnapshot = options.writeSnapshot ?? writeQuotaSnapshot;
+    const identity = resolveIdentity(options);
+    const finish = (state, resolution) => {
+        const enriched = withAge(enrich(providerId, state, identity), now);
+        return {
+            ...enriched,
+            failure: enriched.failure ?? describeQuotaFailure(enriched),
+            resolution,
+        };
+    };
+    const stored = identity.accountId
+        ? readSnapshot(snapshotProviderId(providerId), identity.accountId, now)
+        : null;
+    const snapshot = stored?.available ? stored : null;
+    if (preferFresh && snapshot && snapshot.freshness === 'fresh') {
+        return finish(snapshot, 'snapshot-fresh');
+    }
+    const readLocalCodex = () => resolveCodexQuotaFromLocalSources({
+        workspacePath: options.workspacePath,
+        provider: options.codexProvider,
+        activeAccount: identity.codexAccount,
+        codexHome: options.codexHome,
+        // Only rollout hits count as "session-derived"; the snapshot fallback is
+        // handled below so it can be labelled by age.
+        readSnapshot: () => null,
+        // Inspect candidates without overwriting the persisted fallback. Only
+        // the selected session sample is written, using the resolved account key.
+        writeSnapshot: () => { },
+    });
+    const finishLocal = (local) => {
+        if (identity.accountId)
+            writeSnapshot('codex', identity.accountId, local);
+        return finish(local, 'session');
+    };
+    if (providerId === 'codex' && !apiFirst) {
+        const local = readLocalCodex();
+        if (local?.available)
+            return finishLocal(local);
+    }
+    let apiState = null;
+    if (allowApi) {
+        apiState = await fetchFromApi(options, identity, capturedAt);
+        if (apiState.available) {
+            if (identity.accountId) {
+                writeSnapshot(snapshotProviderId(providerId), identity.accountId, apiState);
+            }
+            return finish(apiState, 'api');
+        }
+    }
+    if (providerId === 'codex' && apiFirst) {
+        const local = readLocalCodex();
+        if (local?.available && (!snapshot || captureTimeMs(local) > captureTimeMs(snapshot))) {
+            return { ...finishLocal(local), failure: describeQuotaFailure(apiState) };
+        }
+    }
+    if (snapshot) {
+        const fallback = finish(snapshot, snapshotResolution(snapshot));
+        return apiState ? { ...fallback, failure: describeQuotaFailure(apiState) } : fallback;
+    }
+    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');
+}

package/dist/esm/quotaSnapshots.js

@@ -0,0 +1,130 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getConfigDir } from './paths';
+import { atomicWriteJsonSync, withFileLockSync } from './writers/atomic';
+import { classifyQuotaFreshness } from './quota';
+import { isAggregateCodexLimit } from './types/codex';
+function getQuotaSnapshotPath() {
+    return path.join(getConfigDir(), 'quota-snapshots.json');
+}
+function ensureConfigDir() {
+    fs.mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+}
+function readStore() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(getQuotaSnapshotPath(), 'utf8'));
+        if (parsed?.version === 1 && Array.isArray(parsed.snapshots)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Ignore absent or malformed store.
+    }
+    return {
+        version: 1,
+        snapshots: [],
+    };
+}
+function writeStore(store) {
+    ensureConfigDir();
+    atomicWriteJsonSync(getQuotaSnapshotPath(), store);
+}
+/**
+ * Serializes snapshot read-modify-write cycles across processes on the shared
+ * store lock. The lock file path is unchanged from the previous local
+ * implementation, so processes running older versions still exclude correctly.
+ */
+function withSnapshotStoreLock(operation) {
+    ensureConfigDir();
+    return withFileLockSync(`${getQuotaSnapshotPath()}.lock`, operation);
+}
+function snapshotTimeMs(quota) {
+    const capturedAt = quota.capturedAt ? Date.parse(quota.capturedAt) : NaN;
+    return Number.isFinite(capturedAt) ? capturedAt : 0;
+}
+function windowResetMs(value) {
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : 0;
+}
+// Preserve the best-known same-window snapshot while still allowing lower
+// utilization after Codex advances to a newer reset window.
+function shouldKeepExistingSnapshot(existing, next) {
+    // Family rank first (Codex): the aggregate plan-quota family ("codex") must never be
+    // replaced or blocked by a model/feature-specific family (e.g. codex_bengalfox), whose
+    // later-resetting 0% window would otherwise win the reset-window comparison below. This
+    // is a no-op for providers whose limitId is consistent across samples (Claude: absent;
+    // z.ai: zai-*), where both sides share the same aggregate-ness.
+    const existingAggregate = isAggregateCodexLimit(existing.limitId);
+    const nextAggregate = isAggregateCodexLimit(next.limitId);
+    if (existingAggregate !== nextAggregate)
+        return existingAggregate;
+    const existingPrimaryReset = windowResetMs(existing.fiveHour.resetsAt);
+    const nextPrimaryReset = windowResetMs(next.fiveHour.resetsAt);
+    if (existingPrimaryReset !== nextPrimaryReset)
+        return existingPrimaryReset > nextPrimaryReset;
+    const existingSecondaryReset = windowResetMs(existing.sevenDay.resetsAt);
+    const nextSecondaryReset = windowResetMs(next.sevenDay.resetsAt);
+    if (existingSecondaryReset !== nextSecondaryReset)
+        return existingSecondaryReset > nextSecondaryReset;
+    const existingUtilization = existing.fiveHour.utilization + existing.sevenDay.utilization;
+    const nextUtilization = next.fiveHour.utilization + next.sevenDay.utilization;
+    if (existingUtilization !== nextUtilization)
+        return existingUtilization > nextUtilization;
+    return snapshotTimeMs(existing) > snapshotTimeMs(next);
+}
+export function writeQuotaSnapshot(providerId, accountId, quota) {
+    withSnapshotStoreLock(() => {
+        const store = readStore();
+        const index = store.snapshots.findIndex((item) => item.providerId === providerId && item.accountId === accountId);
+        const existingQuota = index >= 0 ? store.snapshots[index].quota : undefined;
+        // `ageMs`, `freshness`, `stale`, and `capturedSource` are read-time facts: a
+        // sample that came back from `readQuotaSnapshot()` and is written again keeps
+        // its original source rather than being stored as `cache`.
+        const { capturedSource, ...sample } = quota;
+        delete sample.ageMs;
+        delete sample.freshness;
+        const snapshot = {
+            ...sample,
+            providerId,
+            capturedAt: quota.capturedAt ?? new Date().toISOString(),
+            source: sample.source && sample.source !== 'cache' ? sample.source : (capturedSource ?? 'session'),
+            stale: false,
+            resetCredits: quota.resetCredits ?? (providerId === 'codex' ? existingQuota?.resetCredits : undefined),
+        };
+        if (index >= 0 && shouldKeepExistingSnapshot(store.snapshots[index].quota, snapshot))
+            return;
+        const record = { providerId, accountId, quota: snapshot };
+        if (index >= 0)
+            store.snapshots[index] = record;
+        else
+            store.snapshots.push(record);
+        writeStore(store);
+    });
+}
+/**
+ * Read the persisted snapshot for one provider/account.
+ *
+ * `stale: true` and `source: 'cache'` mean "not a live fetch"; the age of the
+ * sample is reported separately as `ageMs` and `freshness` so a reader can
+ * tell a ten-second-old snapshot from a two-day-old one, and the original
+ * origin is kept as `capturedSource` (`statusline`, `session`, or `api`).
+ */
+export function readQuotaSnapshot(providerId, accountId, now = new Date()) {
+    const store = readStore();
+    const snapshot = store.snapshots.find((item) => item.providerId === providerId && item.accountId === accountId);
+    if (!snapshot)
+        return null;
+    const capturedMs = snapshotTimeMs(snapshot.quota);
+    const ageMs = capturedMs > 0 ? Math.max(0, now.getTime() - capturedMs) : undefined;
+    const storedSource = snapshot.quota.capturedSource ?? snapshot.quota.source;
+    const capturedSource = storedSource && storedSource !== 'cache' ? storedSource : undefined;
+    return {
+        ...snapshot.quota,
+        providerId,
+        source: 'cache',
+        ...(capturedSource ? { capturedSource } : {}),
+        stale: true,
+        ...(ageMs !== undefined ? { ageMs } : {}),
+        freshness: classifyQuotaFreshness(ageMs),
+    };
+}