simframe 0.18.0 → 0.19.1

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.
@@ -880,6 +939,10 @@ export async function runScript(
         action: step.action,
         verification,
         ok: true,
+        // Either sensor saying nothing moved, and no state change explaining
+        // it. The verdict alone missed the case where only the settle
+        // detector saw it: `ok … [no visible change] (never settled)`.
+        unconfirmed: wentNowhere,
         ms: Date.now() - stepStart,
         detail: `${detail}${note}${wrongTurn ? ` [${verification.verdict}: ${verification.detail}]` : ''}`,
         settled,
@@ -1775,6 +1838,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.
  *
@@ -2716,11 +2850,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
@@ -2760,6 +2895,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.]`
@@ -2873,25 +3012,74 @@ 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;
+      // Whether any scroll in this step changed what was showing. A step whose
+      // every scroll moved nothing is not evidence about the target at all.
+      let movedOnce = false;
       // Where the target is, when the tree knows. `null` means no evidence, and
       // that distinction is load bearing: guessing "up" without it scrolls to
       // 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 };
         }
       };
       /**
@@ -2924,25 +3112,62 @@ 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();
-        if (evidence) dir = evidence;
-        const wasAt = await hashNow(deviceQuery, ctx.options);
+        const { says: evidence, signature: wasShowing } = await lookAround();
+        // Not after a reversal. The stall that caused it is a measurement that
+        // this direction is exhausted, and letting the tree's hint overrule it
+        // sent the step back the way it had just failed — reported on 0.19.0 as
+        // `it stopped moving both ways (down, down)`, a message naming two
+        // attempts in one direction and claiming both.
+        if (evidence && !reversed) dir = evidence;
         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
@@ -2956,17 +3181,71 @@ 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) movedOnce = true;
+        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`
+              + (new Set(scrolled).size > 1 ? ' both ways' : ` scrolling ${scrolled[0]}`)
+              + ` (${scrolled.join(', ')}) after ${i + 1} attempt(s).`
+              // Reported on 0.19.0: a React Native ScrollView that a plain swipe
+              // from another tool scrolled at once, and that none of these moved.
+              + (movedOnce ? '' : ' No scroll moved the screen at all, so this says nothing about'
+                + ' where the target is — if this view does scroll, the gesture is not reaching it'
+                + ' (try sim_do with a swipe that starts inside the list, or check input with sim_state).')
+              // 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;
@@ -3337,6 +3616,25 @@ export function settleEvidence(w) {
     + (m ? `\n${m.map}` : '');
 }
 
+/**
+ * The mark a step result is printed under: `ok  `, `WARN` or `FAIL`.
+ *
+ * `ok` used to mean only "nothing threw". A tap whose own verdict was
+ * `no-visible-change` printed `ok … [no visible change]`, and a field report
+ * (0.19.0) counted three such taps in a row that had not landed, each caught
+ * only by an outside screenshot, while the escalation log recorded every one
+ * of them as a mis-tap. The verdict was right and the mark contradicted it.
+ *
+ * WARN rather than FAIL, and no automatic retry. `no-visible-change` also
+ * fires on changes too small to register — a field gaining focus was measured
+ * reading as no change on 2026-10-01 — and retrying on a false one is how a
+ * tap fires twice, which the verify barrier forbids.
+ */
+export function stepMark(r) {
+  if (!r?.ok) return 'FAIL';
+  return r.unconfirmed || metrics.ESCALATING_VERDICTS.has(r.verification?.verdict) ? 'WARN' : 'ok  ';
+}
+
 /**
  * The one-line flow summary, so `ok` and `FAIL` each mean exactly one thing.
  *
@@ -3361,7 +3659,15 @@ export function flowSummary(res, { withTime = true } = {}) {
   const skips = skipped
     ? ` (${skipped} optional step${skipped === 1 ? '' : 's'} skipped as absent)`
     : '';
-  if (res.ok) return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}${skips}`;
+  if (res.ok) {
+    // "Completed" over a step that did nothing visible is the same one word
+    // arguing with its numbers that the failure branch below was fixed for.
+    const unconfirmed = (res.results ?? []).filter((r) => stepMark(r) === 'WARN').length;
+    if (unconfirmed) {
+      return `flow ran — ${res.ranSteps}/${res.totalSteps} steps, ${unconfirmed} not confirmed to have landed${time}${skips}`;
+    }
+    return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}${skips}`;
+  }
   const failed = (res.results ?? []).filter((r) => r.ok === false).length || 1;
   const worked = Math.max(0, res.ranSteps - failed);
   const unattempted = Math.max(0, res.totalSteps - res.ranSteps);

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';
@@ -12,11 +12,14 @@ 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)
@@ -265,7 +268,7 @@ async function lineReader() {
 const stepLine = (r) => {
   const settle = r.settled ? (r.settled.ok ? ` (settled ${r.settled.waitedMs}ms)` : ' (never settled)') : '';
   const verdict = r.verification && r.verification.verdict !== 'ok' ? ` [${r.verification.verdict}]` : '';
-  return `${r.ok ? 'ok  ' : 'FAIL'} [${r.index}] ${r.action}: ${r.ok ? r.detail : r.error}${settle}${verdict}`;
+  return `${actions.stepMark(r)} [${r.index}] ${r.action}: ${r.ok ? r.detail : r.error}${settle}${verdict}`;
 };
 
 async function main() {
@@ -421,31 +424,31 @@ 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;
     }
 
@@ -461,7 +464,23 @@ async function main() {
         '',
         `  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`,
-        `  fusion     ${r.agreement ?? 'n/a'} of elements seen by both sensors (measured healthy ${wedge.HEALTHY_FUSION}; at or below ${wedge.DISAGREEMENT} the frame is stale)`,
+        // **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.'] : []),
       ]);

package/src/device-state.js

@@ -49,6 +49,18 @@ export const DEVICE_STATE = [
     /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.
@@ -62,3 +74,28 @@ export const DEVICE_STATE = [
 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 ?? ''));
+}