simframe 0.12.2 → 0.14.0

package/scripts/ci-integration-local.sh

@@ -43,6 +43,15 @@ for (const key of ["input.driver", "ax.driver"]) {
   console.log(`${good ? "ok  " : "FAIL"} ${key} = ${JSON.stringify(d[key])} (want "simframed")`);
   if (!good) failed = true;
 }
+// A configured driver is not an answering driver — the same check as ci.yml.
+// A whole CI run read the screen eighteen times, every reading came back
+// OCR-only, and this step said `ok` because a driver was present.
+{
+  const n = d["ax.elements"];
+  const good = typeof n === "number" && n > 0;
+  console.log(`${good ? "ok  " : "FAIL"} ax.elements = ${JSON.stringify(n)} (want > 0 — the tree must answer, not merely exist)`);
+  if (!good) failed = true;
+}
 if (d.warnings > 0) {
   console.log(`\n${d.warnings} degraded layer(s):`);
   for (const c of d.checks.filter((c) => c.level !== "ok")) console.log(`  ${c.level} ${c.name}: ${c.detail}`);
@@ -58,17 +67,32 @@ 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"
-node scripts/ci-memory.mjs --device="$DEVICE" && ok "ci-memory" || bad "ci-memory"
+# Mirrors the job: exit 75 means the display wedged and nothing was tested, so
+# revive once and run again; any other non-zero is a real check failing. The
+# wedge lands on an app switch and hit roughly every other run of this script on
+# the day it was written, which is most of why the job looked flaky.
+if node scripts/ci-memory.mjs --device="$DEVICE"; then
+  ok "ci-memory"
+elif [ $? = 75 ]; then
+  printf '     (the display wedged — DEFERRED 126. Reviving once and running again.)\n'
+  node src/cli.js revive --device="$DEVICE" || true
+  node scripts/ci-memory.mjs --device="$DEVICE" && ok "ci-memory (after one revive)" || bad "ci-memory"
+else
+  bad "ci-memory"
+fi
 
 step "The fingerprint distributions, measured and bounded"
 node scripts/eval-fingerprint.mjs --tour=test/tours/device-native.json --rounds=3 \

package/scripts/ci-memory.mjs

@@ -50,6 +50,9 @@ let failures = 0;
  */
 let deviceDied = null;
 
+/** EX_TEMPFAIL: the device died under the checks, so nothing was tested. */
+const DEVICE_DIED_EXIT = 75;
+
 function check(ok, label, detail = '') {
   if (!ok) failures += 1;
   console.log(`${ok ? 'ok  ' : 'FAIL'} ${label}${detail ? ` — ${detail}` : ''}`);
@@ -108,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)}`);
   }
 }
 
@@ -171,13 +181,42 @@ async function jsonRetry(args, opts, attempts = 3) {
     console.error(`  ${String(last.message).split('\n')[0]}`);
     console.error('\nEverything after this point would be testing a dead simulator, so the run');
     console.error('stops here. This is not a memory-layer failure — it is the device-state');
-    console.error('problem in docs/DEFERRED.md. A device restart is the only known cure;');
-    console.error('on a hosted runner it means a retry.');
-    process.exit(1);
+    console.error('problem in docs/DEFERRED.md (126). A device restart is the only known cure,');
+    console.error('and `simframe revive` is that restart.');
+    // Exit 75, not 1, and the distinction is the whole point of this file.
+    //
+    // "A check about the memory layer failed" and "the simulator died under the
+    // checks" are different conditions with different responses, and for two CI
+    // rounds they were one exit code — so a caller could only retry everything
+    // or retry nothing. 75 is EX_TEMPFAIL, which is exactly what this is: the
+    // subject under test was never reached.
+    //
+    // The caller reviving and running again is not papering over a product bug.
+    // The wedge is a documented CoreSimulator condition, `frame --fresh` names
+    // it, and `revive` is the cure this project ships for it — CI simply had no
+    // way to say "use it".
+    process.exit(DEVICE_DIED_EXIT);
   }
   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) {
@@ -244,7 +283,36 @@ if (failures) {
 
 console.log('\n--- the screen map ---');
 await jsonRetry(['do', LOOP], { allowFail: true });
-const map = await jsonRetry(['ui']);
+const map = await readableMap();
+
+/**
+ * A map that is empty *and* says a sensor failed is a blink, not a result.
+ *
+ * `jsonRetry` retries a command that throws, and this one did not throw: `ui`
+ * returned 200 with zero elements and a degraded note, which is the shape of
+ * failure this whole repo keeps writing rules about. The run that made this
+ * necessary had the accessibility read time out once, report an empty map, and
+ * then resolve a ref correctly sixty seconds later on the same device — so the
+ * device was fine and the check had caught one bad read.
+ *
+ * Deliberately narrow. An empty map with **no** degraded sensor is a real
+ * answer — that is a blank screen and the check should fail on it. Only an
+ * empty map that admits a layer did not answer is worth asking again, and after
+ * three attempts it fails with what the sensor said, which is the diagnosis
+ * either way.
+ */
+async function readableMap(attempts = 3) {
+  let last;
+  for (let i = 0; i < attempts; i += 1) {
+    last = await jsonRetry(['ui']);
+    if (last.elements?.length || !(last.degraded ?? []).length) return last;
+    if (i < attempts - 1) {
+      console.log(`     (the map came back empty and a sensor said why — retrying \`ui\`: ${(last.degraded ?? []).join('; ')})`);
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  }
+  return last;
+}
 
 // Report what actually answered rather than asserting the runner's situation.
 // This line used to read "with no accessibility tree available" unconditionally,
