sidekick-shared 0.24.5 → 0.26.0

package/dist/quotaHistory.d.ts

@@ -6,7 +6,8 @@
  * dashboard, the `sidekick quota history` CLI, external consumers) can render heatmaps and
  * trend visualisations over a 13-week window.
  */
-export type QuotaHistoryRuntimeProvider = 'claude' | 'codex' | 'zai';
+import type { RuntimeQuotaProviderId } from './providerIds';
+export type QuotaHistoryRuntimeProvider = RuntimeQuotaProviderId;
 export interface QuotaHistorySample {
     timestamp: string;
     runtimeProvider: QuotaHistoryRuntimeProvider;
@@ -22,7 +23,7 @@ export interface QuotaHistorySample {
     };
     available: boolean;
     error?: string;
-    source?: 'session' | 'cache' | 'api';
+    source?: 'session' | 'cache' | 'api' | 'statusline';
     stale?: boolean;
 }
 export interface QuotaHistoryAppendOptions {

package/dist/quotaHistory.js

@@ -50,8 +50,10 @@ exports._resetQuotaHistoryInMemoryStateForTests = _resetQuotaHistoryInMemoryStat
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const formatting_1 = require("./formatting");
 const paths_1 = require("./paths");
 const quotaSnapshots_1 = require("./quotaSnapshots");
+const atomic_1 = require("./writers/atomic");
 const DEFAULT_MIN_INTERVAL_MS = 60_000;
 const DEFAULT_RETENTION_DAYS = 91;
 const PRUNE_FILESIZE_THRESHOLD = 16 * 1024;
@@ -150,21 +152,16 @@ function readLastSampleTimestampMs(filePath) {
         }
     }
 }
