simframe 0.7.2 → 0.9.0

package/README.md

@@ -37,6 +37,7 @@ Same four-tab navigation flow, on a real production app:
 | | Before | With simframe |
 | --- | --- | --- |
 | Look at the screen | ~130–400 ms, blocking | **~20 ms**, already captured |
+
 | "Did anything change?" | a full image | **~2 ms**, text only |
 | Finding a control | read tree (~570 ms) + reason | **~1 ms** from memory |
 | A 4-step flow, verified | 4+ model round trips | **1 call**, 3.6 s |
@@ -44,6 +45,13 @@ Same four-tab navigation flow, on a real production app:
 | A 10-step flow | 10 turns, 10 images (~16,000 tokens at best) | **1 turn, 0 images, ~1,650 characters** |
 | Reading a screen | an image: ~1,600 tokens, no tap points | **~330 tokens** of text, with tap points |
 
+Every figure above is the cost inside a live process — the MCP server, or the
+daemon answering a socket — which is how an agent actually uses simframe. A
+one-shot `simframe` command from a shell pays about 200 ms of Node startup on
+top, and a frame sitting on an idle screen can be older than 20 ms because the
+capture loop throttles when nothing moves. `~20 ms` is the read, not the
+process.
+
 The four-tab tour, three times back to back from a cleared memory:
 
 | Pass | Wall clock | Steps verified | Controls from memory |
@@ -67,10 +75,16 @@ npm install -g simframe
 simframe doctor
 ```
 
-The first `simframe start` builds a small Swift daemon from source — a few
-seconds, once. It needs the Xcode command line tools, which you already have if
-you have a simulator. Without them simframe falls back to the original
-`simctl` loop and says so.
+**Whichever of those two commands you run first** builds a small Swift daemon
+from source — including `doctor`, which is why a cold `doctor` takes around 15
+seconds and every later one takes two. It needs the Xcode command line tools,
+which you already have if you have a simulator. Without them simframe falls
+back to the original `simctl` loop and says so.
+
+If more than one simulator is booted, name the one you mean — `--device=<udid>`,
+or `export SIMFRAME_DEVICE=<udid>` once per shell. simframe refuses to choose
+for you, because the first booted device is nobody's idea of "yours" and the
+command that would act on it is a tap.
 
 `doctor` checks each capability separately and tells you what you have:
 
@@ -527,6 +541,9 @@ simframe recall --ago=15000    # the frame from 15s ago
 simframe frame --out=now.png   # newest frame, native resolution, to a file
 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 hpi                   # speed and accuracy against a human baseline
+simframe baseline record settings-larger-text --runs=5   # record the human
 simframe start / status / stop [--force] / devices
 simframe ui --device=emulator-5554      # or export SIMFRAME_DEVICE once
 ```

package/flows/hpi-suite.json

@@ -0,0 +1,68 @@
+[
+  {
+    "name": "settings-larger-text",
+    "note": "Four steps into a nested Settings list. The two Settings sublists are the fingerprint pair that needs a nav title to tell them apart, so this flow exercises screen identity as well as navigation.",
+    "minSteps": 4,
+    "endsOn": "Larger Text",
+    "human": [
+      "Tap Settings on the home screen.",
+      "Tap Accessibility.",
+      "Tap Display & Text Size.",
+      "Tap Larger Text, and stop there."
+    ],
+    "reset": {
+      "terminate": [
+        "com.apple.Preferences"
+      ],
+      "home": true,
+      "launch": "com.apple.Preferences",
+      "rootMarker": "Accessibility",
+      "maxBack": 4
+    },
+    "steps": [
+      {
+        "launch": {
+          "value": "com.apple.Preferences"
+        }
+      },
+      {
+        "tap": "Accessibility"
+      },
+      {
+        "tap": "Display & Text Size"
+      },
+      {
+        "tap": "Larger Text"
+      }
+    ]
+  },
+  {
+    "name": "contacts-kate-bell",
+    "note": "An indexed list with a search field, two steps deep. Short on purpose: a flow this shallow is where a per-step overhead shows up as a ratio rather than being absorbed by navigation.",
+    "minSteps": 2,
+    "endsOn": "Kate Bell",
+    "human": [
+      "Tap Contacts on the home screen.",
+      "Tap Kate Bell, and stop there."
+    ],
+    "reset": {
+      "terminate": [
+        "com.apple.MobileAddressBook"
+      ],
+      "home": true,
+      "launch": "com.apple.MobileAddressBook",
+      "rootMarker": "Kate Bell",
+      "maxBack": 3
+    },
+    "steps": [
+      {
+        "launch": {
+          "value": "com.apple.MobileAddressBook"
+        }
+      },
+      {
+        "tap": "Kate Bell"
+      }
+    ]
+  }
+]

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

