staysfixed 0.7.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers — as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",
@@ -55,6 +55,7 @@
   },
   "dependencies": {
     "pixelmatch": "^7.2.0",
+    "playwright-core": "^1.56.0",
     "pngjs": "^7.0.0"
   },
   "devDependencies": {

package/src/cli/index.js

@@ -12,6 +12,8 @@ import { setLogLevel } from '../core/log.js';
 import { V2_COMMANDS } from '../v2/cli.js';
 import { SHIP_COMMANDS } from '../v2/ship.js';
 import { INIT_COMMANDS } from '../v2/init.js';
+import { BROWSERS_COMMAND } from '../v2/browsers.js';
+export { watchFlags } from './watch-flags.js';
 
 /** @type {{version?: string}} */
 const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
@@ -61,9 +63,22 @@ export const VERSION = pkg.version ?? '0.0.0';
  * @property {() => Promise<{run: (ctx: CliContext) => Promise<number>}>} [load]
  */
 
-/** @type {ArgSpec} */
+/**
+ * The flags every command takes.
+ *
+ * `no-color` is declared as its own switch rather than as `color`, and that is not a
+ * spelling choice. Colour is settled in bin/staysfixed.js, before anything else is
+ * imported, because src/core/log.js decides once at load whether it may paint — so by the
+ * time a command is parsed the answer is already fixed and nothing here could change it.
+ * Declaring `color` made `--color` a real flag that turned nothing on, which is the worst
+ * kind: a person types it, the tool accepts it, and nothing happens. There is no way to
+ * force colour ON from here, so the only honest thing to offer is the half that works.
+ * `--no-color` is named so `--help` and the parser agree; the work is already done.
+ *
+ * @type {ArgSpec}
+ */
 const GLOBAL_SPEC = {
-  booleans: ['verbose', 'quiet', 'help', 'version', 'color'],
+  booleans: ['verbose', 'quiet', 'help', 'version', 'no-color'],
   strings: ['config', 'cwd'],
   alias: { v: 'verbose', q: 'quiet', h: 'help', V: 'version' },
 };
@@ -76,7 +91,7 @@ const GLOBAL_VALUE_FLAGS = new Set(['--config', '--cwd']);
  * are declared once here so the two commands cannot drift apart.
  */
 const WATCH_SPEC = {
-  booleans: ['watch', 'watch-front', 'keep-open', 'profile'],
+  booleans: ['watch', 'watch-front', 'keep-open', 'profile', 'snap'],
   strings: ['watch-side', 'watch-width'],
 };
 
@@ -86,12 +101,20 @@ const WATCH_OPTIONS = [
   ['--watch-side <side>', 'Which side of the app the panel sits on: left or right. Default right.'],
   ['--watch-width <n>', 'How wide the panel is, in pixels. Default 460.'],
   ['--no-keep-open', 'Close the panel as soon as the run finishes.'],
+  ['--no-snap', 'Leave both windows exactly where they are instead of putting them side by side.'],
   ['--watch-front', 'Bring the panel to the front. By default it opens behind your work.'],
   ['--profile', 'Print where the time went when the run is over.'],
 ];
 
-/** @type {Record<string, CommandEntry>} */
-const COMMANDS = {
+/**
+ * Every command, and the only list of them. `--help` is printed from this, and every
+ * flag any command accepts is declared in its `spec` here — so a flag that prints in the
+ * help and a flag the parser knows about cannot drift apart. It is exported so that can
+ * be checked from outside rather than by reading two lists side by side.
+ *
+ * @type {Record<string, CommandEntry>}
+ */
+export const COMMANDS = {
   init: {
     summary: 'Set this project up. Takes about thirty seconds.',
     usage: 'staysfixed init [--force] [--json]',
@@ -227,6 +250,16 @@ const COMMANDS = {
     examples: ['staysfixed mcp', 'staysfixed mcp --v1'],
     spec: { booleans: ['v1'] },
   },
+
+  /*
+   * `browsers` was written, tested, given a finished command entry in src/v2/browsers.js
+   * with a comment saying "wiring it up is one line" — and that line was never written.
+   * README.md told people to run `npx staysfixed browsers` and `--clean` to tidy up after
+   * an interrupted run, and both answered "There is no command called browsers". Somebody
+   * whose disk was filling with abandoned browser profiles had no way to clear them and no
+   * reason to doubt the page telling them there was.
+   */
+  browsers: BROWSERS_COMMAND,
 };
 
 /*
@@ -352,45 +385,8 @@ function contextFor(parsed, cwd, configFile) {
  * @property {boolean} [foreground]
  */
 
-/**
- * Read the panel flags. Shared by `check` and `walk` so the two behave the same.
- * @param {CliContext} ctx
- * @returns {WatchFlags}
- */
-export function watchFlags(ctx) {
-  /** @type {WatchFlags} */
-  const flags = { enabled: ctx.bool('watch') };
-
-  const side = ctx.str('watch-side');
-  if (side !== undefined) {
-    if (side !== 'left' && side !== 'right') {
-      throw new StaysFixedError(`--watch-side has to be left or right, not "${side}".`, {
-        hint: 'Write it as `--watch-side left` or `--watch-side right`.',
-      });
-    }
-    flags.side = side;
-  }
-
-  const width = ctx.str('watch-width');
-  if (width !== undefined) {
-    const n = Number(width);
-    // A panel narrower than this cannot show the before-and-after pictures side
-    // by side, which is the only reason to open it.
-    if (!Number.isFinite(n) || n < 240) {
-      throw new StaysFixedError(`--watch-width has to be a number of pixels, 240 or more — I got "${width}".`, {
-        hint: 'Write it as `--watch-width 520`.',
-      });
-    }
-    flags.width = Math.round(n);
-  }
+// `watchFlags` moved to ./watch-flags.js — see the note there about the import cycle.
 
-  // Only mention these when they were actually typed, so --no-keep-open turns the
-  // panel off at the end without a bare --watch turning it on against the settings.
-  if (ctx.flags['keep-open'] !== undefined) flags.keepOpen = ctx.flags['keep-open'] === true;
-  if (ctx.bool('watch-front')) flags.foreground = true;
-
-  return flags;
-}
 
 /**
  * The panel settings a project's settings file carries, if it carries any.
@@ -446,15 +442,28 @@ function splitCommand(argv) {
 }
 
 /**
+ * The global flags plus one command's own — with the command winning any name they share.
+ *
+ * That last part is the whole reason this is not a concatenation. `--version` is global and
+ * means "print the tool's version"; `staysfixed ship --version 0.14.0` means "the release
+ * that went out was called 0.14.0", and it is in that command's own help. Merged naively,
+ * the name landed in both lists, the parser reads booleans first, and `staysfixed ship
+ * --version 0.14.0` printed `0.7.2` and shipped nothing at all — no error, no clue, and the
+ * release script that called it carried on. A command's own list of flags is the more
+ * specific statement of what that command means, so it wins.
+ *
  * @param {ArgSpec} base
  * @param {ArgSpec} extra
  * @returns {ArgSpec}
  */
 function mergeSpec(base, extra) {
+  const claimed = new Set([...(extra.booleans ?? []), ...(extra.strings ?? []), ...(extra.arrays ?? [])]);
+  /** @param {string[]|undefined} names */
+  const keep = (names) => (names ?? []).filter((name) => !claimed.has(name));
   return {
-    booleans: [...(base.booleans ?? []), ...(extra.booleans ?? [])],
-    strings: [...(base.strings ?? []), ...(extra.strings ?? [])],
-    arrays: [...(base.arrays ?? []), ...(extra.arrays ?? [])],
+    booleans: [...keep(base.booleans), ...(extra.booleans ?? [])],
+    strings: [...keep(base.strings), ...(extra.strings ?? [])],
+    arrays: [...keep(base.arrays), ...(extra.arrays ?? [])],
     alias: { ...(base.alias ?? {}), ...(extra.alias ?? {}) },
   };
 }

package/src/cli/status.js

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

package/src/cli/watch-flags.js

@@ -0,0 +1,54 @@
+/**
+ * Reading the --watch flags off a command line.
+ *
+ * This lives on its own, and not in `src/cli/index.js` where it started, because both
+ * halves of the tool need it and the import went in a circle: version 1's command table
+ * imports version 2's commands, and version 2's command file imported this back out of
+ * version 1's table. That worked only while the modules happened to load in a helpful
+ * order — the day another import was added to version 2, the whole command line failed
+ * with "cannot access V2_COMMANDS before initialization" and nothing ran at all.
+ *
+ * A shared thing that both sides need belongs to neither of them.
+ */
+
+import { StaysFixedError } from '../core/errors.js';
+
+/**
+ * Read the panel flags. Shared by `check` and `walk` so the two behave the same.
+ * @param {import('./index.js').CliContext} ctx
+ * @returns {import('./index.js').WatchFlags}
+ */
+export function watchFlags(ctx) {
+  /** @type {import('./index.js').WatchFlags} */
+  const flags = { enabled: ctx.bool('watch') };
+
+  const side = ctx.str('watch-side');
+  if (side !== undefined) {
+    if (side !== 'left' && side !== 'right') {
+      throw new StaysFixedError(`--watch-side has to be left or right, not "${side}".`, {
+        hint: 'Write it as `--watch-side left` or `--watch-side right`.',
+      });
+    }
+    flags.side = side;
+  }
+
+  const width = ctx.str('watch-width');
+  if (width !== undefined) {
+    const n = Number(width);
+    // A panel narrower than this cannot show the before-and-after pictures side
+    // by side, which is the only reason to open it.
+    if (!Number.isFinite(n) || n < 240) {
+      throw new StaysFixedError(`--watch-width has to be a number of pixels, 240 or more — I got "${width}".`, {
+        hint: 'Write it as `--watch-width 520`.',
+      });
+    }
+    flags.width = Math.round(n);
+  }
+
+  // Only mention these when they were actually typed, so --no-keep-open turns the
+  // panel off at the end without a bare --watch turning it on against the settings.
+  if (ctx.flags['keep-open'] !== undefined) flags.keepOpen = ctx.flags['keep-open'] === true;
+  if (ctx.bool('watch-front')) flags.foreground = true;
+
+  return flags;
+}

package/src/core/config.js

@@ -49,9 +49,29 @@ export const DEFAULT_FREEZE = {
 
 /** @type {Required<Omit<import('../types.js').ToleranceConfig,'maxPixels'>>} */
 export const DEFAULT_TOLERANCE = {
-  // 0.05% of pixels. On a 1440x900 @2x picture that is about 1300 pixels — enough
-  // for font hinting noise, nowhere near enough to hide a missing stylesheet.
-  pixels: 0.0005,
+  // Nothing is allowed through by default, and that is a change made after measuring.
+  //
+  // This used to be 0.0005 — 0.05% of the picture — with a comment saying it was "enough for
+  // font hinting noise, nowhere near enough to hide a missing stylesheet". The first half was
+  // a guess and the second half was wrong. On a 2880x1800 picture, 0.05% is **2,592 pixels**.
+  // Changing `<h1>Welcome</h1>` to `<h1>Welcom</h1>` — one letter missing from the main
+  // heading of the page, plainly visible to anybody looking at it — moves **593**. So the
+  // check reported "Everything that worked still works" over a page that was visibly wrong.
+  // That is the exact failure this tool exists to prevent, produced by the tool itself.
+  //
+  // The number that replaces it was measured rather than chosen. Ten fresh takes of the same
+  // build, on a real page, compared against the approved picture: **zero differing pixels,
+  // every time.** The freeze layer underneath — the stopped clock, the killed motion, the
+  // seeded randomness, the pinned text rendering, and the settle loop that keeps shooting
+  // until two frames come back identical — is what makes that true. Where nothing wobbles,
+  // an allowance buys nothing at all and costs you the one thing you came for.
+  //
+  // Version 2 answers this properly by measuring each product's own wobble and subtracting
+  // it, which is why it has no tolerance setting and never will. Version 1 cannot do that
+  // without becoming version 2, so it does the honest next-best thing: allow nothing, and
+  // let a project that genuinely wobbles say so out loud with `tolerance.pixels`. A run that
+  // uses an allowance now says so, and says how much of it was used.
+  pixels: 0,
   threshold: 0.12,
   antialiasing: true,
 };
@@ -126,6 +146,27 @@ export function resolveConfig(raw, file = '(inline)') {
   }
   const c = /** @type {import('../types.js').StaysFixedConfig} */ (raw);
 
+  // Version 2's settings describe a website under `web:` and a desktop app under
+  // `electron:`. These commands are version 1's and only ever knew about `app:` — so on the
+  // settings file `staysfixed init` writes for a website, `status`, `walk` and `flake` all
+  // answered "these settings do not name anything to open", and then listed `process,
+  // source` as the shape of the project. `init` had said, one command earlier, "The website
+  // can be checked here now ... watched by opening it in a throwaway browser". Both about
+  // the same file, seconds apart, and `status` is the command whose whole promise is to say
+  // instantly what is set up here.
+  //
+  // Where the address is actually knowable, take it and let the command work. Booting is
+  // version 2's job and these commands cannot do it, so `web.start` alone is not enough —
+  // that case falls through to the message below, which now says so honestly.
+  if ((!c.app || typeof c.app !== 'object')) {
+    const v2 = /** @type {Record<string, any>} */ (/** @type {unknown} */ (c));
+    if (v2.web && typeof v2.web === 'object' && typeof v2.web.url === 'string' && v2.web.url) {
+      c.app = { kind: 'web', url: v2.web.url };
+    } else if (v2.electron && typeof v2.electron === 'object' && typeof v2.electron.binary === 'string' && v2.electron.binary) {
+      c.app = { kind: 'electron', binary: v2.electron.binary };
+    }
+  }
+
   if (!c.app || typeof c.app !== 'object') {
     // Every command that lands here — status, walk, approve, mark, trace, flake, and
     // `check --pictures` — works by OPENING something and photographing it. A settings
@@ -135,6 +176,16 @@ export function resolveConfig(raw, file = '(inline)') {
     // half of the tool needs it, and names the half that does not.
     const anything = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (c));
     const notVisual = ['process', 'http', 'source', 'android', 'ios', 'windows'].filter((k) => anything[k] && typeof anything[k] === 'object');
+    // A project that DOES have a screen, described the version 2 way, must never be told it
+    // has none. It is told the true thing instead: this half of the tool photographs an
+    // address you can point it at, and version 2 finds the address by booting the product,
+    // which is why `check` covers it and these do not.
+    const started = anything.web && typeof anything.web === 'object' && typeof (/** @type {any} */ (anything.web).start) === 'string';
+    if (started) {
+      throw new StaysFixedError('This project has a website, but these settings start it rather than name an address, and this command photographs an address.', {
+        hint: "`staysfixed check` covers it exactly as it is — it boots `web.start` and finds the address itself. These picture commands need one they can point at, so add `url: 'http://localhost:3000'` beside `start` in the `web` block if you want them too.",
+      });
+    }
     throw new StaysFixedError('These settings do not name anything to open, and this command works by opening your product and photographing it.', {
       hint: notVisual.length
         ? `That is the right shape for what this project is — ${notVisual.join(', ')} settings need nothing to open. Run \`staysfixed check\`, which covers it without a picture. If there IS a screen here too, add \`app: { kind: 'web', url: 'http://localhost:3000' }\` or \`app: { kind: 'electron', binary: '...' }\`.`

package/src/core/paths.js

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

package/src/guard/run.js

@@ -28,6 +28,7 @@ const FRESH_KEY = 'fresh';
 /**
  * @typedef {import('../types.js').GuardResult & {
  *   retriedToPass?: boolean,
+ *   assertedNothing?: boolean,
  *   checks?: import('../types.js').CheckStep[],
  * }} GuardRunResult
  */
@@ -136,10 +137,22 @@ export async function runGuards(project, app, guards, opts = {}) {
       if (opts.signal?.aborted) break;
     }
 
+    // A guard that asserted NOTHING has not held. It cannot hold, and it cannot fail — it is
+    // a name over an empty room. Measured on 2026-08-30: a guard called "the checkout total
+    // is never charged twice", whose `run()` was an empty function, came back as
+    // "ok ... still holds". That is a false all-clear wearing the friendliest face this tool
+    // has, and it would go on saying it every day for ever. The whole promise here is one
+    // plain-English rule per bug somebody already had; a rule that checks nothing is worse
+    // than no rule, because somebody believes it.
+    // Its OWN questions, not the runner's. Every guard gets a "fresh start" step from this
+    // file whether it asks anything or not, so counting the whole list would always find one.
+    const asked = checks.filter((c) => c.key !== FRESH_KEY && !String(c.key ?? '').endsWith(`-${FRESH_KEY}`));
+    const assertedNothing = outcome.ok && asked.length === 0;
+
     /** @type {GuardRunResult} */
     const result = {
       name: guard.name,
-      status: outcome.ok ? 'passed' : 'failed',
+      status: outcome.ok && !assertedNothing ? 'passed' : 'failed',
       file: guard.file,
       because: guard.because,
       durationMs: Date.now() - startedAt,
@@ -147,7 +160,13 @@ export async function runGuards(project, app, guards, opts = {}) {
     };
     if (checks.length > 0) result.checks = checks;
 
-    if (outcome.ok) {
+    if (assertedNothing) {
+      result.assertedNothing = true;
+      result.message =
+        `This guard checked nothing. Its \`run()\` finished without asking a single question, so it cannot fail ` +
+        `and it is not protecting anything — it would report "still holds" every day for ever. ` +
+        `Give it at least one \`expect(...)\`. ${guard.because ? `What it is meant to protect: ${guard.because}` : ''}`.trim();
+    } else if (outcome.ok) {
       // Passing only on the second go is not passing. The flake register picks
       // this up and condemns the guard, because a guard nobody trusts is worse
       // than no guard: people learn to re-run it until it goes green.
@@ -289,7 +308,7 @@ async function attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep) {
       };
     }
     const raw = error instanceof Error ? error.message : String(error);
-    return { ok: false, message: `${raw}${consoleNote(app)}` };
+    return { ok: false, message: `${explainApiSlip(raw, app.page, project)}${consoleNote(app)}` };
   } finally {
     // The losing side of the race keeps running otherwise, and a stray timer
     // holds the process open long after the run is reported.
@@ -299,6 +318,54 @@ async function attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep) {
   return { ok: true };
 }
 
+/**
+ * Turn "page.goto is not a function" into one sentence a person can act on.
+ *
+ * A guard is the first code most people write against this tool, and the object it is handed
+ * is not the shape anybody arrives expecting. Reach for a name from a browser library that is
+ * not there and JavaScript answers with its own sentence, which is true, useless, and exactly
+ * the kind of raw error this project promises never to print. The first guard written against
+ * it while proving the tool still worked failed this way.
+ *
+ * Two things it must not do, both learned by getting them wrong first:
+ *
+ *  - **Do not trust the receiver's name.** The guard above called its one parameter `page`,
+ *    so the error read `page.goto is not a function` — but the parameter holds `app`, and the
+ *    honest answer is `app.open()`. Reading that name as if it meant the page suggested
+ *    "did you mean goto()", which is the very thing they had just written.
+ *  - **Do not list every method.** An earlier version printed all thirty names on the page
+ *    handle inline. It was complete, unreadable, and it destroyed the results table it sat in.
+ *
+ * So: name the six things on `app`, say where the rest live, and stop.
+ *
+ * @param {string} raw
+ * @param {import('../types.js').PageHandle} page
+ * @param {import('../types.js').Project} project
+ * @returns {string}
+ */
+export function explainApiSlip(raw, page, project) {
+  const missing = /^(?:\w+\.)?(\w+) is not a function$/.exec(String(raw || ''));
+  if (!missing) return raw;
+  const method = missing[1];
+  const api = makeGuardApi(page, project, {});
+  const onApp = Object.keys(api).filter((k) => typeof (/** @type {any} */ (api))[k] === 'function').sort();
+  if (onApp.includes(method)) return raw;
+
+  // Only ever suggested from what `app` itself offers, and only when one name is clearly the
+  // one meant. A guess between three is worse than no guess.
+  const near = onApp.filter((n) => n.toLowerCase().includes(method.toLowerCase()) || method.toLowerCase().includes(n.toLowerCase()));
+  const browserish = /^(goto|navigate|visit|load|open|click|type|fill|press|hover|wait|screenshot|querySelector|\$)/i.test(method);
+  const meant = near.length === 1 ? ` You probably want \`app.${near[0]}()\`.`
+    : browserish ? ' To go to a page it is `app.open(\'/path\')`; anything a browser does is on `app.page`.'
+    : '';
+
+  return (
+    `This guard called \`${method}()\` on what it was handed, and there is no such thing there.${meant} ` +
+    `A guard is given one object — call it \`app\` — with ${onApp.map((n) => `\`${n}()\``).join(', ')}. ` +
+    'The whole page is `app.page`. There is a worked example in `examples/guards/`.'
+  );
+}
+
 /** A timeout, kept apart from a real error so the wording stays ours. */
 class TookTooLong extends Error {
   /** @param {string} message */

package/src/report/console.js

@@ -124,7 +124,11 @@ function tally(run) {
     missing: pictures.filter((p) => p.status === 'missing').length,
     broken: pictures.filter((p) => p.status === 'failed').length,
     wobbled: pictures.filter((p) => p.status === 'flaky').length,
-    guardsFailed: guards.filter((g) => g.status === 'failed').length,
+    // Two different things wear the same status, and calling both of them "a bug is back"
+    // sends somebody hunting a regression that never happened. A guard that asked no
+    // question at all has not caught anything; it has admitted it cannot.
+    guardsFailed: guards.filter((g) => g.status === 'failed' && !(/** @type {any} */ (g).assertedNothing)).length,
+    guardsEmpty: guards.filter((g) => /** @type {any} */ (g).assertedNothing === true).length,
   };
 }
 
@@ -139,6 +143,20 @@ export function verdictFor(run) {
   const parts = [];
   if (t.guardsFailed === 1) parts.push({ n: 1, text: '1 guard failed — a bug that was already fixed is back.' });
   else if (t.guardsFailed > 1) parts.push({ n: t.guardsFailed, text: `${countText(t.guardsFailed)} guards failed — bugs that were already fixed are back.` });
+  // Said even on a green run, because that is the run it changes the meaning of.
+  const left = /** @type {any} */ (run).leftOut;
+  if (left && (left.screens > 0 || left.guards > 0)) {
+    const bits = [];
+    if (left.screens > 0) bits.push(`${left.screens} ${left.screens === 1 ? 'screen' : 'screens'}`);
+    if (left.guards > 0) bits.push(`${left.guards} ${left.guards === 1 ? 'guard' : 'guards'}`);
+    const how_many = (left.screens ?? 0) + (left.guards ?? 0);
+    parts.push({
+      n: 0,
+      text: `${bits.join(' and ')} ${how_many === 1 ? 'was' : 'were'} left out by --only, so this covers a slice and not the whole.`,
+    });
+  }
+  if (t.guardsEmpty === 1) parts.push({ n: 1, text: '1 guard checks nothing, so it is not protecting anything.' });
+  else if (t.guardsEmpty > 1) parts.push({ n: t.guardsEmpty, text: `${countText(t.guardsEmpty)} guards check nothing, so they are not protecting anything.` });
   if (t.changed === 1) parts.push({ n: 1, text: '1 thing changed. Look at it before you ship.' });
   else if (t.changed > 1) parts.push({ n: t.changed, text: `${countText(t.changed)} things changed. Look at them before you ship.` });
   if (t.fresh === 1) parts.push({ n: 1, text: '1 new screen is waiting for a person to approve it.' });
@@ -162,9 +180,12 @@ export function verdictFor(run) {
  * @param {import('../types.js').RunSummary} run
  * @returns {boolean}
  */
-function allClear(run) {
+export function allClear(run) {
   const t = tally(run);
-  return t.changed + t.fresh + t.missing + t.broken + t.wobbled + t.guardsFailed === 0;
+  // `guardsEmpty` counts too. Splitting it out of `guardsFailed` was so the SENTENCE could
+  // tell a returned bug from a guard that asks nothing — not so that one of them could
+  // quietly become a pass.
+  return t.changed + t.fresh + t.missing + t.broken + t.wobbled + t.guardsFailed + t.guardsEmpty === 0;
 }
 
 /**
@@ -210,9 +231,22 @@ export function printPictureResult(r) {
   const time = paint.grey(duration(r.durationMs ?? 0));
   const line = `${r.name.padEnd(NAME_WIDTH)} ${pictureOutcome(r)}`;
   switch (r.status) {
-    case 'passed':
-      say(`${paint.green(sym(mark.pass))} ${r.name.padEnd(NAME_WIDTH)} ${paint.grey('still the same')} ${time}`);
+    case 'passed': {
+      // "Still the same" has to mean the same, or it is the most expensive sentence here.
+      //
+      // A picture that differs and is waved through by an allowance was reported as
+      // identical, in the same words as one that matched byte for byte. That is how a
+      // missing letter in a heading — 593 pixels, plainly visible — came back as "still the
+      // same" while an allowance of 2,592 quietly absorbed it. Nothing is allowed through by
+      // default any more, so this is rare; when a project sets `tolerance.pixels` because its
+      // product genuinely wobbles, the line says what its setting just swallowed.
+      const swallowed = r.diffPixels ?? 0;
+      const note = swallowed > 0
+        ? paint.grey(`the same, apart from ${swallowed} ${swallowed === 1 ? 'pixel your tolerance allowed' : 'pixels your tolerance allowed'}`)
+        : paint.grey('still the same');
+      say(`${paint.green(sym(mark.pass))} ${r.name.padEnd(NAME_WIDTH)} ${note} ${time}`);
       break;
+    }
     case 'changed':
       say(`${paint.red(sym(mark.fail))} ${paint.red(line)} ${time}`);
       if (r.approvedSize && r.size && (r.approvedSize.width !== r.size.width || r.approvedSize.height !== r.size.height)) {
@@ -548,6 +582,8 @@ export function printFlakes(history, flakeLimit = 2) {
  * @property {number} [markers]       Known-good markers saved.
  * @property {{label: string, at?: string}|null} [lastMarker]
  * @property {import('../types.js').RunSummary|null} [lastRun]
+ * @property {{at: string, verdict: string, reference: string|null, findings: number}|null} [v2]
+ *   What version 2 has recorded here. Version 1's counts say nothing about it.
  * @property {string[]} [condemned]   Names from the flake register, if the CLI already has them.
  * @property {string} [configFile]
  * @property {string} [root]
@@ -578,7 +614,15 @@ export function printStatus(status) {
 
   blank();
   const run = s.lastRun ?? null;
-  if (!run) {
+  if (!run && s.v2) {
+    // Version 2 has run here even though version 1's picture record has not. Saying
+    // "nothing has been checked here yet" one command after a real run is the sort of
+    // wrongness that costs a person their trust in everything else the tool says.
+    say(paint.grey(`  last checked ${ago(s.v2.at)} — ${s.v2.verdict}`));
+    if (s.v2.findings > 0) say(paint.grey(`  ${s.v2.findings} ${plural(s.v2.findings, 'thing', 'things')} nobody had accounted for`));
+    if (s.v2.reference) say(paint.grey(`  compared against ${s.v2.reference}`));
+    else say(`  Nothing is on record as working yet — run ${paint.cyan('staysfixed check')}, then ${paint.cyan('staysfixed ship')}.`);
+  } else if (!run) {
     say('  Nothing has been checked here yet.');
     say(`  Start with: ${paint.cyan('staysfixed check')}`);
   } else {

package/src/run.js

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

package/src/types.js

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

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

@@ -1393,8 +1393,13 @@ export async function permissionsHeld(device, pkg) {
  * and pids are stripped from the text kept, since all three differ on every run and none of
  * them is ever the finding.
  *
+ * There is no time window here, and there used to be a `sinceMs` in this signature that
+ * nothing read. The window comes from the other end: the adapter clears both log buffers
+ * before it walks anything, so what is left is this run. An option that silently does
+ * nothing is worse than no option, because a caller passing it believes it worked.
+ *
  * @param {Device} device
- * @param {{pkg: string, pid?: number, sinceMs?: number}} what
+ * @param {{pkg: string, pid?: number}} what
  * @returns {Promise<{crashes: string[], anrs: string[], errors: string[], lines: string[], raw: string}>}
  */
 export async function complaints(device, what) {