staysfixed 0.9.1 → 0.11.0

package/src/guard/run.js

@@ -16,7 +16,7 @@
  * this one is not" is most of the value of running it at all.
  */
 
-import { makeGuardApi, ExpectationFailed } from './api.js';
+import { makeGuardApi, ExpectationFailed, GuardAbandoned } from './api.js';
 import { resetWindow } from '../drive/launch.js';
 import { emitEvent } from '../core/events.js';
 
@@ -29,6 +29,7 @@ const FRESH_KEY = 'fresh';
  * @typedef {import('../types.js').GuardResult & {
  *   retriedToPass?: boolean,
  *   assertedNothing?: boolean,
+ *   timedOut?: boolean,
  *   checks?: import('../types.js').CheckStep[],
  * }} GuardRunResult
  */
@@ -38,6 +39,8 @@ const FRESH_KEY = 'fresh';
  * @property {boolean} ok
  * @property {string} [message]
  * @property {string} [failedAt]
+ * @property {boolean} [timedOut]  The clock ran out before the guard answered. Not the same
+ *                                 as the answer being no — see the note on the result below.
  */
 
 /** @typedef {(step: import('../types.js').CheckStep) => void} StepSink */
@@ -162,10 +165,31 @@ export async function runGuards(project, app, guards, opts = {}) {
 
     if (assertedNothing) {
       result.assertedNothing = true;
+      // The story of the bug is not repeated in here. It travels on `because`, and the console,
+      // the HTML report, the MCP answer and the live panel each print it themselves — so
+      // putting it in the message too printed it twice on one screen.
       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();
+        `Give it at least one \`expect(...)\`.`;
+    } else if (outcome.timedOut) {
+      // A third thing wearing the same status, for the same reason as the second one.
+      // Measured on 2026-08-31 against a healthy shop with three guards — one genuinely broken,
+      // one whose `run()` slept six seconds against its own limit of one and a half: the run
+      // announced "2 guards failed — bugs that were already fixed are back." One bug was back.
+      // The other guard was never answered, and somebody reading that line goes hunting a
+      // regression in checkout that never happened. Running out of time is the guard failing to
+      // report, not the product failing — the same distance as "nothing changed" from "nothing
+      // was compared".
+      //
+      // The status stays 'failed' on purpose. A question nobody got an answer to must never
+      // count as a pass, or a stuck guard becomes the quietest way there is to go green. The
+      // flag is what lets the words be right without letting the verdict go soft.
+      result.timedOut = true;
+      result.message = outcome.message ?? 'This guard ran out of time before it answered.';
+      // The story of the original bug is deliberately left off. It is printed beside every
+      // failure to say whether the failure matters — and here nothing yet says the bug is
+      // back, so leading with its story is the exact wrong impression to give.
     } 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
@@ -173,7 +197,11 @@ export async function runGuards(project, app, guards, opts = {}) {
       if (attempts > 1) result.retriedToPass = true;
     } else {
       if (outcome.failedAt) result.failedAt = outcome.failedAt;
-      result.message = withStory(outcome.message ?? 'This guard failed.', guard.because);
+      // Said once. The story of the original bug used to be appended here as well, and every
+      // renderer prints `because` on its own line underneath — so a failing guard showed the
+      // same sentence twice, with a blank line in the middle of the message that broke the
+      // one-line-per-guard layout and the results table under it. Measured 2026-08-31.
+      result.message = outcome.message ?? 'This guard failed.';
     }
 
     results.push(result);
@@ -221,6 +249,11 @@ function emitGuardDone(events, result) {
     message: result.message,
     failedAt: result.failedAt,
     because: result.because,
+    // Three different things wear the status 'failed', and a watcher that only sees the
+    // status calls all three "broken again". The result knows which it was; until this went
+    // out with it, only the terminal did.
+    timedOut: result.timedOut,
+    assertedNothing: result.assertedNothing,
     // Everything this guard actually asserted, in its own words and its own
     // order — so a listener that arrived late, or one that only keeps the
     // verdicts, still has the working.
@@ -243,12 +276,30 @@ async function attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep) {
   /** @type {ReturnType<typeof setTimeout>|undefined} */
   let timer;
 
+  /**
+   * Losing the race below does not stop the loser, so this is what does.
+   *
+   * Measured on 2026-08-31: a guard with `timeoutMs: 200` whose body ticked every 25
+   * milliseconds had written 7 lines to a file by the time the run reported it, and 26 half
+   * a second later. It was still clicking, still reading, still holding the page — behind a
+   * run that had already printed its verdict and started the guard after it. That is how one
+   * slow guard makes the next three wobble, and the wobble is blamed on the product.
+   *
+   * A promise cannot be taken back in JavaScript. What can be done is shut every door the
+   * guard reaches the app through: from here on `app.open`, `app.click`, `app.expect`,
+   * `app.run`, `app.read` and everything on `app.page` refuse, so the body unwinds at its
+   * very next step, and a shell command it started is killed rather than left running.
+   */
+  const givenUp = new AbortController();
+
   /**
    * @param {import('../types.js').CheckStep} step
    * @returns {void}
    */
   const tell = (step) => {
-    if (!onStep) return;
+    // Nothing is said on behalf of a guard the run has already reported. A step arriving
+    // after the verdict reads, to anything watching, as a guard that is still going.
+    if (!onStep || givenUp.signal.aborted) return;
     try {
       onStep(step);
     } catch {
@@ -291,10 +342,20 @@ async function attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep) {
         });
 
         clearConsole(app);
-        await guard.run(makeGuardApi(app.page, project, onStep ? { onStep } : {}));
+        // The clock can run out during the clean start, on a page that will not load. Starting
+        // a body the run has already given up on would put a second guard on the same page.
+        if (givenUp.signal.aborted) {
+          throw new GuardAbandoned('The run gave up on this guard before its body ever started.');
+        }
+        await guard.run(
+          makeGuardApi(app.page, project, onStep ? { onStep, signal: givenUp.signal } : { signal: givenUp.signal }),
+        );
       })(),
       new Promise((_resolve, reject) => {
         timer = setTimeout(() => {
+          // Given up on FIRST, then reported. The other way round leaves a gap in which the
+          // run has moved on and the guard is still driving the app.
+          givenUp.abort();
           reject(new TookTooLong(`'${guard.name}' did not finish within ${humanSeconds(timeoutMs)}.`));
         }, timeoutMs);
       }),
