@genee/omp-opsx-addon 0.1.0

package/lib/usage-poller.ts

@@ -0,0 +1,1200 @@
+/**
+ * System-level shared usage cache — persisted to `~/.omp/cache/` so multiple
+ * OMP processes share one fetch cycle instead of hammering provider APIs.
+ *
+ * Fetching is **per-provider independent**. Each provider tracks its own
+ * last-fetch/attempt timestamps and its own pending/loading flag, so:
+ *  - a `turn_end` poke marks ONLY the current model's provider dirty (direct
+ *    fetcher → one HTTP call; never touches the bulk API);
+ *  - the tick fetches only dirty providers whose minimum-interval floor has
+ *    elapsed, concurrently — a slow provider never blocks another;
+ *  - a provider being fetched shows a `⟳` loading hint (header) while its
+ *    previous report stays visible, and an unfetched logged-in placeholder
+ *    shows `⟳` instead of `—` until the first fetch lands.
+ *
+ * Triggering is a **dirty-flag model**: every "fetch is due" signal — a local
+ * `turn_end`, another process's consumption landing on disk, a forced trigger
+ * (reset-imminent / exhausted-unconfirmed), or the idle fallback period — only
+ * marks the provider dirty. The actual fetch happens in one place: `fetchDue`,
+ * run on every render tick, honoring a per-provider minimum interval floor
+ * (`minFetchIntervalMs`, default 10s) and skipping in-flight providers. A
+ * failed fetch re-marks the provider dirty so the next floor-eligible tick
+ * retries. The idle fallback (`idleDirtyMs`, default 60s) marks every
+ * provider whose last SUCCESSFUL fetch is older than the period, so quiet
+ * sessions still refresh at most once per 60s per provider.
+ *
+ * One `renderTimer` ticks every `renderTickMs` (~1s). Each firing runs
+ * `fetchDue` and renders the widget (`onTick`), and — when the absolute
+ * elapsed time since the previous data tick reaches `tickMs` (~5s) — also
+ * reads disk (`syncFromDisk`), evaluates forced/idle triggers, and fetches.
+ * Absolute time (not tick counting) decides refreshes, so a suspended machine
+ * (closed laptop lid) refreshes immediately on its first tick after wake
+ * instead of losing cycles.
+ * The standalone {@link pokeProvider} entry marks providers dirty and runs the
+ * same `fetchDue` kernel immediately (optionally bypassing the floor with
+ * `force`, for decision paths that await fresh data).
+
+ * The cache is split into TWO files under `~/.omp/cache/`: a REALTIME file
+ * (`omp-opsx-addon-usage-realtime.json`, `sessionUsage` only) and a FETCH file
+ * (`omp-opsx-addon-usage-fetch.json`, `reports` + `fetchedByProvider` +
+ * `fetchedAt` only). The legacy single file is migrated on first start and
+ * removed. Both files share the same cross-process LOCKED read-modify-write
+ * protocol: an exclusive lock file (`<file>.lock`, stolen when older than 5s)
+ * serializes concurrent writers; each writer re-reads the file inside the lock
+ * and lands the serialized payload via an atomic tmp+rename. Readers take no
+ * lock — the rename swap guarantees they see a complete old-or-new file.
+ * Concurrent sessions consuming in the same second therefore queue their
+ * writes and keep their per-second increments under the same absolute
+ * unix-second keys instead of clobbering each other's `sessionUsage` entries.
+ * Realtime entries whose `updatedAt` is older than `REALTIME_TTL_MS` are
+ * reclaimed on write (crash-residue self-healing).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, statSync, openSync, writeSync, closeSync, rmSync } from 'fs';
+import { join, dirname, extname } from 'path';
+import { homedir } from 'os';
+import type { UsageReport } from '@oh-my-pi/pi-ai';
+import type { AuthStorageLike, ProviderHealth, DirectFetcher, ApiKeyResolver } from './usage-resolver.js';
+import { resolveProviderReports, buildHealthMap, canonicalizeProvider, listDetectableProviders } from './usage-resolver.js';
+import { RedisRelay } from './usage-redis-probe.js';
+import type { RedisTransport } from './usage-redis-client.js';
+import type { UsageBucket } from './usage-estimator.js';
+import { normalizeBucket } from './usage-estimator.js';
+import type { ProviderUsageTotals } from './session-usage.js';
+interface SharedUsageState {
+    reports: UsageReport[];
+    health: Map<string, ProviderHealth>;
+    fetchedAt: number;
+    /** Canonical ids of providers with an in-flight fetch (loading state). */
+    loadingProviders: ReadonlySet<string>;
+}
+
+/** Realtime cache file: GLOBAL cross-session aggregates (totals + per-second). */
+interface RealtimeFile {
+    /** provider → cumulative bucketed totals (summed across every session). */
+    totals: Record<string, UsageBucket>;
+    /** unix second → provider → tokens consumed during that second (global sum). */
+    seconds: Record<string, Record<string, number>>;
+}
+
+/** Fetch cache file: provider reports + per-provider freshness timestamps. */
+interface FetchFile {
+    fetchedAt: number;
+    reports: UsageReport[];
+    fetchedByProvider?: Record<string, number>;
+}
+
+/** Legacy single-file cache shape — migration source only (per-session entries). */
+interface LegacyCacheFile {
+    fetchedAt: number;
+    reports: UsageReport[];
+    fetchedByProvider?: Record<string, number>;
+    sessionUsage?: Record<string, { perProvider?: Record<string, ProviderUsageTotals | number>; updatedAt?: number }>;
+}
+
+const CACHE_DIR = join(homedir(), '.omp', 'cache');
+/** Legacy single cache file — kept ONLY as the one-time migration source. */
+const CACHE_FILE = join(CACHE_DIR, 'omp-opsx-addon-usage.json');
+/** Realtime cache file: global totals + per-second aggregates. */
+export const CACHE_REALTIME_FILE = join(CACHE_DIR, 'omp-opsx-addon-usage-realtime.json');
+/** Fetch cache file: `reports` + `fetchedByProvider` + `fetchedAt` only. */
+export const CACHE_FETCH_FILE = join(CACHE_DIR, 'omp-opsx-addon-usage-fetch.json');
+
+/** Default data-refresh cadence (~5s) — absolute elapsed time checked on each render tick. */
+export const DEFAULT_TICK_MS = 5_000;
+/** Default render cadence — the countdown advances every second. */
+export const DEFAULT_RENDER_TICK_MS = 1_000;
+/** Default minimum interval between fetch attempts per provider (10s). */
+export const DEFAULT_MIN_FETCH_INTERVAL_MS = 10_000;
+/** Default idle fallback period (60s): providers with no consumption still re-fetch. */
+export const DEFAULT_IDLE_DIRTY_MS = 60_000;
+/** Threshold for a "即将重置" forced fetch: any window resetting within this. */
+export const RESET_IMMINENT_MS = 60_000;
+
+/** Options for {@link startSharedPoller}. */
+export interface StartPollerOptions {
+    /** Data-refresh cadence (ms of absolute elapsed time between refreshes). Default 5s. */
+    tickMs?: number;
+    /** Render cadence (countdown seconds). Default 1s; data refreshes are checked on this tick. */
+    renderTickMs?: number;
+    /** Minimum interval between fetch attempts per provider. Default 10s. */
+    minFetchIntervalMs?: number;
+    /** Idle fallback: providers whose last successful fetch is older than this get marked dirty. Default 60s. */
+    idleDirtyMs?: number;
+    /** Fired once at the end of every tick (after syncFromDisk + any fetch). */
+    onTick?: () => void;
+    /** Whether the calling session owns a real UI surface. A non-UI session (in-process task subagent whose ctx.ui is a no-op) must NOT steal the tick-render callback from the UI-owning session. */
+    ownsUi?: boolean;
+    /** Optional local Redis relay (write-through mirror + read prefetch + reconcile). `enabled: false` or omitted keeps the pure file path. */
+    redis?: RedisPollerOptions;
+}
+
+/** Redis relay sub-config passed to {@link startSharedPoller} (mirrors `RedisRelayOptions`). */
+export interface RedisPollerOptions {
+    /** Total switch. `false` disables probe/relay entirely (pure file path). */
+    enabled: boolean;
+    host: string;
+    port: number;
+    connectTimeoutMs: number;
+    commandTimeoutMs: number;
+    /** Reconcile cadence (absolute elapsed time between per-key overwrites). */
+    reconcileIntervalMs: number;
+    probeIntervalMs: number;
+    unhealthyRetryMs: number;
+    ttlMs: number;
+    /** Test seam: injected into the underlying RedisClient. */
+    transport?: RedisTransport;
+
+}
+
+/** Per-provider last-SUCCESSFUL-fetch timestamp (canonical id → epoch ms). */
+const lastFetchedByProvider = new Map<string, number>();
+/** Per-provider last-ATTEMPT timestamp (canonical id → epoch ms; gates the retry floor). */
+const lastAttemptByProvider = new Map<string, number>();
+/** Canonical ids marked dirty: a fetch is due (triggered, not yet consumed). */
+const dirtyProviders = new Set<string>();
+/** Canonical ids currently mid-fetch (the loading set). */
+const pendingProviders = new Set<string>();
+/** Runtime fetch floor — set by `startSharedPoller` from `StartPollerOptions`. */
+let minFetchIntervalMs = DEFAULT_MIN_FETCH_INTERVAL_MS;
+/** Runtime idle fallback period — set by `startSharedPoller` from `StartPollerOptions`. */
+let idleDirtyMs = DEFAULT_IDLE_DIRTY_MS;
+
+/**
+ * Providers whose most recent fetch attempt produced NO fresh report (direct
+ * fetcher returned null or threw). Any existing health for them is
+ * UNCONFIRMED — it may be a stale snapshot (e.g. an old "exhausted" report
+ * that a healthy provider like deepseek never produced itself). Selection
+ * still reads their current health, but the auto-refresh path re-attempts
+ * these providers every tick (bypassing TTL) so a stale report can't keep
+ * blocking selection for long.
+ */
+const unconfirmedProviders = new Set<string>();
+/**
+ * Providers whose exhausted health THIS process confirmed via a fresh fetch.
+ * Guards `syncFromDisk` from re-flagging a provider right after `fetchProvider`
+ * confirmed it and wrote the (exhausted) report to disk — without it, disk
+ * reads would re-add the provider to {@link unconfirmedProviders} and hammer it.
+ */
+const confirmedThisProcess = new Set<string>();
+/** Canonical ids of providers covered by a direct fetcher (the fresh source). */
+const directFetcherIds = new Set<string>();
+let cachedReports: UsageReport[] = [];
+let cachedHealth: Map<string, ProviderHealth> = new Map();
+/** Single interval: renders every tick AND checks absolute elapsed time for the data refresh. */
+let renderTimer: NodeJS.Timeout | null = null;
+/**
+ * Tick render callback, shared with the standalone {@link pokeProvider} path.
+ * `startSharedPoller` stores the caller's `onTick` here; both tick and
+ * `pokeProvider` read this ref so there is a single source of truth for the
+ * registered render callback regardless of which path fires.
+ */
+let onTickRef: (() => void) | undefined;
+let startInFlight: Promise<void> | null = null;
+/**
+ * Process-global tick-owner claim. The harness loads this plugin as a fresh
+ * module instance per session via `import(path?mtime=…)`, so a module-level
+ * claim is invisible to sibling instances sharing this JS realm — a subagent
+ * instance would otherwise misread `hasTickOwner()` as false and steal the
+ * owner's render callback + recorder key (double-counting on disk merge).
+ * The claim therefore lives on `globalThis`, keyed with the plugin name.
+ * The local {@link onTickRef} still holds the actual render callback (only
+ * meaningful in the module graph that registered it); the ownership check
+ * reads this shared claim instead.
+ */
+const TICK_OWNER_KEY = Symbol.for('omp-opsx-addon.usage-poller.tickOwner');
+function setTickOwner(cb: (() => void) | undefined): void {
+    (globalThis as Record<symbol, unknown>)[TICK_OWNER_KEY] = cb;
+}
+function getTickOwner(): (() => void) | undefined {
+    return (globalThis as Record<symbol, unknown>)[TICK_OWNER_KEY] as (() => void) | undefined;
+}
+
+/**
+ * Local Redis relay (write-through mirror / prefetch / reconcile). `null` =
+ * disabled or not yet configured — every path falls back to the realtime file.
+ */
+let relay: RedisRelay | null = null;
+/**
+ * Redis-prefetched read cache (healthy mode only). Stat-gated on the realtime
+ * file with the same ino/mtimeMs/size triple as the file-side caches: the
+ * prefetch step refreshes it when the file changes; the synchronous getters
+ * only ever return this cache while healthy.
+ */
+let redisUsageCache: {
+    ino: number;
+    mtimeMs: number;
+    size: number;
+    totals: Record<string, UsageBucket>;
+    perSecond: Record<string, Record<string, number>>;
+} | null = null;
+/** Reconcile cadence set at relay creation (default 30s, design D5). */
+let reconcileIntervalMs = 30_000;
+
+
+// Test seams: the cache files are resolved lazily so tests can redirect I/O to
+// temp paths without touching the real `~/.omp/cache`. `null` = production path.
+let realtimeFileOverride: string | null = null;
+let fetchFileOverride: string | null = null;
+let legacyFileOverride: string | null = null;
+const resolveRealtimeFile = (): string => realtimeFileOverride ?? CACHE_REALTIME_FILE;
+const resolveFetchFile = (): string => fetchFileOverride ?? CACHE_FETCH_FILE;
+const resolveLegacyCacheFile = (): string => legacyFileOverride ?? CACHE_FILE;
+
+/** Stat the realtime file for the relay prefetch gate; null when absent/unreadable. */
+function statRealtimeForRelay(): { ino: number; mtimeMs: number; size: number } | null {
+    try {
+        const st = statSync(resolveRealtimeFile());
+        return { ino: st.ino, mtimeMs: st.mtimeMs, size: st.size };
+    } catch {
+        return null;
+    }
+}
+
+/** Derive a sibling path (`<base>-<suffix><ext>`) from a realtime path. */
+function deriveSiblingPath(realtimePath: string, suffix: string): string {
+    const ext = extname(realtimePath);
+    const base = ext ? realtimePath.slice(0, -ext.length) : realtimePath;
+    return `${base}-${suffix}${ext}`;
+}
+
+/** Newest per-provider fetch timestamp (0 when nothing fetched yet). */
+function globalFetchedAt(): number {
+    let max = 0;
+    for (const t of lastFetchedByProvider.values()) if (t > max) max = t;
+    return max;
+}
+
+function buildCachedState(): SharedUsageState {
+    return {
+        reports: cachedReports,
+        health: cachedHealth,
+        fetchedAt: globalFetchedAt(),
+        loadingProviders: pendingProviders,
+    };
+}
+
+/** Record which providers are covered by a direct fetcher (the fresh source). */
+function setDirectFetcherCoverage(directFetchers: DirectFetcher[]): void {
+    for (const f of directFetchers) directFetcherIds.add(canonicalizeProvider(f.provider));
+}
+
+/**
+ * Disk-loaded reports are UNCONFIRMED for direct-fetcher providers whose
+ * health says exhausted: the direct fetcher is authoritative, and disk may hold
+ * a stale exhausted snapshot (e.g. an older bulk/discovery write) that a fresh
+ * process would otherwise trust silently (fresh timestamps → not TTL-stale →
+ * never re-fetched). Flagging them keeps the auto path re-attempting until THIS
+ * process confirms the real state — which recovers a healthy PAYG provider
+ * (deepseek/zhipu) instead of leaving it "exhausted". Providers already
+ * confirmed this process are skipped so a genuinely-exhausted provider is not
+ * re-hammered.
+ */
+function seedUnconfirmedFromDisk(): void {
+    if (directFetcherIds.size === 0) return;
+    for (const [p, h] of cachedHealth) {
+        if (h.exhausted && directFetcherIds.has(p) && !confirmedThisProcess.has(p)) {
+            unconfirmedProviders.add(p);
+        }
+    }
+}
+
+/** Read the realtime cache file, tolerating missing/partial fields. */
+function readRealtimeDisk(): RealtimeFile | null {
+    try {
+        const file = resolveRealtimeFile();
+        if (!existsSync(file)) return null;
+        const parsed = JSON.parse(readFileSync(file, 'utf-8')) as Partial<RealtimeFile> & { sessionUsage?: LegacyCacheFile['sessionUsage'] };
+        if (typeof parsed !== 'object' || parsed === null) return null;
+        // Older realtime shape (per-session entries): aggregate on read — the
+        // next locked write re-serializes the file in the global shape.
+        if (parsed.sessionUsage !== undefined) {
+            return aggregateLegacySessionUsage(parsed.sessionUsage);
+        }
+        return {
+            totals: (parsed.totals ?? {}) as Record<string, UsageBucket>,
+            seconds: (parsed.seconds ?? {}) as Record<string, Record<string, number>>,
+        };
+    } catch {
+        return null;
+    }
+}
+
+/** Read the fetch cache file, tolerating missing/partial fields. */
+function readFetchDisk(): FetchFile | null {
+    try {
+        const file = resolveFetchFile();
+        if (!existsSync(file)) return null;
+        const parsed = JSON.parse(readFileSync(file, 'utf-8')) as Partial<FetchFile>;
+        return {
+            fetchedAt: typeof parsed.fetchedAt === 'number' ? parsed.fetchedAt : 0,
+            reports: Array.isArray(parsed.reports) ? parsed.reports : [],
+            fetchedByProvider: parsed.fetchedByProvider ?? {},
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Per-session snapshot of what THIS process last wrote to the realtime file —
+ * the delta baseline. On flush we add `current - lastFlushed` to the file's
+ * GLOBAL aggregates under the lock, then advance the snapshot. A failed write
+ * leaves the snapshot untouched, so the same delta is re-applied next time
+ * (no double count, no loss). Session shutdown just drops the baseline — the
+ * already-flushed aggregates stay (totals are permanent cross-session sums).
+ */
+const lastFlushedBySession = new Map<string, Record<string, ProviderUsageTotals>>();
+/** Last-seen global totals from `syncFromDisk` — the cross-process consumption signal baseline. */
+let lastSyncedTotals: Map<string, number> = new Map();
+
+function ensureDir(dir: string): void {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// ── cross-process write lock ───────────────────────────────────────
+// Every write cycle is a locked read-modify-write: under the exclusive lock we
+// re-read the file, add this process's deltas, serialize, and atomically
+// rename. Concurrent writers queue on the lock (blocking acquire), so two
+// sessions consuming in the same second accumulate instead of clobbering.
+// Readers take NO lock — the tmp+rename swap guarantees a complete snapshot.
+// A lock left by a crashed process is stolen once older than LOCK_STALE_MS.
+
+
+const LOCK_STALE_MS = 5_000;
+const LOCK_RETRY_MS = 10;
+
+function sleepSync(ms: number): void {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    } catch {
+        const until = Date.now() + ms;
+        while (Date.now() < until) { /* spin */ }
+    }
+}
+
+/** Acquire the exclusive write lock for `file`; returns its release fn. */
+function acquireWriteLock(file: string): () => void {
+    const lockPath = `${file}.lock`;
+    for (;;) {
+        try {
+            const fd = openSync(lockPath, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => {
+                try { rmSync(lockPath); } catch { /* already gone */ }
+            };
+        } catch {
+            // Held by another process (or a crashed one). Steal stale locks.
+            try {
+                const st = statSync(lockPath);
+                if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                    try { rmSync(lockPath); } catch { /* raced */ }
+                    continue;
+                }
+            } catch {
+                continue; // lock vanished — retry immediately
+            }
+            sleepSync(LOCK_RETRY_MS);
+        }
+    }
+}
+let writeSeq = 0;
+
+/**
+ * Locked atomic replace of `file` with the payload `payload()` produces.
+ * `payload()` runs INSIDE the lock so a caller can build the payload from a
+ * lock-consistent disk read (read-modify-write); concurrent writers queue on
+ * the lock, and the tmp+rename swap guarantees a fresh inode per write so read
+ * gates keyed on ino never miss an update (even same-ms, same-size).
+ */
+function writePayloadLocked(file: string, payload: () => string): boolean {
+    const release = acquireWriteLock(file);
+    try {
+        ensureDir(dirname(file));
+        const body = payload();
+        const tmp = `${file}.tmp-${process.pid}-${writeSeq++}`;
+        writeFileSync(tmp, body, 'utf-8');
+        renameSync(tmp, file);
+        return true;
+    } catch {
+        return false;
+    } finally {
+        release();
+    }
+}
+
+/** Locked atomic write of a realtime payload (global totals + per-second sums). */
+function writeRealtimePayload(disk: RealtimeFile): boolean {
+    return writePayloadLocked(resolveRealtimeFile(), () => JSON.stringify(disk, null, 2));
+}
+
+/** Locked atomic write of a fetch payload (only reports/fetchedByProvider/fetchedAt). */
+function writeFetchPayload(fetch: {
+    fetchedAt: number;
+    reports: UsageReport[];
+    fetchedByProvider?: Record<string, number>;
+}): boolean {
+    return writePayloadLocked(resolveFetchFile(), () => JSON.stringify(fetch, null, 2));
+}
+
+/**
+ * Realtime write path: under the lock, re-read the file (the LATEST global
+ * aggregates), add this process's per-provider deltas onto the corresponding
+ * absolute-second slots and totals, prune the seconds tail to 120s, and
+ * atomically rename. Every writer therefore accumulates on the freshest data —
+ * concurrent sessions sum instead of clobbering.
+ */
+function writeRealtimeDisk(deltas: Record<string, ProviderUsageTotals>): boolean {
+    return writePayloadLocked(resolveRealtimeFile(), () => {
+        const disk = readRealtimeDisk() ?? { totals: {}, seconds: {} };
+        for (const [provider, delta] of Object.entries(deltas)) {
+            const prev = normalizeBucket(disk.totals[provider]);
+            disk.totals[provider] = {
+                total: prev.total + delta.total,
+                input: prev.input + delta.input,
+                output: prev.output + delta.output,
+            };
+            for (const [sec, dv] of Object.entries(delta.seconds ?? {})) {
+                if (dv === 0) continue;
+                const secMap = (disk.seconds[sec] ??= {});
+                secMap[provider] = (secMap[provider] ?? 0) + dv;
+            }
+        }
+        const cutoff = Math.floor(Date.now() / 1000) - 120;
+        for (const sec of Object.keys(disk.seconds)) {
+            if (Number(sec) < cutoff) delete disk.seconds[sec];
+        }
+        return JSON.stringify(disk, null, 2);
+    });
+}
+
+/**
+ * Fetch write path: serializes the in-memory fetch mirror under the same lock
+ * protocol. Never reads or rewrites the realtime aggregates.
+ */
+function writeFetchDisk(): boolean {
+    const fetchedByProvider: Record<string, number> = {};
+    for (const [p, t] of lastFetchedByProvider) fetchedByProvider[p] = t;
+    return writeFetchPayload({
+        fetchedAt: globalFetchedAt(),
+        reports: cachedReports,
+        fetchedByProvider,
+    });
+}
+
+
+/**
+ * Aggregate the legacy PER-SESSION structure into the GLOBAL aggregate shape:
+ * every session's per-provider buckets sum into `totals`, and its per-second
+ * deltas sum into the same absolute-second slots (legacy `number` values are
+ * normalized first).
+ */
+function aggregateLegacySessionUsage(
+    sessionUsage: LegacyCacheFile['sessionUsage'],
+): RealtimeFile {
+    const disk: RealtimeFile = { totals: {}, seconds: {} };
+    for (const entry of Object.values(sessionUsage ?? {})) {
+        for (const [provider, raw] of Object.entries(entry?.perProvider ?? {})) {
+            const bucket = normalizeBucket(raw);
+            const prev = normalizeBucket(disk.totals[provider]);
+            disk.totals[provider] = {
+                total: prev.total + bucket.total,
+                input: prev.input + bucket.input,
+                output: prev.output + bucket.output,
+            };
+            const seconds = typeof raw === 'object' && raw !== null ? (raw as ProviderUsageTotals).seconds : undefined;
+            for (const [sec, n] of Object.entries(seconds ?? {})) {
+                const secMap = (disk.seconds[sec] ??= {});
+                secMap[provider] = (secMap[provider] ?? 0) + n;
+            }
+        }
+    }
+    return disk;
+}
+
+/**
+ * One-time migration from the legacy single cache file to the split realtime +
+ * fetch files. Runs at poller start. Idempotent: when BOTH new files already
+ * exist the legacy file is skipped entirely (newer data is never overwritten);
+ * each missing new file is written under the same lock protocol from the
+ * legacy payload, then the legacy file is removed once both landed. A crash
+ * mid-migration simply re-runs on the next start (writes are atomic).
+ */
+function migrateLegacyCache(): void {
+    const legacyPath = resolveLegacyCacheFile();
+    if (!existsSync(legacyPath)) return;
+    const realtimePath = resolveRealtimeFile();
+    const fetchPath = resolveFetchFile();
+    if (existsSync(realtimePath) && existsSync(fetchPath)) return; // already migrated
+    let legacy: LegacyCacheFile | null = null;
+    try {
+        legacy = JSON.parse(readFileSync(legacyPath, 'utf-8')) as LegacyCacheFile;
+    } catch {
+        return; // unreadable legacy file — leave it untouched
+    }
+    if (!legacy) return;
+    if (!existsSync(realtimePath)) {
+        writeRealtimePayload(aggregateLegacySessionUsage(legacy.sessionUsage));
+    }
+    if (!existsSync(fetchPath)) {
+        writeFetchPayload({
+            fetchedAt: typeof legacy.fetchedAt === 'number' ? legacy.fetchedAt : 0,
+            reports: Array.isArray(legacy.reports) ? legacy.reports : [],
+            fetchedByProvider: legacy.fetchedByProvider,
+        });
+    }
+    if (existsSync(realtimePath) && existsSync(fetchPath)) {
+        try { rmSync(legacyPath); } catch { /* best effort */ }
+    }
+}
+
+/**
+ * Merge disk data into memory if any per-provider timestamp on disk is newer
+ * than the in-memory one (a cross-process fetch). Falls back to the legacy
+ * global `fetchedAt` when the cache file predates per-provider tracking.
+ */
+function syncFromDisk(loggedInProviders?: ReadonlySet<string>): void {
+    // Consumption signal (→ markDirty) reads the REALTIME file's GLOBAL totals:
+    // any provider whose aggregate grew since the last sync marks dirty.
+    const realtime = readRealtimeDisk();
+    if (realtime) {
+        const nowTotals = new Map<string, number>();
+        for (const [p, raw] of Object.entries(realtime.totals)) nowTotals.set(p, normalizeBucket(raw).total);
+        // Empty baseline = nothing seen yet → any positive total is new consumption.
+        for (const [p, total] of nowTotals) {
+            if (total > (lastSyncedTotals.get(p) ?? 0)) dirtyProviders.add(canonicalizeProvider(p));
+        }
+        lastSyncedTotals = nowTotals;
+    }
+    // ...freshness signal (→ merge reports) reads the FETCH file. The two are
+    // independent: a realtime write never re-fires a fetch merge, and a fetch
+    // write never re-fires consumption.
+    const disk = readFetchDisk();
+    if (!disk) {
+        // No disk data, but still prune in-memory caches.
+        if (loggedInProviders) pruneDisconnected(loggedInProviders);
+        return;
+    }
+    let touched = false;
+    if (disk.fetchedByProvider) {
+        for (const [p, t] of Object.entries(disk.fetchedByProvider)) {
+            const canonical = canonicalizeProvider(p);
+            // Skip providers no longer connected when we know the current set.
+            if (loggedInProviders && !loggedInProviders.has(canonical)) continue;
+            const prev = lastFetchedByProvider.get(canonical) ?? 0;
+            if (t > prev) {
+                lastFetchedByProvider.set(canonical, t);
+                touched = true;
+            }
+        }
+    } else if (disk.fetchedAt > globalFetchedAt()) {
+        // Legacy cache file: treat the global timestamp as the freshness floor
+        // for every provider present in reports.
+        for (const r of disk.reports) {
+            if (loggedInProviders && !loggedInProviders.has(r.provider)) continue;
+            lastFetchedByProvider.set(r.provider, disk.fetchedAt);
+        }
+        touched = true;
+    }
+    if (touched) {
+        cachedReports = mergeReports(cachedReports, disk.reports);
+        cachedHealth = buildHealthMap(cachedReports);
+    }
+    // Disk-loaded exhausted reports for direct-fetcher providers are unconfirmed.
+    seedUnconfirmedFromDisk();
+    // Prune in-memory caches to only connected providers, regardless of
+    // whether disk contributed new data — stale entries must go.
+    if (loggedInProviders) pruneDisconnected(loggedInProviders);
+}
+
+function seedFromDisk(loggedInProviders?: ReadonlySet<string>): void {
+    if (lastFetchedByProvider.size > 0) return;
+    const disk = readFetchDisk();
+    if (!disk) return;
+    // Canonicalize disk reports once (legacy files may carry pre-canonical ids).
+    let reports = disk.reports.map((r) => ({ ...r, provider: canonicalizeProvider(r.provider) }));
+    if (loggedInProviders) {
+        reports = reports.filter((r) => loggedInProviders.has(r.provider));
+    }
+    cachedReports = reports;
+    cachedHealth = buildHealthMap(cachedReports);
+    seedUnconfirmedFromDisk();
+    if (disk.fetchedByProvider) {
+        for (const [p, t] of Object.entries(disk.fetchedByProvider)) {
+            const canonical = canonicalizeProvider(p);
+            if (loggedInProviders && !loggedInProviders.has(canonical)) continue;
+            lastFetchedByProvider.set(canonical, t);
+        }
+    } else if (disk.reports.length > 0) {
+        for (const r of reports) lastFetchedByProvider.set(r.provider, disk.fetchedAt);
+    }
+}
+/** Remove stale in-memory AND on-disk cached data for any provider NOT in `loggedIn`. */
+function pruneDisconnected(loggedIn: ReadonlySet<string>): void {
+    let removed = false;
+    for (const key of dirtyProviders) {
+        if (!loggedIn.has(key)) { dirtyProviders.delete(key); removed = true; }
+    }
+    for (const key of lastAttemptByProvider.keys()) {
+        if (!loggedIn.has(key)) { lastAttemptByProvider.delete(key); removed = true; }
+    }
+    for (const key of lastFetchedByProvider.keys()) {
+        if (!loggedIn.has(key)) { lastFetchedByProvider.delete(key); removed = true; }
+    }
+    for (const key of unconfirmedProviders) {
+        if (!loggedIn.has(key)) { unconfirmedProviders.delete(key); removed = true; }
+    }
+    for (const key of confirmedThisProcess) {
+        if (!loggedIn.has(key)) { confirmedThisProcess.delete(key); removed = true; }
+    }
+    const next = cachedReports.filter((r) => loggedIn.has(r.provider));
+    removed = removed || next.length !== cachedReports.length;
+    cachedReports = next;
+    cachedHealth = buildHealthMap(cachedReports);
+    // Persist only when something was actually dropped — the 5s sync tick must
+    if (removed) writeFetchDisk();
+}
+/** Merge `incoming` into `existing` by canonical provider id (incoming wins). */
+function mergeReports(existing: UsageReport[], incoming: UsageReport[]): UsageReport[] {
+    const byId = new Map(existing.map((r) => [r.provider, r]));
+    for (const r of incoming) byId.set(r.provider, r);
+    return [...byId.values()];
+}
+
+/** All canonical provider ids the host considers logged-in. */
+function getLoggedInProviders(
+    authStorage: AuthStorageLike | undefined,
+    directFetchers: DirectFetcher[],
+): string[] {
+    const detectable = listDetectableProviders(directFetchers);
+    if (authStorage?.list) {
+        return [...new Set([...authStorage.list().map(canonicalizeProvider), ...detectable])];
+    }
+    // No authStorage (tests / offline): direct fetchers' providers are the universe,
+    // with detectable probes still honored when present.
+    return [...new Set([...directFetchers.map((f) => canonicalizeProvider(f.provider)), ...detectable])];
+}
+
+
+/**
+ * True when any limit window for `provider` resets within `RESET_IMMINENT_MS`
+ * or has already elapsed. Drives a forced fetch so the widget's "即将重置"
+ * countdown flips to the new window promptly instead of waiting out the static
+ * TTL. `resetsAt - now < RESET_IMMINENT_MS` covers both near-future and past.
+ */
+export function isResetImminent(provider: string): boolean {
+    const canonical = canonicalizeProvider(provider);
+    const report = cachedReports.find((r) => r.provider === canonical);
+    if (!report) return false;
+    return report.limits.some(
+        (l) => typeof l.window?.resetsAt === "number" && l.window.resetsAt - Date.now() < RESET_IMMINENT_MS,
+    );
+}
+
+/**
+ * Fetch a single provider and merge its report into the cache. Per-provider
+ * pending guard makes concurrent calls for the same provider no-op. Toggles the
+ * provider's id in the loading set for the duration of the fetch so the render
+ * can show a `⟳` hint. Failure leaves the previous report (if any) intact.
+ */
+async function fetchProvider(
+    provider: string,
+    authStorage: AuthStorageLike | undefined,
+    directFetchers: DirectFetcher[],
+    getApiKey?: ApiKeyResolver,
+): Promise<void> {
+    const canonical = canonicalizeProvider(provider);
+    if (pendingProviders.has(canonical)) return; // already fetching this provider
+    pendingProviders.add(canonical);
+    try {
+        const { reports } = await resolveProviderReports(authStorage, directFetchers, undefined, getApiKey, [canonical]);
+        const fetchedAt = Date.now();
+        lastFetchedByProvider.set(canonical, fetchedAt);
+        // Replace (or insert) just this provider's report; keep all others.
+        const byId = new Map(cachedReports.map((r) => [r.provider, r]));
+        const newReport = reports.find((r) => r.provider === canonical);
+        if (newReport) {
+            byId.set(canonical, newReport);
+            // Fresh report landed → the provider's health is CONFIRMED.
+            unconfirmedProviders.delete(canonical);
+            confirmedThisProcess.add(canonical);
+        } else {
+            // Fetch produced nothing for this provider: any existing report is
+            // UNCONFIRMED (possibly stale) — keep it for display, but flag it so
+            // the auto path re-attempts sooner than TTL.
+            if (byId.has(canonical)) unconfirmedProviders.add(canonical);
+        }
+        // Fetch returned nothing: still advance TTL via lastFetchedByProvider
+        // above, but KEEP any prior report (matches the comment / avoids
+        // multi-process cache races wiping a good Cursor report).
+        cachedReports = [...byId.values()];
+        cachedHealth = buildHealthMap(cachedReports);
+        writeFetchDisk();
+    } catch {
+        // Fetch threw: any existing report is unconfirmed until a fetch lands,
+        // and the provider re-enters the dirty set so the next floor-eligible
+        // tick retries (attempt timestamp already advanced by `fetchDue`).
+        if (cachedReports.some((r) => r.provider === canonical)) unconfirmedProviders.add(canonical);
+        dirtyProviders.add(canonical);
+        /* keep previous data */
+    } finally {
+        pendingProviders.delete(canonical);
+    }
+}
+
+/**
+ * Fetch every dirty provider whose per-provider minimum-interval floor has
+ * elapsed (skipping in-flight ones), consuming the dirty marks on initiation.
+ * `force` bypasses the floor for decision paths that await fresh data.
+ * `fetchProvider` re-marks a provider dirty when it throws, so a failed fetch
+ * retries on the next floor-eligible tick instead of being lost.
+ */
+async function fetchDue(
+    authStorage: AuthStorageLike | undefined,
+    directFetchers: DirectFetcher[],
+    getApiKey: ApiKeyResolver | undefined,
+    opts?: { force?: boolean },
+): Promise<void> {
+    const now = Date.now();
+    const due: string[] = [];
+    for (const provider of dirtyProviders) {
+        if (pendingProviders.has(provider)) continue;
+        const lastAttempt = lastAttemptByProvider.get(provider);
+        // No attempt record yet → first fetch always passes the floor.
+        if (!opts?.force && lastAttempt !== undefined && now - lastAttempt < minFetchIntervalMs) continue;
+        due.push(provider);
+    }
+    if (due.length === 0) return;
+    for (const provider of due) {
+        dirtyProviders.delete(provider); // consumed on initiation — failures re-add
+        lastAttemptByProvider.set(provider, now);
+    }
+    await Promise.all(due.map((p) => fetchProvider(p, authStorage, directFetchers, getApiKey)));
+}
+
+/**
+ * Mark every logged-in provider that should fetch right now: forced triggers
+ * (reset-imminent / exhausted-unconfirmed) and the idle fallback (no
+ * consumption, last SUCCESSFUL fetch older than `idleDirtyMs`).
+ */
+function evaluateDirty(loggedIn: ReadonlySet<string>): void {
+    const now = Date.now();
+    for (const provider of loggedIn) {
+        if (isResetImminent(provider) || isExhaustedUnconfirmed(provider)) {
+            dirtyProviders.add(provider);
+        } else if (now - (lastFetchedByProvider.get(provider) ?? 0) >= idleDirtyMs) {
+            dirtyProviders.add(provider);
+        }
+    }
+}
+
+/**
+ * Poke one or more providers: mark them dirty, sync the shared cache from
+ * disk, run {@link fetchDue} immediately, and render once at the end. The
+ * `turn_end` hook uses the default (floor-honoring) path for the current
+ * model's provider; the 429-diagnosis and `/pick-model` decision paths pass
+ * `force: true` because they await fresh data before deciding.
+ */
+export async function pokeProvider(
+    authStorage: AuthStorageLike | undefined,
+    directFetchers: DirectFetcher[],
+    getApiKey: ApiKeyResolver | undefined,
+    opts?: { providers?: readonly string[]; force?: boolean },
+): Promise<void> {
+    setDirectFetcherCoverage(directFetchers);
+    const loggedIn = getLoggedInProviders(authStorage, directFetchers);
+    const targets =
+        opts?.providers && opts.providers.length > 0
+            ? opts.providers.map(canonicalizeProvider)
+            : loggedIn;
+    for (const provider of targets) dirtyProviders.add(provider);
+    syncFromDisk(new Set(loggedIn));
+    await fetchDue(authStorage, directFetchers, getApiKey, { force: opts?.force });
+    onTickRef?.();
+}
+/**
+ * Provider whose health says `exhausted` but whose most recent fetch attempt
+ * produced no fresh report (its report is unconfirmed and possibly stale).
+ * These are re-attempted by the automatic refresh path every cycle so a
+ * healthy provider flagged exhausted by old data recovers on its own.
+ */
+function isExhaustedUnconfirmed(provider: string): boolean {
+    const canonical = canonicalizeProvider(provider);
+    return unconfirmedProviders.has(canonical) && (cachedHealth.get(canonical)?.exhausted ?? false);
+}
+
+/** Canonical ids of providers whose health is unconfirmed (last fetch produced nothing). */
+export function getUnconfirmedProviders(): string[] {
+    return [...unconfirmedProviders];
+}
+
+/** Start the poller. Resolves when first usable data is available (disk or fetch). Idempotent. */
+export async function startSharedPoller(
+    authStorage: AuthStorageLike | undefined,
+    directFetchers: DirectFetcher[],
+    getApiKey?: ApiKeyResolver,
+    opts?: StartPollerOptions,
+): Promise<void> {
+    // Subagent session_start shares this process; its render closure writes to a no-op UI and would freeze the host widget.
+        if (opts?.redis?.enabled && relay === null) {
+            relay = new RedisRelay({
+                host: opts.redis.host,
+                port: opts.redis.port,
+                connectTimeoutMs: opts.redis.connectTimeoutMs,
+                commandTimeoutMs: opts.redis.commandTimeoutMs,
+                probeIntervalMs: opts.redis.probeIntervalMs,
+                unhealthyRetryMs: opts.redis.unhealthyRetryMs,
+                reconcileIntervalMs: opts.redis.reconcileIntervalMs,
+                ttlMs: opts.redis.ttlMs,
+                transport: opts.redis.transport,
+            });
+            reconcileIntervalMs = opts.redis.reconcileIntervalMs;
+        }
+    if (opts?.onTick && !(opts.ownsUi === false && getTickOwner() !== undefined)) {
+        onTickRef = opts.onTick;
+        setTickOwner(opts.onTick);
+    }
+    if (startInFlight) return startInFlight;
+    if (renderTimer) return;
+
+    startInFlight = (async () => {
+        const tickMs = opts?.tickMs ?? DEFAULT_TICK_MS;
+        const renderTickMs = opts?.renderTickMs ?? DEFAULT_RENDER_TICK_MS;
+        if (opts?.minFetchIntervalMs !== undefined) minFetchIntervalMs = opts.minFetchIntervalMs;
+        if (opts?.idleDirtyMs !== undefined) idleDirtyMs = opts.idleDirtyMs;
+
+        // One-time migration from the legacy single cache file (idempotent).
+        migrateLegacyCache();
+        const loggedInSet = new Set(getLoggedInProviders(authStorage, directFetchers));
+        setDirectFetcherCoverage(directFetchers);
+        syncFromDisk(loggedInSet);
+        seedFromDisk(loggedInSet);
+
+        const tick = async (): Promise<void> => {
+            syncFromDisk(loggedInSet);
+            evaluateDirty(loggedInSet);
+            await fetchDue(authStorage, directFetchers, getApiKey);
+            onTickRef?.();
+        };
+
+        // Redis relay steps run on EVERY render firing (before the data tick /
+        // render), per design D6 — all absolute-time gated inside the relay,
+        // no extra timer. Failures never escape into the interval.
+        const relaySteps = async (): Promise<void> => {
+            // Local ref: `_resetForTest` may null `relay` while an in-flight
+            // tick is still awaiting — steps must not crash on the dangling read.
+            const r = relay;
+            if (r === null) return;
+            const now = Date.now();
+            r.observeMirrorFailure(now);
+            await r.maybeProbe(now);
+            if (r.state === 'healthy') {
+                // Unconditional per-tick prefetch: redis is the LIVE side (its
+                // aggregates already sum across sessions at write time), so the
+                // window is re-read every second. Local loopback cost is
+                // negligible; the file is only the fallback + authority.
+                try {
+                    const snapshot = await r.prefetch(readRealtimeDisk() ?? { totals: {}, seconds: {} }, now);
+                    const st = statRealtimeForRelay();
+                    if (st !== null) {
+                        redisUsageCache = { ino: st.ino, mtimeMs: st.mtimeMs, size: st.size, totals: snapshot.totals, perSecond: snapshot.perSecond };
+                    }
+                } catch {
+                    // prefetch already flipped the relay unhealthy; fall back to file reads.
+                    redisUsageCache = null;
+                }
+                if (r.state === 'healthy' && now - r.lastReconcileAt >= reconcileIntervalMs) {
+                    try {
+                        await r.reconcile(readRealtimeDisk() ?? { totals: {}, seconds: {} }, now);
+                    } catch {
+                        // reconcile already flipped the relay unhealthy (defensive).
+                    }
+                }
+            }
+        };
+
+
+        // Single timer. Every renderTickMs we run the relay steps, consume dirty
+        // providers and render; when the absolute elapsed time since the
+        // previous data tick reaches tickMs we also sync disk + evaluate
+        // triggers + fetch. Absolute time (not tick counting) survives machine
+        // suspend: the first tick after a closed-lid wake refreshes
+        // immediately, and tickInFlight prevents overlapping refreshes if a
+        // fetch is slower than the cadence.
+        let lastTickAt = Date.now();
+        let tickInFlight = false;
+        const dataTickPath = (): void => {
+            if (!tickInFlight && Date.now() - lastTickAt >= tickMs) {
+                lastTickAt = Date.now();
+                tickInFlight = true;
+                void tick().finally(() => {
+                    tickInFlight = false;
+                });
+            } else {
+                void fetchDue(authStorage, directFetchers, getApiKey);
+                onTickRef?.();
+            }
+        };
+        renderTimer = setInterval(() => {
+            // Relay disabled: keep the data tick + render fully synchronous
+            // (fake-timer tests and the render loop rely on it). Relay enabled:
+            // run the D6 relay steps first, then the data path.
+            if (relay === null) {
+                dataTickPath();
+                return;
+            }
+            void relaySteps().then(dataTickPath);
+        }, renderTickMs);
+
+        const fresh = [...lastFetchedByProvider.values()].some((t) => Date.now() - t < idleDirtyMs);
+        if (fresh) return;
+
+        evaluateDirty(loggedInSet);
+        await fetchDue(authStorage, directFetchers, getApiKey);
+    })();
+    try {
+        await startInFlight;
+    } finally {
+        startInFlight = null;
+    }
+}
+
+export function getSharedUsage(): SharedUsageState | null {
+    syncFromDisk();
+    // Return state once we have data OR an in-flight fetch (so the UI can show
+    // a loading hint even before the first report lands).
+    if (cachedReports.length === 0 && lastFetchedByProvider.size === 0 && pendingProviders.size === 0) return null;
+    return buildCachedState();
+}
+
+// ── cross-process session usage (consumption waveform source) ──────
+
+/**
+ * Publish this session's cumulative per-provider token totals to the shared
+ * cache under the cross-process write lock: other processes' entries are
+ * re-read and preserved — only the entry for `sessionId` is overwritten.
+ * After a successful file write, mirrors the full snapshot to Redis
+ * (fire-and-forget HSET + EXPIRE) and DELs any entries reclaimed this cycle.
+ */
+/** Whether THIS process still holds a delta baseline for the given session. */
+export function hasManagedSessionUsage(sessionId: string): boolean {
+    return !!sessionId && lastFlushedBySession.has(sessionId);
+}
+
+export function writeSessionUsage(sessionId: string, perProvider: Record<string, ProviderUsageTotals>): boolean {
+    if (!sessionId) return false;
+    const prev = lastFlushedBySession.get(sessionId) ?? {};
+    const deltas: Record<string, ProviderUsageTotals> = {};
+    const snapshot: Record<string, ProviderUsageTotals> = {};
+    for (const [provider, raw] of Object.entries(perProvider)) {
+        const cur = normalizeBucket(raw);
+        const curSeconds = typeof raw === 'object' && raw !== null ? (raw as ProviderUsageTotals).seconds : undefined;
+        const beforeRaw = prev[provider];
+        const before = normalizeBucket(beforeRaw);
+        const beforeSeconds = typeof beforeRaw === 'object' && beforeRaw !== null ? (beforeRaw as ProviderUsageTotals).seconds : undefined;
+        const seconds: Record<string, number> = {};
+        for (const [sec, n] of Object.entries(curSeconds ?? {})) {
+            const dv = n - (beforeSeconds?.[sec] ?? 0);
+            if (dv !== 0) seconds[sec] = dv;
+        }
+        // input/output are observational maxima — never regress the aggregate.
+        const dTotal = Math.max(0, cur.total - before.total);
+        const dInput = Math.max(0, cur.input - before.input);
+        const dOutput = Math.max(0, cur.output - before.output);
+        deltas[provider] = { total: dTotal, input: dInput, output: dOutput, seconds };
+        snapshot[provider] = {
+            total: before.total + dTotal,
+            input: before.input + dInput,
+            output: before.output + dOutput,
+            seconds: { ...(curSeconds ?? {}) },
+        };
+    }
+    if (Object.keys(deltas).length === 0) return true;
+    const ok = writeRealtimeDisk(deltas);
+    if (ok) {
+        lastFlushedBySession.set(sessionId, snapshot);
+        // Event-level totals mirror: HINCRBY deltas (no retry — mirrorFailed;
+        // a lost increment is repaired by the next reconcile overwrite).
+        for (const [provider, d] of Object.entries(deltas)) {
+            if (d.total > 0 || d.input > 0 || d.output > 0) relay?.onTotalsDelta(provider, d.total, d.input, d.output);
+        }
+    }
+    return ok;
+}
+
+/**
+ * Session shutdown: the aggregates are PERMANENT cross-session sums — nothing
+ * is subtracted. Only this process's delta baseline is dropped so a later
+ * session id never re-applies stale deltas.
+ */
+export function removeSessionUsage(sessionId: string): void {
+    if (!sessionId) return;
+    lastFlushedBySession.delete(sessionId);
+}
+
+/**
+ * Event-level sec-delta mirror entry (wired to `SessionUsageSink.onDelta` in
+ * index.ts): healthy relay → fire-and-forget `HINCRBY` + `EXPIRE`; otherwise
+ * no-op. Never throws.
+ */
+export function mirrorSessionDelta(sessionId: string, provider: string, secNow: string, deltaTotal: number): void {
+    relay?.onDelta(sessionId, provider, secNow, deltaTotal);
+}
+
+/**
+ * Global totals per provider — the file stores cross-session aggregates
+ * directly, so the getter is a plain stat-gated read with NO per-session
+ * traversal. Healthy relay → served from the prefetched Redis cache; stat
+ * miss (prefetch hasn't refreshed yet, e.g. render fired outside the tick
+ * flow) falls through to the file path.
+ */
+let usageReadCache: { ino: number; mtimeMs: number; size: number; totals: Record<string, UsageBucket> } | null = null;
+
+export function getSessionUsageTotals(): Record<string, UsageBucket> {
+    const file = resolveRealtimeFile();
+    try {
+        const st = statSync(file);
+        if (relay !== null && relay.state === 'healthy') {
+            if (redisUsageCache && redisUsageCache.ino === st.ino && redisUsageCache.mtimeMs === st.mtimeMs && redisUsageCache.size === st.size) {
+                return redisUsageCache.totals;
+            }
+        }
+        if (usageReadCache && usageReadCache.ino === st.ino && usageReadCache.mtimeMs === st.mtimeMs && usageReadCache.size === st.size) {
+            return usageReadCache.totals;
+        }
+        const disk = JSON.parse(readFileSync(file, 'utf-8')) as RealtimeFile;
+        const totals: Record<string, UsageBucket> = {};
+        for (const [p, raw] of Object.entries(disk.totals ?? {})) totals[p] = normalizeBucket(raw);
+        usageReadCache = { ino: st.ino, mtimeMs: st.mtimeMs, size: st.size, totals };
+        return totals;
+    } catch {
+        // File absent or unreadable: nothing aggregated.
+        usageReadCache = null;
+        return {};
+    }
+}
+
+/**
+ * Global per-second token map (unix second → provider → tokens, already summed
+ * across sessions in storage). Same hot-file mtime+ino+size gate as
+ * {@link getSessionUsageTotals}; seconds older than `windowSecs` are dropped.
+ * Healthy relay → served from the prefetched Redis snapshot.
+ */
+let perSecondReadCache: { ino: number; mtimeMs: number; size: number; perSecond: Record<string, Record<string, number>> } | null = null;
+
+export function getSessionUsagePerSecond(windowSecs = 60): Record<string, Record<string, number>> {
+    const file = resolveRealtimeFile();
+    const cutoff = Math.floor(Date.now() / 1_000) - windowSecs;
+    try {
+        const st = statSync(file);
+        if (relay !== null && relay.state === 'healthy') {
+            if (redisUsageCache && redisUsageCache.ino === st.ino && redisUsageCache.mtimeMs === st.mtimeMs && redisUsageCache.size === st.size) {
+                return filterSeconds(redisUsageCache.perSecond, cutoff);
+            }
+        }
+        if (perSecondReadCache && perSecondReadCache.ino === st.ino && perSecondReadCache.mtimeMs === st.mtimeMs && perSecondReadCache.size === st.size) {
+            return filterSeconds(perSecondReadCache.perSecond, cutoff);
+        }
+        const disk = JSON.parse(readFileSync(file, 'utf-8')) as RealtimeFile;
+        const perSecond = transposeSeconds((disk.seconds ?? {}) as Record<string, Record<string, number>>, cutoff);
+        perSecondReadCache = { ino: st.ino, mtimeMs: st.mtimeMs, size: st.size, perSecond };
+        return perSecond;
+    } catch {
+        perSecondReadCache = null;
+        return {};
+    }
+}
+
+/** Transpose the file's {sec: {provider: tokens}} into {provider: {sec: tokens}}, dropping old seconds. */
+function transposeSeconds(seconds: Record<string, Record<string, number>>, cutoff: number): Record<string, Record<string, number>> {
+    const out: Record<string, Record<string, number>> = {};
+    for (const [sec, secMap] of Object.entries(seconds)) {
+        if (Number(sec) < cutoff) continue;
+        for (const [provider, n] of Object.entries(secMap)) {
+            (out[provider] ??= {})[sec] = n;
+        }
+    }
+    return out;
+}
+
+/** Drop seconds older than `cutoff` from a provider → {sec: tokens} map. */
+function filterSeconds(seconds: Record<string, Record<string, number>>, cutoff: number): Record<string, Record<string, number>> {
+    const out: Record<string, Record<string, number>> = {};
+    for (const [p, secMap] of Object.entries(seconds)) {
+        const m: Record<string, number> = {};
+        for (const [k, v] of Object.entries(secMap)) {
+            if (Number(k) >= cutoff) m[k] = v;
+        }
+        if (Object.keys(m).length > 0) out[p] = m;
+    }
+    return out;
+}
+export function _setCacheFileForTest(path: string | null): void {
+    realtimeFileOverride = path;
+    fetchFileOverride = path === null ? null : deriveSiblingPath(path, 'fetch');
+    legacyFileOverride = path === null ? null : deriveSiblingPath(path, 'legacy');
+}
+
+export function _setRealtimeFileForTest(path: string | null): void {
+    realtimeFileOverride = path;
+}
+
+export function _setFetchFileForTest(path: string | null): void {
+    fetchFileOverride = path;
+}
+
+export function _setLegacyCacheFileForTest(path: string | null): void {
+    legacyFileOverride = path;
+}
+
+export function _resetForTest(): void {
+    if (renderTimer) {
+        clearInterval(renderTimer);
+        renderTimer = null;
+    }
+    lastFetchedByProvider.clear();
+    lastAttemptByProvider.clear();
+    dirtyProviders.clear();
+    pendingProviders.clear();
+    unconfirmedProviders.clear();
+    confirmedThisProcess.clear();
+    directFetcherIds.clear();
+    cachedReports = [];
+    cachedHealth = new Map();
+    lastFlushedBySession.clear();
+    lastSyncedTotals = new Map();
+    perSecondReadCache = null;
+    redisUsageCache = null;
+    if (relay !== null) {
+        relay.close();
+        relay = null;
+    }
+    reconcileIntervalMs = 30_000;
+    onTickRef = undefined;
+    setTickOwner(undefined);
+    minFetchIntervalMs = DEFAULT_MIN_FETCH_INTERVAL_MS;
+    idleDirtyMs = DEFAULT_IDLE_DIRTY_MS;
+    if (realtimeFileOverride !== null || fetchFileOverride !== null) {
+        // Drop any lock files this process left behind (e.g. a crashed worker).
+        for (const file of [resolveRealtimeFile(), resolveFetchFile()]) {
+            try { rmSync(`${file}.lock`); } catch { /* absent */ }
+        }
+    }
+}
+/** Test seam: current relay instance (null when disabled). */
+export function _getRelayForTest(): RedisRelay | null {
+    return relay;
+}
+/** Test seam: current redis prefetch cache (null when not yet prefetched). */
+export function _getRedisUsageCacheForTest(): typeof redisUsageCache {
+    return redisUsageCache;
+}
+export function clearOnTickRef(): void {
+    onTickRef = undefined;
+    setTickOwner(undefined);
+}
+/** True once a session claimed the process-wide tick-render callback. */
+export function hasTickOwner(): boolean {
+    return getTickOwner() !== undefined;
+}