staysfixed 0.12.0 → 0.13.0

package/src/v2/check.js

@@ -51,6 +51,7 @@ import {
 } from './watch/window.js';
 import { onAppStarted, stillOpen } from './adapters/isolate.js';
 
+import { isAnAnswerJourney, journeysFromExports, splitAnswerSheet } from './journeys/from-exports.js';
 import { processAdapter } from './adapters/process.js';
 import { sourceAdapter } from './adapters/source.js';
 import { httpAdapter } from './adapters/http.js';
@@ -582,6 +583,7 @@ async function countTheDoors(verdict, project) {
     const { ledger, toCoverage } = await import('./coverage.js');
     const led = await ledger(project.store, project.product, {
       root: project.root,
+      folders: project.sourceFolders,
       journeys: project.journeys,
       builds: [project.candidate.id],
     });
@@ -1085,28 +1087,34 @@ async function stopWhateverIsStillRunningIn(dir) {
 function noScratchFolder(e) {
   const tmp = os.tmpdir();
   const code = String(/** @type {any} */ (e)?.code ?? '');
+  // The setting is not called the same thing everywhere, and naming the wrong one is advice
+  // that cannot be followed. Windows reads TEMP and TMP; everything else reads TMPDIR. All
+  // three sentences below said "TMPDIR" on every machine, so on Windows the only instruction
+  // a stuck person was given named a setting their operating system does not read. Measured
+  // on a real Windows 11 machine, 2026-08-31.
+  const setting = process.platform === 'win32' ? 'TEMP' : 'TMPDIR';
+  const trailing = process.platform === 'win32' ? /[\\/]$/ : /\/$/;
   // Worth naming only when a setting in this shell is what chose the folder. On a machine
-  // where nothing set it, saying "TMPDIR" sends somebody looking for a setting they have not
+  // where nothing set it, saying the name sends somebody looking for a setting they have not
   // got, and the folder is the operating system's own.
-  const yours = (process.env.TMPDIR ?? '').replace(/\/$/, '') === tmp.replace(/\/$/, '')
-    ? ' That folder is whatever TMPDIR is set to in this shell.'
-    : '';
+  const chosenHere = (process.env[setting] ?? '').replace(trailing, '') === tmp.replace(trailing, '');
+  const yours = chosenHere ? ` That folder is whatever ${setting} is set to in this shell.` : '';
   /** @type {{why: string, hint: string}} */
   const said =
     code === 'ENOENT'
       ? {
         why: `There is no folder at ${tmp}, so there was nowhere to put it.`,
-        hint: `Make that folder, or point TMPDIR at one that exists — or unset TMPDIR to fall back to this machine's own — and run the check again.${yours}`,
+        hint: `Make that folder, or point ${setting} at one that exists — or unset ${setting} to fall back to this machine's own — and run the check again.${yours}`,
       }
       : code === 'EACCES' || code === 'EPERM'
         ? {
           why: `${tmp} is there, but this user is not allowed to write in it.`,
-          hint: `Give yourself write access to that folder, or point TMPDIR at one you can write to, and run the check again.${yours}`,
+          hint: `Give yourself write access to that folder, or point ${setting} at one you can write to, and run the check again.${yours}`,
         }
         : code === 'EROFS'
           ? {
             why: `${tmp} is on a disk that is mounted read-only, so nothing can be written there at all.`,
-            hint: `Point TMPDIR at a folder on a disk that takes writes and run the check again.${yours}`,
+            hint: `Point ${setting} at a folder on a disk that takes writes and run the check again.${yours}`,
           }
           : code === 'ENOSPC'
             ? {
@@ -1214,7 +1222,7 @@ function blocked(options, e, storeTrouble) {
  * for itself.
  *
  * @param {CheckOptions & {finding?: string, revert?: string[]}} options
- * @returns {Promise<{gone: boolean, detail?: string, verdict?: string, escalates?: boolean}>}
+ * @returns {Promise<{gone: boolean, detail?: string, verdict?: string, escalates?: boolean, reran?: number, checked?: number}>}
  */
 export async function prove(options = {}) {
   const root = projectRootFor(options);
@@ -1225,6 +1233,12 @@ export async function prove(options = {}) {
   if (!finding) {
     return {
       gone: false,
+      // Said out loud rather than left absent. An absent verdict resolves to "could not test"
+      // at the surface, deliberately, but a reader of this function should not have to know
+      // that to see which of the three answers this is.
+      verdict: 'could not test',
+      reran: 0,
+      checked: 0,
       detail: `The last check has no finding called "${options.finding ?? ''}". Run a check first, then prove one of the ids it gives you.`,
     };
   }
@@ -1240,6 +1254,27 @@ export async function prove(options = {}) {
       ? { ...changed, hunks: changed.hunks.filter((h) => wanted.some((w) => h.file === w || h.file.startsWith(`${w}/`))) }
       : changed;
 
+    // A file named for reverting that is not among the changes is NOT "nothing has changed".
+    // With an empty narrowing, proveCause said "Nothing has changed between the build you were
+    // happy with and this one" — about a working tree with two edited files in it — which
+    // sends somebody to debug their tree instead of the filename they just typed. Measured
+    // 2026-08-31.
+    if (wanted.length > 0 && narrowed.hunks.length === 0 && changed.hunks.length > 0) {
+      const names = [...new Set(changed.hunks.map((h) => h.file))];
+      return {
+        gone: false,
+        verdict: /** @type {const} */ ('could not test'),
+        escalates: false,
+        reran: 0,
+        checked: 0,
+        detail:
+          `Nothing was re-run: ${wanted.join(', ')} ${wanted.length === 1 ? 'is' : 'are'} not among the files that changed `
+          + `between the build you were happy with and this one, so there was no change in ${wanted.length === 1 ? 'it' : 'them'} `
+          + `to undo. What did change: ${names.slice(0, 10).join(', ')}${names.length > 10 ? `, and ${names.length - 10} more` : ''}. `
+          + 'Name one of those and the claim can actually be tested.',
+      };
+    }
+
     const proof = await proveCause(finding, {
       cwd: project.root,
       walk: project.walk,
@@ -1253,7 +1288,13 @@ export async function prove(options = {}) {
       gone: proof.verdict === 'caused by that change',
       verdict: proof.verdict,
       escalates: proof.escalates,
-      detail: proof.why ? `${proof.what} ${proof.why}` : proof.what,
+      // How much was really walked again, carried through rather than left in a number the
+      // reader never sees. A reply that took a second must never read like one that took ten
+      // minutes, and the only way to tell them apart is to say so.
+      reran: proof.reran,
+      checked: proof.checked,
+      // `proof.what` already ends with the reason. Gluing `why` on printed it twice.
+      detail: proof.what,
     };
   } finally {
     await project.close();
@@ -1588,6 +1629,9 @@ async function waitForItsWindow(pid, stopped) {
  * @property {import('./types.js').Store} store
  * @property {BuildFingerprint} candidate
  * @property {string} [against]   The reference build's own id, once a name has been resolved.
+ * @property {string[]} [sourceFolders]  The folders this run reads code from, straight from
+ *                                       the settings it was given, so nothing downstream has
+ *                                       to find them a second time and find different ones.
  * @property {number} keepBuilds  How many builds of this product other than the reference keep
  *   their full record. Everything older is thinned out at the end of a run.
  * @property {string} [referenceSha]  The commit the build you were happy with is at. It is
@@ -1800,6 +1844,112 @@ export function suiteBudgetFrom(config) {
   return Number.isFinite(asked) && asked >= 0 ? Math.floor(asked) : null;
 }
 
+/**
+ * How long the harvest gets when NOBODY asked for it.
+ *
+ * A quarter of what somebody who typed `--journeys suite` gets, and that gap is the whole
+ * design. Measured on this machine on 2026-08-31: twelve near-empty test files harvested in
+ * 3.1 seconds. Twenty seconds therefore covers a small suite outright and takes a useful bite
+ * out of a large one, and every file it does not reach is named in the coverage list with the
+ * command that would reach it. The alternative — deciding from a file count whether to run at
+ * all — guesses at how slow somebody's tests are and is wrong in both directions.
+ */
+const AUTO_HARVEST_BUDGET_MS = 20_000;
+
+/**
+ * How many harvested test files an unasked-for run will then WALK.
+ *
+ * The harvest budget bounds the harvest and not what comes after it: each harvested journey
+ * is walked twice on the new build and again on the old one. Measured on this machine on
+ * 2026-08-31, twelve harvested journeys took a check from 1.4 seconds to 8.2. Twelve is
+ * therefore the cap, and the files past it are named rather than dropped in silence.
+ */
+const AUTO_HARVEST_JOURNEY_CAP = 12;
+
+/**
+ * How long ONE test file gets on an unasked-for run, harvesting and walking alike.
+ *
+ * The budget above is checked before a file STARTS, never in the middle of one, so without
+ * this a single slow test file could walk straight through a twenty-second budget and spend
+ * the runner's default two minutes doing it — turning a bounded default into an unbounded
+ * one on exactly the projects where that hurts most. Thirty seconds is generous for one file
+ * of a suite somebody runs on every change, and a file that needs longer is named as a hole
+ * with the reason, which is the honest outcome rather than a silent wait.
+ */
+const AUTO_FILE_TIMEOUT_MS = 30_000;
+
+/**
+ * Should this run harvest the project's own tests without being asked?
+ *
+ * The question is only ever "can this be done at all", never "is this project's suite worth
+ * it" — a suite that is too slow is handled by the budget and the cap above, not by refusing
+ * to look. Everything here is cheap: package.json is read, a few filenames are tested for
+ * existence, and nothing is run.
+ *
+ * IT CAN BE SWITCHED OFF, in two ways, because a default that cannot be turned off is a
+ * default somebody works around by uninstalling. `--journeys code` says "read the source and
+ * nothing else" for one run; `suite: { auto: false }` in the settings says it for good. Both
+ * are reported as a hole in that run's coverage, so switching it off never quietly turns into
+ * believing a check that no longer looks.
+ *
+ * @param {string} root
+ * @param {Record<string, any>} config
+ * @returns {Promise<{run: boolean, gap?: CoverageGap}>}
+ */
+async function suiteWorthRunningByDefault(root, config) {
+  if (config?.suite?.auto === false) {
+    return {
+      run: false,
+      gap: {
+        what: "This project's own tests were not run, because the settings switch that off.",
+        why: 'suite: { auto: false } in your settings file. Nothing your tests can see is being compared on this run, which on a library is most of what there is to see.',
+        unlockedBy: 'Remove that line, or run `staysfixed check --journeys suite` once to see what it would find.',
+      },
+    };
+  }
+  try {
+    const { detectRunner } = await import('./journeys/from-suite.js');
+    const found = await detectRunner(root);
+    if (found.runner === 'none') {
+      // Said out loud, on every run, rather than passed over as "there was nothing to do".
+      // A project with no tests is not a project where the tests are fine — it is a project
+      // where a whole channel is empty, and on a library that channel is most of what there
+      // is to look at. The reader is told which it is.
+      return {
+        run: false,
+        gap: {
+          what: "None of this project's own tests were run, because there are none this tool can find.",
+          why: `${found.why} A test suite is the only source that walks this product with the arguments somebody actually thought about, so without one the check compares what it can read and call for itself, and no more.`,
+          unlockedBy: "Point the project at vitest or Node's own test runner and every test file becomes a journey, run twice on each build and compared.",
+        },
+      };
+    }
+    const blocking = (found.missing ?? []).filter((m) => m.blocking);
+    if (blocking.length > 0) {
+      return {
+        run: false,
+        gap: {
+          what: "This project has a test suite and none of it was run, so nothing here says anything about what those tests cover.",
+          why: `${blocking.map((m) => m.what).join(', ')} ${blocking.length === 1 ? 'is' : 'are'} missing, and the harvest cannot run one test file at a time without ${blocking.length === 1 ? 'it' : 'them'}.`,
+          unlockedBy: blocking.map((m) => m.howToGet).join(' '),
+        },
+      };
+    }
+    return { run: true };
+  } catch (e) {
+    // Being unable to work out whether a suite exists is a hole like any other. It must never
+    // read as "this project has no tests", which is the same silence wearing a different hat.
+    return {
+      run: false,
+      gap: {
+        what: "Nothing could work out whether this project has a test suite, so none of it was run.",
+        why: messageOf(e),
+        unlockedBy: 'Run `staysfixed check --journeys suite` to see what it says, or `staysfixed doctor` for what this folder is missing.',
+      },
+    };
+  }
+}
+
 /**
  * Thin out the record of builds nobody is going to ask about again.
  *
@@ -2139,6 +2289,12 @@ async function openProject(options) {
     store,
     candidate,
     keepBuilds: keepBuildsFrom(config),
+    // The folders THIS run is reading, carried so the coverage ledger counts the doors of the
+    // same product the run walked. The ledger can find the settings itself, and does — but it
+    // finds them by looking beside the project, and a run started with `--config elsewhere`
+    // is reading a different file. Two answers to "what is in this project" is how the
+    // ledger came to measure "78 of 78 doors" from 8 of 20 files. Measured 2026-08-31.
+    sourceFolders: Array.isArray(config.source?.folders) ? config.source.folders : undefined,
     referenceSha,
     against: reference ? reference.id : options.against,
     journeys,
@@ -2340,6 +2496,14 @@ async function walkOne(req, where) {
         ctx,
       );
       observations = await adapter.run(req.journey, prepared, ctx);
+      // An answer sheet arrives as one wall of text at one address, because that is what the
+      // process adapter does with anything a command prints. Left that way, a library whose
+      // every return value changed produced ONE finding, worded as a window onto the middle of
+      // a string: "…eserved(\"admin\") -> false…" where it read "…eserved(\"admin\") -> true…".
+      // True, and useless to the person who has to decide whether to ship. Taken apart, every
+      // call gets the exported name's own address and the finding names the function, the
+      // input and both answers. Measured 2026-08-31 — see `splitAnswerSheet`.
+      if (isAnAnswerJourney(req.journey)) observations = splitAnswerSheet(observations, req.journey);
     } catch (e) {
       // A journey that fell over is a hole in the coverage, never a silent pass and never
       // the end of the run — the other journeys' work is worth keeping.
@@ -2540,29 +2704,64 @@ async function gatherJourneys({ root, config, options }) {
 
   if (named) journeys.push(...(await readJourneyFile(path.resolve(root, named))));
 
-  // The project's own test suite, when somebody asked for it in those words and never
-  // otherwise. This RUNS their tests — twice each, inside the same scratch clone everything
-  // else uses, under a time budget — and that is a cost nobody gets charged by accident, so
-  // it is off unless `--journeys suite` says so.
+  // ---- The project's own test suite.
+  //
+  // WHY THIS USED TO BE OFF BY DEFAULT, and the reasoning was right as far as it went: this
+  // RUNS somebody else's tests — every file twice to harvest, and then every harvested
+  // journey twice more on each build — and charging a stranger for that on a command they
+  // ran to get a fast answer is how a tool gets uninstalled. So it waited for
+  // `--journeys suite`.
+  //
+  // WHY IT IS NOW ON BY DEFAULT ANYWAY. The cost was measured against the wrong thing. It was
+  // weighed against a slower check; it should have been weighed against a WRONG one. Measured
+  // 2026-08-31 on a four-line library: two exported functions were rewritten so that every
+  // web address the product produces came out different, and the default check answered
+  // "Nothing that worked has changed" and exited 0, because no default channel had ever
+  // called a function. A flag that is off by default cannot save anybody, and a false
+  // all-clear is not a cheaper answer than a slow one — it is the one answer this tool may
+  // never give.
   //
-  // It is worth switching on because it sees what walking a product cannot. On the fixture
-  // where a total quietly stops rounding pennies, and the command line only ever adds whole
-  // pounds, the discovered journeys produce nothing at all — the output does not move by one
-  // character — and the harvested ones produce five findings.
+  // WHERE THE LINE IS DRAWN, and the measurement that drew it. Default-on is held to a
+  // TIGHTER budget than an explicit `--journeys suite`, and to a cap on how many harvested
+  // journeys are then walked, so the cost of a check nobody asked to slow down is bounded by
+  // construction instead of by a guess about somebody's suite. Measured on this machine on
+  // 2026-08-31, with twelve near-empty test files: harvesting them took 3.1 seconds, and the
+  // whole check went from 1.4 seconds to 8.2 — about 570ms per test file, and that is the
+  // FLOOR, because those tests did nothing. So the automatic path gets 20 seconds of harvest
+  // and walks at most 12 of what comes out, which lands a default check at well under half a
+  // minute on a project of that shape. Everything the budget or the cap left out is named as
+  // a hole with the command that would reach it — never dropped quietly.
+  //
+  // Asking for it by name still gets the full, uncapped ninety seconds, because somebody who
+  // typed `--journeys suite` has said what they are willing to wait for.
   //
   // Loaded here rather than at the top of the file: a copy of this tool without the harvest
   // in it still runs every other kind of check, and saying so is better than failing to start.
-  if (options.journeys === 'suite') {
+  const askedForTheSuite = options.journeys === 'suite';
+  let autoSuite = null;
+  if (!askedForTheSuite && !named && options.journeys !== 'recorded' && options.journeys !== 'code') {
+    autoSuite = await suiteWorthRunningByDefault(root, config);
+    if (autoSuite.gap) gaps.push(autoSuite.gap);
+  }
+  if (askedForTheSuite || autoSuite?.run) {
+    const automatic = !askedForTheSuite;
     try {
       const { journeysFromSuite, DEFAULT_HARVEST_BUDGET_MS } = await import('./journeys/index.js');
       // The settings file gets a say in how long this is allowed to take. Left out, the
       // harvest applies its own default, which is why nothing is passed rather than the
-      // default being copied to here — see `suiteBudgetFrom`.
-      const budgetMs = suiteBudgetFrom(config);
+      // default being copied to here — see `suiteBudgetFrom`. On the automatic path the
+      // tighter budget is used unless the settings ask for something of their own, because a
+      // number somebody wrote down beats a number this file guessed.
+      const asked = suiteBudgetFrom(config);
+      const budgetMs = asked ?? (automatic ? AUTO_HARVEST_BUDGET_MS : null);
+      const suiteOptions = {
+        ...(budgetMs === null ? {} : { budgetMs }),
+        ...(automatic ? { timeoutMs: AUTO_FILE_TIMEOUT_MS } : {}),
+      };
       const suite = await journeysFromSuite({
         root,
         surface: options.surface === 'auto' ? undefined : options.surface,
-        ...(budgetMs === null ? {} : { suite: { budgetMs } }),
+        ...(Object.keys(suiteOptions).length === 0 ? {} : { suite: suiteOptions }),
         // The harvest talks while it works, and it can take most of a minute. Its sentences
         // go into the same stream as everything else rather than nowhere.
         log: (message) => options.events?.emit({ type: 'note', at: options.events.elapsed(), message }),
@@ -2578,9 +2777,24 @@ async function gatherJourneys({ root, config, options }) {
         message:
           applied === 0
             ? 'The test-suite harvest was given no time budget at all, so every test file was run however long it took. Your settings asked for that with suite.budgetMs: 0.'
-            : `The test-suite harvest was held to ${Math.round(applied / 1000)} seconds${budgetMs === null ? ', which is the default' : ', which your settings asked for'}. Anything it did not reach in that time is named below rather than skipped quietly; change it with suite.budgetMs.`,
+            : `The test-suite harvest was held to ${Math.round(applied / 1000)} seconds${
+                asked !== null ? ', which your settings asked for' : automatic ? ', which is what an automatic run gets' : ', which is the default'
+              }. Anything it did not reach in that time is named below rather than skipped quietly; change it with suite.budgetMs.`,
       });
-      journeys.push(...suite.journeys);
+      // The cap, and only on the automatic path. Somebody who typed the flag gets everything
+      // their suite produced. Whoever did not type anything gets a bounded run and a list of
+      // exactly which of their test files are therefore not being watched.
+      let kept = suite.journeys;
+      if (automatic && kept.length > AUTO_HARVEST_JOURNEY_CAP) {
+        const dropped = kept.slice(AUTO_HARVEST_JOURNEY_CAP);
+        kept = kept.slice(0, AUTO_HARVEST_JOURNEY_CAP);
+        gaps.push({
+          what: `${dropped.length} of this project's test files were harvested and then not walked, so nothing here says anything about what they cover: ${dropped.map((j) => j.name).join(', ')}.`,
+          why: `A check nobody asked to slow down walks at most ${AUTO_HARVEST_JOURNEY_CAP} harvested test files, because each one is run twice on every build and the bill for a big suite would land on somebody who only wanted a quick answer.`,
+          unlockedBy: 'Run `staysfixed check --journeys suite` to walk all of them, or narrow the suite to the files that matter.',
+        });
+      }
+      journeys.push(...kept);
       gaps.push(...suite.gaps);
     } catch (e) {
       // A harvest that fell over is a hole, never a pass. Everything else this project has is
@@ -2593,13 +2807,37 @@ async function gatherJourneys({ root, config, options }) {
     }
   }
 
+  // ---- Calling what a library exports, rather than only reading its labels.
+  //
+  // See `from-exports.js` for the false all-clear that put this here. In one sentence: a
+  // library was checked, shipped, rewritten so that every value it returns came out
+  // different, and checked again — and the check passed, because every channel in the tool
+  // compared the NAMES and SHAPES of the exports and none of them had ever called one.
+  //
+  // It costs one extra process per configured module per build, which is the cheapest thing
+  // on this page, and it needs nothing configured that is not configured already: `init`
+  // writes `process.imports` for every library it sets up.
+  if (!named && options.journeys !== 'recorded') {
+    const answers = journeysFromExports({ config: config.process });
+    journeys.push(...answers.journeys);
+    gaps.push(...answers.gaps);
+  }
+
   for (const adapter of ADAPTERS) {
     if (adapter === sourceAdapter && named && options.journeys !== 'code') {
       // A journeys file names exactly what to walk. The contract read is still added,
       // because it cannot break anything and it sees what no journey does.
     }
     /** @type {import('./adapters/contract.js').AdapterProject} */
-    const project = { root, config: config[adapter.name] ?? {} };
+    // The folders the settings name, handed to every adapter alongside its own block.
+    //
+    // An adapter is given only the settings under its own name, so `http` could see
+    // `http.folders` and never `source.folders` — which is where `init` actually writes them.
+    // Route discovery therefore read the folders it guesses at, and a route outside them was
+    // never found on a project that had said, in its own settings, exactly where its code is.
+    // The adapter's own block still wins, because a project that overrode this meant it.
+    // Measured 2026-08-31.
+    const project = { root, config: { folders: config.source?.folders, ...(config[adapter.name] ?? {}) } };
     let detection;
     try {
       detection = await adapter.detect(project);
@@ -2825,6 +3063,69 @@ function nameOfReference(reference, asked) {
   return asked && asked.trim() !== '' ? `${asked} (${reference.id})` : reference.id;
 }
 
+/**
+ * Put one commit's files into a folder, without a shell and without touching the repository.
+ *
+ * `git archive` writes a tar to its standard output and `tar` reads one from its standard
+ * input, so the two are joined here directly. The archive never reaches the disk, which is why
+ * a big repository does not cost twice the space to look at — the reason the shell pipeline was
+ * there in the first place. Both programs are on every machine this runs on: Windows has
+ * shipped `tar.exe` since Windows 10, and git is already required for anything here to work.
+ *
+ * @param {string} root  The repository.
+ * @param {string} sha   The commit to put back.
+ * @param {string} dir   An empty folder to put it in.
+ * @returns {Promise<void>}
+ */
+function gitArchiveInto(root, sha, dir) {
+  return new Promise((resolve, reject) => {
+    const git = spawn('git', ['-C', root, 'archive', '--format=tar', sha], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    const untar = spawn('tar', ['-x', '-f', '-', '-C', dir], {
+      stdio: ['pipe', 'ignore', 'pipe'],
+      windowsHide: true,
+    });
+
+    let said = '';
+    for (const stream of [git.stderr, untar.stderr]) {
+      stream?.setEncoding('utf8');
+      stream?.on('data', (chunk) => { said = (said + chunk).slice(0, 4000); });
+    }
+
+    let done = false;
+    /** @param {Error|null} e */
+    const finish = (e) => {
+      if (done) return;
+      done = true;
+      clearTimeout(giveUp);
+      try { git.kill('SIGKILL'); } catch { /* already gone */ }
+      try { untar.kill('SIGKILL'); } catch { /* already gone */ }
+      if (e) reject(e);
+      else resolve();
+    };
+    const giveUp = setTimeout(
+      () => finish(new Error(`putting ${sha.slice(0, 7)} back took longer than two minutes.`)),
+      120_000,
+    );
+
+    git.on('error', finish);
+    untar.on('error', finish);
+    git.stdout.pipe(untar.stdin);
+    // A pipe that breaks because the other end has died is not news worth an unhandled error.
+    git.stdout.on('error', () => {});
+    untar.stdin.on('error', () => {});
+
+    git.on('exit', (code) => {
+      if (code !== 0) finish(new Error(said.trim() || `git archive stopped with code ${code}`));
+    });
+    untar.on('exit', (code) => {
+      finish(code === 0 ? null : new Error(said.trim() || `tar stopped with code ${code}`));
+    });
+  });
+}
+
 /**
  * Put the old build back on this machine so it can be walked live.
  *
@@ -2857,12 +3158,13 @@ async function exportBuild(root, reference, scratch) {
   const dir = path.join(scratch, `reference-${sha.slice(0, 12)}`);
   await fsp.mkdir(dir, { recursive: true });
   try {
-    // Straight through a pipe: the archive is never written to disk, so a big repository
-    // does not cost twice the space to look at.
-    await exec('/bin/sh', ['-c', `git -C ${quote(root)} archive --format=tar ${quote(sha)} | tar -x -C ${quote(dir)}`], {
-      timeout: 120_000,
-      maxBuffer: 8 * 1024 * 1024,
-    });
+    // Straight through a pipe: the archive is never written to disk, so a big repository does
+    // not cost twice the space to look at. The two programs are joined below rather than by a
+    // shell, because there is no `/bin/sh` on Windows — and that one word was the whole of
+    // paired mode there. Measured on a real Windows 11 machine on 2026-08-31: every `--paired`
+    // run answered "<sha> cannot be built here" and fell back to the stored record, which is
+    // the weaker comparison. The tool's strongest mode had never once run on Windows.
+    await gitArchiveInto(root, sha, dir);
   } catch (e) {
     await fsp.rm(dir, { recursive: true, force: true });
     throw new StaysFixedError(`${sha.slice(0, 7)} could not be put back on this machine, so it cannot be walked live. ${messageOf(e)}`, {
@@ -2983,10 +3285,6 @@ async function packageVersion(root) {
   return typeof pkg?.version === 'string' ? pkg.version : null;
 }
 
-/** @param {string} text */
-function quote(text) {
-  return `'${text.split("'").join(`'\\''`)}'`;
-}
 
 /** @param {string} name */
 function safeSegment(name) {

package/src/v2/cli.js

@@ -259,7 +259,7 @@ export const V2_COMMANDS = {
     summary: 'Test whether your own edit really caused a finding, by undoing it.',
     usage: 'staysfixed prove <finding> --revert <file> [--revert <file>]',
     describe:
-      'You believe your change to a particular file caused a difference. This puts that file\nback to the reference build, runs again, and says whether the difference went away.\nIf it survives, your edit did not cause it and you were about to fix the wrong thing.\n\nNothing is left reverted: the working tree is put back exactly as it was.\n\nIt answers 0 when it could test the claim and 2 when it could not. The answer itself —\ncaused it, or did not — is in the words, not the exit code, because "your edit was\ninnocent" is not a failure and must not be read as one.',
+      'You believe your change to a particular file caused a difference. This puts that file\nback to the reference build, runs again, and says whether the difference went away.\n\nIt gives you one of THREE answers, and only two of them are answers:\n  PROVEN CAUSED      undoing your change made the difference go away.\n  PROVEN NOT CAUSED  it was re-run without your change and the difference is still there,\n                     so you were about to fix the wrong file.\n  NOT TESTED         nothing was measured — the file you named was not among your changes,\n                     the old build would not build, or nothing was re-run at all. This\n                     never means your edit is innocent. It means nobody looked.\n\nIt is a real re-run, not a lookup: expect it to take about as long as a check.\nNothing is left reverted: the working tree is put back exactly as it was.\n\nIt answers 0 when it could test the claim and 2 when it could not. Which way it came out —\ncaused it, or did not — is in the words, not the exit code, because "your edit was\ninnocent" is not a failure and must not be read as one.',
     options: [
       ['--revert <file>', 'A file to put back to the reference for one run. Repeat it for several.'],
     ],
@@ -475,8 +475,26 @@ export async function proveRun(ctx) {
     });
   }
 
+  // The price, said before it is charged rather than after.
+  //
+  // Proving a cause is not a lookup. It checks out the old build into a scratch copy, undoes
+  // the one change, and WALKS THE JOURNEYS AGAIN - on a real website that is eleven to
+  // twenty minutes, and somebody who thinks they typed a query sits watching a blank screen
+  // and kills it. On 2026-08-31 the opposite also happened and is worse: an answer came back
+  // in five seconds, having started no build and walked nothing, and read exactly like a
+  // measurement. Saying what this is about to cost is half of what stops a fast reply being
+  // mistaken for a cheap one - the reply itself now says what it actually ran.
+  say(paint.grey(`Undoing ${revert.join(', ')} in a scratch copy and walking this product again. That is a full re-run of the journeys this finding came from, so it costs about what a check costs. Nothing of yours is touched and nothing is left reverted.`));
+  blank();
+
   const reply = await askTheToolSet(ctx, 'staysfixed_prove', { finding, revert });
   sayReply(reply);
+  // Non-zero means "could not test", never "your edit was innocent". `staysfixed_prove`
+  // marks exactly one of its three answers as an error - the one that is not an answer -
+  // which is the promise this command's own help has always made: 0 when it could test the
+  // claim, 2 when it could not. Until 2026-08-31 it exited 0 on all three, so a CI step or
+  // an agent reading the code alone was told a question nobody had answered had come back
+  // clean.
   return reply.isError ? EXIT.error : EXIT.ok;
 }