@@ -307,12 +368,35 @@ async function attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep) {
         message: `This should still be true, and it is not: "${error.claim}".${consoleNote(app)}`,
       };
     }
+    // Out of time is its own answer, and it is not "no". The guard was still going when the
+    // clock stopped, so all anyone knows is that nobody asked it anything it managed to
+    // finish. Said in those words rather than as a returned bug.
+    if (error instanceof TookTooLong || error instanceof GuardAbandoned) {
+      return {
+        ok: false,
+        timedOut: true,
+        message:
+          `This guard ran out of time after ${humanSeconds(timeoutMs)} and never gave an answer, so nothing ` +
+          `here says the bug is back — only that the guard could not be asked. Either it genuinely needs ` +
+          `longer than its own \`timeoutMs\`, or it is waiting for something that never arrives. ` +
+          // Precisely what was done about it, and no more. The doors are shut, which is the
+          // only stopping there is; a sleep or a request the guard is sitting inside still has
+          // to finish by itself, and claiming otherwise would be its own small lie.
+          `Its \`run()\` has been cut off — every step it takes through \`app\` from here refuses — so it ` +
+          `cannot go on driving the app behind the rest of the run.${consoleNote(app)}`,
+      };
+    }
     const raw = error instanceof Error ? error.message : String(error);
