taskchef 9.2.0 → 9.4.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "9.2.0",
+  "version": "9.4.0",
   "description": "Native Codex dashboard with lightweight project delegation.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -6,9 +6,33 @@ Chats appear regardless of how they were started.
 
 ## Install
 
-Install **TaskChef** from the `favoyang-plugins` Codex marketplace. TaskChef uses
-a local Node.js MCP server; Node.js 22.18+, 23.2+, or 24+ is required. Open **TaskChef**
-from the Codex sidebar. No dispatcher workspace or project indexing is needed.
+TaskChef's marketplace lives in this repository. In Codex, open **Settings →
+Plugins → Add → Add a marketplace** and use
+`https://github.com/favoyang/taskchef.git`. Leave the Git ref as `main` and Sparse
+paths empty. Open **Plugins → Personal**, find **TaskChef** under **TaskChef**,
+and install it.
+
+Alternatively, use the Codex CLI:
+
+```sh
+codex plugin marketplace add favoyang/taskchef
+codex plugin add taskchef@taskchef
+```
+
+Restart Codex. Open **…** below Plugins in the left dock, find **TaskChef**, and
+pin it to keep the board in the sidebar. TaskChef uses a local Node.js MCP
+server and npm. Supported Node.js versions are 22.18+ in the 22 series, or
+23.2 and newer. Node.js 24 is recommended for a new installation. Server
+dependencies are included in the published package.
+
+### Move from the shared marketplace
+
+If you installed `taskchef@favoyang-plugins`, add the new marketplace and install
+`taskchef@taskchef` with the commands above. After it installs successfully,
+remove the old plugin with `codex plugin remove taskchef@favoyang-plugins`, then
+restart Codex. Keep only one released TaskChef installation enabled. Local
+settings, GitHub credentials, and Codex chat history are independent of the
+marketplace cache and do not need to be reset. TaskChef Dev stays separate.
 
 Codex databases and logs stay on your computer and remain the source of truth.
 TaskChef keeps its own settings, manual Done marks, notification state, and
