@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/usage-analytics.js

@@ -0,0 +1,663 @@
+/**
+ * Local Usage dashboard accounting from trajectory JSONL.
+ *
+ * Model usage is provider-reported and counted once per model.response. A Jev bypass has no
+ * provider usage: estimate its input only when the same run/node has a preceding measured
+ * response. This is a counterfactual estimate, never billed or actually saved tokens.
+ * The reader never sends model prompts, response text, or tool arguments to the desktop —
+ * neither over the wire nor into the cache file, which holds captured token counts and
+ * identifiers only.
+ *
+ * Records carry the provider id each call ran under, and rows aggregate by that id: it is the
+ * identity every call shares, and grouping by the display name instead would merge two providers
+ * a user named the same. The name is resolved at read time for presentation only — the id is
+ * immutable and the name is what a user renames, so every row a provider contributed shows its
+ * current name. A provider the configuration no longer holds falls back to the raw journaled id
+ * — the only name that record still has.
+ */
+import { createReadStream } from 'node:fs';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadConfig } from './config.js';
+import { providerLabel } from './providers.js';
+const nonnegative = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+/** File facts, unlike token counts, carry sub-millisecond precision on most filesystems. */
+const finiteNonnegative = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+const asObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+const dateOf = (time) => {
+    if (typeof time !== 'string')
+        return undefined;
+    const instant = new Date(time);
+    return Number.isFinite(instant.getTime()) ? instant.toISOString().slice(0, 10) : undefined;
+};
+const keyOf = (providerId, model) => JSON.stringify([providerId, model]);
+const emptyModel = (providerId, provider, model) => ({ providerId, provider, model, inputTokens: 0, outputTokens: 0, cacheRead: 0, savedInputEstimate: 0, bypassedTurns: 0 });
+const emptyDay = (date) => ({ date, inputTokens: 0, outputTokens: 0, cacheRead: 0, savedInputEstimate: 0, bypassedTurns: 0, models: [] });
+/** A streaming collector, also usable with synthetic records in regression tests. */
+export function createUsageCollector(windowDays, now = new Date(), resolveProvider = provider => provider) {
+    if (![7, 30, 365].includes(windowDays))
+        throw new Error('windowDays must be 7, 30, or 365');
+    const midnight = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    const cutoff = new Date(midnight - (windowDays - 1) * 86400000).toISOString().slice(0, 10);
+    const today = new Date(midnight).toISOString().slice(0, 10);
+    const days = new Map();
+    const models = new Map();
+    const baselines = new Map();
+    let unestimatedTurns = 0;
+    const dayFor = (date) => {
+        let day = days.get(date);
+        if (!day) {
+            day = { row: emptyDay(date), models: new Map() };
+            days.set(date, day);
+        }
+        return day;
+    };
+    const modelFor = (collection, providerId, model) => {
+        // Rows aggregate by the journaled id, never by the resolved name: two providers a user named
+        // the same must stay two rows, and a row's tokens must not move when a rename lands.
+        const key = keyOf(providerId, model);
+        let value = collection.get(key);
+        if (!value) {
+            value = emptyModel(providerId, resolveProvider(providerId), model);
+            collection.set(key, value);
+        }
+        return value;
+    };
+    const add = (record) => {
+        const item = asObject(record);
+        if (!item)
+            return;
+        const date = dateOf(item.time);
+        if (!date || date > today)
+            return;
+        if (item.type === 'model.response') {
+            const usage = asObject(item.usage);
+            const input = nonnegative(usage?.inputTokens);
+            const output = nonnegative(usage?.outputTokens);
+            if (input === undefined || output === undefined)
+                return; // missing data is not measured zero
+            const providerId = typeof item.providerId === 'string' ? item.providerId : 'unknown';
+            const model = typeof item.model === 'string' && item.model ? item.model : 'unknown';
+            const cache = Math.min(input, nonnegative(usage?.cacheRead) ?? 0);
+            const identity = JSON.stringify([item.runId, item.nodeId]);
+            // Keep an observed baseline even when it predates the displayed date range.
+            if (typeof item.runId === 'string' && typeof item.nodeId === 'string')
+                baselines.set(identity, { providerId, model, inputTokens: input });
+            if (date < cutoff)
+                return;
+            const day = dayFor(date);
+            for (const target of [day.row, modelFor(day.models, providerId, model), modelFor(models, providerId, model)]) {
+                target.inputTokens += input;
+                target.outputTokens += output;
+                target.cacheRead += cache;
+            }
+            return;
+        }
+        if (item.type !== 'runtime.event')
+            return;
+        const event = asObject(item.event);
+        if (event?.type !== 'decision.turn_bypassed')
+            return;
+        const data = asObject(event.data);
+        const baseline = typeof data?.runId === 'string' && typeof data.nodeId === 'string'
+            ? baselines.get(JSON.stringify([data.runId, data.nodeId])) : undefined;
+        if (date < cutoff)
+            return;
+        const day = dayFor(date);
+        day.row.bypassedTurns++;
+        if (!baseline) {
+            unestimatedTurns++;
+            return;
+        }
+        day.row.savedInputEstimate += baseline.inputTokens;
+        for (const target of [modelFor(day.models, baseline.providerId, baseline.model), modelFor(models, baseline.providerId, baseline.model)]) {
+            target.savedInputEstimate += baseline.inputTokens;
+            target.bypassedTurns++;
+        }
+    };
+    const finish = (filesScanned = 0, incomplete = false) => {
+        const orderedDays = [];
+        for (let i = 0; i < windowDays; i++) {
+            const date = new Date(midnight - (windowDays - i - 1) * 86400000).toISOString().slice(0, 10);
+            const day = days.get(date);
+            orderedDays.push({ ...(day?.row ?? emptyDay(date)), models: [...(day?.models.values() ?? [])].sort((a, b) => b.inputTokens + b.outputTokens - a.inputTokens - a.outputTokens) });
+        }
+        const orderedModels = [...models.values()].sort((a, b) => b.inputTokens + b.outputTokens - a.inputTokens - a.outputTokens);
+        const totals = {
+            inputTokens: orderedModels.reduce((sum, row) => sum + row.inputTokens, 0),
+            outputTokens: orderedModels.reduce((sum, row) => sum + row.outputTokens, 0),
+            cacheRead: orderedModels.reduce((sum, row) => sum + row.cacheRead, 0),
+            savedInputEstimate: orderedModels.reduce((sum, row) => sum + row.savedInputEstimate, 0),
+            bypassedTurns: orderedDays.reduce((sum, day) => sum + day.bypassedTurns, 0),
+            unestimatedTurns,
+        };
+        return { days: orderedDays, models: orderedModels, totals, incomplete, filesScanned, windowDays };
+    };
+    return { add, finish };
+}
+const MAX_FILES = 3000;
+const MAX_FILE_BYTES = 256 * 1024 * 1024;
+const MAX_LINE_BYTES = 8 * 1024 * 1024;
+const MAX_CACHE_BYTES = 64 * 1024 * 1024;
+const MAX_CACHE_RECORDS = 500_000;
+/** Retained records across the whole home; past this, further files are excluded, not read. */
+const MAX_CACHE_RECORDS_TOTAL = 250_000;
+const CACHE_VERSION = 1;
+const NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}\.jsonl$/;
+/** The largest window the collector accepts; files older than its bound are never replayed. */
+const MAX_WINDOW_DAYS = 365;
+/**
+ * Capture the fields the collector reads from one parsed trajectory record, or undefined when the
+ * collector would ignore the record entirely. The guards mirror `createUsageCollector`'s early
+ * returns — the same usage validity and string-typed identifiers — so replaying captured records
+ * into the collector behaves exactly like feeding it the original lines. The display window is
+ * deliberately NOT applied here: a record captured today must survive until tomorrow's window
+ * slides forward, so only the time validity is checked at capture time.
+ */
+const slimOf = (record) => {
+    const item = asObject(record);
+    if (!item)
+        return undefined;
+    if (typeof item.time !== 'string' || !Number.isFinite(new Date(item.time).getTime()))
+        return undefined;
+    if (item.type === 'model.response') {
+        const usage = asObject(item.usage);
+        const input = nonnegative(usage?.inputTokens);
+        const output = nonnegative(usage?.outputTokens);
+        if (input === undefined || output === undefined)
+            return undefined; // missing data is not measured zero
+        const cacheRead = nonnegative(usage?.cacheRead);
+        return {
+            k: 'r', t: item.time,
+            p: typeof item.providerId === 'string' ? item.providerId : 'unknown',
+            m: typeof item.model === 'string' && item.model ? item.model : 'unknown',
+            ...(typeof item.runId === 'string' ? { r: item.runId } : {}),
+            ...(typeof item.nodeId === 'string' ? { n: item.nodeId } : {}),
+            i: input, o: output,
+            ...(cacheRead === undefined ? {} : { c: cacheRead }),
+        };
+    }
+    if (item.type !== 'runtime.event')
+        return undefined;
+    const event = asObject(item.event);
+    if (event?.type !== 'decision.turn_bypassed')
+        return undefined;
+    const data = asObject(event.data);
+    return {
+        k: 'b', t: item.time,
+        ...(typeof data?.runId === 'string' ? { r: data.runId } : {}),
+        ...(typeof data?.nodeId === 'string' ? { n: data.nodeId } : {}),
+    };
+};
+/** Rebuild a collector-shaped record from its slim capture; absent optional fields stay absent. */
+const replayOf = (slim) => slim.k === 'r'
+    ? {
+        type: 'model.response', time: slim.t, providerId: slim.p, model: slim.m,
+        ...(slim.r === undefined ? {} : { runId: slim.r }), ...(slim.n === undefined ? {} : { nodeId: slim.n }),
+        usage: { inputTokens: slim.i, outputTokens: slim.o, ...(slim.c === undefined ? {} : { cacheRead: slim.c }) },
+    }
+    : {
+        type: 'runtime.event', time: slim.t,
+        event: { type: 'decision.turn_bypassed', data: { ...(slim.r === undefined ? {} : { runId: slim.r }), ...(slim.n === undefined ? {} : { nodeId: slim.n }) } },
+    };
+/**
+ * Validate one loaded slim record. Anything malformed is dropped rather than trusted: the cache is
+ * an optimization, and a wrong entry would be a wrong dashboard. The collector re-derives and
+ * re-normalizes every field at replay time, so validation only has to keep the shape honest.
+ */
+const validSlim = (value) => {
+    const item = asObject(value);
+    if (!item || typeof item.t !== 'string' || !Number.isFinite(new Date(item.t).getTime()))
+        return false;
+    if (item.r !== undefined && typeof item.r !== 'string')
+        return false;
+    if (item.n !== undefined && typeof item.n !== 'string')
+        return false;
+    if (item.k === 'b')
+        return true;
+    if (item.k !== 'r')
+        return false;
+    if (typeof item.p !== 'string' || typeof item.m !== 'string')
+        return false;
+    if (nonnegative(item.i) === undefined || nonnegative(item.o) === undefined)
+        return false;
+    return item.c === undefined || nonnegative(item.c) !== undefined;
+};
+/**
+ * Read one file region and capture its complete newline-terminated lines.
+ *
+ * `limit` caps how many records the region may retain; the caller passes the room its per-file
+ * and per-home budgets leave. Once a record would exceed it, retention stops and the rest of the
+ * region is abandoned (`overLimit`, with the stream destroyed early) — the caller excludes or
+ * defers the file, so there is no reason to materialize records that will be thrown away.
+ *
+ * A trailing partial line — a write interrupted before its newline — is left unread: the offset
+ * stops before it and the next scan reads it once the append completes it, instead of parsing a
+ * truncated half-record and flagging every future scan incomplete over a line that was never
+ * whole.
+ */
+async function readRegion(file, start, limit) {
+    const records = [];
+    let bad = false;
+    let failed = false;
+    let consumed = 0;
+    let overLimit = false;
+    // Lines are assembled from a chunk list rather than re-copying an accumulated carry buffer, so
+    // the scan stays linear in file size. A line still unfinished past the record-size bound is
+    // rejected early and the rest of it is discarded without ever being assembled.
+    const pending = [];
+    let pendingBytes = 0;
+    let skipping = false;
+    let skippedBytes = 0;
+    const newlineIn = () => {
+        let offset = 0;
+        for (const chunk of pending) {
+            const index = chunk.indexOf(0x0A);
+            if (index !== -1)
+                return offset + index;
+            offset += chunk.length;
+        }
+        return -1;
+    };
+    const take = (count) => {
+        const parts = [];
+        let remaining = count;
+        let index = 0;
+        while (remaining > 0) {
+            const chunk = pending[index];
+            if (chunk.length <= remaining) {
+                parts.push(chunk);
+                remaining -= chunk.length;
+                index++;
+            }
+            else {
+                parts.push(chunk.subarray(0, remaining));
+                pending[index] = chunk.subarray(remaining);
+                remaining = 0;
+            }
+        }
+        pending.splice(0, index);
+        pendingBytes -= count;
+        return parts.length === 1 ? parts[0] : Buffer.concat(parts);
+    };
+    const absorb = (line) => {
+        if (overLimit)
+            return;
+        if (line.length > MAX_LINE_BYTES) {
+            bad = true;
+            return;
+        }
+        const text = line.toString('utf8');
+        if (!text.trim())
+            return;
+        try {
+            const slim = slimOf(JSON.parse(text));
+            if (slim) {
+                if (records.length >= limit) {
+                    overLimit = true;
+                    stream?.destroy();
+                    return;
+                }
+                records.push(slim);
+            }
+        }
+        catch {
+            bad = true;
+        }
+    };
+    // Created inside the try: an out-of-range start must degrade this one read to `failed` (the
+    // entry is dropped and fully re-read next time), not fail the whole request.
+    let stream;
+    try {
+        stream = createReadStream(file, { start });
+        for await (const chunk of stream) {
+            const buffer = chunk;
+            if (skipping) {
+                // Mid-rejection, a newline-free chunk is discarded as it arrives; only the terminating
+                // newline ends the line, and searching the whole accumulated pile per chunk would be
+                // quadratic in the rejected line's length. Whatever follows the newline in the same
+                // chunk is ordinary content again and falls through to the line processing below.
+                const index = buffer.indexOf(0x0A);
+                if (index === -1) {
+                    skippedBytes += buffer.length;
+                    continue;
+                }
+                skippedBytes += index + 1;
+                consumed += skippedBytes;
+                skippedBytes = 0;
+                skipping = false;
+                const rest = buffer.subarray(index + 1);
+                if (rest.length === 0)
+                    continue;
+                pending.push(rest);
+                pendingBytes += rest.length;
+            }
+            else {
+                pending.push(buffer);
+                pendingBytes += buffer.length;
+            }
+            for (;;) {
+                const index = newlineIn();
+                if (index === -1) {
+                    if (pendingBytes > MAX_LINE_BYTES) {
+                        bad = true;
+                        skipping = true;
+                        skippedBytes = pendingBytes;
+                        pending.length = 0;
+                        pendingBytes = 0;
+                    }
+                    break;
+                }
+                // The newline byte belongs to the consumption, or the next search finds this same
+                // newline at index 0 and takes nothing — an infinite spin on a single-line file.
+                const line = take(index + 1);
+                consumed += index + 1;
+                absorb(line.subarray(0, line.length - 1));
+            }
+        }
+    }
+    catch {
+        if (!overLimit)
+            failed = true;
+    }
+    finally {
+        stream?.destroy();
+    }
+    return { records, consumed, bad, failed, overLimit };
+}
+const cachePath = (directory) => join(directory, 'usage-cache.json');
+/**
+ * Load the persisted cache. Every entry is re-validated; anything malformed, and the whole file
+ * when it is unreadable or from another cache generation, is discarded and rebuilt from the
+ * trajectories.
+ */
+async function loadCache(directory) {
+    const entries = new Map();
+    let stored;
+    try {
+        stored = await readFile(cachePath(directory), 'utf8');
+    }
+    catch {
+        return entries;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stored);
+    }
+    catch {
+        return entries;
+    }
+    const root = asObject(parsed);
+    const files = asObject(root?.files);
+    if (root?.version !== CACHE_VERSION || !files)
+        return entries;
+    for (const [name, raw] of Object.entries(files)) {
+        if (!NAME_PATTERN.test(name))
+            continue;
+        const entry = asObject(raw);
+        if (!entry)
+            continue;
+        // Byte facts (size, offset) index real reads and must stay whole numbers; only the modified
+        // time legitimately carries the filesystem's sub-millisecond precision.
+        const mtimeMs = finiteNonnegative(entry.m);
+        const size = nonnegative(entry.s);
+        const offset = nonnegative(entry.o);
+        if (mtimeMs === undefined || size === undefined || offset === undefined || offset > size)
+            continue;
+        if (entry.r !== null && !Array.isArray(entry.r))
+            continue;
+        if (Array.isArray(entry.r) && !entry.r.every(validSlim))
+            continue;
+        entries.set(name, { mtimeMs, size, offset, bad: entry.b === true, records: entry.r });
+    }
+    return entries;
+}
+/** Publish the cache with one rename, so a reader never sees a truncated file (activity.json's rule). */
+async function persistCache(directory, entries) {
+    const files = {};
+    for (const [name, entry] of entries) {
+        files[name] = { m: entry.mtimeMs, s: entry.size, o: entry.offset, ...(entry.bad ? { b: true } : {}), r: entry.records };
+    }
+    const serialized = JSON.stringify({ version: CACHE_VERSION, files });
+    if (Buffer.byteLength(serialized) > MAX_CACHE_BYTES)
+        return; // Keep the memory cache; skip the disk copy.
+    const target = cachePath(directory);
+    const staging = `${target}.tmp-${process.pid}`;
+    try {
+        await mkdir(directory, { recursive: true });
+        await writeFile(staging, serialized, { mode: 0o600 });
+        await rename(staging, target);
+    }
+    catch { /* Cache persistence is advisory; the next scan rebuilds it. */ }
+    finally {
+        await rm(staging, { force: true }).catch(() => { });
+    }
+}
+const cacheStates = new Map();
+const refreshJobs = new Map();
+/**
+ * Bring one directory's cache up to date: stat every trajectory file, reuse captured records for
+ * unchanged files, read only the appended tail of grown files, and fully re-read anything new,
+ * shrunk, or previously excluded. Concurrent callers share one refresh.
+ *
+ * The refresh is bounded to what a full 365-day scan already spent: files whose modified time
+ * predates the largest window are neither read nor retained, because no request can replay them,
+ * and the home's total retained records stop at a budget, past which further files are deferred —
+ * set aside without being read, reported incomplete, and retried next time the budget has room.
+ * Files inside those bounds are captured regardless of the request's display window — the window
+ * is applied per request — so switching between 7, 30 and 365 days never re-reads anything.
+ */
+async function refreshUsageCache(directory) {
+    const running = refreshJobs.get(directory);
+    if (running)
+        return running;
+    const job = (async () => {
+        let cache = cacheStates.get(directory);
+        if (!cache) {
+            cache = { entries: await loadCache(directory), deferred: new Map() };
+            cacheStates.set(directory, cache);
+        }
+        const { entries, deferred } = cache;
+        const folder = join(directory, 'trajectories');
+        const names = await readdir(folder).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        let failedRead = false;
+        let dirty = false;
+        if (names === null) {
+            if (entries.size) {
+                entries.clear();
+                dirty = true;
+            }
+            deferred.clear();
+        }
+        else {
+            const present = new Set(names.filter(name => NAME_PATTERN.test(name)));
+            // Entries for files that vanished from the directory outright never reach the stat loop
+            // below, so they are pruned here; otherwise a deleted session would keep contributing its
+            // captured records forever.
+            for (const name of [...entries.keys()]) {
+                if (!present.has(name)) {
+                    entries.delete(name);
+                    dirty = true;
+                }
+            }
+            for (const name of [...deferred.keys()]) {
+                if (!present.has(name))
+                    deferred.delete(name);
+            }
+            let retained = 0;
+            for (const entry of entries.values())
+                retained += entry.records?.length ?? 0;
+            // The aged-out bound is the largest window's, so a file pruned here is one no replay would
+            // ever visit; pruning it cannot change any answer.
+            const agedOut = Date.now() - (MAX_WINDOW_DAYS + 1) * 86400000;
+            for (const name of [...present].sort()) {
+                const file = join(folder, name);
+                const info = await stat(file).catch(() => undefined);
+                let entry = entries.get(name);
+                if (!info || !info.isFile() || info.mtimeMs < agedOut) {
+                    if (entry) {
+                        retained -= entry.records?.length ?? 0;
+                        entries.delete(name);
+                        dirty = true;
+                    }
+                    deferred.delete(name);
+                    continue;
+                }
+                const exclude = () => {
+                    if (entry)
+                        retained -= entry.records?.length ?? 0;
+                    if (!entry || entry.records !== null || entry.mtimeMs !== info.mtimeMs || entry.size !== info.size) {
+                        entries.set(name, { mtimeMs: info.mtimeMs, size: info.size, offset: 0, bad: false, records: null });
+                        dirty = true;
+                    }
+                };
+                // A deferral holds no records and is retried whenever the budget has room again.
+                const defer = () => {
+                    if (entry) {
+                        retained -= entry.records?.length ?? 0;
+                        entries.delete(name);
+                        dirty = true;
+                    }
+                    deferred.set(name, info.mtimeMs);
+                };
+                if (info.size > MAX_FILE_BYTES) {
+                    exclude();
+                    continue;
+                }
+                if (entry?.records === null) {
+                    if (entry.mtimeMs === info.mtimeMs && entry.size === info.size)
+                        continue;
+                    entries.delete(name);
+                    entry = undefined;
+                    dirty = true;
+                }
+                if (entry && entry.mtimeMs === info.mtimeMs && entry.size === info.size)
+                    continue;
+                // A file with nothing cached is only read when the budget has room: past it, further
+                // files are set aside without being read at all, the answer's incomplete flag covers
+                // them, the heap stays bounded, and the next refresh retries them. A file that already
+                // has records is settled after the read, when the actual delta is known — refusing it
+                // here would throw away good history over an append that may add none.
+                if (entry === undefined && retained >= MAX_CACHE_RECORDS_TOTAL) {
+                    defer();
+                    continue;
+                }
+                // Only a strictly grown file is tailed; a same-size rewrite with a fresh mtime gets a full
+                // read, because bytes before the offset cannot be trusted to match what was captured.
+                const prior = entry && entry.records !== null ? entry.records : null;
+                const priorCount = prior?.length ?? 0;
+                const tail = prior !== null && info.size > entry.size;
+                // The reader stops retaining at the tighter of the two budgets, so a file far over either
+                // bound never materializes records that would be discarded. A tail keeps its prior
+                // records, so they consume both budgets; a full read replaces them, so they are credited
+                // back — otherwise a truncate could refuse a replacement that fits comfortably.
+                const perFileRoom = tail ? MAX_CACHE_RECORDS - priorCount : MAX_CACHE_RECORDS;
+                const budgetRoom = MAX_CACHE_RECORDS_TOTAL - retained + (tail ? 0 : priorCount);
+                const region = await readRegion(file, tail ? entry.offset : 0, Math.max(0, Math.min(perFileRoom, budgetRoom)));
+                if (region.failed) {
+                    failedRead = true;
+                    retained -= priorCount;
+                    entries.delete(name);
+                    dirty = true;
+                    continue;
+                }
+                if (region.overLimit) {
+                    // The file exceeded the tighter bound: an over-large file is intrinsically excluded,
+                    // while a budget-bound one is set aside and retried when the budget has room.
+                    if (perFileRoom <= budgetRoom)
+                        exclude();
+                    else
+                        defer();
+                    continue;
+                }
+                const records = tail ? prior.concat(region.records) : region.records;
+                // The limit makes these unreachable; they stay as the final guard on the retained shape.
+                if (records.length > MAX_CACHE_RECORDS) {
+                    exclude();
+                    continue;
+                }
+                if (retained - priorCount + records.length > MAX_CACHE_RECORDS_TOTAL) {
+                    defer();
+                    continue;
+                }
+                retained += records.length - (prior?.length ?? 0);
+                deferred.delete(name);
+                if (tail) {
+                    entry.records = records;
+                    entry.offset += region.consumed;
+                    entry.bad = entry.bad || region.bad;
+                    entry.mtimeMs = info.mtimeMs;
+                    entry.size = info.size;
+                }
+                else {
+                    entries.set(name, { mtimeMs: info.mtimeMs, size: info.size, offset: region.consumed, bad: region.bad, records });
+                }
+                dirty = true;
+            }
+        }
+        if (dirty)
+            await persistCache(directory, entries);
+        return { entries, deferred, failedRead };
+    })();
+    refreshJobs.set(directory, job);
+    void job.catch(() => { }).finally(() => { if (refreshJobs.get(directory) === job)
+        refreshJobs.delete(directory); });
+    return job;
+}
+/**
+ * Map each journaled provider id to the name a person reads for it.
+ *
+ * The configuration is the one place the current display names live, and grouping rows by the
+ * resolved name is what makes a rename cover past runs: the journals keep the immutable id, and
+ * this is the only translation between the two. A configuration that cannot be read keeps every
+ * id as itself — usage accounting must not fail over a broken config, and an id the configuration
+ * no longer holds falls back to the raw journaled string anyway.
+ */
+async function providerNameResolver(directory) {
+    try {
+        const config = await loadConfig(directory);
+        const labels = new Map(config.providers.map(provider => [provider.id, providerLabel(provider, config.providers)]));
+        return (providerId) => labels.get(providerId) ?? providerId;
+    }
+    catch {
+        return providerId => providerId;
+    }
+}
+/**
+ * Local-only read, bounded by modified time, file count and record size, served from a per-file
+ * cache of the records the collector consumes. The replay visits the captured records in the same
+ * order a full read would — files sorted by name, lines in file order — so the answer is the one
+ * the equivalent full scan produces, whatever the cache happened to hold.
+ */
+export async function readUsageAnalytics(directory, windowDays) {
+    const { entries, deferred, failedRead } = await refreshUsageCache(directory);
+    const collector = createUsageCollector(windowDays, new Date(), await providerNameResolver(directory));
+    const earliest = Date.now() - (windowDays + 1) * 86400000;
+    let scanned = 0;
+    let incomplete = failedRead;
+    for (const name of [...entries.keys()].sort()) {
+        const entry = entries.get(name);
+        if (entry.mtimeMs < earliest)
+            continue;
+        if (entry.records === null || scanned >= MAX_FILES) {
+            incomplete = true;
+            continue;
+        }
+        scanned++;
+        if (entry.bad)
+            incomplete = true;
+        for (const slim of entry.records)
+            collector.add(replayOf(slim));
+    }
+    // Deferred files were never read this round; within a window that would have read them, the
+    // answer says so rather than presenting their absence as an empty measurement.
+    for (const mtimeMs of deferred.values()) {
+        if (mtimeMs >= earliest)
+            incomplete = true;
+    }
+    return collector.finish(scanned, incomplete);
+}