staysfixed 0.7.2 → 0.8.0

package/src/v2/ci.js

@@ -415,7 +415,12 @@ export async function referenceForCI(opts = {}) {
   }
 
   // ---- released ----------------------------------------------------------
-  const released = await releasedCommit(cwd, opts.product);
+  // Anything the store could not read travels with the answer and is said out loud, whether
+  // the answer was found or not. A run that says "this project has nothing on record as
+  // working" while a build folder sat there unreadable is stating a fact it does not have.
+  const releasedLook = await releasedCommit(cwd, opts.product);
+  const released = releasedLook.found;
+  const storeTrouble = releasedLook.trouble;
   if (released) {
     const found = await resolveCommit(cwd, released.sha);
     const sha = notThisBuild(found);
@@ -443,11 +448,12 @@ export async function referenceForCI(opts = {}) {
           'The fork point of this branch could not be worked out, so this was compared against the last shipped build instead. Anything else that was merged since that release will show up here as well, even though this branch did not do it.';
         result.unlockedBy = deepen;
       }
+      if (storeTrouble) result.caveat = result.caveat ? `${result.caveat} ${storeTrouble}` : storeTrouble;
       return result;
     }
-    else missed('released', `The project's reference points at ${short(released.sha)}, and that commit is not in this checkout.`, shallow ? deepen : 'Make sure the commit that was shipped is still in this repository.');
+    else missed('released', withTrouble(`The project's reference points at ${short(released.sha)}, and that commit is not in this checkout.`, storeTrouble), shallow ? deepen : 'Make sure the commit that was shipped is still in this repository.');
   } else {
-    missed('released', 'This project has no build on record as working. Only its owner can set one, by shipping.');
+    missed('released', withTrouble('This project has no build on record as working. Only its owner can set one, by shipping.', storeTrouble));
   }
 
   // ---- last tag ----------------------------------------------------------
