staysfixed 0.11.1 → 0.13.0

package/src/v2/adapters/android.js

@@ -9,6 +9,27 @@
  * Everything below is arranged around that: one device, one build at a time, the whole
  * machine put back in between.
  *
+ * IS THAT GOOD ENOUGH FOR A PAIRED RUN? YES, AND IT HAS NOW BEEN MEASURED.
+ *
+ * Until 2026-08-31 this file said a paired run was not offered here, because nobody had proven
+ * that two emulator snapshots come back the same. That was a guess. It was measured that day,
+ * on an Apple Silicon Mac, against Terminal Deck's own Android app (dev.terminaldeck.apk.debug
+ * 0.13.0) on the `sfx_a33` virtual device — Android 13, Google APIs, arm64, no Play Store.
+ *
+ * One build was walked TEN times, and the device was put back from its own snapshot between
+ * every one of them, which is exactly what happens between the two builds of a paired run.
+ * Five pairs, 309 addresses in each walk. 301 of those 309 agreed in every single pair. The
+ * eight that did not were one thing seen at eight checkpoints: the identity code this app
+ * makes fresh for itself every time it is installed. A control run with the snapshot restore
+ * switched OFF produced the same eight and no others — so the restore contributed exactly
+ * zero disagreements, and the eight belong to the app, not to the emulator.
+ *
+ * Eight addresses out of 309 that move on their own is ordinary wobble, and the engine
+ * already measures and subtracts it: the new build is always walked twice and anything that
+ * cannot answer the same way twice is taken out of the comparison before a single difference
+ * is reported. So a paired Android run is offered, and what actually limits it is not the
+ * device at all — it is getting hold of the OLD build's package. See `prepare`.
+ *
  * What is read, and in which channel:
  *
  *   CONTRACT    Everything the APK declares, read out of the file without installing it and
