@ngockhoale/ukit 3.4.23 → 3.4.25

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.25 - 2026-10-08
+
+**P0 hotfix: Stop hook no longer force-continues a run the user paused or cancelled.**
+- `stop-coordinator`: a genuine user pause/cancel turn ("pause", "cancel", "tạm dừng", "dừng lại", ...) now outranks every Stop lane (completion gate, task watchdog, handoff cursor). The stop is released with a visible note and run state (RUN.md, tasks, branches, worktrees) is left untouched. The signal is read only from real user turns in the host transcript, never from agent text, tool output, sub-agent reports or hook feedback; a later resume turn wins; an unreadable or over-budget scan means "no interruption", so enforcement is never relaxed by a lost read.
+- Handoff cursor reentrancy valve: when `stop_hook_active` is set and the same cursor signature repeats, the stop is released once with an advisory instead of waiting for the stalled-block cap. A cursor that moved keeps blocking.
+- Regression tests: `tests/hooks/stopHookInterruption.test.js` (15 cases).
+- Documentation registry: `docs/analysis/SUBAGENT-COST-AUDIT.md` (C99) is now classified in `manifests/documentation.yaml`; 3.4.24's consistency suite flagged it as an unregistered/orphan doc.
+- Not included: no change to evidence/ledger accounting or model routing.
+
+## 3.4.24 - 2026-10-08
+
+**Honest per-category token usage record + report** (C98; capability only — no producer exists yet, so real stores report `no_data`).
+- Schema v1.3 (additive): `model.completed`/`model.failed` payloads may now carry `usage_categories` — the five typed `{value, source}` resources `fresh_input_tokens`, `cache_read_tokens`, `cache_write_tokens`, `output_tokens`, `reasoning_tokens`. Absent categories stay `UNKNOWN`/null — never 0, never estimated. The registry stays append-only; old records remain valid.
+- `routeAdapter` maps provider-reported categories when a producer supplies `usage.categories`; numeric values are accepted only from `PROVIDER` sources, and the legacy aggregate-token mapping is byte-unchanged.
+- New read-only `ukit telemetry usage [--json]`: scans the segment store non-destructively (corrupt segments are skipped and reported, never quarantined by a read), prints a readiness verdict `no_data | aggregate_only | categorized`, per-source totals only (never combined), record counts (not unique runs), and labels `cache.hit/miss` as UKit-internal lookups, not a provider prompt cache. Exit codes: 0 normal, 1 usage error, 2 typed store failure. Creates no files.
+- `readSegments(..., {readOnly: true})` new option: default quarantine behavior is byte-for-byte unchanged.
+- Privacy: the five category keys + `usage_categories` joined the support-projection allowlist and `REDACTION_VERSION` bumped to `df-redact-7` (existing support bundles invalidate once). Counts and source tags only — never content.
+- Not included: a producer that actually records provider token categories (queued Q-C98-1/Q-C98-2 — needs evidence the host exposes usage), any cost/price model or provider identity fields (Q-C98-3). No token-savings or cost claims are made or implied.
+
 ## 3.4.23 - 2026-10-08
 
 **Core hook/gate reliability repairs** (C97; each backed by baseline RED, GREEN and independent different-model review).

package/manifests/documentation.yaml

@@ -405,6 +405,17 @@ entries:
     load_policy: never
     validation: [none]
     archive_policy: immutable
+  - id: docs-analysis-subagent-cost-audit
+    path: docs/analysis/SUBAGENT-COST-AUDIT.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/SUBAGENT-COST-AUDIT.md
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
+    notes: C99 measurement-only sub-agent cost audit snapshot; registered in 3.4.25 (was unclassified on 3.4.24)
   - id: docs-skill-audits
     path: docs/skill-audits/
     class: archive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.23",
