glassbox-trace 0.3.0 → 0.5.0

package/src/trace-core.js

@@ -9,7 +9,7 @@
 })(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict';
 
-  const VERSION = '0.3.0';
+  const VERSION = '0.5.0';
 
   // ---------------------------------------------------------------------------
   // Rate card (USD per million tokens). Prefix-matched against model ids so dated
@@ -57,6 +57,13 @@
     longTurnTools: 30,
     failedToolRate: 0.5,
     failedToolMinCalls: 3,
+    failedToolWarnMinErrors: 2,
+    failedToolWarnRate: 0.2,
+    cacheMissMinShare: 0.05,
+    longGenerationMaxTokPerSec: 15,
+    duplicateReadAgents: 3,
+    duplicateReadWarnChars: 100000,
+    groupRepeatsMin: 3, // slow-tool / oversized-result: this many from one tool become one finding
   };
 
   // ---------------------------------------------------------------------------
@@ -66,18 +73,31 @@
   const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
   const EXEC_TOOLS = new Set(['Bash', 'BashOutput', 'KillShell']);
   const AGENT_TOOLS = new Set(['Agent', 'Task', 'Workflow']);
-  const USER_TOOLS = new Set(['AskUserQuestion']);
+  const USER_TOOLS = new Set(['AskUserQuestion', 'SendUserMessage', 'SendUserFile', 'ExitPlanMode', 'EnterPlanMode']);
+  // Cowork: Artifact publishes a page (a write), Skill loads instructions (a read); Task* are bookkeeping (other).
+  const COWORK_READ = new Set(['Skill', 'ListSkills', 'SearchSkills', 'TaskList', 'TaskGet']);
+  const COWORK_WRITE = new Set(['Artifact']);
+  // Blocking reads of a background task's output: the duration is the task's run time, and re-issuing the
+  // same call after a "still running" timeout is polling, not a retry.
+  const WAIT_TOOLS = new Set(['TaskOutput', 'AgentOutputTool']);
+  const isWait = (c) => WAIT_TOOLS.has(c.name) && !(c.input && c.input.block === false);
+  const waitTarget = (c) => { const i = c.input || {}; return String(i.task_id || i.agentId || i.bash_id || ''); };
+  const hasRange = (c) => !!(c.input && (c.input.limit != null || c.input.offset != null || c.input.head_limit != null));
+  // MCP leaf names are verb_noun or noun_verb ("memory_read", "device_list_dir", "send_message"): match the verb as a word.
+  const MCP_READ = /(^|_)(get|list|search|read|find|fetch|query|describe|show|stage|screenshot|context|status|info|check)(_|$)/i;
+  const MCP_WRITE = /(^|_)(write|set|put|create|update|delete|remove|commit|send|reply|forward|upload|str_replace|append|label|move|rename|save)(_|$)/i;
 
   function toolCategory(name) {
     if (!name) return 'other';
-    if (READ_TOOLS.has(name)) return 'read';
-    if (WRITE_TOOLS.has(name)) return 'write';
+    if (READ_TOOLS.has(name) || COWORK_READ.has(name)) return 'read';
+    if (WRITE_TOOLS.has(name) || COWORK_WRITE.has(name)) return 'write';
     if (EXEC_TOOLS.has(name) || /device_bash$/.test(name)) return 'exec';
     if (AGENT_TOOLS.has(name)) return 'agent';
     if (USER_TOOLS.has(name)) return 'user';
     if (name.startsWith('mcp__')) {
       const leaf = name.split('__').pop() || '';
-      if (/^(get|list|search|read|find|fetch|query|describe|show)/i.test(leaf)) return 'read';
+      if (MCP_READ.test(leaf)) return 'read';
+      if (MCP_WRITE.test(leaf)) return 'write';
       return 'mcp';
     }
     return 'other';
@@ -143,6 +163,26 @@
     return !u.input && !u.cacheRead && !u.cacheWrite && !u.output;
   }
 
