agent-device 0.19.3 → 0.20.1

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"))
@@ -649,15 +755,46 @@ extension RunnerTests {
       }
     case .uptime:
       return executeUptime()
+    case .activate:
+      guard
+        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !bundleId.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "activate requires appBundleId"))
+      }
+      // prepareActiveCommandContext already activated this bundle. Keep this case as the
+      // explicit acknowledgement after that preflight, not as a second activation.
+      return Response(ok: true, data: DataPayload(message: "app activated"))
+    case .terminate:
+      guard
+        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !bundleId.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "terminate requires appBundleId"))
+      }
+      XCUIApplication(bundleIdentifier: bundleId).terminate()
+      if currentBundleId == bundleId {
+        invalidateCachedTarget(reason: "target_terminated")
+      }
+      return Response(ok: true, data: DataPayload(message: "app terminated"))
     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 +803,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 +859,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, .activate, .terminate, .targetReset, .shutdown, .recordStart, .recordStop, .uptime:
       return Response(
         ok: false,
         error: ErrorPayload(
@@ -734,11 +876,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 +916,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 +941,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"))
@@ -867,7 +1027,6 @@ extension RunnerTests {
         durationMs: command.durationMs,
         synthesized: command.synthesized == true,
         message: "dragged",
-        dragSemantics: command.dragSemantics,
         synthesizedPolicyKind: .synthesizedDrag
       )
     case .scroll:
@@ -1094,6 +1253,12 @@ extension RunnerTests {
       guard let pngData = runnerPngData(for: screenshot.image) else {
         return Response(ok: false, error: ErrorPayload(message: "Failed to encode screenshot as PNG"))
       }
+      if command.inlineScreenshot == true {
+        return Response(
+          ok: true,
+          data: DataPayload(imageBase64: pngData.base64EncodedString())
+        )
+      }
       let fileName = "screenshot-\(Int(Date().timeIntervalSince1970 * 1000)).png"
       let filePath = (NSTemporaryDirectory() as NSString).appendingPathComponent(fileName)
       do {
@@ -1127,15 +1292,35 @@ extension RunnerTests {
       else {
         return Response(ok: false, error: ErrorPayload(message: "rotate requires orientation"))
       }
-      if rotateDevice(to: orientation) {
+      let supportedOrientations = [
+        "portrait",
+        "portrait-upside-down",
+        "landscape-left",
+        "landscape-right",
+      ]
+      guard supportedOrientations.contains(orientation) else {
         return Response(
-          ok: true,
-          data: DataPayload(message: "rotate", orientation: orientation)
+          ok: false,
+          error: ErrorPayload(message: "unsupported rotate orientation: \(orientation)")
+        )
+      }
+      guard let observedOrientation = rotateDevice(to: orientation) else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(message: "unable to observe device orientation after rotate")
+        )
+      }
+      guard observedOrientation == orientation else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(
+            message: "device orientation is \(observedOrientation), expected \(orientation)"
+          )
         )
       }
       return Response(
-        ok: false,
-        error: ErrorPayload(message: "unsupported rotate orientation: \(orientation)")
+        ok: true,
+        data: DataPayload(message: "rotate", orientation: observedOrientation)
       )
     case .appSwitcher:
       performAppSwitcherGesture(app: activeApp)
@@ -1183,83 +1368,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)
     }
   }
 
@@ -1275,9 +1437,9 @@ extension RunnerTests {
     durationMs: Double?,
     synthesized: Bool,
     message: String,
-    dragSemantics: SynthesizedDragSemantics? = nil,
     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 {
@@ -1294,9 +1456,9 @@ extension RunnerTests {
       y2: y2,
       durationMs: durationMs,
       message: message,
-      dragSemantics: dragSemantics,
       context: synthesizedContext,
-      policyKind: synthesizedPolicyKind
+      policyKind: synthesizedPolicyKind,
+      profile: synthesizedProfile
     ) {
       return synthesizedResponse
     }
@@ -1320,7 +1482,7 @@ extension RunnerTests {
           x2: dragPoints.x2,
           y2: dragPoints.y2,
           durationMs: durationMs,
-          semantics: dragSemantics,
+          profile: synthesizedProfile,
           context: context
         )
       }
@@ -1361,9 +1523,9 @@ extension RunnerTests {
     y2: Double,
     durationMs: Double?,
     message: String,
-    dragSemantics: SynthesizedDragSemantics?,
     context: SynthesizedCoordinateContext?,
-    policyKind: SynthesizedGesturePolicyKind
+    policyKind: SynthesizedGesturePolicyKind,
+    profile: SynthesizedDragProfile
   ) -> Response? {
 #if os(iOS)
     let policy = synthesizedGesturePolicy(policyKind)
@@ -1415,7 +1577,7 @@ extension RunnerTests {
         x2: plan.points.x2,
         y2: plan.points.y2,
         durationMs: durationMs,
-        semantics: dragSemantics,
+        profile: profile,
         context: plan.context
       )
     }
@@ -1535,23 +1697,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 {
@@ -1580,6 +1777,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(
@@ -1597,6 +1795,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)
@@ -1645,7 +1846,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
       )
     )
   }