@@ -157,6 +157,21 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
         return try resolveDisplay(on: device, warmInput: true)
     }
 
+    /// Rebind to the device from scratch: a fresh device object, a fresh port.
+    ///
+    /// `reattachDisplay` reuses the cached `device`, which is right for a port
+    /// that was rebuilt under a living device and wrong for everything else —
+    /// the device object itself can be stale after a restart, and re-walking
+    /// its `ioPorts` then re-finds the same dead descriptors. This asks
+    /// CoreSimulator for the device list again, so nothing from the previous
+    /// session survives. Input is warmed too, because a session that outlived
+    /// its device is dead anyway.
+    public func reattachDevice(udid: String?) throws -> DeviceInfo {
+        device = nil
+        display = nil
+        return try attach(udid: udid)
+    }
+
     /// Re-resolve the display port on the device we are already bound to.
     ///
     /// Input is deliberately left alone: the HID session is independent of the
@@ -180,15 +195,36 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
         let sizeSel = NSSelectorFromString("displaySize")
         typealias SizeFn = @convention(c) (AnyObject, Selector) -> CGSize
 
+        // Two passes, because a size is a claim and a surface is evidence.
+        //
+        // A torn-down port keeps reporting a real `displaySize` while
+        // `framebufferSurface` returns nil for the rest of the device's life.
+        // Selecting on size alone therefore reattached to the dead port and
+        // declared success: the daemon logged "re-resolved the display port
+        // after 6 failed reads" and then failed six more, in a loop, until the
+        // device was restarted. That is the pathology CaptureRecovery's
+        // `stalledAfterReattaches` exists to *notice*; this is what fixes it.
+        //
+        // The size check stays as the cheap pre-filter. The second pass is the
+        // one that decides, and if no candidate yields a surface the first
+        // plausible one is used anyway — during boot the port is real and the
+        // surface has simply not arrived yet, and refusing to attach then
+        // would trade a recoverable wedge for a daemon that never starts.
+        var candidates: [NSObject] = []
         for port in ports {
             guard port.responds(to: descriptorSel),
                   let descriptor = port.perform(descriptorSel)?.takeUnretainedValue() as? NSObject,
                   descriptor.conforms(to: proto),
                   descriptor.responds(to: sizeSel),
                   let sizeImp = descriptor.method(for: sizeSel) else { continue }
-            // Several ports conform; only the live one reports a real size.
             let size = unsafeBitCast(sizeImp, to: SizeFn.self)(descriptor, sizeSel)
             guard size.width > 0, size.height > 0 else { continue }
+            candidates.append(descriptor)
+        }
+        let live = candidates.first(where: Self.yieldsSurface) ?? candidates.first
+        for descriptor in candidates where descriptor === live {
+            let sizeImp = descriptor.method(for: sizeSel)!
+            let size = unsafeBitCast(sizeImp, to: SizeFn.self)(descriptor, sizeSel)
             display = descriptor
             // The bridge captures one device's token and installs itself on a
             // process-wide translator, so it belongs to the device it was built
@@ -259,6 +295,18 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
         }
     }
 
