simframe 0.6.1 → 0.7.0

package/README.md

@@ -129,6 +129,76 @@ breaks the host-side path.
 brew tap facebook/fb && brew install idb-companion && pipx install fb-idb
 ```
 
+## Android
+
+simframe's second backend drives an Android emulator with the same commands, the
+same screen map and the same memory as a simulator. Everything above the
+platform boundary — the frame store, settle, the structural fingerprint, the
+screen map, refs and the transition graph — runs on it unmodified, because the
+boundary hands it frames and nothing above it knows what a simulator is.
+
+| Capability | Android | How |
+| --- | --- | --- |
+| Watch the screen, wait, recall | yes | frames at **41 ms** through the emulator console, host-side — no adb in the capture path |
+| Read labels + coordinates from pixels | yes | the same Vision OCR + CV, off the same PNG |
+| Screen map, refs, screen memory, the graph | yes | unchanged above the boundary |
+| Tap, type, swipe, keys | yes | the console's `event mouse` as a real down/move/up, `event text` for characters, `input keyevent` for keys |
+| Clipboard | yes | the emulator's gRPC `setClipboard`, over `node:http2`, no dependency |
+| List/resolve devices, launch, terminate, open a URL, permissions | yes | `adb`, with the permission state read back off the device |
+| Accessibility tree | **not available (OCR + CV only)** | `uiautomator dump` costs **2,012 ms** a read, against 45 ms for the iOS tree. See [`docs/DEFERRED.md`](docs/DEFERRED.md) |
+
+```bash
+# an emulator is found the same way a simulator is
+simframe devices          # ● Small_Phone_API_36  Android 16 (API 36)  emulator-5554
+simframe ui --device=emulator-5554
+simframe do --device=emulator-5554 flow.json
+```
+
+The tree is a deliberate omission, not an oversight. Making it fast needs a
+resident instrumentation APK on the device — the shape uiautomator2, Maestro and
+Appium all converged on — and that would be simframe's first runtime artifact
+installed onto your device. The perception ladder was built so a missing tier
+degrades rather than fails, and this is exactly that case: OCR and CV yield
+labels and coordinates on Android today, and a tap by label works without a tree
+at all. `simframe doctor` reports the tier as `optional` with that number, so
+the gap is visible rather than silent, and the criteria for revisiting it are in
+`docs/DEFERRED.md` under **Phase 8b**.
+
+**What the missing tree costs, measured rather than hand-waved.** Screen
+*identity* is weaker on Android than on iOS, and specifically so. Tokens per
+screen, and where they come from:
+
+| Screen | Tokens | Regions | Roles | Chrome labels |
+| --- | --- | --- | --- | --- |
+| launcher | **1** | nav-bar 1 | text 1 | 0 |
+| Settings root | 9 | content 9 | text 9 | 0 |
+| example.com in Chrome | 6 | content 3, nav-bar 3 | text 6 | 0 |
+
+Every token has role `text`, because without a tree nothing infers a button from
+a rectangle reliably enough to say so, and no screen here carries a chrome label
+at all. So on Android a screen is recognised by the geometry of its text, which
+is thinner and noisier than the iOS mix of roles, chrome labels and geometry.
+Flows still work; screen *memory* is doing more guessing, and that is the honest
+cost of the tier being absent.
+
+It is also why the obvious fix for the iOS drift — dropping content-region text
+out of identity, which would be a strict improvement there — is not available:
+it would leave Settings' root with zero tokens, and zero tokens is no identity
+at all. See [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md).
+
+That last column read **3** before this measurement changed it. Chrome's address
+bar is chrome by every structural test there is, so the screen's identity
+contained `"== example.com"` — a URL, meaning the same browser on a different
+page was a different screen and every learned route through it broke on
+navigation — plus `":"` and `"+"`, which are OCR reading punctuation off icons.
+A chrome label now has to be a name: two letters at minimum, and not an
+address.
+
+The emulator's own gRPC surface was checked for anything tree-shaped and has
+nothing: 43 RPCs for sensors, input, screenshots and VM state, and no notion of
+a view. That question is settled, not open. The same surface is what carries the
+clipboard.
+
 ## The tools
 
 Read first, act in batches, and look at pixels only when the question is about
@@ -397,7 +467,10 @@ an Xcode upgrade that moves something is a bounded fix rather than an
 archaeology project. If a layer breaks, simframe degrades to the layer below
 and `doctor` says which.
 
-Run `simframe start --engine=simctl` to use the original loop instead.
+Run `simframe start --engine=screenshot` to use the one-frame-at-a-time loop
+instead — it is also the only capture engine on Android, where it reaches the
+emulator console rather than any simulator tool. `--engine=simctl` is still
+accepted as the name that loop used to have.
 
 - **Files are the IPC for reads.** The daemon renames completed frames into
   place; readers just read them. A rename is atomic, so a reader can never see a
@@ -488,6 +561,13 @@ So every downgrade now announces itself:
   is deliberate: `WARN` means this machine could be doing better and silently is
   not, which is the failure worth shouting about. An optional fallback missing on
   a fresh machine has not degraded from anything, and `--strict` ignores it.
+- A device whose capture has **wedged** says so: `capture: stalled — the display
+  surface has been unreadable for 62s; 3 re-attaches did not help; only
+  restarting the device is known to cure it`. This is a different thing from a
+  still screen, and it used to look identical, because a damage-driven engine
+  produces no frames for either. An agent told "nothing changed" keeps tapping;
+  one told the simulator is wedged stops. simframe reports it and does not
+  restart your device.
 - `--strict`, or `SIMFRAME_STRICT=1`, turns any downgrade into a non-zero exit.
   CI runs strict, so a release cannot ship in the state that shipped twice.
 
@@ -511,12 +591,15 @@ said a word — the exact failure shape, found by the thing built to catch it.
 
 ## Limitations
 
-- Simulators only. Neither the framebuffer nor `simctl` can reach a physical
-  device.
+- Simulators and Android emulators only. Neither the framebuffer nor `simctl`
+  nor the emulator console can reach a physical device.
+- Android has no accessibility tree, so its screen identity rests on the
+  geometry of OCR'd text: thinner and noisier than iOS's. See
+  [Android](#android) above.
 - The daemon depends on private frameworks. They are stable enough to build on —
   capture and accessibility survived the iOS 26 transition — but an Xcode
   upgrade can move a symbol. `doctor` reports each layer separately so a break
-  is visible rather than mysterious, and `--engine=simctl` still works.
+  is visible rather than mysterious, and `--engine=screenshot` still works.
 - Hardware buttons: only `home` is implemented. The other Indigo codes are
   unverified, and a wrong one can crash `backboardd` or lock the device, so they
   return an error rather than a guess.
@@ -532,9 +615,13 @@ said a word — the exact failure shape, found by the thing built to catch it.
 
 ## Roadmap
 
-- **Android, as a second backend.** Everything above the platform boundary is
-  already platform-agnostic; nothing above it imports a simulator framework.
 - **Extend the confirm vocabulary beyond English.**
+- **Region bands from clustering**, replacing the positional bands. They have
+  produced three bugs in three phases, and on Android they put a URL bar in the
+  nav bar and its URL into the screen's identity.
+- **Phase 8b, conditionally:** an instrumentation APK for the Android
+  accessibility tree, with the criteria for doing it stated in
+  `docs/DEFERRED.md` rather than left to enthusiasm.
 
 ## Releasing
 

package/native/simframed/Sources/PrivateAPI/AccessibilityBridge.swift

@@ -237,8 +237,13 @@ public final class AccessibilityBridge {
             cut = cut ?? "the read ran out of time"
             return
         }
-        out.append(node(from: element, depth: depth))
-        guard let children = attribute(element, "AXChildren") as? [NSObject] else { return }
+        // Each node's reads hand back autoreleased objects, and a 4000-node
+        // cap means 4000 nodes' worth of them living until the whole walk
+        // returns. Draining per node keeps the peak flat.
+        autoreleasepool {
+            out.append(node(from: element, depth: depth))
+        }
+        guard let children = autoreleasepool(invoking: { attribute(element, "AXChildren") as? [NSObject] }) else { return }
         for child in children {
             walk(child, depth: depth + 1, into: &out, deadline: deadline, cut: &cut)
         }

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

@@ -18,15 +18,48 @@ public struct CaptureRecovery {
     /// watches a dead capture loop and wonders.
     public static let reattachAfterFailures = 6
 
+    /// When re-resolving the port has demonstrably not helped.
+    ///
+    /// Re-resolving *succeeds* in the pathology this exists for: the call
+    /// returns a fresh descriptor, the callback re-arms, and every read still
+    /// fails. Because a successful re-resolve resets the failure count, that
+    /// state loops — six failures, re-resolve, six failures — and no count of
+    /// consecutive failures ever grows large enough to notice it. Observed
+    /// three times in one afternoon on a simulator driven hard for ten minutes;
+    /// only restarting the device cured it.
+    ///
+    /// So the signal is re-resolves, not failures. Two of them means the port
+    /// was not the problem.
+    public static let stalledAfterReattaches = 2
+
+    /// And the other way it goes wrong: re-resolving itself failing, where the
+    /// failure count does keep growing because nothing resets it.
+    public static let stalledAfterFailures = reattachAfterFailures * 3
+
     public private(set) var consecutiveFailures = 0
+    /// Successful re-resolves since the last real frame.
+    public private(set) var reattaches = 0
     private let threshold: Int
 
     public init(threshold: Int = CaptureRecovery.reattachAfterFailures) {
         self.threshold = threshold
     }
 
+    /// Is capture wedged rather than merely stumbling?
+    ///
+    /// Deliberately a state and not an event: the daemon reports it, and does
+    /// not act on it. A capture loop that restarted the device it is watching
+    /// would be a tool that reaches for the mains when a reading looks wrong.
+    public var isStalled: Bool {
+        reattaches >= Self.stalledAfterReattaches || consecutiveFailures >= Self.stalledAfterFailures
+    }
+
     public mutating func captureSucceeded() {
         consecutiveFailures = 0
+        // A real frame is the only evidence that health is back. Resetting this
+        // anywhere else — on a re-resolve, say — is how the loop above stayed
+        // invisible.
+        reattaches = 0
     }
 
     /// Records a failure and says whether the port is now due a re-resolve.
@@ -50,6 +83,7 @@ public struct CaptureRecovery {
             _ = try platform.reattachDisplay()
             try platform.observeChanges(onDamage)
             consecutiveFailures = 0
+            reattaches += 1
             return .success(failures)
         } catch {
             // Deliberately not reset: if the port cannot be re-resolved, the

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

@@ -80,6 +80,26 @@ public final class FrameStore {
 
     /// The newest state written, for callers that need the current hashes
     /// without recomputing them.
+    /// Publish how capture itself is doing, separately from any frame.
+    ///
+    /// It cannot ride in `state.json`, because that is written when a frame is
+    /// recorded and a stall is precisely the absence of frames: the state a
+    /// reader sees during a stall is the last healthy one, arbitrarily old, and
+    /// there is nothing in it that says so. An idle screen also produces no
+    /// frames, so "no frames" is not the signal either — the signal is the
+    /// daemon's own failed reads, which only the daemon knows about.
+    ///
+    /// `nil` removes the file: health is the absence of a complaint, so a
+    /// reader that finds nothing here is right to assume capture is fine.
+    public func writeCaptureHealth(_ health: [String: Any]?) throws {
+        let url = root.appendingPathComponent("capture-health.json")
+        guard let health else {
+            try? FileManager.default.removeItem(at: url)
+            return
+        }
+        try writeAtomic(try JSONSerialization.data(withJSONObject: health), to: url)
+    }
+
     public func latestState() -> [String: Any]? {
         guard let data = try? Data(contentsOf: root.appendingPathComponent("state.json")) else { return nil }
         return try? JSONSerialization.jsonObject(with: data) as? [String: Any]

package/native/simframed/Sources/simframed/main.swift

@@ -167,6 +167,7 @@ case "run":
         let lock = NSLock()
         var dirty = true
         var recovery = CaptureRecovery()
+        var stalledSince: Double?
         var lastCapture = 0.0
         var frames = 0
         var lastReport = Date().timeIntervalSince1970
@@ -433,7 +434,17 @@ case "run":
                     latencies.append(Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6)
                     frames += 1
                     lastCapture = now
+                    let wasStalled = recovery.isStalled
                     recovery.captureSucceeded()
+                    if wasStalled {
+                        // A frame after a stall is the only thing that clears
+                        // it, and it is worth saying out loud: the device came
+                        // back on its own, which nobody would otherwise know.
+                        try? store.writeCaptureHealth(nil)
+                        stalledSince = nil
+                        FileHandle.standardError.write(
+                            "simframed: capture recovered on its own\n".data(using: .utf8)!)
+                    }
                 } catch {
                     let due = recovery.captureFailed()
                     FileHandle.standardError.write(
@@ -460,6 +471,25 @@ case "run":
                                 "simframed: could not re-resolve the display port: \(error)\n".data(using: .utf8)!)
                         }
                     }
+                    // Say that capture is wedged rather than merely slow, and
+                    // then do nothing about it. The cure for this state is a
+                    // device restart, which is the user's to make: a capture
+                    // loop that rebooted the device it was watching would be a
+                    // tool reaching for the mains because a reading looked
+                    // wrong. So it is published, `doctor` grades it and
+                    // `simframe state` prints it, and an agent reads "the
+                    // simulator is wedged" instead of "nothing changed".
+                    if recovery.isStalled {
+                        if stalledSince == nil { stalledSince = FrameStore.nowMs() }
+                        try? store.writeCaptureHealth([
+                            "stalled": true,
+                            "since": stalledSince ?? FrameStore.nowMs(),
+                            "at": FrameStore.nowMs(),
+                            "consecutiveFailures": recovery.consecutiveFailures,
+                            "reattaches": recovery.reattaches,
+                            "reason": "\(error)",
+                        ])
+                    }
                     Thread.sleep(forTimeInterval: 0.5)
                 }
             }

package/native/simframed/Tests/SimframeCoreTests/HashingTests.swift

@@ -306,6 +306,45 @@ final class CaptureRecoveryTests: XCTestCase {
         XCTAssertTrue(damaged, "the damage callback was re-armed on the new descriptor")
     }
 
+    func testReResolvingTwiceWithoutAFrameIsAStall() {
+        // The pathology this is for: re-resolving *works* and reads keep
+        // failing. Because a successful re-resolve clears the failure count,
+        // the loop is six-failures-then-re-resolve for as long as you let it,
+        // and no count of consecutive failures ever notices. Observed three
+        // times in one afternoon; only a device restart cured it.
+        let platform = StubPlatform()
+        _ = try? platform.attach(udid: "STUB-1")
+        var recovery = CaptureRecovery(threshold: 2)
+
+        _ = recovery.captureFailed()
+        XCTAssertTrue(recovery.captureFailed())
+        _ = recovery.reattach(platform: platform, onDamage: {})
+        XCTAssertFalse(recovery.isStalled, "one re-resolve is a recovery, not a stall")
+
+        _ = recovery.captureFailed()
+        XCTAssertTrue(recovery.captureFailed())
+        _ = recovery.reattach(platform: platform, onDamage: {})
+        XCTAssertTrue(recovery.isStalled, "the second says the port was never the problem")
+
+        // And only a real frame clears it. Nothing else is evidence.
+        recovery.captureSucceeded()
+        XCTAssertFalse(recovery.isStalled)
+        XCTAssertEqual(recovery.reattaches, 0)
+    }
+
+    func testAReattachThatKeepsFailingIsAlsoAStall() {
+        // The other direction: when the re-resolve itself fails the count does
+        // keep growing, because nothing resets it.
+        let platform = StubPlatform()
+        platform.failReattach = true
+        var recovery = CaptureRecovery(threshold: 6)
+        for _ in 0..<(CaptureRecovery.stalledAfterFailures - 1) { _ = recovery.captureFailed() }
+        XCTAssertFalse(recovery.isStalled)
+        _ = recovery.captureFailed()
+        XCTAssertTrue(recovery.isStalled)
+        XCTAssertEqual(recovery.reattaches, 0, "nothing was ever re-resolved")
+    }
+
     func testAFailedReattachStaysDueRatherThanWaitingForAnotherSix() {
         let platform = StubPlatform()
         platform.failReattach = true

package/package.json

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

package/scripts/analyse-fingerprint.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// Why do same-screen revisits disagree? Aggregate, not anecdotal.
+//
+// `eval-fingerprint.mjs` says how far apart the two distributions are and names
+// the single worst pair. That was enough while the gap was wide and stopped
+// being enough the day it narrowed: one pair is an anecdote, and the fix has to
+// be aimed at whatever causes most of the divergence.
+//
+// So this reads an eval's `--out` JSON and classifies every divergent token in
+// every same-screen pair. The token grammar is
+// `role:region[:@slot]:w:h["label"]:x:y#count`, which is enough to say what
+// moved:
+//
+//   label      the same structure under a different chrome label — a dynamic or
+//              misread name, the thing chrome labels were most feared to do
+//   role       the same geometry and place under a different role — inference
+//              flipping, e.g. a field that sometimes gets a rectangle
+//   bucket     the same key, `#1` on one side and `#many` on the other — a
+//              sibling count straddling the boundary
+//   anchor     the same key at a different quantised x/y — the group's topmost
+//              member moved by half a grid cell
+//   size       the same role and place at a different quantised w/h — usually
+//              OCR returning a different bounding box for the same text
+//   presence   a structural key on one side only — an element that came or went
+import fs from 'node:fs';
+import * as fingerprint from '../src/fingerprint.js';
+
+const file = process.argv[2];
+if (!file) {
+  console.error('usage: node scripts/analyse-fingerprint.mjs <eval --out file.json>');
+  process.exit(2);
+}
+const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+const readings = data.readings ?? [];
+if (!readings.length || !readings[0].tokens) {
+  console.error('that eval was written without tokens — re-run the eval, it keeps them now');
+  process.exit(2);
+}
+
+/**
+ * A token, taken apart.
+ *
+ * `role:region[:@slot]:w<n>:h<n>[:"label"]:x<n>:y<n>#<count>` — every field is
+ * separated so a pair of tokens can be compared field by field. The first
+ * version of this file matched tokens by stripping one field at a time and
+ * asking whether the rest was equal, which sounds equivalent and is not: the
+ * size-stripped form of a content text token is `text:content`, which matches
+ * *every* content text token, so whichever candidate happened to be left over
+ * got called a size change. It reported 100% `size` for a sample the eval
+ * itself had already shown contained a count flip.
+ */
+const FIELDS = ['role', 'region', 'slot', 'w', 'h', 'label', 'x', 'y', 'count'];
+const TOKEN = /^([^:]+):([^:]+)(?::@([^:]+))?:w(\d+):h(\d+)(?::"([^"]*)")?:x(-?\d+):y(-?\d+)#(1|many)$/;
+
+function parse(token) {
+  const m = TOKEN.exec(token);
+  if (!m) return null;
+  const [, role, region, slot, w, h, label, x, y, count] = m;
+  return { token, role, region, slot: slot ?? null, w, h, label: label ?? null, x, y, count };
+}
+
+/** Which fields differ, in a stable order. */
+function differing(a, b) {
+  return FIELDS.filter((f) => a[f] !== b[f]);
+}
+
+/**
+ * What to call a difference of these fields.
+ *
+ * Named after the cause rather than the field, because the fix is different for
+ * each: a label that moves is normalisation, a role that flips is inference, a
+ * count that straddles is bucketing, a box that changes is OCR segmentation.
+ */
+function nameOf(fields) {
+  if (!fields.length) return 'identical';
+  const names = new Set();
+  for (const f of fields) {
+    if (f === 'label') names.add('label');
+    else if (f === 'role') names.add('role');
+    else if (f === 'count') names.add('bucket');
+    else if (f === 'x' || f === 'y') names.add('anchor');
+    else if (f === 'w' || f === 'h') names.add('size');
+    else names.add(f);
+  }
+  return [...names].sort().join('+');
+}
+
+/** Beyond this many differing fields, two tokens are not the same thing moved. */
+const RELATED_MAX_FIELDS = 3;
+
+const causes = new Map();
+const byRegion = new Map();
+const bump = (map, k, n = 1) => map.set(k, (map.get(k) ?? 0) + n);
+
+const pairs = [];
+for (let i = 0; i < readings.length; i += 1) {
+  for (let j = i + 1; j < readings.length; j += 1) {
+    if (readings[i].name !== readings[j].name) continue;
+    const a = readings[i];
+    const b = readings[j];
+    const similarity = fingerprint.similarity(a.tokens, b.tokens);
+    const setA = new Set(a.tokens);
+    const setB = new Set(b.tokens);
+    const onlyA = a.tokens.filter((t) => !setB.has(t)).map(parse).filter(Boolean);
+    const onlyB = b.tokens.filter((t) => !setA.has(t)).map(parse).filter(Boolean);
+    pairs.push({ name: a.name, ra: a.round, rb: b.round, similarity, divergent: onlyA.length + onlyB.length });
+
+    // Best match, not first match: each unmatched token on the left is paired
+    // with the candidate on the right that differs in the fewest fields, and
+    // that pairing is consumed. Greedy-by-preference-order is what produced the
+    // wrong answer above.
+    const remaining = [...onlyB];
+    for (const left of onlyA) {
+      let best = null;
+      for (let k = 0; k < remaining.length; k += 1) {
+        const fields = differing(left, remaining[k]);
+        if (!best || fields.length < best.fields.length) best = { k, fields };
+      }
+      const related = best && best.fields.length <= RELATED_MAX_FIELDS;
+      const cause = related ? nameOf(best.fields) : 'presence';
+      if (related) remaining.splice(best.k, 1);
+      bump(causes, cause);
+      bump(byRegion, `${left.region}/${left.role}`);
+    }
+    for (const right of remaining) {
+      bump(causes, 'presence');
+      bump(byRegion, `${right.region}/${right.role}`);
+    }
+  }
+}
+
+pairs.sort((x, y) => x.similarity - y.similarity);
+const totalDivergent = [...causes.values()].reduce((a, b) => a + b, 0);
+const pct = (n) => `${((n / totalDivergent) * 100).toFixed(0)}%`;
+
+console.log(`${pairs.length} same-screen pairs from ${readings.length} readings (${data.label ?? 'unlabelled'}, ${data.device ?? '?'})`);
+console.log(`similarity: min ${pairs[0]?.similarity.toFixed(2)}  median ${pairs[pairs.length >> 1]?.similarity.toFixed(2)}  max ${pairs[pairs.length - 1]?.similarity.toFixed(2)}`);
+console.log(`\n${totalDivergent} divergent token(s) across those pairs, by cause:`);
+for (const [cause, n] of [...causes].sort((a, b) => b[1] - a[1])) {
+  console.log(`  ${String(n).padStart(4)}  ${pct(n).padStart(4)}  ${cause}`);
+}
+console.log('\nby region/role — where the instability lives:');
+for (const [where, n] of [...byRegion].sort((a, b) => b[1] - a[1])) {
+  console.log(`  ${String(n).padStart(4)}  ${pct(n).padStart(4)}  ${where}`);
+}
+console.log('\nweakest pairs:');
+for (const p of pairs.slice(0, 8)) {
+  console.log(`  ${p.similarity.toFixed(2)}  ${p.name} r${p.ra} vs r${p.rb}  (${p.divergent} divergent)`);
+}

