@ngockhoale/ukit 3.4.24 → 3.4.26

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.26 - 2026-10-08
+
+**P1 fix: completion gate no longer reports `missing write-evidence` for tracked-file changes made through Bash.**
+- `execution-ledger`: a Bash receipt records a git workspace fingerprint (HEAD + hash of `git diff HEAD`, tracked files only). When it differs from the previous receipt, a synthetic write is applied. First observation, git failure/timeout, non-git directories and untracked files record nothing (fail-closed).
+- Strictly read-only Bash (`ls`, `cat`, `git status`, ...) and verification commands absorb the delta into the baseline instead of earning a write, so a background process or subagent edit is not credited to the main agent.
+- Evidence tier: a Bash-derived write is `inferred` (`evidenceTier: 'inferred'`, supporting evidence); only Edit/Write is direct. Inferred writes never satisfy `verification-evidence`.
+- Known limits: the first Bash of a session only seeds the baseline, so a mutation made by that very command is not credited; a delta that coincides with a non-read-only Bash is still attributed to it (inferred, not proof).
+- Regression tests: `tests/hooks/bashMutationEvidence.test.js` (12 cases).
+- Not included: AWAITING_USER stop handling (separate bug); `isVerificationCommand` coverage for commands such as `yarn release:verify`.
+
+## 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`).

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.24",
+  "version": "3.4.26",
   "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,
+  };
+}

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

