simframe 0.11.0 → 0.12.0

package/README.md

@@ -636,9 +636,11 @@ simframe strip --count=6       # contact sheet, for an animation
 simframe doctor --strict       # any degraded layer is a non-zero exit
 simframe escalations           # why simframe still needs a model, by reason
 simframe escalations --session # ...this agent only, not every agent on the device
+simframe supervisions          # local supervisor rulings, and what came of each
 simframe hpi                   # speed and accuracy against a human baseline
 simframe baseline record settings-larger-text --runs=5   # record the human
 simframe input reset           # rebuild the HID session, without restarting anything
+simframe revive                # power-cycle a wedged device: stop, shutdown, boot, start, reset input
 simframe start / status / stop [--force] / devices
 simframe ui --device=emulator-5554      # or export SIMFRAME_DEVICE once
 ```
@@ -648,6 +650,48 @@ first: the space form set the flag to `true` and then resolved a device named
 "true", which is a poor answer to a flag `doctor`'s own advice tells you to
 type.
 
+### When the simulator stops rendering
+
+A simulator driven hard for several minutes can stop rendering: capture fails,
+`simctl screenshot` fails too, and the daemon's own recoveries — re-resolving the
+display port, then rebinding the device — do not help. It reports the state
+rather than acting on it, because a capture loop that rebooted the device it was
+watching would be a tool reaching for the mains:
+
+```
+capture is wedged and both recoveries are spent (2 port re-resolves, 2 device
+rebinds, no frame since). This needs the device restarted —
+`simframe revive --device=<udid>`. Backing off until a frame arrives.
+```
+
+`simframe revive` is that restart, in the order that matters — stop the daemon,
+shut the device down, boot it and *wait for the boot to finish*, start capture,
+rebuild the HID session — and it ends by checking frames are flowing again
+rather than by reporting that the steps ran. It is a command and not a
+behaviour: the decision stays yours.
+
+### Reading what the local supervisor decided
+
+With `SIMFRAME_SUPERVISOR=apple`, every consultation is written to
+`~/.simframe/<udid>/supervisions.jsonl` with what the executor observed
+afterwards, which is what makes a ruling scoreable rather than merely recorded.
+`simframe supervisions` reads it:
+
+```
+14 supervisor rulings on iPhone 17 Pro
+
+  stop -> stopped                    7
+  wait -> recovered                  5
+  wait -> still_failed               2
+
+sourced: model 14
+median latency: 1440ms
+edges the graph had timed: 0/14 — 14 ruling(s) are on edges with no p95
+```
+
+That last line is the honest one: a step that failed is usually a step that has
+never succeeded on that edge, so the graph has no timing to compare against.
+
 ### Keeping a session cheap
 
 The expensive part of driving a simulator with an agent is not the tapping, it

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

@@ -167,6 +167,9 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
     /// session survives. Input is warmed too, because a session that outlived
     /// its device is dead anyway.
     public func reattachDevice(udid: String?) throws -> DeviceInfo {
+        // Before the port reference goes, not after: unregistering needs the
+        // port it was registered on.
+        unregisterChangeCallback()
         device = nil
         display = nil
         return try attach(udid: udid)
@@ -183,6 +186,10 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
     }
 
     private func resolveDisplay(on device: NSObject, warmInput: Bool) throws -> DeviceInfo {
+        // This re-walks the same `ioPorts` array and frequently finds the *same*
+        // port object, so replacing `display` without releasing the callback on
+        // the outgoing one is how registrations accumulated on a single port.
+        unregisterChangeCallback()
         guard let io = device.value(forKey: "io") as? NSObject,
               let ports = io.value(forKey: "ioPorts") as? [NSObject] else {
             throw PrivateAPIError.noDisplayPort
@@ -359,6 +366,17 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
     /// to dismiss as broken.
     public func observeChanges(_ handler: @escaping () -> Void) throws {
         guard let display else { throw PrivateAPIError.noDisplayPort }
+        // Registration is not idempotent and this used to be called as though it
+        // were. Every call minted a fresh UUID and left the previous
+        // registration live, and the recovery loop calls it on every attempt:
+        // one log from 2026-09-12 shows **670 port re-resolves**, which is up to
+        // 670 damage callbacks registered on one port, each invoked per redraw
+        // (~52/s while an app switches).
+        //
+        // That is the best available explanation for a wedge that gets worse the
+        // longer it runs and that only a device restart cures — and it means the
+        // recovery was a cause as well as a response. Unregister first, always.
+        unregisterChangeCallback()
         let sel = NSSelectorFromString("registerCallbackWithUUID:damageRectanglesCallback:")
         guard display.responds(to: sel), let imp = display.method(for: sel) else {
             throw PrivateAPIError.frameworksUnavailable("damageRectanglesCallback missing")
@@ -371,7 +389,13 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
         unsafeBitCast(imp, to: RegFn.self)(display, sel, uuid, block as AnyObject)
     }
 
-    public func detach() {
+    /// Drop the damage callback we registered, if we registered one.
+    ///
+    /// Safe to call when there is nothing to drop, which is what lets both
+    /// `observeChanges` and the port-replacement paths call it unconditionally.
+    /// Unregisters against the port it was registered on — the one currently in
+    /// `display` — so it must run *before* that reference is replaced.
+    func unregisterChangeCallback() {
         if let display, let uuid = changeUUID {
             let sel = NSSelectorFromString("unregisterDamageRectanglesCallbackWithUUID:")
             if display.responds(to: sel), let imp = display.method(for: sel) {
@@ -381,6 +405,10 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
         }
         changeCallback = nil
         changeUUID = nil
+    }
+
+    public func detach() {
+        unregisterChangeCallback()
         display = nil
         attached = nil
     }

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

@@ -192,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
@@ -495,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)!)
                         }
@@ -510,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
@@ -552,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

@@ -121,11 +121,19 @@ func serve() async {
     are not being asked what to do, only whether this can proceed. Answer with \
     the decision alone.
     """
-    // A throwaway session up front so the first real judgement does not pay
-    // model load — measured at ~880ms against ~600ms warm.
-    _ = try? await LanguageModelSession(instructions: instructions)
-        .respond(to: "Step: warm\nIt failed with: warm", generating: Judgement.self)
-    emit(["ready": true])
+    // 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),
@@ -165,8 +173,35 @@ func serve() async {
                 "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)"])
+            emit(["error": "\(error)", "kind": "unknown"])
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.11.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": [

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))