agent-device 0.18.2 → 0.19.0

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

@@ -0,0 +1,67 @@
+import XCTest
+
+struct FlatSnapshotFilterNode {
+  let isRoot: Bool
+  let label: String
+  let identifier: String
+  let valueText: String?
+  let visible: Bool
+
+  func matchesScope(_ scope: String) -> Bool {
+    let haystack = [label, identifier, valueText ?? ""].joined(separator: "\n")
+    return haystack.localizedCaseInsensitiveContains(scope)
+  }
+}
+
+struct FlatSnapshotFilterDecision {
+  let include: Bool
+  let insideMatchedScope: Bool
+}
+
+extension RunnerTests {
+  func flatSnapshotFilterDecision(
+    _ node: FlatSnapshotFilterNode,
+    options: SnapshotOptions,
+    insideMatchedScope: Bool
+  ) -> FlatSnapshotFilterDecision {
+    let scope = options.scope?.trimmingCharacters(in: .whitespacesAndNewlines)
+    let scopeActive = scope?.isEmpty == false
+    let matchesScope: Bool
+    if scopeActive, let scope {
+      matchesScope = node.matchesScope(scope)
+    } else {
+      matchesScope = false
+    }
+    let nowInsideScope = insideMatchedScope || matchesScope
+
+    let include: Bool
+    if node.isRoot {
+      include = true
+    } else if scopeActive && !nowInsideScope {
+      include = false
+    } else if options.interactiveOnly && !node.visible {
+      include = false
+    } else {
+      include = true
+    }
+
+    return FlatSnapshotFilterDecision(include: include, insideMatchedScope: nowInsideScope)
+  }
+
+  func privateAXInteractiveCandidate(rawElementType: Int) -> Bool {
+    guard let type = flatSnapshotElementType(rawElementType: rawElementType) else {
+      return false
+    }
+    return interactiveTypes.contains(type) || Self.scrollContainerTypes.contains(type)
+  }
+
+  func flatSnapshotElementType(rawElementType: Int) -> XCUIElement.ElementType? {
+    guard let raw = UInt(exactly: rawElementType),
+      let type = XCUIElement.ElementType(rawValue: raw)
+    else {
+      return nil
+    }
+    return type
+  }
+
+}

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

@@ -200,16 +200,32 @@ extension RunnerTests {
     )
   }
 
