sidekick-shared 0.25.0 → 0.26.0

package/dist/parsers/sessionActivityDetector.d.ts

@@ -9,6 +9,7 @@
  *
  * @module parsers/sessionActivityDetector
  */
+import type { SessionEvent } from '../types/sessionEvent';
 export type SessionActivityState = 'ongoing' | 'ended' | 'stale';
 export interface SessionActivityResult {
     state: SessionActivityState;
@@ -17,6 +18,10 @@ export interface SessionActivityResult {
     /** Reason for the classification */
     reason: string;
 }
+/** Grace period to prevent spinner flicker (ms) */
+export declare const SESSION_ACTIVITY_GRACE_PERIOD_MS = 5000;
+/** If mtime is older than this, session is stale regardless of content */
+export declare const SESSION_ACTIVITY_STALENESS_MS: number;
 /**
  * Determines whether a session is ongoing, ended, or stale.
  *
@@ -29,9 +34,26 @@ export interface SessionActivityResult {
  * @returns Activity state with classification reason
  */
 export declare function detectSessionActivity(sessionPath: string): SessionActivityResult;
+export interface ClassifySessionActivityOptions {
+    /** Canonical events already read for the session; only the tail is inspected. */
+    events: readonly SessionEvent[];
+    /** Source mtime; the last event's timestamp is used when unknown. */
+    mtimeMs: number | null | undefined;
+    /** Clock (default `Date.now()`). */
+    now?: number;
+}
+/**
+ * Classify a session from events already in memory, with the same states,
+ * reasons, grace period, and staleness rule as {@link detectSessionActivity},
+ * but without opening the file again. Works for every provider (the raw
+ * tail patterns only ever matched Claude Code JSONL) and for database-backed
+ * sessions that have no file to tail.
+ */
+export declare function classifySessionActivity(options: ClassifySessionActivityOptions): SessionActivityResult;
 /**
  * Refresh a cached classification from its unchanged fingerprint without
  * re-reading the transcript. An active file remains active until it crosses
- * the same five-minute staleness boundary used by detectSessionActivity.
+ * the same five-minute staleness boundary used by detectSessionActivity,
+ * unless it was active only by grace period (`previousReason`).
  */
-export declare function refreshSessionActivityState(previous: 'active' | 'idle' | 'ended' | 'unknown', mtimeMs: number, nowMs?: number): 'active' | 'idle' | 'ended' | 'unknown';
+export declare function refreshSessionActivityState(previous: 'active' | 'idle' | 'ended' | 'unknown', mtimeMs: number, nowMs?: number, previousReason?: string): 'active' | 'idle' | 'ended' | 'unknown';

package/dist/parsers/sessionActivityDetector.js

@@ -44,16 +44,22 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_ACTIVITY_STALENESS_MS = exports.SESSION_ACTIVITY_GRACE_PERIOD_MS = void 0;
 exports.detectSessionActivity = detectSessionActivity;
+exports.classifySessionActivity = classifySessionActivity;
 exports.refreshSessionActivityState = refreshSessionActivityState;
 const fs = __importStar(require("fs"));
 // ── Constants ──
 /** How many bytes to read from the end of the file for analysis */
 const TAIL_BYTES = 32 * 1024;
 /** Grace period to prevent spinner flicker (ms) */
-const GRACE_PERIOD_MS = 5_000;
+exports.SESSION_ACTIVITY_GRACE_PERIOD_MS = 5_000;
+const GRACE_PERIOD_MS = exports.SESSION_ACTIVITY_GRACE_PERIOD_MS;
 /** If mtime is older than this, session is stale regardless of content */
-const STALENESS_THRESHOLD_MS = 5 * 60 * 1000;
+exports.SESSION_ACTIVITY_STALENESS_MS = 5 * 60 * 1000;
+const STALENESS_THRESHOLD_MS = exports.SESSION_ACTIVITY_STALENESS_MS;
+/** How many trailing events the in-memory classifier inspects (about a 32 KiB tail). */
+const TAIL_EVENTS = 200;
 // ── Event Classification Patterns ──
 /** Patterns indicating the AI is actively working */
 const AI_ACTIVITY_PATTERNS = [
@@ -106,7 +112,9 @@ function detectSessionActivity(sessionPath) {
     if (lines.length === 0) {
         return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'no-events' };
     }
-    // Find the last line that matches each category
+    return classifyFromSignals(signalsFromLines(lines), stat.mtimeMs, mtimeAge);
+}
+function signalsFromLines(lines) {
     let lastAiActivityIndex = -1;
     let lastEndingIndex = -1;
     let hasTerminal = false;
@@ -136,38 +144,101 @@ function detectSessionActivity(sessionPath) {
             }
         }
     }
