staysfixed 0.11.1 → 0.13.0

package/src/v2/adapters/ios.js

@@ -26,6 +26,30 @@
  *   never on screen during a run.
  * - COUNTERS AND PICTURES, coarse and last.
  *
+ * IS A PAIRED RUN POSSIBLE HERE? YES, AND IT HAS NOW BEEN MEASURED.
+ *
+ * A paired run means the old build is put back on this machine and walked minutes before the
+ * new one, so nothing that drifted in between — the weather, a dependency, the clock — can be
+ * mistaken for somebody's change. On a phone that means one device, two builds one after the
+ * other, and the device put back in between. Until 2026-08-31 this was not offered, because
+ * nobody had ever checked whether the device really does come back to the same place.
+ *
+ * It has been checked. On an Apple Silicon Mac, on 2026-08-31, against Terminal Deck's own
+ * iPhone app (0.15.0, build 2608221311) on a simulator this adapter made for itself — an
+ * iPhone 17 Pro on iOS 27.0 — ONE build was walked ten times, with the device put back
+ * between every walk exactly the way it is put back between two builds: the app and
+ * everything it had written removed, and every permission it had been granted taken back.
+ *
+ * Five pairs. 725 addresses in each walk, 215 of them read out of the RUNNING app and the
+ * rest out of the bundle and the source. 725 of 725 agreed, in all five pairs — 3,625
+ * comparisons and not one disagreement. The Mac was carrying a load average of about 500 at
+ * the time, which makes that the harsher version of the result rather than the flattering
+ * one.
+ *
+ * So a paired iOS run is offered. What actually limits it is not the simulator — it is
+ * getting hold of the OLD build's app bundle, because a `.app` is a build output and a
+ * checkout of the old commit does not contain one. See `prepare` and `ios.reference`.
+ *
  * WHAT IT CANNOT SEE, and these are not hedges.
  *
  * - A REAL iPHONE. Nothing here touches a device somebody is holding. A paired run means
