staysfixed 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -8,6 +8,32 @@ numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Nothing yet.
 
+## [0.11.1] — 2026-08-31
+
+Two defects that a Mac could never have shown, both caught by CI on Linux minutes after
+0.11.0 went out. Both were verified as broken and then as fixed on a real Linux machine
+rather than by reading the code.
+
+- **A command a guard had been abandoned mid-flight kept running.** Killing the shell is not
+  killing what the shell started: a command runs through a shell, so the signal reaches the
+  shell and the program it started carries on with a new parent. On macOS the shell usually
+  takes its child with it and this was invisible; on Linux it does not, and a command the run
+  had given up on finished its work 800 milliseconds later and wrote its file. It now runs in
+  its own process group and the group is what gets signalled. (`exec` does not document
+  `detached`; `spawn` does, so this moved to `spawn` rather than resting on behaviour that
+  happens to work.)
+- **The ordinary way of closing a browser left its throwaway profile behind.** One `rm` is a
+  snapshot, and a browser is not one process: the parent exiting says nothing about its
+  renderers, which are still writing into the profile while they are reaped. The last-resort
+  path had learned this; the polite path — the one every ordinary run uses — swallowed the
+  failure with a bare catch. It passes on macOS and on an idle Linux box and fails on a loaded
+  one, which is exactly how a race behaves.
+- **`doctor` asked the machine before it asked the project.** For iPhone and Windows apps the
+  platform test came first, so on Linux a project containing no iPhone app was told its
+  non-existent app could not be reached from this machine — a machine reason given for a
+  project fact, which is the exact conflation that sends somebody to install thirty gigabytes
+  of Xcode for nothing. The project is asked first now, on every surface and every platform.
+
 ## [0.11.0] — 2026-08-31
 
 Fifty-odd defects, found by running the thing rather than reading it. Two rounds of seven

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers \u2014 as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",

package/src/guard/api.js

@@ -15,7 +15,7 @@
  * off IS the guard's own words, in the guard's own order.
  */
 
