taskchef 7.19.1 → 7.20.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.19.1",
+  "version": "7.20.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -25,6 +25,12 @@ request -> recorded TaskChef task -> Codex executor -> request/result turn timel
 TaskChef requires Node.js 18 or newer, Git, Codex desktop, and local access to
 the projects that will receive work.
 
+Install [`ccusage`](https://github.com/ccusage/ccusage) separately when you want
+the optional dashboard token and API-equivalent cost estimates. TaskChef calls
+its structured offline Codex report and does not parse Codex rollout files
+itself. Lifecycle reporting and the dashboard continue to work when `ccusage`
+is absent or incompatible.
+
 ```sh
 codex plugin marketplace add favoyang/codex-plugins
 codex plugin add taskchef@favoyang-plugins
@@ -50,6 +56,7 @@ The canonical workspace is `~/.agents/taskchef`. TaskChef owns only:
 AGENTS.md       managed dispatcher instructions plus user additions
 taskchef.json   schema-2 Codex project index, dashboard preference, and delegation metadata
 tasks.jsonl     one task snapshot per line (schema 9; schema 4-8 migration supported)
+.taskchef-usage.json   optional mode-0600 ccusage snapshot and turn-boundary cache
 ```
 
 Index or inspect Codex projects conversationally:
@@ -269,6 +276,16 @@ Codex CLI at the canonical ChatGPT or Codex desktop app location under
 `/Applications`, to archive the exact thread UUID. The Codex chat leaves active chat lists while the TaskChef record
 and its activity timeline remain unchanged. If the bundled CLI is unavailable,
 the dashboard does not fall back to another `codex` executable from `PATH`.
+
+Task details also show whole-task and per-turn token usage when `ccusage` can
+map the linked Codex thread. A completed turn briefly shows “Tokens:
+calculating…” while TaskChef performs bounded deferred reconciliation, because
+the terminal lifecycle callback precedes Codex's final output write. Historical
+tasks may show a trustworthy task total while older turns remain “Tokens
+unavailable” when no cumulative turn boundaries were recorded. Input, cached
+input, output, reasoning, and total counts retain ccusage's categories. Dollar
+figures are labeled API-equivalent estimates; zero-priced unknown models show
+cost unavailable rather than a misleading `$0.00`.
 The header shows the running TaskChef package version reported by the same
 bounded health identity used for compatible-listener checks.
 The canonical port is owned by a dashboard initialized in the TaskChef MCP host
@@ -304,6 +321,8 @@ or secrets.
 
 ![Task detail activity timeline](docs/images/result-history-dashboard.jpg)
 
+![Deferred ccusage token consumption in task details](docs/images/ccusage-token-consumption.png)
+
 ![Interrupted turn followed by active recovery](docs/images/interrupted-turn-recovery.jpg)
 
 ## Common recovery

package/docs/spec.md

@@ -28,7 +28,7 @@ is dated research, not contract.
 | **Last semantic result** | The final result-history entry, exposed through the derived `lastResult` compatibility alias. |
 | **Turn reference** | Required lifecycle identity for one executor prompt. It is the native Codex turn ID when available, otherwise a retained client-generated UUID. |
 | **Current turn ID** | Optional Codex metadata for the reported prompt; null when native turn reading is unavailable. |
-| **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots and bounded native actions. |
+| **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots, optional local usage projections, and bounded native actions. |
 | **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-dashboard`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-copilot`. |
 
 ## Components and ownership
@@ -56,7 +56,8 @@ is dated research, not contract.
 
 ## Workspace contract
 
-TaskChef MUST manage only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl`
+TaskChef MUST manage only `AGENTS.md`, `taskchef.json`, `tasks.jsonl`, and the
+optional `.taskchef-usage.json` cache
 inside the dispatcher workspace. It MUST preserve unrelated paths.
 
 `taskchef.json` MUST have schema version 2, the following required fields, and
@@ -116,6 +117,48 @@ from the final derived semantic result. Interrupted outcomes MUST be excluded.
 These projections MUST NOT be persisted in schema 9 and remain compatibility
 aliases for existing callers.
 
+## Optional usage projection
+
+TaskChef MAY invoke an installed `ccusage` executable as an optional local
+adapter using `ccusage codex session --json --offline`. TaskChef MUST NOT parse,
+store, or serve raw Codex rollout files, prompts, responses, transcripts, or
+reasoning. Analyzer absence, timeout, malformed output, unknown pricing, or an
+unresolved thread MUST NOT block lifecycle tools or dashboard loading.
+
+The mode-0600 `.taskchef-usage.json` cache stores only normalized cumulative
+token boundaries, per-turn deltas, model names, estimated cost, source version,
+and freshness. It is independent of schema-9 task records so legacy logs remain
+readable. Writes MUST use the workspace lock and atomic replacement. Symlinked
+or unsupported cache files MUST be rejected. Writes MUST compact the derived
+cache to recent task projections, recent per-turn results, and the latest
+cumulative boundary. An oversized legacy cache MUST be treated as rebuildable
+derived data so it cannot permanently disable usage reporting.
+
+A linked Codex thread MAY map to multiple ccusage session segments. TaskChef
+MUST aggregate only records whose primary durable thread UUID is that exact
+identity; a UUID appearing only as a nested suffix MUST NOT be attributed to
+the parent or child TaskChef task. It MUST retain input, cached-input, output,
+reasoning-output, and total fields without adding cached or reasoning subsets
+into totals a second time.
+
+After a terminal report, TaskChef MUST mark the turn `calculating` and perform
+bounded deferred reconciliation without delaying the lifecycle response.
+Per-turn usage MUST be a non-negative delta between adjacent reliable cumulative
+boundaries. A first recorded turn MAY use zero as its baseline. Historical
+turns without boundaries and decreasing or ambiguous snapshots MUST be labeled
+`unavailable`, never zero or estimated. A historical task MAY still show its
+resolvable cumulative total. A boundary is reliable only after two consecutive
+samples agree. Exhausted unstable sampling and a newer turn beginning before
+stabilization MUST leave that turn unavailable and MUST NOT establish a delta
+baseline. Zero is valid for the first turn only when TaskChef observed that turn
+in progress before its terminal report; a first historical terminal turn MUST
+remain unavailable even when its cumulative task total is resolvable.
+
+Every available projection MUST identify ccusage, its version when available,
+and freshness. Dollar values MUST be labeled API-equivalent estimates. Positive
+token usage with a zero or missing analyzer cost MUST display cost unavailable,
+not `$0.00`.
+
 Task IDs and non-null thread identities MUST be unique. The immutable intent
 fields MUST NOT change after recording.
 

package/docs/workflows.md

@@ -21,6 +21,8 @@ research.
 | `src/cli.js` | Administration, normalized cached briefs, inspection, diagnostics, and dashboard startup. |
 | `src/dashboard.js` | Versioned health identity, validated compact snapshots, SSE fan-out, on-demand details, and bounded open actions. |
 | `src/dashboard-manager.js` | Concurrent singleton ensure, exact listener reuse, conflicts, and owned shutdown. |
+| `src/usage.js` | Optional bounded ccusage execution, exact primary-thread mapping, normalized aggregation, and the private usage cache. |
+| `src/usage-tracker.js` | Deferred sampling, cumulative boundaries, historical availability, and per-turn deltas. |
 
 The MCP process resolves `TASKCHEF_WORKSPACE` once and never accepts a model
 supplied path. The CLI resolves `--workspace`, then the environment, then the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.19.1",
+  "version": "7.20.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -27,6 +27,7 @@
     "docs/workflows.md",
     "docs/firstmate-taskchef-comparison.md",
     "docs/images/dashboard-identity.jpg",
+    "docs/images/ccusage-token-consumption.png",
     "docs/images/notification-event-snapshots.jpg",
     "docs/images/result-history-dashboard.jpg",
     "docs/images/interrupted-turn-recovery.jpg",

package/src/dashboard/app.js

@@ -25,6 +25,9 @@ import {
 } from "./github-links.js";
 import { formatRelativeTime, RelativeTimeController, parsedTimestamp } from "./time.js";
 
+const USAGE_POLL_INTERVAL_MS = 1_500;
+const MAX_USAGE_POLL_ATTEMPTS = 40;
+
 const state = {
   archivedThreadIds: new Set(),
   tasks: [],
@@ -57,6 +60,7 @@ const elements = {
   dialogRelatedLinks: document.querySelector("#dialog-related-links"),
   dialogResults: document.querySelector("#dialog-results"),
   dialogTitle: document.querySelector("#dialog-title"),
+  dialogUsage: document.querySelector("#dialog-usage"),
   dismissDashboardMessage: document.querySelector("#dismiss-dashboard-message"),
   emptyState: document.querySelector("#empty-state"),
   notifications: document.querySelector("#notifications"),
@@ -347,6 +351,58 @@ function detailRow(term, value) {
   return [dt, dd];
 }
 
+const tokenFormatter = new Intl.NumberFormat();
+
+function formatEstimatedCost(value) {
+  if (typeof value !== "number") return "cost unavailable";
+  if (value === 0) return "estimated $0.00";
+  return `estimated $${value < 0.01 ? value.toFixed(4) : value.toFixed(2)}`;
+}
+
+function usageBreakdownText(usage) {
+  return [
+    `${tokenFormatter.format(usage.inputTokens)} input`,
+    `${tokenFormatter.format(usage.cachedInputTokens)} cached input`,
+    `${tokenFormatter.format(usage.outputTokens)} output`,
+    `${tokenFormatter.format(usage.reasoningOutputTokens)} reasoning`,
+  ].join(" · ");
+}
+
+function usagePresentation(usage, { wholeTask = false } = {}) {
+  const container = document.createElement("div");
+  container.className = `usage-summary usage-${usage?.status ?? "calculating"}`;
+  if (!usage || usage.status === "calculating") {
+    const indicator = document.createElement("span");
+    indicator.className = "usage-spinner";
+    indicator.setAttribute("aria-hidden", "true");
+    const text = document.createElement("span");
+    text.textContent = "Tokens: calculating…";
+    container.replaceChildren(indicator, text);
+    return container;
+  }
+  if (usage.status !== "available") {
+    container.textContent = `Tokens unavailable${usage.reason ? ` — ${usage.reason}` : "."}`;
+    return container;
+  }
+  const headline = document.createElement("strong");
+  headline.textContent = `${tokenFormatter.format(usage.totalTokens)} tokens · ${formatEstimatedCost(usage.estimatedCostUsd)}`;
+  const breakdown = document.createElement("span");
+  breakdown.textContent = usageBreakdownText(usage);
+  container.append(headline, breakdown);
+  const provenance = document.createElement("span");
+  const version = usage.provenance?.version ? ` ${usage.provenance.version}` : "";
+  const freshness = usage.sourceUpdatedAt ?? usage.sampledAt;
+  provenance.textContent = `Source: ccusage${version}${freshness ? ` · updated ${formatRelativeTime(freshness)}` : ""}. Dollar cost is an API-equivalent estimate${wholeTask ? " for the task" : " for this turn"}.`;
+  container.append(provenance);
+  return container;
+}
+
+function usageStillCalculating(task) {
+  return task.usage?.status === "calculating"
+    || (task.status !== "working" && Object.values(task.usage?.turns ?? {})
+      .some((turn) => turn.status === "calculating"));
+}
+
 function turnTimeline(task) {
   if (task.turns.length === 0) {
     const empty = document.createElement("p");
@@ -387,7 +443,20 @@ function turnTimeline(task) {
     const turnMetadata = document.createElement("p");
     turnMetadata.className = "result-history-turn";
     turnMetadata.textContent = `Turn ref ${turn.turnRef ?? "not recorded"}; Codex turn ${turn.turnId ?? "unavailable"}`;
-    item.append(header, requestLabel, request, resultLabel, result, turnMetadata);
+    const turnUsage = task.usage?.turns?.[turn.turnRef ?? turn.turnId] ?? (
+      turn.result === null
+        ? { status: "calculating" }
+        : { status: "unavailable", reason: "No reliable turn boundary is available." }
+    );
+    item.append(
+      header,
+      requestLabel,
+      request,
+      resultLabel,
+      result,
+      usagePresentation(turnUsage),
+      turnMetadata,
+    );
     return item;
   });
 }
@@ -418,6 +487,12 @@ function renderDialog(task) {
     (task.relatedGitHubLinks?.length ?? 0) === 0 && !task.relatedGitHubLinksTruncated
   );
   elements.dialogResults.replaceChildren(...turnTimeline(detailedTask));
+  elements.dialogUsage.replaceChildren(usagePresentation(
+    task.usage?.status === "available" && task.usage.task
+      ? { status: "available", ...task.usage.task }
+      : task.usage ?? { status: task.threadId ? "calculating" : "unavailable" },
+    { wholeTask: true },
+  ));
   elements.dialogInstruction.textContent = task.instruction;
   elements.copyTaskId.disabled = !task.id;
   setCopyTaskIdLabel("Copy Task ID");
@@ -464,22 +539,28 @@ async function openDialog(task) {
   const requestGeneration = ++detailRequestGeneration;
   renderDialog(task);
   if (!elements.dialog.open) elements.dialog.showModal();
-  try {
-    const response = await fetch(`/api/tasks/${encodeURIComponent(task.id)}`);
-    if (!response.ok) throw new Error("Task details are unavailable.");
-    const detail = await response.json();
-    if (
-      requestGeneration === detailRequestGeneration
-      && state.selectedTask?.id === task.id
-      && elements.dialog.open
-    ) {
-      renderDialog(detail.task);
-    }
-  } catch {
-    if (state.selectedTask?.id === task.id) {
-      showMessage("Task activity timeline is temporarily unavailable.");
+  const load = async (attempt = 0) => {
+    try {
+      const response = await fetch(`/api/tasks/${encodeURIComponent(task.id)}`);
+      if (!response.ok) throw new Error("Task details are unavailable.");
+      const detail = await response.json();
+      if (
+        requestGeneration === detailRequestGeneration
+        && state.selectedTask?.id === task.id
+        && elements.dialog.open
+      ) {
+        renderDialog(detail.task);
+        if (usageStillCalculating(detail.task) && attempt < MAX_USAGE_POLL_ATTEMPTS) {
+          setTimeout(() => load(attempt + 1), USAGE_POLL_INTERVAL_MS);
+        }
+      }
+    } catch {
+      if (state.selectedTask?.id === task.id) {
+        showMessage("Task activity timeline is temporarily unavailable.");
+      }
     }
-  }
+  };
+  await load();
 }
 
 function taskCard(task) {

package/src/dashboard/index.html

@@ -116,6 +116,10 @@
         <button id="archive-codex" class="danger-button" type="button" aria-label="Archive this chat in Codex" hidden>Archive chat</button>
       </div>
       <nav id="dialog-related-links" class="github-links" aria-label="Related GitHub links" hidden></nav>
+      <section>
+        <h3>Usage</h3>
+        <div id="dialog-usage" class="usage-panel" aria-live="polite"></div>
+      </section>
       <section>
         <h3>Activity timeline</h3>
         <div id="dialog-results" class="result-history"></div>

package/src/dashboard/styles.css

@@ -165,6 +165,13 @@ dialog section + section { margin-top: 24px; }
 .result-history-item h4 { margin: 10px 0 3px; color: var(--muted); font-size: 0.72rem; letter-spacing: 0.04em; text-transform: uppercase; }
 .result-history-turn, .result-history-empty { color: var(--muted); font-size: 0.78rem; overflow-wrap: anywhere; }
 .result-history-empty { margin: 0; }
+.usage-panel { margin-top: 8px; }
+.usage-summary { display: grid; gap: 3px; margin: 10px 0 4px; color: var(--muted); font-size: 0.8rem; }
+.usage-summary strong { color: var(--text); font-size: 0.9rem; }
+.usage-calculating { display: flex; align-items: center; gap: 7px; }
+.usage-spinner { width: 12px; height: 12px; border: 2px solid var(--border); border-top-color: var(--accent); border-radius: 50%; animation: usage-spin 0.8s linear infinite; }
+@keyframes usage-spin { to { transform: rotate(360deg); } }
+@media (prefers-reduced-motion: reduce) { .usage-spinner { animation: none; border-top-color: var(--border); background: var(--accent); } }
 pre { max-height: 280px; margin: 0; padding: 14px; overflow: auto; border-radius: 7px; background: var(--surface-muted); white-space: pre-wrap; overflow-wrap: anywhere; font: 0.86rem/1.55 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
 .metadata { display: grid; grid-template-columns: minmax(100px, 150px) 1fr; margin: 0; font-size: 0.88rem; }
 .metadata dt, .metadata dd { padding: 7px 0; border-bottom: 1px solid var(--border); overflow-wrap: anywhere; }

package/src/dashboard.js

@@ -22,6 +22,7 @@ import {
 } from "./workspace.js";
 import { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./version.js";
 import { taskGitHubProjection } from "./dashboard/github-links.js";
+import { createUsageTracker } from "./usage-tracker.js";
 
 const TASKS_FILE_NAME = "tasks.jsonl";
 const STATIC_ROOT = fileURLToPath(new URL("./dashboard/", import.meta.url));
@@ -455,6 +456,7 @@ export async function createDashboardServer({
   launcher = "standalone",
   taskchefVersion = TASKCHEF_VERSION,
   serverVersion = DASHBOARD_SERVER_VERSION,
+  usageTracker = null,
 } = {}) {
   if (!LOOPBACK_HOSTS.has(host)) {
     throw new Error("dashboard host must be a loopback address");
@@ -470,6 +472,7 @@ export async function createDashboardServer({
   }
   const monitor = new DashboardMonitor(workspace, monitorOptions);
   await monitor.start();
+  const taskUsageTracker = usageTracker ?? createUsageTracker({ workspace: monitor.workspace });
   const identity = Object.freeze({
     schemaVersion: 1,
     service: "taskchef-dashboard",
@@ -574,7 +577,16 @@ export async function createDashboardServer({
         response.writeHead(200, securityHeaders("application/json; charset=utf-8"));
         response.end();
       } else {
-        sendJson(response, 200, { schemaVersion: 1, task: taskDetailProjection(task) });
+        const usage = await taskUsageTracker.get(task).catch(() => ({
+          status: "unavailable",
+          reason: "Task usage is temporarily unavailable.",
+          task: null,
+          turns: {},
+        }));
+        sendJson(response, 200, {
+          schemaVersion: 1,
+          task: { ...taskDetailProjection(task), usage },
+        });
       }
       return;
     }

package/src/mcp.js

@@ -13,6 +13,7 @@ import { parseTaskChefMarker } from "./delegation.js";
 import { createDashboardManager } from "./dashboard-manager.js";
 import { resolveWorkspacePath } from "./workspace-path.js";
 import { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./version.js";
+import { createUsageTracker } from "./usage-tracker.js";
 
 const projectSchema = z.object({
   name: z.string(),
@@ -145,6 +146,7 @@ export function createTaskChefMcpServer({
   dashboardManager = createDashboardManager({ workspace }),
   readConfiguration = readConfig,
   logDashboardDiagnostic,
+  usageTracker = createUsageTracker({ workspace }),
 } = {}) {
   const server = new McpServer(
     { name: "taskchef", version: TASKCHEF_VERSION },
@@ -287,6 +289,7 @@ export function createTaskChefMcpServer({
     },
     async (input) => {
       const task = await reportState(workspace, input);
+      void usageTracker.observe(task).catch(() => {});
       return toolResult("task", task, `Recorded ${task.status} state for TaskChef task ${task.id}.`);
     },
   );
@@ -314,6 +317,7 @@ export function createTaskChefMcpServer({
     },
     async (input) => {
       const task = await reportResult(workspace, input);
+      void usageTracker.observe(task).catch(() => {});
       return toolResult("task", task, `Recorded ${task.status} result for TaskChef task ${task.id}.`);
     },
   );

package/src/usage-tracker.js

@@ -0,0 +1,425 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { acquireWorkspaceLock } from "./workspace.js";
+import {
+  readCcusageThreadUsage,
+  readUsageStore,
+  usageDelta,
+  writeUsageStore,
+} from "./usage.js";
+
+const TERMINAL_STATUSES = new Set(["needs_input", "completed", "failed"]);
+const MAX_TRACKED_TURNS = 250;
+
+function hasTerminalLatestTurn(task) {
+  return task.latestTurn !== null
+    && task.latestTurn !== undefined
+    && task.latestTurn.result !== null
+    && TERMINAL_STATUSES.has(task.latestTurn.result.status);
+}
+
+function lifecycleGeneration(task) {
+  return {
+    turnCount: task.turns.length,
+    terminal: hasTerminalLatestTurn(task),
+  };
+}
+
+function generationIsOlder(task, existing) {
+  if (!existing) return false;
+  const incoming = lifecycleGeneration(task);
+  if (incoming.turnCount !== existing.generationTurnCount) {
+    return incoming.turnCount < existing.generationTurnCount;
+  }
+  return !incoming.terminal && existing.generationTerminal;
+}
+
+function publicReason(error) {
+  const message = String(error?.message ?? "");
+  if (/not installed/i.test(message)) return "ccusage is not installed.";
+  if (/could not resolve/i.test(message)) return "No matching Codex usage session was found.";
+  if (/timed out/i.test(message)) return "ccusage did not finish in time.";
+  return "Codex usage is unavailable from ccusage.";
+}
+
+function calculatingTask(task, existing = null, now = new Date().toISOString()) {
+  const latestTurnRef = task.latestTurn?.turnRef ?? null;
+  const preserveAvailable = existing?.generationTurnRef === latestTurnRef
+    && existing?.status === "available"
+    && existing?.turns?.[latestTurnRef]?.status === "available";
+  const recentTurns = task.turns.slice(-MAX_TRACKED_TURNS);
+  const turns = Object.fromEntries(recentTurns.flatMap((turn) => (
+    existing?.turns?.[turn.turnRef]
+      ? [[turn.turnRef, existing.turns[turn.turnRef]]]
+      : []
+  )));
+  const generation = lifecycleGeneration(task);
+  for (const turn of recentTurns) {
+    if (turn.result === null) {
+      turns[turn.turnRef] = { status: "calculating", updatedAt: now };
+    } else if (turn.result.status === "interrupted") {
+      turns[turn.turnRef] = {
+        status: "unavailable",
+        reason: "The turn ended without a terminal usage boundary.",
+        updatedAt: now,
+      };
+    } else if (turns[turn.turnRef]?.status === "calculating"
+      && turn.turnRef !== task.latestTurn?.turnRef) {
+      turns[turn.turnRef] = {
+        status: "unavailable",
+        reason: "A newer turn started before a stable usage boundary was recorded.",
+        updatedAt: now,
+      };
+    } else if (!turns[turn.turnRef]) {
+      turns[turn.turnRef] = {
+        status: "unavailable",
+        reason: "No reliable cumulative boundary was recorded for this historical turn.",
+        updatedAt: now,
+      };
+    }
+  }
+  if (task.latestTurn?.result
+    && TERMINAL_STATUSES.has(task.latestTurn.result.status)
+    && !preserveAvailable) {
+    turns[task.latestTurn.turnRef] = { status: "calculating", updatedAt: now };
+  }
+  return {
+    threadId: task.threadId,
+    generationTurnRef: latestTurnRef,
+    generationTurnCount: generation.turnCount,
+    generationTerminal: generation.terminal,
+    zeroBaselineTurnRef: existing?.zeroBaselineTurnRef ?? (
+      task.turns.length === 1 && task.latestTurn?.result === null
+        ? task.latestTurn.turnRef
+        : null
+    ),
+    status: preserveAvailable ? "available" : "calculating",
+    updatedAt: preserveAvailable ? existing.updatedAt : now,
+    retryAfter: null,
+    task: existing?.task ?? null,
+    turns,
+    boundaries: existing?.boundaries ?? {},
+  };
+}
+
+async function updateStore(workspace, taskId, transform) {
+  const release = await acquireWorkspaceLock(workspace);
+  try {
+    const store = await readUsageStore(workspace);
+    const next = await transform(store.tasks[taskId] ?? null);
+    store.tasks[taskId] = next;
+    await writeUsageStore(workspace, store);
+    return next;
+  } finally {
+    await release();
+  }
+}
+
+function snapshotFingerprint(snapshot) {
+  return JSON.stringify([
+    snapshot.inputTokens,
+    snapshot.cachedInputTokens,
+    snapshot.outputTokens,
+    snapshot.reasoningOutputTokens,
+    snapshot.totalTokens,
+    snapshot.estimatedCostUsd,
+    snapshot.sourceUpdatedAt,
+  ]);
+}
+
+function snapshotSupersedes(current, incoming) {
+  if (!current) return true;
+  const currentSampledAt = Date.parse(current.sampledAt ?? 0);
+  const incomingSampledAt = Date.parse(incoming.sampledAt ?? 0);
+  if (!Number.isFinite(incomingSampledAt) || incomingSampledAt < currentSampledAt) return false;
+  return [
+    "inputTokens",
+    "cachedInputTokens",
+    "outputTokens",
+    "reasoningOutputTokens",
+    "totalTokens",
+  ].every((field) => incoming[field] >= current[field]);
+}
+
+function candidateHasAdvanced(task, existing, snapshot) {
+  const latestIndex = task.turns.findIndex((turn) => turn.turnRef === task.latestTurn?.turnRef);
+  if (latestIndex <= 0) return true;
+  const previousTurn = task.turns[latestIndex - 1];
+  const previousBoundary = existing?.boundaries?.[previousTurn.turnRef];
+  if (!previousBoundary) return true;
+  const delta = usageDelta(snapshot, previousBoundary);
+  return delta !== null && delta.totalTokens > 0;
+}
+
+function reconcileRecord(task, existing, snapshot, { boundaryReliable = true } = {}) {
+  const now = snapshot.sampledAt;
+  const boundaries = { ...(existing?.boundaries ?? {}) };
+  const recentTurns = task.turns.slice(-MAX_TRACKED_TURNS);
+  const turns = Object.fromEntries(recentTurns.flatMap((turn) => (
+    existing?.turns?.[turn.turnRef]
+      ? [[turn.turnRef, existing.turns[turn.turnRef]]]
+      : []
+  )));
+  const terminalTurns = recentTurns.filter((turn) => (
+    turn.result !== null && TERMINAL_STATUSES.has(turn.result.status)
+  ));
+  const generation = lifecycleGeneration(task);
+  for (const turn of terminalTurns) {
+    if (!turns[turn.turnRef]) {
+      turns[turn.turnRef] = {
+        status: "unavailable",
+        reason: "No reliable cumulative boundary was recorded for this historical turn.",
+        updatedAt: now,
+      };
+    }
+  }
+
+  const latest = terminalTurns.at(-1);
+  if (latest && latest.turnRef === task.latestTurn?.turnRef && boundaryReliable) {
+    const index = task.turns.findIndex((turn) => turn.turnRef === latest.turnRef);
+    const previousTurn = index > 0 ? task.turns[index - 1] : null;
+    const previousBoundary = previousTurn ? boundaries[previousTurn.turnRef] ?? null : null;
+    const delta = previousTurn === null
+      ? (existing?.zeroBaselineTurnRef === latest.turnRef ? usageDelta(snapshot, null) : null)
+      : (previousBoundary !== null ? usageDelta(snapshot, previousBoundary) : null);
+    const advanced = previousTurn === null || previousBoundary === null || delta?.totalTokens > 0;
+    if (advanced) boundaries[latest.turnRef] = snapshot;
+    turns[latest.turnRef] = delta === null || !advanced
+      ? {
+        status: "unavailable",
+        reason: !advanced
+          ? "Cumulative usage did not advance beyond the preceding turn."
+          : (previousTurn === null
+            ? "No live zero-token boundary was recorded for this historical turn."
+            : "The preceding turn has no reliable cumulative boundary."),
+        updatedAt: now,
+      }
+      : {
+        status: "available",
+        ...delta,
+        provenance: snapshot.provenance,
+        sampledAt: snapshot.sampledAt,
+        sourceUpdatedAt: snapshot.sourceUpdatedAt,
+        updatedAt: now,
+      };
+  } else if (latest && latest.turnRef === task.latestTurn?.turnRef) {
+    turns[latest.turnRef] = {
+      status: "unavailable",
+      reason: "Usage did not stabilize before reconciliation finished.",
+      updatedAt: now,
+    };
+  }
+
+  return {
+    threadId: task.threadId,
+    generationTurnRef: task.latestTurn?.turnRef ?? null,
+    generationTurnCount: generation.turnCount,
+    generationTerminal: generation.terminal,
+    zeroBaselineTurnRef: existing?.zeroBaselineTurnRef ?? null,
+    status: "available",
+    updatedAt: now,
+    retryAfter: null,
+    task: snapshot,
+    turns,
+    boundaries,
+  };
+}
+
+export function createUsageTracker({
+  workspace,
+  readThreadUsage = readCcusageThreadUsage,
+  retryDelaysMs = [2_000, 3_000, 4_000, 1_000],
+  retryCooldownMs = 60_000,
+  setTimer = setTimeout,
+} = {}) {
+  const jobs = new Map();
+  const observationChains = new Map();
+  let canonicalWorkspace = null;
+
+  const root = async () => {
+    canonicalWorkspace ??= await realpath(path.resolve(workspace));
+    return canonicalWorkspace;
+  };
+
+  const markCalculating = async (task) => updateStore(await root(), task.id, (existing) => (
+    generationIsOlder(task, existing) ? existing : calculatingTask(task, existing)
+  ));
+
+  const reconcile = async (task, {
+    finalAttempt = false,
+    isCurrent = () => true,
+    job,
+  } = {}) => {
+    let snapshot;
+    try {
+      snapshot = await readThreadUsage(task.threadId);
+    } catch (error) {
+      if (!finalAttempt) throw error;
+      if (!isCurrent()) return null;
+      return updateStore(await root(), task.id, (existing) => {
+        if (existing?.generationTurnRef !== task.latestTurn?.turnRef) return existing;
+        if (existing?.status === "available"
+          && existing?.turns?.[task.latestTurn?.turnRef]?.status === "available") return existing;
+        const calculating = calculatingTask(task, existing);
+        return {
+          ...calculating,
+          status: "unavailable",
+          reason: publicReason(error),
+          updatedAt: new Date().toISOString(),
+          retryAfter: new Date(Date.now() + retryCooldownMs).toISOString(),
+          turns: Object.fromEntries(Object.entries(calculating.turns).map(
+            ([turnRef, usage]) => [turnRef, usage.status === "calculating"
+              ? { status: "unavailable", reason: publicReason(error), updatedAt: new Date().toISOString() }
+              : usage],
+          )),
+        };
+      });
+    }
+    if (!isCurrent()) return null;
+    const fingerprint = snapshotFingerprint(snapshot);
+    const stable = job.previousFingerprint === fingerprint;
+    job.previousFingerprint = fingerprint;
+    if (!stable && !finalAttempt) return null;
+    if (stable && !finalAttempt) {
+      const store = await readUsageStore(await root());
+      if (!candidateHasAdvanced(task, store.tasks[task.id], snapshot)) return null;
+    }
+    return updateStore(await root(), task.id, (existing) => {
+      const latestTurnRef = task.latestTurn?.turnRef;
+      if (existing?.generationTurnRef !== latestTurnRef) return existing;
+      const supersedes = snapshotSupersedes(existing?.task, snapshot);
+      if (existing?.boundaries?.[latestTurnRef]
+        || existing?.turns?.[latestTurnRef]?.status === "available") {
+        return supersedes
+          ? { ...existing, status: "available", updatedAt: snapshot.sampledAt, task: snapshot }
+          : existing;
+      }
+      if (!supersedes) return existing;
+      return reconcileRecord(task, existing, snapshot, { boundaryReliable: stable });
+    });
+  };
+
+  const schedule = (task, { immediate = false } = {}) => {
+    if (!task.threadId || jobs.has(task.id)) return;
+    const job = {
+      cancelled: false,
+      previousFingerprint: null,
+      turnRef: task.latestTurn?.turnRef ?? null,
+    };
+    let attempt = 0;
+    const run = async () => {
+      if (job.cancelled || jobs.get(task.id) !== job) return;
+      let complete = false;
+      try {
+        const result = await reconcile(task, {
+          finalAttempt: attempt >= retryDelaysMs.length,
+          isCurrent: () => !job.cancelled && jobs.get(task.id) === job,
+          job,
+        });
+        complete = result !== null;
+      } catch {
+        // Retry bounded transient analyzer failures.
+      }
+      if (job.cancelled || jobs.get(task.id) !== job) return;
+      if (complete || attempt >= retryDelaysMs.length) {
+        if (jobs.get(task.id) === job) jobs.delete(task.id);
+        return;
+      }
+      const delay = retryDelaysMs[attempt] ?? 0;
+      attempt += 1;
+      const timer = setTimer(run, delay);
+      timer?.unref?.();
+    };
+    jobs.set(task.id, job);
+    const timer = setTimer(run, immediate ? 0 : retryDelaysMs[attempt++]);
+    timer?.unref?.();
+  };
+
+  return {
+    observe(task) {
+      const previous = observationChains.get(task.id) ?? Promise.resolve();
+      const observation = previous.catch(() => {}).then(async () => {
+        if (!task.threadId) return null;
+        const active = jobs.get(task.id);
+        const latestTurnRef = task.latestTurn?.turnRef ?? null;
+        if (active && active.turnRef !== latestTurnRef) {
+          active.cancelled = true;
+          jobs.delete(task.id);
+        }
+        const usage = await markCalculating(task);
+        if (hasTerminalLatestTurn(task)) schedule(task);
+        return usage;
+      });
+      observationChains.set(task.id, observation);
+      void observation.finally(() => {
+        if (observationChains.get(task.id) === observation) observationChains.delete(task.id);
+      }).catch(() => {});
+      return observation;
+    },
+    async get(task) {
+      const store = await readUsageStore(await root());
+      const usage = store.tasks[task.id] ?? null;
+      if (!task.threadId) return {
+        status: "unavailable",
+        reason: "This task has no linked Codex thread.",
+        task: null,
+        turns: {},
+      };
+      if (!task.latestTurn) return {
+        status: "unavailable",
+        reason: "No TaskChef turn has started yet.",
+        task: null,
+        turns: {},
+      };
+      const active = jobs.get(task.id);
+      const latestTurnRef = task.latestTurn?.turnRef ?? null;
+      if (active && active.turnRef !== latestTurnRef) {
+        active.cancelled = true;
+        jobs.delete(task.id);
+      }
+      if (!usage || usage.threadId !== task.threadId) {
+        const calculating = calculatingTask(task);
+        void markCalculating(task)
+          .then(() => {
+            if (hasTerminalLatestTurn(task)) schedule(task, { immediate: true });
+          })
+          .catch(() => {});
+        return calculating;
+      }
+      if (usage.generationTurnRef !== latestTurnRef) {
+        const calculating = calculatingTask(task, usage);
+        void markCalculating(task)
+          .then(() => {
+            if (hasTerminalLatestTurn(task)) schedule(task, { immediate: true });
+          })
+          .catch(() => {});
+        return calculating;
+      }
+      const latestTurnUsage = task.latestTurn
+        ? usage.turns?.[task.latestTurn.turnRef]
+        : null;
+      if (!latestTurnUsage) {
+        const calculating = calculatingTask(task, usage);
+        void markCalculating(task)
+          .then(() => {
+            if (hasTerminalLatestTurn(task)) schedule(task, { immediate: true });
+          })
+          .catch(() => {});
+        return calculating;
+      }
+      if (hasTerminalLatestTurn(task) && usage.status !== "available") {
+        if (usage.status === "unavailable"
+          && usage.retryAfter
+          && Date.parse(usage.retryAfter) > Date.now()) return usage;
+        const calculating = calculatingTask(task, usage);
+        void markCalculating(task)
+          .then(() => schedule(task, { immediate: true }))
+          .catch(() => {});
+        return calculating;
+      }
+      return usage;
+    },
+    schedule,
+  };
+}

package/src/usage.js

@@ -0,0 +1,388 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+
+const execFile = promisify(execFileCallback);
+const USAGE_FILE_NAME = ".taskchef-usage.json";
+const UUID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/gi;
+const TOKEN_FIELDS = [
+  "inputTokens",
+  "cachedInputTokens",
+  "outputTokens",
+  "reasoningOutputTokens",
+  "totalTokens",
+];
+const USAGE_STATUSES = new Set(["calculating", "available", "unavailable"]);
+const MAX_USAGE_FILE_BYTES = 16 * 1024 * 1024;
+const USAGE_WRITE_BUDGET_BYTES = 8 * 1024 * 1024;
+const MAX_PERSISTED_TASKS = 1_000;
+const MAX_PERSISTED_TURNS = 250;
+
+function nonNegativeNumber(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative number`);
+  }
+  return value;
+}
+
+function matchingSession(session, threadId) {
+  const identity = `${session.sessionId ?? ""} ${session.sessionFile ?? ""}`;
+  const [primaryThreadId] = identity.match(UUID_PATTERN) ?? [];
+  return primaryThreadId?.toLowerCase() === threadId;
+}
+
+function normalizeModelUsage(models, name) {
+  if (!models || typeof models !== "object" || Array.isArray(models)) {
+    throw new Error(`${name}.models must be an object`);
+  }
+  return Object.fromEntries(Object.entries(models).map(([model, usage]) => {
+    if (model.length === 0 || model.length > 256) throw new Error(`${name}.models has an invalid model name`);
+    return [model, {
+    inputTokens: nonNegativeNumber(usage.inputTokens, `${name}.models.${model}.inputTokens`),
+    cachedInputTokens: nonNegativeNumber(usage.cacheReadTokens, `${name}.models.${model}.cacheReadTokens`),
+    outputTokens: nonNegativeNumber(usage.outputTokens, `${name}.models.${model}.outputTokens`),
+    reasoningOutputTokens: nonNegativeNumber(
+      usage.reasoningOutputTokens,
+      `${name}.models.${model}.reasoningOutputTokens`,
+    ),
+    totalTokens: nonNegativeNumber(usage.totalTokens, `${name}.models.${model}.totalTokens`),
+    }];
+  }));
+}
+
+function addModelUsage(target, source) {
+  for (const [model, usage] of Object.entries(source)) {
+    if (!Object.hasOwn(target, model)) {
+      target[model] = Object.fromEntries(TOKEN_FIELDS.map((field) => [field, 0]));
+    }
+    for (const field of TOKEN_FIELDS) target[model][field] += usage[field];
+  }
+}
+
+function timestampOrNull(value, name) {
+  if (value === null) return null;
+  if (typeof value !== "string" || Number.isNaN(Date.parse(value))) {
+    throw new Error(`${name} must be an ISO timestamp or null`);
+  }
+  return value;
+}
+
+function normalizeProvenance(value, name, { includeSessionCount = false } = {}) {
+  if (!value || value.provider !== "ccusage") {
+    throw new Error(`${name}.provenance is invalid`);
+  }
+  return {
+    provider: "ccusage",
+    version: typeof value.version === "string" ? value.version.slice(0, 64) : null,
+    ...(includeSessionCount ? {
+      sessionCount: nonNegativeNumber(value.sessionCount, `${name}.provenance.sessionCount`),
+    } : {}),
+  };
+}
+
+function normalizeStoredSnapshot(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  const snapshot = Object.fromEntries(TOKEN_FIELDS.map((field) => [
+    field,
+    nonNegativeNumber(value[field], `${name}.${field}`),
+  ]));
+  if (value.estimatedCostUsd !== null) {
+    snapshot.estimatedCostUsd = nonNegativeNumber(value.estimatedCostUsd, `${name}.estimatedCostUsd`);
+  } else {
+    snapshot.estimatedCostUsd = null;
+  }
+  snapshot.costStatus = value.costStatus === "estimated" ? "estimated" : "unavailable";
+  const models = normalizeModelUsage(Object.fromEntries(Object.entries(value.models ?? {}).map(
+    ([model, usage]) => [model, {
+      ...usage,
+      cacheReadTokens: usage.cachedInputTokens,
+    }],
+  )), name);
+  if (Object.keys(models).length > 64 || Object.keys(models).some((model) => model.length > 256)) {
+    throw new Error(`${name}.models exceeds the usage cache limit`);
+  }
+  snapshot.models = models;
+  snapshot.provenance = normalizeProvenance(value.provenance, name, { includeSessionCount: true });
+  snapshot.sampledAt = timestampOrNull(value.sampledAt, `${name}.sampledAt`);
+  snapshot.sourceUpdatedAt = timestampOrNull(value.sourceUpdatedAt, `${name}.sourceUpdatedAt`);
+  return snapshot;
+}
+
+function normalizeStoredTurn(value, name) {
+  if (!value || typeof value !== "object" || !USAGE_STATUSES.has(value.status)) {
+    throw new Error(`${name} has an invalid status`);
+  }
+  const updatedAt = timestampOrNull(value.updatedAt, `${name}.updatedAt`);
+  if (value.status === "available") {
+    const normalized = Object.fromEntries(TOKEN_FIELDS.map((field) => [
+      field,
+      nonNegativeNumber(value[field], `${name}.${field}`),
+    ]));
+    normalized.estimatedCostUsd = value.estimatedCostUsd === null
+      ? null
+      : nonNegativeNumber(value.estimatedCostUsd, `${name}.estimatedCostUsd`);
+    return {
+      status: "available",
+      ...normalized,
+      costStatus: normalized.estimatedCostUsd === null ? "unavailable" : "estimated",
+      provenance: normalizeProvenance(value.provenance, name),
+      sampledAt: timestampOrNull(value.sampledAt, `${name}.sampledAt`),
+      sourceUpdatedAt: timestampOrNull(value.sourceUpdatedAt, `${name}.sourceUpdatedAt`),
+      updatedAt,
+    };
+  }
+  return {
+    status: value.status,
+    ...(value.status === "unavailable" ? {
+      reason: typeof value.reason === "string" ? value.reason.slice(0, 256) : "Usage is unavailable.",
+    } : {}),
+    updatedAt,
+  };
+}
+
+function normalizeStoredRecord(value, name) {
+  if (!value || typeof value !== "object" || !USAGE_STATUSES.has(value.status)) {
+    throw new Error(`${name} is invalid`);
+  }
+  const threadId = String(value.threadId ?? "").toLowerCase();
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(threadId)) {
+    throw new Error(`${name}.threadId is invalid`);
+  }
+  const generationTurnRef = value.generationTurnRef ?? null;
+  if (generationTurnRef !== null
+    && (typeof generationTurnRef !== "string" || generationTurnRef.length === 0 || generationTurnRef.length > 256)) {
+    throw new Error(`${name}.generationTurnRef is invalid`);
+  }
+  const zeroBaselineTurnRef = value.zeroBaselineTurnRef ?? null;
+  if (zeroBaselineTurnRef !== null
+    && (typeof zeroBaselineTurnRef !== "string" || zeroBaselineTurnRef.length === 0 || zeroBaselineTurnRef.length > 256)) {
+    throw new Error(`${name}.zeroBaselineTurnRef is invalid`);
+  }
+  const generationTurnCount = nonNegativeNumber(
+    value.generationTurnCount ?? 0,
+    `${name}.generationTurnCount`,
+  );
+  const generationTerminal = value.generationTerminal === true;
+  const normalizeMap = (entries, normalizer, mapName) => {
+    if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+      throw new Error(`${mapName} must be an object`);
+    }
+    const pairs = Object.entries(entries);
+    if (pairs.length > 10_000) throw new Error(`${mapName} exceeds the usage cache limit`);
+    return Object.fromEntries(pairs.map(([key, item]) => [key, normalizer(item, `${mapName}.${key}`)]));
+  };
+  return {
+    threadId,
+    generationTurnRef,
+    generationTurnCount,
+    generationTerminal,
+    zeroBaselineTurnRef,
+    status: value.status,
+    updatedAt: timestampOrNull(value.updatedAt, `${name}.updatedAt`),
+    retryAfter: timestampOrNull(value.retryAfter ?? null, `${name}.retryAfter`),
+    task: value.task === null ? null : normalizeStoredSnapshot(value.task, `${name}.task`),
+    turns: normalizeMap(value.turns, normalizeStoredTurn, `${name}.turns`),
+    boundaries: normalizeMap(value.boundaries, normalizeStoredSnapshot, `${name}.boundaries`),
+    ...(value.status === "unavailable" ? {
+      reason: typeof value.reason === "string" ? value.reason.slice(0, 256) : "Usage is unavailable.",
+    } : {}),
+  };
+}
+
+export function aggregateCcusageSessions(payload, threadId, {
+  sampledAt = new Date().toISOString(),
+  version = null,
+} = {}) {
+  if (!payload || typeof payload !== "object" || !Array.isArray(payload.sessions)) {
+    throw new Error("ccusage output must contain a sessions array");
+  }
+  const normalizedThreadId = String(threadId).toLowerCase();
+  const sessions = payload.sessions.filter((session) => matchingSession(session, normalizedThreadId));
+  if (sessions.length === 0) throw new Error("ccusage could not resolve this Codex thread");
+
+  const usage = Object.fromEntries(TOKEN_FIELDS.map((field) => [field, 0]));
+  const models = Object.create(null);
+  let estimatedCostUsd = 0;
+  let hasUnpricedUsage = false;
+  let sourceUpdatedAt = null;
+  for (const [index, session] of sessions.entries()) {
+    const name = `ccusage.sessions[${index}]`;
+    usage.inputTokens += nonNegativeNumber(session.inputTokens, `${name}.inputTokens`);
+    usage.cachedInputTokens += nonNegativeNumber(session.cacheReadTokens, `${name}.cacheReadTokens`);
+    usage.outputTokens += nonNegativeNumber(session.outputTokens, `${name}.outputTokens`);
+    usage.reasoningOutputTokens += nonNegativeNumber(
+      session.reasoningOutputTokens,
+      `${name}.reasoningOutputTokens`,
+    );
+    const sessionTotalTokens = nonNegativeNumber(session.totalTokens, `${name}.totalTokens`);
+    usage.totalTokens += sessionTotalTokens;
+    const sessionCost = session.costUSD === undefined || session.costUSD === null
+      ? null
+      : nonNegativeNumber(session.costUSD, `${name}.costUSD`);
+    if (sessionCost !== null) estimatedCostUsd += sessionCost;
+    if (sessionTotalTokens > 0 && (sessionCost === null || sessionCost === 0)) hasUnpricedUsage = true;
+    addModelUsage(models, normalizeModelUsage(session.models, name));
+    if (typeof session.lastActivity === "string" && !Number.isNaN(Date.parse(session.lastActivity))) {
+      if (sourceUpdatedAt === null || Date.parse(session.lastActivity) > Date.parse(sourceUpdatedAt)) {
+        sourceUpdatedAt = session.lastActivity;
+      }
+    }
+  }
+
+  return {
+    ...usage,
+    estimatedCostUsd: hasUnpricedUsage ? null : estimatedCostUsd,
+    costStatus: hasUnpricedUsage ? "unavailable" : "estimated",
+    models,
+    provenance: {
+      provider: "ccusage",
+      version,
+      sessionCount: sessions.length,
+    },
+    sampledAt,
+    sourceUpdatedAt,
+  };
+}
+
+export async function readCcusageThreadUsage(threadId, {
+  command = "ccusage",
+  run = execFile,
+  sampledAt = new Date().toISOString(),
+  timeoutMs = 8_000,
+} = {}) {
+  let version = null;
+  try {
+    const result = await run(command, ["--version"], {
+      timeout: Math.min(timeoutMs, 2_000),
+      maxBuffer: 64 * 1024,
+    });
+    version = String(result.stdout).trim().replace(/^ccusage\s+/i, "") || null;
+  } catch {
+    // Usage remains useful if an older compatible ccusage cannot print its version.
+  }
+  let result;
+  try {
+    result = await run(command, ["codex", "session", "--json", "--offline"], {
+      timeout: timeoutMs,
+      maxBuffer: 32 * 1024 * 1024,
+      env: { ...process.env, NO_COLOR: "1" },
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new Error("ccusage is not installed");
+    if (error?.killed || error?.code === "ETIMEDOUT") throw new Error("ccusage timed out");
+    throw new Error("ccusage could not read Codex usage");
+  }
+  let payload;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("ccusage returned malformed JSON");
+  }
+  return aggregateCcusageSessions(payload, threadId, { sampledAt, version });
+}
+
+function usageFile(workspace) {
+  return path.join(workspace, USAGE_FILE_NAME);
+}
+
+export async function readUsageStore(workspace) {
+  const filePath = usageFile(workspace);
+  const details = await lstat(filePath).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (details === null) return { schemaVersion: 1, tasks: {} };
+  if (details.isSymbolicLink() || !details.isFile()) {
+    throw new Error("TaskChef usage cache must be a regular file");
+  }
+  if (details.size > MAX_USAGE_FILE_BYTES) {
+    return { schemaVersion: 1, tasks: {} };
+  }
+  const value = JSON.parse(await readFile(filePath, "utf8"));
+  if (value?.schemaVersion !== 1 || !value.tasks || typeof value.tasks !== "object") {
+    throw new Error("TaskChef usage cache has an unsupported schema");
+  }
+  const tasks = Object.entries(value.tasks);
+  if (tasks.length > 2_000) return { schemaVersion: 1, tasks: {} };
+  return {
+    schemaVersion: 1,
+    tasks: Object.fromEntries(tasks.map(([taskId, record]) => [
+      taskId,
+      normalizeStoredRecord(record, `usage task ${taskId}`),
+    ])),
+  };
+}
+
+function compactUsageRecord(record) {
+  const turnEntries = Object.entries(record.turns ?? {}).slice(-MAX_PERSISTED_TURNS);
+  const boundaryEntries = Object.entries(record.boundaries ?? {}).slice(-1);
+  return {
+    ...record,
+    turns: Object.fromEntries(turnEntries),
+    boundaries: Object.fromEntries(boundaryEntries),
+  };
+}
+
+export function compactUsageStore(store) {
+  const entries = Object.entries(store.tasks ?? {})
+    .sort(([, left], [, right]) => Date.parse(right.updatedAt ?? 0) - Date.parse(left.updatedAt ?? 0))
+    .slice(0, MAX_PERSISTED_TASKS);
+  const tasks = {};
+  let approximateBytes = 64;
+  for (const [taskId, record] of entries) {
+    const compacted = compactUsageRecord(record);
+    const entryBytes = Buffer.byteLength(JSON.stringify([taskId, compacted]), "utf8");
+    if (Object.keys(tasks).length > 0 && approximateBytes + entryBytes > USAGE_WRITE_BUDGET_BYTES) break;
+    tasks[taskId] = compacted;
+    approximateBytes += entryBytes;
+  }
+  return { schemaVersion: 1, tasks };
+}
+
+export async function writeUsageStore(workspace, store) {
+  await mkdir(workspace, { recursive: true });
+  const filePath = usageFile(workspace);
+  const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  const serialized = `${JSON.stringify(compactUsageStore(store), null, 2)}\n`;
+  if (Buffer.byteLength(serialized, "utf8") > MAX_USAGE_FILE_BYTES) {
+    throw new Error("TaskChef usage cache cannot be compacted below the size limit");
+  }
+  await writeFile(temporaryPath, serialized, {
+    encoding: "utf8",
+    flag: "wx",
+    mode: 0o600,
+  });
+  try {
+    await rename(temporaryPath, filePath);
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => {});
+    throw error;
+  }
+}
+
+export function usageDelta(current, previous = null) {
+  const baseline = previous ?? Object.fromEntries(TOKEN_FIELDS.map((field) => [field, 0]));
+  const delta = {};
+  for (const field of TOKEN_FIELDS) {
+    const value = current[field] - baseline[field];
+    if (!Number.isFinite(value) || value < 0) return null;
+    delta[field] = value;
+  }
+  let estimatedCostUsd = current.estimatedCostUsd === null
+    || (previous !== null && previous.estimatedCostUsd === null)
+    ? null
+    : current.estimatedCostUsd - (previous?.estimatedCostUsd ?? 0);
+  if (estimatedCostUsd !== null && (!Number.isFinite(estimatedCostUsd) || estimatedCostUsd < 0)) {
+    estimatedCostUsd = null;
+  }
+  if (estimatedCostUsd === 0 && delta.totalTokens > 0) estimatedCostUsd = null;
+  return {
+    ...delta,
+    estimatedCostUsd,
+    costStatus: estimatedCostUsd === null ? "unavailable" : "estimated",
+  };
+}