staysfixed 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -8,6 +8,93 @@ numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Nothing yet.
 
+## [0.9.0] — 2026-08-30
+
+Found the same way as 0.8.0 and one better: the published build was installed as a stranger
+installs it and used on real throwaway products — a café API, a static site, a library, a
+server that spawns its own child — until it said something untrue. And this time the repo's
+own CI was read, which had been **red for ten releases** while every summary said the tests
+passed. It was red for two real reasons, both below.
+
+**The tool was breaking the products it was sent to protect**, and on some shapes it never
+came back at all. Those two are why this release exists.
+
+### Fixed — it broke the product, or itself
+
+- **Refusing a connection killed the program that made it.** The refusal was delivered by
+  emitting `'error'` on the socket; at that instant nothing is listening, and in Node an
+  `'error'` with no listener is a thrown exception. `http.get` on Node 22 — the floor this
+  package declares — and a bare `net.connect` on every version died with exit 1, and the run
+  then reported the user's product as broken. The refusal is real now rather than simulated,
+  so the operating system produces it through Node's own plumbing.
+- **`check` printed its whole answer and never exited.** A start command runs through a
+  shell, so the server is a grandchild; killing the shell left it alive holding the output
+  pipe, so the event loop never emptied. It also orphaned the server. The shell is started as
+  its own process group now and the whole group is signalled.
+- **Two agents shipping at once lost what "working" means.** Six ships, all reporting
+  success, four records, and the "already the reference" path never firing. The whole cut is
+  one at a time per product now.
+- **Every killed run left a whole copy of the project in the temporary folder, for ever** —
+  777 MB of them on an ordinary machine. Abandoned copies are reclaimed; a copy a live run
+  owns is never touched.
+
+### Fixed — it said things that were not true
+
+- **The agent was told "everything that worked before still works"** about a run that
+  compared nothing at all, while the terminal correctly called it no answer. The engine's
+  verdict is the floor for the machine surface now, so this class cannot come back one reason
+  at a time.
+- **A sealed money change reached the agent labelled `"ordinary"`** — the human text said
+  sealed, `waive` refused it, and the JSON said it was waivable.
+- **The seal that exists because somebody was burned before could never fire.** Guard names
+  were never passed to the decision, so that class was empty on every run this tool has ever
+  done. And a check on a project with a guard in `.staysfixed/guards` printed the word
+  "guard" zero times: not run, not counted, not mentioned.
+- **A guard that asks nothing was reported as holding.** An empty `run()` came back as
+  "still holds", and would have said so every day for ever.
+- **The library journey never imported anything.** `init` writes `module: "index.js"`; the
+  probe treated that as a package name, failed identically on both builds, and the check said
+  "Nothing that worked has changed" for ever.
+- **`ship` blessed a build nothing had looked at.** It matched by git commit, so an
+  uncommitted edit resolved to an earlier build that had been checked and was clean.
+- **`doctor` said a check "here" covers things in a folder where a check cannot run at all.**
+- **`--only` printed "everything that worked still works"** about a slice.
+- **`init` and `doctor` both offered `check --paired` as the way to record a reference.** It
+  cannot; only shipping cuts one, on purpose. `doctor` also marked it as something the agent
+  could do — the single thing an agent must never do.
+- **`status` said nothing had happened** one command after a check and a ship.
+- **It called the person's own browser "a separate application from the browser you use"**,
+  which is the one case where that sentence matters and the one case it was false.
+
+### Fixed — it could not see, or would not run
+
+- **Full Chrome was invisible on Linux and Windows.** Playwright and Puppeteer both unpack
+  into `chrome-linux64` and `chrome-win64`; only macOS uses the names this looked for. On
+  Linux, the very command this tool tells people to run left a browser it could not find.
+- **`status`, `walk`, `flake`, `approve`, `mark` and `trace` told a website it had no
+  screen** — they only knew version 1's `app:`, and `init` writes version 2's `web:`.
+- **The sign-in example `init` writes used two words the tool does not know**, and a step made
+  only of unknown words was skipped in silence — so the form was never filled, every page
+  behind the login photographed the login page, and the run came back clean.
+- **A browser's throwaway profile outlived an interrupted run.**
+
+### Fixed — it was noisy or unhelpful
+
+- **Renaming one heading came back as five findings**, none of them saying "renamed". A thing
+  addressed by its own words is now recognised when it is renamed, and its children travel
+  with it.
+- **`doctor` connected to every machine in your ssh config, unasked, on the first run.** Nine
+  connections on a brand-new scratch project. It is asked for now, and the machines are still
+  listed either way.
+- **Every command-line check wrote two rows** to the log `ship` reads.
+- **The `.gitignore` lines `init` writes matched nothing version 2 writes** — 151 untracked
+  files and 1.9 MB of run evidence in `git status` after nine checks.
+- `check --json` now carries `notChecked` and `doorsNeverOpened`, which the README had
+  promised and only the MCP reply had.
+- `init` no longer names `staysfixed check --product <name>`, which is not an option.
+- The docs said the self-check builds seventeen products; it builds twenty.
+- `process.alsoWatch` is documented.
+
 ## [0.8.0] — 2026-08-30
 
 The night this was pointed at itself. Everything below was found the same way:

