simframe 0.10.0 → 0.12.0

package/scripts/ci-memory.mjs

@@ -56,6 +56,36 @@ function check(ok, label, detail = '') {
   return ok;
 }
 
+let skipped = 0;
+
+/**
+ * A check whose *setup* did not happen, reported as untested rather than failed.
+ *
+ * This exists because the harness did to itself what three peer reports spent a
+ * day telling us not to do to callers. A `simctl launch` timed out on a loaded
+ * runner, `allowFail` swallowed it, and the next check announced `FAIL the
+ * screen actually changed before testing the stale ref — 7070f77757 ->
+ * 7070f77757`. Every word of that is true and it names the wrong thing: the
+ * screen did not change because **the app never launched**, which the run knew
+ * and did not say. Two more checks failed downstream of the same cause.
+ *
+ * A skip does not fail the build, and that is deliberate. A red build caused by
+ * somebody else's build farm is the cry-wolf failure this project keeps writing
+ * down: it trains everyone to re-run rather than to read. But it is counted and
+ * printed, because a run that tested less than it claims must say so.
+ */
+function skip(label, why) {
+  skipped += 1;
+  console.log(`skip ${label} — NOT TESTED: ${why}`);
+  return false;
+}
+
+/** Did a setup flow actually do what it was there for? */
+function ran(res) {
+  if (!res || res.ok === false) return false;
+  return !(res.steps ?? []).some((st) => st.ok === false);
+}
+
 /**
  * `expectFail` asserts a non-zero exit; `allowFail` tolerates one.
  *
@@ -96,7 +126,21 @@ async function json(args, opts) {
  * rather than serving a stale frame, which is the right behaviour and a
  * transient condition. Retry those, and only those.
  */
+// Capture dropping out, and — since 2026-09-11 — simctl timing out.
+//
+// The second one is this repo's oldest CI complaint and it was never in this
+// pattern, so `jsonRetry` sailed past it: `simctl launch` takes 47-55s per
+// attempt on a loaded hosted runner and `simctl openurl` times out internally,
+// which means simframe is handed a failure it did not cause and cannot fix.
+// Three checks in one run failed downstream of exactly that.
+//
+// Retried HERE and deliberately not inside simframe, which is the rule DEFERRED
+// already wrote down for the bench script: a retried launch is an action that
+// fires twice, and the verify barrier exists to stop simframe doing that on its
+// own initiative. A test harness re-running its own setup is a different thing
+// from a driver silently repeating a user's action.
 const TRANSIENT = /did not produce a frame|display surface could not be read|no frames buffered/i;
+const SIMCTL_FLAKE = /simctl|Command failed: xcrun|timed out/i;
 
 async function jsonRetry(args, opts, attempts = 3) {
   let last;
@@ -105,9 +149,13 @@ async function jsonRetry(args, opts, attempts = 3) {
       return await json(args, opts);
     } catch (err) {
       last = err;
-      if (!TRANSIENT.test(err.message)) throw err;
-      console.log(`     (capture dropped out; retrying \`${args.join(' ')}\`)`);
-      await new Promise((r) => setTimeout(r, 1500));
+      const capture = TRANSIENT.test(err.message);
+      const simctl = SIMCTL_FLAKE.test(err.message);
+      if (!capture && !simctl) throw err;
+      console.log(`     (${capture ? 'capture dropped out' : 'simctl did not answer'}; retrying \`${args.join(' ')}\`)`);
+      // simctl's own timeouts are tens of seconds, so a 1.5s pause is not a
+      // wait, it is a formality. Give the runner room when that is the cause.
+      await new Promise((r) => setTimeout(r, simctl ? 5000 : 1500));
     }
   }
   // Out of attempts on a capture error: the device is not blinking, it is gone.
