@bglocation/tune-context 2.3.1 → 2.4.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "tune-context",
       "source": "./",
       "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-      "version": "2.3.1",
+      "version": "2.4.0",
       "author": {
         "name": "Szymon Walczak",
         "url": "https://bglocation.dev"

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "tune-context",
   "displayName": "tune-context",
   "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,83 @@ All notable changes to `@bglocation/tune-context` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.0] — 2026-07-31
+
+### Added
+
+- **`tune-context experiment` — the second arm** (TASK-087, EPIC-009). Measuring
+  one arm is not measuring: until now there was no way to run the same work
+  *without* the doctrine and without RAG, so every figure the reports produced
+  was absolute and had nothing to be compared against. `experiment set --tc off
+  --rag off` switches off hook registrations, the managed `CLAUDE.md` block, the
+  doctrine skills and the agents (the full arm, PO decision) plus the project
+  `.mcp.json`; `restore` puts every byte back. Each `set` appends to an
+  append-only ledger (`<config dir>/tune-context/experiment.jsonl`) — the source
+  of truth an analyzer uses to assign a session to an arm.
+- **`restore` refuses rather than clobbers.** Every touched path is fingerprinted
+  and copied aside *before* it is modified — so a `set` interrupted halfway is
+  still reversible — and `restore` compares each path against what `set` left
+  there. A file edited during the arm (a permission added to `settings.json`,
+  text written below the `CLAUDE.md` marker — the TASK-082 scenario) aborts the
+  whole restore and reports **what** diverged, not just which file: the first
+  differing line with a preview of both sides for a text file, per-file counts
+  and names for a directory, plus the path to the saved copy. Refusal is the
+  correct outcome here, not a failure.
+- **`verify` understands the off arm.** With an arm set it reports "off" instead
+  of a broken install — and stays RED when the arm did *not* fully land, e.g. a
+  leftover hook registration still firing. Reporting a correctly disabled
+  doctrine as breakage would be the EPIC-006 false-red regression pointing the
+  other way. `init` now refuses to run while an arm is set: it would re-install
+  what the arm parked and leave `restore` with fingerprints it never wrote.
+
+- **Rows say which arm they belong to** (TASK-088, EPIC-009). `prompt-metrics`
+  rows from a branch shaped `exp/<task>/<arm>` now carry `exp_task`, `exp_arm`,
+  `exp_arm_source`, `exp_ledger_arm` and `pass_order`. The branch says which arm
+  was *intended*, the ledger which was *set* — and when they disagree the tool
+  does **not** pick a winner: the arm is left unresolved with the reason on the
+  row (`conflict:ledger`, `conflict:no-ledger-entry`, `conflict:branch-changed`),
+  because silently assigning a run to an arm is exactly the false saving the
+  paired measurement exists to prevent. The branch parser is strict for the same
+  reason: `exp/task-089/off-by-one` and `feat/exp/task-089/on` resolve to nothing
+  rather than to the nearest matching arm.
+- **`pass_order` on the row.** The second implementation of the same task is
+  cheaper for a reason that has nothing to do with the arm — the solution is
+  already known — and that effect runs in the same direction as the one being
+  measured. Recorded per (task, arm) from the start time, it is what lets the
+  order effect be subtracted from the arm effect instead of being counted as one.
+
+- **`restore` ends a measurement run even when it moved nothing.** The switch
+  only ever turns things *off*, so the `on` arm parks no files — and `restore`
+  used to refuse there, ledger entry included. That left the `on` arm's window
+  open forever: a follow-up a week later, in the same worktree on the same
+  `exp/` branch, still resolved to `branch+ledger` and joined the sample, while
+  the identical work after an `off` arm was flagged and excluded. A leak on one
+  side only is worse than a leak on both, because the two sides are what the
+  epic compares. Now `restore` closes the ledger window whether or not it had
+  bytes to put back, and refuses only when there is no open arm to close.
+
+### Fixed
+
+- **A cost that is not a number is no longer counted as a cost.** `NaN` is
+  neither `null` nor `undefined`, so a row carrying one passed every "is there a
+  price here?" check, entered the priced count, and turned the whole run's total
+  into `$NaN` — every other row's money gone while the counter still claimed to
+  have priced them. The published amount is now refused unless it is finite, and
+  the roll-up checks each class, not only the total. The way in is closed too:
+  the price, tier and geo tables are looked up by *own* key, so a `service_tier`
+  spelled `constructor` reads as unknown instead of handing back a function from
+  `Object.prototype`.
+
+### Notes
+
+- `rag off` covers the **project** `.mcp.json` only. `~/.claude.json` is rewritten
+  by Claude Code while it runs, so the switch never touches the user scope —
+  `experiment status` says this explicitly instead of implying RAG is globally
+  off.
+- The arm belongs to the **session**: `settings.json` and MCP servers load at
+  startup, so a `set` applies from the next Claude Code start. Both `set` and
+  `status` say so; nothing here restarts anything for you.
+
 ## [2.3.1] — 2026-07-28
 
 ### Fixed
@@ -464,6 +541,7 @@ action needed on upgrade.
   (`explore-cheap`, `reviewer`), the PreCompact / SessionStart / PostToolUse hook
   suite, and the adoption report (`eval/adoption-report.mjs`).
 
+[2.4.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.4.0
 [2.3.1]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.1
 [2.3.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.0
 [2.2.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.2.0

package/README.md

@@ -17,7 +17,7 @@ tune-context/
 ├── agents/            # explore-cheap, reviewer (model right-sizing)
 ├── hooks/             # PreCompact state-doc, SessionStart re-inject, adoption log, context reminder + hooks.json
 ├── bin/ + cli/        # `tune-context init` — deterministic detect → generate → verify
-├── eval/              # adoption-report.mjs (the rag-usage analog)
+├── eval/              # adoption-report.mjs (the rag-usage analog), prompt-metrics.mjs, pricing.mjs
 └── scripts/           # verify-pack, smoke-init, sync-tune-context (dev/maintenance)
 ```
 
@@ -332,19 +332,124 @@ instead of printing a number the doubling would have faked.
 `~/.claude/tune-context/` (or the `CLAUDE_CONFIG_DIR` override) and records only
 tool names, file paths, and skill/agent names — never full Bash command strings.
 
-**Honest scope:** this is a *behavioral proxy*, not a bill. Token cost lands only
-in OTEL (`CLAUDE_CODE_ENABLE_TELEMETRY=1` → `claude_code.cost.usage`, needs a
-collector), never a hook; and caveman is an output style with no tool call, so it
+**Honest scope:** this is a *behavioral proxy*, not a bill. The hook log carries
+no tokens, so dollars come from `prompt-metrics` below (or from OTEL, which is
+Anthropic's own figure); and caveman is an output style with no tool call, so it
 can't be counted this way. Doctrine applied as *method* — narrow reads,
 contracts-first edits, delegation — is only partly visible too: no `Skill` call,
 but its trace shows up in the report's edit:read ratio, so the verdict never
 reads zero `Skill` calls as "unused."
 
+### Per-prompt metrics from transcripts (`eval/prompt-metrics.mjs`)
+
+The adoption report reads *our* hook log. `prompt-metrics` reads the transcripts
+**Claude Code writes itself** (`<config dir>/projects/<slug>/<session>.jsonl`) and
+emits one JSONL row per prompt — time, tokens split by cache class, model,
+effort, tools, delegations, and cost in dollars (`eval/pricing.mjs`):
+
+```bash
+node eval/prompt-metrics.mjs                              # every transcript
+node eval/prompt-metrics.mjs --transcript <path.jsonl>    # one session
+node eval/prompt-metrics.mjs --dir <dir> > prompts.jsonl  # JSONL on stdout
+```
+
+Rows go to stdout, a run summary to stderr — so a pipe stays clean. Two things
+that source makes possible and a hook cannot: it works for **past** sessions, and
+it works when tune-context is switched **off** (a disabled hook records nothing,
+and that is exactly the arm a comparison needs).
+
+Honest scope, printed on every run:
+
+- **`list_cost_usd` is API list price, not your bill.** A Pro/Max subscription
+  charges a flat fee and consumes plan limits; nothing here is billed per token.
+  The figure answers *"what would this work have cost through the API"* — which
+  is the right yardstick for comparing two arms, and the wrong number to
+  reconcile against a statement. The field is named so the qualifier travels
+  with the data.
+- **Cache-aware, because a naive token sum is off by ~10×.** Cache reads cost
+  0.1× and writes 1.25×/2×; the local run carries 4.18 **billion** cache-read
+  tokens against 521 k plain input ones — 99.9% of the figure is cache and
+  output. The total never appears without its per-class split, and a model the
+  table doesn't know yields `null` plus an `UNPRICED` count, never a zero.
+- **Prices are data, dated, and expire.** `eval/pricing.mjs` holds one table
+  taken from the published pricing page with its retrieval date, storing base
+  input/output only and deriving the three cache columns from the documented
+  1.25×/2×/0.1× multipliers — a test asserts the derivation reproduces every
+  published row. Service tier (batch −50%), fast mode, and `inference_geo`
+  (us +10%) are applied; the claude-sonnet-5 introductory price ends in the
+  table on 2026-08-31. Rows are priced at the **prompt's own timestamp**, so
+  re-running the report later yields the same figure.
+- **Subagent cost is uncaptured, not zero.** Measured over 29 local transcripts:
+  21 `Agent` calls, **zero** sidechain entries — subagent turns never reach the
+  parent transcript. So `agent_spawns` is always counted, and `sidechain_turns`
+  is counted too: if a future Claude Code starts writing them, the number stops
+  being 0 with no code change.
+- **Queue wait is not work.** `queued_s` (submission → first assistant entry) is
+  reported apart from `work_s`, because a prompt sent while the agent is busy
+  waits in a queue and that is the user's time. `max_gap_s` exposes the same
+  thing *inside* a turn — a tool call blocked on a permission prompt lands in
+  `work_s` otherwise.
+- **Model and effort change mid-session** (measured), so both ride on every row,
+  with a per-model token split when a single prompt used more than one.
+- Entries that can't be attributed to a prompt are **counted and reported**,
+  never silently dropped. Same for the two ways the figure can be too low:
+  `usage.iterations` reporting more than the `usage` we price from (3 turns
+  locally), and web searches, which are billed per request ($10/1000) rather
+  than per token and so sit outside the token total. Web *fetch* is free.
+
+### The other arm (`tune-context experiment`)
+
+A cost figure with nothing to compare it against is a number, not a measurement.
+This switch turns the doctrine **off** so the same work can be run twice —
+`tc={on,off}` × `rag={on,off}` — and records which arm was in force when:
+
+```bash
+tune-context experiment status                              # what is set, and what the config actually shows
+tune-context experiment set --tc off --rag off --note "pair 1"
+tune-context experiment restore                             # byte for byte, or a refusal
+```
+
+- **`tc off` is the full arm** (PO decision, EPIC-009): hook registrations in
+  `settings.json`, the managed block in the project `CLAUDE.md`, the doctrine
+  skills, the agents. Four interventions in one variable on purpose — at small
+  *n* the biggest effect is the easiest to detect; splitting them is the *next*
+  experiment.
+- **`rag off` means this project's `.mcp.json`, and nothing else.** The user
+  scope (`~/.claude.json`) is rewritten by Claude Code while it runs, so the
+  switch never touches it — `status` says so out loud instead of letting you
+  assume RAG is off globally. Check `claude mcp list` before a measured run.
+- **Reversibility comes before the change.** Every touched path is fingerprinted
+  and copied aside *before* it is modified, so a `set` that dies halfway is still
+  undoable. `restore` compares each path against what `set` left there and
+  **refuses** if anything changed in between, naming the file *and the
+  difference* (first differing line for a text file, changed/added/removed files
+  for a directory, and where the saved copy is) — the working session between the
+  two commands is exactly when you might add a permission or write below the
+  `CLAUDE.md` marker, and silently erasing that is worse than refusing.
+- **The ledger is the source of truth**
+  (`<config dir>/tune-context/experiment.jsonl`, append-only). An analyzer
+  assigns a session to an arm by timestamp; detecting the arm from a transcript
+  is a cross-check, never the verdict. Every `set` appends — including one that
+  changes nothing, because a run whose ledger is silent at its start cannot be
+  assigned to an arm at all.
+- **The arm belongs to the session.** `settings.json` and MCP servers are read at
+  startup, so it applies from the next Claude Code start; flipping it mid-session
+  produces a mixed session, which the analysis throws away.
+- `tune-context verify` reads the arm and reports **"off"** rather than a broken
+  install — and stays RED if the arm did not fully land. `init` refuses to run
+  while an arm is set: it would re-install what the arm parked and leave
+  `restore` with nothing it recognises.
+
+The measurement protocol that uses this — paired runs on `exp/<task>/<arm>`
+branches, frozen prompt script, verdict gates — is
+[COST_EVALUATION_PROCEDURE.md](COST_EVALUATION_PROCEDURE.md).
+
 ### Getting real cost (OTEL) — outside tune-context
 
 tune-context does not set this up for you (deliberate — see TASK-062: it needs
-infra this tool stays zero-infra without). If you want actual dollars instead of
-the behavioral proxy above:
+infra this tool stays zero-infra without). `prompt-metrics` above computes cost
+from a public price list, which is an *independent* calculation, not Anthropic's
+invoice — OTEL is the way to check it against the real one:
 
 ```bash
 export CLAUDE_CODE_ENABLE_TELEMETRY=1     # off by default

package/bin/tune-context.mjs

@@ -30,6 +30,15 @@ import {
   mergePermissions,
 } from '../cli/generate.mjs';
 import { staleDoctrineEntries, verify } from '../cli/verify.mjs';
+import {
+  ExperimentError,
+  experimentPaths,
+  experimentRestore,
+  experimentSet,
+  observeArm,
+  readLedger,
+  readState,
+} from '../cli/experiment.mjs';
 
 const HOOK_EVENTS = [
   { event: 'PreCompact', scriptName: 'pre-compact-snapshot.mjs' },
@@ -58,6 +67,9 @@ function usage() {
 Usage:
   tune-context init [--cwd <dir>] [--force-claude-md]
   tune-context verify [--cwd <dir>]
+  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 --help
   tune-context --version
 
@@ -66,12 +78,76 @@ Usage:
                       match this package. Run it after upgrading: an upgrade
                       does not refresh copies an earlier init made.
 
+  experiment          A/B switch for measuring the doctrine against its own
+                      absence (EPIC-009). \`set\` disables what the arm asks for
+                      and records how to put it back; \`restore\` puts it back
+                      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.
+
   --force-claude-md   Regenerate a project CLAUDE.md whose hand-written content
                       still sits inside the managed block. Discards that content.
                       Without it, such a file is left untouched.
 `;
 }
 
+// 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']);
+
+/**
+ * @returns {string|{error: string}} the value after `name`, or undefined if the
+ *   flag is absent. Undefined (last arg) and another flag both count as "no
+ *   value given" — resolve(undefined) used to throw a raw ERR_INVALID_ARG_TYPE
+ *   with a Node stacktrace instead of a usage message.
+ */
+function flagValue(args, name) {
+  const idx = args.indexOf(name);
+  if (idx === -1) return undefined;
+  const value = args[idx + 1];
+  if (value === undefined || value.startsWith('-')) return { error: `Missing value for ${name}` };
+  return value;
+}
+
+function positionals(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (VALUE_FLAGS.has(args[i])) {
+      i += 1;
+      continue;
+    }
+    if (!args[i].startsWith('-')) out.push(args[i]);
+  }
+  return out;
+}
+
+const EXPERIMENT_SUBCOMMANDS = ['status', 'set', 'restore'];
+
+/**
+ * `experiment` argument shape. `set` demands BOTH --tc and --rag: an arm stated
+ * by halves is an arm nobody can reproduce from the ledger, and inferring the
+ * unstated half from the current config would write a value nobody chose.
+ */
+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 !== 'set') return { mode: 'experiment', sub, cwd };
+
+  const values = {};
+  for (const flag of ['--tc', '--rag', '--note']) {
+    const value = flagValue(rest, flag);
+    if (value?.error) return { mode: 'error', message: value.error };
+    values[flag] = value;
+  }
+  for (const flag of ['--tc', '--rag']) {
+    if (values[flag] === undefined) return { mode: 'error', message: `experiment set requires ${flag} <on|off>` };
+    if (values[flag] !== 'on' && values[flag] !== 'off') return { mode: 'error', message: `${flag} must be on or off, got: ${values[flag]}` };
+  }
+  return { mode: 'experiment', sub, cwd, tc: values['--tc'], rag: values['--rag'], note: values['--note'] ?? '' };
+}
+
 // 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
@@ -86,32 +162,48 @@ export function parseArgs(argv) {
   // `verify` joins `init` as an accepted command (TASK-081). It writes nothing,
   // which is the point: init syncs before it verifies, so init can never
   // observe the drift an upgrade leaves behind — only a check that runs on its
-  // own can. The TASK-078 rule still holds: an unknown command fails loudly.
-  if (command !== 'init' && command !== 'verify') {
+  // own can. `experiment` joins them as the A/B switch (TASK-087). The TASK-078
+  // rule still holds: an unknown command fails loudly.
+  const commands = ['init', 'verify', 'experiment'];
+  if (!commands.includes(command)) {
     return {
       mode: 'error',
-      message: command === undefined ? 'Missing command: init or verify' : `Unknown command: ${command}`,
+      message: command === undefined ? `Missing command: ${commands.join(', ')}` : `Unknown command: ${command}`,
     };
   }
+
+  const cwdValue = flagValue(rest, '--cwd');
+  if (cwdValue?.error) return { mode: 'error', message: cwdValue.error };
+  const cwd = cwdValue === undefined ? process.cwd() : resolve(cwdValue);
+
+  if (command === 'experiment') return parseExperiment(rest, cwd);
   // Opt-in only, and never inferred: this is the one flag that can destroy
   // content the tool otherwise refuses to touch (TASK-082).
-  const forceClaudeMd = rest.includes('--force-claude-md');
-  const cwdFlagIdx = rest.indexOf('--cwd');
-  if (cwdFlagIdx === -1) return { mode: command, cwd: process.cwd(), forceClaudeMd };
-  const value = rest[cwdFlagIdx + 1];
-  // Undefined (last arg) or another flag (e.g. `--cwd --foo`) both mean "no
-  // value was actually given" — resolve(undefined) used to throw a raw
-  // ERR_INVALID_ARG_TYPE with a Node stacktrace instead of a usage message.
-  if (value === undefined || value.startsWith('-')) {
-    return { mode: 'error', message: 'Missing value for --cwd' };
-  }
-  return { mode: command, cwd: resolve(value), forceClaudeMd };
+  return { mode: command, cwd, forceClaudeMd: rest.includes('--force-claude-md') };
 }
 
 function runInit(cwd, { forceClaudeMd = false } = {}) {
   const templatesDir = join(pkgRoot, 'skills', 'tune-context', 'templates');
   const { claudeDir } = claudeDirs();
 
+  // An experiment arm is the one state in which init must NOT run. It would
+  // re-install everything the arm parked — turning the config back on while the
+  // ledger still says off (a mislabelled measurement), and putting content back
+  // where `restore` then finds a fingerprint it did not write, so the only way
+  // out would be refusal. Blocking here keeps both the arm and the undo intact.
+  const state = readState(claudeDir);
+  if (state) {
+    process.stderr.write(`tune-context init refused — experiment arm tc=${state.arm.tc} rag=${state.arm.rag} has been set (since ${state.startedAt}).
+
+  init would re-install what the arm parked, and \`experiment restore\` would then
+  refuse, because the files no longer match what it saved.
+
+  Run \`tune-context experiment restore\` first, then init.
+`);
+    process.exitCode = 1;
+    return;
+  }
+
   const stack = detectStack(cwd);
   const existing = detectExistingConfig(cwd);
 
@@ -226,6 +318,11 @@ function runVerify(cwd) {
   const detection = { stack: detectStack(cwd), mcpServers: detectMcpServers(cwd) };
   const permissionsAllow = buildPermissionsAllow(detection);
 
+  // The arm comes from the ledger state, never from guessing at the config:
+  // "the doctrine is missing" and "the doctrine was switched off on purpose"
+  // look identical on disk, and only one of them is a broken install.
+  const arm = readState(claudeDir)?.arm ?? null;
+
   const result = verify({
     claudeDir,
     userSettingsPath: existing.userSettingsJson,
@@ -233,9 +330,14 @@ function runVerify(cwd) {
     expectedHookCommands: HOOK_EVENTS,
     expectedPermissions: permissionsAllow,
     pkgRoot,
+    arm,
   });
 
   console.log(`tune-context verify — ${cwd}\n`);
+  if (arm) {
+    console.log(`Experiment arm: tc=${arm.tc} rag=${arm.rag} — the checks below are read against that arm, not against a full install.
+  This is the pre-run check from COST_EVALUATION_PROCEDURE §4: it must say the arm you meant to set, BEFORE the first prompt.\n`);
+  }
   console.log(`Verify: ${result.ok ? 'OK' : 'FAILED'}`);
   for (const check of result.checks) {
     const mark = check.unknown ? '?' : check.ok ? '✓' : '✗';
@@ -245,7 +347,129 @@ function runVerify(cwd) {
   // never ran init, this prints a screen of ✗ and, without the line below,
   // nothing that says the whole list is one command away from green.
   if (!result.ok) {
-    console.log('\nNext: `tune-context init` writes what is missing and refreshes what drifted. It never edits content outside the managed block.');
+    console.log(
+      arm
+        ? '\nNext: `tune-context experiment restore` — while an arm is set, init is refused, and a red check here means the arm did not fully land.'
+        : '\nNext: `tune-context init` writes what is missing and refreshes what drifted. It never edits content outside the managed block.',
+    );
+    process.exitCode = 1;
+  }
+}
+
+// Said the same way everywhere: an arm is a property of the SESSION, not of the
+// prompt. settings.json and MCP servers are read when Claude Code starts, so a
+// switch flipped mid-session produces a mixed session — the one sample class
+// EPIC-009 throws away rather than assigns.
+const RESTART_NOTE = `The arm applies from the NEXT Claude Code start. settings.json and MCP servers are read at
+  startup, so a session already running is unaffected — close it before the measured run.`;
+
+const MCP_SCOPE_NOTE = `MCP scope: only this project's .mcp.json is switched. The USER scope (~/.claude.json) is
+  rewritten by Claude Code while it runs, so this switch never touches it — a user-scope
+  semantic-search server stays available in a \`rag off\` arm. Check with \`claude mcp list\`
+  before the run, or the arm is mislabelled.`;
+
+function armLine(observed) {
+  return `tc=${observed.tc} rag=${observed.rag}`;
+}
+
+function runExperimentStatus(cwd) {
+  const { claudeDir } = claudeDirs();
+  const { statePath, ledgerPath } = experimentPaths(claudeDir);
+  const state = readState(claudeDir);
+  const ledger = readLedger(claudeDir);
+  const observed = observeArm({ claudeDir, cwd, pkgRoot });
+
+  console.log(`tune-context experiment status — ${cwd}\n`);
+
+  const last = ledger[ledger.length - 1];
+  console.log('Ledger (source of truth for assigning a session to an arm):');
+  console.log(`  ${ledgerPath}`);
+  if (!last) {
+    console.log('  no entries yet — no run has been labelled through this switch');
+  } else {
+    console.log(`  last: ${last.event ?? 'set'} tc=${last.tc} rag=${last.rag} at ${last.ts}${last.note ? ` — "${last.note}"` : ''} (${ledger.length} entr${ledger.length === 1 ? 'y' : 'ies'})`);
+  }
+
+  console.log('\nActive switch state:');
+  console.log(
+    state
+      ? `  arm tc=${state.arm.tc} rag=${state.arm.rag} set at ${state.startedAt}; ${state.entries.length} path(s) parked, restorable from ${statePath}`
+      : '  none — this switch has nothing parked, so `restore` has nothing to put back',
+  );
+
+  console.log('\nObserved in the config (cross-check, NOT the source of truth):');
+  console.log(`  ${armLine(observed)}`);
+  for (const c of observed.components) {
+    const mark = c.state === 'on' ? '✓' : c.state === 'off' ? '·' : '!';
+    console.log(`    ${mark} ${c.label} — ${c.detail}`);
+  }
+  console.log(
+    `    ${observed.mcp.servers.length ? '✓' : '·'} ${observed.mcp.path} — ${observed.mcp.servers.length ? `${observed.mcp.servers.length} server(s): ${observed.mcp.servers.join(', ')}` : 'absent or empty'}`,
+  );
+
+  // The two must agree before a measured run: the ledger is what the analyzer
+  // reads, the config is what the session actually gets.
+  if (state && (state.arm.tc !== observed.tc || state.arm.rag !== observed.rag)) {
+    console.log(`\n! The set arm (tc=${state.arm.tc} rag=${state.arm.rag}) and the observed config (${armLine(observed)}) DISAGREE.
+  Something changed the config after \`set\` — do not measure in this state; \`restore\` and set again.`);
+  }
+
+  console.log(`\n${MCP_SCOPE_NOTE}`);
+  console.log(`\n${RESTART_NOTE}`);
+}
+
+function runExperimentSet(cwd, { tc, rag, note }) {
+  const { claudeDir } = claudeDirs();
+  const result = experimentSet({ claudeDir, cwd, pkgRoot, tc, rag, note });
+
+  console.log(`tune-context experiment set — tc=${tc} rag=${rag}${note ? ` — "${note}"` : ''}\n`);
+  if (result.alreadySet) {
+    console.log('Config unchanged: this arm was already set. The ledger entry is written anyway — a run whose\n  ledger is silent at its start cannot be assigned to an arm at all.');
+  } else if (result.changes.length === 0) {
+    console.log('Config unchanged: nothing had to be switched off for this arm. Ledger entry written.');
+  } else {
+    console.log(`Switched off (${result.changes.length}):`);
+    for (const change of result.changes) console.log(`  - ${change}`);
+    console.log(`\nUndo: \`tune-context experiment restore\` — byte for byte from ${result.statePath},
+  or a refusal naming the file if one of those paths changed in the meantime.`);
+  }
+
+  for (const warning of result.warnings) console.log(`\n! ${warning}`);
+
+  console.log(`\n${RESTART_NOTE}`);
+  console.log(`\n${MCP_SCOPE_NOTE}`);
+  console.log('\nNext: `tune-context verify` — confirm the arm BEFORE the first prompt, not after the run.');
+  if (result.warnings.length) process.exitCode = 1;
+}
+
+function runExperimentRestore() {
+  const { claudeDir } = claudeDirs();
+  const result = experimentRestore({ claudeDir });
+  console.log('tune-context experiment restore\n');
+  if (result.parked) {
+    console.log(`Restored ${result.restored.length} path(s), verified against the fingerprints taken before the change:`);
+    for (const r of result.restored) console.log(`  - ${r.path}`);
+  } else {
+    // The `on` arm parks nothing, so this is its normal ending — and not an
+    // empty one: the ledger entry is what tells the analyzer the run is over,
+    // instead of letting the last `set` label every later session (TASK-088).
+    console.log('Nothing had been parked — this arm changed no files. The ledger entry below is the point of\n  the command: it closes the measurement window, so work done from now on is not read as part of the run.');
+  }
+  console.log(`\nLedger: arm back to tc=${result.armBefore.tc} rag=${result.armBefore.rag} at ${result.ledgerEntry.ts}.`);
+  console.log(`\n${RESTART_NOTE}`);
+}
+
+function runExperiment(parsed) {
+  try {
+    if (parsed.sub === 'status') runExperimentStatus(parsed.cwd);
+    else if (parsed.sub === 'set') runExperimentSet(parsed.cwd, parsed);
+    else runExperimentRestore();
+  } catch (error) {
+    // Operator-facing conditions (arm already set, nothing to restore, a file
+    // changed under us) are answers, not crashes: message + next step + exit 1,
+    // never a stacktrace. Anything else is a real bug and is rethrown.
+    if (!(error instanceof ExperimentError)) throw error;
+    process.stderr.write(`tune-context experiment ${parsed.sub}: ${error.message}\n${error.hint ? `\n  ${error.hint}\n` : ''}`);
     process.exitCode = 1;
   }
 }
@@ -265,6 +489,8 @@ export function main() {
     process.exitCode = 1;
   } else if (parsed.mode === 'verify') {
     runVerify(parsed.cwd);
+  } else if (parsed.mode === 'experiment') {
+    runExperiment(parsed);
   } else {
     runInit(parsed.cwd, { forceClaudeMd: parsed.forceClaudeMd });
   }