staysfixed 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -8,6 +8,157 @@ 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
+lanes, each lane required to reproduce its defect on a throwaway product before touching
+anything, and each fix held by a test that fails without it.
+
+**All eight surfaces have now actually been driven against a real product** — command-line
+tools, libraries, servers, websites, Electron, Android, iOS and, last of all, native Windows.
+That sentence was not true before this release. Each of the four that had only ever had an
+adapter and tests turned out to hold at least one defect that only running it could find.
+
+### The three that could have blessed a broken build
+
+- **A refusal was stored as an ordinary value.** When a journey cannot run — the product
+  throws on its first line, a command dies before printing anything — what got written down
+  was a fact about the crash. Two builds that crash the same way agree at every address, and
+  agreement is what this tool reads as "nothing changed". So a product that did nothing at
+  all came back *"Nothing that worked has changed. 7 addresses checked"*, `ship` blessed it,
+  and the day somebody fixed the product, four findings arrived that nobody had caused. A
+  refusal is now a different kind of thing from a value: never compared to one, never
+  compared to another refusal as though both were answers, and refused at `ship` in
+  `shouldCut`, where every caller passes through.
+- **`settle()` assigned the verdict instead of narrowing it**, throwing away every not-a-pass
+  the engine had already decided — a run where the product never answered, and a run drowning
+  in wobble, both came back through that line as a pass. Accounting may take a pass away; it
+  may never hand one back.
+- **A reference cut from a tree with uncommitted changes was booted from its commit.** The
+  record is filed under a fingerprint of the tree that was walked, because the files checked
+  are not the files git has. Paired mode walked the commit and called it the old build, so an
+  address the record holds a real value for was reported as *"is there now and was not
+  before"*.
+
+### It reported things as checked that were never checked
+
+- **A root-level server went unread the moment the project also had a `src/` folder.** A
+  deleted route and a 200 turning into a 500 both came back "Nothing that worked has changed".
+- **`ship` blessed a run in which every journey refused**, and **the command-line surface was
+  hard-coded ready** and never looked at the project.
+- **`init` said a library "can be checked here now" and is "covered in full"** about an
+  `index.js` that does not exist.
+- **`init` asked the machine what it could do before working out the settings**, so on a fresh
+  project every question that is answered by reading the settings was answered against none.
+  A plain Node command-line tool was told it needed "a command to run" by the same run that
+  had just written `node cli.js --help` into its settings.
+
+### It stated things it had never looked for
+
+- **"No Windows desktop is reachable from here"** on a project whose settings named the
+  machine — with that machine reachable, signed in and unlocked the whole time. Nothing had
+  been dialled. Naming a machine in your own settings is the ask; the rest of your ssh config
+  is still left alone, and when nothing was dialled the sentence now says so.
+- **The live panel called every failed guard "broken again"**, with the story of the original
+  bug printed underneath as though it were proof. A guard that ran out of time did not answer
+  the question, and one that asserted nothing never asked it.
+- The HTML report said *"All 3 bugs that were fixed are still fixed"* over three guards that
+  were skipped, and *"Everything that worked still works"* over a run that checked nothing at
+  all.
+
+### Nothing hangs, and nothing waits in silence
+
+- **Every wait in the phone, desktop and Windows adapters now has a limit, and every limit
+  says what it was waiting for.** The cause was never a missing timeout: waits were settled by
+  a child's `close` event, which does not mean the program ended — it means nobody anywhere is
+  still holding its pipes, and one orphaned grandchild refuses that for ever. A verdict
+  printed, and then nothing, for ever. That is what the unexplained Electron deadlock was.
+- **A mistyped limit removed the limit.** `Number("10s")` is `NaN`, and every comparison
+  against `NaN` is false, so a step with a typo in its settings looped without end.
+- **A stock Vite app cost three minutes and told you nothing.** Vite ignores the port and host
+  it is handed and binds the name `localhost`, which on a Mac is the IPv6 loopback — so the
+  site came up on `[::1]` and the check knocked on `127.0.0.1` about 450 times a side. Boot
+  waits now knock on both, and a command that ignores its port, or exits, is named in seconds:
+  three minutes became ten seconds.
+- **A person at a terminal is told what the run is waiting for.** The running commentary
+  reached the live panel and nothing else, so a long wait was a blank screen — which is
+  indistinguishable from the tool being broken.
+- **Reclaiming a scratch folder now stops what is still running inside it.** Four servers from
+  the previous day were still up on this machine, out of folders that had already been deleted.
+
+### The measurement no longer measures itself
+
+- **With nothing edited, a check compared the build against the same build** — and called
+  whatever flickered between two runs minutes apart a change nobody made. On a stock Next.js
+  app with a link between two pages, four runs in five reported a difference, and one claimed
+  the change "made something non-deterministic". Two runs of one build are a wobble
+  measurement, which is this tool's own word for it, and it now says so.
+- **The record of what "working" means moved on its own.** The store keeps every capture a
+  build ever produced and the reader took the newest, so anybody checking out the old commit
+  and running a check quietly replaced the standard. Only `ship` decides what working means.
+- **A request cancelled by our own teardown was reported as the product complaining.** Next.js
+  starts a prefetch behind every internal link; closing the page aborts it, and the browser
+  reports that exactly like a real failure. It is recorded as a hole now — louder than a
+  complaint, never quieter.
+
+### The report no longer disagrees with itself
+
+- **A renamed field was described only as the field that appeared**, never the one that
+  vanished — the half that breaks every caller, on the channel that exists to catch it.
+- **Two byte-identical runs produced different `coverage.gaps`**, and `coverage.doorsWalked`
+  counted doors as walked in the same report whose only line about them said "was not tried".
+- **`ship` said "nothing is being compared against anything yet"** with a reference in force.
+- **`ship` read the product name only out of a JSON settings file** — and every settings file
+  `init` writes is JavaScript. So it blessed under the package name while `check` recorded
+  under the settings name, and the two never met: a project could ship and check for ever
+  without once comparing anything.
+
+### The person and the agent get the same truth
+
+- **Five commands a person did not have:** `coverage`, `explain`, `prove`, `waive` and
+  `intent`. All are commands now, `check` prints the finding ids so there is something to hand
+  them, and a test asserts the two readers get byte-identical facts.
+- **An intent sealed at the command line was recorded as "an agent, over MCP".**
+- **Six places sent a person to something only an agent can call** — a tool name, a JSON
+  field, an `include:` block — and `check --help` still said intent and waive live only on the
+  MCP server.
+- **`staysfixed_waive` refused the only file in the product**, because an agent holds absolute
+  paths and the seal expected relative ones; **`staysfixed_coverage` forced the machine survey
+  offline** and reported the forced answer as a fact about the world.
+
+### What a person is handed when something goes wrong
+
+- An unwritable `TMPDIR` handed over a raw `ENOENT ... mkdtemp`; a check run inside a nested
+  project silently checked the parent's product; `flake` said "No check here has ever changed
+  its mind" about a register whose own JSON showed a guard flipping, and gave an untrue
+  reason; a monorepo container folder was announced as a product.
+
 ## [0.10.0] — 2026-08-31
 
 The night the four surfaces nobody had pointed it at were pointed at it, and the biggest

