sidekick-shared 0.24.5 → 0.26.0

package/dist/providers/openCodeDatabase.d.ts

@@ -17,12 +17,22 @@ export declare class OpenCodeDatabase {
     open(): boolean;
     close(): void;
     private query;
+    private queryAsync;
     private queryOne;
     findProjectByWorktree(workspacePath: string): DbProject | null;
     findProjectBySessionDirectory(workspacePath: string): DbProject | null;
     getAllProjects(): DbProject[];
     hasProject(projectId: string): boolean;
     getSessionsForProject(projectId: string): DbSession[];
+    /** Get every root session in one query for global preview enumeration. */
+    getAllSessions(): DbSession[];
+    /** Enumerate root sessions with one non-blocking sqlite3 subprocess. */
+    getAllSessionsAsync(): Promise<DbSession[]>;
+    /**
+     * Resolve many sessions with non-blocking sqlite3 subprocesses — one per
+     * chunk of ids, so the inlined query stays clear of argv length limits.
+     */
+    getSessionsByIdsAsync(sessionIds: readonly string[]): Promise<DbSession[]>;
     /** Get the most recently updated session for a project (excludes subagent child sessions). */
     getMostRecentSession(projectId: string): DbSession | null;
     /** Get child sessions (subagents) whose parent_id matches the given session ID. */

package/dist/providers/openCodeDatabase.js

@@ -41,6 +41,11 @@ exports.OpenCodeDatabase = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+/**
+ * Ids per inlined `IN (…)` query. Values are passed inside a single argv
+ * element to sqlite3, so an unbounded list would hit E2BIG on large stores.
+ */
+const SQL_ID_CHUNK_SIZE = 400;
 class OpenCodeDatabase {
     dbPath;
     runtimeStatus = null;
@@ -127,6 +132,23 @@ class OpenCodeDatabase {
             return [];
         }
     }
+    async queryAsync(sql, params = []) {
+        if (!this.isAvailable()) {
+            this.runtimeStatus = { available: false, kind: 'db_missing' };
+            return [];
+        }
+        const query = bindSqlParams(sql, params);
+        try {
+            const result = await execSqlite(this.dbPath, query);
+            this.runtimeStatus = { available: true, kind: 'available' };
+            const trimmed = result.trim();
+            return trimmed ? JSON.parse(trimmed) : [];
+        }
+        catch (error) {
+            this.runtimeStatus = toRuntimeStatus(error, 'query_failed');
+            return [];
+        }
+    }
     queryOne(sql, params = []) {
         const results = this.query(sql, params);
         return results[0] ?? null;
@@ -181,6 +203,27 @@ class OpenCodeDatabase {
     getSessionsForProject(projectId) {
         return this.query('SELECT id, project_id, title, directory, time_created, time_updated FROM session WHERE project_id = ? AND parent_id IS NULL ORDER BY time_updated DESC', [projectId]);
     }
+    /** Get every root session in one query for global preview enumeration. */
+    getAllSessions() {
+        return this.query('SELECT id, project_id, title, directory, time_created, time_updated FROM session WHERE parent_id IS NULL ORDER BY time_updated DESC');
+    }
+    /** Enumerate root sessions with one non-blocking sqlite3 subprocess. */
+    getAllSessionsAsync() {
+        return this.queryAsync('SELECT id, project_id, title, directory, time_created, time_updated FROM session WHERE parent_id IS NULL ORDER BY time_updated DESC');
+    }
+    /**
+     * Resolve many sessions with non-blocking sqlite3 subprocesses — one per
+     * chunk of ids, so the inlined query stays clear of argv length limits.
+     */
+    async getSessionsByIdsAsync(sessionIds) {
+        const results = [];
+        for (let i = 0; i < sessionIds.length; i += SQL_ID_CHUNK_SIZE) {
+            const chunk = sessionIds.slice(i, i + SQL_ID_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(', ');
+            results.push(...(await this.queryAsync(`SELECT id, project_id, title, directory, time_created, time_updated FROM session WHERE id IN (${placeholders})`, [...chunk])));
+        }
+        return results;
+    }
     /** Get the most recently updated session for a project (excludes subagent child sessions). */
     getMostRecentSession(projectId) {
         return this.queryOne('SELECT id, project_id, title, directory, time_created, time_updated FROM session WHERE project_id = ? AND parent_id IS NULL ORDER BY time_updated DESC LIMIT 1', [projectId]);
@@ -315,6 +358,32 @@ class OpenCodeDatabase {
     }
 }
 exports.OpenCodeDatabase = OpenCodeDatabase;
+function bindSqlParams(sql, params) {
+    let paramIndex = 0;
+    return sql.replace(/\?/g, () => {
+        if (paramIndex >= params.length)
+            return '?';
+        const param = params[paramIndex++];
+        if (typeof param === 'number')
+            return Number.isFinite(param) ? String(param) : '0';
+        return `'${String(param).replace(/'/g, "''")}'`;
+    });
+}
+function execSqlite(dbPath, query) {
+    return new Promise((resolve, reject) => {
+        (0, child_process_1.execFile)('sqlite3', ['-json', '-readonly', dbPath, query], {
+            encoding: 'utf8',
+            timeout: 4_000,
+            killSignal: 'SIGKILL',
+            maxBuffer: 50 * 1024 * 1024,
+        }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve(stdout);
+        });
+    });
+}
 function normalizePath(input) {
     try {
         return fs.realpathSync(input);

package/dist/providers/rolloutWalker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * One capped walker for Codex rollout files.
+ *
+ * Codex writes `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl`.
+ * Six recursive, uncapped walkers used to exist across the provider and the
+ * quota resolver; this module replaces them with a single walk that caps
+ * depth and file count, visits the newest-dated directories first so a
+ * `limit` can stop early, stats each file exactly once, and returns results
+ * newest first with the size and session id already attached.
+ *
+ * With `limit`, the early exit is by directory date: a rollout that was
+ * created days ago but is still being written lands in its creation day's
+ * directory, so a very small limit can miss it in favour of newer-dated,
+ * older-modified files. Callers that need exact mtime order over the whole
+ * history omit `limit` (the `maxFiles` cap still applies).
+ *
+ * @module providers/rolloutWalker
+ */
+export interface RolloutFileInfo {
+    path: string;
+    mtime: Date;
+    sizeBytes: number;
+    /** Session id parsed from the file name. */
+    sessionId: string;
+}
+export interface WalkRolloutFilesOptions {
+    /** Directory depth below each root to descend into (default 6; the dated tree is 3). */
+    maxDepth?: number;
+    /** Upper bound on files returned across all roots (default 20 000). */
+    maxFiles?: number;
+    /** Stop once this many files are collected, visiting newest-dated directories first. */
+    limit?: number;
+    /** Only files whose name carries this session id (case-insensitive). */
+    sessionId?: string;
+    /** Include zero-byte files (default false). */
+    includeEmpty?: boolean;
+}
+export declare const DEFAULT_ROLLOUT_WALK_MAX_DEPTH = 6;
+export declare const DEFAULT_ROLLOUT_WALK_MAX_FILES = 20000;
+/** Test if a filename is a Codex rollout file. */
+export declare function isRolloutFile(filename: string): boolean;
+/**
+ * Extract the session UUID from a rollout filename.
+ * Format: rollout-<timestamp>-<uuid>.jsonl -> <uuid>
+ */
+export declare function extractRolloutSessionId(filename: string): string;
+/**
+ * Walk one or more `sessions` roots for rollout files, newest first.
+ * Missing or unreadable directories are skipped; paths are deduplicated.
+ */
+export declare function walkRolloutFiles(roots: readonly string[], options?: WalkRolloutFilesOptions): RolloutFileInfo[];
+/** Async twin of {@link walkRolloutFiles} that yields between directories. */
+export declare function walkRolloutFilesAsync(roots: readonly string[], options?: WalkRolloutFilesOptions): Promise<RolloutFileInfo[]>;

package/dist/providers/rolloutWalker.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * One capped walker for Codex rollout files.
+ *
+ * Codex writes `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl`.
+ * Six recursive, uncapped walkers used to exist across the provider and the
+ * quota resolver; this module replaces them with a single walk that caps
+ * depth and file count, visits the newest-dated directories first so a
+ * `limit` can stop early, stats each file exactly once, and returns results
+ * newest first with the size and session id already attached.
+ *
+ * With `limit`, the early exit is by directory date: a rollout that was
+ * created days ago but is still being written lands in its creation day's
+ * directory, so a very small limit can miss it in favour of newer-dated,
+ * older-modified files. Callers that need exact mtime order over the whole
+ * history omit `limit` (the `maxFiles` cap still applies).
+ *
+ * @module providers/rolloutWalker
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = void 0;
+exports.isRolloutFile = isRolloutFile;
+exports.extractRolloutSessionId = extractRolloutSessionId;
+exports.walkRolloutFiles = walkRolloutFiles;
+exports.walkRolloutFilesAsync = walkRolloutFilesAsync;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = 6;
+exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = 20_000;
+/** Test if a filename is a Codex rollout file. */
+function isRolloutFile(filename) {
+    return filename.startsWith('rollout-') && filename.endsWith('.jsonl');
+}
+/**
+ * Extract the session UUID from a rollout filename.
+ * Format: rollout-<timestamp>-<uuid>.jsonl -> <uuid>
+ */
+function extractRolloutSessionId(filename) {
+    const base = path.basename(filename, '.jsonl');
+    // rollout-YYYYMMDD-HHMMSS-<uuid> or rollout-<timestamp>-<uuid>
+    const parts = base.split('-');
+    // The UUID is typically the last 5 segments (8-4-4-4-12)
+    if (parts.length >= 6) {
+        const possibleUuid = parts.slice(-5).join('-');
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(possibleUuid)) {
+            return possibleUuid;
+        }
+    }
+    // Fallback: use everything after "rollout-"
+    return base.replace(/^rollout-/, '');
+}
+function walkState(options) {
+    const maxFiles = Math.max(0, options.maxFiles ?? exports.DEFAULT_ROLLOUT_WALK_MAX_FILES);
+    const limit = options.limit === undefined ? Infinity : Math.max(0, options.limit);
+    return {
+        results: [],
+        seen: new Set(),
+        cap: Math.min(maxFiles, limit),
+        maxDepth: options.maxDepth ?? exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH,
+        sessionId: options.sessionId ? options.sessionId.trim().toLowerCase() : null,
+        includeEmpty: options.includeEmpty ?? false,
+    };
+}
+/** Newest-dated first: directory and file names sort descending. */
+function byNameDescending(a, b) {
+    return b.name.localeCompare(a.name);
+}
+function matchesFilter(state, name) {
+    if (!isRolloutFile(name))
+        return false;
+    return (state.sessionId === null || extractRolloutSessionId(name).toLowerCase() === state.sessionId);
+}
+function record(state, fullPath, name, stat) {
+    if (!state.includeEmpty && stat.size <= 0)
+        return;
+    if (state.seen.has(fullPath))
+        return;
+    state.seen.add(fullPath);
+    state.results.push({
+        path: fullPath,
+        mtime: stat.mtime,
+        sizeBytes: stat.size,
+        sessionId: extractRolloutSessionId(name),
+    });
+}
+function finish(state) {
+    return state.results.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+}
+function visitSync(state, dir, depth) {
+    if (depth > state.maxDepth || state.results.length >= state.cap)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort(byNameDescending);
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (!entry.isFile() || !matchesFilter(state, entry.name))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            record(state, fullPath, entry.name, fs.statSync(fullPath));
+        }
+        catch {
+            // Skip files that vanish between readdir and stat.
+        }
+    }
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (entry.isDirectory())
+            visitSync(state, path.join(dir, entry.name), depth + 1);
+    }
+}
+/**
+ * Walk one or more `sessions` roots for rollout files, newest first.
+ * Missing or unreadable directories are skipped; paths are deduplicated.
+ */
+function walkRolloutFiles(roots, options = {}) {
+    const state = walkState(options);
+    for (const root of roots)
+        visitSync(state, root, 0);
+    return finish(state);
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+async function visitAsync(state, dir, depth) {
+    if (depth > state.maxDepth || state.results.length >= state.cap)
+        return;
+    let entries;
+    try {
+        entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort(byNameDescending);
+    let sinceYield = 0;
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (!entry.isFile() || !matchesFilter(state, entry.name))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            record(state, fullPath, entry.name, await fs.promises.stat(fullPath));
+        }
+        catch {
+            // Skip files that vanish between readdir and stat.
+        }
+        if (++sinceYield >= 200) {
+            sinceYield = 0;
+            await yieldToEventLoop();
+        }
+    }
+    await yieldToEventLoop();
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (entry.isDirectory())
+            await visitAsync(state, path.join(dir, entry.name), depth + 1);
+    }
+}
+/** Async twin of {@link walkRolloutFiles} that yields between directories. */
+async function walkRolloutFilesAsync(roots, options = {}) {
+    const state = walkState(options);
+    for (const root of roots)
+        await visitAsync(state, root, 0);
+    return finish(state);
+}