+    return { lastAiActivityIndex, lastEndingIndex, hasTerminal };
+}
+function hasToolResultBlock(event) {
+    const content = event.message?.content;
+    return (Array.isArray(content) &&
+        content.some((block) => typeof block === 'object' &&
+            block !== null &&
+            block.type === 'tool_result'));
+}
+/**
+ * The same signals the tail scanner derives from raw JSONL lines, read from
+ * canonical events instead: assistant, tool-use, and tool-result events (and
+ * user events carrying tool results) are AI activity; an assistant turn that
+ * stopped with `end_turn` or a user prompt is an ending event.
+ */
+function signalsFromEvents(events) {
+    let lastAiActivityIndex = -1;
+    let lastEndingIndex = -1;
+    for (let i = 0; i < events.length; i++) {
+        const event = events[i];
+        const carriesToolResult = event.type === 'user' && hasToolResultBlock(event);
+        if (event.type === 'assistant' ||
+            event.type === 'tool_use' ||
+            event.type === 'tool_result' ||
+            carriesToolResult) {
+            lastAiActivityIndex = i;
+        }
+        if ((event.type === 'assistant' && event.message?.stop_reason === 'end_turn') ||
+            (event.type === 'user' && !carriesToolResult)) {
+            lastEndingIndex = i;
+        }
+    }
+    return { lastAiActivityIndex, lastEndingIndex, hasTerminal: false };
+}
+function classifyFromSignals(signals, mtimeMs, mtimeAge) {
+    const lastActivityTime = new Date(mtimeMs);
+    const { lastAiActivityIndex, lastEndingIndex, hasTerminal } = signals;
     // Terminal patterns mean the session is definitely done
     if (hasTerminal) {
-        return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'terminal-event' };
+        return { state: 'ended', lastActivityTime, reason: 'terminal-event' };
     }
-    // AI activity after the last ending event → ongoing
+    // AI activity after the last ending event -> ongoing
     if (lastAiActivityIndex > lastEndingIndex) {
-        return {
-            state: 'ongoing',
-            lastActivityTime: new Date(stat.mtimeMs),
-            reason: 'ai-activity-after-ending',
-        };
+        return { state: 'ongoing', lastActivityTime, reason: 'ai-activity-after-ending' };
     }
     // Ending event with no subsequent AI activity
     if (lastEndingIndex >= 0) {
         // Apply grace period to prevent flicker
         if (mtimeAge < GRACE_PERIOD_MS) {
-            return { state: 'ongoing', lastActivityTime: new Date(stat.mtimeMs), reason: 'grace-period' };
+            return { state: 'ongoing', lastActivityTime, reason: 'grace-period' };
         }
-        return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'ending-event' };
+        return { state: 'ended', lastActivityTime, reason: 'ending-event' };
     }