-import { exec } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { StaysFixedError } from '../core/errors.js';
@@ -298,41 +298,120 @@ export function makeGuardApi(page, project, opts = {}) {
 
       /** @type {Promise<{code: number, stdout: string, stderr: string}>} */
       const finished = new Promise((resolve, reject) => {
-        exec(
-          cmd,
-          // `signal` is what actually kills the child. A guard that shells out to something
-          // long-running was the clearest case of a timed-out guard holding a real resource:
-          // the run had reported and moved on, and the command was still going.
-          { cwd, timeout: timeoutMs, maxBuffer: MAX_OUTPUT, encoding: 'utf8', signal: givenUp },
-          (error, stdout, stderr) => {
-            const out = String(stdout ?? '');
-            let err = String(stderr ?? '');
-            let code = 0;
-
-            if (error) {
-              const e = /** @type {any} */ (error);
-              // Stopped because the run gave up on this guard, not because the command ran
-              // long. Saying "stopped after 60 seconds" here would be a made-up reason.
-              if (givenUp?.aborted && (e.name === 'AbortError' || e.killed)) {
-                reject(
-                  new GuardAbandoned(
-                    'The run gave up on this guard while this command was still going, so the command was stopped.',
-                  ),
-                );
-                return;
-              }
-              if (e.killed || e.signal) {
-                // 124 is what `timeout(1)` uses, so a guard can spot it.
-                code = 124;
-                err += `\n(the command was stopped after ${humanTime(timeoutMs)})`;
-              } else {
-                code = typeof e.code === 'number' ? e.code : 1;
-              }
-            }
-
-            resolve({ code, stdout: out, stderr: err });
-          },
-        );
+        // `spawn` with `shell: true` rather than `exec`, for one reason: `detached`.
+        //
+        // KILLING THE SHELL IS NOT KILLING WHAT THE SHELL STARTED. A command runs through a
+        // shell, so a signal reaches the shell and the program it started carries on with a
+        // new parent. On a Mac the shell usually takes its child with it and this was
+        // invisible; on Linux it does not, and a command the run had given up on finished its
+        // work 800ms later, wrote its file, and proved it — caught by CI on 2026-08-31
+        // against a green Mac suite. `detached` puts the shell and everything it starts in
+        // one process group, and the group is what gets signalled.
+        //
+        // `exec` cannot do this: `detached` is not one of its documented options. It happens
+        // to be passed through today, and a tool built on not lying should not rest on that.
+        const child = spawn(cmd, {
+          cwd,
+          shell: true,
+          detached: process.platform !== 'win32',
+          windowsHide: true,
+        });
+
+        let out = '';
+        let err = '';
+        let tooMuch = false;
+        /** @type {'ran'|'gave up'|'ran out of time'} */
+        let how = 'ran';
+        let done = false;
+
+        /** Stop the shell AND everything it started. */
+        const stopEverything = () => {
+          if (!child.pid) return;
+          try {
+            if (process.platform === 'win32') child.kill('SIGKILL');
+            else process.kill(-child.pid, 'SIGKILL');
+          } catch {
+            // Already gone, which is the good case.
+          }
+        };
+
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (/** @type {string} */ chunk) => {
+          if (out.length + chunk.length > MAX_OUTPUT) {
+            tooMuch = true;
+            out = (out + chunk).slice(0, MAX_OUTPUT);
+            stopEverything();
+            return;
+          }
+          out += chunk;
+        });
+        child.stderr?.on('data', (/** @type {string} */ chunk) => {
+          if (err.length + chunk.length > MAX_OUTPUT) {
+            tooMuch = true;
+            err = (err + chunk).slice(0, MAX_OUTPUT);
+            stopEverything();
+            return;
+          }
+          err += chunk;
+        });
+
+        const ranOut = setTimeout(() => {
+          how = 'ran out of time';
+          stopEverything();
+        }, timeoutMs);
+        if (typeof ranOut.unref === 'function') ranOut.unref();
+
+        const gaveUp = () => {
+          how = 'gave up';
+          stopEverything();
+        };
+        givenUp?.addEventListener('abort', gaveUp, { once: true });
+        if (givenUp?.aborted) gaveUp();
+
+        /** @param {number} code */
+        const finish = (code) => {
+          if (done) return;
+          done = true;
+          clearTimeout(ranOut);
+          givenUp?.removeEventListener('abort', gaveUp);
+
+          // Stopped because the run gave up on this guard, not because the command ran long.
+          // Saying "stopped after 60 seconds" here would be a made-up reason.
+          if (how === 'gave up') {
+            reject(
+              new GuardAbandoned(
+                'The run gave up on this guard while this command was still going, so the command was stopped.',
+              ),
+            );
+            return;
+          }
+          if (how === 'ran out of time') {
+            // 124 is what `timeout(1)` uses, so a guard can spot it.
+            resolve({ code: 124, stdout: out, stderr: `${err}\n(the command was stopped after ${humanTime(timeoutMs)})` });
+            return;
+          }
+          if (tooMuch) {
+            resolve({ code: 124, stdout: out, stderr: `${err}\n(the command was stopped after printing more than this tool will keep)` });
+            return;
+          }
+          resolve({ code, stdout: out, stderr: err });
+        };
+
+        child.on('error', (/** @type {any} */ e) => {
+          if (done) return;
+          done = true;
+          clearTimeout(ranOut);
+          givenUp?.removeEventListener('abort', gaveUp);
+          if (how === 'gave up') {
+            reject(new GuardAbandoned('The run gave up on this guard while this command was still going, so the command was stopped.'));
+            return;
+          }
+          resolve({ code: 1, stdout: out, stderr: `${err}\n${String(e?.message ?? e)}` });
+        });
+        // `close`, not `exit`: exit fires when the shell ends, and everything it printed has
+        // to have been read before the answer is handed back.
+        child.on('close', (/** @type {number|null} */ code) => finish(typeof code === 'number' ? code : 1));
       });
 
       const outcome = await finished;

package/src/v2/browsers.js

@@ -532,6 +532,37 @@ function installGuards() {
   }
 }
 