@@ -0,0 +1,320 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { createHash } from 'node:crypto';
+
+const sha1 = (value) => createHash('sha1').update(value).digest('hex').slice(0, 12);
+const timestampMs = (value) => {
+  const result = typeof value === 'number' ? value : Date.parse(value);
+  return Number.isFinite(result) ? result : null;
+};
+const estimateTokens = (text) => (text ? Math.ceil(text.length / 4) : 0);
+const contentText = (content) => {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter((part) => part?.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text).join('\n');
+};
+
+async function readJsonl(file, stats, consume) {
+  const stream = fs.createReadStream(file, { encoding: 'utf8' });
+  const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of lines) {
+      stats.lines += 1;
+      if (!line.trim()) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        stats.malformed += 1;
+        continue;
+      }
+      consume(record);
+    }
+  } finally {
+    lines.close();
+    stream.destroy();
+  }
+}
+
+function transcriptFiles(root) {
+  const files = [];
+  const rootEntries = fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of rootEntries) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+      files.push({ file: entryPath, sessionId: entry.name.slice(0, -'.jsonl'.length), isAgent: false });
+    }
+  }
+  for (const entry of rootEntries) {
+    if (!entry.isDirectory()) continue;
+    const sessionDir = path.join(root, entry.name);
+    const subagentsDir = path.join(sessionDir, 'subagents');
+    let subagentEntries;
+    try {
+      subagentEntries = fs.readdirSync(subagentsDir, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') continue;
+      throw error;
+    }
+    for (const agentEntry of subagentEntries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!agentEntry.isFile() || !agentEntry.name.endsWith('.jsonl')) continue;
+      const stem = agentEntry.name.slice(0, -'.jsonl'.length);
+      files.push({
+        file: path.join(subagentsDir, agentEntry.name),
+        metaFile: path.join(subagentsDir, `${stem}.meta.json`),
+        sessionId: entry.name,
+        agentId: stem.replace(/^agent-/, ''),
+        isAgent: true,
+      });
+    }
+  }
+  return files;
+}
+
+async function readMeta(file) {
+  try {
+    const value = JSON.parse(await fs.promises.readFile(file, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function makeCall(record, sessionId, agentId, agentType, depth, ts, priorTs) {
+  const message = record.message ?? {};
+  const usage = message.usage ?? {};
+  const input = Number(usage.input_tokens) || 0;
+  const cacheRead = Number(usage.cache_read_input_tokens ?? usage.cache_read_tokens) || 0;
+  const cacheWrite = Number(usage.cache_creation_input_tokens ?? usage.cache_creation_tokens) || 0;
+  const output = Number(usage.output_tokens) || 0;
+  const key = message.id ?? record.requestId ?? record.uuid;
+  return {
+    id: key == null ? null : String(key),
+    sessionId,
+    turnId: null,
+    agentId: agentId ?? null,
+    agentType: agentType ?? null,
+    model: message.model ?? record.model ?? null,
+    ts,
+    latencyMs: ts != null && priorTs != null && ts >= priorTs ? ts - priorTs : null,
+    input,
+    cacheRead,
+    cacheWrite,
+    output,
+    zero: input === 0 && cacheRead === 0 && cacheWrite === 0 && output === 0,
+    depth,
+    _dedupeKey: key == null ? null : String(key),
+  };
+}
+
+function hashFinalReferences(finalText, parentText) {
+  if (!finalText || !parentText) return null;
+  const words = (text) => text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+  const finalWords = words(finalText);
+  const parentWords = words(parentText);
+  if (finalWords.length < 5 || parentWords.length < 5) return null;
+  const grams = new Set();
+  for (let i = 0; i <= parentWords.length - 5; i += 1) {
+    grams.add(sha1(parentWords.slice(i, i + 5).join(' ')));
+  }
+  let matches = 0;
+  let total = 0;
+  for (let i = 0; i <= finalWords.length - 5; i += 1) {
+    total += 1;
+    if (grams.has(sha1(finalWords.slice(i, i + 5).join(' ')))) matches += 1;
+  }
+  return total ? matches / total : null;
+}
+
+export async function loadCorpus(root, { since = null, until = null } = {}) {
+  let rootStat;
+  try {
+    rootStat = fs.statSync(root);
+  } catch {
+    throw new Error(`root not found: ${root}`);
+  }
+  if (!rootStat.isDirectory()) throw new Error(`root not found: ${root}`);
+
+  const stats = {
+    files: 0, lines: 0, malformed: 0, zeroUsage: 0, dupIds: 0,
+    missingMeta: 0, noParent: 0, unattributed: 0,
+  };
+  const files = transcriptFiles(root);
+  const mainFilesBySession = new Map();
+  const agentFiles = [];
+  const promptRecordsBySession = new Map();
+  const toolUsesBySession = new Map();
+  const calls = [];
+  const agents = [];
+  const turns = [];
+  const sinceMs = since == null ? null : timestampMs(since);
+  const untilMs = until == null ? null : timestampMs(until);
+
+  for (const fileInfo of files) {
+    stats.files += 1;
+    const meta = fileInfo.isAgent ? await readMeta(fileInfo.metaFile) : null;
+    if (fileInfo.isAgent && !meta) stats.missingMeta += 1;
+    const agentType = fileInfo.isAgent ? (meta?.agentType ?? null) : null;
+    const depth = fileInfo.isAgent
+      ? (Number.isFinite(meta?.spawnDepth) ? meta.spawnDepth : 1)
+      : 0;
+    const deduped = new Map();
+    const userRecords = [];
+    let previousTs = null;
+    let finalAssistantText = null;
+
+    await readJsonl(fileInfo.file, stats, (record) => {
+      const ts = timestampMs(record.timestamp);
+      if (!fileInfo.isAgent && record.type === 'user' && !record.isSidechain) {
+        const body = contentText(record.message?.content ?? record.content);
+        if (body.trim()) userRecords.push({ ts, body });
+      }
+      if (record.type !== 'assistant') return;
+
+      const call = makeCall(
+        record,
+        fileInfo.sessionId,
+        fileInfo.isAgent ? fileInfo.agentId : null,
+        fileInfo.isAgent ? (agentType ?? record.attributionAgent ?? 'unknown') : null,
+        depth,
+        ts,
+        previousTs,
+      );
+      previousTs = ts;
+      const key = call._dedupeKey ?? `line:${stats.lines}`;
+      if (deduped.has(key) && call._dedupeKey != null) stats.dupIds += 1;
+      deduped.set(key, { call, record });
+
+      if (fileInfo.isAgent) {
+        const text = contentText(record.message?.content);
+        if (text) finalAssistantText = text;
+      } else {
+        for (const part of record.message?.content ?? []) {
+          if (part?.type !== 'tool_use' || typeof part.id !== 'string') continue;
+          if (!toolUsesBySession.has(fileInfo.sessionId)) toolUsesBySession.set(fileInfo.sessionId, new Map());
+          toolUsesBySession.get(fileInfo.sessionId).set(part.id, { ts, record, tool: part });
+        }
+      }
+    });
+
+    const records = [...deduped.values()];
+    if (fileInfo.isAgent) {
+      agentFiles.push({ fileInfo, meta, agentType, depth, records, finalAssistantText });
+    } else {
+      mainFilesBySession.set(fileInfo.sessionId, records);
+      promptRecordsBySession.set(fileInfo.sessionId, userRecords);
+    }
+  }
+
+  const turnsBySession = new Map();
+  for (const [sessionId, prompts] of promptRecordsBySession) {
+    prompts.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+    const sessionTurns = prompts.map((prompt, index) => ({
+      turnId: `${sessionId}#${index + 1}`,
+      sessionId,
+      ts: prompt.ts,
+      promptHash: sha1(prompt.body),
+      promptTokensEst: estimateTokens(prompt.body),
+    }));
+    turnsBySession.set(sessionId, sessionTurns);
+    turns.push(...sessionTurns);
+  }
+
+  function turnForTime(sessionId, ts) {
+    const sessionTurns = turnsBySession.get(sessionId) ?? [];
+    let selected = null;
+    for (const turn of sessionTurns) {
+      if (ts == null || turn.ts == null || turn.ts <= ts) selected = turn;
+      else break;
+    }
+    return selected;
+  }
+
+  const parentTextBySessionTurn = new Map();
+  for (const [sessionId, records] of mainFilesBySession) {
+    let latestTurn = null;
+    const assistantTextsByTurn = new Map();
+    for (const { call, record } of records) {
+      const turn = turnForTime(sessionId, call.ts);
+      if (turn) latestTurn = turn;
+      call.turnId = latestTurn?.turnId ?? `${sessionId}#unattributed`;
+      if (record.message?.content) {
+        const text = contentText(record.message.content);
+        if (text) assistantTextsByTurn.set(call.turnId, text);
+      }
+      calls.push(call);
+    }
+    for (const [turnId, text] of assistantTextsByTurn) {
+      parentTextBySessionTurn.set(`${sessionId}\u0000${turnId}`, text);
+    }
+  }
+
+  agentFiles.sort((a, b) => {
+    const aTs = a.records[0]?.call.ts ?? 0;
+    const bTs = b.records[0]?.call.ts ?? 0;
+    return aTs - bTs || a.fileInfo.agentId.localeCompare(b.fileInfo.agentId);
+  });
+  const agentsById = new Map();
+  for (const { fileInfo, meta, agentType, depth, records, finalAssistantText } of agentFiles) {
+    const toolUseId = meta?.toolUseId ?? null;
+    const parent = toolUseId == null ? null : toolUsesBySession.get(fileInfo.sessionId)?.get(toolUseId) ?? null;
+    if (!parent) stats.noParent += 1;
+    const turn = parent ? turnForTime(fileInfo.sessionId, parent.ts) : null;
+    const turnId = turn?.turnId ?? `${fileInfo.sessionId}#unattributed`;
+    if (!turn) stats.unattributed += 1;
+
+    const delegatedPrompt = typeof parent?.tool?.input?.prompt === 'string' ? parent.tool.input.prompt : '';
+    const description = typeof meta?.description === 'string' ? meta.description : '';
+    const segments = delegatedPrompt.split(/\n\s*\n/)
+      .map((segment) => segment.trim())
+      .filter((segment) => segment.length >= 200)
+      .map((segment) => ({ h: sha1(segment), t: estimateTokens(segment) }));
+    const firstTs = records.reduce((value, item) => item.call.ts == null ? value : value == null ? item.call.ts : Math.min(value, item.call.ts), null);
+    const lastTs = records.reduce((value, item) => item.call.ts == null ? value : value == null ? item.call.ts : Math.max(value, item.call.ts), null);
+    const parentText = parentTextBySessionTurn.get(`${fileInfo.sessionId}\u0000${turnId}`) ?? '';
+    const agent = {
+      agentId: fileInfo.agentId,
+      sessionId: fileInfo.sessionId,
+      turnId,
+      agentType: agentType ?? records.find((item) => item.record.attributionAgent)?.record.attributionAgent ?? 'unknown',
+      descriptionHash: description ? sha1(description) : null,
+      toolUseId,
+      depth,
+      parentAgentId: meta?.parentAgentId ?? null,
+      metaModel: meta?.model ?? null,
+      hasMeta: Boolean(meta),
+      promptHash: delegatedPrompt ? sha1(delegatedPrompt) : null,
+      promptTokensEst: delegatedPrompt ? estimateTokens(delegatedPrompt) : null,
+      segments,
+      finalTokensEst: finalAssistantText ? estimateTokens(finalAssistantText) : null,
+      finalRefRatio: hashFinalReferences(finalAssistantText, parentText),
+      firstTs,
+      lastTs,
+    };
+    agents.push(agent);
+    agentsById.set(`${fileInfo.sessionId}\u0000${fileInfo.agentId}`, agent);
+    for (const { call } of records) {
+      call.turnId = turnId;
+      calls.push(call);
+    }
+  }
+
+  // Resolve explicit parent-agent links when the parent transcript is present; retain null for unknown links.
+  for (const agent of agents) {
+    if (agent.parentAgentId != null) {
+      const parent = agentsById.get(`${agent.sessionId}\u0000${agent.parentAgentId}`);
+      if (parent && agent.turnId.endsWith('#unattributed')) agent.turnId = parent.turnId;
+    }
+  }
+
+  stats.zeroUsage = calls.reduce((count, call) => count + (call.zero ? 1 : 0), 0);
+  const filteredCalls = calls.filter((call) =>
+    (sinceMs == null || (call.ts != null && call.ts >= sinceMs)) &&
+    (untilMs == null || (call.ts != null && call.ts <= untilMs)));
+  for (const call of filteredCalls) {
+    delete call._dedupeKey;
+  }
+  return { calls: filteredCalls, turns, agents, stats };
+}

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

@@ -0,0 +1,34 @@
+const fmt = (value) => value == null || !Number.isFinite(value) ? 'N/A' : Number(value).toLocaleString('en-US', { maximumFractionDigits: 3 });
+const table = (headers, rows) => [`| ${headers.join(' | ')} |`, `| ${headers.map(() => '---').join(' | ')} |`, ...rows.map((row) => `| ${row.map((cell) => String(cell ?? 'N/A').replaceAll('|', '\\|').replaceAll('\n', ' ')).join(' | ')} |`)].join('\n');
+
+export function renderMarkdown(report) {
+  const m = report.metrics ?? {};
+  const d = report.duplicates ?? {};
+  const totals = m.totals ?? {};
+  const typeRows = Object.entries(m.byType ?? {}).sort(([a], [b]) => a.localeCompare(b))
+    .map(([type, value]) => [type, value.agents, value.calls, fmt(value.inputSide), fmt(value.uncached), fmt(value.output), fmt(value.latencyP50)]);
+  const topRows = (items, key) => (items ?? []).map((item) => [item[key], item.agentType ?? 'N/A', item.calls, fmt(item.uncached), fmt(item.inputSide), fmt(item.output)]);
+  const flowRows = (m.tokenFlow ?? []).flatMap((turn) => turn.calls.map((call) => [turn.turnId, new Date(call.ts).toISOString(), call.agentType ?? 'main', call.depth, fmt(call.input), fmt(call.cacheRead), fmt(call.cacheWrite), fmt(call.output)]));
+  const flags = (value) => (value?.turnIds ?? []).map((turnId) => [turnId]);
+  return [
+    '# Sub-agent cost audit report',
+    '',
+    `Generated: ${report.generatedAt}`, `Root: ${report.root}`, `Window: ${report.window?.since ?? 'all'} — ${report.window?.until ?? 'all'}`,
+    '', '## Totals', '',
+    table(['Group', 'Calls', 'Input', 'Cache read', 'Cache write', 'Output', 'Uncached', 'Input-side'], ['main', 'sub'].map((key) => { const t = totals[key] ?? {}; return [key, t.calls, fmt(t.input), fmt(t.cacheRead), fmt(t.cacheWrite), fmt(t.output), fmt(t.uncached), fmt(t.inputSide)]; })),
+    '', '## Main vs sub-agent', '', table(['Metric', 'Value'], Object.entries(m.share ?? {}).map(([key, value]) => [key, fmt(value)])),
+    '', '## By type', '', table(['Type', 'Agents', 'Calls', 'Input-side', 'Uncached', 'Output', 'Latency p50 ms'], typeRows),
+    '', '## Fan-out', '', table(['Metric', 'Value'], [['Maximum', m.fanout?.max], ['p90', fmt(m.fanout?.p90)], ...Object.entries(m.fanout?.histogram ?? {}).map(([count, turns]) => [`${count} agents`, turns])]),
+    '', '## Cache', '', table(['Group', 'Hit rate', 'Cache read', 'Input-side'], ['main', 'sub'].map((key) => { const c = m.cache?.[key] ?? {}; return [key, fmt(c.hitRate), fmt(c.cacheRead), fmt(c.inputSide)]; })),
+    '', '## Top agents (20)', '', table(['Agent', 'Type', 'Calls', 'Uncached', 'Input-side', 'Output'], topRows(m.topAgents, 'agentId')),
+    '', '## Top turns (20)', '', table(['Turn', 'Type', 'Calls', 'Uncached', 'Input-side', 'Output'], topRows(m.topTurns, 'turnId')),
+    '', '## Token flow (5 costliest turns)', '', table(['Turn', 'Timestamp', 'Type', 'Depth', 'Input', 'Cache read', 'Cache write', 'Output'], flowRows),
+    '', '## N+1 flags', '', table(['Turn'], flags(m.nPlusOne)),
+    '', '## Retry flags', '', table(['Turn'], flags(m.retryLoops)),
+    '', '## Repeated-loop flags', '', table(['Turn'], flags(m.loops)),
+    '', '## Heavy calls and replay hypothesis', '', table(['Metric', 'Value'], [['Heavy calls', m.heavyCalls?.count], ['Heavy share', fmt(m.heavyCalls?.share)], ['Replay verdict', d.replayHypothesis?.verdict], ['Replay share', fmt(d.replayHypothesis?.share)]]),
+    '', '## Context duplication', '', table(['Metric', 'Value'], [['Amplification', fmt(d.amplification)], ['Duplicate context ratio', fmt(d.duplicateRatio)], ['Within-turn ratio', fmt(d.withinTurn?.ratio)], ['Cross-turn ratio', fmt(d.crossTurn?.ratio)]]),
+    '', '## Missing telemetry', '', ...(report.missing ?? []).map((item) => `- ${item}`),
+    '',
+  ].join('\n');
+}

package/template_project/.claude/ukit/runtime/execution-ledger.mjs

@@ -549,6 +549,52 @@ function gitOutput(args, cwd) {
   }
 }
 
+// Verifiable Bash-mutation evidence: a Bash command is never a write by itself. It counts
+// only when the TRACKED git workspace fingerprint (HEAD + content hash of `git diff HEAD`)
+// differs from the one recorded at the previous receipt. Any git failure, timeout or
+// oversize diff yields null, and null never creates evidence (fail-closed). Untracked files
+// are deliberately excluded: runtime state under .ukit/ would otherwise look like a change.
+function workspaceFingerprint(cwd) {
+  if (!cwd) return null;
+  try {
+    const run = (args) => execFileSync('git', args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    const head = String(run(['rev-parse', 'HEAD'])).trim();
+    if (!head) return null;
+    const diffHash = crypto.createHash('sha256').update(run(['diff', 'HEAD', '--no-ext-diff'])).digest('hex');
+    return `${head.slice(0, 12)}:${diffHash.slice(0, 16)}`;
+  } catch {
+    return null;
+  }
+}
+
+// A workspace delta cannot be attributed to the Bash call that happened to observe it: a
+// background process or a subagent may have changed the tree in between. The classifier below
+// only ever REMOVES credit — a command it recognises as strictly read-only never receives a
+// delta write (the delta is absorbed into the baseline). It never grants credit by itself;
+// unrecognised commands are merely eligible, and their write stays tier "inferred".
+const READ_ONLY_BASH = new Set([
+  'ls', 'cat', 'head', 'tail', 'wc', 'pwd', 'echo', 'printf', 'grep', 'rg', 'cd', 'which',
+  'stat', 'file', 'diff', 'sort', 'uniq', 'date', 'env', 'true', 'test', '[', 'basename', 'dirname',
+]);
+const READ_ONLY_GIT = new Set(['status', 'diff', 'log', 'show', 'rev-parse', 'ls-files', 'blame', 'describe', 'merge-base']);
+
+function isReadOnlyBashCommand(command) {
+  const text = String(command || '').trim();
+  if (!text || /[>`]|\$\(|<\(|\btee\b|\s-i\b|--in-place|-exec\b|-delete\b/.test(text)) return false;
+  return text.split(/&&|\|\||;|\||\n/).every((segment) => {
+    const words = segment.trim().split(/\s+/).filter(Boolean);
+    while (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) words.shift();
+    if (words.length === 0) return false;
+    if (words[0] === 'git') return READ_ONLY_GIT.has(words.find((w, i) => i > 0 && !w.startsWith('-')) || '');
+    return READ_ONLY_BASH.has(words[0]);
+  });
+}
+
 // A diff whose changed paths are all tests/docs/lint-format config is
 // stale-but-recoverable: one rebuild at current head restores currency.
 const RECOVERABLE_DIFF_PATH = /(^|\/)(docs\/|[^/]*\.md$)|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|specs?|__tests__)\/|(?:^|\/)\.?eslint|\.prettierrc|biome\.json|\.editorconfig|tsconfig.*\.json$/i;
@@ -899,6 +945,11 @@ function carriedEvidenceLedger(fresh, current) {
       || current.targetedVerificationSucceeded === true,
     sourceFiles: [...new Set([...(current.sourceFiles || []), ...(fresh.sourceFiles || [])])]
       .slice(-MAX_SOURCE_FILES),
+    // Workspace baseline for Bash-mutation attribution: same-prompt re-keys keep it (the router
+    // re-keys on every tool call); a different prompt returns `fresh` above and re-seeds.
+    workspaceFp: current.workspaceFp || fresh.workspaceFp || null,
+    inferredWrite: fresh.inferredWrite === true || current.inferredWrite === true,
+    directWrite: fresh.directWrite === true || current.directWrite === true,
     writeAttempted: fresh.writeAttempted || current.writeAttempted === true,
     writeSucceeded: fresh.writeSucceeded || current.writeSucceeded === true,
     verificationAttempted: fresh.verificationAttempted || current.verificationAttempted === true,
@@ -1032,7 +1083,7 @@ const MAX_JOURNAL_SEEN = 64;
 const MAX_JOURNAL_RECORDS = 128;
 const MAX_JOURNAL_QUARANTINE_LINES = 32;
 const LEDGER_EVENT_TYPES = new Set(['receipt', 'continuation', 'notified', 'stop-progress', 'resumable-run']);
-const RECEIPT_KINDS = new Set(['source', 'write', 'verification', 'playbook-finding']);
+const RECEIPT_KINDS = new Set(['source', 'write', 'verification', 'playbook-finding', 'workspace']);
 
 function journalPathFor(target) {
   return `${target}.journal`;
@@ -1151,7 +1202,7 @@ function newEventId() {
   return `${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
 }
 
-const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope'];
+const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope', 'workspaceFp', 'bashReadOnly'];
 
 // TASK-009 (BL-011): evidence attestations are whitelisted verbatim — class /
 // surface / result / claim, the ARCH §Evidence Schema fields a receipt may
@@ -1605,7 +1656,36 @@ function applyBugFixFloorReceipt(ledger, receipt) {
   return receipt;
 }
 
-function applyReceiptToLedger(ledger, receipt, { vibecode = false } = {}) {
+// Folds the workspace fingerprint into the ledger, then applies the receipt itself. A
+// successful Bash receipt whose fingerprint moved since the last receipt is additionally
+// applied as a synthetic write (fingerprint equality is the only evidence — never the
+// command text). A first observation only seeds the baseline.
+function applyReceiptToLedger(ledger, receipt, options = {}) {
+  if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
+  const fp = typeof receipt.workspaceFp === 'string' && receipt.workspaceFp ? receipt.workspaceFp : null;
+  let base = ledger;
+  if (fp) {
+    const prior = ledger?.workspaceFp || null;
+    base = { ...ledger, workspaceFp: fp };
+    if (prior && prior !== fp && receipt.kind === 'workspace' && receipt.toolName === 'Bash' && receipt.success === true && receipt.bashReadOnly !== true) {
+      const applied = applyReceiptCore(base, {
+        ts: receipt.ts,
+        kind: 'write',
+        toolName: 'Bash',
+        toolUseId: receipt.toolUseId,
+        success: true,
+        exitCode: receipt.exitCode,
+        file: `bash-workspace:${fp}`,
+        detail: 'bash-workspace-delta',
+      }, options);
+      if (applied) base = applied.ledger;
+    }
+  }
+  if (receipt.kind === 'workspace') return { ledger: base, value: null };
+  return applyReceiptCore(base, receipt, options);
+}
+
+function applyReceiptCore(ledger, receipt, { vibecode = false } = {}) {
   if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
   const next = { ...ledger };
   if (receipt.kind === 'source') {
@@ -1616,6 +1696,10 @@ function applyReceiptToLedger(ledger, receipt, { vibecode = false } = {}) {
   } else if (receipt.kind === 'write') {
     next.writeAttempted = true;
     next.writeSucceeded = next.writeSucceeded || receipt.success;
+    // Evidence tier: a fingerprint-derived Bash delta is inferred (supporting) evidence; only a
+    // tool-attributed Edit/Write is direct.
+    if (receipt.detail === 'bash-workspace-delta') next.inferredWrite = true;
+    else if (receipt.success) next.directWrite = true;
     // A mutation attempt between failures breaks the "no change in between" loop shape.
     if (next.failedVerificationStreak) next.failedVerificationStreak = null;
     // TASK-026 fix round 1: bank the FIRST successful write to this target. Later replays of
@@ -2166,6 +2250,7 @@ export async function recordExecutionReceipt({
   const success = !failed && (exitCode === null || exitCode === 0);
   const toolInput = payload.tool_input || {};
   const evidence = receiptEvidenceAttestation(payload, toolInput);
+  const workspaceFp = workspaceFingerprint(projectRoot);
   const receipt = {
     ts: Date.now(),
     toolName,
@@ -2203,10 +2288,18 @@ export async function recordExecutionReceipt({
     if (isVerificationCommand(toolInput.command)) {
       receipt.verdict = mintVerificationVerdict(receipt, payload, projectRoot);
     }
+  } else if (toolName === 'Bash' && workspaceFp) {
+    // Any other Bash: no evidence of its own. The receipt only carries the workspace
+    // fingerprint so a verifiable tracked-file change can be attributed at apply time.
+    receipt.kind = 'workspace';
   } else {
     // Untracked tool: no event, no lock, no write — same as the old unlocked early return.
     return { rejected: true, eventId: null };
   }
+  if (workspaceFp) {
+    receipt.workspaceFp = workspaceFp;
+    if (toolName === 'Bash' && isReadOnlyBashCommand(toolInput.command)) receipt.bashReadOnly = true;
+  }
   if (evidence) {
     receipt.evidence = evidence;
   }
@@ -2474,6 +2567,12 @@ function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}, {
   return instruction ?? 'Complete the current routed milestone before stopping.';
 }
 
+// Write evidence that exists only as a Bash workspace delta is supporting evidence, labelled so
+// consumers never mistake it for tool-attributed proof. It never satisfies verification.
+function writeEvidenceTier(ledger = {}) {
+  return ledger.inferredWrite === true && ledger.directWrite !== true ? { evidenceTier: 'inferred' } : {};
+}
+
 export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   const routeSummary = state?.routeSummary || {};
   // Explicit vibecode autonomy: the user asked UKit to run one prompt to a finished result,
@@ -2581,6 +2680,7 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
         complete: true,
         outcome: 'verified',
         missingEvidence: [],
+        ...writeEvidenceTier(effectiveLedger),
       };
     }
   }
@@ -2588,7 +2688,7 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
     // Silent success: the route is present and every required evidence is satisfied. Marked
     // `complete` so the CLI dispatch recognizes it BEFORE the loud final else — otherwise a
     // bare loud else would turn a clean stop into user-visible noise.
-    return { continue: false, notify: false, complete: true, missingEvidence: [] };
+    return { continue: false, notify: false, complete: true, missingEvidence: [], ...writeEvidenceTier(effectiveLedger) };
   }
 
   // `find-cause` can validly end clean: an investigation may establish that no actionable

package/template_project/.claude/ukit/runtime/stop-coordinator.mjs

@@ -956,7 +956,7 @@ async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
  *
  * Advisory lane: EVERY failure path returns { kind: 'none' }, never throws.
  */
-export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null } = {}) {
+export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null, stopHookActive = false } = {}) {
   const gate = await loadHandoffGateConfig(projectRoot);
   if (!gate.enabled) return { kind: 'none' };
 
@@ -1024,6 +1024,20 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
 
   const signature = `${phase}|${cursor}|${next}`;
   const streak = await bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs });
+  // Reentrancy valve (stop_hook_active): Claude Code sets it when this Stop fires
+  // inside the continuation turn WE forced. The same cursor signature seen again
+  // (streak > 1) means that continuation made no cursor progress — blocking again
+  // is a no-progress loop, so release once instead of waiting for the stalled cap.
+  // A moved cursor resets the streak to 1 and keeps blocking (real progress).
+  if (stopHookActive === true && streak !== null && streak > 1) {
+    return {
+      kind: 'advisory',
+      systemMessage:
+        `[ukit-stop-coordinator] handoff-cursor released this reentrant stop (stop_hook_active): ` +
+        `the run cursor ("${signature}") did not advance during the forced continuation. ` +
+        `RUN.md is untouched; resume with /ukit:handoff-fullstack or clear with /ukit:handoff-clear.`,
+    };
+  }
   if (streak !== null && streak > gate.maxStalledBlocks) {
     let predicateState = 'no ExitPredicate recorded';
     if (exitPredicate) {
@@ -1064,6 +1078,101 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   return { kind: 'block', reason: lines.join('\n') };
 }
 
+// ─── Explicit user interruption (pause / cancel) ──────────────────────────
+// A Stop must never be forced while the USER has paused or cancelled the run:
+// every lane (completion, watchdog, handoff-cursor) would otherwise bounce the
+// agent's "PAUSED" reply back as "CONTINUE IMMEDIATELY". The signal is read ONLY
+// from genuine user turns in the host-authored transcript — never from the agent's
+// own words, tool output, sub-agent reports or hook feedback (all skipped). The
+// latest pause/cancel-vs-resume turn wins; neutral turns (questions, health
+// checks) keep the earlier state; an unreadable/over-budget scan is "no
+// interruption" so enforcement is never relaxed by a lost read.
+export const INTERRUPT_SCAN_BUDGET_MS = 800;
+export const INTERRUPT_SCAN_MAX_BYTES = 8 * 1024 * 1024;
+const INTERRUPT_MAX_TEXT = 240;
+const WORD_END = '(?![\\p{L}\\p{N}])';
+const CANCEL_RE = new RegExp(`^(?:please\\s+)?(?:cancel|abort)${WORD_END}|^(?:hủy|huỷ|huy)${WORD_END}`, 'iu');
+const PAUSE_RE = new RegExp(
+  `^(?:please\\s+)?(?:pause|halt|stop|hold\\s+(?:on|off))${WORD_END}`
+  + `|^(?:tạm\\s+dừng|tạm\\s+ngưng|tạm\\s+ngừng|tam\\s+dung|dừng(?:\\s+lại)?|dung\\s+lai|ngừng)${WORD_END}`,
+  'iu',
+);
+const RESUME_RE = new RegExp(
+  `^(?:please\\s+)?(?:continue|resume|proceed|unpause|go\\s+on|carry\\s+on)${WORD_END}`
+  + `|^(?:tiếp\\s+tục|tiep\\s+tuc)${WORD_END}`,
+  'iu',
+);
+const SYNTHETIC_USER_PREFIX = /^(?:<system-reminder|<task-notification|<local-command|<user-prompt-submit-hook|Stop hook feedback|\[ukit|Caveat:|\[Request interrupted)/i;
+const RESUME_COMMAND_TAG = /^<command-name>\/?(?:ukit:)?handoff-(?:fullstack|implement)(?![\w-])/;
+
+function genuineUserText(entry) {
+  if (!entry || entry.type !== 'user' || entry.isSidechain === true || entry.isMeta === true) return null;
+  const msg = entry.message;
+  if (!msg || msg.role !== 'user') return null;
+  let text = '';
+  if (typeof msg.content === 'string') {
+    text = msg.content;
+  } else if (Array.isArray(msg.content)) {
+    for (const b of msg.content) {
+      if (!b || typeof b !== 'object') continue;
+      if (b.type === 'tool_result') return null;
+      if (b.type === 'text' && typeof b.text === 'string') text += (text ? '\n' : '') + b.text;
+    }
+  } else {
+    return null;
+  }
+  text = text.trim();
+  if (!text || SYNTHETIC_USER_PREFIX.test(text)) return null;
+  return text;
+}
+
+/**
+ * @returns {Promise<{ kind: 'pause'|'cancel'|null }>} Newest decisive genuine user
+ * turn: pause/cancel → interrupted; resume → not interrupted; none → not interrupted.
+ */
+export async function detectUserInterruption(transcriptPath, {
+  budgetMs = INTERRUPT_SCAN_BUDGET_MS,
+  maxBytes = INTERRUPT_SCAN_MAX_BYTES,
+} = {}) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return { kind: null };
+  let handle;
+  try {
+    handle = await fs.open(transcriptPath, 'r');
+    const size = Number((await handle.stat()).size) || 0;
+    const start = Math.max(0, size - maxBytes);
+    const deadline = Date.now() + budgetMs;
+    const buf = Buffer.allocUnsafe(size - start);
+    let got = 0;
+    while (got < buf.length) {
+      if (Date.now() > deadline) return { kind: null };
+      const { bytesRead } = await handle.read(buf, got, buf.length - got, start + got);
+      if (!bytesRead) break;
+      got += bytesRead;
+    }
+    let lines = buf.toString('utf8', 0, got).split('\n');
+    if (start > 0) lines = lines.slice(1);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      if (Date.now() > deadline) return { kind: null };
+      const line = lines[i];
+      if (!line || !line.includes('"user"') || line.includes('"tool_result"')) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      const text = genuineUserText(entry);
+      if (text === null) continue;
+      if (RESUME_COMMAND_TAG.test(text)) return { kind: null };
+      if (text.length > INTERRUPT_MAX_TEXT) continue;
+      if (CANCEL_RE.test(text)) return { kind: 'cancel' };
+      if (PAUSE_RE.test(text)) return { kind: 'pause' };
+      if (RESUME_RE.test(text)) return { kind: null };
+    }
+    return { kind: null };
+  } catch {
+    return { kind: null };
+  } finally {
+    try { await handle?.close(); } catch {}
+  }
+}
+
 // ─── Once-per-stop guard ──────────────────────────────────────────────────
 /**
  * Lock-scoped dedupe: persist `{ lastStop: { key, ts } }` and report whether this
@@ -1124,6 +1233,27 @@ export async function runStopCoordinator({
     return { skip: 'duplicate Stop invocation for this session inside the dedupe window', merged: null };
   }
 
+  // User pause/cancel outranks every lane: release, change nothing (RUN.md, tasks,
+  // branches, worktrees stay as they are so the run can be resumed).
+  const interruption = await detectUserInterruption(
+    typeof payload?.transcript_path === 'string' ? payload.transcript_path : null,
+  );
+  if (interruption.kind) {
+    return {
+      skip: null,
+      merged: {
+        decision: null,
+        reason: undefined,
+        systemMessage:
+          `[ukit-stop-coordinator] stop allowed: the user requested ${interruption.kind}. ` +
+          `No verification or continuation is forced; run state is preserved. ` +
+          `Resume by asking to continue (or /ukit:handoff-fullstack).`,
+        policyOwner: 'user-interruption',
+        policies: ['user-interruption'],
+      },
+    };
+  }
+
   let completion = null;
   const failures = {};
   try {
@@ -1149,6 +1279,7 @@ export async function runStopCoordinator({
       now,
       lockBudgetMs,
       transcriptPath: typeof payload?.transcript_path === 'string' ? payload.transcript_path : null,
+      stopHookActive: payload?.stop_hook_active === true,
     });
   } catch (error) {
     failures.handoff = error?.message || String(error);