+  "version": "3.4.25",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/scripts/audit/subagent-cost/analyze.mjs

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadCorpus } from './reader.mjs';
+import { computeMetrics } from './metrics.mjs';
+import { computeDuplicates } from './duplicates.mjs';
+import { renderMarkdown } from './render.mjs';
+
+const MISSING = [
+  'Provider/gateway id is not recorded in transcript usage.',
+  'Native request latency is unavailable; timestamp gaps are only approximate.',
+  'Retry counts are not recorded as a distinct telemetry field.',
+  'Per-sub-agent request-shape cost is unavailable.',
+  'Price table is absent; currency cost cannot be calculated.',
+  'Codex and omp transcripts are not included by this Claude Code reader.',
+  'Observability token categories are unavailable.',
+];
+
+export async function buildReport(root, opts = {}) {
+  const corpus = await loadCorpus(root, { since: opts.since ?? null, until: opts.until ?? null });
+  // Wave-1 reader predates the normalized call.depth field; derive it without
+  // changing that shared module, while honoring depth when it is already present.
+  const depthByAgent = new Map(corpus.agents.map((agent) => [`${agent.sessionId}\u0000${agent.agentId}`, agent.depth]));
+  for (const call of corpus.calls) {
+    if (call.depth == null) call.depth = call.agentId == null ? 0 : (depthByAgent.get(`${call.sessionId}\u0000${call.agentId}`) ?? 1);
+  }
+  const metrics = computeMetrics(corpus);
+  const duplicates = computeDuplicates(corpus);
+  const headline = {
+    subShare: metrics.share.subOfInputSide,
+    subUncachedShare: metrics.share.subOfUncached,
+    contextAmplification: duplicates.amplification,
+    duplicateContextRatio: duplicates.duplicateRatio,
+    avgCallsPerTask: metrics.perTask.avgCalls,
+  };
+  return {
+    schema: 'subagent-cost/v1',
+    generatedAt: new Date().toISOString(),
+    root: path.basename(path.resolve(root)),
+    window: { since: opts.since ?? null, until: opts.until ?? null },
+    stats: corpus.stats,
+    headline,
+    metrics,
+    duplicates,
+    missing: [...MISSING],
+  };
+}
+
+function parseArgs(args) {
+  const opts = {};
+  const allowed = new Set(['--root', '--since', '--until', '--json', '--md']);
+  for (let i = 0; i < args.length; i += 1) {
+    const flag = args[i];
+    if (!allowed.has(flag)) throw new Error(`bad flag: ${flag}`);
+    const value = args[i + 1];
+    if (!value || value.startsWith('--')) throw new Error(`missing value for ${flag}`);
+    if (opts[flag]) throw new Error(`duplicate flag: ${flag}`);
+    opts[flag] = value;
+    i += 1;
+  }
+  if (!opts['--root']) throw new Error('missing required --root');
+  for (const flag of ['--since', '--until']) {
+    if (opts[flag] && !Number.isFinite(Date.parse(opts[flag]))) throw new Error(`invalid ISO date for ${flag}: ${opts[flag]}`);
+  }
+  if (opts['--since'] && opts['--until'] && Date.parse(opts['--since']) > Date.parse(opts['--until'])) throw new Error('--since must be <= --until');
+  return opts;
+}
+
+async function main(args) {
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 2;
+  }
+  let report;
+  try {
+    report = await buildReport(opts['--root'], { since: opts['--since'] ?? null, until: opts['--until'] ?? null });
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 2;
+  }
+  const markdown = renderMarkdown(report);
+  try {
+    if (opts['--json']) {
+      fs.mkdirSync(path.dirname(path.resolve(opts['--json'])), { recursive: true });
+      fs.writeFileSync(opts['--json'], `${JSON.stringify(report, null, 2)}\n`);
+    }
+    if (opts['--md']) {
+      fs.mkdirSync(path.dirname(path.resolve(opts['--md'])), { recursive: true });
+      fs.writeFileSync(opts['--md'], markdown);
+    }
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 2;
+  }
+  process.stdout.write(`subagent-cost: ${report.metrics.totals.main.calls + report.metrics.totals.sub.calls} calls, ${report.stats.files} files, headline subShare=${report.headline.subShare}\n`);
+  if (opts['--json']) process.stdout.write(`json: ${path.resolve(opts['--json'])}\n`);
+  if (opts['--md']) process.stdout.write(`md: ${path.resolve(opts['--md'])}\n`);
+  return 0;
+}
+
+const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/scripts/audit/subagent-cost/check-doc.mjs

