simframe 0.17.0 → 0.19.0

package/scripts/demo-gif/flow.json

@@ -0,0 +1,6 @@
+[
+  { "tap": "Accessibility" },
+  { "tap": "Display & Text Size" },
+  { "tap": "Larger Text" },
+  { "assert": { "value": "Larger Text" } }
+]

package/scripts/device-state.mjs

@@ -1,62 +1,5 @@
-// Is a failed CI step the device's fault or the check's?
-//
-// Its own module, and the reason is the same one that moved `classifyStray` out
-// of `eval-fingerprint.mjs`: `ci-device-guard.mjs` reads `process.argv` and
-// `process.exit(2)`s at import, so nothing could ever test this table there —
-// and the only thing that exercised it was a hosted runner, at the end of a
-// fifteen-minute job, in the middle of a report. Two runtime bugs in this
-// project came from logic that was correct and had never executed.
-//
-// Every entry here has been seen in a real run. Adding one from imagination is
-// how a guard starts reviving genuine failures into passes.
-
-/** Conditions that are the simulator, not the code. Each seen in a real run. */
-export 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'],
-  // 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)',
-  ],
-  // The same condition, now said outright by the step that suffered it instead
-  // of inferred from the shape of the screen afterwards. Item 169 gave `launch`
-  // a pid to compare, so a launch that starts a process and never fronts it
-  // reports itself; this signature fires on the cause rather than on a
-  // consequence that had to be recognised by "two labels, one a clock".
-  //
-  // It cannot be triggered by a tour asking for the wrong label — only a failed
-  // launch emits this sentence — so it needs none of the narrowing above.
-  [
-    /never came to the front within \d+ms/i,
-    'a launched app never came to the front (the launch said so itself, by pid)',
-  ],
-  // Seen on the v0.14.3 bench run: `could not launch com.apple.Preferences:
-  // The system shell (SpringBoard:36454) probably crashed.` The guest's window
-  // server going down is the device, not the check, and nothing here matched it.
-  [
-    /system shell \(SpringBoard[^)]*\) probably crashed/i,
-    "the guest's SpringBoard crashed, so nothing can be fronted",
-  ],
-];
-
-/** The condition this output shows, or null when the check failed on its merits. */
-export function deviceCause(text) {
-  return DEVICE_STATE.find(([re]) => re.test(String(text ?? '')))?.[1] ?? null;
-}
+// Kept as a re-export: the table moved to `src/device-state.js` so `src/` can
+// use it without importing out of `scripts/`. `ci-device-guard.mjs` and the
+// unit test both reach it through this path, and a redirect is cheaper than
+// updating every caller for a move that changes nothing about the table.
+export { DEVICE_STATE, deviceCause } from '../src/device-state.js';

