glassbox-trace 0.5.0 → 0.6.0

package/README.md

@@ -31,6 +31,9 @@ glassbox open 81c4 --out trace.html   write a self-contained HTML you can send t
 glassbox check                        print findings; exit 1 on any error-level finding
 glassbox check --format md            the findings as Markdown written for the agent: evidence + what to do next time
 glassbox check --fail-on warn --format json   stricter, machine-readable (CI, hooks, agents); add --redact before sharing
+glassbox check --all --since 30d --redact --legend audit.legend.json --format json
+                                      every session, counts only, files as keys; the legend (key → path) stays with you
+glassbox reveal report.md --legend audit.legend.json   turn the keys in a report back into paths, on your machine
 glassbox compare 81c4 9f0a            same task, two sessions: time, tokens, cost, tools and findings side by side
 glassbox compare 81c4 9f0a --out cmp.html     …as one HTML with both sessions in it
 glassbox watch                        live tail: the viewer follows the newest session as Claude Code writes it
@@ -38,7 +41,7 @@ glassbox watch                        live tail: the viewer follows the newest s
 
 The npm package is `glassbox-trace` (plain `glassbox` was already taken); the command it installs is `glassbox`. Subagent transcripts next to the session are included automatically. `GLASSBOX_HOME` overrides `~/.claude`; `GLASSBOX_BROWSER` names the command used to open HTML.
 
-**In CI:** exit 0 clean, 1 on findings at/above `--fail-on`, 2 on a usage error; `--format json` carries `glassbox` (version) and `schema`; `--redact` blanks prompt text, tool inputs and quoted output. A GitHub Actions example for Agent SDK runs is in [docs/CI.md](docs/CI.md).
+**In CI:** exit 0 clean, 1 on findings at/above `--fail-on`, 2 on a usage error; `--format json` carries `glassbox` (version) and `schema` (2 since 0.6.0: adds `summary.files` and `evidence.files` when a legend is used; schema-1 readers can ignore them); `--redact` blanks prompt text, tool inputs and quoted output. A GitHub Actions example for Agent SDK runs is in [docs/CI.md](docs/CI.md).
 
 **Feed it back to Claude.** `glassbox check --format md` prints the findings the way an agent needs them: each one with the concrete tool calls and request numbers it is about, and a fixed "next time" line per rule. Paste it into the next session ("here's what went wrong last time"), pipe it into a file, or let the Stop hook below deliver it automatically.
 
@@ -62,6 +65,8 @@ glassbox hook uninstall
 
 **In the browser:** the viewer is one HTML file — open `dist/glassbox.html` (double-click, no server; the CLI, compare-from-terminal and live tail need Node 18+). It shows the demo session at rest. Then either drop your `.jsonl` (or the whole `<session-id>` folder for subagent lanes), or in Chrome/Edge click **Open folder…**, pick `~/.claude/projects`, and choose a session from the list — the folder is remembered, so next time it's **Recent**. Finding the file by hand: `ls -t ~/.claude/projects/*/*.jsonl | head` on macOS/Linux, `%USERPROFILE%\.claude\projects\` on Windows.
 
+**Cowork sessions that run in the cloud** keep their transcript in the cloud workspace, not on your machine, and it goes away when the session ends. Before you finish, ask Claude to copy it to a folder you've connected ("save this session's transcript to my Glassbox folder"); it can read its own `~/.claude/projects/…/<session-id>.jsonl` and write it out. Cowork sessions that run locally, and all Claude Code sessions, are already where `glassbox list` looks.
+
 Read top to bottom: stats → timeline (with minimap, search, fit-to-turn) → context & cost → findings → tools → turns. Click anything for detail. Every selection is a permalink (`#req=17`, `#tool=…`, `#find=3`, `#turn=2`).
 
 **Keyboard:** `Tab` into the timeline, `←`/`→` previous/next call, `↑`/`↓` change lane, `Enter` opens detail, `Esc` closes it; `+` `−` `0` zoom, `Shift+←/→` pan, `/` search, `?` help. Touch: drag to pan, pinch to zoom.
@@ -148,6 +153,10 @@ console.log(compare({ trace, findings, cost }, other));      // other = the same
 
 ## Privacy
 
