@bglocation/tune-context 2.5.0 → 3.0.0

package/cli/entry-point.mjs

@@ -0,0 +1,73 @@
+// What every runnable module needs at its entry, answered once — shared by bin/
+// and by every runnable module in eval/ (TASK-095): "was this file run, or
+// imported?", how a step ends when its reader leaves early, and reading stdin.
+//
+// One implementation on purpose. eval/ used to answer it with
+// `process.argv[1]?.endsWith('<name>.mjs')`, the exact test that shipped 2.0.0
+// with a silent CLI. Harmless there only for as long as nobody called those
+// scripts through a symlink — and `tune-context eval` exists precisely so that
+// people stop calling them by path.
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * True only when the module at `moduleUrl` (pass `import.meta.url`) is the
+ * process entry point, so importing it for its functions (tests, the
+ * extensionless bin/tune-context wrapper, the `tune-context eval` dispatcher)
+ * never runs its CLI as a side effect of the import.
+ *
+ * Deliberately NOT a filename-suffix test on argv[1]. npm installs the
+ * package.json `bin` entry as a symlink named `tune-context` — no extension —
+ * so `argv[1].endsWith('tune-context.mjs')` was false for every real npm-channel
+ * invocation: main() never ran and the CLI exited 0 in total silence. That
+ * shipped in 2.0.0 (see the symlink test in test/bin-tune-context.test.mjs);
+ * the whole suite missed it because tests and smoke:init both spawned the full
+ * `.../bin/tune-context.mjs` path, which is the one shape a user never uses.
+ *
+ * Comparing resolved real paths holds for all four shapes: direct `.mjs`
+ * invocation, the npm symlink (resolves THROUGH the link to the file), the
+ * extensionless wrapper or the dispatcher (a different real path, so this stays
+ * false and the caller's own main() call is the single entry — no double run),
+ * and `import` from a test (argv[1] is the test runner). realpathSync on both
+ * sides also survives a symlinked package dir, as `npm link` and nvm both
+ * produce.
+ */
+export function isEntryPoint(moduleUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    // argv[1] can name something unresolvable (deleted, or a bare `-`); a CLI
+    // that cannot identify its own entry point must stay silent, not crash.
+    return false;
+  }
+}
+
+let pipeGuarded = false;
+
+/**
+ * A reader that leaves early — `| head`, a pager quit after one screen — is a
+ * normal end for a step writing to stdout, not a crash. Without a listener the
+ * EPIPE becomes an uncaught 'error' and a stacktrace once the output outgrows
+ * the pipe buffer (64 KB): a long report page, an aggregate of many tasks. Any
+ * other stdout error still goes up.
+ *
+ * Every eval step's main() calls this first, so both doors end the same way —
+ * one guard instead of a copy in the steps somebody happened to pipe (TASK-094
+ * covered prompt-metrics; report and analyze had none). Idempotent: one
+ * listener per process, however many mains run in it.
+ */
+export function endQuietlyOnClosedPipe() {
+  if (pipeGuarded) return;
+  pipeGuarded = true;
+  process.stdout.on('error', (e) => {
+    if (e.code !== 'EPIPE') throw e;
+  });
+}
+
+/** All of stdin as text — for a step reading its input from a pipe. */
+export async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}

package/cli/experiment.mjs

