agent-device 0.21.0 → 0.21.2

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

@@ -2,8 +2,32 @@ import XCTest
 import AgentDeviceSnapshotPresentation
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 extension RunnerTests {
-  // MARK: - Main Thread Dispatch
+
 
   private func currentUptimeMs() -> Double {
     ProcessInfo.processInfo.systemUptime * 1000
@@ -35,7 +59,7 @@ extension RunnerTests {
     }
   }
 
-  /// Optional visualization frame returned with a gesture response.
+
   enum GestureFrame {
     case none
     case touch(TouchVisualizationFrame?)
@@ -58,111 +82,861 @@ 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,
-    _ action: () -> RunnerInteractionOutcome
-  ) -> (timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double), outcome: RunnerInteractionOutcome) {
-    var outcome = RunnerInteractionOutcome.performed
-    let timing = measureGesture {
-      if idleTimeout {
-        withTemporaryScrollIdleTimeoutIfSupported(app) { outcome = action() }
-      } else {
-        outcome = action()
-      }
-    }
-    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),
-    frame: GestureFrame = .none,
-    fallback: GestureFallback? = nil,
-    maestroNonHittableCoordinateFallbackUsed: Bool? = nil
-  ) -> Response {
-    let data: DataPayload
-    switch frame {
-    case .none:
-      data = DataPayload(
-        message: message,
-        gestureStartUptimeMs: timing.gestureStartUptimeMs,
-        gestureEndUptimeMs: timing.gestureEndUptimeMs,
-        gestureFallback: fallback?.strategy,
-        gestureFallbackMessage: fallback?.message,
-        gestureFallbackHint: fallback?.hint,
-        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
-      )
-    case .touch(let f):
-      data = DataPayload(
-        message: message,
-        gestureStartUptimeMs: timing.gestureStartUptimeMs,
-        gestureEndUptimeMs: timing.gestureEndUptimeMs,
-        x: f?.x,
-        y: f?.y,
-        referenceWidth: f?.referenceWidth,
-        referenceHeight: f?.referenceHeight,
-        gestureFallback: fallback?.strategy,
-        gestureFallbackMessage: fallback?.message,
-        gestureFallbackHint: fallback?.hint,
-        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
-      )
-    case .drag(let f):
-      data = DataPayload(
-        message: message,
-        gestureStartUptimeMs: timing.gestureStartUptimeMs,
-        gestureEndUptimeMs: timing.gestureEndUptimeMs,
-        x: f.x,
-        y: f.y,
-        x2: f.x2,
-        y2: f.y2,
-        referenceWidth: f.referenceWidth,
-        referenceHeight: f.referenceHeight,
-        gestureFallback: fallback?.strategy,
-        gestureFallbackMessage: fallback?.message,
-        gestureFallbackHint: fallback?.hint
-      )
-    }
-    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 performGesture(
+    _ app: XCUIApplication,
+    idleTimeout: Bool = true,
+    _ action: () -> RunnerInteractionOutcome
+  ) -> (timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double), outcome: RunnerInteractionOutcome) {
+    var outcome = RunnerInteractionOutcome.performed
+    let timing = measureGesture {
+      if idleTimeout {
+        withTemporaryScrollIdleTimeoutIfSupported(app) { outcome = action() }
+      } else {
+        outcome = action()
+      }
+    }
+    return (timing, outcome)
+  }
+
+
+
+  private func gestureResponse(
+    message: String,
+    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
+    frame: GestureFrame = .none,
+    fallback: GestureFallback? = nil,
+    maestroNonHittableCoordinateFallbackUsed: Bool? = nil
+  ) -> Response {
+    let data: DataPayload
+    switch frame {
+    case .none:
+      data = DataPayload(
+        message: message,
+        gestureStartUptimeMs: timing.gestureStartUptimeMs,
+        gestureEndUptimeMs: timing.gestureEndUptimeMs,
+        gestureFallback: fallback?.strategy,
+        gestureFallbackMessage: fallback?.message,
+        gestureFallbackHint: fallback?.hint,
+        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
+      )
+    case .touch(let f):
+      data = DataPayload(
+        message: message,
+        gestureStartUptimeMs: timing.gestureStartUptimeMs,
+        gestureEndUptimeMs: timing.gestureEndUptimeMs,
+        x: f?.x,
+        y: f?.y,
+        referenceWidth: f?.referenceWidth,
+        referenceHeight: f?.referenceHeight,
+        gestureFallback: fallback?.strategy,
+        gestureFallbackMessage: fallback?.message,
+        gestureFallbackHint: fallback?.hint,
+        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
+      )
+    case .drag(let f):
+      data = DataPayload(
+        message: message,
+        gestureStartUptimeMs: timing.gestureStartUptimeMs,
+        gestureEndUptimeMs: timing.gestureEndUptimeMs,
+        x: f.x,
+        y: f.y,
+        x2: f.x2,
+        y2: f.y2,
+        referenceWidth: f.referenceWidth,
+        referenceHeight: f.referenceHeight,
+        gestureFallback: fallback?.strategy,
+        gestureFallbackMessage: fallback?.message,
+        gestureFallbackHint: fallback?.hint
+      )
+    }
+    return Response(ok: true, data: data)
+  }
+
+
+
+
+  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)
+  }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 
@@ -195,16 +969,16 @@ extension RunnerTests {
   }
 
   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