package/scripts/bench-flow.mjs

@@ -3,7 +3,7 @@
 import { runScript } from '../src/actions.js';
 import * as input from '../src/input.js';
 import * as api from '../src/index.js';
-import { launchApp, terminateApp } from '../src/simctl.js';
+import { launchApp, terminateApp } from '../src/platform/index.js';
 
 const BUNDLE = process.argv[2];
 const device = process.argv[3];

package/scripts/ci-memory.mjs

@@ -41,6 +41,15 @@ const CONVERGE_PASSES = 3;
 const BETWEEN_PASSES_MS = 1200;
 
 let failures = 0;
+/**
+ * The device is gone, as distinct from having blinked. See `jsonRetry`, which
+ * is the only thing that sets it: a dropped frame is retryable and this file
+ * already treats it that way, so calling the first one fatal would fight the
+ * retry rather than help it. Exhausted attempts are the difference between a
+ * blink and a death.
+ */
+let deviceDied = null;
+
 function check(ok, label, detail = '') {
   if (!ok) failures += 1;
   console.log(`${ok ? 'ok  ' : 'FAIL'} ${label}${detail ? ` — ${detail}` : ''}`);
@@ -65,6 +74,10 @@ async function cli(args, { expectFail = false, allowFail = false } = {}) {
     if (err.unexpectedSuccess) throw err;
     if (expectFail || allowFail) return `${err.stdout ?? ''}${err.stderr ?? ''}`;
     const why = (err.stdout || err.stderr || err.message || '').trim();
+    // Noted here, not in `check`: by the time a failure reaches a check its
+    // 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)}`);
   }
 }
