agent-device 0.18.3 → 0.19.1

package/{apple-runner → dist/apple-runner}/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -130,58 +130,6 @@ extension RunnerTests {
     return Response(ok: true, data: data)
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testGestureResponseIncludesSynthesizedTapFallbackDiagnostics() {
-    let response = gestureResponse(
-      message: "tapped",
-      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
-      fallback: GestureFallback(
-        strategy: "xctest-coordinate-tap",
-        message: "Runner synthesized coordinate tap is unavailable",
-        hint: "Using XCTest coordinate tap fallback."
-      )
-    )
-
-    XCTAssertEqual(response.ok, true)
-    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
-    XCTAssertEqual(
-      response.data?.gestureFallbackMessage,
-      "Runner synthesized coordinate tap is unavailable"
-    )
-    XCTAssertEqual(response.data?.gestureFallbackHint, "Using XCTest coordinate tap fallback.")
-  }
-
-  func testXCTestRecordedFailureResponseFailsMutatingSuccesses() throws {
-    let command = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
-    let response = Response(ok: true, data: DataPayload(message: "tapped"))
-
-    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
-
-    XCTAssertEqual(failureResponse?.ok, false)
-    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
-    XCTAssertEqual(
-      failureResponse?.error?.message,
-      "XCTest recorded a failure while executing tap; the action may not have been performed."
-    )
-  }
-
-  func testXCTestRecordedFailureResponseDoesNotWrapReadOnlyOrRunnerFatalResponses() throws {
-    let snapshotCommand = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-1"}"#)
-    let tapCommand = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
-    let runnerFatalResponse = Response(
-      ok: true,
-      data: DataPayload(runnerFatal: true, runnerFatalReason: "ax_snapshot_unavailable")
-    )
-
-    XCTAssertNil(
-      xctestRecordedFailureResponse(
-        command: snapshotCommand,
-        response: Response(ok: true, data: DataPayload(nodes: [], truncated: false))
-      )
-    )
-    XCTAssertNil(xctestRecordedFailureResponse(command: tapCommand, response: runnerFatalResponse))
-  }
-#endif
 
   func execute(command: Command) throws -> Response {
     if command.command == .status {
@@ -233,32 +181,158 @@ extension RunnerTests {
     )
   }
 
+  /// Tracks one main-queue dispatch so the watchdog and the dispatched block can agree —
+  /// under `mainThreadWorkLock` — on exactly one of: finished in time, or abandoned.
+  private final class MainThreadWorkState {
+    var finished = false
+    var abandoned = false
+  }
+
+  struct ActiveCommandContext {
+    let app: XCUIApplication
+  }
+
+  enum ActiveCommandPreparation {
+    case response(Response)
+    case context(ActiveCommandContext)
+  }
+
+  enum MainThreadBusyState {
+    case idle
+    case busy(abandonedForSeconds: TimeInterval)
+    case wedged(abandonedForSeconds: TimeInterval)
+  }
+
+  func currentMainThreadBusyState() -> MainThreadBusyState {
+    mainThreadWorkLock.lock()
+    defer { mainThreadWorkLock.unlock() }
+    guard abandonedMainThreadWorkCount > 0 else { return .idle }
+    let abandonedFor = abandonedMainThreadWorkSince.map { Date().timeIntervalSince($0) } ?? 0
+    if abandonedFor > mainThreadWedgeThreshold {
+      return .wedged(abandonedForSeconds: abandonedFor)
+    }
+    return .busy(abandonedForSeconds: abandonedFor)
+  }
+
+  private func runnerBusyResponse(command: Command, abandonedForSeconds: TimeInterval) -> Response {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_BUSY command=%@ commandId=%@ abandonedForSeconds=%.1f",
+      command.command.rawValue,
+      command.commandId ?? "",
+      abandonedForSeconds
+    )
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "RUNNER_BUSY",
+        message:
+          "The iOS runner is still finishing a previous command that exceeded its execution watchdog (usually an accessibility capture on a heavy or animating screen).",
+        hint:
+          "Wait a few seconds and retry. If snapshots keep failing on this screen, use screenshot as visual truth and interact by coordinates, or navigate to another screen."
+      )
+    )
+  }
+
+  private func runnerWedgedResponse(command: Command, abandonedForSeconds: TimeInterval) -> Response {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_WEDGED command=%@ commandId=%@ abandonedForSeconds=%.1f",
+      command.command.rawValue,
+      command.commandId ?? "",
+      abandonedForSeconds
+    )
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "RUNNER_WEDGED",
+        message:
+          "The iOS runner main thread has been stuck in abandoned work for \(Int(abandonedForSeconds)) seconds and cannot recover on its own.",
+        hint:
+          "The runner session will be restarted. Retry the command after the restart; if this screen keeps wedging captures, use screenshot as visual truth and interact by coordinates."
+      )
+    )
+  }
+
   private func executeDispatched(command: Command) throws -> Response {
+    // XCTest work cannot be cancelled mid-flight: once the watchdog abandons a main-queue
+    // block, queueing more main-thread commands behind it only buries the runner deeper.
+    // Refuse fast instead so the daemon backs off while the abandoned work drains; past the
+    // wedge threshold, escalate so the daemon recycles this runner (#1105).
+    switch currentMainThreadBusyState() {
+    case .idle:
+      break
+    case .busy(let abandonedForSeconds):
+      return runnerBusyResponse(command: command, abandonedForSeconds: abandonedForSeconds)
+    case .wedged(let abandonedForSeconds):
+      return runnerWedgedResponse(command: command, abandonedForSeconds: abandonedForSeconds)
+    }
     if Thread.isMainThread {
       return try executeOnMainSafely(command: command)
     }
-    var result: Result<Response, Error>?
+    if command.command == .snapshot {
+      return try executeSnapshotDispatched(command: command)
+    }
+    return try runMainThreadWork(
+      command: command,
+      timeout: mainThreadExecutionTimeout,
+      timeoutError: mainThreadExecutionTimeoutError
+    ) {
+      try self.executeOnMainSafely(command: command)
+    }
+  }
+
+  func runMainThreadWork<T>(
+    command: Command?,
+    timeout: TimeInterval,
+    timeoutError: @escaping () -> Error,
+    onAbandoned: (() -> Void)? = nil,
+    onDrained: (() -> Void)? = nil,
+    _ work: @escaping () throws -> T
+  ) throws -> T {
+    if Thread.isMainThread {
+      return try work()
+    }
+    var result: Result<T, Error>?
     let semaphore = DispatchSemaphore(value: 0)
+    let workState = MainThreadWorkState()
     DispatchQueue.main.async {
       do {
-        result = .success(try self.executeOnMainSafely(command: command))
+        result = .success(try work())
       } catch {
         result = .failure(error)
       }
+      self.mainThreadWorkLock.lock()
+      if workState.abandoned {
+        self.abandonedMainThreadWorkCount -= 1
+        if self.abandonedMainThreadWorkCount == 0 {
+          self.abandonedMainThreadWorkSince = nil
+          NSLog("AGENT_DEVICE_RUNNER_ABANDONED_WORK_DRAINED")
+        }
+        self.mainThreadWorkLock.unlock()
+        onDrained?()
+      } else {
+        workState.finished = true
+        self.mainThreadWorkLock.unlock()
+      }
       semaphore.signal()
     }
-    let waitResult = semaphore.wait(timeout: .now() + mainThreadExecutionTimeout)
+    let waitResult = semaphore.wait(timeout: .now() + timeout)
     if waitResult == .timedOut {
-      // The main queue work may still be running; we stop waiting and report timeout.
-      throw NSError(
-        domain: RunnerErrorDomain.general,
-        code: RunnerErrorCode.mainThreadExecutionTimedOut,
-        userInfo: [NSLocalizedDescriptionKey: "main thread execution timed out"]
-      )
+      mainThreadWorkLock.lock()
+      let stillRunning = !workState.finished
+      if stillRunning {
+        workState.abandoned = true
+        abandonedMainThreadWorkCount += 1
+        if abandonedMainThreadWorkSince == nil {
+          abandonedMainThreadWorkSince = Date()
+        }
+        onAbandoned?()
+      }
+      mainThreadWorkLock.unlock()
+      throw timeoutError()
     }
     switch result {
-    case .success(let response):
-      return response
+    case .success(let value):
+      return value
     case .failure(let error):
       throw error
     case .none:
@@ -270,6 +344,14 @@ extension RunnerTests {
     }
   }
 
+  private func mainThreadExecutionTimeoutError() -> Error {
+    NSError(
+      domain: RunnerErrorDomain.general,
+      code: RunnerErrorCode.mainThreadExecutionTimedOut,
+      userInfo: [NSLocalizedDescriptionKey: "main thread execution timed out"]
+    )
+  }
+
   // MARK: - Command Handling
 
   private func executeOnMainSafely(command: Command) throws -> Response {
@@ -333,68 +415,171 @@ extension RunnerTests {
     }
   }
 
-  private func executeOnMain(command: Command) throws -> Response {
-    var activeApp = currentApp ?? app
-    if shouldSkipAppActivationPreflight(command) {
-      activeApp = resolveAppWithoutActivation(command: command)
-    } else if !isRunnerLifecycleCommand(command.command) {
-      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")
+  private func executeSnapshotDispatched(command: Command) throws -> Response {
+    var hasRetried = false
+    while true {
+      let failureCountBefore = try runMainThreadWork(
+        command: command,
+        timeout: mainThreadExecutionTimeout,
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        self.currentXCTestFailureCount()
+      }
+      let response = try executeSnapshotDispatchedOnce(command: command)
+      let recordedFailureResponse = try runMainThreadWork(
+        command: command,
+        timeout: mainThreadExecutionTimeout,
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        self.didRecordXCTestFailure(since: failureCountBefore)
+          ? self.xctestRecordedFailureResponse(command: command, response: response)
+          : nil
+      }
+      if let recordedFailureResponse {
+        try runMainThreadWork(
+          command: command,
+          timeout: mainThreadExecutionTimeout,
+          timeoutError: mainThreadExecutionTimeoutError
+        ) {
+          self.invalidateCachedTarget(reason: "xctest_recorded_failure")
         }
-      } else {
-        // Do not reuse stale bundle targets when the caller does not explicitly request one.
-        currentApp = nil
-        currentBundleId = nil
+        return recordedFailureResponse
       }
-
-      activeApp = currentApp ?? app
-      if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
-        activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
-      } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
-        ensureRunnerHostAppActive(reason: "missing_app_bundle")
-        activeApp = app
+      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
+        NSLog(
+          "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
+          command.command.rawValue
+        )
+        hasRetried = true
+        try runMainThreadWork(
+          command: command,
+          timeout: mainThreadExecutionTimeout,
+          timeoutError: mainThreadExecutionTimeoutError
+        ) {
+          self.invalidateCachedTarget(reason: "response_unavailable")
+          self.sleepFor(self.retryCooldown)
+        }
+        continue
       }
+      return response
+    }
+  }
 
-      let skipExistenceWait = canUseFastForegroundAppGuard(
-        activeApp: activeApp,
-        requestedBundleId: requestedBundleId,
-        command: command.command
+  private func executeSnapshotDispatchedOnce(command: Command) throws -> Response {
+    let preparation = try runMainThreadWork(
+      command: command,
+      timeout: mainThreadExecutionTimeout,
+      timeoutError: mainThreadExecutionTimeoutError
+    ) {
+      try self.prepareActiveCommandContextSafely(command: command)
+    }
+    switch preparation {
+    case .response(let response):
+      return response
+    case .context(let context):
+      return try executeSnapshotPrepared(command: command, activeApp: context.app)
+    }
+  }
+
+  private func executeSnapshotPrepared(command: Command, activeApp: XCUIApplication) throws -> Response {
+    let options = SnapshotOptions(
+      interactiveOnly: command.interactiveOnly ?? false,
+      depth: command.depth,
+      scope: command.scope,
+      raw: command.raw ?? false
+    )
+    do {
+      let payload: DataPayload
+      if options.raw {
+        payload = try snapshotRaw(app: activeApp, options: options)
+      } else {
+        payload = try snapshotFast(app: activeApp, options: options)
+      }
+      setNeedsPostSnapshotInteractionDelay()
+      return Response(ok: true, data: payload)
+    } catch let failure as SnapshotCaptureFailure {
+      invalidateCachedTargetAfterSnapshotFailure()
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: failure.code,
+          message: failure.message,
+          hint: failure.hint
+        )
       )
-      if !skipExistenceWait && !activeApp.waitForExistence(timeout: appExistenceTimeout) {
-        if let bundleId = requestedBundleId {
-          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"))
-        }
+    }
+  }
+
+  private func setNeedsPostSnapshotInteractionDelay() {
+    if Thread.isMainThread {
+      needsPostSnapshotInteractionDelay = true
+      return
+    }
+    guard !hasAbandonedTreeCapture() else {
+      NSLog("AGENT_DEVICE_RUNNER_POST_SNAPSHOT_DELAY_MARK_SKIPPED_XCTEST_OCCUPIED")
+      return
+    }
+    do {
+      try runMainThreadWork(
+        command: nil,
+        timeout: 1,
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        self.needsPostSnapshotInteractionDelay = true
       }
+    } catch {
+      NSLog("AGENT_DEVICE_RUNNER_POST_SNAPSHOT_DELAY_MARK_FAILED=%@", String(describing: error))
+    }
+  }
 
-      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 {
-          ensureRunnerHostAppActive(reason: "interaction_missing_app_bundle")
-          activeApp = app
-        }
-        let skipInteractionExistenceWait = canUseFastForegroundAppGuard(
-          activeApp: activeApp,
-          requestedBundleId: requestedBundleId,
-          command: command.command
-        )
-        if !skipInteractionExistenceWait && !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"))
-        }
-        applyInteractionStabilizationIfNeeded()
+  private func invalidateCachedTargetAfterSnapshotFailure() {
+    if Thread.isMainThread {
+      invalidateCachedTarget(reason: "ax_snapshot_failure")
+      return
+    }
+    do {
+      try runMainThreadWork(
+        command: nil,
+        timeout: 1,
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        self.invalidateCachedTarget(reason: "ax_snapshot_failure")
       }
+    } catch {
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_INVALIDATION_FAILED=%@", String(describing: error))
+    }
+  }
+
+  private func prepareActiveCommandContextSafely(command: Command) throws -> ActiveCommandPreparation {
+    var preparation: ActiveCommandPreparation?
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      preparation = self.prepareActiveCommandContext(command: command)
+    })
+    if let exceptionMessage {
+      throw NSError(
+        domain: RunnerErrorDomain.exception,
+        code: RunnerErrorCode.objcException,
+        userInfo: [NSLocalizedDescriptionKey: exceptionMessage]
+      )
+    }
+    guard let preparation else {
+      throw NSError(
+        domain: RunnerErrorDomain.general,
+        code: RunnerErrorCode.commandReturnedNoResponse,
+        userInfo: [NSLocalizedDescriptionKey: "snapshot preflight returned no response"]
+      )
+    }
+    return preparation
+  }
+
+  private func executeOnMain(command: Command) throws -> Response {
+    let preparation = prepareActiveCommandContext(command: command)
+    let activeApp: XCUIApplication
+    switch preparation {
+    case .response(let response):
+      return response
+    case .context(let context):
+      activeApp = context.app
     }
 
     switch command.command {
@@ -464,6 +649,89 @@ extension RunnerTests {
       }
     case .uptime:
       return executeUptime()
+    default:
+      break
+    }
+    return try executeOnMainPrepared(command: command, activeApp: activeApp)
+  }
+
+  private func prepareActiveCommandContext(command: Command) -> ActiveCommandPreparation {
+    var activeApp = currentApp ?? app
+    if shouldSkipAppActivationPreflight(command) {
+      activeApp = resolveAppWithoutActivation(command: command)
+    } else if !isRunnerLifecycleCommand(command.command) {
+      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
+      }
+
+      activeApp = currentApp ?? app
+      if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
+        activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
+      } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
+        ensureRunnerHostAppActive(reason: "missing_app_bundle")
+        activeApp = app
+      }
+
+      let skipExistenceWait = canUseFastForegroundAppGuard(
+        activeApp: activeApp,
+        requestedBundleId: requestedBundleId,
+        command: command.command
+      )
+      if !skipExistenceWait && !activeApp.waitForExistence(timeout: appExistenceTimeout) {
+        if let bundleId = requestedBundleId {
+          activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
+          guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
+            return .response(Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available")))
+          }
+        } else {
+          return .response(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 {
+          ensureRunnerHostAppActive(reason: "interaction_missing_app_bundle")
+          activeApp = app
+        }
+        let skipInteractionExistenceWait = canUseFastForegroundAppGuard(
+          activeApp: activeApp,
+          requestedBundleId: requestedBundleId,
+          command: command.command
+        )
+        if !skipInteractionExistenceWait && !activeApp.waitForExistence(timeout: 2) {
+          if let bundleId = requestedBundleId {
+            return .response(Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available")))
+          }
+          return .response(Response(ok: false, error: ErrorPayload(message: "runner app is not available")))
+        }
+        applyInteractionStabilizationIfNeeded()
+      }
+    }
+    return .context(ActiveCommandContext(app: activeApp))
+  }
+
+  private func executeOnMainPrepared(command: Command, activeApp: XCUIApplication) throws -> Response {
+    var activeApp = activeApp
+    switch command.command {
+    case .status, .shutdown, .recordStart, .recordStop, .uptime:
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "UNSUPPORTED_OPERATION",
+          message: "\(command.command.rawValue) cannot be executed through the prepared command path"
+        )
+      )
     case .tap:
       if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
         let match = findElement(
@@ -477,6 +745,24 @@ extension RunnerTests {
         }
         if let element = match.element {
           let frame = element.frame
+          // XCTest reports closed-drawer/off-viewport items as hittable, then
+          // "taps" coordinates outside the visible window as a silent no-op.
+          // Refuse instead; the daemon falls back to tree-based resolution,
+          // which can prefer an on-screen candidate or explain the off-screen
+          // state. The check uses the main window frame, not app.frame: on RN
+          // apps app.frame unions transformed subtrees (a closed drawer at
+          // negative x), so it happily "contains" unreachable coordinates.
+          // The DECISION lives in TapPointPolicy (golden parity table with the
+          // TS twin); onScreenWindowFrame only supplies the frame.
+          if !match.usedNonHittableFallback
+            && !TapPointPolicy.isAllowed(
+              elementFrame: frame,
+              windowFrame: onScreenWindowFrame(app: activeApp)
+            ) {
+            return Response(ok: false, error: ErrorPayload(
+              code: "ELEMENT_OFFSCREEN",
+              message: "element resolved off-screen at (\(Int(frame.midX)), \(Int(frame.midY)))"))
+          }
           let isTextEntry = isTextEntryElement(element)
           let touchFrame = frame.isEmpty
             ? nil
@@ -504,27 +790,19 @@ extension RunnerTests {
         }
         return Response(ok: false, error: ErrorPayload(code: "ELEMENT_NOT_FOUND", message: "element not found"))
       }
-      if let text = command.text {
-        if let element = findElement(app: activeApp, text: text) {
-          let (timing, outcome) = performGesture(activeApp) {
-            activateElement(app: activeApp, element: element, action: "tap by text")
-          }
-          if let response = unsupportedResponse(for: outcome) {
-            return response
-          }
-          return gestureResponse(message: "tapped", timing: timing)
-        }
-        return Response(ok: false, error: ErrorPayload(message: "element not found"))
-      }
       if let x = command.x, let y = command.y {
         var fallback: GestureFallback?
         if command.synthesized == true {
+          let policyKind = SynthesizedGesturePolicyKind.coordinateTap
+          let context = synthesizedCoordinateContext(policy: synthesizedGesturePolicy(policyKind))
           let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-            synthesizedTapAt(app: activeApp, x: x, y: y)
+            synthesizedTapAt(app: activeApp, x: x, y: y, context: context)
           }
           if case .performed = outcome {
+            logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: false)
             return gestureResponse(message: "tapped", timing: timing)
           }
+          logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: true)
           fallback = gestureFallback(strategy: "xctest-coordinate-tap", from: outcome)
         }
         let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