+  // A tool call that never ran because the human or a permission rule stopped it. Claude Code
+  // records toolDenialKind (user-rejected, permission-rule, automode-blocked, interrupted); older
+  // transcripts only have the result text. A shell's own "Permission denied" is a real failure.
+  function denialKind(rec, text) {
+    if (rec && rec.toolDenialKind) return String(rec.toolDenialKind);
+    const t = String(text || '').trim();
+    if (/^\[Request interrupted by user/.test(t)) return 'interrupted';
+    if (/^The user doesn't want to proceed with this tool use|^User rejected tool use|^Denied by voice/.test(t)) return 'user-rejected';
+    if (/^Permission (for this action was|to use \S+ has been) denied/.test(t)) return 'permission-rule';
+    return null;
+  }
+
+  // One API response is written as several records (one per content block). Subagent transcripts
+  // rewrite output_tokens as the stream progresses, so the first record can be far below the final
+  // count; the other fields repeat. Keep the largest value seen for each field.
+  function maxUsage(a, b) {
+    for (const k of Object.keys(a)) if ((b[k] || 0) > a[k]) a[k] = b[k];
+    return a;
+  }
+
   // ---------------------------------------------------------------------------
   // Line parsing
   // ---------------------------------------------------------------------------
@@ -233,7 +273,7 @@
     const meta = {
       sessionId: null, version: null, cwd: null, gitBranch: null, entrypoint: null, title: null,
       models: [], start: null, end: null, hasTimestamps, files: fileMeta, format: 'claude-code',
-      reportedCost: null, reportedUsage: null, recordCounts: {},
+      reportedCost: null, reportedUsage: null, reportedTurns: null, reportedDurationMs: null, recordCounts: {},
     };
 
     const agents = new Map(); // id -> agent
@@ -243,6 +283,7 @@
         agents.set(id, {
           id, type: id === 'main' ? 'main' : 'subagent', description: null, parentToolUseId: null,
           start: null, end: null, usage: emptyUsage(), requestCount: 0, toolCount: 0, model: null,
+          workflowRun: (String(rec._file || '').match(/workflows[\\/](wf_[^\\/]+)[\\/]/) || [])[1] || null,
         });
       }
       const a = agents.get(id);
@@ -293,13 +334,17 @@
       if (!meta.gitBranch && rec.gitBranch) meta.gitBranch = rec.gitBranch;
       if (!meta.entrypoint && rec.entrypoint) meta.entrypoint = rec.entrypoint;
       const t = ts(rec);
-      if (t != null) { if (meta.start == null || t < meta.start) meta.start = t; if (meta.end == null || t > meta.end) meta.end = t; }
+      // Only conversation records bound the session: bookkeeping records (frame-link, file-history…)
+      // can be written days later and would stretch the wall clock.
+      if (t != null && (type === 'user' || type === 'assistant' || type === 'system')) { if (meta.start == null || t < meta.start) meta.start = t; if (meta.end == null || t > meta.end) meta.end = t; }
 
       if (type === 'summary') { if (rec.summary && !meta.title) meta.title = rec.summary; events.push({ kind: 'summary', at: t, detail: rec.summary }); continue; }
       if (type === 'attachment') { attachments.count++; attachments.chars += JSON.stringify(rec.attachment || '').length; continue; }
       if (type === 'result') {
         meta.format = 'stream-json';
         if (typeof rec.total_cost_usd === 'number') meta.reportedCost = rec.total_cost_usd;
+        if (typeof rec.num_turns === 'number') meta.reportedTurns = rec.num_turns;
+        if (typeof rec.duration_ms === 'number') meta.reportedDurationMs = rec.duration_ms;
         if (rec.usage) meta.reportedUsage = usageFrom(rec.usage);
         if (rec.is_error) events.push({ kind: 'api_error', at: t, detail: textOf(rec.result) || 'result is_error' });
         continue;
@@ -345,6 +390,7 @@
               if (structured && typeof structured === 'object' && !text && !imgs.length) call.resultChars = JSON.stringify(structured).length;
               // stream-json puts is_error only in block; Claude Code also stores toolUseResult as an Error string
               if (!tr.is_error && typeof structured === 'string' && /^Error/i.test(structured)) { call.status = 'error'; call.isError = true; }
+              if (call.isError) call.denial = denialKind(rec, text);
             } else {
               toolCalls.push(mkOrphanResult(tr, rec, a.id, text, turns.length ? turns[turns.length - 1].index : null));
             }
@@ -357,6 +403,7 @@
         let kind = 'human';
         if (rec.isCompactSummary) kind = 'compact';
         else if (rec.isMeta) kind = 'meta';
+        else if (/^\[Request interrupted by user/.test(text.trim())) kind = 'interrupt';
         else if (/^<(system-reminder|local-command|command-name|bash-input|bash-stdout)/.test(text.trim())) kind = 'meta';
         ensureTurn(rec, kind, text);
         continue;
@@ -379,16 +426,10 @@
           turn.requestIds.push(req.id);
           a.requestCount++;
           if (msg.model) { pushModel(meta, msg.model); if (!a.model) a.model = msg.model; }
-          const u = usageFrom(msg.usage);
-          if (!isEmptyUsage(u)) { req.usage = u; req.contextTokens = u.input + u.cacheRead + u.cacheWrite; addUsage(turn.usage, u); addUsage(a.usage, u); }
         } else {
           if (t != null) { if (req.start == null || t < req.start) req.start = t; if (req.end == null || t > req.end) req.end = t; }
-          // usage: if the first record lacked it and a later one has it, take it once
-          if (isEmptyUsage(req.usage)) {
-            const u = usageFrom(msg.usage);
-            if (!isEmptyUsage(u)) { req.usage = u; req.contextTokens = u.input + u.cacheRead + u.cacheWrite; const turn = turns[req.turnIndex]; addUsage(turn.usage, u); addUsage(a.usage, u); }
-          }
         }
+        maxUsage(req.usage, usageFrom(msg.usage)); // turn and agent totals are summed once, after the loop
         req.records++;
         if (msg.stop_reason) req.stopReason = msg.stop_reason;
         if (rec.isApiErrorMessage) req.isApiError = true;
@@ -401,7 +442,7 @@
               id: b.id || (key + ':' + blockIndex), agent: a.id, requestId: req.id, name: b.name || 'unknown', input: b.input || {},
               start: t, end: null, durationMs: null, status: 'orphan', isError: false, resultText: '', resultChars: 0,
               resultStructured: null, category: toolCategory(b.name), turnIndex: req.turnIndex, subagentId: null,
-              inputChars: JSON.stringify(b.input || {}).length, resultImages: 0, imageBytes: 0,
+              inputChars: JSON.stringify(b.input || {}).length, resultImages: 0, imageBytes: 0, denial: null,
             };
             toolCalls.push(call);
             toolCallById.set(call.id, call);
@@ -423,7 +464,12 @@
     }
 
     // Finalise
-    for (const req of requests) req.blocks.sort((x, y) => x.index - y.index);
+    for (const req of requests) {
+      req.blocks.sort((x, y) => x.index - y.index);
+      req.contextTokens = req.usage.input + req.usage.cacheRead + req.usage.cacheWrite;
+      addUsage(turns[req.turnIndex].usage, req.usage);
+      addUsage(agents.get(req.agent).usage, req.usage);
+    }
     for (const turn of turns) if (turn.end == null) turn.end = meta.end;
     // Response timing. Assistant record timestamps are written when a block finishes streaming,
     // so a request's "start" is really its first completed block. We measure from the moment the
@@ -455,9 +501,14 @@
         const parent = toolCalls.find((c) => c.category === 'agent' && c.agent === 'main' && ((c.resultText && c.resultText.includes(ag.id)) || (c.resultStructured && JSON.stringify(c.resultStructured).includes(ag.id))));
         if (parent) ag.parentToolUseId = parent.id;
       }
+      // Workflow agents live in subagents/workflows/<runId>/; the Workflow call's result names that runId.
+      if (!ag.parentToolUseId && ag.workflowRun) {
+        const parent = toolCalls.find((c) => c.name === 'Workflow' && ((c.resultStructured && c.resultStructured.runId === ag.workflowRun) || (c.resultText && c.resultText.includes(ag.workflowRun))));
+        if (parent) ag.parentToolUseId = parent.id;
+      }
       if (ag.parentToolUseId) {
         const parent = toolCallById.get(ag.parentToolUseId);
-        if (parent) { parent.subagentId = ag.id; if (!ag.description && parent.input && parent.input.description) ag.description = parent.input.description; if (!ag.agentType && parent.input && parent.input.subagent_type) ag.agentType = parent.input.subagent_type; }
+        if (parent) { if (!parent.subagentId) parent.subagentId = ag.id; (parent.subagentIds || (parent.subagentIds = [])).push(ag.id); if (!ag.description && parent.input && parent.input.description) ag.description = parent.input.description; if (!ag.agentType && parent.input && parent.input.subagent_type) ag.agentType = parent.input.subagent_type; }
       }
     }
 
@@ -465,12 +516,15 @@
     const usage = emptyUsage();
     for (const r of requests) addUsage(usage, r.usage);
     const humanIdleMs = turns.reduce((s, tn) => s + (tn.idleBeforeMs || 0), 0);
