staysfixed 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -6,7 +6,88 @@ numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-Nothing yet.
+## [0.14.0] — 2026-09-02
+
+Four defects, every one of them found by WATCHING this tool work rather than by reading it.
+The owner could not find its live window, then recorded four minutes of it running and the
+recording contained three faults nobody had noticed in a month of testing.
+
+### A system dialog can no longer stall a run in silence
+
+A real check froze for two of its four minutes behind a macOS alert — *"A keychain cannot be
+found to store 'Terminal Deck Key'"* — while a journey waited for a person who was never going
+to arrive. The run finished and reported one journey with no answer, and never said why.
+
+Every adapter here starts the product under test in a throwaway settings folder, which is
+exactly the condition that makes an application ask the operating system for something it has
+never been granted. These dialogs are a normal consequence of how this tool works, so they are
+its problem.
+
+- Modal boxes belonging to an application **this run started** are noticed, closed and reported
+  with their own words. Nothing else is touched.
+- The button pressed comes from a fixed list that decline, dismiss or close — never one that
+  grants, resets, deletes or agrees. On the alert that started this, the other button was
+  *Reset To Defaults*, on a keychain, and it was the default.
+- A dialog with nothing safe on it is **left exactly as it is** and named in the result instead.
+- `AXModal` is the test, not the subrole: an ordinary Terminal window reports the same
+  `AXDialog` subrole the real alert does, so matching on that would send this tool hunting for
+  buttons to press in somebody's actual work.
+
+### The report survives the findings
+
+When a verdict landed, everything the run had spent four minutes drawing — the walk, every
+journey and its address count, the wobble, what survived, what was not checked — vanished. The
+footer holding "Needs a person" had no cap, so seventeen findings grew it past the height of the
+panel and squeezed the body to **eighteen pixels holding 41,115** of content.
+
+The footer is capped and its list scrolls inside itself; the body keeps a floor. Held both ways
+by a guard, including against the first over-correction, which lost the same detail from the
+other end by letting the footer collapse to its label.
+
+### The live window says that it exists
+
+`--watch` is off by default, the window opens behind your work on purpose, and nothing anywhere
+ever mentioned it. Three correct decisions adding up to a feature nobody could find. `check` now
+says one line on a project that has a screen: that the window is there and how to open it, or,
+when it is open, which side of the screen it went to.
+
+### Something added is no longer described as a deletion
+
+An escalation read *"SessionBar is there now and was not before"* and then, one line below,
+*"Say whether that deletion is meant to happen."* A sealed class says what a change TOUCHES; it
+says nothing about which way it moved, and the sentence a person is asked to rule on has to
+describe what actually happened.
+
+
+### The self-check corpus knows about the five false all-clears found on 2026-08-31
+
+Five defects were found and fixed that day, each of which could have blessed a broken build,
+and not one of them would have been caught by the corpus that is supposed to make that
+impossible. There is a case for each now, and every one of them was made to fail against the
+code as it stood before its fix before it was believed.
+
+- **A build that crashes on its first line is no longer a build that agrees with itself.** Two
+  builds that crash the same way used to agree at every address, and agreement is the silence
+  this tool reads as "nothing changed".
+- **Coverage this build took away is never handed back as a pass.** The engine decided that
+  correctly and the bookkeeping then assigned the verdict rather than narrowing it.
+- **A standard cut from a tree git does not have is never walked out of git.** The old build
+  was exported from the commit, walked, and a real regression was dropped as something it does
+  too.
+- **With nothing edited, nothing can be a change.** The build being checked and the build on
+  record were one build, and whatever flickered between two runs was reported as a change
+  nobody made.
+- **What "working" means moves only when somebody ships.** Re-running a check on the shipped
+  build quietly replaced the standard with whatever that run happened to see.
+
+### A guard can hand `evaluate` a function
+
+`page.evaluate` took JavaScript as text and nothing else. Passing it a function — the obvious
+thing, and what every other tool in this space accepts — answered `The app refused the request
+"Runtime.evaluate": Invalid parameters`, which is the debug protocol talking about its own wire
+format to somebody who had done nothing wrong. It now takes either, and the two things it
+genuinely cannot run — a built-in, and a function that asks for an argument it has no way to
+be given — say so in a sentence with an example in it.
 
 ## [0.12.0] — 2026-08-31
 
@@ -140,7 +221,9 @@ adapter and tests turned out to hold at least one defect that only running it co
   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"*.
+  before"*. Asking for a paired run against such a reference is now refused outright, naming
+  the reason and what to do instead, rather than quietly giving you something weaker; an
+  ordinary check still falls back to the stored record and says so.
 
 ### It reported things as checked that were never checked
 

package/docs/guards.md