@@ -48,3 +72,8 @@ name; apply that identity only to its local staging package. See
 [development packaging](docs/mcp-app.md#development-plugin-identity).
 
 [Native app guide](docs/mcp-app.md) · [GitHub setup](docs/taskchef-next-github.md)
+
+## Feedback
+
+[Report a bug](https://github.com/favoyang/taskchef/issues/new?template=bug_report.yml)
+or [request a feature](https://github.com/favoyang/taskchef/issues/new?template=feature_request.yml).

package/docs/mcp-app.md

@@ -83,14 +83,13 @@ Open the installed TaskChef plugin details page to edit its native
 settings. The sidebar receives them at its next visible refresh, or immediately
 when Refresh is clicked. Settings persist across sidebar and embedded views.
 The old browser-local visibility keys are no longer used; configure the native
-switches once after upgrading. The Board/List choice stays browser-local.
+switches once after upgrading. The Board opens by default.
 See the [OpenAI structured settings specification](https://github.com/openai/mcp-extensions/blob/main/docs/spec.md#structured-settings).
 
 ### Board presentation
 
-TaskChef exposes only Board. The List implementation remains in the
-source, but the Board/List selector is hidden and saved List choices are
-ignored. Interrupted chats appear in Waiting for input/review with an
+TaskChef exposes Board and Usage. The List implementation remains in the
+source, but List is hidden and saved List choices are ignored. Interrupted chats appear in Waiting for input/review with an
 Interrupted tag; their recorded status remains available in Details.
 Scheduled, Running, Waiting, and Done remain visible when empty, with a short
 message specific to each column. This keeps their positions steady when chats
@@ -337,3 +336,75 @@ message does not cause polling to replay it. Other features continue working. Th
 second, and missing chat snapshots wait at most 250 ms for all subscriptions
 combined. Hidden views do not initiate refreshes; an existing subscription can
 still receive live updates while the MCP process remains running.
+
+## Marketplace and release ownership
+
+The public catalog is `.agents/plugins/marketplace.json` in this repository.
+Its marketplace name is `taskchef`; the released install is `taskchef@taskchef`.
+The catalog pins a published npm package containing the built UI and production
+server dependencies. A raw Git checkout is not a packaged release.
+
+After semantic-release publishes, the marketplace job checks the expected npm
+version and archive, then commits only the catalog pin on the latest `main`.
+A failed check leaves the prior pin in place and fails the workflow. The job
+uses this repository's GitHub token; no shared-marketplace deploy key is needed.
+If the push loses a race with another main update, rerun the Release workflow
+on main to retry after checking the current published version. Do not force push.
+
+Keep TaskChef Dev in a separate local marketplace named `taskchef-next-preview`,
+with plugin ID `taskchef-next` and display name **TaskChef Dev**. Store that
+marketplace and its staging packages in a persistent local folder, outside
+this public checkout. Its catalog uses `source.source: local` with a path to
+the prepared staging package. Add that folder with
+`codex plugin marketplace add /path/to/local-dev-marketplace`, then install
+`codex plugin add taskchef-next@taskchef-next-preview`. This can coexist with
+`taskchef@taskchef`. Never rename the source release manifest for Dev.
+
+Retire the old shared catalog entry only after this repository's catalog is
+live, the release workflow has completed, and a clean installation from the
+new marketplace succeeds. Existing users must migrate explicitly; changing
+a marketplace does not automatically move their installed plugin identity.
+
+## Usage analytics
+
+![Usage analytics with sample data](images/usage-analytics.jpg)
+
+The Board/Usage selector sits beside the logo in the navbar, separated from
+Board filters by a divider. It opens an on-demand historical usage view. Ranges are
+7, 30, or 90 calendar days including today, This month (the default, through
+today), and Last month (the full previous calendar month).
+There is no custom range. Dates use the view's local timezone, including DST.
+Range changes and reopening Usage query one shared history snapshot without
+rescanning logs. The snapshot is scoped by CLI/exec visibility, independently of
+range or timezone. After one minute it refreshes in the background while cached
+charts remain visible. Refresh explicitly rebuilds it, reusing existing per-file
+metadata and incremental parsing caches. Unchanged files retain parsed records
+on disk across restarts and turn or price changes. A session filename index
+avoids searching the full inventory for each chat. Missing paths do not incur
+reader retry delays. Empty or mismatched files are checked again when their
+metadata changes; transient I/O failures retry while retaining healthy sources.
+Rescan explicitly reparses available files and refreshes the inventory, while
+retaining known history for missing sources. Board polling never starts a history scan.
+
+The combined chart uses cost bars on the left axis and a token line on the
+right. Today's cost bars have a lighter fill and dashed borders in both charts;
+the token segment leading into today is dashed too. Finished days, including
+the last day of Last month, stay solid. The project chart uses stacked cost bars for the period's top five
+projects plus Other. Select a legend entry or a Top 10 row to isolate that
+project in the project chart; All projects restores the stack. Hovering or
+focusing a legend entry highlights its bars and dims other project colors. Totals, the
+combined chart, and rankings always describe the full selected period.
+
+Archived chats and descendant usage are included. CLI/exec visibility settings
+still apply to root chats. Descendants are counted once under their root chat's
+current project. Unassigned chats share one Unassigned project. Daily usage
+comes from recorded call timestamps, not chat creation or last-update dates.
+Unexplained cumulative counter gaps stay in lifetime totals but are excluded
+from daily totals because their dates are unknown. Missing records or prices
+remain marked in the analytics response without displaying coverage warnings.
+Unknown costs are excluded from estimated cost.
+Cached input is part of input tokens, and reasoning output is part of output.
+Cost is an estimate at current API-equivalent rates, not subscription billing
+or remaining allowance. The first read shows a progress bar with the actual number of root chats
+processed and polls an app-only tool. Cached charts stay visible during later
+refreshes, with their last-update time and scan progress.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "9.2.0",
+  "version": "9.4.0",
   "description": "A native Codex dashboard for chats, usage, pull requests, and schedules.",
   "license": "Apache-2.0",
   "author": "Favo Yang",

package/src/codex-rollout.js

@@ -4,19 +4,19 @@ import * as zlib from "node:zlib";
 export function plainRolloutPath(path) { return path.replace(/\.jsonl\.zst$/, ".jsonl"); }
 
 // Codex can replace either representation while readers are resolving a path.
-async function resolve(path, inspect) {
+async function resolve(path, inspect, retries = 3) {
   const plain = plainRolloutPath(path);
   for (let attempt = 0; ; attempt++) {
     for (const candidate of [plain, `${plain}.zst`]) {
       try { return { path: candidate, ...await inspect(candidate) }; }
       catch (error) { if (error.code !== "ENOENT") throw error; }
     }
-    if (attempt === 3) { const error = new Error("Rollout is missing."); error.code = "ENOENT"; throw error; }
+    if (attempt === retries) { const error = new Error("Rollout is missing."); error.code = "ENOENT"; throw error; }
     await new Promise(resolve => setTimeout(resolve, 50));
   }
 }
 
-export function rolloutMetadata(path) { return resolve(path, async path => ({ info: await stat(path) })); }
+export function rolloutMetadata(path, { retries = 3 } = {}) { return resolve(path, async path => ({ info: await stat(path) }), retries); }
 export function openRollout(path) {
   return resolve(path, async path => {
     const handle = await open(path, "r");

package/src/codex-session-scanner.js

@@ -1,3 +1,4 @@
+import { aggregateUsage } from "./usage-analytics.js";
 import { openRollout, rolloutChunks } from "./codex-rollout.js";
 import { createHash } from "node:crypto";
 import { normalizeUri } from "micromark-util-sanitize-uri";
@@ -239,9 +240,10 @@ function readDatabaseRecords(state, history) {
       FROM thread_turns WHERE thread_id = ? ORDER BY rollout_ordinal DESC LIMIT 1`);
     const turns = new Map();
     const needsAnswers = new Map();
-    const rows = state.prepare(`SELECT id, name, title, cwd, archived, ${hasPinned ? "is_pinned" : "0 AS is_pinned"}, source, created_at_ms, updated_at_ms, recency_at_ms, rollout_path, history_mode, project_id,
+    const allRows = state.prepare(`SELECT id, name, title, cwd, archived, ${hasPinned ? "is_pinned" : "0 AS is_pinned"}, source, created_at_ms, updated_at_ms, recency_at_ms, rollout_path, history_mode, project_id,
       (SELECT count(*) FROM thread_spawn_edges WHERE parent_thread_id = threads.id) AS child_count
-      FROM threads WHERE ${eligible} ORDER BY recency_at_ms DESC`).all().filter((row) => {
+      FROM threads WHERE ${eligible} ORDER BY recency_at_ms DESC`).all();
+    const rows = allRows.filter((row) => {
       const key = historyId(row);
       const turn = latestTurn.get(key);
       if (!turn) return false;
@@ -285,7 +287,7 @@ function readDatabaseRecords(state, history) {
         attachments.set(row.thread_id, urls);
       }
     }
-    return { rows, turns, inputs, replies, projects, attachments, turnAttachments, needsAnswers };
+    return { rows, allRows, turns, inputs, replies, projects, attachments, turnAttachments, needsAnswers };
 }
 
 function buildDatabaseSnapshot(records, now, doneMarks, schedules, scheduleErrors, cacheHit) {
@@ -649,6 +651,39 @@ export class CodexSessionScanner {
     ) SELECT id, rollout_path FROM threads WHERE id IN (SELECT id FROM family)`).all(id);
     return this.sessionUsage.read({ id, latestTurnId: task.turnId, sessions, savedDurations });
   }
+  async usageAnalytics({ range, timeZone, settings }) {
+    return aggregateUsage(await this.usageHistory({ settings }), { range, timeZone, now: this.now() });
+  }
+  async usageHistory({ settings, onProgress = () => {}, rescan = false }) {
+    if (rescan) this.sessionUsage.inventoryAt = -Infinity;
+    const snapshot = await this.refresh();
+    if (!snapshot.healthy) throw new Error(snapshot.scan.error);
+    const records = this.databaseCache.records;
+    // Analytics inventories every root, even if its latest turn is absent from
+    // the board's history database. Its rollout can still hold valid usage.
+    const grouped = await this.projectCatalog.group(records.allRows.map(row => ({
+      id: row.id, turnId: records.turns.get(historyId(row))?.turn_id ?? null,
+      project: { id: row.project_id, path: row.cwd || "", githubRepos: [] }, observed: { source: row.source },
+    })), records.projects);
+    const families = [];
+    const seen = new Set();
+    // History includes archived chats. CLI/exec preferences still apply.
+    const tasks = grouped.tasks.filter(task => (settings.showCli || task.observed?.source !== "cli") && (settings.showExec || task.observed?.source !== "exec"));
+    let completed = 0;
+    onProgress({ completed, total: tasks.length });
+    for (const task of tasks) {
+      const sessions = this.connections.state.prepare(`WITH RECURSIVE family(id) AS (
+        SELECT ? UNION SELECT child_thread_id FROM thread_spawn_edges JOIN family ON parent_thread_id = family.id
+      ) SELECT id, rollout_path FROM threads WHERE id IN (SELECT id FROM family)`).all(task.id).filter(row => !seen.has(row.id));
+      if (sessions.length) {
+        sessions.forEach(row => seen.add(row.id));
+        const usage = await this.sessionUsage.read({ id: task.id, latestTurnId: task.turnId, sessions, rescan });
+        families.push({ project: task.project, usage });
+      }
+      onProgress({ completed: ++completed, total: tasks.length });
+    }
+    return families;
+  }
   recordedUsage(id, turnId) {
     const result = (this.recordedPending ?? Promise.resolve()).then(() => this.readRecordedUsage(id, turnId));
     this.recordedPending = result.catch(() => {});
@@ -711,7 +746,7 @@ export class CodexSessionScanner {
     let detail = { ...task, ...records.latestContent.get(id), detailPullRequests, observed: { ...task.observed,
       recordedChatDurationMs: durations.total ?? 0, missingTurnDurations: durations.missing ?? 0 } };
     try {
-      const sessionUsage = await this.taskUsage(id, durations.saved);
+      const { timeline: _timeline, analyticsPartial: _analyticsPartial, ...sessionUsage } = await this.taskUsage(id, durations.saved);
       detail = { ...detail, sessionUsage, observed: { ...detail.observed,
         ...(sessionUsage.durationTurns ? { recordedChatDurationMs: Math.max(durations.total ?? 0, sessionUsage.durationMs) } : {}),
         historicalTimePartial: sessionUsage.partial || !sessionUsage.durationTurns } };

package/src/codex-session-usage.js

@@ -19,7 +19,7 @@ const bucket = () => ({ tokens: zero(), costUsd: 0, partial: false, costPartial:
 // Cumulative totals and call counters are independent. A missing boundary can
 // leave one turn partial without preventing later calls from being allocated.
 export function summarizeRecords(records, latestTurnId, models, child = false) {
-  const total = bucket(), latest = bucket(), durations = new Map(), seen = new Set();
+  const total = bucket(), latest = bucket(), durations = new Map(), seen = new Set(), timeline = [];
   let previous = zero();
   for (const record of [...records].sort((a, b) => a.time - b.time || a.order - b.order)) {
     const key = JSON.stringify([record.time, record.kind, record.turn, record.root, record.model, record.total, record.last, record.duration]);
@@ -56,6 +56,10 @@ export function summarizeRecords(records, latestTurnId, models, child = false) {
     const price = estimateCallCost(last, record.model, models);
     total.costUsd += price ?? 0;
     total.costPartial ||= !complete || price == null;
+    // Only the last call has a known timestamp. An unexplained cumulative gap
+    // belongs in lifetime totals, not arbitrarily on the day it was noticed.
+    if (record.time > 0) timeline.push({ time: record.time, tokens: complete || reset ? captured : last,
+      costUsd: price ?? 0, samples: 1, partial: !complete, costPartial: !complete || price == null });
     total.partial ||= reset;
     const belongs = (child ? record.root : record.turn) === latestTurnId;
     if (belongs) {
@@ -67,7 +71,7 @@ export function summarizeRecords(records, latestTurnId, models, child = false) {
       latest.partial = latest.costPartial = true;
     }
   }
-  return { total, latest, durations };
+  return { total, latest, durations, timeline };
 }
 
 async function inventory(root, paths = []) {
@@ -84,7 +88,7 @@ async function inventory(root, paths = []) {
 export class CodexSessionUsage {
   constructor({ codexHome, now = Date.now, pricing, cacheDir, legacyCacheDir }) {
     this.home = codexHome; this.now = now; this.pricing = pricing; this.cacheDir = cacheDir; this.legacyCacheDir = legacyCacheDir;
-    this.files = new Map(); this.paths = []; this.inventoryAt = -Infinity;
+    this.files = new Map(); this.paths = []; this.pathsBySession = new Map(); this.inventoryAt = -Infinity;
     this.pending = Promise.resolve();
     this.results = new Map();
   }
@@ -94,7 +98,7 @@ export class CodexSessionUsage {
     this.pending = result.catch(() => {});
     return result;
   }
-  async readOnce({ id, latestTurnId, sessions, savedDurations = [] }) {
+  async readOnce({ id, latestTurnId, sessions, savedDurations = [], rescan = false }) {
     if (this.legacyCacheDir && this.cacheDir) {
       try { await migrateCache(this.legacyCacheDir, this.cacheDir); this.legacyCacheDir = null; }
       catch { /* Optional caches never prevent reading source usage. */ }
@@ -103,6 +107,13 @@ export class CodexSessionUsage {
     if (this.now() - this.inventoryAt >= 60_000) {
       try {
         this.paths = [...await inventory(join(this.home, "sessions")), ...await inventory(join(this.home, "archived_sessions"))];
+        this.pathsBySession = new Map();
+        for (const path of this.paths) {
+          for (const [id] of basename(path).matchAll(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi)) {
+            if (!this.pathsBySession.has(id)) this.pathsBySession.set(id, []);
+            this.pathsBySession.get(id).push(path);
+          }
+        }
         this.inventoryAt = this.now();
       } catch { inventoryFailed = true; }
     }
@@ -111,11 +122,11 @@ export class CodexSessionUsage {
     const pricing = await this.pricing.get();
     const sources = [];
     for (const session of sessions) {
-      const paths = new Set(this.paths.filter(path => basename(path).includes(`-${session.id}`)));
+      const paths = new Set(this.sessionPaths(session.id));
       if (session.rollout_path) paths.add(plainRolloutPath(session.rollout_path));
       const versions = [];
       for (const path of paths) {
-        try { const { info } = await rolloutMetadata(path); versions.push([path, info.dev, info.ino, info.size, info.mtimeMs]); }
+        try { const { info } = await rolloutMetadata(path, { retries: 0 }); versions.push([path, info.dev, info.ino, info.size, info.mtimeMs]); }
         catch { versions.push([path, "missing"]); }
       }
       sources.push([session.id, versions]);
@@ -127,7 +138,7 @@ export class CodexSessionUsage {
     if (!saved && cachePath) {
       try {
         const value = JSON.parse(await readFile(cachePath, "utf8"));
-        if (value.version === 1 && validResult(value.result)) saved = value;
+        if ([1, 2, 3].includes(value.version) && validResult(value.result) && (value.version === 1 || (Array.isArray(value.result.timeline) && value.result.timeline.every(sample => Number.isFinite(sample.time) && usage(sample.tokens) && Number.isFinite(sample.costUsd) && sample.costUsd >= 0 && sample.samples === 1 && typeof sample.partial === "boolean" && typeof sample.costPartial === "boolean")))) saved = value;
       } catch { /* An absent or damaged cache is rebuilt from source records. */ }
     }
     const sourceKeys = (items) => items.flatMap(([sessionId, versions]) => versions
@@ -153,29 +164,41 @@ export class CodexSessionUsage {
       })) knownSources = [];
     } catch { knownSources = []; /* No prior valid source coverage is available. */ }
     const missingSources = knownSources.filter(key => !currentSources.has(key));
-    if (saved?.recordSources && saved.sourceSignature === sourceSignature) { this.results.set(resultKey, saved); return saved.result; }
+    if (!rescan && !saved?.retryRead && saved?.version === 3 && typeof saved.result.analyticsPartial === "boolean" && saved.recordSources && saved.sourceSignature === sourceSignature) { this.results.set(resultKey, saved); return saved.result; }
     const availablePaths = new Set(sources.flatMap(([, versions]) => versions.filter(version => version.length > 2).map(version => version[0])));
     let retryRead = false;
     const parsed = [];
     const recordSources = {};
+    const sourceFiles = {};
     for (const session of sessions) {
-      const paths = new Set(this.paths.filter(path => basename(path).includes(`-${session.id}`)));
+      const paths = new Set(this.sessionPaths(session.id));
       if (session.rollout_path) paths.add(plainRolloutPath(session.rollout_path));
       const records = [], versions = [];
       let failed = inventoryFailed, latestFailed = false, timePartial = inventoryFailed;
       if (!paths.size) failed = latestFailed = timePartial = true;
       for (const path of paths) {
         try {
-          const file = await this.readFile(path, session.id);
+          const sourceKey = JSON.stringify([session.id, basename(path)]);
+          const stamp = sources.find(([sessionId]) => sessionId === session.id)?.[1].find(version => version[0] === path);
+          if (!availablePaths.has(path)) throw new Error("Rollout is missing.");
+          const previous = saved?.sourceFiles?.[sourceKey];
+          let file;
+          if (!rescan && previous && JSON.stringify(previous.stamp) === JSON.stringify(stamp) && Array.isArray(saved.recordSources?.[sourceKey])) {
+            file = { records: saved.recordSources[sourceKey], partial: previous.partial };
+          } else {
+            if (rescan) this.files.delete(path);
+            file = await this.readFile(path, session.id);
+          }
+          sourceFiles[sourceKey] = { stamp, partial: file.partial };
           for (const record of file.records) records.push(record);
           recordSources[JSON.stringify([session.id, basename(path)])] = file.records;
           versions.push([path, file.identity, file.size, file.mtime]);
           timePartial ||= file.partial;
-        } catch {
+        } catch (error) {
           failed = timePartial = true;
           const sourceKey = JSON.stringify([session.id, basename(path)]);
           if (Array.isArray(saved?.recordSources?.[sourceKey]) && !missingSources.includes(sourceKey)) missingSources.push(sourceKey);
-          retryRead ||= availablePaths.has(path);
+          retryRead ||= availablePaths.has(path) && error.code !== "INVALID_ROLLOUT";
           latestFailed ||= session.id !== id || path === plainRolloutPath(session.rollout_path ?? "");
           versions.push([path, "missing"]);
         }
@@ -188,7 +211,7 @@ export class CodexSessionUsage {
       if (Array.isArray(rows) && rows.every(row => row && Number.isFinite(row.time) && ["usage", "duration", "issue"].includes(row.kind))) recordSources[key] = rows;
     }
     const result = { latest: bucket(), total: bucket(), subagents: sessions.length - 1, pricingDate: pricing.date,
-      durationMs: 0, durationTurns: 0, partial: inventoryFailed };
+      durationMs: 0, durationTurns: 0, timeline: [], analyticsPartial: inventoryFailed, partial: inventoryFailed };
     for (const { session, records, failed, latestFailed, timePartial } of parsed) {
       const summary = summarizeRecords(records, latestTurnId, pricing.models, session.id !== id);
       const retained = missingSources.filter(key => JSON.parse(key)[0] === session.id).flatMap(key => recordSources[key] ?? []);
@@ -202,7 +225,10 @@ export class CodexSessionUsage {
         summary.latest.partial ||= missing.latest.samples > 0 || missing.latest.partial;
         summary.latest.costPartial ||= missing.latest.samples > 0 || missing.latest.costPartial;
         summary.durations = combined.durations;
+        summary.timeline = combined.timeline;
       }
+      result.analyticsPartial ||= timePartial || summary.total.tokens.total_tokens !== summary.timeline.reduce((sum, sample) => sum + sample.tokens.total_tokens, 0);
+      result.timeline.push(...summary.timeline);
       for (const key of ["total", "latest"]) {
         add(result[key].tokens, summary[key].tokens);
         result[key].costUsd += summary[key].costUsd;
@@ -221,6 +247,7 @@ export class CodexSessionUsage {
       }
     }
     if (missingSources.length) {
+      result.analyticsPartial = true;
       result.total.partial = result.total.costPartial = true;
       const prior = saved?.result.total;
       if (prior) {
@@ -240,22 +267,29 @@ export class CodexSessionUsage {
       }
       if (missingSources.some(key => JSON.parse(key)[0] === id)) result.partial = true;
     }
-    const entry = { version: 1, sourceSignature, result, recordSources, knownSources: [...new Set([...knownSources, ...currentSources])] };
-    // Retry readable-looking sources after I/O failures; do not freeze a transient
-    // failure under an otherwise unchanged metadata fingerprint.
-    if (!retryRead) this.results.set(resultKey, entry);
-    if (cachePath && !inventoryFailed && !retryRead) {
+    const entry = { version: 3, sourceSignature, result, recordSources, sourceFiles, retryRead, knownSources: [...new Set([...knownSources, ...currentSources])] };
+    // Keep successful sources even if another source failed. Retry failures on
+    // the next read without reparsing all healthy historical files.
+    this.results.set(resultKey, entry);
+    if (cachePath && !inventoryFailed) {
       try { await writeDurableAtomic(cachePath, JSON.stringify(entry) + "\n", { mode: 0o600 }); }
       catch { /* Cache write failures do not hide readable source usage. */ }
     }
     return result;
   }
+  sessionPaths(id) {
+    // Production chat IDs are UUIDs. Index once instead of walking every filename
+    // for every root and descendant on each refresh.
+    return /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(id)
+      ? this.pathsBySession.get(id) ?? []
+      : this.paths.filter(path => basename(path).includes(`-${id}`));
+  }
   async readFile(path, expectedId) {
     const source = await openRollout(path);
     try {
       path = plainRolloutPath(path);
       const { info } = source;
-      if (!info.isFile() || info.size === 0) throw new Error("Rollout is empty or not a file.");
+      if (!info.isFile() || info.size === 0) throw Object.assign(new Error("Rollout is empty or not a file."), { code: "INVALID_ROLLOUT" });
       let cached = this.files.get(path);
       if (cached && cached.identity === `${info.dev}:${info.ino}` && cached.size === info.size && cached.mtime === info.mtimeMs) return this.sourceView(cached, expectedId);
       const compressed = source.path.endsWith(".zst");
@@ -283,7 +317,7 @@ export class CodexSessionUsage {
       cached.size = info.size; cached.mtime = info.mtimeMs;
       cached.tail = pending; cached.skipping = skipping;
       const view = this.sourceView(cached, expectedId);
-      if (!view.valid) throw new Error("Rollout belongs to a different chat.");
+      if (!view.valid) throw Object.assign(new Error("Rollout belongs to a different chat."), { code: "INVALID_ROLLOUT" });
       this.files.set(path, cached);
       return view;
     } finally { await source.handle.close(); }