simframe 0.14.2 → 0.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "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/check-published.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Does the version on npm contain the code you think it does?
+ *
+ * **DEFERRED 149.** `0.14.1` was tagged at one commit and a change landed
+ * immediately after it, so `npm install simframe@0.14.1` shipped the previous
+ * `centerOf()`. An external tester was asked to evaluate that change, diffed
+ * the package against the checkout themselves, and wrote: *"I came within one
+ * command of filing this report against the wrong binary."*
+ *
+ * Nothing in the pipeline compared what was tagged against what was being asked
+ * for, and the release workflow cannot: it checks that the tag, `package.json`
+ * and `server.json` agree, which they did. The gap is between the tag and
+ * whatever arrived afterwards.
+ *
+ * So this is the check to run **before handing someone a version to test**, and
+ * before cutting the next one. It fetches the published tarball and compares
+ * every shipped source file against the working tree.
+ *
+ * It deliberately compares against the WORKING TREE rather than a tag: the
+ * question being asked is "is what I am about to ask someone to install the code
+ * I am looking at", and a tag cannot answer that.
+ *
+ * Usage:
+ *   node scripts/check-published.mjs            # the version in package.json
+ *   node scripts/check-published.mjs 0.14.1     # any published version
+ *   node scripts/check-published.mjs --latest   # whatever npm serves as latest
+ *
+ * Exit 0 when every shipped file matches, 1 when any differs, 2 when the
+ * version is not published or npm could not be reached — which is a different
+ * answer and must not read as "it matches".
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const md5 = (buf) => createHash('md5').update(buf).digest('hex');
+const here = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+
+const arg = process.argv.slice(2).find((a) => !a.startsWith('-'));
+const wantLatest = process.argv.includes('--latest');
+const local = JSON.parse(fs.readFileSync(path.join(here, 'package.json'), 'utf8'));
+
+let version = arg ?? local.version;
+if (wantLatest) {
+  try {
+    version = execFileSync('npm', ['view', local.name, 'version'], { encoding: 'utf8' }).trim();
+  } catch (err) {
+    console.error(`could not ask npm for the latest ${local.name}: ${err.message}`);
+    process.exit(2);
+  }
+}
+
+console.log(`comparing ${local.name}@${version} on npm against this working tree`);
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'simframe-published-'));
+let tarball;
+try {
+  tarball = execFileSync('npm', ['pack', `${local.name}@${version}`, '--silent', '--pack-destination', tmp], {
+    encoding: 'utf8',
+  }).trim().split('\n').pop();
+} catch (err) {
+  // Not published, unpublished, or no network. None of those is a match.
+  console.error(`could not fetch ${local.name}@${version} from npm.`);
+  console.error('That is not the same answer as "it differs" — nothing was compared.');
+  console.error(String(err.stderr || err.message).trim().split('\n').slice(-3).join('\n'));
+  process.exit(2);
+}
+
+execFileSync('tar', ['-xzf', path.join(tmp, tarball), '-C', tmp]);
+const root = path.join(tmp, 'package');
+
+/** Every file the package ships, relative to the package root. */
+const shipped = [];
+const walk = (dir) => {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walk(full);
+    else shipped.push(path.relative(root, full));
+  }
+};
+walk(root);
+
+// Only compare what this repo is the source of. `package.json` is rewritten by
+// npm on publish (it adds `_id`, `dist`, and normalises fields), so byte
+// equality there is not the question and would be a permanent false alarm.
+const comparable = shipped.filter((f) => /^(src|scripts|native)\//.test(f) && !f.includes('/.build/'));
+
+const same = [];
+const differ = [];
+const missing = [];
+for (const rel of comparable) {
+  const mine = path.join(here, rel);
+  if (!fs.existsSync(mine)) { missing.push(rel); continue; }
+  if (md5(fs.readFileSync(mine)) === md5(fs.readFileSync(path.join(root, rel)))) same.push(rel);
+  else differ.push(rel);
+}
+
+const publishedVersion = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+console.log(`  published version: ${publishedVersion}`);
+console.log(`  files compared:    ${comparable.length}`);
+console.log(`  identical:         ${same.length}`);
+
+if (missing.length) {
+  console.log(`  shipped but absent here: ${missing.length}`);
+  for (const f of missing) console.log(`    ${f}`);
+}
+
+if (!differ.length && !missing.length) {
+  console.log(`\nok — ${local.name}@${version} is the code in this tree`);
+  process.exit(0);
+}
+
+console.error(`\nFAIL ${differ.length} shipped file(s) differ from this tree:`);
+for (const f of differ) console.error(`    ${f}`);
+console.error('\nIf you are about to ask someone to test a change, they would be testing');
+console.error('the published bytes above, not what you are reading. Publish first, or point');
+console.error('them at the checkout and say so.');
+process.exit(1);

package/scripts/ci-device-guard.mjs

@@ -31,6 +31,24 @@ const DEVICE_STATE = [
   [/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'],
+  // A launched app that never comes to the front, seen as the tour waiting for
+  // one of its landmarks on a screen that is showing a clock and nothing else.
+  //
+  // Measured on a runner: `ok launch — launched com.apple.Preferences
+  // (relaunched)` followed by `waited 8000ms for General: "General" is not on
+  // this screen. Visible: 10:50, .?o (the screen has not moved for 6181ms)`.
+  // Two labels, one of them a clock, on a still screen — the device is not
+  // presenting the app, and the guard called that a check failing on its
+  // merits and declined to revive.
+  //
+  // Deliberately narrow. It requires the wait to have failed AND the screen to
+  // have been still AND almost nothing readable: a tour that genuinely asks for
+  // the wrong label has a screen full of other labels, and must keep failing
+  // rather than being retried into a pass.
+  [
+    /never arrived[\s\S]*?Visible:[^\n]{0,24}\(the screen has not moved for \d+ms/i,
+    'a launched app never came to the front (the screen shows a clock and nothing else)',
+  ],
 ];
 
 const udid = process.argv[2];

package/scripts/classify-stray.mjs

@@ -0,0 +1,63 @@
+/**
+ * Why does a fingerprint reading not resemble its own screen?
+ *
+ * Its own module, with no side effects, for one reason: this logic has failed
+ * at RUNTIME twice — once reaching for a variable local to another function,
+ * once on declaration order — while being correct both times. `eval-fingerprint.mjs`
+ * runs the whole eval on import, so nothing could test it there, and the only
+ * thing that ever exercised it was a hosted runner at the end of a
+ * fifteen-minute job, in the middle of a report. That is the most expensive
+ * place in this project to find a typo.
+ *
+ * Three causes, and they have different remedies — which is the whole reason to
+ * tell them apart rather than print one sentence about all three:
+ *
+ * - **collided** — neither reading carries a chrome label, so both are
+ *   structure with no name and the fingerprint has nothing left to separate two
+ *   list screens. That is this harness's own subject, and a real finding.
+ * - **wrongScreen** — the tokens are identical to another screen AND this
+ *   screen reads differently in its other rounds, so it is demonstrably
+ *   distinguishable and the tour was simply somewhere else. A tap that missed.
+ * - **underRead** — the reading stayed under the token floor and the screen
+ *   cannot tell itself apart in any round, so we never looked long enough. Ours
+ *   to fix, and nothing about the tour or the fingerprint.
+ *
+ * The middle case is the correction that prompted this. Sparseness alone used
+ * to claim `underRead`, and a wrong turn onto a screen that *legitimately*
+ * reads sparse — the Settings root, at 4 tokens on a runner — is flagged sparse
+ * too. So a genuine tour failure was reported as our instrument's fault, and
+ * the harness's original and correct message had been silenced by an
+ * "improvement".
+ */
+import * as fingerprint from '../src/fingerprint.js';
+
+/**
+ * @param {object} o
+ * @param {object} o.reading           the stray
+ * @param {object|null} o.match        the other screen's reading it most resembles
+ * @param {number} o.bestOther         how much it resembles that one, 0..1
+ * @param {object[]} o.siblings        every reading of the stray's own screen
+ * @param {boolean} o.wasSparse        did it stay under the token floor after retries
+ * @param {string[]} [o.named]         chrome-labelled tokens in the stray
+ * @param {string[]} [o.matchNamed]    chrome-labelled tokens in the match
+ */
+export function classifyStray({
+  reading, match, bestOther, siblings, wasSparse, named = [], matchNamed = [],
+}) {
+  // Does any other round of this same screen read differently from the screen
+  // we collided with? If so this screen CAN be told apart, and a round that
+  // matched the other one exactly was somewhere else.
+  const distinguishable = (siblings ?? [])
+    .some((o) => o !== reading && fingerprint.similarity(o.tokens, match?.tokens ?? []) < 0.99);
+  const identical = bestOther >= 0.99;
+  // Checked first and exclusively: a reading with no names at all cannot be
+  // said to have gone anywhere, because there is nothing in it that would have
+  // named a destination.
+  const collided = identical && named.length === 0 && matchNamed.length === 0;
+  return {
+    collided,
+    wrongScreen: !collided && identical && distinguishable,
+    underRead: !collided && Boolean(wasSparse) && !distinguishable,
+    distinguishable,
+  };
+}

package/scripts/eval-fingerprint.mjs

@@ -20,6 +20,7 @@
 import fs from 'node:fs';
 import * as actions from '../src/actions.js';
 import * as fingerprint from '../src/fingerprint.js';
+import { classifyStray } from './classify-stray.mjs';
 import * as graph from '../src/graph.js';
 import * as api from '../src/index.js';
 
@@ -152,12 +153,24 @@ const STALE_READ_RETRIES = 3;
  * 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.
  */
+/**
+ * How old a frame may be and still be a reading of NOW.
+ *
+ * `FRAME_IS_CURRENT_MS` in src/index.js is 2500 for the same question on the
+ * settle path. Doubled here because this harness deliberately reads cold and a
+ * hosted runner's capture p50 is 2.5x this laptop's — but bounded, because a
+ * 38-second-old frame is a different screen, not a slow one.
+ */
+const FRAME_TOO_OLD_MS = 5000;
+
 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;
+/** What the tour's own steps said, kept for the arrival report. */
+let lastSteps = [];
 /** Readings that never got a frame newer than their own navigation. */
 const staleReadings = [];
 
@@ -222,7 +235,37 @@ for (let round = 1; round <= rounds; round += 1) {
       // written out first, because a failing run is the one whose evidence
       // matters.
       try {
-        await actions.runScript(device, { steps: screen.steps, verify: false });
+        // Keep what the tour's own steps reported. On an arrival failure the
+        // decisive question is whether the last wait PASSED and on what — and
+        // that answer was being thrown away, so three CI failures in a row
+        // could only be reasoned about rather than read. A local reproduction
+        // ran the same sequence 14 times and landed correctly every time, so
+        // the runner is the only place this can be observed.
+        const run = await actions.runScript(device, { steps: screen.steps, verify: false });
+        lastSteps = (run?.results ?? []).map((r) => ({
+          action: r.action,
+          ok: r.ok !== false,
+          ms: r.ms,
+          detail: typeof r.detail === 'string' ? r.detail.slice(0, 200) : null,
+        }));
+        // **`runScript` does not throw on a failed step** — it returns
+        // `ok: !failed` — and this only ever caught throws. So a tour whose
+        // `waitFor` timed out was treated as having arrived: `navigatedAt` was
+        // set, the previous screen was read, and the arrival check then reported
+        // it as a fingerprint result. Three CI failures were that, and the
+        // diagnostic added one commit earlier is what showed it —
+        // `ok launch … / FAIL waitFor` sitting under a reading the harness had
+        // accepted.
+        //
+        // A tour that did not arrive is a precondition, not a measurement. It
+        // throws into the same handler as a step that threw, so the report is
+        // identical and the readings so far are still written out.
+        if (run && run.ok === false) {
+          const bad = (run.results ?? []).find((r) => r.ok === false);
+          throw new Error(
+            `step ${bad?.action ?? '?'} did not succeed: ${bad?.error ?? 'no reason given'}`,
+          );
+        }
         navigatedAt = Date.now();
       } catch (err) {
         save({ abandonedAt: { screen: screen.name, round, error: err.message } });
@@ -275,18 +318,38 @@ for (let round = 1; round <= rounds; round += 1) {
     // 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) {
+      // TWO conditions, and the second was missing.
+      //
+      // Newer than the navigation is not the same as recent. Measured on a
+      // runner: a reading came off a frame **38,266 ms old** and passed this
+      // guard, because the navigation had also been more than 38 s earlier — so
+      // `capturedAt >= navigatedAt` held while the frame was half a minute
+      // stale and showed a screen two steps back. `settled: true` alongside it,
+      // because a starved capture looks exactly like a still one.
+      //
+      // A frame this old is capture starvation, not a slow screen, and no
+      // number of re-reads invents a frame the daemon is not producing. So it
+      // retries and then says which of the two it is, because "the frame
+      // predates the navigation" and "capture stopped producing frames" point
+      // at completely different things.
+      const tooOld = (r) => Date.now() - (r.state?.capturedAt ?? 0) > FRAME_TOO_OLD_MS;
+      const predatesNav = (r) => (r.state?.capturedAt ?? 0) < 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`
+        if (!predatesNav(id) && !tooOld(id)) break;
+        const age = Date.now() - (id.state?.capturedAt ?? 0);
+        console.log(`         ("${screen.name}" read a frame from ${age}ms ago`
+          + `${predatesNav(id) ? ', older than the navigation' : `, over the ${FRAME_TOO_OLD_MS}ms freshness bound`}`
           + ` — 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) {
+      if (predatesNav(id)) {
         staleReadings.push(`${screen.name} round ${round}: frame still predates the navigation`
           + ` by ${navigatedAt - (id.state?.capturedAt ?? 0)}ms after ${STALE_READ_RETRIES} re-reads`);
+      } else if (tooOld(id)) {
+        staleReadings.push(`${screen.name} round ${round}: newest frame is`
+          + ` ${Date.now() - (id.state?.capturedAt ?? 0)}ms old after ${STALE_READ_RETRIES} re-reads`
+          + ' — capture is starved, not the screen still');
       }
     }
     // A reading too sparse to be a screen is not a reading.
@@ -343,6 +406,7 @@ for (let round = 1; round <= rounds; round += 1) {
     // taken, and every distribution below it is then measuring the tour rather
     // than the fingerprint. The first version of this harness did exactly that
     // and reported that the distributions overlapped completely.
+    id.steps = lastSteps;
     const previous = readings[readings.length - 1];
     if (previous && previous.name !== screen.name) {
       // Not just an identical hash. Two readings of the same screen can differ
@@ -367,10 +431,20 @@ for (let round = 1; round <= rounds; round += 1) {
           `${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)'}`);
+          + `\n         on screen: ${labels.length ? labels.join(' · ') : '(nothing readable)'}`
+          // The decisive line, and it was missing. Whether the tour's last wait
+          // PASSED, and what it said, separates "the wait matched something it
+          // should not have" from "the screen changed after the wait was
+          // satisfied" — the two causes this message has always named as having
+          // opposite fixes, while giving the reader nothing to tell them apart.
+          + `\n         the tour's own steps: ${
+            (lastSteps ?? []).length
+              ? lastSteps.map((st) => `${st.ok ? 'ok' : 'FAIL'} ${st.action}${st.detail ? ` — ${st.detail}` : ''}`).join('\n                               ')
+              : '(not recorded)'}`);
       }
     }
     readings.push({
+      steps: lastSteps,
       name: screen.name,
       round,
       hash: id.hash,
@@ -506,6 +580,17 @@ function findStrays(all) {
 }
 
 const strays = findStrays(readings);
+// Readings grouped by screen, for the classification below.
+//
+// `findStrays` builds this too and it is LOCAL to that function — so reaching
+// for it here threw `byName is not defined` on a runner, in the middle of the
+// report, after the strays had already been printed. I had validated the
+// classification against a saved artifact in a standalone script, where I had
+// declared it myself, and never once in place. The logic was right and the
+// integration was never run: the unit tests do not reach this file at all.
+const readingsByName = new Map();
+for (const r of readings) readingsByName.set(r.name, [...(readingsByName.get(r.name) ?? []), r]);
+
 if (strays.length) {
   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
@@ -516,10 +601,25 @@ if (strays.length) {
   // 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;
+  // Kept so the SUMMARY agrees with the lines above it. It did not: the summary
+  // tested `sparseAt` directly while each line used the classifier, so a stray
+  // correctly labelled WRONG SCREEN was followed by "every stray above was
+  // UNDER-READ". A report that contradicts itself in consecutive paragraphs is
+  // worse than either sentence alone.
+  const verdicts = [];
   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;
+    // One classifier, one source of truth. `collided` was computed here as well
+    // and the two could drift — which is how this block came to have a third
+    // cause landing in the wrong bucket in the first place.
+    const verdict = classifyStray({
+      reading, match, bestOther, named, matchNamed,
+      siblings: readingsByName.get(reading.name) ?? [],
+      wasSparse: sparseAt.has(`${reading.name}|${reading.round}`),
+    });
+    const { collided, underRead, wrongScreen } = verdict;
+    verdicts.push(verdict);
     if (collided) collisions += 1;
     // The third cause, and the one that produced this report on 2026-09-15.
     //
@@ -549,10 +649,6 @@ if (strays.length) {
     // distinguishable and a round matching another screen exactly went
     // somewhere else. Only when no round of this screen can tell itself apart
     // is "we did not look long enough" the honest reading.
-    const distinguishable = (byName.get(reading.name) ?? [])
-      .some((o) => o !== reading && fingerprint.similarity(o.tokens, match?.tokens ?? []) < 0.99);
-    const underRead = sparseAt.has(`${reading.name}|${reading.round}`) && !distinguishable;
-    const wrongScreen = bestOther >= 0.99 && distinguishable;
     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'})`);
@@ -576,10 +672,16 @@ 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}`))) {
+  } else if (verdicts.length && verdicts.every((v) => v.underRead)) {
     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 if (verdicts.some((v) => v.wrongScreen)) {
+    const n = verdicts.filter((v) => v.wrongScreen).length;
+    console.error(`\n${n} stray(s) were read on the WRONG SCREEN — the tokens match another screen`);
+    console.error('exactly while this one reads differently in its other rounds, so it is');
+    console.error('distinguishable and the tour was somewhere else. Not a fingerprint result:');
+    console.error('a tap that missed, or a screen that went back before it was read.');
   } 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');

package/src/actions.js

@@ -732,7 +732,10 @@ export async function runScript(
         // eight times below its threshold, so it reads as no-visible-change and
         // its edge is no longer recorded. That is the right trade while the
         // detector cannot see it, and it comes back on its own once it can.
-        const noEvidence = Boolean(settled?.noVisibleChange);
+        // A changed control IS evidence, whatever the frame hash says. Without
+        // this the edge is not recorded either, so a toggle that worked teaches
+        // the graph nothing and stays unpredictable forever.
+        const noEvidence = Boolean(settled?.noVisibleChange) && !stateDelta(beforeScreen?.entry, afterReading?.entry);
         if (afterScreen.confirmed && afterScreen.hash && !noEvidence) {
           // The observed cost of this transition, which is what makes the next
           // one adaptive. Only from a settle that was actually satisfied: a
@@ -788,7 +791,22 @@ export async function runScript(
       // first — and six swipes reporting "no visible change" is what item 120
       // was reported against. Keying on one of them would have shipped a fix
       // that did not fire on its own bug report.
-      const wentNowhere = Boolean(settled?.noVisibleChange) || verification?.verdict === 'no-visible-change';
+      // Declared BEFORE `wentNowhere`, which reads it. It sat below and the
+      // unit tests were green because nothing without a device reaches this
+      // line — a `const` in the temporal dead zone throws on first use, which
+      // is the same trap the `afterReading` comment above records.
+      //
+      // Computed on EITHER signal, because they are two different sensors and
+      // the reported case came through the one this first version missed: the
+      // radio move settled in 2714ms with `sawChange` true, so
+      // `settled.noVisibleChange` was false and the verdict came from the
+      // fingerprint instead.
+      const changedState = (settled?.noVisibleChange || verification?.verdict === 'no-visible-change')
+        ? stateDelta(beforeScreen?.entry, afterReading?.entry)
+        : null;
+      if (changedState) verification = stateChanged(verification, changedState);
+      const wentNowhere = !changedState
+        && (Boolean(settled?.noVisibleChange) || verification?.verdict === 'no-visible-change');
       const aimNote = wentNowhere && aim.at
         ? screenmap.describePoint(
           // `beforeScreen` is null with verification off, and that is exactly
@@ -802,7 +820,9 @@ export async function runScript(
       const note = launchNote
         + (filling ? ` [settled, but ${filling} — waitFor content, do not act on this yet]` : '')
         + (settled?.smallChange ? ' [a small change, in one region only]' : '')
-        + (settled?.noVisibleChange ? ' [no visible change]' : '')
+        + (changedState
+          ? ` [the screen did not move, but ${changedState.detail} — this worked, do not retry]`
+          : (settled?.noVisibleChange ? ' [no visible change]' : ''))
         // After the symptom, because it is the explanation of it.
         + (aimNote ? ` [${aimNote}]` : '')
         + (settled?.staleBaseline ? ' [baseline had already settled; re-taken from the live screen]' : '')
@@ -1594,6 +1614,37 @@ async function confirmNoChange(deviceQuery, verification, { beforeScreen, option
   };
 }
 
+/**
+ * A control that changed state is not a step that did nothing.
+ *
+ * The sibling of `belowThreshold` on the same verdict, for the other kind of
+ * evidence. `no-visible-change` arrives by two routes — the pixel detector and
+ * the fingerprint agreeing we are on the same screen — and a switch or a radio
+ * satisfies both while having plainly worked. Measured on a device: a radio
+ * moving from "Top" to "Inline" reported `(settled 2714ms)
+ * [no-visible-change]` with `selected` moving between the two rows in the
+ * element list either side of it.
+ *
+ * This is the verdict an agent reads to decide whether to retry, and after item
+ * 148 made the tap actually land, a retry undoes the thing that worked. So the
+ * verdict carries the evidence rather than contradicting it.
+ *
+ * Still not `ok`: the screen genuinely did not become a different screen, and
+ * claiming a transition that did not happen would be the opposite error. It
+ * becomes `unverified` — the verdict this project uses for "something happened
+ * and nobody can vouch for what" — with the change named.
+ */
+export function stateChanged(verification, delta) {
+  if (verification?.verdict !== 'no-visible-change' || !delta) return verification;
+  return {
+    ...verification,
+    verdict: 'unverified',
+    detail: `the screen did not change, but ${delta.detail}`
+      + ' — the action worked; do not retry it, or you will undo it',
+    stateDelta: delta,
+  };
+}
+
 export function belowThreshold(verification, settled) {
   if (verification?.verdict !== 'no-visible-change' || !settled?.smallChange) return verification;
   return {
@@ -1641,6 +1692,37 @@ async function focusHint(deviceQuery, target, ctx) {
   }
 }
 
+/**
+ * Is anything focused? Asked before typing blind.
+ *
+ * `{"type": "text"}` with no `into` types into whatever has focus, and reported
+ * `ok … [unconfirmed — no field named, so nothing was read back]`. The note was
+ * honest and it was attached to a **green step**, so a chained `sim_do`
+ * continued on a premise that had never been checked — a field report lost text
+ * that went nowhere exactly this way.
+ *
+ * If nothing has focus, the keystrokes are lost and there is no version of that
+ * which is an `ok`. The tree already answers it: one accessibility read, no
+ * OCR, which is the same cost `focusHint` pays on the `into` path.
+ *
+ * Advisory in one direction only. A tree that cannot answer — no targets, a
+ * read that threw — returns `unknown`, and the step proceeds with its
+ * unconfirmed note rather than failing on our inability to look. Refusing to
+ * type because we could not read the screen would be a worse trade than the
+ * bug.
+ */
+async function focusedSomewhere(deviceQuery, ctx) {
+  try {
+    const { entry } = await api.readScreenWith(deviceQuery, { useOcr: false, options: ctx.options });
+    const targets = entry?.targets ?? [];
+    if (!targets.length) return { known: false };
+    const hit = targets.find((t) => t.focused === true);
+    return { known: true, focused: Boolean(hit), where: hit?.label ?? hit?.identifier ?? null };
+  } catch {
+    return { known: false };
+  }
+}
+
 /**
  * How long to wait for the tap to become focus before inserting text.
  *
@@ -2319,11 +2401,29 @@ async function runStep(deviceQuery, udid, step, ctx) {
         journalWrite(udid, step, sent, back, ctx);
         return `typed into ${field.where}${back.note}${back.landed ? '' : field.quiet}`;
       }
+      // **Refusing here was tried and reverted — see DEFERRED 161.** The idea
+      // was that "nothing focused" is knowable before typing, so typing into
+      // nothing should fail rather than report `ok`. On a device it produced a
+      // FALSE REFUSAL on the legitimate case: after tapping Settings' own
+      // search field, every element in the tree read `focused: false`. iOS does
+      // not reliably publish AXFocused here, which `focusHint` above already
+      // says in its own comment — *"with a hardware keyboard attached to the
+      // simulator no software keyboard appears, so there is often nothing to
+      // see"*. A gate on an unpublished signal blocks real work, which is worse
+      // than the verdict it was fixing.
+      //
+      // So the focus reading stays advisory and goes into the note. What the
+      // field report actually objected to was an honest caveat attached to a
+      // GREEN step, and the note is where that has to be fixed until there is a
+      // signal worth gating on.
+      const focus = await focusedSomewhere(deviceQuery, ctx);
       await input.typeText(udid, step.text ?? step.value);
-      // No selector, so there is nothing to read back — which is a fine trade
-      // for typing into whatever Safari's own form chevrons focused, but it
-      // must not be reported as though the text was seen to land.
-      return 'typed text [unconfirmed — no field named, so nothing was read back]';
+      return 'typed text [NOT CONFIRMED: no field named, so nothing was read back'
+        + (focus.known && !focus.focused
+          ? ' and nothing on this screen reports keyboard focus — the text may have gone nowhere'
+          : '')
+        + '. Name the field — {"type": {"into": "<field>", "text": "..."}} — to have it tapped'
+        + ' first and read back]';
     }
     case 'paste': {
       // Long strings are much faster on the pasteboard than through the
@@ -2850,6 +2950,66 @@ async function runStep(deviceQuery, udid, step, ctx) {
   }
 }
 
+/**
+ * What changed in the controls, when the pixels say nothing did.
+ *
+ * `settle()` decides `noVisibleChange` from frame hashes alone, and a control
+ * that flips is eight times below the change threshold (DEFERRED 4, measured on
+ * a switch: 0.00049 peak against 0.004). So a switch that genuinely flipped is
+ * reported as an action that did nothing — with the changed value printed in the
+ * same response.
+ *
+ * **That verdict became dangerous the moment item 148 made the tap land.** While
+ * the tap missed the frame centre, `no-visible-change` was true and harmless.
+ * Now the tap actuates, and `no-visible-change` is what an agent reads to decide
+ * whether to retry — so a retry silently un-flips the toggle. An external
+ * tester made exactly that point about my own commit message, which had claimed
+ * the verdict "was telling the truth".
+ *
+ * This is wiring, not calibration. The element values are already in hand on
+ * both sides of the action — `beforeScreen.entry` and the after-reading are read
+ * for verification anyway — so the comparison costs nothing on the device. A
+ * control whose value or selected state changed did something, whatever the
+ * frame hash says.
+ *
+ * Identity across the two readings goes by identifier, then label, then
+ * type-and-place: a row that moved is not the same reading of the same control,
+ * and pretending otherwise would invent changes.
+ */
+export function stateDelta(beforeEntry, afterEntry) {
+  const keyOf = (t) => t.identifier || t.label || `${t.type ?? '?'}@${Math.round(t.x ?? 0)},${Math.round(t.y ?? 0)}`;
+  const stateOf = (t) => `${t.value ?? ''}|${t.selected ?? ''}`;
+  const before = new Map();
+  for (const t of beforeEntry?.targets ?? []) {
+    if (t.value == null && t.selected == null) continue;
+    before.set(keyOf(t), { state: stateOf(t), target: t });
+  }
+  if (!before.size) return null;
+  const changes = [];
+  for (const t of afterEntry?.targets ?? []) {
+    if (t.value == null && t.selected == null) continue;
+    const was = before.get(keyOf(t));
+    if (!was || was.state === stateOf(t)) continue;
+    changes.push({
+      name: t.label || t.identifier || keyOf(t),
+      from: was.target.value ?? was.target.selected,
+      to: t.value ?? t.selected,
+    });
+  }
+  if (!changes.length) return null;
+  // Name the control that turned ON, not the one that turned off. A radio move
+  // changes two rows and reporting "Inline changed from true to false" is
+  // accurate and reads like a loss — the useful half is what is selected now.
+  const on = (v) => v === true || v === 'true' || v === '1';
+  const first = changes.find((c) => on(c.to) && !on(c.from)) ?? changes[0];
+  return {
+    count: changes.length,
+    detail: `${JSON.stringify(String(first.name).slice(0, 32))} changed from `
+      + `${JSON.stringify(String(first.from))} to ${JSON.stringify(String(first.to))}`
+      + (changes.length > 1 ? ` (and ${changes.length - 1} other control(s))` : ''),
+  };
+}
+
 /**
  * Why a settle gave up, in the numbers that decided it.
  *