sidekick-shared 0.25.0 → 0.26.1

package/dist/observedContextWindows.js

@@ -64,6 +64,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OBSERVED_CONTEXT_WINDOW_TTL_MS = void 0;
 exports.getObservedContextWindowPath = getObservedContextWindowPath;
 exports._clearObservedContextWindowWriteCache = _clearObservedContextWindowWriteCache;
 exports.loadObservedContextWindows = loadObservedContextWindows;
@@ -76,6 +77,13 @@ const atomic_1 = require("./writers/atomic");
 // ── Constants ──
 const STORE_FILE_NAME = 'observed-context-windows.json';
 const STORE_VERSION = 1;
+/**
+ * Observations older than this are ignored on load. A provider reports its
+ * context window on every session, so a live model refreshes its entry
+ * constantly; an entry that has gone quiet this long belongs to a tier or
+ * model the user no longer runs and must not outrank the catalog forever.
+ */
+exports.OBSERVED_CONTEXT_WINDOW_TTL_MS = 30 * 86_400_000;
 /** Resolve the on-disk store path. */
 function getObservedContextWindowPath(cacheDir) {
     return path.join(cacheDir ?? (0, paths_1.getConfigDir)(), STORE_FILE_NAME);
@@ -98,13 +106,20 @@ const lastPersistedByStore = new Map();
 function _clearObservedContextWindowWriteCache() {
     lastPersistedByStore.clear();
 }
-/** Keep only well-formed entries; a hand-edited or partly-corrupt file shouldn't poison lookups. */
-function toOverrideMap(store) {
+/**
+ * Keep only well-formed, recent entries; a hand-edited or partly-corrupt file
+ * shouldn't poison lookups, and a stale observation shouldn't outrank the
+ * catalog (see {@link OBSERVED_CONTEXT_WINDOW_TTL_MS}).
+ */
+function toOverrideMap(store, now = Date.now()) {
     const out = {};
     for (const [modelId, entry] of Object.entries(store.models ?? {})) {
         const window = entry?.contextWindow;
         if (typeof window !== 'number' || !Number.isFinite(window) || window <= 0)
             continue;
+        const observedAt = typeof entry.observedAt === 'string' ? Date.parse(entry.observedAt) : NaN;
+        if (Number.isFinite(observedAt) && now - observedAt > exports.OBSERVED_CONTEXT_WINDOW_TTL_MS)
+            continue;
         out[modelId] = window;
     }
     return out;

package/dist/observedSessionCollector.d.ts

@@ -1,9 +1,8 @@
 import type { ObservedAgentSessionV1, ProviderCapabilitiesV1, ProviderSessionAdapterV1Options } from './types/observedSessionV1';
 import type { SessionProviderBase } from './providers/types';
-export interface ObservedSessionFingerprintParts {
-    sizeBytes: number;
-    mtimeMs: number;
-}
+import type { ObservedSessionFingerprintParts } from './sessionFingerprint';
+export { fileFingerprint, fileFingerprintParts } from './sessionFingerprint';
+export type { ObservedSessionFingerprintParts } from './sessionFingerprint';
 export interface ObservedSessionReference {
     sessionId: string;
     /** Opaque source locator used only by the source implementation. Never emitted in diagnostics. */
@@ -136,7 +135,3 @@ export declare class ObservedSessionCollector<T = unknown> {
  * one malformed session cannot reject discovery of its healthy siblings.
  */
 export declare function observedSessionSourceFromProvider(provider: SessionProviderBase, cwd: string, options?: ProviderSessionAdapterV1Options): ProviderObservedSessionCollectionSource;
-/** 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;

package/dist/observedSessionCollector.js

@@ -33,14 +33,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ObservedSessionCollector = void 0;
+exports.ObservedSessionCollector = exports.fileFingerprintParts = exports.fileFingerprint = void 0;
 exports.observedSessionSourceFromProvider = observedSessionSourceFromProvider;
-exports.fileFingerprintParts = fileFingerprintParts;
-exports.fileFingerprint = fileFingerprint;
 const fs = __importStar(require("node:fs"));
-const node_fs_1 = require("node:fs");
 const observedSessionV1_1 = require("./types/observedSessionV1");
 const sessionActivityDetector_1 = require("./parsers/sessionActivityDetector");
+const sessionFingerprint_1 = require("./sessionFingerprint");
+var sessionFingerprint_2 = require("./sessionFingerprint");
+Object.defineProperty(exports, "fileFingerprint", { enumerable: true, get: function () { return sessionFingerprint_2.fileFingerprint; } });
+Object.defineProperty(exports, "fileFingerprintParts", { enumerable: true, get: function () { return sessionFingerprint_2.fileFingerprintParts; } });
 const DEFAULT_MAX_CONCURRENT_READS = 4;
 const MAX_CONCURRENT_READS = 16;
 const DEFAULT_DEBOUNCE_MS = 100;
@@ -444,12 +445,12 @@ function observedSessionSourceFromProvider(provider, cwd, options = {}) {
     const referenceFromPath = (sessionPath, sessionId = provider.getSessionId(sessionPath), suppliedParts) => {
         const metadata = suppliedParts ? null : provider.getSessionMetadata?.(sessionPath);
         const parts = suppliedParts ??
-            fileFingerprintParts(sessionPath) ??
+            (0, sessionFingerprint_1.fileFingerprintParts)(sessionPath) ??
             (metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null);
         return {
             sessionId,
             sourceKey: sessionPath,
-            fingerprintHint: parts ? fingerprintString(parts) : undefined,
+            fingerprintHint: parts ? (0, sessionFingerprint_1.fingerprintString)(parts) : undefined,
             fingerprintParts: parts ?? undefined,
         };
     };
@@ -472,12 +473,12 @@ function observedSessionSourceFromProvider(provider, cwd, options = {}) {
         }
         return provider.findAllSessions(cwd).map((sessionPath) => {
             const metadata = provider.getSessionMetadata?.(sessionPath);
-            const parts = fileFingerprintParts(sessionPath) ??
+            const parts = (0, sessionFingerprint_1.fileFingerprintParts)(sessionPath) ??
                 (metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null);
             return {
                 sessionId: provider.getSessionId(sessionPath),
                 sourceKey: sessionPath,
-                fingerprintHint: parts ? fingerprintString(parts) : undefined,
+                fingerprintHint: parts ? (0, sessionFingerprint_1.fingerprintString)(parts) : undefined,
                 fingerprintParts: parts ?? undefined,
             };
         });
@@ -493,7 +494,7 @@ function observedSessionSourceFromProvider(provider, cwd, options = {}) {
         },
         refreshCached(reference, cached, observedAt) {
             const mtimeMs = reference.fingerprintParts?.mtimeMs ?? Date.parse(cached.observedAt);
-            const activity = (0, sessionActivityDetector_1.refreshSessionActivityState)(cached.activity.value, mtimeMs);
+            const activity = (0, sessionActivityDetector_1.refreshSessionActivityState)(cached.activity.value, mtimeMs, Date.now(), (0, observedSessionV1_1.getObservedActivityReason)(cached));
             return {
                 ...cached,
                 activity: { ...cached.activity, value: activity },
@@ -506,24 +507,6 @@ function observedSessionSourceFromProvider(provider, cwd, options = {}) {
         dispose: () => adapter.dispose(),
     };
 }
-/** 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;
-}
-function fingerprintString(parts) {
-    return `${parts.sizeBytes}:${parts.mtimeMs}`;
-}
 function parseFingerprintParts(value) {
     if (!value)
         return null;

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. */