@bglocation/tune-context 2.4.0 → 3.0.0

package/eval/prompt-metrics.mjs

@@ -20,11 +20,14 @@
 //     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).
+//     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".
@@ -40,9 +43,11 @@ 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 { endQuietlyOnClosedPipe, isEntryPoint } from '../cli/entry-point.mjs';
+import { readStepLedger } from '../cli/experiment.mjs';
+import { meterStamp } from '../cli/version.mjs';
 import { annotateRows, formatArmSummary } from './arm.mjs';
-import { formatCostLines, priceRow, summarizeCost } from './pricing.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.
@@ -58,7 +63,7 @@ const USAGE = `
 prompt-metrics — per-prompt time/token/tool metrics from Claude Code transcripts.
 
 Usage:
-  prompt-metrics [--transcript <path>]... [--dir <path>]
+  prompt-metrics [--transcript <path>]... [--dir <path>] [--ledger <path>]
 
 Options:
   --transcript <path>  A single .jsonl transcript. Repeatable.
@@ -67,6 +72,12 @@ Options:
                        (default when neither is given: <config dir>/projects,
                        where <config dir> is $CLAUDE_CONFIG_DIR if set,
                        else ~/.claude)
+  --ledger <path>      The experiment ledger to assign arms by (default:
+                       <config dir>/tune-context/experiment.jsonl). For
+                       recomputing an archive — \`tune-context experiment
+                       archive\` keeps the ledger next to the transcripts. A
+                       path that does not exist, or is not a file, is an
+                       error.
   -h, --help           Show this help
 
 Writes JSONL to stdout, one row per prompt. A run summary — including how many
@@ -86,6 +97,16 @@ 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.
+
+Every row also carries meter_version: the code that computed it — the bare
+release number for an npm install, number+<sha> for a checkout, .dirty for
+uncommitted changes in the meter's paths (EPIC-010). The first line of the
+summary on stderr is that stamp, as \`meter <stamp>\`: it goes into the run
+journal before the first pair. analyze refuses rows without it.
+
+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. */
@@ -168,6 +189,33 @@ function addUsage(into, usage) {
   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,
@@ -207,6 +255,12 @@ function newPrompt({ promptId, session }) {
     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,
   };
 }
@@ -292,10 +346,86 @@ function applyUserEntry(p, entry) {
   }
 }
 
+/**
+ * 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 }) {
-  for (const block of Array.isArray(entry.message?.content) ? entry.message.content : []) {
-    if (block?.type !== 'tool_use') continue;
+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++;
@@ -309,6 +439,26 @@ function applyAssistantEntry(p, entry, { usage, model, synthetic }) {
     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);
@@ -329,11 +479,9 @@ function applyAssistantEntry(p, entry, { usage, model, synthetic }) {
   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;
-  }
+  const server = serverToolRequests(usage);
+  p.webSearchRequests += server.search;
+  p.webFetchRequests += server.fetch;
 }
 
 /**
@@ -365,8 +513,34 @@ export function createCollector() {
   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 };
+  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.
@@ -389,6 +563,28 @@ export function createCollector() {
 
   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.
@@ -405,11 +601,64 @@ export function createCollector() {
     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++;
-      if (isAssistant && !synthetic) {
+      // 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);
+        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;
     }
@@ -424,9 +673,21 @@ export function createCollector() {
 
     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);
+    // 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) {
@@ -486,6 +747,13 @@ export function createCollector() {
       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,
@@ -524,10 +792,18 @@ export function createCollector() {
         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'),
@@ -557,23 +833,89 @@ export function formatRow(row) {
  * 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 }) {
+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`,
   );
-  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)'
-        : ''),
-  );
+  // 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}`);
   }
@@ -645,14 +987,21 @@ function defaultDir() {
   return join(claudeBaseDir(), 'projects');
 }
 
-async function main() {
+/**
+ * The CLI. `args` is everything after the script name, or after
+ * `tune-context eval prompt-metrics` — one parser behind both doors (EPIC-010).
+ */
+export async function main(args = process.argv.slice(2)) {
+  endQuietlyOnClosedPipe();
   let paths;
+  let ledger;
   try {
     const { values } = parseArgs({
-      args: process.argv.slice(2),
+      args,
       options: {
         transcript: { type: 'string', multiple: true },
         dir: { type: 'string' },
+        ledger: { type: 'string' },
         help: { type: 'boolean', short: 'h', default: false },
       },
       strict: true,
@@ -661,6 +1010,9 @@ async function main() {
       process.stdout.write(`${USAGE}\n`);
       return;
     }
+    // Read now, before the transcripts: a --ledger that is not a file stops the
+    // run here, with the same message analyze gives (TASK-098).
+    ledger = readStepLedger(values.ledger, claudeBaseDir());
     // 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.
@@ -688,11 +1040,6 @@ async function main() {
     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();
 
@@ -700,19 +1047,21 @@ async function main() {
   // 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,
-  });
+  const rows = annotateRows(result.rows, ledger);
 
-  for (const row of rows) process.stdout.write(`${formatRow(row)}\n`);
-  process.stderr.write(`${formatSummary(result)}\n`);
+  // Which code computed the rows rides on every row — added here, with the arm,
+  // because it is a property of the process that ran, not of the transcript
+  // (TASK-097). Last on the row, so nothing that already read a row by position
+  // in a diff moves.
+  const stamp = meterStamp();
+  for (const row of rows) process.stdout.write(`${formatRow({ ...row, meter_version: stamp })}\n`);
+  // First line of the summary, on its own: this is what the operator copies
+  // into the run journal before the first pair.
+  process.stderr.write(`meter ${stamp}\n${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')) {
+if (isEntryPoint(import.meta.url)) {
   await main();
 }