-    const wallMs = (meta.start != null && meta.end != null) ? meta.end - meta.start : null;
+    // stream-json runs carry no per-record timestamps and no human prompt record, but the result
+    // record reports duration_ms and num_turns; use those rather than showing "—" and 0.
+    const wallMs = (meta.start != null && meta.end != null) ? meta.end - meta.start : (meta.reportedDurationMs != null ? meta.reportedDurationMs : null);
+    const humanTurns = turns.filter((tn) => tn.promptKind === 'human' && tn.agent === 'main').length;
     const totals = {
       usage, wallMs, humanIdleMs, activeMs: wallMs != null ? Math.max(0, wallMs - humanIdleMs) : null,
       requests: requests.length, toolCalls: toolCalls.length, toolErrors: toolCalls.filter((c) => c.isError).length,
       orphans: toolCalls.filter((c) => c.status === 'orphan').length,
-      turns: turns.filter((tn) => tn.promptKind === 'human' && tn.agent === 'main').length,
+      turns: humanTurns || (meta.reportedTurns != null ? meta.reportedTurns : 0),
       toolTimeMs: toolCalls.filter((c) => c.agent === 'main').reduce((s, c) => s + (c.durationMs || 0), 0),
       modelTimeMs: agents.get('main').modelTimeMs || 0,
       cacheHitRatio: (usage.cacheRead + usage.cacheWrite + usage.input) ? usage.cacheRead / (usage.cacheRead + usage.cacheWrite + usage.input) : null,
@@ -508,9 +562,20 @@
       if (!byTurnSig.has(sig)) byTurnSig.set(sig, []);
       byTurnSig.get(sig).push(c);
     }
