simframe 0.13.0 → 0.14.1

package/README.md

@@ -406,6 +406,7 @@ steer the model is a tool surface the model uses wrong.
 | `sim_wait` | Waits for the screen to change *and then* settle. |
 | `sim_look` | **The only tool that returns an image**, capped at 1024 px. For layout, colour, spacing — questions text cannot answer. |
 | `sim_recall` · `sim_strip` | Look backwards: a text timeline of what happened, or recent frames tiled into one image. |
+| `sim_storage` | **What the app believes**, as opposed to what it drew: its `UserDefaults` and, for React Native, its `AsyncStorage`. Reads the data container off disk, so it answers on a device that is **not running**. |
 | `sim_capture` · `sim_devices` | Manage capture loops; list simulators. |
 
 ### What the screen looks like as text
@@ -585,6 +586,20 @@ simframe screens              # what this device has learned
 simframe goto invoices        # walk there, verifying every step
 ```
 
+And when the screen and the behaviour disagree, the question is usually not
+about the screen at all:
+
+```bash
+simframe storage                          # apps with a data container
+simframe storage com.example.myapp        # what that app saved
+```
+
+`sim_ui` says what is drawn; `sim_storage` says what the app believes. It reads
+the data container straight off the host filesystem, which means it works on a
+device that is **shut down** — `simctl` cannot do this at all, on any of its own
+paths, once a device stops running.
+
+
 Measured on a four-tab tour, `goto` plans and walks three-step routes with every
 step verified and no model call. It fails rather than guesses: an unknown
 destination, a query matching two screens equally, or no path of known edges all

package/native/simframed/Sources/SimframeCore/Motion.swift

@@ -13,6 +13,10 @@ public enum Motion {
 
     /// Below this mean absolute difference, two frames are the same picture.
     public static let stillThreshold = 0.004
+
+    /// How many moving cells make an animation rather than sensor noise.
+    /// Set from the measurements in `state(history:now:)` below.
+    public static let minAnimatingCells = 12
     /// Frames that must agree before the screen counts as settled.
     ///
     /// Paired with a duration, because frame count alone is not a measure of
@@ -170,8 +174,35 @@ public enum Motion {
             let cellThreshold = 0.06
             let moving = union.filter { $0 > cellThreshold }.count
             let fraction = Double(moving) / Double(union.count)
-            // Small and persistent, rather than a screen changing.
-            if fraction > 0 && fraction < 0.06 {
+            // Small and persistent, rather than a screen changing — and big
+            // enough to be something.
+            //
+            // `fraction > 0` meant one cell of 4,608 counted as an animation,
+            // and measured on a device that fires constantly on screens where
+            // nothing is happening. A field report put it exactly right: a
+            // warning that is usually wrong trains the reader to ignore the one
+            // that matters.
+            //
+            // Measured on this device, 2026-09-14, which is what
+            // `minAnimatingCells` is set from:
+            //
+            //   static home screen, nothing moving   1-4 cells, on 54% of frames
+            //   a blinking text caret                **2 cells** (1x2), on 100%
+            //   the testbed's spinner                169 cells (13x13)
+            //   Maps launching, median               656 cells (41x16)
+            //   a real spinner, from the field       1,364 cells (44x31)
+            //
+            // Caret and noise sit at 1-4; the smallest real animation seen is
+            // 169. A 42x gap with nothing in it, so the threshold is not
+            // delicate — 12 is three times the worst noise and an order of
+            // magnitude below the weakest signal.
+            //
+            // The caret is the case this is really for, and it is why the
+            // question could not be settled by reasoning: a caret must never
+            // stop a screen from settling, and before this it did — 72 frames
+            // out of 72 with `settled: false` on a screen holding nothing but a
+            // text cursor.
+            if moving >= Self.minAnimatingCells && fraction < 0.06 {
                 animating = boundingBox(of: union, threshold: cellThreshold)
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [

package/scripts/ci-device-guard.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Run a CI step, and tell a sick simulator apart from a failing check.
+//
+//   node scripts/ci-device-guard.mjs <udid> -- <command> [args...]
+//
+// **Why this exists, with the number that justifies it.** Over the last 25 CI
+// runs the `integration` job failed 17 times and passed 5. Eight of the nine
+// most recent failures name a device-state condition in their own output —
+// `NSPOSIXErrorDomain code=60`, `the display produced no frame in 60s`, `the
+// second app never launched` — and one of those runs was a **docs-only commit**
+// that changed a single markdown file. Two runs of byte-identical code failed at
+// two different steps.
+//
+// So the job has been answering two questions at once — *does simframe work* and
+// *did this hosted simulator survive twenty minutes* — and the second dominates.
+// A red build that is usually the device is the cry-wolf failure this repo keeps
+// writing items about, and it cost two days of re-reading logs to learn nothing.
+//
+// This does not paper over failures. It distinguishes them: a named device
+// condition gets the cure this project already ships (`simframe revive`) and one
+// retry, exactly as DEFERRED 126 says to; anything else fails on the spot,
+// untouched. The classification is written to the job summary so the *rate*
+// becomes visible instead of arguable.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+/** Conditions that are the simulator, not the code. Each seen in a real run. */
+const DEVICE_STATE = [
+  [/NSPOSIXErrorDomain.*code=?\s*60|Operation timed out/i, 'simctl stopped answering (NSPOSIXErrorDomain 60)'],
+  [/did not produce a frame|produced no frame in \d+s/i, 'the daemon is up and the display renders nothing'],
+  [/Timeout waiting for screen surfaces|display surface is not answering|display surface could not be read/i, 'the display surface is wedged'],
+  [/no frames buffered|capture is wedged/i, 'capture stopped'],
+  [/the second app never launched|could not be dispatched/i, 'an app would not launch'],
+];
+
+const udid = process.argv[2];
+const sep = process.argv.indexOf('--');
+if (!udid || sep < 0) {
+  console.error('usage: ci-device-guard.mjs <udid> -- <command> [args...]');
+  process.exit(2);
+}
+const cmd = process.argv.slice(sep + 1);
+
+function run(argv, { capture = true } = {}) {
+  return new Promise((resolve) => {
+    const p = spawn(argv[0], argv.slice(1), { stdio: capture ? ['inherit', 'pipe', 'pipe'] : 'inherit' });
+    let out = '';
+    p.stdout?.on('data', (d) => { out += d; process.stdout.write(d); });
+    p.stderr?.on('data', (d) => { out += d; process.stderr.write(d); });
+    p.on('close', (code) => resolve({ code, out }));
+  });
+}
+
+const summary = (line) => {
+  const f = process.env.GITHUB_STEP_SUMMARY;
+  if (f) { try { fs.appendFileSync(f, `${line}\n`); } catch { /* summaries are a nicety */ } }
+};
+
+const deviceCause = (text) => DEVICE_STATE.find(([re]) => re.test(text))?.[1] ?? null;
+
+const first = await run(cmd);
+if (first.code === 0) process.exit(0);
+
+const cause = deviceCause(first.out);
+if (!cause) {
+  console.error(`\n     (this step failed on its merits, not on the device — not retrying)`);
+  summary(`- \`${cmd.join(' ')}\` — **check failed** (exit ${first.code})`);
+  process.exit(first.code ?? 1);
+}
+
+console.error(`\n     (${cause} — DEFERRED 126. Reviving once and running again.)`);
+await run(['node', 'src/cli.js', 'revive', `--device=${udid}`], { capture: false });
+const second = await run(cmd);
+if (second.code === 0) {
+  summary(`- \`${cmd.join(' ')}\` — passed after one revive (${cause})`);
+  process.exit(0);
+}
+// Twice in a row, on a condition we know the cure for. Reported as what it is.
+const again = deviceCause(second.out);
+summary(`- \`${cmd.join(' ')}\` — **${again ? 'device unavailable' : 'check failed'}** after a revive${again ? ` (${again})` : ''}`);
+if (again) console.error(`\nFAIL the simulator is still in a bad state after a revive: ${again}`);
+process.exit(second.code ?? 1);