@@ -539,7 +817,7 @@ extension RunnerTests {
           fallback: fallback
         )
       }
-      return Response(ok: false, error: ErrorPayload(message: "tap requires text or x/y"))
+      return Response(ok: false, error: ErrorPayload(message: "tap requires a selector or x/y"))
     case .mouseClick:
       guard let x = command.x, let y = command.y else {
         return Response(ok: false, error: ErrorPayload(message: "mouseClick requires x and y"))
@@ -588,12 +866,13 @@ extension RunnerTests {
         y2: y2,
         durationMs: command.durationMs,
         synthesized: command.synthesized == true,
-        message: "dragged"
+        message: "dragged",
+        synthesizedPolicyKind: .synthesizedDrag
       )
     case .scroll:
-      // Fused frame-resolve + drag scroll for non-tvOS. Resolves the interaction frame via
-      // resolvedTouchReferenceFrame, computes drag endpoints with the Swift port of
-      // buildScrollGesturePlan, then runs the same non-synthesized drag path scroll's drag used.
+      // Fused frame-resolve + drag scroll for non-tvOS. On iOS this intentionally stays on the
+      // AX-free synthesized coordinate lane so scroll keeps working when XCTest cannot serialize
+      // the accessibility tree.
       guard let direction = command.direction,
         direction == "up" || direction == "down" || direction == "left" || direction == "right"
       else {
@@ -605,7 +884,14 @@ extension RunnerTests {
           )
         )
       }
