agent-device 0.20.10 → 0.21.1

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

@@ -1,8 +1,33 @@
 import XCTest
+import AgentDeviceSnapshotPresentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 extension RunnerTests {
-  // MARK: - Main Thread Dispatch
+
 
   private func currentUptimeMs() -> Double {
     ProcessInfo.processInfo.systemUptime * 1000
@@ -34,7 +59,7 @@ extension RunnerTests {
     }
   }
 
-  /// Optional visualization frame returned with a gesture response.
+
   enum GestureFrame {
     case none
     case touch(TouchVisualizationFrame?)
@@ -57,13 +82,13 @@ 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
-  /// 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
-  /// it in the scroll idle-timeout/quiescence-skip path and change its runtime behavior.
+
+
+
+
+
+
+
   func performGesture(
     _ app: XCUIApplication,
     idleTimeout: Bool = true,
@@ -80,8 +105,8 @@ extension RunnerTests {
     return (timing, outcome)
   }
 
-  /// Single factory for the success payload every gesture returns (message + gesture timing +
-  /// an optional touch/drag visualization frame), so the field shape lives in one place.
+
+
   private func gestureResponse(
     message: String,
     timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
@@ -134,46 +159,786 @@ 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
-      )
-    )
-  }
 
-  private func plannedGestureResponse(
-    plan: RunnerGesturePlan,
-    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
-    outcome: RunnerInteractionOutcome
-  ) -> Response {
-    if let response = unsupportedResponse(for: outcome) {
-      return response
-    }
-    return gestureResponse(message: plan.intent, timing: timing)
-  }
 
 
-  func execute(command: Command) throws -> Response {
-    if command.command == .status {
-      return executeStatus(command: command)
-    }
-    if command.command == .uptime {
-      return executeUptime()
-    }
-    commandJournal.accept(command: command)
-    return try executeAccepted(command: command)
-  }
+  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
+      )
+    )
+  }
+
+  private func plannedGestureResponse(
+    plan: RunnerGesturePlan,
+    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
+    outcome: RunnerInteractionOutcome
+  ) -> Response {
+    if let response = unsupportedResponse(for: outcome) {
+      return response
+    }
+    return gestureResponse(message: plan.intent, timing: timing)
+  }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
   func executeAccepted(command: Command) throws -> Response {
     commandJournal.start(command: command)
@@ -189,9 +954,7 @@ extension RunnerTests {
 
   func executeStatus(command: Command) -> Response {
     guard
-      let statusCommandId = command.statusCommandId?
-        .trimmingCharacters(in: .whitespacesAndNewlines),
-      !statusCommandId.isEmpty
+      let statusCommandId = command.statusCommandId?.trimmedNonEmpty
     else {
       return Response(
         ok: false,
@@ -202,20 +965,20 @@ extension RunnerTests {
         )
       )
     }
-    return Response(ok: true, data: commandJournal.status(commandId: statusCommandId))
+    return Response(ok: true, data: commandJournal.status(normalizedCommandId: statusCommandId))
   }
 
   func executeUptime() -> Response {
-    // Placeholder value: the transport layer (jsonResponse) overwrites currentUptimeMs with a
-    // fresher send-time stamp on every ok response; kept so direct callers still get a value.
+
+
     Response(
       ok: true,
       data: DataPayload(currentUptimeMs: currentUptimeMs())
     )
   }
 
-  /// 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
@@ -223,6 +986,8 @@ extension RunnerTests {
 
   struct ActiveCommandContext {
     let app: XCUIApplication
+
+    var systemSurface: SystemSurfaceHost? = nil
   }
 
   enum ActiveCommandPreparation {
@@ -297,10 +1062,10 @@ 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).
+
+
+
+
     if let unavailable = runnerUnavailableResponse(command: command) {
       return unavailable
     }
@@ -308,23 +1073,17 @@ extension RunnerTests {
       ? Date().addingTimeInterval(Self.alertCommandTimeout(timeoutMs: command.timeoutMs))
       : nil
     if Thread.isMainThread {
-      let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(
-        command,
-        deadline: alertDeadline
-      )
+      let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(command)
       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
-    )
+
+
+
+    let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(command)
     if let unavailable = runnerUnavailableResponse(command: command) {
       return unavailable
     }
@@ -333,7 +1092,6 @@ extension RunnerTests {
     }
     if command.command == .alert, let deadline = alertDeadline {
       return try runMainThreadWork(
-        command: command,
         timeout: max(0.001, deadline.timeIntervalSinceNow),
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -345,7 +1103,6 @@ extension RunnerTests {
       }
     }
     return try runMainThreadWork(
-      command: command,
       timeout: mainThreadExecutionTimeout,
       timeoutError: mainThreadExecutionTimeoutError
     ) {
@@ -354,7 +1111,6 @@ extension RunnerTests {
   }
 
   func runMainThreadWork<T>(
-    command: Command?,
     timeout: TimeInterval,
     timeoutError: @escaping () -> Error,
     onAbandoned: (() -> Void)? = nil,
@@ -425,7 +1181,7 @@ extension RunnerTests {
     )
   }
 
-  // MARK: - Command Handling
+
 
   private func executeOnMainSafely(
     command: Command,
@@ -476,6 +1232,20 @@ extension RunnerTests {
           userInfo: [NSLocalizedDescriptionKey: "command returned no response"]
         )
       }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
       if didRecordXCTestFailure(since: failureCountBefore),
         let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
       {
@@ -502,9 +1272,9 @@ extension RunnerTests {
     }
   }
 
-  /// 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
@@ -512,15 +1282,14 @@ extension RunnerTests {
     var hasRetried = false
     while true {
       let failureCountBefore = try runMainThreadWork(
-        command: command,
         timeout: mainThreadExecutionTimeout,
         timeoutError: mainThreadExecutionTimeoutError
       ) {
         self.currentXCTestFailureCount()
       }
       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=%@",
@@ -529,7 +1298,6 @@ extension RunnerTests {
         return response
       }
       let recordedFailureResponse = try runMainThreadWork(
-        command: command,
         timeout: mainThreadExecutionTimeout,
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -539,7 +1307,6 @@ extension RunnerTests {
       }
       if let recordedFailureResponse {
         try runMainThreadWork(
-          command: command,
           timeout: mainThreadExecutionTimeout,
           timeoutError: mainThreadExecutionTimeoutError
         ) {
@@ -554,7 +1321,6 @@ extension RunnerTests {
         )
         hasRetried = true
         try runMainThreadWork(
-          command: command,
           timeout: mainThreadExecutionTimeout,
           timeoutError: mainThreadExecutionTimeoutError
         ) {
@@ -569,7 +1335,6 @@ extension RunnerTests {
 
   private func executeSnapshotDispatchedOnce(command: Command) throws -> Response {
     let preparation = try runMainThreadWork(
-      command: command,
       timeout: mainThreadExecutionTimeout,
       timeoutError: mainThreadExecutionTimeoutError
     ) {
@@ -579,12 +1344,16 @@ extension RunnerTests {
     case .response(let response):
       return response
     case .context(let context):
-      return try executeSnapshotPrepared(command: command, activeApp: context.app)
+      return try executeSnapshotPrepared(
+        command: command,
+        activeApp: context.app,
+        systemSurface: context.systemSurface
+      )
     }
   }
 
-  /// Pure command→options projection, extracted so the runner unit bundle can
-  /// prove the decoded wire field actually reaches presentation options (#1634 P2).
+
+
   static func presentationOptions(from command: Command) -> PresentationOptions {
     let customActions = command.customActions ?? false
     return PresentationOptions(
@@ -592,24 +1361,34 @@ extension RunnerTests {
       depth: command.depth,
       scope: command.scope,
       raw: command.raw ?? false,
-      // Custom actions are only readable through the private AX client, so
-      // asking for them pins that backend rather than silently returning a
-      // capture that structurally cannot carry them. An explicit pin wins.
+
+
+
       preferredBackend: command.preferredBackend
         ?? (customActions ? SnapshotBackendKind.privateAX.rawValue : nil),
       customActions: customActions
     )
   }
 
-  private func executeSnapshotPrepared(command: Command, activeApp: XCUIApplication) throws -> Response {
+  private func executeSnapshotPrepared(
+    command: Command,
+    activeApp: XCUIApplication,
+    systemSurface: SystemSurfaceHost? = nil
+  ) throws -> Response {
     let options = Self.presentationOptions(from: command)
     do {
-      let payload: DataPayload
+      var payload: DataPayload
       if options.raw {
         payload = try snapshotRaw(app: activeApp, options: options)
       } else {
         payload = try snapshotFast(app: activeApp, options: options)
       }
+      if let systemSurface {
+        payload.systemSurface = SystemSurfaceProvenancePayload(
+          bundleId: systemSurface.bundleId,
+          kind: systemSurface.kind.rawValue
+        )
+      }
       setNeedsPostSnapshotInteractionDelay()
       return Response(ok: true, data: payload)
     } catch let failure as SnapshotCaptureFailure {
@@ -636,7 +1415,6 @@ extension RunnerTests {
     }
     do {
       try runMainThreadWork(
-        command: nil,
         timeout: 1,
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -654,7 +1432,6 @@ extension RunnerTests {
     }
     do {
       try runMainThreadWork(
-        command: nil,
         timeout: 1,
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -761,10 +1538,10 @@ extension RunnerTests {
       }
     case .recordStop:
       guard let recorder = activeRecording else {
-        // The runner protocol is the durable cleanup primitive. A daemon may crash after the
-        // native stop succeeds but before it commits the resource transition, so exact-owner
-        // recovery must be able to repeat this command safely. Public `record stop` still owns
-        // its user-facing no-active validation through the daemon session manifest.
+
+
+
+
         return Response(ok: true, data: DataPayload(message: "recording already stopped"))
       }
       do {
@@ -784,8 +1561,8 @@ extension RunnerTests {
       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
@@ -814,10 +1591,20 @@ extension RunnerTests {
     routeToSpringboard: Bool = false
   ) -> ActiveCommandPreparation {
     var activeApp = currentApp ?? app
+    var systemSurface: SystemSurfaceHost? = nil
     if routeToSpringboard {
       activeApp = springboard
     } else if shouldSkipAppActivationPreflight(command) {
       activeApp = resolveAppWithoutActivation(command: command)
+    } else if let presented = presentedSystemSurfaceHost() {
+
+
+
+      activeApp = presented.app
+      systemSurface = presented.host
+      if isInteractionCommand(command.command) {
+        applyInteractionStabilizationIfNeeded()
+      }
     } else if !isRunnerLifecycleCommand(command.command) {
       let normalizedBundleId = command.appBundleId?
         .trimmingCharacters(in: .whitespacesAndNewlines)
@@ -829,7 +1616,7 @@ extension RunnerTests {
           refreshCachedTargetIfProcessChanged(bundleId: bundleId)
         }
       } else {
-        // Do not reuse stale bundle targets when the caller does not explicitly request one.
+
         invalidateCachedTarget(reason: "missing_app_bundle")
       }
 
@@ -878,7 +1665,25 @@ extension RunnerTests {
         applyInteractionStabilizationIfNeeded()
       }
     }
-    return .context(ActiveCommandContext(app: activeApp))
+    return .context(ActiveCommandContext(app: activeApp, systemSurface: systemSurface))
+  }
+
+
+
+
+
+  private func presentedSystemSurfaceHost() -> (host: SystemSurfaceHost, app: XCUIApplication)? {
+#if os(iOS)
+    for host in SystemSurfaceHostRegistry.hosts {
+      let candidate = XCUIApplication(bundleIdentifier: host.bundleId)
+      if candidate.state == .runningForeground {
+        return (host, candidate)
+      }
+    }
+    return nil
+#else
+    return nil
+#endif
   }
 
   func executeOnMainPrepared(
@@ -923,15 +1728,15 @@ 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,
@@ -995,10 +1800,10 @@ extension RunnerTests {
           }
           let (timing, outcome) = performGesture(activeApp) {
             if expectedPoint != nil || match.usedNonHittableFallback {
-              // Maestro compatibility: RN E2E backdoor controls can be 1x1 and
-              // 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")
@@ -1034,9 +1839,9 @@ extension RunnerTests {
         )
         let textInput: XCUIElement?
         if !xCTestTextInputProbeSkipped {
-          textInput = textInputAt(app: activeApp, x: x, y: y)
+          textInput = coordinateTapTextInputAt(app: activeApp, x: x, y: y)
         } else {
-          // A process-scoped tap cannot authorize later typing without concrete element identity.
+
           textInput = nil
           NSLog(
             "AGENT_DEVICE_RUNNER_COORDINATE_TAP_TEXT_INPUT_PROBE_SKIPPED bundle=%@",
@@ -1083,8 +1888,8 @@ extension RunnerTests {
       }
       let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
       do {
-        // mouseClick throws (it has no RunnerInteractionOutcome), so it keeps raw measureGesture
-        // and only routes the success payload through gestureResponse.
+
+
         var clickError: Error?
         let timing = measureGesture {
           do {
@@ -1117,31 +1922,26 @@ extension RunnerTests {
       guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
         return Response(ok: false, error: ErrorPayload(message: "drag requires x, y, x2, and y2"))
       }
+      let defaults = runnerDragCommandDefaults(command)
       return executeDragGesture(
         activeApp: activeApp,
         x: x,
         y: y,
         x2: x2,
         y2: y2,
-        durationMs: command.durationMs,
+        durationMs: defaults.durationMs,
         synthesized: command.synthesized == true,
         message: "dragged",
         synthesizedPolicyKind: .synthesizedDrag
       )
     case .scroll:
-      // 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"
+
+
+
+      guard let rawDirection = command.direction,
+        let direction = RunnerScrollDirection(rawValue: rawDirection)
       else {
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: "INVALID_ARGS",
-            message: "scroll requires direction up|down|left|right"
-          )
-        )
+        return invalidScrollDirectionResponse(commandName: "scroll")
       }
       let scrollPolicyKind = SynthesizedGesturePolicyKind.scroll
       guard let scrollContext = synthesizedCoordinateContext(
@@ -1160,9 +1960,10 @@ extension RunnerTests {
           error: ErrorPayload(message: "scroll could not resolve a usable interaction frame")
         )
       }
+      let defaults = runnerDragCommandDefaults(command)
       guard let plan = runnerScrollGesturePlan(
         direction: direction,
-        amount: command.amount,
+        amount: defaults.scrollAmount,
         pixels: command.pixels,
         referenceWidth: frame.width,
         referenceHeight: frame.height
@@ -1175,40 +1976,25 @@ extension RunnerTests {
           )
         )
       }
-      if let durationMs = command.durationMs,
-        durationMs.isFinite == false || durationMs < 0 || durationMs > 10000
-      {
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: "INVALID_ARGS",
-            message: "scroll durationMs must be between 0 and 10000"
-          )
-        )
+      guard scrollDurationIsValid(command.durationMs) else {
+        return invalidScrollDurationResponse(commandName: "scroll")
       }
-      return executeDragGesture(
+      return executeScrollDragGesture(
         activeApp: activeApp,
         x: frame.minX + plan.x1,
         y: frame.minY + plan.y1,
         x2: frame.minX + plan.x2,
         y2: frame.minY + plan.y2,
-        durationMs: command.durationMs,
-        synthesized: shouldUseSynthesizedScrollPath(),
+        durationMs: defaults.durationMs,
         message: "scrolled",
-        synthesizedContext: scrollContext.withReferenceFrame(frame),
-        synthesizedPolicyKind: scrollPolicyKind
+        context: scrollContext.withReferenceFrame(frame),
+        releaseBehavior: command.scrollReleaseBehavior
       )
     case .desktopScroll:
-      guard let direction = command.direction,
-        direction == "up" || direction == "down" || direction == "left" || direction == "right"
+      guard let rawDirection = command.direction,
+        let direction = RunnerScrollDirection(rawValue: rawDirection)
       else {
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: "INVALID_ARGS",
-            message: "desktopScroll requires direction up|down|left|right"
-          )
-        )
+        return invalidScrollDirectionResponse(commandName: "desktopScroll")
       }
       let appFrame = activeApp.frame
       let frame = resolvedTouchReferenceFrame(app: activeApp, appFrame: appFrame)
@@ -1237,16 +2023,8 @@ extension RunnerTests {
       let y = frame.midY
       let localX = x - (appFrame.isEmpty ? frame.minX : appFrame.minX)
       let localY = y - (appFrame.isEmpty ? frame.minY : appFrame.minY)
-      if let durationMs = command.durationMs,
-        durationMs.isFinite == false || durationMs < 0 || durationMs > 10000
-      {
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: "INVALID_ARGS",
-            message: "desktopScroll durationMs must be between 0 and 10000"
-          )
-        )
+      guard scrollDurationIsValid(command.durationMs) else {
+        return invalidScrollDurationResponse(commandName: "desktopScroll")
       }
       let touchFrame = resolvedTouchVisualizationFrame(
         app: activeApp,
@@ -1298,8 +2076,8 @@ extension RunnerTests {
       guard let direction = command.direction else {
         return Response(ok: false, error: ErrorPayload(message: "swipe requires direction"))
       }
-      // swipe returns an optional frame (tvOS-only) rather than a RunnerInteractionOutcome, so it
-      // keeps raw measureGesture and only routes the success payload through gestureResponse.
+
+
       var executedFrame: DragVisualizationFrame?
       let timing = measureGesture {
         withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
@@ -1334,12 +2112,12 @@ extension RunnerTests {
     case .screenshot:
       let screenshot: XCUIScreenshot
 #if os(macOS)
-      // macOS keeps the app-targeted capture behavior for window-level screenshots.
+
       if let bundleId = command.appBundleId, !bundleId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
         let targetApp = XCUIApplication(bundleIdentifier: bundleId)
         targetApp.activate()
         activeApp = targetApp
-        // Brief wait for the app transition animation to complete
+
         sleepFor(0.5)
       }
       if command.fullscreen == true {
@@ -1371,7 +2149,7 @@ extension RunnerTests {
 #if os(macOS)
       return Response(ok: true, data: DataPayload(message: filePath))
 #else
-      // Return path relative to app container root (tmp/ maps to NSTemporaryDirectory)
+
       return Response(ok: true, data: DataPayload(message: "tmp/\(fileName)"))
 #endif
     case .back, .backInApp:
@@ -1441,7 +2219,12 @@ extension RunnerTests {
         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 Response(
+          ok: false,
+          error: ErrorPayload(code: "ALERT_NOT_FOUND", message: "alert not found")
+        )
       }
       return handleAlert(alert, action: action, deadline: deadline)
     case .gesture:
@@ -1459,7 +2242,7 @@ extension RunnerTests {
       }
       switch plannedGestureExecution(for: plan) {
       case .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(
@@ -1493,9 +2276,73 @@ extension RunnerTests {
     }
   }
 
-  /// 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 invalidScrollDirectionResponse(commandName: String) -> Response {
+    Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "INVALID_ARGS",
+        message: "\(commandName) requires direction up|down|left|right"
+      )
+    )
+  }
+
+  private func scrollDurationIsValid(_ durationMs: Double?) -> Bool {
+    guard let durationMs else { return true }
+    return durationMs.isFinite && durationMs >= 0 && durationMs <= 10000
+  }
+
+  private func invalidScrollDurationResponse(commandName: String) -> Response {
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "INVALID_ARGS",
+        message: "\(commandName) durationMs must be between 0 and 10000"
+      )
+    )
+  }
+
+  private func executeScrollDragGesture(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double,
+    message: String,
+    context: SynthesizedCoordinateContext,
+    releaseBehavior: ScrollReleaseBehavior?
+  ) -> Response {
+#if os(iOS)
+    return executeDragGesture(
+      activeApp: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      durationMs: durationMs,
+      synthesized: true,
+      message: message,
+      synthesizedContext: context,
+      synthesizedPolicyKind: .scroll,
+      synthesizedProfile: scrollDragProfile(releaseBehavior: releaseBehavior)
+    )
+#else
+    return executeDragGesture(
+      activeApp: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      durationMs: durationMs,
+      synthesized: false,
+      message: message,
+      synthesizedPolicyKind: .scroll
+    )
+#endif
+  }
+
+
+
   private func executeDragGesture(
     activeApp: XCUIApplication,
     x: Double,
@@ -1509,6 +2356,7 @@ extension RunnerTests {
     synthesizedPolicyKind: SynthesizedGesturePolicyKind,
     synthesizedProfile: SynthesizedDragProfile = .continuous
   ) -> Response {
+    let durationMs = durationMs ?? runnerDefaultDragDurationMs
     let commandName = dragCommandName(message: message)
     guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
       return Response(
@@ -1540,7 +2388,7 @@ extension RunnerTests {
     )
     var fallback: GestureFallback?
     if synthesized {
-      let durationMs = min(max(durationMs ?? 250, 16), 10000)
+      let durationMs = min(max(durationMs, 16), 10000)
       let context = synthesizedCoordinateContext(
         app: activeApp,
         policy: synthesizedGesturePolicy(synthesizedPolicyKind)
@@ -1563,7 +2411,7 @@ extension RunnerTests {
       fallback = gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
     }
     let holdDuration = synthesized
-      ? synthesizedSwipeFallbackHoldDuration(durationMs: durationMs ?? 250)
+      ? synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
       : coordinateDragHoldDuration()
     let (timing, outcome) = performGesture(activeApp) {
       dragAt(
@@ -1592,7 +2440,7 @@ extension RunnerTests {
     y: Double,
     x2: Double,
     y2: Double,
-    durationMs: Double?,
+    durationMs: Double,
     message: String,
     context: SynthesizedCoordinateContext?,
     policyKind: SynthesizedGesturePolicyKind,
@@ -1632,7 +2480,7 @@ extension RunnerTests {
         )
       )
     }
-    let durationMs = min(max(durationMs ?? 250, 16), 10000)
+    let durationMs = min(max(durationMs, 16), 10000)
     let dragFrame = axFreeDragVisualizationFrame(
       x: plan.points.x,
       y: plan.points.y,
@@ -1682,7 +2530,7 @@ extension RunnerTests {
     y: Double,
     x2: Double,
     y2: Double,
-    durationMs: Double?,
+    durationMs: Double,
     message: String,
     fallback: GestureFallback?
   ) -> Response {
@@ -1694,7 +2542,7 @@ extension RunnerTests {
       x2: dragPoints.x2,
       y2: dragPoints.y2
     )
-    let holdDuration = synthesizedSwipeFallbackHoldDuration(durationMs: durationMs ?? 250)
+    let holdDuration = synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
     let (timing, outcome) = performGesture(activeApp) {
       dragAt(
         app: activeApp,
@@ -1724,14 +2572,6 @@ extension RunnerTests {
 #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"
   }
@@ -1762,19 +2602,21 @@ extension RunnerTests {
     )
   }
 
-  func runnerCommandFixture(_ json: String) throws -> Command {
-    try JSONDecoder().decode(Command.self, from: Data(json.utf8))
-  }
+
+
+
+
+
 
   private func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
 #if os(iOS)
     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 isCoordinateOnlyTap(command)
@@ -1784,18 +2626,21 @@ extension RunnerTests {
   }
 
   private func shouldRouteToSpringboardBlockingSystemModal(
-    _ command: Command,
-    deadline: Date? = nil
+    _ command: Command
   ) -> Bool {
 #if os(iOS)
-    guard command.command == .alert || isCoordinateOnlyTap(command) else {
+    guard 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.
+
+
+
+
+
+    let probeDeadline = Date().addingTimeInterval(systemModalProbeBudget)
+
+
+
     if Thread.isMainThread {
       return firstBlockingSystemModal(
         in: springboard,
@@ -1854,8 +2699,8 @@ extension RunnerTests {
       command.x != nil,
       command.y != nil
     {
-      // The shared runtime has already resolved this node as non-hittable and
-      // deliberately selected Maestro's coordinate compatibility route.
+
+
       maestroNonHittableCoordinateFallbackUsed = true
     }
     let focusStartedAt = Date()
@@ -1903,8 +2748,8 @@ extension RunnerTests {
     if let resolvedCoordinateTarget {
       target = resolvedCoordinateTarget
     } else if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
-      // Released daemons may still send selector-keyed type commands even though current
-      // daemons resolve fill selectors through the runtime tree before reaching the runner.
+
+
       let match = findElement(
         app: activeApp,
         selectorKey: selectorKey,
@@ -1986,8 +2831,8 @@ extension RunnerTests {
     } else if point != nil {
       frame = activeApp.frame
     } else {
-      // Bare `type` has no coordinate response to normalize. Avoid serializing the
-      // application AX tree only to emit unused reference dimensions.
+
+
       frame = .zero
     }
     return Response(