@@ -263,14 +331,38 @@ check(Number.isFinite(map.points?.width) && Number.isFinite(map.points?.height),
   'the map knows the screen size in points', `${map.points?.width}x${map.points?.height}pt`);
 
 const refs = (map.elements ?? []).map((e) => e.ref);
-check(refs.every((r, i) => r === i + 1),
-  'refs are numbered 1..n with no gaps', `#1..#${refs.length}`);
-check((map.elements ?? []).every((e) =>
-  Number.isInteger(e.x) && Number.isInteger(e.y)
-  && e.y >= 0 && e.y <= map.points.height && e.x >= 0 && e.x <= map.points.width),
-  'every element has a tap point on the screen');
-check(!(map.elements ?? []).some((e) => e.region === 'status-bar'),
-  'the status bar is not offered as something to tap');
+// Three checks over a collection, and `every`/`!some` are all true of an empty
+// one. On a CI run whose map came back with **0 elements** they printed
+// `ok   refs are numbered 1..n with no gaps — #1..#0` and two more like it:
+// three lines of reassurance about nothing, directly under the failure that
+// said the map was empty.
+//
+// That is the exact defect three field reports spent a day describing — a
+// confident statement that verified nothing — and the harness was doing it to
+// itself in the same output. Untested is not passed.
+if (!map.elements?.length) {
+  for (const label of [
+    'refs are numbered 1..n with no gaps',
+    'every element has a tap point on the screen',
+    'the status bar is not offered as something to tap',
+  ]) skip(label, 'the map was empty, so there was nothing to check');
+  // And say what the device was showing, because an empty map on a live device
+  // is the shape this project has chased under four different symptoms. The
+  // liveness note carries the ignored-gesture check; `stableForMs` and the
+  // frame age are the two numbers whose disagreement names a dead surface.
+  const st = await jsonRetry(['state'], { allowFail: true });
+  console.log(`     the device at that moment: frame #${st?.seq ?? '?'}, `
+    + `${st?.stableForMs ?? '?'}ms still, ${st?.live?.note ?? 'liveness reported nothing'}`);
+} else {
+  check(refs.every((r, i) => r === i + 1),
+    'refs are numbered 1..n with no gaps', `#1..#${refs.length}`);
+  check(map.elements.every((e) =>
+    Number.isInteger(e.x) && Number.isInteger(e.y)
+    && e.y >= 0 && e.y <= map.points.height && e.x >= 0 && e.x <= map.points.width),
+    'every element has a tap point on the screen');
+  check(!map.elements.some((e) => e.region === 'status-bar'),
+    'the status bar is not offered as something to tap');
+}
 
 console.log('\n--- element refs ---');
 // Re-read on a screen we chose, rather than on whatever the device happened to
