taskchef 9.3.0 → 9.5.0

package/.codex-plugin/plugin.json

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

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
@@ -300,7 +299,7 @@ UI surfaces. Native font families use locally available fonts with system fallba
 read the installed desktop application or fetch theme files from the network.
 
 The compact **Pinned** toggle button shows chats pinned in Codex and combines with project,
-update window, and search filters. It starts off when the dashboard opens. Pin
+update window, and search filters. It defaults to off and remembers the user’s selection locally. Pin
 changes appear on the next data refresh. The current desktop pin list takes
 precedence over the database `is_pinned` field. TaskChef ignores old migration
 snapshots and never writes pin state. Without either source, chats are unpinned.
@@ -365,3 +364,87 @@ 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 (through today), and
+Last month (the full previous calendar month). The default is 30 days; the
+selected range is remembered locally when Usage is reopened.
+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.
+
+## Month calendar
+
+Calendar sits beside Board and Usage. It opens on the current local month;
+previous/next arrows surround the month title. Next is disabled at the current
+local month, so future months cannot be selected. There is no Today control.
+Arrows stay hidden until the month navigation is hovered or contains focus;
+a clicked arrow remains visible while focused. This also applies in embedded
+hosts that do not report mouse hover support. Project, search, update window, and Pinned
+filters are remembered locally. An unavailable saved project resets to All
+projects only after the project inventory loads.
+Project, Search Chats, Pinned, and native visibility settings apply. The Board's
+Updated filter does not apply to Calendar. A Calendar-only Scheduled
+toggle starts enabled and hides chats with an active schedule when disabled,
+including those currently Running or Waiting. Its choice is remembered locally across page visits and does not filter
+Board or Usage. Selecting one project hides
+project prefixes on calendar bars. The grid has no persistent helper captions. Scheduled and Pinned share
+the same toggle styling for their on, off, and hover states.
+
+Each chat's recorded turn intervals become calendar dates in the viewer's
+timezone. Adjacent dates merge into one bar. One full idle date breaks the bar,
+including weekends; a later segment has a resumed marker and opens the same
+chat Details. Continuous work across a week boundary uses continuation arrows.
+An exact midnight end does not occupy the following date. A current running
+turn extends to now; completed turns do not extend through idle review waits.
+Project colors stay consistent when navigating or filtering. Crowded weeks show
+three bar rows and a control to expand the remaining chats. Narrow views scroll
+horizontally to retain seven readable day columns.
+
+The calendar reads all turn timing rows for each eligible chat's selected
+SQLite history, cached until the databases change. The calendar rereads on
+changed snapshots or database reads, explicit Refresh, and local date rollover;
+an unchanged five-second poll does not reread calendar history. It does not scan usage,
+modify Codex records, or create editable start/end dates. Earlier histories
+replaced by a rewind may be absent. Missing start timestamps are omitted;
+missing durations show only a known start date. Missing timing data does not
+add a notice to the calendar.
+
+![Month calendar with paused and resumed sample chats](images/calendar-month.png)

package/package.json

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

package/src/calendar-history.js

@@ -0,0 +1,30 @@
+// Date-only arithmetic uses UTC; recorded instants are first converted to the
+// viewer's timezone. This keeps full idle days consistent across DST changes.
+const nextDay = date => new Date(Date.parse(`${date}T00:00:00Z`) + 86400000).toISOString().slice(0, 10);
+export function calendarSegments(turns, { month, timeZone, now = Date.now(), latestTurnId }) {
+  const format = new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' });
+  const day = time => {
+    const parts = Object.fromEntries(format.formatToParts(time).map(part => [part.type, part.value]));
+    return `${parts.year}-${parts.month}-${parts.day}`;
+  };
+  let incomplete = false;
+  const intervals = [];
+  for (const turn of turns) {
+    const start = turn.started_at * 1000;
+    if (!Number.isFinite(start) || turn.started_at == null || start <= 0 || start > now) { incomplete = true; continue; }
+    const running = turn.status === 'inProgress' && turn.turn_id === latestTurnId;
+    const hasDuration = Number.isFinite(turn.duration_ms) && turn.duration_ms >= 0;
+    if (!running && !hasDuration) incomplete = true;
+    const end = running ? now : Math.min(now, start + (hasDuration ? turn.duration_ms : 0));
+    // A turn ending exactly at midnight did not work on the following day.
+    intervals.push({ start: day(start), end: day(Math.max(start, end - 1)) });
+  }
+  intervals.sort((a, b) => a.start.localeCompare(b.start) || a.end.localeCompare(b.end));
+  const segments = [];
+  for (const interval of intervals) {
+    const previous = segments.at(-1);
+    if (previous && interval.start <= nextDay(previous.end)) previous.end = previous.end > interval.end ? previous.end : interval.end;
+    else segments.push({ ...interval, resumed: segments.length > 0 });
+  }
+  return { incomplete, segments: segments.filter(segment => segment.start.slice(0, 7) <= month && segment.end.slice(0, 7) >= month) };
+}

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,5 @@
+import { calendarSegments } from "./calendar-history.js";
+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 +241,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 +288,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 +652,60 @@ 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 calendarHistory({ month, timeZone, settings }) {
+    const snapshot = await this.refresh();
+    if (!snapshot.healthy) throw new Error(snapshot.scan.error);
+    const records = this.databaseCache.records;
+    const cache = records.calendarTurns ??= new Map();
+    const rows = new Map(records.rows.map(row => [row.id, row]));
+    const query = this.connections.history.prepare(`SELECT turn_id, started_at, duration_ms, status
+      FROM thread_turns WHERE thread_id = ? ORDER BY rollout_ordinal`);
+    const chats = [];
+    for (const task of snapshot.tasks) {
+      if ((!settings.showArchived && task.observed?.archive) ||
+          (!settings.showCli && task.observed?.source === "cli") ||
+          (!settings.showExec && task.observed?.source === "exec")) continue;
+      const row = rows.get(task.id);
+      let turns = cache.get(task.id);
+      if (!turns) { turns = query.all(historyId(row)); cache.set(task.id, turns); }
+      const result = calendarSegments(turns, { month, timeZone, now: this.now(), latestTurnId: task.turnId });
+      if (result.segments.length || result.incomplete) chats.push({ id: task.id, ...result });
+    }
+    return { month, timeZone, chats };
+  }
+  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 +768,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(); }