simframe 0.13.0 → 0.14.0

package/README.md

@@ -406,6 +406,7 @@ steer the model is a tool surface the model uses wrong.
 | `sim_wait` | Waits for the screen to change *and then* settle. |
 | `sim_look` | **The only tool that returns an image**, capped at 1024 px. For layout, colour, spacing — questions text cannot answer. |
 | `sim_recall` · `sim_strip` | Look backwards: a text timeline of what happened, or recent frames tiled into one image. |
+| `sim_storage` | **What the app believes**, as opposed to what it drew: its `UserDefaults` and, for React Native, its `AsyncStorage`. Reads the data container off disk, so it answers on a device that is **not running**. |
 | `sim_capture` · `sim_devices` | Manage capture loops; list simulators. |
 
 ### What the screen looks like as text
@@ -585,6 +586,20 @@ simframe screens              # what this device has learned
 simframe goto invoices        # walk there, verifying every step
 ```
 
+And when the screen and the behaviour disagree, the question is usually not
+about the screen at all:
+
+```bash
+simframe storage                          # apps with a data container
+simframe storage com.example.myapp        # what that app saved
+```
+
+`sim_ui` says what is drawn; `sim_storage` says what the app believes. It reads
+the data container straight off the host filesystem, which means it works on a
+device that is **shut down** — `simctl` cannot do this at all, on any of its own
+paths, once a device stops running.
+
+
 Measured on a four-tab tour, `goto` plans and walks three-step routes with every
 step verified and no model call. It fails rather than guesses: an unknown
 destination, a query matching two screens equally, or no path of known edges all

package/native/simframed/Sources/SimframeCore/Motion.swift

@@ -13,6 +13,10 @@ public enum Motion {
 
     /// Below this mean absolute difference, two frames are the same picture.
     public static let stillThreshold = 0.004
+
+    /// How many moving cells make an animation rather than sensor noise.
+    /// Set from the measurements in `state(history:now:)` below.
+    public static let minAnimatingCells = 12
     /// Frames that must agree before the screen counts as settled.
     ///
     /// Paired with a duration, because frame count alone is not a measure of
@@ -170,8 +174,35 @@ public enum Motion {
             let cellThreshold = 0.06
             let moving = union.filter { $0 > cellThreshold }.count
             let fraction = Double(moving) / Double(union.count)
-            // Small and persistent, rather than a screen changing.
-            if fraction > 0 && fraction < 0.06 {
+            // Small and persistent, rather than a screen changing — and big
+            // enough to be something.
+            //
+            // `fraction > 0` meant one cell of 4,608 counted as an animation,
+            // and measured on a device that fires constantly on screens where
+            // nothing is happening. A field report put it exactly right: a
+            // warning that is usually wrong trains the reader to ignore the one
+            // that matters.
+            //
+            // Measured on this device, 2026-09-14, which is what
+            // `minAnimatingCells` is set from:
+            //
+            //   static home screen, nothing moving   1-4 cells, on 54% of frames
+            //   a blinking text caret                **2 cells** (1x2), on 100%
+            //   the testbed's spinner                169 cells (13x13)
+            //   Maps launching, median               656 cells (41x16)
+            //   a real spinner, from the field       1,364 cells (44x31)
+            //
+            // Caret and noise sit at 1-4; the smallest real animation seen is
+            // 169. A 42x gap with nothing in it, so the threshold is not
+            // delicate — 12 is three times the worst noise and an order of
+            // magnitude below the weakest signal.
+            //
+            // The caret is the case this is really for, and it is why the
+            // question could not be settled by reasoning: a caret must never
+            // stop a screen from settling, and before this it did — 72 frames
+            // out of 72 with `settled: false` on a screen holding nothing but a
+            // text cursor.
+            if moving >= Self.minAnimatingCells && fraction < 0.06 {
                 animating = boundingBox(of: union, threshold: cellThreshold)
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [

package/scripts/ci-device-guard.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Run a CI step, and tell a sick simulator apart from a failing check.
+//
+//   node scripts/ci-device-guard.mjs <udid> -- <command> [args...]
+//
+// **Why this exists, with the number that justifies it.** Over the last 25 CI
+// runs the `integration` job failed 17 times and passed 5. Eight of the nine
+// most recent failures name a device-state condition in their own output —
+// `NSPOSIXErrorDomain code=60`, `the display produced no frame in 60s`, `the
+// second app never launched` — and one of those runs was a **docs-only commit**
+// that changed a single markdown file. Two runs of byte-identical code failed at
+// two different steps.
+//
+// So the job has been answering two questions at once — *does simframe work* and
+// *did this hosted simulator survive twenty minutes* — and the second dominates.
+// A red build that is usually the device is the cry-wolf failure this repo keeps
+// writing items about, and it cost two days of re-reading logs to learn nothing.
+//
+// This does not paper over failures. It distinguishes them: a named device
+// condition gets the cure this project already ships (`simframe revive`) and one
+// retry, exactly as DEFERRED 126 says to; anything else fails on the spot,
+// untouched. The classification is written to the job summary so the *rate*
+// becomes visible instead of arguable.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+/** Conditions that are the simulator, not the code. Each seen in a real run. */
+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'],
+];
+
+const udid = process.argv[2];
+const sep = process.argv.indexOf('--');
+if (!udid || sep < 0) {
+  console.error('usage: ci-device-guard.mjs <udid> -- <command> [args...]');
+  process.exit(2);
+}
+const cmd = process.argv.slice(sep + 1);
+
+function run(argv, { capture = true } = {}) {
+  return new Promise((resolve) => {
+    const p = spawn(argv[0], argv.slice(1), { stdio: capture ? ['inherit', 'pipe', 'pipe'] : 'inherit' });
+    let out = '';
+    p.stdout?.on('data', (d) => { out += d; process.stdout.write(d); });
+    p.stderr?.on('data', (d) => { out += d; process.stderr.write(d); });
+    p.on('close', (code) => resolve({ code, out }));
+  });
+}
+
+const summary = (line) => {
+  const f = process.env.GITHUB_STEP_SUMMARY;
+  if (f) { try { fs.appendFileSync(f, `${line}\n`); } catch { /* summaries are a nicety */ } }
+};
+
+const deviceCause = (text) => DEVICE_STATE.find(([re]) => re.test(text))?.[1] ?? null;
+
+const first = await run(cmd);
+if (first.code === 0) process.exit(0);
+
+const cause = deviceCause(first.out);
+if (!cause) {
+  console.error(`\n     (this step failed on its merits, not on the device — not retrying)`);
+  summary(`- \`${cmd.join(' ')}\` — **check failed** (exit ${first.code})`);
+  process.exit(first.code ?? 1);
+}
+
+console.error(`\n     (${cause} — DEFERRED 126. Reviving once and running again.)`);
+await run(['node', 'src/cli.js', 'revive', `--device=${udid}`], { capture: false });
+const second = await run(cmd);
+if (second.code === 0) {
+  summary(`- \`${cmd.join(' ')}\` — passed after one revive (${cause})`);
+  process.exit(0);
+}
+// Twice in a row, on a condition we know the cure for. Reported as what it is.
+const again = deviceCause(second.out);
+summary(`- \`${cmd.join(' ')}\` — **${again ? 'device unavailable' : 'check failed'}** after a revive${again ? ` (${again})` : ''}`);
+if (again) console.error(`\nFAIL the simulator is still in a bad state after a revive: ${again}`);
+process.exit(second.code ?? 1);

