agent-device 0.19.2 → 0.20.0

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

@@ -1,5 +1,6 @@
 import XCTest
 
+
 extension RunnerTests {
   // MARK: - Main Thread Dispatch
 
@@ -58,7 +59,7 @@ extension RunnerTests {
 
   /// Runs a gesture action with uniform timing capture. Touch gestures pass `idleTimeout: true`
   /// (the default) to run inside the scroll idle-timeout + quiescence-skip wrapper; synthesis
-  /// gestures (pinch/rotate/transform) pass `false` because RunnerSynthesizedGesture governs its
+  /// pointer-plan gestures pass `false` because RunnerSynthesizedGesture governs their
   /// own timing. Returns the captured timing and the action's outcome.
   ///
   /// NOTE: a new SYNTHESIS gesture must pass `idleTimeout: false` — the default `true` would wrap
@@ -85,7 +86,8 @@ extension RunnerTests {
     message: String,
     timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
     frame: GestureFrame = .none,
-    fallback: GestureFallback? = nil
+    fallback: GestureFallback? = nil,
+    maestroNonHittableCoordinateFallbackUsed: Bool? = nil
   ) -> Response {
     let data: DataPayload
     switch frame {
@@ -96,7 +98,8 @@ extension RunnerTests {
         gestureEndUptimeMs: timing.gestureEndUptimeMs,
         gestureFallback: fallback?.strategy,
         gestureFallbackMessage: fallback?.message,
-        gestureFallbackHint: fallback?.hint
+        gestureFallbackHint: fallback?.hint,
+        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
       )
     case .touch(let f):
       data = DataPayload(
@@ -109,7 +112,8 @@ extension RunnerTests {
         referenceHeight: f?.referenceHeight,
         gestureFallback: fallback?.strategy,
         gestureFallbackMessage: fallback?.message,
-        gestureFallbackHint: fallback?.hint
+        gestureFallbackHint: fallback?.hint,
+        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
       )
     case .drag(let f):
       data = DataPayload(
@@ -130,6 +134,24 @@ extension RunnerTests {
     return Response(ok: true, data: data)
   }
 
+  /// Gesture plans already return canonical centroid endpoints from the portable runtime.
+  /// Keep runner timing/fallback diagnostics, but do not leak the coordinate-drag adapter's
+  /// visualization frame into only the fast-fling response shape.
+  private func canonicalPlannedGestureResponse(_ response: Response) -> Response {
+    guard response.ok, let data = response.data else { return response }
+    return Response(
+      ok: true,
+      data: DataPayload(
+        message: data.message,
+        gestureStartUptimeMs: data.gestureStartUptimeMs,
+        gestureEndUptimeMs: data.gestureEndUptimeMs,
+        gestureFallback: data.gestureFallback,
+        gestureFallbackMessage: data.gestureFallbackMessage,
+        gestureFallbackHint: data.gestureFallbackHint
+      )
+    )
+  }
+
 
   func execute(command: Command) throws -> Response {
     if command.command == .status {
@@ -252,31 +274,71 @@ extension RunnerTests {
     )
   }
 
-  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).
+  private func runnerUnavailableResponse(command: Command) -> Response? {
     switch currentMainThreadBusyState() {
     case .idle:
-      break
+      return nil
     case .busy(let abandonedForSeconds):
       return runnerBusyResponse(command: command, abandonedForSeconds: abandonedForSeconds)
     case .wedged(let abandonedForSeconds):
       return runnerWedgedResponse(command: command, abandonedForSeconds: abandonedForSeconds)
     }
+  }
+
+  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).
+    if let unavailable = runnerUnavailableResponse(command: command) {
+      return unavailable
+    }
+    let alertDeadline = command.command == .alert
+      ? Date().addingTimeInterval(Self.alertCommandTimeout(timeoutMs: command.timeoutMs))
+      : nil
     if Thread.isMainThread {
-      return try executeOnMainSafely(command: command)
+      let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(
+        command,
+        deadline: alertDeadline
+      )
+      return try executeOnMainSafely(
+        command: command,
+        alertDeadline: alertDeadline,
+        routeToSpringboard: routeToSpringboard
+      )
+    }
+    // Resolve this before the command's outer main-thread block. If the bounded probe abandons
+    // slow XCTest enumeration, return the established recoverable response instead of queueing
+    // command preparation behind work that may outlive the 30-second command watchdog.
+    let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(
+      command,
+      deadline: alertDeadline
+    )
+    if let unavailable = runnerUnavailableResponse(command: command) {
+      return unavailable
     }
     if command.command == .snapshot {
       return try executeSnapshotDispatched(command: command)
     }
+    if command.command == .alert, let deadline = alertDeadline {
+      return try runMainThreadWork(
+        command: command,
+        timeout: max(0.001, deadline.timeIntervalSinceNow),
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        try self.executeOnMainSafely(
+          command: command,
+          alertDeadline: deadline,
+          routeToSpringboard: routeToSpringboard
+        )
+      }
+    }
     return try runMainThreadWork(
       command: command,
       timeout: mainThreadExecutionTimeout,
       timeoutError: mainThreadExecutionTimeoutError
     ) {
-      try self.executeOnMainSafely(command: command)
+      try self.executeOnMainSafely(command: command, routeToSpringboard: routeToSpringboard)
     }
   }
 
@@ -354,7 +416,11 @@ extension RunnerTests {
 
   // MARK: - Command Handling
 
-  private func executeOnMainSafely(command: Command) throws -> Response {
+  private func executeOnMainSafely(
+    command: Command,
+    alertDeadline: Date? = nil,
+    routeToSpringboard: Bool
+  ) throws -> Response {
     var hasRetried = false
     while true {
       var response: Response?
@@ -362,7 +428,11 @@ extension RunnerTests {
       let failureCountBefore = currentXCTestFailureCount()
       let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
         do {
-          response = try self.executeOnMain(command: command)
+          response = try self.executeOnMain(
+            command: command,
+            alertDeadline: alertDeadline,
+            routeToSpringboard: routeToSpringboard
+          )
         } catch {
           swiftError = error
         }
@@ -416,6 +486,18 @@ extension RunnerTests {
   }
 
   private func executeSnapshotDispatched(command: Command) throws -> Response {
+    try executeDispatchedWithRecovery(command: command) {
+      try self.executeSnapshotDispatchedOnce(command: command)
+    }
+  }
+
+  /// The dispatched snapshot recovery loop: read-only retry + XCTest-recorded-failure invalidation,
+  /// matching what `executeOnMainSafely` gives the generic path. `perform` runs the capture and its
+  /// own bounded main-thread work.
+  func executeDispatchedWithRecovery(
+    command: Command,
+    perform: () throws -> Response
+  ) throws -> Response {
     var hasRetried = false
     while true {
       let failureCountBefore = try runMainThreadWork(
@@ -425,7 +507,16 @@ extension RunnerTests {
       ) {
         self.currentXCTestFailureCount()
       }
-      let response = try executeSnapshotDispatchedOnce(command: command)
+      let response = try perform()
+      // Recovered independently — re-entering main for bookkeeping would queue behind the still-
+      // abandoned XCTest query and re-stall the command (#1244), so skip it until that work drains.
+      if hasAbandonedTreeCapture() {
+        NSLog(
+          "AGENT_DEVICE_RUNNER_DISPATCH_RECOVERY_SKIPPED_XCTEST_OCCUPIED command=%@",
+          command.command.rawValue
+        )
+        return response
+      }
       let recordedFailureResponse = try runMainThreadWork(
         command: command,
         timeout: mainThreadExecutionTimeout,
@@ -471,7 +562,7 @@ extension RunnerTests {
       timeout: mainThreadExecutionTimeout,
       timeoutError: mainThreadExecutionTimeoutError
     ) {
-      try self.prepareActiveCommandContextSafely(command: command)
+      try self.prepareActiveCommandContextSafely(command: command, routeToSpringboard: false)
     }
     switch preparation {
     case .response(let response):
@@ -550,10 +641,16 @@ extension RunnerTests {
     }
   }
 
-  private func prepareActiveCommandContextSafely(command: Command) throws -> ActiveCommandPreparation {
+  private func prepareActiveCommandContextSafely(
+    command: Command,
+    routeToSpringboard: Bool
+  ) throws -> ActiveCommandPreparation {
     var preparation: ActiveCommandPreparation?
     let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      preparation = self.prepareActiveCommandContext(command: command)
+      preparation = self.prepareActiveCommandContext(
+        command: command,
+        routeToSpringboard: routeToSpringboard
+      )
     })
     if let exceptionMessage {
       throw NSError(
@@ -572,8 +669,15 @@ extension RunnerTests {
     return preparation
   }
 
-  private func executeOnMain(command: Command) throws -> Response {
-    let preparation = prepareActiveCommandContext(command: command)
+  private func executeOnMain(
+    command: Command,
+    alertDeadline: Date?,
+    routeToSpringboard: Bool
+  ) throws -> Response {
+    let preparation = prepareActiveCommandContext(
+      command: command,
+      routeToSpringboard: routeToSpringboard
+    )
     let activeApp: XCUIApplication
     switch preparation {
     case .response(let response):
@@ -585,6 +689,8 @@ extension RunnerTests {
     switch command.command {
     case .status:
       return executeStatus(command: command)
+    case .targetReset:
+      return resetTargetAfterExternalRelaunch()
     case .shutdown:
       stopRecordingIfNeeded()
       return Response(ok: true, data: DataPayload(message: "shutdown"))
@@ -652,12 +758,21 @@ extension RunnerTests {
     default:
       break
     }
-    return try executeOnMainPrepared(command: command, activeApp: activeApp)
+    return try executeOnMainPrepared(
+      command: command,
+      activeApp: activeApp,
+      alertDeadline: alertDeadline
+    )
   }
 
-  private func prepareActiveCommandContext(command: Command) -> ActiveCommandPreparation {
+  private func prepareActiveCommandContext(
+    command: Command,
+    routeToSpringboard: Bool = false
+  ) -> ActiveCommandPreparation {
     var activeApp = currentApp ?? app
-    if shouldSkipAppActivationPreflight(command) {
+    if routeToSpringboard {
+      activeApp = springboard
+    } else if shouldSkipAppActivationPreflight(command) {
       activeApp = resolveAppWithoutActivation(command: command)
     } else if !isRunnerLifecycleCommand(command.command) {
       let normalizedBundleId = command.appBundleId?
@@ -666,11 +781,12 @@ extension RunnerTests {
       if let bundleId = requestedBundleId {
         if currentBundleId != bundleId || currentApp == nil {
           _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
+        } else {
+          refreshCachedTargetIfProcessChanged(bundleId: bundleId)
         }
       } else {
         // Do not reuse stale bundle targets when the caller does not explicitly request one.
-        currentApp = nil
-        currentBundleId = nil
+        invalidateCachedTarget(reason: "missing_app_bundle")
       }
 
       activeApp = currentApp ?? app
@@ -721,10 +837,14 @@ extension RunnerTests {
     return .context(ActiveCommandContext(app: activeApp))
   }
 
-  private func executeOnMainPrepared(command: Command, activeApp: XCUIApplication) throws -> Response {
+  private func executeOnMainPrepared(
+    command: Command,
+    activeApp: XCUIApplication,
+    alertDeadline: Date? = nil
+  ) throws -> Response {
     var activeApp = activeApp
     switch command.command {
-    case .status, .shutdown, .recordStart, .recordStop, .uptime:
+    case .status, .targetReset, .shutdown, .recordStart, .recordStop, .uptime:
       return Response(
         ok: false,
         error: ErrorPayload(
@@ -734,11 +854,21 @@ extension RunnerTests {
       )
     case .tap:
       if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
+        let expectedPoint: CGPoint?
+        if command.allowNonHittableCoordinateFallback == true,
+          let x = command.x,
+          let y = command.y
+        {
+          expectedPoint = CGPoint(x: x, y: y)
+        } else {
+          expectedPoint = nil
+        }
         let match = findElement(
           app: activeApp,
           selectorKey: selectorKey,
           selectorValue: selectorValue,
-          allowNonHittableFallback: command.allowNonHittableCoordinateFallback == true
+          allowNonHittableFallback: command.allowNonHittableCoordinateFallback == true,
+          expectedPoint: expectedPoint
         )
         if match.isAmbiguous {
           return Response(ok: false, error: ErrorPayload(code: "AMBIGUOUS_MATCH", message: "selector matched multiple elements"))
@@ -764,15 +894,19 @@ extension RunnerTests {
               message: "element resolved off-screen at (\(Int(frame.midX)), \(Int(frame.midY)))"))
           }
           let isTextEntry = isTextEntryElement(element)
-          let touchFrame = frame.isEmpty
-            ? nil
-            : resolvedTouchVisualizationFrame(app: activeApp, x: frame.midX, y: frame.midY)
+          let touchPoint = expectedPoint ?? CGPoint(x: frame.midX, y: frame.midY)
+          let touchFrame = resolvedTouchVisualizationFrame(
+            app: activeApp,
+            x: touchPoint.x,
+            y: touchPoint.y
+          )
           let (timing, outcome) = performGesture(activeApp) {
-            if match.usedNonHittableFallback {
+            if expectedPoint != nil || match.usedNonHittableFallback {
               // Maestro compatibility: RN E2E backdoor controls can be 1x1 and
-              // reported non-hittable by XCTest, while Maestro still taps their
-              // resolved bounds. Keep this behind the explicit replay-only flag.
-              return tapAt(app: activeApp, x: frame.midX, y: frame.midY)
+              // reported non-hittable by XCTest. Snapshot-resolved targets also
+              // need coordinate delivery because XCUIElement.activate() does not
+              // invoke every React Native accessibility wrapper.
+              return tapAt(app: activeApp, x: touchPoint.x, y: touchPoint.y)
             }
             return activateElement(app: activeApp, element: element, action: "tap by selector")
           }
@@ -785,7 +919,11 @@ extension RunnerTests {
           return gestureResponse(
             message: match.usedNonHittableFallback ? "tapped via non-hittable coordinate fallback" : "tapped",
             timing: timing,
-            frame: .touch(touchFrame)
+            frame: .touch(touchFrame),
+            maestroNonHittableCoordinateFallbackUsed:
+              command.allowNonHittableCoordinateFallback == true
+              ? match.usedNonHittableFallback
+              : nil
           )
         }
         return Response(ok: false, error: ErrorPayload(code: "ELEMENT_NOT_FOUND", message: "element not found"))
@@ -1146,7 +1284,9 @@ extension RunnerTests {
           ok: false,
           error: ErrorPayload(
             code: "UNSUPPORTED_OPERATION",
-            message: "Unable to dismiss the iOS keyboard without a safe native dismiss control"
+            message: "Unable to dismiss the iOS keyboard without a safe native dismiss control",
+            hint:
+              "The on-screen keyboard usually does not block agent-device interactions: press the next target directly instead of retrying dismiss. If that press fails or reports no visible effect, scroll the target into view, or use keyboard enter to press the return key when submission is wanted."
           )
         )
       }
@@ -1180,83 +1320,60 @@ extension RunnerTests {
       )
     case .alert:
       let action = (command.action ?? "get").lowercased()
-      guard let alert = resolveAlert(app: activeApp) else {
+      let deadline = alertDeadline ?? Date().addingTimeInterval(
+        Self.alertCommandTimeout(timeoutMs: command.timeoutMs)
+      )
+      guard let alert = resolveAlert(app: activeApp, deadline: deadline) else {
         return Response(ok: false, error: ErrorPayload(message: "alert not found"))
       }
-      return handleAlert(alert, action: action)
-    case .pinch:
-      guard let scale = command.scale, scale > 0 else {
-        return Response(ok: false, error: ErrorPayload(message: "pinch requires scale > 0"))
-      }
-      let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-        pinch(app: activeApp, scale: scale, x: command.x, y: command.y)
-      }
-      if let response = unsupportedResponse(for: outcome) {
-        return response
-      }
-      return gestureResponse(message: "pinched", timing: timing)
-    case .sequence:
-      return executeSequence(command: command, activeApp: activeApp)
-    case .rotateGesture:
-      guard let degrees = command.degrees, degrees.isFinite else {
-        return Response(ok: false, error: ErrorPayload(message: "rotateGesture requires degrees"))
-      }
-      let velocity = command.velocity ?? (degrees >= 0 ? 1.0 : -1.0)
-      guard velocity.isFinite && velocity != 0 else {
-        return Response(ok: false, error: ErrorPayload(message: "rotateGesture velocity must be non-zero"))
-      }
-      let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-        rotateGesture(
-          app: activeApp,
-          degrees: degrees,
-          x: command.x,
-          y: command.y,
-          velocity: velocity
+      return handleAlert(alert, action: action, deadline: deadline)
+    case .gesture:
+      guard let plan = command.gesturePlan else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(code: "INVALID_ARGS", message: "gesture requires gesturePlan")
         )
       }
-      if let response = unsupportedResponse(for: outcome) {
-        return response
-      }
-      return gestureResponse(message: "rotatedGesture", timing: timing)
-    case .transformGesture:
-      guard
-        let x = command.x,
-        let y = command.y,
-        let dx = command.dx,
-        let dy = command.dy,
-        x.isFinite,
-        y.isFinite,
-        dx.isFinite,
-        dy.isFinite
-      else {
-        return Response(ok: false, error: ErrorPayload(message: "transformGesture requires finite x y dx dy"))
-      }
-      guard let scale = command.scale, scale.isFinite, scale > 0 else {
-        return Response(ok: false, error: ErrorPayload(message: "transformGesture requires scale > 0"))
-      }
-      guard let degrees = command.degrees, degrees.isFinite else {
-        return Response(ok: false, error: ErrorPayload(message: "transformGesture requires finite degrees"))
+      if let validationError = plannedGestureValidationError(plan) {
+        return Response(
+          ok: false,
+          error: ErrorPayload(code: "INVALID_ARGS", message: validationError)
+        )
       }
-      let durationMs = command.durationMs ?? 300
-      guard durationMs.isFinite && durationMs >= 16 else {
-        return Response(ok: false, error: ErrorPayload(message: "transformGesture durationMs must be >= 16"))
+      if plannedGestureExecution(for: plan) == .fastSwipe {
+        // Validation above guarantees a non-empty, single-pointer path for this execution kind.
+        let first = plan.pointers[0].samples.first!.point
+        let last = plan.pointers[0].samples.last!.point
+        return canonicalPlannedGestureResponse(
+          executeDragGesture(
+            activeApp: activeApp,
+            x: first.x,
+            y: first.y,
+            x2: last.x,
+            y2: last.y,
+            durationMs: plan.durationMs,
+            synthesized: true,
+            message: plan.intent,
+            synthesizedPolicyKind: .synthesizedDrag,
+            synthesizedProfile: .fastSwipe
+          )
+        )
       }
       let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-        transformGesture(
-          app: activeApp,
-          x: x,
-          y: y,
-          dx: dx,
-          dy: dy,
-          scale: scale,
-          degrees: degrees,
-          durationMs: durationMs
-        )
+        sampledPlannedGesture(app: activeApp, plan: plan)
       }
       if let response = unsupportedResponse(for: outcome) {
         return response
       }
-      return gestureResponse(message: "transformedGesture", timing: timing)
+      return gestureResponse(message: plan.intent, timing: timing)
+    case .gestureViewport:
+      let frame = resolvedTouchReferenceFrame(app: activeApp, appFrame: activeApp.frame)
+      guard !frame.isNull, !frame.isInfinite, !frame.isEmpty else {
+        return Response(ok: false, error: ErrorPayload(code: "COMMAND_FAILED", message: "Active app interaction viewport is unavailable"))
+      }
+      return Response(ok: true, data: DataPayload(message: "gestureViewport", x: frame.minX, y: frame.minY, x2: frame.width, y2: frame.height))
+    case .sequence:
+      return executeSequence(command: command, activeApp: activeApp)
     }
   }
 
@@ -1273,7 +1390,8 @@ extension RunnerTests {
     synthesized: Bool,
     message: String,
     synthesizedContext: SynthesizedCoordinateContext? = nil,
-    synthesizedPolicyKind: SynthesizedGesturePolicyKind
+    synthesizedPolicyKind: SynthesizedGesturePolicyKind,
+    synthesizedProfile: SynthesizedDragProfile = .continuous
   ) -> Response {
     let commandName = dragCommandName(message: message)
     guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
@@ -1291,7 +1409,8 @@ extension RunnerTests {
       durationMs: durationMs,
       message: message,
       context: synthesizedContext,
-      policyKind: synthesizedPolicyKind
+      policyKind: synthesizedPolicyKind,
+      profile: synthesizedProfile
     ) {
       return synthesizedResponse
     }
@@ -1315,6 +1434,7 @@ extension RunnerTests {
           x2: dragPoints.x2,
           y2: dragPoints.y2,
           durationMs: durationMs,
+          profile: synthesizedProfile,
           context: context
         )
       }
@@ -1356,7 +1476,8 @@ extension RunnerTests {
     durationMs: Double?,
     message: String,
     context: SynthesizedCoordinateContext?,
-    policyKind: SynthesizedGesturePolicyKind
+    policyKind: SynthesizedGesturePolicyKind,
+    profile: SynthesizedDragProfile
   ) -> Response? {
 #if os(iOS)
     let policy = synthesizedGesturePolicy(policyKind)
@@ -1408,6 +1529,7 @@ extension RunnerTests {
         x2: plan.points.x2,
         y2: plan.points.y2,
         durationMs: durationMs,
+        profile: profile,
         context: plan.context
       )
     }
@@ -1527,23 +1649,58 @@ 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
+    if command.command == .alert {
+      return true
+    }
+    // Coordinate-only synthesized taps can run after an AX-fatal foreground 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
+    return isCoordinateOnlyTap(command)
+#else
+    return false
+#endif
+  }
+
+  private func shouldRouteToSpringboardBlockingSystemModal(
+    _ command: Command,
+    deadline: Date? = nil
+  ) -> Bool {
+#if os(iOS)
+    guard command.command == .alert || isCoordinateOnlyTap(command) else {
+      return false
+    }
+    let budgetDeadline = Date().addingTimeInterval(systemModalProbeBudget)
+    let probeDeadline = deadline.map { min($0, budgetDeadline) } ?? budgetDeadline
+    // `runMainThreadWork` executes inline for a main-thread caller, so that path cannot use its
+    // timeout machinery. Direct main-thread dispatch keeps the prior synchronous modal check;
+    // normal off-main command dispatch uses the bounded probe and post-probe busy recovery.
+    if Thread.isMainThread {
+      return firstBlockingSystemModal(
+        in: springboard,
+        deadline: probeDeadline
+      ) != nil
+    }
+    return boundedBlockingSystemAlertSnapshot(
+      deadline: probeDeadline
+    ) != nil
 #else
     return false
 #endif
   }
 
+  private func isCoordinateOnlyTap(_ command: Command) -> Bool {
+    return command.command == .tap
+      && command.text == nil
+      && command.selectorKey == nil
+      && command.x != nil
+      && command.y != nil
+  }
+
   private func hasCachedTargetForActivationSkip(command: Command) -> Bool {
-    guard currentApp != nil else { return false }
+    guard let currentApp, currentApp.state == .runningForeground else { return false }
     guard let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
       !bundleId.isEmpty
     else {
@@ -1572,6 +1729,7 @@ extension RunnerTests {
     let delaySeconds = Double(max(command.delayMs ?? 0, 0)) / 1000.0
     let textEntryMode = resolveTextEntryMode(command)
     let target: TextEntryTarget
+    var maestroNonHittableCoordinateFallbackUsed: Bool?
     let focusStartedAt = Date()
     if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
       let match = findElement(
@@ -1589,6 +1747,9 @@ extension RunnerTests {
       guard isTextEntryElement(element) else {
         return Response(ok: false, error: ErrorPayload(code: "INVALID_TARGET", message: "selector did not match a text input"))
       }
+      if command.allowNonHittableCoordinateFallback == true {
+        maestroNonHittableCoordinateFallbackUsed = match.usedNonHittableFallback
+      }
       target = focusTextInputForTextEntry(app: activeApp, element: element)
     } else {
       target = focusTextInputForTextEntry(app: activeApp, x: command.x, y: command.y)
@@ -1637,7 +1798,8 @@ extension RunnerTests {
         x: point.map { Double($0.x) },
         y: point.map { Double($0.y) },
         referenceWidth: frame.isEmpty ? nil : Double(frame.width),
-        referenceHeight: frame.isEmpty ? nil : Double(frame.height)
+        referenceHeight: frame.isEmpty ? nil : Double(frame.height),
+        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
       )
     )
   }

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

@@ -146,8 +146,8 @@ final class RunnerCommandJournal {
     case .tap, .mouseClick, .longPress, .drag,
          .remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText, .back,
          .backInApp, .backSystem, .home, .rotate, .appSwitcher, .keyboardDismiss, .keyboardReturn,
-         .alert, .pinch, .sequence, .rotateGesture, .transformGesture, .recordStart, .recordStop,
-         .status, .uptime, .shutdown:
+         .alert, .sequence, .gesture, .gestureViewport, .recordStart, .recordStop,
+         .status, .uptime, .targetReset, .shutdown:
       return true
     }
   }