@@ -212,6 +986,8 @@ extension RunnerTests {
 
   struct ActiveCommandContext {
     let app: XCUIApplication
+
+    var systemSurface: SystemSurfaceHost? = nil
   }
 
   enum ActiveCommandPreparation {
@@ -286,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
     }
@@ -304,9 +1080,9 @@ extension RunnerTests {
         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)
     if let unavailable = runnerUnavailableResponse(command: command) {
       return unavailable
@@ -405,7 +1181,7 @@ extension RunnerTests {
     )
   }
 
-  // MARK: - Command Handling
+
 
   private func executeOnMainSafely(
     command: Command,
@@ -456,6 +1232,20 @@ extension RunnerTests {
           userInfo: [NSLocalizedDescriptionKey: "command returned no response"]
         )
       }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
       if didRecordXCTestFailure(since: failureCountBefore),
         let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
       {
@@ -482,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
@@ -498,8 +1288,8 @@ extension RunnerTests {
         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=%@",
@@ -554,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(
@@ -567,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 {
@@ -734,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 {
@@ -757,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
@@ -787,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)
@@ -802,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")
       }
 
@@ -851,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(
@@ -896,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,
@@ -968,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")
@@ -1007,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=%@",
@@ -1056,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 {
@@ -1103,9 +1935,9 @@ extension RunnerTests {
         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 rawDirection = command.direction,
         let direction = RunnerScrollDirection(rawValue: rawDirection)
       else {
@@ -1121,21 +1953,25 @@ extension RunnerTests {
           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 {
+      let viewport = resolvedScrollViewport(app: activeApp, context: scrollContext)
+      let defaults = runnerDragCommandDefaults(command)
+      switch viewport.gestureDispatch(
+        direction: direction,
+        amount: defaults.scrollAmount,
+        pixels: command.pixels
+      ) {
+      case .occluded(let occlusionKeyboardMinY, let visibleHeight):
+        return scrollKeyboardOccludedResponse(
+          direction: direction.rawValue,
+          keyboardMinY: occlusionKeyboardMinY,
+          visibleHeight: visibleHeight
+        )
+      case .unusableFrame:
         return Response(
           ok: false,
           error: ErrorPayload(message: "scroll could not resolve a usable interaction frame")
         )
-      }
-      let defaults = runnerDragCommandDefaults(command)
-      guard let plan = runnerScrollGesturePlan(
-        direction: direction,
-        amount: defaults.scrollAmount,
-        pixels: command.pixels,
-        referenceWidth: frame.width,
-        referenceHeight: frame.height
-      ) else {
+      case .unusablePlan:
         return Response(
           ok: false,
           error: ErrorPayload(
@@ -1143,21 +1979,24 @@ extension RunnerTests {
             message: "scroll could not compute a gesture plan"
           )
         )
+      case .gesture(let gesture):
+        guard scrollDurationIsValid(command.durationMs) else {
+          return invalidScrollDurationResponse(commandName: "scroll")
+        }
+        return gesture.attachingEvidence(
+          to: executeScrollDragGesture(
+            activeApp: activeApp,
+            x: gesture.planFrame.minX + gesture.plan.x1,
+            y: gesture.planFrame.minY + gesture.plan.y1,
+            x2: gesture.planFrame.minX + gesture.plan.x2,
+            y2: gesture.planFrame.minY + gesture.plan.y2,
+            durationMs: defaults.durationMs,
+            message: "scrolled",
+            context: scrollContext.withReferenceFrame(gesture.coordinateFrame),
+            releaseBehavior: command.scrollReleaseBehavior
+          )
+        )
       }
-      guard scrollDurationIsValid(command.durationMs) else {
-        return invalidScrollDurationResponse(commandName: "scroll")
-      }
-      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: defaults.durationMs,
-        message: "scrolled",
-        context: scrollContext.withReferenceFrame(frame),
-        releaseBehavior: command.scrollReleaseBehavior
-      )
     case .desktopScroll:
       guard let rawDirection = command.direction,
         let direction = RunnerScrollDirection(rawValue: rawDirection)
@@ -1244,8 +2083,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) {
@@ -1280,12 +2119,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 {
@@ -1317,7 +2156,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:
@@ -1387,8 +2226,8 @@ extension RunnerTests {
         Self.alertCommandTimeout(timeoutMs: command.timeoutMs)
       )
       guard let alert = resolveAlert(app: activeApp, deadline: deadline) else {
-        // Typed so the host retries on absence alone: a transport or runner failure carries no
-        // code and must not be mistaken for "no alert yet" (ALERT_NOT_FOUND_RUNNER_CODE).
+
+
         return Response(
           ok: false,
           error: ErrorPayload(code: "ALERT_NOT_FOUND", message: "alert not found")
@@ -1410,7 +2249,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(
@@ -1509,8 +2348,8 @@ extension RunnerTests {
 #endif
   }
 
-  /// Shared drag execution for explicit drag commands. The iOS synthesized lane keeps its
-  /// fallback policy explicit; viewport scrolling owns a separate single drag specification.
+
+
   private func executeDragGesture(
     activeApp: XCUIApplication,
     x: Double,
@@ -1732,12 +2571,30 @@ extension RunnerTests {
     )
   }
 
-  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 scrollKeyboardOccludedResponse(
+    direction: String,
+    keyboardMinY: Double,
+    visibleHeight: Double
+  ) -> Response {
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: ScrollViewportPolicy.occlusionRunnerCode,
+        message: String(
+          format:
+            "scroll %@ refused: the keyboard leaves %.0fpt of visible surface above it, too little to swipe",
+          direction,
+          visibleHeight
+        )
+      )
+    )
   }
 
   private func dragCommandName(message: String) -> String {
@@ -1771,15 +2628,20 @@ extension RunnerTests {
   }
 
 
+
+
+
+
+
   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)
@@ -1795,10 +2657,15 @@ extension RunnerTests {
     guard isCoordinateOnlyTap(command) else {
       return false
     }
+
+
+
+
+
     let probeDeadline = Date().addingTimeInterval(systemModalProbeBudget)
-    // `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,
@@ -1857,8 +2724,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()
@@ -1906,8 +2773,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,
@@ -1989,8 +2856,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(