staysfixed 0.8.0 → 0.9.1

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
@@ -1796,6 +1916,18 @@ async function gatherJourneys({ root, config, options }) {
 
   const named =
     options.journeys && !['code', 'config', 'suite'].includes(options.journeys) ? options.journeys : null;
+  // `recorded` is a word this tool knows and `check --help` offers it — it is simply not
+  // wired into a run yet. The MCP surface says exactly that; the command line fell through to
+  // the branch above, treated the word as a FILE PATH, and answered that a file called
+  // "recorded" was missing. The same question has to get the same answer on both.
+  if (options.journeys === 'recorded') {
+    throw new StaysFixedError(
+      'Replaying a recorded session is written and not wired into a run yet, so nothing was checked.',
+      {
+        hint: 'Leave --journeys out to use the steps each adapter reads from your source, pass `suite` to walk your own test suite, or pass the path to a journeys file.',
+      },
+    );
+  }
   if (named) journeys.push(...(await readJourneyFile(path.resolve(root, named))));
 
   // The project's own test suite, when somebody asked for it in those words and never
@@ -1996,7 +2128,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.

package/src/v2/doctor.js

@@ -196,7 +196,7 @@ export const CHANNELS = [
  * should be able to read it once and know what to call, what it will get back,
  * and what it must not bother asking for here.
  *
- * @param {{cwd?: string, configFile?: string, offline?: boolean}} [opts]
+ * @param {{cwd?: string, configFile?: string, offline?: boolean, machines?: boolean}} [opts]
  * @returns {Promise<Capabilities>}
  */
 export async function capabilities(opts = {}) {
@@ -218,7 +218,12 @@ export async function capabilities(opts = {}) {
 
   const [tools, hosts, repo, reference, drivers, phones, asked] = await Promise.all([
     findTools(cwd, browsers),
-    offline ? Promise.resolve(/** @type {HostReport[]} */ ([])) : reachableHosts(),
+    // Only a product that could actually run somewhere else is a reason to go looking for
+    // somewhere else. A website or a command-line tool never needs a Windows desktop, and
+    // the hosts list feeds exactly one surface: that one.
+    offline
+      ? Promise.resolve(/** @type {HostReport[]} */ ([]))
+      : reachableHosts({ dial: opts.machines === true || desktopApp !== null }),
     isRepo(root).catch(() => false),
     findReference(root),
     whatThisCopyCanDrive(),
@@ -249,7 +254,7 @@ export async function capabilities(opts = {}) {
     },
     surfaces,
     drivers,
-    covers: whatThisRunActuallyCovers(surfaces),
+    covers: whatThisRunActuallyCovers(surfaces, configFile !== null),
     browsers: {
       willOpen: browsers.chosen,
       borrowingYourOwn: browsers.borrowingHis,
@@ -1175,13 +1180,40 @@ function androidSdkTool(folder, name) {
  * answers is a runner the tool already has, and it must never appear in the
  * result as something to go and set up.
  *
+ * @param {{dial?: boolean}} [opts]
  * @returns {Promise<HostReport[]>}
  */
-export async function reachableHosts() {
+export async function reachableHosts(opts = {}) {
   if (!onPath('ssh')) return [];
   const names = await sshConfigHosts();
   if (names.length === 0) return [];
 
+  // READING the ssh config is free and tells nobody anything. DIALLING is neither, and it
+  // is not something this tool may do to somebody who has just installed it.
+  //
+  // The first command a stranger runs is `doctor`. On a brand-new scratch project with no
+  // settings file and nothing that could possibly need a second machine, this opened ssh
+  // connections to every host in their `~/.ssh/config` and ran a command on each — measured
+  // on 2026-08-30: ten hosts configured, connections out within seconds of the first run,
+  // nothing said before or after. Those are production servers in a lot of people's configs,
+  // and in a lot of workplaces that alone is a policy breach. `--offline` existed, but a way
+  // out you only learn about afterwards is not consent.
+  //
+  // So it is asked for now rather than assumed, and the machines are still NAMED either way,
+  // because a machine quietly left out of the answer is the same bug as a folder quietly
+  // skipped while reading source: the list looks complete and the runner somebody needed is
+  // simply not in it.
+  if (opts.dial !== true) {
+    return names.map(
+      (name) =>
+        /** @type {HostReport} */ ({
+          name,
+          reachable: false,
+          how: 'named in your ssh config and deliberately NOT dialled. Nothing here needs a second machine, and this tool does not connect to yours unasked. `staysfixed doctor --machines` checks them.',
+        })
+    );
+  }
+
   const dialled = await Promise.all(names.slice(0, MAX_HOSTS).map((name) => describeHost(name)));
   // Anything past the cap is NAMED rather than dropped. A machine quietly left out of
   // this list is the same shape of bug as a folder quietly skipped while reading source:
@@ -1776,6 +1808,9 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
  * @property {{name: string, why: string}[]} partly   Looked at, but not completely, and why.
  * @property {{name: string, why: string, whoFixes: SurfaceState}[]} notCovered
  * @property {boolean} everything    True only when nothing at all is left out.
+  * @property {boolean} [canRunHere]
+ *   False when nothing is set up in this folder, so a check cannot run here at all
+ *   whatever this machine could otherwise drive.
  */
 
 /**
@@ -1787,9 +1822,10 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
  * covers your website; your iPhone app is not being checked, and here is why.
  *
  * @param {SurfaceReport[]} surfaces
+ * @param {boolean} setUpHere   Whether a check can actually run in this folder at all.
  * @returns {Covers}
  */
-function whatThisRunActuallyCovers(surfaces) {
+function whatThisRunActuallyCovers(surfaces, setUpHere = true) {
   // Three buckets, not two. Folding "partly" into "covered" is exactly the
   // over-claim this function exists to stop: an iPhone app whose screens cannot
   // be read is not a covered iPhone app.
@@ -1813,7 +1849,23 @@ function whatThisRunActuallyCovers(surfaces) {
 
   /** @type {string[]} */
   const parts = [];
-  parts.push(full.length > 0 ? `A check here covers ${plainList(out.covered)} in full.` : 'A check here covers nothing in full.');
+  // What this MACHINE can drive and what a check in THIS FOLDER would cover are two
+  // different questions, and only one of them was being answered. In an empty folder — no
+  // settings, no code — this said "A check here covers command-line tools and libraries and
+  // web apps and sites in full" and doctor exited 0, while `check` in that same folder
+  // refused to run at all: "No Stays Fixed config found here, so there is nothing to check."
+  // Measured 2026-08-30. `doctor --json` is the first call an agent is told to make, which
+  // is the worst place there is for a sentence with "here" in it to mean somewhere else.
+  //
+  // Everything below still says what it said — a reader needs the whole picture either way —
+  // it is just no longer written as though a check could run.
+  if (!setUpHere) {
+    out.canRunHere = false;
+    parts.push('Nothing is set up in this folder, so a check cannot run here at all and would cover nothing. Run `staysfixed init` first.');
+    parts.push(full.length > 0 ? `Once it is set up, this machine could cover ${plainList(out.covered)} in full.` : 'Even set up, this machine could cover nothing in full.');
+  } else {
+    parts.push(full.length > 0 ? `A check here covers ${plainList(out.covered)} in full.` : 'A check here covers nothing in full.');
+  }
   if (some.length > 0) parts.push(`It covers ${plainList(some.map((s) => s.name))} only partly — read the summary for each before treating a clean result as proof.`);
   if (missing.length > 0) {
     parts.push(`It does NOT check ${plainList(missing.map((s) => s.name))} at all, so a clean result says nothing whatever about ${missing.length === 1 ? 'that' : 'those'}.`);
@@ -1888,8 +1940,15 @@ function nextSteps(surfaces, reference, repo) {
     steps.push({
       what: 'record a reference',
       why: 'Until one build has been recorded there is nothing to compare a new one against, and a clean result would mean nothing.',
-      fix: 'staysfixed check --paired',
-      automatic: true,
+      // Both halves of this were wrong, and they were wrong in the direction that matters.
+      // `check --paired` cannot record a reference — run it twice on a fresh project and
+      // both runs answer that there is no build on record, with the reference id still
+      // empty — so anybody following this went round in a circle. And `automatic: true` told
+      // the agent this was its to do, when the one rule underneath this whole product is
+      // that only shipping cuts a reference and no agent may bless its own work. Saying an
+      // agent can do the single thing it must never do is worse than saying nothing.
+      fix: 'staysfixed ship    (only shipping records what "working" means — no agent may cut that reference)',
+      automatic: false,
       unlocks: 'Every check after this one has something to compare against, so "nothing changed" starts meaning something.',
     });
   }
@@ -2072,7 +2131,7 @@ export function describeCapabilities(caps) {
  * @returns {Promise<number>}
  */
 export async function run(ctx) {
-  const caps = await capabilities({ cwd: ctx.cwd, configFile: ctx.configFile, offline: ctx.bool('offline') });
+  const caps = await capabilities({ cwd: ctx.cwd, configFile: ctx.configFile, offline: ctx.bool('offline'), machines: ctx.bool('machines') });
 
   if (ctx.bool('json')) {
     // Nothing but the object may reach standard output. Doctor is the first call

package/src/v2/escalate.js

@@ -517,7 +517,11 @@ function buildEscalations(product, record, verdict) {
       kind: 'no-reference',
       what: `There is no build of ${product} on record as working yet, so this run had nothing to compare against.`,
       why: 'Only you can say what "working" means, and you say it by shipping — no agent may cut that reference.',
-      todo: 'Ship once with the hook in place. From the next change onwards it is automatic and you will not see this again.',
+      // The order is said out loud because leaving it out sent people round a circle: `ship`
+      // on a build nothing has watched answers "run a check before the next release", and
+      // this line answered "you say it by shipping". Both are true and neither says which
+      // comes first. A check watches the build; shipping then blesses what was watched.
+      todo: 'Run `staysfixed check` once so there is a build to bless, then `staysfixed ship`. From the next change onwards it is automatic and you will not see this again.',
     });
   }
 

package/src/v2/init.js

@@ -824,7 +824,10 @@ function sortNeeds(readiness, project, machine) {
       what: 'one build on record as working',
       why: 'Until one build has been recorded there is nothing to compare a new one against, and a clean result would mean nothing at all.',
       unlocks: 'every check from then on',
-      fix: 'staysfixed check --paired    (or ship once with `staysfixed ship` at the end of your release)',
+      // `check --paired` was named here first, and it does not do this: run it twice on a
+      // fresh project and both runs answer "there is no build on record as working". Only
+      // shipping cuts a reference, on purpose — no agent may bless its own work.
+      fix: 'staysfixed ship    (only shipping records what "working" means — run it once at the end of your release)',
       who: 'the agent',
     });
   }
@@ -1148,7 +1151,10 @@ export function configText(project) {
   w('  // "working" means, so the name is how two of them are told apart.');
   if (project.products.length > 1) {
     w('  // This repository makes more than one thing. A check covers whichever of them the');
-    w('  // settings below describe; run the others with `staysfixed check --product <name>`.');
+    // `--product` is not an option on `check` and never has been. Naming it here sent people
+    // to a flag the CLI rejects, in the settings file the tool itself wrote for them.
+    w('  // settings below describe. To check one of the others, run `staysfixed check` from');
+    w('  // inside that package, or point at its settings with `--config <file>`.');
   }
   w(`  product: ${JSON.stringify(project.name)},`);
   w('');
@@ -1342,7 +1348,12 @@ export function configText(project) {
   } else if (project.pages.length > 0) {
     w(`${webOn}// ${project.pages.length} page address${project.pages.length === 1 ? '' : 'es'} are read out of your folder names automatically — nothing to list here.`);
     w(`${webOn}// Add a screen only for something a walk has to DO rather than just open:`);
-    w(`${webOn}// screens: [{ name: 'signing in', url: '/login', steps: [{ fill: '#email', with: 'a@b.c' }, { click: 'Sign in' }] }],`);
+    // `fill:` and `with:` are not words this tool knows — the verb is `type:` and the value
+    // is `text:`. An unknown key used to be skipped in silence, so this example, handed to
+    // every stranger with a sign-in, filled nothing, clicked Sign in on an empty form, and
+    // then photographed the login page for every screen behind the wall while reporting a
+    // clean run. The example that teaches the vocabulary has to be IN the vocabulary.
+    w(`${webOn}// screens: [{ name: 'signing in', url: '/login', steps: [{ type: '#email', text: 'a@b.c' }, { type: '#password', text: 'secret' }, { click: 'Sign in' }] }],`);
   } else {
     w(`${webOn}// screens: [{ name: 'the front page', url: '/' }],`);
   }
@@ -1568,7 +1579,14 @@ function whatItCovers(readiness) {
   else parts.push('Right now a check here covers nothing in full.');
   if (waiting.length > 0) parts.push(`${plainList(waiting, true)} ${waiting.length === 1 ? 'is' : 'are'} not covered yet, and the list below says exactly what is in the way and who has to do it.`);
   if (notCovered.length > 0) parts.push(`${plainList(notCovered, true)} ${notCovered.length === 1 ? 'is' : 'are'} not checked at all, so a clean result says nothing whatever about ${notCovered.length === 1 ? 'it' : 'them'}.`);
-  if (partly.length === 0 && notCovered.length === 0 && covered.length > 0) parts.push('Nothing is being left out.');
+  // "on this machine", because that is the only thing this sentence knows. It is built from
+  // SURFACES — which kinds of product can be watched here — and says nothing whatever about
+  // how much of this project a run actually walks. Unqualified, it read as a coverage
+  // promise, and `getting-started` tells the agent to repeat it to the person: measured
+  // 2026-08-30 on a project the same run reported as five of six doors never opened.
+  if (partly.length === 0 && notCovered.length === 0 && covered.length > 0) {
+    parts.push('Nothing is being left out on this machine — though how much of the project a run actually walks is a separate question, and every check answers it.');
+  }
 
   // The hole that never closes, named with the language that causes it. "Not covered yet"
   // reads as a job somebody will get to; this one is nobody's job and saying so is the
@@ -1600,9 +1618,14 @@ function nextCommands(readiness, project) {
   if (reachable.length > 0) {
     next.push({
       command: 'staysfixed check --paired',
+      // It does NOT record what "working" means, and saying so here sent everybody round a
+      // loop: run it, be told there is no build on record, run it again, be told the same
+      // thing. Only `ship` cuts a reference — that is the rule the whole product rests on,
+      // because an agent that can bless its own work is not a safety net. So this says what
+      // the run actually does, and `ship` below says what only it can do.
       what: reachable.some((r) => r.state === 'ready')
-        ? 'The first real run. It records what working looks like, so later runs have something to compare against.'
-        : 'The first real run. Nothing here is fully set up yet, so it records what it can reach and says plainly what it left out — which is more useful than waiting.',
+        ? 'The first real run. It walks everything and shows you what it sees. It cannot record what "working" means — only shipping does that.'
+        : 'The first real run. Nothing here is fully set up yet, so it walks what it can reach and says plainly what it left out — which is more useful than waiting.',
     });
   }
   if (project.tests.files > 0) {