staysfixed 0.11.1 → 0.13.0

package/src/v2/journeys/record.js

@@ -35,6 +35,18 @@ import path from 'node:path';
 /** The shape of a journeys file on disk. Version it, because a format nobody versioned is a format nobody can change. */
 export const JOURNEY_FILE_VERSION = 2;
 
+/**
+ * Where recordings live, relative to the project.
+ *
+ * One name, because three readers used to spell it out for themselves — the gatherer, the
+ * check path and the recording command — and three copies of a folder name is three chances
+ * for a recording to be written where nothing looks for it, which reads afterwards exactly
+ * like a recording that was never made.
+ *
+ * It is committed, not ignored: a recording is the promise, not the evidence.
+ */
+export const RECORDINGS_DIR = path.join('.staysfixed', 'journeys');
+
 // ---------------------------------------------------------------------------
 // Keeping secrets out
 // ---------------------------------------------------------------------------

package/src/v2/mcp/tools.js

@@ -493,13 +493,13 @@ export function toolDefinitions() {
           journeys: {
             type: 'string',
             description:
-              "Where the steps come from. 'code' is the default and needs nothing: each adapter reads your source and offers what it finds - routes, commands, screens, message channels. 'suite' walks the project's own test suite as well: each test file runs twice inside the scratch copy, every check is reported by name, and it stops after 90 seconds naming each file it did not reach. It catches breaks nothing else can - a rounding change the product's own output never shows. It is opt-in because running a stranger's whole suite twice on every check is not something to do by default. You can also pass a path to a journeys file naming steps by hand. 'recorded' (replay a recorded session) is written and not yet wired into a run: ask for it and it says so rather than checking something else.",
+              "Where the steps come from. 'code' is the default and needs nothing: each adapter reads your source and offers what it finds - routes, commands, screens, message channels. 'suite' walks the project's own test suite as well: each test file runs twice inside the scratch copy, every check is reported by name, and it stops after 90 seconds naming each file it did not reach. It catches breaks nothing else can - a rounding change the product's own output never shows. It is opt-in because running a stranger's whole suite twice on every check is not something to do by default. 'recorded' replays the sessions somebody recorded with `staysfixed record` and kept in .staysfixed/journeys - the only source that knows which four screens a person actually opens every morning, which reading the source cannot work out. You can also pass a path to a journeys file naming steps by hand.",
           },
           surface: {
             type: 'string',
-            enum: ['auto', 'cli', 'library', 'server', 'web', 'electron', 'android', 'ios'],
+            enum: ['auto', 'cli', 'library', 'server', 'web', 'electron', 'android', 'ios', 'extension'],
             description:
-              "What kind of product to aim at. Default 'auto', which uses the settings. 'web' opens the page in a browser of the tool's own — never yours — and reads what the screen says each control is and does. 'electron' opens the desktop app with its own scratch data folder and drives it over its own debugging port. 'android' installs the APK on a virtual device; 'ios' boots the built app on a simulator. Aim it at something this copy or this machine cannot drive and it refuses by name rather than checking something else and reporting that.",
+              "What kind of product to aim at. Default 'auto', which uses the settings. 'web' opens the page in a browser of the tool's own — never yours — and reads what the screen says each control is and does. 'electron' opens the desktop app with its own scratch data folder and drives it over its own debugging port. 'android' installs the APK on a virtual device; 'ios' boots the built app on a simulator. 'extension' loads a browser extension into a throwaway browser: its manifest is read as a contract, its popup and options pages are walked like any other page, and what its content scripts do to somebody else's page is measured by opening that page with the extension and without it and comparing the difference — point 'extension.dir' in the settings at the folder you would load unpacked. Aim it at something this copy or this machine cannot drive and it refuses by name rather than checking something else and reporting that.",
           },
           at: {
             type: 'string',
@@ -538,7 +538,10 @@ export function toolDefinitions() {
       title: 'Prove what caused it',
       annotations: behaves({ title: 'Prove what caused it' }),
       description:
-        'Test a causal claim by undoing a change and running again. You believe your edit to a particular file caused a finding: this puts that file back to the reference, re-runs, and tells you whether the difference went away. If it survives the revert, your edit did not cause it and you were about to fix the wrong thing. Nothing is left reverted.',
+        'Test a causal claim by undoing a change and running again. You believe your edit to a particular file caused a finding: this puts that file back to the reference, re-runs, and tells you whether the difference went away. ' +
+        'It answers one of THREE things, and only two of them are answers: PROVEN CAUSED (undoing it made the difference go away), PROVEN NOT CAUSED (it was re-run without your change and the difference is still there, so you were about to fix the wrong file), ' +
+        'and NOT TESTED (nothing was measured - the file you named was not among the changes, the old build would not build, or nothing was re-run at all). NOT TESTED never means your edit is innocent; it means nobody looked, and it comes back as an error so it cannot be mistaken for a clean answer. ' +
+        'Proving costs a full re-run of the affected journeys - roughly what a check costs - because that is the only thing that settles it. Nothing is left reverted.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -934,19 +937,12 @@ async function toolCheck(ctx, input) {
   const limit = positive(input.limit) ?? DEFAULT_LIMIT;
   const offset = positive(input.offset) ?? 0;
 
-  // A value the engine does not understand must be refused BY NAME, never passed down.
-  //
-  // `suite` is now wired and reaches the harvest. `recorded` is still written and called by
-  // nothing, so passing it down would reach the engine as the name of a FILE and come back as
-  // "there is no journeys file at .../recorded" — an error that sends an agent looking for a
-  // file it never asked for. Refusing it by name and saying why is the honest answer, and a
-  // clean result about the wrong steps would be worse than no result.
+  // Every word this tool offers now reaches something that walks. `suite` harvests the
+  // project's own tests; `recorded` replays the sessions in `.staysfixed/journeys`, which was
+  // written and wired to nothing until 2026-08-31 and was refused here by name because of it.
+  // A project with no recordings comes back BLOCKED from the engine, naming the folder and the
+  // command that makes one - never as a clean result about steps nobody walked.
   const wantedJourneys = text(input.journeys);
-  if (wantedJourneys === 'recorded') {
-    return problem(
-      'Replaying a recorded session is written and not wired into a run yet, so nothing was checked. 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.'
-    );
-  }
 
   const surface = text(input.surface);
   const at = text(input.at);
@@ -1519,6 +1515,22 @@ async function toolExplain(ctx, input) {
   } else if (deep && typeof deep.text === 'string') {
     out.push('');
     out.push(deep.text);
+  } else {
+    // The deep half is missing and nothing above says so.
+    //
+    // Same shape as the `prove` defect measured on 2026-08-31: a reply that is complete on
+    // its face while a whole half of it was never fetched. Everything above comes from the
+    // stored finding, which this surface can always read; the full list of addresses with
+    // both values comes from the engine, and when the engine cannot be loaded, or has no
+    // `explain` in it, the reply simply ended early and read as the whole answer. A reader
+    // has no way to tell "this is all there is" from "the rest could not be fetched", so it
+    // is said out loud rather than left to be inferred from an absence.
+    out.push('');
+    out.push(
+      engine.parts.explain
+        ? 'The engine returned nothing for this finding, so everything above comes from the stored record of the check and the full side-by-side values are missing. This is not the whole answer.'
+        : `This copy of Stays Fixed has no difference engine to ask, so everything above comes from the stored record of the check alone - the full list of addresses with both values is missing. This is not the whole answer. ${voice.isPerson ? 'Run' : 'Call'} ${voice.capabilities} for what this copy can do.`
+    );
   }
 
   content.push({ type: 'text', text: out.join('\n') });
@@ -1577,7 +1589,10 @@ async function toolProve(ctx, input) {
     return engineMissing(
       engine,
       'prove',
-      'prove({cwd, configFile, finding, revert}) returning {gone: boolean, detail?: string}. src/v2/cause.js already has proveCause(), but it takes an engine-internal finding and a loaded project, which this surface does not have - a small facade in src/v2/check.js is all that is needed.',
+      'prove({cwd, configFile, finding, revert}) returning {verdict: "caused by that change"|"not caused by that change"|"could not test", detail?: string, reran?: number, checked?: number, escalates?: boolean}. ' +
+      'The verdict has to be all three of those, not a boolean: "could not test" is a third outcome and reporting it as "not caused" is a false all-clear (measured 2026-08-31). ' +
+      '`reran` and `checked` are what let this reply say whether anything was actually run, so a five-second answer cannot pass for an eleven-minute one. ' +
+      'src/v2/cause.js already has proveCause() returning exactly that shape, but it takes an engine-internal finding and a loaded project, which this surface does not have - a small facade in src/v2/check.js is all that is needed.',
       voice
     );
   }
@@ -1593,23 +1608,174 @@ async function toolProve(ctx, input) {
 
   /** @type {any} */
   const result = (await run({ cwd: ctx.root, finding: id, revert })) ?? {};
-  const gone = result.gone === true;
+
+  // THREE OUTCOMES, THREE SENTENCES. Only two of them are answers.
+  //
+  // Until 2026-08-31 this branched on `result.gone === true` and printed one of two
+  // paragraphs, so everything that was not a proof came out as the confident denial "Your
+  // edit did not cause this, so fixing that file will not help." Measured on a real website
+  // that day: a one-line heading change that had definitely caused the finding was told it
+  // was innocent; naming a completely unrelated file produced the word-for-word identical
+  // denial; and a file that does not exist produced it too. All three came back in about
+  // five seconds, on a project where a real check takes eleven to twenty minutes, and the
+  // run log recorded zero server starts. Nothing had been re-run at all.
+  //
+  // `src/v2/cause.js` had the third outcome the whole time — its `cannot()` path carries a
+  // comment saying "not proven either way is not the same as proven innocent, and it must
+  // never be reported as if it were" — and this is the surface that was reporting it as if
+  // it were. So the verdict is read here, not re-derived from a boolean that cannot carry
+  // three states.
+  const verdict = verdictOf(result);
 
   /** @type {string[]} */
   const out = [];
-  if (gone) {
-    out.push(`PROVEN: your change caused it. With ${revert.join(', ')} put back, this matched the reference again.`);
-    out.push(`  ${trim(f.title, 200)}`);
+  const files = revert.join(', ');
+  const title = `  ${trim(f.title, 200)}`;
+  // How much real work the answer rests on, when the engine says. `reran` counts journeys
+  // actually walked again; `checked` counts the finding's addresses that were re-measured.
+  // Both are absent when the facade in src/v2/check.js does not forward them, and an absent
+  // number is never guessed at - it simply goes unsaid.
+  const reran = positive(result.reran);
+  const checked = positive(result.checked);
+
+  if (verdict === 'caused by that change') {
+    out.push(`PROVEN CAUSED: your change caused it. With ${files} put back, this matched the reference again.`);
+    out.push(title);
+    out.push(measuredLine(reran, checked, 'and the difference went away'));
     out.push('So it is yours to fix - or to record as intended, if that is genuinely what you meant and it is not sealed.');
+  } else if (verdict === 'not caused by that change') {
+    out.push(`PROVEN NOT CAUSED: it was re-run with your change undone and the difference is still there.`);
+    out.push(title);
+    out.push(measuredLine(reran, checked, 'and the difference survived'));
+    out.push(`So putting ${files} back does not fix this, and fixing that file will not either. Something else caused it, and nothing knows what yet - this finding is louder now, not quieter.`);
   } else {
-    out.push(`NOT PROVEN: it survived the revert. With ${revert.join(', ')} put back, this was still different.`);
-    out.push(`  ${trim(f.title, 200)}`);
-    out.push('Your edit did not cause this, so fixing that file will not help. Something else did, or it was already broken before you started.');
+    // The one that must never sound like the one above it. It says what it is, why, what it
+    // is NOT, and what would actually settle the question.
+    out.push(`NOT TESTED: this was not proved either way. Nobody looked.`);
+    out.push(title);
+    out.push('');
+    const why = trim(dropRepeatedTail(String(result.detail ?? 'The engine did not say why.')), 600);
+    out.push(`Why: ${why}`);
+    out.push('');
+    // The re-run fact, said once. `cause.js` writes it into its own sentence so that it
+    // survives a facade that forwards only the words, so when it is already in `why` there
+    // is nothing to add - and adding a vaguer version underneath ("nothing here says how
+    // much was re-run") would contradict the specific one directly above it.
+    const rerunLine =
+      reran === 0
+        ? 'Nothing was re-run: no build was started and no journey was walked again, so no part of this reply is a measurement of your product.'
+        : reran !== null
+          ? `${reran} ${reran === 1 ? 'journey was' : 'journeys were'} walked again and it still settled nothing.`
+          : /re-run|walked again/i.test(why)
+            ? ''
+            : 'Nothing here says how much was re-run, so do not read any of this as a measurement.';
+    if (rerunLine) out.push(rerunLine);
+    out.push(`This is NOT "your edit did not cause it". ${files} has not been cleared - it was never tested. Keep suspecting it.`);
+    out.push(`To get a real answer: ${voice.isPerson ? 'run' : 'call'} ${voice.check} so there is a fresh run to work from, then ${explainThis(voice, id)} to see which files this finding actually sits near, and name one you really changed.`);
   }
-  if (result.detail) out.push('', trim(String(result.detail), 600));
-  out.push('', 'The working tree has been put back exactly as it was.');
 
-  return { content: [{ type: 'text', text: out.join('\n') }] };
+  if (verdict !== 'could not test' && result.detail) out.push('', trim(dropRepeatedTail(String(result.detail)), 600));
+  out.push('', 'Nothing was left reverted. The working tree is exactly as it was.');
+
+  return {
+    content: [{ type: 'text', text: out.join('\n') }],
+    structuredContent: { finding: id, verdict, reverted: revert, reran, checked, escalates: result.escalates === true },
+    // "Could not test" answers non-zero on purpose, and the CLI's own help has promised
+    // exactly this since the command existed: "It answers 0 when it could test the claim and
+    // 2 when it could not." It exited 0 instead. An agent - or a CI step - that reads a zero
+    // as "asked and answered" is the false all-clear this tool exists to prevent, so the one
+    // outcome that is not an answer is the one outcome that does not come back clean.
+    isError: verdict === 'could not test',
+  };
+}
+
+/**
+ * How this reader asks to see THIS finding in full.
+ *
+ * `voice.explainCall` is a worked example carrying the made-up id f-a1b2c3, which is right
+ * where the point is to show the shape of a call and wrong the moment the sentence is about
+ * a finding that has a real id. Telling somebody to run `staysfixed explain f-a1b2c3` about
+ * finding f-15365c reads as a copy-and-paste slip and sends them to look up an id that does
+ * not exist.
+ *
+ * @param {Voice} voice
+ * @param {string} id
+ * @returns {string}
+ */
+function explainThis(voice, id) {
+  return voice.isPerson ? `\`staysfixed explain ${id}\`` : `staysfixed_explain { "finding": "${id}" }`;
+}
+
+/**
+ * Which of the three this is, refusing to invent the difference between two of them.
+ *
+ * The engine's own three-state verdict is used whenever it is there. When it is not - an
+ * older facade, or one that only ever returned `{gone: boolean}` - a `false` is genuinely
+ * ambiguous: it means either "measured, and your edit is innocent" or "could not measure".
+ * Those are the two this whole defect confused, so the unknown resolves to the one that
+ * claims nothing. Reporting "could not test" about something that was really tested costs
+ * somebody one more command; reporting "your edit did not cause this" about something
+ * nobody measured sends them to fix the wrong file, which is what happened on 2026-08-31.
+ *
+ * @param {any} result
+ * @returns {'caused by that change'|'not caused by that change'|'could not test'}
+ */
+function verdictOf(result) {
+  const said = typeof result?.verdict === 'string' ? result.verdict : null;
+  if (said === 'caused by that change' || said === 'not caused by that change' || said === 'could not test') return said;
+  if (result?.gone === true) return 'caused by that change';
+  return 'could not test';
+}
+
+/**
+ * One line saying what the verdict above actually rests on.
+ *
+ * A verdict with no measurement behind it reads exactly like one with eleven minutes behind
+ * it, which is how a five-second reply passed for a check of a whole website. When the
+ * numbers are not forwarded this says so plainly rather than inventing a reassuring one.
+ *
+ * @param {number|null} reran    Journeys walked again.
+ * @param {number|null} checked  Addresses re-measured.
+ * @param {string} outcome       What happened to the difference, in a few words.
+ * @returns {string}
+ */
+function measuredLine(reran, checked, outcome) {
+  if (reran === null && checked === null) return `That was measured by running it again, ${outcome}.`;
+  const bits = [];
+  if (reran !== null) bits.push(`${reran} ${reran === 1 ? 'journey' : 'journeys'} walked again`);
+  if (checked !== null) bits.push(`${checked} ${checked === 1 ? 'address' : 'addresses'} re-measured`);
+  return `Measured, not assumed: ${bits.join(', ')}, ${outcome}.`;
+}
+
+/**
+ * Drop a sentence the engine handed over twice.
+ *
+ * `prove` in src/v2/check.js builds its detail as `${proof.what} ${proof.why}`, and
+ * `proof.what` already ends with `why` - so every "could not test" arrived with its reason
+ * printed twice in a row. That is only noise, but a reply that visibly repeats itself is a
+ * reply people stop reading closely, and this one is asking to be read closely.
+ *
+ * @param {string} detail
+ * @returns {string}
+ */
+function dropRepeatedTail(detail) {
+  const s = detail.trim();
+  // Walk back from the end looking for a tail that already appeared earlier in the string.
+  // Only whole trailing sentences of real length count, so ordinary repeated words - "the
+  // change", "this file" - are never mistaken for a duplicated reason.
+  for (let cut = Math.floor(s.length / 2); cut >= 30; cut -= 1) {
+    const tail = s.slice(s.length - cut).trim();
+    if (tail.length < 30) break;
+    if (s.slice(0, s.length - cut).includes(tail)) {
+      const kept = s.slice(0, s.length - cut).trim();
+      // The cut can land one character inside the sentence that is being KEPT, because the
+      // repeated tail often starts at ". " and the full stop it takes belongs to the line
+      // before it. Losing it leaves the reason ending mid-air, which reads like the text was
+      // truncated - the one impression this particular reply must never give.
+      return /[.!?]$/.test(kept) ? kept : `${kept}.`;
+    }
+  }
+  return s;
 }
 
 // ---------------------------------------------------------------------------

package/src/v2/observation.js

@@ -829,6 +829,21 @@ export function mergeWobble(wobbles) {
  * here decides whether any difference is real. It decides one thing only — whether this run is
  * entitled to say the word "clean".
  *
+ * IT IS ASKED PER JOURNEY, NOT ONLY ONCE OVER THE WHOLE RUN, and that is the scope this rule
+ * was missing until 2026-08-31. Measured on a real Next.js site: 179 of 2849 addresses were
+ * unsteady across the run, which is nowhere near half, so the whole-run answer was "no storm"
+ * and the run exited 0 saying `ok` — while four of its twelve journeys had been unsteady at
+ * 69%, 75% and twice 100% of their own addresses. A page where EVERY address disagreed with
+ * itself was folded into a passing total by nine pages that behaved. The rule was right and
+ * the scope was wrong: applied per journey, the same one comparison catches all four. Whoever
+ * calls this owes it one call per journey; `noAnswerJourneys` below is that call.
+ *
+ * A MEASUREMENT OVER NOTHING IS ALSO NOT A MEASUREMENT. Two runs that each came back with no
+ * addresses at all agree about everything, which arithmetically is nought unsteady and nought
+ * steady, and `unstable <= steady` waved it through as calm weather. That is the same false
+ * all-clear wearing the opposite clothes — a journey with no answer in it counted towards a
+ * pass — so it is answered here rather than left to whichever caller thinks to look.
+ *
  * @param {Wobble} wobble
  * @returns {{stormy: boolean, share: number, looked: number, vanished: number, why: string}}
  */
@@ -837,6 +852,21 @@ export function wobbleStorm(wobble) {
   const looked = unstable + wobble.steady;
   const vanished = wobble.entries.filter((e) => e.kind === 'vanished').length;
   const share = looked === 0 ? 0 : unstable / looked;
+  // NOTHING WAS LOOKED AT, so there is nothing here to be steady or unsteady about. A walk
+  // that ran, came back empty, and was run again and came back empty a second time produces
+  // nought unsteady out of nought — which reads as perfect agreement to every count below
+  // and is the emptiest possible sentence to build a pass on. Said out loud instead.
+  if (wobble.measured && looked === 0) {
+    return {
+      stormy: true,
+      share: 0,
+      looked: 0,
+      vanished: 0,
+      why:
+        'The new build was run twice here and neither run found a single address to look at, so there was nothing to measure and nothing to compare. ' +
+        'Two empty walks agree with each other about everything, which is why this used to count towards a clean run. It is not a pass and not a failure — there is no answer here.',
+    };
+  }
   // MORE OF IT WOBBLED THAN HELD STILL, and that one comparison is the whole rule. There is
   // no threshold here to tune and no number to defend: half is the point past which more of
   // the comparison has been thrown away than kept, and no answer computed from what is left
@@ -866,6 +896,121 @@ export function wobbleStorm(wobble) {
   return { stormy: true, share, looked, vanished, why };
 }
 
+/**
+ * Which journeys have no answer in them, asked ONE AT A TIME.
+ *
+ * This is `wobbleStorm` with the scope it should always have had. The rule inside it — more
+ * addresses wobbled than held still — is right, and it was being asked once, of everything
+ * added together. Measured 2026-08-31 on a real Next.js site: 179 unsteady addresses out of
+ * 2849 across twelve journeys is not a storm by any reading, and underneath that total sat
+ * four journeys that were unsteady at 69%, 75% and twice 100% of their own addresses. Two
+ * whole pages where every single address disagreed with itself were folded into a passing
+ * run by the nine pages that behaved.
+ *
+ * Adding journeys together is what did it. Each journey is its own measurement — its own
+ * pages, its own two walks, its own chance of falling over — and averaging a page that told
+ * you nothing with nine that told you plenty produces a number that describes no page at
+ * all. So the wobbles come in one per journey and the answer is a list, not a share.
+ *
+ * A journey in this list is NOT a failure and NOT a pass: whatever it disagreed with itself
+ * about was dropped before it could be compared, so the quiet underneath it is the quiet of
+ * nothing having been looked at. The caller owes it a named hole in the coverage and a
+ * verdict that is not `ok`.
+ *
+ * @param {Wobble[]} wobbles   One per journey, in the order they were walked.
+ * @returns {{journey: string, why: string, looked: number, unstable: number, steady: number, share: number}[]}
+ */
+export function noAnswerJourneys(wobbles) {
+  /** @type {{journey: string, why: string, looked: number, unstable: number, steady: number, share: number}[]} */
+  const out = [];
+  for (const wobble of wobbles) {
+    // The merged record is the whole run wearing one journey's shape, and asking it here
+    // would put the very scope bug this function exists to fix straight back in.
+    if (wobble.journey === '*') continue;
+    const storm = wobbleStorm(wobble);
+    if (!storm.stormy) continue;
+    out.push({
+      journey: wobble.journey,
+      why: storm.why,
+      looked: storm.looked,
+      unstable: wobble.unstable.length,
+      steady: wobble.steady,
+      share: storm.share,
+    });
+  }
+  return out;
+}
+
+/**
+ * WHAT KIND of disagreement this was: the answers moving, or the addresses themselves coming
+ * and going between the two passes.
+ *
+ * The two are folded into one number everywhere else — `unstable` — and they are not the
+ * same news. An answer that changed is the product wobbling, which is what the measurement
+ * is for. An address that only one of the two passes ever saw is the WALK not covering the
+ * same ground twice, and it is why the run's own headline count moves.
+ *
+ * Measured 2026-08-31, three checks of one untouched Next.js site, minutes apart, nothing
+ * edited between them: 2364, 2684 and 2861 addresses looked at, and 0, 179 and 500 of them
+ * unsteady. A tool whose whole method is running one thing twice and subtracting what
+ * disagrees cannot give three answers to one question and expect to be believed. Some of
+ * that spread is the product being genuinely unsteady, which is the measurement working;
+ * the ADDRESS COUNT moving by five hundred is not the product at all. Separating the two is
+ * what lets the run say which is which instead of quoting one number that means neither.
+ *
+ * @param {Wobble} wobble
+ * @returns {{changed: number, appeared: number, vanished: number, drifted: number, bothPasses: number, steady: number, looked: number}}
+ */
+export function wobbleShape(wobble) {
+  let changed = 0;
+  let appeared = 0;
+  let vanished = 0;
+  for (const e of wobble.entries) {
+    if (e.kind === 'changed') changed += 1;
+    else if (e.kind === 'appeared') appeared += 1;
+    else vanished += 1;
+  }
+  return {
+    changed,
+    appeared,
+    vanished,
+    // The addresses that exist on one pass and not the other. This is the part of the total
+    // that is the walk rather than the product, and the part that moves between runs.
+    drifted: appeared + vanished,
+    // The addresses BOTH passes actually reached. The steadiest count this run owns, and
+    // the honest one to quote.
+    bothPasses: wobble.steady + changed,
+    steady: wobble.steady,
+    looked: wobble.steady + wobble.unstable.length,
+  };
+}
+
+/**
+ * The sentence that names the drifting count, so no run has to invent its own wording for
+ * the one number readers were quoting at each other.
+ *
+ * It is said whenever the two passes of one build did not look at the same addresses. Empty
+ * when they did, because a sentence that appears on every single run is a sentence people
+ * learn to skip, and this one has to land when it is true.
+ *
+ * @param {Wobble} wobble
+ * @returns {string}   Empty when both passes covered the same ground.
+ */
+export function populationDriftNote(wobble) {
+  if (!wobble.measured) return '';
+  const shape = wobbleShape(wobble);
+  if (shape.drifted === 0) return '';
+  const parts = [];
+  if (shape.vanished > 0) parts.push(`${shape.vanished} ${shape.vanished === 1 ? 'address' : 'addresses'} the first pass saw ${shape.vanished === 1 ? 'was' : 'were'} not there on the second`);
+  if (shape.appeared > 0) parts.push(`${shape.appeared} ${shape.appeared === 1 ? 'address' : 'addresses'} turned up only on the second`);
+  return (
+    `THE TWO PASSES DID NOT LOOK AT THE SAME ADDRESSES: ${parts.join(', and ')}. ` +
+    `That is the walk moving, not the product answering differently — ${shape.changed} ${shape.changed === 1 ? 'address' : 'addresses'} really did give two different answers. ` +
+    `So the total of ${shape.looked} addresses is not a number that will be the same on the next run of the identical build; ` +
+    `${shape.bothPasses} is the count both passes actually reached, and it is the one to quote.`
+  );
+}
+
 /**
  * Subtract the measured noise from the differences.
  *