@@ -0,0 +1,91 @@
+import { readFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+const HEADLINE_KEYS = ['subShare', 'subUncachedShare', 'contextAmplification', 'duplicateContextRatio', 'avgCallsPerTask'];
+const MARKER = /<!--\s*HEADLINE\s+(\{[^\n]*\})\s*-->/;
+
+function parseArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const flag = args[i];
+    if (!['--doc', '--report'].includes(flag) || !args[i + 1] || args[i + 1].startsWith('--')) {
+      throw new Error('usage: check-doc.mjs --doc <md> --report <json>');
+    }
+    if (options[flag]) throw new Error(`duplicate flag: ${flag}`);
+    options[flag] = args[++i];
+  }
+  if (!options['--doc'] || !options['--report']) throw new Error('usage: check-doc.mjs --doc <md> --report <json>');
+  return options;
+}
+
+async function checkDoc(docPath, reportPath) {
+  let doc;
+  let reportText;
+  try {
+    [doc, reportText] = await Promise.all([readFile(docPath, 'utf8'), readFile(reportPath, 'utf8')]);
+  } catch (error) {
+    console.error(`check-doc: ${error.message}`);
+    return 2;
+  }
+
+  let report;
+  try {
+    report = JSON.parse(reportText);
+  } catch {
+    console.error('check-doc: report is not valid JSON');
+    return 2;
+  }
+  const marker = doc.match(MARKER);
+  if (!marker) {
+    console.error('check-doc: missing HEADLINE marker');
+    return 2;
+  }
+  let embedded;
+  try {
+    embedded = JSON.parse(marker[1]);
+  } catch {
+    console.error('check-doc: invalid HEADLINE JSON');
+    return 2;
+  }
+
+  const mismatches = [];
+  const headline = report?.headline;
+  for (const key of HEADLINE_KEYS) {
+    const actual = embedded[key];
+    const expected = headline?.[key];
+    if (actual === null || expected === null) {
+      if (actual !== expected) mismatches.push(key);
+    } else if (typeof actual !== 'number' || !Number.isFinite(actual) || typeof expected !== 'number' || !Number.isFinite(expected) || Math.abs(actual - expected) > 0.001 * Math.max(1, Math.abs(actual), Math.abs(expected))) {
+      mismatches.push(key);
+    }
+  }
+
+  for (let section = 1; section <= 17; section += 1) {
+    if (!new RegExp(`^## ${section}\\.`, 'm').test(doc)) mismatches.push(`## ${section}.`);
+  }
+  for (let question = 1; question <= 16; question += 1) {
+    if (!new RegExp(`\\bQ${question}\\b`).test(doc)) mismatches.push(`Q${question}`);
+  }
+
+  if (mismatches.length) {
+    console.error(`check-doc: mismatch: ${[...new Set(mismatches)].join(', ')}`);
+    return 1;
+  }
+  console.log('check-doc: headline and required markers match');
+  return 0;
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`check-doc: ${error.message}`);
+    process.exitCode = 2;
+    return;
+  }
+  process.exitCode = await checkDoc(options['--doc'], options['--report']);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) await main();

package/scripts/audit/subagent-cost/duplicates.mjs