-    return { ok: false, message: `${explainApiSlip(raw, app.page, project)}${consoleNote(app)}` };
+    return { ok: false, message: `${explainApiSlip(plainly(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.
     if (timer) clearTimeout(timer);
+    // One attempt owns the app only while it is being awaited. Whatever is still in flight
+    // when this returns — a timed-out body, a step a guard started and never waited for — is
+    // given up on here, so it cannot touch the app that the next guard, or the next attempt
+    // at this one, is about to use.
+    givenUp.abort();
   }
 
   return { ok: true };
@@ -366,6 +450,65 @@ export function explainApiSlip(raw, page, project) {
   );
 }
 
+/**
+ * Fragments that only ever come out of the debugging protocol talking to itself.
+ *
+ * Chrome's parameter reader answers in its own vocabulary — the byte it got stuck on, the
+ * name of an internal binding, a JSON-RPC error number. Measured on 2026-08-31: a guard that
+ * passed the wrong sort of value to `app.page.send` failed with `Invalid parameters (Failed to
+ * deserialize params.expression - BINDINGS: string value expected at position 19)` printed at
+ * the person as the whole explanation. Nothing in the bracket is about their app, their guard
+ * or their bug.
+ */
+const PROTOCOL_CHATTER = /Failed to deserialize|BINDINGS:|at position \d|-32\d{3}|"method"\s*:|"params"\s*:/;
+
+/** Past this a failure message stops being something anyone reads and starts being a wall. */
+const MAX_MESSAGE = 400;
+
+/**
+ * Say a failure in words, with the machinery's own muttering taken out.
+ *
+ * Three things had to go, all of them seen printed at somebody:
+ *
+ *  - **More than one line.** A stack trace, a browser library's "Call log" block or a dump of
+ *    the debugging protocol all arrive as one long message with newlines in it, and the
+ *    results table this sits inside is built of rows — the second line lands in the next
+ *    column and the table comes apart. The same lesson `explainApiSlip` above learned by
+ *    printing thirty method names inline.
+ *  - **The protocol's own diagnostics**, which Chrome hangs off the end in brackets.
+ *  - **`[object Object]`**, which is what a guard that throws something other than an error
+ *    turns into. It was, on its own, the entire reason given for a failing guard.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+export function plainly(raw) {
+  const text = String(raw ?? '').trim();
+
+  if (text === '' || text === '[object Object]' || text === '[object Undefined]') {
+    return (
+      'This guard threw something that is not an error, so there is no message to read. ' +
+      "Throw `new Error('what went wrong')`, or better, use `app.expect(...)` — it fails with the " +
+      'plain sentence you wrote, which is the sentence that gets printed.'
+    );
+  }
+
+  // One line. Everything after it is the machinery describing itself.
+  let line = text.split('\n')[0].trim();
+
+  // A whole protocol frame, pasted in as if it were a sentence.
+  if (/^[[{]/.test(line) && PROTOCOL_CHATTER.test(line)) {
+    return 'The app answered this guard with a raw debugging-protocol message rather than a result, so the guard could not finish.';
+  }
+
+  // Chrome's own diagnostics, bracketed on the end. Only dropped when the bracket really is
+  // protocol talk — plenty of failures put something useful in brackets.
+  line = line.replace(/\s*\([^()]*\)$/, (blob) => (PROTOCOL_CHATTER.test(blob) ? '' : blob)).trim();
+
+  if (line.length > MAX_MESSAGE) return `${line.slice(0, MAX_MESSAGE).trimEnd()}… (cut short)`;
+  return line;
+}
+
 /** A timeout, kept apart from a real error so the wording stays ours. */
 class TookTooLong extends Error {
   /** @param {string} message */
@@ -404,25 +547,16 @@ function consoleNote(app) {
   return `\nThe page also logged an error while this guard ran: ${first}${rest}`;
 }
 
-/**
- * The story of the original bug is the single most useful thing to print when a
- * guard fails — it says whether the failure matters.
- *
- * @param {string} message
- * @param {string|undefined} because
- * @returns {string}
- */
-function withStory(message, because) {
-  if (typeof because !== 'string' || because.trim() === '') return message;
-  return `${message}\n\nWhy this guard exists: ${because.trim()}`;
-}
-
 /**
  * @param {number} ms
  * @returns {string}
  */
 function humanSeconds(ms) {
   if (ms < 1000) return `${Math.round(ms)} milliseconds`;
-  const seconds = Math.round(ms / 1000);
+  // Rounded to whole seconds, `timeoutMs: 1500` came back as "did not finish within 2
+  // seconds" — a number the person cannot find anywhere in their own guard, which reads
+  // as the tool having waited longer than it did. One decimal place, so it matches what
+  // they typed: 1.5, 8, 30.
+  const seconds = Math.round(ms / 100) / 10;
   return seconds === 1 ? '1 second' : `${seconds} seconds`;
 }

package/src/report/console.js

@@ -43,6 +43,12 @@ const MAX_COMMANDS = 10;
 /** How many touched files a trace prints before summarising the rest. */
 const MAX_TRACE_FILES = 12;
 
+/**
+ * How many of a check's recorded answers are printed. The register keeps twelve; six is
+ * enough to see a check flipping, and the whole row is one `staysfixed flake --json` away.
+ */
+const MAX_RECENT_STATUSES = 6;
+
 /**
  * Thousands separators, always. "1024 pixels" reads as noise; "1,024" reads as a number.
  * @param {number} n
@@ -108,6 +114,63 @@ function shorten(s, max) {
   return text.length > max ? text.slice(0, max - 1) + '…' : text;
 }
 
+/**
+ * What a guard's result actually says, in one word.
+ *
+ * Four different things wear the status 'failed' or 'skipped', and every renderer used to
+ * decide for itself which was which — the terminal line, the verdict sentence, the results
+ * table and the HTML report, four times, differently. That is how "1 guard failed — a bug
+ * that was already fixed is back" ended up printed on 2026-08-31 over a healthy tree, for a
+ * guard whose clock had simply run out. It is decided once here now, and everything reads it.
+ *
+ *  - `back`       — the guard asked its question and the answer was no. The bug is back.
+ *  - `unanswered` — nobody got an answer: it ran out of time, or it asserted nothing at all.
+ *                   Not a pass, and not a returned bug either.
+ *  - `left out`   — marked skip. Never ran.
+ *  - `held`       — asked, and the answer was yes.
+ *
+ * Anything unrecognised counts as `unanswered`, never as `held`: the one thing that must
+ * never happen here is a result nobody understood being read as a clean bill of health.
+ *
+ * @param {import('../types.js').GuardResult} guard
+ * @returns {'held'|'back'|'unanswered'|'left out'}
+ */
+export function guardVerdict(guard) {
+  const g = /** @type {any} */ (guard ?? {});
+  if (g.status === 'passed') return 'held';
+  if (g.status === 'skipped') return 'left out';
+  if (g.timedOut === true || g.assertedNothing === true) return 'unanswered';
+  if (g.status === 'failed') return 'back';
+  return 'unanswered';
+}
+
+/**
+ * The one short phrase a guard gets in the results table.
+ *
+ * The table is built of rows, and a message with a newline in it or four sentences of advice
+ * lands in the next column and takes the table apart — the same lesson `plainly()` in
+ * src/guard/run.js learned the hard way. The full message is printed on the guard's own line
+ * above; this is the scannable version.
+ *
+ * @param {import('../types.js').GuardResult} g
+ * @returns {string}
+ */
+function guardOutcome(g) {
+  const any = /** @type {any} */ (g);
+  switch (guardVerdict(g)) {
+    case 'held':
+      return 'still holds';
+    case 'left out':
+      return 'left out on purpose';
+    case 'unanswered':
+      if (any.timedOut === true) return 'ran out of time — nothing was proved either way';
+      if (any.assertedNothing === true) return 'checks nothing, so it is protecting nothing';
+      return shorten(g.message || 'gave no answer', 90);
+    default:
+      return g.failedAt ? `expected: ${g.failedAt}` : shorten(g.message || 'this one is broken again', 90);
+  }
+}
+
 /**
  * The counts every verdict is built from. Taken from the results themselves
  * rather than `totals`, so the sentence can never disagree with the list above it.
@@ -124,11 +187,18 @@ 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,
-    // Two different things wear the same status, and calling both of them "a bug is back"
+    // Three different things wear the same status, and calling all 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,
+    // question at all has not caught anything; nor has one whose clock ran out.
+    guardsFailed: guards.filter((g) => guardVerdict(g) === 'back').length,
     guardsEmpty: guards.filter((g) => /** @type {any} */ (g).assertedNothing === true).length,
+    guardsTimedOut: guards.filter((g) => guardVerdict(g) === 'unanswered' && /** @type {any} */ (g).timedOut === true).length,
+    // How much this run actually looked at. A run that skipped everything it had, or had
+    // nothing to begin with, proves nothing — and the sentence for "nothing was wrong" and
+    // the sentence for "nothing was checked" must never be the same sentence.
+    looked:
+      pictures.filter((p) => p.status !== 'skipped').length +
+      guards.filter((g) => g.status !== 'skipped').length,
   };
 }
 
@@ -157,6 +227,10 @@ export function verdictFor(run) {
   }
   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.` });