package/scripts/ci-integration-local.sh

@@ -67,14 +67,17 @@ read_state() {
 printf '[{"button":"home"},{"settle":true}]\n' > /tmp/reset-local.json
 node src/cli.js do /tmp/reset-local.json --device="$DEVICE" >/dev/null 2>&1
 BEFORE=$(read_state)
-printf '[{"openUrl":"https://example.com"},{"settle":true}]\n' > /tmp/flow-local.json
-if node src/cli.js do /tmp/flow-local.json --device="$DEVICE" >/dev/null 2>&1; then
-  AFTER=$(read_state)
-  if [ "${BEFORE%% *}" != "${AFTER%% *}" ]; then ok "frame hash changed: ${BEFORE%% *} -> ${AFTER%% *}"
-  else bad "a step ran cleanly but capture saw no change"; fi
-else
-  bad "openUrl flow failed"
-fi
+# From inside an app, pressing home always changes the screen — see the job's
+# comment for the four vehicles that did not hold. Setup gets to a known screen;
+# the asserted action is simframe's own HID path with no simctl in it.
+printf '[{"launch":{"value":"com.apple.Preferences","relaunch":true}},{"settle":true}]\n' > /tmp/setup-local.json
+node src/cli.js do /tmp/setup-local.json --device="$DEVICE" >/tmp/step-local.log 2>&1 || true
+BEFORE=$(read_state)
+printf '[{"button":"home"},{"settle":true}]\n' > /tmp/flow-local.json
+node src/cli.js do /tmp/flow-local.json --device="$DEVICE" >>/tmp/step-local.log 2>&1 || true
+AFTER=$(read_state)
+if [ "${BEFORE%% *}" != "${AFTER%% *}" ]; then ok "frame hash changed: ${BEFORE%% *} -> ${AFTER%% *}"
+else bad "a step ran and capture saw no change"; tail -5 /tmp/step-local.log; fi
 
 step "The memory layer — screen map, refs, graph, verdicts, flows"
 # Mirrors the job: exit 75 means the display wedged and nothing was tested, so

package/scripts/ci-memory.mjs

@@ -111,7 +111,14 @@ async function cli(args, { expectFail = false, allowFail = false } = {}) {
     // detail has been truncated for legibility, and the first version of this
     // guard looked for "did not produce a frame" in a string that had been cut
     // to "simframe daemon di". The full text only exists at this boundary.
-    throw new Error(`simframe ${full.join(' ')} failed: ${why.slice(0, 400)}`);
+    //
+    // And when the payload is a JSON report, say what failed rather than
+    // handing back its first hundred characters. A run of this printed
+    // `simframe doctor --json failed: {\n "ok": false,\n "strict": true,\n
+    // "failu` — the word "failures" cut in half, one character before the only
+    // content that mattered. A harness that truncates away the reason is doing
+    // to its reader exactly what this repo keeps writing items about.
+    throw new Error(`simframe ${full.join(' ')} failed: ${summarise(why)}`);
   }
 }
 