@@ -97,6 +110,23 @@ async function jsonRetry(args, opts, attempts = 3) {
       await new Promise((r) => setTimeout(r, 1500));
     }
   }
+  // Out of attempts on a capture error: the device is not blinking, it is gone.
+  //
+  // Diagnosed and exited here rather than flagged for a later `check` to
+  // notice, because most call sites do not wrap this — the throw escapes, the
+  // run dies on an unhandled rejection, and the operator gets a stack trace
+  // pointing at this file instead of a sentence about their simulator. Which is
+  // exactly what the first version of this did.
+  if (TRANSIENT.test(last?.message ?? '')) {
+    deviceDied = last.message;
+    console.error(`\nFAIL the device stopped producing frames, and did not come back after ${attempts} attempts:`);
+    console.error(`  ${String(last.message).split('\n')[0]}`);
+    console.error('\nEverything after this point would be testing a dead simulator, so the run');
+    console.error('stops here. This is not a memory-layer failure — it is the device-state');
+    console.error('problem in docs/DEFERRED.md. A device restart is the only known cure;');
+    console.error('on a hosted runner it means a retry.');
+    process.exit(1);
+  }
   throw last;
 }
 
@@ -307,7 +337,19 @@ const novelVerdicts = novelSteps.length
 // has not told us anything about the graph.
 const novelRan = novelSteps.length > 0 && novelSteps.every((r) => r.ok !== false);
 check(novelRan, 'the novel action ran at all', `[${novelVerdicts.join(', ')}]`);