-The page makes no network requests except the Google Fonts stylesheet (it falls back to system fonts if that's blocked). `glassbox watch` binds to `127.0.0.1` only and stops with the command. Transcripts contain everything the agent saw; that's why share mode exists.
+Your context is private — by construction, not by promise.
+
+- **Nothing leaves.** The page makes no network requests except the Google Fonts stylesheet (it falls back to system fonts if that's blocked). The CLI sends nothing anywhere. `glassbox watch` binds to `127.0.0.1` only and stops with the command.
+- **Counts, not text.** Transcripts contain everything the agent saw; that's why share mode and `--redact` exist. Redacted output keeps tool names, numbers, timings and cost and drops every string — prompts, commands, results, titles. Where a finding would quote something it says `«240 chars»`.
+- **The shape, not the names.** A redacted report still needs to say "this one file was read 48 times and 6 of those failed". `check --redact --legend audit.legend.json` replaces every path with a keyed hash (`file:b94b1a35`, HMAC-SHA256 with a random salt) and writes the key → path map to the legend file, which stays on your machine. The redacted JSON carries `summary.files` (reads, writes, failures, agents, chars per key) and `evidence.files` on findings; `duplicate-subagent-read` keeps its sentence with the key in it. `glassbox reveal report.md --legend audit.legend.json` turns the keys back into paths for you. Re-using the legend keeps keys stable across runs; two machines with two legends produce different keys for the same file. Treat the legend like a password file: local, git-ignored, never attached to the same email as the report. Design notes in DESIGN.md §12.
 
 Source: [github.com/aldohushi1-stack/glassbox](https://github.com/aldohushi1-stack/glassbox) · MIT © Aldo Hushi

package/dist/glassbox.html

@@ -402,7 +402,7 @@ kbd{font:11px var(--mono);border:1px solid var(--line);border-bottom-width:2px;b
 })(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict';
 
-  const VERSION = '0.5.0';
+  const VERSION = '0.6.0';
 
   // ---------------------------------------------------------------------------
   // Rate card (USD per million tokens). Prefix-matched against model ids so dated
@@ -1378,6 +1378,41 @@ kbd{font:11px var(--mono);border:1px solid var(--line);border-bottom-width:2px;b
   const CONTENT_DETAIL = new Set(['failed-tool', 'api-error', 'hook-error', 'duplicate-subagent-read']);
   function redactDetail(f) { return CONTENT_DETAIL.has(f.id) ? blank(f.detail) : f.detail; }
 
+  // ---------------------------------------------------------------------------
+  // Per-file use: how often each file was read or written, by how many agents, and how often
+  // those calls failed. Paths are normalised (backslashes, case) but otherwise kept; the CLI's
+  // legend replaces them with keys when sharing.
+  // ---------------------------------------------------------------------------
+  const FILE_READ = new Set(['Read']);
+  const FILE_WRITE = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+  function filePathOf(c) { const i = c && c.input; if (!i) return null; const p = i.file_path || i.notebook_path; return typeof p === 'string' && p ? p : null; }
+  function normalisePath(p) { return String(p).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase(); }
+  function fileStats(trace, opts) {
+    const minCalls = (opts && opts.minCalls) || 3, minAgents = (opts && opts.minAgents) || 2;
+    const rows = new Map();
+    for (const c of trace.toolCalls) {
+      if (c.unmatched) continue;
+      const isRead = FILE_READ.has(c.name), isWrite = FILE_WRITE.has(c.name);
+      if (!isRead && !isWrite) continue;
+      const p = filePathOf(c); if (!p) continue;
+      const k = normalisePath(p);
+      if (!rows.has(k)) rows.set(k, { path: p, reads: 0, writes: 0, errors: 0, chars: 0, agentSet: new Set(), tools: {} });
+      const r = rows.get(k);
+      if (isRead) { r.reads++; r.chars += c.resultChars || 0; } else r.writes++;
+      if (c.isError) r.errors++;
+      r.agentSet.add(c.agent);
+      r.tools[c.name] = (r.tools[c.name] || 0) + 1;
+    }
+    const out = [];
+    for (const r of rows.values()) {
+      const calls = r.reads + r.writes;
+      if (calls < minCalls && !r.errors && r.agentSet.size < minAgents) continue;
+      out.push({ path: r.path, reads: r.reads, writes: r.writes, errors: r.errors, agents: r.agentSet.size, chars: r.chars, tools: r.tools });
+    }
+    out.sort((a, b) => (b.reads + b.writes) - (a.reads + a.writes) || b.errors - a.errors || a.path.localeCompare(b.path));
+    return out;
+  }
+
   function reportMarkdown(trace, findings, cost, opts) {
     opts = opts || {};
     const redact = !!opts.redact, maxEv = opts.maxEvidence || 6;
@@ -1533,7 +1568,7 @@ kbd{font:11px var(--mono);border:1px solid var(--line);border-bottom-width:2px;b
   }
   function toJsonl(records) { return records.map((r) => JSON.stringify(r)).join('\n') + '\n'; }
 
-  return { VERSION, RATES, DEFAULTS, ADVICE, METRICS, parseLines, parseTrace, diagnose, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, fmtMetric, fmtRatio, fmtChange, stableStringify, inputSummary, adviceFor, redactDetail, reportMarkdown, compare, compareMarkdown, toolTable };
+  return { VERSION, RATES, DEFAULTS, ADVICE, METRICS, parseLines, parseTrace, diagnose, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, fmtMetric, fmtRatio, fmtChange, stableStringify, inputSummary, adviceFor, redactDetail, reportMarkdown, compare, compareMarkdown, toolTable, fileStats, filePathOf, normalisePath };
 });
 </script>
 <script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glassbox-trace",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Other tools show what happened in a Claude Code session; Glassbox tells you what went wrong. Timeline, token and cost burn, auto-diagnostics with evidence and advice, session compare, live tail, a CLI and a Claude Code Stop hook that feeds the findings back to the agent.",
   "main": "src/trace-core.js",
   "scripts": {
@@ -44,7 +44,7 @@
     "accessibility"
   ],
   "devDependencies": {
-    "playwright": "^1.49.0"
+    "playwright": "1.63.0"
   },
   "homepage": "https://github.com/aldohushi1-stack/glassbox#readme",
   "repository": {

package/src/cli.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 const require = createRequire(import.meta.url);
@@ -125,6 +126,34 @@ export function openInBrowser(file, env = process.env) {
   child.on('error', () => { }); child.unref();
 }
 
+// ---------------------------------------------------------------------------
+// Legend: file paths → stable keys ("file:1a2b3c4d") for redacted output. The key is the first
+// 8 hex chars of HMAC-SHA256(salt, normalised path); the salt is random, made once, and lives
+// only in the legend file with the key→path map. Re-using the file keeps keys stable across runs.
+// ---------------------------------------------------------------------------
+export const FILE_KEY_RE = /\bfile:[0-9a-f]{8,16}\b/g;
+export class Legend {
+  constructor(data) { this.salt = data && data.salt || crypto.randomBytes(32).toString('hex'); this.files = data && data.files || {}; this.created = data && data.created || new Date().toISOString(); this.byPath = new Map(Object.entries(this.files).map(([k, v]) => [core.normalisePath(v), k])); this.dirty = !data; }
+  static load(file) {
+    if (!file || !fs.existsSync(file)) return new Legend(null);
+    let json; try { json = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`--legend ${file}: not valid JSON (delete it to start a new legend)`); }
+    if (!json || typeof json.salt !== 'string' || typeof json.files !== 'object') throw new Error(`--legend ${file}: not a Glassbox legend`);
+    return new Legend(json);
+  }
+  keyFor(p) {
+    const norm = core.normalisePath(p);
+    const have = this.byPath.get(norm); if (have) return have;
+    const hex = crypto.createHmac('sha256', Buffer.from(this.salt, 'hex')).update(norm).digest('hex');
+    let len = 8; let key = 'file:' + hex.slice(0, len);
+    while (this.files[key] && core.normalisePath(this.files[key]) !== norm && len < 16) { len += 2; key = 'file:' + hex.slice(0, len); } // collision: lengthen
+    this.files[key] = String(p); this.byPath.set(norm, key); this.dirty = true;
+    return key;
+  }
+  pathFor(key) { return this.files[key] || null; }
+  save(file) { if (!file) return null; fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true }); fs.writeFileSync(file, JSON.stringify({ glassbox: core.VERSION, note: 'Glassbox legend: maps file keys in a redacted report back to paths on this machine. Keep it here; never send it with the report.', created: this.created, updated: new Date().toISOString(), salt: this.salt, files: this.files }, null, 2) + '\n'); this.dirty = false; return path.resolve(file); }
+  reveal(text) { let unknown = 0; const out = String(text).replace(FILE_KEY_RE, (k) => { const p = this.pathFor(k); if (p == null) unknown++; return p == null ? k : p; }); return { text: out, unknown }; }
+}
+
 const SEV = { error: 0, warn: 1, info: 2 };
 // Text output only: identical findings (same severity, rule and title) print once with a ×N count.
 export function collapseFindings(findings) {
@@ -141,8 +170,22 @@ export function checkReport({ trace, findings, cost }, opts = {}) {
   const fmt = core.fmtDur, fi = core.fmtInt;
   const usd = (v) => v == null ? '—' : '$' + (v < 1 ? v.toFixed(3) : v.toFixed(2));
   const redact = !!opts.redact;
+  const legend = opts.legend || null;
+  const keyed = (p) => legend ? legend.keyFor(p) : p;
   const summary = { session: m.sessionId, title: m.title ? (redact ? '«' + m.title.length + ' chars»' : m.title) : null, model: m.models, wallMs: T.wallMs, activeMs: T.activeMs, turns: T.turns, requests: T.requests, toolCalls: T.toolCalls, toolErrors: T.toolErrors, orphans: T.orphans, usage: T.usage, cacheHitRatio: T.cacheHitRatio, cost: cost.reported != null ? cost.reported : cost.total, costSource: cost.source };
-  const json = { glassbox: core.VERSION, schema: 1, redacted: redact, summary, findings: findings.map((f) => ({ id: f.id, severity: f.severity, title: f.title, detail: redact ? core.redactDetail(f) : f.detail, metric: f.metric, evidence: f.evidence })), failOn, failed: failing.length > 0 };
+  // Per-file use, keyed when a legend is given; with --redact and no legend the paths would leak, so it is omitted.
+  if (legend || !redact) summary.files = core.fileStats(trace).map((r) => ({ key: legend ? legend.keyFor(r.path) : r.path, reads: r.reads, writes: r.writes, errors: r.errors, agents: r.agents, chars: r.chars }));
+  const findingJson = (f) => {
+    const ev = f.evidence || {};
+    const paths = Array.from(new Set((ev.toolCallIds || []).map((id) => { const c = trace.toolCalls.find((x) => x.id === id); return c ? core.filePathOf(c) : null; }).filter(Boolean)));
+    let detail = redact ? core.redactDetail(f) : f.detail;
+    // duplicate-subagent-read quotes the path and nothing else: with a legend, keep the sentence and key the path.
+    if (redact && legend && f.id === 'duplicate-subagent-read') { detail = f.detail; for (const p of paths) detail = detail.split(p).join(legend.keyFor(p)); }
+    const evidence = Object.assign({}, ev);
+    if (paths.length && (legend || !redact)) evidence.files = Array.from(new Set(paths.map(keyed)));
+    return { id: f.id, severity: f.severity, title: f.title, detail, metric: f.metric, evidence };
+  };
+  const json = { glassbox: core.VERSION, schema: 2, redacted: redact, legend: !!legend, summary, findings: findings.map(findingJson), failOn, failed: failing.length > 0 };
   const lines = [];
   lines.push(`Glassbox · ${m.sessionId ? m.sessionId.slice(0, 8) : 'session'} · ${m.models.join(', ') || 'unknown model'}`);
   lines.push(`  wall ${fmt(T.wallMs)} (active ${fmt(T.activeMs)}) · ${T.turns} turns · ${T.requests} requests · ${T.toolCalls} tool calls (${T.toolErrors} failed${T.orphans ? ', ' + T.orphans + ' unanswered' : ''})`);
@@ -281,7 +324,7 @@ export function parseArgs(argv) {
   const args = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a.startsWith('--')) { const [k, v] = a.slice(2).split('='); if (v !== undefined) args.flags[k] = v; else if (i + 1 < argv.length && !argv[i + 1].startsWith('-') && ['last', 'grep', 'project', 'out', 'fail-on', 'home', 'command', 'events', 'format', 'label-a', 'label-b', 'port', 'rates', 'since'].includes(k)) args.flags[k] = argv[++i]; else args.flags[k] = true; }
+    if (a.startsWith('--')) { const [k, v] = a.slice(2).split('='); if (v !== undefined) args.flags[k] = v; else if (i + 1 < argv.length && !argv[i + 1].startsWith('-') && ['last', 'grep', 'project', 'out', 'fail-on', 'home', 'command', 'events', 'format', 'label-a', 'label-b', 'port', 'rates', 'since', 'legend'].includes(k)) args.flags[k] = argv[++i]; else args.flags[k] = true; }
     else args._.push(a);
   }
   return args;
@@ -300,6 +343,11 @@ export const HELP = `glassbox — other tools show you what happened in a Claude
                                  --redact blanks prompt text, tool inputs and result text so the report can be shared
   glassbox check --all [--since 1h] [--project PATH]
                                  one line per session (all, or written in the last 30m/1h/2d); exit 1 if any fails
+  glassbox check --redact --legend FILE
+                                 keep the shape of file use in redacted output: every path becomes a key (file:1a2b3c4d)
+                                 and FILE gets the key→path map — it stays with you and never goes with the report
+  glassbox reveal FILE --legend LEGEND
+                                 print FILE (a report, JSON, any text) with the keys turned back into paths
   glassbox compare A B [--format text|json|md] [--out FILE.html] [--label-a NAME --label-b NAME]
                                  same task, two sessions: what changed in time, tokens, cost, tools and findings
   glassbox watch [ID|FILE] [--port N] [--no-open]
@@ -357,14 +405,27 @@ export async function main(argv, io = {}) {
       for (const s of list) out(`${s.id.slice(0, 8)}  ${new Date(s.mtime).toISOString().slice(0, 16).replace('T', ' ')}  ${String(Math.round(s.size / 1024)).padStart(6)} KB  ${s.project.padEnd(28).slice(0, 28)}  ${sessionTitle(s.file)}`);
       return 0;
     }
+    const legendFile = args.flags.legend ? String(args.flags.legend) : null;
+    if (legendFile && !args.flags.redact && cmd === 'check') throw new Error('--legend only makes sense with --redact (without --redact the paths are in the output anyway)');
+    const legend = legendFile ? Legend.load(legendFile) : null;
+    const saveLegend = () => { if (legend && legend.dirty) err(`legend: ${legend.save(legendFile)} (${Object.keys(legend.files).length} files) — keep it; do not send it with the report`); };
+    if (cmd === 'reveal') {
+      if (!args._[1]) throw new Error('reveal needs a file: glassbox reveal report.md --legend audit.legend.json');
+      if (!legendFile || !fs.existsSync(legendFile)) throw new Error('reveal needs --legend FILE (the legend written by check --redact --legend)');
+      const r = legend.reveal(fs.readFileSync(args._[1], 'utf8'));
+      out(r.text.replace(/\n$/, ''));
+      if (r.unknown) err(`reveal: ${r.unknown} key${r.unknown === 1 ? '' : 's'} not in this legend (left as they are)`);
+      return 0;
+    }
     if (cmd === 'check' && args.flags.all) {
       // Every session (optionally only those written in the last --since), one line each; exit 1 if any fails.
       const since = args.flags.since ? parseSince(args.flags.since) : null;
       const list = findSessions({ home, project: args.flags.project }).filter((s) => since == null || s.mtime >= Date.now() - since);
       const fmtOut = outputFormat(args.flags);
-      const reps = list.map((s) => ({ s, rep: checkReport(analyse(loadSessionFiles(s), rates), { failOn: args.flags['fail-on'], redact: !!args.flags.redact }) }));
+      const reps = list.map((s) => ({ s, rep: checkReport(analyse(loadSessionFiles(s), rates), { failOn: args.flags['fail-on'], redact: !!args.flags.redact, legend }) }));
+      saveLegend();
       const failed = reps.filter((r) => r.rep.failed).length;
-      if (fmtOut === 'json') out(JSON.stringify({ glassbox: core.VERSION, schema: 1, failOn: args.flags['fail-on'] || 'error', failed: failed > 0, sessions: reps.map((r) => r.rep.json) }, null, 2));
+      if (fmtOut === 'json') out(JSON.stringify({ glassbox: core.VERSION, schema: 2, redacted: !!args.flags.redact, legend: !!legend, failOn: args.flags['fail-on'] || 'error', failed: failed > 0, sessions: reps.map((r) => r.rep.json) }, null, 2));
       else if (fmtOut === 'md') out(reps.map((r) => r.rep.markdown).join('\n---\n\n'));
       else {
         if (!reps.length) out(since != null ? `No sessions written in the last ${args.flags.since}.` : noSessionsMessage(home));
@@ -375,7 +436,8 @@ export async function main(argv, io = {}) {
     }
     if (cmd === 'check') {
       const s = resolveTarget(args._[1], { home });
-      const res = checkReport(analyse(loadSessionFiles(s), rates), { failOn: args.flags['fail-on'], redact: !!args.flags.redact });
+      const res = checkReport(analyse(loadSessionFiles(s), rates), { failOn: args.flags['fail-on'], redact: !!args.flags.redact, legend });
+      saveLegend();
       const fmtOut = outputFormat(args.flags);
       if (fmtOut === 'json') out(JSON.stringify(res.json, null, 2)); else if (fmtOut === 'md') out(res.markdown); else out(res.text);
       return res.failed ? 1 : 0;

package/src/trace-core.js

@@ -9,7 +9,7 @@
 })(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict';
 
-  const VERSION = '0.5.0';
+  const VERSION = '0.6.0';
 
   // ---------------------------------------------------------------------------
   // Rate card (USD per million tokens). Prefix-matched against model ids so dated
@@ -985,6 +985,41 @@
   const CONTENT_DETAIL = new Set(['failed-tool', 'api-error', 'hook-error', 'duplicate-subagent-read']);
   function redactDetail(f) { return CONTENT_DETAIL.has(f.id) ? blank(f.detail) : f.detail; }
 
+  // ---------------------------------------------------------------------------
+  // Per-file use: how often each file was read or written, by how many agents, and how often
+  // those calls failed. Paths are normalised (backslashes, case) but otherwise kept; the CLI's
+  // legend replaces them with keys when sharing.
+  // ---------------------------------------------------------------------------
+  const FILE_READ = new Set(['Read']);
+  const FILE_WRITE = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+  function filePathOf(c) { const i = c && c.input; if (!i) return null; const p = i.file_path || i.notebook_path; return typeof p === 'string' && p ? p : null; }
+  function normalisePath(p) { return String(p).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase(); }
+  function fileStats(trace, opts) {
+    const minCalls = (opts && opts.minCalls) || 3, minAgents = (opts && opts.minAgents) || 2;
+    const rows = new Map();
+    for (const c of trace.toolCalls) {
+      if (c.unmatched) continue;
+      const isRead = FILE_READ.has(c.name), isWrite = FILE_WRITE.has(c.name);
+      if (!isRead && !isWrite) continue;
+      const p = filePathOf(c); if (!p) continue;
+      const k = normalisePath(p);
+      if (!rows.has(k)) rows.set(k, { path: p, reads: 0, writes: 0, errors: 0, chars: 0, agentSet: new Set(), tools: {} });
+      const r = rows.get(k);
+      if (isRead) { r.reads++; r.chars += c.resultChars || 0; } else r.writes++;
+      if (c.isError) r.errors++;
+      r.agentSet.add(c.agent);
+      r.tools[c.name] = (r.tools[c.name] || 0) + 1;
+    }
+    const out = [];
+    for (const r of rows.values()) {
+      const calls = r.reads + r.writes;
+      if (calls < minCalls && !r.errors && r.agentSet.size < minAgents) continue;
+      out.push({ path: r.path, reads: r.reads, writes: r.writes, errors: r.errors, agents: r.agentSet.size, chars: r.chars, tools: r.tools });
+    }
+    out.sort((a, b) => (b.reads + b.writes) - (a.reads + a.writes) || b.errors - a.errors || a.path.localeCompare(b.path));
+    return out;
+  }
+
   function reportMarkdown(trace, findings, cost, opts) {
     opts = opts || {};
     const redact = !!opts.redact, maxEv = opts.maxEvidence || 6;
@@ -1140,5 +1175,5 @@
   }
   function toJsonl(records) { return records.map((r) => JSON.stringify(r)).join('\n') + '\n'; }
 
-  return { VERSION, RATES, DEFAULTS, ADVICE, METRICS, parseLines, parseTrace, diagnose, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, fmtMetric, fmtRatio, fmtChange, stableStringify, inputSummary, adviceFor, redactDetail, reportMarkdown, compare, compareMarkdown, toolTable };
+  return { VERSION, RATES, DEFAULTS, ADVICE, METRICS, parseLines, parseTrace, diagnose, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, fmtMetric, fmtRatio, fmtChange, stableStringify, inputSummary, adviceFor, redactDetail, reportMarkdown, compare, compareMarkdown, toolTable, fileStats, filePathOf, normalisePath };
 });