@@ -193,6 +200,23 @@ async function jsonRetry(args, opts, attempts = 3) {
   throw last;
 }
 
+/** A failed JSON report, reduced to the part that says what went wrong. */
+function summarise(why) {
+  try {
+    const parsed = JSON.parse(why);
+    const failures = parsed.failures ?? parsed.failing ?? null;
+    if (Array.isArray(failures) && failures.length) {
+      return failures
+        .map((f) => (typeof f === 'string' ? f : `${f.name ?? f.check ?? '?'}: ${f.detail ?? f.note ?? f.message ?? ''}`.trim()))
+        .join('; ')
+        .slice(0, 400);
+    }
+    const bad = (parsed.checks ?? []).filter((c) => c.ok === false);
+    if (bad.length) return bad.map((c) => `${c.name}: ${c.detail ?? ''}`.trim()).join('; ').slice(0, 400);
+  } catch { /* not JSON, or not a shape we know — fall through to the raw text */ }
+  return why.slice(0, 400);
+}
+
 const markHash = async () => (await jsonRetry(['mark'])).hash;
 
 function writeFlow(name, steps) {

package/scripts/eval-fingerprint.mjs

@@ -86,6 +86,17 @@ console.log(`tour: ${tour.length} screens x ${rounds} rounds, every reading cold
 const readings = [];
 /** Navigations that did not land before the reading was taken. */
 const arrivalFailures = [];
+/** Readings too bare to be a screen — see the guard where this is used. */
+const sparseReadings = [];
+/**
+ * Below this, a reading cannot distinguish its screen from any other bare one.
+ *
+ * Not a failure threshold — see where it is used. The Settings root legitimately
+ * reads 4 tokens on a hosted runner, so treating this as "the screen has not
+ * drawn" rejected a real screen and made CI deterministically red. It marks
+ * readings worth suspecting when a score disagrees with itself, nothing more.
+ */
+const MIN_TOKENS_FOR_A_READING = 5;
 
 /**
  * The tokens that carry a name, as opposed to a shape.
@@ -124,6 +135,22 @@ const save = (extra = {}) => {
   }, null, 2));
 };
 
+/**
+ * How hard to try for a frame newer than the navigation before giving up.
+ *
+ * Three re-reads a second apart is ~3s of slack against capture medians that
+ * were measured above 1s on a bad runner. Generous enough to absorb the spikes
+ * that caused this, small enough that a genuinely stopped capture still fails
+ * rather than hanging the job.
+ */
+const STALE_READ_RETRIES = 3;
+const STALE_READ_WAIT_MS = 1000;
+
+/** When the steps that were supposed to change the screen finished. */
+let navigatedAt = 0;
+/** Readings that never got a frame newer than their own navigation. */
+const staleReadings = [];
+
 for (let round = 1; round <= rounds; round += 1) {
   for (const screen of tour) {
     if (screen.steps?.length) {
@@ -140,6 +167,7 @@ for (let round = 1; round <= rounds; round += 1) {
       // matters.
       try {
         await actions.runScript(device, { steps: screen.steps, verify: false });
+        navigatedAt = Date.now();
       } catch (err) {
         save({ abandonedAt: { screen: screen.name, round, error: err.message } });
         console.error(`\nFAIL round ${round}, "${screen.name}" never arrived: ${err.message}`);
@@ -148,7 +176,66 @@ for (let round = 1; round <= rounds; round += 1) {
         process.exit(1);
       }
     }
-    const id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+    let id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+    // A reading off a frame older than the navigation is not a reading either.
+    //
+    // Same rule as the sparseness guard below, on the other axis, and it took a
+    // third symptom to see they were one cause. Three CI runs failed this step
+    // three different ways — `settings` reading 4 tokens, a reading that "does
+    // not resemble its own screen", and a reading "taken on the previous
+    // screen" at similarity 1.00 off a frame **7168ms old**. All three are the
+    // same sentence: the reading is not of the screen we think it is, because
+    // capture on a hosted runner is slow. The daemon log for that run shows
+    // capture medians of 417ms, 503ms, 996ms, 1106ms and 1132ms against the
+    // 55.4ms p50 measured for a healthy runner — 20x, and with damage-driven
+    // capture a `fresh` read returns the newest frame that EXISTS, which on a
+    // runner that far behind can predate the navigation entirely.
+    //
+    // So the frame must have been captured after the steps that were supposed
+    // to change the screen. Re-read rather than fail, and fail only if it stays
+    // stale — an eval that scores a stale frame is measuring the runner, which
+    // is the one thing this harness says it is not doing.
+    if (navigatedAt) {
+      for (let attempt = 0; attempt < STALE_READ_RETRIES; attempt += 1) {
+        const capturedAt = id.state?.capturedAt ?? 0;
+        if (capturedAt >= navigatedAt) break;
+        const age = Date.now() - capturedAt;
+        console.log(`         ("${screen.name}" read a frame from ${age}ms ago, older than the navigation`
+          + ` — reading again ${attempt + 1}/${STALE_READ_RETRIES})`);
+        await new Promise((r) => setTimeout(r, STALE_READ_WAIT_MS));
+        id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+      }
+      if ((id.state?.capturedAt ?? 0) < navigatedAt) {
+        staleReadings.push(`${screen.name} round ${round}: frame still predates the navigation`
+          + ` by ${navigatedAt - (id.state?.capturedAt ?? 0)}ms after ${STALE_READ_RETRIES} re-reads`);
+      }
+    }
+    // A reading too sparse to be a screen is not a reading.
+    //
+    // On a runner measured at ~2.5x slower than a laptop (EXPERIMENTS §15),
+    // perception can land on a half-rendered screen: two CI runs recorded
+    // `settings` and `settings-general` **both at 4 tokens**, identical hash,
+    // and the eval duly reported that a reading did not resemble its own
+    // screen. It resembled nothing, because almost nothing had been drawn yet.
+    //
+    // This is the hazard `TOKEN_RULES_VERSION` 7 was written for, arriving
+    // through the harness instead of the rules: *"two sparse nameless readings
+    // then matched exactly, one hash standing for two different screens"*. A
+    // guard exists for identity and there was none here.
+    //
+    // Read again rather than fail, and fail only if it stays sparse — the same
+    // "untested is not passed" rule the memory harness learned. A screen that
+    // is genuinely this bare after a second look is a real finding.
+    if ((id.tokens ?? []).length < MIN_TOKENS_FOR_A_READING) {
+      const before = (id.tokens ?? []).length;
+      await new Promise((r) => setTimeout(r, 1500));
+      id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+      const after = (id.tokens ?? []).length;
+      console.log(`         ("${screen.name}" read ${before} token(s) — too sparse to compare; read again: ${after})`);
+      if (after < MIN_TOKENS_FOR_A_READING) {
+        sparseReadings.push(`${screen.name} round ${round}: ${after} token(s) after two reads`);
+      }
+    }
     // Did we actually arrive? Two differently-named screens reading the same
     // fingerprint means the navigation did not land before the reading was
     // taken, and every distribution below it is then measuring the tour rather
@@ -219,9 +306,45 @@ for (let round = 1; round <= rounds; round += 1) {
   }
 }
 
-save();
+save({ staleReadings });
 if (outFile) console.log(`\nwrote ${readings.length} readings to ${outFile}`);
 
+if (sparseReadings.length) {
+  // Reported, NOT failed — and that correction is worth more than the check.
+  //
+  // This exited 1 for four hours on 2026-09-14 and turned an intermittent CI
+  // failure into a deterministic one. The reasoning was that a 4-token reading
+  // is a screen that has not drawn. It is not: the Settings root legitimately
+  // reads 4 tokens on a hosted runner, twice in a row, three times in a row —
+  // which the comment on `MIN_TOKENS_FOR_A_READING` had itself said ("4-8
+  // tokens") one screen above the code that rejected it.
+  //
+  // What remains true is that a reading this bare cannot distinguish its screen
+  // from anything else equally bare, so it is worth saying out loud. What is not
+  // true is that saying so should stop the run. The arrival check below is the
+  // one that catches the real collision, and it does so on evidence rather than
+  // on a token count.
+  console.log(`\nNOTE ${sparseReadings.length} reading(s) were too bare to distinguish a screen:`);
+  for (const f of sparseReadings) console.log(`       ${f}`);
+  console.log(`\nFewer than ${MIN_TOKENS_FOR_A_READING} tokens after two reads. That is not automatically`);
+  console.log('wrong — a plain screen really can be this bare — but two readings this sparse');
+  console.log('cannot be told apart, which is the hazard TOKEN_RULES_VERSION 7 was written');
+  console.log('for. If a same-screen score below disagrees with itself, start here.');
+}
+
+if (staleReadings.length) {
+  // A NOTE and not a failure, for the same reason the sparseness guard is one:
+  // this says the runner was too slow to give a fresh frame, which is a fact
+  // about the machine and not about the fingerprint. It is printed *above* the
+  // arrival check on purpose — when both fire, this is the explanation of that.
+  console.log(`\nNOTE ${staleReadings.length} reading(s) never got a frame newer than their navigation:`);
+  for (const f of staleReadings) console.log(`       ${f}`);
+  console.log(`\nCapture on this host is behind the tour. With damage-driven capture a "fresh"`);
+  console.log('read returns the newest frame that exists, so on a slow runner it can predate');
+  console.log('the navigation entirely. If an arrival failure follows, this is its cause and');
+  console.log('the tour is not what needs fixing.');
+}
+
 if (arrivalFailures.length) {
   console.error(`\nFAIL ${arrivalFailures.length} reading(s) were taken on the previous screen:`);
   for (const f of arrivalFailures) console.error(`       ${f}`);

package/src/actions.js

@@ -2555,7 +2555,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
         for (let attempt = 0; ; attempt += 1) {
           for (const one of alternatives) {
             try {
-              const found = await api.locate(deviceQuery, one, { refresh: attempt > 0 });
+              const found = await api.locate(deviceQuery, one, { refresh: step.refresh !== false, options: ctx.options });
               return `${JSON.stringify(one)} appeared at ${found.target.x},${found.target.y}`
                 + ` (first of ${alternatives.length} awaited)`;
             } catch (err) {
@@ -2563,10 +2563,12 @@ async function runStep(deviceQuery, udid, step, ctx) {
             }
           }
           if (Date.now() >= limit) {
+            const stillAny = await stillnessNote(deviceQuery, ctx);
             throw new Error(
               `none of ${alternatives.length} awaited strings appeared`
               + ` (${alternatives.map((a) => JSON.stringify(a)).join(', ')}) in ${step.timeoutMs ?? 8000}ms.`
-              + ` Last: ${lastError}`,
+              + ` Last: ${lastError}`
+              + (stillAny ? ` (${stillAny.note})` : ''),
             );
           }
           await api.waitFor(deviceQuery, { mode: 'stable', stableMs: 200, timeoutMs: 700, options: ctx.options })
@@ -2575,7 +2577,26 @@ async function runStep(deviceQuery, udid, step, ctx) {
       }
       for (let attempt = 0; ; attempt += 1) {
         try {
-          const found = await api.locate(deviceQuery, query, { index: step.index, refresh: attempt > 0 });
+          // Fresh, like `assert` — and for the same reason, found the same way.
+          //
+          // This read `refresh: attempt > 0`, so the FIRST look resolved against
+          // the remembered map. A wait that can be satisfied by memory is not a
+          // wait: if recall hands back the wrong screen's map — which it does
+          // when two screens collide on a layout hash — the target "appears"
+          // without ever having been on screen, instantly, and the caller
+          // proceeds against a screen it is not on.
+          //
+          // Caught by the fingerprint eval on CI, which is the only place it
+          // could show: `settings-general` read the **Settings root** and its
+          // `waitFor "About"` had passed. The signature is in the round numbers
+          // — r2 and r3, never r1 — because memory has to be warm before it can
+          // lie, and round 1 is always cold.
+          //
+          // `assert` was made fresh by default after this exact defect cost a
+          // reported session; `waitFor` was left as it was. One perception pass
+          // is the price, and it is the same trade: a read is cheaper than the
+          // round trip a wrong verdict causes.
+          const found = await api.locate(deviceQuery, query, { index: step.index, refresh: step.refresh !== false, options: ctx.options });
           return `"${found.target.label}" appeared at ${found.target.x},${found.target.y}`;
         } catch (err) {
           lastError = err.message;
@@ -2609,9 +2630,23 @@ async function runStep(deviceQuery, udid, step, ctx) {
           }
         }
         if (Date.now() >= limit) break;
+        // Opt-in: stop early on a screen that has plainly stopped changing.
+        if (Number.isFinite(step.failIfStillFor)) {
+          const still = await stillnessNote(deviceQuery, ctx);
+          if (still && still.ms >= step.failIfStillFor) {
+            throw new Error(`gave up on ${query} after ${Date.now() - (limit - (step.timeoutMs ?? 8000))}ms:`
+              + ` ${still.note}, which is past the ${step.failIfStillFor}ms you said to stop at.`
+              + ` Last: ${lastError}`);
+          }
+        }
         await sleep(POLL_MS);
       }
-      throw new Error(`waited ${step.timeoutMs ?? 8000}ms for ${query}: ${lastError}`);
+      // Say how long it had been still. A wait that burned three minutes on a
+      // screen static for the last twelve seconds should not make the reader
+      // work that out from a second command.
+      const still = await stillnessNote(deviceQuery, ctx);
+      throw new Error(`waited ${step.timeoutMs ?? 8000}ms for ${query}: ${lastError}`
+        + (still ? ` (${still.note} — pass failIfStillFor to stop early next time)` : ''));
     }
 
     // One assert step for every condition, because `assertText` could only ask
@@ -2639,6 +2674,32 @@ async function runStep(deviceQuery, udid, step, ctx) {
         // is the opposite of what you want learned."*
         found = await api.locate(deviceQuery, query, { index: step.index, refresh: step.refresh !== false, options: ctx.options });
       } catch (err) {
+        // Ambiguity answers "is it there", and it answers it *yes*.
+        //
+        // `locate` refuses a query that matches several elements, which is right
+        // for `tap` — picking the wrong one of two taps the wrong thing — and
+        // wrong for a question about presence. Reported from the field on
+        // 0.13.0: `assert Administrator is visible` failed, and aborted the rest
+        // of the batch, against a screen with **two** Administrators on it. The
+        // assertion's own semantics were satisfied twice over. The message was
+        // praised in the same breath — candidates, coordinates and scores — so
+        // what was wrong was the verdict, not the diagnosis.
+        //
+        // The `gone` direction had the mirror-image bug and nobody had hit it
+        // yet: any error at all returned "is gone", so a query matching two
+        // visible elements would have reported them absent. Ambiguity is the one
+        // error that is positive evidence of presence, and it was being read as
+        // proof of absence.
+        //
+        // Strict single-match resolution stays for `enabled`, `disabled` and
+        // `value`, where the question is about a *particular* element and
+        // answering it from the wrong one is how a confident wrong answer gets
+        // made.
+        if (err.ambiguous && err.candidates?.length) {
+          const n = err.candidates.length;
+          if (want === 'visible') return `${query} is visible (${n} things match it here — a presence check does not have to choose)`;
+          if (want === 'gone') throw new Error(`${query}: still here — ${n} things on this screen match it`);
+        }
         if (want === 'gone') return `${query} is gone`;
         throw new Error(`${query}: ${err.message}`);
       }
@@ -2744,3 +2805,55 @@ export function settleEvidence(w) {
   return (parts.length ? parts.join('; ') : 'nothing observed')
     + (m ? `\n${m.map}` : '');
 }
+
+/**
+ * The one-line flow summary, so `ok` and `FAIL` each mean exactly one thing.
+ *
+ * `FLOW FAILED — 3/3 steps` was reported from the field as reading like a
+ * success, and the reporter had it exactly: the denominator means *attempted*
+ * on failure and *succeeded* on success, so the same shape carries opposite
+ * meanings. `flow completed — 5/5 steps` and `FLOW FAILED — 3/3 steps` differ
+ * only in a word, and the numbers argue against the word.
+ *
+ * On failure it says how many worked and how many did not, which is the thing a
+ * caller has to know to decide whether to resume or re-plan.
+ */
+export function flowSummary(res, { withTime = true } = {}) {
+  const time = withTime && Number.isFinite(res.totalMs) ? ` in ${res.totalMs}ms` : '';
+  if (res.ok) return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}`;
+  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);
+  return `FLOW FAILED — ${worked} ok, ${failed} failed`
+    + (unattempted ? `, ${unattempted} not attempted` : '')
+    + ` (of ${res.totalSteps})${time}`;
+}
+
+/**
+ * How long the screen has been still, for a wait that is about to give up.
+ *
+ * A field report: a 180-second wait for a control that never appeared, on a
+ * screen that had been static for about twelve of those seconds — the app had
+ * logged itself out and was sitting on a login form. The failure message was
+ * praised for listing what *was* on screen; it arrived three minutes late.
+ *
+ * Stillness is already tracked and already printed by other commands, so the
+ * information existed and this wait simply never asked for it. Reported on
+ * every timeout, and — only when the caller opts in — allowed to end the wait
+ * early. Opt-in and not default, because a still screen is exactly what a
+ * pending network call looks like: the target may yet arrive, and a wait that
+ * gave up on stillness alone would break the case waits exist for.
+ *
+ * This is only trustworthy because of 134. Before the animation threshold was
+ * measured, a completely static screen claimed something was animating on 54%
+ * of its frames, and "nothing has moved" could not be said with a straight face.
+ */
+async function stillnessNote(deviceQuery, ctx) {
+  try {
+    const { state } = await api.getState(deviceQuery, { options: ctx.options });
+    const ms = state?.stableForMs;
+    return Number.isFinite(ms) ? { ms, note: `the screen has not moved for ${Math.round(ms)}ms` } : null;
+  } catch {
+    return null;
+  }
+}