-      let frame = resolvedTouchReferenceFrame(app: activeApp, appFrame: activeApp.frame)
+      let scrollPolicyKind = SynthesizedGesturePolicyKind.scroll
+      guard let scrollContext = synthesizedCoordinateContext(policy: synthesizedGesturePolicy(scrollPolicyKind)) else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(message: "scroll could not resolve a usable interaction frame")
+        )
+      }
+      let frame = scrollReferenceFrame(app: activeApp, context: scrollContext)
       guard frame.width > 0, frame.height > 0 else {
         return Response(
           ok: false,
@@ -645,8 +931,10 @@ extension RunnerTests {
         x2: frame.minX + plan.x2,
         y2: frame.minY + plan.y2,
         durationMs: command.durationMs,
-        synthesized: command.durationMs != nil,
-        message: "scrolled"
+        synthesized: shouldUseSynthesizedScrollPath(),
+        message: "scrolled",
+        synthesizedContext: scrollContext.withReferenceFrame(frame),
+        synthesizedPolicyKind: scrollPolicyKind
       )
     case .desktopScroll:
       guard let direction = command.direction,
@@ -780,33 +1068,7 @@ extension RunnerTests {
       }
       return Response(ok: true, data: DataPayload(text: text))
     case .snapshot:
-      let options = SnapshotOptions(
-        interactiveOnly: command.interactiveOnly ?? false,
-        depth: command.depth,
-        scope: command.scope,
-        raw: command.raw ?? false
-      )
-      do {
-        let payload: DataPayload
-        if options.raw {
-          payload = try snapshotRaw(app: activeApp, options: options)
-        } else {
-          payload = try snapshotFast(app: activeApp, options: options)
-        }
-        needsPostSnapshotInteractionDelay = true
-        return Response(ok: true, data: payload)
-      } catch let failure as SnapshotCaptureFailure {
-        invalidateCachedTarget(reason: "ax_snapshot_failure")
-        // Other thrown errors fall through to executeOnMainSafely's generic error response.
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: failure.code,
-            message: failure.message,
-            hint: failure.hint
-          )
-        )
-      }
+      return try executeSnapshotPrepared(command: command, activeApp: activeApp)
     case .screenshot:
       let screenshot: XCUIScreenshot
 #if os(macOS)