@@ -0,0 +1,195 @@
+const HEAVY_INPUT_SIDE_MIN = 250_000;
+const HEAVY_OUTPUT_MAX = 2_000;
+const MIN_HEAVY_CALLS_FOR_VERDICT = 10;
+const TOP_LIMIT = 20;
+
+const isFiniteNumber = Number.isFinite;
+const inputSide = (call) => (isFiniteNumber(call.input) ? call.input : 0)
+  + (isFiniteNumber(call.cacheRead) ? call.cacheRead : 0)
+  + (isFiniteNumber(call.cacheWrite) ? call.cacheWrite : 0);
+const ratio = (numerator, denominator) => denominator > 0 ? numerator / denominator : null;
+const agentType = (agent) => agent.agentType ?? 'unknown';
+const sortText = (a, b) => String(a) < String(b) ? -1 : (String(a) > String(b) ? 1 : 0);
+
+function getAgents(corpus) {
+  return Array.isArray(corpus?.agents) ? corpus.agents.filter((agent) => agent && typeof agent === 'object') : [];
+}
+
+function getCalls(corpus) {
+  return Array.isArray(corpus?.calls) ? corpus.calls.filter((call) => call && typeof call === 'object') : [];
+}
+
+function collectSegments(agents) {
+  const byHash = new Map();
+  for (const agent of agents) {
+    if (!Array.isArray(agent.segments)) continue;
+    for (const segment of agent.segments) {
+      if (!segment || typeof segment !== 'object' || segment.h == null
+        || !isFiniteNumber(segment.t) || segment.t < 0) continue;
+      if (!byHash.has(segment.h)) byHash.set(segment.h, []);
+      byHash.get(segment.h).push({
+        h: segment.h,
+        t: segment.t,
+        turnId: agent.turnId,
+        agentId: agent.agentId,
+        agentType: agentType(agent),
+      });
+    }
+  }
+  return byHash;
+}
+
+function repeatedOccurrences(occurrences) {
+  // A segment can occur more than once inside an agent prompt. Repetition is
+  // measured between agents, so retain that agent's first occurrence only.
+  const firstByAgent = new Map();
+  for (const occurrence of occurrences) {
+    if (occurrence.agentId == null || firstByAgent.has(occurrence.agentId)) continue;
+    firstByAgent.set(occurrence.agentId, occurrence);
+  }
+  const distinctAgents = [...firstByAgent.values()];
+  if (distinctAgents.length < 2) return null;
+  return distinctAgents;
+}
+
+function duplicateBreakdown(occurrences) {
+  const agents = repeatedOccurrences(occurrences);
+  if (!agents) return null;
+
+  let withinTokens = 0;
+  let crossTokens = 0;
+  const first = agents[0];
+  for (const occurrence of agents.slice(1)) {
+    if (occurrence.turnId === first.turnId) withinTokens += occurrence.t;
+    else crossTokens += occurrence.t;
+  }
+  return {
+    withinTokens,
+    crossTokens,
+    count: agents.length,
+    displayTokens: first.t,
+    duplicateTokens: withinTokens + crossTokens,
+  };
+}
+
+function computeAmplification(corpus, agents, calls) {
+  const agentsById = new Map(agents.filter((agent) => agent.agentId != null)
+    .map((agent) => [agent.agentId, agent]));
+  const inputByType = new Map();
+  for (const call of calls) {
+    const agent = agentsById.get(call.agentId);
+    if (!agent || call.zero || (call.depth ?? agent.depth ?? 1) <= 0) continue;
+    const type = agentType(agent);
+    inputByType.set(type, (inputByType.get(type) ?? 0) + inputSide(call));
+  }
+
+  const promptsByType = new Map();
+  for (const agent of agents) {
+    if (agent.agentId == null || (agent.depth ?? 1) <= 0
+      || !isFiniteNumber(agent.promptTokensEst) || agent.promptTokensEst < 0) continue;
+    const type = agentType(agent);
+    promptsByType.set(type, (promptsByType.get(type) ?? 0) + agent.promptTokensEst);
+  }
+
+  const inputTotal = [...inputByType.values()].reduce((sum, value) => sum + value, 0);
+  const promptTotal = [...promptsByType.values()].reduce((sum, value) => sum + value, 0);
+  const types = [...new Set([...inputByType.keys(), ...promptsByType.keys()])].sort(sortText);
+  return {
+    overall: promptTotal === 0 ? null : inputTotal / promptTotal,
+    byType: Object.fromEntries(types.map((type) => [
+      type,
+      (promptsByType.get(type) ?? 0) === 0 ? null : (inputByType.get(type) ?? 0) / promptsByType.get(type),
+    ])),
+  };
+}
+
+function summarizeSegments(byHash) {
+  let totalTokens = 0;
+  let duplicateTokens = 0;
+  let withinTokens = 0;
+  let crossTokens = 0;
+  const repeated = [];
+
+  for (const [hash, occurrences] of byHash) {
+    totalTokens += occurrences.reduce((sum, item) => sum + item.t, 0);
+    const breakdown = duplicateBreakdown(occurrences);
+    if (!breakdown) continue;
+    duplicateTokens += breakdown.duplicateTokens;
+    withinTokens += breakdown.withinTokens;
+    crossTokens += breakdown.crossTokens;
+    repeated.push({
+      h: hash,
+      t: breakdown.displayTokens,
+      count: breakdown.count,
+      agentTypes: [...new Set(occurrences.filter((item) => item.agentId != null)
+        .map((item) => item.agentType))].sort(sortText),
+      duplicateTokens: breakdown.duplicateTokens,
+    });
+  }
+
+  repeated.sort((a, b) => b.duplicateTokens - a.duplicateTokens || sortText(a.h, b.h));
+  return {
+    totalTokens,
+    duplicateTokens,
+    withinTokens,
+    crossTokens,
+    topRepeatedSegments: repeated.slice(0, TOP_LIMIT).map(({ duplicateTokens: _tokens, ...segment }) => segment),
+  };
+}
+
+function computeReplayHypothesis(calls, agents, byHash) {
+  const agentsById = new Map(agents.filter((agent) => agent.agentId != null)
+    .map((agent) => [agent.agentId, agent]));
+  const heavyCalls = calls.filter((call) => {
+    const agent = agentsById.get(call.agentId);
+    if (!agent || call.zero || (call.depth ?? agent.depth ?? 1) <= 0) return false;
+    return inputSide(call) >= HEAVY_INPUT_SIDE_MIN
+      && isFiniteNumber(call.output) && call.output <= HEAVY_OUTPUT_MAX;
+  });
+  const heavyTurns = new Set(heavyCalls.map((call) => call.turnId).filter((turnId) => turnId != null));
+  const sharedHeavyTurns = new Set();
+
+  for (const occurrences of byHash.values()) {
+    const agentIdsByTurn = new Map();
+    for (const occurrence of repeatedOccurrences(occurrences) ?? []) {
+      if (occurrence.turnId == null || !heavyTurns.has(occurrence.turnId)) continue;
+      if (!agentIdsByTurn.has(occurrence.turnId)) agentIdsByTurn.set(occurrence.turnId, new Set());
+      agentIdsByTurn.get(occurrence.turnId).add(occurrence.agentId);
+    }
+    for (const [turnId, ids] of agentIdsByTurn) if (ids.size >= 2) sharedHeavyTurns.add(turnId);
+  }
+
+  return {
+    verdict: heavyCalls.length < MIN_HEAVY_CALLS_FOR_VERDICT
+      ? 'inconclusive'
+      : (sharedHeavyTurns.size > 0 ? 'supported' : 'not_supported'),
+    heavyCalls: heavyCalls.length,
+    heavyTurns: heavyTurns.size,
+    sharedHeavyTurns: sharedHeavyTurns.size,
+    share: ratio(sharedHeavyTurns.size, heavyTurns.size),
+  };
+}
+
+export function computeDuplicates(corpus) {
+  const agents = getAgents(corpus);
+  const calls = getCalls(corpus);
+  const byHash = collectSegments(agents);
+  const segments = summarizeSegments(byHash);
+  const amplification = computeAmplification(corpus, agents, calls);
+
+  return {
+    amplification: amplification.overall,
+    amplificationByType: amplification.byType,
+    duplicateRatio: ratio(segments.duplicateTokens, segments.totalTokens),
+    withinTurn: {
+      tokens: segments.withinTokens,
+      ratio: ratio(segments.withinTokens, segments.totalTokens),
+    },
+    crossTurn: {
+      tokens: segments.crossTokens,
+      ratio: ratio(segments.crossTokens, segments.totalTokens),
+    },
+    topRepeatedSegments: segments.topRepeatedSegments,
+    replayHypothesis: computeReplayHypothesis(calls, agents, byHash),
+  };
+}