package/scripts/ci-integration-local.sh

@@ -67,14 +67,17 @@ read_state() {
 printf '[{"button":"home"},{"settle":true}]\n' > /tmp/reset-local.json
 node src/cli.js do /tmp/reset-local.json --device="$DEVICE" >/dev/null 2>&1
 BEFORE=$(read_state)
-printf '[{"openUrl":"https://example.com"},{"settle":true}]\n' > /tmp/flow-local.json
-if node src/cli.js do /tmp/flow-local.json --device="$DEVICE" >/dev/null 2>&1; then
-  AFTER=$(read_state)
-  if [ "${BEFORE%% *}" != "${AFTER%% *}" ]; then ok "frame hash changed: ${BEFORE%% *} -> ${AFTER%% *}"
-  else bad "a step ran cleanly but capture saw no change"; fi
-else
-  bad "openUrl flow failed"
-fi
+# From inside an app, pressing home always changes the screen — see the job's
+# comment for the four vehicles that did not hold. Setup gets to a known screen;
+# the asserted action is simframe's own HID path with no simctl in it.
+printf '[{"launch":{"value":"com.apple.Preferences","relaunch":true}},{"settle":true}]\n' > /tmp/setup-local.json
+node src/cli.js do /tmp/setup-local.json --device="$DEVICE" >/tmp/step-local.log 2>&1 || true
+BEFORE=$(read_state)
+printf '[{"button":"home"},{"settle":true}]\n' > /tmp/flow-local.json
+node src/cli.js do /tmp/flow-local.json --device="$DEVICE" >>/tmp/step-local.log 2>&1 || true
+AFTER=$(read_state)
+if [ "${BEFORE%% *}" != "${AFTER%% *}" ]; then ok "frame hash changed: ${BEFORE%% *} -> ${AFTER%% *}"
+else bad "a step ran and capture saw no change"; tail -5 /tmp/step-local.log; fi
 
 step "The memory layer — screen map, refs, graph, verdicts, flows"
 # Mirrors the job: exit 75 means the display wedged and nothing was tested, so

package/scripts/ci-memory.mjs

@@ -111,7 +111,14 @@ async function cli(args, { expectFail = false, allowFail = false } = {}) {
     // detail has been truncated for legibility, and the first version of this
     // guard looked for "did not produce a frame" in a string that had been cut
     // to "simframe daemon di". The full text only exists at this boundary.
-    throw new Error(`simframe ${full.join(' ')} failed: ${why.slice(0, 400)}`);
+    //
+    // And when the payload is a JSON report, say what failed rather than
+    // handing back its first hundred characters. A run of this printed
+    // `simframe doctor --json failed: {\n "ok": false,\n "strict": true,\n
+    // "failu` — the word "failures" cut in half, one character before the only
+    // content that mattered. A harness that truncates away the reason is doing
+    // to its reader exactly what this repo keeps writing items about.
+    throw new Error(`simframe ${full.join(' ')} failed: ${summarise(why)}`);
   }
 }
 