+// The other half of the precondition, which was written above as a comment and
+// then trusted. It is not trustworthy: the positioning run sends the device
+// home, and a simulator that has been driven hard stops delivering `home` while
+// still reporting success (docs/DEFERRED.md). From a screen the action cannot
+// change, `no-visible-change` is the honest verdict and the claim below was
+// never asked — so this is a precondition, and saying otherwise is how this
+// file has spent the day accusing the graph of something the device did.
+const novelMoved = novelRan && !novelVerdicts.every((v) => v === 'no-visible-change');
 if (novelRan) {
+  check(novelMoved, 'and the device was somewhere the novel action could change',
+    novelMoved ? `[${novelVerdicts.join(', ')}]` : 'the screen never moved — the device was already there, or ignored being sent home');
+}
+if (novelRan && novelMoved) {
   check(novelSteps.some((r) => r.verification?.verdict === 'unverified'),
     'an action never taken here before is reported as unverified, not as verified',
     `[${novelVerdicts.join(', ')}]`);
@@ -394,9 +436,14 @@ if (check(forced.saved?.ok === true, 'and --force saves it anyway', `${forced.sa
 console.log('\n--- every command speaks JSON ---');
 // The --json plumbing is per-command and hand-written, so one command quietly
 // printing prose is exactly the kind of thing nothing else would catch.
+// Through `jsonRetry` like everything else. This loop used to call `cli`
+// directly, and it is the last section of a run that takes minutes — so a
+// capture dropout here failed five checks about `--json` plumbing that was
+// working perfectly, while every earlier section shrugged the same dropout off.
+// The one place that did not retry was the one place most likely to need it.
 for (const args of [['status'], ['state'], ['mark'], ['ui'], ['screens'], ['devices'], ['doctor'], ['flow', 'list'], ['recall']]) {
   try {
-    const parsed = JSON.parse(await cli([...args, '--json']));
+    const parsed = await jsonRetry([...args]);
     check(parsed !== null && parsed !== undefined, `simframe ${args.join(' ')} --json`);
   } catch (err) {
     check(false, `simframe ${args.join(' ')} --json`, err.message.slice(0, 120));