crewforth 3.1.0-rc.1 → 3.1.0-rc.3

package/kit/skills/frontend-flutter/references/sensitive-data.md

@@ -0,0 +1,54 @@
+# An app that holds sensitive data (Flutter)
+
+Apply only when the app stores data its user would not want read off a lost phone, a backup or the network:
+financial, health, identity. Checked against https://pub.dev/packages/sqlite3 and its hook documentation,
+https://pub.dev/packages/sqlcipher_flutter_libs and https://developer.android.com/identity/data/autobackup
+(2026-10-07). The iOS part is from Apple's API names and was **not checked against a fetched page**.
+
+## The database is encrypted
+- The project's database package decides how; the rule is that the file on disk is ciphertext.
+- With `package:sqlite3` 3.x the SQLite build is chosen by a build hook, in the `pubspec.yaml` at the workspace root:
+
+  ```yaml
+  hooks:
+    user_defines:
+      sqlite3:
+        source: sqlcipher   # or sqlite3mc; the default is sqlite3, which does not encrypt
+  ```
+
+- `sqlcipher_flutter_libs` belongs to version 2.x of `package:sqlite3`; its own page says "Not used anymore, update
+  to version 3.x of package:sqlite3 instead". Do not add it to a project on 3.x.
+- A test opens the database file without the key and expects the open to fail: an encryption that was configured
+  and silently not applied looks the same from the app.
+
+## The key is in the platform's secure store
+- Generated on the device, kept in the Keychain (iOS) or behind the Keystore (Android) through the project's
+  secure-storage package. Not in the database's directory, not in shared preferences, not in the code or its assets.
+- A key that is lost makes the data unreadable. Decide and write down what the app does then (an `adr`).
+
+## Out of backup and device transfer
+The database and the secure store's own files are excluded on both platforms; a restored copy without its key is
+unreadable at best, and a copy with its key is the data on another device.
+
+- **Android.** `android:allowBackup="false"` on `<application>`. For an app that targets Android 12 (API 31) or
+  higher that turns off cloud backup but, in the documentation's words, "doesn't disable device-to-device transfers"
+  on some manufacturers' devices. So also `android:dataExtractionRules` pointing at an XML file whose
+  `<cloud-backup>` and `<device-transfer>` sections each exclude the database and the secure-storage files. Devices
+  on Android 11 or lower read `android:fullBackupContent` instead.
+- **iOS.** The files carry the resource value `isExcludedFromBackup` (`NSURLIsExcludedFromBackupKey`), set from
+  native code or a plugin after the file exists. Set it again when the file is created anew.
+- A test (or a check in CI) reads the manifest and the rules file and fails when either attribute is missing.
+
+## Every network call through a transport bound to its allowed hosts
+- A transport is the one object a service's requests leave through. Each holds the host or hosts **it** may talk
+  to and **refuses any other**: it throws before the request is sent. An app with one backend has one transport;
+  an app that talks to several services gives each its own, with its own list, so a transport for one service
+  cannot reach another's host.
+- A test asks each transport for a host that is not on its list and expects the throw. An architecture test fails
+  on a network call made outside a transport (a client constructed or a socket opened anywhere else). In a debug
+  run the throw is a crash someone sees; it is never swallowed.
+
+## Ads
+In an app that shows ads, **no ad is drawn in a window where a sensitive screen is visible.** In a two-pane layout
+the detail pane may be the sensitive one while the list is not: the rule is about the window, so the list's ad goes
+too. A widget test at an expanded width expects no ad widget while the sensitive detail is shown.

package/kit/studio/server/index.js

@@ -19,6 +19,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { getFleet, measureSpawnCost } from './lib/fleet.js';
 import { projectDir, listSessions, findSession, listProjects, sessionCwd } from './lib/projects.js';
 import { buildGraph, agentDetail, conversation, STALE_MS } from './lib/graph.js';