package/README.md

@@ -808,7 +808,7 @@ A tool that reports "nothing changed" looks exactly like a tool that is broken,
 and there is no way to tell the two apart from the outside. So:
 
 **It has to prove it still catches things.** `staysfixed check --selfcheck`
-builds seventeen tiny products — each a real repository with a working commit and
+builds twenty tiny products — each a real repository with a working commit and
 an uncommitted change on top, which is the shape an agent actually points this
 tool at — and requires the engine to behave on every one.
 
@@ -843,7 +843,7 @@ a false accusation people learn to ignore. Measured on 2026-08-30: eleven of
 eleven, three times running, with the project's own suite running in parallel and
 the machine's load average between 227 and 334; then twelve of twelve after the
 second sweep of silences, three times running, with the suite in parallel again
-and the load average between 208 and 343; and finally **seventeen of seventeen**,
+and the load average between 208 and 343; and finally **twenty of twenty**,
 with the suite in parallel, at the end of the same day.
 
 **The unstable app.** `fixtures/unstable-app` is a page built to be impossible to

package/docs/getting-started.md

@@ -229,7 +229,7 @@ watch it notice. There is a built-in version of the same idea:
 staysfixed check --selfcheck
 ```
 
-which builds seventeen deliberately broken products and proves the engine still behaves on
+which builds twenty deliberately broken products and proves the engine still behaves on
 every one — twelve breaks it must catch, four clean pairs it must stay silent about, and one
 product so unsteady that the only correct answer is that the run says nothing at all. A case that
 misbehaves is built again and run again before that counts: fail twice and it is a real

package/docs/settings.md

@@ -61,6 +61,21 @@ twice, and subtracted. And there is nothing to approve: the build you say
 
 ---
 
+
+### `process.alsoWatch`
+
+A list of extra folders a command is allowed to touch, so that what it writes there is
+watched rather than counted as a surprise. The tool's own run output names this option, and
+until 2026-08-30 it appeared nowhere here — in a page whose promise is every option, per kind
+of product.
+
+```js
+process: {
+  commands: [{ name: 'build', run: 'npm run build' }],
+  alsoWatch: ['dist', '../shared/generated'],
+}
+```
+
 ## `product`
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.8.0",
+  "version": "0.9.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.",
   "type": "module",
   "license": "MIT",

package/src/cli/status.js

@@ -2,11 +2,55 @@
  * `staysfixed status` — reads what is on disk and says it. Launches nothing.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
+
 import { loadProject } from '../core/config.js';
 import { projectStatus } from '../run.js';
 import { printStatus } from '../report/console.js';
 import { EXIT } from '../core/errors.js';
 
+/**
+ * What version 2 has recorded here, if anything.
+ *
+ * `status` only ever counted version 1's things — approved pictures, screens, guards,
+ * markers — so on a project that had just been checked and shipped it said "Nothing has been
+ * checked here yet. Start with: staysfixed check". Measured on 2026-08-30, one command after
+ * a run that walked 36 addresses and a ship that cut the reference. The command whose whole
+ * promise is to say instantly what is going on here was the one saying nothing had happened.
+ *
+ * @param {string} root
+ * @returns {{at: string, verdict: string, reference: string|null, findings: number}|null}
+ */
+export function versionTwoState(root) {
+  try {
+    const file = path.join(root, '.staysfixed', 'v2', 'last-check.json');
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!raw || typeof raw.at !== 'string') return null;
+    // The reference is read from where it is KEPT, not from the last check's memory of it.
+    // A check writes what it compared against at the time; ship cuts a reference after
+    // that, so on the ordinary first-run order — check, then ship — the check's field still
+    // says "no-reference-yet" while a reference plainly exists.
+    let reference = null;
+    try {
+      const cuts = JSON.parse(fs.readFileSync(path.join(root, '.staysfixed', 'v2', 'reference-log.json'), 'utf8'));
+      const newest = Array.isArray(cuts) && cuts.length ? cuts[cuts.length - 1] : null;
+      if (newest && typeof newest.id === 'string') reference = newest.id;
+    } catch {
+      if (typeof raw.reference === 'string' && raw.reference !== 'no-reference-yet') reference = raw.reference;
+    }
+    return {
+      at: raw.at,
+      verdict: typeof raw.verdict === 'string' ? raw.verdict : 'ran',
+      reference,
+      findings: Array.isArray(raw.findings) ? raw.findings.length : 0,
+    };
+  } catch {
+    // Nothing recorded, or nothing readable. Either way there is nothing to add.
+    return null;
+  }
+}
+
 /**
  * @param {import('./index.js').CliContext} ctx
  * @returns {Promise<number>}
@@ -14,6 +58,6 @@ import { EXIT } from '../core/errors.js';
 export async function run(ctx) {
   const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile });
   const status = await projectStatus(project);
-  printStatus(/** @type {any} */ (status));
+  printStatus(/** @type {any} */ ({ ...status, v2: versionTwoState(project.paths?.root ?? ctx.cwd) }));
   return EXIT.ok;
 }

package/src/core/config.js

@@ -146,6 +146,27 @@ export function resolveConfig(raw, file = '(inline)') {
   }
   const c = /** @type {import('../types.js').StaysFixedConfig} */ (raw);
 
+  // Version 2's settings describe a website under `web:` and a desktop app under
+  // `electron:`. These commands are version 1's and only ever knew about `app:` — so on the
+  // settings file `staysfixed init` writes for a website, `status`, `walk` and `flake` all
+  // answered "these settings do not name anything to open", and then listed `process,
+  // source` as the shape of the project. `init` had said, one command earlier, "The website
+  // can be checked here now ... watched by opening it in a throwaway browser". Both about
+  // the same file, seconds apart, and `status` is the command whose whole promise is to say
+  // instantly what is set up here.
+  //
+  // Where the address is actually knowable, take it and let the command work. Booting is
+  // version 2's job and these commands cannot do it, so `web.start` alone is not enough —
+  // that case falls through to the message below, which now says so honestly.
+  if ((!c.app || typeof c.app !== 'object')) {
+    const v2 = /** @type {Record<string, any>} */ (/** @type {unknown} */ (c));
+    if (v2.web && typeof v2.web === 'object' && typeof v2.web.url === 'string' && v2.web.url) {
+      c.app = { kind: 'web', url: v2.web.url };
+    } else if (v2.electron && typeof v2.electron === 'object' && typeof v2.electron.binary === 'string' && v2.electron.binary) {
+      c.app = { kind: 'electron', binary: v2.electron.binary };
+    }
+  }
+
   if (!c.app || typeof c.app !== 'object') {
     // Every command that lands here — status, walk, approve, mark, trace, flake, and
     // `check --pictures` — works by OPENING something and photographing it. A settings
@@ -155,6 +176,16 @@ export function resolveConfig(raw, file = '(inline)') {
     // half of the tool needs it, and names the half that does not.
     const anything = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (c));
     const notVisual = ['process', 'http', 'source', 'android', 'ios', 'windows'].filter((k) => anything[k] && typeof anything[k] === 'object');
+    // A project that DOES have a screen, described the version 2 way, must never be told it
+    // has none. It is told the true thing instead: this half of the tool photographs an
+    // address you can point it at, and version 2 finds the address by booting the product,
+    // which is why `check` covers it and these do not.
+    const started = anything.web && typeof anything.web === 'object' && typeof (/** @type {any} */ (anything.web).start) === 'string';
+    if (started) {
+      throw new StaysFixedError('This project has a website, but these settings start it rather than name an address, and this command photographs an address.', {
+        hint: "`staysfixed check` covers it exactly as it is — it boots `web.start` and finds the address itself. These picture commands need one they can point at, so add `url: 'http://localhost:3000'` beside `start` in the `web` block if you want them too.",
+      });
+    }
     throw new StaysFixedError('These settings do not name anything to open, and this command works by opening your product and photographing it.', {
       hint: notVisual.length
         ? `That is the right shape for what this project is — ${notVisual.join(', ')} settings need nothing to open. Run \`staysfixed check\`, which covers it without a picture. If there IS a screen here too, add \`app: { kind: 'web', url: 'http://localhost:3000' }\` or \`app: { kind: 'electron', binary: '...' }\`.`

package/src/core/paths.js

@@ -139,4 +139,19 @@ export const GITIGNORE_LINES = [
   // Where one person dragged the watch panel on one screen. Nobody else's business,
   // and it would otherwise turn up in their commits.
   '.staysfixed/watch-window.json',
+  // Version 2's evidence, which none of the lines above match — they were all written for
+  // version 1's folders. Measured 2026-08-30 on a Next.js project: 151 untracked files and
+  // 1.9 MB of run evidence sitting in `git status` after nine checks, and every release then
+  // warning that it was made from a dirty tree. `builds/` is the bulk of it: one folder per
+  // build, holding what each run observed.
+  '.staysfixed/v2/builds/',
+  '.staysfixed/v2/last-check.json',
+  // The lock a run holds while it changes the record. Never anybody's to commit.
+  '.staysfixed/**/*.lock',
 ];
+
+/*
+ * Deliberately NOT ignored: `references.json` and `reference-log.json`. Those are the record
+ * of what this product calls working and which release said so — the one thing here a team
+ * genuinely shares, and the thing a new clone needs in order to compare against anything.
+ */

package/src/guard/run.js

@@ -28,6 +28,7 @@ const FRESH_KEY = 'fresh';
 /**
  * @typedef {import('../types.js').GuardResult & {
  *   retriedToPass?: boolean,
+ *   assertedNothing?: boolean,
  *   checks?: import('../types.js').CheckStep[],
  * }} GuardRunResult
  */
@@ -136,10 +137,22 @@ export async function runGuards(project, app, guards, opts = {}) {
       if (opts.signal?.aborted) break;
     }
 
+    // A guard that asserted NOTHING has not held. It cannot hold, and it cannot fail — it is
+    // a name over an empty room. Measured on 2026-08-30: a guard called "the checkout total
+    // is never charged twice", whose `run()` was an empty function, came back as
+    // "ok ... still holds". That is a false all-clear wearing the friendliest face this tool
+    // has, and it would go on saying it every day for ever. The whole promise here is one
+    // plain-English rule per bug somebody already had; a rule that checks nothing is worse
+    // than no rule, because somebody believes it.
+    // Its OWN questions, not the runner's. Every guard gets a "fresh start" step from this
+    // file whether it asks anything or not, so counting the whole list would always find one.
+    const asked = checks.filter((c) => c.key !== FRESH_KEY && !String(c.key ?? '').endsWith(`-${FRESH_KEY}`));
+    const assertedNothing = outcome.ok && asked.length === 0;
+
     /** @type {GuardRunResult} */
     const result = {
       name: guard.name,
-      status: outcome.ok ? 'passed' : 'failed',
+      status: outcome.ok && !assertedNothing ? 'passed' : 'failed',
       file: guard.file,
       because: guard.because,
       durationMs: Date.now() - startedAt,
@@ -147,7 +160,13 @@ export async function runGuards(project, app, guards, opts = {}) {
     };
     if (checks.length > 0) result.checks = checks;
 
-    if (outcome.ok) {
+    if (assertedNothing) {
+      result.assertedNothing = true;
+      result.message =
+        `This guard checked nothing. Its \`run()\` finished without asking a single question, so it cannot fail ` +
+        `and it is not protecting anything — it would report "still holds" every day for ever. ` +
+        `Give it at least one \`expect(...)\`. ${guard.because ? `What it is meant to protect: ${guard.because}` : ''}`.trim();
+    } else if (outcome.ok) {
       // Passing only on the second go is not passing. The flake register picks
       // this up and condemns the guard, because a guard nobody trusts is worse
       // than no guard: people learn to re-run it until it goes green.

package/src/report/console.js

@@ -124,7 +124,11 @@ function tally(run) {
     missing: pictures.filter((p) => p.status === 'missing').length,
     broken: pictures.filter((p) => p.status === 'failed').length,
     wobbled: pictures.filter((p) => p.status === 'flaky').length,
-    guardsFailed: guards.filter((g) => g.status === 'failed').length,
+    // Two different things wear the same status, and calling both of them "a bug is back"
+    // sends somebody hunting a regression that never happened. A guard that asked no
+    // question at all has not caught anything; it has admitted it cannot.
+    guardsFailed: guards.filter((g) => g.status === 'failed' && !(/** @type {any} */ (g).assertedNothing)).length,
+    guardsEmpty: guards.filter((g) => /** @type {any} */ (g).assertedNothing === true).length,
   };
 }
 
@@ -139,6 +143,20 @@ export function verdictFor(run) {
   const parts = [];
   if (t.guardsFailed === 1) parts.push({ n: 1, text: '1 guard failed — a bug that was already fixed is back.' });
   else if (t.guardsFailed > 1) parts.push({ n: t.guardsFailed, text: `${countText(t.guardsFailed)} guards failed — bugs that were already fixed are back.` });
+  // Said even on a green run, because that is the run it changes the meaning of.
+  const left = /** @type {any} */ (run).leftOut;
+  if (left && (left.screens > 0 || left.guards > 0)) {
+    const bits = [];
+    if (left.screens > 0) bits.push(`${left.screens} ${left.screens === 1 ? 'screen' : 'screens'}`);
+    if (left.guards > 0) bits.push(`${left.guards} ${left.guards === 1 ? 'guard' : 'guards'}`);
+    const how_many = (left.screens ?? 0) + (left.guards ?? 0);
+    parts.push({
+      n: 0,
+      text: `${bits.join(' and ')} ${how_many === 1 ? 'was' : 'were'} left out by --only, so this covers a slice and not the whole.`,
+    });
+  }
+  if (t.guardsEmpty === 1) parts.push({ n: 1, text: '1 guard checks nothing, so it is not protecting anything.' });
+  else if (t.guardsEmpty > 1) parts.push({ n: t.guardsEmpty, text: `${countText(t.guardsEmpty)} guards check nothing, so they are not protecting anything.` });
   if (t.changed === 1) parts.push({ n: 1, text: '1 thing changed. Look at it before you ship.' });
   else if (t.changed > 1) parts.push({ n: t.changed, text: `${countText(t.changed)} things changed. Look at them before you ship.` });
   if (t.fresh === 1) parts.push({ n: 1, text: '1 new screen is waiting for a person to approve it.' });
@@ -162,9 +180,12 @@ export function verdictFor(run) {
  * @param {import('../types.js').RunSummary} run
  * @returns {boolean}
  */
-function allClear(run) {
+export function allClear(run) {
   const t = tally(run);
-  return t.changed + t.fresh + t.missing + t.broken + t.wobbled + t.guardsFailed === 0;
+  // `guardsEmpty` counts too. Splitting it out of `guardsFailed` was so the SENTENCE could
+  // tell a returned bug from a guard that asks nothing — not so that one of them could
+  // quietly become a pass.
+  return t.changed + t.fresh + t.missing + t.broken + t.wobbled + t.guardsFailed + t.guardsEmpty === 0;
 }
 
 /**
@@ -561,6 +582,8 @@ export function printFlakes(history, flakeLimit = 2) {
  * @property {number} [markers]       Known-good markers saved.
  * @property {{label: string, at?: string}|null} [lastMarker]
  * @property {import('../types.js').RunSummary|null} [lastRun]
+ * @property {{at: string, verdict: string, reference: string|null, findings: number}|null} [v2]
+ *   What version 2 has recorded here. Version 1's counts say nothing about it.
  * @property {string[]} [condemned]   Names from the flake register, if the CLI already has them.
  * @property {string} [configFile]
  * @property {string} [root]
@@ -591,7 +614,15 @@ export function printStatus(status) {
 
   blank();
   const run = s.lastRun ?? null;
-  if (!run) {
+  if (!run && s.v2) {
+    // Version 2 has run here even though version 1's picture record has not. Saying
+    // "nothing has been checked here yet" one command after a real run is the sort of
+    // wrongness that costs a person their trust in everything else the tool says.
+    say(paint.grey(`  last checked ${ago(s.v2.at)} — ${s.v2.verdict}`));
+    if (s.v2.findings > 0) say(paint.grey(`  ${s.v2.findings} ${plural(s.v2.findings, 'thing', 'things')} nobody had accounted for`));
+    if (s.v2.reference) say(paint.grey(`  compared against ${s.v2.reference}`));
+    else say(`  Nothing is on record as working yet — run ${paint.cyan('staysfixed check')}, then ${paint.cyan('staysfixed ship')}.`);
+  } else if (!run) {
     say('  Nothing has been checked here yet.');
     say(`  Start with: ${paint.cyan('staysfixed check')}`);
   } else {

package/src/run.js

@@ -226,6 +226,17 @@ export async function runCheck(project, opts = {}) {
     tool: TOOL,
     platform: platformTag(),
     condemned: condemnedNames,
+    // What `--only` left out. A narrowed run that says "everything that worked still works"
+    // is describing a slice and sounding like the whole: measured 2026-08-30 with five of
+    // six guards filtered away and one of the five failing, and the run still exited 0
+    // saying everything works. A pass has to carry the size of what it looked at.
+    leftOut: terms
+      ? {
+          screens: Math.max(0, allScreens.length - screens.length),
+          guards: Math.max(0, allGuards.length - guards.length),
+          terms,
+        }
+      : undefined,
     // Read here rather than at the very end: what follows is writing files, and
     // where the run spent its time is a fact about the run, not about the report.
     timings: timings.get(),

package/src/types.js

@@ -328,6 +328,9 @@
  * @property {string} tool
  * @property {string} platform
  * @property {string[]} [condemned]           Names of checks that have flaked past the limit.
+ * @property {{screens: number, guards: number, terms: string[]}} [leftOut]
+ *   What `--only` filtered away. A narrowed run that reads as a full pass is describing a
+ *   slice and sounding like the whole.
  */
 
 /**

package/src/v2/adapters/child.js

@@ -0,0 +1,101 @@
+/**
+ * Starting and stopping the product's own server.
+ *
+ * A start command is run through a shell, because that is what people write: `npm run dev`,
+ * `sh dev.sh`, `poetry run uvicorn ...`. So the thing that is spawned is the SHELL, and the
+ * server is its child — often its grandchild, since `npm run dev` is npm, which runs next,
+ * which runs node.
+ *
+ * Killing the shell therefore does not kill the server. And because the shell's stdout and
+ * stderr are pipes, every survivor inherits the writing end of them — so the pipes never
+ * close, this process's event loop never empties, and `staysfixed check` prints its whole
+ * answer and then hangs for ever at nothing per cent of a CPU. Measured on 2026-08-30 on a
+ * start command that spawns its server and waits, which is the shape `npm run dev` has: the
+ * verdict appeared in about thirty seconds and the command never returned.
+ *
+ * So the shell is started as its own process GROUP and the whole group is signalled. And
+ * after that, the pipes are torn down here rather than trusted to close, because a survivor
+ * this file did not start — a stray `node` somebody's dev server left behind — must not be
+ * able to hold a finished check open.
+ */
+
+import { spawn } from 'node:child_process';
+
+/**
+ * Start the product, in a group of its own.
+ *
+ * @param {string} command
+ * @param {{cwd: string, env: any, stdio?: any}} opts
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnServer(command, opts) {
+  return spawn(String(command), {
+    shell: true,
+    cwd: opts.cwd,
+    env: opts.env,
+    stdio: opts.stdio ?? ['ignore', 'pipe', 'pipe'],
+    // The whole point. On Windows there are no process groups of this kind, and killing the
+    // child is the best that can be done there.
+    detached: process.platform !== 'win32',
+  });
+}
+
+/**
+ * Stop it, and everything it started.
+ *
+ * @param {import('node:child_process').ChildProcess|null|undefined} child
+ * @param {{graceMs?: number}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function stopServer(child, opts = {}) {
+  if (!child) return;
+  const pid = child.pid;
+  const graceMs = opts.graceMs ?? 500;
+
+  /** @param {NodeJS.Signals} signal */
+  const tellTheGroup = (signal) => {
+    if (!pid) return;
+    try {
+      // A negative pid is the GROUP. This is the line that makes the difference.
+      if (process.platform === 'win32') child.kill(signal);
+      else process.kill(-pid, signal);
+    } catch {
+      // No group, or already gone. Ask the one process we definitely know about.
+      try {
+        child.kill(signal);
+      } catch {
+        // Already gone, which is the outcome wanted.
+      }
+    }
+  };
+
+  if (child.exitCode === null && child.signalCode === null) {
+    tellTheGroup('SIGTERM');
+    await new Promise((done) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        done(undefined);
+      };
+      child.once('exit', finish);
+      const timer = setTimeout(finish, graceMs);
+      if (typeof timer.unref === 'function') timer.unref();
+    });
+    if (child.exitCode === null && child.signalCode === null) tellTheGroup('SIGKILL');
+  }
+
+  // And never let what it left behind hold this process open.
+  for (const stream of [child.stdout, child.stderr, child.stdin]) {
+    try {
+      stream?.destroy();
+    } catch {
+      // Nothing to close.
+    }
+  }
+  try {
+    child.unref();
+  } catch {
+    // Not every child can be unreferenced. It has been signalled either way.
+  }
+}

package/src/v2/adapters/http.js

@@ -31,7 +31,6 @@
 import fsp from 'node:fs/promises';
 import net from 'node:net';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
 import {
   defineAdapter, joinPath, notCovered, observation, sizeBucket, stableValue,
   howLongItTook, timeBucket, trimForStorage, undoOurFootprint,
@@ -40,6 +39,7 @@ import {
   compareTrees, copyForScratch, frozenEnvironment, readWatcher, snapshotTree, watcherScript,
 } from './process.js';
 import { readContract, readFileRoutes } from './source.js';
+import { spawnServer, stopServer } from './child.js';
 
 // ---------------------------------------------------------------------------
 // Headers
@@ -456,7 +456,7 @@ export const httpAdapter = defineAdapter({
         notes.push(verdict.why);
       } else {
         const result = await new Promise((resolve) => {
-          const child = spawn(String(config.restore), { shell: true, cwd: work, env, stdio: ['ignore', 'pipe', 'pipe'] });
+          const child = spawnServer(String(config.restore), { cwd: work, env });
           /** @type {Buffer[]} */
           const err = [];
           child.stderr?.on('data', (c) => err.push(c));
@@ -483,7 +483,7 @@ export const httpAdapter = defineAdapter({
     /** @type {Buffer[]} */
     const bootOut = [];
     let exited = /** @type {string|null} */ (null);
-    const child = spawn(String(config.start), { shell: true, cwd: work, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawnServer(String(config.start), { cwd: work, env });
     child.stdout?.on('data', (c) => bootOut.push(c));
     child.stderr?.on('data', (c) => bootErr.push(c));
     child.on('close', (code, signal) => {
@@ -496,11 +496,11 @@ export const httpAdapter = defineAdapter({
     });
 
     if (!up.up) {
-      child.kill('SIGTERM');
+      await stopServer(child);
       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)'}`,
-        dispose: async () => { child.kill('SIGKILL'); await fsp.rm(base, { recursive: true, force: true }); },
+        dispose: async () => { await stopServer(child); await fsp.rm(base, { recursive: true, force: true }); },
       };
     }
 
@@ -522,9 +522,7 @@ export const httpAdapter = defineAdapter({
         if (!held) return;
         // Only ever the process we started. Somebody else's server on this machine is
         // somebody else's business.
-        held.child.kill('SIGTERM');
-        await new Promise((r) => setTimeout(r, 500));
-        if (held.child.exitCode === null) held.child.kill('SIGKILL');
+        await stopServer(held.child);
         await fsp.rm(base, { recursive: true, force: true });
       },
     };
@@ -612,7 +610,7 @@ export const httpAdapter = defineAdapter({
 
   async teardown() {
     for (const [, held] of running) {
-      held.child.kill('SIGTERM');
+      await stopServer(held.child);
     }
     running.clear();
   },