staysfixed 0.11.1 → 0.13.0

package/src/v2/check.js

@@ -51,11 +51,13 @@ 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';
 import { webAdapter } from './adapters/web.js';
 import { electronAdapter } from './adapters/electron.js';
+import { extensionAdapter } from './adapters/extension.js';
 
 const exec = promisify(execFile);
 
@@ -124,7 +126,7 @@ const exec = promisify(execFile);
  */
 
 /** The adapters compiled into every copy, in the order the engine trusts them. Reading the code is free, so it is first. */
-const BUILT_IN = [sourceAdapter, processAdapter, httpAdapter, webAdapter, electronAdapter];
+const BUILT_IN = [sourceAdapter, processAdapter, httpAdapter, webAdapter, electronAdapter, extensionAdapter];
 
 /**
  * The platforms that arrive as a file of their own.
@@ -158,6 +160,20 @@ const SEPARATE_ADAPTERS = [
     missing:
       'This copy has no native-Windows adapter in it. That is usually fine: a Windows product built with Electron is driven over its own debugging port by the Electron adapter and needs nothing else.',
   },
+  {
+    surface: 'macos',
+    file: './adapters/macos.js',
+    exports: ['macosAdapter', 'adapter', 'default'],
+    missing:
+      'This copy has no native-Mac adapter in it, so nothing here can open a Swift or Objective-C app and read what is on its screen. That is usually fine: a Mac product built with Electron is driven over its own debugging port by the Electron adapter and needs nothing else.',
+  },
+  {
+    surface: 'linux',
+    file: './adapters/linux.js',
+    exports: ['linuxAdapter', 'adapter', 'default'],
+    missing:
+      'This copy has no native-Linux adapter in it. That is usually fine: a Linux product built with Electron is driven over its own debugging port by the Electron adapter and needs nothing else.',
+  },
 ];
 
 /**
@@ -193,9 +209,12 @@ export const ADAPTER_FOR_SURFACE = {
   server: 'http',
   web: 'web',
   electron: 'electron',
+  extension: 'extension',
   android: 'android',
   ios: 'ios',
   windows: 'windows',
+  linux: 'linux',
+  macos: 'macos',
 };
 
 /**
@@ -564,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],
     });
@@ -1067,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'
             ? {
@@ -1196,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);
@@ -1207,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.`,
     };
   }
@@ -1222,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,
@@ -1235,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();
@@ -1570,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
@@ -1782,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.
  *
@@ -2121,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,
@@ -2322,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.
@@ -2377,6 +2559,65 @@ async function walkOne(req, where) {
   };
 }
 
+/**
+ * Something that can walk one journey in this project, right now, without a whole check.
+ *
+ * A check is the only thing that walked a journey until 2026-08-31, and that left the
+ * recording command with a choice between running a full check to find out whether a fresh
+ * recording repeats — minutes, a store write, a verdict nobody asked for — or writing a
+ * second, simpler walker of its own, which would then be the walker that never gets fixed
+ * when the real one is. Neither is acceptable, so the walk is handed out instead: the same
+ * adapters, the same scratch-copy-per-walk rule, and the same normalisation a real check
+ * applies, so what a recording is judged on is exactly what a later check will see.
+ *
+ * The caller closes it. Everything it made lives in one throwaway folder and `close` takes
+ * that folder away.
+ *
+ * @param {{cwd?: string, root?: string, configFile?: string, config?: Record<string, any>}} [options]
+ * @returns {Promise<{root: string, config: Record<string, any>, walk: (req: WalkRequest) => Promise<Capture>, close: () => Promise<void>}>}
+ */
+export async function walkerFor(options = {}) {
+  await loadAdapters();
+  const root = projectRootFor(options);
+  const config = options.config ?? (await readConfig(options.configFile ?? findConfigFile(root)));
+  const scratch = await fsp.mkdtemp(path.join(os.tmpdir(), 'staysfixed-walk-'));
+  const evidenceDir = path.join(scratch, 'evidence');
+  await fsp.mkdir(evidenceDir, { recursive: true });
+  // The same rewriting a check does, and for the same reason: every walk gets its own
+  // throwaway folder, so a product that prints where it is running from would otherwise
+  // look different on every single walk — including the two walks that are meant to prove a
+  // recording repeats, which would then never repeat and no recording would ever be
+  // accepted.
+  const rules = mergeRules(DEFAULT_RULES, [
+    ...pathRules({ root, scratch }),
+    ...(await loadRules(path.join(root, '.staysfixed', 'rules.json'))),
+  ]);
+  return {
+    root,
+    config,
+    walk: async (req) => normaliseCapture(await walkOne(req, { root, scratch, evidenceDir, config }), rules),
+    close: async () => {
+      await fsp.rm(scratch, { recursive: true, force: true }).catch(() => {});
+    },
+  };
+}
+
+/**
+ * This project's settings, found the way a check finds them.
+ *
+ * Exported so that nothing else has to re-implement "walk up from here looking for a config
+ * file, and read it whether it is JSON or a module". Two readers of one settings file that
+ * disagree about where it is, is a bug that only shows up in somebody else's repository.
+ *
+ * @param {{cwd?: string, root?: string, configFile?: string}} [options]
+ * @returns {Promise<{root: string, configFile: string|null, config: Record<string, any>}>}
+ */
+export async function settingsFor(options = {}) {
+  const root = projectRootFor(options);
+  const configFile = options.configFile ?? findConfigFile(root) ?? null;
+  return { root, configFile, config: await readConfig(configFile) };
+}
+
 /**
  * @param {Journey} journey
  * @returns {Adapter|null}
@@ -2409,44 +2650,118 @@ async function gatherJourneys({ root, config, options }) {
   const gaps = [];
 
   const named =
-    options.journeys && !['code', 'config', 'suite'].includes(options.journeys) ? options.journeys : null;
-  // `recorded` is a word this tool knows and `check --help` offers it — it is simply not
-  // wired into a run yet. The MCP surface says exactly that; the command line fell through to
-  // the branch above, treated the word as a FILE PATH, and answered that a file called
-  // "recorded" was missing. The same question has to get the same answer on both.
+    options.journeys && !['code', 'config', 'suite', 'recorded'].includes(options.journeys) ? options.journeys : null;
+
+  // Sessions somebody actually performed, read back off the disk and walked like anything
+  // else. This is the one source that knows how a person really uses the product — the four
+  // screens they open every morning, in that order — and no amount of reading the source can
+  // work that out, because the source only says which doors exist, never which ones anybody
+  // opens. Until 2026-08-31 asking for it threw: the code to make a recording existed, and
+  // nothing on the check path ever read one.
+  //
+  // A run that was ASKED for recorded sessions and found none stops and says so. Carrying on
+  // with the journeys read out of the code would walk something the person did not ask for
+  // and then report "nothing that worked has broken" — a clean answer about the wrong steps,
+  // which is the one shape of reply this tool may never produce.
   if (options.journeys === 'recorded') {
-    throw new StaysFixedError(
-      'Replaying a recorded session is written and not wired into a run yet, so nothing was checked.',
-      {
-        hint: 'Leave --journeys out to use the steps each adapter reads from your source, pass `suite` to walk your own test suite, or pass the path to a journeys file.',
-      },
-    );
+    const { RECORDINGS_DIR, loadJourneyFolder, whatWillNotReplay } = await import('./journeys/record.js');
+    const dir = path.join(root, RECORDINGS_DIR);
+    const loaded = await loadJourneyFolder(dir);
+    if (loaded.journeys.length === 0) {
+      throw new StaysFixedError(
+        `You asked for recorded sessions and there are none in ${shortPath(dir)}, so nothing was checked.`,
+        {
+          hint:
+            'Make one: `staysfixed record <a-name-for-it>` opens your product, follows what you do, walks it twice to prove it repeats, and writes it there. ' +
+            `${loaded.problems.length > 0 ? `Something is already in that folder and could not be read: ${loaded.problems.join(' ')} ` : ''}` +
+            'Or leave --journeys out to use the steps each adapter reads from your source.',
+        },
+      );
+    }
+    for (const journey of loaded.journeys) {
+      // Said before it is walked, not after it fails. A recording rots quietly: the ids,
+      // ports and timestamps captured on the afternoon somebody made it go stale, and the
+      // replay then fails for a reason that has nothing to do with the product.
+      const willNotReplay = whatWillNotReplay(journey);
+      if (willNotReplay.length > 0) {
+        gaps.push({
+          what: `The recorded session "${journey.name}" may not replay.`,
+          why: willNotReplay.join(' '),
+          unlockedBy: 'Record it again with `staysfixed record`, or reach the same thing from the code or the test suite, where nothing goes stale.',
+          surface: journey.surface,
+        });
+      }
+    }
+    for (const problem of loaded.problems) {
+      gaps.push({
+        what: 'A file in the recordings folder was not walked.',
+        why: problem,
+        unlockedBy: 'Fix that file, or record the session again. A recording nothing can read is a hole, not a pass.',
+      });
+    }
+    journeys.push(...loaded.journeys);
   }
+
   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 }),
@@ -2462,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
@@ -2477,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);
@@ -2501,7 +2855,11 @@ async function gatherJourneys({ root, config, options }) {
       continue;
     }
     if (!detection.applies) continue;
-    if (adapter !== sourceAdapter && named) continue;
+    // A journeys file and a recorded session both name exactly what to walk, so no adapter
+    // adds journeys of its own on top of them. The source reader is the exception: it runs
+    // nothing, it cannot break anything, and it is the only channel that sees a door nobody
+    // has ever walked through.
+    if (adapter !== sourceAdapter && (named || options.journeys === 'recorded')) continue;
     try {
       journeys.push(...(await adapter.journeys(project)));
     } catch (e) {
@@ -2705,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.
  *
@@ -2737,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)}`, {
@@ -2863,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) {