@bglocation/tune-context 2.5.0 → 3.0.0

package/bin/tune-context.mjs

@@ -16,10 +16,11 @@
 // "No model in the loop" is the feature here, not a gap — but the gap has to be
 // stated, or a CLI user cannot know what they did not get. Run the skill
 // (/tune-context) for the full pass.
-import { readFileSync, realpathSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { claudeDirs, detectExistingConfig, detectMcpServers, detectRejectedMcpServers, detectStack } from '../cli/detect.mjs';
+import { isEntryPoint } from '../cli/entry-point.mjs';
+import { readVersion } from '../cli/version.mjs';
 import {
   buildPermissionsAllow,
   generateProjectClaudeMd,
@@ -30,6 +31,7 @@ import {
   mergePermissions,
 } from '../cli/generate.mjs';
 import { staleDoctrineEntries, verify } from '../cli/verify.mjs';
+import { archiveExperiment } from '../cli/archive.mjs';
 import {
   ExperimentError,
   experimentPaths,
@@ -51,14 +53,44 @@ const HOOK_EVENTS = [
 const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
 /**
- * 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).
+ * `tune-context eval <step>` — the cost measurement's meter, reachable from any
+ * directory (EPIC-010). Before this it existed only as `node eval/<file>.mjs`, a
+ * relative path that resolves in a checkout of this repo and nowhere else, so
+ * the switch (`experiment`, from PATH) and the meter (from cwd) could come from
+ * two different versions of the code.
+ *
+ * A step's name IS its module's name — `eval/<step>.mjs` — and that is the whole
+ * mapping (PO decision 1): no aliases, because an alias is a second name for
+ * the same thing, and deriving the path from the name leaves no table in which
+ * one could be added. Dispatch and usage are both built from this object.
  */
-export function readVersion() {
-  return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+const EVAL_STEPS = {
+  'prompt-metrics': 'transcripts → JSONL rows, one per prompt, priced',
+  analyze: 'rows → one aggregate per arm; stops before a verdict',
+  verdict: 'aggregate → the gates and the finding, as JSON',
+  report: 'aggregate → one self-contained HTML page',
+  'adoption-report': 'hook log → which levers the model reaches for',
+};
+
+/** One line per step, aligned — the same listing in both usage texts. */
+function evalStepLines(indent) {
+  const width = Math.max(...Object.keys(EVAL_STEPS).map((s) => s.length));
+  return Object.entries(EVAL_STEPS)
+    .map(([step, what]) => `${indent}${step.padEnd(width)}  ${what}`)
+    .join('\n');
+}
+
+function evalUsage() {
+  return `tune-context eval — the cost measurement (EPIC-009), from any directory.
+
+Usage:
+  tune-context eval <step> [flags]
+
+Steps:
+${evalStepLines('  ')}
+
+Every flag after the step belongs to the step: tune-context eval <step> --help.
+`;
 }
 
 function usage() {
@@ -70,6 +102,8 @@ Usage:
   tune-context experiment status [--cwd <dir>]
   tune-context experiment set --tc <on|off> --rag <on|off> [--note "..."] [--cwd <dir>]
   tune-context experiment restore
+  tune-context experiment archive --out <dir>
+  tune-context eval <step> [step flags]
   tune-context --help
   tune-context --version
 
@@ -84,6 +118,15 @@ Usage:
                       byte for byte, or refuses if a touched file changed since.
                       Both --tc and --rag are required for \`set\`: an arm that
                       was only half-stated is an arm nobody can reproduce.
+                      \`archive\` copies the sessions on exp/ branches and the
+                      ledger out of reach of Claude Code's retention, append-only
+                      — run it after every arm. Refused inside a git work tree
+                      unless ignored: a transcript is the whole conversation.
+
+  eval                The meter of that experiment, one step at a time, from
+                      any directory:
+${evalStepLines('                        ')}
+                      Flags belong to the step: tune-context eval <step> --help.
 
   --force-claude-md   Regenerate a project CLAUDE.md whose hand-written content
                       still sits inside the managed block. Discards that content.
@@ -94,7 +137,7 @@ Usage:
 // Flags that consume the token after them. Listed once so the positional
 // scanner below cannot mistake a flag's VALUE for a subcommand — `experiment
 // --cwd /tmp/x status` must find `status`, not `/tmp/x`.
-const VALUE_FLAGS = new Set(['--cwd', '--tc', '--rag', '--note']);
+const VALUE_FLAGS = new Set(['--cwd', '--tc', '--rag', '--note', '--out']);
 
 /**
  * @returns {string|{error: string}} the value after `name`, or undefined if the
@@ -122,7 +165,7 @@ function positionals(args) {
   return out;
 }
 
-const EXPERIMENT_SUBCOMMANDS = ['status', 'set', 'restore'];
+const EXPERIMENT_SUBCOMMANDS = ['status', 'set', 'restore', 'archive'];
 
 /**
  * `experiment` argument shape. `set` demands BOTH --tc and --rag: an arm stated
@@ -133,6 +176,14 @@ function parseExperiment(rest, cwd) {
   const [sub] = positionals(rest);
   if (sub === undefined) return { mode: 'error', message: `Missing experiment subcommand: ${EXPERIMENT_SUBCOMMANDS.join(', ')}` };
   if (!EXPERIMENT_SUBCOMMANDS.includes(sub)) return { mode: 'error', message: `Unknown experiment subcommand: ${sub}` };
+  if (sub === 'archive') {
+    // Required, never defaulted: where whole conversations get copied to is
+    // the one choice this command must not make on the operator's behalf.
+    const out = flagValue(rest, '--out');
+    if (out?.error) return { mode: 'error', message: out.error };
+    if (out === undefined) return { mode: 'error', message: 'experiment archive requires --out <dir>' };
+    return { mode: 'experiment', sub, cwd, out: resolve(out) };
+  }
   if (sub !== 'set') return { mode: 'experiment', sub, cwd };
 
   const values = {};
@@ -148,12 +199,37 @@ function parseExperiment(rest, cwd) {
   return { mode: 'experiment', sub, cwd, tc: values['--tc'], rag: values['--rag'], note: values['--note'] ?? '' };
 }
 
+/**
+ * `eval` argument shape: the step, and everything after it VERBATIM. The step's
+ * own module parses the rest with its own parser — the one `node eval/<step>.mjs`
+ * uses — so the two doors cannot disagree about a flag. A second parser here
+ * would be a second implementation of every step's contract.
+ */
+function parseEval(rest) {
+  const [step, ...args] = rest;
+  if (step === '--help' || step === '-h') return { mode: 'eval-help' };
+  // Missing step is an error, not a listing: the TASK-078 rule for a missing
+  // command, one level down. A flag in the step's slot means the same thing.
+  if (step === undefined || step.startsWith('-')) {
+    return { mode: 'error', message: `Missing eval step: ${Object.keys(EVAL_STEPS).join(', ')}`, usage: evalUsage };
+  }
+  // hasOwn, not `in`: `tune-context eval constructor` must not find a step on
+  // Object.prototype.
+  if (!Object.hasOwn(EVAL_STEPS, step)) return { mode: 'error', message: `Unknown eval step: ${step}`, usage: evalUsage };
+  return { mode: 'eval', step, args };
+}
+
 // Pure so it is unit-testable without spawning a process. `init` is the ONLY
 // accepted command — no bare-args shortcut (PO decision 2026-07-25, TASK-078):
 // README never once documents calling this without it, and accepting anything
 // un-checked is exactly how a subcommand typo used to silently run init
 // against the wrong repo instead of failing loud.
 export function parseArgs(argv) {
+  // First, before the global flags below. After the word `eval` every flag
+  // belongs to the step: `tune-context eval prompt-metrics --help` must print
+  // that step's usage, not this CLI's, and a step's `--cwd` must not be eaten
+  // as ours (TASK-095).
+  if (argv[0] === 'eval') return parseEval(argv.slice(1));
   if (argv.includes('--help') || argv.includes('-h')) return { mode: 'help' };
   // Before the command check, like --help: `--version` is a query about the
   // tool, not an operation on a repo, so it must not require a subcommand.
@@ -168,7 +244,8 @@ export function parseArgs(argv) {
   if (!commands.includes(command)) {
     return {
       mode: 'error',
-      message: command === undefined ? `Missing command: ${commands.join(', ')}` : `Unknown command: ${command}`,
+      // `eval` is named too: it is accepted, just recognised above, first.
+      message: command === undefined ? `Missing command: ${[...commands, 'eval'].join(', ')}` : `Unknown command: ${command}`,
     };
   }
 
@@ -459,10 +536,54 @@ function runExperimentRestore() {
   console.log(`\n${RESTART_NOTE}`);
 }
 
-function runExperiment(parsed) {
+/** Shell-quoted only when it has to be, so a printed command can be pasted as is. */
+function shq(path) {
+  return /^[\w@%+=:,./-]+$/.test(path) ? path : `'${path.replaceAll("'", "'\\''")}'`;
+}
+
+async function runExperimentArchive({ out }) {
+  const { claudeDir } = claudeDirs();
+  const r = await archiveExperiment({ claudeDir, out });
+  const t = r.transcripts;
+  console.log(`tune-context experiment archive — ${r.out}\n`);
+  console.log(`Transcripts on exp/ branches, from ${r.liveProjects}:`);
+  console.log(`  ${t.new.length} new, ${t.extended.length} extended, ${t.unchanged.length} unchanged, ${t.kept.length} kept only here`);
+  for (const f of t.new) console.log(`  + ${f.path}  ${f.exp_branches.join(', ')}`);
+  for (const f of t.extended) console.log(`  ~ ${f.path} — grew by ${f.bytes_added.toLocaleString('en-US')} byte(s), the old copy was a prefix of it`);
+  for (const path of t.kept) console.log(`  · ${path} — gone from the config dir (retention); this is the only copy`);
+  if (r.naturalSkipped > 0) {
+    console.log(`  not archived: ${r.naturalSkipped} transcript(s) with no exp/ branch — natural work is not evidence, and it is your whole history`);
+  }
+  if (t.new.length + t.extended.length + t.unchanged.length + t.kept.length === 0) {
+    console.log(`\n! No transcript on an exp/ branch in ${r.liveProjects}. Is CLAUDE_CONFIG_DIR the one the measured sessions ran under?`);
+  }
+
+  // Every archive path comes from the archive: its layout is defined once, in cli/archive.mjs.
+  const p = r.paths;
+  console.log(
+    r.ledger
+      ? `\nLedger: ${r.ledger.kind}${r.ledger.kind === 'extended' ? ` (+${r.ledger.bytes_added.toLocaleString('en-US')} byte(s))` : ''}, ${r.ledger.entries} entr${r.ledger.entries === 1 ? 'y' : 'ies'} → ${p.ledger}`
+      : `\n! Ledger: none at ${r.ledgerPath}. Recomputing this archive gives exp_arm_source: branch, which the paired pool does not accept.`,
+  );
+  console.log(`Manifest: ${p.manifest}`);
+  console.log(`Checksums: ${p.sums} — check with: (cd ${shq(r.out)} && shasum -a 256 -c ${shq(basename(p.sums))})`);
+
+  console.log(`
+! A transcript is the whole conversation: contents of the files read, command output, possibly secrets.
+  Keep ${r.out} out of every repository — this command refuses a git work tree path that is not ignored.`);
+
+  const ledgerFlag = r.ledger ? ` --ledger ${shq(p.ledger)}` : '';
+  console.log(`
+Recompute from the archive — works after Claude Code has deleted the originals:
+  tune-context eval prompt-metrics --dir ${shq(p.projects)}${ledgerFlag} > rows.jsonl
+  tune-context eval analyze --rows rows.jsonl${ledgerFlag} > aggregate.json`);
+}
+
+async function runExperiment(parsed) {
   try {
     if (parsed.sub === 'status') runExperimentStatus(parsed.cwd);
     else if (parsed.sub === 'set') runExperimentSet(parsed.cwd, parsed);
+    else if (parsed.sub === 'archive') await runExperimentArchive(parsed);
     else runExperimentRestore();
   } catch (error) {
     // Operator-facing conditions (arm already set, nothing to restore, a file
@@ -474,9 +595,31 @@ function runExperiment(parsed) {
   }
 }
 
-export function main() {
+/**
+ * Hand the step its arguments, untouched. The module is imported only now, so
+ * `init`, `verify` and `experiment` never pay for parsing ~200 KB of eval/.
+ *
+ * Allowed in any experiment arm, unlike init: a step reads transcripts, rows or
+ * logs and writes only to stdout or a file it was given — never the config
+ * that an arm parks.
+ *
+ * The exit code is the step's (`process.exitCode`). An exception that escapes
+ * the step's own main() is a bug and goes up as one, the same rule as
+ * runExperiment: operator-facing conditions are already answered inside the
+ * step, with a message and exit 1.
+ */
+async function runEval({ step, args }) {
+  const { main: stepMain } = await import(new URL(`../eval/${step}.mjs`, import.meta.url));
+  await stepMain(args);
+}
+
+export async function main() {
   const parsed = parseArgs(process.argv.slice(2));
-  if (parsed.mode === 'help') {
+  if (parsed.mode === 'eval') {
+    await runEval(parsed);
+  } else if (parsed.mode === 'eval-help') {
+    process.stdout.write(evalUsage());
+  } else if (parsed.mode === 'help') {
     console.log(usage());
   } else if (parsed.mode === 'version') {
     // Bare number, no prefix or banner — this is what a script greps.
@@ -484,49 +627,22 @@ export function main() {
   } else if (parsed.mode === 'error') {
     // Usage on stderr + exit 1, never a stacktrace, and — because this whole
     // branch returns before runInit() is ever called — no config file is
-    // touched on an invalid invocation (TASK-078).
-    process.stderr.write(`${parsed.message}\n\n${usage()}`);
+    // touched on an invalid invocation (TASK-078). An `eval` mistake gets the
+    // list of steps rather than the whole CLI's usage.
+    process.stderr.write(`${parsed.message}\n\n${(parsed.usage ?? usage)()}`);
     process.exitCode = 1;
   } else if (parsed.mode === 'verify') {
     runVerify(parsed.cwd);
   } else if (parsed.mode === 'experiment') {
-    runExperiment(parsed);
+    await runExperiment(parsed);
   } else {
     runInit(parsed.cwd, { forceClaudeMd: parsed.forceClaudeMd });
   }
 }
 
-/**
- * True only when THIS file is the process entry point, so importing it for
- * parseArgs/main (tests, or the extensionless bin/tune-context wrapper) never
- * runs the 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 spawn 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 this file), the
- * extensionless wrapper (a different real path, so this stays false and the
- * wrapper'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.
- */
-function isEntryPoint() {
-  if (!process.argv[1]) return false;
-  try {
-    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
-  } 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;
-  }
-}
-
-if (isEntryPoint()) {
-  main();
+// Run only when this file IS the entry point, never as a side effect of an
+// import (tests, the extensionless wrapper). Why that is a realpath comparison
+// and not a filename test — the 2.0.0 silent CLI — is in cli/entry-point.mjs.
+if (isEntryPoint(import.meta.url)) {
+  await main();
 }

package/cli/archive.mjs

@@ -0,0 +1,322 @@
+// tune-context experiment archive — the series' transcripts and ledger, kept
+// past Claude Code's retention (TASK-098, EPIC-010 PO decision 5).
+//
+// A required meter stamp (TASK-097) closes the door on old ROWS, so the only way
+// back to old data is old TRANSCRIPTS recomputed by a meter one trusts. Those
+// live in <config>/projects and Claude Code deletes them after
+// `cleanupPeriodDays` (30 by default). EPIC-009 found its meter bug after that
+// window: the voided verdict could never be recomputed. Transcripts alone are
+// not enough either — a row's arm comes from the branch AND the ledger
+// (`branch+ledger`), so the ledger travels with them.
+//
+// Four rules, and they are the design:
+//
+//   1. **Append-only.** A file identical to the live one is skipped; a live file
+//      that EXTENDS the archived one byte for byte (a resumed session, a ledger
+//      that grew) replaces it; any other difference refuses the whole run and
+//      leaves the archive untouched — the discipline `experiment restore` keeps.
+//   2. **What retention deleted stays.** A file gone from the config dir is kept
+//      and still listed: that is what the archive is for.
+//   3. **Experiment sessions only.** A transcript qualifies by one entry on a
+//      branch claiming the convention (`exp/…`), deliberately broader than
+//      arm.mjs's strict parser — an off-convention branch is archived too, so a
+//      recount rejects it by name instead of losing it. Natural work is not
+//      archived: it is not evidence, and an archive of it would be an archive of
+//      the user's whole Claude Code history, a different privacy class.
+//   4. **Never where git would publish it.** A transcript is the whole
+//      conversation — file contents, command output, possibly secrets — and
+//      this repo is public. A destination inside a git work tree that git does
+//      not ignore is refused, with no flag to override it.
+import { createHash } from 'node:crypto';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { ExperimentError, experimentPaths, readLedgerFile } from './experiment.mjs';
+import { gitEnv, meterStamp } from './version.mjs';
+
+// The two files that describe the archive, next to the data they describe.
+const MANIFEST = 'manifest.json';
+const SUMS = 'SHA256SUMS';
+
+/** A branch name that claims the experiment convention, valid or not. */
+function claimsExperiment(branch) {
+  if (typeof branch !== 'string') return false;
+  const b = branch.trim();
+  return b === 'exp' || b.startsWith('exp/');
+}
+
+/** What a transcript says about itself: the exp/ branches and the Claude Code
+ *  versions on its entries. Every line is parsed — a quick substring filter
+ *  would skip a file that wrote its JSON differently, and silently. */
+function describeTranscript(buffer, parseEntry) {
+  const branches = new Set();
+  const versions = new Set();
+  for (const line of buffer.toString('utf8').split('\n')) {
+    const entry = parseEntry(line);
+    if (entry === null) continue;
+    if (claimsExperiment(entry.gitBranch)) branches.add(entry.gitBranch);
+    if (typeof entry.version === 'string') versions.add(entry.version);
+  }
+  return { exp_branches: [...branches].sort(), cc_versions: [...versions].sort() };
+}
+
+const sha256 = (buffer) => createHash('sha256').update(buffer).digest('hex');
+
+/**
+ * How the live bytes relate to the archived ones: the same, an append, or a
+ * change — and for a change, the byte and line where the two first part.
+ */
+function compareBytes(archived, live) {
+  if (archived.equals(live)) return { kind: 'unchanged' };
+  if (live.length > archived.length && live.subarray(0, archived.length).equals(archived)) {
+    return { kind: 'extended', bytesAdded: live.length - archived.length };
+  }
+  const n = Math.min(archived.length, live.length);
+  let at = 0;
+  while (at < n && archived[at] === live[at]) at += 1;
+  let line = 1;
+  for (let i = 0; i < at; i += 1) if (archived[i] === 0x0a) line += 1;
+  return { kind: 'changed', byte: at, line };
+}
+
+/** The nearest part of `path` that exists: the path itself, or a parent. */
+function nearestExisting(path) {
+  let probe = path;
+  while (!existsSync(probe)) probe = dirname(probe);
+  return probe;
+}
+
+/**
+ * `path` resolved through every symlink on the part of it that exists — it may
+ * not exist yet. Every guard below compares these: two names for one directory
+ * (a symlinked config dir, macOS's /var → /private/var) must not pass for two.
+ */
+function realPath(path) {
+  const probe = nearestExisting(path);
+  return join(realpathSync(probe), relative(probe, path));
+}
+
+/** A directory with a `.git` somewhere above it — read off disk, for when git itself is missing. */
+function insideGitTreeOnDisk(dir) {
+  for (let d = dir; ; d = dirname(d)) {
+    if (existsSync(join(d, '.git'))) return true;
+    if (dirname(d) === d) return false;
+  }
+}
+
+/**
+ * Rule 4. `destinations` are every path the archive will hold, relative to
+ * `out` — all of them checked, not the directory: git matches `archive/` only
+ * against files inside a directory that does not exist yet, and `*.json` would
+ * ignore the manifest while publishing every transcript.
+ */
+function refuseIfPublishable(out, destinations) {
+  const realOut = realPath(out);
+  const realProbe = nearestExisting(realOut);
+
+  const env = gitEnv();
+  let topDir;
+  try {
+    const top = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: realProbe, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    topDir = realpathSync(top.trim());
+  } catch (e) {
+    if (e.code !== 'ENOENT') return; // not a work tree: nothing here to publish it
+    if (!insideGitTreeOnDisk(realProbe)) return;
+    throw new ExperimentError(
+      `refusing to archive into ${out}: it is inside a git work tree, and without git there is no telling whether it is ignored`,
+      'transcripts are whole conversations — choose a directory outside any repository',
+    );
+  }
+
+  const rels = destinations.map((d) => relative(topDir, join(realOut, d)));
+  // NUL-separated both ways: without -z git C-quotes a path that is not plain
+  // ASCII ("archiwum-\305\274…"), it never equals the name asked about, and an
+  // ignored directory reads as exposed. --stdin keeps a long series off argv.
+  const check = spawnSync('git', ['check-ignore', '--stdin', '-z'], {
+    cwd: topDir,
+    env,
+    input: rels.map((r) => `${r}\0`).join(''),
+    encoding: 'utf8',
+  });
+  // 0: some ignored, 1: none ignored; anything else is git failing to answer,
+  // and an unanswered question is not a yes.
+  const ignored = check.status === 0 || check.status === 1 ? new Set(check.stdout.split('\0').filter(Boolean)) : new Set();
+  const exposed = rels.filter((r) => !ignored.has(r));
+  if (exposed.length === 0) return;
+  throw new ExperimentError(
+    `refusing to archive into ${out}: it is inside the git work tree ${topDir} and git does not ignore` +
+      ` ${exposed.length} of the ${rels.length} file(s) it would hold (first: ${exposed[0]})`,
+    'A transcript is the whole conversation: file contents, command output, possibly secrets. Add the directory to' +
+      ' .gitignore, or archive outside any repository. There is no flag to override this.',
+  );
+}
+
+function writeAtomically(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, data);
+  renameSync(tmp, path);
+}
+
+const within = (parent, child) => {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+
+/**
+ * Archive every experiment transcript and the ledger from `claudeDir` into
+ * `out`, in the config dir's own layout — `projects/<slug>/<session>.jsonl`,
+ * `tune-context/experiment.jsonl` — plus `manifest.json` and `SHA256SUMS`
+ * (checkable with `shasum -a 256 -c`, no code of ours needed).
+ *
+ * Reads everything first, decides, checks, and only then writes: a refusal
+ * leaves the archive exactly as it was. Writes nothing in the config dir, the
+ * ledger or the switch state, so it runs in any arm.
+ *
+ * @returns {Promise<object>} what happened to each file, the manifest, and
+ *   `paths` — where the archive keeps what, so no caller re-derives its layout.
+ * @throws {ExperimentError} a destination git would publish, an archived file
+ *   the live one changed other than by appending, or `out` in a place that
+ *   would feed the archive back into the next measurement.
+ */
+export async function archiveExperiment({ claudeDir, out, now = new Date() }) {
+  // The transcript reader is prompt-metrics' own — one definition of where
+  // transcripts are and how a line parses. Loaded here, not at the top, so the
+  // rest of the CLI never pays for eval/.
+  const { findTranscripts, parseEntry } = await import('../eval/prompt-metrics.mjs');
+  const outDir = resolve(out);
+  const liveProjects = join(claudeDir, 'projects');
+  const archProjects = join(outDir, 'projects');
+  // The archive keeps the config dir's own layout, so the ledger sits where
+  // experimentPaths() puts it — one definition of that place.
+  const liveLedger = experimentPaths(claudeDir).ledgerPath;
+  const ledgerRel = relative(claudeDir, liveLedger);
+  const archLedger = join(outDir, ledgerRel);
+
+  // Inside <config>/projects the archive would be read back by the next
+  // prompt-metrics run as live transcripts, every session counted twice; the
+  // config dir itself would make the archive the live ledger's own copy.
+  // Compared by real path: a symlinked config dir is still that directory.
+  const realOut = realPath(outDir);
+  if (realOut === realPath(claudeDir) || within(realPath(liveProjects), realOut)) {
+    throw new ExperimentError(
+      `refusing to archive into ${outDir}: inside the config dir's projects/ the archive would be measured again as live transcripts`,
+      'choose a directory outside the config dir, or anywhere in it except projects/',
+    );
+  }
+  if (existsSync(outDir) && !statSync(outDir).isDirectory()) {
+    throw new ExperimentError(`refusing to archive into ${outDir}: it is a file, not a directory`);
+  }
+
+  // 1. Read the live side.
+  const live = new Map();
+  let natural = 0;
+  for (const path of findTranscripts(liveProjects)) {
+    const buffer = readFileSync(path);
+    const info = describeTranscript(buffer, parseEntry);
+    if (info.exp_branches.length === 0) {
+      natural += 1;
+      continue;
+    }
+    live.set(relative(liveProjects, path), { buffer, info });
+  }
+
+  // 2. Decide against what the archive already holds. Nothing is written yet.
+  // One rule for every file, transcript or ledger: new, unchanged, extended —
+  // or a conflict, which refuses the run.
+  const conflicts = [];
+  const decide = (path, bytes, extra = {}) => {
+    const dest = join(outDir, path);
+    const cmp = existsSync(dest) ? compareBytes(readFileSync(dest), bytes) : { kind: 'new' };
+    if (cmp.kind === 'changed') {
+      conflicts.push({ path, ...cmp });
+      return null;
+    }
+    return { path, kind: cmp.kind, bytesAdded: cmp.bytesAdded ?? 0, buffer: bytes, ...extra };
+  };
+  const kept = (path) => ({ path, kind: 'kept', bytesAdded: 0, buffer: readFileSync(join(outDir, path)) });
+
+  const files = [];
+  for (const [rel, { buffer, info }] of live) {
+    const file = decide(`projects/${rel}`, buffer, { info });
+    if (file) files.push(file);
+  }
+  for (const dest of findTranscripts(archProjects)) {
+    const rel = relative(archProjects, dest);
+    if (live.has(rel)) continue;
+    const file = kept(`projects/${rel}`);
+    files.push({ ...file, info: describeTranscript(file.buffer, parseEntry) });
+  }
+  let ledger = null;
+  if (existsSync(liveLedger)) ledger = decide(ledgerRel, readFileSync(liveLedger));
+  else if (existsSync(archLedger)) ledger = kept(ledgerRel);
+
+  // 3. Check, still before any write.
+  const destinations = [...files.map((f) => f.path), ...conflicts.map((c) => c.path), MANIFEST, SUMS];
+  if (ledger || existsSync(liveLedger)) destinations.push(ledgerRel);
+  refuseIfPublishable(outDir, [...new Set(destinations)]);
+
+  if (conflicts.length > 0) {
+    throw new ExperimentError(
+      `refusing to archive: ${conflicts.length} file(s) changed other than by appending — nothing was written\n` +
+        conflicts.map((c) => `  ${c.path} — first difference at byte ${c.byte} (line ${c.line})`).join('\n'),
+      'A transcript or the ledger only ever grows. A file changed in the middle is a different file under the same' +
+        ' name or a damaged copy — compare the two by hand, or archive into a new directory. The archive is as it was.',
+    );
+  }
+
+  // 4. Write: data first, then the two files that describe it.
+  for (const f of ledger ? [...files, ledger] : files) {
+    if (f.kind === 'new' || f.kind === 'extended') writeAtomically(join(outDir, f.path), f.buffer);
+  }
+
+  // By code unit, as `LC_ALL=C sort` would: the same order on every machine,
+  // whatever its collation.
+  const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const transcripts = files
+    .map((f) => ({
+      path: f.path,
+      sha256: sha256(f.buffer),
+      bytes: f.buffer.length,
+      exp_branches: f.info.exp_branches,
+      cc_versions: f.info.cc_versions,
+      // false: retention removed it from the config dir, and this is the only copy.
+      in_config_dir: f.kind !== 'kept',
+    }))
+    .sort(byPath);
+  const ledgerEntry = ledger && {
+    path: ledgerRel,
+    sha256: sha256(ledger.buffer),
+    bytes: ledger.buffer.length,
+    entries: readLedgerFile(archLedger).length,
+    in_config_dir: ledger.kind !== 'kept',
+  };
+  const manifest = {
+    schema: 'tune-context/archive@1',
+    archived_at: now.toISOString(),
+    // Which code wrote the archive, in the meter's own grammar (TASK-097).
+    archived_by: meterStamp(),
+    transcripts,
+    ledger: ledgerEntry,
+  };
+  writeAtomically(join(outDir, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+  const sums = [...transcripts, ...(ledgerEntry ? [ledgerEntry] : [])].sort(byPath);
+  writeAtomically(join(outDir, SUMS), sums.map((f) => `${f.sha256}  ${f.path}\n`).join(''));
+
+  const of = (kind) => files.filter((f) => f.kind === kind);
+  return {
+    out: outDir,
+    paths: { projects: archProjects, ledger: archLedger, manifest: join(outDir, MANIFEST), sums: join(outDir, SUMS) },
+    liveProjects,
+    transcripts: {
+      new: of('new').map((f) => ({ path: f.path, exp_branches: f.info.exp_branches })),
+      extended: of('extended').map((f) => ({ path: f.path, bytes_added: f.bytesAdded })),
+      unchanged: of('unchanged').map((f) => f.path),
+      kept: of('kept').map((f) => f.path),
+    },
+    naturalSkipped: natural,
+    ledger: ledger ? { kind: ledger.kind, entries: ledgerEntry.entries, bytes_added: ledger.bytesAdded ?? 0 } : null,
+    ledgerPath: liveLedger,
+    manifest,
+  };
+}