@bglocation/tune-context 2.3.1 → 2.5.0

package/eval/prompt-metrics.mjs

@@ -0,0 +1,1046 @@
+#!/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. But the
+//     RESULT of an `Agent` call carries its own `usage` and `resolvedModel`, so
+//     the delegation is measurable FROM BELOW — see applyDelegation(). The row
+//     therefore reports two figures that are never added together: the parent
+//     session's cost, and `delegations[].list_cost_usd`, a lower bound on what
+//     the subagents cost (COST_EVALUATION_PROCEDURE §11a). `agent_spawns` and
+//     `sidechain_turns` are still counted, so the size of the remaining blind
+//     spot stays visible (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, formatUsd, priceRow, summarizeCost, webSearchCost } 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.
+
+Each row also carries delegations[]: one record per Agent call that returned its
+own usage, priced with the same table. That figure is a LOWER BOUND on what the
+subagents cost and is never added to the row's own cost.
+`.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;
+}
+
+/** The `tool_use` blocks an assistant entry carries, in block order. One reader
+ *  for the row path and the unattributed bucket both: what counts as a tool call
+ *  must not quietly become two slightly different answers. */
+function toolUseBlocks(entry) {
+  const content = Array.isArray(entry.message?.content) ? entry.message.content : [];
+  return content.filter((block) => block?.type === 'tool_use');
+}
+
+/** Server-side tool requests carried by a usage block, as plain counts.
+ *
+ *  Deliberately NOT folded into addUsage(): every field that function touches is
+ *  a token class priced PER TOKEN, and these are billed PER REQUEST, which is
+ *  why they sit outside list_cost_by_class on a row. addUsage also feeds the
+ *  usage.iterations comparison (where a request count would be compared against
+ *  token counts) and the per-model buckets published as `by_model` — a field
+ *  added there would surface in a row's token breakdown, which its own test
+ *  pins to exactly the five priced classes plus the unsplit one. So the shape of
+ *  `usage.server_tool_use` gets ONE reader instead, and the two accumulators
+ *  that need it keep their own field names. */
+function serverToolRequests(usage) {
+  const server = usage?.server_tool_use;
+  return {
+    search: server?.web_search_requests || 0,
+    fetch: server?.web_fetch_requests || 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,
+    // Keyed by agentId, because the same delegation result is written to
+    // SEVERAL transcript files (measured: 8 entries for 4 delegations). A list
+    // here would double the only figure we have for subagent cost.
+    delegations: new Map(),
+    delegationDuplicates: 0,
+    delegationsUnidentified: 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);
+  }
+}
+
+/**
+ * The subagent's own bill, off the `Agent` tool RESULT.
+ *
+ * A delegation leaves no turns in the parent transcript (0 `isSidechain`
+ * entries over the whole of `~/.claude/projects`), but the result entry carries
+ * `toolUseResult.usage` — the same structure as `message.usage`, cache split
+ * included — plus `resolvedModel`. So it is priced with the SAME `priceRow`
+ * that prices the parent turn: TASK-089 criterion 8 asks for no new pricing
+ * logic, and a second code path to dollars is a second set of prices.
+ *
+ * Three rules this obeys, all from COST_EVALUATION_PROCEDURE §11a:
+ *
+ *   • **Deduplicated by `agentId`.** The result entry is written twice (8
+ *     entries = 4 delegations, measured) — and, measured 2026-08-02, WITHIN one
+ *     file rather than across files as first assumed, sometimes under a
+ *     different `promptId`, which puts one delegation on two rows. The entry
+ *     dedup in addEntry() removes the byte-identical copies; this keeps the
+ *     guarantee for the ones it cannot see, i.e. copies with distinct uuids and
+ *     rows collected from more than one file.
+ *   • **A lower bound, not a cost.** `cache_read` grows LINEARLY with the
+ *     subagent's tool-call count (13 → 37.6k, 19 → 59.5k, 26 → 76.5k), which is
+ *     what one turn reading the whole accumulated context looks like — not a
+ *     sum over turns, which would grow quadratically. So this is most likely
+ *     the subagent's LAST turn. It rides on its own field and is never added to
+ *     the row's cost.
+ *   • **A result with no `agentId` is dropped, not guessed.** It cannot be
+ *     deduplicated, and a double-counted lower bound is worse than a smaller
+ *     one that is honest. Counted, so the omission is visible.
+ */
+function applyDelegation(p, entry, tsMs) {
+  const result = entry.toolUseResult;
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return;
+  const usage = result.usage;
+  if (!usage || typeof usage !== 'object') return;
+
+  const id = typeof result.agentId === 'string' ? result.agentId : '';
+  if (id === '') {
+    p.delegationsUnidentified++;
+    return;
+  }
+  if (p.delegations.has(id)) {
+    p.delegationDuplicates++;
+    return;
+  }
+
+  const tokens = emptyTokens();
+  addUsage(tokens, usage);
+  const model = typeof result.resolvedModel === 'string' ? result.resolvedModel : '';
+  // Shaped as a one-model row so priceRow answers about it unchanged — including
+  // the refusals: an unknown model, an unsplit cache write or a tier we cannot
+  // price yields `list_cost_usd: null` here for exactly the same reasons as on a
+  // parent turn, and lands in the same unpriced counter downstream.
+  const cost = priceRow(
+    {
+      by_model: { [model]: tokens },
+      speed: typeof usage.speed === 'string' ? usage.speed : null,
+      service_tier: usage.service_tier,
+      inference_geo: usage.inference_geo,
+    },
+    { at: tsMs },
+  );
+
+  p.delegations.set(id, {
+    agent_id: id,
+    agent_type: typeof result.agentType === 'string' ? result.agentType : '',
+    model,
+    status: typeof result.status === 'string' ? result.status : '',
+    duration_ms: Number.isFinite(result.totalDurationMs) ? result.totalDurationMs : null,
+    // The subagent's own tool calls — the quantity `cache_read` tracks linearly,
+    // i.e. the evidence for reading the figure above as a lower bound.
+    tool_calls_total: Number.isFinite(result.totalToolUseCount) ? result.totalToolUseCount : null,
+    ...tokens,
+    web_search_requests: usage.server_tool_use?.web_search_requests || 0,
+    ...cost,
+  });
+}
+
+/** Tools, delegations, model/effort, and the per-model token split. */
+function applyAssistantEntry(p, entry, { usage, model, synthetic, repeatOfResponse }) {
+  for (const block of toolUseBlocks(entry)) {
+    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;
+  }
+
+  // `usage` describes the RESPONSE, not the entry. One API response reaches the
+  // transcript as several entries — one per content block (thinking / text /
+  // each tool_use) — and every one of them carries an identical copy of the same
+  // usage block. The uuid dedup in addEntry() cannot see this class: those uuids
+  // differ by definition. Measured over 19 transcripts: 11 295 entries for 5 954
+  // responses = 1.90x on api_turns, and 2.02x on the dollar figure, because the
+  // per-class inflation is not flat (cache-read 1.82x, output 2.17x) — a
+  // many-block response is not a scaled copy of a one-block response.
+  //
+  // Not a constant that cancels in a ratio of two arms: the factor IS the number
+  // of content blocks per turn, i.e. how many tools the model reached for, which
+  // is the variable the doctrine sets out to move. Per-session spread on one
+  // project: 1.66x to 2.24x (error class 1 — a figure that prints like a fact).
+  //
+  // The tool_use loop above runs BEFORE this guard on purpose: tool_use blocks
+  // are NOT duplicated across a response's entries (6 403 blocks, 6 403 distinct
+  // ids, 0 repeats), so skipping the whole entry would drop ~2/3 of all tool
+  // calls and gut the adoption half of the analysis.
+  if (repeatOfResponse) 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 = serverToolRequests(usage);
+  p.webSearchRequests += server.search;
+  p.webFetchRequests += server.fetch;
+}
+
+/**
+ * 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,
+    // Counted for the same reason the rows count them: tool_calls is an
+    // ADOPTION metric — how often the model reached for a tool, i.e. the very
+    // variable the doctrine sets out to move — so an entry that lands outside
+    // every row must still show up in that denominator. `web_search_requests`
+    // is a different kind of thing: it is MONEY ($10/1000, billed per request),
+    // and money that counting the entry's tokens does not cover, because no
+    // token class prices it (TASK-093).
+    tool_calls: 0,
+    // A strict subset of tool_calls, tracked separately for the same reason the
+    // rows track it: agent_spawns is one half of how big the subagent blind spot
+    // is (error class 3), and a spawn nobody counted is a whole delegation whose
+    // cost we do not merely under-report — we never learn it happened.
+    agent_spawns: 0,
+    web_search_requests: 0,
+    web_fetch_requests: 0,
+    ...emptyTokens(),
+  };
+  // Identity of every API response already billed. NOT reset in beginFile, and
+  // deliberately unlike uuidGroup: a uuid chain cannot cross a file, but nothing
+  // promises the same about a response id, and a global set costs one string per
+  // response. Measured across the 19 guidetrackee transcripts: 0 of 5 954 ids
+  // appear in more than one file, so today the scope changes no figure — it only
+  // removes a way for a future transcript layout to reopen the bug silently.
+  const seenResponses = new Set();
+  const totals = { malformed: 0, entries: 0, duplicates: 0, responseRepeats: 0, responsesUnidentified: 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++;
+
+    // A transcript repeats entries VERBATIM, and not rarely: 11 296 of 36 463
+    // local entries (31%) carry a uuid already written earlier IN THE SAME FILE,
+    // 6 739 of them assistant turns with a usage block. The copies are identical
+    // apart from a cosmetic `slug` — same tokens, same model, same timestamp —
+    // so summing both charged 45% of all cache-read tokens and 42% of all output
+    // tokens twice. That is not a rounding error, it is the epic's whole effect
+    // size several times over (error class 1: a figure that prints like a fact).
+    //
+    // Scoped to the file on purpose: across the 34 local transcripts ZERO uuids
+    // are shared between files, so the index that already exists per file
+    // (uuidGroup, dropped in beginFile) is exactly the right one to ask. First
+    // occurrence wins — file order is event order, and a later copy carrying a
+    // different promptId is the copy, not the event.
+    //
+    // Counted, never silent: a run over a transcript that suddenly stops
+    // repeating itself must show that too.
+    if (typeof entry.uuid === 'string' && uuidGroup.has(entry.uuid)) {
+      totals.duplicates++;
+      return;
+    }
+
+    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;
+
+    // Decided here, not inside applyAssistantEntry, because the unattributed
+    // branch below bills its own turns and tokens and never reaches that
+    // function — the same response split across blocks would inflate the one
+    // counter whose job is to report what fell outside the rows.
+    //
+    // `message.id` is the identity the API gives a response; `requestId` is the
+    // fallback for an entry that lacks it. Measured: the two are 1:1 (no id maps
+    // to two of the other, in either direction) and no entry has neither, so the
+    // fallback is belt-and-braces rather than load-bearing. An entry with NO id
+    // at all is counted rather than assumed unique — an unidentifiable response
+    // is not silently a new one — and reported via `responsesUnidentified`.
+    //
+    // Synthetic turns never enter the set: they are excluded from every billing
+    // figure anyway, and 8 of them carry a message.id (0 colliding with a real
+    // response) that would otherwise poison it.
+    let repeatOfResponse = false;
+    if (isAssistant && !synthetic) {
+      // Non-empty strings only, the same test groupFor() applies to promptId.
+      // `??` alone would accept `id: ''`, and an empty id shared by every entry
+      // in a file would collapse the whole file into ONE response — the bill
+      // would fall to near zero and read as a clean result. Under-counting is
+      // the worse direction: an over-count announces itself as implausible.
+      const id = entry.message?.id;
+      const req = entry.requestId;
+      const responseId =
+        (typeof id === 'string' && id !== '' && id) || (typeof req === 'string' && req !== '' && req) || null;
+      if (responseId === null) totals.responsesUnidentified++;
+      else if (seenResponses.has(responseId)) {
+        repeatOfResponse = true;
+        totals.responseRepeats++;
+      } else seenResponses.add(responseId);
+    }
+
+    if (group === null) {
+      unattributed.entries++;
+      // Per ENTRY, above the repeat guard and outside the synthetic test —
+      // exactly where the row path counts them, and for its reasons: tool_use
+      // blocks are NOT duplicated across the entries of one response
+      // (TASK-092), and a synthetic turn's tool call still happened even though
+      // nobody billed for it.
+      if (isAssistant) {
+        for (const block of toolUseBlocks(entry)) {
+          unattributed.tool_calls++;
+          if (AGENT_TOOLS.has(block.name)) unattributed.agent_spawns++;
+        }
+      }
+      if (isAssistant && !synthetic && !repeatOfResponse) {
+        unattributed.turns++;
+        if (usage) {
+          addUsage(unattributed, usage);
+          // Under the guard, the mirror image of the tool calls above:
+          // server_tool_use is part of `usage`, so it IS copied onto every entry
+          // of a split response, and counting it per entry would re-open
+          // TASK-092 in the one place we just closed it.
+          const server = serverToolRequests(usage);
+          unattributed.web_search_requests += server.search;
+          unattributed.web_fetch_requests += server.fetch;
+        }
+      }
+      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);
+    // Guarded like api_turns, and for the same reason: this is a TURN counter —
+    // it is the figure that says how big the subagent blind spot is (error class
+    // 3), paired with agent_spawns. A subagent response splits across content
+    // blocks like any other, and being tool-heavy it splits MORE, so counting it
+    // per entry would inflate the very number that measures what we cannot see.
+    // Zero isSidechain entries in all data measured so far, so this moves no
+    // current figure — it stops the bug from arriving with the first one.
+    if (entry.isSidechain === true && isAssistant && !repeatOfResponse) p.sidechainTurns++;
+    if (isAssistant) applyAssistantEntry(p, entry, { usage, model, synthetic, repeatOfResponse });
+    else {
+      applyUserEntry(p, entry);
+      // Tool results come back as `user` entries; the delegation's bill rides on
+      // the one belonging to an `Agent` call, priced at the moment it happened.
+      applyDelegation(p, entry, msOf(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,
+      // Deliberately NOT folded into the row's tokens or cost: what the
+      // subagents cost is a lower bound (see applyDelegation), and a lower bound
+      // added into a total stops being labelled as one. Sorted so two runs over
+      // the same transcripts produce byte-identical rows.
+      delegations: [...p.delegations.values()].sort((a, b) => a.agent_id.localeCompare(b.agent_id)),
+      delegation_duplicates_dropped: p.delegationDuplicates,
+      delegations_unidentified: p.delegationsUnidentified,
+      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),
+        // Rolled up with the SAME summarizer as the rows — a delegation record
+        // carries the cost fields summarizeCost reads, so the lower bound is
+        // built by the code that already knows how to refuse an unpriced row.
+        // Kept beside `cost`, never inside it (TASK-089 criterion 8b).
+        delegationCost: summarizeCost(rows.flatMap((r) => r.delegations)),
+        totals: {
+          ...totals,
+          prompts: rows.length,
+          agent_spawns: sum('agent_spawns'),
+          delegations_measured: rows.reduce((n, r) => n + r.delegations.length, 0),
+          delegation_duplicates_dropped: sum('delegation_duplicates_dropped'),
+          delegations_unidentified: sum('delegations_unidentified'),
+          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, delegationCost }) {
+  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` : ''),
+  );
+  if (totals.duplicates > 0) {
+    // Loud, because the figure below is ~1.8x smaller than it used to be and a
+    // reader comparing two runs of this tool deserves to know why.
+    L.push(
+      `  repeated entries skipped: ${totals.duplicates} (same uuid, already seen in this file)` +
+        ' — counting them charged the same tokens twice',
+    );
+  }
+  if (totals.responseRepeats > 0) {
+    // Its own line, never folded into the uuid count above: the two are
+    // different defects with different fixes, and this one halves the bill. A
+    // reader comparing this run against a pre-TASK-092 run must be able to see
+    // which of the two moved the number.
+    L.push(
+      `  extra entries of the same response: ${totals.responseRepeats}` +
+        ' (same message.id — one API response split across content blocks; usage counted once)',
+    );
+  }
+  if (totals.responsesUnidentified > 0) {
+    // Counted, not assumed unique: an entry with neither id could be a fresh
+    // response or the fourth copy of one already billed. We charge it (an
+    // unknown response is never priced at zero) and say so.
+    L.push(
+      `  assistant entries with no message.id and no requestId: ${totals.responsesUnidentified}` +
+        ' — billed as distinct responses; may double-count if they are split blocks',
+    );
+  }
+  L.push(
+    `  unattributed entries: ${unattributed.entries}` +
+      ` (${unattributed.turns} API turn(s), ${unattributed.output_tokens} output tokens) — not in any row`,
+  );
+  // Its own line, and only the parts that are non-zero — a clean run stays
+  // clean, and so does a run whose only gap is one of the three. Split from the
+  // line above because the halves are different kinds of gap: the tool calls are
+  // missing from an adoption DENOMINATOR, the searches are missing DOLLARS, and
+  // dollars that appear in no cost figure this tool prints, here or below.
+  const outside = [];
+  if (unattributed.tool_calls > 0) {
+    outside.push(
+      `${unattributed.tool_calls} tool call(s)` +
+        (unattributed.agent_spawns > 0
+          ? `, ${unattributed.agent_spawns} of them subagent spawn(s) whose cost is UNCAPTURED (class 3)`
+          : ''),
+    );
+  }
+  if (unattributed.web_search_requests > 0) {
+    outside.push(
+      `${unattributed.web_search_requests} web search(es) =` +
+        ` ${formatUsd(webSearchCost(unattributed.web_search_requests))} NOT in any cost figure below`,
+    );
+  }
+  if (unattributed.web_fetch_requests > 0) outside.push(`${unattributed.web_fetch_requests} web fetch(es) (free)`);
+  if (outside.length > 0) L.push(`    also outside every row: ${outside.join(', ')}`);
+  L.push(`  subagent spawns: ${totals.agent_spawns}; sidechain turns in transcript: ${totals.sidechain_turns}`);
+  if (totals.delegations_measured > 0) {
+    // Two numbers, never one: what we could price, and how far the spawns
+    // outrun it. A spawn with no result entry is cost we have NO figure for.
+    const missing = Math.max(0, totals.agent_spawns - totals.delegations_measured);
+    L.push(
+      `  delegations priced from their own usage: ${totals.delegations_measured}` +
+        ` (${totals.delegation_duplicates_dropped} duplicate entr(ies) dropped` +
+        `, ${totals.delegations_unidentified} without an agentId, not counted)`,
+    );
+    if (delegationCost) {
+      L.push(
+        `    subagent LOWER BOUND: ${formatUsd(delegationCost.list_cost_usd)} over` +
+          ` ${delegationCost.priced_rows} of ${delegationCost.total_rows} delegation(s)` +
+          ' — separate from the figure above, NEVER added to it (procedure §11a)',
+      );
+    }
+    if (missing > 0) {
+      L.push(`    ${missing} spawn(s) left no priced result — their cost is UNCAPTURED, not zero (EPIC-009 class 3)`);
+    }
+  } else if (totals.agent_spawns > 0) {
+    L.push('    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]?.endsWith('prompt-metrics.mjs')) {
+  await main();
+}