simframe 0.10.0 → 0.12.0

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

@@ -105,6 +105,10 @@ extension StubPlatform {
     }
     public func type(_ text: String) throws { recorded.append("type(\(text))") }
     public func paste(_ text: String) throws { recorded.append("paste(\(text))") }
+    public func pressKey(usage: UInt32, modifiers: [UInt32]) throws {
+        throw PrivateAPIError.frameworksUnavailable("stub platform")
+    }
+
     public func press(_ button: HardwareButton) throws { recorded.append("press(\(button.rawValue))") }
     public func longPress(at point: CGPoint, durationMs: Double) throws {
         recorded.append("longPress(\(Int(point.x)),\(Int(point.y)),\(Int(durationMs)))")

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

@@ -75,6 +75,25 @@ public struct CaptureRecovery {
         reattaches >= Self.stalledAfterReattaches && rebinds < Self.maxRebinds
     }
 
+    /// Both rungs of the ladder have been tried and no frame has arrived since.
+    ///
+    /// What happens after the ladder runs out was left implicit, and the
+    /// implicit answer was "go back to the bottom rung forever". Measured from a
+    /// real wedge: **670 re-resolves against 42 rebinds** in one log. Once
+    /// `rebinds` hits `maxRebinds` — and it only resets on a real frame —
+    /// `needsRebind` is false for good, so every sixth failure re-resolved a
+    /// port that two rebinds had already proved was not the problem, at 600ms a
+    /// go, each time logging a message that calls the condition "usually
+    /// transient".
+    ///
+    /// That is why a wedged device reads as the tool hanging rather than the
+    /// tool reporting. The state is unchanged in spirit — the daemon still only
+    /// reports, and restarting the device stays the operator's call — but it can
+    /// stop pretending it has something left to try.
+    public var recoveryExhausted: Bool {
+        rebinds >= Self.maxRebinds && reattaches >= Self.stalledAfterReattaches
+    }
+
     public mutating func captureSucceeded() {
         consecutiveFailures = 0
         // A real frame is the only evidence that health is back. Resetting this

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

@@ -122,7 +122,7 @@ case "input":
         print("     \(device.name): \(device.pixelWidth)x\(device.pixelHeight)px @\(device.scale)x = \(device.pointWidth)x\(device.pointHeight)pt")
     } catch { fail("\(error)") }
 
-case "tap", "swipe", "type", "paste", "press":
+case "tap", "swipe", "type", "paste", "press", "key":
     do {
         _ = try platform.attach(udid: flag("udid"))
         let positional = args.filter { !$0.hasPrefix("--") }.dropFirst()
@@ -141,6 +141,11 @@ case "tap", "swipe", "type", "paste", "press":
         case "type":
             guard !positional.isEmpty else { fail("usage: simframed type <text>") }
             try platform.type(positional.joined(separator: " "))
+        case "key":
+            guard let u = positional.first, let usage = UInt32(u) else {
+                fail("usage: simframed key <hid-usage-code>")
+            }
+            try platform.pressKey(usage: usage, modifiers: [])
         case "paste":
             guard !positional.isEmpty else { fail("usage: simframed paste <text>") }
             try platform.paste(positional.joined(separator: " "))
@@ -187,6 +192,8 @@ case "run":
         var dirty = true
         var recovery = CaptureRecovery()
         var stalledSince: Double?
+        /// Said once per stall episode, not once per failed read.
+        var announcedExhausted = false
         var lastCapture = 0.0
         var frames = 0
         var lastReport = Date().timeIntervalSince1970
@@ -404,6 +411,13 @@ case "run":
                     }
                     try platform.press(button)
                     return done()
+                case "key":
+                    guard let usage = request["usage"] as? NSNumber else {
+                        return ["ok": false, "error": "key needs a HID usage code"]
+                    }
+                    let mods = (request["modifiers"] as? [NSNumber])?.map { $0.uint32Value } ?? []
+                    try platform.pressKey(usage: usage.uint32Value, modifiers: mods)
+                    return done()
                 case "resetInput":
                     try platform.resetInput()
                     FileHandle.standardError.write("simframed: HID session reset on request\n".data(using: .utf8)!)
@@ -483,6 +497,7 @@ case "run":
                             // back on its own, which nobody would otherwise know.
                             try? store.writeCaptureHealth(nil)
                             stalledSince = nil
+                            announcedExhausted = false
                             FileHandle.standardError.write(
                                 "simframed: capture recovered on its own\n".data(using: .utf8)!)
                         }