@@ -296,7 +388,8 @@ if (first) {
   // 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;
-  if (!ran(left)) skip('the screen actually changed before testing the stale ref',
+  const launched = ran(left);
+  if (!launched) 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)}`
@@ -305,7 +398,16 @@ if (first) {
   // reports "the stale-ref guard failed" for a device that never left the
   // 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) {
+  // A skip has to propagate. The precondition above reported NOT TESTED and this
+  // check ran anyway and failed — which is the harness doing to itself, one line
+  // later, exactly what `skip` was written to stop it doing. `moved` is true
+  // when a hash is too degenerate to have a say, and that is right for "did the
+  // screen change" and wrong as a licence to run a check whose setup is known
+  // not to have happened.
+  if (!launched) {
+    skip('a ref numbered on another screen refuses instead of tapping those coordinates',
+      'we never reached another screen, so there was nothing to refuse from');
+  } else if (moved) {
     // 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

package/scripts/eval-fingerprint.mjs

@@ -86,6 +86,17 @@ 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 = [];
+/**
+ * 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 +135,22 @@ 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;
+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 = [];
+
 for (let round = 1; round <= rounds; round += 1) {
   for (const screen of tour) {
     if (screen.steps?.length) {
@@ -140,6 +167,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 +176,66 @@ for (let round = 1; round <= rounds; round += 1) {
         process.exit(1);
       }
     }
-    const id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+    let id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+    // 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) {
+      const before = (id.tokens ?? []).length;
+      await new Promise((r) => setTimeout(r, 1500));
+      id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+      const after = (id.tokens ?? []).length;
+      console.log(`         ("${screen.name}" read ${before} token(s) — too sparse to compare; read again: ${after})`);
+      if (after < MIN_TOKENS_FOR_A_READING) {
+        sparseReadings.push(`${screen.name} round ${round}: ${after} token(s) after two reads`);
+      }
+    }
     // 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
@@ -164,8 +251,21 @@ for (let round = 1; round <= rounds; round += 1) {
       // means the navigation did not happen.
       const s = fingerprint.similarity(previous.tokens, id.tokens ?? []);
       if (s >= ARRIVAL_SUSPICION) {
+        // What was actually on screen, not just that it was the wrong thing.
+        //
+        // This check has fired twice on CI and both times the report was a
+        // similarity score and two screen names, which is enough to know the
+        // run is void and not enough to know why. The tour asserts arrival with
+        // a `waitFor` before this ever runs, so a failure here means the
+        // `waitFor` *passed* on a screen that was not the destination — and the
+        // labels are the only thing that can say what that screen was.
+        const labels = (id.entry?.targets ?? [])
+          .map((t) => t.label).filter(Boolean).slice(0, 12).map((l) => l.slice(0, 24));
         arrivalFailures.push(
-          `${previous.name} -> ${screen.name}: similarity ${s.toFixed(2)} — the screen did not change`);
+          `${previous.name} -> ${screen.name}: similarity ${s.toFixed(2)} — the screen did not change`
+          + `\n         sensors: ${(id.entry?.sources ?? []).join('+') || 'none'}`
+          + `, settled: ${id.settled}, frame ${Math.round(Date.now() - (id.state?.capturedAt ?? Date.now()))}ms old`
+          + `\n         on screen: ${labels.length ? labels.join(' · ') : '(nothing readable)'}`);
       }
     }
     readings.push({
@@ -206,9 +306,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}`);
@@ -216,6 +352,12 @@ if (arrivalFailures.length) {
   console.error('measure the tour rather than the fingerprint. Fix the tour and re-run.');
   console.error('A `settle` step defaults to mode "stable", which returns instantly in the');
   console.error('moment before an animation begins — action steps already settle on their own.');
+  console.error('');
+  console.error('The tour asserts arrival with a `waitFor` before any reading is taken, so a');
+  console.error('failure here means that wait PASSED on a screen that was not the destination.');
+  console.error('Read the labels above before changing the tour: either the wait matched');
+  console.error('something it should not have, or the reading came off a frame older than the');
+  console.error('navigation — and those have opposite fixes.');
   process.exit(1);
 }
 

package/scripts/replay-rulings.mjs