@@ -101,6 +125,111 @@ import {
 /** Everything prepared, per build, so `run` can be called many times without re-installing. */
 const ready = new Map();
 
+/**
+ * Which app bundle each half of a comparison was walked from, remembered across the run.
+ *
+ * It lives out here rather than on a prepared build because the engine prepares one build,
+ * walks one journey against it and throws it away before the next: nothing kept on a
+ * prepared build survives long enough to notice that the old build and the new build were
+ * the same folder on disk.
+ *
+ * And that is the thing worth noticing. `ios.app` in the settings is usually an absolute
+ * path — Xcode writes into DerivedData, which is nowhere near the project — and an absolute
+ * path does not move when the old commit is checked out somewhere else. So both halves of a
+ * paired run would read the SAME bundle, find nothing different, and the run would say
+ * "nothing that worked has changed" about a comparison that never took place. That is the
+ * one failure this tool exists to prevent, arriving through the front door. Anything caught
+ * here is reported as a hole on every journey; see `run`.
+ *
+ * Keyed by role — 'candidate' or 'reference' — and emptied by `teardown`.
+ *
+ * @type {Map<string, string>}
+ */
+const walkedFrom = new Map();
+
+/**
+ * The build ids that turned out to be the other half of the comparison, and the sentence
+ * that says so.
+ *
+ * Separate from `ready` above because `ready` only holds builds that reached a simulator,
+ * and the warning has to survive a build that did not: a reference half that failed to
+ * prepare AND was the same bundle as the candidate is two pieces of bad news, and losing the
+ * second one is how a comparison comes back green for the wrong reason.
+ *
+ * @type {Map<string, string>}
+ */
+const sameBundleFor = new Map();
+
+/**
+ * Which bundle this really is: the path with the links and the `..`s taken out.
+ *
+ * A symlink, a `./` or a `..` must not be able to make one bundle look like two, because one
+ * bundle looking like two is the whole failure being guarded against here.
+ *
+ * @param {string} appPath
+ * @returns {Promise<string>}
+ */
+async function bundleIdentity(appPath) {
+  try {
+    return await fsp.realpath(appPath);
+  } catch {
+    // A path that will not resolve is still worth remembering exactly as it was typed. The
+    // question below is whether the two halves agree, not whether the bundle is there.
+    return appPath;
+  }
+}
+
+/**
+ * Did this half of the comparison read the same app bundle as the other half?
+ *
+ * Returns the sentence to put in front of a reader, or null when the two halves really are
+ * two different bundles.
+ *
+ * WHAT IT DOES NOT CATCH, said here rather than left to be discovered: two different paths
+ * holding the same build. Somebody whose release script copies today's build to
+ * `builds/latest/App.app` and points `reference` at it is comparing one build against itself
+ * with two names, and nothing here notices. That was left alone on purpose — two different
+ * bundles are usually two builds somebody produced on purpose, and refusing them on a guess
+ * would block real comparisons to prevent an unusual one.
+ *
+ * @param {'reference'|'candidate'} role
+ * @param {string} mine
+ * @returns {string|null}
+ */
+function sameBundleAsTheOtherHalf(role, mine) {
+  // Only ever asked about the OLD build's half, and that is not squeamishness — it is the
+  // only answer that stays the same from one journey to the next. The engine prepares a
+  // build, walks ONE journey against it and throws it away, and it always does the new build
+  // first: new-run-a, new-run-b, old-run-a, old-run-b, then the same four again for the next
+  // journey. So from the second journey onwards the new build's half would find the previous
+  // journey's old half sitting in the map and flag itself as well — the warning would be
+  // absent on the first journey and doubled on every one after it, which reads like a bug in
+  // the tool rather than a fact about the run.
+  if (role !== 'reference') return null;
+  const other = walkedFrom.get('candidate');
+  if (!other || other !== mine) return null;
+  return `Both halves of this comparison were walked from the same app bundle: ${mine}. Nothing in it is older or newer than anything else in it, so no difference between the two builds could possibly show up.`;
+}
+
+/**
+ * Where a kept copy of the OLD build's app bundle lives, if the settings name one.
+ *
+ * Two spellings, because both read naturally and neither is worth an argument:
+ * `{"reference": "builds/0.14.0/YourApp.app"}` and
+ * `{"reference": {"app": "builds/0.14.0/YourApp.app"}}`. A relative path is resolved against
+ * whatever `findAppBundle` is given, which for the reference half is the checkout of the old
+ * commit — so a project that DOES commit a simulator build can leave this out entirely.
+ *
+ * @param {Record<string, any>} config
+ * @returns {string|undefined}
+ */
+export function referenceBundle(config) {
+  const said = config?.reference;
+  if (typeof said === 'string' && said.trim() !== '') return said;
+  if (said && typeof said === 'object' && typeof said.app === 'string' && said.app.trim() !== '') return said.app;
+  return undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Reading the doors out of the source
 // ---------------------------------------------------------------------------
@@ -542,6 +671,13 @@ export const iosAdapter = defineAdapter({
     /** @type {string[]} */
     const notes = [];
 
+    // What was MEASURED goes on before the machine is asked, so it survives every early
+    // return below. These notes are what `doctor` prints and what an agent reads, and on a
+    // machine that is not a Mac they were dropped entirely — so somebody planning where to
+    // run their checks was told only "not here", never what a Mac would actually do or what
+    // it would need from them. A fact that exists only in a comment is a fact nobody sees.
+    notes.push('Putting the device back really does put it back, and that is measured rather than assumed. On 2026-08-31 one build was walked ten times on an iOS 27.0 simulator with the app removed and every permission taken back between walks: 725 of 725 addresses agreed in all five pairs — 3,625 comparisons, no disagreements. So a paired run is offered here. What it needs from you is a copy of the OLD build\'s app bundle, because a .app is a build output and a checkout of the old commit does not contain one: name it with {"reference": "path/to/TheOld.app"} under "ios" in the settings.');
+
     const machine = await readMachine();
     if (!machine.isMac) {
       return {
@@ -667,23 +803,61 @@ export const iosAdapter = defineAdapter({
     const scratch = path.join(ctx.scratchDir, `ios-${build.id.slice(0, 12).replace(/[^A-Za-z0-9_-]/g, '-')}`);
     await fsp.mkdir(scratch, { recursive: true });
 
+    // Worked out a few lines below, and captured here so that even a build which could not
+    // be got ready still says it. A reference half that failed AND was the same bundle as the
+    // candidate is two separate pieces of bad news, and the second one is the one that would
+    // otherwise be lost — the run would report "could not be prepared", somebody would fix
+    // that, and the comparison would come back green for the wrong reason.
+    /** @type {string|null} */
+    let sameBundle = null;
+
     /** @param {string} why */
     const notReady = (why) => ({
       build,
       root: scratch,
       ready: false,
-      why,
+      why: sameBundle ? `${why} ${sameBundle}` : why,
+      ...(build.role === 'reference' ? { facts: { paired: sameBundle === null } } : {}),
       dispose: async () => {
+        sameBundleFor.delete(build.id);
         await fsp.rm(scratch, { recursive: true, force: true });
       },
     });
 
+    // WHICH bundle this half of the comparison walks.
+    //
+    // For the build you have, that is whatever the settings point at. For the build you were
+    // happy with it is different, and the difference is the whole of paired mode on a phone:
+    // the engine hands over a checkout of the old commit, and a `.app` is a BUILD OUTPUT that
+    // nobody commits, so a checkout of the old commit contains no app at all. `ios.reference`
+    // is where a kept copy of the old build's bundle goes, and it is looked at first for the
+    // reference half and never for the candidate.
+    const forThisHalf = build.role === 'reference' ? { ...config, app: referenceBundle(config) ?? config.app } : config;
+    const found = await findAppBundle(build.root, forThisHalf);
+    if (!found.ok) {
+      return notReady(
+        found.why +
+        (build.role === 'reference'
+          ? ' A paired run walks the OLD build here, and a .app is a build output that a repository does not commit — so a checkout of the old commit has no app in it. Keep a copy of each release\'s simulator build and point at it with {"reference": "path/to/TheOld.app"} under "ios" in the settings, and this becomes a real comparison. Without it this journey falls back to the record the old build left the last time it ran, which is weaker and says so.'
+          : ''),
+      );
+    }
+
+    // Two halves, one bundle. Worked out here, said on every journey — see `run`.
+    const mine = await bundleIdentity(found.appPath);
+    sameBundle = sameBundleAsTheOtherHalf(/** @type {'reference'|'candidate'} */ (build.role), mine);
+    walkedFrom.set(build.role, mine);
+    if (sameBundle) sameBundleFor.set(build.id, sameBundle);
+
+    // The machine is asked AFTER all of that, and the order is the point. Working out which
+    // bundle each half walks needs nothing but the filesystem, and it is true on every
+    // machine. Asking the machine first meant that anywhere an iPhone app cannot run — any
+    // Linux box, any Windows box, a Mac without Xcode — the reference half returned before
+    // the check and reported `paired: true`, which is a claim about a comparison it had not
+    // made. Caught by CI on Linux against a green Mac suite, 2026-08-31.
     const machine = await readMachine({ signal: ctx.signal });
     if (!machine.ok) return notReady(machine.why);
 
-    const found = await findAppBundle(build.root, config);
-    if (!found.ok) return notReady(found.why);
-
     const facts = await readAppBundle(found.appPath);
     if (!facts.ok) return notReady(facts.why);
 
@@ -720,7 +894,7 @@ export const iosAdapter = defineAdapter({
       build,
       root: scratch,
       ready: true,
-      why: `${facts.name} ${facts.version} (${facts.build}) is on the simulator called ${device.device.name}, running ${device.device.runtimeName}. ${device.why} ${probe.ok ? 'The screen can be read by meaning.' : `The screen CANNOT be read by meaning: ${probe.why} Only pictures, logs, crashes and the files it writes are being checked, which is much less than it sounds.`}`,
+      why: `${facts.name} ${facts.version} (${facts.build}) is on the simulator called ${device.device.name}, running ${device.device.runtimeName}. ${device.why} ${probe.ok ? 'The screen can be read by meaning.' : `The screen CANNOT be read by meaning: ${probe.why} Only pictures, logs, crashes and the files it writes are being checked, which is much less than it sounds.`}${sameBundle ? ` ${sameBundle}` : ''}`,
       facts: {
         device: device.device.name,
         udid: device.device.udid,
@@ -729,10 +903,15 @@ export const iosAdapter = defineAdapter({
         version: facts.version,
         readsMeaning: probe.ok,
         weBootedIt: device.device.weBootedIt,
+        app: found.appPath,
+        // Only ever set on the OLD build's half, because that is the half the question is
+        // about: was there really a second build here, or did both halves read one bundle.
+        ...(build.role === 'reference' ? { paired: sameBundle === null } : {}),
       },
       dispose: async () => {
         const kept = ready.get(build.id);
         ready.delete(build.id);
+        sameBundleFor.delete(build.id);
         if (kept?.device) await releaseDevice(kept.device, { signal: ctx.signal });
         await fsp.rm(scratch, { recursive: true, force: true });
       },
@@ -748,28 +927,53 @@ export const iosAdapter = defineAdapter({
    * @returns {Promise<Observation[]>}
    */
   async run(journey, build, ctx) {
+    // FIRST, IN FRONT OF EVERY OTHER ANSWER THIS FUNCTION CAN GIVE.
+    //
+    // Said on every journey rather than once at the start, which is the same rule the web
+    // adapter follows for an app read at a fixed address. A run that compared one bundle
+    // against itself finds no differences, and "no differences" is the sentence this whole
+    // tool is believed for.
+    //
+    // It has to come before the "was this build ever got ready" answer below and not after
+    // it, because a reference half can fail to prepare AND have been the same bundle as the
+    // candidate. Say only the first and somebody fixes the preparation, runs it again, and
+    // gets a clean comparison of one bundle against itself with nothing anywhere to say so.
+    const sameBundle = sameBundleFor.get(build.build.id);
+    /** @type {Observation[]} */
+    const sameBundleSaid = sameBundle
+      ? [notCovered({
+          channel: 'meaning',
+          path: joinPath('screen', journey.name, 'which build this was'),
+          reason: 'not supported here',
+          says:
+            `${sameBundle} A .app is a build output, so a checkout of the old commit does not contain one and the settings' own path was used for both halves. ` +
+            'Keep a copy of the simulator build you shipped and name it with {"reference": "path/to/TheOld.app"} under "ios" in the settings, and this becomes a real comparison.',
+        })]
+      : [];
+
     const kept = ready.get(build.build.id);
     if (!kept) {
-      return [notCovered({
+      return [...sameBundleSaid, notCovered({
         channel: 'meaning',
         path: joinPath('screen', journey.name, 'walked'),
         reason: 'not supported here',
-        says: 'This build was never got ready, so nothing about it could be walked.',
+        says: `This build was never got ready, so nothing about it could be walked. ${build.why}`,
       })];
     }
     if (journey.skip) {
-      return [notCovered({
+      return [...sameBundleSaid, notCovered({
         channel: 'meaning',
         path: joinPath('screen', journey.name, 'walked'),
         reason: 'missing tool',
         says: journey.skip,
       })];
     }
+
     if (journey.name === 'what-the-app-declares') {
-      return declaredObservations(kept.facts, kept.doors, journey.name, kept.limits ?? []);
+      return [...sameBundleSaid, ...declaredObservations(kept.facts, kept.doors, journey.name, kept.limits ?? [])];
     }
 
-    return walkObservations(journey, kept, ctx);
+    return [...sameBundleSaid, ...(await walkObservations(journey, kept, ctx))];
   },
 
   async teardown() {
@@ -777,6 +981,12 @@ export const iosAdapter = defineAdapter({
       if (kept?.device) await releaseDevice(kept.device);
       ready.delete(id);
     }
+    // One run's memory of which bundle each half was walked from. It must not survive into
+    // the next run in the same process — the MCP server and the watch panel both call
+    // check() more than once — or a second run would report the first run's bundles as its
+    // own.
+    walkedFrom.clear();
+    sameBundleFor.clear();
   },
 });
 

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,
     },