package/scripts/smithery-bundle.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Builds the Smithery bundle for the current version:
+//   node scripts/smithery-bundle.mjs            -> simframe-<version>.mcpb
+//   npx -y @smithery/cli mcp publish ./simframe-<version>.mcpb -n lvlr-xaus/simframe
+//
+// Smithery does not sync from the official MCP Registry, and its web form
+// takes only an HTTPS URL, so a local stdio server reaches it as an MCPB
+// bundle through the CLI. Two things learned publishing 0.18.0, both
+// load-bearing:
+//
+// - Smithery's validator wants an `inputSchema` on every tool it is told
+//   about, and Anthropic's `mcpb pack` refuses that key as unknown. So the
+//   tool list is taken from the server's own tools/list answer, schemas
+//   included, and the archive is a plain zip — a .mcpb is nothing else.
+// - The bundle is the packed npm tarball plus its runtime dependency
+//   installed inside it, because a bundle runs from its own directory.
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+const work = fs.mkdtempSync(path.join(os.tmpdir(), 'simframe-mcpb-'));
+const dir = path.join(work, 'pkg');
+fs.mkdirSync(dir);
+
+const tarball = execFileSync('npm', ['pack', '--silent', '--pack-destination', work], { cwd: root }).toString().trim();
+execFileSync('tar', ['-xzf', path.join(work, tarball), '-C', dir, '--strip-components=1']);
+execFileSync('npm', ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', '--silent'], { cwd: dir, stdio: 'inherit' });
+fs.copyFileSync(path.join(root, 'scripts/smithery/icon.png'), path.join(dir, 'icon.png'));
+
+// The tool list, with schemas, from the server that ships in the bundle.
+const tools = await new Promise((resolve, reject) => {
+  const child = spawn('node', [path.join(dir, 'src/cli.js'), 'mcp'], { cwd: dir, stdio: ['pipe', 'pipe', 'ignore'] });
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; });
+  child.on('close', () => {
+    const line = out.split('\n').find((l) => l.includes('"id":2'));
+    line ? resolve(JSON.parse(line).result.tools) : reject(new Error('the bundled server did not answer tools/list'));
+  });
+  child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'bundle', version: '0' } } }) + '\n');
+  child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+  child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list' }) + '\n');
+  child.stdin.end();
+});
+
+const firstSentence = (s) => s.trim().split(/(?<=[.!?])\s/)[0].slice(0, 200);
+const manifest = {
+  manifest_version: '0.3',
+  name: 'simframe',
+  display_name: 'simframe',
+  version: pkg.version,
+  description: 'Eyes, hands and memory for a coding agent driving the iOS Simulator or an Android emulator.',
+  long_description: 'simframe reads the simulator screen as a numbered text element map with tap points (accessibility tree + on-device OCR, ~20 ms warm frames instead of screenshots), runs whole tap/type/scroll/assert flows in one call with every step verified against what it did last time, and remembers screens so repeated flows need no model calls. Needs a Mac with Xcode; the first call builds a small Swift daemon from source (~15 s, once). Android emulators are driven with the same tools, without an accessibility tree.',
+  author: { name: 'Sadjad Asadi', url: 'https://github.com/lvlrSajjad' },
+  repository: { type: 'git', url: 'https://github.com/lvlrSajjad/simframe.git' },
+  homepage: 'https://lvlrsajjad.github.io/simframe/',
+  documentation: 'https://github.com/lvlrSajjad/simframe#readme',
+  support: 'https://github.com/lvlrSajjad/simframe/issues',
+  icon: 'icon.png',
+  server: { type: 'node', entry_point: 'src/cli.js', mcp_config: { command: 'node', args: ['${__dirname}/src/cli.js', 'mcp'] } },
+  tools: tools.map((t) => ({ name: t.name, description: firstSentence(t.description ?? ''), inputSchema: t.inputSchema ?? { type: 'object', properties: {} } })),
+  tools_generated: false,
+  keywords: pkg.keywords,
+  license: 'MIT',
+  compatibility: { platforms: ['darwin'], runtimes: { node: '>=18.17' } },
+};
+fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+const out = path.join(root, `simframe-${pkg.version}.mcpb`);
+fs.rmSync(out, { force: true });
+execFileSync('zip', ['-qr', out, '.', '-x', '*.DS_Store'], { cwd: dir });
+fs.rmSync(work, { recursive: true, force: true });
+console.log(`${path.relative(root, out)}: ${tools.length} tools, ${(fs.statSync(out).size / 1e6).toFixed(1)} MB`);
+console.log(`publish: npx -y @smithery/cli mcp publish ./${path.relative(root, out)} -n lvlr-xaus/simframe`);

package/src/actions.js

@@ -16,6 +16,7 @@ import * as planner from './planner.js';
 import * as metrics from './metrics.js';
 import * as screenmap from './screenmap.js';
 import { launchApp, openUrl, setPermission, terminateApp } from './platform/index.js';
+import { shellCrashed } from './device-state.js';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const MAX_PAUSE_MS = 5000;
@@ -164,6 +165,59 @@ export function normalizeStep(raw) {
   return step;
 }
 