+    /// Does this display descriptor actually produce a framebuffer?
+    ///
+    /// The single question that separates a live port from a torn-down one, and
+    /// it is not the one the resolver used to ask. Cheap: one selector call and
+    /// a cast, no lock, no pixels read.
+    static func yieldsSurface(_ descriptor: NSObject) -> Bool {
+        guard descriptor.responds(to: NSSelectorFromString("framebufferSurface")),
+              let raw = descriptor.perform(NSSelectorFromString("framebufferSurface"))?.takeUnretainedValue()
+        else { return false }
+        return raw is IOSurface
+    }
+
     public func withFrame<T>(_ body: (RawFrame) throws -> T) throws -> T {
         guard let display else { throw PrivateAPIError.noDisplayPort }
         guard let raw = display.perform(NSSelectorFromString("framebufferSurface"))?.takeUnretainedValue(),

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

@@ -84,6 +84,13 @@ public protocol SimulatorPlatform: AnyObject {
     /// perfectly visible, and a daemon restart fixed it instantly. Without a
     /// way to re-resolve, a restart is the only cure.
     func reattachDisplay() throws -> DeviceInfo
+    /// Rebind from scratch: a fresh device object as well as a fresh port.
+    ///
+    /// The escalation for when re-resolving the port has demonstrably not
+    /// helped. `reattachDisplay` re-walks the cached device's ports, which
+    /// re-finds the same dead descriptors when it is the device binding that
+    /// is stale.
+    func reattachDevice(udid: String?) throws -> DeviceInfo
     /// Borrow the current framebuffer. The pointer is only valid inside `body`.
     func withFrame<T>(_ body: (RawFrame) throws -> T) throws -> T
     /// Called whenever the display reports damage — the per-redraw signal, so a

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

@@ -33,6 +33,10 @@ public final class StubPlatform: SimulatorPlatform {
     /// Counted so a test can assert the capture loop actually tries to recover
     /// rather than logging the same failure forever.
     public private(set) var reattachCount = 0
+    /// Full rebinds, counted separately: the escalation is a different act
+    /// from re-resolving a port and a test that cannot tell them apart cannot
+    /// assert the escalation happened.
+    public private(set) var rebindCount = 0
     private var attachedUdid: String?
 
     /// Counted, so a test can assert that a dead input path is actually retried.
@@ -50,6 +54,13 @@ public final class StubPlatform: SimulatorPlatform {
         return DeviceInfo(udid: attachedUdid ?? "STUB-0000", name: "Stub Device", runtime: "iOS 26.0")
     }
 
+    public func reattachDevice(udid: String?) throws -> DeviceInfo {
+        rebindCount += 1
+        if failReattach { throw PrivateAPIError.noDisplayPort }
+        attachedUdid = udid ?? attachedUdid
+        return DeviceInfo(udid: attachedUdid ?? "STUB-0000", name: "Stub Device", runtime: "iOS 26.0")
+    }
+
     public func withFrame<T>(_ body: (RawFrame) throws -> T) throws -> T {
         let bytesPerRow = width * 4 + 40   // deliberate padding: mirrors real surfaces
         if buffer.count != bytesPerRow * height {

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

@@ -36,9 +36,19 @@ public struct CaptureRecovery {
     /// failure count does keep growing because nothing resets it.
     public static let stalledAfterFailures = reattachAfterFailures * 3
 
+    /// How many times to rebind the device per stall episode.
+    ///
+    /// Bounded because a rebind asks CoreSimulator for the whole device list
+    /// and warms input: worth doing when re-resolving has failed twice, not
+    /// worth doing every half second forever. Two attempts, then the loop goes
+    /// back to reporting the state it is in.
+    public static let maxRebinds = 2
+
     public private(set) var consecutiveFailures = 0
     /// Successful re-resolves since the last real frame.
     public private(set) var reattaches = 0
+    /// Full rebinds since the last real frame.
+    public private(set) var rebinds = 0
     private let threshold: Int
 
     public init(threshold: Int = CaptureRecovery.reattachAfterFailures) {
@@ -54,12 +64,24 @@ public struct CaptureRecovery {
         reattaches >= Self.stalledAfterReattaches || consecutiveFailures >= Self.stalledAfterFailures
     }
 
+    /// Has re-resolving the port had its chance?
+    ///
+    /// Two successful re-resolves with no frame between them is the port
+    /// telling us it was never the problem. That was already the *stalled*
+    /// signal; now it is also the trigger to try the one thing that had only
+    /// ever been done by hand — rebinding to the device, which is what
+    /// restarting the daemon did.
+    public var needsRebind: Bool {
+        reattaches >= Self.stalledAfterReattaches && rebinds < Self.maxRebinds
+    }
+
     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
+        rebinds = 0
     }
 
     /// Records a failure and says whether the port is now due a re-resolve.
@@ -91,4 +113,30 @@ public struct CaptureRecovery {
             return .failure(error)
         }
     }
+
+    /// Rebind to the device itself, and re-arm the callback on the new port.
+    ///
+    /// The escalation `needsRebind` gates. Re-arming matters here for the same
+    /// reason it does in `reattach`: a fresh descriptor with no callback on it
+    /// is a daemon that has recovered and will never notice another change,
+    /// which looks exactly like the failure it just recovered from.
+    public mutating func rebind(
+        platform: SimulatorPlatform,
+        udid: String?,
+        onDamage: @escaping () -> Void
+    ) -> Result<Int, Error> {
+        let failures = consecutiveFailures
+        rebinds += 1
+        do {
+            _ = try platform.reattachDevice(udid: udid)
+            try platform.observeChanges(onDamage)
+            consecutiveFailures = 0
+            // `reattaches` is deliberately left alone. It is the evidence that
+            // the port was not the problem, and a rebind does not make that
+            // untrue — only a real frame does, in captureSucceeded().
+            return .success(failures)
+        } catch {
+            return .failure(error)
+        }
+    }
 }

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

@@ -3,6 +3,25 @@ import Foundation
 import PrivateAPI
 import SimframeCore
 
+/// Resident size of this process, in bytes, or 0 if the kernel will not say.
+///
+/// Logged with throughput because the capture wedge has no established cause
+/// and memory pressure is one of two candidates. A number in the log every
+/// second is what lets the next wedge be correlated with a spike — or clear
+/// memory of suspicion, which is just as useful.
+func residentBytes() -> UInt64 {
+    var info = mach_task_basic_info()
+    var count = mach_msg_type_number_t(
+        MemoryLayout<mach_task_basic_info>.size / MemoryLayout<natural_t>.size
+    )
+    let result = withUnsafeMutablePointer(to: &info) { pointer in
+        pointer.withMemoryRebound(to: integer_t.self, capacity: Int(count)) { rebound in
+            task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), rebound, &count)
+        }
+    }
+    return result == KERN_SUCCESS ? info.resident_size : 0
+}
+
 let args = Array(CommandLine.arguments.dropFirst())
 func flag(_ name: String) -> String? {
     guard let a = args.first(where: { $0.hasPrefix("--\(name)=") }) else { return nil }
@@ -405,6 +424,15 @@ case "run":
         }
         defer { control.stop() }
 
+        // A new capture session inherits no stall.
+        //
+        // capture-health.json is cleared when a stalled loop captures a frame
+        // again, and a loop that dies while stalled never gets to. So a fresh
+        // daemon captured happily while `doctor` reported "stalled for 221s,
+        // 60 re-attaches" from its dead predecessor — and the display probe,
+        // correctly on that input, called it a simframe bug. It was: this one.
+        try? store.writeCaptureHealth(nil)
+
         FileHandle.standardError.write("simframed: capturing \(device.name) (\(device.udid))\n".data(using: .utf8)!)
 
         while true {
@@ -417,80 +445,103 @@ case "run":
             if due {
                 lock.lock(); dirty = false; lock.unlock()
                 let t0 = DispatchTime.now().uptimeNanoseconds
-                do {
-                    // One grab produces both sizes; the surface pointer is only
-                    // valid inside this call, so nothing may be deferred out of it.
-                    let wantFull = store.wantsFullFrame()
-                    let (bmp, full) = try platform.withFrame { frame -> (Bitmap, Bitmap?) in
-                        let scaled = CoreGraphicsScaler.bitmap(from: frame, targetLongEdge: longEdge)
-                            ?? Bitmap.from(frame, targetLongEdge: longEdge)
-                        let native = wantFull
-                            ? CoreGraphicsScaler.bitmap(from: frame, targetLongEdge: max(frame.width, frame.height))
-                            : nil
-                        return (scaled, native)
-                    }
-                    let ms = Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6
-                    try store.record(bmp, fullBitmap: full, captureMs: ms)
-                    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(
-                        "simframed: capture failed: \(error) (\(recovery.consecutiveFailures) in a row)\n".data(using: .utf8)!)
-                    // The display port can be torn down and rebuilt under a
-                    // running daemon, and every read on the old descriptor
-                    // returns nil from then on. Observed on a device that was
-                    // awake and visible the whole time: six minutes of
-                    // "the display surface could not be read", cured instantly
-                    // 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 {
-                        switch recovery.reattach(platform: platform, onDamage: {
-                            lock.lock(); dirty = true; lock.unlock()
-                        }) {
-                        case .success(let after):
-                            lock.lock(); dirty = true; lock.unlock()
-                            FileHandle.standardError.write(
-                                "simframed: re-resolved the display port after \(after) failed reads\n"
-                                    .data(using: .utf8)!)
-                        case .failure(let error):
+                // One pool per capture.
+                //
+                // There was none anywhere in this loop, and on Darwin that is
+                // the standard way to get the working set this daemon had:
+                // 732 MB resident after eleven minutes and 2831 frames, for a
+                // process that holds one frame at a time. CoreGraphics scaling
+                // and IOSurface access both produce autoreleased temporaries,
+                // and a `while true` loop with no pool of its own drains
+                // nothing. Whether that pressure is what wedges capture is
+                // unproven — the RSS also *fell* 200 MB in 25 s, so nothing is
+                // leaking monotonically — but a frame grabber should not hold
+                // half a gigabyte either way.
+                autoreleasepool {
+                    do {
+                        // One grab produces both sizes; the surface pointer is only
+                        // valid inside this call, so nothing may be deferred out of it.
+                        let wantFull = store.wantsFullFrame()
+                        let (bmp, full) = try platform.withFrame { frame -> (Bitmap, Bitmap?) in
+                            let scaled = CoreGraphicsScaler.bitmap(from: frame, targetLongEdge: longEdge)
+                                ?? Bitmap.from(frame, targetLongEdge: longEdge)
+                            let native = wantFull
+                                ? CoreGraphicsScaler.bitmap(from: frame, targetLongEdge: max(frame.width, frame.height))
+                                : nil
+                            return (scaled, native)
+                        }
+                        let ms = Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6
+                        try store.record(bmp, fullBitmap: full, captureMs: ms)
+                        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: could not re-resolve the display port: \(error)\n".data(using: .utf8)!)
+                                "simframed: capture recovered on its own\n".data(using: .utf8)!)
                         }
+                    } catch {
+                        let due = recovery.captureFailed()
+                        FileHandle.standardError.write(
+                            "simframed: capture failed: \(error) (\(recovery.consecutiveFailures) in a row)\n".data(using: .utf8)!)
+                        // The display port can be torn down and rebuilt under a
+                        // running daemon, and every read on the old descriptor
+                        // returns nil from then on. Observed on a device that was
+                        // awake and visible the whole time: six minutes of
+                        // "the display surface could not be read", cured instantly
+                        // 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 {
+                            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
+                            // problem, so try the thing that until now needed a human:
+                            // rebind to the device, which is what restarting the
+                            // daemon did.
+                            let rebinding = recovery.needsRebind
+                            let outcome = rebinding
+                                ? recovery.rebind(platform: platform, udid: device.udid, onDamage: onDamage)
+                                : recovery.reattach(platform: platform, onDamage: onDamage)
+                            let what = rebinding ? "rebound to the device" : "re-resolved the display port"
+                            switch outcome {
+                            case .success(let after):
+                                lock.lock(); dirty = true; lock.unlock()
+                                FileHandle.standardError.write(
+                                    "simframed: \(what) after \(after) failed reads\n".data(using: .utf8)!)
+                            case .failure(let error):
+                                FileHandle.standardError.write(
+                                    "simframed: could not \(rebinding ? "rebind to the device" : "re-resolve the display port"): \(error)\n".data(using: .utf8)!)
+                            }
+                        }
+                        // Say that capture is wedged rather than merely slow.
+                        //
+                        // The loop now tries two things — re-resolve the port, then
+                        // rebind the device — and stops there. Restarting the device
+                        // remains 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)
                     }
-                    // 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)
                 }
             }
 
@@ -499,8 +550,12 @@ case "run":
                 let sorted = latencies.sorted()
                 let median = sorted.isEmpty ? 0 : sorted[sorted.count / 2]
                 FileHandle.standardError.write(
-                    String(format: "simframed: %.1f fps, median %.2fms\n", Double(frames) / (wall - lastReport), median)
-                        .data(using: .utf8)!)
+                    String(
+                        format: "simframed: %.1f fps, median %.2fms, rss %.0fMB\n",
+                        Double(frames) / (wall - lastReport),
+                        median,
+                        Double(residentBytes()) / 1_048_576
+                    ).data(using: .utf8)!)
                 frames = 0; latencies.removeAll(); lastReport = wall
             }
 

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