@@ -998,10 +1260,9 @@ extension RunnerTests {
     }
   }
 
-  /// Shared drag execution for `.drag` and the fused `.scroll`. Mirrors the original `.drag` body
-  /// exactly: keyboardAvoidingDragPoints -> resolvedDragVisualizationFrame -> synthesized branch
-  /// (16-10000ms clamp) or non-synthesized dragAt with coordinateDragHoldDuration ->
-  /// gestureResponse(.drag). `.scroll` uses the synthesized path only when a duration is requested.
+  /// Shared drag execution for `.drag` and the fused `.scroll`. The iOS synthesized lane keeps
+  /// each command's fallback policy explicit: scroll requires private synthesis, while explicit
+  /// synthesized drag can still use the coordinate fallback unless AX is known unavailable.
   private func executeDragGesture(
     activeApp: XCUIApplication,
     x: Double,
@@ -1010,8 +1271,30 @@ extension RunnerTests {
     y2: Double,
     durationMs: Double?,
     synthesized: Bool,
-    message: String
+    message: String,
+    synthesizedContext: SynthesizedCoordinateContext? = nil,
+    synthesizedPolicyKind: SynthesizedGesturePolicyKind
   ) -> Response {
+    let commandName = dragCommandName(message: message)
+    guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
+      return Response(
+        ok: false,
+        error: ErrorPayload(code: "INVALID_ARGS", message: "\(commandName) requires finite coordinates")
+      )
+    }
+    if synthesized, let synthesizedResponse = executeSynthesizedDragGesture(
+      activeApp: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      durationMs: durationMs,
+      message: message,
+      context: synthesizedContext,
+      policyKind: synthesizedPolicyKind
+    ) {
+      return synthesizedResponse
+    }
     let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
     let dragFrame = resolvedDragVisualizationFrame(
       app: activeApp,
@@ -1023,6 +1306,7 @@ extension RunnerTests {
     var fallback: GestureFallback?
     if synthesized {
       let durationMs = min(max(durationMs ?? 250, 16), 10000)
+      let context = synthesizedCoordinateContext(policy: synthesizedGesturePolicy(synthesizedPolicyKind))
       let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
         synthesizedDragAt(
           app: activeApp,
@@ -1030,7 +1314,8 @@ extension RunnerTests {
           y: dragPoints.y,
           x2: dragPoints.x2,
           y2: dragPoints.y2,
-          durationMs: durationMs
+          durationMs: durationMs,
+          context: context
         )
       }
       if case .performed = outcome {
@@ -1062,6 +1347,154 @@ extension RunnerTests {
     )
   }
 
+  private func executeSynthesizedDragGesture(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double?,
+    message: String,
+    context: SynthesizedCoordinateContext?,
+    policyKind: SynthesizedGesturePolicyKind
+  ) -> Response? {
+#if os(iOS)
+    let policy = synthesizedGesturePolicy(policyKind)
+    let context = context ?? synthesizedCoordinateContext(policy: policy)
+    guard let plan = axFreeSynthesizedDragPlan(
+      app: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      context: context
+    )
+    else {
+      if context?.allowsXCTestCoordinateFallback == true {
+        logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: true)
+        return executeCoordinateDragFallback(
+          activeApp: activeApp,
+          x: x,
+          y: y,
+          x2: x2,
+          y2: y2,
+          durationMs: durationMs,
+          message: message,
+          fallback: nil
+        )
+      }
+      logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: false)
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "INVALID_ARGS",
+          message: "\(dragCommandName(message: message)) could not resolve a finite synthesized coordinate frame"
+        )
+      )
+    }
+    let durationMs = min(max(durationMs ?? 250, 16), 10000)
+    let dragFrame = axFreeDragVisualizationFrame(
+      x: plan.points.x,
+      y: plan.points.y,
+      x2: plan.points.x2,
+      y2: plan.points.y2,
+      referenceFrame: plan.referenceFrame
+    )
+    let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+      synthesizedDragAt(
+        app: activeApp,
+        x: plan.points.x,
+        y: plan.points.y,
+        x2: plan.points.x2,
+        y2: plan.points.y2,
+        durationMs: durationMs,
+        context: plan.context
+      )
+    }
+    if case .performed = outcome {
+      logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: false)
+      return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
+    }
+    if plan.context.allowsXCTestCoordinateFallback {
+      logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: true)
+      return executeCoordinateDragFallback(
+        activeApp: activeApp,
+        x: plan.points.x,
+        y: plan.points.y,
+        x2: plan.points.x2,
+        y2: plan.points.y2,
+        durationMs: durationMs,
+        message: message,
+        fallback: gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
+      )
+    }
+    logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: false)
+    return unsupportedResponse(for: outcome)
+#else
+    return nil
+#endif
+  }
+
+  private func executeCoordinateDragFallback(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double?,
+    message: String,
+    fallback: GestureFallback?
+  ) -> Response {
+    let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
+    let dragFrame = resolvedDragVisualizationFrame(
+      app: activeApp,
+      x: dragPoints.x,
+      y: dragPoints.y,
+      x2: dragPoints.x2,
+      y2: dragPoints.y2
+    )
+    let holdDuration = synthesizedSwipeFallbackHoldDuration(durationMs: durationMs ?? 250)
+    let (timing, outcome) = performGesture(activeApp) {
+      dragAt(
+        app: activeApp,
+        x: dragPoints.x,
+        y: dragPoints.y,
+        x2: dragPoints.x2,
+        y2: dragPoints.y2,
+        holdDuration: holdDuration
+      )
+    }
+    if let response = unsupportedResponse(for: outcome) {
+      return response
+    }
+    return gestureResponse(
+      message: message,
+      timing: timing,
+      frame: .drag(dragFrame),
+      fallback: fallback
+    )
+  }
+
+  private func scrollReferenceFrame(app: XCUIApplication, context: SynthesizedCoordinateContext) -> CGRect {
+#if os(iOS)
+    return synthesizedFrameAvoidingKeyboardWhenAllowed(app: app, context: context)
+#else
+    return resolvedTouchReferenceFrame(app: app, appFrame: app.frame)
+#endif
+  }
+
+  private func shouldUseSynthesizedScrollPath() -> Bool {
+#if os(iOS)
+    return true
+#else
+    return false
+#endif
+  }
+
+  private func dragCommandName(message: String) -> String {
+    return message == "scrolled" ? "scroll" : "drag"
+  }
+
   private func currentXCTestFailureCount() -> Int {
     return testRun?.failureCount ?? 0
   }