@@ -242,13 +290,15 @@ if (first) {
   // Now leave that screen WITHOUT re-reading it: `--json` skips the end-state
   // map, so the ref table still describes the screen we have left.
   const before = await markHash();
-  await jsonRetry(['do', AT_OTHER_SCREEN], { allowFail: true });
+  const left = await jsonRetry(['do', AT_OTHER_SCREEN], { allowFail: true });
   const after = await markHash();
   // Two different apps are two different screens by construction. The pixel
   // hashes only have to agree with that, and they only get a say when they are
   // informative enough to have one.
   const moved = !informativeHash(before) || !informativeHash(after) || before !== after;
-  check(moved, 'the screen actually changed before testing the stale ref',
+  if (!ran(left)) skip('the screen actually changed before testing the stale ref',
+    'the second app never launched, so there was no screen change to test against');
+  else check(moved, 'the screen actually changed before testing the stale ref',
     `${before.slice(0, 10)} -> ${after.slice(0, 10)}`
     + (informativeHash(before) && informativeHash(after) ? '' : ' (degenerate hash: not evidence either way)'));
   // Only assert the guard if the precondition actually held. Running it anyway
@@ -256,17 +306,28 @@ if (first) {
   // screen, which is a false accusation against the one layer this file exists
   // to defend — and it is how this check has failed twice.
   if (moved) {
-    const stale = await cli(['find', `#${first.ref}`], { expectFail: true });
-    // Matched on prose, which is this check's weakness: simframe refused
-    // correctly with "#1 cannot be trusted here — simframe does not recognise
-    // this screen. Read it again", and the check failed because that wording was
-    // not one of the two it knew. The refusal is what matters, so the
-    // alternation covers how a refusal is actually phrased; the durable fix is a
-    // machine-readable reason on the failure, which `find --json` does not yet
-    // carry.
-    check(/different screen|read the screen|read it again|does not recognise this screen|cannot be trusted/i.test(stale),
+    // This matched on prose twice and went red twice, both times for a refusal
+    // that was correct and better worded than the alternation knew — most
+    // recently `"Welcome to Reminders" is not on this screen`, which refuses
+    // *and* names what the number stood for. `find --json` now carries the
+    // reason as a field, so the check reads the contract instead of the
+    // sentence. What is under test is unchanged: the ref must not resolve to
+    // the coordinates it was numbered at on the screen we have left.
+    // A refusal that cannot be parsed is a failed check, not a dead script:
+    // `json` throws on anything non-JSON reaching the stream, and this is the
+    // one call site that expects a failure, so it is the one that would take
+    // the whole file down with it.
+    let stale;
+    try {
+      stale = await json(['find', `#${first.ref}`], { expectFail: true });
+    } catch (err) {
+      stale = { ok: null, error: err.message };
+    }
+    const refused = stale.ok === false
+      && (stale.staleRef === true || stale.reason === 'unknown_screen' || stale.reason === 'ambiguous_intent');
+    check(refused,
       'a ref numbered on another screen refuses instead of tapping those coordinates',
-      stale.trim().split('\n')[0]?.slice(0, 90));
+      `${stale.reason ?? 'no reason'}${stale.staleRef ? ' staleRef' : ''} — ${String(stale.error ?? '').split('\n')[0].slice(0, 70)}`);
   }
 } else {
   check(false, 'element refs', 'no elements to number');
@@ -343,7 +404,15 @@ const novelVerdicts = novelSteps.length
 // accusing the layer underneath it. A device that crashed SpringBoard mid-run
 // has not told us anything about the graph.
 const novelRan = novelSteps.length > 0 && novelSteps.every((r) => r.ok !== false);
-check(novelRan, 'the novel action ran at all', `[${novelVerdicts.join(', ')}]`);
+// The comment above states the principle and this line used to contradict it:
+// it called `check`, so a `simctl openurl` that timed out on the runner failed
+// the build and said "the novel action ran at all" as though the graph were at
+// fault. It is a precondition. Untested is not broken.
+if (!novelRan) {
+  skip('the novel action ran at all', `the action could not be dispatched — [${novelVerdicts.join(', ')}]`);
+} else {
+  check(true, 'the novel action ran at all', `[${novelVerdicts.join(', ')}]`);
+}
 // The other half of the precondition, which was written above as a comment and
 // then trusted. It is not trustworthy: the positioning run sends the device
 // home, and a simulator that has been driven hard stops delivering `home` while
@@ -361,9 +430,20 @@ if (novelRan && novelMoved) {
     'an action never taken here before is reported as unverified, not as verified',
     `[${novelVerdicts.join(', ')}]`);
 }
-check(passes.some((p) => p.verdicts.includes('ok')),
-  'and once the graph has seen it, the outcome is predicted',
-  `pass ${passes.findIndex((p) => p.verdicts.includes('ok')) + 1}`);
+// The same precondition rule as the two above. The graph can only predict an
+// outcome it has seen, and it can only have seen one if a pass actually ran —
+// so a run in which every pass failed to dispatch says nothing about
+// prediction. It failed the build as `pass 0` while the real cause was a
+// simctl launch timing out, three checks upstream.
+const anyPassRan = passes.some((p) => Array.isArray(p.run?.results) && p.run.results.some((r) => r.ok !== false));
+if (!anyPassRan) {
+  skip('and once the graph has seen it, the outcome is predicted',
+    'no pass dispatched a step, so the graph was never given anything to learn');
+} else {
+  check(passes.some((p) => p.verdicts.includes('ok')),
+    'and once the graph has seen it, the outcome is predicted',
+    `pass ${passes.findIndex((p) => p.verdicts.includes('ok')) + 1}`);
+}
 
 // One direction only: a wrong turn must fail the run. The converse does not
 // hold — a run can fail for reasons that are not wrong turns, such as a step
@@ -472,5 +552,9 @@ try {
   }
 } catch { /* nothing to clean up */ }
 
-console.log(`\n${failures ? `${failures} check(s) failed` : 'every check passed'}`);
+const summary = [
+  failures ? `${failures} check(s) failed` : 'every check passed',
+  skipped ? `${skipped} check(s) NOT TESTED — the runner could not set them up` : null,
+].filter(Boolean).join('; ');
+console.log(`\n${summary}`);
 process.exit(failures ? 1 : 0);

package/scripts/collect-rulings.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+// Generate a population of supervisor rulings, and score them.
+//
+// Items 101, 96, 106 and 109a all need rulings to replay, and the log held one,
+// because a ruling requires a step that genuinely fails and Apple's own apps do
+// not fail on command. The React Native testbed does, from a seeded stream, so
+// this turns "we need dozens of rulings" into a script.
+//
+// Every fixture here has a **known correct outcome**, which is what makes the
+// population scoreable rather than merely large:
+//
+//   arriving  a list still loading. Re-running the step works, so the right
+//             answer is wait/retry and the right outcome is `recovered`.
+//   blocked   a required field is empty, so the thing waited for can never
+//             appear. Waiting and retrying are both wrong; `stopped` is right.
+//   refused   a submit that failed. Re-running the *wait* cannot help — only
+//             re-submitting could, and that is the planner's call, not the
+//             supervisor's — so `stopped` is right here too.
+//
+// Note `refused` and `blocked` want the same answer for different reasons. That
+// is deliberate: a judge that says stop for the wrong reason is still right, and
+// a population that only contains obvious cases measures nothing.
+//
+//   SIMFRAME_SUPERVISOR=apple node scripts/collect-rulings.mjs --device=<udid> --seeds=8
+import { execFile } from 'node:child_process';
+import * as actions from '../src/actions.js';
+import * as api from '../src/index.js';
+import * as metrics from '../src/metrics.js';
+import * as store from '../src/store.js';
+import * as supervisor from '../src/supervisor.js';
+
+const arg = (name, fallback) => {
+  const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
+  return hit ? hit.slice(name.length + 3) : fallback;
+};
+const device = arg('device');
+const seeds = Number(arg('seeds', 6));
+const BUNDLE = 'com.example.simframetestbed';
+
+if (!supervisor.requested({})) {
+  console.error('SIMFRAME_SUPERVISOR is not set, so nothing would be judged and no ruling would be recorded.');
+  process.exit(2);
+}
+
+// Before anything else, because the device may already be wedged from the last
+// run — `ensureDaemon` throws on a display that has stopped rendering, and it
+// threw here on the third attempt of the afternoon, before the loop's own check
+// could ever run. Driving one simulator hard for a few minutes is what does it.
+{
+  const { execFileSync } = await import('node:child_process');
+  try {
+    await api.ensureDaemon(device);
+  } catch {
+    console.log('the device is not producing frames; reviving before starting');
+    try {
+      execFileSync(process.execPath, ['src/cli.js', 'revive', `--device=${device}`],
+        { cwd: new URL('..', import.meta.url).pathname, timeout: 300_000, stdio: 'inherit' });
+    } catch { /* reported below by the throw from ensureDaemon */ }
+  }
+}
+
+const { device: dev } = await api.ensureDaemon(device);
+console.log(`device: ${dev.name} (${dev.runtime})`);
+
+/**
+ * Cold-launch the app with a seed.
+ *
+ * `openUrl` on a terminated app launches it with that URL as its initial URL,
+ * which is the only way to set the seed *before* the first screen mounts and
+ * starts its own timers. Relaunching and then opening the URL would be too
+ * late: the list's delay has already been drawn from the default stream.
+ */
+/**
+ * Scaffolding runs with the supervisor OFF, and that is not a detail.
+ *
+ * The first collection run produced 18 rulings of which **14 came from the
+ * harness's own plumbing** — seven from tapping an "Open in …?" dialog that was
+ * not always there, two from terminating an app that was not running, three
+ * from typing into a form we had failed to reach. Every one was a real
+ * consultation and every one would have landed in the population that 101 and
+ * 96 are going to measure.
+ *
+ * A fixture is a claim about what the supervisor should say. Plumbing is not,
+ * and a harness that cannot tell them apart is measuring itself.
+ */
+const SCAFFOLD = { supervisor: 'none' };
+
+const launchSeeded = async (seed) => {
+  // Terminating an app that is not running fails, and a failed step aborts the
+  // rest of the batch — so it gets its own call and its own shrug.
+  await actions.runScript(device, { steps: [{ terminate: BUNDLE }], verify: false, options: SCAFFOLD }).catch(() => null);
+  await actions.runScript(device, {
+    steps: [{ openUrl: `simframetestbed://seed/${seed}` }, { pause: 1200 }],
+    verify: false,
+    options: SCAFFOLD,
+  });
+  // iOS asks "Open in ...?" whenever a custom scheme is opened by another
+  // process, springboard included, and it asks on every launch. Answered here
+  // rather than designed around: the alternative is launch arguments, which RN
+  // does not expose to JavaScript without a native module.
+  await actions.runScript(device, {
+    steps: [{ tap: 'Open' }, { pause: 2200 }],
+    verify: false,
+    options: SCAFFOLD,
+  }).catch(async () => {
+    // No dialog this time. Give the app the same settling time anyway, so the
+    // fixture's timing does not depend on whether iOS felt like asking.
+    await actions.runScript(device, { steps: [{ pause: 2200 }], verify: false, options: SCAFFOLD }).catch(() => null);
+  });
+};
+
+/**
+ * Walk to where a fixture starts, unjudged — and *prove* you arrived.
+ *
+ * Navigation is scaffolding too. Three of the first run's stray rulings were a
+ * `type` that failed because the form had never been reached.
+ *
+ * The `arrive` half is the harder lesson, and it cost a wrong number. A walk
+ * that does not throw is not a walk that arrived: two `Next` taps landed on a
+ * live button, threw nothing, and advanced nothing, so **three of four rulings
+ * in the first clean run were taken on step 1 of a three-step form** while the
+ * fixture claimed they were about the review step. The scoreboard read 25% and
+ * was measuring the harness.
+ *
+ * `eval-fingerprint.mjs` already learned exactly this — it checks that each
+ * reading was taken on the screen the tour named, having once measured a
+ * distribution against readings taken somewhere else. The check simply had not
+ * been carried over.
+ */
+const walk = async (steps, arrive) => {
+  try {
+    if (steps.length) await actions.runScript(device, { steps, verify: false, options: SCAFFOLD });
+    if (!arrive) return true;
+    // Asserted, not assumed. An assert that throws means we are not there.
+    await actions.runScript(device, {
+      steps: [{ assert: { value: arrive, is: 'visible' } }],
+      verify: false,
+      options: SCAFFOLD,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Revive the device if capture has given up, and keep going.
+ *
+ * Collecting a population means driving one simulator hard for several minutes,
+ * and the display stops rendering when you do — twice in one afternoon here. The
+ * daemon detects it, tries both its recoveries, reports `stalled` and stops,
+ * because a capture loop that rebooted the device it was watching would be a
+ * tool reaching for the mains. This is a harness, not the product, and the
+ * operator's answer is exactly what it is here to automate — otherwise a run of
+ * twenty fixtures ends at the third and the population is however many rulings
+ * the device survived.
+ */
+const reviveIfWedged = async () => {
+  const health = store.captureHealth(dev.udid);
+  if (!health?.stalled) return false;
+  process.stdout.write('  (capture stalled — reviving the device before continuing)\n');
+  await new Promise((resolve) => {
+    execFile(process.execPath, ['src/cli.js', 'revive', `--device=${dev.udid}`],
+      { timeout: 300_000, cwd: new URL('..', import.meta.url).pathname }, () => resolve());
+  });
+  return true;
+};
+
+const FIXTURES = [
+  {
+    name: 'arriving',
+    want: 'recovered',
+    // Pull to refresh rather than relying on the launch, because reaching the
+    // fixture now takes three seconds of its own — answering iOS's "Open in …?"
+    // — and by then the list has always arrived. The first clean run produced
+    // *no rulings at all* from this fixture for that reason. A refresh empties
+    // the list and reloads it on a fresh seeded delay, right where we want it.
+    walk: [{ swipe: { from: [201, 300], to: [201, 620] } }],
+    arrive: null,
+    judge: { waitFor: { value: 'Monstera #1', timeoutMs: 700 } },
+    expect: 'the list is still loading; its rows arrive shortly after launch',
+  },
+  {
+    name: 'detail',
+    want: 'recovered',
+    // A detail screen that is still fetching. Waiting is the right answer and
+    // re-running the step proves it, which is what makes this scoreable.
+    walk: [{ tap: 'Monstera #1' }],
+    arrive: null,
+    judge: { waitFor: { value: 'Prefers bright indirect light', timeoutMs: 700 } },
+    expect: 'the detail screen is still fetching; its text arrives shortly',
+  },
+  {
+    name: 'secondwave',
+    want: 'recovered',
+    // The list renders its count header, then a third of its rows, then the
+    // rest. `Jade #24` is in the last wave, so a tight wait for it fails while
+    // the screen is *stable and incomplete at the same moment* — the state that
+    // has fooled settle detection and the supervisor alike.
+    walk: [{ swipe: { from: [201, 300], to: [201, 620] } }],
+    arrive: null,
+    judge: { waitFor: { value: 'Jade #24', timeoutMs: 700 } },
+    expect: 'the list arrives in waves and this row is in the last one',
+  },
+  {
+    name: 'blocked',
+    want: 'stopped',
+    walk: [
+      { tap: 'Forms, tab, 2 of 3' }, { pause: 900 }, { tap: 'Stepped form' }, { pause: 900 },
+      { tap: 'Next' }, { pause: 1200 }, { tap: 'Next' }, { pause: 1200 },
+    ],
+    // The review step, proved rather than hoped for.
+    arrive: 'Step 3 of 3',
+    judge: { waitFor: { value: 'Submitted', timeoutMs: 2500 } },
+    expect: 'Review is blocked until Species is filled in, and it is empty',
+  },
+  {
+    name: 'refused',
+    want: 'stopped',
+    walk: [
+      { tap: 'Forms, tab, 2 of 3' }, { pause: 900 }, { tap: 'One-step form' },
+      { pause: 6500 },
+      { type: { into: 'Your Name', text: 'Ada' } },
+      { tap: 'Submit' }, { pause: 1200 },
+    ],
+    // The rejection is on screen, so the submit demonstrably happened and
+    // failed — otherwise this fixture can pass by never having submitted.
+    arrive: 'The order was rejected',
+    // "Saved" was the string here and it fuzzy-matched "Could not save: …", so
+    // the judge step *succeeded* on the failure it was meant to catch and the
+    // fixture produced no rulings at all. Success and failure now share no words.
+    judge: { waitFor: { value: 'Order placed', timeoutMs: 2500 } },
+    expect: 'the first submit always fails and the second works, so waiting cannot help',
+  },
+];
+
+const before = metrics.readSupervisions(dev.udid).length;
+let runs = 0;
+let skipped = 0;
+
+for (let i = 0; i < seeds; i += 1) {
+  const seed = 1000 + i * 7;
+  for (const fx of FIXTURES) {
+    await reviveIfWedged();
+    await launchSeeded(seed);
+    const reached = await walk(fx.walk, fx.arrive);
+    if (!reached) {
+      process.stdout.write(`  seed ${seed}  ${fx.name.padEnd(9)} SKIPPED — could not reach the fixture\n`);
+      skipped += 1;
+      continue;
+    }
+    try {
+      await actions.runScript(device, {
+        steps: [{ ...fx.judge, expect: fx.expect }],
+        supervise: fx.name,
+        verify: true,
+      });
+    } catch { /* a failing step is the point */ }
+    runs += 1;
+    process.stdout.write(`  seed ${seed}  ${fx.name.padEnd(9)} judged\n`);
+  }
+}
+
+const all = metrics.readSupervisions(dev.udid);
+const fresh = all.slice(before);
+console.log(`\n${runs} judged step(s), ${skipped} skipped, ${fresh.length} ruling(s)\n`);
+
+const byFixture = new Map(FIXTURES.map((f) => [f.expect, f]));
+const score = new Map(FIXTURES.map((f) => [f.name, { n: 0, right: 0, decisions: {}, outcomes: {} }]));
+let unattributed = 0;
+for (const r of fresh) {
+  const fx = byFixture.get(r.expect);
+  if (!fx) { unattributed += 1; continue; }
+  const s = score.get(fx.name);
+  s.n += 1;
+  s.decisions[r.decision] = (s.decisions[r.decision] ?? 0) + 1;
+  s.outcomes[r.outcome] = (s.outcomes[r.outcome] ?? 0) + 1;
+  if (r.outcome === fx.want) s.right += 1;
+}
+
+console.log(`${'fixture'.padEnd(10)} ${'n'.padStart(3)} ${'right'.padStart(6)}  wanted      decisions / outcomes`);
+for (const fx of FIXTURES) {
+  const s = score.get(fx.name);
+  const pct = s.n ? `${Math.round((100 * s.right) / s.n)}%` : '—';
+  console.log(
+    `${fx.name.padEnd(10)} ${String(s.n).padStart(3)} ${pct.padStart(6)}  ${fx.want.padEnd(10)}  `
+    + `${JSON.stringify(s.decisions)} / ${JSON.stringify(s.outcomes)}`,
+  );
+}
+if (unattributed) console.log(`\n${unattributed} ruling(s) came from a step this script did not label.`);
+
+// Said before the accuracy is read, not after. The first population was 12
+// `stop` to 2 `wait`, so a majority-class guess scored 86% against the model's
+// 64% — and every number computed from it was an artifact of that skew. A
+// scoreboard that prints accuracy without printing its own balance invites
+// exactly that mistake a second time.
+{
+  const want = {};
+  for (const fx of FIXTURES) {
+    const s = score.get(fx.name);
+    want[fx.want] = (want[fx.want] ?? 0) + s.n;
+  }
+  const total = Object.values(want).reduce((a, b) => a + b, 0);
+  const biggest = Math.max(0, ...Object.values(want));
+  const baseline = total ? Math.round((100 * biggest) / total) : 0;
+  console.log(`\nbalance: ${JSON.stringify(want)} — guessing the commonest answer scores ${baseline}%.`);
+  if (baseline > 65) {
+    console.log('  SKEWED. Any accuracy above is mostly a fact about the fixture set, not the judge.');
+    console.log('  Add fixtures for the under-represented answer before comparing anything against anything.');
+  }
+}
+console.log(`\nthe log now holds ${all.length} ruling(s) — simframe supervisions --device=${dev.udid}`);

package/scripts/eval-fingerprint.mjs

@@ -87,6 +87,43 @@ const readings = [];
 /** Navigations that did not land before the reading was taken. */
 const arrivalFailures = [];
 
+/**
+ * The tokens that carry a name, as opposed to a shape.
+ *
+ * A fingerprint is deliberately geometry — role, region, size, position — and
+ * chrome labels are the only text that survives into it (`fingerprint.js`).
+ * That module's own comment states the consequence: "two list screens with
+ * identical structure differ by their title, and nothing else says so". So a
+ * reading with none of these has no identity to speak of, and two such
+ * readings of *different* screens can hash identically. Counted here because
+ * that is diagnosable and "the tour went somewhere unintended" is not.
+ */
+const namedTokens = (tokens) => tokens.filter((t) => t.includes('"'));
+
+/**
+ * Write the readings out now, rather than after the checks.
+ *
+ * The write used to sit past every `process.exit(1)`, so the only run that
+ * kept its evidence was the run with nothing to explain. A failing run exited
+ * before the file existed and `if: always()` on the upload step faithfully
+ * uploaded nothing — which is how one red integration job cost an evening of
+ * inferring from a summary line while `analyse-fingerprint.mjs`, which exists
+ * to classify exactly these divergences, had no file to read. Called as soon
+ * as the tour is done and again with the analysis, so every exit below this
+ * point still leaves the readings behind.
+ */
+const save = (extra = {}) => {
+  if (!outFile) return;
+  fs.writeFileSync(outFile, JSON.stringify({
+    label, device: dev.name, runtime: dev.runtime, rounds, at: Date.now(),
+    threshold: graph.SIMILARITY_THRESHOLD,
+    // Tokens are kept. They were stripped here once, and the first time the
+    // margin narrowed the run could not be diagnosed from its own output.
+    readings,
+    ...extra,
+  }, null, 2));
+};
+
 for (let round = 1; round <= rounds; round += 1) {
   for (const screen of tour) {
     if (screen.steps?.length) {
@@ -136,12 +173,25 @@ for (let round = 1; round <= rounds; round += 1) {
       // like fingerprint drift.
       sources: id.entry?.sources ?? [],
     });
+    // Sensors and named tokens are on every line, not only inside a failure.
+    // Both were invisible until a run failed, and both are what the failure
+    // turns out to be about: two readings of one screen taken by different
+    // sensors do not share a hash by design, and a reading carrying no chrome
+    // label cannot be told from any other screen of the same shape. A summary
+    // line that hid those sent an evening after hosted-runner speed.
     process.stdout.write(
-      `  round ${round}  ${screen.name.padEnd(14)} ${String(id.hash).slice(0, 10)}  ${String((id.tokens ?? []).length).padStart(3)} tokens${id.settled ? '' : '  (never settled)'}\n`,
+      `  round ${round}  ${screen.name.padEnd(22)} ${String(id.hash).slice(0, 10)}  `
+      + `${String((id.tokens ?? []).length).padStart(3)} tokens  `
+      + `${String(namedTokens(id.tokens ?? []).length).padStart(2)} named  `
+      + `${((id.entry?.sources ?? []).join('+') || 'none').padEnd(9)}`
+      + `${id.settled ? '' : '  (never settled)'}\n`,
     );
   }
 }
 
+save();
+if (outFile) console.log(`\nwrote ${readings.length} readings to ${outFile}`);
+
 if (arrivalFailures.length) {
   console.error(`\nFAIL ${arrivalFailures.length} reading(s) were taken on the previous screen:`);
   for (const f of arrivalFailures) console.error(`       ${f}`);
@@ -178,11 +228,17 @@ function findStrays(all) {
     if (siblings.length < 2) continue;
     const bestSelf = Math.max(...siblings.map((o) => fingerprint.similarity(r.tokens, o.tokens)));
     const others = all.filter((o) => o.name !== r.name);
-    const bestOther = others.length
-      ? Math.max(...others.map((o) => fingerprint.similarity(r.tokens, o.tokens)))
-      : 0;
+    // Which screen it resembles, not merely how much. A stray that resembles
+    // one particular other screen at 1.00 is a different animal from one that
+    // resembles everything weakly, and the report could not tell them apart.
+    let match = null;
+    let bestOther = 0;
+    for (const o of others) {
+      const s = fingerprint.similarity(r.tokens, o.tokens);
+      if (s > bestOther) { bestOther = s; match = o; }
+    }
     if (bestSelf < graph.SIMILARITY_THRESHOLD && bestOther >= bestSelf) {
-      strays.push({ reading: r, bestSelf, bestOther });
+      strays.push({ reading: r, bestSelf, bestOther, match });
     }
   }
   return strays;
@@ -190,14 +246,41 @@ function findStrays(all) {
 
 const strays = findStrays(readings);
 if (strays.length) {
-  console.error(`\nFAIL ${strays.length} reading(s) were taken on a screen other than the one named:`);
-  for (const { reading, bestSelf, bestOther } of strays) {
-    console.error(`       ${reading.name} r${reading.round}: resembles its own screen ${bestSelf.toFixed(2)}, `
-      + `another screen ${bestOther.toFixed(2)} (${reading.count} tokens, sources ${reading.sources.join('+') || 'none'})`);
+  console.error(`\nFAIL ${strays.length} reading(s) do not resemble their own screen:`);
+  // Two causes wear the same symptom, and until now the report asserted the
+  // second one. A reading can be unlike its siblings because the tour went
+  // somewhere unintended — or because the fingerprint could not tell two
+  // screens apart, which is the harness's actual subject. They are separable
+  // from the data in hand: a collision is a reading that carries no chrome
+  // label while matching one particular other screen almost exactly, and a
+  // wrong turn is one whose tokens name a screen the tour did not ask for.
+  let collisions = 0;
+  for (const { reading, bestSelf, bestOther, match } of strays) {
+    const named = namedTokens(reading.tokens);
+    const matchNamed = match ? namedTokens(match.tokens) : [];
+    const collided = bestOther >= 0.99 && named.length === 0 && matchNamed.length === 0;
+    if (collided) collisions += 1;
+    console.error(`       ${reading.name} r${reading.round}: own screen ${bestSelf.toFixed(2)}, `
+      + `${match ? `${match.name} r${match.round}` : 'another screen'} ${bestOther.toFixed(2)} `
+      + `(${reading.count} tokens, ${named.length} named, sources ${reading.sources.join('+') || 'none'})`);
+    if (collided) {
+      console.error('              ^ a COLLISION, not a wrong turn: neither reading carries a chrome');
+      console.error('                label, so both are structure with no name and the fingerprint has');
+      console.error('                nothing left to tell two list screens apart.');
+    }
+    if (named.length) console.error(`              names: ${named.map((t) => t.slice(t.indexOf('"'), t.lastIndexOf('"') + 1)).join(' ')}`);
+  }
+  if (collisions) {
+    console.error(`\n${collisions} of ${strays.length} are fingerprint collisions. That is this harness's own subject,`);
+    console.error('not a tour fault: a reading whose chrome label went missing cannot establish');
+    console.error('identity, and comparing it as though it could is what produced the verdict above.');
+  } else {
+    console.error('\nThat is the tour going somewhere unintended, not the fingerprint drifting, and');
+    console.error('measuring it as either distribution poisons both ends. Fix the tour — a tap that');
+    console.error('missed, or a screen that needs longer than its pause — and re-run.');
   }
-  console.error('\nThat is the tour going somewhere unintended, not the fingerprint drifting, and');
-  console.error('measuring it as either distribution poisons both ends. Fix the tour — a tap that');
-  console.error('missed, or a screen that needs longer than its pause — and re-run.');
+  console.error(`\nEvery reading is in ${outFile ?? 'the --out file'}; `
+    + 'run `node scripts/analyse-fingerprint.mjs <that file>` to classify the divergent tokens.');
   process.exit(1);
 }
 
@@ -317,17 +400,11 @@ for (const r of readings) {
 }
 console.log(`\n${labels.size} distinct chrome label(s) entered identity: ${[...labels].sort().join(' · ') || '(none)'}`);
 
-if (outFile) {
-  fs.writeFileSync(outFile, JSON.stringify({
-    label, device: dev.name, runtime: dev.runtime, rounds, at: Date.now(),
-    threshold, same: s, mixed: m, different: d, gap, separated, thresholdInGap,
-    labels: [...labels].sort(),
-    // Tokens are kept. They were stripped here, and the first time the margin
-    // narrowed the run could not be diagnosed from its own output.
-    readings,
-  }, null, 2));
-  console.log(`\nwrote ${outFile}`);
-}
+save({
+  same: s, mixed: m, different: d, gap, separated, thresholdInGap,
+  labels: [...labels].sort(),
+});
+if (outFile) console.log(`\nwrote ${outFile}`);
 
 // The stated margin, checked rather than eyeballed. A person noticing that a
 // number moved is not a test; this is the machine that re-measures it.