taskchef 9.3.0 → 9.4.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "9.3.0",
+  "version": "9.4.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
@@ -365,3 +364,47 @@ 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.3.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(); }