@@ -517,6 +538,93 @@ export function screenObservations(input) {
 /** Keyed by build id, emptied on teardown. Never shared between two builds. */
 const open = new Map();
 
+/**
+ * Which file each half of a comparison was walked from, remembered across the whole run.
+ *
+ * It has to live out here rather than inside a prepared build, because the engine prepares
+ * ONE build, walks ONE journey against it and throws it away again before the next: nothing
+ * that lives on a prepared build survives long enough to notice that the old build and the
+ * new build were the same file.
+ *
+ * And that is the thing worth noticing. `android.apk` in the settings is very often an
+ * absolute path, and an absolute path does not move when the old commit is checked out
+ * somewhere else — so both halves of a paired run read the SAME package, find no differences
+ * at all, and the run says "nothing that worked has changed" about a comparison that never
+ * happened. That is the one failure this tool exists to prevent, arriving through the front
+ * door. Anything found here is reported as a hole on every journey the reference walked; see
+ * `sameFileAsTheOtherHalf` below.
+ *
+ * Keyed by role — 'candidate' or 'reference' — and emptied by `teardown`.
+ *
+ * @type {Map<string, string>}
+ */
+const walkedFrom = new Map();
+
+/**
+ * The build ids that turned out to be the other half of the comparison, and the sentence
+ * that says so.
+ *
+ * Separate from `open` above because `open` only holds builds that reached a device, and the
+ * dangerous case is the one that does NOT: on a machine with no emulator this adapter still
+ * reads everything the package declares, and one package compared against itself declares
+ * exactly the same things. That is a clean, confident, meaningless all-clear, and it has to
+ * carry the warning like every other journey does.
+ *
+ * @type {Map<string, string>}
+ */
+const sameFileFor = new Map();
+
+/**
+ * Which file this really is: the path with the links and the `..`s taken out.
+ *
+ * A symlink, a `./` and a `..` must not be able to make one file look like two, because one
+ * file looking like two is the whole failure being guarded against here.
+ *
+ * @param {string} file
+ * @returns {Promise<string>}
+ */
+async function artifactIdentity(file) {
+  try {
+    return await fsp.realpath(file);
+  } catch {
+    // A path that will not resolve is still worth remembering exactly as it was typed. The
+    // question below is whether the two halves agree, not whether the file is there.
+    return file;
+  }
+}
+
+/**
+ * Did this half of the comparison read the same package as the other half?
+ *
+ * Returns the sentence to put in front of a reader, or null when the two halves really are
+ * two different files.
+ *
+ * WHAT IT DOES NOT CATCH, said here rather than left to be discovered: two different paths
+ * holding the same build. Somebody whose release script copies today's package to
+ * `builds/latest.apk` and points `reference` at it is comparing one build against itself with
+ * two names, and nothing here notices. That was left alone on purpose — two different files
+ * are usually two builds somebody produced on purpose, and refusing them on a guess would
+ * block real comparisons to prevent an unusual one.
+ *
+ * @param {'reference'|'candidate'} role
+ * @param {string} mine
+ * @returns {string|null}
+ */
+function sameFileAsTheOtherHalf(role, mine) {
+  // Only ever asked about the OLD build's half, and that is not squeamishness — it is the
+  // only answer that stays the same from one journey to the next. The engine prepares a
+  // build, walks ONE journey against it and throws it away, and it always does the new build
+  // first: new-run-a, new-run-b, old-run-a, old-run-b, then the same four again for the next
+  // journey. So from the second journey onwards the new build's half would find the previous
+  // journey's old half sitting in the map and flag itself as well — the warning would be
+  // absent on the first journey and doubled on every one after it, which reads like a bug in
+  // the tool rather than a fact about the run.
+  if (role !== 'reference') return null;
+  const other = walkedFrom.get('candidate');
+  if (!other || other !== mine) return null;
+  return `Both halves of this comparison were walked from the same file: ${mine}. Nothing in it is older or newer than anything else in it, so no difference between the two builds could possibly show up.`;
+}
+
 /**
  * Read the size out of a PNG without decoding it.
  *
@@ -532,6 +640,25 @@ export function pngSize(png) {
   return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
 }
 
+/**
+ * Where a kept copy of the OLD build's package lives, if the settings name one.
+ *
+ * Two spellings, because both read naturally and neither is worth an argument:
+ * `{"reference": "builds/0.14.0.apk"}` and `{"reference": {"apk": "builds/0.14.0.apk"}}`.
+ * A relative path is resolved against whatever `findApk` is given, which for the reference
+ * half is the checkout of the old commit — so a project that DOES commit its package can
+ * simply leave this out and everything still works.
+ *
+ * @param {Record<string, any>} config
+ * @returns {string|undefined}
+ */
+export function referenceArtifact(config) {
+  const said = config?.reference;
+  if (typeof said === 'string' && said.trim() !== '') return said;
+  if (said && typeof said === 'object' && typeof said.apk === 'string' && said.apk.trim() !== '') return said.apk;
+  return undefined;
+}
+
 /**
  * Choose how the device gets put back between builds, and say what that costs.
  *
@@ -657,6 +784,7 @@ export const androidAdapter = defineAdapter({
         ...notes,
         'What is compared is what the screen MEANS — the roles, names and states a screen reader would read — and every control is found by what it is, never by where it sits. Moving something, restyling it, or wrapping it in another layout reports nothing.',
         'The two builds are never installed at once. Android allows one app of a given name on a device, so each build is installed, walked and removed, and the whole device is put back in between.',
+        'Putting the device back really does put it back, and that is measured rather than assumed. On 2026-08-31 one build was walked ten times on an emulator with a snapshot restore between every walk: 301 of 309 addresses agreed in all five pairs, and the eight that did not were the app\'s own freshly-made identity code — a control run with no restore at all produced exactly the same eight. So a paired run is offered here. What it needs from you is a copy of the OLD build\'s package, because an APK is a build output and a checkout of the old commit does not contain one: name it with {"reference": "path/to/the-old.apk"} under "android" in the settings.',
         'Nothing is allowed off this machine. Every call the app makes is written down at a proxy and stopped there — which also means what is inside an encrypted request is never seen, and is reported as unchecked rather than as fine.',
       ],
     };
@@ -690,14 +818,51 @@ export const androidAdapter = defineAdapter({
     const base = path.join(ctx.scratchDir, `android-${build.id.slice(0, 12).replace(/[^A-Za-z0-9_-]/g, '-')}`);
     await fsp.mkdir(base, { recursive: true });
 
+    // Worked out a few lines below, and captured here so that even a build which could not
+    // be got ready still says it. A reference half that failed AND was the same file as the
+    // candidate is two separate pieces of bad news, and the second one is the one that would
+    // otherwise be lost — the run would report "could not be prepared", somebody would fix
+    // that, and the comparison would come back green for the wrong reason.
+    /** @type {string|null} */
+    let sameFile = null;
+
     /** @param {string} why */
     const notReady = (why) => ({
-      build, root: base, ready: false, why,
-      dispose: async () => { await fsp.rm(base, { recursive: true, force: true }); },
+      build,
+      root: base,
+      ready: false,
+      why: sameFile ? `${why} ${sameFile}` : why,
+      ...(build.role === 'reference' ? { facts: { paired: sameFile === null } } : {}),
+      dispose: async () => {
+        sameFileFor.delete(build.id);
+        await fsp.rm(base, { recursive: true, force: true });
+      },
     });
 
-    const found = await findApk(build.artifact ? path.dirname(build.artifact) : build.root, { ...config, apk: build.artifact ?? config.apk });
-    if (!found.path) return notReady(`There is no APK for ${build.label}: ${found.why}.`);
+    // WHICH package this half of the comparison walks.
+    //
+    // For the build you have, that is whatever the settings point at. For the build you were
+    // happy with it is different, and the difference is the whole of paired mode on a phone:
+    // the engine hands over a checkout of the old commit, and an APK is a BUILD OUTPUT that
+    // nobody commits, so a checkout of the old commit contains no app at all. `android.reference`
+    // is where a kept copy of the old build's package goes, and it is looked at first for the
+    // reference half and never for the candidate.
+    const wanted = build.role === 'reference' ? (referenceArtifact(config) ?? config.apk) : config.apk;
+    const found = await findApk(build.artifact ? path.dirname(build.artifact) : build.root, { ...config, apk: build.artifact ?? wanted });
+    if (!found.path) {
+      return notReady(
+        `There is no APK for ${build.label}: ${found.why}.` +
+        (build.role === 'reference'
+          ? ' A paired run walks the OLD build here, and an APK is a build output that a repository does not commit — so a checkout of the old commit has no app in it. Keep a copy of each release\'s package and point at it with {"reference": "path/to/the-old.apk"} under "android" in the settings, and this becomes a real comparison. Without it this journey falls back to the record the old build left the last time it ran, which is weaker and says so.'
+          : ''),
+      );
+    }
+
+    // Two halves, one file. Worked out here, said on every journey — see `run`.
+    const mine = await artifactIdentity(found.path);
+    sameFile = sameFileAsTheOtherHalf(/** @type {'reference'|'candidate'} */ (build.role), mine);
+    walkedFrom.set(build.role, mine);
+    if (sameFile) sameFileFor.set(build.id, sameFile);
     const apk = await readApk(found.path);
     if (!apk.ok) return notReady(`The APK for ${build.label} could not be read: ${apk.why}`);
 
@@ -708,8 +873,16 @@ export const androidAdapter = defineAdapter({
       return {
         build, root: base, ready: true,
         why: `adb is not on this machine, so ${build.label} cannot be installed or opened. What it declares — its version, its permissions and all ${apk.components.length} of its components — is still read straight out of the file, and every journey that needs a device is reported as unchecked rather than passed.`,
-        facts: { apk: found.path, pkg: apk.pkg, deviceless: true },
-        dispose: async () => { await fsp.rm(base, { recursive: true, force: true }); },
+        facts: {
+          apk: found.path,
+          pkg: apk.pkg,
+          deviceless: true,
+          ...(build.role === 'reference' ? { paired: sameFile === null } : {}),
+        },
+        dispose: async () => {
+          sameFileFor.delete(build.id);
+          await fsp.rm(base, { recursive: true, force: true });
+        },
       };
     }
 
@@ -791,7 +964,7 @@ export const androidAdapter = defineAdapter({
       build,
       root: base,
       ready: true,
-      why: `${build.label} is installed on ${serial} (${apk.pkg} ${apk.versionName ?? ''} build ${apk.versionCode ?? '?'}). The clock, the time zone, the text size and every animation are pinned, the first launch has been used up and thrown away, and between builds the device is put back ${reset === 'snapshot' ? 'completely, from a snapshot taken before anything was installed' : 'by removing the app — which does not undo anything it changed elsewhere on the device'}.${caveats.length > 0 ? ` Worth knowing: ${caveats.join('; ')}.` : ''}`,
+      why: `${build.label} is installed on ${serial} (${apk.pkg} ${apk.versionName ?? ''} build ${apk.versionCode ?? '?'}). The clock, the time zone, the text size and every animation are pinned, the first launch has been used up and thrown away, and between builds the device is put back ${reset === 'snapshot' ? 'completely, from a snapshot taken before anything was installed' : 'by removing the app — which does not undo anything it changed elsewhere on the device'}.${sameFile ? ` ${sameFile}` : ''}${caveats.length > 0 ? ` Worth knowing: ${caveats.join('; ')}.` : ''}`,
       facts: {
         serial: /** @type {string} */ (serial),
         pkg: apk.pkg,
@@ -800,9 +973,13 @@ export const androidAdapter = defineAdapter({
         rooted: device.rooted === true,
         firstLaunchMs: warmMs,
         ownsDevice,
+        // Only ever set on the OLD build's half, because that is the half the question is
+        // about: was there really a second build here, or did both halves read one file.
+        ...(build.role === 'reference' ? { paired: sameFile === null } : {}),
       },
       dispose: async () => {
         open.delete(build.id);
+        sameFileFor.delete(build.id);
         try {
           await resetDevice(session);
         } catch {
@@ -828,18 +1005,44 @@ export const androidAdapter = defineAdapter({
     const out = [];
     const session = open.get(prepared.build.id);
 
+    // FIRST, BEFORE ANY JOURNEY INCLUDING THE ONE THAT NEEDS NO DEVICE.
+    //
+    // Said on every journey rather than once at the start, which is the same rule the web
+    // adapter follows for an app read at a fixed address. A run that compared one file
+    // against itself finds no differences, and "no differences" is the sentence this whole
+    // tool is believed for.
+    //
+    // It has to come before the contract journey below rather than after it, and that
+    // ordering is the whole point. The contract journey needs no emulator at all — it reads
+    // the package's own manifest — so on a machine with no device it is the ONLY thing that
+    // runs, and it is exactly where one file compared against itself produces a complete,
+    // confident, meaningless all-clear. This check first went in after that early return, on
+    // 2026-08-31, and the deviceless case was still wide open; it was caught by running it
+    // against a real emulator and reading the answer rather than the code.
+    const sameFile = sameFileFor.get(prepared.build.id);
+    if (sameFile) {
+      out.push(notCovered({
+        channel: 'meaning',
+        path: joinPath('screen', journey.name, 'which build this was'),
+        reason: 'not supported here',
+        says:
+          `${sameFile} An APK is a build output, so a checkout of the old commit does not contain one and the settings' own path was used for both halves. ` +
+          'Keep a copy of the package you shipped and name it with {"reference": "path/to/the-old.apk"} under "android" in the settings, and this becomes a real comparison.',
+      }));
+    }
+
     // The one journey that needs nothing but the file.
     if (journey.name === DECLARED) {
       const apkPath = String(prepared.facts?.apk ?? session?.apkPath ?? '');
       const apk = session?.apk ?? (apkPath ? await readApk(apkPath) : null);
       if (!apk?.ok) {
-        return [notCovered({ channel: 'contract', path: ['manifest', 'read'], reason: 'missing tool', says: 'the app file could not be read, so nothing it declares was checked' })];
+        return [...out, notCovered({ channel: 'contract', path: ['manifest', 'read'], reason: 'missing tool', says: 'the app file could not be read, so nothing it declares was checked' })];
       }
-      return declaredObservations(apk, apkPath);
+      return [...out, ...declaredObservations(apk, apkPath)];
     }
 
     if (!session) {
-      return [notCovered({
+      return [...out, notCovered({
         channel: 'meaning',
         path: joinPath('screen', journey.name, 'walked'),
         reason: 'missing tool',
@@ -850,8 +1053,9 @@ export const androidAdapter = defineAdapter({
     const { device, apk } = session;
     const started = Date.now();
 
+
     if (journey.irreversible && ctx.allowIrreversible !== true) {
-      return [notCovered({
+      return [...out, notCovered({
         channel: 'effects',
         path: joinPath('screen', journey.name, 'walked'),
         reason: 'irreversible',
@@ -1238,6 +1442,11 @@ export const androidAdapter = defineAdapter({
       }
       open.delete(id);
     }
+    // One run's memory of which file each half was walked from. It must not survive into the
+    // next run in the same process — the MCP server and the watch panel both call check()
+    // more than once — or a second run would report the first run's packages as its own.
+    walkedFrom.clear();
+    sameFileFor.clear();
   },
 });
 

package/src/v2/adapters/child.js

@@ -21,6 +21,8 @@
 
 import { spawn } from 'node:child_process';
 
+import { stopTree, OWN_PROCESS_GROUP } from '../../core/stop-tree.js';
+
 /**
  * Start the product, in a group of its own.
  *
@@ -34,9 +36,10 @@ export function spawnServer(command, opts) {
     cwd: opts.cwd,
     env: opts.env,
     stdio: opts.stdio ?? ['ignore', 'pipe', 'pipe'],
-    // The whole point. On Windows there are no process groups of this kind, and killing the
-    // child is the best that can be done there.
-    detached: process.platform !== 'win32',
+    // The whole point. Windows has no process groups of this kind, and `detached` there means
+    // a console window of its own instead — so Windows is left alone at spawn time and gets
+    // its whole tree stopped by `stopTree` below, which walks the children itself.
+    detached: OWN_PROCESS_GROUP,
   });
 }
 
@@ -52,21 +55,16 @@ export async function stopServer(child, opts = {}) {
   const pid = child.pid;
   const graceMs = opts.graceMs ?? 500;
 
-  /** @param {NodeJS.Signals} signal */
+  /**
+   * @param {'SIGTERM'|'SIGKILL'} signal
+   */
   const tellTheGroup = (signal) => {
-    if (!pid) return;
-    try {
-      // A negative pid is the GROUP. This is the line that makes the difference.
-      if (process.platform === 'win32') child.kill(signal);
-      else process.kill(-pid, signal);
-    } catch {
-      // No group, or already gone. Ask the one process we definitely know about.
-      try {
-        child.kill(signal);
-      } catch {
-        // Already gone, which is the outcome wanted.
-      }
-    }
+    // The group on Linux and a Mac, the tree of children on Windows. Killing only the shell
+    // on Windows left the server running and holding the folder it was started in: measured
+    // on a real Windows 11 machine on 2026-08-31, where the whole of `waiting.test.js` failed
+    // on being unable to delete its own scratch folder afterwards, because the servers it had
+    // asked to stop were all still there.
+    stopTree(pid, signal, { child });
   };
 
   if (child.exitCode === null && child.signalCode === null) {

package/src/v2/adapters/contract.js

@@ -378,6 +378,10 @@ export function compareJson(a, b) {
  * @param {string} spec.says
  * @param {boolean} [spec.covered]        False means we did not really look. See `reason`.
  * @param {NotCoveredReason} [spec.reason]
+ * @param {string} [spec.detail]          What the thing itself said, in its own words, when it
+ *                                        said anything. Goes onto the refusal's reason, which
+ *                                        is where a person reads why a hole is a hole. Never
+ *                                        compared — see `whatItSaid` for why that matters.
  * @param {{file?: string, line?: number, url?: string}} [spec.where]
  * @param {string} [spec.evidence]
  * @param {string} [spec.journey]
@@ -414,7 +418,16 @@ export function observation(spec) {
     // — and never this flag. Written down on 2026-08-31 after the refusal lane found the two
     // meanings sharing one field.
     meta.refused = true;
-    meta.refusedWhy = `${NOT_COVERED_MEANING[spec.reason ?? 'refused']} (${spec.reason ?? 'refused'})`;
+    // The reason word stays first and stays in the fixed vocabulary, because the ledger counts
+    // these and a free-text reason cannot be counted. What the thing ITSELF said goes on the
+    // end. That position is deliberate: `staysfixed coverage` prints this line with a 400
+    // character budget and the sentence above it with 160, so this is the place where the real
+    // error — the `ModuleNotFoundError`, the `SyntaxError` — reliably survives being trimmed
+    // and reaches the person who has to go and fix it. Added 2026-08-31, after three broken
+    // products were checked and none of their owners was ever told what was wrong.
+    meta.refusedWhy = `${NOT_COVERED_MEANING[spec.reason ?? 'refused']} (${spec.reason ?? 'refused'})${
+      spec.detail ? ` — and this is what it said for itself: ${spec.detail}` : ''
+    }`;
   }
   return makeObservation(path, spec.channel, stableValue(spec.value), meta);
 }
@@ -431,6 +444,7 @@ export function observation(spec) {
  * @param {string|(string|number)[]} spec.path
  * @param {NotCoveredReason} spec.reason
  * @param {string} spec.says              What we would have looked at, and why we did not.
+ * @param {string} [spec.detail]          What the thing itself said about it, in its own words.
  * @param {{file?: string, line?: number, url?: string}} [spec.where]
  * @returns {Observation}
  */
@@ -438,10 +452,15 @@ export function notCovered(spec) {
   return observation({
     channel: spec.channel,
     path: spec.path,
+    // The VALUE stays the fixed sentence and never carries what the thing said. Two builds
+    // that fall over with two different messages would otherwise differ at this address, and
+    // the report would call a crash a change in the product. The words go in `says` and in the
+    // refusal's reason, neither of which is ever compared.
     value: `not checked — ${NOT_COVERED_MEANING[spec.reason]}`,
     says: spec.says,
     covered: false,
     reason: spec.reason,
+    detail: spec.detail,
     where: spec.where,
   });
 }
@@ -610,6 +629,108 @@ export function undoOurFootprint(text, footprint) {
   return out;
 }
 
+/**
+ * What a program said about itself, cut down to the part a person can act on.
+ *
+ * WHY THIS EXISTS. Measured on 2026-08-31, against three deliberately broken products: a Node
+ * server whose source has a syntax error, a Python command importing a module that is not
+ * installed, and a Node command importing a package that is not installed. All three were
+ * correctly refused — no false all-clear, and that half worked. But a grep of the whole reply,
+ * `--verbose` included, found no mention of `SyntaxError`, `ModuleNotFoundError` or
+ * `ERR_MODULE_NOT_FOUND` anywhere in it. Every owner was told "the thing being observed fell
+ * over before it could be read" and then had to go and find the reason themselves. Each
+ * product had printed the reason, in one line, on its own standard error, and this tool threw
+ * it away. Handing somebody a sentence they can act on is the whole design; this is the
+ * function that keeps the product's own sentence instead of a paraphrase of it.
+ *
+ * NOTHING IS INVENTED HERE. What comes out is the program's own words. What is dropped is only
+ * what carries nothing for the person reading: blank lines, the `at ...` frames of a stack
+ * trace, the caret lines that underline a column of a terminal that is not this one, "... 4
+ * more" frame counts, and Node's own version footer. What is left over the budget is dropped
+ * from the FRONT, because every runtime in use here — Node, Python, a shell — puts the
+ * sentence that says what went wrong at the END of what it printed.
+ *
+ * This is evidence, not noise, and it belongs in the reply. It is never compared: it goes into
+ * the sentence and into the refusal's reason, both of which live in `meta`, so a crash that
+ * words itself differently on two machines can never register as a difference in the product.
+ *
+ * @param {string} text            Whatever the thing printed. Run our own footprint out of it
+ *                                 first, or a scratch path ends up quoted at a person.
+ * @param {object} [opts]
+ * @param {number} [opts.mostLines]  How many lines of it to keep. Default 6.
+ * @param {number} [opts.mostChars]  How many characters of it to keep. Default 300.
+ * @returns {string}  One line, or '' when it said nothing worth repeating.
+ */
+export function whatItSaid(text, opts = {}) {
+  const mostLines = opts.mostLines ?? 6;
+  const mostChars = opts.mostChars ?? 300;
+  const lines = String(text ?? '')
+    // Colour codes are how a program makes an error red in a terminal. Printed into a
+    // sentence they are unreadable rubbish, and they are not part of what it said.
+    .replace(/\u001b\[[0-9;]*m/g, '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !NOT_WORTH_REPEATING.some((noise) => noise.test(line)));
+  if (lines.length === 0) return '';
+
+  // ONE LINE MEANS THE ONE THAT NAMES THE TROUBLE, not simply the last one.
+  //
+  // "The last line" was the first thing tried and it is wrong often enough to matter: measured
+  // 2026-08-31 on a Node command importing a package that is not installed, Node printed the
+  // whole error object after the message, so the last line was `}` and the headline read "It
+  // said: }." — which is worse than saying nothing. So the line that looks like a runtime
+  // naming a fault is preferred, and the last line is what happens when none does. Preferred,
+  // never required: nothing is dropped by this, it only decides which single line gets quoted
+  // where there is room for one, and the fuller quote sits directly underneath it.
+  if (mostLines === 1) {
+    const named = [...lines].reverse().find((line) => NAMES_THE_TROUBLE.test(line)) ?? lines[lines.length - 1];
+    return named.length > mostChars ? `${named.slice(0, mostChars - 3)}...` : named;
+  }
+
+  /** @type {string[]} */
+  const kept = [];
+  let used = 0;
+  for (let i = lines.length - 1; i >= 0 && kept.length < mostLines; i--) {
+    const line = lines[i];
+    if (kept.length > 0 && used + line.length + 3 > mostChars) break;
+    kept.unshift(line);
+    used += line.length + 3;
+  }
+  // One line longer than the whole budget is still the line that says what went wrong, so it
+  // is kept and cut rather than dropped for being too long.
+  if (kept.length === 1 && kept[0].length > mostChars) kept[0] = `${kept[0].slice(0, mostChars - 3)}...`;
+  const left = lines.length - kept.length;
+  // Said out loud rather than trimmed silently: a reader who is told six lines were left out
+  // knows to open the evidence file, and a reader who is not told assumes they have all of it.
+  return `${left > 0 ? `(${left} earlier ${left === 1 ? 'line' : 'lines'} left out) ` : ''}${kept.join(' / ')}`;
+}
+
+/**
+ * A line that reads like a runtime saying what went wrong.
+ *
+ * The three shapes measured on 2026-08-31, one from each broken product: `SyntaxError:
+ * Unexpected end of input`, `ModuleNotFoundError: No module named 'tabulate'`, and `Error
+ * [ERR_MODULE_NOT_FOUND]: Cannot find package 'chalk' imported from ...`. The second pattern is
+ * for the tools that write their trouble in lower case instead — a compiler, git, a shell.
+ */
+const NAMES_THE_TROUBLE =
+  /^[A-Za-z_$][A-Za-z0-9_$.]*(?:Error|Exception|Warning)(?:\s*\[[^\]]*\])?\s*:|^(?:fatal|error|panic|Traceback)\b/i;
+
+/**
+ * Lines that are in the way of the sentence rather than part of it.
+ *
+ * Deliberately short. Every pattern here has to be something that cannot possibly BE the
+ * reason a product fell over — a stack frame under the message, a caret underlining a column,
+ * a version footer. Anything else stays, because a rule that guesses which of a program's own
+ * lines matter is a rule that will one day drop the only line that did.
+ */
+const NOT_WORTH_REPEATING = [
+  /^at\s+\S/,                    // a stack frame under the message that already said it
+  /^[\^~]+$/,                    // the caret line underlining a column in somebody else's terminal
+  /^\.\.\.\s*\d+\s+more$/,        // "... 4 more", the frames a runtime left out itself
+  /^Node\.js v[\d.]+$/,          // Node's version footer, printed under every uncaught throw
+];
+
 /**
  * Keep a piece of text at a size worth storing.
  *