@@ -126,6 +126,24 @@ export default {
 | `app.read(file)` | Read a project file as text. |
 | `app.project` | The resolved config and paths. |
 
+### Running your own JavaScript in the page
+
+`page.evaluate` takes it either way round — as a piece of JavaScript written as
+text, or as a function it will call inside the app:
+
+```js
+const title = await app.page.evaluate('document.title');
+const title = await app.page.evaluate(() => document.title);
+```
+
+The function is run with nothing passed to it, so one that asks for an argument
+is refused rather than quietly handed `undefined`. Close over what it needs, or
+write the value into the JavaScript itself:
+
+```js
+await app.page.evaluate(`document.title === ${JSON.stringify(expected)}`);
+```
+
 ---
 
 ## The `expect` style

package/docs/how-v2-works.md

@@ -309,6 +309,16 @@ RUN`, and the reason is in the coverage as a hole. This is not a tolerance — n
 number here decides whether any single difference is real. It decides one thing:
 whether this run has earned the right to use the word clean.
 
+**It is asked once per journey, not once per run.** Asking it only of everything
+added together is how a page that told you nothing gets averaged away by nine
+pages that behaved: 179 unsteady addresses out of 2849 is not a storm, while four
+of that run's twelve journeys were unsteady at 69%, 75% and twice 100% of their
+own. `noAnswerJourneys(wobbles)` is the same one comparison asked journey by
+journey, and any journey it names takes the pass away and is listed by name in the
+summary's first sentence. A journey walked twice that came back with no addresses
+at all is in that list too — two empty walks agree about everything, and that is
+not a measurement.
+
 ### A finding
 
 A cluster of differences that share a cause, which is what the agent reads:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.12.0",
+  "version": "0.14.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 \u2014 as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",

package/src/cli/approve.js

@@ -16,7 +16,10 @@ 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` — approving moves a picture the last check already took. It launches
+  // nothing. On a project with no screen there is simply never anything waiting, and saying
+  // that in one line is the true answer; refusing to load the settings at all was not.
+  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile, opening: false });
   const all = ctx.bool('all');
   const names = ctx.args.filter((a) => a.trim() !== '');
 

package/src/cli/flake.js

@@ -17,7 +17,10 @@ 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` — the register is a file on disk and reading it opens nothing. Without
+  // this, the one command whose whole job is to name unreliable checks was itself refused on
+  // every command-line tool and library this tool sets up. Measured 2026-08-31.
+  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile, opening: false });
   const history = await loadHistory(project.paths.historyFile);
 
   const forgive = ctx.str('clear');

package/src/cli/mark.js

@@ -13,7 +13,11 @@ import { StaysFixedError, 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` — a marker is a commit, a date and a set of fingerprints written to a
+  // file. Nothing is opened and nothing is photographed, so a project with no screen can pin
+  // a known-good version exactly like any other. It was refused on every one of them until
+  // 2026-08-31, which took `trace` down with it: there was nothing to trace back to.
+  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile, opening: false });
 
   if (ctx.bool('list')) return showAll(project);
 

package/src/cli/status.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { loadProject } from '../core/config.js';
 import { projectStatus } from '../run.js';
 import { printStatus } from '../report/console.js';
+import { say, blank, heading, paint } from '../core/log.js';
 import { EXIT } from '../core/errors.js';
 
 /**
@@ -56,8 +57,59 @@ export function versionTwoState(root) {
  * @returns {Promise<number>}
  */
 export async function run(ctx) {
-  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile });
+  // `opening: false` — this command reads files and prints them. It says so in its own first
+  // line. Loading the settings through the check that insists on something to open made the
+  // fastest command in the tool refuse outright on every command-line tool, library and
+  // server it had just set up, with a paragraph about an `app` key version 2 never writes.
+  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile, opening: false });
   const status = await projectStatus(project);
   printStatus(/** @type {any} */ ({ ...status, v2: versionTwoState(project.paths?.root ?? ctx.cwd) }));
+  printWhatIsSetUp(project.config);
   return EXIT.ok;
 }
+
+/**
+ * What these settings actually cover, in one short list.
+ *
+ * The promise of this command is "what is set up here", and on a project with no screen the
+ * picture counters answer it with four zeroes — every one of them true, and together they
+ * read as "nothing is set up" about a project whose settings name three commands and two
+ * folders of source. So the settings are read back in the words they were written in.
+ *
+ * Everything here is read out of the settings file. Nothing is inferred and nothing is
+ * counted that is not there, because a status line that overstates what is covered is the
+ * one kind of wrong this tool cannot afford.
+ *
+ * @param {import('../types.js').ResolvedConfig} config
+ * @returns {void}
+ */
+function printWhatIsSetUp(config) {
+  const any = /** @type {Record<string, any>} */ (/** @type {unknown} */ (config));
+  /** @type {string[]} */
+  const lines = [];
+
+  const commands = Array.isArray(any.process?.commands) ? any.process.commands.filter((/** @type {any} */ c) => c && !c.skip) : [];
+  const imports = Array.isArray(any.process?.imports) ? any.process.imports : [];
+  if (commands.length > 0) lines.push(`${commands.length} ${commands.length === 1 ? 'command' : 'commands'} to run and compare word for word`);
+  if (imports.length > 0) lines.push(`${imports.length} ${imports.length === 1 ? 'library entry' : 'library entries'} to import and compare what ${imports.length === 1 ? 'it exports' : 'they export'}`);
+  if (any.source && typeof any.source === 'object') {
+    const folders = Array.isArray(any.source.folders) ? any.source.folders : [];
+    lines.push(folders.length > 0 ? `the code in ${folders.join(', ')}, read without running it` : 'the code, read without running it');
+  }
+  if (any.http && typeof any.http === 'object') lines.push('a server, booted on a spare port and asked for every route');
+  if (any.web && typeof any.web === 'object') {
+    const screens = Array.isArray(any.web.screens) ? any.web.screens.length : 0;
+    lines.push(screens > 0 ? `a website, and ${screens} ${screens === 1 ? 'screen' : 'screens'} of it` : 'a website');
+  }
+  if (any.electron && typeof any.electron === 'object') lines.push('a desktop app');
+  if (any.android && typeof any.android === 'object') lines.push('an Android app');
+  if (any.ios && typeof any.ios === 'object') lines.push('an iPhone app');
+  if (any.windows && typeof any.windows === 'object') lines.push('a native Windows app');
+
+  if (lines.length === 0) return;
+  heading('What these settings cover');
+  for (const line of lines) say(`  ${paint.grey('·')} ${line}`);
+  blank();
+  say(paint.grey(`  Run ${paint.cyan('staysfixed check')} to walk it, and ${paint.cyan('staysfixed coverage')} for what a run did NOT look at.`));
+  blank();
+}

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';