agent-device 0.19.3 → 0.20.1

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

@@ -24,23 +24,19 @@ enum CommandType: String, Codable {
   case keyboardDismiss
   case keyboardReturn
   case alert
-  case pinch
   case sequence
-  case rotateGesture
-  case transformGesture
+  case gesture
+  case gestureViewport
   case recordStart
   case recordStop
   case status
   case uptime
+  case activate
+  case terminate
+  case targetReset
   case shutdown
 }
 
-enum SynthesizedDragSemantics: String, Codable {
-  case swipe
-  case pan
-  case fling
-}
-
 /// Runner command traits — see CONTEXT.md ("Runner command traits").
 ///
 /// Single source of truth for how the runner classifies a command across three
@@ -80,11 +76,11 @@ extension CommandType {
     // .sequence is the fused multi-step gesture batch.
     case .tap, .longPress, .drag, .remotePress, .type, .swipe, .scroll, .desktopScroll,
          .back, .backInApp, .backSystem, .rotate, .appSwitcher,
-         .keyboardDismiss, .keyboardReturn, .pinch, .sequence, .rotateGesture, .transformGesture:
+         .keyboardDismiss, .keyboardReturn, .sequence, .gesture:
       return CommandTraits(isInteraction: true, readOnly: .never, isLifecycle: false)
 
     // Read-only reads: eligible for the session-invalidating retry.
-    case .findText, .readText, .snapshot:
+    case .findText, .readText, .snapshot, .gestureViewport:
       return CommandTraits(isInteraction: false, readOnly: .always, isLifecycle: false)
 
     // Screenshot is both a read and a runner-lifecycle command (skips app-activation preflight).
@@ -96,7 +92,7 @@ extension CommandType {
       return CommandTraits(isInteraction: false, readOnly: .conditional, isLifecycle: false)
 
     // Runner-lifecycle commands: skip the app-activation preflight.
-    case .recordStop, .uptime, .shutdown:
+    case .recordStop, .uptime, .terminate, .targetReset, .shutdown:
       return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: true)
 
     case .status:
@@ -107,7 +103,7 @@ extension CommandType {
     // guard interacts with bespoke macOS activation, so classifying it needs a macOS smoke
     // check first (tracked as a follow-up). Also preserved: querySelector is NOT read-only;
     // recordStart is NOT a lifecycle command; home/alert remain non-interaction by design.
-    case .mouseClick, .querySelector, .home, .recordStart:
+    case .mouseClick, .querySelector, .home, .recordStart, .activate:
       return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: false)
     }
   }