@@ -430,7 +430,16 @@ export function appendLedger(claudeDir, entry) {
 
 /** Parsed ledger, oldest first. Unparseable lines are skipped, never guessed at. */
 export function readLedger(claudeDir) {
-  const raw = readText(experimentPaths(claudeDir).ledgerPath);
+  return readLedgerFile(experimentPaths(claudeDir).ledgerPath);
+}
+
+/**
+ * The same reading for a ledger that is not the config dir's own — an
+ * archive's (TASK-098), handed to prompt-metrics/analyze with `--ledger`. One
+ * parser, so a ledger cannot mean one thing live and another in the archive.
+ */
+export function readLedgerFile(path) {
+  const raw = readText(path);
   if (raw === null) return [];
   return raw
     .split('\n')
@@ -445,6 +454,29 @@ export function readLedger(claudeDir) {
     .filter(Boolean);
 }
 
+/**
+ * The ledger an eval step assigns arms by — prompt-metrics and analyze, one
+ * rule for both: `--ledger <path>` when it was given, else the config dir's own.
+ *
+ * An explicit path must be a file. Read as no ledger (missing) or as an empty
+ * one (a directory), it would turn every experiment row into `branch` — the
+ * source the paired pool refuses — and nothing would say why (TASK-098).
+ *
+ * @returns {{ledger: object[], ledgerAvailable: boolean}} what annotateRows()
+ *   and analyze() take.
+ * @throws {ExperimentError} an explicit path that is missing or not a file.
+ */
+export function readStepLedger(explicitPath, claudeDir) {
+  if (explicitPath !== undefined) {
+    const stat = statSync(explicitPath, { throwIfNoEntry: false });
+    if (stat === undefined) throw new ExperimentError(`no ledger at ${explicitPath} (--ledger)`);
+    if (!stat.isFile()) throw new ExperimentError(`--ledger ${explicitPath} is not a file`);
+  }
+  const path = explicitPath ?? experimentPaths(claudeDir).ledgerPath;
+  const ledgerAvailable = existsSync(path);
+  return { ledger: ledgerAvailable ? readLedgerFile(path) : [], ledgerAvailable };
+}
+
 /**
  * Switch to `{tc, rag}`, recording everything needed to switch back.
  *

package/cli/version.mjs

@@ -0,0 +1,118 @@
+// Which code is this? Two answers, for two readers (TASK-097).
+//
+//   readVersion()  the release number, for `tune-context --version` — a script
+//                  greps it, and the plugin manifests are cross-checked against
+//                  it (verify:plugin).
+//   meterStamp()   the CODE that computed a measurement, stamped on every
+//                  artifact of the eval chain: rows (`meter_version`), the
+//                  aggregate (`analyzed_by`), the verdict (`judged_by`).
+//
+// They differ on purpose. EPIC-009's verdict was voided because its rows came
+// from a meter with a bug (TASK-092, costs inflated 2.02x) and nothing in the
+// frozen files said which code wrote them. A release number alone would not
+// have said it either: under `npm link`, which the runbook prescribed for that
+// series, the number changes only at release — a fix committed before the
+// release carries the same number as the bug it fixes.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Paths whose state is the meter's state. Coarse on purpose: a change to a hook
+ * eval never imports also makes the stamp `.dirty`. A false "dirty" holds a
+ * verdict that could have been issued; a false "clean" issues one from code
+ * nobody can rebuild — the cheaper error is the first. epics/, tasks/ and
+ * docs/ do not touch the meter and do not dirty the stamp.
+ */
+const METER_PATHS = ['eval', 'cli', 'hooks', 'bin', 'package.json'];
+
+/**
+ * Version straight from the shipped package.json — one source of truth, the
+ * same file verify:plugin cross-checks against plugin.json/marketplace.json,
+ * so `--version` can never drift from what the manifests claim. Both channels
+ * ship it: npm always includes package.json in the tarball, and the plugin
+ * channel is a git clone of this repo (guarded in verify-plugin's REQUIRE).
+ */
+export function readVersion(pkgRoot = PKG_ROOT) {
+  return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+}
+
+/**
+ * The environment for a git that must answer about `cwd` and nothing else:
+ * GIT_* variables dropped. Inside a git hook they point at the hook's own
+ * repository (GIT_DIR, GIT_INDEX_FILE), and git would read that one instead.
+ */
+export function gitEnv() {
+  return Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+}
+
+function git(cwd, args) {
+  return execFileSync('git', ['--no-optional-locks', ...args], { cwd, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+/**
+ * The stamp for the package at `pkgRoot`, computed now. Grammar (number
+ * illustrative):
+ *
+ *   2.6.0                  pkgRoot is not the TOP of a git repo: an npm install,
+ *                          including a local node_modules inside someone else's
+ *                          repo. A registry version is immutable, so the number
+ *                          names the code, and `npx -p @bglocation/tune-context@2.6.0`
+ *                          rebuilds it on demand.
+ *   2.6.0+<sha>            a checkout of this repo (`npm link`, the plugin's
+ *                          clone, `node eval/…`), clean in METER_PATHS. The first
+ *                          12 characters of HEAD, always 12: a shorter prefix
+ *                          can turn ambiguous as the repo grows.
+ *   2.6.0+<sha>.dirty      changes in METER_PATHS, untracked files included.
+ *   2.6.0+unknown          the top of a repo, but git is missing or failed.
+ *
+ * "The top", compared by realpath: inside someone else's repo, their HEAD would
+ * pass for ours. No `.git` at pkgRoot settles it without spawning git — which
+ * is also how a missing git still tells an install from a checkout.
+ *
+ * Uncached, for tests that change a repository between calls. Everything else
+ * uses meterStamp().
+ */
+export function readMeterStamp(pkgRoot = PKG_ROOT) {
+  const version = readVersion(pkgRoot);
+  if (!existsSync(join(pkgRoot, '.git'))) return version;
+  try {
+    if (realpathSync(git(pkgRoot, ['rev-parse', '--show-toplevel'])) !== realpathSync(pkgRoot)) return version;
+    const sha = git(pkgRoot, ['rev-parse', 'HEAD']).slice(0, 12);
+    const dirty = git(pkgRoot, ['status', '--porcelain', '--untracked-files=all', '--', ...METER_PATHS]) !== '';
+    return `${version}+${sha}${dirty ? '.dirty' : ''}`;
+  } catch {
+    return `${version}+unknown`;
+  }
+}
+
+const stamps = new Map();
+
+/**
+ * The stamp, computed once per process (and per package root): every artifact
+ * one process writes carries the same stamp even if the tree changes while it
+ * runs — the code that is running did not change with it.
+ */
+export function meterStamp(pkgRoot = PKG_ROOT) {
+  if (!stamps.has(pkgRoot)) stamps.set(pkgRoot, readMeterStamp(pkgRoot));
+  return stamps.get(pkgRoot);
+}
+
+const STAMP = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+(?:[0-9a-f]{12}(\.dirty)?|(unknown)))?$/;
+
+/**
+ * Why a stamp does not name code anyone can rebuild — or null when it does.
+ * A message rather than a boolean, because the verdict has to say which of the
+ * three it was.
+ */
+export function stampProblem(stamp) {
+  if (typeof stamp !== 'string' || stamp === '') return 'no stamp at all';
+  const m = STAMP.exec(stamp);
+  if (m === null) return 'not a meter stamp';
+  if (m[1]) return "computed from uncommitted changes in the meter's paths — that code exists nowhere else";
+  if (m[2]) return 'computed from a checkout git could not read — the commit is unknown';
+  return null;
+}

package/eval/adoption-report.mjs

@@ -19,6 +19,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
+import { endQuietlyOnClosedPipe, isEntryPoint } from '../cli/entry-point.mjs';
 import { claudeBaseDir } from '../hooks/config-dir.mjs';
 import { classifyAvailability, probeProjectMcp } from './mcp-probe.mjs';
 
@@ -76,7 +77,7 @@ Options:
   -h, --help     Show this help
 
 The log is written by the adoption-log.mjs PostToolUse hook (installed by
-tune-context). Cost in dollars is NOT here — see eval/prompt-metrics.mjs.
+tune-context). Cost in dollars is NOT here — see tune-context eval prompt-metrics.
 `.trim();
 
 export function parseLog(text) {
@@ -496,7 +497,7 @@ export function formatReport(a) {
   }
   L.push('');
   L.push('Cost (dollars) is not in the hook log. Two independent routes to it:');
-  L.push('  eval/prompt-metrics.mjs — prices the transcript, works with hooks OFF too.');
+  L.push('  tune-context eval prompt-metrics — prices the transcript, works with hooks OFF too.');
   L.push('  OTEL: CLAUDE_CODE_ENABLE_TELEMETRY=1 + an OTLP collector →');
   L.push('  metric `claude_code.cost.usage` (direct) / `claude_code.token.usage`.');
   L.push('  caveman (output style) leaves no tool call — not measured here.');
@@ -504,11 +505,16 @@ export function formatReport(a) {
   return L.join('\n');
 }
 
-function main() {
+/**
+ * The CLI. `args` is everything after the script name, or after
+ * `tune-context eval adoption-report` — one parser behind both doors (EPIC-010).
+ */
+export function main(args = process.argv.slice(2)) {
+  endQuietlyOnClosedPipe();
   let logPath;
   try {
     const { values } = parseArgs({
-      args: process.argv.slice(2),
+      args,
       options: {
         log: { type: 'string' },
         help: { type: 'boolean', short: 'h', default: false },
@@ -539,6 +545,6 @@ function main() {
   process.stdout.write(`${formatReport(aggregate(records))}\n`);
 }
 
-if (process.argv[1]?.endsWith('adoption-report.mjs')) {
+if (isEntryPoint(import.meta.url)) {
   main();
 }

package/eval/analyze.mjs

@@ -29,7 +29,9 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { claudeBaseDir } from '../hooks/config-dir.mjs';
-import { experimentPaths, readLedger } from '../cli/experiment.mjs';
+import { endQuietlyOnClosedPipe, isEntryPoint, readStdin } from '../cli/entry-point.mjs';
+import { readStepLedger } from '../cli/experiment.mjs';
+import { meterStamp, stampProblem } from '../cli/version.mjs';
 import { ledgerArmAt, parseArmBranch, rowTimestamp } from './arm.mjs';
 import { TOKEN_CLASS_FIELDS, formatUsd, summarizeCost } from './pricing.mjs';
 
@@ -40,15 +42,25 @@ const USAGE = `
 analyze — per-arm aggregate from prompt-metrics rows (TASK-089).
 
 Usage:
-  analyze [--rows <path>]...
+  analyze [--rows <path>]... [--ledger <path>]
 
 Options:
-  --rows <path>  A JSONL file written by prompt-metrics. Repeatable.
-                 (default: read from stdin)
-  -h, --help     Show this help
+  --rows <path>    A JSONL file written by prompt-metrics. Repeatable.
+                   (default: read from stdin)
+  --ledger <path>  The experiment ledger natural work is attributed by
+                   (default: <config dir>/tune-context/experiment.jsonl). For
+                   recomputing an archive. A path that does not exist, or is
+                   not a file, is an error.
+  -h, --help       Show this help
 
 Writes the aggregate as JSON to stdout and a short summary to stderr. It does
-NOT rule on which arm is cheaper — that is TASK-090.
+NOT rule on which arm is cheaper — that is tune-context eval verdict.
+
+Every row must carry meter_version, the stamp prompt-metrics puts on it
+(EPIC-010). One row without it refuses the WHOLE input: exit 1, nothing on
+stdout. Rows from before that contract are not used — recompute them from the
+transcripts or from an archive. Rows from different meters are aggregated, and
+the verdict holds on its meter_mixed gate.
 `.trim();
 
 // ─── numbers ────────────────────────────────────────────────────────────────
@@ -459,6 +471,9 @@ function pairedPool(rows) {
   return {
     pool: 'paired',
     source: 'branch exp/<task>/<arm> (TASK-088), reconciled against the TASK-087 ledger',
+    // What the verdict's meter_mixed gate reads: the stamps of the rows the
+    // verdict is built on, and no others.
+    meter_versions: meterVersions(rows),
     arms: armsOf(rows, pairsPerArm),
     pairs,
     n_pairs_complete: complete.length,
@@ -477,14 +492,37 @@ function naturalPool(rows) {
   return {
     pool: 'natural',
     source: 'TASK-087 ledger, by timestamp',
+    meter_versions: meterVersions(rows),
     arms: armsOf(rows),
   };
 }
 
+/**
+ * Rows per meter stamp, `{ '<stamp>': n }`, keys sorted so two runs over the
+ * same rows serialize to the same bytes — by code unit, the order the verdict's
+ * meter_mixed gate lists the same stamps in. localeCompare would tie the bytes
+ * to the machine's collation and put `-rc.1` where the gate puts `+<sha>`.
+ */
+function meterVersions(rows) {
+  const counts = new Map();
+  for (const row of rows) counts.set(row.meter_version, (counts.get(row.meter_version) ?? 0) + 1);
+  return Object.fromEntries([...counts.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+/** True for a row that says which meter computed it (TASK-097). */
+export function isStamped(row) {
+  return typeof row?.meter_version === 'string' && row.meter_version !== '';
+}
+
 /**
  * Rows in, aggregate out. Pure: no disk, no clock, no ambient state.
  *
- * @param rows  prompt-metrics rows that have been through annotateRows().
+ * @param rows  prompt-metrics rows that have been through annotateRows(), each
+ *        carrying `meter_version`. A row without one is input from before the
+ *        measurement contract (EPIC-010, PO decision 4) — not a measurement by
+ *        another meter — and this throws rather than aggregate it, the same
+ *        layer-boundary rule classifyRow() applies to an unannotated row. The
+ *        CLI checks first, so an operator sees file and line, not this.
  * @param ledger / ledgerAvailable  the TASK-087 ledger, for natural work only.
  *        Paired rows carry their arm already; ordinary work has no marker but
  *        this one.
@@ -492,8 +530,19 @@ function naturalPool(rows) {
  *        in no row at all. It is not derivable from rows — that is the point of
  *        it — so it is passed through, and stays **null** when the caller did
  *        not supply it. Null means "not reported", never zero.
+ * @param analyzedBy  the stamp of the code running this function, from the
+ *        caller (no ambient state here, like report's `generatedAt`). Null when
+ *        not given, and the verdict's meter_mixed gate holds on a step that left
+ *        no stamp.
  */
-export function analyze(rows, { ledger = [], ledgerAvailable = false, unattributed = null } = {}) {
+export function analyze(rows, { ledger = [], ledgerAvailable = false, unattributed = null, analyzedBy = null } = {}) {
+  const unstamped = rows.filter((row) => !isStamped(row)).length;
+  if (unstamped > 0) {
+    throw new TypeError(
+      `analyze: ${unstamped} of ${rows.length} row(s) carry no meter_version — rows from before EPIC-010 are not used;` +
+        ' recompute them from the transcripts or from an archive with prompt-metrics',
+    );
+  }
   const classified = rows.map((row) => ({ row, verdict: classifyRow(row, { ledger, ledgerAvailable }) }));
   const mixed = mixedArmSessions(classified);
 
@@ -534,7 +583,13 @@ export function analyze(rows, { ledger = [], ledgerAvailable = false, unattribut
 
   const used = pools.paired.length + pools.natural.length;
   return {
-    schema: 'tune-context/analyze@1',
+    // @2 since EPIC-010: the stamps below are required, and verdict and report
+    // refuse an @1 aggregate rather than judge numbers nobody can trace.
+    schema: 'tune-context/analyze@2',
+    analyzed_by: analyzedBy,
+    // Every row that came in, by the meter that computed it — rejected rows
+    // included, because they were input too. The pools carry their own.
+    meter_versions: meterVersions(rows),
     // No cost field at this level, on purpose. There is nothing here to add the
     // pools into, and no array of pools to fold over — see the file header.
     paired: pairedPool(pools.paired),
@@ -580,6 +635,23 @@ function armLine(a) {
  */
 export function formatAnalysis(agg) {
   const L = [`analyze: ${agg.counters.rows_in} row(s) in, ${agg.counters.rows_used} used, ${agg.counters.rows_rejected} rejected`];
+  // Named, never just counted: different stamps do not stop the aggregate
+  // (PO decision 2), and this line is where an operator sees them before the
+  // verdict holds on them.
+  const stamps = Object.entries(agg.meter_versions);
+  // What it predicts, it predicts from what the meter_mixed gate reads, as far
+  // as analyze can know it: the PAIRED rows' stamps and its own (the verdict's
+  // comes later). Natural work never reaches the verdict — a stranger there is
+  // named on this line and holds nothing. A missing analyze stamp is its own
+  // problem, not a second meter.
+  const chain = [...new Set([...Object.keys(agg.paired.meter_versions ?? {}), agg.analyzed_by].filter(Boolean))];
+  const unnamed = chain.filter((stamp) => stampProblem(stamp) !== null);
+  L.push(
+    `  meter: rows ${stamps.length === 0 ? '—' : stamps.map(([stamp, n]) => `${stamp} ×${n}`).join(', ')}; analyzed by ${agg.analyzed_by ?? 'NO STAMP'}` +
+      (chain.length > 1 ? ' — MORE THAN ONE METER: the verdict holds on meter_mixed' : '') +
+      (unnamed.length > 0 ? ` — ${unnamed.join(', ')} names no code: the verdict holds on meter_mixed` : '') +
+      (agg.analyzed_by ? '' : ' — the verdict holds on meter_mixed until analyze is run through its CLI'),
+  );
   L.push('  paired measurement (TASK-088 — the only pool a verdict may be built on):');
   for (const arm of ARMS) L.push(armLine(agg.paired.arms[arm]));
   for (const pair of agg.paired.pairs) {
@@ -607,44 +679,49 @@ export function formatAnalysis(agg) {
   } else {
     L.push(`  unattributed transcript entries: ${agg.counters.unattributed.entries ?? agg.counters.unattributed}`);
   }
-  L.push('  this is an aggregate, NOT a verdict — thresholds and gates are TASK-090.');
+  L.push('  this is an aggregate, NOT a verdict — the gates and their thresholds are tune-context eval verdict.');
   return L.join('\n');
 }
 
 // ─── CLI ────────────────────────────────────────────────────────────────────
 
-async function readStdin() {
-  const chunks = [];
-  for await (const chunk of process.stdin) chunks.push(chunk);
-  return Buffer.concat(chunks).toString('utf8');
-}
-
 /** JSONL → rows, malformed lines counted rather than fatal — the same rule the
  *  collector applies to transcripts, for the same reason: the file may be being
- *  appended to while we read it. */
+ *  appended to while we read it. `lines[i]` is the 1-based line `rows[i]` came
+ *  from, so a refusal can point at the line instead of at the file. */
 export function parseRows(text) {
   const rows = [];
+  const lines = [];
   let malformed = 0;
-  for (const line of text.split('\n')) {
-    if (line.trim() === '') continue;
+  text.split('\n').forEach((line, i) => {
+    if (line.trim() === '') return;
     try {
       const row = JSON.parse(line);
-      if (row && typeof row === 'object' && !Array.isArray(row)) rows.push(row);
-      else malformed++;
+      if (row && typeof row === 'object' && !Array.isArray(row)) {
+        rows.push(row);
+        lines.push(i + 1);
+      } else malformed++;
     } catch {
       malformed++;
     }
-  }
-  return { rows, malformed };
+  });
+  return { rows, lines, malformed };
 }
 
-async function main() {
-  let text;
+/**
+ * The CLI. `args` is everything after the script name, or after
+ * `tune-context eval analyze` — one parser behind both doors (EPIC-010).
+ */
+export async function main(args = process.argv.slice(2)) {
+  endQuietlyOnClosedPipe();
+  let sources;
+  let ledger;
   try {
     const { values } = parseArgs({
-      args: process.argv.slice(2),
+      args,
       options: {
         rows: { type: 'string', multiple: true },
+        ledger: { type: 'string' },
         help: { type: 'boolean', short: 'h', default: false },
       },
       strict: true,
@@ -653,6 +730,11 @@ async function main() {
       process.stdout.write(`${USAGE}\n`);
       return;
     }
+    // The ledger is read here rather than inside analyze() for the same reason
+    // prompt-metrics reads it in its CLI: it is machine state, and a pure
+    // function that reaches for the disk cannot be tested against someone
+    // else's run. One reader for both steps, --ledger included (TASK-098).
+    ledger = readStepLedger(values.ledger, claudeBaseDir());
     const paths = values.rows ?? [];
     const missing = paths.filter((p) => !existsSync(p));
     if (missing.length > 0) {
@@ -660,30 +742,51 @@ async function main() {
       process.exitCode = 1;
       return;
     }
-    text = paths.length > 0 ? paths.map((p) => readFileSync(p, 'utf8')).join('\n') : await readStdin();
+    // One source per file (or stdin), parsed apart, so a refusal can name the
+    // file AND the line. The rows come out in the same order as before.
+    sources = paths.length > 0 ? paths.map((p) => ({ name: p, text: readFileSync(p, 'utf8') })) : [{ name: 'stdin', text: await readStdin() }];
   } catch (e) {
     process.stderr.write(`analyze: ${e.message}\n`);
     process.exitCode = 1;
     return;
   }
 
-  const { rows, malformed } = parseRows(text);
+  const rows = [];
+  const unstamped = [];
+  let malformed = 0;
+  for (const { name, text } of sources) {
+    const parsed = parseRows(text);
+    malformed += parsed.malformed;
+    parsed.rows.forEach((row, i) => {
+      rows.push(row);
+      if (!isStamped(row)) unstamped.push(`${name}:${parsed.lines[i]}`);
+    });
+  }
   if (malformed > 0) process.stderr.write(`analyze: ${malformed} malformed line(s) skipped\n`);
 
-  // The ledger is read here rather than inside analyze() for the same reason
-  // prompt-metrics reads it in its CLI: it is machine state, and a pure function
-  // that reaches for the disk cannot be tested against someone else's run.
-  const ledgerPath = experimentPaths(claudeBaseDir()).ledgerPath;
-  const ledgerAvailable = existsSync(ledgerPath);
-  const agg = analyze(rows, {
-    ledger: ledgerAvailable ? readLedger(claudeBaseDir()) : [],
-    ledgerAvailable,
-  });
+  // PO decision 4 (EPIC-010): a row without a stamp is input from before the
+  // measurement contract, not a measurement by another meter. The WHOLE input
+  // is refused, not the row: a file mixing old and new rows is a pasted-together
+  // input, and skipping the old ones with a counter would hand the verdict an
+  // aggregate that looks complete. Nothing goes to stdout, so nothing
+  // downstream can pick up half an answer.
+  if (unstamped.length > 0) {
+    process.stderr.write(
+      `analyze: refusing the whole input — ${unstamped.length} of ${rows.length} row(s) carry no meter_version` +
+        ` (first: ${unstamped.slice(0, 3).join(', ')})\n` +
+        '  recompute the rows from the transcripts or from an archive: tune-context eval prompt-metrics …\n' +
+        '  (EPIC-010: unstamped data is not used — a row without a stamp predates the measurement contract)\n',
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const agg = analyze(rows, { ...ledger, analyzedBy: meterStamp() });
 
   process.stdout.write(`${JSON.stringify(agg, null, 2)}\n`);
   process.stderr.write(`${formatAnalysis(agg)}\n`);
 }
 
-if (process.argv[1]?.endsWith('analyze.mjs')) {
+if (isEntryPoint(import.meta.url)) {
   await main();
 }