@@ -498,7 +513,19 @@ case "run":
                         // by restarting the daemon. Reporting a failure loudly is
                         // right; never recovering from it is not, so re-resolve the
                         // port and re-arm the damage callback.
-                        if due {
+                        // Nothing left to try is a thing to say once, not a
+                        // rung to keep pulling. See `recoveryExhausted`.
+                        if due && recovery.recoveryExhausted {
+                            if !announcedExhausted {
+                                announcedExhausted = true
+                                FileHandle.standardError.write(
+                                    ("simframed: capture is wedged and both recoveries are spent"
+                                     + " (\(recovery.reattaches) port re-resolves, \(recovery.rebinds) device rebinds,"
+                                     + " no frame since). This needs the device restarted —"
+                                     + " `simframe revive --device=<udid>`. Backing off until a frame arrives.\n")
+                                        .data(using: .utf8)!)
+                            }
+                        } else if due {
                             let onDamage = { lock.lock(); dirty = true; lock.unlock() }
                             // Escalate rather than repeat. Two successful re-resolves
                             // with no frame between them means the port was never the
@@ -540,7 +567,10 @@ case "run":
                                 "reason": "\(error)",
                             ])
                         }
-                        Thread.sleep(forTimeInterval: 0.5)
+                        // Back off once there is nothing left to attempt. Half a
+                        // second forever on a dead display is pure heat, and the
+                        // log it produced buried everything else in the file.
+                        Thread.sleep(forTimeInterval: recovery.recoveryExhausted ? 5.0 : 0.5)
                     }
                 }
             }

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

@@ -397,4 +397,45 @@ final class CaptureRecoveryTests: XCTestCase {
         XCTAssertEqual(recovery.consecutiveFailures, 2, "the run is not cleared by an attempt that did not work")
         XCTAssertTrue(recovery.captureFailed(), "so the next failure tries again immediately")
     }
+
+    /// What happens when the ladder runs out, which was previously implicit —
+    /// and the implicit answer was "start again at the bottom, forever".
+    func testAnExhaustedLadderStopsPretendingItHasSomethingLeft() {
+        let platform = StubPlatform()
+        var recovery = CaptureRecovery(threshold: 1)
+        XCTAssertFalse(recovery.recoveryExhausted, "nothing has been tried yet")
+
+        // Two re-resolves that each succeed and change nothing: this is the
+        // pathology, not a hypothetical. The port hands back a fresh descriptor
+        // and every read still fails.
+        for _ in 0..<CaptureRecovery.stalledAfterReattaches {
+            _ = recovery.captureFailed()
+            guard case .success = recovery.reattach(platform: platform, onDamage: {}) else {
+                return XCTFail("the stub re-resolves")
+            }
+        }
+        XCTAssertTrue(recovery.needsRebind, "so the escalation is due")
+        XCTAssertFalse(recovery.recoveryExhausted, "but the ladder has a second rung")
+
+        for _ in 0..<CaptureRecovery.maxRebinds {
+            _ = recovery.captureFailed()
+            guard case .success = recovery.rebind(platform: platform, udid: "UDID", onDamage: {}) else {
+                return XCTFail("the stub rebinds")
+            }
+        }
+        XCTAssertFalse(recovery.needsRebind, "the rebinds are spent")
+        XCTAssertTrue(recovery.recoveryExhausted, "and so is the ladder")
+
+        // Measured from a real wedge: 670 port re-resolves against 42 rebinds in
+        // one log, because this state fell back to the bottom rung every sixth
+        // failure at 600ms a go, each time logging "usually transient".
+        _ = recovery.captureFailed()
+        XCTAssertTrue(recovery.recoveryExhausted, "more failures do not restore an option")
+
+        // A real frame is the only thing that resets it, exactly as for the rest
+        // of this machine — a re-resolve must never look like recovery.
+        recovery.captureSucceeded()
+        XCTAssertFalse(recovery.recoveryExhausted, "a frame is the only evidence health is back")
+        XCTAssertFalse(recovery.isStalled)
+    }
 }