+/**
+ * Take the throwaway profile away, and keep taking it away until it stays gone.
+ *
+ * One `rm` is a snapshot. A browser is not one process: the parent exiting says nothing about
+ * its renderers, and while they are being reaped they are still writing into the profile — so
+ * the sweep starts, a file appears behind it, the folder is not empty, and the profile
+ * outlives the run. That is the one thing "nothing it opened outlives the run" promises.
+ *
+ * The last-resort path (`killNow`) learned this and this one did not, so the polite close —
+ * which is the one every ordinary run uses — swallowed the failure with a bare `.catch()` and
+ * left the folder behind. It passed on macOS and on an idle Linux box, and failed on a loaded
+ * CI runner, which is exactly how a race behaves. Measured 2026-08-31.
+ *
+ * @param {string} home
+ * @returns {Promise<void>}
+ */
+async function removeStubbornly(home) {
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    try {
+      await fsp.rm(home, { recursive: true, force: true });
+      if (!fs.existsSync(home)) return;
+    } catch {
+      // A file recreated a millisecond after the sweep began. Wait for whoever wrote it to
+      // finish dying, and go round again.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
+  }
+  // Still there. Untidy rather than harmful, and exactly what `staysfixed browsers --clean`
+  // is for — but never reported as success.
+}
+
 /**
  * The last-resort cleanup: no promises, no awaiting, no politeness.
  * @param {number|null} pid
@@ -900,7 +931,7 @@ export async function openBrowser(opts = {}) {
     closing ??= (async () => {
       live.delete(id);
       await stopProcess(child, GRACE_MS);
-      await fsp.rm(home, { recursive: true, force: true }).catch(() => {});
+      await removeStubbornly(home);
     })();
     return closing;
   };

package/src/v2/doctor.js

@@ -898,9 +898,15 @@ function findDesktopApp(cwd) {
  * install thirty gigabytes of Xcode is asking for work that changes nothing, and the whole
  * design turns on never doing that.
  *
+ * Windows is answered here too, for the same reason and by the same rule: a repository with
+ * no Windows program in it does not need a Windows machine, and saying "no Windows desktop
+ * can be reached from here" about one sends somebody looking for a machine they will never
+ * use. Only the settings can answer it — a native Windows build is not something this file
+ * can go and find in a folder.
+ *
  * @param {string} root
  * @param {string|null} settingsText
- * @returns {Promise<{android: FoundApp|null, ios: FoundApp|null}>}
+ * @returns {Promise<{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null}>}
  */
 async function phoneApps(root, settingsText) {
   // Comments taken away first, for the same reason `findDesktopApp` does it: a
@@ -977,7 +983,9 @@ async function phoneApps(root, settingsText) {
         ? { where: root, how: 'there is an Xcode project here, but nothing says where the built app is' }
         : null);
 
-  return { android, ios };
+  const windows = named('remoteExe') ?? namedPath('exe', (v) => /\.exe$/i.test(v));
+
+  return { android, ios, windows };
 }
 
 /**
@@ -1671,7 +1679,7 @@ async function findReference(root) {
  * @param {import('./browsers.js').BrowserSurvey} browsers
  * @param {{where: string, how: string}|null} desktopApp
  * @param {DriverReport[]} drivers      What this copy of the tool can drive at all.
- * @param {{android: FoundApp|null, ios: FoundApp|null}} phones
+ * @param {{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null}} phones
  * @param {Map<string, Need[]>} asked   What each separate adapter says IT is missing.
  * @param {{commands: number, imports: number}} [wires]
  *   What this project's own settings wire for the command-line surface. A surface with
@@ -1884,7 +1892,20 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
   const iosBlocked = iosWants.some(blocks);
   const iosReady = iosMachine && canDrive('ios') && phones.ios !== null && iosWants.length === 0;
   const iosPartly = iosMachine && canDrive('ios') && phones.ios !== null && !iosReady && !iosBlocked;
-  if (!onAMac) {
+  // THE PROJECT IS ASKED BEFORE THE MACHINE, and the order is the whole point. "There is no
+  // iPhone app in this repository" and "this machine cannot run one" are different sentences
+  // with different things to do about them, and a machine reason given for a project that has
+  // no iPhone app in it sends somebody to install thirty gigabytes of Xcode for nothing. On a
+  // Mac this was already right; on Linux the platform test came first, so every project on
+  // every Linux machine was told its non-existent iPhone app was out of reach. Caught by CI
+  // on 2026-08-31 — the Mac suite was green and said nothing about it.
+  if (phones.ios === null) {
+    notInThisProject.add('ios');
+    impossible.set(
+      'ios',
+      'This project has no iPhone app in it, so there is nothing for a simulator to run. If yours is built somewhere else, name the built .app in your settings under ios.app.'
+    );
+  } else if (!onAMac) {
     impossible.set('ios', 'An iPhone build can only be run on a Mac. Everything else on this list is unaffected — check the iPhone app from a Mac, and let this machine cover the rest.');
   } else if (phones.ios === null) {
     notInThisProject.add('ios');
@@ -1902,10 +1923,10 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
     id: 'ios',
     name: 'iPhone apps, on the simulator',
     status: iosReady ? 'ready' : iosPartly ? 'partial' : 'unavailable',
-    summary: !onAMac
-      ? 'Cannot run here: iOS needs a Mac.'
-      : phones.ios === null
-        ? 'Nothing to check: no iPhone app was found in this project, and the settings do not name one.'
+    summary: phones.ios === null
+      ? 'Nothing to check: no iPhone app was found in this project, and the settings do not name one.'
+      : !onAMac
+        ? 'Cannot run here: iOS needs a Mac.'
         : !canDrive('ios')
           ? `An iPhone app is here (${phones.ios.how}), and this copy of Stays Fixed cannot drive one. ${noDriver('ios')}`
           : !iosMachine
@@ -1949,6 +1970,20 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
   // is "detect rather than ask" at its sharpest: a runner that already answers must never
   // be presented as something to go and set up.
   const windowsDriver = canDrive('windows');
+  // Same rule as iPhone and Android: the project is asked before the machine. A repository
+  // with no native Windows program in it does not need a Windows machine, and "no Windows
+  // desktop is reachable from here" about one is a machine reason given for a project fact.
+  // Caught by CI on 2026-08-31, where a Linux runner reported native Windows apps as out of
+  // reach for a project that contains none.
+  if (phones.windows === null) {
+    notInThisProject.add('windows');
+    impossible.set(
+      'windows',
+      'This project has no native Windows program named in its settings, so there is nothing to open on a Windows desktop. '
+      + 'If yours is built somewhere else, name it under windows.remoteExe (already on that machine) or windows.exe (copied over each run). '
+      + 'Most Windows products are Electron, and those are covered over their debug port from any machine.'
+    );
+  }
   // A Windows desktop nobody has signed into is not a runner. There is nothing on it to read
   // — no windows, no controls — so calling it "partly covered" would be the exact over-claim
   // this file exists to prevent. The question can only be asked when the runner started
@@ -1959,7 +1994,9 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
     id: 'windows',
     name: 'native Windows apps',
     status: windowsUsable ? 'partial' : 'unavailable',
-    summary: !windowsHost
+    summary: phones.windows === null
+      ? 'Nothing to check: this project names no native Windows program in its settings. Most Windows products are Electron, and those are covered over their debug port from any machine.'
+      : !windowsHost
       ? nobodyWasDialled
         // Not "no Windows desktop is reachable" — nothing was dialled, so that is not known.
         // The two were the same sentence until 2026-08-31, and it stated as a fact about the

package/src/v2/init.js

@@ -1893,7 +1893,15 @@ export async function run(ctx) {
   const others = (result.plan?.readiness ?? [])
     .map((/** @type {any} */ r) => String(r.product ?? ''))
     .filter((/** @type {string} */ n, /** @type {number} */ i, /** @type {string[]} */ all) => n !== '' && all.indexOf(n) === i);
-  if (result.written.length > 0) ok(`Written: ${result.written.map((f) => shortPath(f)).join(', ')}`);
+  if (result.written.length > 0) {
+    ok(`Written: ${result.written.map((f) => shortPath(f)).join(', ')}`);
+    // Worth one line, because of what happens if it is not done. These files are part of the
+    // build now: until they are committed the working tree is not what git has, so the first
+    // reference gets cut from a tree that has no commit of its own — and a later check cannot
+    // put that build back on the machine to walk it live. It falls back to the stored record,
+    // says so, and is weaker for it. One `git add` avoids the whole thing.
+    say('Commit them before you ship. Settings that are not committed leave the first reference tied to a build git does not have, and a later check can then only compare against the record rather than running the old build live.');
+  }
   if (others.length > 1) {
     warn(
       `Those settings describe ONE product. ${others.length} were found here (${others.join(', ')}), and the others are not covered by this file. ` +