+  // Maestro-compat gate for the non-hittable coordinate fallback: an element
+  // with no frame at all cannot be coordinate-tapped, otherwise the decision
+  // is the shared TapPointPolicy center-in-frame rule (golden parity table
+  // with the TS twin). app.frame is the frame source here — replay taps
+  // resolved bounds Maestro-style, so the union frame is intentional.
   private func hasTappableFrame(app: XCUIApplication, element: XCUIElement) -> Bool {
     let frame = element.frame
     if frame.isEmpty {
       return false
     }
-    let appFrame = app.frame
-    if appFrame.isEmpty {
-      return true
+    return TapPointPolicy.isAllowed(elementFrame: frame, windowFrame: app.frame)
+  }
+
+  // The tappable on-screen viewport. app.frame is unsuitable: it unions
+  // transformed subtrees, so a closed drawer at negative x inflates it and
+  // out-of-window coordinates still pass containment. Falls back to app.frame
+  // when no window frame is readable.
+  func onScreenWindowFrame(app: XCUIApplication) -> CGRect {
+    let window = app.windows.element(boundBy: 0)
+    if window.exists {
+      let frame = window.frame
+      if !frame.isEmpty {
+        return frame
+      }
     }
-    return appFrame.contains(CGPoint(x: frame.midX, y: frame.midY))
+    return app.frame
   }
 
   func queryElement(app: XCUIApplication, selectorKey: String, selectorValue: String) -> Response {
@@ -1232,74 +1248,4 @@ extension RunnerTests {
     return element.exists ? element : nil
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  // Identity in portrait/unknown, 90° per landscape, 180° upside-down.
-  func testNativeSynthesizedPointRotatesByInterfaceOrientation() {
-    let portrait = CGRect(x: 0, y: 0, width: 834, height: 1210)
-    let landscape = CGRect(x: 0, y: 0, width: 1210, height: 834)
-    let offsetLandscape = CGRect(x: 10, y: 20, width: 1210, height: 834)
-    // (frame, UIInterfaceOrientation, expected native point) for a tap at (170, 268).
-    let cases: [(CGRect, Int, CGPoint)] = [
-      (portrait, RunnerInterfaceOrientation.portrait, CGPoint(x: 170, y: 268)),
-      (landscape, RunnerInterfaceOrientation.landscapeRight, CGPoint(x: 566, y: 170)),
-      (landscape, RunnerInterfaceOrientation.landscapeLeft, CGPoint(x: 268, y: 1040)),
-      (portrait, RunnerInterfaceOrientation.portraitUpsideDown, CGPoint(x: 664, y: 942)),
-      (portrait, RunnerInterfaceOrientation.unknown, CGPoint(x: 170, y: 268)),
-    ]
-    for (frame, orientation, expected) in cases {
-      XCTAssertEqual(
-        nativeSynthesizedPoint(orientedX: 170, orientedY: 268, in: frame, interfaceOrientation: orientation),
-        expected,
-        "interfaceOrientation \(orientation)"
-      )
-    }
-    XCTAssertEqual(
-      nativeSynthesizedPoint(
-        orientedX: 180,
-        orientedY: 288,
-        in: offsetLandscape,
-        interfaceOrientation: RunnerInterfaceOrientation.landscapeLeft
-      ),
-      CGPoint(x: 268, y: 1040),
-      "non-zero frame origin is localized before rotation"
-    )
-  }
-
-  func testNativeSynthesizedVectorRotatesByInterfaceOrientation() {
-    let cases: [(Int, CGVector)] = [
-      (RunnerInterfaceOrientation.portrait, CGVector(dx: 40, dy: -20)),
-      (RunnerInterfaceOrientation.landscapeRight, CGVector(dx: 20, dy: 40)),
-      (RunnerInterfaceOrientation.landscapeLeft, CGVector(dx: -20, dy: -40)),
-      (RunnerInterfaceOrientation.portraitUpsideDown, CGVector(dx: -40, dy: 20)),
-      (RunnerInterfaceOrientation.unknown, CGVector(dx: 40, dy: -20)),
-    ]
-    for (orientation, expected) in cases {
-      let vector = nativeSynthesizedVector(orientedDx: 40, orientedDy: -20, interfaceOrientation: orientation)
-      XCTAssertEqual(vector.dx, expected.dx, "dx interfaceOrientation \(orientation)")
-      XCTAssertEqual(vector.dy, expected.dy, "dy interfaceOrientation \(orientation)")
-    }
-  }
-
-  func testDesktopScrollWheelDeltasMapDirections() throws {
-    XCTAssertEqual(try XCTUnwrap(desktopScrollWheelDeltas(direction: "up", pixels: 120)).vertical, 120)
-    XCTAssertEqual(try XCTUnwrap(desktopScrollWheelDeltas(direction: "down", pixels: 120)).vertical, -120)
-    XCTAssertEqual(try XCTUnwrap(desktopScrollWheelDeltas(direction: "left", pixels: 120)).horizontal, 120)
-    XCTAssertEqual(try XCTUnwrap(desktopScrollWheelDeltas(direction: "right", pixels: 120)).horizontal, -120)
-    XCTAssertNil(desktopScrollWheelDeltas(direction: "diagonal", pixels: 120))
-  }
-
-  func testDesktopScrollWheelDeltaEventsHonorDurationAndPreservePixels() throws {
-    let events = try XCTUnwrap(desktopScrollWheelDeltaEvents(direction: "down", pixels: 200, durationMs: 50))
-    XCTAssertEqual(events.count, 4)
-    XCTAssertEqual(events.map(\.vertical).reduce(0, +), -200)
-    XCTAssertEqual(events.map(\.horizontal).reduce(0, +), 0)
-    XCTAssertEqual(desktopScrollEventIntervalSeconds(durationMs: 50, eventCount: events.count), 0.05 / 3.0)
-  }
-
-  func testDesktopScrollWheelDeltaEventsKeepInstantScrollSingleEvent() throws {
-    let events = try XCTUnwrap(desktopScrollWheelDeltaEvents(direction: "down", pixels: 200, durationMs: 0))
-    XCTAssertEqual(events.count, 1)
-    XCTAssertEqual(events.first?.vertical, -200)
-  }
-#endif
 }

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

@@ -0,0 +1,64 @@
+import XCTest
+
+// Swift port of buildScrollGesturePlan from src/core/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 —
+// 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()`
+// (half away from zero) matches JS `Math.round` (half up) on every value computed below.
+
+struct RunnerScrollGesturePlan {
+  let x1: Double
+  let y1: Double
+  let x2: Double
+  let y2: Double
+  let travelPixels: Double
+}
+
+private let runnerDefaultScrollAmount = 0.6
+private let runnerDefaultEdgePaddingFraction = 0.05
+
+func runnerScrollGesturePlan(
+  direction: String,
+  amount: Double?,
+  pixels: Double?,
+  referenceWidth: Double,
+  referenceHeight: Double
+) -> RunnerScrollGesturePlan? {
+  // Mirror the TS INVALID_ARGS contract: non-positive or non-finite amount/pixels are rejected
+  // rather than clamped into a journaled 1px scroll. The daemon validates before sending, so
+  // this only triggers for non-daemon wire clients.
+  if let amount, !(amount.isFinite && amount > 0) { return nil }
+  if let pixels, !(pixels.isFinite && pixels > 0) { return nil }
+  let axisLength = (direction == "up" || direction == "down") ? referenceHeight : referenceWidth
+  let requestedAmount = amount ?? runnerDefaultScrollAmount
+  let requestedPixels: Double =
+    pixels.map { max(1, $0.rounded()) } ?? (axisLength * requestedAmount).rounded()
+  let edgePadding = max(1, (axisLength * runnerDefaultEdgePaddingFraction).rounded())
+  let maxTravelPixels = max(1, axisLength - edgePadding * 2)
+  let travelPixels = max(1, min(requestedPixels, maxTravelPixels))
+  let halfTravel = (travelPixels / 2).rounded()
+  let centerX = (referenceWidth / 2).rounded()
+  let centerY = (referenceHeight / 2).rounded()
+
+  func plan(_ x1: Double, _ y1: Double, _ x2: Double, _ y2: Double) -> RunnerScrollGesturePlan {
+    RunnerScrollGesturePlan(x1: x1, y1: y1, x2: x2, y2: y2, travelPixels: travelPixels)
+  }
+
+  switch direction {
+  case "up":
+    return plan(centerX, centerY - halfTravel, centerX, centerY + halfTravel)
+  case "down":
+    return plan(centerX, centerY + halfTravel, centerX, centerY - halfTravel)
+  case "left":
+    return plan(centerX - halfTravel, centerY, centerX + halfTravel, centerY)
+  case "right":
+    return plan(centerX + halfTravel, centerY, centerX - halfTravel, centerY)
+  default:
+    return nil
+  }
+}
+

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

@@ -273,180 +273,3 @@ extension RunnerTests {
   }
 }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-// MARK: - In-bundle unit tests (device-free)
-
-extension RunnerTests {
-  func testSequenceDecodesStepsFromWire() throws {
-    let json = """
-    {"command":"sequence","commandId":"seq-1","steps":[
-      {"kind":"tap","x":100,"y":200},
-      {"kind":"doubleTap","x":101,"y":200},
-      {"kind":"longPress","x":102,"y":200,"durationMs":300},
-      {"kind":"drag","x":10,"y":600,"x2":10,"y2":200,"durationMs":250,"pauseMs":50}
-    ]}
-    """
-    let command = try JSONDecoder().decode(Command.self, from: Data(json.utf8))
-    XCTAssertEqual(command.command, .sequence)
-    XCTAssertEqual(command.steps?.count, 4)
-    XCTAssertEqual(command.steps?[0].kind, "tap")
-    XCTAssertEqual(command.steps?[1].kind, "doubleTap")
-    XCTAssertEqual(command.steps?[3].x2, 10)
-    XCTAssertEqual(command.steps?[3].pauseMs, 50)
-  }
-
-  func testSequenceAcceptsDoubleTapKind() {
-    // A doubleTap step missing coords must fail on the coords check, not the kind allowlist —
-    // proving "doubleTap" passes validateSequenceStep without needing a device to execute on.
-    let response = executeSequenceForTest(steps: [
-      sequenceStep(kind: "doubleTap", x: nil)
-    ])
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-    XCTAssertTrue(response.error?.message.contains("requires finite x and y") ?? false)
-    XCTAssertFalse(response.error?.message.contains("unsupported kind") ?? true)
-  }
-
-  func testSequenceRejectsUnknownKind() throws {
-    let response = executeSequenceForTest(steps: [
-      sequenceStep(kind: "tap", x: 1, y: 2),
-      sequenceStep(kind: "pinch", x: 3, y: 4),
-    ])
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-    XCTAssertTrue(response.error?.message.contains("step 1") ?? false)
-    XCTAssertTrue(response.error?.message.contains("pinch") ?? false)
-  }
-
-  func testSequenceRejectsEmpty() {
-    let response = executeSequenceForTest(steps: [])
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-  }
-
-  func testSequenceRejectsTooManySteps() {
-    let steps = (0..<21).map { _ in sequenceStep(kind: "tap", x: 1, y: 2) }
-    let response = executeSequenceForTest(steps: steps)
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-    XCTAssertTrue(response.error?.message.contains("at most 20") ?? false)
-  }
-
-  func testSequenceRejectsDragMissingSecondPoint() {
-    let response = executeSequenceForTest(steps: [
-      sequenceStep(kind: "tap", x: 1, y: 2),
-      sequenceStep(kind: "drag", x: 3, y: 4),
-    ])
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-    XCTAssertTrue(response.error?.message.contains("step 1") ?? false)
-  }
-
-  func testAssembleSequencePreservesOrderOnSuccess() {
-    let steps = [
-      sequenceStep(kind: "tap", x: 1, y: 1),
-      sequenceStep(kind: "longPress", x: 2, y: 2),
-      sequenceStep(kind: "tap", x: 3, y: 3),
-    ]
-    var calls: [Int] = []
-    let execution = assembleSequenceExecution(steps: steps) { index, _ in
-      calls.append(index)
-      return SequenceStepOutcome(
-        outcome: .performed,
-        gestureStartUptimeMs: Double(index * 10),
-        gestureEndUptimeMs: Double(index * 10 + 5)
-      )
-    }
-    XCTAssertEqual(calls, [0, 1, 2])
-    XCTAssertEqual(execution.completedSteps, 3)
-    XCTAssertNil(execution.failedStepIndex)
-    XCTAssertEqual(execution.results.map { $0.kind }, ["tap", "longPress", "tap"])
-    XCTAssertEqual(execution.gestureStartUptimeMs, 0)
-    XCTAssertEqual(execution.gestureEndUptimeMs, 25)
-  }
-
-  func testAssembleSequenceStopsAtFirstFailure() {
-    let steps = [
-      sequenceStep(kind: "tap", x: 1, y: 1),
-      sequenceStep(kind: "drag", x: 2, y: 2),
-      sequenceStep(kind: "tap", x: 3, y: 3),
-    ]
-    var calls: [Int] = []
-    let execution = assembleSequenceExecution(steps: steps) { index, _ in
-      calls.append(index)
-      if index == 1 {
-        return SequenceStepOutcome(
-          outcome: .unsupported(message: "drag unsupported", hint: nil),
-          gestureStartUptimeMs: 10,
-          gestureEndUptimeMs: 15
-        )
-      }
-      return SequenceStepOutcome(outcome: .performed, gestureStartUptimeMs: 0, gestureEndUptimeMs: 5)
-    }
-    // Step 2 is never invoked.
-    XCTAssertEqual(calls, [0, 1])
-    XCTAssertEqual(execution.completedSteps, 1)
-    XCTAssertEqual(execution.failedStepIndex, 1)
-    // results.count == completedSteps + 1 (the failed step).
-    XCTAssertEqual(execution.results.count, 2)
-    XCTAssertEqual(execution.results[1].ok, false)
-    XCTAssertEqual(execution.results[1].errorCode, "UNSUPPORTED_OPERATION")
-    XCTAssertEqual(execution.results[1].errorMessage, "drag unsupported")
-  }
-
-  func testSequenceWorstCaseResponseStaysUnderJournalCap() throws {
-    let longMessage = String(repeating: "e", count: 200)
-    let results = (0..<20).map { index in
-      SequenceStepResult(
-        ok: index < 19,
-        kind: "drag",
-        errorCode: index < 19 ? nil : "UNSUPPORTED_OPERATION",
-        errorMessage: index < 19 ? nil : longMessage,
-        gestureStartUptimeMs: 123456.789,
-        gestureEndUptimeMs: 123466.789
-      )
-    }
-    let response = Response(
-      ok: true,
-      data: DataPayload(
-        message: "sequence",
-        completedSteps: 19,
-        failedStepIndex: 19,
-        sequenceResults: results
-      )
-    )
-    let encoded = try JSONEncoder().encode(response)
-    XCTAssertLessThan(encoded.count, 16 * 1024)
-  }
-
-  private func sequenceStep(
-    kind: String,
-    x: Double?,
-    y: Double? = nil,
-    x2: Double? = nil,
-    y2: Double? = nil
-  ) -> SequenceStep {
-    SequenceStep(
-      kind: kind, x: x, y: y, x2: x2, y2: y2, durationMs: nil, pauseMs: nil, synthesized: nil)
-  }
-
-  /// Validation runs before any executor call, so the INVALID_ARGS paths are exercised without
-  /// reaching the device executor (which is never invoked when validation rejects).
-  private func executeSequenceForTest(steps: [SequenceStep]) -> Response {
-    let command = makeSequenceCommand(steps: steps)
-    return executeSequence(command: command, activeApp: app)
-  }
-
-  /// Build a sequence Command via JSON so the test does not depend on the memberwise init's
-  /// parameter order.
-  private func makeSequenceCommand(steps: [SequenceStep]) -> Command {
-    struct SequenceCommandFixture: Encodable {
-      let command = "sequence"
-      let commandId = "seq-test"
-      let steps: [SequenceStep]
-    }
-    let data = try! JSONEncoder().encode(SequenceCommandFixture(steps: steps))
-    return try! JSONDecoder().decode(Command.self, from: data)
-  }
-}
-#endif

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

@@ -302,7 +302,11 @@ extension RunnerTests {
     return DataPayload(nodes: nodes, truncated: false)
   }
 
-  func snapshotFlatInteractive(app: XCUIApplication, options: SnapshotOptions) -> DataPayload {
+  func snapshotFlatInteractive(
+    app: XCUIApplication,
+    options: SnapshotOptions,
+    planDeadline: Date = .distantFuture
+  ) -> DataPayload {
     var nodes: [SnapshotNode] = [
       interactiveRootNode(rect: .zero)
     ]
@@ -310,9 +314,12 @@ extension RunnerTests {
       return DataPayload(nodes: nodes, truncated: false)
     }
 
-    let deadline = options.interactiveOnly
+    // Bounded by both its own sweep budget and the umbrella capture-plan deadline, so a
+    // chained recovery tier can never push the plan past the main-thread watchdog (#1105).
+    let sweepDeadline = options.interactiveOnly
       ? Date().addingTimeInterval(Self.flatInteractiveFallbackBudget)
       : Date.distantFuture
+    let deadline = min(sweepDeadline, planDeadline)
     let viewport = safeSnapshotViewport(app: app)
     var seen = Set<String>()
     var candidates: [SnapshotNode] = []
@@ -426,50 +433,6 @@ extension RunnerTests {
     )
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testSnapshotAccessibilityUnavailableMarksSparseSnapshotRunnerFatal() {
-    currentApp = app
-    currentBundleId = "com.example.app"
-
-    let payload = snapshotAccessibilityUnavailable(
-      failure: SnapshotCaptureFailure(
-        code: Self.axSnapshotErrorCode,
-        message: Self.axSnapshotFailureMessage,
-        hint: Self.axSnapshotHint
-      )
-    )
-
-    XCTAssertEqual(payload.message, "\(Self.axSnapshotFailureMessage) Hint: \(Self.axSnapshotHint)")
-    XCTAssertEqual(payload.nodes?.count, 1)
-    XCTAssertEqual(payload.nodes?.first?.type, "Application")
-    XCTAssertEqual(payload.truncated, true)
-    XCTAssertEqual(payload.runnerFatal, true)
-    XCTAssertEqual(payload.runnerFatalReason, Self.axSnapshotUnavailableReason)
-    XCTAssertNil(currentApp)
-    XCTAssertNil(currentBundleId)
-  }
-
-  func testRecoveredSnapshotMessagePreservesHint() {
-    let message = recoveredSnapshotMessage(
-      SnapshotCaptureFailure(
-        code: Self.axSnapshotErrorCode,
-        message: Self.axSnapshotFailureMessage,
-        hint: Self.axSnapshotHint
-      )
-    )
-
-    XCTAssertTrue(message.contains(Self.axSnapshotFailureMessage))
-    XCTAssertTrue(message.contains(Self.axSnapshotHint))
-  }
-
-  func testRawSnapshotTooLargeFailureIsStructured() {
-    let failure = rawSnapshotTooLargeFailure(nodeCount: Self.rawSnapshotMaxNodes + 1)
-
-    XCTAssertEqual(failure.code, Self.rawSnapshotTooLargeCode)
-    XCTAssertTrue(failure.message.contains("\(Self.rawSnapshotMaxNodes) nodes"))
-    XCTAssertEqual(failure.hint, Self.rawSnapshotTooLargeHint)
-  }
-#endif
 
   private func interactiveRootNode(rect: CGRect) -> SnapshotNode {
     SnapshotNode(
@@ -562,12 +525,14 @@ extension RunnerTests {
 
   func makeSnapshotTraversalContext(
     app: XCUIApplication,
-    options: SnapshotOptions
+    options: SnapshotOptions,
+    captureDeadline: Date = .distantFuture
   ) throws -> SnapshotTraversalContext? {
     let viewport = safeSnapshotViewport(app: app)
     let queryRoot = options.scope.flatMap { findScopeElement(app: app, scope: $0) } ?? app
 
-    guard let rootSnapshot = try captureSnapshotRoot(queryRoot) else {
+    let slice = min(treeCaptureSliceBudget, max(0.5, captureDeadline.timeIntervalSinceNow))
+    guard let rootSnapshot = try captureSnapshotRootBounded(queryRoot, sliceSeconds: slice) else {
       return nil
     }
 
@@ -582,6 +547,74 @@ extension RunnerTests {
     )
   }
 
+  static let treeCaptureTimeoutCode = "IOS_TREE_CAPTURE_TIMEOUT"
+
+  func hasAbandonedTreeCapture() -> Bool {
+    treeCaptureLock.lock()
+    defer { treeCaptureLock.unlock() }
+    return abandonedTreeCaptureCount > 0
+  }
+
+  /// Runs the blocking tree-snapshot XPC on a worker thread bounded by `sliceSeconds`. On
+  /// timeout the XPC keeps running on its worker (it cannot be cancelled); the capture is
+  /// marked abandoned so plans avoid XCTest-backed tiers until it drains, the tree backend is
+  /// penalized for this bundle, and the plan moves on to the private AX backend (#1105).
+  private func captureSnapshotRootBounded(
+    _ element: XCUIElement,
+    sliceSeconds: TimeInterval
+  ) throws -> XCUIElementSnapshot? {
+    final class TreeCaptureBox {
+      var abandoned = false
+      var outcome: Result<XCUIElementSnapshot?, Error>?
+    }
+    let box = TreeCaptureBox()
+    let semaphore = DispatchSemaphore(value: 0)
+    DispatchQueue.global(qos: .userInitiated).async {
+      var result: Result<XCUIElementSnapshot?, Error>
+      do {
+        result = .success(try self.captureSnapshotRoot(element))
+      } catch {
+        result = .failure(error)
+      }
+      self.treeCaptureLock.lock()
+      if box.abandoned {
+        self.abandonedTreeCaptureCount -= 1
+        self.treeCaptureLock.unlock()
+        NSLog("AGENT_DEVICE_RUNNER_TREE_CAPTURE_DRAINED")
+      } else {
+        box.outcome = result
+        self.treeCaptureLock.unlock()
+      }
+      semaphore.signal()
+    }
+    if semaphore.wait(timeout: .now() + sliceSeconds) == .timedOut {
+      treeCaptureLock.lock()
+      let timedOut = box.outcome == nil
+      if timedOut {
+        box.abandoned = true
+        abandonedTreeCaptureCount += 1
+      }
+      treeCaptureLock.unlock()
+      if timedOut {
+        NSLog("AGENT_DEVICE_RUNNER_TREE_CAPTURE_SLICE_TIMEOUT slice=%.1f", sliceSeconds)
+        penalizeSnapshotTreeBackend(bundleId: currentBundleId, reason: "tree_capture_slice_timeout")
+        throw SnapshotCaptureFailure(
+          code: Self.treeCaptureTimeoutCode,
+          message: "the XCTest tree capture exceeded its \(Int(sliceSeconds))s time slice",
+          hint: "The capture plan recovers through the private AX backend on this screen."
+        )
+      }
+    }
+    switch box.outcome {
+    case .success(let snapshot):
+      return snapshot
+    case .failure(let error):
+      throw error
+    case .none:
+      return nil
+    }
+  }
+
   private func captureSnapshotRoot(_ element: XCUIElement) throws -> XCUIElementSnapshot? {
     var rootSnapshot: XCUIElementSnapshot?
     var swiftErrorMessage: String?