package/native/supervise.swift

@@ -0,0 +1,216 @@
+// The local supervisor, and it may say exactly three things.
+//
+// Claude plans. The deterministic executor in src/actions.js runs the plan and
+// verifies each step — round 6's best result was 18 steps in one call, and code
+// is a better executor than a model: faster, exact, auditable, and it cannot
+// hallucinate a step. What the executor has never had is judgement at the
+// moment a step fails, so a batch died and a round trip was spent on a decision
+// that was usually obvious.
+//
+// This answers that moment and nothing else:
+//
+//   in   {"goal":"...","step":"tap REVIEW","expected":"...","failure":"...","screen":["…labels…"],"stillMs":120}
+//   out  {"decision":"wait","ms":410}
+//
+// `wait`, `retry`, `stop`. It cannot invent a step, skip one, substitute a
+// target, or continue past an unexpected screen — not because a threshold
+// forbids it but because those are not words it can say. That constraint is the
+// safety property. `seek` was given latitude over *what* to open and pressed
+// "YES, THIS FIXED MY PROBLEM" in a live app; a component whose whole answer
+// space is three words cannot do that whatever it believes.
+//
+// Unavailable is a normal answer. It says so and exits, `doctor` reports
+// `supervisor: none`, and the executor behaves exactly as it does today.
+import Foundation
+#if canImport(FoundationModels)
+import FoundationModels
+
+@available(macOS 26.0, *)
+@Generable
+enum Decision: String {
+    case wait
+    case retry
+    case stop
+}
+
+@available(macOS 26.0, *)
+@Generable
+struct Judgement {
+    @Guide(description: "wait if the screen is still arriving, retry if the same step should be attempted again, stop if nothing further can work")
+    var decision: Decision
+}
+
+struct Situation: Decodable {
+    let goal: String?
+    let step: String
+    let expected: String?
+    let failure: String
+    let screen: [String]?
+    let stillMs: Int?
+    let note: String?
+}
+
+func emit(_ object: [String: Any]) {
+    guard let data = try? JSONSerialization.data(withJSONObject: object),
+          let line = String(data: data, encoding: .utf8) else { return }
+    print(line)
+    fflush(stdout)
+}
+
+@available(macOS 26.0, *)
+func serve() async {
+    switch SystemLanguageModel.default.availability {
+    case .available: break
+    case .unavailable(let reason):
+        emit(["unavailable": "\(reason)"])
+        return
+    @unknown default:
+        emit(["unavailable": "unknown availability"])
+        return
+    }
+    // Instructions, reused; the *session* is not.
+    //
+    // One session reused across requests is what made the supervisor go silent
+    // in the field: `LanguageModelSession` accumulates its transcript, so after
+    // seven real failures it hit `exceededContextWindowSize` — 4,441 tokens
+    // against a 4,096 maximum — and every request after that errored. The tester
+    // saw three rulings and then nothing for twenty supervised calls, while
+    // `doctor` in a separate process kept reporting the model available. It
+     // degraded before it broke, too: latency climbed 987ms to 1,890ms as the
+    // transcript grew, and the reasons collapsed into boilerplate repeated
+    // verbatim across unrelated failures.
+    //
+    // Each judgement is independent by nature — a failed step, what was
+    // expected, what is on screen — so there is nothing for a transcript to
+    // carry, and carrying it was pure cost even before it was fatal. The process
+    // stays warm, which is where the model load is paid; only the conversation
+    // is fresh.
+    let instructions = """
+    You supervise a UI test that is running a plan someone else wrote. A step \
+    has just failed. Decide one of three things and nothing else.
+
+    wait  — the screen is still arriving: a spinner, a list that has not \
+    rendered, a count header with no rows, a transition in progress. Waiting \
+    would let the same step succeed.
+    retry — the step is sound and the moment was wrong: something moved under \
+    it, focus was lost, a stale reading. Repeating it would work.
+    stop  — nothing further in the plan can work: the app is somewhere else, a \
+    required control is absent or disabled for a reason, or the screen has not \
+    responded at all.
+
+    Weigh the evidence you are given, in this order.
+
+    The plan's own guidance about this app comes FIRST and outranks everything \
+    below. It is the only knowledge of this app you have, and it was written by \
+    someone who has seen it. If it says lists arrive late, then a row that is \
+    not there yet means wait — even on a screen that has gone completely still, \
+    because a screen waiting on a network call is perfectly still and perfectly \
+    empty.
+
+    If a note says the screen is still filling in — a spinner, a count header \
+    with too few rows, a transition — that is decisive: answer wait.
+    If the screen has been still for under about 1500ms, content may still be \
+    arriving: prefer wait.
+    If the visible labels belong to a different part of the app than the step \
+    implies, answer stop.
+    If a control the step names is present but refused, answer stop.
+    Otherwise, if the step looks like it simply caught a bad moment, answer \
+    retry.
+
+    Never suggest a different step, a different target, or skipping ahead. You \
+    are not being asked what to do, only whether this can proceed. Answer with \
+    the decision alone.
+    """
+    // Warm up front so the first real judgement does not pay model load —
+    // measured at ~880ms against ~600ms warm.
+    //
+    // `prewarm()` is the supported way and this used to be a throwaway
+    // `respond`, which loaded the same weights the hard way and paid a whole
+    // generation to do it. Warming a session we then discard works because
+    // residency is process- and system-managed: the expensive part outlives the
+    // session, which is also why fresh-session-per-judgement is affordable.
+    LanguageModelSession(instructions: instructions).prewarm()
+    // The window, reported rather than assumed. 4,096 has been a documented
+    // constant we repeated; since 26.4 it is queryable, so it is now read from
+    // the model and handed to the caller, who prints it in `doctor`.
+    emit(["ready": true, "contextSize": SystemLanguageModel.default.contextSize])
+    while let line = readLine(strippingNewline: true) {
+        if line.isEmpty { continue }
+        guard let data = line.data(using: .utf8),
+              let s = try? JSONDecoder().decode(Situation.self, from: data) else {
+            emit(["error": "could not parse that line"])
+            continue
+        }
+        // Capped here as well as in the caller. A single realistic failure
+        // message carries the whole "Visible: …" list, and one request built
+        // from raw input measured 4,266 tokens against a 4,096 window — so a
+        // request can exceed the context on its own, with no transcript
+        // involved at all. Truncation belongs where the limit is.
+        let clip = { (t: String, n: Int) in t.count > n ? String(t.prefix(n)) + "…" : t }
+        var prompt = "Step: \(clip(s.step, 120))\nIt failed with: \(clip(s.failure, 220))"
+        if let goal = s.goal, !goal.isEmpty { prompt += "\nThe plan's guidance about this app: \(clip(goal, 300))" }
+        if let expected = s.expected, !expected.isEmpty { prompt += "\nExpected: \(clip(expected, 200))" }
+        if let ms = s.stillMs { prompt += "\nThe screen has been still for \(ms)ms" }
+        if let note = s.note, !note.isEmpty { prompt += "\nPerception note: \(clip(note, 160))" }
+        if let screen = s.screen, !screen.isEmpty {
+            prompt += "\nOn screen now: \(screen.prefix(14).map { clip($0, 28) }.joined(separator: ", "))"
+        }
+        let started = Date()
+        do {
+            let session = LanguageModelSession(instructions: instructions)
+            let out = try await session.respond(to: prompt, generating: Judgement.self)
+            // No reason field, deliberately. Asked for one it confabulated in
+            // every observed run: a correct `stop` justified as "screen is
+            // elsewhere" when the screen was exactly where the plan expected,
+            // and reasons repeated verbatim across unrelated failures. The
+            // reporter's judgement, and it is right — *"a right answer with a
+            // fabricated justification teaches me to distrust the
+            // justification, which is most of the value of it explaining
+            // itself. No reason at all would be better than a confident wrong
+            // one."* What the caller gets instead is which rule or which model
+            // answered, which is true by construction.
+            emit([
+                "decision": out.content.decision.rawValue,
+                "ms": Int(Date().timeIntervalSince(started) * 1000),
+            ])
+        } catch let err as LanguageModelSession.GenerationError {
+            // Named, not merely stringified, because the cases mean different
+            // things to whoever reads the log — and because a string match on
+            // an error message is a classification that silently becomes
+            // "unknown" the day Apple rewords it.
+            //
+            // Deliberately NOT a retry policy. The research that asked for this
+            // warned that a blanket retry burns battery on the permanent cases,
+            // and checking found we never retry at all: `ask` resolves null on
+            // any error and `judge` refuses anything outside the three words. So
+            // what these buy is a diagnosis, which is what was actually missing
+            // — every failure reached the log as "the supervisor did not answer".
+            let kind: String
+            switch err {
+            // Our own bug if it appears: the caller clips every field and the
+            // worst case those caps allow measures 1,918 tokens of 4,096.
+            case .exceededContextWindowSize: kind = "context-window"
+            // Permanent for this input. Retrying cannot help and it says so.
+            case .guardrailViolation: kind = "guardrail"
+            case .unsupportedLanguageOrLocale: kind = "locale"
+            // A session takes one request at a time. The line protocol here
+            // serialises them and each gets a fresh session, so this should be
+            // unreachable — worth knowing loudly if it ever is not.
+            case .rateLimited: kind = "rate-limited"
+            default: kind = "generation"
+            }
+            emit(["error": "\(err)", "kind": kind])
+        } catch {
+            emit(["error": "\(error)", "kind": "unknown"])
+        }
+    }
+}
+
+if #available(macOS 26.0, *) {
+    await serve()
+} else {
+    emit(["unavailable": "the on-device model needs macOS 26 or newer"])
+}
+#else
+print("{\"unavailable\":\"this toolchain cannot import FoundationModels\"}")
+#endif

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.10.0",
+  "version": "0.12.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": [
@@ -42,8 +42,11 @@
   },
   "files": [
     "src",
+    "data",
     "flows",
     "native/ocr.swift",
+    "native/rank.swift",
+    "native/supervise.swift",
     "native/simframed/Package.swift",
     "native/simframed/Sources",
     "native/simframed/Tests",

package/scripts/check-package.mjs

@@ -60,8 +60,28 @@ function requiredFiles() {
     throw new Error('no Swift test sources found — has the layout moved? This check would silently pass.');
   }
 
-  // The standalone OCR helper, compiled on demand by src/ocr.js.
-  required.add(rel(path.join(ROOT, 'native', 'ocr.swift')));
+  // Every standalone Swift helper compiled on demand from `src/`.
+  //
+  // This listed `native/ocr.swift` by name, which is why it did not catch the
+  // next two: `rank.swift` and `supervise.swift` were absent from `files`, so
+  // the local planner and the local supervisor would have been silently
+  // unavailable for every installed user — the exact failure this whole check
+  // exists to prevent, reproduced because the check named one file instead of
+  // stating the rule.
+  //
+  // The rule is: if a module under `src/` compiles it, it has to ship.
+  const helpers = walk(path.join(ROOT, 'native'), (p) => p.endsWith('.swift'))
+    .filter((p) => !p.includes(`${path.sep}simframed${path.sep}`) && !p.includes(`${path.sep}spikes${path.sep}`));
+  if (!helpers.length) {
+    throw new Error('no standalone Swift helper found under native/ — has the layout moved? This check would silently pass.');
+  }
+  const sources = walk(path.join(ROOT, 'src'), (p) => p.endsWith('.js'))
+    .map((f) => fs.readFileSync(f, 'utf8')).join('\n');
+  for (const helper of helpers) {
+    const name = path.basename(helper);
+    if (!sources.includes(name)) continue; // not compiled by anything; not required
+    required.add(rel(helper));
+  }
 
   // Every runtime module. `files` ships "src" wholesale today; asserting each
   // one catches anybody narrowing that later.

package/scripts/check-private.mjs

@@ -53,6 +53,15 @@ export const ALLOWED = [
   /^com\.google\./i,
   /^org\.swift\./i,
   /^org\.json\./i,
+  // Build-tool namespaces, not app identifiers — and they arrive by the
+  // hundred the moment an Android project exists. `org.jetbrains.kotlin.android`
+  // is a Gradle plugin id, `org.jetbrains.kotlin:kotlin-gradle-plugin` a Maven
+  // coordinate, and `org.gradle.jvmargs` is a *property name* that merely looks
+  // like a bundle id. Added when the React Native testbed landed and flagged
+  // four of them; same judgement as the two lines above, which are Swift's and
+  // JSON's own namespaces rather than anybody's app.
+  /^org\.jetbrains\./i,
+  /^org\.gradle\./i,
   /^com\.facebook\./i,     // idb, a reference implementation named in the docs
   /^com\.example\./i,
   /^com\.acme\./i,

package/scripts/ci-integration-local.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# The `integration` job, run here instead of there.
+#
+# One round trip on a hosted runner is 30+ minutes, and cancel-in-progress means
+# a second push while you wait throws the answer away. Most of what that job
+# asserts is reproducible on a developer's own simulator in a couple of minutes,
+# so there is no reason to learn it from GitHub.
+#
+# What it cannot reproduce is the runner's *speed*: this machine settles a
+# screen in a few hundred milliseconds where a loaded hosted runner has taken
+# 45s for a two-step flow. So a green run here means "the code is right", not
+# "CI will pass" — see DEFERRED 95. Everything else that has gone red, including
+# the fingerprint collision that took an evening to find, would have shown up in
+# this script.
+#
+#   ./scripts/ci-integration-local.sh <udid>
+#
+# Assumes the device is booted and `simframe start` has been run on it, exactly
+# as the job's earlier steps do.
+set -u
+DEVICE="${1:?usage: ci-integration-local.sh <udid>}"
+cd "$(dirname "$0")/.." || exit 1
+fails=0
+step() { printf '\n=== %s ===\n' "$1"; }
+ok()   { printf 'ok   %s\n' "$1"; }
+bad()  { printf 'FAIL %s\n' "$1"; fails=$((fails+1)); }
+
+export SIMFRAME_STRICT=1
+
+step "Every layer is the good one, or this fails"
+node src/cli.js doctor --json --device="$DEVICE" > /tmp/doctor-local.json 2>/dev/null
+node -e '
+const d = JSON.parse(require("fs").readFileSync("/tmp/doctor-local.json", "utf8"));
+const want = { "capture.engine": "simframed", "ocr.available": true };
+let failed = false;
+for (const [k, v] of Object.entries(want)) {
+  const good = d[k] === v;
+  console.log(`${good ? "ok  " : "FAIL"} ${k} = ${JSON.stringify(d[k])} (want ${JSON.stringify(v)})`);
+  if (!good) failed = true;
+}
+for (const key of ["input.driver", "ax.driver"]) {
+  const good = d[key] === "simframed";
+  console.log(`${good ? "ok  " : "FAIL"} ${key} = ${JSON.stringify(d[key])} (want "simframed")`);
+  if (!good) failed = true;
+}
+if (d.warnings > 0) {
+  console.log(`\n${d.warnings} degraded layer(s):`);
+  for (const c of d.checks.filter((c) => c.level !== "ok")) console.log(`  ${c.level} ${c.name}: ${c.detail}`);
+}
+process.exit(failed ? 1 : 0);
+' && ok "doctor: every layer is the daemon" || bad "doctor"
+
+step "A step runs, and capture notices the screen change"
+read_state() {
+  node src/cli.js state --device="$DEVICE" --json \
+    | node -e 'const s=JSON.parse(require("fs").readFileSync(0,"utf8")); process.stdout.write(s.hash+" "+s.seq)'
+}
+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
+
+step "The memory layer — screen map, refs, graph, verdicts, flows"
+node scripts/ci-memory.mjs --device="$DEVICE" && ok "ci-memory" || bad "ci-memory"
+
+step "The fingerprint distributions, measured and bounded"
+node scripts/eval-fingerprint.mjs --tour=test/tours/device-native.json --rounds=3 \
+  --device="$DEVICE" --out=/tmp/fp-local-ci.json --label=local-ci >/tmp/fp-out.txt 2>&1 \
+  && ok "fingerprint distributions" || { bad "fingerprint distributions"; tail -25 /tmp/fp-out.txt; }
+
+printf '\n=== %s failure(s) ===\n' "$fails"
+exit $((fails > 0))