+import { cachedUsage } from './lib/usage.js';
+
+const USAGE_BATCH = 12;
 import { palette } from './lib/palette.js';
 import { latestVersion, latestVersionCached, kitStatus } from './lib/kit.js';
 import { parsePeers, askAll, ask } from './lib/peers.js';
@@ -192,6 +195,21 @@ async function handle(req, res) {
     });
   }
 
+  // What a handful of sessions spent, for the navigator's rows. Asked for a few at a time and answered from a
+  // cache that lasts until a transcript grows: reading every transcript on the machine to draw a list is not
+  // something a page load should do.
+  if (url.pathname === '/api/usage') {
+    const ids = (url.searchParams.get('ids') ?? '').split(',').filter(Boolean).slice(0, USAGE_BATCH);
+    const usage = {};
+    for (const id of ids) {
+      const session = await findSession(id);
+      if (!session) continue;                 // a session on another machine: not read here, and not guessed
+      const u = await cachedUsage(session);
+      usage[id] = { durationMs: u.durationMs, workedMs: u.workedMs, tokens: u.tokens.total, cost: u.cost, unpriced: u.unpriced };
+    }
+    return sendJson(res, 200, { measured: true, usage });
+  }
+
   if (url.pathname === '/api/fleet') {
     const local = await getFleet();
     const mine = (local.sessions ?? []).map((sn) => ({ ...sn, origin: SELF_NAME, local: true }));

package/kit/studio/server/lib/graph.js

@@ -19,6 +19,8 @@ import path from 'node:path';
 
 import { readAll, contextFill } from './transcript.js';
 import { agentMetaFiles } from './projects.js';
+import { Usage, timesOf } from './usage.js';
+import { detailOf } from './permissions.js';
 
 const SESSION_NODE = 'session';
 
@@ -37,8 +39,12 @@ function textOf(content) {
  * pairs the first id with the status swallows the rest; measured on this
  * machine, one notice carried six ids and five were being dropped. Every id
  * seen since the previous status takes that status.
+ *
+ * `at` is when the record carrying the notice was written. A notice is not the end of an agent: Claude Code sends
+ * one each time a background agent stops, and the agent can be sent another message and work again. Whether a
+ * notice still stands is decided by comparing `at` with what the agent wrote afterwards.
  */
-function harvestCompletions(text, into) {
+function harvestCompletions(text, into, at = null) {
   if (!text || !text.includes('<task-id>')) return;
   const token = /<task-id>([^<]+)<\/task-id>|<status>([^<]+)<\/status>/g;
   let pending = [];
@@ -48,7 +54,7 @@ function harvestCompletions(text, into) {
       pending.push(m[1].trim());
     } else {
       const status = m[2].trim();
-      for (const id of pending) into.set(id, status);
+      for (const id of pending) into.set(id, { status, at });
       pending = [];
     }
   }
@@ -60,7 +66,9 @@ function scanMain(records) {
     startedAt: null, updatedAt: null,
     agentCalls: new Map(),   // toolUseId -> { subagentType, description }
     links: new Map(),        // toolUseId -> { agentId, status, model }
-    completions: new Map(),  // agentId  -> status
+    completions: new Map(),  // task id (an agent's, or a background command's) -> { status, at }
+    commands: new Map(),     // toolUseId -> the command a Bash call ran
+    background: new Map(),   // background task id -> { toolUseId, startedAt }
     owners: new Map(),       // toolUseId -> owner node id
     userTurns: 0,
   };
@@ -71,9 +79,11 @@ function scanMain(records) {
     if (r?.cwd && !out.cwd) out.cwd = r.cwd;
     if (r?.gitBranch && !out.gitBranch) out.gitBranch = r.gitBranch;
     if (r?.version && !out.version) out.version = r.version;
+    let at = null;
     if (r?.timestamp) {
       const t = Date.parse(r.timestamp);
       if (Number.isFinite(t)) {
+        at = t;
         if (out.startedAt === null || t < out.startedAt) out.startedAt = t;
         if (out.updatedAt === null || t > out.updatedAt) out.updatedAt = t;
       }
@@ -86,6 +96,7 @@ function scanMain(records) {
         for (const c of content) {
           if (c?.type === 'tool_use' && c.id) {
             out.owners.set(c.id, SESSION_NODE);
+            if (typeof c.input?.command === 'string') out.commands.set(c.id, c.input.command);
             if (c.name === 'Agent') {
               out.agentCalls.set(c.id, {
                 subagentType: c.input?.subagent_type ?? null,
@@ -95,12 +106,12 @@ function scanMain(records) {
           }
         }
       }
-      harvestCompletions(textOf(content), out.completions);
+      harvestCompletions(textOf(content), out.completions, at);
     }
 
     if (r?.type === 'user') {
       out.userTurns += 1;
-      harvestCompletions(textOf(r.message?.content), out.completions);
+      harvestCompletions(textOf(r.message?.content), out.completions, at);
     }
 
     // Present on the record that carries a subagent's result, whatever its type.
@@ -112,15 +123,81 @@ function scanMain(records) {
       if (id) out.links.set(id, entry);
       else out.links.set(`agent:${tur.agentId}`, entry);
     }
-    if (r?.type === 'attachment') harvestCompletions(JSON.stringify(r.attachment ?? ''), out.completions);
+    // A command sent to the background answers at once with the id it runs under; its end comes later, as a notice.
+    if (tur && typeof tur === 'object' && typeof tur.backgroundTaskId === 'string') {
+      const id = r.message?.content?.find?.((c) => c?.type === 'tool_result')?.tool_use_id ?? null;
+      out.background.set(tur.backgroundTaskId, { toolUseId: id, startedAt: at });
+    }
+    if (r?.type === 'attachment') harvestCompletions(JSON.stringify(r.attachment ?? ''), out.completions, at);
   }
 
   return out;
 }
 
+/**
+ * Does a transcript stop in the middle of a turn? It does when the last thing in it is a tool call with no answer,
+ * or an answer the agent has not replied to. A turn that is over ends on the agent's own words.
+ */
+export function midTurn(records) {
+  for (let i = records.length - 1; i >= 0; i -= 1) {
+    const r = records[i];
+    if (r?.type !== 'assistant' && r?.type !== 'user') continue;
+    const content = r.message?.content;
+    if (r.type === 'user') return true;
+    return Array.isArray(content) && content.some((c) => c?.type === 'tool_use');
+  }
+  return false;
+}
+
+// How long after a notice an agent's own last record may be and still belong to the turn the notice ended. The
+// notice is written after the agent's last record, so anything later than this is the agent working again.
+const NOTICE_SLACK_MS = 5000;
+
+/**
+ * Does a completion notice still say how the agent stands? Not when the agent wrote to its transcript after it:
+ * it was sent another message and is working, or has worked, again.
+ */
+export function noticeStands(notice, lastOwnAt) {
+  if (!notice) return false;
+  if (notice.at == null || lastOwnAt == null) return true;
+  return lastOwnAt <= notice.at + NOTICE_SLACK_MS;
+}
+
+// A call that hands work to an agent is open for as long as that agent runs; it is not a call anyone is asked about.
+const DELEGATES = new Set(['Agent', 'Task']);
+const OPEN_DETAIL_MAX = 2000;
+
+/**
+ * The tool calls a transcript has asked for and has no result for yet, oldest first.
+ *
+ * A call is open while it runs and while it waits for someone to allow it; the transcript does not say which. It
+ * is what a session started in a terminal is asking about when the machine reports it as waiting for its user —
+ * the panel has no hook in such a session, so this is the only place the question can be read from.
+ */
+export function openCalls(records) {
+  const open = new Map();
+  for (const r of records) {
+    const content = r?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const c of content) {
+      if (r.type === 'assistant' && c?.type === 'tool_use' && c.id && !DELEGATES.has(c.name)) {
+        const at = Date.parse(r.timestamp ?? '');
+        const detail = detailOf(c.input);
+        open.set(c.id, {
+          toolUseId: c.id, toolName: c.name ?? 'unknown',
+          detail: detail === null ? null : detail.slice(0, OPEN_DETAIL_MAX),
+          at: Number.isFinite(at) ? at : null,
+        });
+      } else if (r.type === 'user' && c?.type === 'tool_result' && c.tool_use_id) open.delete(c.tool_use_id);
+    }
+  }
+  return [...open.values()];
+}
+
 /** Roll one agent's own transcript into the numbers its node shows. */
-async function scanAgent(file) {
+async function scanAgent(file, usage = null) {
   const { records } = await readAll(file);
+  usage?.add(records);
   const stats = {
     tools: {}, toolCount: 0, lastTool: null, errors: 0,
     tokens: null, startedAt: null, endedAt: null, turns: 0,
@@ -164,10 +241,12 @@ async function scanAgent(file) {
   stats.durationMs = stats.startedAt !== null && stats.endedAt !== null
     ? stats.endedAt - stats.startedAt
     : null;
+  stats.midTurn = midTurn(records);
+  stats.open = openCalls(records);
   return stats;
 }
 
-async function readAgentDir(subagentsDir) {
+async function readAgentDir(subagentsDir, usage = null) {
   const out = [];
   // Nested too: a workflow puts its agents under subagents/workflows/<id>/.
   for (const metaPath of await agentMetaFiles(subagentsDir)) {
@@ -185,7 +264,7 @@ async function readAgentDir(subagentsDir) {
     // `stats` needs the transcript read; a missing file is a normal state (the
     // agent has not written yet), so absence is a null rather than a throw.
     let stats = null;
-    if (mtime !== null) stats = await scanAgent(jsonl);
+    if (mtime !== null) stats = await scanAgent(jsonl, usage);
 
     out.push({
       agentId,
@@ -220,7 +299,9 @@ export const STALE_MS = 120000;
 export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
   const { records, malformed } = await readAll(session.file);
   const main = scanMain(records);
-  const agents = await readAgentDir(session.subagentsDir);
+  // What the session spent, its agents' tokens included and each response counted once.
+  const usage = new Usage().add(records);
+  const agents = await readAgentDir(session.subagentsDir, usage);
   const now = Date.now();
 
   // Ownership: session first, then every agent's own tool_use ids, so a nested
@@ -248,13 +329,26 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
     tokens: contextFill(records),
     startedAt: main.startedAt,
     endedAt: main.updatedAt,
+    usage: { ...usage.result(), ...timesOf(records) },
+    // Commands sent to the background that no notice has ended, oldest first. A session that is over has none
+    // running whatever this says: the page shows them only while the session is live.
+    backgroundCommands: [...main.background]
+      .filter(([id]) => !main.completions.has(id))
+      .map(([id, b]) => ({ id, toolName: 'Bash', detail: main.commands.get(b.toolUseId) ?? null, startedAt: b.startedAt }))
+      .sort((x, y) => (x.startedAt ?? 0) - (y.startedAt ?? 0)),
+    // The newest call nothing has answered, the session's own or an agent's. Null when every call has its result.
+    openCall: [
+      ...openCalls(records).map((c) => ({ ...c, agentId: null, agentType: null })),
+      ...agents.flatMap((a) => (a.stats?.open ?? []).map((c) => ({ ...c, agentId: a.agentId, agentType: a.agentType ?? null }))),
+    ].sort((a, b) => (b.at ?? 0) - (a.at ?? 0))[0] ?? null,
   }];
   const edges = [];
 
   for (const a of agents) {
     const call = a.toolUseId ? main.agentCalls.get(a.toolUseId) : null;
     const link = a.toolUseId ? byToolUse.get(a.toolUseId) : null;
-    const completion = main.completions.get(a.agentId) ?? null;
+    const notice = main.completions.get(a.agentId) ?? null;
+    const completion = noticeStands(notice, a.stats?.endedAt ?? null) ? notice.status : null;
 
     // Order matters. A synchronous Agent call never produces a task
     // notification — it reports through toolUseResult.status instead. Reading
@@ -288,6 +382,11 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
       toolUseId: a.toolUseId,
       model: link?.model ?? null,
       launchStatus: link?.status ?? null,
+      // Started in the background, and its transcript stops in the middle of a turn. Such an agent can be quiet
+      // for a long time inside one tool call; whether it is still working is the live session's to say, so the
+      // page decides (graph-plan.js `settle`), not this file.
+      background: link?.status === 'async_launched',
+      midTurn: a.stats?.midTurn ?? false,
       parentId,
       tools: a.stats?.tools ?? {},
       toolCount: a.stats?.toolCount ?? 0,

package/kit/studio/server/lib/permissions.js

@@ -74,6 +74,16 @@ function gateMode(mode) {
   return typeof mode === 'string' && /^[A-Za-z]+$/.test(mode) ? `CREW_GATE_MODE=${mode} ` : '';
 }
 
+/**
+ * The most identifying field each tool has. Showing "Bash" alone would ask someone to approve a command they
+ * cannot see.
+ */
+export function detailOf(input) {
+  const i = input && typeof input === 'object' ? input : {};
+  const d = i.command ?? i.file_path ?? i.pattern ?? i.query ?? i.description ?? null;
+  return typeof d === 'string' ? d : null;
+}
+
 /** One pending request, as the panel needs to show it. */
 function readRequest(spool, file) {
   const toolUseId = file.replace(/\.json$/, '');
@@ -87,9 +97,7 @@ function readRequest(spool, file) {
   return {
     toolUseId,
     toolName: payload.tool_name ?? 'unknown',
-    // The most identifying field each tool has. Showing "Bash" alone would ask
-    // someone to approve a command they cannot see.
-    detail: input.command ?? input.file_path ?? input.pattern ?? input.query ?? input.description ?? null,
+    detail: detailOf(input),
     input,
     cwd: payload.cwd ?? null,
     // Who asked. Claude Code puts these in the hook's input only when the call comes from inside a subagent, so

package/kit/studio/server/lib/pricing.js

@@ -0,0 +1,63 @@
+// API list prices, for the estimate the panel shows beside a session's tokens.
+//
+// THIS IS THE ONLY PLACE A PRICE IS WRITTEN. Everything is USD per million tokens, copied from the page named
+// in SOURCE on the day named there. A model that is not in this table has no price here: its cost is not
+// estimated from a neighbour, and the panel shows a dash.
+//
+// What the page says and this file follows:
+//   - a cache write costs 1.25x the input price for the 5-minute cache and 2x for the 1-hour cache;
+//   - a cache read costs 0.1x the input price, except where a model's row says otherwise (`cacheRead`);
+//   - Claude Haiku 5.5 has a second set of prices for a prompt of over 100,000 tokens (`over`);
+//   - fast mode has its own input and output prices (`fast`), and the cache multipliers apply on top of them;
+//   - US-only inference multiplies every category by 1.1.
+// What it does not cover: the Batch API discount, web search requests ($10 per 1,000), and prices on other
+// cloud platforms. A session billed under any of those is estimated at the standard rate.
+
+export const SOURCE = {
+  url: 'https://platform.claude.com/docs/en/about-claude/pricing',
+  read: '2026-10-08',
+};
+
+export const CACHE_WRITE_5M = 1.25;
+export const CACHE_WRITE_1H = 2;
+export const CACHE_READ = 0.1;
+export const US_ONLY = 1.1;
+
+// Keyed by the Claude API model id as a transcript records it. Only ids that were checked are here: the four
+// current ones against the models overview page, and the four others against transcripts that name them.
+export const PRICES = {
+  'claude-fable-5-1': { input: 10, output: 50, cacheRead: 0.025 },
+  'claude-opus-5-5': { input: 4, output: 20, cacheRead: 0.05, fast: { input: 8, output: 40 } },
+  'claude-sonnet-5-5': { input: 2, output: 10, cacheRead: 0.05 },
+  'claude-haiku-5-5': { input: 0.10, output: 0.50, over: { promptTokens: 100_000, input: 0.50, output: 2.50 } },
+  'claude-opus-5': { input: 5, output: 25, fast: { input: 10, output: 50 } },
+  'claude-opus-4-8': { input: 5, output: 25, fast: { input: 10, output: 50 } },
+  'claude-sonnet-5': { input: 2, output: 10 },
+  'claude-haiku-4-5': { input: 1, output: 5 },
+};
+
+/** The row for a model id, or null. A dated snapshot (`<id>-20260101`) is the same model; nothing else matches. */
+export function priceOf(model) {
+  if (typeof model !== 'string') return null;
+  if (Object.hasOwn(PRICES, model)) return PRICES[model];
+  const m = model.match(/^(.*)-\d{8}$/);
+  return m && Object.hasOwn(PRICES, m[1]) ? PRICES[m[1]] : null;
+}
+
+/**
+ * What one API response cost at list price, in USD. Null when the model has no row.
+ * @param u { model, input, output, cacheWrite5m, cacheWrite1h, cacheRead, fast, usOnly } — token counts
+ */
+export function costOf(u) {
+  const row = priceOf(u.model);
+  if (!row) return null;
+  const prompt = u.input + u.cacheWrite5m + u.cacheWrite1h + u.cacheRead;
+  const tier = (u.fast && row.fast) || (row.over && prompt > row.over.promptTokens ? row.over : row);
+  const read = row.cacheRead ?? CACHE_READ;
+  const usd = (u.input * tier.input
+    + u.cacheWrite5m * tier.input * CACHE_WRITE_5M
+    + u.cacheWrite1h * tier.input * CACHE_WRITE_1H
+    + u.cacheRead * tier.input * read
+    + u.output * tier.output) / 1_000_000;
+  return u.usOnly ? usd * US_ONLY : usd;
+}

package/kit/studio/server/lib/usage.js

@@ -0,0 +1,144 @@
+// What a session spent: tokens read from its transcripts, and what they would cost at API list price.
+//
+// Claude Code writes one record per content block, and every record of one API response repeats that response's
+// usage. Measured on one machine before this was written: 23,867 assistant records carried usage, for 11,245
+// responses, and every repeat carried the same numbers. So a response is counted once, by its message id — and
+// once across the session's files too, which is what keeps an agent's tokens from being added twice.
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { readAll } from './transcript.js';
+import { agentMetaFiles } from './projects.js';
+import { costOf, SOURCE } from './pricing.js';
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+
+/** One response's usage, in the shape pricing.js prices. Null when the record carries none. */
+export function usageOfRecord(r) {
+  const m = r?.type === 'assistant' ? r.message : null;
+  const u = m?.usage;
+  if (!u || typeof u !== 'object') return null;
+  const split = u.cache_creation && typeof u.cache_creation === 'object' ? u.cache_creation : null;
+  const w1h = num(split?.ephemeral_1h_input_tokens);
+  // With no split recorded, a cache write is the 5-minute kind: that is the default, and the cheaper of the two.
+  const w5m = split ? num(split.ephemeral_5m_input_tokens) : num(u.cache_creation_input_tokens);
+  return {
+    id: typeof m.id === 'string' ? m.id : null,
+    model: typeof m.model === 'string' ? m.model : null,
+    input: num(u.input_tokens),
+    output: num(u.output_tokens),
+    cacheWrite5m: w5m,
+    cacheWrite1h: w1h,
+    cacheRead: num(u.cache_read_input_tokens),
+    fast: u.speed === 'fast',
+    usOnly: u.inference_geo === 'us',
+  };
+}
+
+export class Usage {
+  constructor() {
+    this.seen = new Set();
+    this.tokens = { input: 0, output: 0, cacheWrite: 0, cacheRead: 0 };
+    this.usd = 0;
+    this.responses = 0;
+    this.priced = new Set();
+    this.unpriced = new Set();
+  }
+
+  /** Add a transcript's records. A response already counted, from this file or another, is not counted again. */
+  add(records) {
+    for (const r of records ?? []) {
+      const u = usageOfRecord(r);
+      if (!u) continue;
+      if (u.id) { if (this.seen.has(u.id)) continue; this.seen.add(u.id); }
+      const total = u.input + u.output + u.cacheWrite5m + u.cacheWrite1h + u.cacheRead;
+      if (!total) continue;                    // a record the harness made up for itself carries no tokens
+      this.responses += 1;
+      this.tokens.input += u.input;
+      this.tokens.output += u.output;
+      this.tokens.cacheWrite += u.cacheWrite5m + u.cacheWrite1h;
+      this.tokens.cacheRead += u.cacheRead;
+      const usd = costOf(u);
+      if (usd === null) this.unpriced.add(u.model ?? 'unknown model');
+      else { this.usd += usd; this.priced.add(u.model); }
+    }
+    return this;
+  }
+
+  /**
+   * @returns tokens by kind and in total; `cost` in USD at list price, or null when any of the tokens came from
+   *          a model the table has no row for — a sum that leaves some of them out would read as the whole.
+   */
+  result() {
+    const t = this.tokens;
+    return {
+      tokens: { ...t, total: t.input + t.output + t.cacheWrite + t.cacheRead },
+      responses: this.responses,
+      cost: this.unpriced.size ? null : this.usd,
+      models: [...this.priced].sort(),
+      unpriced: [...this.unpriced].sort(),
+      priceSource: SOURCE,
+    };
+  }
+}
+
+/**
+ * How long a session took, two ways. `durationMs` is from its first record to its last, pauses included.
+ * `workedMs` is the turns Claude Code timed itself (`system` / `turn_duration` records), added up; zero when it
+ * recorded none, and a turn that is still running is not in it.
+ */
+export function timesOf(records) {
+  let first = null;
+  let last = null;
+  let workedMs = 0;
+  let turns = 0;
+  for (const r of records ?? []) {
+    const t = r?.timestamp ? Date.parse(r.timestamp) : NaN;
+    if (Number.isFinite(t)) {
+      if (first === null || t < first) first = t;
+      if (last === null || t > last) last = t;
+    }
+    if (r?.type === 'system' && r.subtype === 'turn_duration' && typeof r.durationMs === 'number' && r.durationMs > 0) {
+      workedMs += r.durationMs;
+      turns += 1;
+    }
+  }
+  return { durationMs: first !== null && last !== null ? last - first : null, workedMs, turns };
+}
+
+/** A session's usage with its agents', and how long it took. */
+export async function sessionUsage(session) {
+  const usage = new Usage();
+  const { records } = await readAll(session.file);
+  usage.add(records);
+  for (const meta of await agentMetaFiles(session.subagentsDir)) {
+    const jsonl = meta.replace(/\.meta\.json$/, '.jsonl');
+    try { usage.add((await readAll(jsonl)).records); } catch { /* an agent that has not written yet */ }
+  }
+  return { ...usage.result(), ...timesOf(records) };
+}
+
+// One answer per session, kept until one of its files changes. The key is what the stream's own signature
+// watches: the transcript's size, and every agent file's.
+const cache = new Map();   // sessionId -> { sig, value }
+
+async function sigOf(session) {
+  const parts = [];
+  try { parts.push(String((await fsp.stat(session.file)).size)); } catch { parts.push('0'); }
+  for (const meta of await agentMetaFiles(session.subagentsDir)) {
+    const jsonl = meta.replace(/\.meta\.json$/, '.jsonl');
+    try { parts.push(`${path.basename(jsonl)}:${(await fsp.stat(jsonl)).size}`); } catch { /* not written yet */ }
+  }
+  return parts.join('|');
+}
+
+export async function cachedUsage(session) {
+  const sig = await sigOf(session);
+  const hit = cache.get(session.sessionId);
+  if (hit && hit.sig === sig) return hit.value;
+  const value = await sessionUsage(session);
+  if (cache.size > 500) cache.clear();
+  cache.set(session.sessionId, { sig, value });
+  return value;
+}