-    // No clear signal — if recently modified, assume ongoing
+    // No clear signal: if recently modified, assume ongoing
     if (mtimeAge < GRACE_PERIOD_MS) {
-        return { state: 'ongoing', lastActivityTime: new Date(stat.mtimeMs), reason: 'recent-mtime' };
+        return { state: 'ongoing', lastActivityTime, reason: 'recent-mtime' };
+    }
+    return { state: 'ended', lastActivityTime, reason: 'no-activity-signal' };
+}
+/**
+ * Classify a session from events already in memory, with the same states,
+ * reasons, grace period, and staleness rule as {@link detectSessionActivity},
+ * but without opening the file again. Works for every provider (the raw
+ * tail patterns only ever matched Claude Code JSONL) and for database-backed
+ * sessions that have no file to tail.
+ */
+function classifySessionActivity(options) {
+    const now = options.now ?? Date.now();
+    const events = options.events;
+    const lastEventMs = events.length > 0 ? Date.parse(events[events.length - 1].timestamp) : NaN;
+    const mtimeMs = typeof options.mtimeMs === 'number' && Number.isFinite(options.mtimeMs)
+        ? options.mtimeMs
+        : Number.isFinite(lastEventMs)
+            ? lastEventMs
+            : null;
+    if (mtimeMs === null) {
+        return { state: 'ended', lastActivityTime: null, reason: 'no-events' };
     }
-    return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'no-activity-signal' };
+    const mtimeAge = now - mtimeMs;
+    if (mtimeAge > STALENESS_THRESHOLD_MS) {
+        return { state: 'stale', lastActivityTime: new Date(mtimeMs), reason: 'mtime-stale' };
+    }
+    if (events.length === 0) {
+        return { state: 'ended', lastActivityTime: new Date(mtimeMs), reason: 'no-events' };
+    }
+    const tail = events.length > TAIL_EVENTS ? events.slice(-TAIL_EVENTS) : events;
+    return classifyFromSignals(signalsFromEvents(tail), mtimeMs, mtimeAge);
 }
 /**
  * Refresh a cached classification from its unchanged fingerprint without
  * re-reading the transcript. An active file remains active until it crosses
- * the same five-minute staleness boundary used by detectSessionActivity.
+ * the same five-minute staleness boundary used by detectSessionActivity,
+ * unless it was active only by grace period (`previousReason`).
  */