+/**
+ * How long to keep waiting for a guest shell that has just crashed.
+ *
+ * Measured: six crashes on `326464A4`, every one of them recovered by waiting
+ * and launching again, in 5.7-7.9 s. 20 s is that with room, and it is bounded
+ * so a device that is genuinely gone still fails rather than hanging.
+ */
+export const SHELL_PATIENCE_MS = 20_000;
+
+/** How often to try again while waiting for it. */
+export const SHELL_POLL_MS = 1500;
+
+/**
+ * Launch, and survive the guest's window server dying under the attempt.
+ *
+ * `simctl` reports a SpringBoard crash as a launch failure, which is true and
+ * unhelpful: the shell is back a few seconds later and the same launch works.
+ * Until now the only remedy in the project was `simframe revive`, a ~40 s
+ * device restart — and item 173 notes that waiting and retrying "has never been
+ * tried". It was tried on 2026-09-18 and recovered 6 of 6.
+ *
+ * Deliberately narrow. Only the shell-crash signature is retried; every other
+ * device failure, including `simctl did not return within 90s`, fails on the
+ * first attempt as before, because none of them has been observed to heal and a
+ * retry on that one costs another 90 s to learn nothing.
+ *
+ * `report` is filled in rather than returned so the step can say it happened.
+ * A retry that does not show up in the summary is a rate nobody can argue with.
+ */
+export async function launchThroughShellCrash(
+  udid,
+  bundleId,
+  options,
+  report = {},
+  { launch = launchApp, wait = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now } = {},
+) {
+  const started = now();
+  for (;;) {
+    report.attempts = (report.attempts ?? 0) + 1;
+    try {
+      const out = await launch(udid, bundleId, options);
+      report.waitedMs = now() - started;
+      return out;
+    } catch (err) {
+      if (!shellCrashed(err.message) || now() - started >= SHELL_PATIENCE_MS) {
+        report.waitedMs = now() - started;
+        throw err;
+      }
+      await wait(SHELL_POLL_MS);
+    }
+  }
+}
+
 /**
  * Does this verdict mean the flow went somewhere nobody intended?
  *
@@ -740,6 +794,11 @@ export async function runScript(
         verification = await confirmNoChange(deviceQuery, verification, {
           beforeScreen, options, stableMs, timeoutMs,
         });
+        // And the same courtesy before a wrong turn throws away the rest of
+        // the batch, which is the more expensive of the two mistakes.
+        verification = await confirmWrongTurn(deviceQuery, verification, {
+          udid, prediction, beforeScreen, step, options, stableMs, timeoutMs,
+        });
         if (verification.lateArrival) {
           // The reading the verdict was taken from is now known to be stale, so
           // nothing downstream may learn a screen or an edge from it.
@@ -933,7 +992,19 @@ export async function runScript(
           // switch moving 0.1% of the screen, which is neither faculty. Saying
           // "assumed" is the honest answer; guessing a better-sounding reason
           // would be the same mistake in the other direction.
-          classified: false,
+          //
+          // **Per verdict, though, not per site.** That argument is about
+          // `no-visible-change` and does not extend to every verdict: an
+          // `unexpected-screen` means the screen after the action was not the
+          // one memory predicted, which is item 174 and nothing else.
+          // `metrics.VERDICT_FACULTY` holds the verdicts whose faculty is read,
+          // and `no-visible-change` is deliberately not one of them — so this
+          // still says "assumed" for the 162 records the reasoning above is
+          // actually about, and stops saying it for the 26 it never covered.
+          classified: Boolean(metrics.VERDICT_FACULTY[verification?.verdict]),
+          // Recorded as a field rather than left as a prefix of `detail`, which
+          // is how the breakdown had to recover it: by parsing a string.
+          verdict: verification?.verdict ?? null,
           // `verification_failed` is the largest reason class in the log and it
           // was the only one carrying no intent, which made most of the corpus
           // useless for asking what kind of decision costs us. The step knows
@@ -989,6 +1060,11 @@ export async function runScript(
       const why = metrics.reasonForStepError(step, err);
       noteEscalation({
         stepIndex: i,
+        // When the failure is the simulator rather than the code, say so. 78 of
+        // the bench device's `verification_failed` records are `simctl` failing,
+        // an app that would not launch, or capture stopping — item 173, counted
+        // towards a perception phase.
+        device: why.device ?? null,
         fingerprint: beforeScreen?.hash ?? metrics.fingerprintNow(udid, screenmap),
         reason: why.reason,
         candidates: why.candidates,
@@ -1758,6 +1834,77 @@ async function confirmNoChange(deviceQuery, verification, { beforeScreen, option
   };
 }
 
+/**
+ * What a second look at a wrong turn establishes.
+ *
+ * Pure, and separate from the read that feeds it, because the read needs a
+ * device and this needs to be provable without one. `stillOnPlan` is tested by
+ * asserting against its own source text, which is what you write when the
+ * decision cannot be reached in a test, and it checks that the code says what
+ * it says rather than that it decides what it should.
+ *
+ * The rule: a second reading that *also* says wrong turn confirms the first,
+ * and the halt stands on two reads instead of one. Any other second reading
+ * replaces it, because the first was taken of a screen that had not finished
+ * being itself. The disagreement is kept either way — it is the evidence that
+ * this gate is flaky rather than protective, and it is what a supervisor would
+ * be asked to rule on.
+ */
+export function afterSecondLook(verification, second, again) {
+  if (!second?.verdict || second.verdict === 'unexpected-screen') return verification;
+  const was = String(verification?.observed?.to ?? '').slice(0, 8);
+  const now = String(again?.hash ?? '').slice(0, 8);
+  return {
+    ...verification,
+    verdict: second.verdict,
+    detail: `${second.detail} — read again after settling, because the first read said`
+      + ` "${verification.detail}"${was && now && was !== now ? ` (${was} → ${now})` : ''}`,
+    // Both answers, so the log can count how often perception contradicts
+    // itself here rather than only how often it halted a run.
+    disagreed: { first: verification.verdict, second: second.verdict, from: was || null, to: now || null },
+    lateArrival: again,
+  };
+}
+
+/**
+ * One more look before a wrong turn is allowed to stop the batch.
+ *
+ * The sibling of `confirmNoChange`, for the same reason and against the same
+ * class of mistake: a verdict taken from a screen that was still arriving. The
+ * reported symptom is that the gate is **non-deterministic** — a reporter
+ * re-issued the identical call with no state change and it passed — and a gate
+ * that fails once and passes on retry is flaky, not protective. Asked twice,
+ * the perception disagrees with itself, and the first answer was never
+ * evidence.
+ *
+ * This keeps the verify barrier rather than softening it. The barrier asks for
+ * confirmed perception before acting on a screen an `unexpected-*` verdict has
+ * touched; a halt on one premature read is not confirmed perception either.
+ * Both directions now cost a second, settled read, and a wrong turn that is
+ * real still halts — on better evidence than before.
+ *
+ * Deliberately not gated on a supervisor being configured. The escape hatch the
+ * item proposed was a supervisor ruling, which `doctor` reports as
+ * `none — not requested` on a default install, so that fix would have reached
+ * only callers who opted in. A second read needs no model and no opt-in; a
+ * supervisor, when there is one, still gets asked about what survives it.
+ */
+async function confirmWrongTurn(deviceQuery, verification, { udid, prediction, beforeScreen, step, options, stableMs, timeoutMs }) {
+  if (verification?.verdict !== 'unexpected-screen' || !prediction || !beforeScreen?.hash) return verification;
+  await api.waitFor(deviceQuery, {
+    mode: 'settle', stableMs: 250, timeoutMs: LATE_CHANGE_MS, options,
+  }).catch(() => null);
+  const again = await api.screenIdentity(deviceQuery, { options, settleMs: stableMs, timeoutMs }).catch(() => null);
+  // Nothing looked, so nothing was established and the first answer stands.
+  // A failed read may never be read as agreement.
+  if (!again?.hash) return verification;
+  // `kind` is deliberately not passed: the transition classifier's reading
+  // belongs to the moment of the first look, and it only ever decorates an
+  // `ok`. Re-using it here would date-stamp this answer with that one.
+  const second = graph.verdict({ udid, prediction, before: beforeScreen, after: again, action: step.action });
+  return afterSecondLook(verification, second, again);
+}
+
 /**
  * A control that changed state is not a step that did nothing.
  *
@@ -2699,11 +2846,12 @@ async function runStep(deviceQuery, udid, step, ctx) {
       return `pressed key ${step.value ?? step.code}`;
     case 'launch': {
       const bundleId = step.value ?? step.bundleId;
-      const started = await launchApp(udid, bundleId, {
+      const shell = { waitedMs: 0, attempts: 0 };
+      const started = await launchThroughShellCrash(udid, bundleId, {
         args: step.args ?? [],
         env: step.env ?? {},
         terminateFirst: step.relaunch === true,
-      });
+      }, shell);
       // Item 169: simctl returning ok means the process started, not that the
       // app came forward, and the two came apart repeatedly on a loaded
       // runner — leaving the device on the previous app under a step that
@@ -2743,6 +2891,10 @@ async function runStep(deviceQuery, udid, step, ctx) {
       if (ctx.landing) ctx.landing.verdict = landed.verdict;
       return `launched ${bundleId}${step.relaunch ? ' (relaunched)' : ''}`
         + (landed.verdict === 'fronted' ? ` (frontmost after ${landed.ms}ms)` : '')
+        + (shell.attempts > 1
+          ? ` [the guest's SpringBoard crashed and came back; launched again after ${shell.waitedMs}ms`
+            + `, on attempt ${shell.attempts}]`
+          : '')
         + (retried
           ? ` [it did not front on the first attempt — ${frontmost.describeHeld(retried.held, started.pid)}`
             + `; a second launch fronted it. The launch is unreliable on this host.]`
@@ -2856,6 +3008,30 @@ async function runStep(deviceQuery, udid, step, ctx) {
       // `direction` still wins, for a caller who knows better.
       const asked = step.direction ? String(step.direction).toLowerCase() : null;
       const max = Math.min(MAX_SCROLLS, step.maxScrolls ?? 6);
+      // **The screen's size, in scope.** It was not, and that single omission is
+      // the whole of item 190 and of the field report's Defect 2.
+      //
+      // `points` existed only inside `offsetSays`'s own destructure, so every
+      // other reference to it — `inViewport`, and the message that reports a
+      // target as out of view — was an undeclared identifier. `inViewport` runs
+      // on **every successful locate**, so the moment this step found what it
+      // was looking for it threw `ReferenceError: points is not defined`, the
+      // loop's own `catch` swallowed it as "not found", and it scrolled on until
+      // the budget ran out and it reported the target unreachable.
+      //
+      // So `scrollTo` could fail on a target that was on screen, could fail
+      // after a scroll that had just brought the target into view, and could
+      // burn its whole budget doing it — all three of the reported symptoms,
+      // and all three are this. Measured from the loop, i is the iteration:
+      //
+      //   i=0 locate threw: "Developer" is not on this screen   (true, it was above)
+      //   i=1 locate threw: points is not defined               (it had FOUND it)
+      //   i=2 locate threw: points is not defined               (again)
+      //
+      // Optional chaining does not help: `points?.width` on an undeclared name
+      // is still a ReferenceError, which is why nothing caught this by reading.
+      const geo = await ctx.screen();
+      const points = { width: geo.pointWidth, height: geo.pointHeight };
       let dir = asked ?? 'down';
       let reversed = false;
       // Where the target is, when the tree knows. `null` means no evidence, and
@@ -2863,18 +3039,40 @@ async function runStep(deviceQuery, udid, step, ctx) {
       // the top of a web page, which **triggers pull-to-refresh**, reloads the
       // page and changes the screen hash — defeating the end-detection below
       // and reading, from outside, as an endless loop. Observed live.
-      const offsetSays = async () => {
-        if (asked) return asked;
+      //
+      // **And it answers `null` far more often than this was written for.**
+      // Measured on 2026-09-18, which is item 190: iOS puts only the *visible*
+      // rows of a table in the accessibility tree. A scrolled-away row is not
+      // there with an out-of-bounds coordinate — it is absent.
+      //
+      //   Settings at the top,    resolve("Developer")     -> status=none, y=undefined
+      //   Settings at the bottom, resolve("Accessibility")  -> status=none, y=undefined
+      //
+      // Zero elements whose label even contains the query, both times. So on a
+      // native list this returns `null` in precisely the case it exists to
+      // answer, and the y<0 / y>height reasoning below only ever fires on the
+      // frameworks that do keep off-screen rows in the tree — React Native, and
+      // the `y = -693` case this was written for.
+      // One read answers both questions, so asking them costs what asking one
+      // used to: which way is the target, and what is on screen right now.
+      const lookAround = async () => {
         try {
-          const { entry, points } = await api.readScreenWith(deviceQuery, { useOcr: false, options: ctx.options });
-          const hit = matching.resolve(entry.targets ?? [], String(query));
+          const { entry } = await api.readScreenWith(deviceQuery, { useOcr: false, options: ctx.options });
+          const targets = entry.targets ?? [];
+          // What is visible, as one comparable string. This is the end detector
+          // now, and the frame hash is not — see `scrolledNowhere`.
+          const signature = targets.map((t) => String(t.label ?? '')).filter(Boolean).sort().join('\u0000');
+          if (asked) return { says: asked, signature };
+          const hit = matching.resolve(targets, String(query));
           const y = hit?.target?.y;
-          if (!Number.isFinite(y)) return null;
-          if (y < 0) return 'up';
-          if (y > (points?.height ?? Infinity)) return 'down';
-          return dir;
+          let says = null;
+          if (!Number.isFinite(y)) says = null;
+          else if (y < 0) says = 'up';
+          else if (y > (points?.height ?? Infinity)) says = 'down';
+          else says = dir;
+          return { says, signature };
         } catch {
-          return null;
+          return { says: asked ?? null, signature: null };
         }
       };
       /**
@@ -2907,25 +3105,57 @@ async function runStep(deviceQuery, udid, step, ctx) {
       // rather than the act — reported as "after 1 scroll down" on a request
       // for "up".
       const scrolled = [];
+      const arrivedHow = () => (scrolled.length
+        ? ` after ${scrolled.length} scroll${scrolled.length === 1 ? '' : 's'} `
+          + (new Set(scrolled).size === 1 ? scrolled[0] : scrolled.join(' then '))
+        : ' already');
+      /**
+       * Is it here now? Asked without throwing, so a give-up path can use it.
+       *
+       * **A frame hash is a whole-screen measure and a strip is a small part of
+       * the screen**, so "the frame did not change" is not "nothing moved".
+       * Reported from the field: a horizontally-scrolling tab strip had the
+       * target scrolled into view — the visible tabs demonstrably changed — and
+       * this step reported `not reachable by scrolling` anyway, because the
+       * whole-frame hash barely moved. A confident wrong *failure* after the
+       * action succeeded, which costs what a silent success costs: the caller
+       * is handed a false fact and a round trip.
+       *
+       * Same principle as the recall path (DEFERRED 184): a miss may not be the
+       * final word until something has looked.
+       */
+      const nowInView = async () => {
+        try {
+          const found = await api.locate(deviceQuery, query, { index: step.index, refresh: true });
+          return inViewport(found.target) ? found : null;
+        } catch {
+          return null;
+        }
+      };
+      // What the last look actually established, so the give-up message can say
+      // what it knows instead of guessing. `absent` means the resolver did not
+      // find it; `off-view` means it did and the target sits outside the
+      // viewport — and in that case claiming it may not be in the tree is
+      // flatly contradicted by the tree we just read.
+      let lastMiss = null;
       for (let i = 0; i <= max; i += 1) {
         try {
           const found = await api.locate(deviceQuery, query, { index: step.index, refresh: i > 0 });
-          if (!inViewport(found.target)) throw new Error(
-            `"${query}" is in the tree but not in view (at ${found.target.x},${found.target.y}`
-            + ` on a ${Math.round(points?.width ?? 0)}x${Math.round(points?.height ?? 0)}pt screen)`);
-          const how = scrolled.length
-            ? ` after ${scrolled.length} scroll${scrolled.length === 1 ? '' : 's'} `
-              + (new Set(scrolled).size === 1 ? scrolled[0] : scrolled.join(' then '))
-            : ' already';
-          return `"${found.target.label ?? query}" is in view at ${found.target.x},${found.target.y}${how}`;
+          if (!inViewport(found.target)) {
+            lastMiss = 'off-view';
+            throw new Error(
+              `"${query}" is in the tree but not in view (at ${found.target.x},${found.target.y}`
+              + ` on a ${Math.round(points?.width ?? 0)}x${Math.round(points?.height ?? 0)}pt screen)`);
+          }
+          return `"${found.target.label ?? query}" is in view at ${found.target.x},${found.target.y}${arrivedHow()}`;
         } catch (err) {
+          if (lastMiss !== 'off-view') lastMiss = 'absent';
           if (i === max) {
             throw new Error(`scrolled ${dir} ${max}x without finding ${query}: ${err.message}`);
           }
         }
-        const evidence = await offsetSays();
+        const { says: evidence, signature: wasShowing } = await lookAround();
         if (evidence) dir = evidence;
-        const wasAt = await hashNow(deviceQuery, ctx.options);
         scrolled.push(dir);
         await runStep(deviceQuery, udid, { action: 'scroll', value: dir }, ctx);
         // A scroll either moves immediately or not at all, so it does not need a
@@ -2939,17 +3169,64 @@ async function runStep(deviceQuery, udid, step, ctx) {
         // page"*. Reverse once — the target may be behind us, and on a page
         // whose fields never enter the tree there is no offset to follow — then
         // stop rather than thrash.
-        const nowAt = await hashNow(deviceQuery, ctx.options);
-        if (wasAt && nowAt && wasAt === nowAt) {
-          // Reverse only on evidence. Without it we do not know the target is
-          // behind us, and scrolling blindly the other way is how a web page
-          // gets pulled to refresh.
-          if (reversed || !evidence) {
+        // **What "it stopped moving" is measured on, and the frame hash was the
+        // wrong thing.** At the end of a list iOS rubber-bands: the content does
+        // not advance and the pixels do, so a whole-frame comparison answers
+        // "yes, it moved" on every attempt and the end is never detected. Seen
+        // on 2026-09-18 — `scrolled down 6x without finding Accessibility` on a
+        // list that had been against its bottom stop the whole time, 21.5s for
+        // nothing.
+        //
+        // The visible labels do not bounce. If the same rows are on screen after
+        // a scroll as before it, the scroll achieved nothing, whatever the
+        // framebuffer did.
+        const { signature: nowShowing } = await lookAround();
+        if (wasShowing && nowShowing && wasShowing === nowShowing) {
+          // Before believing the hash, look. See `nowInView` — an unchanged
+          // whole-frame hash is weak evidence about a strip, and this step has
+          // reported failure on a scroll that worked.
+          const arrived = await nowInView();
+          if (arrived) {
+            return `"${arrived.target.label ?? query}" is in view at ${arrived.target.x},${arrived.target.y}`
+              + `${arrivedHow()} (the frame hash did not register the scroll — looked again rather than`
+              + ' reporting a failure the screen contradicts)';
+          }
+          // **A stall is evidence, and treating it as none is item 190.**
+          //
+          // This used to reverse only when the *tree* said where the target
+          // was — and on a native list the tree never does, because scrolled-
+          // away rows are not in it. So the common case was: no evidence, the
+          // default direction, and if that direction happened to be the wrong
+          // one the step burned its budget moving away from the target and then
+          // refused, having never looked the other way. Field-measured at 12.6s
+          // and 18.4s for zero progress, the largest single latency cost in
+          // that round.
+          //
+          // Having scrolled and moved nothing, we know this direction is
+          // exhausted. That is a fact about the screen rather than a guess, and
+          // it is a different claim from the one the rule above was protecting
+          // against: the danger there was *opening* with an unfounded "up",
+          // which walks a web page to the top and pulls it to refresh. Here we
+          // are at one end and the only place left to look is the other. Still
+          // exactly once, still bounded by `max`.
+          if (reversed) {
             throw new Error(
-              `${query} is not reachable by scrolling: ${dir} stopped moving after ${i + 1} attempt(s)`
-              + (evidence ? ' and so did the other way.' : ' and the tree does not say where it is,'
-                + ' so there is no direction to try.')
-              + ' It may not be in the accessibility tree at all — read the screen, or aim at a coordinate.',
+              // Both ways, always — this branch is now only reached after a
+              // reversal, so "there is no direction to try" (which it used to
+              // say when the tree was silent) is no longer true and would be
+              // the same kind of unchecked assertion as the sentence below it.
+              `${query} is not reachable by scrolling: it stopped moving both ways`
+              + ` (${scrolled.join(', ')}) after ${i + 1} attempt(s).`
+              // Say what was established, not what would be convenient. This
+              // used to assert "It may not be in the accessibility tree at all"
+              // in every case — a claim the function never checks, and one the
+              // `off-view` branch has already disproved by reading the element
+              // out of the tree a line earlier.
+              + (lastMiss === 'off-view'
+                ? ' It IS in the tree and outside the viewport, so this is a scrolling problem'
+                  + ' rather than a perception one — try a different container, or aim at a coordinate.'
+                : ' The resolver did not find it here either, so it may not be on this screen at all —'
+                  + ' read the screen (sim_ui), or aim at a coordinate.'),
             );
           }
           reversed = true;