+/**
+ * Append-and-prune under the shared cross-process lock. Without it a prune
+ * rewrite (rename over the file) could race another process's append, and
+ * the appended line would land on the old, unlinked inode.
+ */
+function withHistoryFileLock(filePath, operation) {
+    return (0, atomic_1.withFileLockSync)(`${filePath}.lock`, operation);
+}
 function atomicRewriteFile(filePath, contents) {
-    const tmp = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomBytes(8).toString('hex')}.tmp`;
-    try {
-        fs.writeFileSync(tmp, contents, { encoding: 'utf8', mode: 0o600 });
-        fs.renameSync(tmp, filePath);
-    }
-    catch (error) {
-        try {
-            fs.rmSync(tmp, { force: true });
-        }
-        catch {
-            // Best effort cleanup only.
-        }
-        throw error;
-    }
+    (0, atomic_1.atomicWriteFileSync)(filePath, contents, 0o600);
 }
 function pruneFileSync(filePath, retentionDays) {
     let stat;
@@ -245,18 +242,19 @@ async function runAppend(sample, filePath, options) {
     }
     ensureHistoryDir(sample.workspaceId);
     const line = JSON.stringify(sample) + '\n';
-    await fs.promises.appendFile(filePath, line, { encoding: 'utf8', mode: 0o600 });
-    lastWriteCache.set(filePath, Number.isFinite(sampleTs) ? sampleTs : Date.now());
-    // Opportunistic prune. Skip when the file is small to avoid pointless rewrite churn.
-    try {
-        const stat = await fs.promises.stat(filePath);
-        if (stat.size >= PRUNE_FILESIZE_THRESHOLD) {
-            pruneFileSync(filePath, options.retentionDays);
+    withHistoryFileLock(filePath, () => {
+        fs.appendFileSync(filePath, line, { encoding: 'utf8', mode: 0o600 });
+        // Opportunistic prune. Skip when the file is small to avoid pointless rewrite churn.
+        try {
+            if (fs.statSync(filePath).size >= PRUNE_FILESIZE_THRESHOLD) {
+                pruneFileSync(filePath, options.retentionDays);
+            }
         }
-    }
-    catch {
-        // ignore
-    }
+        catch {
+            // ignore
+        }
+    });
+    lastWriteCache.set(filePath, Number.isFinite(sampleTs) ? sampleTs : Date.now());
     // Backwards-compat: keep the latest-snapshot store hot so existing callers (DashboardViewProvider,
     // codex session provider, external consumers) don't have to query history for "latest".
     try {
@@ -323,23 +321,26 @@ async function readQuotaHistoryRange(options) {
     samples.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
     return samples;
 }
-function utcDateString(ms) {
-    return new Date(ms).toISOString().slice(0, 10);
-}
-function addDaysUtc(dateString, days) {
-    const ms = Date.parse(`${dateString}T00:00:00Z`) + days * MS_PER_DAY;
-    return utcDateString(ms);
+/**
+ * Daily buckets are keyed by the machine's local calendar day, matching the
+ * `today` brief, the historical-data store, and the dashboard date filters.
+ */
+function localDateString(ms) {
+    return (0, formatting_1.formatLocalDateKey)(ms);
 }
 async function readQuotaHistoryDailyBuckets(options) {
     const samples = await readQuotaHistoryRange(options);
     const { fromMs: defaultFromMs, toMs: defaultToMs } = defaultRangeMs();
     const fromMs = options.from ? Date.parse(options.from) : defaultFromMs;
     const toMs = options.to ? Date.parse(options.to) : defaultToMs;
-    const startDate = utcDateString(fromMs);
-    const endDate = utcDateString(toMs);
+    const startDate = localDateString(fromMs);
+    const endDate = localDateString(toMs);
     const grouped = new Map();
     for (const sample of samples) {
-        const day = sample.timestamp.slice(0, 10);
+        const sampleMs = Date.parse(sample.timestamp);
+        if (!Number.isFinite(sampleMs))
+            continue;
+        const day = localDateString(sampleMs);
         const bucket = grouped.get(day);
         if (bucket) {
             bucket.push(sample);
@@ -389,7 +390,7 @@ async function readQuotaHistoryDailyBuckets(options) {
                 anyUnavailable,
             });
         }
-        cursor = addDaysUtc(cursor, 1);
+        cursor = (0, formatting_1.addLocalDays)(cursor, 1);
     }
     return buckets;
 }

package/dist/quotaPoller.d.ts

@@ -7,6 +7,7 @@
  * @module quotaPoller
  */
 import type { QuotaState } from './quota';
+import { type AccountsChangedEvent } from './accountChanges';
 /** Disposable subscription handle. */
 export interface Disposable {
     dispose(): void;
@@ -20,7 +21,11 @@ export interface QuotaPollerOptions {
     /** Maximum backoff delay for retries (ms). Default: 120_000 (2 minutes). */
     maxBackoffMs?: number;
     /** Returns the current access token. Called before each fetch. */
-    getAccessToken: () => Promise<string>;
+    getAccessToken: () => Promise<string | null | undefined>;
+    /** Optional cheap account-presence check performed before credential access. */
+    hasAccount?: () => boolean | Promise<boolean>;
+    /** Override the process-wide login/logout signal (primarily for embedded hosts/tests). */
+    subscribeAccountsChanged?: (listener: (event: AccountsChangedEvent) => void) => Disposable;
 }
 /**
  * Polls Claude Max quota usage with exponential backoff on transient errors,
@@ -47,12 +52,18 @@ export declare class QuotaPoller {
     private readonly idleIntervalMs;
     private readonly maxBackoffMs;
     private readonly getAccessToken;
+    private readonly hasAccount?;
+    private readonly subscribeAccountsChanged;
     private timer;
     private listeners;
     private latest;
     private isActive;
     private consecutiveFailures;
     private stopped;
+    private polling;
+    private pendingWake;
+    private dormant;
+    private accountSubscription;
     constructor(options: QuotaPollerOptions);
     /**
      * Starts polling. First poll is immediate.
@@ -82,6 +93,7 @@ export declare class QuotaPoller {
      */
     getLatest(): QuotaState | null;
     private poll;
+    private wake;
     private scheduleNext;
     private notify;
 }

package/dist/quotaPoller.js

@@ -10,6 +10,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QuotaPoller = void 0;
 const quota_1 = require("./quota");
+const accountChanges_1 = require("./accountChanges");
 /**
  * Polls Claude Max quota usage with exponential backoff on transient errors,
  * cached fallback, and configurable active/idle intervals.
@@ -35,17 +36,25 @@ class QuotaPoller {
     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 ?? accountChanges_1.onAccountsChanged;
     }
     /**
      * Starts polling. First poll is immediate.
@@ -53,17 +62,21 @@ class QuotaPoller {
     start() {
         this.stopped = false;
         this.isActive = true;
-        void this.poll();
+        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.
@@ -102,8 +115,35 @@ class QuotaPoller {
     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 (0, quota_1.fetchQuota)(token);
             if (state.available) {
                 this.latest = state;
@@ -116,7 +156,7 @@ class QuotaPoller {
                 this.latest = state;
                 this.notify(state);
                 this.consecutiveFailures = 0;
-                this.scheduleNext(this.idleIntervalMs);
+                nextDelayOverride = this.idleIntervalMs;
                 return;
             }
             else {
@@ -148,7 +188,29 @@ class QuotaPoller {
             this.latest = state;
             this.notify(state);
         }
-        this.scheduleNext();
+        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)

package/dist/quotaResolver.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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()` applies one 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` skips step 1 (the `--refresh` flag). Every result carries
+ * `source`, `capturedSource`, `freshness`, `ageMs`, and a `resolution` tag.
+ */
+import type { ResolvedActiveAccount, SavedAccountProfile } from './accountRegistry';
+import type { ProviderQuotaState } from './providerQuota';
+import type { CodexProvider } from './providers/codex';
+import type { QuotaState } from './quota';
+import type { QuotaSnapshotProviderId } from './quotaSnapshots';
+import type { ZaiQuotaApiOptions } from './zaiQuotaApi';
+/** Providers the resolver knows how to read. `opencode` callers map to `zai`. */
+export type QuotaResolveProviderId = 'claude-code' | 'codex' | 'zai';
+/** Which step of the precedence produced the answer. */
+export type QuotaResolution = 'snapshot-fresh' | 'session' | 'api' | 'snapshot-aging' | 'snapshot-stale' | 'unavailable';
+type RuntimeProviderFor<T extends QuotaResolveProviderId> = T extends 'claude-code' ? 'claude' : T extends 'codex' ? 'codex' : 'zai';
+export interface ResolvedQuota<T extends QuotaResolveProviderId = QuotaResolveProviderId> extends ProviderQuotaState<RuntimeProviderFor<T>> {
+    /** Precedence step that produced this sample. */
+    resolution: QuotaResolution;
+}
+export interface ResolveQuotaOptions<T extends QuotaResolveProviderId = QuotaResolveProviderId> {
+    providerId: T;
+    /** Snapshot key; derived from the active account when omitted. */
+    accountId?: string;
+    /** Workspace whose Codex rollouts are searched first for session-derived rate limits. */
+    workspacePath?: string;
+    /** Use a fresh persisted snapshot before anything else (default true). `--refresh` passes false. */
+    preferFresh?: boolean;
+    /** Allow a provider API call when no fresh local sample exists (default true). */
+    allowApi?: boolean;
+    /** Re-point a stale saved-account pointer while resolving the account (default true). */
+    selfHeal?: boolean;
+    /** Clock for freshness classification; defaults to `new Date()`. */
+    now?: Date;
+    /** Fetch implementation forwarded to every API call (tests inject a stub). */
+    fetchImpl?: typeof fetch;
+    readSnapshot?: (providerId: QuotaSnapshotProviderId, accountId: string, now?: Date) => QuotaState | null;
+    writeSnapshot?: (providerId: QuotaSnapshotProviderId, accountId: string, quota: QuotaState) => void;
+    /** Claude access token source; defaults to `readClaudeMaxCredentials()`. */
+    getClaudeAccessToken?: () => Promise<string | null>;
+    /** Claude account resolution; defaults to `resolveActiveClaudeAccount()`. */
+    resolveClaudeAccount?: (options: {
+        selfHeal?: boolean;
+    }) => ResolvedActiveAccount;
+    /** Codex account resolution; defaults to the self-healing registry lookup. */
+    resolveCodexAccount?: (options: {
+        selfHeal?: boolean;
+    }) => SavedAccountProfile | null;
+    /** Reuse a caller-owned Codex provider for the session scan. */
+    codexProvider?: CodexProvider;
+    /** Codex home whose `auth.json` and rollouts are read. */
+    codexHome?: string;
+    /** Explicit Codex access token for the API step. */
+    codexAccessToken?: string;
+    /** z.ai credential discovery and API options. */
+    zai?: ZaiQuotaApiOptions;
+}
+/**
+ * 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 declare function resolveQuota<T extends QuotaResolveProviderId>(options: ResolveQuotaOptions<T>): Promise<ResolvedQuota<T>>;
+export {};

package/dist/quotaResolver.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * 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()` applies one 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` skips step 1 (the `--refresh` flag). Every result carries
+ * `source`, `capturedSource`, `freshness`, `ageMs`, and a `resolution` tag.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveQuota = resolveQuota;
+const accounts_1 = require("./accounts");
+const codexProfiles_1 = require("./codexProfiles");
+const codexQuota_1 = require("./codexQuota");
+const credentials_1 = require("./credentials");
+const quota_1 = require("./quota");
+const quotaPresentation_1 = require("./quotaPresentation");
+const quotaSnapshots_1 = require("./quotaSnapshots");
+const zaiQuotaApi_1 = require("./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`.
+    (0, codexProfiles_1.resolveActiveCodexAccount)(options);
+    return (0, codexProfiles_1.getActiveCodexAccount)();
+}
+function resolveIdentity(options) {
+    const selfHeal = options.selfHeal ?? true;
+    switch (options.providerId) {
+        case 'claude-code': {
+            const account = (options.resolveClaudeAccount ?? accounts_1.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 (0, credentials_1.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 (0, quota_1.fetchQuota)(token, { fetchImpl: options.fetchImpl });
+            return { ...state, providerId: 'claude-code', source: 'api', capturedAt };
+        }
+        case 'codex':
+            return (0, codexQuota_1.fetchCodexQuotaFromApi)({
+                codexHome: options.codexHome,
+                fetchImpl: options.fetchImpl,
+                accessToken: options.codexAccessToken,
+                accountId: identity.codexAccount?.providerAccountId,
+                capturedAt,
+            });
+        case 'zai':
+            return (0, zaiQuotaApi_1.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: (0, quota_1.classifyQuotaFreshness)(ageMs),
+    };
+}
+function enrich(providerId, state, identity) {
+    switch (providerId) {
+        case 'claude-code':
+            return {
+                ...(0, quota_1.withQuotaProjections)(state),
+                runtimeProvider: 'claude',
+                providerId: 'claude-code',
+                accountLabel: identity.accountLabel,
+                accountDetail: identity.accountDetail,
+            };
+        case 'codex':
+            return (0, codexQuota_1.enrichCodexQuota)(state, identity.codexAccount);
+        default:
+            return (0, zaiQuotaApi_1.enrichZaiQuota)(state);
+    }
+}
+function snapshotResolution(state) {
+    if (state.freshness === 'fresh')
+        return 'snapshot-fresh';
+    if (state.freshness === 'aging')
+        return 'snapshot-aging';
+    return 'snapshot-stale';
+}
+/**
+ * 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.
+ */
+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 readSnapshot = options.readSnapshot ?? quotaSnapshots_1.readQuotaSnapshot;
+    const writeSnapshot = options.writeSnapshot ?? quotaSnapshots_1.writeQuotaSnapshot;
+    const identity = resolveIdentity(options);
+    const finish = (state, resolution) => {
+        const enriched = withAge(enrich(providerId, state, identity), now);
+        return {
+            ...enriched,
+            failure: enriched.failure ?? (0, quotaPresentation_1.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');
+    }
+    if (providerId === 'codex') {
+        const local = (0, codexQuota_1.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,
+            writeSnapshot,
+        });
+        if (local)
+            return finish(local, 'session');
+    }
+    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 (snapshot) {
+        const fallback = finish(snapshot, snapshotResolution(snapshot));
+        return apiState ? { ...fallback, failure: (0, quotaPresentation_1.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/quotaSnapshots.d.ts

@@ -1,4 +1,4 @@
-import type { QuotaState } from './quota';
+import { type QuotaState } from './quota';
 import type { AccountProviderId } from './accountRegistry';
 /**
  * Storage key for a quota snapshot. Extends `AccountProviderId` with `'zai'`
@@ -6,5 +6,18 @@ import type { AccountProviderId } from './accountRegistry';
  * store still needs a stable key for the z.ai quota cache.
  */
 export type QuotaSnapshotProviderId = AccountProviderId | 'zai';
+export interface QuotaSnapshotRecord {
+    providerId: QuotaSnapshotProviderId;
+    accountId: string;
+    quota: QuotaState;
+}
 export declare function writeQuotaSnapshot(providerId: QuotaSnapshotProviderId, accountId: string, quota: QuotaState): void;
-export declare function readQuotaSnapshot(providerId: QuotaSnapshotProviderId, accountId: string): QuotaState | null;
+/**
+ * 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 declare function readQuotaSnapshot(providerId: QuotaSnapshotProviderId, accountId: string, now?: Date): QuotaState | null;