+  // Out of time is not an answer of no. Said in its own words, or a healthy tree gets told a
+  // bug is back — measured 2026-08-31 on a shop where one guard simply slept past its limit.
+  if (t.guardsTimedOut === 1) parts.push({ n: 1, text: '1 guard ran out of time, so nobody knows whether that bug is back.' });
+  else if (t.guardsTimedOut > 1) parts.push({ n: t.guardsTimedOut, text: `${countText(t.guardsTimedOut)} guards ran out of time, so nobody knows whether those bugs are back.` });
   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.' });
@@ -168,12 +242,22 @@ export function verdictFor(run) {
   if (parts.length === 0 && t.wobbled > 0) {
     parts.push({ n: t.wobbled, text: `${countText(t.wobbled)} ${plural(t.wobbled, 'check', 'checks')} could not make up ${plural(t.wobbled, 'its', 'their')} mind.` });
   }
+  // "Everything that worked still works" over a run that looked at nothing is the same
+  // false all-clear as any other, and the friendliest-sounding one this tool can print.
+  if (parts.length === 0 && t.looked === 0) {
+    return t.pictures + t.guards === 0
+      ? 'Nothing was checked, so nothing is proved — this project has no screens and no guards yet.'
+      : 'Nothing was checked, so nothing is proved — every screen and guard here was left out.';
+  }
   if (parts.length === 0) return 'Everything that worked still works.';
   // Two sentences is as much as anyone reads standing up; the table underneath
   // still names every single one, so nothing is hidden by shortening this.
   if (parts.length <= 2) return parts.map((p) => p.text).join(' ');
   const rest = parts.slice(2).reduce((sum, p) => sum + p.n, 0);
-  return `${parts[0].text} ${parts[1].text} And ${countText(rest)} other ${plural(rest, 'screen needs', 'screens need')} a look.`;
+  // "And 1 other screen needs a look" — said on 2026-08-31 about a run of five guards and no
+  // screens at all. Whatever gets collapsed in here can be either, so it is called what this
+  // tool calls both of them everywhere else. The table underneath still names every one.
+  return `${parts[0].text} ${parts[1].text} And ${countText(rest)} other ${plural(rest, 'check needs', 'checks need')} a look.`;
 }
 
 /**
@@ -182,10 +266,14 @@ export function verdictFor(run) {
  */
 export function allClear(run) {
   const t = tally(run);
-  // `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;
+  // A run that looked at nothing is not a clean run. It is a run.
+  if (t.looked === 0) return false;
+  // `guardsEmpty` and `guardsTimedOut` count too. Splitting them out of `guardsFailed` was so
+  // the SENTENCE could tell a returned bug from a question nobody answered — not so that one
+  // of them could quietly become a pass. A stuck guard is the quietest way there is to go green.
+  return (
+    t.changed + t.fresh + t.missing + t.broken + t.wobbled + t.guardsFailed + t.guardsEmpty + t.guardsTimedOut === 0
+  );
 }
 
 /**
@@ -277,24 +365,39 @@ export function printPictureResult(r) {
 }
 
 /**
- * One line per guard; a failure also tells the story of the bug it watches.
+ * One line per guard; a returned bug also tells the story of the bug it watches.
+ *
+ * The story is deliberately NOT printed under a guard that ran out of time. It is printed to
+ * say whether a failure matters — and a timeout says nothing about the bug at all, so
+ * "why this guard exists: checking out twice used to leave the old basket behind" under a red
+ * line is read as that bug being back. Which is the thing this whole file is trying to stop.
+ *
  * @param {import('../types.js').GuardResult} r
  * @returns {void}
  */
 export function printGuardResult(r) {
   const time = paint.grey(duration(r.durationMs ?? 0));
   const name = r.name.padEnd(NAME_WIDTH);
-  if (r.status === 'passed') {
+  const verdict = guardVerdict(r);
+  if (verdict === 'held') {
     say(`${paint.green(sym(mark.pass))} ${name} ${paint.grey('still holds')} ${time}`);
     return;
   }
-  if (r.status === 'skipped') {
+  if (verdict === 'left out') {
     say(`${paint.grey(sym(mark.info))} ${paint.grey(`${name} left out on purpose`)}`);
     return;
   }
-  say(`${paint.red(sym(mark.fail))} ${paint.red(`${name} ${r.message || 'this one is broken again'}`)} ${time}`);
+  // A question nobody answered is not painted like a bug coming back. It still keeps the run
+  // out of the green — `allClear` counts it — but the colour a person scans for should not
+  // say "regression" about something the run has no opinion on.
+  const shout = verdict === 'back' ? paint.red : paint.yellow;
+  const symbol = verdict === 'back' ? mark.fail : mark.warn;
+  say(`${shout(sym(symbol))} ${shout(`${name} ${r.message || 'this one is broken again'}`)} ${time}`);
   if (r.failedAt) say(paint.red(`    expected: ${r.failedAt}`));
-  if (r.because) say(paint.grey(`    why this guard exists: ${r.because}`));
+  if (r.because && verdict !== 'unanswered') say(paint.grey(`    why this guard exists: ${r.because}`));
+  else if (r.because && /** @type {any} */ (r).assertedNothing === true) {
+    say(paint.grey(`    what it was meant to protect: ${r.because}`));
+  }
   if (r.file) detail(`    ${shortPath(r.file)}`);
 }
 
@@ -336,8 +439,7 @@ export function printRunSummary(run, project, opts = {}) {
   }
   for (const g of guards) {
     if (g.status === 'passed' || g.status === 'skipped') continue;
-    const what = g.failedAt ? `expected: ${g.failedAt}` : g.message || 'this one is broken again';
-    rows.push([g.name, what, paint.grey(g.file ? shortPath(g.file) : '')]);
+    rows.push([g.name, guardOutcome(g), paint.grey(g.file ? shortPath(g.file) : '')]);
   }
   if (rows.length) {
     heading('What is not right');
@@ -532,6 +634,65 @@ export function printTrace(report) {
   blank();
 }
 
+/**
+ * A status that means the check actually reached a verdict.
+ *
+ * The same three as `isDecided` in src/core/history.js, which does not export it. Said
+ * again rather than guessed at, because the three it leaves out matter: 'skipped', 'new'
+ * and 'missing' are checks that never ran, and reading the move from "never ran" to
+ * "passed" as a change of mind would accuse every check somebody switched back on.
+ *
+ * @param {import('../types.js').CheckStatus} status
+ * @returns {boolean}
+ */
+function decided(status) {
+  return status === 'passed' || status === 'changed' || status === 'failed';
+}
+
+/**
+ * Checks whose own recorded answers disagree, and which nothing has counted as wobbling.
+ *
+ * This is the list the register used to have no way to mention, and its absence produced
+ * the worst sentence this tool can print. Measured 2026-08-31 on a real product: a guard
+ * recorded "passed" and then "failed", `staysfixed flake --json` printed both statuses,
+ * and `staysfixed flake` answered "No check here has ever changed its mind. That is exactly
+ * how it should be." — a clean bill of health contradicted by the very file it had just
+ * read out.
+ *
+ * The register was not lying about `flakes`. It counts a wobble only when the code can be
+ * PROVED to have stood still, which needs a commit and a clean tree, and there was no such
+ * proof. But "not counted" and "did not happen" are two different facts, and the second one
+ * was being printed for the first.
+ *
+ * These are not accused of anything here. A check that passed at one commit and failed at
+ * the next is a real break, not a wobble, and calling it flaky would be as corrosive as a
+ * false failure — which is exactly why `foldRun` refuses to count it. All this does is show
+ * what is on record and say plainly that nobody can tell which it was.
+ *
+ * @param {import('../types.js').History} history
+ * @returns {import('../types.js').HistoryEntry[]}
+ */
+function disagreedUncounted(history) {
+  return Object.values(history)
+    .filter((e) => (e.flakes ?? 0) === 0)
+    .filter((e) => new Set((e.recent ?? []).filter(decided)).size > 1);
+}
+
+/**
+ * The commit the last run pinned this check's answer to, if it could pin one.
+ *
+ * `foldRun` writes it, and writes `null` when there was nothing to pin to — no commit, or a
+ * working tree with uncommitted changes in it. It is not in the `HistoryEntry` type, which
+ * is why it is read through a cast rather than off the shape.
+ *
+ * @param {import('../types.js').HistoryEntry} entry
+ * @returns {string|null}
+ */
+function pinnedTo(entry) {
+  const sha = /** @type {{lastSha?: string|null}} */ (entry).lastSha;
+  return typeof sha === 'string' ? sha : null;
+}
+
 /**
  * The flake register, for `staysfixed flake`.
  * @param {import('../types.js').History} history
@@ -539,14 +700,32 @@ export function printTrace(report) {
  * @returns {void}
  */
 export function printFlakes(history, flakeLimit = 2) {
-  const entries = wobbly(history ?? {});
+  const register = history ?? {};
+  const entries = wobbly(register);
+  const uncounted = disagreedUncounted(register);
   blank();
-  if (entries.length === 0) {
+  // The all-clear is now earned rather than assumed: it needs an empty register AND a
+  // record with nothing in it that disagrees with itself.
+  if (entries.length === 0 && uncounted.length === 0) {
     ok('No check here has ever changed its mind. That is exactly how it should be.');
     blank();
     return;
   }
 
+  if (entries.length > 0) printCountedFlakes(entries, flakeLimit);
+  if (uncounted.length > 0) printUncountedDisagreements(uncounted);
+  blank();
+}
+
+/**
+ * The register proper: checks that changed their mind while the code demonstrably stood
+ * still.
+ *
+ * @param {import('../types.js').HistoryEntry[]} entries
+ * @param {number} flakeLimit
+ * @returns {void}
+ */
+function printCountedFlakes(entries, flakeLimit) {
   heading('Checks that have changed their mind');
   /** @type {string[][]} */
   const rows = [[paint.grey('check'), paint.grey('wobbled'), paint.grey('last time'), paint.grey('verdict')]];
@@ -568,7 +747,46 @@ export function printFlakes(history, flakeLimit = 2) {
     say(paint.red('A condemned check is not a warning to live with. Fix it, or delete it.'));
     say(paint.grey('Once it is genuinely fixed, forgive it with: ') + paint.cyan('staysfixed flake --clear <name>'));
   }
+}
+
+/**
+ * What is on record and cannot be judged.
+ *
+ * The sequence is printed rather than summarised, because the sequence is the fact — it is
+ * what `staysfixed flake --json` shows, and a person who has read that file and then reads
+ * this needs the two to agree.
+ *
+ * @param {import('../types.js').HistoryEntry[]} entries
+ * @returns {void}
+ */
+function printUncountedDisagreements(entries) {
+  heading('Different answers on record, and nothing can say why');
+  say('  These gave one answer on one run and a different one on the next. Nothing on record');
+  say('  proves the code stood still in between, so none of it is counted as wobbling — and');
+  say('  none of it is a clean bill of health either. It may be flakiness; it may be a real');
+  say('  break somebody then fixed. Nobody can tell from here.');
   blank();
+  for (const entry of entries) {
+    const recent = (entry.recent ?? []).filter(decided).slice(-MAX_RECENT_STATUSES);
+    say(`  ${entry.name}`);
+    say(paint.grey(`      ${recent.join(' then ')}   (${countText(entry.runs)} ${plural(entry.runs, 'run', 'runs')} on record)`));
+  }
+
+  // Why the register could not judge them, and it is almost always the same reason.
+  //
+  // `staysfixed flake` used to say "this folder has no commit to pin results to", which was
+  // untrue on the product this was measured against 2026-08-31: that folder had a commit.
+  // What it had as well was an uncommitted `.staysfixed/history.json` — written by the
+  // first run — which makes the tree dirty for the second one and every one after it. So a
+  // project that does not ignore this tool's own folder is blind from run two onwards, and
+  // was being told the opposite of the reason.
+  if (entries.some((entry) => pinnedTo(entry) === null)) {
+    blank();
+    say(paint.grey('  The last run could not pin these to a commit, so it had nothing to compare them at.'));
+    say(paint.grey('  Either this folder has no commit yet, or the working tree had uncommitted changes'));
+    say(paint.grey('  when the check finished — and Stays Fixed writes .staysfixed itself, so a project'));
+    say(paint.grey('  that does not ignore that folder is dirty on every run after the first.'));
+  }
 }
 
 /**