sidekick-shared 0.25.0 → 0.26.1

package/dist/quota.d.ts

@@ -46,12 +46,26 @@ export interface QuotaState {
     projectedSevenDay?: number;
     /** Provider that produced this quota sample */
     providerId?: QuotaProviderId;
-    /** Source of the sample */
-    source?: 'api' | 'session' | 'cache';
+    /**
+     * Source of the sample. `statusline` is the official rate-limit block Claude
+     * Code hands to its status-line command; `session` is inferred from session
+     * logs; `api` is a live usage-endpoint fetch; `cache` is a persisted snapshot.
+     */
+    source?: 'api' | 'session' | 'cache' | 'statusline';
+    /**
+     * Where a cached sample originally came from. `readQuotaSnapshot()` forces
+     * `source` to `cache`; this keeps the origin (`statusline`, `session`, `api`)
+     * so a reader can rank an official status-line sample above a session guess.
+     */
+    capturedSource?: 'api' | 'session' | 'statusline';
     /** ISO timestamp when the sample was captured */
     capturedAt?: string;
     /** Whether the sample is stale cached data */
     stale?: boolean;
+    /** Milliseconds between `capturedAt` and the read, when read from a snapshot. */
+    ageMs?: number;
+    /** Freshness tier derived from `ageMs`; see `classifyQuotaFreshness`. */
+    freshness?: QuotaFreshness;
     /** Provider-specific display label for the first window */
     fiveHourLabel?: string;
     /** Provider-specific display label for the second window */
@@ -71,6 +85,16 @@ export interface QuotaState {
 }
 export declare const FIVE_HOUR_WINDOW_MS: number;
 export declare const SEVEN_DAY_WINDOW_MS: number;
+/** How much to trust a cached quota sample, by age. */
+export type QuotaFreshness = 'fresh' | 'aging' | 'stale';
+/** A snapshot younger than this is as good as live. */
+export declare const QUOTA_FRESH_MAX_AGE_MS: number;
+/** A snapshot older than this should be labelled as stale wherever it is shown. */
+export declare const QUOTA_AGING_MAX_AGE_MS: number;
+/** Classify a cached sample's age. Non-finite or negative ages count as stale. */
+export declare function classifyQuotaFreshness(ageMs: number | undefined): QuotaFreshness;
+/** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
+export declare function formatQuotaAge(ageMs: number | undefined): string;
 export interface QuotaProjectionInput {
     utilization: number;
     resetsAt: string;
@@ -95,6 +119,9 @@ export declare function withQuotaProjections<T extends QuotaState>(state: T, opt
  * it in a polling loop, VS Code EventEmitter, or CLI interval as needed.
  *
  * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
+ * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
  * @returns QuotaState with utilization data and elapsed-time projections
  */
-export declare function fetchQuota(accessToken: string): Promise<QuotaState>;
+export declare function fetchQuota(accessToken: string, options?: {
+    fetchImpl?: typeof fetch;
+}): Promise<QuotaState>;

package/dist/quota.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEVEN_DAY_WINDOW_MS = exports.FIVE_HOUR_WINDOW_MS = exports.QUOTA_PROVIDER_IDS = void 0;
+exports.QUOTA_AGING_MAX_AGE_MS = exports.QUOTA_FRESH_MAX_AGE_MS = exports.SEVEN_DAY_WINDOW_MS = exports.FIVE_HOUR_WINDOW_MS = exports.QUOTA_PROVIDER_IDS = void 0;
+exports.classifyQuotaFreshness = classifyQuotaFreshness;
+exports.formatQuotaAge = formatQuotaAge;
 exports.projectQuotaWindow = projectQuotaWindow;
 exports.withQuotaProjections = withQuotaProjections;
 exports.fetchQuota = fetchQuota;
@@ -11,6 +13,34 @@ const BETA_HEADER = 'oauth-2025-04-20';
 const FETCH_TIMEOUT_MS = 10_000;
 exports.FIVE_HOUR_WINDOW_MS = 5 * 3_600_000;
 exports.SEVEN_DAY_WINDOW_MS = 7 * 86_400_000;
+/** A snapshot younger than this is as good as live. */
+exports.QUOTA_FRESH_MAX_AGE_MS = 5 * 60_000;
+/** A snapshot older than this should be labelled as stale wherever it is shown. */
+exports.QUOTA_AGING_MAX_AGE_MS = 60 * 60_000;
+/** Classify a cached sample's age. Non-finite or negative ages count as stale. */
+function classifyQuotaFreshness(ageMs) {
+    if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
+        return 'stale';
+    if (ageMs < exports.QUOTA_FRESH_MAX_AGE_MS)
+        return 'fresh';
+    if (ageMs < exports.QUOTA_AGING_MAX_AGE_MS)
+        return 'aging';
+    return 'stale';
+}
+/** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
+function formatQuotaAge(ageMs) {
+    if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
+        return 'age unknown';
+    const minutes = Math.floor(ageMs / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
 /**
  * Projects utilization at end of window based on elapsed time.
  *
@@ -88,14 +118,16 @@ function parseRetryAfterMs(retryAfter) {
  * it in a polling loop, VS Code EventEmitter, or CLI interval as needed.
  *
  * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
+ * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
  * @returns QuotaState with utilization data and elapsed-time projections
  */
-async function fetchQuota(accessToken) {
+async function fetchQuota(accessToken, options = {}) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     timeout.unref();
     try {
-        const res = await fetch(USAGE_URL, {
+        const fetchImpl = options.fetchImpl ?? fetch;
+        const res = await fetchImpl(USAGE_URL, {
             method: 'GET',
             signal: controller.signal,
             headers: {

package/dist/quotaHistory.d.ts

@@ -23,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/quotaPresentation.js

@@ -23,8 +23,20 @@ function formatRetryAfter(ms) {
 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',
@@ -47,7 +59,7 @@ function describeQuotaFailure(quota) {
             return {
                 severity: 'warning',
                 title: 'Quota API unreachable',
-                message: 'Could not reach Anthropic from the current environment.',
+                message: `Could not reach ${apiName} from the current environment.`,
                 detail: 'Check connectivity, proxy, or firewall settings, then retry.',
                 alertKey: 'network',
                 isRetryable: true,
@@ -59,7 +71,7 @@ function describeQuotaFailure(quota) {
                 message: quota.retryAfterMs != null
                     ? `Retry in ${formatRetryAfter(quota.retryAfterMs)}.`
                     : 'Retry shortly.',
-                detail: quota.httpStatus != null ? `Anthropic returned HTTP ${quota.httpStatus}.` : undefined,
+                detail: quota.httpStatus != null ? `${apiName} returned HTTP ${quota.httpStatus}.` : undefined,
                 alertKey: `rate_limit:${quota.httpStatus ?? 429}`,
                 isRetryable: true,
             };
@@ -68,8 +80,8 @@ function describeQuotaFailure(quota) {
                 severity: 'warning',
                 title: 'Quota API unavailable',
                 message: quota.httpStatus != null
-                    ? `Anthropic returned HTTP ${quota.httpStatus}. Try again shortly.`
-                    : 'Anthropic quota data is temporarily unavailable.',
+                    ? `${apiName} returned HTTP ${quota.httpStatus}. Try again shortly.`
+                    : `${apiName} quota data is temporarily unavailable.`,
                 alertKey: `server:${quota.httpStatus ?? 'unknown'}`,
                 isRetryable: true,
             };
@@ -78,7 +90,7 @@ function describeQuotaFailure(quota) {
                 severity: 'error',
                 title: 'Unexpected quota response',
                 message: quota.httpStatus != null
-                    ? `Anthropic returned HTTP ${quota.httpStatus}.`
+                    ? `${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'}`,

package/dist/quotaResolver.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 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;
+    /** Prefer local samples (default true). False asks the API before any local sample when allowed. */
+    preferFresh?: boolean;
+    /** Allow provider API calls (default true), including when preferFresh is false. */
+    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,234 @@
+"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()` 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.
+ */
+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';
+}
+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.
+ */
+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 ?? 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');
+    }
+    const readLocalCodex = () => (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,
+        // 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: (0, quotaPresentation_1.describeQuotaFailure)(apiState) };
+        }
+    }
+    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;