sidekick-shared 0.18.2 → 0.18.3

package/dist/codexQuotaWatcher.d.ts

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import type { FSWatcher } from 'fs';
+import type { QuotaHistorySample } from './quotaHistory';
 import { CodexProvider } from './providers/codex';
 import type { SavedAccountProfile } from './accountRegistry';
 import type { Disposable } from './quotaPoller';
@@ -8,6 +9,7 @@ import type { ProviderQuotaState } from './providerQuota';
 type CodexAccountReader = () => SavedAccountProfile | null;
 type SnapshotReader = (providerId: 'codex', accountId: string) => QuotaState | null;
 type SnapshotWriter = (providerId: 'codex', accountId: string, quota: QuotaState) => void;
+type HistoryAppender = (sample: QuotaHistorySample) => void | Promise<void>;
 type WatchFile = (filename: fs.PathLike, listener: fs.WatchListener<string>) => FSWatcher;
 export interface CodexQuotaWatcherOptions {
     discoveryPollIntervalMs?: number;
@@ -18,6 +20,10 @@ export interface CodexQuotaWatcherOptions {
     readSnapshot?: SnapshotReader;
     writeSnapshot?: SnapshotWriter;
     watchFile?: WatchFile;
+    /** Stable workspace identifier. When provided, live quotas are appended to the per-workspace history JSONL. */
+    workspaceId?: string;
+    /** Override the history append function (used by tests). Default: `appendQuotaHistorySample`. */
+    appendHistorySample?: HistoryAppender;
 }
 /**
  * Watches the active Codex rollout for quota snapshots and falls back to the
@@ -33,6 +39,8 @@ export declare class CodexQuotaWatcher implements Disposable {
     private readonly watchFile;
     private readonly maxTailBytes;
     private readonly maxSessionFiles;
+    private readonly workspaceId;
+    private readonly appendHistorySample;
     private readonly listeners;
     private discoveryTimer;
     private provider;

package/dist/codexQuotaWatcher.js

@@ -38,6 +38,7 @@ const fs = __importStar(require("fs"));
 const codexProfiles_1 = require("./codexProfiles");
 const codexQuota_1 = require("./codexQuota");
 const quotaSnapshots_1 = require("./quotaSnapshots");
+const quotaHistory_1 = require("./quotaHistory");
 const codex_1 = require("./providers/codex");
 const DEFAULT_DISCOVERY_POLL_INTERVAL_MS = 30_000;
 function accountEmail(account) {
@@ -80,6 +81,8 @@ class CodexQuotaWatcher {
     watchFile;
     maxTailBytes;
     maxSessionFiles;
+    workspaceId;
+    appendHistorySample;
     listeners = [];
     discoveryTimer;
     provider = null;
@@ -98,6 +101,8 @@ class CodexQuotaWatcher {
         this.watchFile = options.watchFile ?? fs.watch;
         this.maxTailBytes = options.maxTailBytes;
         this.maxSessionFiles = options.maxSessionFiles;
+        this.workspaceId = options.workspaceId;
+        this.appendHistorySample = options.appendHistorySample ?? quotaHistory_1.appendQuotaHistorySample;
     }
     start() {
         if (this.running)
@@ -196,6 +201,31 @@ class CodexQuotaWatcher {
         const account = this.getActiveAccount();
         if (account) {
             this.writeSnapshot('codex', account.id, liveQuota);
+            if (this.workspaceId) {
+                const sample = {
+                    timestamp: liveQuota.capturedAt ?? new Date().toISOString(),
+                    runtimeProvider: 'codex',
+                    providerId: account.id,
+                    workspaceId: this.workspaceId,
+                    fiveHour: { utilization: liveQuota.fiveHour.utilization, resetsAt: liveQuota.fiveHour.resetsAt },
+                    sevenDay: { utilization: liveQuota.sevenDay.utilization, resetsAt: liveQuota.sevenDay.resetsAt },
+                    available: liveQuota.available,
+                    error: liveQuota.error,
+                    source: liveQuota.source,
+                    stale: liveQuota.stale,
+                };
+                try {
+                    const result = this.appendHistorySample(sample);
+                    if (result && typeof result.catch === 'function') {
+                        result.catch(() => {
+                            // History append must never break the live emission path.
+                        });
+                    }
+                }
+                catch {
+                    // Synchronous errors swallowed for the same reason.
+                }
+            }
         }
         this.emitState(enrichQuotaState({
             ...liveQuota,

package/dist/index.d.ts

@@ -104,6 +104,8 @@ export type { QuotaFailureDescriptor } from './quotaPresentation';
 export { QuotaPoller } from './quotaPoller';
 export type { QuotaPollerOptions } from './quotaPoller';
 export { readQuotaSnapshot, writeQuotaSnapshot } from './quotaSnapshots';
+export { appendQuotaHistorySample, readQuotaHistoryRange, readQuotaHistoryDailyBuckets, pruneQuotaHistory, getWorkspaceIdFromPath, } from './quotaHistory';
+export type { QuotaHistorySample, QuotaHistoryAppendOptions, QuotaHistoryRangeOptions, QuotaHistoryDailyBucket, QuotaHistoryRuntimeProvider, } from './quotaHistory';
 export { fetchCodexQuotaFromApi, quotaFromCodexRateLimits, readLatestCodexQuotaFromRollouts, resolveCodexQuota, resolveCodexQuotaFromLocalSources, } from './codexQuota';
 export type { CodexQuotaApiOptions, CodexQuotaCreditsSnapshot, CodexQuotaResolveOptions, CodexQuotaResolveSource, } from './codexQuota';
 export { CodexQuotaWatcher } from './codexQuotaWatcher';

package/dist/index.js

@@ -5,8 +5,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findActiveClaudeSession = exports.discoverSessionDirectory = exports.getClaudeSessionDirectory = exports.encodeClaudeWorkspacePath = exports.detectSessionActivity = exports.extractTaskInfo = exports.scanSubagentDir = exports.normalizeCodexToolInput = exports.normalizeCodexToolName = exports.extractPatchFilePaths = exports.CodexRolloutParser = exports.parseDbPartData = exports.parseDbMessageData = exports.convertOpenCodeMessage = exports.detectPlanModeFromText = exports.normalizeToolInput = exports.normalizeToolName = exports.TRUNCATION_PATTERNS = exports.JsonlParser = exports.CodexProvider = exports.OpenCodeProvider = exports.ClaudeCodeProvider = exports.getAllDetectedProviders = exports.detectProvider = exports.readClaudeCodePlanFiles = exports.getPlanAnalytics = exports.writePlans = exports.getLatestPlan = exports.readPlans = exports.readLatestHandoff = exports.readHistory = exports.readNotes = exports.readDecisions = exports.readTasks = exports.getProjectSlugRaw = exports.getProjectSlug = exports.encodeWorkspacePath = exports.getGlobalDataPath = exports.getProjectDataPath = exports.getConfigDir = exports.MAX_PLANS_PER_PROJECT = exports.PLAN_SCHEMA_VERSION = exports.createEmptyTokenTotals = exports.HISTORICAL_DATA_SCHEMA_VERSION = exports.STALENESS_THRESHOLDS = exports.IMPORTANCE_DECAY_FACTORS = exports.KNOWLEDGE_NOTE_SCHEMA_VERSION = exports.DECISION_LOG_SCHEMA_VERSION = exports.normalizeTaskStatus = exports.TASK_PERSISTENCE_SCHEMA_VERSION = void 0;
 exports.deleteSnapshot = exports.loadSnapshot = exports.saveSnapshot = exports.parseTodoDependencies = exports.EventAggregator = exports.getRandomPhrase = exports.PHRASE_CATEGORIES = exports.ALL_PHRASES = exports.HIGHLIGHT_CSS = exports.clearHighlightCache = exports.highlightEvent = exports.formatSessionJson = exports.formatSessionMarkdown = exports.formatSessionText = exports.classifyNoise = exports.shouldMergeWithPrevious = exports.classifyFollowEvent = exports.classifyMessage = exports.getSoftNoiseReason = exports.isHardNoiseFollowEvent = exports.isHardNoise = exports.formatToolSummary = exports.formatTokenCount = exports.formatDurationMs = exports.createJsonlTail = exports.toFollowEvents = exports.createWatcher = exports.parseChangelog = exports.extractProposedPlanShared = exports.parsePlanMarkdownShared = exports.PlanExtractor = exports.composeContext = exports.FilterEngine = exports.searchSessions = exports.CodexDatabase = exports.OpenCodeDatabase = exports.discoverDebugLogs = exports.collapseDuplicates = exports.filterByLevel = exports.parseDebugLog = exports.scanSubagentTraces = exports.findAllSessionsWithWorktrees = exports.discoverWorktreeSiblings = exports.resolveWorktreeMainRepo = exports.getAllClaudeProjectFolders = exports.decodeEncodedPath = exports.getMostRecentlyActiveSessionDir = exports.findSubdirectorySessionDirs = exports.findSessionsInDirectory = exports.findAllClaudeSessions = void 0;
-exports.fetchCodexQuotaFromApi = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.QuotaPoller = exports.describeQuotaFailure = exports.fetchQuota = exports.removeCodexAccount = exports.switchToCodexAccount = exports.finalizeCodexAccount = exports.prepareCodexAccount = exports.getCodexExecutionEnv = exports.resolveSidekickCodexHome = exports.getActiveCodexAccount = exports.listCodexAccounts = exports.getSystemCodexHome = exports.getCodexMonitoringHomes = exports.getCodexProfileHome = exports.getCodexProfilesDir = exports.getActiveAccountStatus = exports.removeSavedAccountProfile = exports.replaceSavedAccountProfiles = exports.setActiveSavedAccount = exports.upsertSavedAccountProfile = exports.getActiveSavedAccount = exports.listSavedAccountProfiles = exports.writeSavedAccountRegistry = exports.readSavedAccountRegistry = exports.getAccountsDir = exports.isMultiAccountEnabled = exports.getActiveAccount = exports.listAccounts = exports.removeAccount = exports.switchToAccount = exports.addCurrentAccount = exports.readActiveClaudeAccount = exports.writeAccountRegistry = exports.readAccountRegistry = exports.ensureDefaultAccounts = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.writeActiveCredentials = exports.readActiveCredentials = exports.openInBrowser = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = exports.HeatmapTracker = exports.FrequencyTracker = exports.getSnapshotPath = exports.isSnapshotValid = void 0;
-exports.fetchPeakHoursStatus = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.extractToolCalls = exports.extractToolCall = exports.extractTokenUsage = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.parseModelId = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = exports.MultiProviderQuotaService = exports.CodexQuotaWatcher = exports.resolveCodexQuotaFromLocalSources = exports.resolveCodexQuota = exports.readLatestCodexQuotaFromRollouts = exports.quotaFromCodexRateLimits = void 0;
+exports.appendQuotaHistorySample = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.QuotaPoller = exports.describeQuotaFailure = exports.fetchQuota = exports.removeCodexAccount = exports.switchToCodexAccount = exports.finalizeCodexAccount = exports.prepareCodexAccount = exports.getCodexExecutionEnv = exports.resolveSidekickCodexHome = exports.getActiveCodexAccount = exports.listCodexAccounts = exports.getSystemCodexHome = exports.getCodexMonitoringHomes = exports.getCodexProfileHome = exports.getCodexProfilesDir = exports.getActiveAccountStatus = exports.removeSavedAccountProfile = exports.replaceSavedAccountProfiles = exports.setActiveSavedAccount = exports.upsertSavedAccountProfile = exports.getActiveSavedAccount = exports.listSavedAccountProfiles = exports.writeSavedAccountRegistry = exports.readSavedAccountRegistry = exports.getAccountsDir = exports.isMultiAccountEnabled = exports.getActiveAccount = exports.listAccounts = exports.removeAccount = exports.switchToAccount = exports.addCurrentAccount = exports.readActiveClaudeAccount = exports.writeAccountRegistry = exports.readAccountRegistry = exports.ensureDefaultAccounts = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.writeActiveCredentials = exports.readActiveCredentials = exports.openInBrowser = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = exports.HeatmapTracker = exports.FrequencyTracker = exports.getSnapshotPath = exports.isSnapshotValid = void 0;
+exports.fetchPeakHoursStatus = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.extractToolCalls = exports.extractToolCall = exports.extractTokenUsage = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.parseModelId = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = exports.MultiProviderQuotaService = exports.CodexQuotaWatcher = exports.resolveCodexQuotaFromLocalSources = exports.resolveCodexQuota = exports.readLatestCodexQuotaFromRollouts = exports.quotaFromCodexRateLimits = exports.fetchCodexQuotaFromApi = exports.getWorkspaceIdFromPath = exports.pruneQuotaHistory = exports.readQuotaHistoryDailyBuckets = exports.readQuotaHistoryRange = void 0;
 var taskPersistence_1 = require("./types/taskPersistence");
 Object.defineProperty(exports, "TASK_PERSISTENCE_SCHEMA_VERSION", { enumerable: true, get: function () { return taskPersistence_1.TASK_PERSISTENCE_SCHEMA_VERSION; } });
 Object.defineProperty(exports, "normalizeTaskStatus", { enumerable: true, get: function () { return taskPersistence_1.normalizeTaskStatus; } });
@@ -237,6 +237,12 @@ Object.defineProperty(exports, "QuotaPoller", { enumerable: true, get: function
 var quotaSnapshots_1 = require("./quotaSnapshots");
 Object.defineProperty(exports, "readQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.readQuotaSnapshot; } });
 Object.defineProperty(exports, "writeQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.writeQuotaSnapshot; } });
+var quotaHistory_1 = require("./quotaHistory");
+Object.defineProperty(exports, "appendQuotaHistorySample", { enumerable: true, get: function () { return quotaHistory_1.appendQuotaHistorySample; } });
+Object.defineProperty(exports, "readQuotaHistoryRange", { enumerable: true, get: function () { return quotaHistory_1.readQuotaHistoryRange; } });
+Object.defineProperty(exports, "readQuotaHistoryDailyBuckets", { enumerable: true, get: function () { return quotaHistory_1.readQuotaHistoryDailyBuckets; } });
+Object.defineProperty(exports, "pruneQuotaHistory", { enumerable: true, get: function () { return quotaHistory_1.pruneQuotaHistory; } });
+Object.defineProperty(exports, "getWorkspaceIdFromPath", { enumerable: true, get: function () { return quotaHistory_1.getWorkspaceIdFromPath; } });
 var codexQuota_1 = require("./codexQuota");
 Object.defineProperty(exports, "fetchCodexQuotaFromApi", { enumerable: true, get: function () { return codexQuota_1.fetchCodexQuotaFromApi; } });
 Object.defineProperty(exports, "quotaFromCodexRateLimits", { enumerable: true, get: function () { return codexQuota_1.quotaFromCodexRateLimits; } });

package/dist/quotaHistory.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Append-only JSONL history of quota samples, scoped per workspace and per runtime provider.
+ *
+ * Sibling to `quotaSnapshots.ts`. Where snapshots persist a single most-recent sample per
+ * (provider, account), this module accumulates time-series samples so consumers (the VS Code
+ * dashboard, the `sidekick quota history` CLI, contextful_desktop) can render heatmaps and
+ * trend visualisations over a 13-week window.
+ */
+export type QuotaHistoryRuntimeProvider = 'claude' | 'codex';
+export interface QuotaHistorySample {
+    timestamp: string;
+    runtimeProvider: QuotaHistoryRuntimeProvider;
+    providerId: string;
+    workspaceId: string;
+    fiveHour: {
+        utilization: number;
+        resetsAt: string;
+    };
+    sevenDay: {
+        utilization: number;
+        resetsAt: string;
+    };
+    available: boolean;
+    error?: string;
+    source?: 'session' | 'cache' | 'api';
+    stale?: boolean;
+}
+export interface QuotaHistoryAppendOptions {
+    /** Drop the sample if the most recent in-store sample is younger than this many ms. Default: 60_000. */
+    minIntervalMs?: number;
+    /** Retention window in days. Default: 91 (13 weeks). */
+    retentionDays?: number;
+}
+export interface QuotaHistoryRangeOptions {
+    workspaceId: string;
+    provider: QuotaHistoryRuntimeProvider;
+    /** Inclusive ISO start. Default: 13 weeks ago. */
+    from?: string;
+    /** Inclusive ISO end. Default: now. */
+    to?: string;
+}
+export interface QuotaHistoryDailyBucket {
+    date: string;
+    samples: number;
+    maxUtilizationFiveHour: number;
+    maxUtilizationSevenDay: number;
+    avgUtilizationFiveHour: number;
+    avgUtilizationSevenDay: number;
+    anyUnavailable: boolean;
+}
+/**
+ * Stable, opaque workspace identifier — first 16 hex chars of sha256(realpath).
+ * Shared between the VS Code extension (workspace folder fsPath) and the CLI (process.cwd()).
+ */
+export declare function getWorkspaceIdFromPath(workspacePath: string): string;
+export declare function appendQuotaHistorySample(sample: QuotaHistorySample, options?: QuotaHistoryAppendOptions): Promise<void>;
+export declare function readQuotaHistoryRange(options: QuotaHistoryRangeOptions): Promise<QuotaHistorySample[]>;
+export declare function readQuotaHistoryDailyBuckets(options: QuotaHistoryRangeOptions): Promise<QuotaHistoryDailyBucket[]>;
+export declare function pruneQuotaHistory(workspaceId: string, provider: QuotaHistoryRuntimeProvider, retentionDays?: number): Promise<{
+    kept: number;
+    pruned: number;
+}>;
+/** Test-only: wipe the in-memory mutex/debounce state. Not exported from index.ts. */
+export declare function _resetQuotaHistoryInMemoryStateForTests(): void;

package/dist/quotaHistory.js

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * Append-only JSONL history of quota samples, scoped per workspace and per runtime provider.
+ *
+ * Sibling to `quotaSnapshots.ts`. Where snapshots persist a single most-recent sample per
+ * (provider, account), this module accumulates time-series samples so consumers (the VS Code
+ * dashboard, the `sidekick quota history` CLI, contextful_desktop) can render heatmaps and
+ * trend visualisations over a 13-week window.
+ */
+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.getWorkspaceIdFromPath = getWorkspaceIdFromPath;
+exports.appendQuotaHistorySample = appendQuotaHistorySample;
+exports.readQuotaHistoryRange = readQuotaHistoryRange;
+exports.readQuotaHistoryDailyBuckets = readQuotaHistoryDailyBuckets;
+exports.pruneQuotaHistory = pruneQuotaHistory;
+exports._resetQuotaHistoryInMemoryStateForTests = _resetQuotaHistoryInMemoryStateForTests;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const paths_1 = require("./paths");
+const quotaSnapshots_1 = require("./quotaSnapshots");
+const DEFAULT_MIN_INTERVAL_MS = 60_000;
+const DEFAULT_RETENTION_DAYS = 91;
+const PRUNE_FILESIZE_THRESHOLD = 16 * 1024;
+const MS_PER_DAY = 86_400_000;
+/** Per-file append serialization across in-process callers. */
+const appendChains = new Map();
+/** Per-file last-write timestamp cache, used for the debounce check. */
+const lastWriteCache = new Map();
+/**
+ * Stable, opaque workspace identifier — first 16 hex chars of sha256(realpath).
+ * Shared between the VS Code extension (workspace folder fsPath) and the CLI (process.cwd()).
+ */
+function getWorkspaceIdFromPath(workspacePath) {
+    let resolved;
+    try {
+        resolved = fs.realpathSync(workspacePath);
+    }
+    catch {
+        resolved = path.resolve(workspacePath);
+    }
+    return crypto.createHash('sha256').update(resolved).digest('hex').slice(0, 16);
+}
+function getHistoryFilePath(workspaceId, provider) {
+    return path.join((0, paths_1.getConfigDir)(), 'quota-history', workspaceId, `${provider}.jsonl`);
+}
+function ensureHistoryDir(workspaceId) {
+    fs.mkdirSync(path.join((0, paths_1.getConfigDir)(), 'quota-history', workspaceId), { recursive: true, mode: 0o700 });
+}
+function parseSampleLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.timestamp === 'string' &&
+            parsed.fiveHour &&
+            parsed.sevenDay) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLastSampleTimestampMs(filePath) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        if (stat.size === 0)
+            return null;
+        const chunkSize = 4096;
+        let remaining = stat.size;
+        let buffer = Buffer.alloc(0);
+        while (remaining > 0) {
+            const readSize = Math.min(chunkSize, remaining);
+            const chunk = Buffer.alloc(readSize);
+            fs.readSync(fd, chunk, 0, readSize, remaining - readSize);
+            buffer = Buffer.concat([chunk, buffer]);
+            remaining -= readSize;
+            const text = buffer.toString('utf8');
+            // Look for the last newline that's not at end-of-text — that's the boundary of the final record.
+            const trimmedRight = text.replace(/\n+$/, '');
+            const lastNewline = trimmedRight.lastIndexOf('\n');
+            if (lastNewline >= 0) {
+                const lastLine = trimmedRight.slice(lastNewline + 1);
+                const sample = parseSampleLine(lastLine);
+                return sample ? Date.parse(sample.timestamp) || null : null;
+            }
+            if (remaining === 0) {
+                const sample = parseSampleLine(trimmedRight);
+                return sample ? Date.parse(sample.timestamp) || null : null;
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // best effort
+            }
+        }
+    }
+}
+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;
+    }
+}
+function pruneFileSync(filePath, retentionDays) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        return { kept: 0, pruned: 0 };
+    }
+    if (stat.size === 0)
+        return { kept: 0, pruned: 0 };
+    const cutoffMs = Date.now() - retentionDays * MS_PER_DAY;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const lines = raw.split('\n');
+    const keptLines = [];
+    let pruned = 0;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const sample = parseSampleLine(line);
+        if (!sample) {
+            // Drop malformed lines during prune so the file self-heals.
+            pruned += 1;
+            continue;
+        }
+        const ts = Date.parse(sample.timestamp);
+        if (Number.isFinite(ts) && ts >= cutoffMs) {
+            keptLines.push(line);
+        }
+        else {
+            pruned += 1;
+        }
+    }
+    if (pruned > 0) {
+        atomicRewriteFile(filePath, keptLines.length > 0 ? keptLines.join('\n') + '\n' : '');
+    }
+    return { kept: keptLines.length, pruned };
+}
+function sampleToQuotaState(sample) {
+    const providerId = sample.runtimeProvider === 'claude' ? 'claude-code' : 'codex';
+    return {
+        fiveHour: { utilization: sample.fiveHour.utilization, resetsAt: sample.fiveHour.resetsAt },
+        sevenDay: { utilization: sample.sevenDay.utilization, resetsAt: sample.sevenDay.resetsAt },
+        available: sample.available,
+        error: sample.error,
+        providerId,
+        source: sample.source ?? 'session',
+        capturedAt: sample.timestamp,
+        stale: sample.stale,
+    };
+}
+async function runAppend(sample, filePath, options) {
+    let lastTs = lastWriteCache.get(filePath);
+    if (lastTs === undefined) {
+        const fromDisk = readLastSampleTimestampMs(filePath);
+        if (fromDisk !== null) {
+            lastTs = fromDisk;
+            lastWriteCache.set(filePath, fromDisk);
+        }
+    }
+    const sampleTs = Date.parse(sample.timestamp);
+    if (lastTs !== undefined && Number.isFinite(sampleTs) && sampleTs - lastTs < options.minIntervalMs) {
+        return;
+    }
+    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);
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Backwards-compat: keep the latest-snapshot store hot so existing callers (DashboardViewProvider,
+    // codex session provider, contextful_desktop) don't have to query history for "latest".
+    try {
+        const providerId = sample.runtimeProvider === 'claude' ? 'claude-code' : 'codex';
+        (0, quotaSnapshots_1.writeQuotaSnapshot)(providerId, sample.providerId, sampleToQuotaState(sample));
+    }
+    catch {
+        // Snapshot write failures must not poison the history append path.
+    }
+}
+async function appendQuotaHistorySample(sample, options = {}) {
+    const resolved = {
+        minIntervalMs: options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS,
+        retentionDays: options.retentionDays ?? DEFAULT_RETENTION_DAYS,
+    };
+    const filePath = getHistoryFilePath(sample.workspaceId, sample.runtimeProvider);
+    const previous = appendChains.get(filePath) ?? Promise.resolve();
+    const next = previous.then(() => runAppend(sample, filePath, resolved)).catch(() => {
+        // Swallow chain-level errors so a single failure doesn't break subsequent appends.
+    });
+    appendChains.set(filePath, next);
+    try {
+        await next;
+    }
+    finally {
+        if (appendChains.get(filePath) === next) {
+            appendChains.delete(filePath);
+        }
+    }
+}
+function defaultRangeMs() {
+    const toMs = Date.now();
+    const fromMs = toMs - DEFAULT_RETENTION_DAYS * MS_PER_DAY;
+    return { fromMs, toMs };
+}
+async function readQuotaHistoryRange(options) {
+    const filePath = getHistoryFilePath(options.workspaceId, options.provider);
+    let raw;
+    try {
+        raw = await fs.promises.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    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 samples = [];
+    for (const line of raw.split('\n')) {
+        const sample = parseSampleLine(line);
+        if (!sample)
+            continue;
+        const ts = Date.parse(sample.timestamp);
+        if (!Number.isFinite(ts))
+            continue;
+        if (ts < fromMs || ts > toMs)
+            continue;
+        samples.push(sample);
+    }
+    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);
+}
+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 grouped = new Map();
+    for (const sample of samples) {
+        const day = sample.timestamp.slice(0, 10);
+        const bucket = grouped.get(day);
+        if (bucket) {
+            bucket.push(sample);
+        }
+        else {
+            grouped.set(day, [sample]);
+        }
+    }
+    const buckets = [];
+    let cursor = startDate;
+    // Safety bound — 26 weeks worst case = 182 days; we cap iteration well above that.
+    for (let i = 0; i <= 366 && cursor <= endDate; i += 1) {
+        const daySamples = grouped.get(cursor);
+        if (!daySamples || daySamples.length === 0) {
+            buckets.push({
+                date: cursor,
+                samples: 0,
+                maxUtilizationFiveHour: 0,
+                maxUtilizationSevenDay: 0,
+                avgUtilizationFiveHour: 0,
+                avgUtilizationSevenDay: 0,
+                anyUnavailable: false,
+            });
+        }
+        else {
+            let maxFive = 0;
+            let maxSeven = 0;
+            let sumFive = 0;
+            let sumSeven = 0;
+            let anyUnavailable = false;
+            for (const s of daySamples) {
+                maxFive = Math.max(maxFive, s.fiveHour.utilization);
+                maxSeven = Math.max(maxSeven, s.sevenDay.utilization);
+                sumFive += s.fiveHour.utilization;
+                sumSeven += s.sevenDay.utilization;
+                if (!s.available)
+                    anyUnavailable = true;
+            }
+            const n = daySamples.length;
+            buckets.push({
+                date: cursor,
+                samples: n,
+                maxUtilizationFiveHour: maxFive,
+                maxUtilizationSevenDay: maxSeven,
+                avgUtilizationFiveHour: Math.round((sumFive / n) * 100) / 100,
+                avgUtilizationSevenDay: Math.round((sumSeven / n) * 100) / 100,
+                anyUnavailable,
+            });
+        }
+        cursor = addDaysUtc(cursor, 1);
+    }
+    return buckets;
+}
+async function pruneQuotaHistory(workspaceId, provider, retentionDays = DEFAULT_RETENTION_DAYS) {
+    const filePath = getHistoryFilePath(workspaceId, provider);
+    return pruneFileSync(filePath, retentionDays);
+}
+/** Test-only: wipe the in-memory mutex/debounce state. Not exported from index.ts. */
+function _resetQuotaHistoryInMemoryStateForTests() {
+    appendChains.clear();
+    lastWriteCache.clear();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",