@@ -124,7 +120,6 @@ struct Command: Codable {
   let allowNonHittableCoordinateFallback: Bool?
   let delayMs: Int?
   let textEntryMode: String?
-  let clearFirst: Bool?
   let action: String?
   let x: Double?
   let y: Double?
@@ -132,16 +127,13 @@ struct Command: Codable {
   let remoteButton: String?
   let x2: Double?
   let y2: Double?
-  let dx: Double?
-  let dy: Double?
   let durationMs: Double?
+  let timeoutMs: Double?
   let direction: String?
   let amount: Double?
   let pixels: Double?
   let orientation: String?
-  let scale: Double?
-  let degrees: Double?
-  let velocity: Double?
+  let gesturePlan: RunnerGesturePlan?
   let outPath: String?
   let fps: Int?
   let maxSize: Int?
@@ -150,12 +142,43 @@ struct Command: Codable {
   let scope: String?
   let raw: Bool?
   let fullscreen: Bool?
+  let inlineScreenshot: Bool?
   let synthesized: Bool?
-  /// Preserves the public gesture's timing semantics after it is lowered to runner `drag`.
-  let dragSemantics: SynthesizedDragSemantics?
   let steps: [SequenceStep]?
 }
 
+/// Canonical one- or two-pointer plan produced by the portable TypeScript planner.
+struct RunnerGesturePlan: Codable {
+  let topology: String
+  let intent: String
+  let executionProfile: String?
+  let durationMs: Double
+  let viewport: RunnerGestureViewport
+  let pointers: [RunnerGesturePointer]
+}
+
+struct RunnerGestureViewport: Codable {
+  let x: Double
+  let y: Double
+  let width: Double
+  let height: Double
+}
+
+struct RunnerGesturePointer: Codable {
+  let pointerId: Int
+  let samples: [RunnerGestureSample]
+}
+
+struct RunnerGestureSample: Codable {
+  let offsetMs: Double
+  let point: RunnerGesturePoint
+}
+
+struct RunnerGesturePoint: Codable {
+  let x: Double
+  let y: Double
+}
+
 /// One allowlisted coordinate gesture step inside a fused `sequence` command.
 /// `kind` is decoded as a raw String (not an enum) so the runner can return a clear
 /// INVALID_ARGS for an unknown kind instead of a generic decode failure.
@@ -163,15 +186,11 @@ struct SequenceStep: Codable {
   let kind: String
   let x: Double?
   let y: Double?
-  let x2: Double?
-  let y2: Double?
   let durationMs: Double?
   let pauseMs: Double?
-  /// For `tap`/`drag` steps on iOS non-tv: use the synthesized HID fast path instead of the
+  /// For `tap` steps on iOS non-tv: use the synthesized HID fast path instead of the
   /// drag-based XCUICoordinate path, matching the individual command behavior.
   let synthesized: Bool?
-  /// Preserves one-shot swipe timing when repeated swipes are fused into a sequence.
-  let dragSemantics: SynthesizedDragSemantics?
 }
 
 /// Per-step result for a `sequence` response. `ok:false` carries the failing step's
@@ -211,6 +230,7 @@ extension Response {
 
 struct DataPayload: Codable {
   let message: String?
+  let imageBase64: String?
   let text: String?
   let found: Bool?
   let items: [String]?
@@ -241,6 +261,7 @@ struct DataPayload: Codable {
   let gestureFallback: String?
   let gestureFallbackMessage: String?
   let gestureFallbackHint: String?
+  let maestroNonHittableCoordinateFallbackUsed: Bool?
   let runnerFatal: Bool?
   let runnerFatalReason: String?
   let completedSteps: Int?
@@ -249,6 +270,7 @@ struct DataPayload: Codable {
 
   init(
     message: String? = nil,
+    imageBase64: String? = nil,
     text: String? = nil,
     found: Bool? = nil,
     items: [String]? = nil,
@@ -279,6 +301,7 @@ struct DataPayload: Codable {
     gestureFallback: String? = nil,
     gestureFallbackMessage: String? = nil,
     gestureFallbackHint: String? = nil,
+    maestroNonHittableCoordinateFallbackUsed: Bool? = nil,
     runnerFatal: Bool? = nil,
     runnerFatalReason: String? = nil,
     completedSteps: Int? = nil,
@@ -286,6 +309,7 @@ struct DataPayload: Codable {
     sequenceResults: [SequenceStepResult]? = nil
   ) {
     self.message = message
+    self.imageBase64 = imageBase64
     self.text = text
     self.found = found
     self.items = items
@@ -316,6 +340,7 @@ struct DataPayload: Codable {
     self.gestureFallback = gestureFallback
     self.gestureFallbackMessage = gestureFallbackMessage
     self.gestureFallbackHint = gestureFallbackHint
+    self.maestroNonHittableCoordinateFallbackUsed = maestroNonHittableCoordinateFallbackUsed
     self.runnerFatal = runnerFatal
     self.runnerFatalReason = runnerFatalReason
     self.completedSteps = completedSteps

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

@@ -1,10 +1,10 @@
 import XCTest
 
-// Swift port of buildScrollGesturePlan from src/core/scroll-gesture.ts.
+// Swift port of buildScrollGesturePlan from src/contracts/scroll-gesture.ts.
 //
 // This is a deliberate two-place invariant: the daemon keeps the TS implementation (for Android,
 // recording, and reported-pixels), and the runner places the gesture with this Swift copy. The
-// parity test vectors at the bottom of this file mirror src/core/__tests__/scroll-gesture.test.ts —
+// parity test vectors at the bottom of this file mirror src/contracts/scroll-gesture.test.ts —
 // if you change the math in either language, update the other and both vector sets.
 //
 // All inputs here are positive (reference dims, travel, center), so Swift's `.rounded()`

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

@@ -9,7 +9,7 @@ extension RunnerTests {
 
   /// Allowlisted step kinds. Validated on both sides so an unsupported kind is rejected with a
   /// clear INVALID_ARGS naming the step index, executing nothing.
-  private var sequenceableStepKinds: Set<String> { ["tap", "doubleTap", "longPress", "drag"] }
+  private var sequenceableStepKinds: Set<String> { ["tap", "doubleTap", "longPress"] }
 
   /// Per-step outcome carried by `assembleSequenceExecution`. The timing is captured by the
   /// executor closure (via performGesture) so ordering/stop-on-failure stay device-free testable.
@@ -127,17 +127,12 @@ extension RunnerTests {
   private func validateSequenceStep(_ step: SequenceStep, index: Int) -> Response? {
     guard sequenceableStepKinds.contains(step.kind) else {
       return sequenceInvalidArgs(
-        "sequence step \(index) has unsupported kind \"\(step.kind)\"; allowed: tap, doubleTap, longPress, drag"
+        "sequence step \(index) has unsupported kind \"\(step.kind)\"; allowed: tap, doubleTap, longPress"
       )
     }
     guard let x = step.x, let y = step.y, x.isFinite, y.isFinite else {
       return sequenceInvalidArgs("sequence step \(index) (\(step.kind)) requires finite x and y")
     }
-    if step.kind == "drag" {
-      guard let x2 = step.x2, let y2 = step.y2, x2.isFinite, y2.isFinite else {
-        return sequenceInvalidArgs("sequence step \(index) (drag) requires finite x2 and y2")
-      }
-    }
     return nil
   }
 
@@ -194,92 +189,6 @@ extension RunnerTests {
 #endif
       // Synthesis unsupported (e.g. macOS) — fall through to the drag-based tapAt below.
     }
-    if step.kind == "drag", step.synthesized == true {
-      let policyKind = SynthesizedGesturePolicyKind.synthesizedDrag
-      let dragPoints: DragPoints
-      let dragContext: SynthesizedCoordinateContext?
-#if os(iOS)
-      guard let dragPlan = axFreeSynthesizedDragPlan(
-        app: activeApp,
-        x: x,
-        y: y,
-        x2: step.x2 ?? x,
-        y2: step.y2 ?? y,
-        context: synthesizedContext
-      ) else {
-        let nowMs = ProcessInfo.processInfo.systemUptime * 1000
-        logSynthesizedGesturePolicyDecision(kind: policyKind, context: synthesizedContext, fallbackAttempted: false)
-        return SequenceStepOutcome(
-          outcome: .unsupported(
-            message: "synthesized coordinate drag could not resolve a finite coordinate frame",
-            hint: "Retry after the app is foregrounded, or use a plain screenshot to choose coordinates."
-          ),
-          gestureStartUptimeMs: nowMs,
-          gestureEndUptimeMs: nowMs
-        )
-      }
-      dragPoints = dragPlan.points
-      dragContext = dragPlan.context
-#else
-      dragPoints = keyboardAvoidingDragPoints(
-        app: activeApp, x: x, y: y, x2: step.x2 ?? x, y2: step.y2 ?? y)
-      dragContext = nil
-#endif
-      let durationMs = min(max(step.durationMs ?? 250, 16), 10000)
-      let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-        synthesizedDragAt(
-          app: activeApp,
-          x: dragPoints.x,
-          y: dragPoints.y,
-          x2: dragPoints.x2,
-          y2: dragPoints.y2,
-          durationMs: durationMs,
-          semantics: step.dragSemantics,
-          context: dragContext
-        )
-      }
-      if case .performed = outcome {
-        logSynthesizedGesturePolicyDecision(kind: policyKind, context: dragContext, fallbackAttempted: false)
-        if let pauseMs = step.pauseMs, pauseMs > 0 {
-          sleepFor(min(max(pauseMs, 0), 10000) / 1000.0)
-        }
-        return SequenceStepOutcome(
-          outcome: outcome,
-          gestureStartUptimeMs: timing.gestureStartUptimeMs,
-          gestureEndUptimeMs: timing.gestureEndUptimeMs
-        )
-      }
-#if os(iOS)
-      guard dragContext?.allowsXCTestCoordinateFallback == true else {
-        logSynthesizedGesturePolicyDecision(kind: policyKind, context: dragContext, fallbackAttempted: false)
-        return SequenceStepOutcome(
-          outcome: outcome,
-          gestureStartUptimeMs: timing.gestureStartUptimeMs,
-          gestureEndUptimeMs: timing.gestureEndUptimeMs
-        )
-      }
-#endif
-      logSynthesizedGesturePolicyDecision(kind: policyKind, context: dragContext, fallbackAttempted: true)
-      let fallbackHoldDuration = synthesizedSwipeFallbackHoldDuration(durationMs: step.durationMs ?? 250)
-      let (fallbackTiming, fallbackOutcome) = performGesture(activeApp) {
-        dragAt(
-          app: activeApp,
-          x: dragPoints.x,
-          y: dragPoints.y,
-          x2: dragPoints.x2,
-          y2: dragPoints.y2,
-          holdDuration: fallbackHoldDuration
-        )
-      }
-      if case .performed = fallbackOutcome, let pauseMs = step.pauseMs, pauseMs > 0 {
-        sleepFor(min(max(pauseMs, 0), 10000) / 1000.0)
-      }
-      return SequenceStepOutcome(
-        outcome: fallbackOutcome,
-        gestureStartUptimeMs: fallbackTiming.gestureStartUptimeMs,
-        gestureEndUptimeMs: fallbackTiming.gestureEndUptimeMs
-      )
-    }
     let (timing, outcome) = performGesture(activeApp) {
       switch step.kind {
       case "doubleTap":
@@ -288,20 +197,6 @@ extension RunnerTests {
       case "longPress":
         let duration = min(max(step.durationMs ?? 800, 16), 10000) / 1000.0
         return longPressAt(app: activeApp, x: x, y: y, duration: duration)
-      case "drag":
-        // Route through keyboardAvoidingDragPoints for parity with the individual `.drag` command.
-        // The non-synthesized coordinate-drag path ignores durationMs, matching that command's
-        // non-synthesized branch.
-        let dragPoints = keyboardAvoidingDragPoints(
-          app: activeApp, x: x, y: y, x2: step.x2 ?? x, y2: step.y2 ?? y)
-        return dragAt(
-          app: activeApp,
-          x: dragPoints.x,
-          y: dragPoints.y,
-          x2: dragPoints.x2,
-          y2: dragPoints.y2,
-          holdDuration: coordinateDragHoldDuration()
-        )
       default:
         return tapAt(app: activeApp, x: x, y: y)
       }

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

@@ -57,12 +57,16 @@ extension RunnerTests {
     case .collectionView: return "CollectionView"
     case .table: return "Table"
     case .scrollView: return "ScrollView"
+    case .toolbar: return "Toolbar"
     case .searchField: return "SearchField"
     case .segmentedControl: return "SegmentedControl"
     case .stepper: return "Stepper"
     case .picker: return "Picker"
+    case .activityIndicator: return "ActivityIndicator"
+    case .progressIndicator: return "ProgressIndicator"
     case .checkBox: return "CheckBox"
     case .menuItem: return "MenuItem"
+    case .webView: return "WebView"
     case .other: return "Other"
     default:
       switch type.rawValue {
@@ -70,8 +74,6 @@ extension RunnerTests {
         return "Keyboard"
       case 20:
         return "Key"
-      case 24:
-        return "SearchField"
       default:
         return "Element(\(type.rawValue))"
       }
@@ -101,15 +103,22 @@ extension RunnerTests {
 
   static let flatInteractiveFallbackBudget: TimeInterval = 1.0
 
+  // The single production entry point -- always compiled, no unit-test overload. A unit test
+  // exercises this exact function; the only injectable seam lives inside
+  // `boundedBlockingSystemAlertSnapshot`'s probe closure (see `systemModalProbeOverrideForTesting`
+  // in RunnerTests.swift), so reverting this entry point to bypass the bounded probe fails the
+  // regression test.
   func snapshotFast(app: XCUIApplication, options: SnapshotOptions) throws -> DataPayload {
-    if let blocking = blockingSystemAlertSnapshot() {
+    let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
+    if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
       return blocking
     }
     return try runSnapshotCapturePlan(
       Self.regularVisiblePlan,
       app: app,
       options: options,
-      terminal: .sparseWithFatalOnAXFailure
+      terminal: .sparseWithFatalOnAXFailure,
+      deadline: deadline
     )
   }
 
@@ -189,7 +198,12 @@ extension RunnerTests {
         regularSnapshot: true
       )
 
-      let key = "\(snapshot.elementType)-\(evaluation.label)-\(evaluation.identifier)-\(snapshot.frame.origin.x)-\(snapshot.frame.origin.y)"
+      let key = Self.snapshotTraversalIdentity(
+        elementType: snapshot.elementType,
+        label: evaluation.label,
+        identifier: evaluation.identifier,
+        frame: snapshot.frame
+      )
       let isDuplicate = seen.contains(key)
       if !isDuplicate {
         seen.insert(key)
@@ -245,18 +259,98 @@ extension RunnerTests {
     )
   }
 
+  // See `snapshotFast` above: the single production entry point, no unit-test overload.
   func snapshotRaw(app: XCUIApplication, options: SnapshotOptions) throws -> DataPayload {
-    if let blocking = blockingSystemAlertSnapshot() {
+    let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
+    if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
       return blocking
     }
     return try runSnapshotCapturePlan(
       Self.rawDiagnosticPlan,
       app: app,
       options: options,
-      terminal: .throwOnAXFailure
+      terminal: .throwOnAXFailure,
+      deadline: deadline
     )
   }
 
+  /// Runs the pre-plan SpringBoard system-modal probe as a bounded capture tier sharing the plan
+  /// deadline, so a slow alert enumeration cannot bypass the snapshot timeout and stall (#1244).
+  func boundedBlockingSystemAlertSnapshot(deadline: Date) -> DataPayload? {
+    boundedBlockingSystemAlertSnapshotBody(deadline: deadline) { probeDeadline in
+      return self.blockingSystemAlertSnapshot(deadline: probeDeadline)
+    }
+  }
+
+  /// The real bounding/hook machinery used by `boundedBlockingSystemAlertSnapshot` above: the
+  /// probe closure it's given always calls `self.blockingSystemAlertSnapshot` in production, and
+  /// in unit-test builds may first consult `systemModalProbeOverrideForTesting`. Keeping this in
+  /// one place means the `runMainThreadWork` wrap and the `onAbandoned`/`onDrained` hooks can
+  /// never drift between what production runs and what the unit tests exercise.
+  private func boundedBlockingSystemAlertSnapshotBody(
+    deadline: Date,
+    probe: @escaping (Date) -> DataPayload?
+  ) -> DataPayload? {
+    #if os(macOS)
+      return nil
+    #else
+    let slice = Self.systemModalProbeSlice(
+      budget: systemModalProbeBudget,
+      deadlineRemaining: deadline.timeIntervalSinceNow
+    )
+    guard slice > 0 else {
+      NSLog("AGENT_DEVICE_RUNNER_SYSTEM_MODAL_PROBE_SKIPPED reason=budget_exhausted")
+      return nil
+    }
+    let probeDeadline = Date().addingTimeInterval(slice)
+    let startedAt = Date()
+    do {
+      return try runMainThreadWork(
+        command: nil,
+        timeout: slice,
+        timeoutError: {
+          SnapshotCaptureFailure(
+            code: Self.xCTestSnapshotTimeoutCode,
+            message: "the system-modal probe exceeded its \(slice)s time slice",
+            hint: "The capture plan recovers through non-XCTest snapshot tiers while the modal probe drains."
+          )
+        },
+        onAbandoned: {
+          self.retainAbandonedXCTestChannelWork()
+          NSLog("AGENT_DEVICE_RUNNER_SYSTEM_MODAL_PROBE_TIMEOUT slice=%.1f", slice)
+          self.penalizeSnapshotXCTestChannel(
+            bundleId: self.currentBundleId,
+            reason: "system_modal_probe_timeout"
+          )
+        },
+        onDrained: {
+          self.releaseAbandonedXCTestChannelWork()
+          NSLog("AGENT_DEVICE_RUNNER_SYSTEM_MODAL_PROBE_DRAINED")
+        }
+      ) {
+        probe(probeDeadline)
+      }
+    } catch {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_SYSTEM_MODAL_PROBE_ABORTED elapsedMs=%d error=%@",
+        Int(Date().timeIntervalSince(startedAt) * 1000),
+        String(describing: error)
+      )
+      return nil
+    }
+    #endif
+  }
+
+  /// The probe gets its own budget, clamped by whatever remains of the shared plan deadline, and
+  /// 0 (skip entirely) once that deadline is already spent.
+  static func systemModalProbeSlice(
+    budget: TimeInterval,
+    deadlineRemaining: TimeInterval
+  ) -> TimeInterval {
+    guard deadlineRemaining > 0 else { return 0 }
+    return min(budget, deadlineRemaining)
+  }
+
   func rawTreeSnapshotPayload(
     context: SnapshotTraversalContext,
     options: SnapshotOptions
@@ -566,6 +660,20 @@ extension RunnerTests {
     return abandonedTreeCaptureCount > 0
   }
 
+  /// The watchdog abandoned one unit of XCTest main-thread capture work that is still draining on
+  /// main; XCTest-backed snapshot tiers skip (`hasAbandonedTreeCapture`) until a matching release.
+  func retainAbandonedXCTestChannelWork() {
+    treeCaptureLock.lock()
+    abandonedTreeCaptureCount += 1
+    treeCaptureLock.unlock()
+  }
+
+  func releaseAbandonedXCTestChannelWork() {
+    treeCaptureLock.lock()
+    abandonedTreeCaptureCount -= 1
+    treeCaptureLock.unlock()
+  }
+
   /// Runs the blocking tree-snapshot XPC on the main thread bounded by `sliceSeconds`. On
   /// timeout the XPC keeps running on main (it cannot be cancelled); the capture is marked
   /// abandoned so plans avoid XCTest-backed tiers until it drains, the tree backend is penalized
@@ -583,9 +691,7 @@ extension RunnerTests {
       timeout: sliceSeconds,
       timeoutError: treeCaptureTimeoutError(sliceSeconds: sliceSeconds),
       onAbandoned: {
-        self.treeCaptureLock.lock()
-        self.abandonedTreeCaptureCount += 1
-        self.treeCaptureLock.unlock()
+        self.retainAbandonedXCTestChannelWork()
         NSLog("AGENT_DEVICE_RUNNER_TREE_CAPTURE_SLICE_TIMEOUT slice=%.1f", sliceSeconds)
         self.penalizeSnapshotXCTestChannel(
           bundleId: self.currentBundleId,
@@ -593,9 +699,7 @@ extension RunnerTests {
         )
       },
       onDrained: {
-        self.treeCaptureLock.lock()
-        self.abandonedTreeCaptureCount -= 1
-        self.treeCaptureLock.unlock()
+        self.releaseAbandonedXCTestChannelWork()
         NSLog("AGENT_DEVICE_RUNNER_TREE_CAPTURE_DRAINED")
       }
     ) {
@@ -789,6 +893,19 @@ extension RunnerTests {
     return .infinite
   }
 
+  static func snapshotTraversalIdentity(
+    elementType: XCUIElement.ElementType,
+    label: String,
+    identifier: String,
+    frame: CGRect
+  ) -> String {
+    #if os(iOS)
+    "\(elementType)-\(label)-\(identifier)-\(frame.origin.x)-\(frame.origin.y)-\(frame.width)-\(frame.height)"
+    #else
+    return "\(elementType)-\(label)-\(identifier)-\(frame.origin.x)-\(frame.origin.y)"
+    #endif
+  }
+
   private func aggregatedLabel(for snapshot: XCUIElementSnapshot, depth: Int = 0) -> String? {
     if depth > 4 { return nil }
     let text = snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)

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

@@ -118,6 +118,17 @@ extension RunnerTests {
     )
   }
 
+  func clearSnapshotXCTestChannelPenalty(reason: String) {
+    snapshotXCTestChannelPenaltyLock.lock()
+    let hadActivePenalty = Date() < snapshotXCTestChannelPenaltyUntil
+    snapshotXCTestChannelPenaltyBundleId = nil
+    snapshotXCTestChannelPenaltyUntil = Date.distantPast
+    snapshotXCTestChannelPenaltyLock.unlock()
+    if hadActivePenalty {
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_PENALTY_CLEARED reason=%@", reason)
+    }
+  }
+
   func isSnapshotXCTestChannelPenalized(bundleId: String?) -> Bool {
     snapshotXCTestChannelPenaltyLock.lock()
     defer { snapshotXCTestChannelPenaltyLock.unlock() }
@@ -127,6 +138,12 @@ extension RunnerTests {
     return penalized == bundleId
   }
 
+  func consumeSnapshotXCTestPenaltyWarmupExemption() -> Bool {
+    let pending = snapshotXCTestPenaltyWarmupExemptionPending
+    snapshotXCTestPenaltyWarmupExemptionPending = false
+    return pending
+  }
+
   /// Pure plan-reorder rule: a penalized XCTest accessibility channel uses independent backends
   /// when the platform has one, otherwise it keeps XCTest work on a short probe. The raw
   /// diagnostic plan keeps tree-first errors, and unknown plans are left untouched.
@@ -168,12 +185,15 @@ extension RunnerTests {
     _ plan: [SnapshotBackendKind],
     app: XCUIApplication,
     options: SnapshotOptions,
-    terminal: SnapshotCaptureTerminalPolicy
+    terminal: SnapshotCaptureTerminalPolicy,
+    deadline: Date? = nil
   ) throws -> DataPayload {
     var best: (kind: SnapshotBackendKind, capture: SnapshotBackendCapture)?
     var firstFailure: (reason: String, code: String)?
     var axFailure: SnapshotCaptureFailure?
-    let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
+    // A caller may share the pre-plan system-modal probe's deadline; otherwise own the full budget (#1244).
+    let deadline = deadline ?? Date().addingTimeInterval(Self.snapshotPlanBudget)
+    let suppressXCTestPenalty = consumeSnapshotXCTestPenaltyWarmupExemption()
 
     // Reorder is iOS-only because hostile screens can make XCTest tree/query work grind while
     // the app remains visually responsive. Simulators can avoid that channel through private AX;
@@ -237,14 +257,30 @@ extension RunnerTests {
             treeCaptureSliceBudgetOverride: effective.treeCaptureSliceBudgetOverride
           )
         else {
-          recordSlowXCTestSnapshotBackendIfNeeded(kind, startedAt: backendStartedAt)
+          recordSlowXCTestSnapshotBackendIfNeeded(
+            kind,
+            startedAt: backendStartedAt,
+            penaltySuppressed: suppressXCTestPenalty
+          )
           continue
         }
         capture = result
-        recordSlowXCTestSnapshotBackendIfNeeded(kind, startedAt: backendStartedAt)
+        recordSlowXCTestSnapshotBackendIfNeeded(
+          kind,
+          startedAt: backendStartedAt,
+          penaltySuppressed: suppressXCTestPenalty
+        )
       } catch let failure as SnapshotCaptureFailure {
-        recordXCTestSnapshotBackendFailureIfNeeded(kind, failure: failure)
-        recordSlowXCTestSnapshotBackendIfNeeded(kind, startedAt: backendStartedAt)
+        recordXCTestSnapshotBackendFailureIfNeeded(
+          kind,
+          failure: failure,
+          penaltySuppressed: suppressXCTestPenalty
+        )
+        recordSlowXCTestSnapshotBackendIfNeeded(
+          kind,
+          startedAt: backendStartedAt,
+          penaltySuppressed: suppressXCTestPenalty
+        )
         if Self.isAxSnapshotFailure(failure) { axFailure = failure }
         if firstFailure == nil {
           firstFailure = (failure.message, Self.isAxSnapshotFailure(failure) ? "ax-rejected" : "capture-failed")
@@ -313,7 +349,12 @@ extension RunnerTests {
 
   /// Marks XCTest-backed snapshot tiers as penalized when one attempt ground past the slow-capture
   /// threshold — even a successful one: the next capture of this screen must not re-grind.
-  private func recordSlowXCTestSnapshotBackendIfNeeded(_ kind: SnapshotBackendKind, startedAt: Date) {
+  private func recordSlowXCTestSnapshotBackendIfNeeded(
+    _ kind: SnapshotBackendKind,
+    startedAt: Date,
+    penaltySuppressed: Bool
+  ) {
+    guard !penaltySuppressed else { return }
     guard kind.usesXCTestAccessibilityChannel else { return }
     let elapsed = Date().timeIntervalSince(startedAt)
     guard elapsed > snapshotXCTestSlowCaptureThreshold else { return }
@@ -325,8 +366,10 @@ extension RunnerTests {
 
   private func recordXCTestSnapshotBackendFailureIfNeeded(
     _ kind: SnapshotBackendKind,
-    failure: SnapshotCaptureFailure
+    failure: SnapshotCaptureFailure,
+    penaltySuppressed: Bool
   ) {
+    guard !penaltySuppressed else { return }
     guard kind.usesXCTestAccessibilityChannel, failure.code == Self.xCTestSnapshotTimeoutCode else { return }
     penalizeSnapshotXCTestChannel(
       bundleId: currentBundleId,