@@ -76,6 +76,8 @@ if (baseline > 0.65) {
 const STILL_MS_THRESHOLD = 3000;
 console.log(`\nthe brief every model arm gets is ${ollama.readBrief().length} characters, read from native/supervise.swift`);
 
+const withAbstain = process.argv.includes('--abstain');
+
 const results = [];
 for (const arm of arms) {
   const judged = [];
@@ -87,6 +89,7 @@ for (const arm of arms) {
     const detail = {};
     const ruling = await supervisor.judge({
       ...r.situation,
+      mayAbstain: withAbstain,
       options: { supervisor: arm },
       // Wide on purpose. The shipped budget is 2.5s and a 14B will exceed it;
       // capping here would score the larger model on *latency* while calling it
@@ -96,7 +99,7 @@ for (const arm of arms) {
       detail,
     });
     if (!ruling) unanswered += 1;
-    judged.push({ r, ruling, detail });
+    judged.push({ r, ruling, detail, abstained: detail.kind === 'abstained' });
     process.stdout.write('.');
   }
   const answered = judged.filter((j) => j.ruling);
@@ -104,6 +107,7 @@ for (const arm of arms) {
   const lat = answered.map((j) => j.ruling.ms).filter(Number.isFinite).sort((a, b) => a - b);
   results.push({
     arm,
+    judged,
     n: rows.length,
     unanswered,
     // Scored over every situation, not only the answered ones. A judge that
@@ -131,6 +135,24 @@ for (const r of results) {
   console.log(`${r.arm.padEnd(26)} ${pct(r.accuracy).padStart(9)} ${`${r.medianMs ?? '—'}ms`.padStart(9)} ${`${r.unanswered}`.padStart(10)}`);
 }
 
+if (withAbstain) {
+  console.log(`\n--- item 100: the fourth word ---`);
+  console.log('The question is not whether it abstains. It is whether it abstains on');
+  console.log('the ones it would have got WRONG, or at random. A judge that declines');
+  console.log('uniformly has added latency and a round trip and bought nothing.\n');
+  console.log(`${'arm'.padEnd(22)} ${'answered'.padStart(9)} ${'of those'.padStart(9)} ${'abstained'.padStart(10)} ${'escalations'.padStart(12)}`);
+  console.log('-'.repeat(66));
+  for (const r of results) {
+    const answered = r.judged.filter((j) => j.ruling);
+    const right = answered.filter((j) => satisfies(j.ruling.decision, want(j.r))).length;
+    const abstained = r.judged.filter((j) => j.abstained).length;
+    console.log(`${r.arm.padEnd(22)} ${`${answered.length}/${rows.length}`.padStart(9)} ${pct(right / (answered.length || 1)).padStart(9)} ${`${abstained}`.padStart(10)} ${pct(abstained / rows.length).padStart(12)}`);
+  }
+  console.log('\n`of those` is accuracy on the questions it chose to answer. If the fourth');
+  console.log('word is working, that number is higher than the three-word accuracy above');
+  console.log('by more than the abstention rate would give by chance.');
+}
+
 console.log('\nerrors, by arm:');
 for (const r of results) {
   console.log(`  ${r.arm}`);
@@ -140,6 +162,43 @@ for (const r of results) {
   for (const [e, n] of [...seen].sort((a, b) => b[1] - a[1])) console.log(`    ${String(n).padStart(3)}x ${e}`);
 }
 
+// --- the cascade: threshold -> local model -> Claude -----------------------
+//
+// The owner's proposal, and the numbers are the only way to say whether it
+// helps: answer with the free rule where it is confident, fall through to the
+// on-device model where it is not, and only then pay a round trip.
+//
+// **A cascade needs a tier that can decline, and neither tier has one.** The
+// threshold is a comparison — it always answers. The supervisor's vocabulary is
+// three words and none of them is "I don't know". So the interesting number is
+// not "does a cascade help" but "how much would an abstain token be worth", and
+// that is item 100. This measures it directly, by letting the rule abstain in a
+// band around its own threshold and handing those to the next tier.
+const armDecisions = new Map(results.map((r) => [r.arm, r.judged]));
+console.log('\n--- cascade: the rule answers, the model covers where it abstains ---');
+console.log(`${'abstain band'.padEnd(22)} ${'rule'.padStart(6)} ${'->model'.padStart(8)} ${'cascade'.padStart(9)} ${'model calls'.padStart(12)}`);
+for (const band of [0, 250, 500, 750, 1000, 1500]) {
+  const lo = STILL_MS_THRESHOLD - band;
+  const hi = STILL_MS_THRESHOLD + band;
+  for (const arm of arms) {
+    const judged = armDecisions.get(arm) ?? [];
+    let right = 0;
+    let escalated = 0;
+    for (const [i, r] of rows.entries()) {
+      const still = r.situation.stillMs ?? 0;
+      if (band > 0 && still >= lo && still <= hi) {
+        escalated += 1;
+        const ruling = judged[i]?.ruling;
+        if (ruling && satisfies(ruling.decision, want(r))) right += 1;
+        continue;
+      }
+      if (satisfies(still > STILL_MS_THRESHOLD ? 'stop' : 'wait', want(r))) right += 1;
+    }
+    console.log(`${`+/-${band}ms -> ${arm}`.padEnd(22)} ${pct(stillRule).padStart(6)} ${`${escalated}`.padStart(8)} ${pct(right / rows.length).padStart(9)} ${`${escalated}/${rows.length}`.padStart(12)}`);
+  }
+  if (band === 0) console.log('  (band 0 = no abstention, the rule alone — every row below adds a tier)');
+}
+
 console.log('\nThis scores DECISIONS on identical inputs. It cannot score outcomes —');
 console.log('whether acting on a ruling recovered the flow is a fact about the device at');
 console.log('that moment, and belongs to whichever arm was live. See docs/EXPERIMENTS.md.');