staysfixed 0.12.0 → 0.13.0

package/src/v2/adapters/http.js

@@ -33,7 +33,7 @@ import net from 'node:net';
 import path from 'node:path';
 import {
   defineAdapter, joinPath, notCovered, observation, sizeBucket, stableValue,
-  howLongItTook, timeBucket, trimForStorage, undoOurFootprint,
+  howLongItTook, timeBucket, trimForStorage, undoOurFootprint, whatItSaid,
 } from './contract.js';
 import {
   compareTrees, copyForScratch, frozenEnvironment, readWatcher, snapshotTree, watcherScript,
@@ -533,7 +533,16 @@ export const httpAdapter = defineAdapter({
     const framework = ['express', 'fastify', 'hono', 'koa', 'next', 'polka', '@hapi/hapi']
       .find((name) => name in dependencies);
 
-    const reading = await readContract({ root: project.root });
+    // The folders the settings name, not the built-in guess. Route discovery read only src,
+    // lib, app, bin, server, pages, api, electron, main and packages, so a project that keeps
+    // its routes in a folder outside that list had them read as not existing — measured
+    // 2026-08-31 with routes in a top-level `routes/` folder, where `GET /api/orders` and
+    // `POST /api/orders` were both invisible and the run reported one route where there were
+    // three. NOTE, and this is a real limit of the fix: an adapter is only handed the settings
+    // under its OWN name, so this reads `http.folders` and cannot see `source.folders`, which
+    // is where `staysfixed init` writes them today. Naming them under `http` works now; making
+    // `source.folders` reach here needs one line in check.js, which this lane does not own.
+    const reading = await readContract({ root: project.root, folders: project.config?.folders });
     const routes = [...reading.doors.filter((d) => d.kind === 'route'), ...(await readFileRoutes(project.root)).doors];
 
     if (!config.start) {
@@ -582,7 +591,16 @@ export const httpAdapter = defineAdapter({
   async journeys(project) {
     const config = project.config ?? {};
     const samples = config.samples ?? {};
-    const reading = await readContract({ root: project.root });
+    // The folders the settings name, not the built-in guess. Route discovery read only src,
+    // lib, app, bin, server, pages, api, electron, main and packages, so a project that keeps
+    // its routes in a folder outside that list had them read as not existing — measured
+    // 2026-08-31 with routes in a top-level `routes/` folder, where `GET /api/orders` and
+    // `POST /api/orders` were both invisible and the run reported one route where there were
+    // three. NOTE, and this is a real limit of the fix: an adapter is only handed the settings
+    // under its OWN name, so this reads `http.folders` and cannot see `source.folders`, which
+    // is where `staysfixed init` writes them today. Naming them under `http` works now; making
+    // `source.folders` reach here needs one line in check.js, which this lane does not own.
+    const reading = await readContract({ root: project.root, folders: project.config?.folders });
     const routes = [...reading.doors.filter((d) => d.kind === 'route'), ...(await readFileRoutes(project.root)).doors];
 
     /** @type {Map<string, import('./contract.js').Journey>} */
@@ -733,9 +751,21 @@ export const httpAdapter = defineAdapter({
 
     if (!up.up) {
       await stopServer(child);
+      // WHAT THE SERVER SAID GOES FIRST, ahead of the wait's own account of the port it knocked
+      // on. Measured 2026-08-31: a server whose source has a syntax error prints `SyntaxError`
+      // and the failing line on its standard error, and this sentence used to bury that behind
+      // a hundred and fifty characters about loopback addresses. `staysfixed coverage` prints
+      // the sentence built from this with a 160 character budget, so buried meant gone: the
+      // owner of a product that would not boot was never told why, on any surface, even with
+      // `--verbose`. The port is the tool's own business; the syntax error is the product's,
+      // and it is the only line here that anybody can act on.
+      const printed = Buffer.concat(bootErr).toString('utf8') || Buffer.concat(bootOut).toString('utf8');
+      const headline = whatItSaid(printed, { mostLines: 1 });
       return {
         build, root: work, ready: false,
-        why: `${up.why} What it printed while trying: ${trimForStorage(Buffer.concat(bootErr).toString('utf8') || Buffer.concat(bootOut).toString('utf8'), 1500).text || '(nothing)'}`,
+        why: `${headline ? `It said: ${headline}. ` : ''}${up.why} What it printed while trying, in full: ${
+          trimForStorage(printed, 1500).text || '(nothing)'
+        }`,
         dispose: async () => { await stopServer(child); await fsp.rm(base, { recursive: true, force: true }); },
       };
     }
@@ -807,7 +837,20 @@ export const httpAdapter = defineAdapter({
         channel: 'effects',
         path: joinPath('api', journey.name, 'answered at all'),
         reason: 'irreversible',
-        says: `${detail.method} ${detail.route} was left alone. The project marked it as spending money, sending a message or destroying data, and nothing is watching this server from the inside, so there is no way to stop it happening for real. This is a hole in what was checked, not a pass.`,
+        // The sentence names the setting, because this is the one place where the guess costs
+        // something. The list under "irreversible" is written by `staysfixed init` by matching
+        // WORDS IN A ROUTE'S NAME, and a name can be wrong: measured 2026-08-31, a pure
+        // arithmetic route called `/api/invoice/estimate` was put on that list because the word
+        // "invoice" is in it. On a Node server that costs nothing — the route is walked anyway,
+        // behind a refusal boundary that is proven to be in force — but here nothing is
+        // watching, and a wrong guess costs the whole route silently. Telling somebody a
+        // control exists without telling them where it is leaves them exactly where they were.
+        says:
+          `${detail.method} ${detail.route} was left alone. It is on the "irreversible" list under "http" in the ` +
+          `settings — routes that spend money, send a message or destroy data — and nothing is watching this server ` +
+          `from the inside, so there is no way to stop it happening for real. This is a hole in what was checked, not ` +
+          `a pass. That list is first written by matching words in a route's name, which is a guess: if this route ` +
+          `only reads or works something out, take it off the list and it starts being checked.`,
       })];
     }
 
@@ -877,6 +920,23 @@ async function snapshotForFolders(root, folders) {
 // Turning one request into observations
 // ---------------------------------------------------------------------------
 
+/**
+ * The verbs that carry a body. Asking one of these with no body at all is asking a question
+ * the route was never designed to answer, so whatever comes back is about the question.
+ */
+const CARRIES_A_BODY = new Set(['POST', 'PUT', 'PATCH']);
+
+/**
+ * What a route answers when what it was handed is not what it needs: 400 Bad Request, 411
+ * Length Required, 415 Unsupported Media Type, 422 Unprocessable Content.
+ *
+ * Deliberately short, and deliberately NOT including 401 or 403. Those mean "you are not
+ * signed in", which is a different hole with a different fix, and folding them in here would
+ * quietly stop comparing every route of every product behind a login wall on the strength of a
+ * guess made in this file.
+ */
+const NOT_WHAT_IT_NEEDS = new Set([400, 411, 415, 422]);
+
 /**
  * @param {object} input
  * @param {import('./contract.js').Journey} input.journey
@@ -907,39 +967,95 @@ export function describeRequest(input) {
     return out;
   }
 
-  out.push(observation({
-    channel: 'results',
-    path: joinPath('api', id, 'status'),
-    value: answer.status,
-    says: `${asked} answered ${answer.status}${answer.status >= 400 ? ', which is a refusal' : ''}.`,
-  }));
-
-  const headers = headersThatMatter(answer.headers);
-  for (const [name, value] of Object.entries(headers)) {
+  // A ROUTE THAT REFUSED THE CALL IS NOT A ROUTE THAT WAS WALKED.
+  //
+  // Measured 2026-08-31 on a small quote API. The route list comes out of the source, and the
+  // source says a route's address and its verb and nothing whatever about the body it expects —
+  // so `POST /api/quote` was asked with no body at all. It answered 400, correctly, and this
+  // function wrote that 400 down as the route's behaviour. From then on every run compared the
+  // new build's 400 against the old build's 400, agreed, and reported the route as walked in
+  // the coverage ledger. The route's real work — the arithmetic that decides what a customer is
+  // charged — had never once been run, and a rounding bug in it was invisible for ever, under a
+  // result that said the route was covered.
+  //
+  // A 400 to a request this tool got wrong is an observation of THIS TOOL, not of the product.
+  // So it is recorded as what it is: a door found and not opened, with the reason. Everything
+  // about this request is marked refused, which is what puts the route in the ledger's
+  // never-opened list instead of its walked list — see `walkFromCapture` in coverage.js, where
+  // a capture whose whole non-contract record is refusals counts as a walk that did nothing.
+  //
+  // NARROW ON PURPOSE, in three ways at once, because the cost of getting this wrong is that a
+  // real answer stops being compared. It only applies to a verb that carries a body; only when
+  // this tool sent no body, so a body somebody wrote into the settings themselves is always the
+  // product's own answer and is always compared; and only to the four codes that mean "that is
+  // not what I need". A route that answers 400 to a request that was properly formed is
+  // untouched by this and goes on being compared exactly as before.
+  const verb = String(detail.method ?? 'GET').toUpperCase();
+  const weSentNoBody = detail.body === undefined;
+  const ourOwnFault = CARRIES_A_BODY.has(verb) && weSentNoBody && NOT_WHAT_IT_NEEDS.has(answer.status);
+  if (ourOwnFault) {
+    // What the route said about it, in the route's own words. It is usually the exact list of
+    // fields it wanted, which is the fastest way for somebody to write the body it needs — so
+    // it is quoted rather than summarised, for the same reason a crash's own words are.
+    const complained = whatItSaid(undoOurFootprint(input.text, footprint), { mostLines: 2 });
+    out.push(notCovered({
+      channel: 'results',
+      path: joinPath('api', id, 'answered at all'),
+      reason: 'needs a sample',
+      says:
+        `${asked} was not really walked. It answered ${answer.status}, and that is this tool's request being turned ` +
+        `away rather than anything the route does: it was asked with no body at all, because a route's address and ` +
+        `verb can be read out of the source and the body it expects cannot.${complained ? ` It said: ${complained}.` : ''} ` +
+        `Whatever is behind that check has never run, so a bug in the route's own working — the kind that charges ` +
+        `somebody the wrong amount — would not be seen here, and this route is counted as a door found and not ` +
+        `opened. Put a real body under "requests" in the "http" settings — ` +
+        `{ name: '${asked}', method: '${verb}', url: '${detail.route}', body: { ... } } — and it starts being checked.`,
+      detail: complained,
+    }));
+  } else {
     out.push(observation({
       channel: 'results',
-      path: joinPath('api', id, 'header', name),
-      value: undoOurFootprint(Array.isArray(value) ? value.join(', ') : value, footprint),
-      says: `${asked} answered with ${name}: ${Array.isArray(value) ? value.join(', ') : value}.`,
+      path: joinPath('api', id, 'status'),
+      value: answer.status,
+      says: `${asked} answered ${answer.status}${answer.status >= 400 ? ', which is a refusal' : ''}.`,
     }));
   }
 
-  const body = readBody(answer.headers.get('content-type') ?? '', undoOurFootprint(input.text, footprint));
-  out.push(observation({
-    channel: 'results',
-    path: joinPath('api', id, 'body'),
-    value: body.value,
-    says: body.truncated
-      ? `What ${asked} sent back, with the middle left out — the whole of it is ${sizeBucket(body.bytes)}.`
-      : `What ${asked} sent back.`,
-  }));
-  if (body.shape !== undefined) {
+  // The headers, the body and its shape describe the answer to a request the route rejected,
+  // so on a rejected request they describe this tool and not the product. They are left out
+  // rather than compared, which is what every other never-really-tried branch in this adapter
+  // does — and what the route said for itself is quoted in the sentence above, where somebody
+  // will actually read it. Comparing them would be worse than useless: two builds whose
+  // validation message was reworded would report a difference nobody caused, at an address
+  // standing in for a route neither run has ever been inside.
+  if (!ourOwnFault) {
+    const headers = headersThatMatter(answer.headers);
+    for (const [name, value] of Object.entries(headers)) {
+      out.push(observation({
+        channel: 'results',
+        path: joinPath('api', id, 'header', name),
+        value: undoOurFootprint(Array.isArray(value) ? value.join(', ') : value, footprint),
+        says: `${asked} answered with ${name}: ${Array.isArray(value) ? value.join(', ') : value}.`,
+      }));
+    }
+
+    const body = readBody(answer.headers.get('content-type') ?? '', undoOurFootprint(input.text, footprint));
     out.push(observation({
       channel: 'results',
-      path: joinPath('api', id, 'shape'),
-      value: body.shape,
-      says: `The fields ${asked} sends back and what type each one is. This stays the same while the values change, so a renamed or dropped field shows up on its own instead of buried in a diff of the whole body.`,
+      path: joinPath('api', id, 'body'),
+      value: body.value,
+      says: body.truncated
+        ? `What ${asked} sent back, with the middle left out — the whole of it is ${sizeBucket(body.bytes)}.`
+        : `What ${asked} sent back.`,
     }));
+    if (body.shape !== undefined) {
+      out.push(observation({
+        channel: 'results',
+        path: joinPath('api', id, 'shape'),
+        value: body.shape,
+        says: `The fields ${asked} sends back and what type each one is. This stays the same while the values change, so a renamed or dropped field shows up on its own instead of buried in a diff of the whole body.`,
+      }));
+    }
   }
 
   for (const change of input.changes) {
@@ -950,6 +1066,12 @@ export function describeRequest(input) {
       says: change.what === 'deleted'
         ? `Answering ${asked} deleted ${change.file}.`
         : `Answering ${asked} ${change.what} ${change.file}. A route that still answers correctly but has stopped writing this file is broken, and only this line sees it.`,
+      // A file written while the route was turning our request away is a real thing the product
+      // did, and it is kept on the record — but it is not evidence that the route works, and if
+      // it were left as a plain observation this one line would put the route back in the
+      // ledger's walked column and undo the whole fix above.
+      covered: ourOwnFault ? false : undefined,
+      reason: ourOwnFault ? 'needs a sample' : undefined,
     }));
   }
 

package/src/v2/adapters/isolate.js

@@ -30,6 +30,7 @@
  */
 
 import crypto from 'node:crypto';
+import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import net from 'node:net';
 import os from 'node:os';
@@ -141,11 +142,20 @@ function announce(app) {
  */
 export function appNameFor(binary) {
   const text = String(binary ?? '');
-  const parts = text.split(path.sep);
+  // Both separators, not just this machine's. A path is a fact about the machine it came
+  // from, and this one is asked about a Mac app bundle — so on Windows, where `path.sep` is a
+  // backslash, `/Applications/Widget.app/Contents/MacOS/Widget` did not split at all and the
+  // app was announced to the person's screen as "Widget" only by luck, or as the wrong name
+  // when the two differ. Measured on a real Windows 11 machine on 2026-08-31, where it
+  // answered "Electron" for an app called Terminal Deck.
+  const parts = text.split(/[\\/]/);
   for (let i = parts.length - 1; i >= 0; i -= 1) {
     if (parts[i].toLowerCase().endsWith('.app')) return parts[i].slice(0, -4);
   }
-  const base = path.basename(text);
+  // The last part of the same split, rather than `path.basename`, so the whole function reads
+  // a path the same way from end to end. `path.basename` only knows this machine's separator,
+  // and half a function that understands both is worse than either.
+  const base = parts[parts.length - 1] ?? '';
   const dot = base.lastIndexOf('.');
   return dot > 0 ? base.slice(0, dot) : base;
 }
@@ -264,6 +274,52 @@ export async function takePort() {
 // Who is holding what
 // ---------------------------------------------------------------------------
 
+/**
+ * The whole process table, on Windows: who is running, who started them, and with what.
+ *
+ * This is Windows' `ps -axo pid=,ppid=,command=`. There is no `ps` there, and the two callers
+ * below used to hand back an empty list rather than an answer — which reads exactly like
+ * "nothing is running", the most dangerous wrong answer either of them could give. PowerShell
+ * is on every Windows machine and answers all three columns in one call; JSON rather than a
+ * table, because a command line is full of spaces and quotes and columns cannot survive it.
+ *
+ * An unanswerable question still returns an empty list, because a sweep that cannot be done is
+ * not a reason to fail somebody's check — but it is now the rare case rather than every case.
+ *
+ * @returns {Promise<{pid: number, ppid: number, command: string}[]>}
+ */
+async function windowsProcessTable() {
+  try {
+    const { stdout } = await execFileAsync(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-ExecutionPolicy',
+        'Bypass',
+        '-Command',
+        'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine | ConvertTo-Json -Compress -Depth 2',
+      ],
+      { timeout: 20_000, maxBuffer: 32 * 1024 * 1024, windowsHide: true },
+    );
+    const text = String(stdout).trim();
+    if (text === '') return [];
+    const parsed = JSON.parse(text);
+    // One process comes back as an object rather than a list of one, which is PowerShell being
+    // helpful in a way that would otherwise crash the loop below.
+    const rows = Array.isArray(parsed) ? parsed : [parsed];
+    return rows
+      .map((row) => ({
+        pid: Number(row?.ProcessId ?? 0),
+        ppid: Number(row?.ParentProcessId ?? 0),
+        command: String(row?.CommandLine ?? ''),
+      }))
+      .filter((row) => Number.isInteger(row.pid) && row.pid > 0);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Every process on this machine whose command line contains `marker`.
  *
@@ -276,6 +332,15 @@ export async function takePort() {
  */
 export async function whoIsUsing(marker) {
   if (!marker || marker.length < 8) return [];
+  // Windows has no `ps`, and asking it nothing at all was the same as answering "nobody is
+  // using this folder" — which is the one answer this function must never invent, because it
+  // is what the run trusts when it decides it is alone. Measured on a real Windows 11 machine
+  // on 2026-08-31: every call here failed silently and returned an empty list.
+  if (process.platform === 'win32') {
+    return (await windowsProcessTable())
+      .filter((row) => row.pid !== process.pid && row.command.includes(marker))
+      .map((row) => ({ pid: row.pid, command: row.command }));
+  }
   try {
     const { stdout } = await execFileAsync('/bin/ps', ['-axo', 'pid=,command='], {
       timeout: 8000,
@@ -321,19 +386,29 @@ export async function descendantsOf(pids) {
   if (roots.length === 0) return [];
   /** @type {Map<number, number[]>} */
   const childrenOf = new Map();
-  try {
-    const { stdout } = await execFileAsync('/bin/ps', ['-axo', 'pid=,ppid='], { timeout: 8000, maxBuffer: 8 * 1024 * 1024 });
-    for (const line of stdout.split('\n')) {
-      const match = line.trim().match(/^(\d+)\s+(\d+)$/);
-      if (!match) continue;
-      const pid = Number(match[1]);
-      const parent = Number(match[2]);
-      const list = childrenOf.get(parent) ?? [];
-      list.push(pid);
-      childrenOf.set(parent, list);
+  /** @param {number} pid @param {number} parent */
+  const note = (pid, parent) => {
+    const list = childrenOf.get(parent) ?? [];
+    list.push(pid);
+    childrenOf.set(parent, list);
+  };
+  // The same table, asked for in Windows' words. Returning nothing here meant the app's own
+  // children — the renderer processes a browser or an Electron app starts — were never found
+  // and never closed, so every check on Windows left a handful of them behind. Measured on a
+  // real Windows 11 machine on 2026-08-31.
+  if (process.platform === 'win32') {
+    for (const row of await windowsProcessTable()) note(row.pid, row.ppid);
+  } else {
+    try {
+      const { stdout } = await execFileAsync('/bin/ps', ['-axo', 'pid=,ppid='], { timeout: 8000, maxBuffer: 8 * 1024 * 1024 });
+      for (const line of stdout.split('\n')) {
+        const match = line.trim().match(/^(\d+)\s+(\d+)$/);
+        if (!match) continue;
+        note(Number(match[1]), Number(match[2]));
+      }
+    } catch {
+      return [];
     }
-  } catch {
-    return [];
   }
   /** @type {Set<number>} */
   const found = new Set();
@@ -379,6 +454,21 @@ function refuseIfNotScratch(scratchDir, dir) {
       'A run always gets its own throwaway settings folder — never a real one.',
     );
   }
+  // Anything inside the machine's own temp folder is throwaway by definition, and the
+  // settings check below is skipped for it.
+  //
+  // This is not a loophole, it is the difference between the two operating systems. On
+  // Windows the temp folder lives INSIDE the settings folder — `C:\Users\me\AppData\Local\Temp`
+  // sits under `C:\Users\me\AppData` — so the rule "refuse anything under AppData" refused
+  // every scratch folder the tool makes for itself. Measured on a real Windows 11 machine on
+  // 2026-08-31: all 18 isolation cases failed with "that is where real settings live" about a
+  // folder the tool had just created for its own use, which means isolation, and therefore
+  // every check that opens an app, could never have worked on Windows at all.
+  //
+  // The guard itself is unchanged everywhere else, and is still the strict one: the folder
+  // has to be inside the scratch folder the engine handed us, and if it is not somewhere the
+  // operating system itself calls temporary, it may not be anywhere near real settings.
+  if (isUnderTemp(inside)) return;
   for (const real of [
     path.join(os.homedir(), 'Library', 'Application Support'),
     path.join(os.homedir(), '.config'),
@@ -390,6 +480,28 @@ function refuseIfNotScratch(scratchDir, dir) {
   }
 }
 
+/**
+ * Is this path inside the folder the operating system itself hands out for throwaway files?
+ *
+ * Both spellings are compared, because Windows hands the same folder out under two names: the
+ * long one and the old eight-character one (`C:\Users\RUNNER~1\...`), and a path that came
+ * back from one call can be spelled the other way from the next.
+ *
+ * @param {string} resolvedWithSeparator  An already-resolved path, ending in a separator.
+ * @returns {boolean}
+ */
+function isUnderTemp(resolvedWithSeparator) {
+  const temp = os.tmpdir();
+  /** @type {string[]} */
+  const spellings = [temp];
+  try {
+    spellings.push(fs.realpathSync.native(temp));
+  } catch {
+    // No second spelling available, which is the ordinary case everywhere but Windows.
+  }
+  return spellings.some((t) => resolvedWithSeparator.startsWith(path.resolve(t) + path.sep));
+}
+
 /**
  * The flags that make one desktop app run alone, and paint the same way twice.
  *
@@ -423,6 +535,41 @@ export function isolationArgs(isolation, opts = {}) {
   ];
 }
 
+/**
+ * The Windows half of "its own settings folder".
+ *
+ * Everything in the list above is POSIX — HOME, TMPDIR, the XDG folders — and a Windows
+ * program reads none of it. It reads USERPROFILE, APPDATA and LOCALAPPDATA. So on Windows the
+ * promise at the very top of this file was quietly not being kept: the run got its own
+ * folders, and the app carried on writing into the person's real ones. Found on 2026-08-31,
+ * the first day anything in this file had ever run on Windows.
+ *
+ * The second group is not isolation, it is the machine. The environment handed to a child here
+ * REPLACES the child's own rather than adding to it, and these are the variables a Windows
+ * program is entitled to assume are there — SystemRoot above all, which is where it looks for
+ * the libraries that open a socket. `node` and `npm` were measured starting perfectly well
+ * without them on 2026-08-31, so this is not a fault anybody has hit; it is a hole left open
+ * that a real desktop app is much more likely to fall into than a command-line tool is. They
+ * are copied from this process rather than invented, because they describe the machine and
+ * not the run.
+ *
+ * @param {string} homeDir  The throwaway home this run was given.
+ * @returns {Record<string, string>}
+ */
+function windowsIsolationEnv(homeDir) {
+  /** @type {Record<string, string>} */
+  const env = {
+    USERPROFILE: homeDir,
+    APPDATA: path.join(homeDir, 'AppData', 'Roaming'),
+    LOCALAPPDATA: path.join(homeDir, 'AppData', 'Local'),
+  };
+  for (const name of ['SystemRoot', 'windir', 'SystemDrive', 'COMSPEC', 'PATHEXT', 'NUMBER_OF_PROCESSORS', 'PROCESSOR_ARCHITECTURE']) {
+    const value = process.env[name];
+    if (value) env[name] = value;
+  }
+  return env;
+}
+
 /**
  * Set one run up: its own folders, its own ports, its own identity.
  *
@@ -458,6 +605,13 @@ export async function reserveIsolation(opts) {
   for (const folder of [userDataDir, homeDir, tmpDir, cacheDir, crashDir]) {
     await fsp.mkdir(folder, { recursive: true });
   }
+  // The two folders a Windows program expects to find already there. It is handed a home of
+  // its own below, and a home with no AppData in it is not one any Windows app has ever seen.
+  if (process.platform === 'win32') {
+    for (const folder of [path.join(homeDir, 'AppData', 'Roaming'), path.join(homeDir, 'AppData', 'Local')]) {
+      await fsp.mkdir(folder, { recursive: true });
+    }
+  }
 
   const debugPort = await takePort();
   const inspectPort = await takePort();
@@ -516,6 +670,7 @@ export async function reserveIsolation(opts) {
       // Nothing being checked should be phoning home about itself.
       ELECTRON_NO_ATTACH_CONSOLE: '1',
       ELECTRON_ENABLE_LOGGING: '1',
+      ...(process.platform === 'win32' ? windowsIsolationEnv(homeDir) : {}),
       ...identityEnv,
       ...opts.env,
     },

package/src/v2/adapters/process.js

@@ -40,7 +40,7 @@ import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import {
   defineAdapter, howLongItTook, joinPath, notCovered, observation, sizeBucket,
-  trimForStorage, undoOurFootprint,
+  trimForStorage, undoOurFootprint, whatItSaid,
 } from './contract.js';
 // The harvest writes the test-file steps this adapter walks, and it owns reading a runner's
 // output back. One place on purpose: a journey read differently from the way it was
@@ -1382,7 +1382,16 @@ export function importProbeCommand(moduleId) {
     "}",
     "process.stdout.write('\\n' + " + JSON.stringify(EXPORTS_MARKER) + " + '\\n' + JSON.stringify(out, null, 2));",
   ].join('\n');
-  return `node --input-type=module -e ${shellQuote(probe)} ${shellQuote(moduleId)}`;
+  // The probe travels as base64 inside a data: URL rather than as its own text.
+  //
+  // It is many lines long, and a `cmd.exe` command line cannot carry a newline at all — the
+  // first one ends the command. It also contains quotes, colons and angle brackets, every one
+  // of which means something to a shell. Base64 is letters, digits and three punctuation marks
+  // that no shell reads as anything, so what arrives is what was sent, on every machine.
+  // Measured on a real Windows 11 machine on 2026-08-31.
+  const carried = Buffer.from(probe, 'utf8').toString('base64');
+  const load = `await import('data:text/javascript;base64,${carried}')`;
+  return `node --input-type=module -e ${shellQuote(load)} ${shellQuote(moduleId)}`;
 }
 
 /**
@@ -1568,8 +1577,20 @@ async function fingerprintOf(file) {
   }
 }
 
-/** @param {string} text */
+/**
+ * One argument, quoted the way THIS machine's shell reads quotes.
+ *
+ * Single quotes everywhere except Windows, where `cmd.exe` does not treat them as quotes at
+ * all — it hands the quote through as part of the word. Measured on a real Windows 11 machine
+ * on 2026-08-31: every command built here arrived as literal text, the probe came back
+ * `SyntaxError: Invalid or unexpected token` on the text `'const`, and the run reported the
+ * product broken when nothing had been run. Windows uses double quotes, and a double quote
+ * inside the value is doubled, which is how `cmd.exe` spells one.
+ *
+ * @param {string} text
+ */
 function shellQuote(text) {
+  if (process.platform === 'win32') return `"${String(text).replace(/"/g, '""')}"`;
   return `'${text.split("'").join(`'\\''`)}'`;
 }
 
@@ -1686,15 +1707,45 @@ export async function describeRun(input) {
         : result.signal
           ? `it was killed by ${result.signal} having printed nothing`
           : `it exited ${result.code} without printing anything at all`;
+    // AND SAY WHAT IT ACTUALLY SAID. This was the whole gap, measured 2026-08-31 on three
+    // deliberately broken products — a Node server with a syntax error, a Python command
+    // importing a module that is not installed, and a Node command importing a package that is
+    // not installed. Every one of them was correctly refused, and every one of their owners was
+    // told only "it fell over", six times over, with `--verbose` on. All three had printed the
+    // reason on their own standard error, in one line, and this sentence threw it away. Being
+    // told "it fell over" instead of "line 18 of server.js has a syntax error" sends a person
+    // off to find it themselves, which is the one thing this tool exists not to do.
+    //
+    // TWO RENDERINGS, because they are read in two places with two different budgets.
+    // `staysfixed coverage` prints this sentence with 160 characters and the refusal's reason
+    // underneath it with 400. So the sentence gets the ONE line that names the thing — a
+    // runtime puts that last, which is why it is the last line — and the reason underneath
+    // gets the fuller quote, file and line and all. Neither is ever compared: both live in
+    // `meta`, so a crash worded differently on two machines cannot register as a change in the
+    // product.
+    const spoke = input.quieten
+      ? input.quieten(undoOurFootprint(result.stderr, footprint))
+      : undoOurFootprint(result.stderr, footprint);
+    // Standard error first, because that is where a runtime puts the reason. Standard output is
+    // the fallback for a program that complains on the wrong channel, and there is nothing to
+    // fall back to when a command never started at all — the machine's own words are in `why`.
+    const spokeOrPrinted = spoke.trim() === '' ? undoOurFootprint(result.stdout, footprint) : spoke;
+    const headline = whatItSaid(spokeOrPrinted, { mostLines: 1 });
+    const inFull = whatItSaid(spokeOrPrinted);
     out.push(notCovered({
       channel: 'complaints',
       path: joinPath('cli', id, 'ran at all'),
       reason: 'crashed',
+      // What it said leads, ahead of the journey's own name, and that ordering is the point:
+      // the name of the journey is something the reader already knows, and the error is the
+      // only new fact in the sentence. Put second, it is what a trim cuts off.
       says:
-        `"${journey.describe}" did not get far enough to observe the product: ${why}. What it complained about and how ` +
-        `it finished are recorded below and are facts about the crash, not about the product — so nothing here is ` +
-        `compared with the other build. A command that fails the same way on both builds otherwise agrees at every ` +
-        `address, and that agreement reads exactly like a clean run.`,
+        `Nothing was seen of the product${headline ? `. It said: ${headline}` : ''}. That is as far as ` +
+        `"${journey.describe}" got — ${why}. What it complained about and how it finished are recorded below and are ` +
+        `facts about the crash, not about the product — so nothing here is compared with the other build. A command ` +
+        `that fails the same way on both builds otherwise agrees at every address, and that agreement reads exactly ` +
+        `like a clean run.`,
+      detail: inFull,
     }));
   }
   out.push(observation({
@@ -1871,11 +1922,24 @@ export function apiSurface(journey, result) {
     surface = JSON.parse(at === -1 ? result.stdout : result.stdout.slice(at + EXPORTS_MARKER.length));
     if (surface === null || typeof surface !== 'object' || Array.isArray(surface)) throw new Error('not a list of names');
   } catch {
+    // A module that will not import is the same defect as a command that will not run, and it
+    // was answered the same unhelpful way: "could not be imported", with the reason sitting
+    // unread in the complaints channel. "Whatever it printed instead is under printed" is
+    // directions to go and look, and a person who has to go and look has not been told
+    // anything. Measured 2026-08-31 alongside the three broken products; the reason a module
+    // fails to import is almost always one line — a missing package, a syntax error — and it is
+    // the one line that fixes it.
+    const spoke = result.stderr.trim() === '' ? result.stdout : result.stderr;
+    const headline = whatItSaid(spoke, { mostLines: 1 });
     return [notCovered({
       channel: 'results',
       path: joinPath('export', journey.name, 'readable at all'),
       reason: 'crashed',
-      says: `"${journey.describe}" could not be imported, so nothing is known about what it exports. Whatever it printed instead is under "printed".`,
+      says:
+        `Nothing is known about what "${journey.describe}" exports, because it could not be imported${
+          headline ? `. It said: ${headline}` : ''
+        }. Whatever else it printed is under "printed".`,
+      detail: whatItSaid(spoke),
     })];
   }
   const names = Object.keys(surface).sort();