@@ -193,6 +200,23 @@ async function jsonRetry(args, opts, attempts = 3) {
   throw last;
 }
 
+/** A failed JSON report, reduced to the part that says what went wrong. */
+function summarise(why) {
+  try {
+    const parsed = JSON.parse(why);
+    const failures = parsed.failures ?? parsed.failing ?? null;
+    if (Array.isArray(failures) && failures.length) {
+      return failures
+        .map((f) => (typeof f === 'string' ? f : `${f.name ?? f.check ?? '?'}: ${f.detail ?? f.note ?? f.message ?? ''}`.trim()))
+        .join('; ')
+        .slice(0, 400);
+    }
+    const bad = (parsed.checks ?? []).filter((c) => c.ok === false);
+    if (bad.length) return bad.map((c) => `${c.name}: ${c.detail ?? ''}`.trim()).join('; ').slice(0, 400);
+  } catch { /* not JSON, or not a shape we know — fall through to the raw text */ }
+  return why.slice(0, 400);
+}
+
 const markHash = async () => (await jsonRetry(['mark'])).hash;
 
 function writeFlow(name, steps) {
@@ -201,10 +225,28 @@ function writeFlow(name, steps) {
   return file;
 }
 
-// A closed loop: openUrl puts Safari in front, home leaves it. Both ends are
-// screens the graph can learn, and every pass starts where the last one ended.
+// A closed loop: launching an app puts it in front, home leaves it. Both ends
+// are screens the graph can learn, and every pass starts where the last one
+// ended.
+//
+// **It used to be `openUrl https://example.com`, and that was the bug.** Item
+// 142 catalogued `simctl openurl` timing out on a loaded runner as a failure
+// class, marked it "fixed — vehicle changed", and changed the vehicle in the
+// *workflow's* step only. This loop was left on it, and so was the novel action
+// below. That is the same class-versus-symptom error the `waitFor`/`assert`
+// twin recorded: the fix went where the report pointed instead of everywhere
+// the cause reached.
+//
+// It came back on 2026-09-14: passes 2 and 3 halted at step 0, the graph never
+// got the chance to predict, and the failure read as "the outcome is predicted
+// — pass 0", which names the graph for something Safari did.
+//
+// The replacement is the vehicle item 142 measured and proved for exactly this:
+// **from inside an app, pressing home always changes the screen.** Settings is
+// already installed everywhere this runs, the launch needs no network, and
+// neither end depends on a browser cold-starting on a shared machine.
 const LOOP = writeFlow('simframe-ci-loop.json', [
-  { openUrl: 'https://example.com' },
+  { launch: { value: 'com.apple.Preferences', relaunch: true } },
   { button: 'home' },
 ]);
 // Leaving whatever screen the map was read on.
@@ -513,10 +555,23 @@ if (novelRan && novelMoved) {
 // 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) {
+//
+// **The rule was right and the test of it was too coarse.** `anyPassRan` asks
+// whether *any* pass ran, but prediction can only be observed on a pass AFTER
+// the one that taught the edge — so pass 1 running is not enough. On
+// 2026-09-14 pass 1 ran, passes 2 and 3 halted at step 0, and this reported
+// `pass 0` as though the graph had declined to predict. Nothing had asked it
+// to. Same sentence as the novel action three checks above: untested is not
+// broken, and the guard has to test the pass the claim actually depends on.
+const dispatched = (p) => Array.isArray(p.run?.results) && p.run.results.some((r) => r.ok !== false);
+const laterPassRan = passes.slice(1).some(dispatched);
+if (!passes.some(dispatched)) {
   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 if (!laterPassRan) {
+  skip('and once the graph has seen it, the outcome is predicted',
+    `only the first pass dispatched a step (${passes.slice(1).map((p, i) => `pass ${i + 2}: [${p.verdicts.join(', ')}]`).join('; ')})`
+    + ' — prediction is only observable on a pass after the one that taught the edge');
 } else {
   check(passes.some((p) => p.verdicts.includes('ok')),
     'and once the graph has seen it, the outcome is predicted',

package/scripts/eval-fingerprint.mjs

@@ -86,6 +86,19 @@ console.log(`tour: ${tour.length} screens x ${rounds} rounds, every reading cold
 const readings = [];
 /** Navigations that did not land before the reading was taken. */
 const arrivalFailures = [];
+/** Readings too bare to be a screen — see the guard where this is used. */
+const sparseReadings = [];
+/** `name|round` of every reading that stayed too sparse, so the report below can name the cause. */
+const sparseAt = new Set();
+/**
+ * Below this, a reading cannot distinguish its screen from any other bare one.
+ *
+ * Not a failure threshold — see where it is used. The Settings root legitimately
+ * reads 4 tokens on a hosted runner, so treating this as "the screen has not
+ * drawn" rejected a real screen and made CI deterministically red. It marks
+ * readings worth suspecting when a score disagrees with itself, nothing more.
+ */
+const MIN_TOKENS_FOR_A_READING = 5;
 
 /**
  * The tokens that carry a name, as opposed to a shape.
@@ -124,6 +137,76 @@ const save = (extra = {}) => {
   }, null, 2));
 };
 
+/**
+ * How hard to try for a frame newer than the navigation before giving up.
+ *
+ * Three re-reads a second apart is ~3s of slack against capture medians that
+ * were measured above 1s on a bad runner. Generous enough to absorb the spikes
+ * that caused this, small enough that a genuinely stopped capture still fails
+ * rather than hanging the job.
+ */
+const STALE_READ_RETRIES = 3;
+/**
+ * How hard to try for a reading rich enough to tell its screen apart.
+ *
+ * Backed off rather than fixed, because the thing being waited for is a screen
+ * finishing its draw, and the runner that needs this is the slow one.
+ */
+const SPARSE_READ_RETRIES = 3;
+const SPARSE_READ_WAIT_MS = 1500;
+const STALE_READ_WAIT_MS = 1000;
+
+/** When the steps that were supposed to change the screen finished. */
+let navigatedAt = 0;
+/** Readings that never got a frame newer than their own navigation. */
+const staleReadings = [];
+
+/**
+ * Visit every screen once before measuring, taking no readings.
+ *
+ * **The rounds are supposed to be repeat measurements of one thing.** They were
+ * not: round 1 systematically differed from rounds 2 and 3 whenever an app was
+ * cold, because an app that has just launched has not finished publishing its
+ * accessibility tree. Measured on CI — round 1 of `browser` read `e00725fce7`
+ * with **0 named** elements where rounds 2 and 3 read `9589eb2471` with **5**,
+ * while every other screen matched across all three. That is the eval measuring
+ * app cold-start, which it never set out to measure and does not report.
+ *
+ * It was invisible for a long time because something else was paying for it:
+ * the memory-layer step runs first on CI and drives the same apps for 504s,
+ * Safari included, so the eval always met a warm device. Sharding the job
+ * removed that neighbour and the dependency surfaced immediately. The defect
+ * was always here; the neighbour was hiding it.
+ *
+ * This is **not** the same as making the readings warm. Every reading is still
+ * taken with `fresh: true` against cold screen memory, which is what "cold"
+ * means in this harness — the graph must not have seen the screen before. What
+ * the warm-up removes is a variable about the *operating system* that the
+ * fingerprint has nothing to do with.
+ *
+ * Skippable with `--no-warmup`, because the comparison is the evidence: run it
+ * both ways to see whether round 1 still disagrees with its own repeats.
+ */
+async function warmUp() {
+  const started = Date.now();
+  console.log('warming: visiting each screen once, taking no readings');
+  for (const screen of tour) {
+    if (!screen.steps?.length) continue;
+    try {
+      await actions.runScript(device, { steps: screen.steps, verify: false });
+    } catch (err) {
+      // A warm-up failure is not a result. The measured rounds below will meet
+      // the same screen and fail there with the harness's own reporting, which
+      // says which screen and writes the readings out. Failing here would cost
+      // that and report a screen that was never measured.
+      console.log(`         (warm-up could not reach "${screen.name}": ${err.message})`);
+    }
+  }
+  console.log(`warming: done in ${Math.round((Date.now() - started) / 1000)}s\n`);
+}
+
+if (!process.argv.includes('--no-warmup')) await warmUp();
+
 for (let round = 1; round <= rounds; round += 1) {
   for (const screen of tour) {
     if (screen.steps?.length) {
@@ -140,6 +223,7 @@ for (let round = 1; round <= rounds; round += 1) {
       // matters.
       try {
         await actions.runScript(device, { steps: screen.steps, verify: false });
+        navigatedAt = Date.now();
       } catch (err) {
         save({ abandonedAt: { screen: screen.name, round, error: err.message } });
         console.error(`\nFAIL round ${round}, "${screen.name}" never arrived: ${err.message}`);
@@ -148,7 +232,112 @@ for (let round = 1; round <= rounds; round += 1) {
         process.exit(1);
       }
     }
-    const id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+    // A read can throw, and when it does the readings so far are the evidence.
+    //
+    // This file already says so — *"Everything read so far is written out
+    // first, because a failing run is the one whose evidence matters"* — and
+    // then left this call unguarded, so a runner whose OCR overran its budget
+    // produced a raw stack trace, no `--out` file, and nothing for
+    // `analyse-fingerprint.mjs` to read. Exactly the failure the `save()` above
+    // was written to prevent, one line away from it.
+    //
+    // Not retried here. The read budget is already the client's own give-up
+    // point, so a read that overran it is a statement about the machine, and
+    // the honest thing is to say which screen and how far the tour got.
+    let id;
+    try {
+      id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+    } catch (err) {
+      save({ abandonedAt: { screen: screen.name, round, error: err.message, phase: 'reading' } });
+      console.error(`\nFAIL round ${round}, "${screen.name}" could not be read: ${err.message}`);
+      console.error(`${readings.length} reading(s) taken before this were written out.`);
+      console.error('A read that overran its budget is a fact about the host, not about the');
+      console.error('fingerprint — the budget is already the client\'s own give-up point, so');
+      console.error('raising it would only move where the wait ends.');
+      process.exit(1);
+    }
+    // A reading off a frame older than the navigation is not a reading either.
+    //
+    // Same rule as the sparseness guard below, on the other axis, and it took a
+    // third symptom to see they were one cause. Three CI runs failed this step
+    // three different ways — `settings` reading 4 tokens, a reading that "does
+    // not resemble its own screen", and a reading "taken on the previous
+    // screen" at similarity 1.00 off a frame **7168ms old**. All three are the
+    // same sentence: the reading is not of the screen we think it is, because
+    // capture on a hosted runner is slow. The daemon log for that run shows
+    // capture medians of 417ms, 503ms, 996ms, 1106ms and 1132ms against the
+    // 55.4ms p50 measured for a healthy runner — 20x, and with damage-driven
+    // capture a `fresh` read returns the newest frame that EXISTS, which on a
+    // runner that far behind can predate the navigation entirely.
+    //
+    // So the frame must have been captured after the steps that were supposed
+    // to change the screen. Re-read rather than fail, and fail only if it stays
+    // stale — an eval that scores a stale frame is measuring the runner, which
+    // is the one thing this harness says it is not doing.
+    if (navigatedAt) {
+      for (let attempt = 0; attempt < STALE_READ_RETRIES; attempt += 1) {
+        const capturedAt = id.state?.capturedAt ?? 0;
+        if (capturedAt >= navigatedAt) break;
+        const age = Date.now() - capturedAt;
+        console.log(`         ("${screen.name}" read a frame from ${age}ms ago, older than the navigation`
+          + ` — reading again ${attempt + 1}/${STALE_READ_RETRIES})`);
+        await new Promise((r) => setTimeout(r, STALE_READ_WAIT_MS));
+        id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+      }
+      if ((id.state?.capturedAt ?? 0) < navigatedAt) {
+        staleReadings.push(`${screen.name} round ${round}: frame still predates the navigation`
+          + ` by ${navigatedAt - (id.state?.capturedAt ?? 0)}ms after ${STALE_READ_RETRIES} re-reads`);
+      }
+    }
+    // A reading too sparse to be a screen is not a reading.
+    //
+    // On a runner measured at ~2.5x slower than a laptop (EXPERIMENTS §15),
+    // perception can land on a half-rendered screen: two CI runs recorded
+    // `settings` and `settings-general` **both at 4 tokens**, identical hash,
+    // and the eval duly reported that a reading did not resemble its own
+    // screen. It resembled nothing, because almost nothing had been drawn yet.
+    //
+    // This is the hazard `TOKEN_RULES_VERSION` 7 was written for, arriving
+    // through the harness instead of the rules: *"two sparse nameless readings
+    // then matched exactly, one hash standing for two different screens"*. A
+    // guard exists for identity and there was none here.
+    //
+    // Read again rather than fail, and fail only if it stays sparse — the same
+    // "untested is not passed" rule the memory harness learned. A screen that
+    // is genuinely this bare after a second look is a real finding.
+    if ((id.tokens ?? []).length < MIN_TOKENS_FOR_A_READING) {
+      // Read again, and keep the BEST reading rather than the last one.
+      //
+      // One retry was not enough and the failure it produced pointed at the
+      // wrong thing. On CI, `settings-general` read 4 tokens twice and then
+      // scored 1.00 against the *Settings root* — because the General screen's
+      // back button is labelled "Settings", so a General seen only down to its
+      // nav bar is structurally the same screen as the root. The harness
+      // reported it as a fingerprint that does not resemble its own screen. The
+      // fingerprint was fine; the look was too short. `settings-general` reads
+      // 5 tokens when it is read properly.
+      //
+      // Best-of, not last, because these reads are samples of a screen that is
+      // still drawing: a later read is usually richer but not reliably so, and
+      // throwing away a 5-token reading because the retry saw 4 would be the
+      // same bug with more steps.
+      const before = (id.tokens ?? []).length;
+      const seen = [before];
+      for (let attempt = 1; attempt <= SPARSE_READ_RETRIES; attempt += 1) {
+        await new Promise((r) => setTimeout(r, SPARSE_READ_WAIT_MS * attempt));
+        const again = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+        seen.push((again.tokens ?? []).length);
+        if ((again.tokens ?? []).length > (id.tokens ?? []).length) id = again;
+        if ((id.tokens ?? []).length >= MIN_TOKENS_FOR_A_READING) break;
+      }
+      const after = (id.tokens ?? []).length;
+      console.log(`         ("${screen.name}" read ${before} token(s) — too sparse to compare;`
+        + ` read again: ${seen.slice(1).join(', ')} — kept ${after})`);
+      if (after < MIN_TOKENS_FOR_A_READING) {
+        sparseReadings.push(`${screen.name} round ${round}: ${after} token(s) after ${seen.length} reads`);
+        sparseAt.add(`${screen.name}|${round}`);
+      }
+    }
     // Did we actually arrive? Two differently-named screens reading the same
     // fingerprint means the navigation did not land before the reading was
     // taken, and every distribution below it is then measuring the tour rather
@@ -219,9 +408,45 @@ for (let round = 1; round <= rounds; round += 1) {
   }
 }
 
-save();
+save({ staleReadings });
 if (outFile) console.log(`\nwrote ${readings.length} readings to ${outFile}`);
 
+if (sparseReadings.length) {
+  // Reported, NOT failed — and that correction is worth more than the check.
+  //
+  // This exited 1 for four hours on 2026-09-14 and turned an intermittent CI
+  // failure into a deterministic one. The reasoning was that a 4-token reading
+  // is a screen that has not drawn. It is not: the Settings root legitimately
+  // reads 4 tokens on a hosted runner, twice in a row, three times in a row —
+  // which the comment on `MIN_TOKENS_FOR_A_READING` had itself said ("4-8
+  // tokens") one screen above the code that rejected it.
+  //
+  // What remains true is that a reading this bare cannot distinguish its screen
+  // from anything else equally bare, so it is worth saying out loud. What is not
+  // true is that saying so should stop the run. The arrival check below is the
+  // one that catches the real collision, and it does so on evidence rather than
+  // on a token count.
+  console.log(`\nNOTE ${sparseReadings.length} reading(s) were too bare to distinguish a screen:`);
+  for (const f of sparseReadings) console.log(`       ${f}`);
+  console.log(`\nFewer than ${MIN_TOKENS_FOR_A_READING} tokens after two reads. That is not automatically`);
+  console.log('wrong — a plain screen really can be this bare — but two readings this sparse');
+  console.log('cannot be told apart, which is the hazard TOKEN_RULES_VERSION 7 was written');
+  console.log('for. If a same-screen score below disagrees with itself, start here.');
+}
+
+if (staleReadings.length) {
+  // A NOTE and not a failure, for the same reason the sparseness guard is one:
+  // this says the runner was too slow to give a fresh frame, which is a fact
+  // about the machine and not about the fingerprint. It is printed *above* the
+  // arrival check on purpose — when both fire, this is the explanation of that.
+  console.log(`\nNOTE ${staleReadings.length} reading(s) never got a frame newer than their navigation:`);
+  for (const f of staleReadings) console.log(`       ${f}`);
+  console.log(`\nCapture on this host is behind the tour. With damage-driven capture a "fresh"`);
+  console.log('read returns the newest frame that exists, so on a slow runner it can predate');
+  console.log('the navigation entirely. If an arrival failure follows, this is its cause and');
+  console.log('the tour is not what needs fixing.');
+}
+
 if (arrivalFailures.length) {
   console.error(`\nFAIL ${arrivalFailures.length} reading(s) were taken on the previous screen:`);
   for (const f of arrivalFailures) console.error(`       ${f}`);
@@ -296,6 +521,20 @@ if (strays.length) {
     const matchNamed = match ? namedTokens(match.tokens) : [];
     const collided = bestOther >= 0.99 && named.length === 0 && matchNamed.length === 0;
     if (collided) collisions += 1;
+    // The third cause, and the one that produced this report on 2026-09-15.
+    //
+    // A reading that stayed under the token floor did not fail to resemble its
+    // screen — it never saw enough of the screen to resemble anything. On CI
+    // `settings-general` read 4 tokens and scored 1.00 against the Settings
+    // root, because the General screen's back button is labelled "Settings", so
+    // a General seen only down to its nav bar IS the root structurally. The
+    // report called that a wrong turn and sent the reader to fix the tour.
+    //
+    // Not folded into `collided` above: that one means the fingerprint had
+    // nothing to work with, which is this harness's subject. This means we did
+    // not look long enough, which is the harness's own fault and a different
+    // remedy.
+    const underRead = sparseAt.has(`${reading.name}|${reading.round}`);
     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'})`);
@@ -303,6 +542,10 @@ if (strays.length) {
       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.');
+    } else if (underRead) {
+      console.error('              ^ UNDER-READ, not a wrong turn: this reading stayed below the token');
+      console.error('                floor after every retry, so it never saw enough of its screen to');
+      console.error('                resemble one. Two screens read this thinly are the same screen.');
     }
     if (named.length) console.error(`              names: ${named.map((t) => t.slice(t.indexOf('"'), t.lastIndexOf('"') + 1)).join(' ')}`);
   }
@@ -310,6 +553,10 @@ if (strays.length) {
     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 if (strays.every((x) => sparseAt.has(`${x.reading.name}|${x.reading.round}`))) {
+    console.error('\nEvery stray above was UNDER-READ, so this says nothing about the tour or the');
+    console.error('fingerprint — the harness scored a look that was too short. The retries are in');
+    console.error('SPARSE_READ_RETRIES; a runner that needs more than they allow is the finding.');
   } 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');