simframe 0.17.0 → 0.19.0

package/src/cli.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { runDaemon, DEFAULTS } from './daemon.js';
-import { bootedDevices, capabilitiesFor, listDevices, PLATFORMS, resolveDevice, restartDevice, screenshot, toolchainChecks } from './platform/index.js';
+import { bootedDevices, capabilitiesFor, listDevices, PLATFORMS, resolveDevice, screenshot, toolchainChecks } from './platform/index.js';
 import * as actions from './actions.js';
 import * as analyze from './analyze.js';
 import * as api from './index.js';
@@ -11,11 +11,15 @@ import * as input from './input.js';
 import * as baseline from './baseline.js';
 import * as metrics from './metrics.js';
 import * as navigate from './navigate.js';
+import * as wedge from './wedge.js';
+
 import { decodePng } from './png.js';
 import * as storage from './storage.js';
 import * as store from './store.js';
 import * as view from './view.js';
 
+
+
 const USAGE = `simframe — always-warm iOS Simulator frames
 
   simframe mcp                       run the MCP server on stdio (for agents)
@@ -51,6 +55,7 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe escalations [device]      why simframe handed decisions back, by reason
   simframe supervisions [device]     local supervisor rulings, and what came of each
   simframe revive [device]           power-cycle a wedged device: stop, shutdown, boot, start, reset input
+  simframe diagnose [device]         what this device is doing right now, and which failure it is
                                      (--session=<id> narrows to one agent; the
                                      ids are listed in the output. SIMFRAME_SESSION
                                      names one, but only at process start — an
@@ -419,31 +424,67 @@ async function main() {
     case 'revive': {
       const dev = await resolveDevice(device);
       const say = (line) => { if (!flags.json) console.log(line); };
-      const steps = [];
-      const did = async (what, fn) => {
-        try { await fn(); steps.push({ step: what, ok: true }); say(`  ok   ${what}`); } catch (err) {
-          steps.push({ step: what, ok: false, error: err.message });
-          say(`  ..   ${what} — ${err.message.split('\n')[0]}`);
-        }
-      };
       say(`reviving ${dev.name}`);
-      // Forced: the point of this command is that the device is wedged, so
-      // something is certainly still holding it.
-      await did('stopped the daemon', async () => { api.stopDaemon(dev.udid, { force: true }); });
-      // Through the boundary, which is the whole point of the boundary: the
-      // first version of this shelled out to `xcrun` from here and the test
-      // that forbids it failed immediately, correctly.
-      await did('restarted the device, and waited for the boot to finish',
-        () => restartDevice(dev.udid));
-      await did('started capture', () => api.ensureDaemon(dev.udid));
-      await did('rebuilt the HID session', () => input.resetSession(dev.udid));
-      const health = await api.getState(dev.udid).then((s) => s?.state ?? null).catch(() => null);
-      const alive = Boolean(health?.hash);
-      emit(flags, { ok: alive, device: dev.udid, steps }, alive
-        ? `\n${dev.name} is producing frames again`
-        : `\n${dev.name} is still not producing frames. This is past what simframe can do —`
-          + ' check Simulator.app is not showing an error, and see docs/DEFERRED.md item 95.');
-      if (!alive) process.exitCode = 1;
+      // The sequence itself lives in `wedge.js`, because `bench-hpi` needs the
+      // same recovery between passes and a second copy of it here is how this
+      // project has repeatedly ended up fixing one symptom in three places.
+      const revived = await wedge.revive(dev.udid, {
+        options,
+        device: dev,
+        onStep: ({ step, ok, error }) => say(ok ? `  ok   ${step}` : `  ..   ${step} — ${String(error).split('\n')[0]}`),
+      });
+      const { steps } = revived;
+      const diag = { verdict: revived.verdict };
+      const state = diag?.verdict?.state ?? 'read-failed';
+      const usable = !wedge.UNUSABLE.has(state);
+      const degraded = usable && state !== 'healthy';
+      emit(flags, { ok: usable, device: dev.udid, steps, verdict: diag?.verdict ?? null }, usable
+        ? (degraded
+          ? `\n${dev.name} is back and usable, but ${state}:\n  ${diag.verdict.detail}`
+            + '\nNot a failure — it taps and reads.'
+          : `\n${dev.name} is healthy again — ${diag.verdict.detail}`)
+        : `\n${dev.name} came back ${state}, which is not usable.`
+          + `\n  ${diag?.verdict?.detail ?? 'nothing could be read from it'}`
+          + '\nA second revive sometimes clears it. If it does not, this is past what simframe'
+          + ' can do — check Simulator.app is not showing an error, and see docs/DEFERRED.md'
+          + ' items 95 and 183.');
+      if (!usable) process.exitCode = 1;
+      return;
+    }
+
+    // Not folded into `doctor`, which answers "can this machine capture". This
+    // answers "what is this device doing right now", which is item 173's
+    // question and has never had an instrument.
+    case 'diagnose': {
+      const dev = await resolveDevice(device);
+      const r = await wedge.diagnose(dev.udid, { options });
+      emit(flags, r, [
+        `${r.device.name} — ${r.verdict.state}`,
+        `  ${r.verdict.detail}`,
+        '',
+        `  frame      seq ${r.frame?.seq ?? '-'}, ${r.frame?.ageMs ?? '-'}ms old, still for ${r.frame?.stableForMs ?? '-'}ms, ${r.frame?.size ?? '-'}`,
+        `  elements   ${r.elements.total} total — ${r.elements.ax} by tree, ${r.elements.ocr} by OCR, ${r.elements.fused} by both`,
+        // **No band here, and that is the second version of this fix.**
+        //
+        // A reporter saw `healthy` printed beside "measured healthy 0.66-0.93"
+        // over a reading of 0.567 and asked, reasonably, which to believe. The
+        // first fix widened the band to 0.57-0.93 — and the very next device
+        // read returned **0.471** on an ordinary Settings screen, which is the
+        // same contradiction one decimal place down. Any fixed band will be
+        // contradicted by the next screen, because fusion tracks how much of a
+        // screen's content is OCR-only and that is a property of the app.
+        //
+        // So the line prints the number and the one threshold the verdict
+        // actually turns on. The observed range lives in `docs/BENCHMARKS.md`,
+        // where it is evidence about screens rather than a standard a device is
+        // being held to. `HEALTHY_FUSION` is still printed by the `stale-frame`
+        // verdict, where a reading of 0.03 genuinely wants the contrast.
+        `  fusion     ${r.agreement ?? 'n/a'} of elements seen by both sensors`
+          + ` — stale at or below ${wedge.DISAGREEMENT}, which is what this verdict turns on`,
+        `  frontmost  ${r.frontmost?.pid ?? 'unknown'}${r.frontmost?.title ? ` (${r.frontmost.title})` : ''}`,
+        ...(r.verdict.revive ? ['', '  `simframe revive` is the recovery. Keep this output — item 173 needs it.'] : []),
+      ]);
+      if (r.verdict.revive) process.exitCode = 1;
       return;
     }
 
@@ -1253,8 +1294,14 @@ async function main() {
         'flow                      runs  agent p50   human p50   HPI_time  step_ratio  turns  esc',
         ...report.flows.map((f) => metrics.flowRow(f, { wide: true })),
         '',
-        `HPI_accuracy ${report.overall.hpi_accuracy} (${report.overall.runs} runs, ` +
+        `HPI_accuracy ${report.overall.hpi_accuracy} (${report.overall.runs} measurable run(s), ` +
           `${report.overall.runs - runs.filter((r) => r.completed && !r.wrong_action_taken).length} not clean)`,
+        // A denominator that quietly shrinks is worse than one that is wrong.
+        report.overall.runs_lost_to_device
+          ? `  ${report.overall.runs_lost_to_device} further run(s) left the denominator because the DEVICE failed,`
+            + ' not the code — those are unmeasured, not inaccurate (item 173):'
+            + `\n${(report.overall.device_causes ?? []).map((c) => `    ${c}`).join('\n')}`
+          : null,
         report.overall.hpi_time == null
           ? `HPI_time and HPI need a human baseline — none of ${report.overall.flows_measured} measured flow(s) has one yet.`
           : `HPI_time ${report.overall.hpi_time} (harmonic mean over ${report.overall.flows_with_human_baseline} flow(s)), HPI ${report.overall.hpi}`,
@@ -1265,7 +1312,10 @@ async function main() {
         `steps per model call ${report.overall.steps_per_call ?? '—'}`
           + (report.overall.steps_per_call
             ? ` — about ${(((20000 + 1700 * report.overall.steps_per_call) / report.overall.steps_per_call) / 1000).toFixed(1)}s`
-              + ' per step end to end, of which simframe is ~1.7s. Raise this, not the engine.'
+              + ' per step end to end. Raise this, not the engine — but note the ~1.7s'
+              + ' figure for simframe\'s own work is WARM taps inside a batch: a cold app'
+              + ' launch is a large one-off on top, and it dominates short flows'
+              + ' (measured: 6.2s/step over 2 steps with no model at all).'
             : ''),
         flags.out ? `wrote ${flags.out}` : null,
       ]);
@@ -1354,13 +1404,45 @@ async function main() {
             if (read > 0) {
               verdict = named + (read < n ? ` (on the ${read} of ${n} whose reason was read)` : '');
             } else if (assumed > 0) {
-              verdict = 'reason assumed, not read — no faculty can be named from these';
+              // For `verification_failed` this line used to end the story, and
+              // it is no longer the whole truth: the verdict split below names
+              // a faculty for some of them and takes the device's own failures
+              // out altogether.
+              verdict = r === 'verification_failed' && (b.verdicts?.length || b.device_total)
+                ? 'reason too coarse to steer by — see the verdict split below'
+                : 'reason assumed, not read — no faculty can be named from these';
             } else {
               // Neither read nor assumed: the log predates the distinction.
-              verdict = `${named} — but these records predate the check, so treat it as untested`;
+              verdict = `${named} — but these records predate the check, so treat it as untested`
+                + ' (legacy, not assumed)';
             }
             return `  ${r.padEnd(20)} ${String(n).padStart(4)}   ${verdict}`;
           }),
+        // The two things the reason alone could not say.
+        //
+        // Both exist because the per-reason table above was the steering wheel
+        // and it pointed at one faculty for a class holding three, and counted
+        // the simulator's own failures towards a perception phase.
+        b.verdicts?.length ? '' : null,
+        b.verdicts?.length
+          ? 'verification_failed, split by the verdict that fired'
+            + (b.derived?.verdicts
+              ? ` (${b.derived.verdicts} of ${b.verdicts.reduce((a, v) => a + v.count, 0)} derived from the detail text, not recorded at the time):`
+              : ':')
+          : null,
+        ...(b.verdicts ?? []).slice(0, 8).map((v) => {
+          const faculty = metrics.VERDICT_FACULTY[v.name];
+          return `  ${v.name.padEnd(20)} ${String(v.count).padStart(4)}   `
+            + (faculty
+              ? `points at: ${faculty}`
+              : 'no faculty follows from this verdict alone — see metrics.VERDICT_FACULTY');
+        }),
+        b.device_total ? '' : null,
+        b.device_total
+          ? `${b.device_total} escalation(s) were the DEVICE, not the code — item 173, and not evidence for any faculty`
+            + `${b.derived?.device ? ` (${b.derived.device} derived from the detail text)` : ''}:`
+          : null,
+        ...(b.device ?? []).slice(0, 6).map((d) => `  ${String(d.count).padStart(4)}  ${d.name}`),
         b.total ? '' : null,
         b.total ? `avoidable ${b.avoidable}/${b.total} (${b.avoidable_escalation_rate})` : null,
         // Said out loud rather than left for someone to discover: the rate is

package/src/device-state.js

@@ -0,0 +1,101 @@
+// Is a failure the device's fault or the code's?
+//
+// Moved out of `scripts/` on 2026-09-17 so `src/metrics.js` can use it. The
+// escalation log needed it: 78 of the `verification_failed` records on the
+// bench device are `xcrun simctl openurl` failing, an app that would not
+// launch, or capture stopping — the device, filed under a code faculty and
+// reported as evidence for "sense of time (Phase 11)". A steering wheel that
+// counts item 173's own occurrences as a perception problem points somewhere
+// nobody chose.
+//
+// Deliberately dependency-free. `wedge.js` imports `index.js`, and `metrics.js`
+// is imported *by* `index.js`, so a shared table living in either would close a
+// cycle. This module imports nothing and is imported by both.
+
+/** 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)',
+  ],
+  // simctl itself stopped answering, and said so in simframe's own words: the
+  // process was killed at the timeout rather than refusing the request.
+  //
+  // Three runs of the 2026-09-17 bench died this way — 95.6 s each — and every
+  // one of them was written to `flows.jsonl` with `device_cause: null`, so the
+  // number CI gates on counted a simulator that had stopped answering as the
+  // code getting things wrong. That is the same fault item 173 recorded as
+  // fixed, still open for this signature because nothing here matched it.
+  [
+    /did not return within \d+s \(killed by simframe/i,
+    'simctl stopped answering and had to be killed at the timeout',
+  ],
+  // 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;
+}
+
+/**
+ * The one device failure that is known to heal by itself.
+ *
+ * The guest's window server dies, the launch that was in flight fails, and
+ * SpringBoard comes back a few seconds later. Item 173 spent a dozen
+ * occurrences unable to observe it for exactly that reason — by the time
+ * anything looked, `diagnose` said `healthy`, fusion 0.857.
+ *
+ * Measured on `326464A4` on 2026-09-18, six occurrences in one run: waiting and
+ * launching again recovered **6 of 6**, in 5.7-7.9 s (median ~6.3 s). The
+ * remedy in use until now was `simframe revive`, a ~40 s device restart — six
+ * times the cost, for a fault that was already over.
+ *
+ * Separate from `deviceCause` on purpose. Every entry there says "this is the
+ * device"; this one says "and it will be back". `simctl did not return within
+ * 90s` is the device too and is deliberately NOT here: it was never once
+ * observed to recover, and a retry costs another 90 s to find that out.
+ */
+export const SHELL_CRASH = /system shell \(SpringBoard[^)]*\) probably crashed/i;
+
+/** Did this failure come from the guest shell dying under us? */
+export function shellCrashed(text) {
+  return SHELL_CRASH.test(String(text ?? ''));
+}

package/src/index.js

@@ -1397,22 +1397,76 @@ export async function getFrameAt(deviceQuery, { msAgo = 0, options } = {}) {
  * Wait, briefly, for a frame that is holding still. Returns whatever the newest
  * frame is once the screen settles or the budget runs out, saying which.
  */
-export async function settledState(udid, { settleMs = MEMORY_SETTLE_MS, timeoutMs = 1500 } = {}) {
+/**
+ * When the stillness a state reports began, or null when that cannot be told.
+ *
+ * `stableForMs` is measured as of the frame's capture, so the quiet period
+ * started `stableForMs` before `capturedAt`. Exported because the rule built on
+ * it below is the interesting part and deserves to be testable without a device.
+ */
+export function stillnessBegan(state) {
+  if (!Number.isFinite(state?.capturedAt) || !Number.isFinite(state?.stableForMs)) return null;
+  return state.capturedAt - state.stableForMs;
+}
+
+/**
+ * Has this screen been still *since we acted*, or was it still before we did?
+ *
+ * The distinction the settle detector was missing. It answers "how long has the
+ * screen been quiet" honestly and has no idea that the quiet it is describing
+ * belongs to the screen the caller has just left.
+ *
+ * Only a stillness we can **prove** predates the action is rejected. When the
+ * timestamps are missing this returns true, which is the previous behaviour —
+ * this may only ever add refusals it can demonstrate, never turn an unknown
+ * into a wait.
+ */
+export function stillSinceActing(state, actedAt) {
+  if (!Number.isFinite(actedAt)) return true;
+  const began = stillnessBegan(state);
+  if (began == null) return true;
+  return began >= actedAt;
+}
+
+export async function settledState(udid, { settleMs = MEMORY_SETTLE_MS, timeoutMs = 1500, since } = {}) {
   const p = store.paths(udid);
   const deadline = Date.now() + timeoutMs;
+  // What we are settling *after*. A caller that knows may say; otherwise it is
+  // the last launch, openUrl or gesture this device was given.
+  const actedAt = since ?? store.lastActionAt(udid);
   let state = store.readJson(p.state);
+  let stale = false;
   while (Date.now() < deadline) {
     state = store.readJson(p.state) ?? state;
-    // The daemon runs a real settle detector that can tell a spinner from a
-    // still screen. Prefer it; the duration check is the fallback for the
-    // simctl engine, which has no such thing.
-    if (state?.settled === true) return { state, settled: true };
-    if (state && state.settled === undefined && state.stableForMs >= settleMs) {
-      return { state, settled: true };
+    // **Stillness from before the action is not settlement.** Measured on the
+    // bench device: 283ms after a Settings launch the state said `settled` with
+    // `stableForMs: 4427` over a screen holding **zero** elements, which filled
+    // 2.3 seconds later; 408ms after `tap General` it said `settled` with
+    // `stableForMs: 7753` over the 23 elements of Settings root. Both readings
+    // were honest about the number and wrong about the screen.
+    //
+    // Field-reported independently as the highest-priority class here: a read
+    // that returns chrome with the content missing and no loading marker is
+    // indistinguishable from a screen that is genuinely empty, so an agent
+    // reports "this filter returns zero results" and means it.
+    const fresh = stillSinceActing(state, actedAt);
+    if (!fresh) stale = true;
+    else {
+      // The daemon runs a real settle detector that can tell a spinner from a
+      // still screen. Prefer it; the duration check is the fallback for the
+      // simctl engine, which has no such thing.
+      if (state?.settled === true) return { state, settled: true, waitedForAction: stale };
+      if (state && state.settled === undefined && state.stableForMs >= settleMs) {
+        return { state, settled: true, waitedForAction: stale };
+      }
     }
     await sleep(40);
   }
-  return { state, settled: false };
+  // `settled: false` is not a failure and never was — callers use the state and
+  // decline to persist a map built from it. What is new is that this can now be
+  // false because the screen has not been seen to move since the action, which
+  // is a different and more honest reason than "it is still moving".
+  return { state, settled: false, ...(stale ? { stillnessPredatesAction: true } : {}) };
 }
 
 /**
@@ -1459,6 +1513,33 @@ export function offScreenMatch(targets, query, points) {
   return hit.status === 'ambiguous' && hit.alternatives?.length ? hit.alternatives[0] : null;
 }
 
+/**
+ * Which way a target is outside the viewport, and by which measure.
+ *
+ * `offViewport` has checked both axes since it was written; the sentence
+ * reporting it only ever named `y` and the screen *height*. So a tab in a
+ * horizontally-scrolling strip was reported as *"it is at y=143 on a 874pt
+ * screen"* — a coordinate plainly inside the screen, next to a conclusion that
+ * it is not in view, with four of its siblings visible. Field-reported, and the
+ * reporter's summary is the right one: the honest half was right and only the
+ * axis was wrong.
+ *
+ * Vertical is checked first because it is overwhelmingly the common case, and
+ * because `scrollTo` reasons vertically — a caller told "below the fold" and a
+ * caller told "past the right edge" do different things next, which is the
+ * whole reason to say which.
+ */
+export function offScreenAxis(target, points) {
+  const { width, height } = points ?? {};
+  if (Number.isFinite(height) && (target.y < 0 || target.y > height)) {
+    return { axis: 'y', at: Math.round(target.y), extent: Math.round(height), edge: target.y < 0 ? 'above' : 'below' };
+  }
+  if (Number.isFinite(width) && (target.x < 0 || target.x > width)) {
+    return { axis: 'x', at: Math.round(target.x), extent: Math.round(width), edge: target.x < 0 ? 'left of' : 'right of' };
+  }
+  return null;
+}
+
 /**
  * Which sensors a read asks for by default.
  *
@@ -1500,9 +1581,52 @@ export function sensorMode(options) {
  */
 const nameFor = (t) => t.label || t.identifier || null;
 
+/**
+ * Did screen memory alone produce this miss?
+ *
+ * A recall that finds the screen and not the target tags `ambiguous_intent`
+ * without `ambiguous` — "I know this screen, and what you asked for is not on
+ * it". That is the only miss worth re-asking, because it is the only one whose
+ * answer came from a file rather than from the device. A miss off a map that
+ * was just built has already read both sensors, and a genuine ambiguity is not
+ * settled by reading again.
+ */
+export function memoryMiss(err) {
+  const why = metrics.escalationOf(err);
+  return Boolean(why && why.reason === 'ambiguous_intent' && !why.ambiguous);
+}
+
 export async function locate(deviceQuery, query, opts = {}) {
   if (sensorMode(opts.options) !== 'ax-first' || opts.useOcr === false || opts.escalated) {
-    return locateWith(deviceQuery, query, opts);
+    if (opts.refresh || opts.escalated) return locateWith(deviceQuery, query, opts);
+    try {
+      return await locateWith(deviceQuery, query, opts);
+    } catch (err) {
+      // **Memory may confirm, never deny.** Measured on the bench device, 8 of
+      // 8 and 4 of 4 in two separate runs: at the instant a flow's next step
+      // asks, a recall says "not on this screen" in 25 ms and a fresh read
+      // finds the target 1.8 s later, on the same device, without anything
+      // touching it in between.
+      //
+      // Why the recall is wrong, and it is not staleness in the usual sense:
+      // the frame it keys on was captured 47-124 ms *after* the tap — the first
+      // frame of the push animation, which still looks like the screen being
+      // left. Capture is damage-driven, so that frame then goes still,
+      // `settledState` calls it settled at 500-700 ms of stillness, and
+      // `recallNearest` — deliberately tolerant, because a list with new rows is
+      // still the same screen — matches it back to the previous screen and
+      // answers out of that screen's stored element list. The screen itself
+      // arrives about 750 ms later.
+      //
+      // The cost is paid only on a miss, which today aborts the batch and buys
+      // a ~20 s model round trip. 1.8 s to be sure is the cheaper mistake. The
+      // hit path — the one the speed argument rests on — is untouched.
+      //
+      // This recovery already existed for `ax-first` (below) and had never run
+      // in the default sensor mode, which is `full`.
+      if (!memoryMiss(err)) throw err;
+      return locateWith(deviceQuery, query, { ...opts, refresh: true, escalated: true });
+    }
   }
   const options = opts;
   try {
@@ -1723,8 +1847,12 @@ async function locateWith(
     if (offScreen) {
       throw metrics.tag(
         new Error(
-          `"${query}" is in the tree but not in view — it is at y=${Math.round(offScreen.y)}`
-          + ` on a ${Math.round(points.height)}pt screen. Scroll to it (sim_scroll_to) rather than waiting;`
+          `"${query}" is in the tree but not in view — ${(() => {
+            const off = offScreenAxis(offScreen, points);
+            if (!off) return `it is at ${Math.round(offScreen.x)},${Math.round(offScreen.y)}`;
+            return `it is ${off.edge} the viewport, at ${off.axis}=${off.at}`
+              + ` on a ${off.extent}pt ${off.axis === 'y' ? 'tall' : 'wide'} screen`;
+          })()}. Scroll to it (sim_scroll_to) rather than waiting;`
           + ' waiting cannot bring it into view.',
         ),
         from === 'memory' ? 'ambiguous_intent' : 'unknown_screen',