package/src/cli.js

@@ -12,6 +12,7 @@ import * as baseline from './baseline.js';
 import * as metrics from './metrics.js';
 import * as navigate from './navigate.js';
 import { decodePng } from './png.js';
+import * as storage from './storage.js';
 import * as store from './store.js';
 import * as view from './view.js';
 
@@ -33,6 +34,7 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe tap     <selector>        tap #3, "Save", or @120,400
   simframe do      <script.json>     run a scripted flow (see below)
   simframe screens [device]          list screens this device has learned
+  simframe storage [bundle-id]       what the app saved (works on a shut-down device)
   simframe goto    <screen>          walk to a known screen through known steps
   simframe flow    save <name> <script.json>   run a flow and save it if every step verifies
   simframe flow    run  <name>       replay a saved flow
@@ -801,7 +803,7 @@ async function main() {
         },
         [
           ...res.results.map(stepLine),
-          `${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps in ${res.totalMs}ms`,
+          actions.flowSummary(res),
           saved && (saved.ok ? `saved flow "${saved.name}" — ${saved.steps} steps` : `not saved: ${saved.reason}`),
           map && `\n${map}`,
         ],
@@ -860,6 +862,25 @@ async function main() {
       return;
     }
 
+    case 'storage': {
+      // A file read, like `screens`, and deliberately not a daemon call. The
+      // whole value of this command is that it answers on a device that is not
+      // running — measured: simctl itself cannot, on this Xcode. Routing it
+      // through the daemon would throw that away for no gain.
+      const device = await resolveDevice(flags.device);
+      const [bundleId] = positional;
+      if (!bundleId) {
+        const list = await storage.apps(device.udid);
+        const match = flags.match ? String(flags.match).toLowerCase() : null;
+        const shown = match ? list.filter((a) => a.bundleId.toLowerCase().includes(match)) : list;
+        emit(flags, shown, storage.formatApps(shown));
+        return;
+      }
+      const result = await storage.read(device.udid, bundleId);
+      emit(flags, result, storage.format(result));
+      return;
+    }
+
     case 'screens': {
       // Reading what this device has learned is a file read. It used to go
       // through ensureDaemon, so a device whose capture had stopped could not
@@ -920,7 +941,7 @@ async function main() {
         }
         emit(flags, res, [
           ...(res.results ?? []).map(stepLine),
-          `${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps`,
+          actions.flowSummary(res, { withTime: false }),
         ]);
         process.exitCode = res.ok ? 0 : 1;
         return;