@bglocation/tune-context 2.3.1 → 2.5.0

package/cli/experiment.mjs

@@ -0,0 +1,674 @@
+// tune-context experiment — the second arm (TASK-087).
+//
+// Measuring one arm is not measuring. Everything else in eval/ reads what a
+// session DID; this is the only module that changes what a session HAS, so it
+// is also the only one that can break a live install. Three rules follow from
+// that, and they are the whole design:
+//
+//   1. **Reversibility before mutation.** Every touched path is fingerprinted
+//      and copied into a backup dir, and the state file naming it is on disk,
+//      BEFORE the path is modified. A `set` killed halfway through still leaves
+//      a `restore` that works — the acceptance criterion, not a nicety.
+//   2. **`restore` may never eat somebody else's work.** A whole working
+//      session sits between `set` and `restore`; the user may well have added a
+//      permission to settings.json or written below CLAUDE.md's marker (exactly
+//      the TASK-082 scenario). So restore compares each path against the
+//      fingerprint `set` left behind and REFUSES on any mismatch, naming the
+//      file. Refusing is the correct outcome here, not a failure.
+//   3. **The ledger is the source of truth, detection is the cross-check.**
+//      `observeArm()` reads the live config, but an analyzer assigns a session
+//      to an arm by timestamp against the ledger. Absence of RAG calls in a
+//      transcript never proved RAG's absence (TASK-070/083) — and absence of a
+//      hook registration does not prove the arm either: a plugin-channel
+//      install registers hooks somewhere this switch cannot see.
+//
+// What `tc off` covers is a PO decision (EPIC-009, 2026-07-30): hooks
+// registered in settings.json, the managed block in the project CLAUDE.md,
+// doctrine skills, agents. Four interventions deliberately mixed into one
+// variable — at small n the biggest effect is the easiest one to detect;
+// splitting them is a separate experiment AFTER the first results.
+//
+// What `rag off` covers: the PROJECT `.mcp.json`, and nothing else. The user
+// scope (`~/.claude.json`) is rewritten by Claude Code while it runs, so a
+// switch that edited it would be overwritten, or would corrupt live state.
+// `status` says this out loud rather than letting the operator assume RAG is
+// globally off.
+import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { END_MARKER, START_MARKER, removeManagedBlock } from './managed-block.mjs';
+import { doctrineEntries } from './sync-doctrine.mjs';
+import { fingerprint } from './verify.mjs';
+
+const STATE_VERSION = 1;
+
+/**
+ * Operator-facing failure: a condition the user can act on (arm already set,
+ * nothing to restore, a file changed under us). Carries a `hint` so the CLI can
+ * print the next step instead of a stacktrace — an instrument that mutates a
+ * live config owes the reader a way out.
+ */
+export class ExperimentError extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.name = 'ExperimentError';
+    this.hint = hint;
+  }
+}
+
+/** All experiment state lives under the same `tune-context/` dir the hooks already use. */
+export function experimentPaths(claudeDir) {
+  const dir = join(claudeDir, 'tune-context');
+  return {
+    dir,
+    statePath: join(dir, 'experiment-state.json'),
+    ledgerPath: join(dir, 'experiment.jsonl'),
+    backupDir: join(dir, 'experiment-backup'),
+  };
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path, obj) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`);
+}
+
+function readText(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** The hook SCRIPT names this package deploys — what a settings.json command would name. */
+function hookScriptNames(pkgRoot) {
+  return doctrineEntries(pkgRoot)
+    .filter((e) => e.kind === 'hooks' && e.name.endsWith('.mjs'))
+    .map((e) => e.name);
+}
+
+/** Deployed-doctrine entries of one kind, split into what is on disk and what is not. */
+function deployed(claudeDir, pkgRoot, kind) {
+  const names = doctrineEntries(pkgRoot)
+    .filter((e) => e.kind === kind)
+    .map((e) => e.name);
+  const present = names.filter((name) => existsSync(join(claudeDir, kind, name)));
+  return { names, present, missing: names.filter((n) => !present.includes(n)) };
+}
+
+/**
+ * Does this settings.json command fire one of OUR hook scripts?
+ *
+ * One definition, used by both the reader (`hookRegistrations`) and the writer
+ * (`stripHookRegistrations`) — two spellings of "ours" would eventually disagree,
+ * and the way they would disagree is: something reported as removed that is still
+ * registered, i.e. an off arm that is not off.
+ *
+ * Matching is by SCRIPT NAME anywhere in the command, deliberately looser than
+ * verify's resolve-the-path cross-check: a registration that merely *might* fire
+ * our hook has to go, whatever dir it points at.
+ */
+function firesOurHook(command, scriptNames) {
+  return typeof command === 'string' && scriptNames.some((name) => command.includes(name));
+}
+
+/** Every `{event, command}` in a settings object naming one of `scriptNames`. */
+function hookRegistrations(settings, scriptNames) {
+  const found = [];
+  for (const [event, groups] of Object.entries(settings?.hooks || {})) {
+    for (const group of groups || []) {
+      for (const hook of group?.hooks || []) {
+        if (firesOurHook(hook.command, scriptNames)) found.push({ event, command: hook.command });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Drop every hook registration naming one of this package's scripts (see
+ * firesOurHook for what counts as ours). Groups emptied by the removal are
+ * dropped, and so is an event left with no groups — restore puts the file back
+ * byte for byte from the backup, so tidying costs nothing.
+ *
+ * Entries belonging to anyone else are never touched.
+ *
+ * @returns {{settings: object, removed: string[]}} a NEW settings object
+ */
+export function stripHookRegistrations(settings, scriptNames) {
+  const next = structuredClone(settings ?? {});
+  const removed = [];
+  for (const [event, groups] of Object.entries(next.hooks || {})) {
+    const kept = [];
+    for (const group of groups || []) {
+      if (!Array.isArray(group?.hooks)) {
+        kept.push(group); // not a shape we wrote — not ours to judge
+        continue;
+      }
+      const hooks = group.hooks.filter((hook) => {
+        const ours = firesOurHook(hook.command, scriptNames);
+        if (ours) removed.push(`${event}: ${hook.command}`);
+        return !ours;
+      });
+      if (hooks.length) kept.push({ ...group, hooks });
+    }
+    if (kept.length) next.hooks[event] = kept;
+    else delete next.hooks[event];
+  }
+  if (next.hooks && Object.keys(next.hooks).length === 0) delete next.hooks;
+  return { settings: next, removed };
+}
+
+/**
+ * What the live configuration currently looks like — the CROSS-CHECK, never the
+ * verdict. Read-only.
+ *
+ * Each component reports `on` / `off` / `partial` / `unknown`; `tc` is `on` only
+ * when all the observable ones are, `off` only when none is, and `mixed`
+ * otherwise. `mixed` is a real and useful answer: a half-applied `set`, or a
+ * `tune-context init` run during an off arm, both land there, and both
+ * invalidate a measurement run.
+ *
+ * `unknown` covers the one case that must not be mistaken for `off`: a package
+ * root that lists no skills (or no agents) at all. Nothing deployed out of
+ * nothing shipped says nothing about the arm — counting it as `off` would drag
+ * a perfectly on config to `mixed` and stall a run over a phantom.
+ *
+ * @returns {{tc: 'on'|'off'|'mixed'|'unknown', rag: 'on'|'off', components: object[], mcp: object}}
+ */
+export function observeArm({ claudeDir, cwd, pkgRoot }) {
+  const settingsPath = join(claudeDir, 'settings.json');
+  const scriptNames = hookScriptNames(pkgRoot);
+  const registrations = hookRegistrations(readJson(settingsPath), scriptNames);
+
+  const claudeMdPath = join(cwd, 'CLAUDE.md');
+  const claudeMd = readText(claudeMdPath);
+  const hasBlock = claudeMd !== null && [START_MARKER, END_MARKER].every((m) => claudeMd.includes(m));
+
+  const skills = deployed(claudeDir, pkgRoot, 'skills');
+  const agents = deployed(claudeDir, pkgRoot, 'agents');
+
+  const mcpPath = join(cwd, '.mcp.json');
+  const mcpServers = Object.keys(readJson(mcpPath)?.mcpServers || {});
+
+  const tri = (present, total) => (total === 0 ? 'unknown' : present === 0 ? 'off' : present === total ? 'on' : 'partial');
+  const deployedDetail = ({ present, names }) => (names.length === 0 ? 'this package deploys none' : `${present.length}/${names.length} deployed`);
+
+  const components = [
+    {
+      kind: 'hooks',
+      // Same rule as skills/agents below: with no script names to look for,
+      // "none registered" is a vacuous truth, not an observation.
+      label: `hook registrations in ${settingsPath}`,
+      state: scriptNames.length === 0 ? 'unknown' : registrations.length ? 'on' : 'off',
+      detail: scriptNames.length === 0 ? 'this package ships no hook scripts' : registrations.length ? `${registrations.length} registered` : 'none registered',
+    },
+    {
+      kind: 'claude-md',
+      label: `managed block in ${claudeMdPath}`,
+      state: hasBlock ? 'on' : 'off',
+      detail: claudeMd === null ? 'no CLAUDE.md in this project' : hasBlock ? 'present' : 'absent',
+    },
+    {
+      kind: 'skills',
+      label: `doctrine skills in ${join(claudeDir, 'skills')}`,
+      state: tri(skills.present.length, skills.names.length),
+      detail: deployedDetail(skills),
+    },
+    {
+      kind: 'agents',
+      label: `agents in ${join(claudeDir, 'agents')}`,
+      state: tri(agents.present.length, agents.names.length),
+      detail: deployedDetail(agents),
+    },
+  ];
+
+  const states = components.map((c) => c.state).filter((s) => s !== 'unknown');
+  const tc = states.length === 0 ? 'unknown' : states.every((s) => s === 'on') ? 'on' : states.every((s) => s === 'off') ? 'off' : 'mixed';
+
+  return {
+    tc,
+    rag: mcpServers.length ? 'on' : 'off',
+    components,
+    mcp: { path: mcpPath, servers: mcpServers, exists: existsSync(mcpPath) },
+  };
+}
+
+/**
+ * The paths `set` would touch to reach the requested arm, each with the mutation
+ * that gets it there. Only ever turns things OFF: re-enabling is `restore`'s job,
+ * because only restore knows the exact bytes that were there before.
+ */
+function planMutations({ claudeDir, cwd, pkgRoot, tc, rag }) {
+  const mutations = [];
+
+  if (tc === 'off') {
+    const settingsPath = join(claudeDir, 'settings.json');
+    const settings = readJson(settingsPath);
+    const scriptNames = hookScriptNames(pkgRoot);
+    const registrations = hookRegistrations(settings, scriptNames);
+    if (registrations.length) {
+      mutations.push({
+        label: `${registrations.length} hook registration(s) removed from settings.json`,
+        path: settingsPath,
+        apply: () => {
+          // Re-read at apply time: minutes may pass between planning and
+          // applying when an earlier mutation is slow, and clobbering an
+          // unrelated edit made in between is the one thing this module must
+          // never do. If the re-read comes back unparseable, stop — writing the
+          // `{}` that a null would strip down to is the very clobber this
+          // re-read exists to prevent, and the backup already taken is the only
+          // remaining copy.
+          const current = readJson(settingsPath);
+          if (current === null) throw new Error(`${settingsPath} is no longer readable JSON — refusing to overwrite it`);
+          const { settings: stripped } = stripHookRegistrations(current, scriptNames);
+          writeJson(settingsPath, stripped);
+        },
+      });
+    }
+
+    const claudeMdPath = join(cwd, 'CLAUDE.md');
+    const claudeMd = readText(claudeMdPath);
+    if (claudeMd !== null && [START_MARKER, END_MARKER].every((m) => claudeMd.includes(m))) {
+      mutations.push({
+        label: 'managed block removed from the project CLAUDE.md',
+        path: claudeMdPath,
+        apply: () => {
+          const { content } = removeManagedBlock(readText(claudeMdPath));
+          writeFileSync(claudeMdPath, content);
+        },
+      });
+    }
+
+    for (const kind of ['skills', 'agents']) {
+      for (const name of deployed(claudeDir, pkgRoot, kind).present) {
+        const path = join(claudeDir, kind, name);
+        mutations.push({ label: `${kind}/${name} parked`, path, apply: () => rmSync(path, { recursive: true, force: true }) });
+      }
+    }
+  }
+
+  if (rag === 'off') {
+    const mcpPath = join(cwd, '.mcp.json');
+    if (existsSync(mcpPath)) {
+      mutations.push({ label: 'project .mcp.json parked', path: mcpPath, apply: () => rmSync(mcpPath, { force: true }) });
+    }
+  }
+
+  return mutations;
+}
+
+export function readState(claudeDir) {
+  return readJson(experimentPaths(claudeDir).statePath);
+}
+
+const PREVIEW_MAX = 80;
+
+function preview(line) {
+  if (line === undefined) return '(nothing at this line)';
+  const trimmed = line.trimEnd();
+  return trimmed.length > PREVIEW_MAX ? `${trimmed.slice(0, PREVIEW_MAX)}…` : trimmed || '(blank line)';
+}
+
+/** Every file under `root`, as sorted paths relative to it. */
+function listFiles(root) {
+  const out = [];
+  const walk = (dir, rel) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const next = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(join(dir, entry.name), next);
+      else out.push(next);
+    }
+  };
+  walk(root, '');
+  return out.sort();
+}
+
+/**
+ * Where two texts stop agreeing, trimming the common head and the common tail.
+ *
+ * Not a diff algorithm and not trying to be one: it answers "from which line do
+ * they differ, and how many lines does each side hold there", which is what a
+ * refusal message needs. An LCS would find the prettiest alignment of an edit
+ * scattered through a file; it would not change the decision the reader has to
+ * make, and it is a lot of code to carry for a message printed rarely.
+ */
+function textDifference(current, saved) {
+  const a = current.split('\n');
+  const b = saved.split('\n');
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start += 1;
+  let endA = a.length - 1;
+  let endB = b.length - 1;
+  while (endA >= start && endB >= start && a[endA] === b[endB]) {
+    endA -= 1;
+    endB -= 1;
+  }
+  return { line: start + 1, dropped: endA - start + 1, returned: endB - start + 1, nowLine: a[start], savedLine: b[start] };
+}
+
+/**
+ * What `restore` would replace, in words — the "and the difference" half of the
+ * task's requirement, so a refusal names not just WHICH file diverged but WHAT
+ * would be lost by overwriting it.
+ *
+ * Compares the live path against the saved copy, in that direction on purpose:
+ * the saved copy is what restore would write, so lines only in the live file are
+ * the ones about to disappear. That is the number a reader is deciding on.
+ *
+ * @returns {string[]} lines for the message; empty when there is nothing useful
+ *   to say (a path that is simply gone, or one with no saved copy at all)
+ */
+function describeDifference(livePath, backupPath) {
+  if (!backupPath || !existsSync(backupPath)) return [];
+  if (!existsSync(livePath)) return ['restoring would put the saved copy back where it was'];
+
+  const liveIsDir = statSync(livePath).isDirectory();
+  const savedIsDir = statSync(backupPath).isDirectory();
+  // A path that changed KIND has no line diff and no file list — and walking it
+  // as if it had one throws ENOTDIR, which would replace this whole refusal
+  // (including the line naming the backups) with a stacktrace.
+  if (liveIsDir !== savedIsDir) {
+    return [`${liveIsDir ? 'a directory' : 'a file'} is there now, ${savedIsDir ? 'a directory' : 'a file'} in the saved copy`];
+  }
+
+  if (liveIsDir) {
+    const live = new Set(listFiles(livePath));
+    const saved = new Set(listFiles(backupPath));
+    const onlyLive = [...live].filter((f) => !saved.has(f));
+    const onlySaved = [...saved].filter((f) => !live.has(f));
+    const changed = [...live].filter((f) => saved.has(f) && fingerprint(join(livePath, f)) !== fingerprint(join(backupPath, f)));
+    const show = (names) => `${names.slice(0, 3).join(', ')}${names.length > 3 ? `, +${names.length - 3} more` : ''}`;
+    return [
+      `restoring would drop ${onlyLive.length} file(s) only in the current copy${onlyLive.length ? `: ${show(onlyLive)}` : ''}`,
+      `                overwrite ${changed.length} changed file(s)${changed.length ? `: ${show(changed)}` : ''}`,
+      `                and bring back ${onlySaved.length} file(s)${onlySaved.length ? `: ${show(onlySaved)}` : ''}`,
+    ];
+  }
+
+  const current = readFileSync(livePath);
+  const saved = readFileSync(backupPath);
+  // A NUL byte means splitting on newlines would produce noise, not lines.
+  if (current.includes(0) || saved.includes(0)) {
+    return [`binary content differs: ${current.length} byte(s) now, ${saved.length} in the saved copy`];
+  }
+
+  const diff = textDifference(current.toString('utf8'), saved.toString('utf8'));
+  return [
+    `first difference at line ${diff.line}: restoring would drop ${diff.dropped} line(s) and bring back ${diff.returned}`,
+    `  now:   ${preview(diff.nowLine)}`,
+    `  saved: ${preview(diff.savedLine)}`,
+  ];
+  // Note for the reader of this message, stated once in the hint below rather
+  // than repeated per entry: the comparison is against the PRE-experiment copy,
+  // which is what restore would write — so part of every difference shown is the
+  // arm's own change (the managed block it removed, the registrations it
+  // stripped), not the user's edit. Diffing against what `set` left behind would
+  // isolate the edit exactly, but only by keeping a second copy of every touched
+  // path for the length of a working session. The numbers above are what restore
+  // would do; the qualifier keeps them from being read as "your edit was 7 lines".
+}
+
+/**
+ * Append one line to the append-only ledger. `{ts, tc, rag, note}` is the shape
+ * TASK-087 specifies and is always present; `event` is a superset field so an
+ * analyzer can tell a `set` from a `restore` without parsing prose.
+ */
+export function appendLedger(claudeDir, entry) {
+  const { ledgerPath } = experimentPaths(claudeDir);
+  mkdirSync(dirname(ledgerPath), { recursive: true });
+  appendFileSync(ledgerPath, `${JSON.stringify(entry)}\n`);
+  return entry;
+}
+
+/** Parsed ledger, oldest first. Unparseable lines are skipped, never guessed at. */
+export function readLedger(claudeDir) {
+  const raw = readText(experimentPaths(claudeDir).ledgerPath);
+  if (raw === null) return [];
+  return raw
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Switch to `{tc, rag}`, recording everything needed to switch back.
+ *
+ * Ordering is load-bearing:
+ *   state file → ledger entry → mutations, each mutation backed up and recorded
+ *   before it runs.
+ *
+ * The ledger entry is written BEFORE the first mutation on purpose. A `set` that
+ * dies halfway leaves a config that is genuinely half-off, and a session started
+ * in that window really is a mixed session — the ledger entry plus the later
+ * restore entry bracket exactly that window, which is what lets an analyzer
+ * throw the session out instead of silently averaging it in.
+ *
+ * @param {'on'|'off'} tc
+ * @param {'on'|'off'} rag
+ * @returns {{arm, armBefore, ledgerEntry, changes: string[], statePath: string|null, alreadySet: boolean, warnings: string[]}}
+ * @throws {ExperimentError} when a DIFFERENT arm is already set — nesting states
+ *   would lose the original bytes, which is the one failure restore cannot survive.
+ */
+export function experimentSet({ claudeDir, cwd, pkgRoot, tc, rag, note = '', now = new Date() }) {
+  const { statePath, backupDir } = experimentPaths(claudeDir);
+  const arm = { tc, rag };
+  const existing = readState(claudeDir);
+
+  if (existing && (existing.arm.tc !== tc || existing.arm.rag !== rag)) {
+    throw new ExperimentError(
+      `arm tc=${existing.arm.tc} rag=${existing.arm.rag} is already set (since ${existing.startedAt})`,
+      'run `tune-context experiment restore` first — setting a second arm on top would lose the bytes the first one saved',
+    );
+  }
+
+  // Re-setting the arm already in force: no config change, but the ledger entry
+  // still goes in. That is not redundancy — a run whose ledger has no entry at
+  // its start cannot be assigned to an arm at all, and "the arm did not change"
+  // is exactly the case an operator hits when the second pass is `on`.
+  if (existing) {
+    const ledgerEntry = appendLedger(claudeDir, { ts: now.toISOString(), event: 'set', tc, rag, note });
+    return { arm, armBefore: existing.armBefore, ledgerEntry, changes: [], statePath, alreadySet: true, warnings: [] };
+  }
+
+  const observed = observeArm({ claudeDir, cwd, pkgRoot });
+  const warnings = [];
+  const mutations = planMutations({ claudeDir, cwd, pkgRoot, tc, rag });
+
+  // Asked for an arm we cannot bring about: `set` only ever turns things off, so
+  // `--tc on` while the doctrine is missing records an arm the config does not
+  // have. Say so loudly — this is the pre-run check in COST_EVALUATION_PROCEDURE
+  // §4 catching a mixed arm before the first prompt, not after the run.
+  if (tc === 'on' && observed.tc !== 'on') {
+    warnings.push(
+      `ledger now says tc=on, but the config observes tc=${observed.tc} — run \`tune-context init\` (or \`experiment restore\`) before the session, or the run is mislabelled`,
+    );
+  }
+  if (rag === 'on' && observed.rag !== 'on') {
+    warnings.push(`ledger now says rag=on, but this project has no .mcp.json server — the run would be mislabelled`);
+  }
+
+  // What the config looked like BEFORE this switch touched it — this is what
+  // `restore` writes back into the ledger. It can legitimately be `mixed`, and
+  // that value is recorded as-is rather than rounded to `on`: a config that was
+  // already half-configured cannot label a run, and an analyzer must be able to
+  // see that instead of inheriting a tidy-looking lie.
+  const armBefore = { tc: observed.tc, rag: observed.rag };
+  const ledgerEntry = appendLedger(claudeDir, { ts: now.toISOString(), event: 'set', tc, rag, note });
+
+  if (mutations.length === 0) {
+    // Nothing to undo, so no state file: `restore` must be able to say "nothing
+    // was changed" instead of pretending to have work to do.
+    return { arm, armBefore, ledgerEntry, changes: [], statePath: null, alreadySet: false, warnings };
+  }
+
+  const state = { version: STATE_VERSION, startedAt: now.toISOString(), cwd, claudeDir, arm, armBefore, note, entries: [] };
+  writeJson(statePath, state);
+
+  const changes = [];
+  for (const [i, mutation] of mutations.entries()) {
+    const before = fingerprint(mutation.path);
+    const backup = before === null ? null : join(backupDir, `${String(i + 1).padStart(2, '0')}-${basename(mutation.path)}`);
+    if (backup) {
+      mkdirSync(backupDir, { recursive: true });
+      cpSync(mutation.path, backup, { recursive: true });
+    }
+    // Recorded BEFORE the mutation runs. If apply() throws — no write
+    // permission, a locked file — the entry is already on disk with its backup,
+    // so restore can still undo it. `pending` marks the one window in which the
+    // path's content is not yet known.
+    const entry = { label: mutation.label, path: mutation.path, backup, before, after: null, pending: true };
+    state.entries.push(entry);
+    writeJson(statePath, state);
+
+    mutation.apply();
+
+    entry.after = fingerprint(mutation.path);
+    entry.pending = false;
+    writeJson(statePath, state);
+    changes.push(mutation.label);
+  }
+
+  return { arm, armBefore, ledgerEntry, changes, statePath, alreadySet: false, warnings };
+}
+
+/** The last ledger entry if it leaves an arm IN FORCE, else null. */
+function openLedgerArm(claudeDir) {
+  const ledger = readLedger(claudeDir);
+  const last = ledger[ledger.length - 1];
+  return last && last.event !== 'restore' ? last : null;
+}
+
+/**
+ * Put back exactly what `set` moved — or refuse.
+ *
+ * Verification runs over EVERY entry before a single byte is written, and any
+ * mismatch aborts the whole restore. Partial restores are worse than none: they
+ * leave a config no state file describes.
+ *
+ * `pending` entries (see experimentSet) are exempt from the comparison. Their
+ * content is genuinely unknown — the mutation may have half-landed — and the
+ * window they cover is the inside of one process, not a working session, so
+ * there is no user edit to protect there.
+ *
+ * It is also how a measurement window ENDS, parked files or not — see the
+ * no-state branch below.
+ *
+ * @returns {{restored: object[], armBefore, ledgerEntry, statePath, parked: boolean}}
+ *   `parked: false` when there was nothing to put back and this only closed the
+ *   ledger window.
+ * @throws {ExperimentError} when no arm is open at all, or when a touched path
+ *   changed after `set` — the refusal is the feature.
+ */
+export function experimentRestore({ claudeDir, note = '', now = new Date() }) {
+  const { statePath, backupDir } = experimentPaths(claudeDir);
+  const state = readState(claudeDir);
+  if (!state) {
+    // Nothing was parked — but an arm can still be OPEN in the ledger, and that
+    // is the normal end of an `on` run: the switch only ever turns things off,
+    // so `set --tc on --rag on` writes a ledger entry and touches no file.
+    //
+    // Refusing here left that window open forever. TASK-088 leans on `restore`
+    // to close it ("no arm is in force from here on"), so without this every
+    // later prompt on an exp/ branch — a follow-up in the same worktree a week
+    // after the run — kept resolving to `branch+ledger`, the one state the
+    // procedure calls fit for analysis, and joined the sample in silence. The
+    // off arm was protected by its state file, so the contamination was
+    // ONE-SIDED: flagged on one arm, invisible on the other. An asymmetric leak
+    // between the two things being compared is worse than the leak.
+    const open = openLedgerArm(claudeDir);
+    if (open) {
+      // tc/rag mirror the `set` this closes, because nothing was changed:
+      // the config after is the config before. (`ledgerArmAt` reads no arm off a
+      // `restore` entry at all — the fields are here for a human reading the
+      // file, and the shape has to stay `{ts, tc, rag, note}`.)
+      const ledgerEntry = appendLedger(claudeDir, {
+        ts: now.toISOString(),
+        event: 'restore',
+        tc: open.tc,
+        rag: open.rag,
+        note: note || 'measurement window closed; nothing had been parked',
+      });
+      return { restored: [], armBefore: { tc: open.tc, rag: open.rag }, ledgerEntry, statePath, parked: false };
+    }
+    throw new ExperimentError(
+      `no experiment state at ${statePath} and no open arm in the ledger — nothing was restored`,
+      'a `restore` closes what a `tune-context experiment set` opened; there is no such entry to close',
+    );
+  }
+
+  // Content matching `before` is NOT drift: that path is already back where it
+  // started. Two ways to get there, and both must stay restorable — a restore
+  // that died partway through (cpSync hit a permission wall on entry 4 of 7) and
+  // is being retried, and a user who put one file back by hand. Comparing only
+  // against `after` made the first case permanently unrestorable: every retry
+  // would refuse over the entries the previous attempt had already fixed.
+  const drifted = state.entries
+    .filter((e) => !e.pending)
+    .map((e) => ({ entry: e, current: fingerprint(e.path) }))
+    .filter(({ entry, current }) => current !== entry.after && current !== entry.before);
+
+  if (drifted.length) {
+    const lines = drifted.flatMap(({ entry, current }) => {
+      const what = current === null ? 'deleted since `set`' : entry.after === null ? 're-created since `set`' : 'edited since `set`';
+      return [
+        `  ${entry.path} — ${what}`,
+        ...describeDifference(entry.path, entry.backup).map((line) => `      ${line}`),
+        `      saved copy: ${entry.backup ?? '(none — the file did not exist before the experiment)'}`,
+      ];
+    });
+    throw new ExperimentError(
+      `refusing to restore: ${drifted.length} path(s) changed after \`set\`\n${lines.join('\n')}`,
+      'Each difference is measured against the pre-experiment copy — the bytes restore would write — so part of it is the arm\'s own ' +
+        'change, not yours. Restoring would erase the rest without a trace: merge what you want to keep out of the saved copies by hand, ' +
+        `then delete ${statePath} to end the experiment — or re-run \`tune-context init\` to regenerate the managed parts.`,
+    );
+  }
+
+  const restored = [];
+  const failures = [];
+  for (const entry of state.entries) {
+    rmSync(entry.path, { recursive: true, force: true });
+    if (entry.backup) cpSync(entry.backup, entry.path, { recursive: true });
+    const now_ = fingerprint(entry.path);
+    if (now_ !== entry.before) failures.push(`${entry.path} — restored content does not match what was saved`);
+    restored.push({ path: entry.path, label: entry.label });
+  }
+
+  if (failures.length) {
+    // Backups are deliberately NOT deleted here: they are the only remaining
+    // copy of whatever did not come back.
+    throw new ExperimentError(
+      `restore finished with ${failures.length} mismatch(es):\n${failures.map((f) => `  ${f}`).join('\n')}`,
+      `the backup copies are kept at ${backupDir} — compare by hand before removing ${statePath}`,
+    );
+  }
+
+  const armBefore = state.armBefore;
+  const ledgerEntry = appendLedger(claudeDir, {
+    ts: now.toISOString(),
+    event: 'restore',
+    tc: armBefore.tc,
+    rag: armBefore.rag,
+    note: note || `restored arm tc=${state.arm.tc} rag=${state.arm.rag}`,
+  });
+
+  rmSync(backupDir, { recursive: true, force: true });
+  rmSync(statePath, { force: true });
+
+  return { restored, armBefore, ledgerEntry, statePath, parked: true };
+}