@bglocation/tune-context 2.3.1 → 2.4.0

package/eval/prompt-metrics.mjs

@@ -0,0 +1,718 @@
+#!/usr/bin/env node
+// prompt-metrics — Claude Code transcripts → one JSONL row per prompt: time,
+// tokens (split by cache class), model/effort, tools, delegations. The raw
+// components EPIC-009 prices in TASK-086 and compares per arm in TASK-089.
+// See tasks/TASK-085.
+//
+// Why the transcript and not a hook: in the "tune-context off" arm our hooks do
+// not run, so hook instrumentation cannot measure the reference arm — by
+// construction. The transcript is written by Claude Code itself, so it is the
+// only source that works in BOTH arms. It also already exists for past sessions,
+// which is why this task runs first in the epic: baseline before any switch.
+//
+// Honest scope (the CLI prints the same facts to stderr on every run):
+//   • `list_cost_usd` (eval/pricing.mjs, TASK-086) is API LIST PRICE for these
+//     tokens — NOT a bill. A Pro/Max subscription charges its flat fee and this
+//     figure is what the same work would have cost through the API. A model
+//     missing from the price table yields null and an `unpriced` count, never a
+//     zero.
+//   • Server-side tool use is billed per request, not per token, so it is not
+//     inside list_cost_usd. Web search costs $10/1000; web FETCH is free. Both
+//     counts ride on the row. Zero on all data measured so far.
+//   • Subagent turns are NOT in the parent transcript. Measured 2026-07-30:
+//     29 transcripts, 21 `Agent` tool calls, ZERO isSidechain entries. Their
+//     cost is UNCAPTURED, not zero. `agent_spawns` is the only trace of it in
+//     the data, so it is always counted; `sidechain_turns` is counted too, so
+//     the blind spot closes by itself if a future Claude Code starts writing
+//     those entries (EPIC-009, error class 3).
+//   • `<synthetic>` assistant entries are generated by Claude Code, not billed
+//     by the API. They are excluded from tokens/turns and counted separately —
+//     an unbillable entry, not TASK-086's "unknown model".
+//
+// The `usage` reading here deliberately does NOT share code with
+// hooks/context-reminder.mjs, which also parses it. That hook answers "how big
+// is the context right now" and sums the three input classes into one number;
+// this file must keep them apart, because they are priced at 1x / 0.1x /
+// 1.25x-2x. One helper serving both would have to pick a side. (A hook also
+// cannot import from eval/ — only hooks/ is installed.)
+import { createReadStream, existsSync, readdirSync, statSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { claudeBaseDir } from '../hooks/config-dir.mjs';
+import { experimentPaths, readLedger } from '../cli/experiment.mjs';
+import { annotateRows, formatArmSummary } from './arm.mjs';
+import { formatCostLines, priceRow, summarizeCost } from './pricing.mjs';
+
+// Tool names that spawn a subagent. `Agent` is what this Claude Code writes
+// (measured); `Task` is the name the same tool carried in earlier versions.
+// Both are counted so a version change cannot silently zero the delegation
+// count — the one number that lets TASK-089 say "uncaptured" instead of nothing.
+const AGENT_TOOLS = new Set(['Agent', 'Task']);
+
+// Model string Claude Code puts on entries it generated itself (interrupts,
+// local notices). Never an API call, never a cost.
+const SYNTHETIC_MODEL = '<synthetic>';
+
+const USAGE = `
+prompt-metrics — per-prompt time/token/tool metrics from Claude Code transcripts.
+
+Usage:
+  prompt-metrics [--transcript <path>]... [--dir <path>]
+
+Options:
+  --transcript <path>  A single .jsonl transcript. Repeatable.
+  --dir <path>         Directory of transcripts, scanned one level deep. Used
+                       together with --transcript, the two are unioned.
+                       (default when neither is given: <config dir>/projects,
+                       where <config dir> is $CLAUDE_CONFIG_DIR if set,
+                       else ~/.claude)
+  -h, --help           Show this help
+
+Writes JSONL to stdout, one row per prompt. A run summary — including how many
+entries could NOT be attributed to a prompt, and how many rows carry a model the
+price table does not know — goes to stderr, so stdout stays a clean data channel.
+
+Rows from a branch shaped exp/<task>/<arm> (the paired measurement, TASK-088)
+also carry:
+  exp_task, exp_arm        the arm, resolved — '' when it could not be resolved
+  exp_arm_source           branch+ledger | branch | none | conflict:<why>
+  exp_ledger_arm           what the TASK-087 ledger said, whenever it resolved —
+                           on agreement too, so a confirmation can be audited
+  pass_order               1 for the arm run first in that task, 2 for the second
+The branch says which arm was INTENDED, the ledger which was SET; a disagreement
+leaves the arm unresolved rather than picking a winner.
+
+These five fields are added here, in the CLI. Rows obtained through the module
+(aggregate, collectFiles) carry the measurement only — call annotateRows from
+eval/arm.mjs to add the arm.
+`.trim();
+
+/** Parse one transcript line. Returns null for blanks, junk, or non-objects. */
+export function parseEntry(line) {
+  const t = typeof line === 'string' ? line.trim() : '';
+  if (t === '') return null;
+  try {
+    const o = JSON.parse(t);
+    return o && typeof o === 'object' && !Array.isArray(o) ? o : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every entry of a transcript, malformed lines dropped. Pure over text — the
+ * I/O-free seam tests use. Real runs go through readLines()/collectFiles()
+ * instead, which never hold the whole file (see readLines).
+ */
+export function parseEntries(text) {
+  const out = [];
+  for (const line of text.split('\n')) {
+    const e = parseEntry(line);
+    if (e !== null) out.push(e);
+  }
+  return out;
+}
+
+function msOf(entry) {
+  const t = Date.parse(entry?.timestamp);
+  return Number.isNaN(t) ? null : t;
+}
+
+function isoOrNull(ms) {
+  return ms === null ? null : new Date(ms).toISOString();
+}
+
+/** Elapsed seconds, 1ms precision; null when either end is unknown. */
+function seconds(fromMs, toMs) {
+  if (fromMs === null || toMs === null) return null;
+  return Math.round(toMs - fromMs) / 1000;
+}
+
+// A prompt may span several models/efforts/tiers (measured: one session carried
+// claude-opus-5, claude-sonnet-5 and <synthetic>; effort took high/xhigh/max).
+// The row keeps a single scalar for the common case and the literal string
+// 'mixed' otherwise — never an average, never a silent first-wins. The full
+// distinct set rides alongside (`models`, `efforts`) so 'mixed' is decodable
+// and by_model below still prices the row exactly.
+function collapse(set) {
+  if (set.size === 0) return null;
+  if (set.size === 1) return [...set][0];
+  return 'mixed';
+}
+
+function emptyTokens() {
+  return {
+    input_tokens: 0,
+    cache_read: 0,
+    cache_write_5m: 0,
+    cache_write_1h: 0,
+    // Cache-creation tokens the entry did NOT break down by TTL. Kept separate
+    // rather than folded into 5m: the write multipliers differ (1.25× vs 2×),
+    // so guessing a TTL here would quietly invent up to 60% of a cost line.
+    // Zero on every entry measured so far; if it ever isn't, TASK-086 sees it.
+    cache_write_unsplit: 0,
+    output_tokens: 0,
+  };
+}
+
+function addUsage(into, usage) {
+  const created = usage.cache_creation_input_tokens || 0;
+  const m5 = usage.cache_creation?.ephemeral_5m_input_tokens || 0;
+  const h1 = usage.cache_creation?.ephemeral_1h_input_tokens || 0;
+  into.input_tokens += usage.input_tokens || 0;
+  into.cache_read += usage.cache_read_input_tokens || 0;
+  into.cache_write_5m += m5;
+  into.cache_write_1h += h1;
+  into.cache_write_unsplit += Math.max(0, created - m5 - h1);
+  into.output_tokens += usage.output_tokens || 0;
+}
+
+function newPrompt({ promptId, session }) {
+  return {
+    promptId,
+    session,
+    cwd: null,
+    gitBranch: null,
+    gitBranchChanged: false,
+    ccVersion: null,
+    tsSubmit: null,
+    tsFirstAssistant: null,
+    tsEnd: null,
+    lastTs: null,
+    maxGap: 0,
+    models: new Set(),
+    efforts: new Set(),
+    speeds: new Set(),
+    tiers: new Set(),
+    // Data residency: `us` costs 1.1x across every token class (Claude 4.6+).
+    geos: new Set(),
+    apiTurns: 0,
+    syntheticTurns: 0,
+    // No flat token totals here on purpose: the row's input_tokens/cache_*/
+    // output_tokens are DERIVED from byModel in toRow(). Two accumulators fed
+    // from the same usage block are two things that can drift, and the drift
+    // would show up as a cost that does not match its own breakdown.
+    byModel: new Map(),
+    // Turns whose `usage.iterations` says more was spent than the top-level
+    // `usage` reports — see usageUnderstated(). Known underestimation, counted
+    // rather than corrected (TASK-086).
+    multiAttemptTurns: 0,
+    understatedTurns: 0,
+    // Split because they are billed differently: web search is $10/1000, web
+    // fetch is free. Counting them together priced free requests.
+    webSearchRequests: 0,
+    webFetchRequests: 0,
+    tools: new Map(),
+    toolCalls: 0,
+    agentSpawns: 0,
+    sidechainTurns: 0,
+    promptChars: null,
+  };
+}
+
+/** Sum over whatever classes emptyTokens() defines — a new class cannot slip
+ *  out of this total by being forgotten in a hand-written list. */
+function totalTokens(t) {
+  return Object.values(t).reduce((a, b) => a + b, 0);
+}
+
+/**
+ * `usage.iterations` is a per-attempt breakdown that appears when a request was
+ * retried or fell back to another model. It is NOT summed with the top-level
+ * `usage`, which describes only the attempt that answered — adding both counts
+ * the same tokens twice. `usage` is the source, full stop; addUsage() reads
+ * named fields only, so it cannot drift into iterations by accident.
+ *
+ * That rule has a price: when the attempts spent more than the top level
+ * reports, the row understates. So the condition is measured rather than
+ * assumed — if the iterations add up to more than the top level, the turn is
+ * counted here and the run says so.
+ *
+ * Measured over 29 transcripts (16 931 usage blocks carrying `iterations`):
+ * 0 blocks with more than one attempt, but 3 where the top-level usage is all
+ * zeros while the single iteration carries real tokens (228k cache reads in one
+ * case). TASK-086 assumed this counter would stay at zero; it does not.
+ */
+function usageUnderstated(usage) {
+  const its = Array.isArray(usage.iterations) ? usage.iterations : [];
+  if (its.length === 0) return false;
+  const top = emptyTokens();
+  addUsage(top, usage);
+  const attempts = emptyTokens();
+  for (const it of its) addUsage(attempts, it);
+  return totalTokens(attempts) > totalTokens(top);
+}
+
+/** Identity fields, from the first entry of the turn that carries each one. */
+function applyIdentity(p, entry) {
+  if (p.cwd === null && typeof entry.cwd === 'string') p.cwd = entry.cwd;
+  if (p.ccVersion === null && typeof entry.version === 'string') p.ccVersion = entry.version;
+  // gitBranch is the ARM marker in the paired measurement (TASK-088), not
+  // decoration, so a change of branch inside one turn is flagged rather than
+  // averaged away — 19 of 495 turns in the live run.
+  if (typeof entry.gitBranch === 'string') {
+    if (p.gitBranch === null) p.gitBranch = entry.gitBranch;
+    else if (p.gitBranch !== entry.gitBranch) p.gitBranchChanged = true;
+  }
+}
+
+/** Turn boundaries and the longest silence inside them. */
+function applyTiming(p, entry, isAssistant) {
+  const ts = msOf(entry);
+  if (ts === null) return;
+  if (p.tsSubmit === null || ts < p.tsSubmit) p.tsSubmit = ts;
+  if (p.tsEnd === null || ts > p.tsEnd) p.tsEnd = ts;
+  if (isAssistant && (p.tsFirstAssistant === null || ts < p.tsFirstAssistant)) p.tsFirstAssistant = ts;
+  // Largest silence between two consecutive entries of this turn. Same rule as
+  // the queued_s/work_s split, applied INSIDE the turn: a tool call waiting on
+  // a permission prompt is the user's time, not the tool's, and it lands in
+  // work_s indistinguishably. Not hypothetical — the live run over 29
+  // transcripts has a turn with work_s = 158999 (44 h). Measured here, judged
+  // in TASK-089: this file reports, it does not filter.
+  if (p.lastTs !== null && ts > p.lastTs) {
+    p.maxGap = Math.max(p.maxGap, ts - p.lastTs);
+    p.lastTs = ts;
+  } else if (p.lastTs === null) {
+    p.lastTs = ts;
+  }
+}
+
+/**
+ * prompt_chars: what the USER sent. The first non-meta user entry that is not a
+ * tool result — later user entries in the group ARE tool results (934 of 1012
+ * in the measured session) and are not the prompt.
+ */
+function applyUserEntry(p, entry) {
+  if (p.promptChars !== null || entry.isMeta === true) return;
+  const content = entry.message?.content;
+  if (typeof content === 'string') p.promptChars = content.length;
+  else if (Array.isArray(content) && !content.some((b) => b?.type === 'tool_result')) {
+    p.promptChars = content.reduce((n, b) => n + (b?.type === 'text' ? (b.text?.length ?? 0) : 0), 0);
+  }
+}
+
+/** Tools, delegations, model/effort, and the per-model token split. */
+function applyAssistantEntry(p, entry, { usage, model, synthetic }) {
+  for (const block of Array.isArray(entry.message?.content) ? entry.message.content : []) {
+    if (block?.type !== 'tool_use') continue;
+    const name = typeof block.name === 'string' ? block.name : '(unknown)';
+    p.tools.set(name, (p.tools.get(name) ?? 0) + 1);
+    p.toolCalls++;
+    if (AGENT_TOOLS.has(name)) p.agentSpawns++;
+  }
+
+  // Counted, then dropped from every billing figure: Claude Code wrote it, the
+  // API did not bill it.
+  if (synthetic) {
+    p.syntheticTurns++;
+    return;
+  }
+
+  p.apiTurns++;
+  if (model) p.models.add(model);
+  if (typeof entry.effort === 'string') p.efforts.add(entry.effort);
+  if (!usage) return;
+  if (typeof usage.speed === 'string') p.speeds.add(usage.speed);
+  if (typeof usage.service_tier === 'string') p.tiers.add(usage.service_tier);
+  if (typeof usage.inference_geo === 'string') p.geos.add(usage.inference_geo);
+  // Per-model split, so a turn that switched models is still priceable exactly
+  // instead of being charged at one model's rate (error class 4). The row's
+  // flat totals are folded back out of this in toRow() — one source, no drift.
+  const key = model ?? '(unknown)';
+  if (!p.byModel.has(key)) p.byModel.set(key, { api_turns: 0, ...emptyTokens() });
+  const bucket = p.byModel.get(key);
+  bucket.api_turns++;
+  addUsage(bucket, usage);
+
+  if (Array.isArray(usage.iterations) && usage.iterations.length > 1) p.multiAttemptTurns++;
+  if (usageUnderstated(usage)) p.understatedTurns++;
+  // Billed per request, not per token, so they sit outside list_cost_by_class.
+  // Counted so the gap announces itself instead of hiding in a clean total.
+  const server = usage.server_tool_use;
+  if (server) {
+    p.webSearchRequests += server.web_search_requests || 0;
+    p.webFetchRequests += server.web_fetch_requests || 0;
+  }
+}
+
+/**
+ * Streaming aggregator. One accumulator per turn, fed entry by entry in file
+ * order, so the caller never has to materialize a transcript (criterion 4).
+ *
+ * Attribution: `promptId` sits on `user` entries only — including the tool
+ * RESULTS, which come back as `user` entries, so it groups the whole turn.
+ * `assistant` entries carry no promptId and are resolved by walking `parentUuid`
+ * to the nearest ancestor that has one (2517/2517 in the measured session).
+ * The walk is O(1) per entry because every uuid seen is memoized with the group
+ * it resolved to, and parents always precede children in the file.
+ *
+ * Entries of ANY type are memoized, not just user/assistant: a `system` or
+ * `attachment` entry can sit in the middle of a chain, and skipping it would
+ * break the link for everything below it.
+ *
+ * An entry that resolves to nothing is counted into `unattributed` — with its
+ * tokens — and reported. Silently dropping it is the failure this file exists
+ * to avoid (criterion 2).
+ */
+export function createCollector() {
+  // Keyed by (session, promptId), never by promptId alone. Nothing documents
+  // promptId as globally unique — it is unique across the 29 local transcripts,
+  // which is a property of that sample, not of the format. If two sessions ever
+  // shared one, keying on it alone would merge their rows, and since the arm is
+  // a property of the SESSION (EPIC-009, error class 6) that merge would blend
+  // two arms into a single row and look like ordinary data.
+  const prompts = new Map(); // key -> accumulator, in first-seen order
+  const groups = new Map(); // key -> {key, promptId, session}, shared by memoized uuids
+  let uuidGroup = new Map(); // uuid -> group | null; reset per file (see beginFile)
+  const unattributed = { entries: 0, turns: 0, ...emptyTokens() };
+  const totals = { malformed: 0, entries: 0, files: 0 };
+
+  function groupFor(entry) {
+    // Direct: `user` entries (prompt AND tool results) carry promptId.
+    const promptId = entry.promptId;
+    if (typeof promptId === 'string' && promptId !== '') {
+      const session = typeof entry.sessionId === 'string' ? entry.sessionId : null;
+      const key = `${session ?? ''}\u0000${promptId}`;
+      let group = groups.get(key);
+      if (!group) {
+        group = { key, promptId, session };
+        groups.set(key, group);
+      }
+      return group;
+    }
+    // Inherited: nearest ancestor with one. Ancestors are already memoized, and
+    // a memoized `null` correctly propagates "unattributable" down the chain.
+    const parent = entry.parentUuid;
+    return typeof parent === 'string' ? (uuidGroup.get(parent) ?? null) : null;
+  }
+
+  function addEntry(entry) {
+    totals.entries++;
+    const group = groupFor(entry);
+    // Memoize BEFORE any type filtering: unknown types are links in the chain
+    // even when they carry no metric of their own.
+    if (typeof entry.uuid === 'string') uuidGroup.set(entry.uuid, group);
+
+    const type = entry.type;
+    const isAssistant = type === 'assistant';
+    // Everything else in a live transcript — queue-operation, ai-title,
+    // file-history-snapshot/delta, last-prompt, attachment, system, mode —
+    // carries no per-prompt metric. Skipped, never fatal.
+    if (type !== 'user' && !isAssistant) return;
+
+    const usage = entry.message?.usage;
+    const model = entry.message?.model ?? null;
+    const synthetic = isAssistant && model === SYNTHETIC_MODEL;
+
+    if (group === null) {
+      unattributed.entries++;
+      if (isAssistant && !synthetic) {
+        unattributed.turns++;
+        if (usage) addUsage(unattributed, usage);
+      }
+      return;
+    }
+
+    // Created here, not in groupFor(): an entry of an unknown type must never
+    // conjure a row of zeros just by carrying a promptId.
+    let p = prompts.get(group.key);
+    if (!p) {
+      p = newPrompt(group);
+      prompts.set(group.key, p);
+    }
+
+    applyIdentity(p, entry);
+    applyTiming(p, entry, isAssistant);
+    if (entry.isSidechain === true && isAssistant) p.sidechainTurns++;
+    if (isAssistant) applyAssistantEntry(p, entry, { usage, model, synthetic });
+    else applyUserEntry(p, entry);
+  }
+
+  function addLine(line) {
+    const entry = parseEntry(line);
+    // A truncated or corrupted line costs exactly that line (criterion 3): a
+    // transcript is appended to live, so the last line can be half-written at
+    // any moment. Counted, so a run over garbage doesn't look like a clean run.
+    if (entry === null) {
+      if (typeof line === 'string' && line.trim() !== '') totals.malformed++;
+      return;
+    }
+    addEntry(entry);
+  }
+
+  function toRow(p) {
+    const queued_s = seconds(p.tsSubmit, p.tsFirstAssistant);
+    const work_s = seconds(p.tsFirstAssistant, p.tsEnd);
+    // Flat totals are the fold of the per-model split, not a second running
+    // sum: EPIC-009 criterion 2 forbids printing a token figure that disagrees
+    // with its own breakdown, and the cheapest way to guarantee that is to have
+    // only one number to disagree with.
+    const tokens = emptyTokens();
+    for (const bucket of p.byModel.values()) {
+      for (const field of Object.keys(tokens)) tokens[field] += bucket[field];
+    }
+    const row = {
+      promptId: p.promptId,
+      session: p.session,
+      cwd: p.cwd,
+      // Always written, empty string included: an absent arm marker is data
+      // (TASK-088), and a row that omits the field would be indistinguishable
+      // from a row the parser failed on.
+      gitBranch: p.gitBranch ?? '',
+      gitBranchChanged: p.gitBranchChanged,
+      cc_version: p.ccVersion,
+      ts_submit: isoOrNull(p.tsSubmit),
+      ts_first_assistant: isoOrNull(p.tsFirstAssistant),
+      ts_end: isoOrNull(p.tsEnd),
+      // Split deliberately. A single duration measured from submission swallows
+      // queue wait — 84 `enqueue` events in one measured session — and that is
+      // the user's time, not the tool's. TASK-089 compares work_s.
+      queued_s,
+      work_s,
+      max_gap_s: p.maxGap / 1000,
+      model: collapse(p.models),
+      models: [...p.models].sort(),
+      effort: collapse(p.efforts),
+      efforts: [...p.efforts].sort(),
+      speed: collapse(p.speeds),
+      service_tier: collapse(p.tiers),
+      inference_geo: collapse(p.geos),
+      api_turns: p.apiTurns,
+      synthetic_turns: p.syntheticTurns,
+      ...tokens,
+      by_model: Object.fromEntries([...p.byModel.entries()].sort((a, b) => a[0].localeCompare(b[0]))),
+      tools: Object.fromEntries([...p.tools.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))),
+      tool_calls_total: p.toolCalls,
+      agent_spawns: p.agentSpawns,
+      sidechain_turns: p.sidechainTurns,
+      multi_attempt_turns: p.multiAttemptTurns,
+      understated_turns: p.understatedTurns,
+      web_search_requests: p.webSearchRequests,
+      web_fetch_requests: p.webFetchRequests,
+      prompt_chars: p.promptChars ?? 0,
+    };
+    // Priced from the row that was just built, so the dollars can only ever be
+    // a function of the published components — nothing is billed that the row
+    // does not also show (EPIC-009 criterion 2). Priced at the prompt's own
+    // timestamp, so re-running this next year yields the same money.
+    return { ...row, ...priceRow(row) };
+  }
+
+  return {
+    addLine,
+    addEntry,
+    /**
+     * Start of a new transcript. Drops the uuid index, because a parentUuid
+     * chain never crosses a file — so keeping it would only let one file's uuid
+     * capture another file's entry, and would grow the index across a whole
+     * scan (17 403 uuids over the 29 local transcripts) for no gain. The
+     * per-turn accumulators survive: rows accumulate across files by design.
+     */
+    beginFile() {
+      totals.files++;
+      uuidGroup = new Map();
+    },
+    result() {
+      const rows = [...prompts.values()].map(toRow);
+      const sum = (field) => rows.reduce((n, r) => n + r[field], 0);
+      const tokens = emptyTokens();
+      for (const row of rows) for (const field of Object.keys(tokens)) tokens[field] += row[field];
+      return {
+        rows,
+        // Reported on every run, never inferred from `rows` being short.
+        unattributed,
+        tokens,
+        cost: summarizeCost(rows),
+        totals: {
+          ...totals,
+          prompts: rows.length,
+          agent_spawns: sum('agent_spawns'),
+          sidechain_turns: sum('sidechain_turns'),
+          synthetic_turns: sum('synthetic_turns'),
+          multi_attempt_turns: sum('multi_attempt_turns'),
+          understated_turns: sum('understated_turns'),
+          web_search_requests: sum('web_search_requests'),
+          web_fetch_requests: sum('web_fetch_requests'),
+        },
+      };
+    },
+  };
+}
+
+/** Convenience wrapper for tests and small inputs: entries in, result out. */
+export function aggregate(entries) {
+  const c = createCollector();
+  for (const entry of entries) c.addEntry(entry);
+  return c.result();
+}
+
+export function formatRow(row) {
+  return JSON.stringify(row);
+}
+
+/**
+ * Human-readable run summary. Goes to stderr so stdout stays parseable JSONL.
+ * Names the two things that are NOT in the numbers — unattributed entries and
+ * the uncaptured cost of delegation — because a summary that only reports what
+ * it measured is how a blind spot becomes a clean-looking result.
+ */
+export function formatSummary({ totals, unattributed, cost, tokens }) {
+  const L = [];
+  L.push(
+    `prompt-metrics: ${totals.prompts} prompt(s) from ${totals.entries} entries` +
+      ` in ${totals.files} transcript(s)` +
+      (totals.malformed > 0 ? `; ${totals.malformed} malformed line(s) skipped` : ''),
+  );
+  L.push(
+    `  unattributed entries: ${unattributed.entries}` +
+      ` (${unattributed.turns} API turn(s), ${unattributed.output_tokens} output tokens) — not in any row`,
+  );
+  L.push(
+    `  subagent spawns: ${totals.agent_spawns}; sidechain turns in transcript: ${totals.sidechain_turns}` +
+      (totals.agent_spawns > 0 && totals.sidechain_turns === 0
+        ? ' — subagent cost is UNCAPTURED, not zero (EPIC-009 class 3)'
+        : ''),
+  );
+  if (totals.synthetic_turns > 0) {
+    L.push(`  <synthetic> turns excluded from tokens/turns: ${totals.synthetic_turns}`);
+  }
+  if (cost) L.push(...formatCostLines(cost, tokens));
+  if (totals.understated_turns > 0 || totals.multi_attempt_turns > 0) {
+    L.push(
+      `  turns where usage.iterations exceeds the reported usage: ${totals.understated_turns}` +
+        ` (${totals.multi_attempt_turns} with >1 attempt) — cost above is a known UNDERestimate`,
+    );
+  }
+  return L.join('\n');
+}
+
+/**
+ * Lines of a file, without ever holding more than a buffer of it. Transcripts
+ * reach tens of MB (16.6MB locally), and a tool whose own footprint grows with
+ * session length is the cost curve this project exists to fight — the same rule
+ * the context-reminder hook follows with readTail(). That hook needs only the
+ * tail; here every line matters, so it is a line stream rather than a slice.
+ */
+export async function* readLines(path) {
+  const rl = createInterface({ input: createReadStream(path, 'utf8'), crlfDelay: Infinity });
+  try {
+    for await (const line of rl) yield line;
+  } finally {
+    rl.close();
+  }
+}
+
+export async function collectFiles(paths, collector = createCollector()) {
+  for (const path of paths) {
+    collector.beginFile();
+    for await (const line of readLines(path)) collector.addLine(line);
+  }
+  return collector;
+}
+
+/** Transcripts directly in `dir` or in its immediate subdirectories, sorted. */
+export function findTranscripts(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  const visit = (base, depth) => {
+    let names;
+    try {
+      names = readdirSync(base);
+    } catch {
+      return; // unreadable dir — skip, never fatal
+    }
+    for (const name of names.sort()) {
+      const full = join(base, name);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        if (depth > 0) visit(full, depth - 1);
+      } else if (name.endsWith('.jsonl')) {
+        out.push(full);
+      }
+    }
+  };
+  visit(dir, 1);
+  return out;
+}
+
+function defaultDir() {
+  return join(claudeBaseDir(), 'projects');
+}
+
+async function main() {
+  let paths;
+  try {
+    const { values } = parseArgs({
+      args: process.argv.slice(2),
+      options: {
+        transcript: { type: 'string', multiple: true },
+        dir: { type: 'string' },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+    });
+    if (values.help) {
+      process.stdout.write(`${USAGE}\n`);
+      return;
+    }
+    // Both flags together are a UNION, deduplicated, not a precedence rule:
+    // silently ignoring one of two flags the user passed is how a run measures
+    // something other than what was asked for.
+    const explicit = values.transcript ?? [];
+    const scanned = values.dir !== undefined || explicit.length === 0 ? findTranscripts(values.dir ?? defaultDir()) : [];
+    paths = [...new Set([...explicit, ...scanned])];
+    const missing = paths.filter((p) => !existsSync(p));
+    if (missing.length > 0) {
+      // Same shape as adoption-report's missing-log case: say where it looked,
+      // change nothing else, exit 0. Note goes to stderr because stdout here is
+      // a data channel, not a report.
+      for (const p of missing) process.stderr.write(`prompt-metrics: no transcript at ${p}\n`);
+      paths = paths.filter((p) => existsSync(p));
+    }
+    if (paths.length === 0) {
+      process.stderr.write(
+        `prompt-metrics: no transcripts found in ${values.dir ?? defaultDir()}.\n` +
+          '(Claude Code writes them to <config dir>/projects/<slug>/<session>.jsonl.)\n',
+      );
+      return;
+    }
+  } catch (e) {
+    process.stderr.write(`prompt-metrics: ${e.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Piping into `head` closes stdout early; that is a normal end, not a crash.
+  process.stdout.on('error', (e) => {
+    if (e.code !== 'EPIPE') throw e;
+  });
+
+  const collector = await collectFiles(paths);
+  const result = collector.result();
+
+  // The arm is added here, not in the collector: the collector turns a
+  // transcript into rows and has no business knowing about the experiment, and
+  // the ledger is machine state rather than transcript content. The split also
+  // lets the same rules run over rows collected elsewhere (TASK-088).
+  const ledgerPath = experimentPaths(claudeBaseDir()).ledgerPath;
+  const ledgerAvailable = existsSync(ledgerPath);
+  const rows = annotateRows(result.rows, {
+    ledger: ledgerAvailable ? readLedger(claudeBaseDir()) : [],
+    ledgerAvailable,
+  });
+
+  for (const row of rows) process.stdout.write(`${formatRow(row)}\n`);
+  process.stderr.write(`${formatSummary(result)}\n`);
+  const arms = formatArmSummary(rows);
+  if (arms !== null) process.stderr.write(`${arms}\n`);
+}
+
+if (process.argv[1] && process.argv[1].endsWith('prompt-metrics.mjs')) {
+  await main();
+}