staysfixed 0.11.1 → 0.13.0

package/src/cli/trace.js

@@ -6,7 +6,7 @@ import { loadProject } from '../core/config.js';
 import { projectStatus } from '../run.js';
 import { traceScreens } from '../marker/trace.js';
 import { printTrace } from '../report/console.js';
-import { say, paint } from '../core/log.js';
+import { say, blank, paint } from '../core/log.js';
 import { resultPicture } from '../core/paths.js';
 import { sha256File } from '../core/hash.js';
 import { EXIT } from '../core/errors.js';
@@ -16,12 +16,37 @@ import { EXIT } from '../core/errors.js';
  * @returns {Promise<number>}
  */
 export async function run(ctx) {
-  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile });
+  // `opening: false` — tracing compares fingerprints already written down against markers
+  // already written down. It opens nothing. Where there is nothing recorded to trace, the
+  // report says so in its own words further down; being refused before it could even look
+  // was the wrong answer, and it named a settings key that version 2 never writes.
+  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile, opening: false });
 
   const asked = ctx.args.filter((a) => a.trim() !== '');
   const changed = asked.length > 0 ? [] : await changedInLastRun(project);
   const names = asked.length > 0 ? asked : changed;
 
+  // A project with nothing to photograph cannot be traced, and it is owed a sentence saying
+  // why rather than a shrug and a suggestion it has already followed.
+  //
+  // The generic ending is "There is nothing to trace yet. Pin a good version first with
+  // `staysfixed mark`." — which, on a project that had just pinned one, told somebody to go
+  // and do the thing they had done thirty seconds earlier. Measured 2026-08-31 on a Python
+  // command-line tool. Tracing follows a SCREEN backwards, so on a product with no screen
+  // the answer is not "not yet", it is "not this kind of project", and saying the second one
+  // stops somebody working through a list that was never going to end.
+  if (asked.length === 0 && names.length === 0 && project.config.screens.length === 0) {
+    blank();
+    say('There is no screen in this project to trace.');
+    say(paint.grey('Tracing follows one screen back through your markers to the commit where it stopped'));
+    say(paint.grey('looking right, so it needs a picture to follow. These settings name none.'));
+    blank();
+    say(`For what changed in a project without a screen, run ${paint.cyan('staysfixed check')} — it compares every`);
+    say('word a command printed, what it exited with and every file it touched.');
+    blank();
+    return EXIT.ok;
+  }
+
   if (asked.length === 0) {
     if (names.length === 0) {
       say(paint.grey('Nothing is different right now, so this looks at every screen there is a record of.'));

package/src/core/config.js

@@ -83,9 +83,40 @@ export const DEFAULT_MCP = {
   allowMark: false,
 };
 
+/**
+ * The `app.kind` of a project that has nothing to open at all.
+ *
+ * A command-line tool, a library and a plain server are all perfectly ordinary products with
+ * no screen anywhere in them, and every command that only READS what is on disk — status,
+ * flake, mark, trace, approve — works on one exactly as well as it works on a website. They
+ * were all refused anyway, because the only way to load settings was through a check that
+ * insisted on something to open. This value is how a command says "I open nothing, so do not
+ * ask", and it is a made-up word on purpose: nothing can accidentally match it, and anything
+ * that reads it and does not understand it fails loudly rather than photographing a guess.
+ */
+export const NOTHING_TO_OPEN = 'nothing-to-open';
+
+/**
+ * Do these settings name anything this tool could open and photograph?
+ *
+ * Exported so a command can ask before it tries, and say something true about this project
+ * instead of the same refusal for every shape of product.
+ *
+ * @param {import('../types.js').ResolvedConfig} config
+ * @returns {boolean}
+ */
+export function hasSomethingToOpen(config) {
+  // Read as a plain string on purpose. The declared shape of `app.kind` is version 1's two
+  // words, and this third one is deliberately outside it — see NOTHING_TO_OPEN above.
+  return /** @type {string} */ (config?.app?.kind) !== NOTHING_TO_OPEN;
+}
+
 /**
  * Find, import and resolve the config.
- * @param {{cwd?: string, configFile?: string}} [opts]
+ * @param {{cwd?: string, configFile?: string, opening?: boolean}} [opts]
+ *   `opening: false` is a command promising it will not open or photograph anything — it
+ *   only reads what is already on disk. Settings with no screen in them are then a normal,
+ *   correct shape rather than a reason to refuse.
  * @returns {Promise<import('../types.js').Project>}
  */
 export async function loadProject(opts = {}) {
@@ -98,7 +129,7 @@ export async function loadProject(opts = {}) {
   }
   const raw = await importConfig(file);
   const root = rootForConfig(file);
-  const config = resolveConfig(raw, file);
+  const config = resolveConfig(raw, file, { opening: opts.opening });
   const paths = pathsFor(root, file, config.dir);
   // `guards` is the one folder a project is free to move, so the config wins over the
   // default layout. Without this the setting silently did nothing and the tool reported
@@ -136,9 +167,11 @@ async function importConfig(file) {
  * Fill in defaults and reject anything that would fail later in a confusing way.
  * @param {unknown} raw
  * @param {string} file
+ * @param {{opening?: boolean}} [opts]
+ *   `opening: false` from a command that only reads what is on disk. See {@link loadProject}.
  * @returns {import('../types.js').ResolvedConfig}
  */
-export function resolveConfig(raw, file = '(inline)') {
+export function resolveConfig(raw, file = '(inline)', opts = {}) {
   if (!raw || typeof raw !== 'object') {
     throw new StaysFixedError(`${path.basename(file)} did not export a config object.`, {
       hint: 'It should `export default { app: { ... }, screens: [ ... ] }`.',
@@ -158,8 +191,8 @@ export function resolveConfig(raw, file = '(inline)') {
   // 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.
+  const v2 = /** @type {Record<string, any>} */ (/** @type {unknown} */ (c));
   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) {
@@ -167,15 +200,49 @@ export function resolveConfig(raw, file = '(inline)') {
     }
   }
 
+  // The screens come across with the address, and they did not before.
+  //
+  // Half a bridge is worse than none: on a version 2 website `walk` and `approve` were
+  // handed the address and then found nothing to photograph, because version 2 keeps its
+  // screens under `web` and these commands only ever looked at the top level. So the
+  // commands ran, opened a browser, and reported an empty walk of a site with six pages in
+  // its settings — measured 2026-08-31. Only a screen with a name and a plain address is
+  // carried over; anything reached by clicking is version 2's to walk, not this half's, and
+  // inventing a journey out of one would put a screen in the report nobody can reach.
+  if (c.app && typeof c.app === 'object' && !Array.isArray(c.screens)) {
+    const fromV2 = Array.isArray(v2.web?.screens) ? v2.web.screens : [];
+    const carried = fromV2.filter((/** @type {any} */ s) => s && typeof s.name === 'string' && typeof s.url === 'string' && s.url !== '');
+    if (carried.length > 0) c.screens = carried.map((/** @type {any} */ s) => ({ name: s.name, url: s.url }));
+  }
+
+  // A command that opens nothing must never be refused for having nothing to open.
+  //
+  // `status`, `flake`, `mark`, `trace` and `approve` all do their whole job by reading files
+  // this tool has already written. Every one of them was dead on the settings this tool's own
+  // `init` writes for a command-line tool, a library or a server — five commands offered in
+  // `--help`, all answering with a paragraph about an `app` key that version 2 never writes
+  // and that nobody running them had ever seen. Measured 2026-08-31 on a Python command-line
+  // tool and on a plain Node one; both were set up by `staysfixed init` seconds earlier.
+  if ((!c.app || typeof c.app !== 'object') && opts.opening === false) {
+    c.app = /** @type {any} */ ({ kind: NOTHING_TO_OPEN });
+  }
+
   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
-    // file with no `app` in it is the normal, correct shape for a command-line tool, a
-    // library or a server: there is nothing to open, and telling somebody to go and add a
-    // web address they do not have sends them off inventing one. So the message says which
-    // half of the tool needs it, and names the half that does not.
+    // Only the commands that really do open something land here now — `walk`, and
+    // `check --pictures`. They photograph a screen, so a project with no screen anywhere in
+    // it genuinely cannot be walked, and the honest thing is to say which product this is
+    // and stop offering it.
+    //
+    // What this message must never do is name a key the person has not got. `app` is version
+    // 1's word for the thing to open; the settings `staysfixed init` writes today have no
+    // `app` in them and never will, so telling somebody to add one sends them editing a file
+    // against a shape nothing else in the tool uses. Where there IS advice worth giving, it
+    // is given in the words their own settings file already uses — `url` inside the `web`
+    // block — and only for a file that is written that way.
     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');
+    const versionTwo = ['process', 'source', 'http', 'web', 'electron', 'android', 'ios', 'windows']
+      .filter((k) => anything[k] && typeof anything[k] === 'object');
+    const notVisual = ['process', 'http', 'source', 'android', 'ios', 'windows'].filter((k) => versionTwo.includes(k));
     // 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,
@@ -186,23 +253,36 @@ export function resolveConfig(raw, file = '(inline)') {
         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.",
       });
     }
+    if (versionTwo.length > 0) {
+      throw new StaysFixedError(
+        `This command photographs a screen, and this project has none — these settings describe ${plainList(versionTwo.map(describeBlock))}.`,
+        {
+          hint: `Nothing is missing and nothing needs adding. Run \`staysfixed check\`, which covers ${notVisual.length === versionTwo.length ? 'exactly what is here' : 'all of it'} without a picture.`
+            + (versionTwo.includes('web') ? " If you want the picture commands on the site too, add `url: 'http://localhost:3000'` inside the `web` block so there is an address to point at." : ''),
+        },
+      );
+    }
     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: '...' }\`.`
-        : "Add `app: { kind: 'web', url: 'http://localhost:3000' }` or `app: { kind: 'electron', binary: '...' }`. If your product has no screen at all, `staysfixed check` covers it without one.",
+      hint: "Add `app: { kind: 'web', url: 'http://localhost:3000' }` or `app: { kind: 'electron', binary: '...' }`. If your product has no screen at all, `staysfixed check` covers it without one.",
     });
   }
-  const kind = c.app.kind;
-  if (kind !== 'web' && kind !== 'electron') {
-    throw new StaysFixedError(`app.kind must be 'web' or 'electron' (found ${JSON.stringify(kind)}).`);
-  }
-  if (kind === 'web' && !c.app.url && !c.app.attach) {
-    throw new StaysFixedError('A web app needs `app.url` — the address to open.');
-  }
-  if (kind === 'electron' && !c.app.binary && !c.app.attach) {
-    throw new StaysFixedError('An Electron app needs `app.binary` — the path to the executable.', {
-      hint: 'On macOS that is inside the bundle: /Applications/Your App.app/Contents/MacOS/Your App',
-    });
+  // Read as a plain string, because a project with nothing to open carries a third value
+  // that is deliberately outside version 1's two — see NOTHING_TO_OPEN at the top.
+  const kind = /** @type {string} */ (c.app.kind);
+  // A command that told us it opens nothing gets no further questions. Asking a project with
+  // no screen for an address or a binary is the refusal this whole branch exists to stop.
+  if (kind !== NOTHING_TO_OPEN) {
+    if (kind !== 'web' && kind !== 'electron') {
+      throw new StaysFixedError(`app.kind must be 'web' or 'electron' (found ${JSON.stringify(kind)}).`);
+    }
+    if (kind === 'web' && !c.app.url && !c.app.attach) {
+      throw new StaysFixedError('A web app needs `app.url` — the address to open.');
+    }
+    if (kind === 'electron' && !c.app.binary && !c.app.attach) {
+      throw new StaysFixedError('An Electron app needs `app.binary` — the path to the executable.', {
+        hint: 'On macOS that is inside the bundle: /Applications/Your App.app/Contents/MacOS/Your App',
+      });
+    }
   }
 
   const screens = (c.screens ?? []).map((s, i) => resolveScreen(s, i));
@@ -285,3 +365,34 @@ export function settingsForScreen(config, screen) {
     masks: [...config.masks, ...(screen.masks ?? [])],
   };
 }
+
+/**
+ * What one block of version 2 settings actually is, in words somebody who did not write this
+ * tool would use. Said out loud in a refusal so the sentence names this project rather than
+ * naming a missing key.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+function describeBlock(key) {
+  return /** @type {Record<string,string>} */ ({
+    process: 'commands to run and libraries to import',
+    source: 'code to read without running it',
+    http: 'a server to boot and ask for its routes',
+    web: 'a website to open',
+    electron: 'a desktop app to open',
+    android: 'an Android app',
+    ios: 'an iPhone app',
+    windows: 'a native Windows app',
+  })[key] ?? key;
+}
+
+/**
+ * A list a person reads out loud: "a, b and c". Two commas and an "and" beats three commas.
+ * @param {string[]} items
+ * @returns {string}
+ */
+function plainList(items) {
+  if (items.length <= 1) return items[0] ?? '';
+  return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}

package/src/core/stop-tree.js

@@ -0,0 +1,109 @@
+/**
+ * Stopping a command AND everything that command started — on every operating system.
+ *
+ * Almost every command this tool runs is really a shell: `npm test`, `npm run dev`,
+ * `poetry run uvicorn ...`. The shell then starts the real program, which often starts
+ * another one. So the process this tool holds a handle to is the shell, and the work is
+ * happening in its children and grandchildren.
+ *
+ * Killing the shell is not killing the work. On Linux the children carry on with a new
+ * parent; on a Mac they usually die with the shell, which is exactly why this was invisible
+ * for so long. The answer there is to put the shell and everything it starts into one
+ * process GROUP and signal the group, which is what a negative process id means.
+ *
+ * WINDOWS HAS NO PROCESS GROUPS OF THAT KIND, and the code here used to say so and give up —
+ * it killed the one process it knew about and hoped. It does not work: measured on a real
+ * Windows 11 machine on 2026-08-31, a command the guard had already given up on kept running,
+ * finished its work and wrote its file, because only `cmd.exe` had been killed and the `node`
+ * underneath it never noticed. Windows does have an answer, it is just spelled differently:
+ * `taskkill /T` walks the tree of children and stops all of them. This file is the one place
+ * that difference is written down, so no caller has to remember it again.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/** Windows spells "stop this and everything under it" as a command, not a signal. */
+const TASKKILL = 'taskkill';
+
+/**
+ * Stop a process and every process it started.
+ *
+ * Safe to call more than once, safe to call on something already gone, and safe to call from
+ * an exit handler — nothing here is asynchronous, because a process on its way out has no
+ * event loop left to wait on.
+ *
+ * @param {number|null|undefined} pid   The process this tool started.
+ * @param {'SIGTERM'|'SIGKILL'} signal  SIGTERM asks; SIGKILL insists.
+ * @param {{child?: import('node:child_process').ChildProcess|null}} [opts]
+ *        The handle, when the caller has one. It is the fallback if the tree walk fails.
+ * @returns {boolean} true when something was asked to stop, false when there was nothing to ask.
+ */
+export function stopTree(pid, signal, opts = {}) {
+  const child = opts.child ?? null;
+  if (!pid) {
+    if (!child) return false;
+    return tryKill(child, signal);
+  }
+
+  if (process.platform === 'win32') {
+    // `/T` takes the children, `/F` insists — and on Windows BOTH are always used, including
+    // for the polite SIGTERM. There is no polite stop for a console program there: `taskkill`
+    // without `/F` sends a window a close message, which `node` has no window to receive, so
+    // it refuses with "this process can only be terminated forcefully" and nothing stops.
+    //
+    // Nothing is lost by that, because Node's own `child.kill('SIGTERM')` on Windows is
+    // already an outright TerminateProcess — the ONLY difference this line makes is that the
+    // children go too. Measured on a real Windows 11 machine on 2026-08-31: the first version
+    // of this file tried the polite form, watched it refuse, and fell back to killing the
+    // shell alone — which left the server running AND made it look like it had stopped,
+    // because the handle the caller was watching had gone. The scratch folder could then not
+    // be deleted, and the whole of `waiting.test.js` failed on it.
+    const ran = spawnSync(TASKKILL, ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true, timeout: 10_000 });
+    if (ran.status === 0) return true;
+    // taskkill was not there, or the process had already finished — which is the outcome the
+    // caller wanted anyway. Stopping the one process this tool definitely knows about is
+    // weaker than stopping the tree, and it is a great deal better than leaving it running.
+    return child ? tryKill(child, signal) : false;
+  }
+
+  try {
+    // A negative process id is the GROUP. This is the line that takes the watchers,
+    // bundlers and servers down with the shell that started them.
+    process.kill(-pid, signal);
+    return true;
+  } catch {
+    // No group — which happens when the caller did not start it detached — or it is already
+    // gone. Either way, ask the one process we know about.
+    if (child) return tryKill(child, signal);
+    try {
+      process.kill(pid, signal);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {'SIGTERM'|'SIGKILL'} signal
+ * @returns {boolean}
+ */
+function tryKill(child, signal) {
+  try {
+    return child.kill(signal);
+  } catch {
+    // Already gone, which is the outcome wanted.
+    return false;
+  }
+}
+
+/**
+ * Should a command be started in a process group of its own?
+ *
+ * Only where process groups exist. On Windows `detached: true` does something else entirely —
+ * it gives the child its own console WINDOW, which flashes up on the person's screen in the
+ * middle of a check and is never what this tool wants. Windows gets its tree walk from
+ * `stopTree` instead, which needs nothing at spawn time.
+ */
+export const OWN_PROCESS_GROUP = process.platform !== 'win32';

package/src/drive/browser.js

@@ -14,6 +14,7 @@ import path from 'node:path';
 
 import { StaysFixedError, isExpected } from '../core/errors.js';
 import { detail } from '../core/log.js';
+import { stopTree, OWN_PROCESS_GROUP } from '../core/stop-tree.js';
 import { DEFAULT_VIEWPORT } from '../core/config.js';
 import { waitForEndpoint, listTargets, connect } from './cdp.js';
 import { requireChrome, freePort } from './find.js';
@@ -116,20 +117,17 @@ export function whenExited(child) {
 export async function stopProcess(child, graceMs) {
   if (isGone(child)) return;
   const exited = whenExited(child);
-  try {
-    child.kill('SIGTERM');
-  } catch {
-    // Already gone between the check and the signal. Nothing to do.
-  }
+  // The tree, not just this one process. A browser is never one process — it is a parent and
+  // a renderer for every page — and on Windows killing only the parent leaves the renderers
+  // running, still writing into the throwaway profile, so the profile folder cannot be
+  // deleted and outlives the run. That is the one thing "nothing it opened outlives the run"
+  // promises. Measured on a real Windows 11 machine on 2026-08-31.
+  stopTree(child.pid, 'SIGTERM', { child });
   const grace = raceTimer(graceMs, false);
   const stopped = await Promise.race([exited.then(() => true), grace.promise]);
   grace.cancel();
   if (stopped) return;
-  try {
-    child.kill('SIGKILL');
-  } catch {
-    // Same race as above.
-  }
+  stopTree(child.pid, 'SIGKILL', { child });
   const last = raceTimer(1000, false);
   await Promise.race([exited, last.promise]);
   last.cancel();
@@ -458,7 +456,11 @@ export async function startWebApp(app, opts = {}) {
     // Its own process group. A dev server is really a shell that spawns a
     // bundler that spawns a watcher; killing only the shell leaves the port held
     // and the next run fails for a reason nobody can see.
-    detached: true,
+    //
+    // Not on Windows, where `detached: true` means something else entirely — a console
+    // WINDOW of its own, flashing up on the person's screen in the middle of a check.
+    // Windows stops the tree a different way, in `stopTree`, and needs nothing at spawn time.
+    detached: OWN_PROCESS_GROUP,
     stdio: ['ignore', 'pipe', 'pipe'],
   });
   const output = keepOutput(child);
@@ -478,30 +480,17 @@ export async function startWebApp(app, opts = {}) {
     stopping ??= (async () => {
       if (isGone(child)) return;
       const exited = whenExited(child);
-      try {
-        // Negative pid means the whole group — the only way to take the
-        // watchers down with the server.
-        if (pid) process.kill(-pid, 'SIGTERM');
-      } catch {
-        try {
-          child.kill('SIGTERM');
-        } catch {
-          // Already gone.
-        }
-      }
+      // The whole tree, not just the shell. On Linux and a Mac that is the process group;
+      // on Windows it is `taskkill /T`, which is what `stopTree` reaches for. Before this,
+      // Windows killed `cmd.exe` and left the dev server holding the port, so the next run
+      // failed for a reason nobody could see — the exact outcome the comment above warns
+      // about, on the one operating system where the code did not do it. Found 2026-08-31.
+      stopTree(pid, 'SIGTERM', { child });
       const grace = raceTimer(5000, false);
       const gone = await Promise.race([exited.then(() => true), grace.promise]);
       grace.cancel();
       if (gone) return;
-      try {
-        if (pid) process.kill(-pid, 'SIGKILL');
-      } catch {
-        try {
-          child.kill('SIGKILL');
-        } catch {
-          // Already gone.
-        }
-      }
+      stopTree(pid, 'SIGKILL', { child });
       const last = raceTimer(1000, false);
       await Promise.race([exited, last.promise]);
       last.cancel();

package/src/drive/page.js

@@ -150,6 +150,73 @@ function removeStyleTagSource(token) {
   );
 }
 
+/**
+ * What somebody handed `evaluate`, turned into a piece of JavaScript the app can run.
+ *
+ * A STRING IS NOT THE OBVIOUS THING TO PASS. Every other tool in this space takes a
+ * function — `page.evaluate(() => document.title)` is what anybody who has driven a browser
+ * before writes first — and this took only text. Handing it a function put a function object
+ * where the debug protocol wanted a string, and what came back was, in full, measured while
+ * using the tool on 2026-08-31:
+ *
+ *     The app refused the request "Runtime.evaluate": Invalid parameters
+ *
+ * That is the machine's own words about its own wire format, said to somebody who has done
+ * nothing wrong except write the thing that works everywhere else. So a function is now
+ * accepted and turned into the call it obviously means, and text goes through untouched.
+ * Only what genuinely cannot be run says so — in a sentence naming what it was given and
+ * showing the one line that works.
+ *
+ * It runs with nothing passed to it, which is why a function that declares a parameter is
+ * refused rather than quietly given `undefined`: there is no way to send a value into the
+ * page here, and the alternative is a guard failing inside the app for a reason that has
+ * nothing to do with the app.
+ *
+ * @param {unknown} what   A piece of JavaScript as text, or a function to call in the page.
+ * @returns {string}
+ */
+export function asJavaScript(what) {
+  if (typeof what === 'string') return what;
+
+  if (typeof what === 'function') {
+    const source = String(what);
+    // A built-in — `page.evaluate(Math.max)`, `page.evaluate(document.querySelector)` — has
+    // no readable body, so there is nothing to send. Asked FIRST, before anything about the
+    // arguments: a built-in usually declares some, and being told to close over them is
+    // advice about a function nobody could have sent anyway. Said plainly, too, because
+    // "SyntaxError: Unexpected token" out of the page is a worse version of the message this
+    // whole function exists to replace.
+    if (/\{\s*\[native code\]\s*\}/.test(source)) {
+      throw new StaysFixedError('evaluate() was handed a built-in function, and the app cannot be sent one: it has no source to run.', {
+        hint: 'Wrap it in a function of your own: page.evaluate(() => document.querySelector(".total").textContent).',
+      });
+    }
+    if (what.length > 0) {
+      throw new StaysFixedError(
+        `evaluate() runs a function inside the app with nothing passed to it, and this one asks for ${what.length === 1 ? 'an argument' : `${what.length} arguments`}.`,
+        {
+          hint: 'Nothing can be sent into the page here. Close over what it needs, or write the value into the JavaScript itself: page.evaluate(`document.title === ${JSON.stringify(expected)}`).',
+        },
+      );
+    }
+    // Shorthand method syntax — `{ title() { ... } }` — is not an expression on its own, so
+    // the ordinary wrapping below would send the app something it cannot parse. Put back in
+    // the object it was written in and called by name.
+    //
+    // A leading `async` is taken off before the name is read, and it has to be: leave it on
+    // and the pattern happily reads `async () => 1` as a method called "async", because
+    // backtracking gives up the optional keyword and matches the word itself.
+    const shorthand = /^(?!function\b)([A-Za-z_$][\w$]*)\s*\(/.exec(source.replace(/^async\s+/, ''));
+    if (shorthand) return `({ ${source} }).${shorthand[1]}()`;
+    return `(${source})()`;
+  }
+
+  throw new StaysFixedError(
+    `evaluate() wants a piece of JavaScript written as text, or a function to run in the app. It was given ${what === null ? 'null' : typeof what}.`,
+    { hint: 'Either way round works: page.evaluate(\'document.title\') or page.evaluate(() => document.title).' },
+  );
+}
+
 /**
  * One line describing whatever the page threw.
  * @param {any} details  Runtime.ExceptionDetails
@@ -283,12 +350,17 @@ export async function createPage(cdp, opts) {
   // ---------------------------------------------------------------------------
 
   /**
-   * @param {string} js
+   * Run JavaScript in the page.
+   *
+   * Takes it as text, or as a function to call — see {@link asJavaScript} for why both, and
+   * for the message that used to come back when somebody wrote the function.
+   *
+   * @param {string|Function} js
    * @returns {Promise<any>}
    */
   async function evaluate(js) {
     const res = await send('Runtime.evaluate', {
-      expression: js,
+      expression: asJavaScript(js),
       awaitPromise: true,
       returnByValue: true,
       userGesture: true,

package/src/guard/api.js

@@ -19,6 +19,7 @@ import { spawn } from 'node:child_process';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { StaysFixedError } from '../core/errors.js';
+import { stopTree, OWN_PROCESS_GROUP } from '../core/stop-tree.js';
 
 /** A plain-language expectation that did not hold. */
 export class ExpectationFailed extends Error {
@@ -313,7 +314,7 @@ export function makeGuardApi(page, project, opts = {}) {
         const child = spawn(cmd, {
           cwd,
           shell: true,
-          detached: process.platform !== 'win32',
+          detached: OWN_PROCESS_GROUP,
           windowsHide: true,
         });
 
@@ -324,15 +325,19 @@ export function makeGuardApi(page, project, opts = {}) {
         let how = 'ran';
         let done = false;
 
-        /** Stop the shell AND everything it started. */
+        /**
+         * Stop the shell AND everything it started.
+         *
+         * This used to kill only the child on Windows, with a comment saying that was the
+         * best that could be done there. It is not: measured on a real Windows 11 machine on
+         * 2026-08-31, "kills a command that was still running when the run gave up" failed,
+         * because killing `cmd.exe` left the `node` underneath it running and it finished its
+         * work and wrote its file after the run had given up on it — the same defect Linux
+         * showed on 2026-08-31, on a different operating system's spelling of it. `stopTree`
+         * holds both spellings.
+         */
         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.
-          }
+          stopTree(child.pid, 'SIGKILL', { child });
         };
 
         child.stdout?.setEncoding('utf8');

package/src/types.js

@@ -206,7 +206,7 @@
  * @property {(selector: string, opts?: {timeoutMs?: number}) => Promise<void>} waitForGone
  * @property {(selector: string) => Promise<void>} scrollTo
  * @property {(ms: number) => Promise<void>} wait
- * @property {(js: string) => Promise<any>} evaluate
+ * @property {(js: string|Function) => Promise<any>} evaluate   Text, or a function to run in the page.
  * @property {(selector: string) => Promise<boolean>} visible
  * @property {(selector: string) => Promise<boolean>} exists
  * @property {(selector: string) => Promise<string>} textOf