@@ -332,6 +332,46 @@ final class CaptureRecoveryTests: XCTestCase {
         XCTAssertEqual(recovery.reattaches, 0)
     }
 
+    func testTwoDeadReResolvesEscalateToRebindingTheDevice() {
+        // The cure that used to require a human. Two successful re-resolves
+        // with no frame between them says the port was never the problem, so
+        // the next attempt rebinds the device itself — which is what
+        // restarting the daemon did, and it was the only known cure for four
+        // wedges in one afternoon.
+        let platform = StubPlatform()
+        _ = try? platform.attach(udid: "STUB-1")
+        var recovery = CaptureRecovery(threshold: 1)
+
+        XCTAssertFalse(recovery.needsRebind, "a healthy loop rebinds nothing")
+        _ = recovery.captureFailed()
+        _ = recovery.reattach(platform: platform, onDamage: {})
+        XCTAssertFalse(recovery.needsRebind, "one re-resolve deserves the benefit of the doubt")
+        _ = recovery.captureFailed()
+        _ = recovery.reattach(platform: platform, onDamage: {})
+        XCTAssertTrue(recovery.needsRebind, "two is enough")
+
+        var damaged = false
+        let outcome = recovery.rebind(platform: platform, udid: "STUB-1") { damaged = true }
+        guard case .success = outcome else { return XCTFail("rebind should succeed on a live stub") }
+        XCTAssertEqual(platform.rebindCount, 1, "it rebound the device, not the port")
+        XCTAssertEqual(platform.reattachCount, 2, "and did not re-resolve a third time")
+        XCTAssertEqual(recovery.consecutiveFailures, 0)
+
+        // Still stalled: a rebind is an attempt, not evidence. Only a frame is.
+        XCTAssertTrue(recovery.isStalled, "the reattach count is untouched by an attempt")
+        platform.simulateChange()
+        XCTAssertTrue(damaged, "the damage callback was re-armed on the new port")
+
+        // Bounded, so a wedged device is not rebound every half second forever.
+        _ = recovery.rebind(platform: platform, udid: "STUB-1", onDamage: {})
+        XCTAssertFalse(recovery.needsRebind, "two attempts per stall episode is the cap")
+
+        // And a real frame resets everything, including the rebind budget.
+        recovery.captureSucceeded()
+        XCTAssertFalse(recovery.isStalled)
+        XCTAssertEqual(recovery.rebinds, 0)
+    }
+
     func testAReattachThatKeepsFailingIsAlsoAStall() {
         // The other direction: when the re-resolve itself fails the count does
         // keep growing, because nothing resets it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.7.2",
+  "version": "0.9.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,6 +42,7 @@
   },
   "files": [
     "src",
+    "flows",
     "native/ocr.swift",
     "native/simframed/Package.swift",
     "native/simframed/Sources",