package/README.md

@@ -166,7 +166,13 @@ pretend otherwise.
 | Steps taken from a recorded session, or rejected at birth for not repeating twice | **Written, not wired.** The code is in `src/v2/journeys/` with tests around it, and nothing on the check path calls it yet. Ask for `--journeys recorded` and you are told so by name. |
 | Android APKs on an emulator | **The adapter is here.** It reads everything the APK declares with nothing installed and no Java, and where there is an emulator it installs one build at a time and walks it. Whether *this* machine can run one is a separate question, and `doctor` asks the adapter itself rather than keeping a second opinion — most of what it wants installs with a command; accepting Google's licence, once, needs a person. Two emulator snapshots restoring byte-identically is unproven, so Android compares against the stored record and says which mode it used. |
 | The iOS simulator | **The adapter is here.** It reads what the app bundle declares with nothing running, and where Xcode and a simulator runtime are present it installs one build at a time, boots it and reads what is on the screen. It is new. Paired running costs two `xcodebuild` passes, so it is for before a release rather than for every edit, and like Android it compares against the stored record and says which mode it used. Ask `doctor` what it is actually covering on your machine before trusting a clean run. |
-| Native Windows GUI (a real Win32 app, not an Electron one) | **The probe is here**, driven over ssh to any machine that reaches a Windows desktop — a WSL shell on one counts, and nothing is installed on it. Windows shows one desktop, so two builds can never run at once: the comparison is genuinely weaker here than anywhere else. |
+| Native Windows GUI (a real Win32 app, not an Electron one) | **Works,** and it has now been driven end to end: a real Win32 window on a Windows 11 desktop reached over ssh, 10 addresses read out of the UI Automation tree, a reference cut, and the next run compared against it. Nothing was installed on that machine — the program that reads the screen is sent down the connection each run. Windows shows one desktop, so two builds can never run at once: the comparison is genuinely weaker here than anywhere else, and a run says so rather than hiding it. |
+
+All eight surfaces — command-line tools, libraries, servers, websites, Electron,
+Android, iOS and native Windows — have now actually been run against a real
+product, rather than only having an adapter and tests. That sentence was not true
+before 2026-08-31, and the four that were unproven each turned out to have at
+least one defect that only running them could find.
 
 `staysfixed check` is the front door for both. Version 1's flags still mean
 exactly what they meant yesterday — `--pictures`, `--guards` and `--only` reach