package/scripts/audit/subagent-cost/metrics.mjs

@@ -0,0 +1,181 @@
+const N_PLUS_ONE_MIN_AGENTS = 3;
+const N_PLUS_ONE_MAX_PROMPT_TOKENS = 2_000;
+const RETRY_MIN_OCCURRENCES = 2;
+const LOOP_MIN_OCCURRENCES = 5;
+const HEAVY_INPUT_SIDE_MIN = 250_000;
+const HEAVY_OUTPUT_MAX = 2_000;
+const TOP_LIMIT = 20;
+
+export function percentile(values, p) {
+  if (!Array.isArray(values) || values.length === 0) return null;
+  const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (sorted.length === 0) return null;
+  const rank = Math.max(1, Math.ceil(p * sorted.length));
+  return sorted[rank - 1];
+}
+
+const sum = (items, field) => items.reduce((total, item) => total + (Number.isFinite(item[field]) ? item[field] : 0), 0);
+const ratio = (n, d) => d > 0 ? n / d : null;
+const inputSide = (call) => (call.input ?? 0) + (call.cacheRead ?? 0) + (call.cacheWrite ?? 0);
+const uncached = (call) => (call.input ?? 0) + (call.cacheWrite ?? 0);
+const callTokens = (call) => inputSide(call) + (call.output ?? 0);
+const validCalls = (corpus) => (corpus.calls ?? []).filter((call) => !call.zero);
+const grouped = (items, keyFn) => {
+  const result = new Map();
+  for (const item of items) {
+    const key = keyFn(item);
+    if (key == null) continue;
+    if (!result.has(key)) result.set(key, []);
+    result.get(key).push(item);
+  }
+  return result;
+};
+const totalFor = (calls) => ({
+  calls: calls.length,
+  input: sum(calls, 'input'),
+  cacheRead: sum(calls, 'cacheRead'),
+  cacheWrite: sum(calls, 'cacheWrite'),
+  output: sum(calls, 'output'),
+  uncached: calls.reduce((n, c) => n + uncached(c), 0),
+  inputSide: calls.reduce((n, c) => n + inputSide(c), 0),
+});
+const cacheFor = (calls) => {
+  const totals = totalFor(calls);
+  return { hitRate: ratio(totals.cacheRead, totals.inputSide), cacheRead: totals.cacheRead, inputSide: totals.inputSide };
+};
+const sortedTop = (items, getValue, getKey) => [...items]
+  .map((item) => ({ ...item, uncached: getValue(item), inputSide: getKey(item) }))
+  .sort((a, b) => b.uncached - a.uncached || b.inputSide - a.inputSide || String(a.agentId ?? a.turnId).localeCompare(String(b.agentId ?? b.turnId)))
+  .slice(0, TOP_LIMIT);
+
+function callPercentiles(calls, selector) {
+  return {
+    p50: percentile(calls.map(selector), 0.5),
+    p90: percentile(calls.map(selector), 0.9),
+    p99: percentile(calls.map(selector), 0.99),
+  };
+}
+
+function computeTasks(corpus, calls) {
+  const tasks = new Map();
+  for (const turn of corpus.turns ?? []) tasks.set(turn.turnId, { turnId: turn.turnId, calls: [] });
+  for (const call of calls) {
+    const key = call.turnId ?? `${call.sessionId}#unattributed`;
+    if (!tasks.has(key)) tasks.set(key, { turnId: key, calls: [] });
+    tasks.get(key).calls.push(call);
+  }
+  const rows = [...tasks.values()];
+  const subAgentCounts = rows.map((task) => new Set((corpus.agents ?? []).filter((a) => a.turnId === task.turnId).map((a) => a.agentId)).size);
+  return {
+    tasks: rows.length,
+    avgSubAgents: ratio(subAgentCounts.reduce((a, b) => a + b, 0), rows.length),
+    avgCalls: ratio(rows.reduce((n, task) => n + task.calls.length, 0), rows.length),
+    ...Object.fromEntries(['Calls', 'Tokens'].flatMap((label) => {
+      const values = rows.map((task) => label === 'Calls' ? task.calls.length : task.calls.reduce((n, c) => n + callTokens(c), 0));
+      return [[`p50${label}`, percentile(values, 0.5)], [`p90${label}`, percentile(values, 0.9)], [`p99${label}`, percentile(values, 0.99)]];
+    })),
+  };
+}
+
+export function computeMetrics(corpus) {
+  const calls = validCalls(corpus);
+  const mainCalls = calls.filter((call) => (call.depth ?? 0) === 0);
+  const subCalls = calls.filter((call) => (call.depth ?? 0) > 0);
+  const main = totalFor(mainCalls);
+  const sub = totalFor(subCalls);
+  const all = totalFor(calls);
+  const totalOutput = all.output;
+  const cacheByType = {};
+  const byType = {};
+  const typeCalls = grouped(subCalls, (call) => call.agentType ?? 'unknown');
+  for (const [type, typeGroup] of typeCalls) {
+    const agents = (corpus.agents ?? []).filter((agent) => (agent.agentType ?? 'unknown') === type);
+    const totals = totalFor(typeGroup);
+    const latencies = typeGroup.map((call) => call.latencyMs).filter(Number.isFinite);
+    const finalTokens = agents.map((agent) => agent.finalTokensEst).filter(Number.isFinite);
+    const refs = agents.map((agent) => agent.finalRefRatio).filter(Number.isFinite);
+    byType[type] = {
+      agents: new Set(agents.map((agent) => agent.agentId)).size,
+      calls: totals.calls,
+      inputSide: totals.inputSide,
+      uncached: totals.uncached,
+      output: totals.output,
+      avgCallsPerAgent: ratio(totals.calls, new Set(agents.map((agent) => agent.agentId)).size),
+      outputPerInput: ratio(totals.output, totals.inputSide),
+      avgFinalTokensEst: ratio(finalTokens.reduce((a, b) => a + b, 0), finalTokens.length),
+      avgFinalRefRatio: ratio(refs.reduce((a, b) => a + b, 0), refs.length),
+      latencyP50: percentile(latencies, 0.5),
+      latencyP90: percentile(latencies, 0.9),
+      valueProxy: { label: 'proxy; not a measure of true agent value', avgFinalTokensEst: ratio(finalTokens.reduce((a, b) => a + b, 0), finalTokens.length), avgFinalRefRatio: ratio(refs.reduce((a, b) => a + b, 0), refs.length), outputPerInput: ratio(totals.output, totals.inputSide) },
+    };
+    cacheByType[type] = cacheFor(typeGroup);
+  }
+  const depthCalls = grouped(calls, (call) => call.depth ?? 0);
+  const byDepth = Object.fromEntries([...depthCalls].map(([depth, group]) => [depth, totalFor(group)]));
+  const modelCalls = grouped(calls, (call) => call.model ?? 'unknown');
+  const byModel = Object.fromEntries([...modelCalls].map(([model, group]) => [model, totalFor(group)]));
+  const turnAgents = grouped(corpus.agents ?? [], (agent) => agent.turnId);
+  const fanoutCounts = [...turnAgents.values()].map((agents) => agents.length);
+  const fanoutHistogram = {};
+  for (const count of fanoutCounts) fanoutHistogram[count] = (fanoutHistogram[count] ?? 0) + 1;
+  const heavy = subCalls.filter((call) => inputSide(call) >= HEAVY_INPUT_SIDE_MIN && call.output <= HEAVY_OUTPUT_MAX);
+  const heavyByType = {};
+  for (const [type, group] of grouped(heavy, (call) => call.agentType ?? 'unknown')) heavyByType[type] = group.length;
+  const heavyBySession = {};
+  for (const [sessionId, group] of grouped(heavy, (call) => call.sessionId ?? 'unknown')) heavyBySession[sessionId] = group.length;
+  const turns = [...new Set([...calls.map((call) => call.turnId), ...(corpus.turns ?? []).map((turn) => turn.turnId)].filter(Boolean))];
+  const turnAgentsAll = grouped(corpus.agents ?? [], (agent) => agent.turnId);
+  const flagged = (predicate) => {
+    const ids = [];
+    for (const [turnId, agents] of turnAgentsAll) if (predicate(agents)) ids.push(turnId);
+    return { count: ids.length, turnIds: ids.slice(0, TOP_LIMIT) };
+  };
+  const nPlusOne = flagged((agents) => {
+    const sorted = [...agents].sort((a, b) => a.firstTs - b.firstTs);
+    let run = 0;
+    let previous = null;
+    for (const agent of sorted) {
+      const small = Number.isFinite(agent.promptTokensEst) && agent.promptTokensEst <= N_PLUS_ONE_MAX_PROMPT_TOKENS;
+      if (small && previous && previous.agentType === agent.agentType && agent.firstTs >= previous.lastTs) run += 1;
+      else run = small ? 1 : 0;
+      previous = agent;
+      if (run >= N_PLUS_ONE_MIN_AGENTS) return true;
+    }
+    return false;
+  });
+  const retryLoops = flagged((agents) => [...grouped(agents.filter((a) => a.promptHash != null), (a) => `${a.agentType}\0${a.promptHash}`).values()].some((group) => group.length >= RETRY_MIN_OCCURRENCES));
+  const loops = flagged((agents) => [...grouped(agents, (a) => a.agentType).values()].some((group) => group.length >= LOOP_MIN_OCCURRENCES));
+  const agentStats = (corpus.agents ?? []).map((agent) => {
+    const group = calls.filter((call) => call.agentId === agent.agentId);
+    return { agentId: agent.agentId, agentType: agent.agentType, turnId: agent.turnId, calls: group.length, uncached: group.reduce((n, c) => n + uncached(c), 0), inputSide: group.reduce((n, c) => n + inputSide(c), 0), output: sum(group, 'output') };
+  });
+  const turnStats = turns.map((turnId) => {
+    const group = calls.filter((call) => call.turnId === turnId);
+    return { turnId, calls: group.length, uncached: group.reduce((n, c) => n + uncached(c), 0), inputSide: group.reduce((n, c) => n + inputSide(c), 0), output: sum(group, 'output') };
+  });
+  const costliest = [...turnStats].sort((a, b) => b.uncached - a.uncached).slice(0, 5);
+  const tokenFlow = costliest.map(({ turnId }) => ({ turnId, calls: calls.filter((call) => call.turnId === turnId).sort((a, b) => a.ts - b.ts).map((call) => ({ ts: call.ts, agentType: call.agentType, depth: call.depth, input: call.input, cacheRead: call.cacheRead, cacheWrite: call.cacheWrite, output: call.output })) }));
+
+  return {
+    totals: { main, sub },
+    share: {
+      subOfInputSide: ratio(sub.inputSide, all.inputSide),
+      subOfUncached: ratio(sub.uncached, all.uncached),
+      subOfOutput: ratio(sub.output, totalOutput),
+      subOfCalls: ratio(sub.calls, all.calls),
+    },
+    cache: { main: cacheFor(mainCalls), sub: cacheFor(subCalls), byType: cacheByType },
+    perTask: computeTasks(corpus, calls),
+    byType,
+    byDepth,
+    byModel,
+    fanout: { histogram: fanoutHistogram, max: fanoutCounts.length ? Math.max(...fanoutCounts) : 0, p90: percentile(fanoutCounts, 0.9) },
+    heavyCalls: { count: heavy.length, share: ratio(heavy.length, subCalls.length), byType: heavyByType, bySession: heavyBySession },
+    nPlusOne,
+    retryLoops,
+    loops,
+    topAgents: sortedTop(agentStats, (agent) => agent.uncached, (agent) => agent.inputSide),
+    topTurns: sortedTop(turnStats, (turn) => turn.uncached, (turn) => turn.inputSide),
+    tokenFlow,
+  };
+}