agent-device 0.5.4 → 0.6.0

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -7,6 +7,9 @@
 
 import XCTest
 import Network
+import AVFoundation
+import CoreVideo
+import UIKit
 
 final class RunnerTests: XCTestCase {
   private enum RunnerErrorDomain {
@@ -23,7 +26,6 @@ final class RunnerTests: XCTestCase {
 
   private static let springboardBundleId = "com.apple.springboard"
   private var listener: NWListener?
-  private var port: UInt16 = 0
   private var doneExpectation: XCTestExpectation?
   private let app = XCUIApplication()
   private lazy var springboard = XCUIApplication(bundleIdentifier: Self.springboardBundleId)
@@ -33,11 +35,16 @@ final class RunnerTests: XCTestCase {
   private let maxSnapshotElements = 600
   private let fastSnapshotLimit = 300
   private let mainThreadExecutionTimeout: TimeInterval = 30
+  private let appExistenceTimeout: TimeInterval = 30
   private let retryCooldown: TimeInterval = 0.2
   private let postSnapshotInteractionDelay: TimeInterval = 0.2
   private let firstInteractionAfterActivateDelay: TimeInterval = 0.25
+  private let scrollInteractionIdleTimeoutDefault: TimeInterval = 1.0
+  private let minRecordingFps = 1
+  private let maxRecordingFps = 120
   private var needsPostSnapshotInteractionDelay = false
   private var needsFirstInteractionDelay = false
+  private var activeRecording: ScreenRecorder?
   private let interactiveTypes: Set<XCUIElement.ElementType> = [
     .button,
     .cell,
@@ -66,6 +73,262 @@ final class RunnerTests: XCTestCase {
     .switch,
   ]
 
+  private final class ScreenRecorder {
+    private let outputPath: String
+    private let fps: Int32?
+    private let uncappedFrameInterval: TimeInterval = 0.001
+    private var uncappedTimestampTimescale: Int32 {
+      Int32(max(1, Int((1.0 / uncappedFrameInterval).rounded())))
+    }
+    private var frameInterval: TimeInterval {
+      guard let fps else { return uncappedFrameInterval }
+      return 1.0 / Double(fps)
+    }
+    private let queue = DispatchQueue(label: "agent-device.runner.recorder")
+    private let lock = NSLock()
+    private var assetWriter: AVAssetWriter?
+    private var writerInput: AVAssetWriterInput?
+    private var pixelBufferAdaptor: AVAssetWriterInputPixelBufferAdaptor?
+    private var timer: DispatchSourceTimer?
+    private var recordingStartUptime: TimeInterval?
+    private var lastTimestampValue: Int64 = -1
+    private var isStopping = false
+    private var startedSession = false
+    private var startError: Error?
+
+    init(outputPath: String, fps: Int32?) {
+      self.outputPath = outputPath
+      self.fps = fps
+    }
+
+    func start(captureFrame: @escaping () -> UIImage?) throws {
+      let url = URL(fileURLWithPath: outputPath)
+      let directory = url.deletingLastPathComponent()
+      try FileManager.default.createDirectory(
+        at: directory,
+        withIntermediateDirectories: true,
+        attributes: nil
+      )
+      if FileManager.default.fileExists(atPath: outputPath) {
+        try FileManager.default.removeItem(atPath: outputPath)
+      }
+
+      var dimensions: CGSize = .zero
+      var bootstrapImage: UIImage?
+      let bootstrapDeadline = Date().addingTimeInterval(2.0)
+      while Date() < bootstrapDeadline {
+        if let image = captureFrame(), let cgImage = image.cgImage {
+          bootstrapImage = image
+          dimensions = CGSize(width: cgImage.width, height: cgImage.height)
+          break
+        }
+        Thread.sleep(forTimeInterval: 0.05)
+      }
+      guard dimensions.width > 0, dimensions.height > 0 else {
+        throw NSError(
+          domain: "AgentDeviceRunner.Record",
+          code: 1,
+          userInfo: [NSLocalizedDescriptionKey: "failed to capture initial frame"]
+        )
+      }
+
+      let writer = try AVAssetWriter(outputURL: url, fileType: .mp4)
+      let outputSettings: [String: Any] = [
+        AVVideoCodecKey: AVVideoCodecType.h264,
+        AVVideoWidthKey: Int(dimensions.width),
+        AVVideoHeightKey: Int(dimensions.height),
+      ]
+      let input = AVAssetWriterInput(mediaType: .video, outputSettings: outputSettings)
+      input.expectsMediaDataInRealTime = true
+      let attributes: [String: Any] = [
+        kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_32ARGB,
+        kCVPixelBufferWidthKey as String: Int(dimensions.width),
+        kCVPixelBufferHeightKey as String: Int(dimensions.height),
+      ]
+      let adaptor = AVAssetWriterInputPixelBufferAdaptor(
+        assetWriterInput: input,
+        sourcePixelBufferAttributes: attributes
+      )
+      guard writer.canAdd(input) else {
+        throw NSError(
+          domain: "AgentDeviceRunner.Record",
+          code: 2,
+          userInfo: [NSLocalizedDescriptionKey: "failed to add video input"]
+        )
+      }
+      writer.add(input)
+      guard writer.startWriting() else {
+        throw writer.error ?? NSError(
+          domain: "AgentDeviceRunner.Record",
+          code: 3,
+          userInfo: [NSLocalizedDescriptionKey: "failed to start writing"]
+        )
+      }
+
+      lock.lock()
+      assetWriter = writer
+      writerInput = input
+      pixelBufferAdaptor = adaptor
+      recordingStartUptime = nil
+      lastTimestampValue = -1
+      isStopping = false
+      startedSession = false
+      startError = nil
+      lock.unlock()
+
+      if let firstImage = bootstrapImage {
+        append(image: firstImage)
+      }
+
+      let timer = DispatchSource.makeTimerSource(queue: queue)
+      timer.schedule(deadline: .now() + frameInterval, repeating: frameInterval)
+      timer.setEventHandler { [weak self] in
+        guard let self else { return }
+        if self.shouldStop() { return }
+        guard let image = captureFrame() else { return }
+        self.append(image: image)
+      }
+      self.timer = timer
+      timer.resume()
+    }
+
+    func stop() throws {
+      var writer: AVAssetWriter?
+      var input: AVAssetWriterInput?
+      var appendError: Error?
+      lock.lock()
+      if isStopping {
+        lock.unlock()
+        return
+      }
+      isStopping = true
+      let activeTimer = timer
+      timer = nil
+      writer = assetWriter
+      input = writerInput
+      appendError = startError
+      lock.unlock()
+
+      activeTimer?.cancel()
+      input?.markAsFinished()
+      guard let writer else { return }
+
+      let semaphore = DispatchSemaphore(value: 0)
+      writer.finishWriting {
+        semaphore.signal()
+      }
+      var stopFailure: Error?
+      let waitResult = semaphore.wait(timeout: .now() + 10)
+      if waitResult == .timedOut {
+        writer.cancelWriting()
+        stopFailure = NSError(
+          domain: "AgentDeviceRunner.Record",
+          code: 6,
+          userInfo: [NSLocalizedDescriptionKey: "recording finalization timed out"]
+        )
+      } else if let appendError {
+        stopFailure = appendError
+      } else if writer.status == .failed {
+        stopFailure = writer.error ?? NSError(
+          domain: "AgentDeviceRunner.Record",
+          code: 4,
+          userInfo: [NSLocalizedDescriptionKey: "failed to finalize recording"]
+        )
+      }
+
+      lock.lock()
+      assetWriter = nil
+      writerInput = nil
+      pixelBufferAdaptor = nil
+      recordingStartUptime = nil
+      lastTimestampValue = -1
+      startedSession = false
+      startError = nil
+      lock.unlock()
+
+      if let stopFailure {
+        throw stopFailure
+      }
+    }
+
+    private func append(image: UIImage) {
+      guard let cgImage = image.cgImage else { return }
+      lock.lock()
+      defer { lock.unlock() }
+      if isStopping { return }
+      if let startError { return }
+      guard
+        let writer = assetWriter,
+        let input = writerInput,
+        let adaptor = pixelBufferAdaptor
+      else {
+        return
+      }
+      if !startedSession {
+        writer.startSession(atSourceTime: .zero)
+        startedSession = true
+      }
+      guard input.isReadyForMoreMediaData else { return }
+      guard let pixelBuffer = makePixelBuffer(from: cgImage) else { return }
+      let nowUptime = ProcessInfo.processInfo.systemUptime
+      if recordingStartUptime == nil {
+        recordingStartUptime = nowUptime
+      }
+      let elapsed = max(0, nowUptime - (recordingStartUptime ?? nowUptime))
+      let timescale = fps ?? uncappedTimestampTimescale
+      var timestampValue = Int64((elapsed * Double(timescale)).rounded(.down))
+      if timestampValue <= lastTimestampValue {
+        timestampValue = lastTimestampValue + 1
+      }
+      let timestamp = CMTime(value: timestampValue, timescale: timescale)
+      if !adaptor.append(pixelBuffer, withPresentationTime: timestamp) {
+        startError = writer.error ?? NSError(
+          domain: "AgentDeviceRunner.Record",
+          code: 5,
+          userInfo: [NSLocalizedDescriptionKey: "failed to append frame"]
+        )
+        return
+      }
+      lastTimestampValue = timestampValue
+    }
+
+    private func shouldStop() -> Bool {
+      lock.lock()
+      defer { lock.unlock() }
+      return isStopping
+    }
+
+    private func makePixelBuffer(from image: CGImage) -> CVPixelBuffer? {
+      guard let adaptor = pixelBufferAdaptor else { return nil }
+      var pixelBuffer: CVPixelBuffer?
+      guard let pool = adaptor.pixelBufferPool else { return nil }
+      let status = CVPixelBufferPoolCreatePixelBuffer(
+        nil,
+        pool,
+        &pixelBuffer
+      )
+      guard status == kCVReturnSuccess, let pixelBuffer else { return nil }
+
+      CVPixelBufferLockBaseAddress(pixelBuffer, [])
+      defer { CVPixelBufferUnlockBaseAddress(pixelBuffer, []) }
+      guard
+        let context = CGContext(
+          data: CVPixelBufferGetBaseAddress(pixelBuffer),
+          width: image.width,
+          height: image.height,
+          bitsPerComponent: 8,
+          bytesPerRow: CVPixelBufferGetBytesPerRow(pixelBuffer),
+          space: CGColorSpaceCreateDeviceRGB(),
+          bitmapInfo: CGImageAlphaInfo.noneSkipFirst.rawValue
+        )
+      else {
+        return nil
+      }
+      context.draw(image, in: CGRect(x: 0, y: 0, width: image.width, height: image.height))
+      return pixelBuffer
+    }
+  }
+
   override func setUp() {
     continueAfterFailure = true
   }
@@ -88,7 +351,6 @@ final class RunnerTests: XCTestCase {
       case .ready:
         NSLog("AGENT_DEVICE_RUNNER_LISTENER_READY")
         if let listenerPort = self?.listener?.port {
-          self?.port = listenerPort.rawValue
           NSLog("AGENT_DEVICE_RUNNER_PORT=%d", listenerPort.rawValue)
         } else {
           NSLog("AGENT_DEVICE_RUNNER_PORT_NOT_SET")
@@ -261,7 +523,11 @@ final class RunnerTests: XCTestCase {
       if let exceptionMessage {
         currentApp = nil
         currentBundleId = nil
-        if !hasRetried, shouldRetryCommand(command.command) {
+        if !hasRetried, shouldRetryException(command, message: exceptionMessage) {
+          NSLog(
+            "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=objc_exception",
+            command.command.rawValue
+          )
           hasRetried = true
           sleepFor(retryCooldown)
           continue
@@ -282,7 +548,11 @@ final class RunnerTests: XCTestCase {
           userInfo: [NSLocalizedDescriptionKey: "command returned no response"]
         )
       }
-      if !hasRetried, shouldRetryCommand(command.command), shouldRetryResponse(response) {
+      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
+        NSLog(
+          "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
+          command.command.rawValue
+        )
         hasRetried = true
         currentApp = nil
         currentBundleId = nil
@@ -294,61 +564,111 @@ final class RunnerTests: XCTestCase {
   }
 
   private func executeOnMain(command: Command) throws -> Response {
-    if command.command == .shutdown {
-      return Response(ok: true, data: DataPayload(message: "shutdown"))
-    }
-
-    let normalizedBundleId = command.appBundleId?
-      .trimmingCharacters(in: .whitespacesAndNewlines)
-    let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
-    if let bundleId = requestedBundleId {
-      if currentBundleId != bundleId || currentApp == nil {
-        _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
-      }
-    } else {
-      // Do not reuse stale bundle targets when the caller does not explicitly request one.
-      currentApp = nil
-      currentBundleId = nil
-    }
-
     var activeApp = currentApp ?? app
-    if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
-      activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
-    } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
-      app.activate()
-      activeApp = app
-    }
-
-    if !activeApp.waitForExistence(timeout: 5) {
+    if !isRunnerLifecycleCommand(command.command) {
+      let normalizedBundleId = command.appBundleId?
+        .trimmingCharacters(in: .whitespacesAndNewlines)
+      let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
       if let bundleId = requestedBundleId {
-        activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
-        guard activeApp.waitForExistence(timeout: 5) else {
-          return Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available"))
+        if currentBundleId != bundleId || currentApp == nil {
+          _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
         }
       } else {
-        return Response(ok: false, error: ErrorPayload(message: "runner app is not available"))
+        // Do not reuse stale bundle targets when the caller does not explicitly request one.
+        currentApp = nil
+        currentBundleId = nil
       }
-    }
 
-    if isInteractionCommand(command.command) {
-      if let bundleId = requestedBundleId, activeApp.state != .runningForeground {
-        activeApp = activateTarget(bundleId: bundleId, reason: "interaction_foreground_guard")
-      } else if requestedBundleId == nil, activeApp.state != .runningForeground {
+      activeApp = currentApp ?? app
+      if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
+        activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
+      } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
         app.activate()
         activeApp = app
       }
-      if !activeApp.waitForExistence(timeout: 2) {
+
+      if !activeApp.waitForExistence(timeout: appExistenceTimeout) {
         if let bundleId = requestedBundleId {
-          return Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available"))
+          activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
+          guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
+            return Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available"))
+          }
+        } else {
+          return Response(ok: false, error: ErrorPayload(message: "runner app is not available"))
+        }
+      }
+
+      if isInteractionCommand(command.command) {
+        if let bundleId = requestedBundleId, activeApp.state != .runningForeground {
+          activeApp = activateTarget(bundleId: bundleId, reason: "interaction_foreground_guard")
+        } else if requestedBundleId == nil, activeApp.state != .runningForeground {
+          app.activate()
+          activeApp = app
+        }
+        if !activeApp.waitForExistence(timeout: 2) {
+          if let bundleId = requestedBundleId {
+            return Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available"))
+          }
+          return Response(ok: false, error: ErrorPayload(message: "runner app is not available"))
         }
-        return Response(ok: false, error: ErrorPayload(message: "runner app is not available"))
+        applyInteractionStabilizationIfNeeded()
       }
-      applyInteractionStabilizationIfNeeded()
     }
 
     switch command.command {
     case .shutdown:
+      stopRecordingIfNeeded()
       return Response(ok: true, data: DataPayload(message: "shutdown"))
+    case .recordStart:
+      guard
+        let requestedOutPath = command.outPath?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !requestedOutPath.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart requires outPath"))
+      }
+      let hasAppBundleId = !(command.appBundleId?
+        .trimmingCharacters(in: .whitespacesAndNewlines)
+        .isEmpty ?? true)
+      guard hasAppBundleId else {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart requires appBundleId"))
+      }
+      if activeRecording != nil {
+        return Response(ok: false, error: ErrorPayload(message: "recording already in progress"))
+      }
+      if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
+      }
+      do {
+        let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
+        let fpsLabel = command.fps.map(String.init) ?? "max"
+        NSLog(
+          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
+          requestedOutPath,
+          resolvedOutPath,
+          fpsLabel
+        )
+        let recorder = ScreenRecorder(outputPath: resolvedOutPath, fps: command.fps.map { Int32($0) })
+        try recorder.start { [weak self] in
+          return self?.captureRunnerFrame()
+        }
+        activeRecording = recorder
+        return Response(ok: true, data: DataPayload(message: "recording started"))
+      } catch {
+        activeRecording = nil
+        return Response(ok: false, error: ErrorPayload(message: "failed to start recording: \(error.localizedDescription)"))
+      }
+    case .recordStop:
+      guard let recorder = activeRecording else {
+        return Response(ok: false, error: ErrorPayload(message: "no active recording"))
+      }
+      do {
+        try recorder.stop()
+        activeRecording = nil
+        return Response(ok: true, data: DataPayload(message: "recording stopped"))
+      } catch {
+        activeRecording = nil
+        return Response(ok: false, error: ErrorPayload(message: "failed to stop recording: \(error.localizedDescription)"))
+      }
     case .tap:
       if let text = command.text {
         if let element = findElement(app: activeApp, text: text) {
@@ -391,7 +711,9 @@ final class RunnerTests: XCTestCase {
         return Response(ok: false, error: ErrorPayload(message: "drag requires x, y, x2, and y2"))
       }
       let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
-      dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+      }
       return Response(ok: true, data: DataPayload(message: "dragged"))
     case .dragSeries:
       guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
@@ -404,12 +726,14 @@ final class RunnerTests: XCTestCase {
         return Response(ok: false, error: ErrorPayload(message: "dragSeries pattern must be one-way or ping-pong"))
       }
       let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
-      runSeries(count: count, pauseMs: pauseMs) { idx in
-        let reverse = pattern == "ping-pong" && (idx % 2 == 1)
-        if reverse {
-          dragAt(app: activeApp, x: x2, y: y2, x2: x, y2: y, holdDuration: holdDuration)
-        } else {
-          dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        runSeries(count: count, pauseMs: pauseMs) { idx in
+          let reverse = pattern == "ping-pong" && (idx % 2 == 1)
+          if reverse {
+            dragAt(app: activeApp, x: x2, y: y2, x2: x, y2: y, holdDuration: holdDuration)
+          } else {
+            dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+          }
         }
       }
       return Response(ok: true, data: DataPayload(message: "drag series"))
@@ -435,7 +759,9 @@ final class RunnerTests: XCTestCase {
       guard let direction = command.direction else {
         return Response(ok: false, error: ErrorPayload(message: "swipe requires direction"))
       }
-      swipe(app: activeApp, direction: direction)
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        swipe(app: activeApp, direction: direction)
+      }
       return Response(ok: true, data: DataPayload(message: "swiped"))
     case .findText:
       guard let text = command.text else {
@@ -443,17 +769,6 @@ final class RunnerTests: XCTestCase {
       }
       let found = findElement(app: activeApp, text: text) != nil
       return Response(ok: true, data: DataPayload(found: found))
-    case .listTappables:
-      let elements = activeApp.descendants(matching: .any).allElementsBoundByIndex
-      let labels = elements.compactMap { element -> String? in
-        guard element.isHittable else { return nil }
-        let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
-        if label.isEmpty { return nil }
-        let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
-        return identifier.isEmpty ? label : "\(label) [\(identifier)]"
-      }
-      let unique = Array(Set(labels)).sorted()
-      return Response(ok: true, data: DataPayload(items: unique))
     case .snapshot:
       let options = SnapshotOptions(
         interactiveOnly: command.interactiveOnly ?? false,
@@ -507,6 +822,37 @@ final class RunnerTests: XCTestCase {
     }
   }
 
+  private func captureRunnerFrame() -> UIImage? {
+    var image: UIImage?
+    let capture = {
+      let screenshot = XCUIScreen.main.screenshot()
+      image = screenshot.image
+    }
+    if Thread.isMainThread {
+      capture()
+    } else {
+      DispatchQueue.main.sync(execute: capture)
+    }
+    return image
+  }
+
+  private func stopRecordingIfNeeded() {
+    guard let recorder = activeRecording else { return }
+    do {
+      try recorder.stop()
+    } catch {
+      NSLog("AGENT_DEVICE_RUNNER_RECORD_STOP_FAILED=%@", String(describing: error))
+    }
+    activeRecording = nil
+  }
+
+  private func resolveRecordingOutPath(_ requestedOutPath: String) -> String {
+    let fileName = URL(fileURLWithPath: requestedOutPath).lastPathComponent
+    let fallbackName = "agent-device-recording-\(Int(Date().timeIntervalSince1970 * 1000)).mp4"
+    let safeFileName = fileName.isEmpty ? fallbackName : fileName
+    return (NSTemporaryDirectory() as NSString).appendingPathComponent(safeFileName)
+  }
+
   private func targetNeedsActivation(_ target: XCUIApplication) -> Bool {
     switch target.state {
     case .unknown, .notRunning, .runningBackground, .runningBackgroundSuspended:
@@ -532,10 +878,67 @@ final class RunnerTests: XCTestCase {
     return target
   }
 
-  private func shouldRetryCommand(_ command: CommandType) -> Bool {
-    switch command {
-    case .tap, .longPress, .drag:
+  private func withTemporaryScrollIdleTimeoutIfSupported(
+    _ target: XCUIApplication,
+    operation: () -> Void
+  ) {
+    let setter = NSSelectorFromString("setWaitForIdleTimeout:")
+    guard target.responds(to: setter) else {
+      operation()
+      return
+    }
+    let previous = target.value(forKey: "waitForIdleTimeout") as? NSNumber
+    target.setValue(resolveScrollInteractionIdleTimeout(), forKey: "waitForIdleTimeout")
+    defer {
+      if let previous {
+        target.setValue(previous.doubleValue, forKey: "waitForIdleTimeout")
+      }
+    }
+    operation()
+  }
+
+  private func resolveScrollInteractionIdleTimeout() -> TimeInterval {
+    guard
+      let raw = ProcessInfo.processInfo.environment["AGENT_DEVICE_IOS_INTERACTION_IDLE_TIMEOUT"],
+      !raw.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+    else {
+      return scrollInteractionIdleTimeoutDefault
+    }
+    guard let parsed = Double(raw), parsed >= 0 else {
+      return scrollInteractionIdleTimeoutDefault
+    }
+    return min(parsed, 30)
+  }
+
+  private func shouldRetryCommand(_ command: Command) -> Bool {
+    if isEnvTruthy("AGENT_DEVICE_RUNNER_DISABLE_READONLY_RETRY") {
+      return false
+    }
+    return isReadOnlyCommand(command)
+  }
+
+  private func shouldRetryException(_ command: Command, message: String) -> Bool {
+    guard shouldRetryCommand(command) else { return false }
+    let normalized = message.lowercased()
+    if normalized.contains("kaxerrorservernotfound") {
+      return true
+    }
+    if normalized.contains("main thread execution timed out") {
+      return true
+    }
+    if normalized.contains("timed out") && command.command == .snapshot {
+      return true
+    }
+    return false
+  }
+
+  private func isReadOnlyCommand(_ command: Command) -> Bool {
+    switch command.command {
+    case .findText, .snapshot:
       return true
+    case .alert:
+      let action = (command.action ?? "get").lowercased()
+      return action == "get"
     default:
       return false
     }
@@ -556,6 +959,15 @@ final class RunnerTests: XCTestCase {
     }
   }
 
+  private func isRunnerLifecycleCommand(_ command: CommandType) -> Bool {
+    switch command {
+    case .shutdown, .recordStop:
+      return true
+    default:
+      return false
+    }
+  }
+
   private func applyInteractionStabilizationIfNeeded() {
     if needsPostSnapshotInteractionDelay {
       sleepFor(postSnapshotInteractionDelay)
@@ -977,43 +1389,58 @@ final class RunnerTests: XCTestCase {
     }
 
     let title = preferredSystemModalTitle(modal)
-
-    var nodes: [SnapshotNode] = [
-      makeSnapshotNode(
-        element: modal,
-        index: 0,
-        type: "Alert",
-        labelOverride: title,
-        identifierOverride: modal.identifier,
-        depth: 0,
-        hittableOverride: true
-      )
-    ]
+    guard let modalNode = safeMakeSnapshotNode(
+      element: modal,
+      index: 0,
+      type: "Alert",
+      labelOverride: title,
+      identifierOverride: modal.identifier,
+      depth: 0,
+      hittableOverride: true
+    ) else {
+      return nil
+    }
+    var nodes: [SnapshotNode] = [modalNode]
 
     for action in actions {
-      nodes.append(
-        makeSnapshotNode(
-          element: action,
-          index: nodes.count,
-          type: elementTypeName(action.elementType),
-          depth: 1,
-          hittableOverride: true
-        )
-      )
+      guard let actionNode = safeMakeSnapshotNode(
+        element: action,
+        index: nodes.count,
+        type: elementTypeName(action.elementType),
+        depth: 1,
+        hittableOverride: true
+      ) else {
+        continue
+      }
+      nodes.append(actionNode)
     }
 
     return DataPayload(nodes: nodes, truncated: false)
   }
 
   private func firstBlockingSystemModal(in springboard: XCUIApplication) -> XCUIElement? {
-    for alert in springboard.alerts.allElementsBoundByIndex {
-      if isBlockingSystemModal(alert, in: springboard) {
+    let disableSafeProbe = isEnvTruthy("AGENT_DEVICE_RUNNER_DISABLE_SAFE_MODAL_PROBE")
+    let queryElements: (() -> [XCUIElement]) -> [XCUIElement] = { fetch in
+      if disableSafeProbe {
+        return fetch()
+      }
+      return self.safeElementsQuery(fetch)
+    }
+
+    let alerts = queryElements {
+      springboard.alerts.allElementsBoundByIndex
+    }
+    for alert in alerts {
+      if safeIsBlockingSystemModal(alert, in: springboard) {
         return alert
       }
     }
 
-    for sheet in springboard.sheets.allElementsBoundByIndex {
-      if isBlockingSystemModal(sheet, in: springboard) {
+    let sheets = queryElements {
+      springboard.sheets.allElementsBoundByIndex
+    }
+    for sheet in sheets {
+      if safeIsBlockingSystemModal(sheet, in: springboard) {
         return sheet
       }
     }
@@ -1021,6 +1448,36 @@ final class RunnerTests: XCTestCase {
     return nil
   }
 
+  private func safeElementsQuery(_ fetch: () -> [XCUIElement]) -> [XCUIElement] {
+    var elements: [XCUIElement] = []
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      elements = fetch()
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_MODAL_QUERY_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      return []
+    }
+    return elements
+  }
+
+  private func safeIsBlockingSystemModal(_ element: XCUIElement, in springboard: XCUIApplication) -> Bool {
+    var isBlocking = false
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      isBlocking = isBlockingSystemModal(element, in: springboard)
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_MODAL_CHECK_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      return false
+    }
+    return isBlocking
+  }
+
   private func isBlockingSystemModal(_ element: XCUIElement, in springboard: XCUIApplication) -> Bool {
     guard element.exists else { return false }
     let frame = element.frame
@@ -1038,18 +1495,36 @@ final class RunnerTests: XCTestCase {
   private func actionableElements(in element: XCUIElement) -> [XCUIElement] {
     var seen = Set<String>()
     var actions: [XCUIElement] = []
-    let descendants = element.descendants(matching: .any).allElementsBoundByIndex
+    let descendants = safeElementsQuery {
+      element.descendants(matching: .any).allElementsBoundByIndex
+    }
     for candidate in descendants {
-      if !candidate.exists || !candidate.isHittable { continue }
-      if !actionableTypes.contains(candidate.elementType) { continue }
+      if !safeIsActionableCandidate(candidate, seen: &seen) { continue }
+      actions.append(candidate)
+    }
+    return actions
+  }
+
+  private func safeIsActionableCandidate(_ candidate: XCUIElement, seen: inout Set<String>) -> Bool {
+    var include = false
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      if !candidate.exists || !candidate.isHittable { return }
+      if !actionableTypes.contains(candidate.elementType) { return }
       let frame = candidate.frame
-      if frame.isNull || frame.isEmpty { continue }
+      if frame.isNull || frame.isEmpty { return }
       let key = "\(candidate.elementType.rawValue)-\(frame.origin.x)-\(frame.origin.y)-\(frame.size.width)-\(frame.size.height)-\(candidate.label)"
-      if seen.contains(key) { continue }
+      if seen.contains(key) { return }
       seen.insert(key)
-      actions.append(candidate)
+      include = true
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_MODAL_ACTION_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      return false
     }
-    return actions
+    return include
   }
 
   private func preferredSystemModalTitle(_ element: XCUIElement) -> String {
@@ -1088,6 +1563,37 @@ final class RunnerTests: XCTestCase {
     )
   }
 
+  private func safeMakeSnapshotNode(
+    element: XCUIElement,
+    index: Int,
+    type: String,
+    labelOverride: String? = nil,
+    identifierOverride: String? = nil,
+    depth: Int,
+    hittableOverride: Bool? = nil
+  ) -> SnapshotNode? {
+    var node: SnapshotNode?
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      node = makeSnapshotNode(
+        element: element,
+        index: index,
+        type: type,
+        labelOverride: labelOverride,
+        identifierOverride: identifierOverride,
+        depth: depth,
+        hittableOverride: hittableOverride
+      )
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_MODAL_NODE_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      return nil
+    }
+    return node
+  }
+
   private func snapshotRect(from frame: CGRect) -> SnapshotRect {
     return SnapshotRect(
       x: Double(frame.origin.x),
@@ -1213,6 +1719,18 @@ private func resolveRunnerPort() -> UInt16 {
   return 0
 }
 
+private func isEnvTruthy(_ name: String) -> Bool {
+  guard let raw = ProcessInfo.processInfo.environment[name] else {
+    return false
+  }
+  switch raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() {
+  case "1", "true", "yes", "on":
+    return true
+  default:
+    return false
+  }
+}
+
 enum CommandType: String, Codable {
   case tap
   case tapSeries
@@ -1222,13 +1740,14 @@ enum CommandType: String, Codable {
   case type
   case swipe
   case findText
-  case listTappables
   case snapshot
   case back
   case home
   case appSwitcher
   case alert
   case pinch
+  case recordStart
+  case recordStop
   case shutdown
 }
 
@@ -1257,6 +1776,8 @@ struct Command: Codable {
   let durationMs: Double?
   let direction: SwipeDirection?
   let scale: Double?
+  let outPath: String?
+  let fps: Int?
   let interactiveOnly: Bool?
   let compact: Bool?
   let depth: Int?