@@ -491,7 +497,8 @@ export async function referenceForCI(opts = {}) {
   missed('previous-commit', 'There is no earlier commit in this checkout.', shallow ? deepen : undefined);
 
   // ---- stored record -----------------------------------------------------
-  const stored = await storedRecord(cwd, opts.product);
+  const storedLook = await storedRecord(cwd, opts.product);
+  const stored = storedLook.found;
   if (stored) {
     considered.push({ mode: 'stored-record', available: true, why: `There are stored observations for ${stored.buildId}.` });
     const same = stored.machine === 'same';
@@ -513,9 +520,14 @@ export async function referenceForCI(opts = {}) {
       machine: stored.machine,
     };
   }
-  missed('stored-record', 'There are no stored observations in this checkout either.', 'Commit the .staysfixed folder, or restore it from a cache written by a job on your main branch.');
+  missed('stored-record', withTrouble('There are no stored observations in this checkout either.', storedLook.trouble), 'Commit the .staysfixed folder, or restore it from a cache written by a job on your main branch.');
 
   // ---- nothing -----------------------------------------------------------
+  // The last line of this file is the one that says a whole checkout holds nothing to
+  // compare against, and it is read as final. It must not be said over the top of a store
+  // that was sitting right there with records nobody could open, so whatever the two looks
+  // in the store could not see is repeated here where a person will actually meet it.
+  const blindSpots = [storeTrouble, storedLook.trouble].filter((t) => t !== '');
   return {
     mode: 'none',
     against: null,
@@ -523,13 +535,27 @@ export async function referenceForCI(opts = {}) {
     strength: 'none',
     how: 'Nothing was found to compare against.',
     why: 'No named commit, no pull request base, no reference, no tag, no earlier commit and no stored record. There is nothing in this checkout that says what this product used to do.',
-    caveat: 'This run proves nothing about your product either way. It is not a pass.',
-    unlockedBy: deepen,
+    caveat:
+      blindSpots.length === 0
+        ? 'This run proves nothing about your product either way. It is not a pass.'
+        : `This run proves nothing about your product either way. It is not a pass. AND IT COULD NOT SEE EVERYTHING THERE IS: ${[...new Set(blindSpots)].join(' ')}`,
+    unlockedBy: blindSpots.length === 0 ? deepen : `${deepen} And repair or delete the build records named above, so the next run can read them.`,
     considered,
     shallow,
   };
 }
 
+/**
+ * Add what could not be seen to a sentence about what was not found.
+ *
+ * @param {string} said
+ * @param {string} trouble
+ * @returns {string}
+ */
+function withTrouble(said, trouble) {
+  return trouble ? `${said} ${trouble}` : said;
+}
+
 /**
  * The commit this branch forked from.
  *
@@ -585,6 +611,19 @@ async function findMergeBase(cwd, ci) {
   return null;
 }
 
+/**
+ * What a look in the store found, and what it could not see while looking.
+ *
+ * `trouble` is empty almost always. It carries a sentence when a build folder had to be
+ * skipped, or when the store would not open at all — and that sentence has to travel,
+ * because both of those turn "this project has nothing on record as working" into a claim
+ * the code is in no position to make. The build being asked for may well be one of the ones
+ * that could not be read.
+ *
+ * @template T
+ * @typedef {{found: T|null, trouble: string}} LookedInTheStore
+ */
+
 /**
  * The commit this project's own reference points at — the build somebody shipped.
  *
@@ -592,23 +631,35 @@ async function findMergeBase(cwd, ci) {
  *
  * @param {string} cwd
  * @param {string} [product]
- * @returns {Promise<{sha: string, note: string}|null>}
+ * @returns {Promise<LookedInTheStore<{sha: string, note: string}>>}
  */
 async function releasedCommit(cwd, product) {
+  /** @type {string[]} */
+  const skipped = [];
   try {
     const store = openStore({ root: cwd });
     const name = product ?? (await productName(cwd));
-    if (!name) return null;
+    if (!name) return { found: null, trouble: '' };
     const pointer = await referencePointer(store, name);
-    if (!pointer) return null;
-    const builds = await listBuilds(store, { product: name });
+    if (!pointer) return { found: null, trouble: '' };
+    // Until 2026-08-30 nothing was passed here, so a build folder that could not be read was
+    // simply not in the list — and "not in the list" is how this file spells "never existed".
+    // The build the reference pointer names is exactly the one most likely to have been
+    // written to most recently, and so exactly the one most likely to be the damaged folder.
+    const builds = await listBuilds(store, { product: name, onProblem: (m) => skipped.push(m) });
     const hit = builds.find((b) => b.fingerprint.id === pointer.buildId);
     const sha = hit?.fingerprint.gitSha ?? shaFromBuildId(pointer.buildId);
-    if (!sha) return null;
-    return { sha, note: hit?.fingerprint.version ? `version ${hit.fingerprint.version}` : '' };
-  } catch {
-    // A store that will not open is a reason to try the next mode, never a reason to fail.
-    return null;
+    if (!sha) return { found: null, trouble: troubleFrom(skipped, '') };
+    return {
+      found: { sha, note: hit?.fingerprint.version ? `version ${hit.fingerprint.version}` : '' },
+      // Named even on the way to a good answer. A reference found without the record that
+      // was supposed to describe it is a weaker answer than one found with it.
+      trouble: hit ? troubleFrom(skipped, '') : troubleFrom(skipped, `The record of build ${pointer.buildId} itself was not among them.`),
+    };
+  } catch (e) {
+    // A store that will not open is a reason to try the next mode, never a reason to fail —
+    // but it is never a reason to then say this project has nothing on record either.
+    return { found: null, trouble: troubleFrom(skipped, `The store here could not be read at all: ${messageOf(e)}`) };
   }
 }
 
@@ -617,26 +668,47 @@ async function releasedCommit(cwd, product) {
  *
  * @param {string} cwd
  * @param {string} [product]
- * @returns {Promise<{buildId: string, machine: 'same'|'different'|'unknown'}|null>}
+ * @returns {Promise<LookedInTheStore<{buildId: string, machine: 'same'|'different'|'unknown'}>>}
  */
 async function storedRecord(cwd, product) {
+  /** @type {string[]} */
+  const skipped = [];
   try {
     const store = openStore({ root: cwd });
     const name = product ?? (await productName(cwd));
-    if (!name) return null;
+    if (!name) return { found: null, trouble: '' };
     const pointer = await referencePointer(store, name);
-    const builds = await listBuilds(store, { product: name });
-    if (builds.length === 0) return null;
+    const builds = await listBuilds(store, { product: name, onProblem: (m) => skipped.push(m) });
+    if (builds.length === 0) return { found: null, trouble: troubleFrom(skipped, '') };
     const hit = (pointer && builds.find((b) => b.fingerprint.id === pointer.buildId)) || builds[0];
     const here = `${process.platform}-${process.arch}`;
     /** @type {'same'|'different'|'unknown'} */
     const machine = !hit.fingerprint.platform ? 'unknown' : hit.fingerprint.platform === here ? 'same' : 'different';
-    return { buildId: hit.fingerprint.id, machine };
-  } catch {
-    return null;
+    return { found: { buildId: hit.fingerprint.id, machine }, trouble: troubleFrom(skipped, '') };
+  } catch (e) {
+    return { found: null, trouble: troubleFrom(skipped, `The store here could not be read at all: ${messageOf(e)}`) };
   }
 }
 
+/**
+ * One sentence about what could not be seen, or nothing at all when everything could.
+ *
+ * @param {string[]} skipped
+ * @param {string} extra
+ * @returns {string}
+ */
+function troubleFrom(skipped, extra) {
+  /** @type {string[]} */
+  const parts = [];
+  if (skipped.length > 0) {
+    parts.push(
+      `${skipped.length} stored build ${skipped.length === 1 ? 'record was' : 'records were'} skipped because ${skipped.length === 1 ? 'it' : 'they'} could not be read, so what is on record here may be more than this run could see: ${skipped.join(' ')}`,
+    );
+  }
+  if (extra) parts.push(extra);
+  return parts.join(' ');
+}
+
 // ---------------------------------------------------------------------------
 // The report
 // ---------------------------------------------------------------------------
@@ -816,23 +888,31 @@ function findingLines(f) {
 /**
  * Append the report to the job summary, when the build server has one.
  *
- * Returns the file it wrote to, or null when there is nowhere to write. Null is a normal
- * answer on GitLab and CircleCI, neither of which has a summary page.
+ * TWO ANSWERS THAT USED TO BE ONE NULL. "This server has no summary page" is the normal
+ * state on GitLab and CircleCI and needs saying to nobody. "This server HAS one and the
+ * report did not reach it" is a report that has vanished — the person opens the job, sees
+ * the tab they expect, finds nothing under it, and concludes the check did not run. Both
+ * came back as null, so nothing anywhere could tell them apart or mention the second.
+ *
+ * The exit code is untouched either way. Losing the page must never cost the half that
+ * actually stops the merge.
  *
  * @param {CIReport} report
  * @param {CIEnvironment} [env]
- * @returns {Promise<string|null>}
+ * @returns {Promise<{file: string|null, why: string}>}  `why` is empty unless there was a
+ *   page to write to and writing failed.
  */
 export async function writeJobSummary(report, env) {
   const where = (env ?? detectCI()).summaryFile;
-  if (!where) return null;
+  if (!where) return { file: null, why: '' };
   try {
     await fsp.appendFile(where, `${report.markdown}\n`);
-    return where;
-  } catch {
-    // A summary page is a nicety. Losing it must never cost the exit code, which is the
-    // half that actually stops the merge.
-    return null;
+    return { file: where, why: '' };
+  } catch (e) {
+    return {
+      file: null,
+      why: `The report could not be written to this job's summary page (${where}): ${messageOf(e)}. The answer below is the whole of it.`,
+    };
   }
 }
 
@@ -931,12 +1011,27 @@ export async function runCI(opts = {}) {
 
   /** @type {string|null} */
   let evidence = null;
+  /** @type {string[]} */
+  const lost = [];
   try {
     evidence = await saveEvidence({ cwd, dir: opts.evidenceDir, verdict, reference, report, env: where });
-  } catch {
-    // Losing the attachment must never change the answer.
+  } catch (e) {
+    // Losing the attachment must never change the answer — and it must never be lost in
+    // silence either, because the report above says in so many words that the rest of the
+    // gaps are "in the evidence attached to this run". A run that swallowed this printed
+    // that sentence pointing at a folder that was never written.
+    lost.push(`THE EVIDENCE FOR THIS RUN WAS NOT SAVED: ${messageOf(e)} Anything the report says is in the attached evidence is not there, so what you can read above is all there is.`);
+  }
+  const summaryPage = await writeJobSummary(report, where);
+  if (summaryPage.why) lost.push(summaryPage.why);
+
+  // Onto the report itself, both shapes of it, rather than only into a log line. The
+  // markdown is what a person opens later and the text is what the job log keeps.
+  if (lost.length > 0) {
+    const said = lost.join(' ');
+    report.markdown = `${report.markdown}\n\n> **${said}**\n`;
+    report.text = `${report.text}\n${said}\n`;
   }
-  await writeJobSummary(report, where);
 
   if (opts.quiet !== true) process.stdout.write(`${report.text}\n`);
   return { exitCode: report.exitCode, report, reference, verdict, evidence };

package/src/v2/cli.js

@@ -35,7 +35,8 @@ import { escalationBlock, escalationsFor, productFor, writeEscalations } from '.
 // to mean two different things depending on which check you ran. src/cli/index.js imports
 // this file in turn; that circle is safe because nothing here touches it while either
 // module is still being evaluated.
-import { watchFlags } from '../cli/index.js';
+import { watchFlags } from '../cli/watch-flags.js';
+import { INIT_COMMANDS } from './init.js';
 
 /**
  * What comes back from a check. Everything that did not change never appears
@@ -102,35 +103,42 @@ const V1_OPTIONS = [
   ['--pictures', 'The version 1 picture check, unchanged.'],
   ['--guards', 'The version 1 guards, unchanged.'],
   ['--only <name>', 'Just this journey, screen or guard. Repeat it for several.'],
+  ['--record', 'The version 1 run that records network fixtures.'],
+  ['--report / --no-report', 'Write the version 1 HTML report. Version 1 checks only.'],
+  ['--profile', 'Print where the time went. Version 1 checks only.'],
 ];
 
 /**
- * The commands version 2 replaces, in exactly the shape `src/cli/index.js`
- * already uses for its own. Merging this over the existing table is the whole
- * of the wiring:
- *
- *     import { V2_COMMANDS } from '../v2/cli.js';
- *     Object.assign(COMMANDS, V2_COMMANDS);
- *
- * @type {Record<string, {summary: string, usage: string, describe: string, options: [string,string][], examples: string[], spec: {booleans?: string[], strings?: string[], arrays?: string[]}, load: () => Promise<{run: (ctx: any) => Promise<number>}>}>}
+ * Flags only version 1's check reads, by the name the parser knows them under.
+ *
+ * They are accepted on every `check` because the two halves share one spec — which is right,
+ * since `--pictures --profile` has to work. What was wrong is that typing one WITHOUT
+ * `--pictures` or `--guards` did nothing at all and said nothing at all: `staysfixed check
+ * --profile` ran a perfectly ordinary difference-engine check, printed no profile, and gave
+ * no hint that the flag had been ignored. A flag that is accepted and does nothing is the
+ * same lie as a flag that does not exist, and a slower one to find.
+ */
+const V1_ONLY_FLAGS = [
+  ['profile', '--profile'],
+  ['report', '--report'],
+  ['record', '--record'],
+];
+
+/**
+ * The commands version 2 contributes. `src/cli/index.js` merges these over version 1's,
+ * so `check` and `doctor` become the difference engine while everything version 1 did
+ * stays reachable behind `--pictures`, `--guards` and `--watch`.
  */
 export const V2_COMMANDS = {
-  // `staysfixed ship` comes from src/v2/ship.js. It is merged in here rather than into the
-  // version 1 command table so that wiring version 2 into the front door stays the one
-  // import it has always been.
+  // Version 2's init replaces version 1's.
   //
-  // `staysfixed init` from src/v2/init.js is deliberately NOT merged in yet, and this is
-  // the same call as the MCP server: version 2's init is a BREAKING change. Version 1's
-  // init writes settings for any folder; version 2's reads the project first and writes
-  // nothing when it cannot tell what the project is, which is better and is not what the
-  // three tests in test/cli.test.js describe. Somebody installed this last week and has
-  // `staysfixed init` in a setup script. Adding one line here —
-  //
-  //     import { INIT_COMMANDS } from './init.js';   ...INIT_COMMANDS,
-  //
-  // switches it over, and those three tests have to be rewritten in the same change to
-  // say what the new one does. That is a decision, not an oversight, and it belongs in a
-  // change of its own rather than arriving as a side effect of wiring up the phones.
+  // It was held back on the grounds that somebody might have `staysfixed init` in a
+  // setup script and would get a different file. True, and not a reason: the old one
+  // writes settings for photographing screens, which is not what this tool does any
+  // more, so leaving it in place hands a new project the wrong shape and calls it done.
+  // The three tests in test/cli.test.js were rewritten in the same change to say what
+  // the new one actually does.
+  ...INIT_COMMANDS,
   ...SHIP_COMMANDS,
 
   check: {
@@ -203,6 +211,16 @@ export async function run(ctx) {
     return await v1.run(ctx);
   }
 
+  // Say so when a flag was accepted and will do nothing.
+  //
+  // This goes to standard error, so it cannot corrupt --json, and it is a warning rather
+  // than a refusal: the person asked for a real check and they should still get one.
+  for (const [flag, written] of V1_ONLY_FLAGS) {
+    if (ctx.flags[flag] !== undefined) {
+      warn(`${written} only applies to the version 1 check. This run is the difference engine, so it was ignored — add --pictures or --guards if that is what you wanted.`);
+    }
+  }
+
   // --json means the answer belongs to a machine. Every line meant for a person
   // is switched off before anything else runs, rather than trusted not to
   // print: one stray sentence on standard output and the JSON will not parse.

package/src/v2/cluster.js

@@ -27,14 +27,6 @@ import { splitPath, sameValue } from './observation.js';
 /** @typedef {import('./types.js').Channel} Channel */
 /** @typedef {import('./types.js').ObservedValue} ObservedValue */
 
-/** How much of a cluster a finding carries with it. Enough to orient, not enough to bury. */
-const KEEP_NEAR_FILES = 5;
-
-/**
- * How many of a cluster's addresses travel with the finding. `count` always says how
- * many there really are, so a long cluster cannot hide its size behind a short list.
- */
-const KEEP_PATHS = 20;
 
 /**
  * How each channel introduces itself. This is the first half of every sentence
@@ -55,8 +47,25 @@ const CHANNEL_WORDS = {
 /**
  * Last segments too vague to identify anything alone. When an address ends in
  * one of these, the segment before it comes along for the ride.
+ *
+ * WHAT PUTS A WORD IN HERE. Every address ends either in something the PRODUCT
+ * named — an exported function, a route, a control, a field — or in a word this
+ * tool wrote to say what was being asked about it. The first kind identifies
+ * something on its own. The second kind is the same word on every journey, every
+ * door and every screen in the product, so a sentence built out of it names
+ * nothing: `"declared" is gone` was a real title, about a route that had been
+ * renamed, and the route was sitting one segment to the left the whole time.
+ * That sentence is not only read by an agent — it goes verbatim into the block a
+ * person reads in the closing summary, and the owner of this tool is not a coder.
+ *
+ * So this holds the words the tool writes, checked against the addresses the
+ * adapters actually produce rather than guessed at. `smartLeaf names the half a
+ * reader can act on` in the tests sweeps one real address of every shape through
+ * here; a new adapter that ends an address in a shared word belongs in that list
+ * and in this set on the same day.
  */
 const VAGUE = new Set([
+  // What was asked about a thing: the thing itself is one segment to the left.
   'value',
   'text',
   'name',
@@ -64,14 +73,45 @@ const VAGUE = new Set([
   'label',
   'title',
   'count',
+  'size',
+  'reason',
   'enabled',
   'visible',
   'status',
   'type',
   'id',
   'body',
+  'shape',
   'result',
   'exit',
+  // Doors, which all end the same way whatever the door is: a route, a command,
+  // an IPC channel, a named control on a phone.
+  'declared',
+  'registered',
+  'reached',
+  // What happened when we asked, on every surface there is.
+  'asked',
+  'answered',
+  'answered at all',
+  'ran at all',
+  'opened at all',
+  'walked',
+  'read',
+  'typed',
+  'pressed',
+  'done',
+  'started',
+  'finished',
+  'refused',
+  'settled',
+  'held still',
+  'looks like',
+  'written',
+  'still running',
+  'stdout',
+  'stderr',
+  'controls',
+  'picture',
 ]);
 
 /**
@@ -194,7 +234,15 @@ export function journeysOf(finding) {
  */
 function buildFinding(signature, members, rename, sources) {
   const head = members[0];
-  const nearFiles = unique(members.map((m) => sources[m.path])).slice(0, KEEP_NEAR_FILES);
+  // EVERY source file this finding touches, not the first five. The short list was written
+  // as "enough to orient, not enough to bury", and the things reading it are not orienting.
+  // `sealed.js` searches these names for the words nobody may wave through, so a finding
+  // whose sixth file was src/billing/refund.js was classified ordinary and became waivable;
+  // `intent.js` matches them against what the agent declared it was changing, and `cause.js`
+  // uses them to work out which edit caused what. A cap on the input to the one gate that
+  // cannot have a ceiling is the same bug that was closed for differences. Everything that
+  // DISPLAYS this list already cuts it itself and says "and N more" when it does.
+  const nearFiles = unique(members.map((m) => sources[m.path]));
   const evidence = members.find((m) => typeof m.evidence === 'string' && m.evidence.length > 0)?.evidence;
   // Half the differences in a rename are the "vanished" side, so the count of
   // places is the count of pairs, not of rows.
@@ -225,7 +273,16 @@ function buildFinding(signature, members, rename, sources) {
     // everything downstream — the MCP reply lists them, and the self-check corpus
     // matches its patterns against them — so they are filled in here rather than
     // left for each reader to dig out of `differences` in its own way.
-    paths: members.map((m) => m.path).slice(0, KEEP_PATHS),
+    // EVERY address, not the first twenty. The short list was there to keep a finding small,
+    // and it was buying nothing: the finding already carries `differences`, which holds the
+    // same addresses AND both values at each of them, so cutting this list saved a fraction
+    // of what was being stored anyway. What it cost was real. A waiver is pinned partly to
+    // this list, so two three-hundred-address findings that agreed about their first twenty
+    // pinned to the same thing; and the reply an agent reads prints the length of this list
+    // under the heading "every address that moved", which was a count of twenty about a
+    // finding with three hundred. Readers that want a short list still cut it themselves,
+    // and every one of them says "and N more" when it does.
+    paths: members.map((m) => m.path),
     sample: head,
   };
   if (nearFiles.length > 0) finding.nearFiles = nearFiles;
@@ -259,8 +316,23 @@ export function describe(d, count, rename, identical = true) {
   if (rename) return `${where}, "${rename.from}" is now called "${rename.to}".${spread}`;
 
   switch (d.kind) {
-    case 'changed':
-      return `${where}, "${name}" is now ${describeValue(d.candidate)} where it was ${describeValue(d.reference)}.${spread}`;
+    case 'changed': {
+      const now = describeValue(d.candidate);
+      const was = describeValue(d.reference);
+      if (now !== was) return `${where}, "${name}" is now ${now} where it was ${was}.${spread}`;
+      // BOTH SIDES CAME OUT IN THE SAME WORDS, so this sentence would say nothing changed
+      // while sitting on top of a difference. It is what happens whenever the two values
+      // are summarised by their SHAPE and the shape held still: an invoice line that went
+      // from "£49.99" to "49.99 GBP" read "is now a set of details (one field: line) where
+      // it was a set of details (one field: line)" — twice the same words, on the tool's own
+      // flagship example, in the paragraph a person reads rather than an agent. So the
+      // summary is put down and the thing that actually moved is named instead.
+      const moved = whatMoved(d.reference, d.candidate);
+      if (!moved) return `${where}, "${name}" changed, and both versions of it read the same at this length.${spread}`;
+      return moved.what === ''
+        ? `${where}, "${name}" now reads ${moved.now} where it read ${moved.was}.${spread}`
+        : `${where}, "${name}" now has "${moved.what}" reading ${moved.now} where it read ${moved.was}.${spread}`;
+    }
     case 'appeared':
       return `${where}, "${name}" is there now and was not before. It says ${describeValue(d.candidate)}.${spread}`;
     case 'vanished':
@@ -354,7 +426,86 @@ export function describeValue(value) {
   if (Array.isArray(value)) return `a list of ${value.length}`;
   const keys = Object.keys(/** @type {object} */ (value));
   if (keys.length === 0) return 'an empty set of details';
-  return `a set of details (${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ', and more' : ''})`;
+  // The field names are quoted and counted. Bare, they run into the sentence around them and
+  // stop looking like names at all: a shape whose fields are the words "a list of" and "each
+  // one" came out as "a set of details (a list of, each one)", which is not a thing anybody
+  // can picture. Quoted, it reads as what it is.
+  const shown = keys.slice(0, 4).map((k) => JSON.stringify(k)).join(', ');
+  return `a set of details (${keys.length === 1 ? 'one field' : `${keys.length} fields`}: ${shown}${keys.length > 4 ? ', and more' : ''})`;
+}
+
+/**
+ * The smallest thing that actually moved between two values.
+ *
+ * Only reached when a summary of the two whole values comes out identical, which is exactly
+ * when a summary is the wrong thing to print. It walks in until it finds the one field, or
+ * the one stretch of text, that is not the same, and hands back that piece with a name for
+ * it. `sameValue` is the tool's one comparison, so what counts as "not the same" here is
+ * what counts as a difference everywhere else.
+ *
+ * @param {ObservedValue|undefined} reference
+ * @param {ObservedValue|undefined} candidate
+ * @param {string[]} [trail]
+ * @returns {{what: string, was: string, now: string}|null}
+ */
+function whatMoved(reference, candidate, trail = []) {
+  if (isSetOfDetails(reference) && isSetOfDetails(candidate)) {
+    for (const key of [...new Set([...Object.keys(reference), ...Object.keys(candidate)])].sort()) {
+      const a = /** @type {Record<string, any>} */ (reference)[key];
+      const b = /** @type {Record<string, any>} */ (candidate)[key];
+      if (sameValue(a, b)) continue;
+      return whatMoved(a, b, [...trail, key]);
+    }
+    return null;
+  }
+  if (Array.isArray(reference) && Array.isArray(candidate)) {
+    for (let i = 0; i < Math.max(reference.length, candidate.length); i += 1) {
+      if (sameValue(reference[i], candidate[i])) continue;
+      return whatMoved(reference[i], candidate[i], [...trail, `number ${i + 1}`]);
+    }
+    return null;
+  }
+  const what = trail.join(' / ');
+  if (typeof reference === 'string' && typeof candidate === 'string') {
+    // Two long strings summarise to their first sixty-odd characters, so if they agree that
+    // far they read the same however differently they end. A window round the first place
+    // they part company says what neither summary can.
+    const spot = firstDifference(reference, candidate);
+    return { what, was: JSON.stringify(spot.was), now: JSON.stringify(spot.now) };
+  }
+  const was = describeValue(reference);
+  const now = describeValue(candidate);
+  return was === now ? null : { what, was, now };
+}
+
+/**
+ * A window round the first character two pieces of text stop agreeing at, with enough either
+ * side to recognise the place.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {{was: string, now: string}}
+ */
+function firstDifference(a, b) {
+  // Short enough to read whole, so read it whole. A window round the difference is only
+  // worth its ellipses when there is genuinely too much text to print.
+  if (a.length <= 70 && b.length <= 70) return { was: a, now: b };
+  let at = 0;
+  while (at < a.length && at < b.length && a[at] === b[at]) at += 1;
+  const from = Math.max(0, at - 20);
+  /** @param {string} text */
+  const window = (text) => `${from > 0 ? '…' : ''}${text.slice(from, at + 40)}${at + 40 < text.length ? '…' : ''}`;
+  return { was: window(a), now: window(b) };
+}
+
+/**
+ * A value made of named fields, as opposed to a list, a number, or a piece of text.
+ *
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isSetOfDetails(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
 /**