agent-device 0.19.0 → 0.19.1

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

@@ -188,6 +188,15 @@ extension RunnerTests {
     var abandoned = false
   }
 
+  struct ActiveCommandContext {
+    let app: XCUIApplication
+  }
+
+  enum ActiveCommandPreparation {
+    case response(Response)
+    case context(ActiveCommandContext)
+  }
+
   enum MainThreadBusyState {
     case idle
     case busy(abandonedForSeconds: TimeInterval)
@@ -259,12 +268,35 @@ extension RunnerTests {
     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)
       }
@@ -275,15 +307,16 @@ extension RunnerTests {
           self.abandonedMainThreadWorkSince = nil
           NSLog("AGENT_DEVICE_RUNNER_ABANDONED_WORK_DRAINED")
         }
+        self.mainThreadWorkLock.unlock()
+        onDrained?()
       } else {
         workState.finished = true
+        self.mainThreadWorkLock.unlock()
       }
-      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.
       mainThreadWorkLock.lock()
       let stillRunning = !workState.finished
       if stillRunning {
@@ -292,24 +325,14 @@ extension RunnerTests {
         if abandonedMainThreadWorkSince == nil {
           abandonedMainThreadWorkSince = Date()
         }
+        onAbandoned?()
       }
       mainThreadWorkLock.unlock()
-      if stillRunning && command.command == .snapshot {
-        // The next capture on this screen must not re-grind the tree backend.
-        penalizeSnapshotTreeBackend(
-          bundleId: command.appBundleId,
-          reason: "main_thread_watchdog"
-        )
-      }
-      throw NSError(
-        domain: RunnerErrorDomain.general,
-        code: RunnerErrorCode.mainThreadExecutionTimedOut,
-        userInfo: [NSLocalizedDescriptionKey: "main thread execution timed out"]
-      )
+      throw timeoutError()
     }
     switch result {
-    case .success(let response):
-      return response
+    case .success(let value):
+      return value
     case .failure(let error):
       throw error
     case .none:
@@ -321,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 {
@@ -384,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 {
@@ -515,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(
@@ -576,12 +793,16 @@ extension RunnerTests {
       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)
@@ -645,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 {
@@ -662,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,
@@ -702,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,
@@ -837,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)
@@ -1055,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,
@@ -1067,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,
@@ -1080,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,
@@ -1087,7 +1314,8 @@ extension RunnerTests {
           y: dragPoints.y,
           x2: dragPoints.x2,
           y2: dragPoints.y2,
-          durationMs: durationMs
+          durationMs: durationMs,
+          context: context
         )
       }
       if case .performed = outcome {
@@ -1119,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
   }
@@ -1151,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),