sidekick-shared 0.25.0 → 0.26.0

package/dist/sessionFingerprint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Size/mtime fingerprints for session sources.
+ *
+ * Shared by the observed-session collector, the V1 adapter's watch loop, and
+ * the usage cache, so "has this session changed?" is answered the same way
+ * everywhere without re-reading content.
+ *
+ * @module sessionFingerprint
+ */
+import type { SessionProviderBase } from './providers/types';
+export interface ObservedSessionFingerprintParts {
+    sizeBytes: number;
+    mtimeMs: number;
+}
+/** Structured size/mtime fingerprint; returns null for inaccessible or synthetic paths. */
+export declare function fileFingerprintParts(sourcePath: string): ObservedSessionFingerprintParts | null;
+/** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
+export declare function fileFingerprint(sourcePath: string): string | null;
+/** Canonical `${sizeBytes}:${mtimeMs}` form of a fingerprint. */
+export declare function fingerprintString(parts: ObservedSessionFingerprintParts): string;
+/**
+ * Fingerprint for a session path, falling back to provider metadata (mtime
+ * only) for database-backed sessions whose path is synthetic.
+ */
+export declare function sessionFingerprintParts(provider: SessionProviderBase, sessionPath: string): ObservedSessionFingerprintParts | null;

package/dist/sessionFingerprint.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Size/mtime fingerprints for session sources.
+ *
+ * Shared by the observed-session collector, the V1 adapter's watch loop, and
+ * the usage cache, so "has this session changed?" is answered the same way
+ * everywhere without re-reading content.
+ *
+ * @module sessionFingerprint
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileFingerprintParts = fileFingerprintParts;
+exports.fileFingerprint = fileFingerprint;
+exports.fingerprintString = fingerprintString;
+exports.sessionFingerprintParts = sessionFingerprintParts;
+const node_fs_1 = require("node:fs");
+/** Structured size/mtime fingerprint; returns null for inaccessible or synthetic paths. */
+function fileFingerprintParts(sourcePath) {
+    try {
+        const stat = (0, node_fs_1.statSync)(sourcePath);
+        return { sizeBytes: stat.size, mtimeMs: stat.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+/** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
+function fileFingerprint(sourcePath) {
+    const parts = fileFingerprintParts(sourcePath);
+    return parts ? fingerprintString(parts) : null;
+}
+/** Canonical `${sizeBytes}:${mtimeMs}` form of a fingerprint. */
+function fingerprintString(parts) {
+    return `${parts.sizeBytes}:${parts.mtimeMs}`;
+}
+/**
+ * Fingerprint for a session path, falling back to provider metadata (mtime
+ * only) for database-backed sessions whose path is synthetic.
+ */
+function sessionFingerprintParts(provider, sessionPath) {
+    const parts = fileFingerprintParts(sessionPath);
+    if (parts)
+        return parts;
+    const metadata = provider.getSessionMetadata?.(sessionPath);
+    return metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null;
+}

package/dist/sessionPreviews.d.ts

@@ -36,7 +36,11 @@ export interface SessionPreview {
     workspacePath: string | null;
 }
 export interface ReadSessionPreviewOptions {
-    /** Byte budget for the generic prefix scan (default 16 KiB). */
+    /**
+     * Byte budget for the generic prefix scan (default 16 KiB). `0` skips the
+     * scan entirely for callers that ignore `firstTimestamp` and
+     * `workspacePath`; both come back `null` and the file is not opened.
+     */
     maxPrefixBytes?: number;
 }
 export interface ListSessionPreviewsOptions extends ReadSessionPreviewOptions {
@@ -64,6 +68,8 @@ export interface SessionPreviewReadResult {
 export interface SessionPreviewListResult {
     previews: SessionPreview[];
     diagnostics: SessionProviderDiagnostic[];
+    /** True when more candidates existed than `limit` allowed; the caller may offer a larger limit. */
+    hasMore: boolean;
 }
 /**
  * Reads a bounded preview of one session file. Returns `null` when the file is

package/dist/sessionPreviews.js

@@ -57,6 +57,9 @@ exports.readSessionPreviewAsync = readSessionPreviewAsync;
 exports.listSessionPreviews = listSessionPreviews;
 exports.listSessionPreviewsAsync = listSessionPreviewsAsync;
 const fs = __importStar(require("fs"));
+function emptyPrefixScan() {
+    return { firstTimestamp: null, workspacePath: null };
+}
 const DEFAULT_PREFIX_BYTES = 16 * 1024;
 const DEFAULT_LIMIT = 50;
 const DEFAULT_CONCURRENCY = 4;
@@ -108,7 +111,8 @@ function readSessionPreview(provider, sessionPath, options = {}) {
     catch {
         // A provider that cannot identify the file still yields a usable preview.
     }
-    const prefix = scanPrefix(sessionPath, options.maxPrefixBytes ?? DEFAULT_PREFIX_BYTES);
+    const prefixBudget = options.maxPrefixBytes ?? DEFAULT_PREFIX_BYTES;
+    const prefix = prefixBudget > 0 ? scanPrefix(sessionPath, prefixBudget) : emptyPrefixScan();
     return {
         provider: provider.id,
         sessionId,
@@ -238,6 +242,7 @@ async function listSessionPreviewsAsync(providers, options = {}) {
     }, concurrency(options));
     return {
         previews: previews.filter((preview) => preview !== null),
+        hasMore: candidates.length > limit,
         diagnostics: dedupeDiagnostics([
             ...operationDiagnostics,
             ...providers.flatMap(providerDiagnostics),
@@ -248,7 +253,13 @@ function resolveSinceMs(since) {
     if (since === undefined)
         return null;
     const ms = since instanceof Date ? since.getTime() : Date.parse(since);
-    return Number.isFinite(ms) ? ms : null;
+    if (!Number.isFinite(ms)) {
+        // An unparseable cutoff used to mean "no cutoff", silently returning
+        // every session. Fail loudly instead so a typo cannot masquerade as a
+        // full listing.
+        throw new RangeError(`Invalid \`since\` value: ${String(since)}`);
+    }
+    return ms;
 }
 function enumerateSessionFiles(provider, workspacePath) {
     try {
@@ -359,7 +370,8 @@ async function readSessionPreviewFromInfoAsync(provider, info, firstUserPrompt,
     catch {
         return null;
     }
-    const prefix = await scanPrefixAsync(info.path, options.maxPrefixBytes ?? DEFAULT_PREFIX_BYTES);
+    const prefixBudget = options.maxPrefixBytes ?? DEFAULT_PREFIX_BYTES;
+    const prefix = prefixBudget > 0 ? await scanPrefixAsync(info.path, prefixBudget) : emptyPrefixScan();
     return {
         provider: provider.id,
         sessionId: info.sessionId ?? safeSessionId(provider, info.path),

package/dist/sessionStats.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One `readSessionStats()` implementation for every session provider.
+ *
+ * Claude Code, Codex, and OpenCode used to compute session stats three
+ * different ways (a hand-rolled JSONL scan, an aggregator drain, and a direct
+ * SQLite read with hardcoded zeros). Every provider now drains its reader once
+ * into the shared `EventAggregator`, so per-model totals use the
+ * cache-inclusive vocabulary, cost carries provenance, tool failures are
+ * split out, and compaction and truncation counts are real for all three.
+ */
+import type { EventAggregatorOptions } from './aggregation/types';
+import type { ProviderId, SessionFileStats, SessionFileStatsAvailability, SessionProviderBase } from './providers/types';
+import type { SessionEvent } from './types/sessionEvent';
+export interface ComputeSessionFileStatsOptions {
+    providerId: ProviderId;
+    sessionId: string;
+    filePath: string;
+    /** Label to use; derived from the first user prompt when omitted or null. */
+    label?: string | null;
+    /** Provider-specific context formula, forwarded to the aggregator. */
+    computeContextSize?: EventAggregatorOptions['computeContextSize'];
+    /** Defaults to `full`. */
+    availability?: SessionFileStatsAvailability;
+    unavailableReason?: string;
+}
+export interface ReadSessionFileStatsOptions {
+    /**
+     * Cheap label source consulted before the events (for example a SQLite
+     * thread title). Return null to fall back to the first user prompt.
+     */
+    resolveLabel?: () => string | null;
+}
+/**
+ * First user prompt in a session, compacted to one line and truncated the
+ * way every provider's `extractSessionLabel()` truncates (60 characters).
+ */
+export declare function firstUserPrompt(events: readonly SessionEvent[], maxLength?: number): string | null;
+/** Compute stats for an already-read event array through the shared aggregator. */
+export declare function computeSessionFileStats(events: readonly SessionEvent[], options: ComputeSessionFileStatsOptions): SessionFileStats;
+/** The aggregator's context-size hook for a provider, or undefined for the default formula. */
+export declare function providerContextSizeFn(provider: SessionProviderBase): EventAggregatorOptions['computeContextSize'];
+/**
+ * Read a session once through the provider's reader and compute its stats.
+ *
+ * The reader is drained with `readAll()` and then `flush()`ed so a final line
+ * without a trailing newline is included, and it is never opened a second
+ * time for the label. A source that cannot be read yields
+ * `availability: 'unavailable'` with a reason instead of silent zeros; a
+ * reader that reports truncation yields `partial`.
+ */
+export declare function readSessionFileStats(provider: SessionProviderBase, sessionPath: string, options?: ReadSessionFileStatsOptions): SessionFileStats;

package/dist/sessionStats.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * One `readSessionStats()` implementation for every session provider.
+ *
+ * Claude Code, Codex, and OpenCode used to compute session stats three
+ * different ways (a hand-rolled JSONL scan, an aggregator drain, and a direct
+ * SQLite read with hardcoded zeros). Every provider now drains its reader once
+ * into the shared `EventAggregator`, so per-model totals use the
+ * cache-inclusive vocabulary, cost carries provenance, tool failures are
+ * split out, and compaction and truncation counts are real for all three.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firstUserPrompt = firstUserPrompt;
+exports.computeSessionFileStats = computeSessionFileStats;
+exports.providerContextSizeFn = providerContextSizeFn;
+exports.readSessionFileStats = readSessionFileStats;
+const EventAggregator_1 = require("./aggregation/EventAggregator");
+const LABEL_MAX_LENGTH = 60;
+function isTextBlock(block) {
+    return (typeof block === 'object' &&
+        block !== null &&
+        typeof block.text === 'string' &&
+        typeof block.type === 'string' &&
+        ['text', 'input_text', 'output_text'].includes(block.type));
+}
+function messageText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const block = content.find((item) => isTextBlock(item) && item.text.trim().length > 0);
+    return block && isTextBlock(block) ? block.text : null;
+}
+/**
+ * First user prompt in a session, compacted to one line and truncated the
+ * way every provider's `extractSessionLabel()` truncates (60 characters).
+ */
+function firstUserPrompt(events, maxLength = LABEL_MAX_LENGTH) {
+    for (const event of events) {
+        if (event.type !== 'user')
+            continue;
+        const text = messageText(event.message?.content);
+        if (!text)
+            continue;
+        const compact = text.replace(/\s+/g, ' ').trim();
+        if (!compact)
+            continue;
+        return compact.length > maxLength ? `${compact.slice(0, maxLength - 3)}...` : compact;
+    }
+    return null;
+}
+/** Compute stats for an already-read event array through the shared aggregator. */
+function computeSessionFileStats(events, options) {
+    const aggregator = new EventAggregator_1.EventAggregator({
+        providerId: options.providerId,
+        computeContextSize: options.computeContextSize,
+    });
+    for (const event of events)
+        aggregator.processEvent(event);
+    const metrics = aggregator.getMetrics();
+    const modelUsage = {};
+    for (const model of metrics.modelStats) {
+        // `tokens` is the aggregator's cache-inclusive total for the model, the
+        // same figure `summarizeTokens().total` reports.
+        modelUsage[model.model] = {
+            calls: model.calls,
+            tokens: model.tokens,
+            costUsd: model.cost,
+            priced: model.priced !== false,
+        };
+    }
+    const toolUsage = {};
+    const toolFailures = {};
+    for (const tool of metrics.toolStats) {
+        toolUsage[tool.name] = tool.successCount + tool.failureCount + tool.pendingCount;
+        if (tool.failureCount > 0)
+            toolFailures[tool.name] = tool.failureCount;
+    }
+    return {
+        providerId: options.providerId,
+        sessionId: options.sessionId,
+        filePath: options.filePath,
+        label: options.label ?? firstUserPrompt(events),
+        startTime: metrics.sessionStartTime ?? '',
+        endTime: metrics.lastEventTime ?? '',
+        messageCount: metrics.messageCount,
+        tokens: {
+            input: metrics.tokens.inputTokens,
+            output: metrics.tokens.outputTokens,
+            cacheWrite: metrics.tokens.cacheWriteTokens,
+            cacheRead: metrics.tokens.cacheReadTokens,
+        },
+        modelUsage,
+        toolUsage,
+        toolFailures,
+        compactionEstimate: metrics.compactionCount,
+        truncationCount: metrics.truncationCount,
+        costUsd: metrics.tokens.costUsd,
+        costProvenance: metrics.tokens.costProvenance,
+        unpricedCalls: metrics.tokens.unpricedCalls,
+        availability: options.availability ?? 'full',
+        ...(options.unavailableReason ? { unavailableReason: options.unavailableReason } : {}),
+        reportedCost: metrics.tokens.costUsd,
+    };
+}
+/** The aggregator's context-size hook for a provider, or undefined for the default formula. */
+function providerContextSizeFn(provider) {
+    if (!provider.computeContextSize)
+        return undefined;
+    return (usage) => provider.computeContextSize({ ...usage, model: '', timestamp: new Date() });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function describeMissingSource(provider) {
+    const status = provider.getRuntimeStatus?.();
+    if (status && !status.available) {
+        return status.message ?? `Provider runtime unavailable (${status.kind}).`;
+    }
+    return 'Session source not found.';
+}
+/**
+ * Read a session once through the provider's reader and compute its stats.
+ *
+ * The reader is drained with `readAll()` and then `flush()`ed so a final line
+ * without a trailing newline is included, and it is never opened a second
+ * time for the label. A source that cannot be read yields
+ * `availability: 'unavailable'` with a reason instead of silent zeros; a
+ * reader that reports truncation yields `partial`.
+ */
+function readSessionFileStats(provider, sessionPath, options = {}) {
+    const base = {
+        providerId: provider.id,
+        sessionId: provider.getSessionId(sessionPath),
+        filePath: sessionPath,
+    };
+    let reader;
+    let events;
+    try {
+        reader = provider.createReader(sessionPath);
+        events = reader.readAll();
+        // Readers buffer line-oriented input; flushing emits a trailing partial
+        // line into the same array `readAll()` returned.
+        reader.flush();
+    }
+    catch (error) {
+        return computeSessionFileStats([], {
+            ...base,
+            availability: 'unavailable',
+            unavailableReason: errorMessage(error),
+        });
+    }
+    if (events.length === 0 && !reader.exists()) {
+        return computeSessionFileStats([], {
+            ...base,
+            availability: 'unavailable',
+            unavailableReason: describeMissingSource(provider),
+        });
+    }
+    return computeSessionFileStats(events, {
+        ...base,
+        label: options.resolveLabel?.() ?? undefined,
+        computeContextSize: providerContextSizeFn(provider),
+        availability: reader.wasTruncated() ? 'partial' : 'full',
+    });
+}

package/dist/stateFile.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `state.json`: a small, versioned file for external consumers (tmux
+ * status bars, menu-bar apps, scripts) that want Sidekick's current account,
+ * quota windows with freshness, context usage, session cost, and the active
+ * billing block without running a Sidekick command.
+ *
+ * Written by the status line on every prompt and by both dashboards on their
+ * refresh ticks, but only when the content changed, so the hot path costs one
+ * small read in the common case. The schema is public: `schemaVersion` is 1,
+ * fields are only ever added, and the matching zod schema lives in
+ * `sidekick-shared/schemas` (`sidekickStateFileSchema`). This module does not
+ * import zod, so the status-line fast path stays small.
+ *
+ * @module stateFile
+ */
+import type { QuotaState } from './quota';
+import type { BillingBlock } from './usage/billingBlocks';
+export declare const STATE_FILE_SCHEMA_VERSION = 1;
+export declare const STATE_FILE_NAME = "state.json";
+export type StateFileWriter = 'statusline' | 'cli-dashboard' | 'vscode-dashboard';
+export interface StateFileQuotaWindow {
+    /** Utilization percentage (0–100). */
+    utilization: number;
+    /** ISO timestamp when the window resets; empty when unknown. */
+    resetsAt: string;
+}
+export interface StateFileQuota {
+    fiveHour: StateFileQuotaWindow;
+    sevenDay: StateFileQuotaWindow;
+    /** How the sample was obtained (`cache` when read back from the snapshot store). */
+    source: 'api' | 'session' | 'cache' | 'statusline' | null;
+    /** Original origin of a cached sample. */
+    capturedSource: 'api' | 'session' | 'statusline' | null;
+    capturedAt: string | null;
+    ageMs: number | null;
+    freshness: 'fresh' | 'aging' | 'stale' | null;
+}
+export interface StateFileAccount {
+    providerId: 'claude-code' | 'codex';
+    /** Sidekick registry id used to key quota snapshots and history. */
+    id: string | null;
+    label: string | null;
+}
+export interface StateFileContext {
+    usedPercentage: number | null;
+    contextWindowSize: number | null;
+    totalInputTokens: number | null;
+    totalOutputTokens: number | null;
+}
+export interface StateFileSession {
+    sessionId: string | null;
+    cwd: string | null;
+    model: string | null;
+    costUsd: number | null;
+    durationMs: number | null;
+    linesAdded: number | null;
+    linesRemoved: number | null;
+    /** Prompt-cache hit ratio (0–1) when the provider reports it. */
+    promptCacheHitRatio: number | null;
+}
+export interface StateFileBillingBlock {
+    start: string;
+    end: string;
+    isActive: boolean;
+    /** Cache-inclusive tokens so far. */
+    tokens: number;
+    costUsd: number;
+    costProvenance: 'reported' | 'estimated' | 'mixed' | 'unpriced' | 'none';
+    burnRatePerMinute: number;
+    projectedTokens: number;
+    projectedCostUsd: number;
+    remainingMs: number;
+}
+export interface SidekickStateFile {
+    schemaVersion: typeof STATE_FILE_SCHEMA_VERSION;
+    /** ISO timestamp of the write. Excluded from the unchanged comparison. */
+    writtenAt: string;
+    writer: StateFileWriter;
+    account: StateFileAccount | null;
+    quota: {
+        claude: StateFileQuota | null;
+        codex: StateFileQuota | null;
+    };
+    context: StateFileContext | null;
+    session: StateFileSession | null;
+    /** Active five-hour block (local estimate); null when unknown or not computed by the writer. */
+    billingBlock: StateFileBillingBlock | null;
+}
+/** Everything but the fields the writer stamps itself. */
+export type SidekickStateInput = Omit<SidekickStateFile, 'schemaVersion' | 'writtenAt'>;
+export interface WriteStateFileOptions {
+    /** Defaults to `<configDir>/state.json`. */
+    filePath?: string;
+    /** Clock for `writtenAt` (default `new Date()`). */
+    now?: Date;
+}
+export declare function getStateFilePath(): string;
+/** Read the current state file; null when absent or unreadable. */
+export declare function readStateFile(filePath?: string): SidekickStateFile | null;
+/**
+ * Write the state file atomically, but only when something other than
+ * `writtenAt` changed since the last write. Returns true when a write
+ * happened. Never throws: the state file is a convenience for other tools.
+ */
+export declare function writeStateFile(state: SidekickStateInput, options?: WriteStateFileOptions): boolean;
+/**
+ * Project a quota sample onto the state-file shape. A live sample (for
+ * example from the status-line payload) carries `capturedAt` but no age, so
+ * the age and freshness are derived from `now` when the sample omits them.
+ */
+export declare function quotaToStateFile(quota: QuotaState | null | undefined, now?: number): StateFileQuota | null;
+/** Project a billing block onto the state-file shape (totals only). */
+export declare function billingBlockToStateFile(block: BillingBlock | null | undefined): StateFileBillingBlock | null;

package/dist/stateFile.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * `state.json`: a small, versioned file for external consumers (tmux
+ * status bars, menu-bar apps, scripts) that want Sidekick's current account,
+ * quota windows with freshness, context usage, session cost, and the active
+ * billing block without running a Sidekick command.
+ *
+ * Written by the status line on every prompt and by both dashboards on their
+ * refresh ticks, but only when the content changed, so the hot path costs one
+ * small read in the common case. The schema is public: `schemaVersion` is 1,
+ * fields are only ever added, and the matching zod schema lives in
+ * `sidekick-shared/schemas` (`sidekickStateFileSchema`). This module does not
+ * import zod, so the status-line fast path stays small.
+ *
+ * @module stateFile
+ */
+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.STATE_FILE_NAME = exports.STATE_FILE_SCHEMA_VERSION = void 0;
+exports.getStateFilePath = getStateFilePath;
+exports.readStateFile = readStateFile;
+exports.writeStateFile = writeStateFile;
+exports.quotaToStateFile = quotaToStateFile;
+exports.billingBlockToStateFile = billingBlockToStateFile;
+const fs = __importStar(require("fs"));
+const paths_1 = require("./paths");
+const quota_1 = require("./quota");
+const atomic_1 = require("./writers/atomic");
+exports.STATE_FILE_SCHEMA_VERSION = 1;
+exports.STATE_FILE_NAME = 'state.json';
+function getStateFilePath() {
+    return (0, paths_1.getGlobalDataPath)(exports.STATE_FILE_NAME);
+}
+/** Read the current state file; null when absent or unreadable. */
+function readStateFile(filePath = getStateFilePath()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return parsed && parsed.schemaVersion === exports.STATE_FILE_SCHEMA_VERSION ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Key-order-independent serialisation, dropping undefined values. */
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        const entries = Object.keys(record)
+            .sort()
+            .filter((key) => record[key] !== undefined)
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/** The content that decides whether a rewrite is needed: everything the writer does not stamp. */
+function comparable(state) {
+    return stableStringify({ ...state, schemaVersion: undefined, writtenAt: undefined });
+}
+/**
+ * Write the state file atomically, but only when something other than
+ * `writtenAt` changed since the last write. Returns true when a write
+ * happened. Never throws: the state file is a convenience for other tools.
+ */
+function writeStateFile(state, options = {}) {
+    const filePath = options.filePath ?? getStateFilePath();
+    try {
+        const existing = readStateFile(filePath);
+        if (existing && comparable(existing) === comparable(state))
+            return false;
+        const next = {
+            schemaVersion: exports.STATE_FILE_SCHEMA_VERSION,
+            writtenAt: (options.now ?? new Date()).toISOString(),
+            ...state,
+        };
+        (0, atomic_1.atomicWriteJsonSync)(filePath, next);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Project a quota sample onto the state-file shape. A live sample (for
+ * example from the status-line payload) carries `capturedAt` but no age, so
+ * the age and freshness are derived from `now` when the sample omits them.
+ */
+function quotaToStateFile(quota, now = Date.now()) {
+    if (!quota || !quota.available)
+        return null;
+    let ageMs = typeof quota.ageMs === 'number' ? quota.ageMs : null;
+    let freshness = quota.freshness ?? null;
+    if (ageMs === null && quota.capturedAt) {
+        const capturedMs = Date.parse(quota.capturedAt);
+        if (Number.isFinite(capturedMs)) {
+            ageMs = Math.max(0, now - capturedMs);
+            freshness ??= (0, quota_1.classifyQuotaFreshness)(ageMs);
+        }
+    }
+    return {
+        fiveHour: { utilization: quota.fiveHour.utilization, resetsAt: quota.fiveHour.resetsAt },
+        sevenDay: { utilization: quota.sevenDay.utilization, resetsAt: quota.sevenDay.resetsAt },
+        source: quota.source ?? null,
+        capturedSource: quota.capturedSource ?? null,
+        capturedAt: quota.capturedAt ?? null,
+        ageMs,
+        freshness,
+    };
+}
+/** Project a billing block onto the state-file shape (totals only). */
+function billingBlockToStateFile(block) {
+    if (!block)
+        return null;
+    return {
+        start: block.start,
+        end: block.end,
+        isActive: block.isActive,
+        tokens: block.tokens.total,
+        costUsd: block.costUsd,
+        costProvenance: block.costProvenance,
+        burnRatePerMinute: block.burnRatePerMinute,
+        projectedTokens: block.projectedTokens,
+        projectedCostUsd: block.projectedCostUsd,
+        remainingMs: block.remainingMs,
+    };
+}