@@ -1094,20 +1527,31 @@ extension RunnerTests {
 
   private func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
 #if os(iOS)
-    // Coordinate-only synthesized taps can run after an AX-fatal screen because they do not need
-    // app activation, window lookup, keyboard lookup, or element resolution. Selector/text taps
-    // intentionally stay on the normal AX path because they need an element query.
+    // Coordinate-only synthesized taps can run after an AX-fatal screen because they do not
+    // need app activation, window lookup, keyboard lookup, or element resolution. Selector/text
+    // interactions intentionally stay on the normal AX path because they need an element query.
+    // Scroll/drag/sequence keep the normal foreground guard and stabilization path.
+    guard command.text == nil, command.selectorKey == nil else { return false }
+    guard hasCachedTargetForActivationSkip(command: command) else { return false }
     return command.command == .tap
       && command.synthesized == true
       && command.x != nil
       && command.y != nil
-      && command.text == nil
-      && command.selectorKey == nil
 #else
     return false
 #endif
   }
 
+  private func hasCachedTargetForActivationSkip(command: Command) -> Bool {
+    guard currentApp != nil else { return false }
+    guard let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+      !bundleId.isEmpty
+    else {
+      return true
+    }
+    return currentBundleId == bundleId
+  }
+
   private func resolveAppWithoutActivation(command: Command) -> XCUIApplication {
     guard let bundleId = command.appBundleId?
       .trimmingCharacters(in: .whitespacesAndNewlines),
@@ -1128,6 +1572,7 @@ extension RunnerTests {
     let delaySeconds = Double(max(command.delayMs ?? 0, 0)) / 1000.0
     let textEntryMode = resolveTextEntryMode(command)
     let target: TextEntryTarget
+    let focusStartedAt = Date()
     if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
       let match = findElement(
         app: activeApp,
@@ -1148,6 +1593,13 @@ extension RunnerTests {
     } else {
       target = focusTextInputForTextEntry(app: activeApp, x: command.x, y: command.y)
     }
+    NSLog(
+      "AGENT_DEVICE_RUNNER_TEXT_ENTRY_PHASE commandId=%@ phase=focus durationMs=%.1f chars=%d mode=%@",
+      command.commandId ?? "",
+      Date().timeIntervalSince(focusStartedAt) * 1000.0,
+      text.count,
+      textEntryModeName(textEntryMode)
+    )
     if textEntryMode == .replacement {
       guard target.element != nil else {
         let message =
@@ -1162,7 +1614,8 @@ extension RunnerTests {
       target: target,
       text: text,
       delaySeconds: delaySeconds,
-      repairMode: textEntryMode
+      repairMode: textEntryMode,
+      commandId: command.commandId
     )
     if textResult.verified == false {
       let expected = textResult.expectedText ?? ""