+    const callIndex = new Map(calls.map((c, i) => [c, i]));
     for (const group of byTurnSig.values()) {
       if (group.length >= o.retryLoopMin) {
         const errs = group.filter((c) => c.isError).length;
+        if (isWait(group[0]) && errs < 2) continue; // polling a running task; failing polls still count
+        if (errs < 2) {
+          // Re-running a test or taking another screenshot after something changed is observing, not
+          // looping: only flag successful repeats that returned the same thing with nothing in between.
+          const inGroup = new Set(group);
+          const between = calls.slice(callIndex.get(group[0]) + 1, callIndex.get(group[group.length - 1]));
+          const changed = between.some((c) => c.agent === group[0].agent && !inGroup.has(c) && c.category !== 'read');
+          const same = group.every((c) => c.resultText === group[0].resultText && c.imageBytes === group[0].imageBytes);
+          if (changed || !same) continue;
+        }
         push({
           id: 'retry-loop', severity: errs >= 2 ? 'error' : 'warn',
           title: `${group[0].name} called ${group.length}× with identical input`,
@@ -520,14 +585,16 @@
       }
     }
 
-    // failed-tool: per tool error rate
+    // failed-tool: per tool error rate. Calls the human or a permission rule stopped are not the
+    // tool's failure (see permission-denied); one stray error in a long session is not a pattern.
     const byTool = new Map();
-    for (const c of calls) { if (c.unmatched) continue; if (!byTool.has(c.name)) byTool.set(c.name, []); byTool.get(c.name).push(c); }
+    for (const c of calls) { if (c.unmatched || c.denial) continue; if (!byTool.has(c.name)) byTool.set(c.name, []); byTool.get(c.name).push(c); }
     for (const [name, list] of byTool) {
       const errs = list.filter((c) => c.isError);
       if (!errs.length) continue;
       const rate = errs.length / list.length;
       const bad = list.length >= o.failedToolMinCalls && rate >= o.failedToolRate;
+      if (!bad && (errs.length < o.failedToolWarnMinErrors || rate < o.failedToolWarnRate)) continue;
       push({
         id: 'failed-tool', severity: bad ? 'error' : 'warn',
         title: `${name} failed ${errs.length} of ${list.length} calls (${Math.round(rate * 100)}%)`,
@@ -536,6 +603,18 @@
       });
     }
 
+    // permission-denied: calls that never ran because the human rejected them, a permission rule or
+    // the auto-mode classifier blocked them, or the human interrupted.
+    const denied = calls.filter((c) => c.denial);
+    if (denied.length) {
+      const kinds = {}; for (const c of denied) kinds[c.denial] = (kinds[c.denial] || 0) + 1;
+      push({
+        id: 'permission-denied', severity: 'info', title: `${denied.length} tool call${denied.length > 1 ? 's' : ''} denied or interrupted`,
+        detail: Object.entries(kinds).map(([k, n]) => `${k} ×${n}`).join(', ') + ' — ' + summariseNames(denied),
+        evidence: { toolCallIds: denied.map((c) => c.id) }, metric: denied.length,
+      });
+    }
+
     // orphan-tool
     const orphans = calls.filter((c) => c.status === 'orphan');
     if (orphans.length) push({
@@ -560,18 +639,52 @@
       };
       for (const c of calls) {
         if (c.agent !== ag.id || c.unmatched) continue;
-        if (c.category === 'read') run.push(c); else if (c.category === 'write' || c.category === 'exec') flush(); // agent/user/mcp calls don't break a run
+        // MCP calls that aren't reads are actions (browser navigate/click, device commands) and end a run;
+        // agent and user calls don't.
+        if (c.category === 'read') run.push(c); else if (c.category === 'write' || c.category === 'exec' || c.category === 'mcp') flush();
       }
       flush();
     }
 
-    // oversized-result
+    // duplicate-subagent-read: the same file read by several agents, each paying for it in its own context
+    const sharedReads = new Set(); // reported here, so oversized-result below skips them
+    const readsByFile = new Map();
     for (const c of calls) {
-      if (c.resultChars >= o.oversizedResultWarn) push({
+      if (c.name !== 'Read' || c.isError || !c.input || !c.input.file_path) continue;
+      const k = String(c.input.file_path).replace(/\\/g, '/').toLowerCase();
+      if (!readsByFile.has(k)) readsByFile.set(k, []);
+      readsByFile.get(k).push(c);
+    }
+    for (const list of readsByFile.values()) {
+      const agentIds = new Set(list.map((c) => c.agent));
+      if (agentIds.size < o.duplicateReadAgents) continue;
+      const chars = list.reduce((s, c) => s + c.resultChars, 0);
+      for (const c of list) sharedReads.add(c);
+      const largest = Math.max(...list.map((c) => c.resultChars));
+      push({
+        id: 'duplicate-subagent-read', severity: largest >= o.oversizedResultError ? 'error' : chars >= o.duplicateReadWarnChars ? 'warn' : 'info',
+        title: `Same file read by ${agentIds.size} agents (${fmtInt(chars)} chars)`, // path only in detail, which --redact blanks
+        detail: `${list.length} reads of ${list[0].input.file_path} across ${agentIds.size} agents; each copy is billed in that agent's context on every later request.`,
+        evidence: { toolCallIds: list.map((c) => c.id) }, metric: chars,
+      });
+    }
+
+    // oversized-result: one line per call, or one per tool when a tool does it repeatedly
+    const bigByTool = new Map();
+    for (const c of calls) if (c.resultChars >= o.oversizedResultWarn && !sharedReads.has(c)) { if (!bigByTool.has(c.name)) bigByTool.set(c.name, []); bigByTool.get(c.name).push(c); }
+    for (const [name, list] of bigByTool) {
+      const largest = Math.max(...list.map((c) => c.resultChars)), total = list.reduce((s, c) => s + c.resultChars, 0);
+      const ranged = list.every(hasRange);
+      const detail = 'Large tool results stay in context for the rest of the session. ' + (ranged ? 'The call already set a range; long lines or a wide window still cost, so narrow it or grep first.' : 'Consider head/limit, grep, or a subagent.');
+      if (list.length >= o.groupRepeatsMin) push({
+        id: 'oversized-result', severity: largest >= o.oversizedResultError ? 'error' : 'warn',
+        title: `${name} returned over ${fmtInt(o.oversizedResultWarn)} chars ${list.length} times (largest ${fmtInt(largest)}, ${fmtInt(total)} in all)`,
+        detail, evidence: { toolCallIds: list.map((c) => c.id) }, metric: largest,
+      });
+      else for (const c of list) push({
         id: 'oversized-result', severity: c.resultChars >= o.oversizedResultError ? 'error' : 'warn',
         title: `${c.name} returned ${fmtInt(c.resultChars)} chars`,
-        detail: 'Large tool results stay in context for the rest of the session. Consider head/limit, grep, or a subagent.',
-        evidence: { toolCallIds: [c.id], turnIndex: c.turnIndex }, metric: c.resultChars,
+        detail, evidence: { toolCallIds: [c.id], turnIndex: c.turnIndex }, metric: c.resultChars,
       });
     }
 
@@ -591,21 +704,45 @@
       if (r.contextTokens >= o.contextBloatWarn && !crossed) crossed = r;
       if (!peak || r.contextTokens > peak.contextTokens) peak = r;
     }
-    if (crossed) push({
-      id: 'context-bloat', severity: peak.contextTokens >= o.contextBloatError ? 'error' : 'warn',
-      title: `Context reached ${fmtInt(peak.contextTokens)} tokens`,
-      detail: `First crossed ${fmtInt(o.contextBloatWarn)} at request #${reqs.indexOf(crossed) + 1} (turn ${crossed.turnIndex + 1}). Every later request pays for that prefix.`,
-      evidence: { requestIds: [crossed.id, peak.id], turnIndex: crossed.turnIndex }, metric: peak.contextTokens,
-    });
+    if (crossed) {
+      // What the large context cost: every request (any agent) sent with more than the threshold.
+      let above = 0, all = 0, n = 0;
+      for (const r of reqs) { const c = requestCost(r.usage, rateFor(r.model, o.rates)); if (c == null) continue; all += c; if (r.contextTokens >= o.contextBloatWarn) { above += c; n++; } }
+      const spend = all > 0 ? ` · ${usd(above)} (${Math.round(above / all * 100)}% of cost) spent above ${fmtInt(o.contextBloatWarn)}` : '';
+      push({
+        id: 'context-bloat', severity: peak.contextTokens >= o.contextBloatError ? 'error' : 'warn',
+        title: `Context reached ${fmtInt(peak.contextTokens)} tokens${spend}`,
+        detail: `First crossed ${fmtInt(o.contextBloatWarn)} at request #${reqs.indexOf(crossed) + 1} (turn ${crossed.turnIndex + 1}); ${n} request${n === 1 ? '' : 's'} ran above it. Every one of them re-reads that prefix.`,
+        evidence: { requestIds: [crossed.id, peak.id], turnIndex: crossed.turnIndex }, metric: peak.contextTokens, cost: all > 0 ? above : null,
+      });
+    }
 
-    // cache-churn
-    const firstReqOfAgent = new Set();
+    // cache-churn / idle-cache-expiry: a request that re-wrote prefix the previous request of the same
+    // agent had already cached. A big cache write on its own is usually just a new tool result being
+    // cached, which is expected. After a gap longer than the cache lifetime the miss is expiry, not
+    // invalidation; right after a compaction it is an expected rebuild.
+    const prevByAgent = new Map(); const ttlByAgent = new Map();
     for (const r of reqs) {
-      if (!firstReqOfAgent.has(r.agent)) { firstReqOfAgent.add(r.agent); continue; }
-      if (r.usage.cacheWrite >= o.cacheChurnMin) push({
-        id: 'cache-churn', severity: 'info', title: `${fmtInt(r.usage.cacheWrite)} tokens re-cached at request #${reqs.indexOf(r) + 1}`,
-        detail: 'A large cache write mid-session means the cached prefix was invalidated (system prompt, tool list or early messages changed).',
-        evidence: { requestIds: [r.id], turnIndex: r.turnIndex }, metric: r.usage.cacheWrite,
+      const prev = prevByAgent.get(r.agent); prevByAgent.set(r.agent, r);
+      if (r.usage.cacheWrite1h > 0) ttlByAgent.set(r.agent, 3600e3); else if (r.usage.cacheWrite5m > 0 && !ttlByAgent.has(r.agent)) ttlByAgent.set(r.agent, 300e3);
+      if (!prev) continue;
+      const cached = prev.usage.cacheRead + prev.usage.cacheWrite;
+      const missed = cached - r.usage.cacheRead;
+      if (missed < o.cacheChurnMin || missed < cached * o.cacheMissMinShare) continue;
+      const sent = r.responseFrom != null ? r.responseFrom : r.start;
+      if (prev.end != null && sent != null && trace.events.some((e) => e.kind === 'compact' && e.at != null && e.at >= prev.end && e.at <= sent)) continue;
+      const idle = prev.end != null && sent != null ? sent - prev.end : null;
+      const ttl = ttlByAgent.get(r.agent) || 300e3;
+      const n = reqs.indexOf(r) + 1;
+      if (idle != null && idle > ttl) push({
+        id: 'idle-cache-expiry', severity: 'info', title: `${fmtInt(missed)} tokens re-cached after ${fmtDur(idle)} idle`,
+        detail: `Request #${n}${r.agent !== 'main' ? ' (subagent)' : ''}: the gap was longer than the ${ttl >= 3600e3 ? '1-hour' : '5-minute'} cache lifetime, so the whole prefix was written again.`,
+        evidence: { requestIds: [prev.id, r.id], turnIndex: r.turnIndex }, metric: missed,
+      });
+      else push({
+        id: 'cache-churn', severity: 'info', title: `${fmtInt(missed)} cached tokens re-written at request #${n}`,
+        detail: `The previous request had ${fmtInt(cached)} tokens cached; this one read only ${fmtInt(r.usage.cacheRead)} back${idle != null ? ` ${fmtDur(idle)} later` : ''}. Something early in the prompt changed (system prompt, tool list, early messages).`,
+        evidence: { requestIds: [prev.id, r.id], turnIndex: r.turnIndex }, metric: missed,
       });
     }
 
@@ -616,14 +753,40 @@
       evidence: {}, metric: trace.totals.cacheHitRatio,
     });
 
-    // slow-tool
+    // slow-tool: blocking waits roll up per background task, other slow calls per tool when repeated
+    const waits = new Map(), slowByTool = new Map();
     for (const c of calls) {
-      if (c.durationMs != null && c.durationMs >= o.slowToolInfoMs) push({
+      if (isWait(c)) { const k = c.agent + '|' + c.name + '|' + waitTarget(c); if (!waits.has(k)) waits.set(k, []); waits.get(k).push(c); continue; }
+      // Time spent on a question to the human, or on a permission prompt that ended in a denial, is the human's.
+      if (c.category === 'user' || c.denial) continue;
+      if (c.durationMs != null && c.durationMs >= o.slowToolInfoMs) { if (!slowByTool.has(c.name)) slowByTool.set(c.name, []); slowByTool.get(c.name).push(c); }
+    }
+    for (const [name, list] of slowByTool) {
+      const longest = Math.max(...list.map((c) => c.durationMs)), total = list.reduce((s, c) => s + c.durationMs, 0);
+      const detail = list[0].category === 'agent' ? 'Subagent run time.' : 'Long-running tool call.';
+      if (list.length >= o.groupRepeatsMin) push({
+        id: 'slow-tool', severity: longest >= o.slowToolWarnMs ? 'warn' : 'info',
+        title: `${name} took over ${fmtDur(o.slowToolInfoMs)} ${list.length} times (longest ${fmtDur(longest)}, ${fmtDur(total)} in all)`,
+        detail, evidence: { toolCallIds: list.map((c) => c.id) }, metric: total,
+      });
+      else for (const c of list) push({
         id: 'slow-tool', severity: c.durationMs >= o.slowToolWarnMs ? 'warn' : 'info',
-        title: `${c.name} took ${fmtDur(c.durationMs)}`, detail: c.category === 'agent' ? 'Subagent run time.' : c.category === 'user' ? 'Waiting on the human.' : 'Long-running tool call.',
+        title: `${c.name} took ${fmtDur(c.durationMs)}`, detail,
         evidence: { toolCallIds: [c.id], turnIndex: c.turnIndex }, metric: c.durationMs,
       });
     }
+    // One finding per waited-on task, always info: the time belongs to the background job.
+    for (const group of waits.values()) {
+      const ms = group.reduce((s, c) => s + (c.durationMs || 0), 0);
+      if (ms < o.slowToolInfoMs) continue;
+      const target = waitTarget(group[0]);
+      push({
+        id: 'slow-tool', severity: 'info',
+        title: `${group[0].name} waited ${fmtDur(ms)} on ${target ? 'task ' + target : 'a background task'}${group.length > 1 ? ` (${group.length} polls)` : ''}`,
+        detail: 'Blocking wait on background work: the time is the task\'s run time, not a slow tool.',
+        evidence: { toolCallIds: group.map((c) => c.id), turnIndex: group[0].turnIndex }, metric: ms,
+      });
+    }
 
     // slow-model: a long response that produced little — API latency, rate limiting or a stall,
     // as opposed to a long response that was simply writing a lot (reported separately as info).
@@ -636,9 +799,10 @@
           detail: `Request #${n} (${r.tokensPerSec != null ? r.tokensPerSec.toFixed(1) : '?'} tok/s): API latency, rate limiting or a stalled stream.`,
           evidence: { requestIds: [r.id], turnIndex: r.turnIndex }, metric: r.responseMs,
         });
-        else push({
-          id: 'long-generation', severity: 'info', title: `${fmtDur(r.responseMs)} writing ${fmtInt(r.usage.output)} tokens`,
-          detail: `Request #${n} at ${r.tokensPerSec != null ? r.tokensPerSec.toFixed(1) : '?'} tok/s (${r.blocksSummary}). Big single outputs are normal for file writes; a stall would show as low tok/s.`,
+        // A long response that wrote a lot at a normal rate is just a big output. Only a slow rate is worth a line.
+        else if (r.tokensPerSec != null && r.tokensPerSec < o.longGenerationMaxTokPerSec) push({
+          id: 'long-generation', severity: 'info', title: `${fmtDur(r.responseMs)} writing ${fmtInt(r.usage.output)} tokens (${r.tokensPerSec.toFixed(1)} tok/s)`,
+          detail: `Request #${n} (${r.blocksSummary}) streamed well below the usual rate: a partial stall or a slow API period.`,
           evidence: { requestIds: [r.id], turnIndex: r.turnIndex }, metric: r.responseMs,
         });
       }
@@ -670,10 +834,18 @@
       detail: 'Most of the spend happened in delegated work.', evidence: {}, metric: subTokens / allTokens,
     });
 
-    // long-turn
-    for (const tn of trace.turns) if (tn.toolCallIds.length >= o.longTurnTools) push({
-      id: 'long-turn', severity: 'info', title: `Turn ${tn.index + 1} made ${tn.toolCallIds.length} tool calls`,
-      detail: 'A very long autonomous stretch. Worth a skim for wasted work.', evidence: { turnIndex: tn.index, toolCallIds: tn.toolCallIds.slice() }, metric: tn.toolCallIds.length,
+    // long-turn: main conversation only (a subagent's whole run is one turn by design), numbered like
+    // the viewer's T1, T2… (human prompts).
+    // Meta turns (injected reminders, interrupts) between two prompts belong to the stretch before them.
+    const stretches = [];
+    for (const tn of trace.turns) {
+      if (tn.agent !== 'main') continue;
+      if (tn.promptKind === 'human' || !stretches.length) stretches.push({ first: tn, no: stretches.length + 1, ids: [] });
+      stretches[stretches.length - 1].ids.push(...tn.toolCallIds);
+    }
+    for (const st of stretches) if (st.ids.length >= o.longTurnTools) push({
+      id: 'long-turn', severity: 'info', title: `Turn ${st.no} made ${st.ids.length} tool calls`,
+      detail: 'A very long autonomous stretch. Worth a skim for wasted work.', evidence: { turnIndex: st.first.index, toolCallIds: st.ids }, metric: st.ids.length,
     });
 
     const order = { error: 0, warn: 1, info: 2 };
@@ -736,6 +908,210 @@
     };
   }
 
+  // ---------------------------------------------------------------------------
+  // Advice — one sentence per rule on what to do differently. Mechanical, like the rules.
+  // ---------------------------------------------------------------------------
+  const ADVICE = {
+    'retry-loop': 'When a call fails, change something before calling again: read the error, fix the input or the environment, or ask the user — never repeat an identical call.',
+    'failed-tool': 'Check the first error message of the failing tool before retrying; if the tool itself is broken, switch tools or tell the user instead of pushing on.',
+    'orphan-tool': 'A call with no result means the session ended mid-call; if you resume, re-run it or confirm its side effects before building on it.',
+    'exploration-run': 'Batch exploration: use one Grep or Glob with a wider pattern, or delegate a broad search to a subagent, then commit to an edit or command sooner.',
+    'oversized-result': 'Ask tools for less: head/limit/offset on reads, a tighter grep pattern, a file listing instead of a dump, or a subagent that returns a summary.',
+    'image-heavy': 'Take fewer screenshots and crop or downscale them; read text with a page-text tool where one exists, since every image is re-billed on each later request.',
+    'context-bloat': 'Keep the prompt small: summarise long results into notes, avoid re-reading files already in context, and hand large investigations to subagents.',
+    'cache-churn': 'Avoid changing anything at the top of the prompt mid-session (system prompt, tool list, early messages), because it invalidates the cached prefix and re-bills it.',
+    'low-cache-hit': 'Long stable prefixes cache well; frequent tool-list or system-prompt changes and many tiny sessions do not.',
+    'slow-tool': 'For calls that take minutes, run them in the background, tighten the command, or set a timeout, instead of blocking the whole turn.',
+    'slow-model': 'A slow, small response is usually API latency or a stall; nothing to fix in the session itself, but note it when reporting session time.',
+    'long-generation': 'Large single outputs are normal for file writes; split very large files into parts if a stall (low tok/s) shows up.',
+    'max-tokens': 'The output was truncated: write large files in sections and keep single responses under the output limit.',
+    'api-error': 'An API error interrupted the session; check what was lost and re-run the affected step rather than assuming it completed.',
+    'hook-error': 'A hook failed; read the hook error, fix the hook command or its permissions, then re-run the step it guarded.',
+    'compaction': 'Context was compacted; state that matters later (decisions, file paths, test status) should be written to a file or note before it is summarised away.',
+    'thinking-heavy': 'Most output tokens were thinking; fine for hard problems, but for routine tool loops a lower effort setting is cheaper and just as good.',
+    'subagent-share': 'Most spend was in subagents; give them narrower briefs and ask for short structured returns so the parent pays for less.',
+    'long-turn': 'A very long autonomous turn; check in with a short progress summary at natural checkpoints so wasted work is caught earlier.',
+    'permission-denied': 'Before a call the user may not want (installs, network, deleting, publishing), say what it will do and ask; for calls they always allow, suggest a permissions allow rule so the prompt goes away.',
+    'duplicate-subagent-read': 'When several subagents need the same file, put the relevant excerpt in their briefs or have one agent summarise it once, instead of every agent reading it into its own context.',
+    'idle-cache-expiry': 'The cache expired while the session sat idle; resume sooner, use the 1-hour cache lifetime where available, or start a fresh session with a summary instead of re-sending the whole history.',
+  };
+
+  // Advice for a concrete finding: the rule's line, except where the evidence says otherwise.
+  function adviceFor(f, trace) {
+    if (f.id === 'slow-tool') {
+      const ids = (f.evidence && f.evidence.toolCallIds) || [];
+      const c = trace.toolCalls.find((x) => x.id === ids[0]);
+      if (c && c.category === 'user') return null; // waiting on the human is not the agent's time
+      if (c && c.category === 'agent') return 'Subagent run time: give it a narrower brief and ask for a short structured return so the parent is not blocked for as long.';
+      if (c && isWait(c)) return 'Waiting on a long background task: keep doing independent work while it runs, or tell the user it is still going, instead of blocking the turn on it.';
+    }
+    if (f.id === 'oversized-result') {
+      const c = trace.toolCalls.find((x) => x.id === ((f.evidence && f.evidence.toolCallIds) || [])[0]);
+      if (c && hasRange(c)) return 'The read already had a range and still returned a lot: grep for the part you need first, or read a narrower window.';
+    }
+    return ADVICE[f.id] || null;
+  }
+
+  function inputSummary(c) {
+    const i = (c && c.input) || {};
+    if (i.command) return String(i.command);
+    if (i.file_path) return String(i.file_path) + (i.pattern ? ' ' + i.pattern : '');
+    if (i.pattern) return String(i.pattern);
+    if (i.query) return String(i.query);
+    if (i.description) return String(i.description);
+    if (i.url) return String(i.url);
+    if (i.prompt) return String(i.prompt);
+    if (i.path) return String(i.path);
+    const s = JSON.stringify(i);
+    return s === '{}' ? '' : s;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Markdown report — written to be handed back to the agent as well as read by a human.
+  // opts: { redact, advice=true, instruction=true, maxEvidence=6, title }
+  // ---------------------------------------------------------------------------
+  function usd(v) { return v == null ? '—' : v < 0.01 ? '$' + v.toFixed(4) : v < 1 ? '$' + v.toFixed(3) : '$' + v.toFixed(2); }
+  function pctStr(x) { return x == null ? '—' : Math.round(x * 100) + '%'; }
+  function oneLine(s, n) { s = String(s == null ? '' : s).replace(/\s+/g, ' ').trim(); return s.length > n ? s.slice(0, n - 1) + '…' : s; }
+  function blank(s) { return '«' + String(s == null ? '' : s).length + ' chars»'; }
+
+  function toolTable(trace) {
+    const rows = new Map();
+    for (const c of trace.toolCalls) { if (c.unmatched) continue; if (!rows.has(c.name)) rows.set(c.name, { name: c.name, calls: 0, errors: 0, time: 0 }); const r = rows.get(c.name); r.calls++; if (c.isError) r.errors++; r.time += c.durationMs || 0; }
+    return Array.from(rows.values()).sort((a, b) => b.time - a.time || b.calls - a.calls);
+  }
+
+  // Rules whose detail quotes tool output or model text (everything else is names and numbers).
+  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; }
+
+  function reportMarkdown(trace, findings, cost, opts) {
+    opts = opts || {};
+    const redact = !!opts.redact, maxEv = opts.maxEvidence || 6;
+    const T = trace.totals, m = trace.meta, u = T.usage;
+    const R = (s) => redact ? blank(s) : s;
+    const total = cost ? (cost.reported != null ? cost.reported : cost.total) : null;
+    const turnNo = (idx) => idx != null ? idx + 1 : null; // same numbering as the finding details and the viewer drawer
+    const advised = new Set();
+    const out = [];
+    out.push(`# Glassbox report — ${oneLine(R(m.title || opts.title || 'session'), 90)}`, '');
+    out.push(`- session: ${m.sessionId || '—'} · model: ${m.models.join(', ') || '—'}${m.start ? ' · started: ' + new Date(m.start).toISOString() : ''}`);
+    out.push(`- wall ${fmtDur(T.wallMs)} (active ${fmtDur(T.activeMs)}) · ${T.turns} turn${T.turns === 1 ? '' : 's'} · ${T.requests} requests · ${T.toolCalls} tool calls (${T.toolErrors} failed${T.orphans ? ', ' + T.orphans + ' unanswered' : ''})`);
+    out.push(`- tokens: ${fmtInt(u.input + u.cacheRead + u.cacheWrite)} context served (${pctStr(T.cacheHitRatio)} cached) · peak prompt ${fmtInt(Math.max(0, ...trace.requests.map((r) => r.contextTokens)))} · ${fmtInt(u.output)} output (${fmtInt(u.thinking)} thinking) · est. cost ${usd(total)}${cost && cost.source === 'reported' ? ' (reported)' : ''}`, '');
+    if (!findings.length) out.push('## Findings', '', 'Nothing flagged — a clean session, or a very short one.', '');
+    else {
+      out.push(`## Findings (${findings.length})`, '');
+      findings.forEach((f, i) => {
+        out.push(`### ${i + 1}. ${f.severity.toUpperCase()} \`${f.id}\` — ${f.title}`, '', redact ? redactDetail(f) : f.detail, '');
+        const ev = f.evidence || {};
+        const lines = [];
+        for (const id of ev.toolCallIds || []) { const c = trace.toolCalls.find((x) => x.id === id); if (!c) continue; const tn = turnNo(c.turnIndex); lines.push(`- ${c.name}${c.isError ? ' (error)' : ''}${c.durationMs != null ? ' · ' + fmtDur(c.durationMs) : ''}${tn != null ? ' · turn ' + tn : ''}${c.agent !== 'main' ? ' · subagent' : ''}: \`${oneLine(R(inputSummary(c)), 100).replace(/`/g, "'") || '(no input)'}\``); }
+        for (const id of ev.requestIds || []) { const r = trace.requests.find((x) => x.id === id); if (!r) continue; const n = trace.requests.indexOf(r) + 1; const tn = turnNo(r.turnIndex); lines.push(`- request #${n}${tn != null ? ' · turn ' + tn : ''}: context ${fmtInt(r.contextTokens)} · output ${fmtInt(r.usage.output)}${r.responseMs != null ? ' · ' + fmtDur(r.responseMs) : ''}`); }
+        if (lines.length) { out.push('Evidence:', ''); out.push(...lines.slice(0, maxEv)); if (lines.length > maxEv) out.push(`- … ${lines.length - maxEv} more`); out.push(''); }
+        const adv = opts.advice !== false && !advised.has(f.id) ? adviceFor(f, trace) : null;
+        if (adv) { advised.add(f.id); out.push(`Next time: ${adv}`, ''); }
+      });
+    }
+    const tools = toolTable(trace);
+    if (tools.length) { out.push('## Tools', '', '| tool | calls | errors | total time |', '|---|---|---|---|'); for (const r of tools) out.push(`| ${r.name} | ${r.calls} | ${r.errors} | ${fmtDur(r.time)} |`); out.push(''); }
+    if (opts.instruction !== false) out.push('## What to do with this', '', 'This is a mechanical review of the session transcript, generated by Glassbox (no AI involved). If you are the agent that ran this session: acknowledge the findings that apply, say in one or two sentences what you will do differently next session, and do not redo any work. If you are a human: the evidence lines are permalinks into the Glassbox viewer for this session.', '');
+    out.push('_Generated by Glassbox ' + VERSION + '._', '');
+    return out.join('\n');
+  }
+
+  // ---------------------------------------------------------------------------
+  // Compare two analysed sessions ({trace, findings, cost}).
+  // ---------------------------------------------------------------------------
+  const METRICS = [
+    { key: 'wallMs', label: 'Wall time', fmt: 'dur', dir: 'low', get: (s) => s.trace.totals.wallMs },
+    { key: 'activeMs', label: 'Active time', fmt: 'dur', dir: 'low', get: (s) => s.trace.totals.activeMs },
+    { key: 'turns', label: 'Turns', fmt: 'int', dir: null, get: (s) => s.trace.totals.turns },
+    { key: 'requests', label: 'API requests', fmt: 'int', dir: 'low', get: (s) => s.trace.totals.requests },
+    { key: 'toolCalls', label: 'Tool calls', fmt: 'int', dir: 'low', get: (s) => s.trace.totals.toolCalls },
+    { key: 'toolErrors', label: 'Tool errors', fmt: 'int', dir: 'low', get: (s) => s.trace.totals.toolErrors },
+    { key: 'toolTimeMs', label: 'Time in tools', fmt: 'dur', dir: 'low', get: (s) => s.trace.meta.hasTimestamps ? s.trace.totals.toolTimeMs : null },
+    { key: 'modelTimeMs', label: 'Time generating', fmt: 'dur', dir: 'low', get: (s) => s.trace.meta.hasTimestamps ? s.trace.totals.modelTimeMs : null },
+    { key: 'contextServed', label: 'Context served', fmt: 'tok', dir: 'low', get: (s) => { const u = s.trace.totals.usage; const v = u.input + u.cacheRead + u.cacheWrite; return v || (s.trace.requests.length ? 0 : null); } },
+    { key: 'peakContext', label: 'Peak prompt', fmt: 'tok', dir: 'low', get: (s) => s.trace.requests.length ? Math.max(0, ...s.trace.requests.map((r) => r.contextTokens)) : null },
+    { key: 'cacheHitRatio', label: 'Cache hit', fmt: 'pct', dir: 'high', get: (s) => s.trace.totals.cacheHitRatio },
+    { key: 'output', label: 'Output tokens', fmt: 'tok', dir: 'low', get: (s) => s.trace.requests.length ? s.trace.totals.usage.output : null },
+    { key: 'thinkingShare', label: 'Thinking share', fmt: 'pct', dir: null, get: (s) => { const u = s.trace.totals.usage; return u.output ? u.thinking / u.output : null; } },
+    { key: 'cost', label: 'Est. cost', fmt: 'usd', dir: 'low', get: (s) => s.cost ? (s.cost.reported != null ? s.cost.reported : s.cost.total) : null },
+    { key: 'findings', label: 'Findings', fmt: 'int', dir: 'low', get: (s) => s.findings.length },
+    { key: 'errorFindings', label: 'Error-level findings', fmt: 'int', dir: 'low', get: (s) => s.findings.filter((f) => f.severity === 'error').length },
+  ];
+  function fmtMetric(v, fmt) {
+    if (v == null) return '—';
+    if (fmt === 'dur') return fmtDur(v);
+    if (fmt === 'pct') return pctStr(v);
+    if (fmt === 'usd') return usd(v);
+    return fmtInt(v);
+  }
+  // "×2.4" when B is bigger, "÷2.4" when smaller; never "×0.00".
+  function fmtRatio(r) {
+    if (r == null || !Number.isFinite(r)) return '—';
+    if (r === 1) return '×1.00';
+    const v = r >= 1 ? r : 1 / r; const t = v >= 100 ? Math.round(v).toString() : v >= 10 ? v.toFixed(1) : v.toFixed(2);
+    return (r >= 1 ? '×' : '÷') + t;
+  }
+  // Change of B relative to A: a signed percentage where that reads well, ×N for big increases,
+  // the absolute delta when A is 0 (no ratio) or B is 0 (no "÷∞").
+  function fmtChange(m) {
+    if (m.delta == null) return '—';
+    const r = m.ratio;
+    if (r == null || !m.a || !m.b) return (m.delta > 0 ? '+' : m.delta < 0 ? '−' : '') + fmtMetric(Math.abs(m.delta), m.fmt);
+    if (r === 1) return '0%';
+    if (r < 1) { const p = (1 - r) * 100; return '−' + (p < 10 || p > 99 ? p.toFixed(1) : Math.round(p)) + '%'; }
+    if (r < 10) { const p = (r - 1) * 100; return '+' + (p < 10 ? p.toFixed(1) : Math.round(p)) + '%'; }
+    return fmtRatio(r);
+  }
+  function compare(A, B) {
+    const metrics = METRICS.map((d) => {
+      const a = d.get(A), b = d.get(B);
+      const ok = a != null && b != null && Number.isFinite(a) && Number.isFinite(b);
+      const delta = ok ? b - a : null;
+      const ratio = ok && a ? b / a : (ok && !a && !b ? 1 : null);
+      let better = null;
+      if (ok && d.dir && a !== b) better = (d.dir === 'low') === (a < b) ? 'a' : 'b';
+      return { key: d.key, label: d.label, fmt: d.fmt, dir: d.dir, a, b, delta, ratio, better, aText: fmtMetric(a, d.fmt), bText: fmtMetric(b, d.fmt) };
+    });
+    const ta = toolTable(A.trace), tb = toolTable(B.trace);
+    const names = new Set([...ta.map((t) => t.name), ...tb.map((t) => t.name)]);
+    const zero = { calls: 0, errors: 0, time: 0 };
+    const tools = Array.from(names).map((name) => { const a = ta.find((t) => t.name === name) || zero, b = tb.find((t) => t.name === name) || zero; return { name, a: { calls: a.calls, errors: a.errors, time: a.time }, b: { calls: b.calls, errors: b.errors, time: b.time }, deltaCalls: b.calls - a.calls, deltaTime: b.time - a.time }; });
+    tools.sort((x, y) => Math.abs(y.deltaCalls) - Math.abs(x.deltaCalls) || (y.a.calls + y.b.calls) - (x.a.calls + x.b.calls) || x.name.localeCompare(y.name));
+    const byId = (fs) => { const m = new Map(); for (const f of fs) { if (!m.has(f.id)) m.set(f.id, []); m.get(f.id).push(f); } return m; };
+    const fa = byId(A.findings), fb = byId(B.findings);
+    const slim = (f) => ({ id: f.id, severity: f.severity, title: f.title });
+    const onlyA = [], onlyB = [], both = [];
+    for (const [id, list] of fa) { if (fb.has(id)) both.push({ id, a: list.map(slim), b: fb.get(id).map(slim) }); else onlyA.push(...list.map(slim)); }
+    for (const [id, list] of fb) if (!fa.has(id)) onlyB.push(...list.map(slim));
+    const pick = (key) => { const m = metrics.find((x) => x.key === key); return m ? m.better : null; };
+    const cleaner = (() => { const ea = A.findings.filter((f) => f.severity === 'error').length, eb = B.findings.filter((f) => f.severity === 'error').length; if (ea !== eb) return ea < eb ? 'a' : 'b'; const wa = A.findings.length, wb = B.findings.length; return wa === wb ? null : (wa < wb ? 'a' : 'b'); })();
+    const verdict = { cheaper: pick('cost'), faster: pick('wallMs') || pick('activeMs'), cleaner };
+    return { metrics, tools, findings: { onlyA, onlyB, both }, verdict, a: { sessionId: A.trace.meta.sessionId, title: A.trace.meta.title, models: A.trace.meta.models }, b: { sessionId: B.trace.meta.sessionId, title: B.trace.meta.title, models: B.trace.meta.models } };
+  }
+  function compareMarkdown(c, opts) {
+    opts = opts || {};
+    const la = opts.labelA || 'A', lb = opts.labelB || 'B';
+    const out = [`# Glassbox compare — ${la} vs ${lb}`, ''];
+    out.push(`- ${la}: ${c.a.sessionId || '—'}${c.a.title ? ' · ' + oneLine(c.a.title, 70) : ''}${c.a.models.length ? ' · ' + c.a.models.join(', ') : ''}`);
+    out.push(`- ${lb}: ${c.b.sessionId || '—'}${c.b.title ? ' · ' + oneLine(c.b.title, 70) : ''}${c.b.models.length ? ' · ' + c.b.models.join(', ') : ''}`, '');
+    const v = c.verdict; const who = (x) => x === 'a' ? la : x === 'b' ? lb : 'tie';
+    out.push(`**Verdict** — cheaper: ${who(v.cheaper)} · faster: ${who(v.faster)} · cleaner: ${who(v.cleaner)}`, '');
+    out.push(`| metric | ${la} | ${lb} | change |`, '|---|---|---|---|');
+    for (const m of c.metrics) { const ch = fmtChange(m); out.push(`| ${m.label} | ${m.aText} | ${m.bText} | ${ch}${m.better ? ' (' + who(m.better) + ' better)' : ''} |`); }
+    out.push('');
+    if (c.tools.length) { out.push('## Tools', '', `| tool | ${la} calls (errors) | ${lb} calls (errors) | Δ calls |`, '|---|---|---|---|'); for (const t of c.tools) out.push(`| ${t.name} | ${t.a.calls} (${t.a.errors}) | ${t.b.calls} (${t.b.errors}) | ${t.deltaCalls > 0 ? '+' : ''}${t.deltaCalls} |`); out.push(''); }
+    out.push('## Findings', '');
+    if (!c.findings.onlyA.length && !c.findings.onlyB.length && !c.findings.both.length) out.push('Neither session was flagged.', '');
+    if (c.findings.onlyA.length) { out.push(`Only in ${la}:`, ''); for (const f of c.findings.onlyA) out.push(`- **${f.severity.toUpperCase()}** \`${f.id}\` — ${f.title}`); out.push(''); }
+    if (c.findings.onlyB.length) { out.push(`Only in ${lb}:`, ''); for (const f of c.findings.onlyB) out.push(`- **${f.severity.toUpperCase()}** \`${f.id}\` — ${f.title}`); out.push(''); }
+    if (c.findings.both.length) { out.push('In both:', ''); for (const f of c.findings.both) out.push(`- \`${f.id}\` — ${la}: ${f.a.length}, ${lb}: ${f.b.length}`); out.push(''); }
+    out.push('_Generated by Glassbox ' + VERSION + '._', '');
+    return out.join('\n');
+  }
+
   // ---------------------------------------------------------------------------
   // Redaction — keep structure, timestamps, usage, tool names; blank every string.
   // ---------------------------------------------------------------------------
@@ -764,5 +1140,5 @@
   }
   function toJsonl(records) { return records.map((r) => JSON.stringify(r)).join('\n') + '\n'; }
 
-  return { VERSION, RATES, DEFAULTS, parseLines, parseTrace, diagnose, estimateCost, rateFor, redact, toJsonl, toolCategory, textOf, fmtDur, fmtInt, stableStringify };
+  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 };
 });