-function refreshSessionActivityState(previous, mtimeMs, nowMs = Date.now()) {
+function refreshSessionActivityState(previous, mtimeMs, nowMs = Date.now(), previousReason) {
     if (!Number.isFinite(mtimeMs))
         return previous;
     if (nowMs - mtimeMs > STALENESS_THRESHOLD_MS)
@@ -176,6 +247,13 @@ function refreshSessionActivityState(previous, mtimeMs, nowMs = Date.now()) {
         return 'ended';
     if (previous === 'idle')
         return 'idle';
+    // A session that was only active thanks to the grace period ends once the
+    // grace period lapses, exactly as a fresh classification would say.
+    if (previous === 'active' &&
+        (previousReason === 'grace-period' || previousReason === 'recent-mtime') &&
+        nowMs - mtimeMs >= GRACE_PERIOD_MS) {
+        return 'ended';
+    }
     return previous === 'unknown' ? 'unknown' : 'active';
 }
 // ── Helpers ──

package/dist/parsers/sessionPathResolver.d.ts

@@ -205,6 +205,17 @@ export declare function getAllProjectFolders(workspacePath?: string): ProjectFol
  * ```
  */
 export declare function findSessionsInDirectory(sessionDir: string): string[];
+export interface SessionFileStat {
+    path: string;
+    mtime: Date;
+    sizeBytes: number;
+}
+/**
+ * The non-empty `.jsonl` files in a session directory with the stat each one
+ * already cost, newest first, so callers that need the mtime do not stat the
+ * same files a second time.
+ */
+export declare function findSessionFilesWithStats(sessionDir: string): SessionFileStat[];
 /**
  * Detects if a workspace is a git worktree and resolves the main repo path.
  *

package/dist/parsers/sessionPathResolver.js

@@ -54,6 +54,7 @@ exports.findAllSessions = findAllSessions;
 exports.decodeEncodedPath = decodeEncodedPath;
 exports.getAllProjectFolders = getAllProjectFolders;
 exports.findSessionsInDirectory = findSessionsInDirectory;
+exports.findSessionFilesWithStats = findSessionFilesWithStats;
 exports.resolveWorktreeMainRepo = resolveWorktreeMainRepo;
 exports.discoverWorktreeSiblings = discoverWorktreeSiblings;
 exports.findAllSessionsWithWorktrees = findAllSessionsWithWorktrees;
@@ -590,31 +591,33 @@ function getAllProjectFolders(workspacePath) {
  * ```
  */
 function findSessionsInDirectory(sessionDir) {
+    return findSessionFilesWithStats(sessionDir).map((file) => file.path);
+}
+/**
+ * The non-empty `.jsonl` files in a session directory with the stat each one
+ * already cost, newest first, so callers that need the mtime do not stat the
+ * same files a second time.
+ */
+function findSessionFilesWithStats(sessionDir) {
     try {
         if (!fs.existsSync(sessionDir)) {
             return [];
         }
-        const files = fs
+        return fs
             .readdirSync(sessionDir)
             .filter((file) => file.endsWith('.jsonl'))
             .map((file) => {
             const fullPath = path.join(sessionDir, file);
             try {
                 const stats = fs.statSync(fullPath);
-                return {
-                    path: fullPath,
-                    mtime: stats.mtime.getTime(),
-                    size: stats.size,
-                };
+                return { path: fullPath, mtime: stats.mtime, sizeBytes: stats.size };
             }
             catch {
                 return null;
             }
         })
-            .filter((f) => f !== null && f.size > 0)
-            .sort((a, b) => b.mtime - a.mtime)
-            .map((f) => f.path);
-        return files;
+            .filter((f) => f !== null && f.sizeBytes > 0)
+            .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
     }
     catch {
         return [];

package/dist/peakHours.d.ts

@@ -22,9 +22,34 @@ export interface PeakHoursState {
     updatedAt: string;
     unavailable: boolean;
     notApplicable?: boolean;
+    /**
+     * `promoclock` when the state came from promoclock.co, `schedule` when it
+     * was computed locally from the published weekday window. Absent on the
+     * not-applicable and unavailable placeholder states.
+     */
+    source?: 'promoclock' | 'schedule';
 }
-/** Default budget for the promoclock.co request, in milliseconds. */
-export declare const DEFAULT_PEAK_HOURS_TIMEOUT_MS = 10000;
+/**
+ * Default budget for the promoclock.co request, in milliseconds. The schedule
+ * fallback answers the question anyway, so a slow third-party host should not
+ * hold up a `sidekick status` or `sidekick quota` run for long.
+ */
+export declare const DEFAULT_PEAK_HOURS_TIMEOUT_MS = 4000;
+/** A promoclock.co answer is reused for this long before the host is asked again. */
+export declare const PEAK_HOURS_CACHE_MS: number;
+/** Published peak window: weekdays 13:00–19:00 UTC. */
+export declare const PEAK_WINDOW_START_UTC_HOUR = 13;
+export declare const PEAK_WINDOW_END_UTC_HOUR = 19;
+export declare const PEAK_HOURS_DESCRIPTION = "Weekdays 13:00\u201319:00 UTC";
+/** Forget the cached promoclock.co answer. Test-only. */
+export declare function _resetPeakHoursCache(): void;
+/**
+ * Peak-hours state computed from the published schedule alone, with no
+ * network access. Used directly by cache-only commands (`sidekick today`) and
+ * as the fallback when promoclock.co cannot be reached, so every surface
+ * agrees on whether it is currently peak.
+ */
+export declare function getScheduledPeakHoursState(now?: Date): PeakHoursState;
 /** Options for {@link fetchPeakHoursStatus}. */
 export interface FetchPeakHoursOptions {
     /**
@@ -32,6 +57,8 @@ export interface FetchPeakHoursOptions {
      * Defaults to {@link DEFAULT_PEAK_HOURS_TIMEOUT_MS}.
      */
     timeoutMs?: number;
+    /** Bypass the in-process cache and ask promoclock.co again. */
+    force?: boolean;
 }
 export declare function isClaudeCodeSessionProvider(providerId: ProviderId): boolean;
 export declare function createPeakHoursNotApplicableState(providerId: ProviderId): PeakHoursState;
@@ -40,7 +67,11 @@ export declare function scopePeakHoursToSessionProvider(providerId: ProviderId,
  * Fetch current Claude peak-hours state from promoclock.co.
  *
  * Single-shot — caller wraps in polling loop, EventEmitter, or interval.
- * Returns `unavailable: true` on any network, timeout, or parse error.
+ * A successful answer is cached in-process for {@link PEAK_HOURS_CACHE_MS}.
+ * On any network, timeout, or parse error the state is computed from the
+ * published schedule instead (`source: 'schedule'`), so callers always get a
+ * usable answer and every surface agrees on it; {@link unavailableState} is
+ * only returned when the schedule itself cannot be evaluated.
  *
  * promoclock.co is a third-party host, so the request is always bounded by
  * an abort timeout. Without one a hung host would stall the caller — and

package/dist/peakHours.js

@@ -11,14 +11,74 @@
  * Polling / eventing is the caller's responsibility.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_PEAK_HOURS_TIMEOUT_MS = void 0;
+exports.PEAK_HOURS_DESCRIPTION = exports.PEAK_WINDOW_END_UTC_HOUR = exports.PEAK_WINDOW_START_UTC_HOUR = exports.PEAK_HOURS_CACHE_MS = exports.DEFAULT_PEAK_HOURS_TIMEOUT_MS = void 0;
+exports._resetPeakHoursCache = _resetPeakHoursCache;
+exports.getScheduledPeakHoursState = getScheduledPeakHoursState;
 exports.isClaudeCodeSessionProvider = isClaudeCodeSessionProvider;
 exports.createPeakHoursNotApplicableState = createPeakHoursNotApplicableState;
 exports.scopePeakHoursToSessionProvider = scopePeakHoursToSessionProvider;
 exports.fetchPeakHoursStatus = fetchPeakHoursStatus;
 const PROMOCLOCK_ENDPOINT = 'https://promoclock.co/api/status';
-/** Default budget for the promoclock.co request, in milliseconds. */
-exports.DEFAULT_PEAK_HOURS_TIMEOUT_MS = 10_000;
+/**
+ * Default budget for the promoclock.co request, in milliseconds. The schedule
+ * fallback answers the question anyway, so a slow third-party host should not
+ * hold up a `sidekick status` or `sidekick quota` run for long.
+ */
+exports.DEFAULT_PEAK_HOURS_TIMEOUT_MS = 4_000;
+/** A promoclock.co answer is reused for this long before the host is asked again. */
+exports.PEAK_HOURS_CACHE_MS = 10 * 60_000;
+/** Published peak window: weekdays 13:00–19:00 UTC. */
+exports.PEAK_WINDOW_START_UTC_HOUR = 13;
+exports.PEAK_WINDOW_END_UTC_HOUR = 19;
+exports.PEAK_HOURS_DESCRIPTION = 'Weekdays 13:00–19:00 UTC';
+let cachedNetworkState = null;
+/** Forget the cached promoclock.co answer. Test-only. */
+function _resetPeakHoursCache() {
+    cachedNetworkState = null;
+}
+function isWeekdayUtc(date) {
+    const day = date.getUTCDay();
+    return day >= 1 && day <= 5;
+}
+function utcDateAtHour(date, hour, dayOffset = 0) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + dayOffset, hour));
+}
+/**
+ * Peak-hours state computed from the published schedule alone, with no
+ * network access. Used directly by cache-only commands (`sidekick today`) and
+ * as the fallback when promoclock.co cannot be reached, so every surface
+ * agrees on whether it is currently peak.
+ */
+function getScheduledPeakHoursState(now = new Date()) {
+    const hour = now.getUTCHours() + now.getUTCMinutes() / 60;
+    const isPeak = isWeekdayUtc(now) && hour >= exports.PEAK_WINDOW_START_UTC_HOUR && hour < exports.PEAK_WINDOW_END_UTC_HOUR;
+    let nextChange;
+    if (isPeak) {
+        nextChange = utcDateAtHour(now, exports.PEAK_WINDOW_END_UTC_HOUR);
+    }
+    else if (isWeekdayUtc(now) && hour < exports.PEAK_WINDOW_START_UTC_HOUR) {
+        nextChange = utcDateAtHour(now, exports.PEAK_WINDOW_START_UTC_HOUR);
+    }
+    else {
+        let offset = 1;
+        while (!isWeekdayUtc(utcDateAtHour(now, 0, offset)))
+            offset += 1;
+        nextChange = utcDateAtHour(now, exports.PEAK_WINDOW_START_UTC_HOUR, offset);
+    }
+    return {
+        status: isPeak ? 'peak' : 'off_peak',
+        isPeak,
+        sessionLimitSpeed: isPeak ? 'faster' : 'normal',
+        label: isPeak ? 'Peak Hours' : 'Off-Peak',
+        peakHoursDescription: exports.PEAK_HOURS_DESCRIPTION,
+        nextChange: nextChange.toISOString(),
+        minutesUntilChange: Math.max(0, Math.round((nextChange.getTime() - now.getTime()) / 60_000)),
+        note: 'Computed from the published weekday schedule.',
+        updatedAt: now.toISOString(),
+        unavailable: false,
+        source: 'schedule',
+    };
+}
 function unavailableState() {
     return {
         status: 'unknown',
@@ -76,13 +136,23 @@ function normalizeSpeed(raw) {
  * Fetch current Claude peak-hours state from promoclock.co.
  *
  * Single-shot — caller wraps in polling loop, EventEmitter, or interval.
- * Returns `unavailable: true` on any network, timeout, or parse error.
+ * A successful answer is cached in-process for {@link PEAK_HOURS_CACHE_MS}.
+ * On any network, timeout, or parse error the state is computed from the
+ * published schedule instead (`source: 'schedule'`), so callers always get a
+ * usable answer and every surface agrees on it; {@link unavailableState} is
+ * only returned when the schedule itself cannot be evaluated.
  *
  * promoclock.co is a third-party host, so the request is always bounded by
  * an abort timeout. Without one a hung host would stall the caller — and
  * this is polled, so the stall would repeat.
  */
 async function fetchPeakHoursStatus(options = {}) {
+    const now = Date.now();
+    if (!options.force &&
+        cachedNetworkState &&
+        now - cachedNetworkState.fetchedAt < exports.PEAK_HOURS_CACHE_MS) {
+        return cachedNetworkState.state;
+    }
     const timeoutMs = options.timeoutMs ?? exports.DEFAULT_PEAK_HOURS_TIMEOUT_MS;
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -90,12 +160,12 @@ async function fetchPeakHoursStatus(options = {}) {
     try {
         const res = await fetch(PROMOCLOCK_ENDPOINT, { signal: controller.signal });
         if (!res.ok)
-            return unavailableState();
+            return scheduleFallback();
         const data = await res.json();
         const status = normalizeStatus(data.status);
         const sessionLimitSpeed = normalizeSpeed(data.sessionLimitSpeed);
         const isPeak = typeof data.isPeak === 'boolean' ? data.isPeak : status === 'peak';
-        return {
+        const state = {
             status,
             isPeak,
             sessionLimitSpeed,
@@ -106,13 +176,28 @@ async function fetchPeakHoursStatus(options = {}) {
             note: data.note ?? '',
             updatedAt: data.timestamp ?? new Date().toISOString(),
             unavailable: false,
+            source: 'promoclock',
         };
+        cachedNetworkState = { state, fetchedAt: now };
+        return state;
     }
     catch {
         // Covers AbortError from the timeout above alongside network/parse failures.
-        return unavailableState();
+        return scheduleFallback();
     }
     finally {
         clearTimeout(timeout);
     }
 }
+function scheduleFallback() {
+    try {
+        const state = getScheduledPeakHoursState();
+        return {
+            ...state,
+            note: 'promoclock.co unreachable; computed from the published weekday schedule.',
+        };
+    }
+    catch {
+        return unavailableState();
+    }
+}

package/dist/pricingCatalog.d.ts

@@ -34,6 +34,13 @@ export interface HydrateOptions {
     url?: string;
     /** Optional logger (useful for diagnostics without pulling a logger dep). */
     logger?: (msg: string) => void;
+    /**
+     * Never touch the network: apply the on-disk cache regardless of its age, or
+     * stay on the static tables when there is none. Callers that must produce
+     * the same figures on every run (scripted reports, tests, air-gapped hosts)
+     * set this; `SIDEKICK_OFFLINE=1` does the same for the CLI.
+     */
+    offline?: boolean;
 }
 export interface HydrateResult {
     /** Where the loaded pricing came from. */

package/dist/pricingCatalog.js

@@ -60,6 +60,7 @@ const path = __importStar(require("node:path"));
 const modelContext_1 = require("./modelContext");
 const modelInfo_1 = require("./modelInfo");
 const paths_1 = require("./paths");
+const atomic_1 = require("./writers/atomic");
 // ── Constants ──
 exports.LITELLM_CATALOG_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
 const CACHE_FILE_NAME = 'pricing-catalog.json';
@@ -77,16 +78,16 @@ const DEFAULT_TIMEOUT_MS = 3_000;
  * Always resolves — never throws. Offline-safe.
  */
 async function hydratePricingCatalog(options = {}) {
-    const { cacheDir = (0, paths_1.getConfigDir)(), fetchImpl = globalThis.fetch, ttlMs = DEFAULT_TTL_MS, timeoutMs = DEFAULT_TIMEOUT_MS, url = exports.LITELLM_CATALOG_URL, logger, } = options;
+    const { cacheDir = (0, paths_1.getConfigDir)(), fetchImpl = globalThis.fetch, ttlMs = DEFAULT_TTL_MS, timeoutMs = DEFAULT_TIMEOUT_MS, url = exports.LITELLM_CATALOG_URL, logger, offline = false, } = options;
     const cachePath = path.join(cacheDir, CACHE_FILE_NAME);
     const now = Date.now();
-    // 1. Fresh cache?
+    // 1. Fresh cache? (Offline callers take any cache, however old.)
     const cached = await readCache(cachePath);
-    if (cached && now - Date.parse(cached.fetchedAt) < ttlMs) {
+    if (cached && (offline || now - Date.parse(cached.fetchedAt) < ttlMs)) {
         return applyCacheFile(cached, 'cache');
     }
     // 2. Try network.
-    if (fetchImpl) {
+    if (fetchImpl && !offline) {
         const fetched = await fetchCatalog(url, fetchImpl, timeoutMs, logger);
         if (fetched) {
             const payload = {
@@ -256,7 +257,9 @@ async function readCache(cachePath) {
 async function writeCache(cachePath, payload, logger) {
     try {
         await node_fs_1.promises.mkdir(path.dirname(cachePath), { recursive: true });
-        await node_fs_1.promises.writeFile(cachePath, JSON.stringify(payload, null, 2), 'utf8');
+        // The CLI and the extension host can both refresh the catalog at once;
+        // the atomic writer keeps a reader from ever seeing a half-written file.
+        await (0, atomic_1.atomicWriteJson)(cachePath, payload);
     }
     catch (err) {
         logger?.(`pricingCatalog: failed to write cache: ${String(err)}`);