@ngockhoale/ukit 3.4.24 → 3.4.25

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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`).

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.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,
+  };
+}

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/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);