staysfixed 0.8.0 → 0.9.0

package/src/v2/adapters/process.js

@@ -180,10 +180,48 @@ export function watcherScript(opts) {
     "    write('reached out', { host: host || 'somewhere it did not name', port: port ?? null });",
     "    // Refused, not allowed through. Whatever this was going to do out there, it does not",
     "    // do it twice, and the run is reported as having a hole rather than as having passed.",
-    "    const error = new Error('Stays Fixed refused a connection to ' + (host || 'an unnamed host') + ': nothing irreversible is allowed out during a check.');",
-    "    error.code = 'ECONNREFUSED';",
-    "    process.nextTick(() => this.emit('error', error));",
-    "    return this;",
+    "    //",
+    "    // HOW the refusal arrives matters as much as that it happens. Emitting 'error' on the",
+    "    // socket ourselves reads correctly and kills the product: at that moment nothing is",
+    "    // listening on the socket yet, and in Node an 'error' event with no listener is a",
+    "    // thrown exception. `http.get` and `https.get` on Node 22 - the floor this package",
+    "    // declares in its own engines field - and a bare `net.connect` on EVERY version all",
+    "    // died that way, exit 1, and the run then reported the product as broken. A tool",
+    "    // blaming a product for something the tool itself did is the exact failure this whole",
+    "    // package exists to prevent. Measured 2026-08-30 against the published 0.8.0 watcher;",
+    "    // its own CI had been red on this for four releases and nobody read it.",
+    "    //",
+    "    // So the refusal is made real rather than simulated: the socket is pointed at a port on",
+    "    // this machine that nothing can be listening on, and the operating system produces the",
+    "    // refusal through Node's own plumbing - by which time every listener the runtime wires",
+    "    // up is in place. The product gets an ordinary ECONNREFUSED, which is exactly what it",
+    "    // would get if the host were unreachable, and cannot tell the difference.",
+    "    const named = host || 'an unnamed host';",
+    "    const explain = 'Stays Fixed refused a connection to ' + named + ': nothing irreversible is allowed out during a check.';",
+    "    const refusal = () => Object.assign(new Error(explain), { code: 'ECONNREFUSED', refusedBy: 'staysfixed' });",
+    "    // Said in the error the product actually catches, without swallowing it: prepending a",
+    "    // listener rewrites the message and still leaves every other handler to run as it would.",
+    "    this.prependListener('error', (e) => {",
+    "      if (e && e.code === 'ECONNREFUSED') { e.message = explain; e.refusedBy = 'staysfixed'; }",
+    "    });",
+    "    // Belt and braces. If something really is listening down there, the connection is cut",
+    "    // before one byte can cross it: a boundary that fails open is not a boundary.",
+    "    this.prependOnceListener('connect', () => { this.destroy(refusal()); });",
+    "    // And a machine where that port is silently dropped rather than refused would hang",
+    "    // here instead of failing, which is worse than the bug this replaced: a check that",
+    "    // never finishes tells you nothing at all. A refusal is owed promptly, so if the",
+    "    // operating system has not produced one shortly, produce it. Safe to do now, and only",
+    "    // now, because the listener above means this can never be an unhandled error.",
+    "    const soon = setTimeout(() => { if (!this.destroyed) this.destroy(refusal()); }, 250);",
+    "    if (typeof soon.unref === 'function') soon.unref();",
+    "    this.once('close', () => clearTimeout(soon));",
+    "    try {",
+    "      return connect.call(this, { port: 1, host: '127.0.0.1' });",
+    "    } catch {",
+    "      // Even the refusal failed. Still never throw into the product.",
+    "      process.nextTick(() => { if (!this.destroyed) this.destroy(refusal()); });",
+    "      return this;",
+    "    }",
     "  };",
     "} catch { /* no net module, nothing to refuse */ }",
     "",
@@ -1090,7 +1128,19 @@ export const processAdapter = defineAdapter({
  */
 export function importProbeCommand(moduleId) {
   const probe = [
-    "const m = await import(process.argv[1].startsWith('.') || process.argv[1].includes('/') ? new URL(process.argv[1], 'file://' + process.cwd() + '/').href : process.argv[1]);",
+    // A FILE unless it is really a package. The old rule was "starts with a dot, or has a
+    // slash in it" — and `index.js` has neither, so Node was asked for a PACKAGE called
+    // "index.js" and answered ERR_MODULE_NOT_FOUND. `staysfixed init` writes exactly
+    // `{ module: "index.js" }` for an ordinary package entry, so on those projects this
+    // journey failed on every run, failed the SAME way on both builds, produced no
+    // difference, and the check said "Nothing that worked has changed" for ever. Measured
+    // 2026-08-30. So: if a file of that name is really there, it is a file.
+    "const id = process.argv[1];",
+    "const { existsSync } = await import('node:fs');",
+    "const { fileURLToPath } = await import('node:url');",
+    "const asFile = new URL(id, 'file://' + process.cwd() + '/').href;",
+    "const onDisk = (() => { try { return existsSync(fileURLToPath(asFile)); } catch { return false; } })();",
+    "const m = await import(id.startsWith('.') || id.startsWith('/') || id.includes('/') || onDisk ? asFile : id);",
     "const out = {};",
     "for (const key of Object.keys(m).sort()) {",
     "  const v = m[key];",

package/src/v2/adapters/web-driver.js

@@ -174,6 +174,8 @@ export async function loadPlaywright(opts = {}) {
   // So: ask it. Only when there is no browser on the machine at all is this a real "no".
   /** @type {string|undefined} */
   let borrowedFrom;
+  /** True when the browser found is the one the PERSON uses, not a separate one. */
+  let borrowedTheirOwn = false;
   if (!there) {
     try {
       const { surveyBrowsers } = await import('../browsers.js');
@@ -181,6 +183,7 @@ export async function loadPlaywright(opts = {}) {
       if (survey.chosen?.binary && (await exists(survey.chosen.binary))) {
         executable = survey.chosen.binary;
         borrowedFrom = survey.chosen.name;
+        borrowedTheirOwn = survey.borrowingHis === true || survey.chosen.everyday === true;
         there = true;
       }
     } catch {
@@ -206,12 +209,35 @@ export async function loadPlaywright(opts = {}) {
     chromium: mod.chromium,
     version,
     executable,
-    why: borrowedFrom
-      ? `The browser driver ${version ?? ''} is here and it will open ${borrowedFrom}, which is a separate application from the browser you use, so pages can be opened.`.trim()
-      : `The browser driver ${version ?? ''} is here and its Chromium is downloaded, so pages can be opened.`.trim(),
+    why: browserNote(version, borrowedFrom, borrowedTheirOwn),
   };
 }
 
+/**
+ * What to say about the browser a check will open.
+ *
+ * "a separate application from the browser you use" used to be said whatever was found — and
+ * the one case where that sentence matters is the case where it is false. With no downloaded
+ * test browser anywhere, the survey falls back to the person's OWN browser, and this then
+ * told them the opposite of what was about to happen. A reassurance is only worth anything
+ * if it is withheld when it is not true.
+ *
+ * Exported so the wording is a test rather than a thing somebody has to notice.
+ *
+ * @param {string|undefined} version        The driver version, if it said one.
+ * @param {string|undefined} borrowedFrom   The browser found, if one had to be borrowed.
+ * @param {boolean} borrowedTheirOwn        True when that browser is the person's own.
+ * @returns {string}
+ */
+export function browserNote(version, borrowedFrom, borrowedTheirOwn) {
+  const v = version ?? '';
+  if (!borrowedFrom) return `The browser driver ${v} is here and its Chromium is downloaded, so pages can be opened.`.trim();
+  if (borrowedTheirOwn) {
+    return `The browser driver ${v} is here and the only browser on this machine is the one you use yourself (${borrowedFrom}). It will be opened invisibly with a throwaway profile, so your own settings, cookies and tabs are never touched — but it is your browser, not a separate one. \`npx playwright install chromium\` gives checks one of their own.`.trim();
+  }
+  return `The browser driver ${v} is here and it will open ${borrowedFrom}, which is a separate application from the browser you use, so pages can be opened.`.trim();
+}
+
 /**
  * @param {string} file
  * @returns {Promise<boolean>}
@@ -1489,6 +1515,20 @@ export async function runStep(page, step, opts = {}) {
         break;
     }
   }
+  // A step that did nothing at all is almost always a word this tool does not know, and
+  // saying nothing about it is the worst outcome available: the journey walks on, the sign-in
+  // never happens, every page behind the login wall photographs the login page, and the run
+  // comes back clean. `staysfixed init` itself shipped `{ fill: '#email', with: 'a@b.c' }`
+  // as its sign-in example, and neither word is in the vocabulary.
+  if (did.length === 0) {
+    const known = new Set([...ACTION_ORDER, 'text', 'timeoutMs', 'name', 'note', 'act', 'checkpoint', 'describe']);
+    const unknown = Object.keys(step).filter((k) => !known.has(k));
+    if (unknown.length > 0) {
+      throw new Error(
+        `This step does nothing: ${unknown.map((k) => `\`${k}\``).join(', ')} ${unknown.length === 1 ? 'is not a word' : 'are not words'} this tool knows, so the step was skipped and whatever it was meant to do did not happen. The steps it understands are: ${ACTION_ORDER.join(', ')} — with \`text\` beside \`type\`. To type into a field: { type: '#email', text: 'a@b.c' }.`,
+      );
+    }
+  }
   return did;
 }
 

package/src/v2/adapters/web.js

@@ -40,7 +40,6 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
 
 import {
   countBucket, defineAdapter, howLongItTook, joinPath, notCovered, observation, sizeBucket,
@@ -50,6 +49,7 @@ import { copyForScratch, frozenEnvironment } from './process.js';
 import { freePort, looksDestructive, waitForServer } from './http.js';
 import { applyFreeze, prepareForShutter } from '../../freeze/index.js';
 import { settle } from '../../freeze/settle.js';
+import { spawnServer, stopServer } from './child.js';
 import {
   actOf, countRoles, flattenAria, inkOf, loadPlaywright, openWindow, parseAria, runStep, short,
   watchTheWire, whereItIs, withLimit,
@@ -537,7 +537,7 @@ export const webAdapter = defineAdapter({
       if (!verdict.safe) notes.push(verdict.why);
       else {
         const done = await new Promise((resolve) => {
-          const child = spawn(String(config.restore), { shell: true, cwd: work, env, stdio: 'ignore' });
+          const child = spawnServer(String(config.restore), { cwd: work, env, stdio: 'ignore' });
           child.on('error', () => resolve(false));
           child.on('close', (code) => resolve(code === 0));
         });
@@ -549,7 +549,7 @@ export const webAdapter = defineAdapter({
     const said = [];
     /** @type {string|null} */
     let exited = 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) => said.push(c));
     child.stderr?.on('data', (c) => said.push(c));
     child.on('close', (code, signal) => {
@@ -558,14 +558,14 @@ export const webAdapter = defineAdapter({
 
     const up = await waitForServer(port, { timeoutMs: config.startTimeoutMs ?? 90000, crashed: () => exited });
     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(said).toString('utf8'), 1500).text || '(nothing)'}`,
         dispose: async () => {
-          child.kill('SIGKILL');
+          await stopServer(child);
           await fsp.rm(base, { recursive: true, force: true });
         },
       };
@@ -584,9 +584,7 @@ export const webAdapter = defineAdapter({
         running.delete(build.id);
         if (!held) return;
         // Only ever the process we started ourselves.
-        held.child?.kill('SIGTERM');
-        await new Promise((r) => setTimeout(r, 400));
-        if (held.child && held.child.exitCode === null) held.child.kill('SIGKILL');
+        await stopServer(held.child);
         await fsp.rm(base, { recursive: true, force: true });
       },
     };
@@ -779,7 +777,7 @@ export const webAdapter = defineAdapter({
   },
 
   async teardown() {
-    for (const [, held] of running) held.child?.kill('SIGTERM');
+    for (const [, held] of running) await stopServer(held.child);
     running.clear();
   },
 });

package/src/v2/browsers.js

@@ -270,6 +270,16 @@ function testingBrowsers() {
         take('chromium', path.join(inner, 'chrome-mac', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'));
         take('chrome-for-testing', path.join(inner, 'chrome-linux', 'chrome'));
         take('chrome-for-testing', path.join(inner, 'chrome-win', 'chrome.exe'));
+        // The 64 matters, and leaving it off made this tool blind to full Chrome on every
+        // machine that is not a Mac. Playwright unpacks Linux into `chrome-linux64` and
+        // Windows into `chrome-win64`; Puppeteer does the same. Only macOS uses the names
+        // above, which is why it was never noticed here. On Linux this meant `npx playwright
+        // install chromium` - the command THIS FILE tells people to run - left a browser the
+        // survey could not see, and checks quietly fell back to the headless shell, or said
+        // there was no browser at all when the shell was not there too. Measured on a real
+        // Linux box on 2026-08-30: three Chromes present, none of them found.
+        take('chrome-for-testing', path.join(inner, 'chrome-linux64', 'chrome'));
+        take('chrome-for-testing', path.join(inner, 'chrome-win64', 'chrome.exe'));
         take('headless-shell', path.join(inner, 'chrome-headless-shell-mac-arm64', 'chrome-headless-shell'), true);
         take('headless-shell', path.join(inner, 'chrome-headless-shell-mac-x64', 'chrome-headless-shell'), true);
         take('headless-shell', path.join(inner, 'chrome-headless-shell-linux64', 'chrome-headless-shell'), true);
@@ -534,11 +544,56 @@ function killNow(pid, home) {
     } catch {
       // Already gone. That is the outcome we wanted.
     }
+    // SIGKILL is a request to the kernel, not something that has already happened, and a
+    // browser is not one process. While the parent is being reaped its children are still
+    // writing into the profile, so deleting the folder in the same breath loses the race:
+    // the sweep starts, a file appears behind it, the directory is not empty, and the
+    // profile outlives the run - which is the one thing `nothing it opened outlives the
+    // run` promises. It passed on macOS and on an idle Linux box and failed on a loaded CI
+    // runner for four releases, which is exactly how a race behaves.
+    for (let i = 0; i < 40 && stillThere(pid); i++) waitSync(10);
   }
+  // Then remove it, and more than once. One rmSync is a snapshot; a file recreated a
+  // millisecond after the sweep began turns it into ENOTEMPTY and a leftover folder.
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      fs.rmSync(home, { recursive: true, force: true });
+      return;
+    } catch {
+      waitSync(20);
+    }
+  }
+  // A profile left in the temporary folder is untidy, not harmful — and it is exactly what
+  // `staysfixed browsers --clean` is for.
+}
+
+/**
+ * Is that process still running? Signal 0 asks without sending anything.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function stillThere(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A real sleep, in the one place nothing may be awaited: this runs inside
+ * `process.on('exit')`, where the event loop is already over and a promise never
+ * resolves. `Atomics.wait` is the only thing that actually pauses here.
+ *
+ * @param {number} ms
+ */
+function waitSync(ms) {
   try {
-    fs.rmSync(home, { recursive: true, force: true });
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
   } catch {
-    // A profile left in the temporary folder is untidy, not harmful.
+    // No SharedArrayBuffer here. Falling straight through is still better than throwing
+    // out of a cleanup handler.
   }
 }
 

package/src/v2/check.js

@@ -95,7 +95,7 @@ const exec = promisify(execFile);
  * quietly checked something else and found nothing", and those two read identically
  * without this. It is only ever set when the run really did reach that surface.
  *
- * @typedef {Verdict & {blocked?: boolean, accounted?: import('./escalate.js').Accounting, target?: {surface: string, at: string|null}}} CheckOutcome
+ * @typedef {Verdict & {blocked?: boolean, comparedNothing?: 'no reference'|'no stored record'|null, accounted?: import('./escalate.js').Accounting, target?: {surface: string, at: string|null}}} CheckOutcome
  */
 
 /**
@@ -315,8 +315,31 @@ export async function check(options = {}) {
     // "nothing was walked" on a run that walked plenty.
     await countTheDoors(verdict, project);
 
+    // THE GUARDS. `settle` takes the names so that a difference touching a bug somebody
+    // already had once is sealed and no agent may wave it through — and both call sites used
+    // to hand it nothing, so that class was empty on every run this tool has ever done. The
+    // one seal that exists because a person was burned before could never fire.
+    //
+    // Running them is version 1's job and needs its browser driver, which this path does not
+    // have. That is a real hole and it is now SAID rather than left silent: measured on
+    // 2026-08-30, a check on a project with a guard sitting in `.staysfixed/guards` printed
+    // the word "guard" exactly zero times. A tool built to catch silent breakage must not do
+    // nothing silently.
+    const named = await guardNames(project.root);
+    if (named.length > 0 && verdict.coverage) {
+      verdict.coverage.gaps = [
+        ...(verdict.coverage.gaps ?? []),
+        {
+          what: `${named.length} guard${named.length === 1 ? '' : 's'} written against bugs that already happened once`,
+          why:
+            `They are sealed by name, so nothing touching one can be waved through quietly — but they were not RUN on this check. ` +
+            `\`staysfixed check --guards\` walks them. ${named.map((n) => `"${n}"`).join(', ')}`,
+        },
+      ];
+    }
+
     /** @type {CheckOutcome} */
-    const outcome = await settle(verdict, project.store, project.product);
+    const outcome = await settle(verdict, project.store, project.product, named);
     // Only a run that really did reach the surface it was aimed at may say so. The
     // confirmation is what lets a caller tell "it went there and found nothing" from
     // "it checked something else and found nothing", and those are not the same answer.
@@ -432,6 +455,14 @@ async function settle(verdict, store, product, guards) {
     // nothing came back different — and it is the exact sentence that would let a real
     // regression through. It is not a pass. It is no answer at all.
     const nothing = comparedNothing(verdict);
+    // Carried as a FIELD, not only folded into a sentence. Every other surface has to be
+    // able to ask this question without reading English: the MCP server rendered its own
+    // headline from the difference count alone, never looked at `ok`, and answered a
+    // machine "NOTHING UNACCOUNTED FOR. Everything that worked before still works" with
+    // `ok: true` and `isError: false` on a project that had nothing on record at all —
+    // while the terminal, on the same run, correctly said it was no answer. The agent is
+    // the reader that matters most here, and it was the one being told the untrue thing.
+    verdict.comparedNothing = nothing;
     if (nothing) {
       verdict.ok = false;
       verdict.summary =
@@ -628,6 +659,92 @@ function comparedNothing(verdict) {
   return nothingToCompare >= walked ? 'no stored record' : null;
 }
 
+/**
+ * The guards this project has, by name.
+ *
+ * Names only: sealing a difference by the guard it touches needs the name, and nothing on
+ * this path can run one. `loadGuards` wants only the folder, and it is the same reader
+ * version 1 uses, so a guard version 1 accepts is a guard this counts.
+ *
+ * @param {string} root
+ * @returns {Promise<string[]>}
+ */
+export async function guardNames(root) {
+  try {
+    const { loadGuards } = await import('../guard/load.js');
+    const guards = await loadGuards(/** @type {any} */ ({ paths: { guards: path.join(root, '.staysfixed', 'guards') } }));
+    return guards.map((g) => String(g?.name ?? '')).filter(Boolean);
+  } catch {
+    // A guards folder that will not load must never stop a check running. Version 1 says the
+    // same about the same folder, and a check that refuses is worse than one without a seal.
+    return [];
+  }
+}
+
+/**
+ * Copies left behind by runs that never finished.
+ *
+ * A check copies the whole project into a scratch folder, and a run that is killed — Ctrl-C,
+ * a laptop closing, a CI job cancelled — never gets to delete it. Nothing else ever did
+ * either: measured on 2026-08-30, an ordinary machine had 777 MB of `staysfixed-check-*`
+ * sitting in the temporary folder, one copy of it 485 MB, and a later run added to the pile
+ * rather than clearing it. A tool that quietly fills somebody's disk is not one they keep.
+ *
+ * The rule is the one the browser sweep already uses: never touch something in use. A folder
+ * whose owner is still running is left completely alone, and one with no owner recorded is
+ * only taken once it is far older than any real run could be. A dead process id that has
+ * since been reused reads as "still running" and the folder survives, which is the safe way
+ * round to be wrong.
+ *
+ * @returns {Promise<void>}
+ */
+export async function sweepAbandonedScratch() {
+  const AN_HOUR = 60 * 60 * 1000;
+  const MOST_PER_RUN = 20;
+  let names = [];
+  try {
+    names = await fsp.readdir(os.tmpdir());
+  } catch {
+    return;
+  }
+  let taken = 0;
+  for (const name of names) {
+    if (taken >= MOST_PER_RUN) break;
+    if (!name.startsWith('staysfixed-check-')) continue;
+    const dir = path.join(os.tmpdir(), name);
+    let abandoned = false;
+    try {
+      const owner = JSON.parse(await fsp.readFile(path.join(dir, 'owner.json'), 'utf8'));
+      abandoned = typeof owner?.pid !== 'number' || !processAlive(owner.pid);
+    } catch {
+      // No owner recorded: either an older copy or one that died before it could say. Age is
+      // all there is to go on, and an hour is well past the longest run this tool makes.
+      try {
+        abandoned = Date.now() - (await fsp.stat(dir)).mtimeMs > AN_HOUR;
+      } catch {
+        abandoned = false;
+      }
+    }
+    if (!abandoned) continue;
+    await fsp.rm(dir, { recursive: true, force: true }).catch(() => {});
+    taken += 1;
+  }
+}
+
+/**
+ * Is that process still running? Signal 0 asks without sending anything.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * One gap's sentence, trimmed to something that fits inside another sentence.
  * @param {string} what
@@ -1382,9 +1499,12 @@ async function openProject(options) {
     storeTrouble.push(`The folder Stays Fixed keeps its records in could not be made: ${messageOf(e)}`);
   }
 
+  await sweepAbandonedScratch();
   const scratch = await fsp.mkdtemp(path.join(os.tmpdir(), 'staysfixed-check-'));
   const evidenceDir = path.join(scratch, 'evidence');
   await fsp.mkdir(evidenceDir, { recursive: true });
+  // Who this belongs to, so a later run can tell an abandoned copy from one in use.
+  await fsp.writeFile(path.join(scratch, 'owner.json'), JSON.stringify({ pid: process.pid, at: new Date().toISOString() })).catch(() => {});
 
   // Working out what there is to walk comes FIRST, before anything is asked of git. Somebody
   // standing in a folder they have not set up yet should be told to run `init`, not told
@@ -1996,7 +2116,7 @@ async function readConfig(configFile) {
  * @param {string} product
  * @returns {Promise<BuildFingerprint>}
  */
-async function fingerprintWorkingTree(root, product) {
+export async function fingerprintWorkingTree(root, product) {
   const sha = await git(root, ['rev-parse', 'HEAD']);
   if (!sha) {
     // REFUSING IS THE ONLY HONEST ANSWER HERE, and the alternative is the worst bug this

package/src/v2/cli.js

@@ -37,6 +37,7 @@ import { escalationBlock, escalationsFor, productFor, writeEscalations } from '.
 // module is still being evaluated.
 import { watchFlags } from '../cli/watch-flags.js';
 import { INIT_COMMANDS } from './init.js';
+import { whatWasNotChecked } from './check.js';
 
 /**
  * What comes back from a check. Everything that did not change never appears
@@ -167,16 +168,17 @@ export const V2_COMMANDS = {
 
   doctor: {
     summary: 'What this tool can and cannot check on this machine, and what would unlock more.',
-    usage: 'staysfixed doctor [--json] [--offline] [--fix]',
+    usage: 'staysfixed doctor [--json] [--machines] [--offline] [--fix]',
     describe:
-      'Looks at this machine rather than at your project: what is installed, which other\nmachines it can already reach, what each of those lets it watch, and what exactly\nis in the way of the rest. It never asks you to set up something that already\nworks — everything it lists as missing failed a real check first.\n\n--json is the same answer as an object, and it is the first thing an agent\nshould call. --fix repairs the small things version 1 could repair.',
+      'Looks at this machine rather than at your project: what is installed, which other\nmachines it can already reach, what each of those lets it watch, and what exactly\nis in the way of the rest. It never asks you to set up something that already\nworks — everything it lists as missing failed a real check first.\n\n--json is the same answer as an object, and it is the first thing an agent\nshould call. --fix repairs the small things version 1 could repair.\n\nIt does not connect to the machines in your ssh config unless this project has a\ndesktop app that might need one, or you pass --machines. They are still listed.',
     options: [
       ['--json', 'The whole answer as one JSON object. For agents.'],
+      ['--machines', 'Also dial the machines in your ssh config, to find a runner for a desktop app.'],
       ['--offline', 'Do not dial any other machine. Faster, and reports no runners.'],
       ['--fix', 'Repair the small local things that can be repaired safely.'],
     ],
     examples: ['staysfixed doctor', 'staysfixed doctor --json'],
-    spec: { booleans: ['json', 'offline', 'fix'] },
+    spec: { booleans: ['json', 'offline', 'fix', 'machines'] },
     load: async () => ({ run: doctorRun }),
   },
 };
@@ -243,23 +245,26 @@ export async function run(ctx) {
   // checks on the command line and then ships is told their build was "never
   // checked", and the safeguard fires on the honest case instead of the careless
   // one. The agent surface records its own; this is the command line's half.
-  try {
-    const { recordCheck } = await import('./reference.js');
-    const { openStore } = await import('./store.js');
-    await recordCheck(openStore({ root: ctx.cwd ?? process.cwd() }), {
-      buildId: verdict.candidate?.id,
-      product: verdict.product,
-      ok: verdict.ok,
-      blocked: /** @type {any} */ (verdict).blocked === true,
-      findings: verdict.findings.length,
-      by: 'staysfixed check',
-    });
-  } catch {
-    // Never let bookkeeping cost somebody the result they came for.
-  }
+  // NOT recorded again here. The engine writes this line itself, for every surface, inside
+  // `rememberCheck` — and with more in it than this ever had: what was waived, what was
+  // sealed, how much went unaccounted for. This block was added on the belief that only the
+  // agent surface recorded, so every command-line check wrote TWO near-identical rows two
+  // milliseconds apart. Measured 2026-08-30: eight rows for four checks, and `ship` reads
+  // this log to decide whether the last check was clean.
 
   if (asJson) {
-    process.stdout.write(JSON.stringify(verdict) + '\n');
+    // The README promises these as fields of their own — "a number an agent can read"
+    // rather than a sentence it has to parse — and only the MCP reply had them. So a human
+    // asking for JSON on the command line got a strictly worse answer about what was NOT
+    // checked than an agent asking over MCP, about the very same run.
+    const coverage = verdict.coverage ?? null;
+    process.stdout.write(
+      JSON.stringify({
+        ...verdict,
+        notChecked: whatWasNotChecked(coverage),
+        doorsNeverOpened: Math.max(0, (coverage?.doorsKnown ?? 0) - (coverage?.doorsWalked ?? 0)),
+      }) + '\n',
+    );
   } else {
     report(verdict);
   }

package/src/v2/cluster.js

@@ -186,20 +186,75 @@ export function findRenames(differences) {
 
   /** @type {Map<Difference, {from: string, to: string}>} */
   const found = new Map();
+  /** @type {{was: string, now: string, from: string, to: string}[]} */
+  const moves = [];
   for (const place of places.values()) {
     if (place.gone.length !== 1 || place.came.length !== 1) continue;
     const gone = place.gone[0];
     const came = place.came[0];
-    if (!sameValue(gone.reference, came.candidate)) continue;
     const from = leafOf(gone.path);
     const to = leafOf(came.path);
     if (from === to) continue;
+    // "The values must match" is right for a thing addressed by its position, and wrong for
+    // one addressed by its own words. A heading lives at `heading:Nine Bakers` and its value
+    // reads `a heading called "Nine Bakers"` — rename it and BOTH move, so the values never
+    // match and the rename was never spotted. Measured 2026-08-30: renaming one heading on a
+    // page came back as five separate findings, one thing vanishing and a different thing
+    // appearing, with nothing anywhere saying "renamed". So a value that changed in exactly
+    // the same way the name did counts as the same value. Anything else is still two edits
+    // that happened to land side by side, which is what this test exists to keep out.
+    if (!sameValue(gone.reference, came.candidate) && !movedWithItsName(gone.reference, came.candidate, from, to)) continue;
     found.set(gone, { from, to });
     found.set(came, { from, to });
+    moves.push({ was: gone.path, now: came.path, from, to });
+  }
+
+  // A rename takes its children with it. Everything under the old address goes away and the
+  // same things arrive under the new one — true, and not a second piece of news. Renaming one
+  // heading on a page reported the heading AND the two halves of its own `level`, so one edit
+  // a person would describe in four words arrived as four findings. Anything that moved with
+  // it, unchanged, belongs to the rename that moved it.
+  for (const move of moves) {
+    for (const gone of differences) {
+      if (gone.kind !== 'vanished' || found.has(gone)) continue;
+      if (!gone.path.startsWith(`${move.was}.`)) continue;
+      const wanted = move.now + gone.path.slice(move.was.length);
+      const came = differences.find(
+        (d) => d.kind === 'appeared' && !found.has(d) && d.path === wanted && d.channel === gone.channel && sameValue(gone.reference, d.candidate),
+      );
+      if (!came) continue;
+      found.set(gone, { from: move.from, to: move.to });
+      found.set(came, { from: move.from, to: move.to });
+    }
   }
   return found;
 }
 
+/**
+ * Did the value change in exactly the way the name did?
+ *
+ * Only for two addresses naming the same KIND of thing — `heading:X` and `heading:Y`, never
+ * `heading:X` and `button:Y` — because the part before the colon is what the thing IS, and a
+ * heading becoming a button is not a rename.
+ *
+ * @param {unknown} before
+ * @param {unknown} after
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+function movedWithItsName(before, after, from, to) {
+  if (typeof before !== 'string' || typeof after !== 'string') return false;
+  const wasNamed = /^([^:]+):(.+)$/.exec(from);
+  const nowNamed = /^([^:]+):(.+)$/.exec(to);
+  if (!wasNamed || !nowNamed) return false;
+  if (wasNamed[1] !== nowNamed[1]) return false;
+  const was = wasNamed[2];
+  const now = nowNamed[2];
+  if (!was || was === now) return false;
+  return before.split(was).join(now) === after;
+}
+
 /**
  * The grouping key: channel, shape of change, what the address ends in, and the
  * move from one value to another.