Merge remote-tracking branch 'origin/main' into feat/maestro-setPermissions

# Conflicts:
#	packages/contracts/src/client-settings.ts
#	packages/contracts/src/settings.ts
#	src/commands/capture/settings.ts

Author: Rohit3523

.fallowrc.json

@@ -95,6 +95,7 @@
       "exports": [
         "detachIosSimulatorRunnerSessionsForShutdown",
         "hasLiveIosRunnerSession",
+        "releaseIosRunnerOnClose",
         "releaseSpeculativeIosRunnerSessionFor",
         "stopAllIosRunnerSessions"
       ]
@@ -160,7 +161,6 @@
         "resolveRunnerAppBundleId",
         "detachIosSimulatorRunnerSessionsForShutdown",
         "getRunnerSessionSnapshot",
-        "scheduleIosRunnerIdleStop",
         "stopIosRunnerSession",
         "stopAllIosRunnerSessions",
         "readStaleRunnerLease",

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- Changed (android): the snapshot helper release manifest no longer carries `installArgs`, and the
+  helper installs with a fixed `adb install -r` like the IME helper. The array only ever spelled
+  `install -r` plus the `-t` that #2603 retired with the `testOnly` flag, so the manifest → flag →
+  option → flag round trip and its allowlist carried nothing. Older manifests that still contain
+  the field parse unchanged; the field is ignored. The adb provider `install` capability now takes
+  only `replace` (#2364).
 - Fixed: BrowserStack sessions honour `--provider-project`, `--provider-build`, and
   `--provider-session-name`. The capability builder emitted the legacy JSON Wire keys `device`,
   `os_version`, and `app` at the top level next to the W3C `bstack:options` block; the hub treats a
@@ -14,6 +20,21 @@
   BrowserStack runs for the session, as `bstack:options.appiumVersion`. Unset, BrowserStack falls
   back to Appium 1.x, which predates the `mobile:` commands the interactor issues (`deepLink`,
   `pressButton`, `activateApp`).
+- Changed (iOS runner): what recovers a stuck runner is decided by the recorded error, not by its
+  wording. A readiness preflight marks the error it gives up with, and that marker is now the whole
+  test for restarting the session and replaying the command — except for a request that was canceled,
+  which that same catch also marks: a command nobody is going to send again has no restart to spend,
+  and the session it would tear down may be one that still works. Two message checks decided it before,
+  and a preflight reaches the caller in whatever shape its connect loop ended with — "Runner did not
+  accept connection", "Runner endpoint probe failed", a killed `simctl` fallback, a post that ran out
+  of its budget — so only some of those restarted and the rest failed the command. The other half is
+  what no longer happens: when a slow
+  boot spends the whole prepare budget, the health check reports "prepare ios-runner timed out", and
+  that no longer wipes a restored `xcodebuild` artifact on the way to a rebuild — the runner session
+  is invalidated and prepare retries with the artifact intact. Only a failure that indicts the
+  artifact rebuilds it, so a runner that refuses the connection or never answers on any route still
+  wipes it and rebuilds, which is what that rule is for.
+
 - Changed (sessions): the implicit session is now keyed by workspace **and platform**, so one checkout
   can drive iOS and Android without inventing a `--session` name for every command (#2580). An
   implicit session was addressed by `cwd:<workspace>:default`, one slot per checkout, and it stayed

android/snapshot-helper/README.md

@@ -137,6 +137,6 @@ The final instrumentation result for the default `snapshot` mode includes:
 Failures return `ok=false`, `errorType`, and `message` in the final result.
 
 The release manifest is a stable provider contract for the current helper protocol. Providers should
-resolve the APK from `apkUrl`, verify `sha256`, install using `installArgs`, and run
-`instrumentationRunner`. `installArgs` must start with `install`; extra arguments are limited to the
-allowlisted adb install flags `-r`, `-t`, `-d`, and `-g`, and the consumer appends the APK path.
+resolve the APK from `apkUrl`, verify `sha256`, install it with `adb install -r <apk>`, and run
+`instrumentationRunner`. Manifests up to 0.21.3 also carried an `installArgs` array; it only ever
+spelled `install -r` (plus `-t` while the helper was `testOnly`), so consumers can ignore it.

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

@@ -999,6 +999,14 @@ extension RunnerTests {
     case idle
     case busy(abandonedForSeconds: TimeInterval)
     case wedged(abandonedForSeconds: TimeInterval)
+
+    /// Whether the main thread is occupied by watchdog-abandoned work, for the occupancy stamp that
+    /// every successful response carries. Wedged is still occupied: it only differs in that a
+    /// restart, not waiting, is the cure.
+    var reportsMainThreadBusy: Bool {
+      if case .idle = self { return false }
+      return true
+    }
   }
 
   func currentMainThreadBusyState() -> MainThreadBusyState {
@@ -2187,7 +2195,7 @@ extension RunnerTests {
             code: "UNSUPPORTED_OPERATION",
             message: "Unable to dismiss the iOS keyboard: the keyboard exposes no dismiss key, and background taps are never attempted (no tap outside the keyboard can be proven side-effect-free)",
             hint:
-              "The on-screen keyboard usually does not block agent-device interactions: press the next target directly instead of retrying dismiss. If that press fails or reports no visible effect, scroll the target into view, or use keyboard enter to press the return key when submission is wanted."
+              "An element whose center sits behind the on-screen keyboard is refused with tap_keyboard_occludes_target; one whose center stays above the keys presses normally. To end editing, tap the app's own Done/Cancel control, or use keyboard enter to press the return key when submission is wanted."
           )
         )
       }

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift

@@ -183,6 +183,52 @@ extension RunnerTests {
     XCTAssertEqual(stamped.error?.message, "boom")
   }
 
+  func testStampingCurrentMainThreadBusyPreservesPayload() {
+    let stamped = Response(ok: true, data: DataPayload(nodes: [], truncated: false))
+      .stampingCurrentMainThreadBusy(true)
+
+    XCTAssertEqual(stamped.ok, true)
+    XCTAssertEqual(stamped.data?.runnerMainThreadBusy, true)
+  }
+
+  func testStampingCurrentMainThreadBusySkipsErrorResponses() {
+    let response = Response(ok: false, error: ErrorPayload(code: "RUNNER_BUSY", message: "busy"))
+    let stamped = response.stampingCurrentMainThreadBusy(true)
+
+    XCTAssertEqual(stamped.ok, false)
+    XCTAssertNil(stamped.data)
+    XCTAssertEqual(stamped.error?.code, "RUNNER_BUSY")
+  }
+
+  func testMainThreadBusyStateReportsOccupancy() {
+    XCTAssertFalse(MainThreadBusyState.idle.reportsMainThreadBusy)
+    XCTAssertTrue(MainThreadBusyState.busy(abandonedForSeconds: 5).reportsMainThreadBusy)
+    XCTAssertTrue(MainThreadBusyState.wedged(abandonedForSeconds: 200).reportsMainThreadBusy)
+    XCTAssertEqual(
+      Response(ok: true).stampingCurrentMainThreadBusy(false).data?.runnerMainThreadBusy, false)
+  }
+
+  func testCommandFailedResponseTagsMainThreadTimeoutWithTypedCode() {
+    let timeout = NSError(
+      domain: RunnerErrorDomain.general,
+      code: RunnerErrorCode.mainThreadExecutionTimedOut,
+      userInfo: [NSLocalizedDescriptionKey: "main thread execution timed out"]
+    )
+
+    let response = commandFailedResponse(from: timeout)
+
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, RunnerWireErrorCode.mainThreadTimeout)
+  }
+
+  func testCommandFailedResponseKeepsGenericCodeForOtherErrors() {
+    let other = NSError(domain: "SomeOtherDomain", code: 99, userInfo: nil)
+
+    let response = commandFailedResponse(from: other)
+
+    XCTAssertEqual(response.error?.code, "COMMAND_FAILED")
+  }
+
   func testJournalStoredResponseStaysUnstamped() throws {
     let journal = RunnerCommandJournal()
     let recordStart = runnerJournalCommand("recordStart", id: "record-start-anchor")

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -229,6 +229,16 @@ extension Response {
     payload.currentUptimeMs = value
     return Response(ok: ok, data: payload, error: error)
   }
+
+  // The daemon reads this occupancy flag to decide whether a healthy response proves the runner
+  // drained its watchdog-abandoned main-thread work. Only successful responses carry it; a refusal
+  // is itself the busy signal and needs no stamp.
+  func stampingCurrentMainThreadBusy(_ value: Bool) -> Response {
+    guard ok else { return self }
+    var payload = data ?? DataPayload()
+    payload.runnerMainThreadBusy = value
+    return Response(ok: ok, data: payload, error: error)
+  }
 }
 
 struct DataPayload: Codable {
@@ -276,6 +286,11 @@ struct DataPayload: Codable {
   var textEntryRoute: String?
   var runnerFatal: Bool?
   var runnerFatalReason: String?
+  /// Whether main-thread XCTest work past the execution watchdog is still draining when this
+  /// response is written. A private-AX snapshot can be served successfully while an abandoned tree
+  /// crawl still grinds, so the healthy response must carry the live occupancy rather than let the
+  /// daemon read `ok` as proof the runner drained (#2552).
+  var runnerMainThreadBusy: Bool?
   var completedSteps: Int?
   var failedStepIndex: Int?
   var sequenceResults: [SequenceStepResult]?

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift

@@ -152,14 +152,7 @@ extension RunnerTests {
           self.deliverCommandResult(
             command: command,
             result: (
-              self.jsonResponse(
-                status: 500,
-                response: self.errorResponse(
-                  code: "COMMAND_FAILED",
-                  message: error.localizedDescription,
-                  hint: "Check the runner log for XCTest details, then retry after the app is foregrounded if this was a timeout or activation failure."
-                )
-              ),
+              self.jsonResponse(status: 500, response: self.commandFailedResponse(from: error)),
               false
             ),
             completion: completion
@@ -274,7 +267,9 @@ extension RunnerTests {
     // rather than pairing a stale uptime with a much-later receipt time.
     let stamped =
       response.ok
-      ? response.stampingCurrentUptimeMs(ProcessInfo.processInfo.systemUptime * 1000)
+      ? response
+        .stampingCurrentUptimeMs(ProcessInfo.processInfo.systemUptime * 1000)
+        .stampingCurrentMainThreadBusy(currentMainThreadBusyState().reportsMainThreadBusy)
       : response
     let encoder = JSONEncoder()
     let body = (try? encoder.encode(stamped)).flatMap { String(data: $0, encoding: .utf8) } ?? "{}"
@@ -285,6 +280,32 @@ extension RunnerTests {
     Response(ok: false, error: ErrorPayload(code: code, message: message, hint: hint))
   }
 
+  /// Turns a thrown command error into its wire response. The execution-watchdog timeout keeps its
+  /// own typed code so the daemon records the runner as main-thread-occupied from the stalling
+  /// command itself, not only from a later `RUNNER_BUSY` refusal (#2552); every other throw stays the
+  /// generic `COMMAND_FAILED`.
+  func commandFailedResponse(from error: Error) -> Response {
+    let nsError = error as NSError
+    if nsError.domain == RunnerErrorDomain.general,
+      nsError.code == RunnerErrorCode.mainThreadExecutionTimedOut
+    {
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: RunnerWireErrorCode.mainThreadTimeout,
+          message: nsError.localizedDescription,
+          hint:
+            "The runner abandoned this command's main-thread work past its execution watchdog and it is still draining. Wait and retry, or use a screenshot and interact by coordinates."
+        )
+      )
+    }
+    return errorResponse(
+      code: "COMMAND_FAILED",
+      message: error.localizedDescription,
+      hint: "Check the runner log for XCTest details, then retry after the app is foregrounded if this was a timeout or activation failure."
+    )
+  }
+
   private func httpResponse(status: Int, body: String) -> Data {
     let headers = [
       "HTTP/1.1 \(status) OK",

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -28,6 +28,13 @@ final class RunnerTests: XCTestCase {
     static let objcException = 1
   }
 
+  /// String codes the daemon keys behavior on. `RUNNER_BUSY` and `RUNNER_WEDGED` come from the busy
+  /// gate; `MAIN_THREAD_TIMEOUT` is emitted by the transport when a command trips the execution
+  /// watchdog, so the daemon can tell "the main thread is now occupied" from a generic failure.
+  enum RunnerWireErrorCode {
+    static let mainThreadTimeout = "MAIN_THREAD_TIMEOUT"
+  }
+
   static let springboardBundleId = "com.apple.springboard"
   // SpringBoard hosts blocking system modals on iOS/visionOS; tvOS (PineBoard/HeadBoard)
   // and macOS have no such host, so there is nothing to probe there.