@@ -357,7 +363,10 @@ everything, because it did not: it checked every way in *this tool knows about*.
 staysfixed check --json            # coverage.doorsKnown, coverage.doorsWalked, coverage.gaps
 ```
 
-Over MCP it is `staysfixed_coverage`. Every `staysfixed_check` reply says it in
+At a terminal it is `staysfixed coverage`; over MCP it is `staysfixed_coverage`.
+Both roads reach the same code — that stopped being true for a while, and a person
+got a strictly worse answer about their own product than an agent did, which is
+now a test. Every `staysfixed_check` reply says it in
 words directly under the headline, and the JSON form carries `notChecked` and
 `doorsNeverOpened` as fields of their own rather than only as prose — a number an
 agent has to go looking for is a number it skips.
@@ -634,9 +643,12 @@ Full wiring for every client: [docs/mcp.md](docs/mcp.md).
 Every version ships knowing, in machine-readable form and in plain English: what
 it can check on this machine right now and what it cannot; what is missing that
 would unlock more, and whether the tool can install it itself or a person has to;
-which other machines it can already reach, **found by dialling them** rather than
-by asking you; and the shape of its own results, so an agent can act on them
-without being taught. That is `staysfixed doctor --json`, and it is
+which other machines your ssh config names, and — for the ones your own settings
+name, plus any you ask about with `--machines` — whether they answer, what they
+run and what they are short of; and the shape of its own results, so an agent can
+act on them without being taught. It does **not** dial your machines unasked: the
+first command a stranger runs must not open connections to their production
+servers, so naming a machine in your settings is what asks about it. That is `staysfixed doctor --json`, and it is
 `staysfixed_capabilities` over MCP.
 
 ---

package/docs/getting-started.md

@@ -297,6 +297,16 @@ Say these once, when someone asks how much it covers. They are permanent, they a
 | `staysfixed check --against <ref>` | Compare against a tag, commit or marker. |
 | `staysfixed check --selfcheck` | Prove the engine still catches deliberate breakage. |
 | `staysfixed ship` | The build that went out is now what "working" means. |
+| `staysfixed coverage` | What the last check did NOT look at. Read it before calling anything safe. |
+| `staysfixed intent "<what you meant to change>"` | Seal what you meant to change, before you check. |
+| `staysfixed explain <id>` | One finding from the last check, in full. |
+| `staysfixed prove <id>` | Undo your own edit and re-measure, to see whether it really caused the finding. |
+| `staysfixed waive <id> --why "<reason>"` | Record that a difference was intended. It is not approval. |
+
+Those last five existed only over MCP until 2026-08-31, which meant a person at a terminal
+got a strictly worse answer about their own product than an agent did. Every one of them is
+now a command as well, and both roads reach the same code. `check` prints the finding ids, so
+there is something to hand them.
 
 If you have to write a settings block by hand — something `init` could not know, a second
 product, a journey through a screen — every option is in

package/docs/how-v2-works.md

@@ -366,8 +366,11 @@ It carries:
   the seven channels are reachable for each
 - what is missing, why it matters, and the exact command that would fix it —
   marked with whether the tool can do it itself or a person has to
-- which other machines it can already reach, **detected by dialling them**, so a
-  working SSH host is never presented as something to go and set up
+- which other machines your ssh config names, and whether the ones it is allowed
+  to dial answer — the ones your own settings name, plus any you ask about with
+  `--machines` — so a working SSH host is never presented as something to go and
+  set up. Nothing is dialled unasked: the first command a stranger runs must not
+  open connections to their production servers
 - the shape of its own results, so an agent can act on them without being taught
 - what it will never be able to see, on any machine
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "staysfixed",
-  "version": "0.10.0",
-  "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 — as a CLI and as an MCP server.",
+  "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",
   "author": "Asad Iqbal",

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';
@@ -31,6 +31,26 @@ export class ExpectationFailed extends Error {
   }
 }
 
+/**
+ * The run has given up on this guard, and the guard is still going.
+ *
+ * Every door in the object a guard is handed throws this once the attempt that opened it has
+ * been abandoned. Measured on 2026-08-31: a guard with `timeoutMs: 200`, ticking every 25
+ * milliseconds, had written 7 lines to a file by the time the run reported it and 26 half a
+ * second later — the timeout is a `Promise.race`, and losing a race does not stop the loser.
+ * It went on clicking, reading and holding a page that the guard after it was already using.
+ *
+ * Nobody prints this. By the time it is thrown the verdict for this guard is already written,
+ * and the point of it is only to unwind a body the run has stopped listening to.
+ */
+export class GuardAbandoned extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'GuardAbandoned';
+  }
+}
+
 const DEFAULT_RUN_TIMEOUT = 60_000;
 
 /** Commands can print a lot; 10MB before we cut them off. */
@@ -57,6 +77,11 @@ const ACTION = 'did';
  * @property {(step: import('../types.js').CheckStep) => void} [onStep]
  *           Called as each claim and each action starts, and again as it settles.
  *           The two calls carry the same `key`.
+ * @property {AbortSignal} [signal]
+ *           Raised when the run has given up on this guard — its clock ran out, or its
+ *           attempt has simply already returned. Every door here refuses from then on, so
+ *           the body stops at its very next step instead of driving the app behind a run
+ *           that has moved on.
  */
 
 /**
@@ -70,8 +95,67 @@ const ACTION = 'did';
 export function makeGuardApi(page, project, opts = {}) {
   const root = project.paths.root;
   const onStep = typeof opts.onStep === 'function' ? opts.onStep : null;
+  const givenUp = opts.signal;
   let counted = 0;
 
+  /**
+   * Refuse to do anything more once the run has given up on this guard.
+   *
+   * This is what makes a timeout mean something. Before it, a guard that ran out of time
+   * kept its whole body running: measured on 2026-08-31, 7 file writes by the time the run
+   * reported it and 26 half a second later, every one of them free to click the page the
+   * next guard had just started on. Refusing at the door is the only stopping there is —
+   * JavaScript cannot take a promise back — but it is enough, because a guard reaches the
+   * app through this object, and it reaches it constantly.
+   *
+   * @returns {void}
+   */
+  function stopHere() {
+    if (!givenUp?.aborted) return;
+    throw refusal();
+  }
+
+  /** @returns {GuardAbandoned} */
+  function refusal() {
+    return new GuardAbandoned(
+      'The run had already given up on this guard and moved on, so this step was refused rather than run.',
+    );
+  }
+
+  /**
+   * The page with one extra rule: once the run has given up on this guard, it refuses.
+   *
+   * `app.page` is documented as "the whole page", so a guard that drives the app itself
+   * never passes through the five methods below — and those were exactly the guards left
+   * holding a page after their own timeout. The wrapper belongs to this attempt and dies
+   * with it; the real handle is untouched, and every other part of the tool keeps using it.
+   *
+   * @param {import('../types.js').PageApi} handle
+   * @returns {import('../types.js').PageApi}
+   */
+  function refusable(handle) {
+    if (!givenUp) return handle;
+    /** @type {Record<string, unknown>} */
+    const doors = {};
+    for (const key of Object.keys(handle)) {
+      const value = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (handle))[key];
+      if (typeof value !== 'function') {
+        doors[key] = value;
+        continue;
+      }
+      // Refused in the same shape the door answers in. `goto` is awaited and `consoleErrors`
+      // is read, and a refusal that arrives as a thrown error where a value was expected —
+      // or as a rejected promise where none was — is a second surprise on top of the first.
+      const answersWithAPromise = value.constructor?.name === 'AsyncFunction';
+      doors[key] = (/** @type {unknown[]} */ ...args) => {
+        if (!givenUp.aborted) return /** @type {(...a: unknown[]) => unknown} */ (value).apply(handle, args);
+        if (answersWithAPromise) return Promise.reject(refusal());
+        throw refusal();
+      };
+    }
+    return /** @type {import('../types.js').PageApi} */ (/** @type {unknown} */ (doors));
+  }
+
   /**
    * Hand one step out, and never let that matter.
    *
@@ -111,7 +195,7 @@ export function makeGuardApi(page, project, opts = {}) {
   }
 
   return {
-    page,
+    page: refusable(page),
     project,
 
     /**
@@ -119,6 +203,7 @@ export function makeGuardApi(page, project, opts = {}) {
      * @returns {Promise<void>}
      */
     async open(to) {
+      stopHere();
       const settle = announce(ACTION, `opened ${short(to)}`);
       try {
         await page.goto(to);
@@ -134,6 +219,7 @@ export function makeGuardApi(page, project, opts = {}) {
      * @returns {Promise<void>}
      */
     async click(selector) {
+      stopHere();
       const settle = announce(ACTION, `clicked ${short(selector)}`);
       try {
         await page.click(selector);
@@ -150,6 +236,7 @@ export function makeGuardApi(page, project, opts = {}) {
      * @returns {Promise<void>}
      */
     async expect(claim, check) {
+      stopHere();
       if (typeof claim !== 'string' || claim.trim() === '') {
         throw new StaysFixedError('An expectation needs a sentence in front of it.', {
           hint: 'Write it the way you would say it: expect("the sidebar is hidden", () => ...). That sentence is what a person reads when the guard fails.',
@@ -202,34 +289,129 @@ export function makeGuardApi(page, project, opts = {}) {
      * @returns {Promise<{code: number, stdout: string, stderr: string}>}
      */
     async run(cmd, runOpts = {}) {
+      // Before the command is started, not after. A guard the run has given up on must not
+      // be able to leave a process of its own behind it.
+      stopHere();
       const cwd = runOpts.cwd ? path.resolve(root, runOpts.cwd) : root;
       const timeoutMs = runOpts.timeoutMs ?? DEFAULT_RUN_TIMEOUT;
       const settle = announce(ACTION, `ran ${short(cmd)}`);
 
       /** @type {Promise<{code: number, stdout: string, stderr: string}>} */
-      const finished = new Promise((resolve) => {
-        exec(
-          cmd,
-          { cwd, timeout: timeoutMs, maxBuffer: MAX_OUTPUT, encoding: 'utf8' },
-          (error, stdout, stderr) => {
-            const out = String(stdout ?? '');
-            let err = String(stderr ?? '');
-            let code = 0;
-
-            if (error) {
-              const e = /** @type {any} */ (error);
-              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 });
-          },
-        );
+      const finished = new Promise((resolve, reject) => {
+        // `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;
@@ -247,6 +429,7 @@ export function makeGuardApi(page, project, opts = {}) {
      * @returns {Promise<string>}
      */
     async read(file) {
+      stopHere();
       const full = path.resolve(root, file);
       const relative = path.relative(root, full);
       // A guard belongs to one project; reading outside it makes the guard depend