package/dist/providers/types.d.ts

@@ -10,7 +10,32 @@
  */
 import type { ReadSessionContextSnapshotOptions, SessionContextSnapshot } from '../context/sessionContext';
 import type { SessionEvent, SubagentStats, TokenUsage, ContextAttribution } from '../types/sessionEvent';
-export type ProviderId = 'claude-code' | 'opencode' | 'codex';
+import { SESSION_PROVIDER_IDS } from '../providerIds';
+import type { AggregatedCostProvenance } from '../aggregation/types';
+/** Stable runtime list for consumers that must enumerate session providers. */
+export { SESSION_PROVIDER_IDS } from '../providerIds';
+export type ProviderId = (typeof SESSION_PROVIDER_IDS)[number];
+export type SessionProviderDiagnosticSeverity = 'info' | 'warning' | 'error';
+export type SessionProviderDiagnosticPhase = 'construct' | 'initialize' | 'enumerate' | 'query' | 'read' | 'watch';
+export type SessionProviderDiagnosticKind = 'construction_failed' | 'home_unavailable' | 'config_unreadable' | 'db_missing' | 'sqlite_missing' | 'sqlite_blocked' | 'query_failed' | 'read_failed' | 'watch_failed';
+/** Content-safe provider degradation emitted at construction or first use. */
+export interface SessionProviderDiagnostic {
+    providerId: ProviderId;
+    kind: SessionProviderDiagnosticKind;
+    severity: SessionProviderDiagnosticSeverity;
+    phase: SessionProviderDiagnosticPhase;
+    message: string;
+}
+export interface ProviderOperationStatus {
+    operation: string;
+    usable: boolean;
+    degraded: boolean;
+    runtimeStatus: ProviderRuntimeStatus;
+    diagnostics: readonly SessionProviderDiagnostic[];
+}
+export interface SessionProviderOptions {
+    onDiagnostic?: (diagnostic: SessionProviderDiagnostic) => void;
+}
 export interface SearchHit {
     sessionPath: string;
     line: string;
@@ -25,7 +50,21 @@ export interface SessionFileInfo {
     mtime: Date;
     /** Optional human-readable label (e.g., first user prompt) */
     label?: string;
+    /** Optional size supplied by synthetic/DB-backed enumerators. */
+    sizeBytes?: number;
+    /** Optional provider-native session id. */
+    sessionId?: string;
+    /** Optional provider-recorded workspace path. */
+    workspacePath?: string;
+    /** Optional provider-recorded creation timestamp. */
+    createdAt?: Date;
 }
+/** How much of a session `readSessionStats()` could read. */
+export type SessionFileStatsAvailability = 'full' | 'partial' | 'unavailable';
+/**
+ * Aggregated stats for one session file, computed by `computeSessionFileStats()`
+ * over the shared `EventAggregator` for every provider.
+ */
 export interface SessionFileStats {
     providerId: ProviderId;
     sessionId: string;
@@ -34,19 +73,42 @@ export interface SessionFileStats {
     startTime: string;
     endTime: string;
     messageCount: number;
+    /** Token buckets; `summarizeTokens()` turns them into the cache-inclusive total. */
     tokens: {
         input: number;
         output: number;
         cacheWrite: number;
         cacheRead: number;
     };
+    /**
+     * Per-model calls, cache-inclusive token total (the `summarizeTokens().total`
+     * vocabulary), priced cost, and whether every call could be priced.
+     */
     modelUsage: Record<string, {
         calls: number;
         tokens: number;
+        costUsd: number;
+        priced: boolean;
     }>;
+    /** Calls per tool name: successful, failed, and still pending. */
     toolUsage: Record<string, number>;
+    /** Failed calls per tool name; a subset of `toolUsage`. */
+    toolFailures: Record<string, number>;
     compactionEstimate: number;
     truncationCount: number;
+    /** Cost of the priced portion of the session; read `costProvenance` before labelling it. */
+    costUsd: number;
+    costProvenance: AggregatedCostProvenance;
+    /** Usage events with neither a provider-reported cost nor a catalog price. */
+    unpricedCalls: number;
+    /**
+     * `full` when every event was read, `partial` when the reader reported a
+     * truncated source, `unavailable` when the session could not be read at all
+     * (`unavailableReason` says why and every number is zero).
+     */
+    availability: SessionFileStatsAvailability;
+    unavailableReason?: string;
+    /** @deprecated Same value as `costUsd`; use it together with `costProvenance`. */
     reportedCost: number;
 }
 export interface ProjectFolderInfo {
@@ -58,7 +120,7 @@ export interface ProjectFolderInfo {
 }
 export interface ProviderRuntimeStatus {
     available: boolean;
-    kind: 'available' | 'db_missing' | 'sqlite_missing' | 'sqlite_blocked' | 'query_failed';
+    kind: 'available' | 'home_unavailable' | 'config_unreadable' | 'db_missing' | 'sqlite_missing' | 'sqlite_blocked' | 'query_failed';
     message?: string;
 }
 /**
@@ -105,6 +167,12 @@ export interface SessionProviderBase {
     findActiveSession(workspacePath: string): string | null;
     /** Finds all session files for a workspace, sorted by mtime (most recent first). */
     findAllSessions(workspacePath: string): string[];
+    /**
+     * Finds one session without reading every transcript. Wrong ids return null.
+     * Optional so pre-0.25 external implementations keep compiling; when absent,
+     * callers fall back to scanning findAllSessions().
+     */
+    findSessionById?(workspacePath: string, sessionId: string): string | null;
     /** Finds all session files in a specific directory. */
     findSessionsInDirectory(dir: string): string[];
     /** Gets all project folders with session data. */
@@ -131,6 +199,12 @@ export interface SessionProviderBase {
     getSessionMetadata?(sessionPath: string): {
         mtime: Date;
     } | null;
+    /** Event-loop-safe metadata refresh for synthetic/DB-backed session paths. */
+    getSessionMetadataAsync?(sessionPath: string): Promise<{
+        mtime: Date;
+    } | null>;
+    /** Roots whose changes can invalidate this provider's session fingerprints. */
+    getWatchRoots?(): string[];
     /** Gets the context window token limit for a model. Returns 200K by default. */
     getContextWindowLimit?(modelId?: string): number;
     /** Computes context window size from token usage. Provider-specific formula. */
@@ -143,11 +217,17 @@ export interface SessionProviderBase {
     readSessionContextSnapshot?(sessionPath: string, options?: ReadSessionContextSnapshotOptions): SessionContextSnapshot;
     /** Reports provider runtime readiness for DB-backed providers. */
     getRuntimeStatus?(): ProviderRuntimeStatus;
+    /** Status for the most recent provider operation, including fallback diagnostics. */
+    getLastOperationStatus?(): ProviderOperationStatus;
     /**
      * Lists every session file this provider knows about, across all workspaces.
      * Stat-only — implementations must not read file contents.
      */
     listAllSessionFiles?(): SessionFileInfo[];
+    /** Event-loop-safe enumeration used by async preview and subscription APIs. */
+    listSessionFilesAsync?(workspacePath?: string): Promise<SessionFileInfo[]>;
+    /** Batch label extraction. DB-backed implementations use at most one query. */
+    extractSessionLabelsAsync?(sessionPaths: readonly string[]): Promise<Map<string, string | null>>;
     /** Tests whether a provider can monitor a directory path, including synthetic DB-backed paths. */
     canMonitorDirectory?(dir: string): boolean;
     /** Release resources. */

package/dist/providers/types.js

@@ -10,3 +10,7 @@
  * compatibility with existing CLI code.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_PROVIDER_IDS = void 0;
+/** Stable runtime list for consumers that must enumerate session providers. */
+var providerIds_1 = require("../providerIds");
+Object.defineProperty(exports, "SESSION_PROVIDER_IDS", { enumerable: true, get: function () { return providerIds_1.SESSION_PROVIDER_IDS; } });

package/dist/quota.d.ts

@@ -1,3 +1,6 @@
+import type { QuotaProviderId } from './providerIds';
+export { QUOTA_PROVIDER_IDS } from './providerIds';
+export type { QuotaProviderId } from './providerIds';
 /**
  * Stateless quota fetcher for Claude Max subscription usage.
  *
@@ -42,13 +45,27 @@ export interface QuotaState {
     /** Projected 7-day utilization at reset (percentage, capped at 200) */
     projectedSevenDay?: number;
     /** Provider that produced this quota sample */
-    providerId?: 'claude-code' | 'codex' | 'zai';
-    /** Source of the sample */
-    source?: 'api' | 'session' | 'cache';
+    providerId?: QuotaProviderId;
+    /**
+     * 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 */
@@ -68,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;
@@ -92,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,20 +1,46 @@
 "use strict";
-/**
- * Stateless quota fetcher for Claude Max subscription usage.
- *
- * Calls the Anthropic OAuth usage endpoint and returns utilization data.
- * Polling / eventing is the caller's responsibility.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEVEN_DAY_WINDOW_MS = exports.FIVE_HOUR_WINDOW_MS = 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;
+var providerIds_1 = require("./providerIds");
+Object.defineProperty(exports, "QUOTA_PROVIDER_IDS", { enumerable: true, get: function () { return providerIds_1.QUOTA_PROVIDER_IDS; } });
 const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 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.
  *
@@ -92,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: {