[worker] Build selective Android log capture for staging

Co-authored-by: Claude Opus 5.5 <[email protected]>

.changeset/bump-apple-utils-capability-sync.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': patch
+---
+
+Bump `@expo/apple-utils` to `2.3.0` to fix iOS capability sync when App Store Connect rejects enabling, disabling or changing a capability.

.changeset/capability-sync-keeps-linked-identifiers.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': patch
+---
+
+Keep already linked App Groups, Merchant IDs and iCloud containers when capability sync links another identifier.

.changeset/config.json

@@ -19,7 +19,9 @@
       "@expo/downloader",
       "@expo/turtle-spawn",
       "@expo/template-file",
-      "create-eas-build-function"
+      "create-eas-build-function",
+      "@expo/vm-tools",
+      "@expo/simulator-launcher"
     ]
   ],
   "linked": [],

.changeset/experimentation-client.md

@@ -1,5 +0,0 @@
----
-'eas-cli': minor
----
-
-Add experimentation client.

.changeset/free-tier-limit-agent-guidance-experiment.md

@@ -1,5 +0,0 @@
----
-'eas-cli': minor
----
-
-Add a Free plan build limit guidance experiment for coding agents to `eas build`.

.changeset/mask-worker-stdout.md

@@ -0,0 +1,5 @@
+---
+'@expo/worker': patch
+---
+
+Mask secrets in every record the worker process writes to its stdout: the build log records and the worker's own records.

.changeset/quiet-android-logs.md

@@ -0,0 +1,6 @@
+---
+'@expo/build-tools': patch
+'eas-cli': patch
+---
+
+Record and upload Android emulator process output as a simulator session artifact by default. Add explicit source selection and a simulator CLI flag to opt in to recording and uploading device-wide logcat. Unselected sources are not recorded by simulator sessions.

.changeset/serve-sim-pr-4544.md

@@ -1,5 +0,0 @@
----
-'@expo/build-tools': minor
----
-
-Let serve-sim boot, install and launch agent-device iOS sessions with the local-egress guard.

.changeset/worker-ssh-drop-host.md

@@ -0,0 +1,5 @@
+---
+'@expo/build-tools': patch
+---
+
+Stop sending the SSH host when registering an SSH session.

.github/workflows/build-and-deploy-worker.yml

@@ -1,208 +1,39 @@
-name: build-and-deploy-worker
-# Assumes main branch always specifies an environment (staging/production).
-# If environment is empty: PR testing build (no upload, no deploy)
-# If environment is set: Build (unless cached on main), upload, and deploy
-
+name: Build Android worker for manual testing
 on:
   workflow_dispatch:
     inputs:
       environment:
-        description: '"staging", "production" or empty'
-        type: string
+        description: Build a Linux artifact for manual staging testing; does not deploy
+        type: choice
+        options:
+          - staging
+        default: staging
         required: true
-  workflow_call:
-    inputs:
-      environment:
-        description: '"staging", "production" or empty'
-        type: string
-        required: true
-
+permissions:
+  contents: read
 jobs:
-  build-and-deploy:
+  build-android-staging-test:
+    if: inputs.environment == 'staging'
     runs-on: ubuntu-latest
-    permissions:
-      id-token: write
+    timeout-minutes: 25
     steps:
       - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
-
       - uses: ./.github/actions/setup-mise
-
-      - name: Install eas-cli
-        run: npm install --global eas-cli@latest
-
-      - uses: ./.github/internal-actions/setup-gcloud
-
-      - name: Check if worker already exists
-        id: check_worker_exists
-        # Check if tarballs for this SHA already exist
-        # If they do, we can skip building regardless of branch
-        if: inputs.environment != ''
-        run: |
-          for platform in android ios; do
-            GCP_TARBALL="worker-$platform-sha1-$GITHUB_SHA.tar.gz"
-
-            if ! gsutil stat "gs://eas-build-worker-tarballs/$GCP_TARBALL"; then
-              echo "worker_exists=false" >> "$GITHUB_OUTPUT"
-              exit 0
-            fi
-          done
-
-          echo "worker_exists=true" >> "$GITHUB_OUTPUT"
-
-      - name: Start EAS Workflow to build worker tarballs
-        id: eas_workflow
-        # Build if: PR testing (no env), or deploying but tarballs don't exist
-        if: inputs.environment == '' || steps.check_worker_exists.outputs.worker_exists == 'false'
-        working-directory: packages/worker
+      - run: yarn install --immutable
+      - name: Package Linux worker from this checkout
         env:
-          EXPO_TOKEN: ${{ secrets.EXPO_DEV_EXPO_GITHUB_ROBOT_ACCESS_TOKEN }}
+          OUTPUT_DIR: ${{ runner.temp }}/android-worker-staging-test
         run: |
           set -euo pipefail
-
-          # Only upload artifacts from EAS if GHA will upload them to GCS
-          # This avoids unnecessary artifact uploads for PR builds
-          SHOULD_UPLOAD_ARTIFACT="${{ inputs.environment != '' && steps.check_worker_exists.outputs.worker_exists == 'false' }}"
-
-          # Run workflow and capture output (includes run ID)
-          WORKFLOW_OUTPUT=$(eas workflow:run build-worker.yml \
-            --ref ${{ github.sha }} \
-            --input upload_artifact=$SHOULD_UPLOAD_ARTIFACT \
-            --non-interactive \
-            --no-wait \
-            --json)
-
-          WORKFLOW_RUN_ID=$(echo "$WORKFLOW_OUTPUT" | jq -r '.id')
-          if [ -z "$WORKFLOW_RUN_ID" ] || [ "$WORKFLOW_RUN_ID" = "null" ]; then
-            echo "Error: Could not determine workflow run ID"
-            echo "Workflow output:"
-            echo "$WORKFLOW_OUTPUT" | jq .
-            exit 1
-          fi
-
-          echo "workflow_run_id=$WORKFLOW_RUN_ID" >> "$GITHUB_OUTPUT"
-
-      - name: Wait for EAS workflow and capture artifacts
-        id: eas_artifacts
-        if: inputs.environment == '' || steps.check_worker_exists.outputs.worker_exists == 'false'
-        working-directory: packages/worker
-        env:
-          EXPO_TOKEN: ${{ secrets.EXPO_DEV_EXPO_GITHUB_ROBOT_ACCESS_TOKEN }}
-        run: |
-          set -euo pipefail
-
-          WORKFLOW_RUN_ID="${{ steps.eas_workflow.outputs.workflow_run_id }}"
-          if [ -z "$WORKFLOW_RUN_ID" ]; then
-            echo "Error: Missing workflow run ID"
-            exit 1
-          fi
-
-          SHOULD_UPLOAD_ARTIFACT="${{ inputs.environment != '' && steps.check_worker_exists.outputs.worker_exists == 'false' }}"
-
-          while true; do
-            VIEW_OUTPUT=$(eas workflow:view "$WORKFLOW_RUN_ID" \
-              --non-interactive \
-              --json)
-            STATUS=$(echo "$VIEW_OUTPUT" | jq -r '.status')
-
-            case "$STATUS" in
-              SUCCESS)
-                break
-                ;;
-              FAILURE)
-                echo "EAS workflow failed."
-                echo "$VIEW_OUTPUT" | jq .
-                exit 1
-                ;;
-              CANCELED)
-                echo "EAS workflow canceled."
-                echo "$VIEW_OUTPUT" | jq .
-                exit 1
-                ;;
-              ACTION_REQUIRED)
-                echo "EAS workflow requires action."
-                echo "$VIEW_OUTPUT" | jq .
-                exit 1
-                ;;
-              NEW|IN_PROGRESS)
-                sleep 7
-                ;;
-              *)
-                echo "Unexpected workflow status: $STATUS"
-                echo "$VIEW_OUTPUT" | jq .
-                exit 1
-                ;;
-            esac
-          done
-
-          # Skip artifact extraction if we didn't request uploads
-          if [ "$SHOULD_UPLOAD_ARTIFACT" == "false" ]; then
-            echo "Skipping artifact download - upload was disabled for this run"
-            exit 0
-          fi
-
-          # Extract artifact download URLs from workflow output
-          # Artifacts are in jobs[].artifacts[] for custom jobs
-          DOWNLOAD_IOS_URL=$(echo "$VIEW_OUTPUT" | jq -r '
-            .jobs[]
-            | .artifacts[]?
-            | select(.name == "worker-ios-tarball")
-            | .downloadUrl
-          ' | head -1)
-
-          DOWNLOAD_ANDROID_URL=$(echo "$VIEW_OUTPUT" | jq -r '
-            .jobs[]
-            | .artifacts[]?
-            | select(.name == "worker-android-tarball")
-            | .downloadUrl
-          ' | head -1)
-
-          if [ -z "$DOWNLOAD_IOS_URL" ] || [ "$DOWNLOAD_IOS_URL" = "null" ]; then
-            echo "Error: Could not find iOS artifact download URL"
-            echo "$VIEW_OUTPUT" | jq .
-            exit 1
-          fi
-
-          if [ -z "$DOWNLOAD_ANDROID_URL" ] || [ "$DOWNLOAD_ANDROID_URL" = "null" ]; then
-            echo "Error: Could not find Android artifact download URL"
-            echo "$VIEW_OUTPUT" | jq .
-            exit 1
-          fi
-
-          # Mask the download URLs
-          echo "::add-mask::$DOWNLOAD_IOS_URL"
-          echo "::add-mask::$DOWNLOAD_ANDROID_URL"
-          echo "download_ios_url=$DOWNLOAD_IOS_URL" >> "$GITHUB_OUTPUT"
-          echo "download_android_url=$DOWNLOAD_ANDROID_URL" >> "$GITHUB_OUTPUT"
-
-      - name: Cancel EAS workflow on GitHub cancellation
-        if: cancelled()
-        working-directory: packages/worker
-        env:
-          EXPO_TOKEN: ${{ secrets.EXPO_DEV_EXPO_GITHUB_ROBOT_ACCESS_TOKEN }}
-        run: |
-          set -euo pipefail
-
-          WORKFLOW_RUN_ID="${{ steps.eas_workflow.outputs.workflow_run_id }}"
-          if [ -n "$WORKFLOW_RUN_ID" ]; then
-            eas workflow:cancel "$WORKFLOW_RUN_ID" --non-interactive
-          fi
-
-      - name: Upload worker tarballs to GCP
-        # Upload when deploying if we built something new
-        # Don't upload PR builds (no environment) or when using cached tarballs
-        if: inputs.environment != '' && steps.check_worker_exists.outputs.worker_exists == 'false'
-        run: |
-          IOS_GCP_TARBALL="worker-ios-sha1-$GITHUB_SHA.tar.gz"
-          ANDROID_GCP_TARBALL="worker-android-sha1-$GITHUB_SHA.tar.gz"
-          curl -L "${{ steps.eas_artifacts.outputs.download_ios_url }}" | gsutil cp - "gs://eas-build-worker-tarballs/$IOS_GCP_TARBALL"
-          curl -L "${{ steps.eas_artifacts.outputs.download_android_url }}" | gsutil cp - "gs://eas-build-worker-tarballs/$ANDROID_GCP_TARBALL"
-
-      - name: Promote worker to ${{ inputs.environment }}
-        if: inputs.environment != ''
-        run: |
-          for platform in android ios; do
-            GCP_TARBALL="worker-$platform-sha1-$GITHUB_SHA.tar.gz"
-            WORKER_STAGING_TARBALL="worker-$platform-${{ inputs.environment }}.tar.gz"
-
-            gsutil cp "gs://eas-build-worker-tarballs/$GCP_TARBALL" "gs://eas-build-worker-tarballs/$WORKER_STAGING_TARBALL"
-          done
+          mkdir -p "$OUTPUT_DIR"
+          bash packages/worker/package.sh "$OUTPUT_DIR/worker-android.tar.gz" android
+          tar -xOf "$OUTPUT_DIR/worker-android.tar.gz" ./packages/build-tools/dist/steps/utils/androidEmulatorLogs.js > "$OUTPUT_DIR/androidEmulatorLogs.js"
+          cd "$OUTPUT_DIR"
+          sha256sum worker-android.tar.gz androidEmulatorLogs.js > SHA256SUMS
+          printf '%s\n' "$GITHUB_SHA" > build-revision.txt
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: android-worker-staging-test
+          path: ${{ runner.temp }}/android-worker-staging-test/
+          retention-days: 7
+          if-no-files-found: error

.github/workflows/test-graphql.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
   schedule:
     - cron: '0 8 * * *' # 8:00 AM UTC time every day
 

CHANGELOG.md

@@ -2,6 +2,148 @@
 
 This is the log of notable changes to EAS CLI and related packages.
 
+## [27.2.0](https://github.com/expo/eas-cli/releases/tag/v27.2.0) - 2026-10-29
+
+### 🎉 New features
+
+- [build-tools] Use single-device previews when the session already has a valid device ID. ([#4733](https://github.com/expo/eas-cli/pull/4733) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add an experiment that suggests Expo Update to coding agents after a build when the Free plan account is within 5 builds of the platform limit. ([#4758](https://github.com/expo/eas-cli/pull/4758) by [@williamgrosset](https://github.com/williamgrosset))
+- [eas-cli] Add `eas observe:traces` to list request trace spans (or a summary of span names and counts), `eas observe:trace` to display one trace as a span tree, and span rows in the `eas observe:session` timeline. ([#4772](https://github.com/expo/eas-cli/pull/4772) by [@kadikraman](https://github.com/kadikraman))
+- [simulator-launcher] Accept a comma-separated list of warm Simulators in `EXPO_SIMULATOR_DEVICE`; the first is the default. One serve-sim serves every listed device on one port. After the default device is ready, warmup preinstalls the latest stable Expo Go from one download and tries to disable apsd on the other devices, until a job claims one. A claim can select any listed device and reports its preinstalled Expo Go. ([#4764](https://github.com/expo/eas-cli/pull/4764) by [@gwdp](https://github.com/gwdp))
+- [simulator-launcher] Add `@expo/simulator-launcher`, which warms an iOS Simulator at VM boot and hands it to one EAS job (`start`, `claim`, `prepare-tools`, `stop`). ([#4722](https://github.com/expo/eas-cli/pull/4722) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Show a one-time Expo Simulators hint after a successful build. ([#4768](https://github.com/expo/eas-cli/pull/4768) by [@FiberJW](https://github.com/FiberJW))
+- [vm-tools] Add a macOS startup script loader that runs `/usr/local/share/vm-tools/startup.sh` once per VM boot. ([#4725](https://github.com/expo/eas-cli/pull/4725) by [@gwdp](https://github.com/gwdp))
+
+### 🐛 Bug fixes
+
+- [build-tools] Explain missing background task identifiers reported by App Store Connect. ([#3465](https://github.com/expo/eas-cli/pull/3465) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Explain App Store Connect NOT_AUTHORIZED responses in the shared API client. ([#3462](https://github.com/expo/eas-cli/pull/3462) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Explain App Store Connect UNEXPECTED_ERROR responses in the shared API client. ([#3467](https://github.com/expo/eas-cli/pull/3467) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Explain missing app icons reported by App Store Connect, including codes 90022 and 90023, while preserving Apple’s validation details. ([#3466](https://github.com/expo/eas-cli/pull/3466) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] List failed Google Play commit attempts in order, including network failures, when the outcome is uncertain. ([#4660](https://github.com/expo/eas-cli/pull/4660) by [@sjchmiela](https://github.com/sjchmiela))
+- [worker] Run package-manager version queries in parallel during worker preparation. ([#4710](https://github.com/expo/eas-cli/pull/4710) by [@gwdp](https://github.com/gwdp))
+- [worker] Start the Xcode version check in the background during worker tool preparation. Apply the Xcode 26.0 upload workaround when the query finishes, without delaying job startup. ([#4707](https://github.com/expo/eas-cli/pull/4707) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Fix a five-minute cleanup delay when a device session is canceled during startup and its screen recorder fails before connecting. ([#4761](https://github.com/expo/eas-cli/pull/4761) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Remove the Free plan build limit guidance experiment for coding agents from `eas build`. ([#4757](https://github.com/expo/eas-cli/pull/4757) by [@williamgrosset](https://github.com/williamgrosset))
+- [worker] Allow jobs to skip installing the CocoaPods cache proxy with EAS_BUILD_DISABLE_COCOAPODS_CACHE_PLUGIN=1. ([#4709](https://github.com/expo/eas-cli/pull/4709) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Handle TURN requests for a stopped device session without reporting a warning. ([#4762](https://github.com/expo/eas-cli/pull/4762) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Preserve indented and incomplete Xcode compiler errors in formatted build logs, including the final diagnostic when logging stops. ([#4365](https://github.com/expo/eas-cli/pull/4365) by [@sjchmiela](https://github.com/sjchmiela))
+
+### 🧹 Chores
+
+- [simulator-launcher] Add the state, request command and service helpers for the warm Simulator launcher. The package stays private until #4722 adds its CLI entry point. ([#4766](https://github.com/expo/eas-cli/pull/4766) by [@gwdp](https://github.com/gwdp))
+
+## [27.1.0](https://github.com/expo/eas-cli/releases/tag/v27.1.0) - 2026-10-28
+
+### 🎉 New features
+
+- [eas-cli] Display queued workflow runs: `workflow:run --wait` and `workflow:status` show a run waiting for its concurrency group and the run blocking it, and `workflow:cancel` includes queued runs in its selection list. ([#4258](https://github.com/expo/eas-cli/pull/4258) by [@hSATAC](https://github.com/hSATAC))
+- [eas-cli] Upload the workflow files that `uses` jobs reference, including nested ones, when running a local workflow file with `eas workflow:run`. ([#4769](https://github.com/expo/eas-cli/pull/4769) by [@sswrk](https://github.com/sswrk))
+
+### 🐛 Bug fixes
+
+- [build-tools] Explain App Store Connect error 90189 as a duplicate build number. ([#3461](https://github.com/expo/eas-cli/pull/3461) by [@sjchmiela](https://github.com/sjchmiela))
+- [eas-cli] Fail the command when EAS CLI cannot pull environment variables from EAS servers, instead of continuing without them. ([#4774](https://github.com/expo/eas-cli/pull/4774) by [@wschurman](https://github.com/wschurman))
+- [eas-cli] Format the generated root changelog before committing a release. ([#4773](https://github.com/expo/eas-cli/pull/4773) by [@gwdp](https://github.com/gwdp))
+- [build-tools][worker] Put the `NPM_TOKEN` registry credential in the builder's npm user config on EAS Build (`~/.npmrc`, or the file `NPM_CONFIG_USERCONFIG` names), where pnpm 10.34.2+ and 11.5.3+ still expand `${NPM_TOKEN}` (they ignore it in a project-level `.npmrc`). Explain what to change when the project's pnpm version needs a newer Node.js than the build runs, including when eas.json sets `node` or `pnpm`. ([#4729](https://github.com/expo/eas-cli/pull/4729) by [@hSATAC](https://github.com/hSATAC))
+- [build-tools] Install `@expo/repack-app` for the `eas/repack` step with npm in a sandbox that sees only `PATH` and its own `HOME`, so the build machine's npm and Yarn configuration cannot break the install, fetch it through the EAS npm cache when the job uses one, and show the installer output in the build log. The step no longer looks the version up separately before installing. When the npm cache fails, the install retries against the public registry like the project install does; the `eas/run_agent` agent CLI install shares the same helper and gains the same retry. ([#4728](https://github.com/expo/eas-cli/pull/4728) by [@hSATAC](https://github.com/hSATAC))
+- [eas-cli] Honor the `--non-interactive` flag in `workflow:cancel`; it was parsed but never applied, so automation could hang on the interactive picker. ([#4258](https://github.com/expo/eas-cli/pull/4258) by [@hSATAC](https://github.com/hSATAC))
+- [eas-cli] Stop reporting a finish time for workflow runs that have not finished: `workflow:runs` reports `finishedAt` only for runs in a final status. ([#4258](https://github.com/expo/eas-cli/pull/4258) by [@hSATAC](https://github.com/hSATAC))
+
+## [27.0.0](https://github.com/expo/eas-cli/releases/tag/v27.0.0) - 2026-10-27
+
+### 🛠 Breaking changes
+
+- [eas-cli] Write the reason a command failed to stderr, next to the `command failed.` line, instead of to stdout. A program that reads the reason from stdout must read stderr instead. ([#4592](https://github.com/expo/eas-cli/pull/4592) by [@vonovak](https://github.com/vonovak))
+
+### 🎉 New features
+
+- [eas-cli] Send the `permissions.account.role` from the build profile to request a role for the build's `EXPO_TOKEN`. ([#4734](https://github.com/expo/eas-cli/pull/4734) by [@wschurman](https://github.com/wschurman))
+- [eas-cli] Add `simulator:logs` to read and follow logs from an iOS simulator session and download saved logs after it stops. ([#4545](https://github.com/expo/eas-cli/pull/4545) by [@gwdp](https://github.com/gwdp))
+
+### 🐛 Bug fixes
+
+- [build-tools] Keep the launched app open when an Appium iOS session starts. ([#4699](https://github.com/expo/eas-cli/pull/4699) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Run Appium through the prepared Full Disk Access helper when available on macOS. ([#4622](https://github.com/expo/eas-cli/pull/4622) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Show permission guidance, including `permissions.account.role` in eas.json, when a build request fails with an authorization error. ([#4760](https://github.com/expo/eas-cli/pull/4760) by [@wschurman](https://github.com/wschurman))
+- [eas-cli] Print the notice about eas-cli in project dependencies only when stderr is a terminal, so programs that read stderr get the command's error. ([#4591](https://github.com/expo/eas-cli/pull/4591) by [@vonovak](https://github.com/vonovak))
+- [eas-cli] Show account roles and credential permission limits in `eas login` when you are already logged in. ([#4759](https://github.com/expo/eas-cli/pull/4759) by [@wschurman](https://github.com/wschurman))
+- [build-tools] Identify the build or application archive when a download fails, and explain when the archive is no longer available. ([#4703](https://github.com/expo/eas-cli/pull/4703) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Run apsd setup in the background without delaying iOS app launch or preview readiness. ([#4706](https://github.com/expo/eas-cli/pull/4706) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Fix simulator control action help routing and show help when a flag is incomplete. ([#4681](https://github.com/expo/eas-cli/pull/4681) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Require explicit `host:` simulator-host upload paths and report missing local files. ([#4683](https://github.com/expo/eas-cli/pull/4683) by [@gwdp](https://github.com/gwdp))
+
+  Missing local absolute paths now require the `host:` prefix. Actions that require upload IDs accept local files and reject host paths with an explanation.
+
+- [build-tools] Handle a device session stopped during startup as normal cleanup instead of reporting a startup error. ([#4716](https://github.com/expo/eas-cli/pull/4716) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Support idle timeouts for iOS web-preview-only sessions, resetting the timer when preview input arrives. ([#4731](https://github.com/expo/eas-cli/pull/4731) by [@gwdp](https://github.com/gwdp))
+
+### 🧹 Chores
+
+- [eas-cli] Run the GraphQL schema and generated code check on pull requests to any base branch, including stacked pull requests. ([#4763](https://github.com/expo/eas-cli/pull/4763) by [@wschurman](https://github.com/wschurman))
+
+## [26.0.0](https://github.com/expo/eas-cli/releases/tag/v26.0.0) - 2026-10-26
+
+### 🛠 Breaking changes
+
+- [eas-build-job][build-tools] Remove legacy artifact type exports and route workflow uploads through workflow storage without file-type categories. Preserve workflow uploads and Maestro reports. ([#4719](https://github.com/expo/eas-cli/pull/4719) by [@sjchmiela](https://github.com/sjchmiela))
+
+### 🎉 New features
+
+- [eas-build-job][build-tools] Export `validateAndroidLaunchOptions` and `quoteAndroidShellCommand` from `@expo/eas-build-job`, so Android launch arguments can be checked for NUL characters and length before a simulator session starts, and check them before the emulator boots in agent-device sessions. ([#4696](https://github.com/expo/eas-cli/pull/4696) by [@brentvatne](https://github.com/brentvatne))
+- [eas-json] Add `permissions.account.role` to build profiles to request a role for the build's `EXPO_TOKEN`. ([#4732](https://github.com/expo/eas-cli/pull/4732) by [@wschurman](https://github.com/wschurman))
+- [build-tools] Stop sandboxes after an optional maximum duration measured from readiness. ([#4702](https://github.com/expo/eas-cli/pull/4702) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Unify signed URL uploading to a single implementation and use it everywhere. ([#4712](https://github.com/expo/eas-cli/pull/4712) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+### 🐛 Bug fixes
+
+- [eas-cli] Regenerate graphql code. ([#4692](https://github.com/expo/eas-cli/pull/4692) by [@wschurman](https://github.com/wschurman))
+- [build-tools] Default Android emulators to 4 GiB of RAM to reduce ADB disconnects during large transfers. Retain the 2 GiB default for API 34 and below outside interactive device sessions, and preserve explicit emulator configuration overrides. ([#4727](https://github.com/expo/eas-cli/pull/4727) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Retry transient failures when reporting that a device run session has started. ([#4680](https://github.com/expo/eas-cli/pull/4680) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Retry the build lookup and the archive download of `eas/download_build` on transient failures, and name the failure cause in the build log. ([#4690](https://github.com/expo/eas-cli/pull/4690) by [@hSATAC](https://github.com/hSATAC))
+- [eas-cli] Read the app config fewer times in `eas build` and other project commands. An iOS build now runs `expo config` 2 times instead of 6. ([`78ba760`](https://github.com/expo/eas-cli/commit/78ba76001b67c9971236af1a1d02e46c2f82d24a) by [@vonovak](https://github.com/vonovak))
+- [build-tools][steps] Stop printing workflow hook parsing messages in build logs: native builds showed them under an "Unknown build phase" group, and custom builds warned about unknown hook keys and hooks on steps that never run. ([#4717](https://github.com/expo/eas-cli/pull/4717) by [@hSATAC](https://github.com/hSATAC))
+- [worker] Retry Node.js installation without the internal Node.js cache mirror when the first attempt fails, while preserving other configured mirrors. ([#3452](https://github.com/expo/eas-cli/pull/3452) by [@sjchmiela](https://github.com/sjchmiela))
+- [eas-cli] Share one GraphQL client between the project ID check and the command, so commands send one fewer app query. ([#4646](https://github.com/expo/eas-cli/pull/4646) by [@vonovak](https://github.com/vonovak))
+- [eas-cli] Show why a simulator session failed in `eas simulator:get`, and add an `errors` array to its `--json` output. For an unknown error, `simulator:start` and `simulator:get` now show the failed step's error from the session logs. ([#4694](https://github.com/expo/eas-cli/pull/4694) by [@brentvatne](https://github.com/brentvatne))
+- [eas-cli] Show why a simulator session failed in `eas simulator:start`, such as an unknown `--device` name, instead of only the session status. ([#4693](https://github.com/expo/eas-cli/pull/4693) by [@brentvatne](https://github.com/brentvatne))
+- [worker] Mask secrets in every field of uploaded job log records, such as logged errors, not only in log messages. ([#4698](https://github.com/expo/eas-cli/pull/4698) by [@brentvatne](https://github.com/brentvatne))
+
+### 🧹 Chores
+
+- [eas-cli] Make command descriptions in `eas --help` consistently lowercase without trailing periods. ([#4385](https://github.com/expo/eas-cli/pull/4385) by [@brentvatne](https://github.com/brentvatne))
+- [eas-cli][build-tools] Bump Node.js to 22.23.4 to fix the CVEs in the [October 2026 Node.js security releases](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases). ([#4714](https://github.com/expo/eas-cli/pull/4714) by [@ramonclaudio](https://github.com/ramonclaudio))
+
+## [25.3.0](https://github.com/expo/eas-cli/releases/tag/v25.3.0) - 2026-10-20
+
+### 🎉 New features
+
+- [eas-cli] Add a Free plan build limit checkout experiment to `eas build` that offers to open the Starter plan checkout. ([#4633](https://github.com/expo/eas-cli/pull/4633) by [@williamgrosset](https://github.com/williamgrosset))
+- [build-tools] Let serve-sim boot, install and launch Argent iOS sessions. ([#4602](https://github.com/expo/eas-cli/pull/4602) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Let serve-sim boot, install and launch Appium iOS sessions. ([#4603](https://github.com/expo/eas-cli/pull/4603) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Upload the screen recording session manifest as a JSON artifact alongside each video. ([#4689](https://github.com/expo/eas-cli/pull/4689) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add a `--system-image` flag to `eas simulator:start` to select the Android SDK system image for the emulator. ([#4500](https://github.com/expo/eas-cli/pull/4500) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+
+### 🐛 Bug fixes
+
+- [build-tools] Quote Android launch arguments and URLs for the device shell in simulator sessions, so values with spaces or shell characters reach `am start` as one argument; pass raw values and remove any shell quoting added as a workaround. ([#4695](https://github.com/expo/eas-cli/pull/4695) by [@brentvatne](https://github.com/brentvatne))
+- [build-tools] Wait up to five minutes for Google Play to finish processing an uploaded bundle before giving up on the edit commit. ([#4700](https://github.com/expo/eas-cli/pull/4700) by [@hSATAC](https://github.com/hSATAC))
+- [build-tools] Reset the device run session idle timer on iOS Simulator preview input. ([#4691](https://github.com/expo/eas-cli/pull/4691) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Forward captured Simulator traffic through the local egress proxy. ([#4598](https://github.com/expo/eas-cli/pull/4598) by [@gwdp](https://github.com/gwdp))
+
+## [25.2.0](https://github.com/expo/eas-cli/releases/tag/v25.2.0) - 2026-10-17
+
+### 🎉 New features
+
+- [eas-cli] Add experimentation client. ([#4558](https://github.com/expo/eas-cli/pull/4558) by [@williamgrosset](https://github.com/williamgrosset))
+- [eas-cli] Add a Free plan build limit guidance experiment for coding agents to `eas build`. ([#4631](https://github.com/expo/eas-cli/pull/4631) by [@williamgrosset](https://github.com/williamgrosset))
+- [build-tools] Let serve-sim boot, install and launch agent-device iOS sessions with the local-egress guard. ([#4544](https://github.com/expo/eas-cli/pull/4544) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add `eas simulator:control` to run serve-sim actions, with file upload and download, on a remote iOS simulator session. ([#4641](https://github.com/expo/eas-cli/pull/4641) by [@gwdp](https://github.com/gwdp))
+
+### 🧹 Chores
+
+- [eas-cli] Prepare authenticated simulator action transport and file transfers. ([#4642](https://github.com/expo/eas-cli/pull/4642) by [@gwdp](https://github.com/gwdp))
+
 ## [25.1.1](https://github.com/expo/eas-cli/releases/tag/v25.1.1) - 2026-10-16
 
 ### 🐛 Bug fixes

CLAUDE.md

@@ -215,7 +215,7 @@ if: ${{ steps.previous_step.outputs.success == 'true' && env.ENVIRONMENT == 'pro
 Artifacts tracked as `ArtifactToUpload`:
 
 - Managed artifacts (APK, IPA, AAB) with specific handling
-- Generic artifacts for any file
+- Workflow artifacts for any file
 - Upload via `ctx.uploadArtifact()` or `upload-artifact` step
 
 ## Package Interdependencies

cli-versions.json

@@ -1,4 +1,4 @@
 {
-  "STAGING": "25.1.1",
-  "PRODUCTION": "25.1.1"
+  "STAGING": "27.2.0",
+  "PRODUCTION": "27.2.0"
 }

lerna.json

@@ -1,5 +1,5 @@
 {
   "npmClient": "yarn",
-  "version": "25.1.1",
+  "version": "27.2.0",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }

mise.toml

@@ -6,4 +6,4 @@ MISE_NODE_COREPACK = "true"
 actionlint = "1.7.12"
 gcloud = "570.0.0"
 jq = "1.8.1"
-node = "22.23.3"
+node = "22.23.4"

packages/build-tools/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @expo/build-tools
 
+## 27.2.0
+
+### Minor Changes
+
+- Use single-device previews when the session already has a valid device ID. ([#4733](https://github.com/expo/eas-cli/pull/4733) by [@gwdp](https://github.com/gwdp))
+
+### Patch Changes
+
+- Explain missing background task identifiers reported by App Store Connect. ([#3465](https://github.com/expo/eas-cli/pull/3465) by [@sjchmiela](https://github.com/sjchmiela))
+- Explain App Store Connect NOT_AUTHORIZED responses in the shared API client. ([#3462](https://github.com/expo/eas-cli/pull/3462) by [@sjchmiela](https://github.com/sjchmiela))
+- Explain App Store Connect UNEXPECTED_ERROR responses in the shared API client. ([#3467](https://github.com/expo/eas-cli/pull/3467) by [@sjchmiela](https://github.com/sjchmiela))
+- Explain missing app icons reported by App Store Connect, including codes 90022 and 90023, while preserving Apple’s validation details. ([#3466](https://github.com/expo/eas-cli/pull/3466) by [@sjchmiela](https://github.com/sjchmiela))
+- List failed Google Play commit attempts in order, including network failures, when the outcome is uncertain. ([#4660](https://github.com/expo/eas-cli/pull/4660) by [@sjchmiela](https://github.com/sjchmiela))
+- Fix a five-minute cleanup delay when a device session is canceled during startup and its screen recorder fails before connecting. ([#4761](https://github.com/expo/eas-cli/pull/4761) by [@gwdp](https://github.com/gwdp))
+- Handle TURN requests for a stopped device session without reporting a warning. ([#4762](https://github.com/expo/eas-cli/pull/4762) by [@gwdp](https://github.com/gwdp))
+- Preserve indented and incomplete Xcode compiler errors in formatted build logs, including the final diagnostic when logging stops. ([#4365](https://github.com/expo/eas-cli/pull/4365) by [@sjchmiela](https://github.com/sjchmiela))
+
+## 27.1.0
+
+### Patch Changes
+
+- Explain App Store Connect error 90189 as a duplicate build number. ([#3461](https://github.com/expo/eas-cli/pull/3461) by [@sjchmiela](https://github.com/sjchmiela))
+- Put the `NPM_TOKEN` registry credential in the builder's npm user config on EAS Build (`~/.npmrc`, or the file `NPM_CONFIG_USERCONFIG` names), where pnpm 10.34.2+ and 11.5.3+ still expand `${NPM_TOKEN}` (they ignore it in a project-level `.npmrc`). Explain what to change when the project's pnpm version needs a newer Node.js than the build runs, including when eas.json sets `node` or `pnpm`. ([#4729](https://github.com/expo/eas-cli/pull/4729) by [@hSATAC](https://github.com/hSATAC))
+- Install `@expo/repack-app` for the `eas/repack` step with npm in a sandbox that sees only `PATH` and its own `HOME`, so the build machine's npm and Yarn configuration cannot break the install, fetch it through the EAS npm cache when the job uses one, and show the installer output in the build log. The step no longer looks the version up separately before installing. When the npm cache fails, the install retries against the public registry like the project install does; the `eas/run_agent` agent CLI install shares the same helper and gains the same retry. ([#4728](https://github.com/expo/eas-cli/pull/4728) by [@hSATAC](https://github.com/hSATAC))
+
+## 27.0.0
+
+### Patch Changes
+
+- Keep the launched app open when an Appium iOS session starts. ([#4699](https://github.com/expo/eas-cli/pull/4699) by [@gwdp](https://github.com/gwdp))
+- Run Appium through the prepared Full Disk Access helper when available on macOS. ([#4622](https://github.com/expo/eas-cli/pull/4622) by [@gwdp](https://github.com/gwdp))
+- Identify the build or application archive when a download fails, and explain when the archive is no longer available. ([#4703](https://github.com/expo/eas-cli/pull/4703) by [@gwdp](https://github.com/gwdp))
+- Run apsd setup in the background without delaying iOS app launch or preview readiness. ([#4706](https://github.com/expo/eas-cli/pull/4706) by [@gwdp](https://github.com/gwdp))
+- Handle a device session stopped during startup as normal cleanup instead of reporting a startup error. ([#4716](https://github.com/expo/eas-cli/pull/4716) by [@gwdp](https://github.com/gwdp))
+- Support idle timeouts for iOS web-preview-only sessions, resetting the timer when preview input arrives. ([#4731](https://github.com/expo/eas-cli/pull/4731) by [@gwdp](https://github.com/gwdp))
+
+## 26.0.0
+
+### Major Changes
+
+- Remove legacy artifact type exports and route workflow uploads through workflow storage without file-type categories. Preserve workflow uploads and Maestro reports. ([#4719](https://github.com/expo/eas-cli/pull/4719) by [@sjchmiela](https://github.com/sjchmiela))
+
+### Minor Changes
+
+- Stop sandboxes after an optional maximum duration measured from readiness. ([#4702](https://github.com/expo/eas-cli/pull/4702) by [@sjchmiela](https://github.com/sjchmiela))
+- Unify signed URL uploading to a single implementation and use it everywhere. ([#4712](https://github.com/expo/eas-cli/pull/4712) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+### Patch Changes
+
+- Default Android emulators to 4 GiB of RAM to reduce ADB disconnects during large transfers. Retain the 2 GiB default for API 34 and below outside interactive device sessions, and preserve explicit emulator configuration overrides. ([#4727](https://github.com/expo/eas-cli/pull/4727) by [@sjchmiela](https://github.com/sjchmiela))
+- Export `validateAndroidLaunchOptions` and `quoteAndroidShellCommand` from `@expo/eas-build-job`, so Android launch arguments can be checked for NUL characters and length before a simulator session starts, and check them before the emulator boots in agent-device sessions. ([#4696](https://github.com/expo/eas-cli/pull/4696) by [@brentvatne](https://github.com/brentvatne))
+- Retry transient failures when reporting that a device run session has started. ([#4680](https://github.com/expo/eas-cli/pull/4680) by [@gwdp](https://github.com/gwdp))
+- Retry the build lookup and the archive download of `eas/download_build` on transient failures, and name the failure cause in the build log. ([#4690](https://github.com/expo/eas-cli/pull/4690) by [@hSATAC](https://github.com/hSATAC))
+- Stop printing workflow hook parsing messages in build logs: native builds showed them under an "Unknown build phase" group, and custom builds warned about unknown hook keys and hooks on steps that never run. ([#4717](https://github.com/expo/eas-cli/pull/4717) by [@hSATAC](https://github.com/hSATAC))
+
+## 25.3.0
+
+### Minor Changes
+
+- Let serve-sim boot, install and launch Argent iOS sessions. ([#4602](https://github.com/expo/eas-cli/pull/4602) by [@gwdp](https://github.com/gwdp))
+- Let serve-sim boot, install and launch Appium iOS sessions. ([#4603](https://github.com/expo/eas-cli/pull/4603) by [@gwdp](https://github.com/gwdp))
+- Upload the screen recording session manifest as a JSON artifact alongside each video. ([#4689](https://github.com/expo/eas-cli/pull/4689) by [@gwdp](https://github.com/gwdp))
+
+### Patch Changes
+
+- Quote Android launch arguments and URLs for the device shell in simulator sessions, so values with spaces or shell characters reach `am start` as one argument; pass raw values and remove any shell quoting added as a workaround. ([#4695](https://github.com/expo/eas-cli/pull/4695) by [@brentvatne](https://github.com/brentvatne))
+- Wait up to five minutes for Google Play to finish processing an uploaded bundle before giving up on the edit commit. ([#4700](https://github.com/expo/eas-cli/pull/4700) by [@hSATAC](https://github.com/hSATAC))
+- Reset the device run session idle timer on iOS Simulator preview input. ([#4691](https://github.com/expo/eas-cli/pull/4691) by [@gwdp](https://github.com/gwdp))
+- Forward captured Simulator traffic through the local egress proxy. ([#4598](https://github.com/expo/eas-cli/pull/4598) by [@gwdp](https://github.com/gwdp))
+
+## 25.2.0
+
+### Minor Changes
+
+- Let serve-sim boot, install and launch agent-device iOS sessions with the local-egress guard. ([#4544](https://github.com/expo/eas-cli/pull/4544) by [@gwdp](https://github.com/gwdp))
+
 ## 25.1.1
 
 ### Patch Changes

packages/build-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/build-tools",
-  "version": "25.1.1",
+  "version": "27.2.0",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",
@@ -26,7 +26,7 @@
     "build:egress-guard": "resources/egress-guard/build.sh",
     "test:egress-guard": "resources/egress-guard/tests/run-policy-tests.sh && resources/egress-guard/tests/run-guard-tests.sh",
     "typecheck": "tsc",
-    "generate-appium-commands": "mise exec [email protected]2.0 -- node scripts/generate-appium-commands.js",
+    "generate-appium-commands": "mise exec [email protected]3.4 -- node scripts/generate-appium-commands.js",
     "prepack": "rimraf dist \"*.tsbuildinfo\" && yarn gql && tsc -p tsconfig.build.json",
     "jest-unit": "jest --config jest/unit-config.ts",
     "jest-integration": "jest --config jest/integration-config.ts",
@@ -42,18 +42,18 @@
   "dependencies": {
     "@expo/config": "55.0.10",
     "@expo/config-plugins": "55.0.7",
-    "@expo/downloader": "25.1.1",
-    "@expo/eas-build-job": "25.1.1",
+    "@expo/downloader": "27.2.0",
+    "@expo/eas-build-job": "27.2.0",
     "@expo/env": "^0.4.0",
-    "@expo/logger": "25.1.1",
+    "@expo/logger": "27.2.0",
     "@expo/package-manager": "1.9.10",
     "@expo/plist": "^0.3.5",
     "@expo/results": "^1.0.0",
     "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "25.1.1",
-    "@expo/template-file": "25.1.1",
-    "@expo/turtle-spawn": "25.1.1",
-    "@expo/xcpretty": "^4.3.1",
+    "@expo/steps": "27.2.0",
+    "@expo/template-file": "27.2.0",
+    "@expo/turtle-spawn": "27.2.0",
+    "@expo/xcpretty": "^4.4.7",
     "@ngrok/ngrok": "1.7.0",
     "@sentry/node": "7.77.0",
     "@urql/core": "^6.0.1",

packages/build-tools/src/buildErrors/__tests__/detectError.test.ts

@@ -125,6 +125,31 @@ describe(resolveBuildPhaseErrorAsync, () => {
     expect(err.trackingCode).toBeUndefined();
   });
 
+  it('explains that the pnpm version needs a newer Node.js than the build runs', async () => {
+    const fakeError = new Error();
+    const err = await resolveBuildPhaseErrorAsync(
+      fakeError,
+      [
+        'Running "pnpm install --frozen-lockfile" in /home/expo/workingdir/build directory',
+        'warn: This version of pnpm requires at least Node.js v22.13',
+        'warn: The current version of Node.js is v20.19.4',
+        'warn: Visit https://r.pnpm.io/comp to see the list of past pnpm versions with respective Node.js version support.',
+        'Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:sqlite',
+      ],
+      {
+        job: { platform: Platform.ANDROID } as Job,
+        phase: BuildPhase.INSTALL_DEPENDENCIES,
+        env: {},
+      },
+      '/fake/path'
+    );
+    expect(err.errorCode).toBe('EAS_BUILD_PNPM_UNSUPPORTED_NODE_VERSION_ERROR');
+    expect(err.message).toBe(
+      'This build uses a pnpm version that requires Node.js 22.13.0 or newer, but runs Node.js 20.19.4. You can fix it by either:\n- setting "node" to "22.13.0" or a newer version in the build profile in eas.json\n- using a pnpm version that supports Node.js 20.19.4: change "packageManager" in package.json if your project sets it, and set "pnpm" in the build profile in eas.json'
+    );
+    expect(err.docsUrl).toBe('https://docs.expo.dev/eas/json/');
+  });
+
   it('detects xcode line error', async () => {
     vol.fromJSON({
       '/path/to/xcodelogs.log': originalFs.readFileSync(

packages/build-tools/src/buildErrors/pnpmUnsupportedNodeVersionError.ts

@@ -0,0 +1,33 @@
+import { errors } from '@expo/eas-build-job';
+import nullthrows from 'nullthrows';
+import semver from 'semver';
+
+import { ErrorHandler } from './errors.types';
+
+// example log: "warn: This version of pnpm requires at least Node.js v22.13" followed by "warn: The current version of Node.js is v20.19.4"
+const PNPM_UNSUPPORTED_NODE_VERSION_REGEXP =
+  /This version of pnpm requires at least Node\.js v([\d.]+)\n.*The current version of Node\.js is v([\d.]+)/;
+
+function createPnpmUnsupportedNodeVersionError(matchResult: RegExpMatchArray): errors.UserError {
+  const [, requiredNodeVersion, currentNodeVersion] = matchResult;
+  const minimumNodeVersion = nullthrows(semver.coerce(requiredNodeVersion)).version;
+  return new errors.UserError(
+    'EAS_BUILD_PNPM_UNSUPPORTED_NODE_VERSION_ERROR',
+    `This build uses a pnpm version that requires Node.js ${minimumNodeVersion} or newer, but runs Node.js ${currentNodeVersion}. You can fix it by either:
+- setting "node" to "${minimumNodeVersion}" or a newer version in the build profile in eas.json
+- using a pnpm version that supports Node.js ${currentNodeVersion}: change "packageManager" in package.json if your project sets it, and set "pnpm" in the build profile in eas.json`,
+    { docsUrl: 'https://docs.expo.dev/eas/json/' }
+  );
+}
+
+export const pnpmUnsupportedNodeVersionErrorHandler: ErrorHandler<errors.UserError> = {
+  regexp: PNPM_UNSUPPORTED_NODE_VERSION_REGEXP,
+  createError: createPnpmUnsupportedNodeVersionError,
+};
+
+export function detectPnpmUnsupportedNodeVersionError(
+  output: string
+): errors.UserError | undefined {
+  const match = output.match(PNPM_UNSUPPORTED_NODE_VERSION_REGEXP);
+  return match ? createPnpmUnsupportedNodeVersionError(match) : undefined;
+}

packages/build-tools/src/buildErrors/userErrorHandlers.ts

@@ -1,6 +1,7 @@
 import { BuildMode, BuildPhase, Platform, Workflow, errors } from '@expo/eas-build-job';
 
 import { ErrorHandler, XCODE_BUILD_PHASE } from './errors.types';
+import { pnpmUnsupportedNodeVersionErrorHandler } from './pnpmUnsupportedNodeVersionError';
 
 import UserError = errors.UserError;
 
@@ -211,6 +212,7 @@ You are seeing this error because either:
       return undefined;
     },
   },
+  pnpmUnsupportedNodeVersionErrorHandler,
   {
     platform: Platform.IOS,
     phase: XCODE_BUILD_PHASE,

packages/build-tools/src/common/__tests__/jobHooks.test.ts

@@ -16,11 +16,13 @@ function createCtx(
   { workingdir = '/tmp/wd' }: { workingdir?: string } = {}
 ): {
   ctx: BuildContext<Ios.Job>;
+  info: jest.Mock;
   warn: jest.Mock;
 } {
+  const info = jest.fn();
   const warn = jest.fn();
   const logger = {
-    info: jest.fn(),
+    info,
     debug: jest.fn(),
     error: jest.fn(),
     warn,
@@ -36,7 +38,7 @@ function createCtx(
       workingdir,
     }
   );
-  return { ctx, warn };
+  return { ctx, info, warn };
 }
 
 // Project checkout lives at <workingdir>/build (job projectRootDirectory is '.').
@@ -79,22 +81,31 @@ describe(parseJobHooksAsync, () => {
     });
   });
 
-  it('treats an unknown hook key as inert and warns', async () => {
-    const { ctx, warn } = createCtx({
+  it('writes nothing to the build log while parsing', async () => {
+    const { ctx, info, warn } = createCtx({
+      before_install_node_modules: [{ run: 'echo hi' }],
+      before_submit: [{ run: 'echo hi' }],
+      before_bogus: [{ run: 'echo hi' }],
+    });
+    await parseJobHooksAsync(ctx, INSTALL);
+    expect(info).not.toHaveBeenCalled();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('treats an unknown hook key as inert', async () => {
+    const { ctx } = createCtx({
       before_bogus: [{ run: 'echo hi' }],
     });
     const parsed = await parseJobHooksAsync(ctx, INSTALL);
     expect(parsed!.hookEntriesByKey).toEqual({});
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('unknown hook key "before_bogus"'));
   });
 
-  it('shape-checks a registered-but-unwrapped key, then warns and skips it', async () => {
-    const { ctx, warn } = createCtx({
+  it('shape-checks a registered-but-unwrapped key, then skips it', async () => {
+    const { ctx } = createCtx({
       before_submit: [{ run: 'echo hi' }],
     });
     const parsed = await parseJobHooksAsync(ctx, INSTALL);
     expect(parsed!.hookEntriesByKey.before_submit).toBeUndefined();
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('hooks.before_submit'));
   });
 
   it('shape-validates a registered-but-unwrapped key even though it is skipped', async () => {
@@ -192,10 +203,9 @@ describe(parseJobHooksAsync, () => {
   });
 
   it('never loads a composite function referenced under a registered-but-unwrapped key', async () => {
-    const { ctx, warn } = createCtx({ before_submit: [{ uses: './.eas/functions/missing' }] });
+    const { ctx } = createCtx({ before_submit: [{ uses: './.eas/functions/missing' }] });
     const parsed = await parseJobHooksAsync(ctx, INSTALL);
     expect(parsed!.hookEntriesByKey).toEqual({});
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('hooks.before_submit'));
   });
 
   it('wraps a cross-key duplicate step id in the aggregate error', async () => {

packages/build-tools/src/common/__tests__/projectSources.test.ts

@@ -12,6 +12,7 @@ import spawn from '@expo/turtle-spawn';
 import { randomBytes, randomUUID } from 'crypto';
 import { vol } from 'memfs';
 import fetch, { Response } from 'node-fetch';
+import { Readable } from 'stream';
 import { setTimeout } from 'timers/promises';
 
 import { createMockLogger } from '../../__tests__/utils/logger';
@@ -390,7 +391,13 @@ describe('projectSources', () => {
       ctx.graphqlClient.mutation = mockGraphqlMutation as any;
 
       const fetchMock = jest.mocked(fetch);
-      fetchMock.mockImplementation(async () => ({ ok: true }) as Response);
+      let uploadedBody = '';
+      fetchMock.mockImplementation(async (_url, request) => {
+        for await (const chunk of request!.body as Readable) {
+          uploadedBody += chunk;
+        }
+        return { ok: true } as Response;
+      });
       fetchMock.mockResolvedValueOnce({
         ok: true,
         json: async () => ({ data: ctx.job.projectArchive }),
@@ -414,10 +421,14 @@ describe('projectSources', () => {
         'https://storage.example.com/upload',
         expect.objectContaining({
           method: 'PUT',
-          headers: { 'x-custom-header': 'value' },
-          body: '{"archiveContent":["project/README.md","project/package.json"]}',
+          headers: {
+            'x-custom-header': 'value',
+            'content-length': '63',
+            'content-type': 'text/plain;charset=UTF-8',
+          },
         })
       );
+      expect(uploadedBody).toBe('{"archiveContent":["project/README.md","project/package.json"]}');
 
       // Verify build metadata was updated
       expect(mockGraphqlMutation).toHaveBeenNthCalledWith(

packages/build-tools/src/common/__tests__/xcpretty.test.ts

@@ -3,6 +3,7 @@ import { EventEmitter } from 'events';
 import spawnAsync from '@expo/spawn-async';
 import { ExpoRunFormatter } from '@expo/xcpretty';
 import fg from 'fast-glob';
+import { vol } from 'memfs';
 
 import { createMockLogger } from '../../__tests__/utils/logger';
 import { Sentry } from '../../sentry';
@@ -59,6 +60,47 @@ describe(XcodeBuildLogger, () => {
     expect(Sentry.capture).not.toHaveBeenCalled();
   });
 
+  it('flushes the final incomplete compiler error when the log reader is interrupted', async () => {
+    const { ExpoRunFormatter: RealFormatter } =
+      jest.requireActual<typeof import('@expo/xcpretty')>('@expo/xcpretty');
+    jest.mocked(ExpoRunFormatter.create).mockImplementation(RealFormatter.create);
+
+    let rejectReader!: (error: Error) => void;
+    const spawnPromise = Object.assign(
+      new Promise<never>((_resolve, reject) => {
+        rejectReader = reject;
+      }),
+      {
+        child: {
+          stdout,
+          kill: () =>
+            rejectReader(Object.assign(new Error('tail interrupted'), { signal: 'SIGINT' })),
+        },
+      }
+    );
+    jest.mocked(spawnAsync).mockReturnValue(spawnPromise as any);
+    const diagnostics =
+      '/project/First.swift:12:3: error: first compiler error\n' +
+      '    /project/Last.swift:20:4: error: final compiler error\n';
+    vol.fromJSON({ '/logs/build.log': diagnostics });
+    const logger = createMockLogger();
+    const buildLogger = new XcodeBuildLogger(logger, '/project');
+    await buildLogger.watchLogFiles('/logs');
+    stdout.emit('data', diagnostics);
+
+    await buildLogger.flush();
+
+    const output = jest
+      .mocked(logger.info)
+      .mock.calls.map(([line]) => String(line))
+      .join('\n');
+    expect(output).toContain('first compiler error');
+    expect(output).toContain('final compiler error');
+    expect(output).toContain('Last.swift:20:4');
+    expect(output).toContain('2 error(s)');
+    expect(output.match(/final compiler error/g)).toHaveLength(1);
+  });
+
   it('falls back to raw logs when the formatter throws', async () => {
     const logger = createMockLogger();
     await startWatchingAsync(logger);

packages/build-tools/src/common/hookableBuildPhase.ts

@@ -44,9 +44,8 @@ export async function runHookableBuildPhaseAsync<TJob extends BuildJob, T>({
     if (hooks) {
       try {
         await runHookEntriesAsync({ ctx, hooks, timing: 'after', anchor, anchorFailed: true });
-      } catch (hookError) {
-        // The phase error wins; still surface the after-hook failure in the log.
-        ctx.logger.error({ err: hookError }, `after_${anchor} hook failed`);
+      } catch {
+        // The phase error wins.
       }
     }
     throw phaseError;

packages/build-tools/src/common/installDependencies.ts

@@ -4,6 +4,7 @@ import path from 'path';
 
 import { BuildContext } from '../context';
 import { Sentry } from '../sentry';
+import { NpmCacheRegistryInstallError, isNpmCacheInstallFailure } from '../utils/npmCacheRegistry';
 import { PackageManager, findPackagerRootDir } from '../utils/packageManager';
 import { isUsingModernYarnVersion } from '../utils/project';
 
@@ -196,10 +197,6 @@ export function resolvePackagerDir(ctx: BuildContext<Job>): string {
   return packagerRunDir;
 }
 
-function isNpmCacheInstallFailure(err: unknown, npmCacheUrl: string): boolean {
-  return getErrorOutput(err).includes(npmCacheUrl);
-}
-
 function isNpmCacheRegistryErrorLine(line: string, npmCacheUrl: string): boolean {
   return (
     line.includes(npmCacheUrl) &&
@@ -207,24 +204,9 @@ function isNpmCacheRegistryErrorLine(line: string, npmCacheUrl: string): boolean
   );
 }
 
-function getErrorOutput(err: unknown): string {
-  if (!(err instanceof Error)) {
-    return '';
-  }
-  const { stdout, stderr } = err as Error & { stdout?: string; stderr?: string };
-  return [stdout, stderr].filter(Boolean).join('\n');
-}
-
 class NpmCacheRegistryNonFatalError extends SystemError {
   override name = 'NpmCacheRegistryNonFatalError';
   constructor() {
     super('Non-fatal npm cache registry error during dependency install');
   }
 }
-
-class NpmCacheRegistryInstallError extends SystemError {
-  override name = 'NpmCacheRegistryInstallError';
-  constructor(cause: unknown) {
-    super('Failed to install dependencies using npm cache registry', { cause });
-  }
-}

packages/build-tools/src/common/jobHooks.ts

@@ -53,19 +53,17 @@ export async function parseJobHooksAsync<TJob extends BuildJob>(
   const globalContext = new BuildStepGlobalContext(customBuildContext, false);
   // Hook steps run in the checked-out project directory, not the pre-checkout
   // target directory the global context defaults to.
-  globalContext.markAsCheckedOut(ctx.logger);
+  globalContext.markAsCheckedOut();
 
   const externalFunctions = getEasFunctions(customBuildContext);
   const externalFunctionGroups = getEasFunctionGroups(customBuildContext);
 
   // Shape-validate every REGISTERED key, reachable or not (steps-world parity:
-  // a malformed `before_submit` fails a steps build, so it fails here too), and
-  // warn on keys this build won't run. An unknown key is inert — a key newer
-  // than this worker must be ignored, never fail the job.
+  // a malformed `before_submit` fails a steps build, so it fails here too). An
+  // unknown key is inert — a key newer than this worker must be ignored, never
+  // fail the job.
   for (const [key, steps] of Object.entries(hooks)) {
-    const parsed = parseHookKey(key);
-    if (parsed === null) {
-      ctx.logger.warn(`Ignoring unknown hook key "${key}".`);
+    if (parseHookKey(key) === null) {
       continue;
     }
     if (Array.isArray(steps) && steps.length === 0) {
@@ -81,15 +79,6 @@ export async function parseJobHooksAsync<TJob extends BuildJob>(
         { cause: err }
       );
     }
-    // Registered but not wrapped by this build: shape-checked above, then
-    // skipped. Function existence is deliberately NOT checked (that happens only
-    // during construction) — an unknown `uses:` under an unwrapped key warns
-    // rather than failing the build.
-    if (!wrappedAnchors.includes(parsed.anchorId)) {
-      ctx.logger.warn(
-        `Ignoring "hooks.${key}": this build does not run the "${parsed.anchorId}" step.`
-      );
-    }
   }
 
   // Construct entries for the wrapped anchors in EXECUTION order (per anchor,

packages/build-tools/src/common/projectSources.ts

@@ -5,13 +5,13 @@ import { asyncResult } from '@expo/results';
 import spawn from '@expo/turtle-spawn';
 import fs from 'fs/promises';
 import { graphql } from 'gql.tada';
-import fetch from 'node-fetch';
 import nullthrows from 'nullthrows';
 import path from 'path';
 import { z } from 'zod';
 
 import { shallowCloneRepositoryAsync } from './git';
 import { BuildContext } from '../context';
+import { uploadContentWithSignedUrl } from '../storage/uploadWithSignedUrl';
 import { turtleFetch } from '../utils/turtleFetch';
 
 export async function prepareProjectSourcesAsync<TJob extends Job>(
@@ -208,10 +208,9 @@ async function uploadProjectMetadataAsync(
     headers: Record<string, string>;
   };
 
-  await fetch(uploadSession.url, {
-    method: 'PUT',
-    body: JSON.stringify({ archiveContent: sortedFiles }),
-    headers: uploadSession.headers,
+  await uploadContentWithSignedUrl({
+    signedUrl: uploadSession,
+    content: JSON.stringify({ archiveContent: sortedFiles }),
   });
 
   const updateMetadataResult = await ctx.graphqlClient

packages/build-tools/src/common/setup.ts

@@ -71,7 +71,12 @@ export async function setupAsync<TJob extends BuildJob>(
       }
     );
 
-    await setUpNpmrcAsync(ctx, ctx.logger);
+    await setUpNpmrcAsync({
+      projectTargetDirectory: ctx.buildDirectory,
+      workingDirectory: ctx.getReactNativeProjectDirectory(),
+      env: ctx.env,
+      logger: ctx.logger,
+    });
     if (ctx.job.platform === Platform.IOS && ctx.env.EAS_BUILD_RUNNER === 'eas-build') {
       await deleteXcodeEnvLocalIfExistsAsync(ctx as BuildContext<Ios.Job>);
     }

packages/build-tools/src/common/xcpretty.ts

@@ -80,9 +80,12 @@ export class XcodeBuildLogger {
           this.logger.info(data.toString());
         }
       });
-      await this.logReaderPromise;
-
-      this.logger.info(formatter.getBuildSummary());
+      try {
+        await this.logReaderPromise;
+      } finally {
+        // flush() interrupts tail, but the formatter may still hold a final compiler diagnostic.
+        this.logger.info(formatter.getBuildSummary());
+      }
     } catch (err: any) {
       if (!this.flushing) {
         this.loggerError = err;

packages/build-tools/src/context.ts

@@ -4,13 +4,11 @@ import {
   BuildPhaseResult,
   Env,
   EnvironmentSecretType,
-  GenericArtifactType,
   Job,
   LogMarker,
   ManagedArtifactType,
   Metadata,
   errors,
-  isGenericArtifact,
 } from '@expo/eas-build-job';
 import { BuildTrigger } from '@expo/eas-build-job/dist/common';
 import { bunyan } from '@expo/logger';
@@ -42,7 +40,7 @@ export type ArtifactToUpload =
       paths: string[];
     }
   | {
-      type: GenericArtifactType;
+      type: null;
       name: string;
       paths: string[];
       metadata?: Record<string, unknown>;
@@ -241,7 +239,7 @@ export class BuildContext<TJob extends Job = Job> {
     logger: bunyan;
   }): Promise<{ artifactId: string | null }> {
     const result = await this._uploadArtifact({ artifact, logger });
-    if (result.filename && !isGenericArtifact(artifact)) {
+    if (result.filename && artifact.type !== null) {
       this.artifacts[artifact.type] = result.filename;
     }
     return { artifactId: result.artifactId ?? null };

packages/build-tools/src/index.ts

@@ -3,8 +3,16 @@ import HttpLogStream from './logging/HttpLogStream';
 import RemoteLoggerStream from './logging/RemoteLoggerStream';
 
 export { Builders, HttpLogStream, RemoteLoggerStream };
-export { uploadWithSignedUrl } from './storage/uploadWithSignedUrl';
-export type { SignedUrl, UploadWithSignedUrlParams } from './storage/uploadWithSignedUrl';
+export {
+  SignedUrlUploadApiError,
+  SignedUrlUploadNetworkError,
+  uploadWithSignedUrl,
+} from './storage/uploadWithSignedUrl';
+export type {
+  SignedUrl,
+  UploadWithSignedUrlOptions,
+  UploadWithSignedUrlParams,
+} from './storage/uploadWithSignedUrl';
 export { downloadCacheAsync } from './steps/functions/restoreCache';
 export { uploadCacheAsync } from './steps/functions/saveCache';
 
@@ -26,6 +34,7 @@ export { formatSecondsForLog } from './utils/formatDuration';
 export { findAndUploadXcodeBuildLogsAsync } from './ios/xcodeBuildLogs';
 
 export { Hook, runHookIfPresent } from './utils/hooks';
+export { detectPnpmUnsupportedNodeVersionError } from './buildErrors/pnpmUnsupportedNodeVersionError';
 
 export { parseGradleProfile, formatGradleProfileReport } from './android/gradleProfile';
 export type { GradleProfileTask } from './android/gradleProfile';

packages/build-tools/src/logging/RemoteLoggerStream.ts

@@ -56,10 +56,10 @@ class RemoteLoggerStream extends Writable {
     return null;
   }
 
-  public async init(): Promise<string> {
+  public async init(): Promise<void> {
     this.fileHandle = await fs.open(this.temporaryLogsPath, 'w+', 0o660);
     this.flushInterval = setInterval(() => this.flush(), this.options.uploadIntervalMs);
-    return (await this.flush(true)) as string;
+    await this.flush(true);
   }
 
   public async cleanUp(): Promise<void> {
@@ -121,17 +121,18 @@ class RemoteLoggerStream extends Writable {
     }
   }
 
-  private async flush(force = false): Promise<string | void> {
+  private async flush(force = false): Promise<void> {
     if (force || this.hasChangesToUpload) {
       if (this.uploadingPromise) {
         await this.uploadingPromise;
-        return await this.flush(force);
+        await this.flush(force);
+        return;
       }
-      return await this.flushInternal();
+      await this.flushInternal();
     }
   }
 
-  private async flushInternal(): Promise<string | void> {
+  private async flushInternal(): Promise<void> {
     await this.safeWriteToFile();
 
     let resolveFn: PromiseResolveFn;
@@ -139,21 +140,17 @@ class RemoteLoggerStream extends Writable {
     this.uploadingPromise = new Promise(res => {
       resolveFn = res;
     });
-    return await this.upload()
-      .then(result => {
-        return result;
-      })
+    await this.upload()
       .catch(err => {
         this.logger.error({ err }, 'Failed to upload logs file');
       })
-      .then(result => {
+      .then(() => {
         this.uploadingPromise = undefined;
         resolveFn();
-        return result;
       });
   }
 
-  private async upload(): Promise<string | void> {
+  private async upload(): Promise<void> {
     if (!this.uploadMethod) {
       return;
     }
@@ -165,7 +162,7 @@ class RemoteLoggerStream extends Writable {
       );
     };
 
-    return await uploadWithSignedUrl({
+    await uploadWithSignedUrl({
       signedUrl: this.uploadMethod.signedUrl,
       srcGeneratorAsync,
     });

packages/build-tools/src/steps/easFunctions.ts

@@ -61,6 +61,7 @@ import { createStartWebPreviewRemoteSessionBuildFunction } from './functions/sta
 import { createStartServeSimMetricsBuildFunction } from './functions/startServeSimMetrics';
 import { createStartServeSimLogsBuildFunction } from './functions/startServeSimLogs';
 import { createCollectServeSimLogsBuildFunction } from './functions/collectServeSimLogs';
+import { createCollectAndroidEmulatorLogsBuildFunction } from './functions/collectAndroidEmulatorLogs';
 import { createStartSandboxBuildFunction } from './functions/startSandbox';
 import { createCollectServeSimMetricsBuildFunction } from './functions/collectServeSimMetrics';
 import { createUploadArtifactBuildFunction } from './functions/uploadArtifact';
@@ -124,6 +125,7 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
     createStartServeSimMetricsBuildFunction(),
     createStartServeSimLogsBuildFunction(),
     createCollectServeSimLogsBuildFunction(ctx),
+    createCollectAndroidEmulatorLogsBuildFunction(ctx),
     createStartSandboxBuildFunction(ctx),
     createRunAgentBuildFunction(ctx),
     createCollectServeSimMetricsBuildFunction(ctx),

packages/build-tools/src/steps/functions/__tests__/checkout.test.ts

@@ -48,7 +48,10 @@ describe(createCheckoutBuildFunction, () => {
   });
 
   it('moves project sources to the target directory when no inputs are given', async () => {
+    const logger = createMockLogger();
+    jest.mocked(logger.child).mockReturnValue(logger);
     const { globalCtx, executeAsync } = createCheckoutStep({
+      logger,
       projectArchive: GIT_PROJECT_ARCHIVE,
     });
 
@@ -56,6 +59,9 @@ describe(createCheckoutBuildFunction, () => {
 
     expect(await vol.promises.readFile(`${projectTargetDirectory}/app.json`, 'utf8')).toBe('{}');
     expect(globalCtx.wasCheckedOut()).toBe(true);
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('Changing default working directory to')
+    );
     expect(fetchAndCheckoutRefAsync).not.toHaveBeenCalled();
   });
 
@@ -96,14 +102,11 @@ describe(createCheckoutBuildFunction, () => {
   });
 
   it('rejects the ref input when the project is already checked out', async () => {
-    const logger = createMockLogger();
-    jest.mocked(logger.child).mockReturnValue(logger);
     const { globalCtx, executeAsync } = createCheckoutStep({
-      logger,
       projectArchive: GIT_PROJECT_ARCHIVE,
       callInputs: { ref: 'feature/add-icon' },
     });
-    globalCtx.markAsCheckedOut(logger);
+    globalCtx.markAsCheckedOut();
 
     await expect(executeAsync()).rejects.toMatchObject({
       errorCode: 'EAS_CHECKOUT_REF_AFTER_CHECKOUT',

packages/build-tools/src/steps/functions/__tests__/collectAndroidEmulatorLogs.test.ts

@@ -0,0 +1,76 @@
+import { BuildRuntimePlatform } from '@expo/steps';
+
+import {
+  createCustomBuildContextMock,
+  createGlobalContextMock,
+} from '../../../__tests__/utils/context';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { Sentry } from '../../../sentry';
+import { collectAndroidEmulatorLogsAsync } from '../../utils/androidEmulatorLogs';
+import { createCollectAndroidEmulatorLogsBuildFunction } from '../collectAndroidEmulatorLogs';
+
+jest.mock('../../../sentry');
+jest.mock('../../utils/androidEmulatorLogs');
+
+function createStep(callInputs: Record<string, unknown> = {}) {
+  const logger = createMockLogger();
+  const ctx = createCustomBuildContextMock();
+  const global = createGlobalContextMock({ logger });
+  const fn = createCollectAndroidEmulatorLogsBuildFunction(ctx);
+  const step = fn.createBuildStepFromFunctionCall(global, {
+    callInputs,
+    env: { DEVICE_RUN_SESSION_ID: 'session' },
+  });
+  return { ctx, global, logger, fn, step };
+}
+
+it('defaults an existing workflow without inputs to emulator output only', async () => {
+  const { ctx, global, fn, step } = createStep();
+  expect(fn.supportedRuntimePlatforms).toEqual([BuildRuntimePlatform.LINUX]);
+  await step.executeAsync();
+  expect(collectAndroidEmulatorLogsAsync).toHaveBeenCalledWith(ctx, {
+    global,
+    deviceRunSessionId: 'session',
+    logger: expect.anything(),
+    sources: ['emulator-output'],
+  });
+});
+
+it.each([
+  { sources: ['emulator-output', 'device-logcat'] },
+  { sources: ['device-logcat'] },
+  { sources: [] },
+])('passes an explicit selection of $sources through the step input', async ({ sources }) => {
+  const { step } = createStep({ sources });
+  await step.executeAsync();
+  expect(collectAndroidEmulatorLogsAsync).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({ sources })
+  );
+});
+
+it.each([
+  { sources: ['unknown'] },
+  { sources: ['emulator-output', 'unknown'] },
+  { sources: [1] },
+  { sources: { logcat: true } },
+])('does not collect any logs for invalid sources %j', async ({ sources }) => {
+  const { step } = createStep({ sources });
+  const collect = jest.mocked(collectAndroidEmulatorLogsAsync);
+  collect.mockClear();
+  await step.executeAsync();
+  expect(collect).not.toHaveBeenCalled();
+  expect(Sentry.capture).toHaveBeenCalled();
+});
+
+it('reports collection failure without changing the session result', async () => {
+  jest
+    .mocked(collectAndroidEmulatorLogsAsync)
+    .mockRejectedValueOnce(new Error('collection failed'));
+  const { step } = createStep();
+  await expect(step.executeAsync()).resolves.toBeUndefined();
+  expect(Sentry.capture).toHaveBeenCalledWith(
+    'Could not collect Android emulator logs',
+    expect.any(Error)
+  );
+});

packages/build-tools/src/steps/functions/__tests__/deviceSessionHost-orchestration.test.ts

@@ -79,9 +79,11 @@ beforeEach(() => {
     apiUrl: 'https://preview.example.test',
     closeAsync: closePreview,
   });
-  jest
-    .mocked(startDeviceSessionHostAsync)
-    .mockResolvedValue({ openPreviewAsync: openPreview, finishAsync: finishHost });
+  jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
+    openPreviewAsync: openPreview,
+    getLastPreviewActivityAt: jest.fn(),
+    finishAsync: finishHost,
+  });
   jest.mocked(spawnDetached).mockReturnValue({
     pid: undefined,
     getOutput: () => '',
@@ -96,7 +98,7 @@ beforeEach(() => {
   const events = { stopAsync: stopEvents, getLastEventObservedAt: () => undefined };
   jest.mocked(startAgentDeviceEventCollectionAsync).mockResolvedValue(events);
   jest.mocked(startAppiumEventCollectionAsync).mockResolvedValue(events);
-  jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
+  jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue('started');
   jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
 });
 

packages/build-tools/src/steps/functions/__tests__/downloadBuild.test.ts

@@ -11,6 +11,7 @@ import * as tar from 'tar';
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { createMockLogger } from '../../../__tests__/utils/logger';
+import { Datadog } from '../../../datadog';
 import * as files from '../../../utils/files';
 import { createDownloadBuildFunction, downloadBuildAsync } from '../downloadBuild';
 
@@ -30,11 +31,17 @@ const APPLICATION_ARCHIVE_URL = `https://expo.dev/artifacts/eas/${randomUUID()}.
 function createMockGraphqlClient({
   applicationArchiveUrl,
   error,
+  transientError,
 }: {
   applicationArchiveUrl?: string | null;
   error?: Error;
+  transientError?: Error;
 }): Client {
-  const toPromise = jest.fn().mockResolvedValue(
+  const toPromise = jest.fn();
+  if (transientError) {
+    toPromise.mockResolvedValueOnce({ error: transientError, data: undefined });
+  }
+  toPromise.mockResolvedValue(
     error
       ? { error, data: undefined }
       : {
@@ -62,7 +69,7 @@ function createSuccessfulResponse({
   url,
   headers,
 }: {
-  body: Buffer;
+  body: Buffer | Readable;
   url: string;
   headers?: Record<string, string>;
 }): Response {
@@ -72,7 +79,7 @@ function createSuccessfulResponse({
 
   return {
     ok: true,
-    body: Readable.from(body),
+    body: body instanceof Readable ? body : Readable.from(body),
     url,
     headers: {
       get: (name: string): string | null => normalizedHeaders[name.toLowerCase()] ?? null,
@@ -80,6 +87,47 @@ function createSuccessfulResponse({
   } as unknown as Response;
 }
 
+function createUndiciNetworkError(code: string): CombinedError {
+  return new CombinedError({
+    networkError: Object.assign(new TypeError('fetch failed'), {
+      cause: Object.assign(new Error(`read ${code}`), { code }),
+    }),
+  });
+}
+
+const { FetchError: ActualFetchError } = jest.requireActual(
+  'node-fetch'
+) as typeof import('node-fetch');
+
+function createSocketFetchError(url: string, code: string): Error {
+  return new ActualFetchError(`request to ${url} failed, reason: connect ${code}`, 'system', {
+    code,
+  } as any);
+}
+
+function useFakeBackoffTimers(): void {
+  // Streams and fs callbacks need the real nextTick and setImmediate; only the backoff timers are faked.
+  jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'queueMicrotask'] });
+}
+
+const MAX_IO_TURNS_BEFORE_BACKOFF = 1000;
+
+async function waitForBackoffTimerAsync(): Promise<void> {
+  for (let turns = 0; jest.getTimerCount() === 0; turns++) {
+    if (turns === MAX_IO_TURNS_BEFORE_BACKOFF) {
+      throw new Error('No backoff timer was scheduled.');
+    }
+    await new Promise(resolve => setImmediate(resolve));
+  }
+}
+
+async function fireBackoffTimersAsync(count: number): Promise<void> {
+  for (let i = 0; i < count; i++) {
+    await waitForBackoffTimerAsync();
+    await jest.advanceTimersToNextTimerAsync();
+  }
+}
+
 async function createFlatAppTarGzBufferAsync(): Promise<Buffer> {
   const sourceDirectory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'flat-app-source-'));
   const archivePath = path.join(os.tmpdir(), `${randomUUID()}.tar.gz`);
@@ -108,7 +156,65 @@ async function createFlatAppTarGzBufferAsync(): Promise<Buffer> {
   }
 }
 
+afterEach(() => {
+  jest.useRealTimers();
+  jest.restoreAllMocks();
+});
+
 describe('downloadBuild', () => {
+  it.each([404, 410])('identifies the unavailable build on HTTP %s', async status => {
+    const buildId = randomUUID();
+    const { Response: ActualResponse } =
+      jest.requireActual<typeof import('node-fetch')>('node-fetch');
+    jest
+      .mocked(fetch)
+      .mockResolvedValue(new ActualResponse('<Error>NoSuchKey</Error>', { status }));
+
+    await expect(
+      downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        buildId,
+        graphqlClient: createMockGraphqlClient({ applicationArchiveUrl: APPLICATION_ARCHIVE_URL }),
+        robotAccessToken: null,
+        extensions: ['app'],
+      })
+    ).rejects.toMatchObject({
+      errorCode: 'EAS_DOWNLOAD_BUILD_ARCHIVE_UNAVAILABLE',
+      message:
+        `Failed to download the application archive for build ${buildId} (HTTP ${status}). ` +
+        'The archive is unavailable. Check that the archive still exists and try again.',
+    });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([404, 410, 500])(
+    'identifies the application URL without credentials on HTTP %s',
+    async status => {
+      const { Response: ActualResponse } =
+        jest.requireActual<typeof import('node-fetch')>('node-fetch');
+      jest.mocked(fetch).mockResolvedValue(new ActualResponse('download failed', { status }));
+
+      const download = downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        applicationArchiveUrl:
+          'https://user:[email protected]/app.tar.gz?token=secret#fragment',
+        graphqlClient: createMockGraphqlClient({}),
+        robotAccessToken: null,
+        extensions: ['app'],
+      });
+
+      const prefix = `Failed to download the archive at https://example.test/app.tar.gz (HTTP ${status})`;
+      await expect(download).rejects.toThrow(
+        status === 500
+          ? `${prefix}: download failed`
+          : `${prefix}. The archive is unavailable. ` +
+              'Check that the URL is correct and the archive still exists, then try again.'
+      );
+      await expect(download).rejects.not.toThrow(/password|secret|fragment/);
+      expect(fetch).toHaveBeenCalledTimes(1);
+    }
+  );
+
   it('downloads from applicationArchiveUrl returned by GraphQL', async () => {
     const buildId = randomUUID();
     const graphqlClient = createMockGraphqlClient({
@@ -465,13 +571,13 @@ describe('downloadBuild', () => {
     expect(jest.mocked(fetch)).not.toHaveBeenCalled();
   });
 
-  it('throws SystemError when GraphQL request fails with a network error', async () => {
+  it('throws SystemError with the cause code after retrying a failing build lookup', async () => {
+    useFakeBackoffTimers();
     const buildId = randomUUID();
     const graphqlClient = createMockGraphqlClient({
-      error: new CombinedError({
-        networkError: new Error('Network request failed'),
-      }),
+      error: createUndiciNetworkError('ECONNRESET'),
     });
+    const datadogLog = jest.spyOn(Datadog, 'log');
 
     const promise = downloadBuildAsync({
       logger: createLogger({ name: 'test' }),
@@ -480,19 +586,81 @@ describe('downloadBuild', () => {
       robotAccessToken: null,
       extensions: ['app'],
     });
+    const rejection = expect(promise).rejects.toBeInstanceOf(SystemError);
+    await fireBackoffTimersAsync(5);
 
-    await expect(promise).rejects.toBeInstanceOf(SystemError);
+    await rejection;
     await expect(promise).rejects.toMatchObject({
-      message: `Could not fetch build ${buildId}: [Network] Network request failed`,
+      message: `Could not fetch build ${buildId}: [Network] fetch failed (ECONNRESET)`,
+    });
+    expect(graphqlClient.query).toHaveBeenCalledTimes(6);
+    expect(datadogLog).toHaveBeenCalledWith('download_build.build_lookup failed on attempt 6', {
+      event: 'network_retry',
+      operation: 'download_build.build_lookup',
+      outcome: 'failed',
+      attempts: '6',
+      code: 'ECONNRESET',
     });
-
     expect(jest.mocked(fetch)).not.toHaveBeenCalled();
   });
 
-  it('throws SystemError when GraphQL request returns 5xx', async () => {
+  it.each([
+    ['a network error', createUndiciNetworkError('ECONNRESET'), 'ECONNRESET'],
+    [
+      'a transient GraphQL error',
+      new CombinedError({
+        graphQLErrors: [
+          {
+            message: 'Too many requests',
+            extensions: { isTransient: true, errorCode: 'TOO_MANY_REQUESTS' },
+          },
+        ],
+        response: { status: 200 },
+      }),
+      'TOO_MANY_REQUESTS',
+    ],
+  ])('downloads after a build lookup that failed once with %s', async (_, transientError, code) => {
+    useFakeBackoffTimers();
     const buildId = randomUUID();
     const graphqlClient = createMockGraphqlClient({
-      error: Object.assign(new Error('Internal Server Error'), {
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+      transientError,
+    });
+    jest
+      .mocked(fetch)
+      .mockResolvedValue(
+        createSuccessfulResponse({ body: Buffer.from('hello'), url: 'https://cdn.test/app.apk' })
+      );
+
+    const datadogLog = jest.spyOn(Datadog, 'log');
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      buildId,
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['apk'],
+    });
+    await fireBackoffTimersAsync(1);
+
+    const { artifactPath } = await promise;
+    expect(path.basename(artifactPath)).toBe('app.apk');
+    expect(graphqlClient.query).toHaveBeenCalledTimes(2);
+    expect(datadogLog).toHaveBeenCalledWith('download_build.build_lookup recovered on attempt 2', {
+      event: 'network_retry',
+      operation: 'download_build.build_lookup',
+      outcome: 'recovered',
+      attempts: '2',
+      code,
+    });
+  });
+
+  it('throws SystemError when GraphQL request returns 5xx', async () => {
+    useFakeBackoffTimers();
+    const buildId = randomUUID();
+    const graphqlClient = createMockGraphqlClient({
+      error: new CombinedError({
+        graphQLErrors: [{ message: 'Internal Server Error' }],
         response: { status: 500 },
       }),
     });
@@ -504,12 +672,14 @@ describe('downloadBuild', () => {
       robotAccessToken: null,
       extensions: ['app'],
     });
+    const rejection = expect(promise).rejects.toBeInstanceOf(SystemError);
+    await fireBackoffTimersAsync(5);
 
-    await expect(promise).rejects.toBeInstanceOf(SystemError);
+    await rejection;
     await expect(promise).rejects.toMatchObject({
-      message: `Could not fetch build ${buildId}: Internal Server Error`,
+      message: `Could not fetch build ${buildId}: [GraphQL] Internal Server Error`,
     });
-
+    expect(graphqlClient.query).toHaveBeenCalledTimes(6);
     expect(jest.mocked(fetch)).not.toHaveBeenCalled();
   });
 
@@ -534,10 +704,193 @@ describe('downloadBuild', () => {
       errorCode: 'EAS_DOWNLOAD_BUILD_FETCH_FAILED',
       message: `Could not fetch build ${buildId}: [GraphQL] Build not found`,
     });
-
+    expect(graphqlClient.query).toHaveBeenCalledTimes(1);
     expect(jest.mocked(fetch)).not.toHaveBeenCalled();
   });
 
+  it('downloads after an archive request that failed once with a socket error', async () => {
+    useFakeBackoffTimers();
+    const graphqlClient = createMockGraphqlClient({});
+    jest
+      .mocked(fetch)
+      .mockRejectedValueOnce(createSocketFetchError(APPLICATION_ARCHIVE_URL, 'ECONNRESET'))
+      .mockResolvedValueOnce(
+        createSuccessfulResponse({ body: Buffer.from('hello'), url: 'https://cdn.test/app.apk' })
+      );
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['apk'],
+    });
+    await fireBackoffTimersAsync(1);
+
+    const { artifactPath } = await promise;
+    expect(path.basename(artifactPath)).toBe('app.apk');
+    expect(jest.mocked(fetch)).toHaveBeenCalledTimes(2);
+  });
+
+  it('throws SystemError with the cause code after retrying a failing build archive request', async () => {
+    useFakeBackoffTimers();
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+    jest
+      .mocked(fetch)
+      .mockRejectedValue(createSocketFetchError(APPLICATION_ARCHIVE_URL, 'ETIMEDOUT'));
+    const datadogLog = jest.spyOn(Datadog, 'log');
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      buildId: randomUUID(),
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['apk'],
+    });
+    const rejection = expect(promise).rejects.toBeInstanceOf(SystemError);
+    await fireBackoffTimersAsync(5);
+
+    await rejection;
+    await expect(promise).rejects.toMatchObject({
+      message: `Could not download the application archive: request to ${APPLICATION_ARCHIVE_URL} failed, reason: connect ETIMEDOUT`,
+    });
+    expect(jest.mocked(fetch)).toHaveBeenCalledTimes(6);
+    expect(datadogLog).toHaveBeenCalledWith('download_build.archive_download failed on attempt 6', {
+      event: 'network_retry',
+      operation: 'download_build.archive_download',
+      outcome: 'failed',
+      attempts: '6',
+      code: 'ETIMEDOUT',
+    });
+  });
+
+  function createBrokenBody(code: string): Readable {
+    return Readable.from(
+      (async function* () {
+        yield Buffer.from('he');
+        throw Object.assign(new Error(`body failed with ${code}`), { code });
+      })()
+    );
+  }
+
+  it.each(['ERR_STREAM_PREMATURE_CLOSE', 'ECONNRESET'])(
+    'downloads again when the archive body breaks off with %s after the headers arrived',
+    async code => {
+      useFakeBackoffTimers();
+      const graphqlClient = createMockGraphqlClient({});
+      const brokenBody = createBrokenBody(code);
+      jest
+        .mocked(fetch)
+        .mockResolvedValueOnce(
+          createSuccessfulResponse({ body: brokenBody, url: 'https://cdn.test/app.apk' })
+        )
+        .mockResolvedValueOnce(
+          createSuccessfulResponse({ body: Buffer.from('hello'), url: 'https://cdn.test/app.apk' })
+        );
+      const datadogLog = jest.spyOn(Datadog, 'log');
+
+      const promise = downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+        graphqlClient,
+        robotAccessToken: null,
+        extensions: ['apk'],
+      });
+      await fireBackoffTimersAsync(1);
+
+      const { artifactPath } = await promise;
+      expect(await fs.promises.readFile(artifactPath, 'utf-8')).toBe('hello');
+      expect(jest.mocked(fetch)).toHaveBeenCalledTimes(2);
+      expect(datadogLog).toHaveBeenCalledWith(
+        'download_build.archive_download recovered on attempt 2',
+        expect.objectContaining({ outcome: 'recovered', code })
+      );
+    }
+  );
+
+  it('throws SystemError when the build archive body keeps breaking off', async () => {
+    useFakeBackoffTimers();
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+    jest.mocked(fetch).mockImplementation(async () =>
+      createSuccessfulResponse({
+        body: createBrokenBody('ECONNRESET'),
+        url: 'https://cdn.test/app.apk',
+      })
+    );
+    const datadogLog = jest.spyOn(Datadog, 'log');
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      buildId: randomUUID(),
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['apk'],
+    });
+    const rejection = expect(promise).rejects.toBeInstanceOf(SystemError);
+    await fireBackoffTimersAsync(5);
+
+    await rejection;
+    await expect(promise).rejects.toMatchObject({
+      message: 'Could not download the application archive: body failed with ECONNRESET',
+    });
+    expect(jest.mocked(fetch)).toHaveBeenCalledTimes(6);
+    expect(datadogLog).toHaveBeenCalledWith(
+      'download_build.archive_download failed on attempt 6',
+      expect.objectContaining({ outcome: 'failed', code: 'ECONNRESET' })
+    );
+  });
+
+  it('does not start another archive attempt after an abort during the backoff', async () => {
+    useFakeBackoffTimers();
+    const graphqlClient = createMockGraphqlClient({});
+    jest
+      .mocked(fetch)
+      .mockRejectedValueOnce(createSocketFetchError(APPLICATION_ARCHIVE_URL, 'ECONNRESET'));
+    const controller = new AbortController();
+    const reason = new Error('step timed out');
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['apk'],
+      signal: controller.signal,
+    });
+    const rejection = expect(promise).rejects.toBe(reason);
+    await waitForBackoffTimerAsync();
+    controller.abort(reason);
+    await jest.advanceTimersToNextTimerAsync();
+
+    await rejection;
+    expect(jest.mocked(fetch)).toHaveBeenCalledTimes(1);
+  });
+
+  it('rethrows the raw error of a failing user-supplied archive URL after the retries', async () => {
+    useFakeBackoffTimers();
+    const graphqlClient = createMockGraphqlClient({});
+    jest
+      .mocked(fetch)
+      .mockRejectedValue(createSocketFetchError(APPLICATION_ARCHIVE_URL, 'ENOTFOUND'));
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['apk'],
+    });
+    const rejection = expect(promise).rejects.toBeInstanceOf(ActualFetchError);
+    await fireBackoffTimersAsync(5);
+
+    await rejection;
+    expect(jest.mocked(fetch)).toHaveBeenCalledTimes(6);
+  });
+
   it('should throw an error if no matching files are found', async () => {
     const graphqlClient = createMockGraphqlClient({
       applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
@@ -605,6 +958,21 @@ describe('createDownloadBuildFunction', () => {
       };
     }
 
+    function createApplicationResponse(buildId: string): Response {
+      return new ActualResponse(
+        JSON.stringify({
+          data: {
+            build: {
+              id: buildId,
+              gitCommitHash: null,
+              applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+            },
+          },
+        }),
+        { status: 200 }
+      );
+    }
+
     function createStep(ctx: any, callInputs: Record<string, unknown>) {
       return createDownloadBuildFunction(ctx).createBuildStepFromFunctionCall(
         createGlobalContextMock({
@@ -620,18 +988,7 @@ describe('createDownloadBuildFunction', () => {
       const graphqlClient = createMockGraphqlClient({});
       jest.mocked(fetch).mockImplementation(async url => {
         if (url === workerApiUrl) {
-          return new ActualResponse(
-            JSON.stringify({
-              data: {
-                build: {
-                  id: buildId,
-                  gitCommitHash: null,
-                  applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
-                },
-              },
-            }),
-            { status: 200 }
-          );
+          return createApplicationResponse(buildId);
         }
         return {
           ok: false,
@@ -661,6 +1018,33 @@ describe('createDownloadBuildFunction', () => {
       expect(graphqlClient.query).not.toHaveBeenCalled();
     });
 
+    it('retries the worker API lookup after a 5xx response', async () => {
+      useFakeBackoffTimers();
+      const buildId = randomUUID();
+      const graphqlClient = createMockGraphqlClient({});
+      jest
+        .mocked(fetch)
+        .mockResolvedValueOnce(new ActualResponse('Service Unavailable', { status: 503 }))
+        .mockResolvedValueOnce(createApplicationResponse(buildId))
+        .mockResolvedValueOnce(
+          createSuccessfulResponse({ body: Buffer.from('hello'), url: 'https://cdn.test/app.apk' })
+        );
+
+      const execution = createStep(createSessionCtx(graphqlClient), {
+        build_id: buildId,
+        extensions: ['apk'],
+      }).executeAsync();
+      await fireBackoffTimersAsync(1);
+
+      await execution;
+      expect(jest.mocked(fetch)).toHaveBeenCalledTimes(3);
+      expect(jest.mocked(fetch).mock.calls.map(([url]) => url)).toEqual([
+        workerApiUrl,
+        workerApiUrl,
+        APPLICATION_ARCHIVE_URL,
+      ]);
+    });
+
     it('does not call the worker API for an application_archive_url input', async () => {
       const graphqlClient = createMockGraphqlClient({});
       jest.mocked(fetch).mockResolvedValue({

packages/build-tools/src/steps/functions/__tests__/launchApplication.test.ts

@@ -1,5 +1,6 @@
 import { BuildRuntimePlatform } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
+import { spawnSync } from 'node:child_process';
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { createMockLogger } from '../../../__tests__/utils/logger';
@@ -201,6 +202,263 @@ describe(launchApplicationAsync, () => {
     expect(mockedSpawn).not.toHaveBeenCalled();
   });
 
+  it('quotes Android launch arguments and URLs for the device shell', async () => {
+    const logger = createMockLogger();
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'dev.example.app',
+      activityName: 'dev.example.app.MainActivity',
+      launchArgs: ['-d', 'euxy://tempo', '--es', 'probe', 'hello world', '--es', 'quote', "it's"],
+      openUrl: 'exp://example.test/path?a=1&b=2',
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: {},
+      logger,
+    });
+
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      1,
+      'adb',
+      [
+        'shell',
+        'am',
+        'start',
+        '-d',
+        'euxy://tempo',
+        '--es',
+        'probe',
+        "'hello world'",
+        '--es',
+        'quote',
+        "'it'\\''s'",
+        '-n',
+        'dev.example.app/dev.example.app.MainActivity',
+      ],
+      { env: {}, logger }
+    );
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      2,
+      'adb',
+      [
+        'shell',
+        'am',
+        'start',
+        '-a',
+        'android.intent.action.VIEW',
+        '-d',
+        "'exp://example.test/path?a=1&b=2'",
+      ],
+      { env: {}, logger }
+    );
+    expect(logger.info).toHaveBeenNthCalledWith(
+      1,
+      `Launching dev.example.app with arguments ${JSON.stringify(['-d', 'euxy://tempo', '--es', 'probe', 'hello world', '--es', 'quote', "it's"])}.`
+    );
+  });
+
+  it('passes iOS launch arguments with spaces unquoted', async () => {
+    await launchApplicationAsync({
+      applicationIdentifier: 'com.example.app',
+      launchArgs: ['-name', 'hello world'],
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: {},
+      logger: createMockLogger(),
+    });
+
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'xcrun',
+      ['simctl', 'launch', 'booted', 'com.example.app', '-name', 'hello world'],
+      expect.any(Object)
+    );
+  });
+
+  it('round-trips quoted Android arguments through a POSIX shell', async () => {
+    const component = 'dev.example.app/dev.example.app.MainActivity$Inner';
+    const launchArgs = [
+      '--es',
+      'text',
+      'hello world',
+      '--es',
+      'json',
+      '{"a":1,"b":2}',
+      '--es',
+      'shell',
+      '$(printf injected) `printf injected` $HOME ; & | < >',
+      '--es',
+      'glob',
+      '*',
+      '--es',
+      'home',
+      '~',
+      '--esa',
+      'list',
+      'a\\,b,c',
+      '--es',
+      'whitespace',
+      'one\ntwo\tthree',
+      '--es',
+      'unicode',
+      'héllo 🌍',
+      '--es',
+      'empty',
+      '',
+    ];
+    const openUrl = 'exp://example.test/path?a=1&b=2#fragment';
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'dev.example.app',
+      activityName: 'dev.example.app.MainActivity$Inner',
+      launchArgs,
+      openUrl,
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: {},
+      logger: createMockLogger(),
+    });
+
+    // adb joins the words after `shell` with spaces and the device shell parses the result.
+    const parsedCommands = mockedSpawn.mock.calls.map(([, args]) => {
+      const { stdout } = spawnSync(
+        '/bin/sh',
+        ['-c', `am() { printf '%s\\0' "$@"; }; ${(args as string[]).slice(1).join(' ')}`],
+        { encoding: 'utf8' }
+      );
+      return stdout.split('\0').slice(0, -1);
+    });
+    expect(parsedCommands).toEqual([
+      ['start', ...launchArgs, '-n', component],
+      ['start', '-a', 'android.intent.action.VIEW', '-d', openUrl],
+    ]);
+  });
+
+  it.each([[['--es', 'key', '']], [['-e', 'key', '']], [['-d', '']]])(
+    'passes empty Android option values as empty arguments (%j)',
+    async launchArgs => {
+      await launchApplicationAsync({
+        applicationIdentifier: 'com.example.app',
+        activityName: 'com.example.app.MainActivity',
+        launchArgs,
+        runtimePlatform: BuildRuntimePlatform.LINUX,
+        env: {},
+        logger: createMockLogger(),
+      });
+
+      expect(mockedSpawn).toHaveBeenCalledWith(
+        'adb',
+        [
+          'shell',
+          'am',
+          'start',
+          ...launchArgs.map(argument => (argument === '' ? "''" : argument)),
+          '-n',
+          'com.example.app/com.example.app.MainActivity',
+        ],
+        expect.any(Object)
+      );
+    }
+  );
+
+  it('explains an Android launch failure when a launch argument is empty', async () => {
+    const launchError = new Error('adb shell am start exited with non-zero code: 1');
+    mockedSpawn.mockRejectedValueOnce(launchError);
+
+    await expect(
+      launchApplicationAsync({
+        applicationIdentifier: 'com.example.app',
+        activityName: 'com.example.app.MainActivity',
+        launchArgs: ['--ez', 'isTest', 'true', ''],
+        runtimePlatform: BuildRuntimePlatform.LINUX,
+        env: {},
+        logger: createMockLogger(),
+      })
+    ).rejects.toMatchObject({
+      errorCode: 'EAS_LAUNCH_APPLICATION_FAILED',
+      message: expect.stringContaining('empty argument at position 4'),
+      cause: launchError,
+    });
+  });
+
+  it('rethrows an Android launch failure unchanged when no launch argument is empty', async () => {
+    const launchError = new Error('adb shell am start exited with non-zero code: 1');
+    mockedSpawn.mockRejectedValueOnce(launchError);
+
+    await expect(
+      launchApplicationAsync({
+        applicationIdentifier: 'com.example.app',
+        activityName: 'com.example.app.MainActivity',
+        launchArgs: ['--ez', 'isTest', 'true'],
+        runtimePlatform: BuildRuntimePlatform.LINUX,
+        env: {},
+        logger: createMockLogger(),
+      })
+    ).rejects.toBe(launchError);
+  });
+
+  it.each([
+    { launchArgs: ['--es', 'key', 'a\0b'] },
+    { launchArgs: [], openUrl: 'exp://example.test/a\0b' },
+  ])('rejects NUL characters on Android (%j)', async ({ launchArgs, openUrl }) => {
+    await expect(
+      launchApplicationAsync({
+        applicationIdentifier: 'com.example.app',
+        activityName: 'com.example.app.MainActivity',
+        launchArgs,
+        openUrl,
+        runtimePlatform: BuildRuntimePlatform.LINUX,
+        env: {},
+        logger: createMockLogger(),
+      })
+    ).rejects.toMatchObject({ errorCode: 'EAS_LAUNCH_APPLICATION_INVALID_INPUT' });
+    expect(mockedSpawn).not.toHaveBeenCalledWith(
+      'adb',
+      expect.arrayContaining([expect.stringContaining('\0')]),
+      expect.any(Object)
+    );
+  });
+
+  it('accepts an Android launch command of exactly 65,000 bytes', async () => {
+    const fixedLength = 'am start --es key  -n com.example.app/com.example.app.MainActivity'.length;
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'com.example.app',
+      activityName: 'com.example.app.MainActivity',
+      launchArgs: ['--es', 'key', 'a'.repeat(65_000 - fixedLength)],
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: {},
+      logger: createMockLogger(),
+    });
+
+    expect(mockedSpawn).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects an Android URL command of 65,001 bytes', async () => {
+    const fixedLength = 'am start -a android.intent.action.VIEW -d exp://example.test/'.length;
+
+    await expect(
+      launchApplicationAsync({
+        applicationIdentifier: 'com.example.app',
+        activityName: 'com.example.app.MainActivity',
+        openUrl: `exp://example.test/${'a'.repeat(65_001 - fixedLength)}`,
+        runtimePlatform: BuildRuntimePlatform.LINUX,
+        env: {},
+        logger: createMockLogger(),
+      })
+    ).rejects.toMatchObject({ errorCode: 'EAS_LAUNCH_APPLICATION_INVALID_INPUT' });
+    expect(mockedSpawn).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects an Android launch command that is too long after quoting', async () => {
+    await expect(
+      launchApplicationAsync({
+        applicationIdentifier: 'com.example.app',
+        activityName: 'com.example.app.MainActivity',
+        launchArgs: ['--es', 'quotes', "'".repeat(20_000)],
+        runtimePlatform: BuildRuntimePlatform.LINUX,
+        env: {},
+        logger: createMockLogger(),
+      })
+    ).rejects.toMatchObject({ errorCode: 'EAS_LAUNCH_APPLICATION_INVALID_INPUT' });
+    expect(mockedSpawn).not.toHaveBeenCalled();
+  });
+
   it('launches using application metadata passed to the build step', async () => {
     const launchApplication = createLaunchApplicationFunction();
     const buildStep = launchApplication.createBuildStepFromFunctionCall(
@@ -237,6 +495,36 @@ describe(launchApplicationAsync, () => {
     );
   });
 
+  it('quotes Android launch arguments passed to the build step', async () => {
+    const launchApplication = createLaunchApplicationFunction();
+    const buildStep = launchApplication.createBuildStepFromFunctionCall(
+      createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.LINUX }),
+      {
+        callInputs: {
+          application_identifier: 'com.example.app',
+          activity_name: 'com.example.app.MainActivity',
+          launch_args: ['--es', 'probe', 'hello world'],
+        },
+      }
+    );
+    await buildStep.executeAsync();
+
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'adb',
+      [
+        'shell',
+        'am',
+        'start',
+        '--es',
+        'probe',
+        "'hello world'",
+        '-n',
+        'com.example.app/com.example.app.MainActivity',
+      ],
+      expect.any(Object)
+    );
+  });
+
   it.each([{}, ['valid', 42]])('rejects invalid launch arguments (%j)', async launchArgs => {
     const launchApplication = createLaunchApplicationFunction();
     const buildStep = launchApplication.createBuildStepFromFunctionCall(

packages/build-tools/src/steps/functions/__tests__/maestroTests.test.ts

@@ -1,4 +1,4 @@
-import { GenericArtifactType, SystemError, UserError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import spawn from '@expo/turtle-spawn';
 import fs from 'fs/promises';
 import os from 'os';
@@ -305,7 +305,6 @@ describe('createMaestroTestsBuildFunction', () => {
       expect(mockUploadArtifact).toHaveBeenCalledWith(
         expect.objectContaining({
           artifact: expect.objectContaining({
-            type: GenericArtifactType.OTHER,
             name:
               format === 'html' ? 'Maestro Runner HTML Report' : 'Maestro Runner Allure Results',
             paths: [
@@ -1091,7 +1090,6 @@ describe('createMaestroTestsBuildFunction', () => {
     expect(mockUploadArtifact).toHaveBeenCalledWith(
       expect.objectContaining({
         artifact: expect.objectContaining({
-          type: GenericArtifactType.OTHER,
           name: 'Maestro HTML Report',
           paths: ['/home/expo/.maestro/tests/android-maestro-html.html'],
         }),
@@ -1420,7 +1418,6 @@ describe('createMaestroTestsBuildFunction', () => {
     expect(mockUploadArtifact).toHaveBeenCalledWith(
       expect.objectContaining({
         artifact: expect.objectContaining({
-          type: GenericArtifactType.OTHER,
           name: shot.displayName,
           metadata: shot.metadata,
         }),

packages/build-tools/src/steps/functions/__tests__/remoteSessionLocalEgress.test.ts

@@ -162,9 +162,10 @@ describe.each(controllers)('%s local egress', (_name, createFunction, controller
     });
     jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
       openPreviewAsync: openPreview,
+      getLastPreviewActivityAt: jest.fn(),
       finishAsync: stopPreview,
     });
-    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
+    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue('started');
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockImplementation(async () => {
       expect(lifetime.aborted).toBe(false);
       expect(monitorLocalEgressAsync).toHaveBeenCalledTimes(1);
@@ -175,6 +176,16 @@ describe.each(controllers)('%s local egress', (_name, createFunction, controller
     jest.restoreAllMocks();
   });
 
+  it('releases resources without monitoring when the session stopped during startup', async () => {
+    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValueOnce('stopped');
+    await run();
+    expect(waitForDeviceRunSessionStoppedAsync).not.toHaveBeenCalled();
+    expect(monitorLocalEgressAsync).not.toHaveBeenCalled();
+    expect(stopPreview).toHaveBeenCalledTimes(1);
+    expect(stopEgress).toHaveBeenCalledTimes(1);
+    expect(lifetime.aborted).toBe(true);
+  });
+
   it('reports credentials and starts monitoring before waiting, then releases resources', async () => {
     await run();
     expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith({

packages/build-tools/src/steps/functions/__tests__/repack.test.ts

@@ -1,8 +1,10 @@
 import { type bunyan } from '@expo/logger';
+import turtleSpawnAsync from '@expo/turtle-spawn';
 import assert from 'node:assert';
 import fg from 'fast-glob';
 import { vol } from 'memfs';
 import path from 'node:path';
+import resolveFrom from 'resolve-from';
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { createTestAndroidJob, createTestIosJob } from '../../../__tests__/utils/job';
@@ -17,17 +19,100 @@ import {
 } from '../repack';
 
 jest.mock('fs');
-jest.mock('@expo/spawn-async');
+jest.mock('@expo/turtle-spawn', () => ({ __esModule: true, default: jest.fn() }));
 jest.mock('@expo/repack-app');
-jest.mock('resolve-from', () => jest.fn((_, moduleName) => moduleName));
+jest.mock('resolve-from', () => jest.fn(() => '@expo/repack-app'));
 jest.mock('../../utils/ios/credentials/manager');
 
 describe(createRepackBuildFunction, () => {
+  beforeEach(() => {
+    jest.mocked(turtleSpawnAsync).mockImplementation((async (_command: string, args: string[]) => {
+      const sandbox = args[args.indexOf('--prefix') + 1];
+      const packageName = args[args.length - 1].replace(/@[^@/]*$/, '');
+      vol.fromJSON({
+        [path.join(sandbox, 'node_modules', packageName, 'package.json')]: JSON.stringify({
+          version: '2.0.0-next.1',
+        }),
+      });
+    }) as unknown as typeof turtleSpawnAsync);
+  });
+
   afterEach(() => {
     jest.restoreAllMocks();
     vol.reset();
   });
 
+  it('installs the repack package with npm in a sandbox whose env is only PATH and HOME, through the npm cache registry', async () => {
+    const globalCtx = createGlobalContextMock({
+      staticContextContent: {
+        job: {},
+      },
+    });
+    globalCtx.updateEnv({
+      PATH: '/usr/local/bin:/usr/bin',
+      EAS_BUILD_NPM_CACHE_URL: 'https://npm-cache.expo.test',
+      NPM_TOKEN: 'secret',
+    });
+    const repack = createRepackBuildFunction();
+    const repackStep = repack.createBuildStepFromFunctionCall(globalCtx, {
+      callInputs: {
+        platform: 'ios',
+        source_app_path: '/path/to/source_app.ipa',
+        repack_package: '@scope/fork',
+        repack_version: 'next',
+      },
+    });
+    const logInfo = jest.spyOn(repackStep.ctx.logger, 'info');
+
+    await repackStep.executeAsync();
+
+    const [installCall] = jest.mocked(turtleSpawnAsync).mock.calls;
+    const npmEnv = installCall[2]?.env;
+    assert(npmEnv);
+    expect(Object.keys(npmEnv).sort()).toEqual(['HOME', 'PATH']);
+    expect(npmEnv.PATH).toMatch(/\/usr\/local\/bin:\/usr\/bin$/);
+    expect(installCall).toEqual([
+      'npm',
+      [
+        'install',
+        '--prefix',
+        npmEnv.HOME,
+        '--no-save',
+        '--package-lock=false',
+        '--no-audit',
+        '--no-fund',
+        '--no-update-notifier',
+        '--registry',
+        'https://npm-cache.expo.test',
+        '@scope/fork@next',
+      ],
+      { env: npmEnv, logger: repackStep.ctx.logger },
+    ]);
+    expect(logInfo).toHaveBeenCalledWith('Using repack from: @scope/fork@next (2.0.0-next.1)');
+    expect(resolveFrom).toHaveBeenCalledWith(npmEnv.HOME, '@scope/fork');
+  });
+
+  it('installs the repack package from the default registry when the job has no npm cache', async () => {
+    const globalCtx = createGlobalContextMock({
+      staticContextContent: {
+        job: {},
+      },
+    });
+    globalCtx.updateEnv({ PATH: '/usr/local/bin:/usr/bin' });
+    const repack = createRepackBuildFunction();
+    const repackStep = repack.createBuildStepFromFunctionCall(globalCtx, {
+      callInputs: {
+        platform: 'ios',
+        source_app_path: '/path/to/source_app.ipa',
+      },
+    });
+
+    await repackStep.executeAsync();
+
+    const [installCall] = jest.mocked(turtleSpawnAsync).mock.calls;
+    expect(installCall[1]).not.toContain('--registry');
+  });
+
   it('should set generated output path for successful repack', async () => {
     const repack = createRepackBuildFunction();
     const repackStep = repack.createBuildStepFromFunctionCall(

packages/build-tools/src/steps/functions/__tests__/runAgent.test.ts

@@ -103,7 +103,7 @@ describe(createRunAgentBuildFunction, () => {
     );
     const npmEnv = installMock.mock.calls[0][2]!.env!;
     const agentEnv = spawnMock.mock.calls[0][2].env!;
-    expect(Object.keys(npmEnv).sort()).toEqual(['HOME', 'LANG', 'PATH', 'TMPDIR']);
+    expect(Object.keys(npmEnv).sort()).toEqual(['HOME', 'PATH']);
     expect(Object.keys(agentEnv).sort()).toEqual([
       'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC',
       'CLAUDE_CODE_OAUTH_TOKEN',

packages/build-tools/src/steps/functions/__tests__/startAgentDeviceRemoteSession-orchestration.test.ts

@@ -76,7 +76,8 @@ async function runAsync(
   runtimePlatform: BuildRuntimePlatform,
   capture: CaptureInputs = NO_CAPTURE,
   disableShare = false,
-  privatePreviewUrl?: string
+  privatePreviewUrl?: string,
+  maxIdleTimeMinutes?: number
 ): Promise<void> {
   await runAgentDeviceRemoteSessionAsync(ctx, {
     env: {},
@@ -88,7 +89,7 @@ async function runAsync(
       ngrokAuthtoken: 'ngrok-token',
     },
     packageVersion: undefined,
-    maxIdleTimeMinutes: undefined,
+    maxIdleTimeMinutes,
     maxDurationSeconds: undefined,
     capture,
     disableShare,
@@ -102,6 +103,18 @@ async function runAsync(
 }
 
 describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
+  it('cleans up a stopped startup without starting live-session polling', async () => {
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValueOnce('stopped');
+    await runAsync(logger, BuildRuntimePlatform.DARWIN);
+    expect(waitForDeviceRunSessionStoppedAsync).not.toHaveBeenCalled();
+    expect(pollAgentDeviceArtifactsForUploadAsync).not.toHaveBeenCalled();
+    expect(startAgentDeviceEventCollectionAsync).not.toHaveBeenCalled();
+    expect(mockDaemonStopAsync).toHaveBeenCalled();
+    expect(mockTunnelStopAsync).toHaveBeenCalled();
+    expect(mockPreviewStopAsync).toHaveBeenCalled();
+  });
+
   beforeEach(async () => {
     jest.clearAllMocks();
 
@@ -133,6 +146,7 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
         apiUrl: 'https://web-preview.tunnel.example.com',
         closeAsync: jest.fn(),
       }),
+      getLastPreviewActivityAt: jest.fn(),
       finishAsync: mockPreviewStopAsync,
     };
     jest.mocked(startDeviceSessionHostAsync).mockImplementation(async (_ctx, options) => {
@@ -145,7 +159,7 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
       }
       return host;
     });
-    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
+    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue('started');
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
 
     await fs.promises.mkdir(path.dirname(DAEMON_ENTRY_PATH), { recursive: true });
@@ -202,6 +216,21 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
     expect(JSON.stringify(logger.info.mock.calls)).not.toContain(encodeURIComponent(token));
   });
 
+  it('resets the idle timer on preview input from the session host', async () => {
+    const previewInputAt = new Date('2026-10-19T12:00:00Z');
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+    const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(ctx, {
+      application: Promise.resolve(),
+    } as never);
+    jest.mocked(host.getLastPreviewActivityAt).mockReturnValue(previewInputAt);
+
+    await runAsync(logger, BuildRuntimePlatform.LINUX, NO_CAPTURE, false, undefined, 5);
+
+    const { idleTimeout } = jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.calls[0][0];
+    expect(idleTimeout?.maxIdleTimeMinutes).toBe(5);
+    expect(idleTimeout?.getLastPreviewActivityAt?.()).toBe(previewInputAt);
+  });
+
   it('hands network capture to serve-sim', async () => {
     const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
 

packages/build-tools/src/steps/functions/__tests__/startAgentDeviceSession.test.ts

@@ -5,6 +5,7 @@ import spawn from '@expo/turtle-spawn';
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
 import { DeviceRunSessionWorkerApi } from '../../utils/deviceRunSessionWorkerApi';
+import { registerAndroidEmulatorLogDirectory } from '../../utils/androidEmulatorLogs';
 import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
 import { stopLocalEgressResourcesAsync } from '../../utils/localEgress';
 import {
@@ -32,6 +33,7 @@ jest.mock('../../utils/localEgressGuard', () => ({
   startLocalEgressGuardRelayAsync: jest.fn(),
 }));
 jest.mock('@expo/turtle-spawn');
+jest.mock('../../utils/androidEmulatorLogs');
 jest.mock('../../../utils/IosSimulatorUtils');
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
@@ -108,6 +110,7 @@ function runStep(
   const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
   const inputs = Object.fromEntries(
     [
+      'android_log_sources',
       'device_identifier',
       'system_image_package',
       'lcd_width',
@@ -126,7 +129,15 @@ function runStep(
       'package_version',
       'max_idle_time_minutes',
       'max_duration_seconds',
-    ].map(id => [id, { value: inputValues[id] }])
+    ].map(id => [
+      id,
+      {
+        value:
+          id === 'android_log_sources' && !(id in inputValues)
+            ? ['emulator-output', 'device-logcat']
+            : inputValues[id],
+      },
+    ])
   );
   return buildFunction.fn!(
     {
@@ -406,6 +417,7 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     expect(downloadBuildAsync).not.toHaveBeenCalled();
     expect(installBuildAsync).not.toHaveBeenCalled();
     expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(registerAndroidEmulatorLogDirectory).not.toHaveBeenCalled();
     expect(sessionDevice()).toEqual({
       iosSimulatorUdid: 'SELECTED-UDID',
       bootEnv: undefined,
@@ -413,6 +425,27 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     });
   });
 
+  it.each([
+    { sources: [] },
+    { sources: ['emulator-output'] },
+    { sources: ['device-logcat'] },
+    { sources: ['emulator-output', 'device-logcat'] },
+  ])('selects $sources before Android boot', async ({ sources }) => {
+    await runStep(BuildRuntimePlatform.LINUX, { android_log_sources: sources });
+    expect(startAndroidEmulatorAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ logSources: sources })
+    );
+  });
+
+  it('rejects invalid Android log sources before boot', async () => {
+    await expect(
+      runStep(BuildRuntimePlatform.LINUX, {
+        android_log_sources: ['unknown'],
+      })
+    ).rejects.toThrow();
+    expect(startAndroidEmulatorAsync).not.toHaveBeenCalled();
+  });
+
   it('boots the Android Emulator with the device inputs', async () => {
     await runStep(BuildRuntimePlatform.LINUX, {
       device_identifier: 'pixel_7',
@@ -424,6 +457,10 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     });
 
     expect(selectXcodeDeveloperDirectoryAsync).not.toHaveBeenCalled();
+    expect(registerAndroidEmulatorLogDirectory).toHaveBeenCalledWith(
+      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX }),
+      jest.mocked(startAndroidEmulatorAsync).mock.calls[0][0].logcatDirectory
+    );
     expect(startAndroidEmulatorAsync).toHaveBeenCalledWith(
       expect.objectContaining({
         deviceIdentifier: 'pixel_7',
@@ -499,6 +536,10 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     // The step returned only after the download stopped.
     expect(download.settled()).toBe(true);
     expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(registerAndroidEmulatorLogDirectory).toHaveBeenCalledTimes(1);
+    expect(
+      jest.mocked(registerAndroidEmulatorLogDirectory).mock.invocationCallOrder[0]
+    ).toBeLessThan(jest.mocked(startAndroidEmulatorAsync).mock.invocationCallOrder[0]);
   });
 
   it('stops a stalled download and does not install when the daemon fails', async () => {
@@ -612,6 +653,7 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     expect(
       buildFunction.inputProviders?.map(provider => provider(globalCtx, 'Test step').id)
     ).toEqual([
+      'android_log_sources',
       'device_identifier',
       'system_image_package',
       'lcd_width',
@@ -687,6 +729,18 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
   });
 
+  it.each([
+    ['NUL argument', { launch_args: ['a\u0000b'] }],
+    ['command length', { launch_args: ['--es', 'quotes', "'".repeat(20_000)] }],
+    ['NUL URL', { open_url: 'example:\u0000screen' }],
+  ])('rejects Android launch %s before startup work', async (_name, inputs) => {
+    const step = runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id', ...inputs });
+    await expect(step).rejects.toMatchObject({ errorCode: 'EAS_LAUNCH_APPLICATION_INVALID_INPUT' });
+    expect(startAndroidEmulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+  });
+
   it('keeps Android launch inputs on its existing direct path', async () => {
     const launchArgs = ['a'.repeat(9000)];
     await runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id', launch_args: launchArgs });

packages/build-tools/src/steps/functions/__tests__/startAndroidEmulator.test.ts

@@ -9,6 +9,7 @@ import {
 } from '../../../utils/AndroidEmulatorUtils';
 import { retryAsync } from '../../../utils/retry';
 import { resolveAndroidEmulatorLocalEgressAsync } from '../../utils/androidLocalEgress';
+import { registerAndroidEmulatorLogDirectory } from '../../utils/androidEmulatorLogs';
 import { createStartAndroidEmulatorBuildFunction } from '../startAndroidEmulator';
 
 jest.mock('@expo/turtle-spawn', () => ({
@@ -24,6 +25,8 @@ jest.mock('../../utils/androidLocalEgress', () => ({
   resolveAndroidEmulatorLocalEgressAsync: jest.fn(),
 }));
 
+jest.mock('../../utils/androidEmulatorLogs');
+
 jest.mock('../../../utils/AndroidEmulatorUtils', () => ({
   AndroidEmulatorUtils: {
     defaultSystemImagePackage: 'system-images;android-30;default;x86_64',
@@ -90,6 +93,25 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
     mockedMkdtemp.mockRestore();
   });
 
+  it.each([
+    { sources: [] },
+    { sources: ['emulator-output'] },
+    { sources: ['device-logcat'] },
+    { sources: ['emulator-output', 'device-logcat'] },
+  ])('preserves $sources through boot retries and clones', async ({ sources }) => {
+    mockedAndroidUtils.waitForReadyAsync.mockRejectedValueOnce(new Error('retry boot'));
+    await createStep({ android_log_sources: sources, count: 2 }).executeAsync();
+    expect(mockedAndroidUtils.startAsync).toHaveBeenCalledTimes(4);
+    for (const [options] of mockedAndroidUtils.startAsync.mock.calls) {
+      expect(options.logSources).toEqual(sources);
+    }
+  });
+
+  it('rejects invalid sources before starting the emulator', async () => {
+    await expect(createStep({ android_log_sources: ['unknown'] }).executeAsync()).rejects.toThrow();
+    expect(mockedAndroidUtils.startAsync).not.toHaveBeenCalled();
+  });
+
   describe('local egress', () => {
     function createLocalEgress() {
       return {
@@ -111,6 +133,7 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
         deviceName: 'EasAndroidDevice01',
         env: expect.any(Object),
         logcatDirectory: '/tmp/logcat-directory',
+        logSources: ['emulator-output', 'device-logcat'],
       });
       expect(mockedAndroidUtils.waitForReadyAsync).toHaveBeenCalledWith({
         env: expect.any(Object),
@@ -226,6 +249,7 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
       expect.objectContaining({
         deviceName: 'EasAndroidDevice01',
         logcatDirectory: '/tmp/logcat-directory',
+        logSources: ['emulator-output', 'device-logcat'],
       })
     );
     expect(mockedAndroidUtils.startAsync).toHaveBeenNthCalledWith(
@@ -233,6 +257,7 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
       expect.objectContaining({
         deviceName: 'EasAndroidDevice01',
         logcatDirectory: '/tmp/logcat-directory',
+        logSources: ['emulator-output', 'device-logcat'],
       })
     );
     expect(mockedAndroidUtils.deleteAsync).toHaveBeenCalledWith(
@@ -307,18 +332,21 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
       expect.objectContaining({
         deviceName: 'EasAndroidDevice01',
         logcatDirectory: '/tmp/logcat-directory',
+        logSources: ['emulator-output', 'device-logcat'],
       })
     );
     expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith(
       expect.objectContaining({
         deviceName: 'eas-simulator-1',
         logcatDirectory: '/tmp/logcat-directory',
+        logSources: ['emulator-output', 'device-logcat'],
       })
     );
     expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith(
       expect.objectContaining({
         deviceName: 'eas-simulator-2',
         logcatDirectory: '/tmp/logcat-directory',
+        logSources: ['emulator-output', 'device-logcat'],
       })
     );
 
@@ -348,6 +376,13 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
     );
     expect(mockedAndroidUtils.deleteAsync).toHaveBeenCalledTimes(3);
     expect(mockedAndroidUtils.startAsync).toHaveBeenCalledTimes(3);
+    expect(registerAndroidEmulatorLogDirectory).toHaveBeenCalledWith(
+      expect.anything(),
+      '/tmp/logcat-directory'
+    );
+    expect(
+      jest.mocked(registerAndroidEmulatorLogDirectory).mock.invocationCallOrder[0]
+    ).toBeLessThan(mockedAndroidUtils.startAsync.mock.invocationCallOrder[0]);
   });
 
   it('outputs and uses a temporary logcat directory', async () => {
@@ -357,9 +392,14 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
     expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith(
       expect.objectContaining({
         logcatDirectory: '/tmp/logcat-directory',
+        logSources: ['emulator-output', 'device-logcat'],
       })
     );
     expect(step.getOutputValueByName('logcat_directory')).toBe('/tmp/logcat-directory');
+    expect(registerAndroidEmulatorLogDirectory).toHaveBeenCalledWith(
+      step.ctx.global,
+      '/tmp/logcat-directory'
+    );
     expect(mockedAndroidUtils.waitForReadyAsync).toHaveBeenCalledWith(
       expect.objectContaining({
         serialId: 'emulator-default',

packages/build-tools/src/steps/functions/__tests__/startAppiumRemoteSession.test.ts

@@ -1,19 +1,24 @@
 import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
 import fs from 'node:fs';
+import path from 'node:path';
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
 import { AndroidEmulatorUtils } from '../../../utils/AndroidEmulatorUtils';
 import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import * as processes from '../../../utils/processes';
 import { sleepAsync } from '../../../utils/retry';
 import { turtleFetch } from '../../../utils/turtleFetch';
 import { startAppiumEventCollectionAsync } from '../../utils/appiumEvents';
 import { startDeviceSessionHostAsync } from '../../utils/deviceSessionHost';
+import { preparePreinstalledWdaAsync } from '../../utils/preinstalledWda';
 import {
+  ensureFfmpegInstalledOnceAsync,
   selectXcodeDeveloperDirectoryAsync,
   spawnDetached,
   startNgrokTunnelAsync,
+  waitForDeviceRunSessionStoppedAsync,
 } from '../../utils/remoteDeviceRunSession';
 
 import {
@@ -27,11 +32,16 @@ jest.mock('../../../utils/AndroidEmulatorUtils', () => ({
   AndroidEmulatorUtils: { getAttachedDevicesAsync: jest.fn() },
 }));
 jest.mock('../../../utils/IosSimulatorUtils', () => ({
-  IosSimulatorUtils: { getAvailableDevicesAsync: jest.fn() },
+  IosSimulatorUtils: {
+    getAvailableDevicesAsync: jest.fn(),
+    getDeviceAsync: jest.fn(),
+    resolveUdidAsync: jest.fn().mockResolvedValue('chosen-ios-udid'),
+  },
 }));
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
   selectXcodeDeveloperDirectoryAsync: jest.fn(),
+  ensureFfmpegInstalledOnceAsync: jest.fn(),
   spawnDetached: jest.fn(),
   startNgrokTunnelAsync: jest.fn(),
   waitForDeviceRunSessionStoppedAsync: jest.fn(),
@@ -48,6 +58,15 @@ jest.mock('../../../utils/turtleFetch', () => ({
 }));
 jest.mock('../../utils/appiumEvents', () => ({ startAppiumEventCollectionAsync: jest.fn() }));
 jest.mock('../../utils/deviceSessionHost');
+jest.mock('../../utils/preinstalledWda', () => ({ preparePreinstalledWdaAsync: jest.fn() }));
+jest.mock('../../utils/iosAppArtifact', () => ({
+  ...jest.requireActual('../../utils/iosAppArtifact'),
+  readIosApplicationIdentifierAsync: jest.fn().mockResolvedValue('dev.example.app'),
+}));
+jest.mock('../../utils/localEgressGuard', () => ({
+  resolveLocalEgressServeSimBootEnvironmentAsync: jest.fn().mockResolvedValue(null),
+}));
+
 jest.mock('../../utils/localEgressSession', () => ({
   ...jest.requireActual('../../utils/localEgressSession'),
   uploadRemoteSessionConfigWithLocalEgressAsync: jest.fn(),
@@ -88,7 +107,6 @@ describe(resolveAppiumDeviceAsync, () => {
       resolveAppiumDeviceAsync({
         runtimePlatform: BuildRuntimePlatform.DARWIN,
         env: {},
-        logger,
       })
     ).resolves.toEqual({
       platformName: 'iOS',
@@ -97,7 +115,6 @@ describe(resolveAppiumDeviceAsync, () => {
       udid: 'ios-simulator-id',
       runtimeIdentifier: 'com.apple.CoreSimulator.SimRuntime.iOS-26-5',
     });
-    expect(selectXcodeDeveloperDirectoryAsync).toHaveBeenCalledWith({ env: {}, logger });
     expect(IosSimulatorUtils.getAvailableDevicesAsync).toHaveBeenCalledWith({
       env: {},
       filter: 'booted',
@@ -113,7 +130,6 @@ describe(resolveAppiumDeviceAsync, () => {
       resolveAppiumDeviceAsync({
         runtimePlatform: BuildRuntimePlatform.LINUX,
         env: {},
-        logger,
       })
     ).resolves.toEqual({
       platformName: 'Android',
@@ -187,6 +203,78 @@ describe(installAppiumAsync, () => {
 });
 
 describe('createStartAppiumRemoteSessionBuildFunction', () => {
+  it.each([
+    [BuildRuntimePlatform.DARWIN, true],
+    [BuildRuntimePlatform.DARWIN, false],
+    [BuildRuntimePlatform.LINUX, true],
+    [BuildRuntimePlatform.LINUX, false],
+  ])('starts Appium on %s with helper present=%s', async (runtimePlatform, helperPresent) => {
+    const helper = '/usr/local/libexec/turtle-tcc-fda';
+    if (helperPresent) {
+      fs.mkdirSync(path.dirname(helper), { recursive: true });
+      fs.writeFileSync(helper, 'prepared helper');
+    }
+    jest.mocked(spawn).mockResolvedValue({ stdout: '{}' } as never);
+    jest
+      .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+      .mockResolvedValue([{ udid: 'simulator' }] as never);
+    jest
+      .mocked(AndroidEmulatorUtils.getAttachedDevicesAsync)
+      .mockResolvedValue([{ serialId: 'emulator-5554', state: 'device' }] as never);
+    // Stop at the launch boundary; no readiness requests or remote session are needed.
+    const launched = new Error('launch captured');
+    jest.mocked(spawnDetached).mockImplementation(() => {
+      throw launched;
+    });
+    const env = {
+      DEVICE_RUN_SESSION_ID: 'session',
+      EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN: 'example.test',
+      PATH: '/configured/node/bin:/usr/bin',
+      DEVELOPER_DIR: '/Applications/Xcode.app/Contents/Developer',
+    };
+    const buildFunction = createStartAppiumRemoteSessionBuildFunction({} as CustomBuildContext);
+    await expect(
+      buildFunction.fn!(
+        { logger, global: { runtimePlatform } } as unknown as BuildStepContext,
+        {
+          inputs: {
+            package_version: { value: undefined },
+            max_idle_time_minutes: { value: undefined },
+          },
+          outputs: {},
+          env: { ...env, NGROK_AUTHTOKEN: 'token' },
+        } as never
+      )
+    ).rejects.toBe(launched);
+
+    expect(spawnDetached).toHaveBeenCalledTimes(1);
+    const launch = jest.mocked(spawnDetached).mock.calls[0][0];
+    const appiumBinPath = path.join(launch.env.APPIUM_HOME!, 'node_modules', '.bin', 'appium');
+    const useHelper = runtimePlatform === BuildRuntimePlatform.DARWIN && helperPresent;
+    expect(launch).toEqual({
+      command: useHelper ? helper : appiumBinPath,
+      args: [
+        ...(useHelper ? [appiumBinPath] : []),
+        '--address',
+        '127.0.0.1',
+        '--port',
+        '4723',
+        '--base-path',
+        '/',
+        '--log-level',
+        'error',
+        '--allow-insecure',
+        '*:session_discovery',
+        '--default-capabilities',
+        runtimePlatform === BuildRuntimePlatform.DARWIN
+          ? '{"appium:eventTimings":true,"appium:isHeadless":true}'
+          : '{"appium:eventTimings":true}',
+      ],
+      env: { ...env, APPIUM_HOME: launch.env.APPIUM_HOME },
+      logger,
+    });
+  });
+
   it('declares the launch inputs so serve-sim can launch the app', () => {
     const ctx = {} as unknown as CustomBuildContext;
     const buildFunction = createStartAppiumRemoteSessionBuildFunction(ctx);
@@ -212,6 +300,13 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
   const stopEventCollection = jest.fn();
 
   beforeEach(() => {
+    jest.mocked(ensureFfmpegInstalledOnceAsync).mockResolvedValue(undefined);
+    jest.mocked(preparePreinstalledWdaAsync).mockResolvedValue({});
+    jest.mocked(IosSimulatorUtils.getDeviceAsync).mockResolvedValue({
+      udid: 'CHOSEN-IOS-UDID',
+      runtime: 'com.apple.CoreSimulator.SimRuntime.iOS-26-5',
+      state: 'Shutdown',
+    } as never);
     jest.mocked(spawn).mockImplementation((async (_command: string, args: string[]) => ({
       stdout: args.includes('--json') ? '{}' : '',
     })) as never);
@@ -242,6 +337,7 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
         apiUrl: 'https://web-preview.tunnel.example.com',
         closeAsync: jest.fn(),
       }),
+      getLastPreviewActivityAt: jest.fn(),
       finishAsync: jest.fn(),
     });
   });
@@ -250,16 +346,22 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
     jest.restoreAllMocks();
   });
 
-  async function runSessionAsync(logger: { info: jest.Mock; warn: jest.Mock }): Promise<void> {
+  async function runSessionAsync(
+    logger: { info: jest.Mock; warn: jest.Mock },
+    maxIdleTimeMinutes?: number,
+    runtimePlatform = BuildRuntimePlatform.LINUX,
+    startupInputs: Record<string, { value: unknown }> = {}
+  ): Promise<void> {
     await createStartAppiumRemoteSessionBuildFunction({} as CustomBuildContext).fn!(
       {
         logger,
-        global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+        global: { runtimePlatform },
       } as unknown as BuildStepContext,
       {
         inputs: {
           package_version: { value: undefined },
-          max_idle_time_minutes: { value: undefined },
+          max_idle_time_minutes: { value: maxIdleTimeMinutes },
+          ...startupInputs,
         },
         outputs: {},
         env: {
@@ -280,6 +382,370 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
     );
   }
 
+  it('passes the existing Android selection to the preview host', async () => {
+    stopAppium.mockResolvedValue(undefined);
+    await runSessionAsync(logger);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ previewDeviceId: 'emulator-5554' })
+    );
+  });
+
+  it('passes the selected iOS preview target without enabling Simulator startup', async () => {
+    stopAppium.mockResolvedValue(undefined);
+    const udid = 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA';
+    jest
+      .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+      .mockResolvedValue([{ udid }, { udid: 'BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB' }] as Awaited<
+        ReturnType<typeof IosSimulatorUtils.getAvailableDevicesAsync>
+      >);
+    await runSessionAsync(logger, undefined, BuildRuntimePlatform.DARWIN);
+    const options = jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1];
+    expect(options).toHaveProperty('previewDeviceId', udid);
+    expect(options.iosSimulatorUdid).toBeUndefined();
+  });
+
+  it.each([false, true])(
+    'preserves preview settings with Simulator startup %s',
+    async bootSimulator => {
+      stopAppium.mockResolvedValue(undefined);
+      jest
+        .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+        .mockResolvedValue([{ udid: 'chosen-ios-udid' } as never]);
+      await runSessionAsync(logger, undefined, BuildRuntimePlatform.DARWIN, {
+        ...(bootSimulator
+          ? { boot_simulator: { value: true }, device_identifier: { value: 'chosen-device' } }
+          : {}),
+        public_preview: { value: false },
+        private_preview_url: { value: 'https://expo.dev/private-preview' },
+        frame_ancestors: { value: ['https://preview.example.com'] },
+        cors_origins: { value: ['https://api.example.com'] },
+      });
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({
+          disableShare: true,
+          privatePreviewUrl: 'https://expo.dev/private-preview',
+          frameAncestors: ['https://preview.example.com'],
+          corsOrigins: ['https://api.example.com'],
+        })
+      );
+    }
+  );
+
+  it('selects Xcode only once for an already-prepared iOS session', async () => {
+    stopAppium.mockResolvedValue(undefined);
+    jest.mocked(selectXcodeDeveloperDirectoryAsync).mockClear();
+    jest.mocked(IosSimulatorUtils.getAvailableDevicesAsync).mockResolvedValue([
+      {
+        udid: 'chosen-ios-udid',
+        runtime: 'com.apple.CoreSimulator.SimRuntime.iOS-26-4',
+      } as never,
+    ]);
+    jest.mocked(preparePreinstalledWdaAsync).mockResolvedValue({
+      'appium:usePreinstalledWDA': true,
+      'appium:prebuiltWDAPath': '/tmp/legacy-wda.app',
+    });
+    await runSessionAsync(
+      { info: jest.fn(), warn: jest.fn() },
+      undefined,
+      BuildRuntimePlatform.DARWIN
+    );
+    expect(preparePreinstalledWdaAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ runtimeIdentifier: 'com.apple.CoreSimulator.SimRuntime.iOS-26-4' })
+    );
+    expect(IosSimulatorUtils.getDeviceAsync).not.toHaveBeenCalled();
+    expect(JSON.parse(jest.mocked(spawnDetached).mock.calls[0][0].args.at(-1)!)).toEqual({
+      'appium:eventTimings': true,
+      'appium:isHeadless': true,
+      'appium:usePreinstalledWDA': true,
+      'appium:prebuiltWDAPath': '/tmp/legacy-wda.app',
+    });
+    expect(selectXcodeDeveloperDirectoryAsync).toHaveBeenCalledTimes(1);
+    expect(
+      jest.mocked(selectXcodeDeveloperDirectoryAsync).mock.invocationCallOrder[0]
+    ).toBeLessThan(
+      jest.mocked(IosSimulatorUtils.getAvailableDevicesAsync).mock.invocationCallOrder[0]
+    );
+  });
+
+  it('starts serve-sim on the selected iOS device while Appium installation is pending', async () => {
+    stopAppium.mockResolvedValue(undefined);
+    jest.mocked(selectXcodeDeveloperDirectoryAsync).mockClear();
+    jest.mocked(IosSimulatorUtils.getAvailableDevicesAsync).mockClear();
+    jest.mocked(preparePreinstalledWdaAsync).mockResolvedValue({
+      'appium:usePreinstalledWDA': true,
+      'appium:prebuiltWDAPath': '/tmp/selected-wda.app',
+    });
+    let releaseInstall!: (value: unknown) => void;
+    let enteredInstall!: () => void;
+    const installEntered = new Promise<void>(resolve => {
+      enteredInstall = resolve;
+    });
+    jest.mocked(spawn).mockImplementationOnce(() => {
+      enteredInstall();
+      return new Promise(resolve => {
+        releaseInstall = resolve;
+      }) as never;
+    });
+    const running = createStartAppiumRemoteSessionBuildFunction({} as CustomBuildContext).fn!(
+      {
+        logger: { info: jest.fn(), warn: jest.fn() },
+        global: { runtimePlatform: BuildRuntimePlatform.DARWIN },
+      } as unknown as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: undefined },
+          device_identifier: { value: 'chosen-device' },
+          install_app_path: { value: '/tmp/App.app' },
+          launch_args: { value: ['--literal'] },
+          open_url: { value: 'example://home' },
+        },
+        outputs: {},
+        env: {
+          DEVICE_RUN_SESSION_ID: 'device-run-session-id',
+          EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN: 'tunnel.example.com',
+          NGROK_AUTHTOKEN: 'ngrok-token',
+        },
+      } as never
+    );
+    await installEntered;
+    expect(
+      jest.mocked(selectXcodeDeveloperDirectoryAsync).mock.invocationCallOrder[0]
+    ).toBeLessThan(jest.mocked(IosSimulatorUtils.resolveUdidAsync).mock.invocationCallOrder[0]);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        iosSimulatorUdid: 'CHOSEN-IOS-UDID',
+        installAppPath: '/tmp/App.app',
+        launchAppIdentifier: 'dev.example.app',
+        launchArgs: ['--literal'],
+        openUrl: 'example://home',
+      })
+    );
+    expect(IosSimulatorUtils.getAvailableDevicesAsync).not.toHaveBeenCalled();
+    expect(preparePreinstalledWdaAsync).not.toHaveBeenCalled();
+    const readyHost = await jest.mocked(startDeviceSessionHostAsync).mock.results[0].value;
+    expect(readyHost.finishAsync).not.toHaveBeenCalled();
+    expect(jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1].signal?.aborted).toBe(false);
+    releaseInstall({ stdout: '' });
+    await running;
+    expect(readyHost.finishAsync).toHaveBeenCalledTimes(1);
+    expect(IosSimulatorUtils.getDeviceAsync).toHaveBeenCalledWith({
+      udid: 'CHOSEN-IOS-UDID',
+      env: expect.objectContaining({ DEVICE_RUN_SESSION_ID: 'device-run-session-id' }),
+    });
+    expect(preparePreinstalledWdaAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runtimeIdentifier: 'com.apple.CoreSimulator.SimRuntime.iOS-26-5',
+        appiumHome: jest.mocked(spawnDetached).mock.calls[0][0].env.APPIUM_HOME,
+      })
+    );
+    expect(JSON.parse(jest.mocked(spawnDetached).mock.calls[0][0].args.at(-1)!)).toEqual({
+      'appium:eventTimings': true,
+      'appium:isHeadless': true,
+      'appium:usePreinstalledWDA': true,
+      'appium:prebuiltWDAPath': '/tmp/selected-wda.app',
+    });
+    expect(selectXcodeDeveloperDirectoryAsync).toHaveBeenCalledTimes(1);
+    expect(stopAppium).toHaveBeenCalledTimes(1);
+  });
+
+  it('drains a failed Simulator startup installer before removing its Appium home', async () => {
+    const hostError = new Error('Simulator boot failed');
+    let failHost!: (error: Error) => void;
+    jest.mocked(startDeviceSessionHostAsync).mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failHost = reject;
+      })
+    );
+    let enteredInstall!: () => void;
+    const installEntered = new Promise<void>(resolve => {
+      enteredInstall = resolve;
+    });
+    let closeInstaller!: (error: Error) => void;
+    const child = { pid: 12345, kill: jest.fn() };
+    jest.mocked(spawn).mockImplementationOnce(() => {
+      enteredInstall();
+      return Object.assign(
+        new Promise((_resolve, reject) => {
+          closeInstaller = reject;
+        }),
+        { child }
+      ) as never;
+    });
+    const killGroup = jest.spyOn(processes, 'killProcessGroup').mockImplementation(() => {});
+    const running = runSessionAsync(logger, undefined, BuildRuntimePlatform.DARWIN, {
+      boot_simulator: { value: true },
+      device_identifier: { value: 'chosen-device' },
+    });
+    const settled = jest.fn();
+    const observed = running.then(settled, settled);
+    try {
+      await installEntered;
+      const home = jest.mocked(spawn).mock.calls[0][2]?.cwd as string;
+      const hostOptions = jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1];
+      hostOptions.onStartupError?.(hostError);
+      failHost(hostError);
+      await Promise.resolve();
+      expect(killGroup).toHaveBeenCalledWith(child, 'SIGKILL');
+      expect(settled).not.toHaveBeenCalled();
+      expect(fs.existsSync(home)).toBe(true);
+      closeInstaller(new Error('installer interrupted'));
+      await expect(running).rejects.toBe(hostError);
+      expect(fs.existsSync(home)).toBe(false);
+      expect(preparePreinstalledWdaAsync).not.toHaveBeenCalled();
+      expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+    } finally {
+      closeInstaller?.(new Error('test cleanup'));
+      await observed;
+    }
+  });
+
+  it('removes a completed Appium install when Simulator failure interrupts FFmpeg setup', async () => {
+    const hostError = new Error('Simulator startup failed');
+    let failHost!: (error: Error) => void;
+    jest.mocked(startDeviceSessionHostAsync).mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failHost = reject;
+      })
+    );
+    jest
+      .mocked(ensureFfmpegInstalledOnceAsync)
+      .mockImplementationOnce(
+        ({ signal }) =>
+          new Promise(resolve => signal?.addEventListener('abort', () => resolve(), { once: true }))
+      );
+    let installed!: () => void;
+    const installationFinished = new Promise<void>(resolve => {
+      installed = resolve;
+    });
+    jest.mocked(spawn).mockImplementation((async (_command: string, args: string[]) => {
+      if (args[0] === 'driver' && args[1] === 'install') {
+        installed();
+      }
+      return { stdout: args.includes('--json') ? '{}' : '' };
+    }) as never);
+    const running = runSessionAsync(logger, undefined, BuildRuntimePlatform.DARWIN, {
+      boot_simulator: { value: true },
+      device_identifier: { value: 'chosen-device' },
+    });
+    await installationFinished;
+    await new Promise<void>(resolve => setImmediate(resolve));
+    jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1].onStartupError?.(hostError);
+    failHost(hostError);
+    await expect(running).rejects.toBe(hostError);
+    const home = jest.mocked(spawn).mock.calls[0][2]?.cwd as string;
+    expect(fs.existsSync(home)).toBe(false);
+    expect(preparePreinstalledWdaAsync).not.toHaveBeenCalled();
+  });
+
+  it('preserves an installer failure before a later host failure during home cleanup', async () => {
+    const installError = new Error('npm install failed');
+    const hostError = new Error('later Simulator failure');
+    let failHost!: (error: Error) => void;
+    jest.mocked(startDeviceSessionHostAsync).mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failHost = reject;
+      })
+    );
+    jest.mocked(spawn).mockRejectedValueOnce(installError);
+    const remove = fs.promises.rm.bind(fs.promises);
+    let enteredCleanup!: () => void;
+    const cleanupEntered = new Promise<void>(resolve => {
+      enteredCleanup = resolve;
+    });
+    let releaseCleanup!: () => void;
+    const cleanupGate = new Promise<void>(resolve => {
+      releaseCleanup = resolve;
+    });
+    jest.spyOn(fs.promises, 'rm').mockImplementationOnce(async (directory, options) => {
+      enteredCleanup();
+      await cleanupGate;
+      await remove(directory, options);
+    });
+    const running = runSessionAsync(logger, undefined, BuildRuntimePlatform.DARWIN, {
+      boot_simulator: { value: true },
+      device_identifier: { value: 'chosen-device' },
+    });
+    const observed = running.catch(() => {});
+    try {
+      await cleanupEntered;
+      const options = jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1];
+      expect(options.signal?.reason).toBe(installError);
+      options.onStartupError?.(hostError);
+      failHost(hostError);
+      releaseCleanup();
+      await expect(running).rejects.toBe(installError);
+      expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+    } finally {
+      failHost(hostError);
+      releaseCleanup();
+      await observed;
+    }
+  });
+
+  it.each(['WDA download', 'Appium readiness'])(
+    'keeps the Simulator error when it interrupts %s',
+    async stage => {
+      stopAppium.mockResolvedValue(undefined);
+      const hostError = new Error('Simulator launch failed');
+      const laterError = new Error(`${stage} interrupted`);
+      let failHost!: (error: Error) => void;
+      jest.mocked(startDeviceSessionHostAsync).mockReturnValueOnce(
+        new Promise((_resolve, reject) => {
+          failHost = reject;
+        })
+      );
+      let enteredStage!: () => void;
+      const stageEntered = new Promise<void>(resolve => {
+        enteredStage = resolve;
+      });
+      let rejectStage!: (error: Error) => void;
+      let setupSignal: AbortSignal | undefined;
+      const waitForStage = (signal?: AbortSignal): Promise<never> => {
+        setupSignal = signal;
+        enteredStage();
+        return new Promise((_resolve, reject) => {
+          rejectStage = reject;
+          signal?.addEventListener('abort', () => reject(laterError), { once: true });
+        });
+      };
+      if (stage === 'WDA download') {
+        jest
+          .mocked(preparePreinstalledWdaAsync)
+          .mockImplementationOnce(({ signal }) => waitForStage(signal));
+      } else {
+        jest
+          .mocked(turtleFetch)
+          .mockImplementationOnce((_url, _method, options) =>
+            waitForStage(options?.signal ?? undefined)
+          );
+      }
+      const running = runSessionAsync(logger, undefined, BuildRuntimePlatform.DARWIN, {
+        boot_simulator: { value: true },
+        device_identifier: { value: 'chosen-device' },
+      });
+      const observed = running.catch(() => {});
+      try {
+        await stageEntered;
+        jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1].onStartupError?.(hostError);
+        failHost(hostError);
+        await Promise.resolve();
+        expect(setupSignal?.aborted).toBe(true);
+        await expect(running).rejects.toBe(hostError);
+        const home = jest.mocked(spawn).mock.calls[0][2]?.cwd as string;
+        expect(fs.existsSync(home)).toBe(false);
+        expect(startAppiumEventCollectionAsync).not.toHaveBeenCalled();
+        expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+      } finally {
+        rejectStage?.(laterError);
+        await observed;
+      }
+    }
+  );
+
   it('keeps the readiness error when Appium cannot be stopped', async () => {
     let now = Date.now();
     jest.spyOn(Date, 'now').mockImplementation(() => now);
@@ -307,10 +773,32 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
     expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
   });
 
+  it('resets the idle timer on preview input from the session host', async () => {
+    const previewInputAt = new Date('2026-10-19T12:00:00Z');
+    const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+      {} as never,
+      {} as never
+    );
+    jest.mocked(host.getLastPreviewActivityAt).mockReturnValue(previewInputAt);
+
+    await expect(runSessionAsync({ info: jest.fn(), warn: jest.fn() }, 5)).rejects.toBe(stopError);
+
+    const { idleTimeout } = jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.calls[0][0];
+    expect(idleTimeout?.maxIdleTimeMinutes).toBe(5);
+    expect(idleTimeout?.getLastPreviewActivityAt?.()).toBe(previewInputAt);
+  });
+
   it('fails a finished session when Appium cannot be stopped', async () => {
     const logger = { info: jest.fn(), warn: jest.fn() };
 
     await expect(runSessionAsync(logger)).rejects.toBe(stopError);
+    expect(preparePreinstalledWdaAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ runtimeIdentifier: undefined })
+    );
+    expect(IosSimulatorUtils.getDeviceAsync).not.toHaveBeenCalled();
+    expect(JSON.parse(jest.mocked(spawnDetached).mock.calls[0][0].args.at(-1)!)).toEqual({
+      'appium:eventTimings': true,
+    });
     expectAppiumStoppedAndHomeRemoved(logger);
     expect(stopEventCollection.mock.invocationCallOrder[0]).toBeLessThan(
       stopAppium.mock.invocationCallOrder[0]

packages/build-tools/src/steps/functions/__tests__/startArgentRemoteSession-orchestration.test.ts

@@ -7,8 +7,9 @@ import path from 'node:path';
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
 import { Sentry } from '../../../sentry';
+import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
 import { startDeviceSessionHostAsync } from '../../utils/deviceSessionHost';
-import { isProcessDescendantOfAsync } from '../../../utils/processes';
+import { isProcessDescendantOfAsync, killProcessGroup } from '../../../utils/processes';
 import { pollArgentArtifactsForUploadAsync } from '../../utils/argentArtifacts';
 import { startArgentEventCollectionAsync } from '../../utils/argentEvents';
 import { createProcessOutput } from '../../utils/processOutput';
@@ -24,6 +25,7 @@ import {
   waitForDeviceRunSessionStoppedAsync,
 } from '../../utils/remoteDeviceRunSession';
 import { createStartArgentRemoteSessionBuildFunction } from '../startArgentRemoteSession';
+import { readIosApplicationIdentifierAsync } from '../../utils/iosAppArtifact';
 
 // Redirect ~/.argent (where the tool-server writes its state file and event log) to a temp
 // home so waitForArgentToolServerStateAsync — which lives in the module under test and cannot
@@ -38,13 +40,32 @@ jest.mock('node:os', () => {
 });
 jest.mock('@expo/turtle-spawn', () => ({ __esModule: true, default: jest.fn() }));
 jest.mock('../../../sentry');
-jest.mock('../../../utils/processes', () => ({ isProcessDescendantOfAsync: jest.fn() }));
+jest.mock('../../../utils/processes', () => ({
+  isProcessDescendantOfAsync: jest.fn(),
+  killProcessGroup: jest.fn(),
+}));
 jest.mock('../../utils/argentArtifacts', () => ({ pollArgentArtifactsForUploadAsync: jest.fn() }));
 jest.mock('../../utils/argentEvents', () => ({
   ...jest.requireActual('../../utils/argentEvents'),
   startArgentEventCollectionAsync: jest.fn(),
 }));
 jest.mock('../../utils/deviceSessionHost');
+jest.mock('../../utils/iosAppArtifact', () => ({
+  ...jest.requireActual('../../utils/iosAppArtifact'),
+  readIosApplicationIdentifierAsync: jest.fn().mockResolvedValue('dev.example.app'),
+}));
+jest.mock('../../../utils/IosSimulatorUtils', () => ({
+  IosSimulatorUtils: {
+    resolveUdidAsync: jest.fn().mockResolvedValue('selected-ios-udid'),
+    getAvailableDevicesAsync: jest
+      .fn()
+      .mockResolvedValue([{ name: 'iPhone 17', udid: 'selected-ios-udid' }]),
+  },
+}));
+jest.mock('../../utils/localEgressGuard', () => ({
+  resolveLocalEgressServeSimBootEnvironmentAsync: jest.fn().mockResolvedValue(null),
+}));
+
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
   ensureFfmpegInstalledOnceAsync: jest.fn(),
@@ -104,9 +125,10 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
         apiUrl: 'https://web-preview.tunnel.example.com',
         closeAsync: jest.fn(),
       }),
+      getLastPreviewActivityAt: jest.fn(),
       finishAsync: mockPreviewStopAsync,
     });
-    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
+    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue('started');
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
 
     // The (real) tool-server state wait reads this file from the redirected ~/.argent.
@@ -217,6 +239,7 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
       if (phase === 'preview') {
         jest.mocked(startDeviceSessionHostAsync).mockResolvedValueOnce({
           openPreviewAsync: jest.fn().mockRejectedValue(error),
+          getLastPreviewActivityAt: jest.fn(),
           finishAsync: mockPreviewStopAsync,
         });
       } else if (phase === 'config') {
@@ -507,6 +530,35 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     expect(waitForDeviceRunSessionStoppedAsync).toHaveBeenCalledTimes(1);
   });
 
+  it('resets the idle timer on preview input from the session host', async () => {
+    const previewInputAt = new Date('2026-10-19T12:00:00Z');
+    const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+      {} as never,
+      {} as never
+    );
+    jest.mocked(host.getLastPreviewActivityAt).mockReturnValue(previewInputAt);
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+
+    await buildFunction.fn!(
+      {
+        logger: { info: jest.fn(), warn: jest.fn() },
+        global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+      } as unknown as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: 5 },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+
+    const { idleTimeout } = jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.calls[0][0];
+    expect(idleTimeout?.maxIdleTimeMinutes).toBe(5);
+    expect(idleTimeout?.getLastPreviewActivityAt?.()).toBe(previewInputAt);
+  });
+
   it('redacts startup credentials and registers the state token for later output', async () => {
     const token = 'tool/server "secret"';
     await fs.promises.writeFile(
@@ -592,6 +644,280 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     );
   });
 
+  it('boots and prepares the downloaded app while Argent installation is pending, and closes the host if installation fails', async () => {
+    let rejectInstall!: (error: Error) => void;
+    let enteredInstall!: () => void;
+    const installEntered = new Promise<void>(resolve => {
+      enteredInstall = resolve;
+    });
+    jest.mocked(spawn).mockImplementationOnce(() => {
+      enteredInstall();
+      return new Promise((_resolve, reject) => {
+        rejectInstall = reject;
+      }) as never;
+    });
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+    const running = buildFunction.fn!(
+      {
+        logger: { info: jest.fn(), warn: jest.fn() },
+        global: { runtimePlatform: BuildRuntimePlatform.DARWIN },
+      } as unknown as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: undefined },
+          device_identifier: { value: 'chosen-device' },
+          install_app_path: { value: '/tmp/App.app' },
+          launch_args: { value: ['--literal'] },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    await installEntered;
+    expect(
+      jest.mocked(selectXcodeDeveloperDirectoryAsync).mock.invocationCallOrder[0]
+    ).toBeLessThan(jest.mocked(IosSimulatorUtils.resolveUdidAsync).mock.invocationCallOrder[0]);
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledWith({
+      artifactPath: '/tmp/App.app',
+      env: {},
+    });
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        iosSimulatorUdid: 'SELECTED-IOS-UDID',
+        installAppPath: '/tmp/App.app',
+        launchAppIdentifier: 'dev.example.app',
+        launchArgs: ['--literal'],
+      })
+    );
+    const error = new Error('Argent install failed');
+    rejectInstall(error);
+    await expect(running).rejects.toBe(error);
+    expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+    expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+  });
+
+  it.each(['artifacts-list-endpoint', 'tool-server-event-log', 'video-watermark'])(
+    'stops and drains the pending %s command when the concurrent host fails',
+    async flag => {
+      const hostError = new Error('serve-sim startup failed');
+      const commandError = new Error('Argent command exited after cancellation');
+      let failHost!: (error: Error) => void;
+      let finishHostCleanup!: () => void;
+      jest.mocked(startDeviceSessionHostAsync).mockImplementationOnce(
+        async (_ctx, options) =>
+          await new Promise((_resolve, reject) => {
+            failHost = error => {
+              options.onStartupError?.(error);
+              finishHostCleanup = () => reject(error);
+            };
+          })
+      );
+      let failCommand!: (error: Error) => void;
+      let commandStarted!: () => void;
+      const commandEntered = new Promise<void>(resolve => {
+        commandStarted = resolve;
+      });
+      const child = { pid: 4242, kill: jest.fn() };
+      jest.mocked(spawn).mockImplementation((_command, args) => {
+        if (!args.includes(flag)) {
+          return Promise.resolve(undefined) as never;
+        }
+        const pending = new Promise((_resolve, reject) => {
+          failCommand = reject;
+        });
+        commandStarted();
+        return Object.assign(pending, { child }) as never;
+      });
+      const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+      const running = Promise.resolve(
+        buildFunction.fn!(
+          {
+            logger: { info: jest.fn(), warn: jest.fn() },
+            global: { runtimePlatform: BuildRuntimePlatform.DARWIN },
+          } as unknown as BuildStepContext,
+          {
+            inputs: {
+              package_version: { value: undefined },
+              max_idle_time_minutes: { value: undefined },
+              boot_simulator: { value: true },
+            },
+            outputs: {},
+            env: {},
+          } as never
+        )
+      );
+      let settled = false;
+      void running
+        .finally(() => {
+          settled = true;
+        })
+        .catch(() => {});
+      try {
+        await commandEntered;
+        failHost(hostError);
+        await new Promise(resolve => setImmediate(resolve));
+        expect(killProcessGroup).toHaveBeenCalledWith(child, 'SIGKILL');
+        expect(settled).toBe(false);
+        expect(spawnDetached).not.toHaveBeenCalled();
+        failCommand(commandError);
+        await new Promise(resolve => setImmediate(resolve));
+        expect(settled).toBe(false);
+        finishHostCleanup();
+        await expect(running).rejects.toBe(hostError);
+        expect(spawnDetached).not.toHaveBeenCalled();
+        expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+        expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+      } finally {
+        failCommand?.(commandError);
+        finishHostCleanup?.();
+        await running.catch(() => {});
+      }
+    }
+  );
+
+  it('interrupts tool-server state polling and retains the original host error', async () => {
+    await fs.promises.rm(path.join(ARGENT_STATE_DIR, 'tool-server-orchestration.json'));
+    const hostError = new Error('serve-sim startup failed');
+    let failHost!: (error: Error) => void;
+    jest.mocked(startDeviceSessionHostAsync).mockImplementationOnce(
+      async () =>
+        await new Promise((_resolve, reject) => {
+          failHost = reject;
+        })
+    );
+    let pollingStarted!: () => void;
+    const pollingEntered = new Promise<void>(resolve => {
+      pollingStarted = resolve;
+    });
+    const getExitError = jest.fn<Error | undefined, []>(() => {
+      pollingStarted();
+      return undefined;
+    });
+    const stopServer = jest.fn().mockResolvedValue(undefined);
+    jest.mocked(spawnDetached).mockReturnValueOnce({
+      pid: 4242,
+      getOutput: () => 'later controller diagnostic',
+      getExitError,
+      stopAsync: stopServer,
+    });
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+    const running = Promise.resolve(
+      buildFunction.fn!(
+        {
+          logger: { info: jest.fn(), warn: jest.fn() },
+          global: { runtimePlatform: BuildRuntimePlatform.DARWIN },
+        } as unknown as BuildStepContext,
+        {
+          inputs: {
+            package_version: { value: undefined },
+            max_idle_time_minutes: { value: undefined },
+            boot_simulator: { value: true },
+          },
+          outputs: {},
+          env: {},
+        } as never
+      )
+    );
+    void running.catch(() => {});
+    try {
+      await pollingEntered;
+      failHost(hostError);
+      await new Promise(resolve => setImmediate(resolve));
+      const options = jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1];
+      expect(options.signal?.aborted).toBe(true);
+      getExitError.mockReturnValue(new Error('later Argent exit'));
+      await expect(running).rejects.toBe(hostError);
+      expect(stopServer).toHaveBeenCalledTimes(1);
+      expect(startArgentEventCollectionAsync).not.toHaveBeenCalled();
+      expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    } finally {
+      getExitError.mockReturnValue(new Error('stop pending state poll'));
+      await running.catch(() => {});
+    }
+  });
+
+  it('keeps Argent setup concurrent but waits for the iOS host before opening tools', async () => {
+    const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+      {} as CustomBuildContext,
+      {} as never
+    );
+    let releaseHost!: () => void;
+    jest.mocked(startDeviceSessionHostAsync).mockReturnValueOnce(
+      new Promise(resolve => {
+        releaseHost = () => resolve(host);
+      })
+    );
+    let stateReady!: () => void;
+    const stateRead = new Promise<void>(resolve => {
+      stateReady = resolve;
+    });
+    jest.mocked(isProcessDescendantOfAsync).mockImplementationOnce(async () => {
+      stateReady();
+      return true;
+    });
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+    const running = Promise.resolve(
+      buildFunction.fn!(
+        {
+          logger: { info: jest.fn(), warn: jest.fn() },
+          global: { runtimePlatform: BuildRuntimePlatform.DARWIN },
+        } as unknown as BuildStepContext,
+        {
+          inputs: {
+            package_version: { value: undefined },
+            max_idle_time_minutes: { value: undefined },
+            boot_simulator: { value: true },
+          },
+          outputs: {},
+          env: {},
+        } as never
+      )
+    );
+    try {
+      await stateRead;
+      await new Promise(resolve => setImmediate(resolve));
+      expect(spawnDetached).toHaveBeenCalledTimes(1);
+      expect(startArgentEventCollectionAsync).not.toHaveBeenCalled();
+      expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    } finally {
+      releaseHost();
+      await running;
+    }
+    expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledTimes(1);
+    expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([BuildRuntimePlatform.DARWIN, BuildRuntimePlatform.LINUX])(
+    'keeps %s prepared setup commands outside the new cancellation path',
+    async runtimePlatform => {
+      const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+      await buildFunction.fn!(
+        {
+          logger: { info: jest.fn(), warn: jest.fn() },
+          global: { runtimePlatform },
+        } as unknown as BuildStepContext,
+        {
+          inputs: {
+            package_version: { value: undefined },
+            max_idle_time_minutes: { value: undefined },
+          },
+          outputs: {},
+          env: {},
+        } as never
+      );
+      expect(spawn).toHaveBeenCalledTimes(3);
+      for (const [, , options] of jest.mocked(spawn).mock.calls) {
+        expect(options).not.toHaveProperty('detached');
+        expect(options).not.toHaveProperty('signal');
+      }
+      expect(killProcessGroup).not.toHaveBeenCalled();
+    }
+  );
+
   it('fails before starting anything when a launch is asked for on Android', async () => {
     const ctx = {} as unknown as CustomBuildContext;
     const logger = { info: jest.fn(), warn: jest.fn() };

packages/build-tools/src/steps/functions/__tests__/startSandbox.test.ts

@@ -1,4 +1,4 @@
-import { SystemError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import { Client, fetchExchange } from '@urql/core';
 
 import * as sandboxDaemon from '../../utils/sandboxDaemon';
@@ -6,6 +6,90 @@ import * as sandboxDaemon from '../../utils/sandboxDaemon';
 import { createStartSandboxBuildFunction, markSandboxReadyAsync } from '../startSandbox';
 
 describe('sandbox build functions', () => {
+  it.each([
+    { completion: 'duration', duration: 0.02 },
+    { completion: 'cancellation', duration: 60 },
+    { completion: 'duration', duration: 0.0001 },
+  ])(
+    'stops after $completion with $duration seconds only after readiness',
+    async ({ completion, duration }) => {
+      const controller = new AbortController();
+      let ready!: () => void;
+      const stopAsync = jest.fn(async () => {});
+      const start = jest.spyOn(sandboxDaemon, 'startSandboxDaemonAsync').mockResolvedValue({
+        ready: new Promise<void>(resolve => {
+          ready = resolve;
+        }),
+        stopAsync,
+      });
+      const mutation = jest.fn(() => ({ toPromise: async () => ({ data: {} }) }));
+      const logger = { info: jest.fn(), child: jest.fn() };
+      logger.child.mockReturnValue(logger);
+      const fn = createStartSandboxBuildFunction({
+        mcpServerUrl: 'ws://localhost:8787',
+        graphqlClient: { mutation },
+      } as any);
+      try {
+        const pending = fn.fn!({ logger } as any, {
+          inputs: {
+            sandbox_id: { value: 'sandbox-id' },
+            max_duration_seconds: { value: duration },
+          },
+          outputs: {},
+          env: { __EAS_SANDBOX_MCP_TOKEN: 'token' },
+          signal: controller.signal,
+        });
+        await new Promise(resolve => setTimeout(resolve, 40));
+        expect(mutation).not.toHaveBeenCalled();
+        expect(stopAsync).not.toHaveBeenCalled();
+        ready();
+        if (completion === 'cancellation') {
+          await new Promise(resolve => setImmediate(resolve));
+          expect(stopAsync).not.toHaveBeenCalled();
+          controller.abort();
+        }
+        await pending;
+        expect(mutation).toHaveBeenCalledTimes(1);
+        expect(stopAsync).toHaveBeenCalledTimes(1);
+        const timeoutMessage = `Sandbox reached its maximum runtime of ${duration} seconds. Stopping.`;
+        if (completion === 'duration') {
+          expect(logger.info).toHaveBeenCalledWith(timeoutMessage);
+        } else {
+          expect(logger.info).not.toHaveBeenCalledWith(timeoutMessage);
+        }
+      } finally {
+        start.mockRestore();
+      }
+    }
+  );
+
+  it.each([0, -1, Infinity, NaN])(
+    'rejects invalid maximum duration %s before starting the daemon',
+    async duration => {
+      const start = jest.spyOn(sandboxDaemon, 'startSandboxDaemonAsync');
+      const fn = createStartSandboxBuildFunction({
+        mcpServerUrl: 'ws://localhost:8787',
+      } as any);
+      try {
+        const result = fn.fn!({} as any, {
+          inputs: {
+            sandbox_id: { value: 'sandbox-id' },
+            max_duration_seconds: { value: duration },
+          },
+          outputs: {},
+          env: { __EAS_SANDBOX_MCP_TOKEN: 'token' },
+        });
+        await expect(result).rejects.toBeInstanceOf(UserError);
+        await expect(result).rejects.toThrow(
+          `Invalid sandbox maximum duration: ${duration}. Provide a finite number greater than zero, or omit max_duration_seconds.`
+        );
+        expect(start).not.toHaveBeenCalled();
+      } finally {
+        start.mockRestore();
+      }
+    }
+  );
+
   it('aborts an active ready request and keeps its authentication headers', async () => {
     const controller = new AbortController();
     let requestStarted!: () => void;

packages/build-tools/src/steps/functions/__tests__/startWebPreviewRemoteSession.test.ts

@@ -81,13 +81,55 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
         apiUrl: 'https://web-preview.example.test',
         closeAsync: jest.fn(),
       }),
+      getLastPreviewActivityAt: jest.fn(),
       finishAsync: stopAsync,
     });
-    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
+    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue('started');
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
     stopAsync.mockResolvedValue(undefined);
   });
 
+  it('uses preview activity to reset the configured idle timeout', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, { max_idle_time_minutes: { value: 5 } });
+    const { idleTimeout } = jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.calls[0][0];
+    expect(idleTimeout?.maxIdleTimeMinutes).toBe(5);
+    expect(idleTimeout?.getLastEventObservedAt()).toBeUndefined();
+    const host = await jest.mocked(startDeviceSessionHostAsync).mock.results[0].value;
+    const observedAt = new Date();
+    jest.mocked(host.getLastPreviewActivityAt).mockReturnValue(observedAt);
+    expect(idleTimeout?.getLastPreviewActivityAt?.()).toBe(observedAt);
+    expect(stopAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([BuildRuntimePlatform.DARWIN, BuildRuntimePlatform.LINUX])(
+    'leaves the idle timer disabled when omitted on %s',
+    async runtimePlatform => {
+      await runAsync(runtimePlatform);
+      expect(waitForDeviceRunSessionStoppedAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ idleTimeout: undefined, maxDurationSeconds: 120 })
+      );
+    }
+  );
+
+  it('leaves the idle timer disabled for zero', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      max_idle_time_minutes: { value: 0 },
+    });
+    expect(waitForDeviceRunSessionStoppedAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ idleTimeout: undefined, maxDurationSeconds: 120 })
+    );
+  });
+
+  it('rejects an Android idle timeout before starting the host', async () => {
+    await expect(
+      runAsync(BuildRuntimePlatform.LINUX, {
+        max_idle_time_minutes: { value: 5 },
+      })
+    ).rejects.toThrow('Omit max_idle_time_minutes for Android sessions.');
+    expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
+    expect(waitForDeviceRunSessionStoppedAsync).not.toHaveBeenCalled();
+  });
+
   it('reports the session token when serve-sim minted one', async () => {
     jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
       openPreviewAsync: jest.fn().mockResolvedValue({
@@ -97,6 +139,7 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
         previewToken: 'tok-1',
         closeAsync: jest.fn(),
       }),
+      getLastPreviewActivityAt: jest.fn(),
       finishAsync: stopAsync,
     });
 
@@ -124,6 +167,7 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
         apiUrl: 'https://web-preview.example.test',
         closeAsync: jest.fn(),
       }),
+      getLastPreviewActivityAt: jest.fn(),
       finishAsync: stopAsync,
     });
 
@@ -151,6 +195,7 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
         apiUrl: 'https://web-preview.example.test',
         closeAsync: jest.fn(),
       }),
+      getLastPreviewActivityAt: jest.fn(),
       finishAsync: stopAsync,
     });
     await runAsync(BuildRuntimePlatform.DARWIN, { public_preview: { value: false } });
@@ -168,6 +213,7 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     if (phase === 'preview') {
       jest.mocked(startDeviceSessionHostAsync).mockResolvedValueOnce({
         openPreviewAsync: jest.fn().mockRejectedValue(error),
+        getLastPreviewActivityAt: jest.fn(),
         finishAsync: stopAsync,
       });
     } else if (phase === 'config') {
@@ -263,6 +309,7 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
       'frame_ancestors',
       'cors_origins',
       'package_version',
+      'max_idle_time_minutes',
       'max_duration_seconds',
     ]);
   });

packages/build-tools/src/steps/functions/__tests__/submitToGooglePlay.test.ts

@@ -198,7 +198,10 @@ it('does not delete the edit or publish outputs when commit outcome is unknown',
       return [204];
     });
   const task = submission();
-  await expect(task.run()).rejects.toBeInstanceOf(SystemError);
+  const error = await task.run().catch(error => error);
+  expect(error).toBeInstanceOf(SystemError);
+  expect((error as Error).message).toContain('HTTP 404');
+  expect((error as Error).message).toContain('Could not confirm whether Google Play saved');
   expect(deleted).toBe(false);
   expect(task.setters.every(set => set.mock.calls.length === 0)).toBe(true);
 });

packages/build-tools/src/steps/functions/__tests__/uploadArtifact.test.ts

@@ -121,26 +121,32 @@ describe(createUploadArtifactBuildFunction, () => {
     expect(typeInput.isRawValueOneOfAllowedValues()).toBe(false);
   });
 
-  it('passes the metadata input through to runtimeApi.uploadArtifact', async () => {
-    contextUploadArtifact.mockClear();
-    const metadata = { kind: 'screen-recording', startedAtMs: '123', device: 'emulator-5554' };
-    const buildStep = uploadArtifact.createBuildStepFromFunctionCall(createGlobalContextMock({}), {
-      callInputs: {
-        // Generic ('other') artifact: only generic artifacts persist metadata in the worker
-        // (the managed-type upload paths drop it), so that's the type metadata is meant for.
-        type: 'other',
-        key: 'Screen Recording',
-        path: '/',
-        metadata,
-      },
-    });
+  it.each(['other', 'android-apk', 'android-aab', 'ios-simulator-app', 'ios-ipa'])(
+    'uploads %s as a workflow artifact with metadata',
+    async type => {
+      contextUploadArtifact.mockClear();
+      const metadata = { kind: 'screen-recording', startedAtMs: '123', device: 'emulator-5554' };
+      const buildStep = uploadArtifact.createBuildStepFromFunctionCall(
+        createGlobalContextMock({}),
+        {
+          callInputs: {
+            type,
+            key: 'Screen Recording',
+            path: '/',
+            metadata,
+          },
+        }
+      );
 
-    await buildStep.executeAsync();
+      await buildStep.executeAsync();
 
-    expect(contextUploadArtifact).toHaveBeenCalledWith(
-      expect.objectContaining({ artifact: expect.objectContaining({ metadata }) })
-    );
-  });
+      expect(contextUploadArtifact).toHaveBeenCalledWith(
+        expect.objectContaining({
+          artifact: expect.objectContaining({ type: null, metadata }),
+        })
+      );
+    }
+  );
 
   it('does not attach metadata to managed artifact types (the worker drops it)', async () => {
     contextUploadArtifact.mockClear();

packages/build-tools/src/steps/functions/__tests__/uploadDeviceRunSessionScreenRecordings.test.ts

@@ -140,9 +140,12 @@ describe(createUploadDeviceRunSessionScreenRecordingsBuildFunction, () => {
 
       await buildStep.executeAsync();
 
-      const names = jest
+      const uploads = jest
         .mocked(uploadDeviceRunSessionArtifactAsync)
-        .mock.calls.map(([, options]) => options.name);
+        .mock.calls.map(([, options]) => options);
+      const names = uploads
+        .filter(options => options.kind === 'screen-recording')
+        .map(options => options.name);
       expect(names).toEqual(
         expect.arrayContaining([
           'iPhone 16 screen recording (01234567-…, started at Jul 10, 2026, 10:00:00.000 UTC)',
@@ -151,6 +154,12 @@ describe(createUploadDeviceRunSessionScreenRecordingsBuildFunction, () => {
         ])
       );
       expect(new Set(names).size).toBe(3);
+      const metadata = uploads.filter(options => options.kind === 'screen-recording-metadata');
+      expect(metadata.map(options => options.name)).toEqual(
+        expect.arrayContaining(names.map(name => `${name} metadata`))
+      );
+      expect(metadata).toHaveLength(3);
+      expect(uploads).toHaveLength(6);
     } finally {
       await Promise.all(
         recordingDirectories.map(directory => fs.rm(directory, { recursive: true, force: true }))

packages/build-tools/src/steps/functions/__tests__/uploadToAsc.test.ts

@@ -1,7 +1,17 @@
+import { UserError } from '@expo/eas-build-job';
+import fs from 'fs-extra';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { AscApiClient } from '../../utils/ios/AscApiClient';
+import { AscApiUtils } from '../../utils/ios/AscApiUtils';
 import {
+  createUploadToAscBuildFunction,
   isClosedVersionTrainError,
   isInvalidBundleIdentifierError,
+  isMissingAppIconsError,
+  isMissingBackgroundTaskIdentifiersError,
   isMissingPurposeStringError,
+  isRedundantBinaryUploadError,
   isSdkVersionIssueError,
   parseMissingUsageDescriptionKeys,
 } from '../uploadToAsc';
@@ -45,6 +55,20 @@ describe(isInvalidBundleIdentifierError, () => {
   });
 });
 
+describe(isRedundantBinaryUploadError, () => {
+  it('returns true when all errors are redundant-binary-upload codes', () => {
+    expect(isRedundantBinaryUploadError([{ code: '90189' }, { code: '90189' }])).toBe(true);
+  });
+
+  it('returns false when any other error code is present', () => {
+    expect(isRedundantBinaryUploadError([{ code: '90189' }, { code: '90062' }])).toBe(false);
+  });
+
+  it('returns false when there are no errors', () => {
+    expect(isRedundantBinaryUploadError([])).toBe(false);
+  });
+});
+
 describe(isMissingPurposeStringError, () => {
   it('returns true when all errors are missing-purpose-string codes', () => {
     expect(isMissingPurposeStringError([{ code: '90683' }, { code: '90683' }])).toBe(true);
@@ -73,6 +97,41 @@ describe(isSdkVersionIssueError, () => {
   });
 });
 
+describe(isMissingBackgroundTaskIdentifiersError, () => {
+  it('returns true when all errors are missing BG task identifiers codes', () => {
+    expect(isMissingBackgroundTaskIdentifiersError([{ code: '90771' }, { code: '90771' }])).toBe(
+      true
+    );
+  });
+
+  it('returns false when any other error code is present', () => {
+    expect(isMissingBackgroundTaskIdentifiersError([{ code: '90771' }, { code: '90062' }])).toBe(
+      false
+    );
+  });
+
+  it('returns false when there are no errors', () => {
+    expect(isMissingBackgroundTaskIdentifiersError([])).toBe(false);
+  });
+});
+
+describe(isMissingAppIconsError, () => {
+  it.each([['90391', '90713', '90713'], ['90713', '90022', '90023'], ['90022'], ['90023']])(
+    'recognizes missing-icon validation codes %j',
+    (...codes) => {
+      expect(isMissingAppIconsError(codes.map(code => ({ code })))).toBe(true);
+    }
+  );
+
+  it('returns false when any other error code is present', () => {
+    expect(isMissingAppIconsError([{ code: '90391' }, { code: '90771' }])).toBe(false);
+  });
+
+  it('returns false when there are no errors', () => {
+    expect(isMissingAppIconsError([])).toBe(false);
+  });
+});
+
 describe(parseMissingUsageDescriptionKeys, () => {
   it('extracts missing UsageDescription keys from ASC messages', () => {
     expect(
@@ -110,3 +169,176 @@ describe(parseMissingUsageDescriptionKeys, () => {
     ).toEqual([]);
   });
 });
+
+describe(createUploadToAscBuildFunction, () => {
+  it('keeps Apple duplicate-build details in the public error and the full state as its cause', async () => {
+    const state = {
+      state: 'FAILED',
+      errors: [
+        {
+          code: '90189',
+          description: 'Redundant Binary Upload. Build number 1 was already uploaded.',
+        },
+      ],
+      warnings: [{ code: 'WARNING', description: 'Apple warning.' }],
+      infos: [{ code: 'INFO', description: 'Apple information.' }],
+    };
+    await fs.writeFile('/app.ipa', 'ipa');
+    await fs.writeFile('/key.json', '{}');
+    jest.spyOn(AscApiUtils, 'loadApiKeyAsync').mockResolvedValue({} as never);
+    jest.spyOn(AscApiUtils, 'getAppInfoAsync').mockResolvedValue({
+      data: { attributes: { name: 'App', bundleId: 'com.example.app' } },
+    } as never);
+    jest.spyOn(AscApiUtils, 'createBuildUploadAsync').mockResolvedValue({
+      data: { id: 'upload-id' },
+    } as never);
+    jest.spyOn(AscApiUtils, 'commitBuildUploadFileAsync').mockResolvedValue(undefined as never);
+    jest.spyOn(AscApiClient.prototype, 'postAsync').mockResolvedValue({
+      data: { id: 'file-id', attributes: { uploadOperations: [] } },
+    } as never);
+    jest
+      .spyOn(AscApiClient.prototype, 'getAsync')
+      .mockResolvedValueOnce({
+        data: { attributes: { assetDeliveryState: { state: 'COMPLETE' } } },
+      } as never)
+      .mockResolvedValueOnce({ data: { attributes: { state } } } as never);
+    try {
+      const step = createUploadToAscBuildFunction().createBuildStepFromFunctionCall(
+        createGlobalContextMock({ staticContextContent: { job: {} } }),
+        {
+          callInputs: {
+            ipa_path: '/app.ipa',
+            asc_api_key_path: '/key.json',
+            apple_app_identifier: 'app-id',
+            bundle_version: '1',
+            bundle_short_version: '1.0',
+            wait_for_processing: true,
+          },
+        }
+      );
+      const error = await step.executeAsync().catch(error => error);
+      expect(error).toBeInstanceOf(UserError);
+      expect(error.errorCode).toBe('EAS_UPLOAD_TO_ASC_VERSION_DUPLICATE');
+      expect(error.cause).toEqual(state);
+      expect(error.toExternalExpoError().message).toContain(
+        'Redundant Binary Upload. Build number 1 was already uploaded. (90189)'
+      );
+    } finally {
+      jest.restoreAllMocks();
+    }
+  });
+});
+
+describe(createUploadToAscBuildFunction, () => {
+  it('keeps Apple background-task details in the public error and the full state as its cause', async () => {
+    const state = {
+      state: 'FAILED',
+      errors: [
+        {
+          code: '90771',
+          description:
+            'Missing BGTaskSchedulerPermittedIdentifiers while UIBackgroundModes includes processing.',
+        },
+      ],
+      warnings: [{ code: 'WARNING', description: 'Apple warning.' }],
+      infos: [{ code: 'INFO', description: 'Apple information.' }],
+    };
+    await fs.writeFile('/app.ipa', 'ipa');
+    await fs.writeFile('/key.json', '{}');
+    jest.spyOn(AscApiUtils, 'loadApiKeyAsync').mockResolvedValue({} as never);
+    jest.spyOn(AscApiUtils, 'getAppInfoAsync').mockResolvedValue({
+      data: { attributes: { name: 'App', bundleId: 'com.example.app' } },
+    } as never);
+    jest.spyOn(AscApiUtils, 'createBuildUploadAsync').mockResolvedValue({
+      data: { id: 'upload-id' },
+    } as never);
+    jest.spyOn(AscApiUtils, 'commitBuildUploadFileAsync').mockResolvedValue(undefined as never);
+    jest.spyOn(AscApiClient.prototype, 'postAsync').mockResolvedValue({
+      data: { id: 'file-id', attributes: { uploadOperations: [] } },
+    } as never);
+    jest
+      .spyOn(AscApiClient.prototype, 'getAsync')
+      .mockResolvedValueOnce({
+        data: { attributes: { assetDeliveryState: { state: 'COMPLETE' } } },
+      } as never)
+      .mockResolvedValueOnce({ data: { attributes: { state } } } as never);
+    try {
+      const step = createUploadToAscBuildFunction().createBuildStepFromFunctionCall(
+        createGlobalContextMock({ staticContextContent: { job: {} } }),
+        {
+          callInputs: {
+            ipa_path: '/app.ipa',
+            asc_api_key_path: '/key.json',
+            apple_app_identifier: 'app-id',
+            bundle_version: '1',
+            bundle_short_version: '1.0',
+            wait_for_processing: true,
+          },
+        }
+      );
+      const error = await step.executeAsync().catch(error => error);
+      expect(error).toBeInstanceOf(UserError);
+      expect(error.errorCode).toBe('EAS_UPLOAD_TO_ASC_MISSING_BG_TASK_IDENTIFIERS');
+      expect(error.cause).toEqual(state);
+      expect(error.toExternalExpoError().message).toContain(
+        'Missing BGTaskSchedulerPermittedIdentifiers while UIBackgroundModes includes processing. (90771)'
+      );
+    } finally {
+      jest.restoreAllMocks();
+    }
+  });
+});
+
+describe(createUploadToAscBuildFunction, () => {
+  it('keeps Apple validation details in the public error and the full state as its cause', async () => {
+    const state = {
+      state: 'FAILED',
+      errors: [{ code: '90713', description: 'Missing CFBundleIconName in Watch.app.' }],
+      warnings: [{ code: 'WARNING', description: 'Apple warning.' }],
+      infos: [{ code: 'INFO', description: 'Apple information.' }],
+    };
+    await fs.writeFile('/app.ipa', 'ipa');
+    await fs.writeFile('/key.json', '{}');
+    jest.spyOn(AscApiUtils, 'loadApiKeyAsync').mockResolvedValue({} as never);
+    jest.spyOn(AscApiUtils, 'getAppInfoAsync').mockResolvedValue({
+      data: { attributes: { name: 'App', bundleId: 'com.example.app' } },
+    } as never);
+    jest.spyOn(AscApiUtils, 'createBuildUploadAsync').mockResolvedValue({
+      data: { id: 'upload-id' },
+    } as never);
+    jest.spyOn(AscApiUtils, 'commitBuildUploadFileAsync').mockResolvedValue(undefined as never);
+    jest.spyOn(AscApiClient.prototype, 'postAsync').mockResolvedValue({
+      data: { id: 'file-id', attributes: { uploadOperations: [] } },
+    } as never);
+    jest
+      .spyOn(AscApiClient.prototype, 'getAsync')
+      .mockResolvedValueOnce({
+        data: { attributes: { assetDeliveryState: { state: 'COMPLETE' } } },
+      } as never)
+      .mockResolvedValueOnce({ data: { attributes: { state } } } as never);
+    try {
+      const step = createUploadToAscBuildFunction().createBuildStepFromFunctionCall(
+        createGlobalContextMock({ staticContextContent: { job: {} } }),
+        {
+          callInputs: {
+            ipa_path: '/app.ipa',
+            asc_api_key_path: '/key.json',
+            apple_app_identifier: 'app-id',
+            bundle_version: '1',
+            bundle_short_version: '1.0',
+            wait_for_processing: true,
+          },
+        }
+      );
+      const error = await step.executeAsync().catch(error => error);
+      expect(error).toBeInstanceOf(UserError);
+      expect(error.errorCode).toBe('EAS_UPLOAD_TO_ASC_MISSING_APP_ICONS');
+      expect(error.cause).toEqual(state);
+      expect(error.toExternalExpoError().message).toContain(
+        'Missing CFBundleIconName in Watch.app. (90713)'
+      );
+    } finally {
+      jest.restoreAllMocks();
+    }
+  });
+});

packages/build-tools/src/steps/functions/__tests__/useNpmToken.test.ts

@@ -0,0 +1,39 @@
+import spawn from '@expo/turtle-spawn';
+import { vol } from 'memfs';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { NpmrcAuthTokenLine } from '../../../templates/npmrc';
+import { createSetUpNpmrcBuildFunction } from '../useNpmToken';
+
+jest.mock('fs');
+jest.mock('@expo/turtle-spawn', () => ({ __esModule: true, default: jest.fn() }));
+
+const projectTargetDirectory = '/workingdir/project';
+const homeDirectory = '/home/expo';
+
+describe(createSetUpNpmrcBuildFunction, () => {
+  beforeEach(async () => {
+    vol.reset();
+    await vol.promises.mkdir(projectTargetDirectory, { recursive: true });
+    await vol.promises.mkdir(homeDirectory, { recursive: true });
+    jest.mocked(spawn).mockResolvedValue({ stdout: `${homeDirectory}/.npmrc\n` } as never);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('adds the NPM_TOKEN placeholder from the step env to ~/.npmrc on EAS Build', async () => {
+    const globalCtx = createGlobalContextMock({ projectTargetDirectory });
+    globalCtx.updateEnv({ NPM_TOKEN: 'npm_secret_token', EAS_BUILD_RUNNER: 'eas-build' });
+    const step = createSetUpNpmrcBuildFunction().createBuildStepFromFunctionCall(globalCtx, {
+      callInputs: {},
+    });
+
+    await step.executeAsync();
+
+    expect(await vol.promises.readFile(`${homeDirectory}/.npmrc`, 'utf8')).toContain(
+      NpmrcAuthTokenLine
+    );
+  });
+});

packages/build-tools/src/steps/functions/checkout.ts

@@ -58,7 +58,11 @@ export function createCheckoutBuildFunction(): BuildFunction {
         });
       }
 
-      stepsCtx.global.markAsCheckedOut(stepsCtx.logger);
+      const previousWorkingDirectory = stepsCtx.global.defaultWorkingDirectory;
+      stepsCtx.global.markAsCheckedOut();
+      stepsCtx.logger.info(
+        `Changing default working directory to ${stepsCtx.global.defaultWorkingDirectory} (was ${previousWorkingDirectory})`
+      );
     },
   });
 }

packages/build-tools/src/steps/functions/collectAndroidEmulatorLogs.ts

@@ -0,0 +1,49 @@
+import {
+  BuildFunction,
+  BuildRuntimePlatform,
+  BuildStepInput,
+  BuildStepInputValueTypeName,
+} from '@expo/steps';
+
+import { type CustomBuildContext } from '../../customBuildContext';
+import { Sentry } from '../../sentry';
+import { AndroidEmulatorLogSourcesSchema } from '../../utils/androidEmulatorLogSources';
+import { collectAndroidEmulatorLogsAsync } from '../utils/androidEmulatorLogs';
+import { getDeviceRunSessionIdOrThrow } from '../utils/remoteDeviceRunSession';
+
+export function createCollectAndroidEmulatorLogsBuildFunction(
+  ctx: CustomBuildContext
+): BuildFunction {
+  return new BuildFunction({
+    namespace: 'eas',
+    id: 'collect_android_emulator_logs',
+    name: 'Collect Android emulator logs',
+    __metricsId: 'eas/collect_android_emulator_logs',
+    supportedRuntimePlatforms: [BuildRuntimePlatform.LINUX],
+    inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'sources',
+        required: false,
+        defaultValue: ['emulator-output'],
+        allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+      }),
+    ],
+    fn: async ({ logger, global }, { inputs, env }) => {
+      try {
+        await collectAndroidEmulatorLogsAsync(ctx, {
+          global,
+          deviceRunSessionId: getDeviceRunSessionIdOrThrow(env),
+          logger,
+          sources: AndroidEmulatorLogSourcesSchema.parse(inputs.sources.value),
+        });
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        Sentry.capture('Could not collect Android emulator logs', error);
+        logger.warn(
+          { err: error },
+          'Could not collect Android logs; the session result is unchanged.'
+        );
+      }
+    },
+  });
+}

packages/build-tools/src/steps/functions/downloadBuild.ts

@@ -7,7 +7,7 @@ import {
   BuildStepInputValueTypeName,
   BuildStepOutput,
 } from '@expo/steps';
-import { Client } from '@urql/core';
+import { Client, CombinedError } from '@urql/core';
 import contentDisposition from 'content-disposition';
 import { glob } from 'fast-glob';
 import { graphql } from 'gql.tada';
@@ -26,10 +26,16 @@ import { CustomBuildContext } from '../../customBuildContext';
 import { formatBytes } from '../../utils/artifacts';
 import { decompressTarAsync, isFileTarGzAsync } from '../../utils/files';
 import { graphqlAbortContext } from '../../utils/graphqlAbort';
-import { retryOnDNSFailure } from '../../utils/retryOnDNSFailure';
+import {
+  describeError,
+  isTransferFailure,
+  isTransientGraphqlError,
+} from '../../utils/networkErrors';
+import { retryOnNetworkFailureAsync } from '../../utils/retryOnNetworkFailure';
 import { pluralize } from '../../utils/strings';
 import {
   type DeviceRunSessionWorkerApi,
+  DeviceRunSessionWorkerApiError,
   getDeviceRunSessionWorkerApi,
 } from '../utils/deviceRunSessionWorkerApi';
 
@@ -152,21 +158,34 @@ async function fetchApplicationArchiveUrlAsync({
       signal,
     });
   }
-  const result = await graphqlClient
-    .query(BUILD_BY_ID_QUERY, { buildId }, graphqlAbortContext(signal))
-    .toPromise();
+  let data;
+  try {
+    data = await retryOnNetworkFailureAsync(
+      async () => {
+        const queryResult = await graphqlClient
+          .query(BUILD_BY_ID_QUERY, { buildId }, graphqlAbortContext(signal))
+          .toPromise();
+        if (queryResult.error) {
+          throw queryResult.error;
+        }
+        return queryResult.data;
+      },
+      {
+        operation: 'download_build.build_lookup',
+        signal,
+        isRetryable: error => error instanceof CombinedError && isTransientGraphqlError(error),
+      }
+    );
+  } catch (error) {
+    signal?.throwIfAborted();
+    const message = `Could not fetch build ${buildId}: ${describeError(error)}`;
+    throw error instanceof CombinedError && !isTransientGraphqlError(error)
+      ? new UserError('EAS_DOWNLOAD_BUILD_FETCH_FAILED', message, { cause: error })
+      : new SystemError(message, { cause: error });
+  }
   signal?.throwIfAborted();
 
-  if (result.error) {
-    const { error } = result;
-    const message = `Could not fetch build ${buildId}: ${error.message}`;
-
-    throw error.networkError || result.error.response?.status >= 500
-      ? new SystemError(message, { cause: error })
-      : new UserError('EAS_DOWNLOAD_BUILD_FETCH_FAILED', message, { cause: error });
-  }
-
-  const applicationArchiveUrl = result.data?.builds.byId?.artifacts?.applicationArchiveUrl;
+  const applicationArchiveUrl = data?.builds.byId?.artifacts?.applicationArchiveUrl;
   if (!applicationArchiveUrl) {
     throw new UserError(
       'EAS_DOWNLOAD_BUILD_NO_APPLICATION_ARCHIVE',
@@ -195,13 +214,18 @@ async function fetchDeviceRunSessionApplicationArchiveUrlAsync({
 }): Promise<string> {
   let application;
   try {
-    application = await deviceRunSessionWorkerApi.getApplicationAsync({ signal });
+    application = await retryOnNetworkFailureAsync(
+      () => deviceRunSessionWorkerApi.getApplicationAsync({ signal }),
+      {
+        operation: 'download_build.session_build_lookup',
+        signal,
+        isRetryable: error => error instanceof DeviceRunSessionWorkerApiError && error.isTransient,
+      }
+    );
   } catch (err) {
     signal?.throwIfAborted();
     throw new SystemError(
-      `Could not fetch build ${buildId} for this device run session: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
+      `Could not fetch build ${buildId} for this device run session: ${describeError(err)}`,
       { cause: err }
     );
   }
@@ -281,18 +305,48 @@ export async function downloadBuildAsync(
   );
 
   signal?.throwIfAborted();
-  const response = await retryOnDNSFailure(fetch)(downloadUrl, { headers, signal });
-
-  if (!response.ok) {
-    const textResult = await asyncResult(response.text());
-    throw new Error(`Unexpected response from server (${response.status}): ${textResult.value}`);
+  let archivePath: string;
+  try {
+    archivePath = await retryOnNetworkFailureAsync(
+      async () => {
+        const response = await fetch(downloadUrl, { headers, signal });
+        if (!response.ok) {
+          const textResult = await asyncResult(response.text());
+          const archiveUrl = new URL(downloadUrl);
+          const source = params.buildId
+            ? `application archive for build ${params.buildId}`
+            : `archive at ${archiveUrl.origin}${archiveUrl.pathname}`;
+          if (response.status === 404 || response.status === 410) {
+            throw new UserError(
+              'EAS_DOWNLOAD_BUILD_ARCHIVE_UNAVAILABLE',
+              `Failed to download the ${source} (HTTP ${response.status}). ` +
+                'The archive is unavailable. ' +
+                (params.buildId
+                  ? 'Check that the archive still exists and try again.'
+                  : 'Check that the URL is correct and the archive still exists, then try again.')
+            );
+          }
+          throw new Error(
+            `Failed to download the ${source} (HTTP ${response.status}): ${textResult.value}`
+          );
+        }
+        const archiveFilename = resolveArchiveFilename({ response, extensions });
+        const attemptArchivePath = path.join(downloadDestinationDirectory, archiveFilename);
+        // On abort, node-fetch emits an error on the body stream, which fails the pipeline.
+        await streamPipeline(response.body, fs.createWriteStream(attemptArchivePath));
+        return attemptArchivePath;
+      },
+      { operation: 'download_build.archive_download', signal, isRetryable: isTransferFailure }
+    );
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (params.buildId && isTransferFailure(error)) {
+      throw new SystemError(`Could not download the application archive: ${describeError(error)}`, {
+        cause: error,
+      });
+    }
+    throw error;
   }
-
-  const archiveFilename = resolveArchiveFilename({ response, extensions });
-  const archivePath = path.join(downloadDestinationDirectory, archiveFilename);
-
-  // On abort, node-fetch emits an error on the body stream, which fails the pipeline.
-  await streamPipeline(response.body, fs.createWriteStream(archivePath));
   signal?.throwIfAborted();
 
   const { size } = await fs.promises.stat(archivePath);

packages/build-tools/src/steps/functions/launchApplication.ts

@@ -1,4 +1,4 @@
-import { UserError } from '@expo/eas-build-job';
+import { UserError, quoteAndroidShellCommand } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import {
   BuildFunction,
@@ -106,24 +106,40 @@ export async function launchApplicationAsync({
   logApplicationLaunch(logger, applicationIdentifier, launchArgs);
   // Android does not support process arguments like iOS. Pass raw `am start` Intent
   // arguments instead, such as `--es key value` or `--ez key true`.
-  await spawn(
-    'adb',
-    ['shell', 'am', 'start', ...launchArgs, '-n', `${applicationIdentifier}/${activityName}`],
-    {
-      env,
-      logger,
+  try {
+    await spawnAndroidShellCommandAsync(
+      ['am', 'start', ...launchArgs, '-n', `${applicationIdentifier}/${activityName}`],
+      { env, logger }
+    );
+  } catch (err) {
+    // An empty argument that is not an option value reaches `am start` as an empty package, and
+    // `am start` then fails to resolve the Intent without saying why.
+    const emptyArgumentIndex = launchArgs.indexOf('');
+    if (emptyArgumentIndex === -1 || err instanceof UserError) {
+      throw err;
     }
-  );
+    throw new UserError(
+      'EAS_LAUNCH_APPLICATION_FAILED',
+      `Launching ${applicationIdentifier} failed. Input "launch_args" has an empty argument at position ${emptyArgumentIndex + 1}, which Android passes to "am start" as an empty argument. Remove it unless it is an option value, such as "--es", "key", "".`,
+      { cause: err }
+    );
+  }
   if (openUrl) {
     logger.info(`Opening ${openUrl} in ${applicationIdentifier}.`);
-    await spawn(
-      'adb',
-      ['shell', 'am', 'start', '-a', 'android.intent.action.VIEW', '-d', openUrl],
+    await spawnAndroidShellCommandAsync(
+      ['am', 'start', '-a', 'android.intent.action.VIEW', '-d', openUrl],
       { env, logger }
     );
   }
 }
 
+async function spawnAndroidShellCommandAsync(
+  command: string[],
+  { env, logger }: { env: BuildStepEnv; logger: bunyan }
+): Promise<void> {
+  await spawn('adb', ['shell', ...quoteAndroidShellCommand(command)], { env, logger });
+}
+
 async function preapproveIosUrlSchemeAsync({
   applicationIdentifier,
   openUrl,

packages/build-tools/src/steps/functions/maestroTests.ts

@@ -1,4 +1,4 @@
-import { GenericArtifactType, SystemError, UserError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import {
   BuildFunction,
@@ -631,7 +631,7 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
         try {
           await ctx.runtimeApi.uploadArtifact({
             artifact: {
-              type: GenericArtifactType.OTHER,
+              type: null,
               name: selectedReport.name,
               paths: [selectedReport.artifactPath],
             },
@@ -738,7 +738,7 @@ async function uploadFailureScreenshotsAsync({
         await fs.copyFile(shot.fileAbsPath, safePath);
         await ctx.runtimeApi.uploadArtifact({
           artifact: {
-            type: GenericArtifactType.OTHER,
+            type: null,
             name: shot.displayName,
             paths: [safePath],
             metadata: shot.metadata,

packages/build-tools/src/steps/functions/repack.ts

@@ -23,7 +23,7 @@ import resolveFrom from 'resolve-from';
 
 import { COMMON_FASTLANE_ENV } from '../../common/fastlane';
 import IosCredentialsManager from '../utils/ios/credentials/manager';
-import { resolvePackageVersionAsync } from '../../utils/packageManager';
+import { installIsolatedNpmPackageAsync } from '../../utils/installIsolatedNpmPackageAsync';
 
 export function createRepackBuildFunction(): BuildFunction {
   return new BuildFunction({
@@ -121,18 +121,12 @@ export function createRepackBuildFunction(): BuildFunction {
         : undefined;
       const jsBundleOnly = (inputs.js_bundle_only.value as boolean | undefined) ?? false;
 
-      const resolvedRepackVersion =
-        (await resolvePackageVersionAsync({
-          logger: stepsCtx.logger,
-          packageName: inputs.repack_package.value as string,
-          distTag: inputs.repack_version.value as string,
-        })) ?? (inputs.repack_version.value as string);
-      stepsCtx.logger.info(
-        `Using repack from: ${inputs.repack_package.value}@${inputs.repack_version.value} (${resolvedRepackVersion})`
-      );
       const repackApp = await installAndImportRepackAsync({
         packageName: inputs.repack_package.value as string,
-        version: resolvedRepackVersion,
+        versionSpec: inputs.repack_version.value as string,
+        pathEnv: env.PATH,
+        npmCacheUrl: env.EAS_BUILD_NPM_CACHE_URL,
+        logger: stepsCtx.logger,
       });
       const { repackAppIosAsync, repackAppAndroidAsync } = repackApp;
 
@@ -226,16 +220,28 @@ function createOutputPath({
  */
 async function installAndImportRepackAsync({
   packageName,
-  version,
+  versionSpec,
+  pathEnv,
+  npmCacheUrl,
+  logger,
 }: {
   packageName: string;
-  version: string;
+  versionSpec: string;
+  pathEnv: string | undefined;
+  npmCacheUrl: string | undefined;
+  logger: bunyan;
 }): Promise<typeof import('@expo/repack-app')> {
   const sandbox = await fs.promises.mkdtemp(path.join(os.tmpdir(), `repack-package-root-`));
-  await spawnAsync('yarn', ['add', `${packageName}@${version}`], {
-    stdio: 'inherit',
-    cwd: sandbox,
+  await installIsolatedNpmPackageAsync({
+    packageSpec: `${packageName}@${versionSpec}`,
+    directory: sandbox,
+    npmCacheUrl,
+    pathEnv,
+    logger,
   });
+  const packageJsonPath = path.join(sandbox, 'node_modules', packageName, 'package.json');
+  const { version } = JSON.parse(await fs.promises.readFile(packageJsonPath, 'utf8'));
+  logger.info(`Using repack from: ${packageName}@${versionSpec} (${version})`);
   return require(resolveFrom(sandbox, packageName));
 }
 

packages/build-tools/src/steps/functions/saveCache.ts

@@ -11,6 +11,7 @@ import path from 'path';
 import * as tar from 'tar';
 import z from 'zod';
 
+import { uploadWithSignedUrl } from '../../storage/uploadWithSignedUrl';
 import { formatBytes } from '../../utils/artifacts';
 import { retryOnDNSFailure } from '../../utils/retryOnDNSFailure';
 import { getCacheVersion } from '../utils/cache';
@@ -161,16 +162,13 @@ export async function uploadCacheAsync({
 
   logger.info(`Uploading cache...`);
 
-  const uploadResponse = await retryOnDNSFailure(fetch)(new URL(url), {
-    method: 'PUT',
-    headers,
-    body: fs.createReadStream(archivePath),
-  });
-  if (!uploadResponse.ok) {
-    throw new Error(
-      `Unexpected response from cache server (${uploadResponse.status}): ${uploadResponse.statusText}`
-    );
-  }
+  await uploadWithSignedUrl(
+    {
+      signedUrl: { url, headers },
+      srcGeneratorAsync: async () => fs.createReadStream(archivePath),
+    },
+    { retries: 3, retryIntervalMs: 100 }
+  );
   logger.info(`Uploaded cache archive to ${archivePath} (${formatBytes(size)}).`);
 }
 
@@ -226,16 +224,13 @@ export async function uploadPublicCacheAsync({
 
   logger.info(`Uploading public cache...`);
 
-  const uploadResponse = await retryOnDNSFailure(fetch)(new URL(url), {
-    method: 'PUT',
-    headers,
-    body: fs.createReadStream(archivePath),
-  });
-  if (!uploadResponse.ok) {
-    throw new Error(
-      `Unexpected response from cache server (${uploadResponse.status}): ${uploadResponse.statusText}`
-    );
-  }
+  await uploadWithSignedUrl(
+    {
+      signedUrl: { url, headers },
+      srcGeneratorAsync: async () => fs.createReadStream(archivePath),
+    },
+    { retries: 3, retryIntervalMs: 100 }
+  );
   logger.info(`Uploaded cache archive to ${archivePath} (${formatBytes(size)}).`);
 }
 

packages/build-tools/src/steps/functions/startAgentDeviceRemoteSession.ts

@@ -225,7 +225,7 @@ export async function runAgentDeviceRemoteSessionAsync(
     tasks.signal.throwIfAborted();
     logger.info(tasks.summary());
 
-    await uploadRemoteSessionConfigWithLocalEgressAsync({
+    const sessionStart = await uploadRemoteSessionConfigWithLocalEgressAsync({
       env,
       signal,
       ctx,
@@ -239,6 +239,9 @@ export async function runAgentDeviceRemoteSessionAsync(
       },
       logger,
     });
+    if (sessionStart === 'stopped') {
+      return;
+    }
     tasks.signal.throwIfAborted();
     void pollAgentDeviceArtifactsForUploadAsync(ctx, {
       deviceRunSessionId,
@@ -265,6 +268,7 @@ export async function runAgentDeviceRemoteSessionAsync(
           ? {
               maxIdleTimeMinutes,
               getLastEventObservedAt: eventCollection.getLastEventObservedAt,
+              getLastPreviewActivityAt: () => sessionHost?.getLastPreviewActivityAt(),
             }
           : undefined,
     });

packages/build-tools/src/steps/functions/startAgentDeviceSession.ts

@@ -1,4 +1,4 @@
-import { UserError } from '@expo/eas-build-job';
+import { UserError, validateAndroidLaunchOptions } from '@expo/eas-build-job';
 import {
   BuildFunction,
   BuildRuntimePlatform,
@@ -16,6 +16,11 @@ import {
   AndroidVirtualDeviceName,
 } from '../../utils/AndroidEmulatorUtils';
 import { getDeviceRunSessionWorkerApi } from '../utils/deviceRunSessionWorkerApi';
+import {
+  AndroidEmulatorLogSourcesSchema,
+  LEGACY_ANDROID_EMULATOR_LOG_SOURCES,
+} from '../../utils/androidEmulatorLogSources';
+import { registerAndroidEmulatorLogDirectory } from '../utils/androidEmulatorLogs';
 import { withLocalEgressSession } from '../utils/localEgressSession';
 import {
   createCorsOriginsInputProvider,
@@ -66,6 +71,12 @@ export function createStartAgentDeviceSessionBuildFunction(ctx: CustomBuildConte
     name: 'Start agent-device session',
     __metricsId: 'eas/start_agent_device_session',
     inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'android_log_sources',
+        required: false,
+        defaultValue: [...LEGACY_ANDROID_EMULATOR_LOG_SOURCES],
+        allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+      }),
       // Device. On iOS a Simulator name or UDID, on Android an AVD hardware profile.
       BuildStepInput.createProvider({
         id: 'device_identifier',
@@ -164,6 +175,8 @@ export function createStartAgentDeviceSessionBuildFunction(ctx: CustomBuildConte
       }
       if (isIos) {
         validateServeSimLaunchOptions({ launchArgs, openUrl });
+      } else {
+        validateAndroidLaunchOptions({ launchArgs, openUrl });
       }
       const deviceIdentifier = inputs.device_identifier.value as string | undefined;
       const capture = parseNetworkCaptureInputs(
@@ -202,9 +215,13 @@ export function createStartAgentDeviceSessionBuildFunction(ctx: CustomBuildConte
         const booted = iosSimulatorUdid
           ? undefined
           : tasks.run('Android Emulator boot', async taskLogger => {
+              const logSources = AndroidEmulatorLogSourcesSchema.parse(
+                inputs.android_log_sources.value
+              );
               const logcatDirectory = await fs.promises.mkdtemp(
                 path.join(os.tmpdir(), 'eas-android-emulator-logcat-')
               );
+              registerAndroidEmulatorLogDirectory(global, logcatDirectory);
               tasks.signal.throwIfAborted();
               await startAndroidEmulatorAsync({
                 deviceName: ANDROID_DEVICE_NAME,
@@ -214,6 +231,7 @@ export function createStartAgentDeviceSessionBuildFunction(ctx: CustomBuildConte
                 lcdHeight: inputs.lcd_height.value as number | undefined,
                 lcdDensity: inputs.lcd_density.value as number | undefined,
                 logcatDirectory,
+                logSources,
                 env,
                 logger: taskLogger,
               });

packages/build-tools/src/steps/functions/startAndroidEmulator.ts

@@ -22,6 +22,12 @@ import {
 } from '../../utils/AndroidEmulatorUtils';
 import { retryAsync } from '../../utils/retry';
 import { resolveAndroidEmulatorLocalEgressAsync } from '../utils/androidLocalEgress';
+import {
+  type AndroidEmulatorLogSource,
+  AndroidEmulatorLogSourcesSchema,
+  LEGACY_ANDROID_EMULATOR_LOG_SOURCES,
+} from '../../utils/androidEmulatorLogSources';
+import { registerAndroidEmulatorLogDirectory } from '../utils/androidEmulatorLogs';
 
 const ANDROID_STARTUP_ATTEMPT_TIMEOUT_MS = [60_000, 120_000, 180_000];
 const ANDROID_STARTUP_RETRIES_COUNT = ANDROID_STARTUP_ATTEMPT_TIMEOUT_MS.length - 1;
@@ -33,6 +39,12 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
     name: 'Start Android Emulator',
     __metricsId: 'eas/start_android_emulator',
     inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'android_log_sources',
+        required: false,
+        defaultValue: [...LEGACY_ANDROID_EMULATOR_LOG_SOURCES],
+        allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+      }),
       BuildStepInput.createProvider({
         id: 'device_name',
         required: false,
@@ -78,10 +90,12 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
         required: true,
       }),
     ],
-    fn: async ({ logger }, { inputs, outputs, env }) => {
+    fn: async ({ logger, global }, { inputs, outputs, env }) => {
+      const logSources = AndroidEmulatorLogSourcesSchema.parse(inputs.android_log_sources.value);
       const logcatDirectory = await fs.promises.mkdtemp(
         path.join(os.tmpdir(), 'eas-android-emulator-logcat-')
       );
+      registerAndroidEmulatorLogDirectory(global, logcatDirectory);
       outputs.logcat_directory.set(logcatDirectory);
 
       const deviceName = `${inputs.device_name.value}` as AndroidVirtualDeviceName;
@@ -95,6 +109,7 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
           lcdHeight: inputs.lcd_height.value as number | undefined,
           lcdDensity: inputs.lcd_density.value as number | undefined,
           logcatDirectory,
+          logSources,
           env,
           logger,
         });
@@ -133,6 +148,7 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
                   deviceName: cloneIdentifier,
                   env,
                   logcatDirectory,
+                  logSources,
                 });
                 cloneSerialId = startResult.serialId;
 
@@ -202,6 +218,7 @@ export async function startAndroidEmulatorAsync({
   lcdHeight,
   lcdDensity,
   logcatDirectory,
+  logSources,
   env,
   logger,
 }: {
@@ -212,6 +229,7 @@ export async function startAndroidEmulatorAsync({
   lcdHeight?: number;
   lcdDensity?: number;
   logcatDirectory: string;
+  logSources?: readonly AndroidEmulatorLogSource[];
   env: BuildStepEnv;
   logger: bunyan;
 }): Promise<{
@@ -293,6 +311,7 @@ export async function startAndroidEmulatorAsync({
           deviceName,
           env,
           logcatDirectory,
+          logSources,
           ...(localEgress ? { launchGate: localEgress.launchGate } : {}),
         });
         attemptSerialId = startResult.serialId;

packages/build-tools/src/steps/functions/startAppiumRemoteSession.ts

@@ -1,6 +1,6 @@
 import { SystemError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
-import { asyncResult } from '@expo/results';
+import { type Result, asyncResult } from '@expo/results';
 import {
   BuildFunction,
   BuildRuntimePlatform,
@@ -8,10 +8,11 @@ import {
   BuildStepInput,
   BuildStepInputValueTypeName,
 } from '@expo/steps';
-import spawn from '@expo/turtle-spawn';
+import spawn, { type SpawnOptions, type SpawnResult } from '@expo/turtle-spawn';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { setTimeout as setTimeoutAsync } from 'node:timers/promises';
 import semver from 'semver';
 import { z } from 'zod';
 
@@ -21,17 +22,19 @@ import {
   withLocalEgressSession,
 } from '../utils/localEgressSession';
 import { type DeviceSessionHost, startDeviceSessionHostAsync } from '../utils/deviceSessionHost';
+import { resolveIosSessionStartupAsync } from '../utils/iosSimulatorSession';
 import {
   createNetworkCaptureInputProviders,
   parseNetworkCaptureInputs,
 } from '../utils/networkCaptureFields';
 import { AndroidEmulatorUtils } from '../../utils/AndroidEmulatorUtils';
-import { IosSimulatorUtils } from '../../utils/IosSimulatorUtils';
+import { IosSimulatorUtils, type IosSimulatorUuid } from '../../utils/IosSimulatorUtils';
 import {
   PackageManager,
   resolveConfiguredPackageManager,
   resolvePackageAdd,
 } from '../../utils/packageManager';
+import { killProcessGroup } from '../../utils/processes';
 import { sleepAsync } from '../../utils/retry';
 import { turtleFetch } from '../../utils/turtleFetch';
 import { startAppiumEventCollectionAsync } from '../utils/appiumEvents';
@@ -39,6 +42,7 @@ import { preparePreinstalledWdaAsync } from '../utils/preinstalledWda';
 import {
   createCorsOriginsInputProvider,
   createFrameAncestorsInputProvider,
+  createIosSessionStartupInputProviders,
   createPrivatePreviewUrlInputProvider,
   createPublicPreviewInputProvider,
   createServeSimLaunchInputProviders,
@@ -51,7 +55,6 @@ import {
   omitNgrokAuthtoken,
   parseCorsOriginsInput,
   parseFrameAncestorsInput,
-  parseServeSimLaunchInputs,
   selectXcodeDeveloperDirectoryAsync,
   spawnDetached,
   startNgrokTunnelAsync,
@@ -62,6 +65,7 @@ const APPIUM_HOST = '127.0.0.1';
 const APPIUM_PORT = 4723;
 const APPIUM_STARTUP_TIMEOUT_MS = 120_000;
 const DEFAULT_APPIUM_VERSION = '^3';
+const FDA_HELPER = '/usr/local/libexec/turtle-tcc-fda';
 
 const AppiumInstalledDriversSchema = z.record(
   z.string(),
@@ -78,6 +82,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
     __metricsId: 'eas/start_appium_remote_session',
     inputProviders: [
       ...createServeSimLaunchInputProviders(),
+      ...createIosSessionStartupInputProviders(),
       ...createNetworkCaptureInputProviders(),
       createPublicPreviewInputProvider(),
       createPrivatePreviewUrlInputProvider(),
@@ -102,14 +107,21 @@ export function createStartAppiumRemoteSessionBuildFunction(
       const packageVersion = inputs.package_version.value as string | undefined;
       const maxIdleTimeMinutes = inputs.max_idle_time_minutes.value as number | undefined;
       const { runtimePlatform } = global;
-      const launch = parseServeSimLaunchInputs(
-        {
-          launchAppIdentifier: inputs.launch_app_identifier?.value,
-          launchArgs: inputs.launch_args?.value,
-          openUrl: inputs.open_url?.value,
-        },
-        { runtimePlatform }
-      );
+      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
+        await selectXcodeDeveloperDirectoryAsync({ env, logger });
+      }
+      const { launch, iosStartup } = await resolveIosSessionStartupAsync({
+        runtimePlatform,
+        bootSimulator: inputs.boot_simulator?.value as boolean | undefined,
+        deviceIdentifier: inputs.device_identifier?.value as string | undefined,
+        installAppPath: inputs.install_app_path?.value as string | undefined,
+        launchAppIdentifier: inputs.launch_app_identifier?.value,
+        launchArgs: inputs.launch_args?.value,
+        openUrl: inputs.open_url?.value,
+        env,
+        logger,
+        signal,
+      });
       const { networkCapture, networkCaptureFields } = parseNetworkCaptureInputs(
         {
           networkCapture: inputs.network_capture?.value,
@@ -122,54 +134,135 @@ export function createStartAppiumRemoteSessionBuildFunction(
       logger.info(
         `Starting Appium remote session (version: ${versionSpec}, runtime: ${runtimePlatform}).`
       );
-      const device = await resolveAppiumDeviceAsync({ runtimePlatform, env, logger });
-      // Appium's startRecordingScreen runs ffmpeg on this host: XCUITest encodes the
-      // simulator stream with it, and UiAutomator2 merges long recordings with it. The
-      // macOS session image does not ship ffmpeg, so install it concurrently with Appium.
-      // Both installs settle before the step continues or fails, so no install outlives it.
-      const [appiumInstall] = await Promise.all([
-        asyncResult(
-          installAppiumAsync({ versionSpec, driverName: device.driverName, env, logger })
-        ),
-        ensureFfmpegInstalledOnceAsync({ runtimePlatform, env, logger }),
-      ]);
-      const { appiumHome, appiumBinPath, appiumEnv } = appiumInstall.enforceValue();
-      const wdaCapabilities = await preparePreinstalledWdaAsync({
-        runtimeIdentifier: device.runtimeIdentifier,
-        appiumHome,
-        appiumBinPath,
-        appiumEnv,
-        logger,
-      });
-
-      const appiumProcess = spawnDetached({
-        command: appiumBinPath,
-        args: [
-          '--address',
-          APPIUM_HOST,
-          '--port',
-          String(APPIUM_PORT),
-          '--base-path',
-          '/',
-          '--log-level',
-          'error',
-          // Appium 3 gates session listing (GET /appium/sessions) behind the
-          // session_discovery insecure feature. We rely on it to poll for
-          // Appium Event Timings, so enable it for all drivers.
-          '--allow-insecure',
-          '*:session_discovery',
-          '--default-capabilities',
-          JSON.stringify({ 'appium:eventTimings': true, ...wdaCapabilities }),
-        ],
-        env: appiumEnv,
-        logger,
-      });
+      const device: AppiumDevice = iosStartup
+        ? {
+            platformName: 'iOS',
+            automationName: 'XCUITest',
+            driverName: 'xcuitest',
+            udid: iosStartup.iosSimulatorUdid,
+          }
+        : await resolveAppiumDeviceAsync({ runtimePlatform, env });
+      const startupAbortController = new AbortController();
+      const startupSignal = signal
+        ? AbortSignal.any([signal, startupAbortController.signal])
+        : startupAbortController.signal;
+      const setupSignal = iosStartup ? startupSignal : undefined;
+      let hostStartup: Promise<Result<DeviceSessionHost>> | undefined;
+      let sessionHost: DeviceSessionHost | undefined;
+      let appiumProcess: ReturnType<typeof spawnDetached> | undefined;
+      let appiumHome: string | undefined;
       let eventCollection: Awaited<ReturnType<typeof startAppiumEventCollectionAsync>> | undefined;
       let appiumTunnel: Awaited<ReturnType<typeof startNgrokTunnelAsync>> | undefined;
-      let sessionHost: DeviceSessionHost | undefined;
       let sessionFailed = false;
+      const startHost = () =>
+        startDeviceSessionHostAsync(ctx, {
+          ...iosStartup,
+          previewDeviceId: device.udid,
+          separateLogPhase: true,
+          runtimePlatform,
+          env,
+          logger,
+          timeoutMs: APPIUM_STARTUP_TIMEOUT_MS,
+          disableShare: inputs.public_preview?.value === false,
+          privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
+          frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
+          corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
+          signal: startupSignal,
+          onStartupError: iosStartup ? error => startupAbortController.abort(error) : undefined,
+          ...launch,
+          networkCapture,
+          networkCaptureFields,
+        }).catch(error => {
+          if (iosStartup) {
+            startupAbortController.abort(error);
+          }
+          throw error;
+        });
       try {
-        await waitForAppiumReadyAsync({ appiumProcess, logger });
+        if (iosStartup) {
+          hostStartup = asyncResult(startHost());
+        }
+        // Appium's startRecordingScreen runs ffmpeg on this host: XCUITest encodes the
+        // simulator stream with it, and UiAutomator2 merges long recordings with it. The
+        // macOS session image does not ship ffmpeg, so install it concurrently with Appium.
+        // Both owned installs settle before proceeding; a shared FFmpeg install keeps its owner.
+        const [appiumInstall] = await Promise.all([
+          asyncResult(
+            installAppiumAsync({
+              versionSpec,
+              driverName: device.driverName,
+              env,
+              logger,
+              signal: setupSignal,
+              onError: iosStartup ? error => startupAbortController.abort(error) : undefined,
+            }).catch(error => {
+              if (iosStartup) {
+                startupAbortController.abort(error);
+              }
+              throw error;
+            })
+          ),
+          asyncResult(
+            ensureFfmpegInstalledOnceAsync({ runtimePlatform, env, logger, signal: setupSignal })
+          ),
+        ]);
+        const installation = appiumInstall.enforceValue();
+        appiumHome = installation.appiumHome;
+        setupSignal?.throwIfAborted();
+        const { appiumBinPath, appiumEnv } = installation;
+        const wdaCapabilities = await preparePreinstalledWdaAsync({
+          runtimeIdentifier: iosStartup
+            ? (
+                await IosSimulatorUtils.getDeviceAsync({
+                  udid: iosStartup.iosSimulatorUdid as IosSimulatorUuid,
+                  env,
+                })
+              )?.runtime
+            : device.runtimeIdentifier,
+          appiumHome,
+          appiumBinPath,
+          appiumEnv,
+          logger,
+          signal: setupSignal,
+        });
+
+        setupSignal?.throwIfAborted();
+        const useFdaHelper =
+          runtimePlatform === BuildRuntimePlatform.DARWIN && fs.existsSync(FDA_HELPER);
+        appiumProcess = spawnDetached({
+          command: useFdaHelper ? FDA_HELPER : appiumBinPath,
+          args: [
+            ...(useFdaHelper ? [appiumBinPath] : []),
+            '--address',
+            APPIUM_HOST,
+            '--port',
+            String(APPIUM_PORT),
+            '--base-path',
+            '/',
+            '--log-level',
+            'error',
+            // Appium 3 gates session listing (GET /appium/sessions) behind the
+            // session_discovery insecure feature. We rely on it to poll for
+            // Appium Event Timings, so enable it for all drivers.
+            '--allow-insecure',
+            '*:session_discovery',
+            '--default-capabilities',
+            JSON.stringify({
+              'appium:eventTimings': true,
+              // Without it, XCUITest restarted the booted Simulator at session start, which
+              // closed the app serve-sim had launched. EAS VMs never show the Simulator window.
+              ...(device.platformName === 'iOS' ? { 'appium:isHeadless': true } : {}),
+              ...wdaCapabilities,
+            }),
+          ],
+          env: appiumEnv,
+          logger,
+        });
+        await waitForAppiumReadyAsync({ appiumProcess, logger, signal: setupSignal });
+        if (hostStartup) {
+          sessionHost = (await hostStartup).enforceValue();
+        }
+        setupSignal?.throwIfAborted();
         eventCollection = await startAppiumEventCollectionAsync({
           ctx,
           deviceRunSessionId,
@@ -184,34 +277,18 @@ export function createStartAppiumRemoteSessionBuildFunction(
           logger,
         });
 
-        // expo-device-hub has no serial-selection flag. Device run session workflows must expose
-        // a single booted Android emulator so the Hub and Appium resolve the same device.
+        // The preview host uses the same device selected for Appium.
         const launchDescription = describeServeSimLaunch(launch);
         if (launchDescription) {
           logger.info(launchDescription);
         }
-        sessionHost = await startDeviceSessionHostAsync(ctx, {
-          separateLogPhase: true,
-          runtimePlatform,
-          env,
-          logger,
-          timeoutMs: APPIUM_STARTUP_TIMEOUT_MS,
-          disableShare: inputs.public_preview?.value === false,
-          privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
-          frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
-          corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
-          launchAppIdentifier: launch.launchAppIdentifier,
-          launchArgs: launch.launchArgs,
-          openUrl: launch.openUrl,
-          networkCapture,
-          networkCaptureFields,
-        });
+        sessionHost ??= (await (hostStartup ??= asyncResult(startHost()))).enforceValue();
         const webPreview = await sessionHost.openPreviewAsync({
           baseDomain: ngrokTunnelDomain,
           authtoken: ngrokAuthtoken,
         });
 
-        await uploadRemoteSessionConfigWithLocalEgressAsync({
+        const sessionStart = await uploadRemoteSessionConfigWithLocalEgressAsync({
           env,
           signal,
           ctx,
@@ -229,6 +306,9 @@ export function createStartAppiumRemoteSessionBuildFunction(
           },
           logger,
         });
+        if (sessionStart === 'stopped') {
+          return;
+        }
 
         await waitForDeviceRunSessionStoppedAsync({
           ctx,
@@ -240,13 +320,15 @@ export function createStartAppiumRemoteSessionBuildFunction(
               ? {
                   maxIdleTimeMinutes,
                   getLastEventObservedAt: eventCollection.getLastEventObservedAt,
+                  getLastPreviewActivityAt: () => sessionHost?.getLastPreviewActivityAt(),
                 }
               : undefined,
         });
       } catch (error) {
         sessionFailed = true;
-        throw error;
+        throw setupSignal?.aborted ? setupSignal.reason : error;
       } finally {
+        startupAbortController.abort(new Error('Appium session ended.'));
         await finishRemoteSessionAsync({
           logger,
           sessionFailed,
@@ -259,14 +341,16 @@ export function createStartAppiumRemoteSessionBuildFunction(
                   await eventCollection?.stopAsync();
                 } finally {
                   try {
-                    await appiumProcess.stopAsync();
+                    await appiumProcess?.stopAsync();
                   } finally {
-                    await fs.promises.rm(appiumHome, { recursive: true, force: true });
+                    if (appiumHome) {
+                      await fs.promises.rm(appiumHome, { recursive: true, force: true });
+                    }
                   }
                 }
               })(),
             ],
-            ['session host', sessionHost?.finishAsync()],
+            ['session host', hostStartup?.then(result => result.value?.finishAsync())],
           ],
         });
       }
@@ -296,15 +380,12 @@ export type AppiumDevice = {
 export async function resolveAppiumDeviceAsync({
   runtimePlatform,
   env,
-  logger,
 }: {
   runtimePlatform: BuildRuntimePlatform;
   env: BuildStepEnv;
-  logger: bunyan;
 }): Promise<AppiumDevice> {
   switch (runtimePlatform) {
     case BuildRuntimePlatform.DARWIN: {
-      await selectXcodeDeveloperDirectoryAsync({ env, logger });
       const [bootedDevice] = await IosSimulatorUtils.getAvailableDevicesAsync({
         env,
         filter: 'booted',
@@ -341,65 +422,135 @@ export async function installAppiumAsync({
   driverName,
   env,
   logger,
+  signal,
+  onError,
 }: {
   versionSpec: string;
   driverName: AppiumDevice['driverName'];
   env: BuildStepEnv;
   logger: bunyan;
+  signal?: AbortSignal;
+  onError?: (error: unknown) => void;
 }): Promise<{ appiumHome: string; appiumBinPath: string; appiumEnv: BuildStepEnv }> {
+  signal?.throwIfAborted();
   const appiumHome = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'eas-appium-home-'));
-  await fs.promises.writeFile(
-    path.join(appiumHome, 'package.json'),
-    `${JSON.stringify({ name: 'eas-appium-home', private: true })}\n`
-  );
-  const appiumEnv: BuildStepEnv = { ...env, APPIUM_HOME: appiumHome };
-  const appiumBinPath = path.join(appiumHome, 'node_modules', '.bin', 'appium');
-  const add = resolvePackageAdd(
-    resolveConfiguredPackageManager(env, PackageManager.NPM),
-    `appium@${versionSpec}`
-  );
+  try {
+    signal?.throwIfAborted();
+    await fs.promises.writeFile(
+      path.join(appiumHome, 'package.json'),
+      `${JSON.stringify({ name: 'eas-appium-home', private: true })}\n`
+    );
+    const appiumEnv: BuildStepEnv = { ...env, APPIUM_HOME: appiumHome };
+    const appiumBinPath = path.join(appiumHome, 'node_modules', '.bin', 'appium');
+    const add = resolvePackageAdd(
+      resolveConfiguredPackageManager(env, PackageManager.NPM),
+      `appium@${versionSpec}`
+    );
 
-  logger.info(`Installing appium@${versionSpec} with ${add.command}.`);
-  await spawn(add.command, add.args, {
-    cwd: appiumHome,
-    env: appiumEnv,
-    logger,
-  });
-  const { stdout } = await spawn(appiumBinPath, ['driver', 'list', '--installed', '--json'], {
-    env: appiumEnv,
-    stdio: 'pipe',
-  });
-  const installedDrivers = AppiumInstalledDriversSchema.parse(JSON.parse(stdout));
-  if (installedDrivers[driverName]?.installed) {
-    logger.info(`Updating the installed Appium ${driverName} driver.`);
-    await spawn(appiumBinPath, ['driver', 'update', driverName], { env: appiumEnv, logger });
-  } else {
-    logger.info(`Installing the Appium ${driverName} driver.`);
-    await spawn(appiumBinPath, ['driver', 'install', driverName], { env: appiumEnv, logger });
+    logger.info(`Installing appium@${versionSpec} with ${add.command}.`);
+    await runAppiumSetupCommandAsync(
+      add.command,
+      add.args,
+      {
+        cwd: appiumHome,
+        env: appiumEnv,
+        logger,
+      },
+      signal
+    );
+    const { stdout } = await runAppiumSetupCommandAsync(
+      appiumBinPath,
+      ['driver', 'list', '--installed', '--json'],
+      {
+        env: appiumEnv,
+        stdio: 'pipe',
+      },
+      signal
+    );
+    const installedDrivers = AppiumInstalledDriversSchema.parse(JSON.parse(stdout));
+    if (installedDrivers[driverName]?.installed) {
+      logger.info(`Updating the installed Appium ${driverName} driver.`);
+      await runAppiumSetupCommandAsync(
+        appiumBinPath,
+        ['driver', 'update', driverName],
+        { env: appiumEnv, logger },
+        signal
+      );
+    } else {
+      logger.info(`Installing the Appium ${driverName} driver.`);
+      await runAppiumSetupCommandAsync(
+        appiumBinPath,
+        ['driver', 'install', driverName],
+        { env: appiumEnv, logger },
+        signal
+      );
+    }
+    return { appiumHome, appiumBinPath, appiumEnv };
+  } catch (error) {
+    onError?.(error);
+    if (signal) {
+      await fs.promises.rm(appiumHome, { recursive: true, force: true });
+      signal.throwIfAborted();
+    }
+    throw error;
+  }
+}
+
+async function runAppiumSetupCommandAsync(
+  command: string,
+  args: string[],
+  options: SpawnOptions,
+  signal?: AbortSignal
+): Promise<SpawnResult> {
+  if (!signal) {
+    return await spawn(command, args, options);
+  }
+  signal.throwIfAborted();
+  const task = spawn(command, args, { ...options, detached: true });
+  const abort = (): void => killProcessGroup(task.child, 'SIGKILL');
+  signal.addEventListener('abort', abort, { once: true });
+  if (signal.aborted) {
+    abort();
+  }
+  try {
+    const result = await task;
+    signal.throwIfAborted();
+    return result;
+  } finally {
+    signal.removeEventListener('abort', abort);
   }
-  return { appiumHome, appiumBinPath, appiumEnv };
 }
 
 async function waitForAppiumReadyAsync({
   appiumProcess,
   logger,
+  signal,
 }: {
   appiumProcess: { getOutput: () => string };
   logger: bunyan;
+  signal?: AbortSignal;
 }): Promise<void> {
   const deadline = Date.now() + APPIUM_STARTUP_TIMEOUT_MS;
   while (Date.now() < deadline) {
+    signal?.throwIfAborted();
     try {
       const response = await turtleFetch(`http://${APPIUM_HOST}:${APPIUM_PORT}/status`, 'GET', {
         timeout: 2_000,
         retries: 0,
         logger,
+        signal,
       });
+      signal?.throwIfAborted();
       if (response.ok) {
         return;
       }
     } catch {}
-    await sleepAsync(1_000);
+    signal?.throwIfAborted();
+    if (signal) {
+      await setTimeoutAsync(1_000, undefined, { signal });
+    } else {
+      await sleepAsync(1_000);
+    }
   }
   const output = appiumProcess.getOutput();
   throw new SystemError(

packages/build-tools/src/steps/functions/startArgentRemoteSession.ts

@@ -1,15 +1,17 @@
 import { SystemError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
+import { type Result, asyncResult } from '@expo/results';
 import {
   BuildFunction,
   BuildRuntimePlatform,
   BuildStepInput,
   BuildStepInputValueTypeName,
 } from '@expo/steps';
-import spawn from '@expo/turtle-spawn';
+import spawn, { type SpawnOptions } from '@expo/turtle-spawn';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { setTimeout as setTimeoutAsync } from 'node:timers/promises';
 import semver from 'semver';
 import { z } from 'zod';
 
@@ -19,6 +21,7 @@ import {
   withLocalEgressSession,
 } from '../utils/localEgressSession';
 import { type DeviceSessionHost, startDeviceSessionHostAsync } from '../utils/deviceSessionHost';
+import { resolveIosSessionStartupAsync } from '../utils/iosSimulatorSession';
 import {
   createNetworkCaptureInputProviders,
   parseNetworkCaptureInputs,
@@ -29,13 +32,14 @@ import {
   resolveConfiguredPackageManager,
   resolvePackageExec,
 } from '../../utils/packageManager';
-import { isProcessDescendantOfAsync } from '../../utils/processes';
+import { isProcessDescendantOfAsync, killProcessGroup } from '../../utils/processes';
 import { sleepAsync } from '../../utils/retry';
 import { pollArgentArtifactsForUploadAsync } from '../utils/argentArtifacts';
 import { ARGENT_EVENT_LOG_FILENAME, startArgentEventCollectionAsync } from '../utils/argentEvents';
 import {
   createCorsOriginsInputProvider,
   createFrameAncestorsInputProvider,
+  createIosSessionStartupInputProviders,
   createPrivatePreviewUrlInputProvider,
   createPublicPreviewInputProvider,
   createServeSimLaunchInputProviders,
@@ -48,7 +52,6 @@ import {
   omitNgrokAuthtoken,
   parseCorsOriginsInput,
   parseFrameAncestorsInput,
-  parseServeSimLaunchInputs,
   selectXcodeDeveloperDirectoryAsync,
   spawnDetached,
   startNgrokTunnelAsync,
@@ -90,6 +93,7 @@ export function createStartArgentRemoteSessionBuildFunction(
     __metricsId: 'eas/start_argent_remote_session',
     inputProviders: [
       ...createServeSimLaunchInputProviders(),
+      ...createIosSessionStartupInputProviders(),
       ...createNetworkCaptureInputProviders(),
       createPublicPreviewInputProvider(),
       createPrivatePreviewUrlInputProvider(),
@@ -128,14 +132,21 @@ export function createStartArgentRemoteSessionBuildFunction(
       warnIfArgentPackageVersionCannotBeVerified({ packageVersion, logger });
       const versionSpec = packageVersion ?? 'latest';
       const { runtimePlatform } = global;
-      const launch = parseServeSimLaunchInputs(
-        {
-          launchAppIdentifier: inputs.launch_app_identifier?.value as string | undefined,
-          launchArgs: inputs.launch_args?.value,
-          openUrl: inputs.open_url?.value as string | undefined,
-        },
-        { runtimePlatform }
-      );
+      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
+        await selectXcodeDeveloperDirectoryAsync({ env, logger });
+      }
+      const { launch, iosStartup } = await resolveIosSessionStartupAsync({
+        runtimePlatform,
+        bootSimulator: inputs.boot_simulator?.value as boolean | undefined,
+        deviceIdentifier: inputs.device_identifier?.value as string | undefined,
+        installAppPath: inputs.install_app_path?.value as string | undefined,
+        launchAppIdentifier: inputs.launch_app_identifier?.value,
+        launchArgs: inputs.launch_args?.value,
+        openUrl: inputs.open_url?.value,
+        env,
+        logger,
+        signal,
+      });
       const { networkCapture, networkCaptureFields } = parseNetworkCaptureInputs(
         {
           networkCapture: inputs.network_capture?.value,
@@ -147,10 +158,6 @@ export function createStartArgentRemoteSessionBuildFunction(
         `Starting argent remote session (version: ${versionSpec}, runtime: ${runtimePlatform}).`
       );
 
-      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
-        await selectXcodeDeveloperDirectoryAsync({ env, logger });
-      }
-
       // Start the potentially slow installation while Argent is being prepared.
       // On Linux expo-device-hub calls this again and awaits the same in-flight
       // setup before launching. On macOS this remains non-blocking, so only a
@@ -162,74 +169,124 @@ export function createStartArgentRemoteSessionBuildFunction(
       const argentExec = (args: string[]): { command: string; args: string[] } =>
         resolvePackageExec(packageManager, args);
 
-      logger.info('Enabling the Argent artifacts list endpoint flag.');
-      const enableArtifacts = argentExec([
-        `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
-        'enable',
-        ARGENT_ARTIFACTS_LIST_ENDPOINT_FLAG,
-      ]);
-      await spawn(enableArtifacts.command, enableArtifacts.args, { env, logger });
-
-      logger.info('Enabling the Argent tool-server event log flag.');
-      const enableEventLog = argentExec([
-        `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
-        'enable',
-        ARGENT_EVENT_LOG_FLAG,
-      ]);
-      await spawn(enableEventLog.command, enableEventLog.args, { env, logger });
-
-      logger.info('Disabling the Argent video watermark flag.');
-      const disableVideoWatermark = argentExec([
-        `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
-        'disable',
-        ARGENT_VIDEO_WATERMARK_FLAG,
-      ]);
-      // The watermark is cosmetic, so a failure here must not fail the session.
-      try {
-        await spawn(disableVideoWatermark.command, disableVideoWatermark.args, { env, logger });
-      } catch (err) {
-        logger.warn(
-          { err },
-          'Could not disable the Argent video watermark, so recorded videos may include it. Continuing the session.'
-        );
-      }
-
-      const startServer = argentExec([
-        `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
-        'server',
-        'start',
-        '--port',
-        '0',
-        '--idle-timeout',
-        '0',
-        '--force',
-      ]);
-      logger.info(
-        `Launching ${ARGENT_PACKAGE_NAME}@${versionSpec} tool-server via ${startServer.command}.`
-      );
-      // Keep Argent itself in foreground mode under the detached process. This preserves
-      // the npx/bun -> Argent CLI -> tool-server ancestry used to identify the matching state file.
-      const secrets: string[] = [];
-      const argentServer = spawnDetached({
-        command: startServer.command,
-        args: startServer.args,
-        env: { ...env, ARGENT_EVENT_LOG: ARGENT_EVENT_LOG_PATH, ARGENT_EMULATOR_NO_WINDOW: '1' },
-        logger,
-        secrets,
-      });
-      if (argentServer.pid === undefined) {
-        throw new SystemError(
-          'Failed to start Argent: could not determine the PID of the launched process.'
-        );
-      }
-
+      const startupAbortController = new AbortController();
+      const startupSignal = signal
+        ? AbortSignal.any([signal, startupAbortController.signal])
+        : startupAbortController.signal;
+      const setupSignal = iosStartup ? startupSignal : undefined;
       const artifactPollAbortController = new AbortController();
       let artifactPollingPromise: Promise<void> | undefined;
       let eventCollection: Awaited<ReturnType<typeof startArgentEventCollectionAsync>> | undefined;
       let toolsTunnel: Awaited<ReturnType<typeof startNgrokTunnelAsync>> | undefined;
+      let argentServer: ReturnType<typeof spawnDetached> | undefined;
+      let hostStartup: Promise<Result<DeviceSessionHost>> | undefined;
       let sessionHost: DeviceSessionHost | undefined;
       let sessionFailed = false;
+      const startHost = () =>
+        startDeviceSessionHostAsync(ctx, {
+          ...iosStartup,
+          separateLogPhase: true,
+          runtimePlatform,
+          env,
+          logger,
+          disableShare: inputs.public_preview?.value === false,
+          privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
+          frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
+          corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
+          timeoutMs: STARTUP_TIMEOUT_MS,
+          signal: startupSignal,
+          onStartupError: iosStartup ? error => startupAbortController.abort(error) : undefined,
+          ...launch,
+          networkCapture,
+          networkCaptureFields,
+        }).catch(error => {
+          if (iosStartup) {
+            startupAbortController.abort(error);
+          }
+          throw error;
+        });
       try {
+        if (iosStartup) {
+          hostStartup = asyncResult(startHost());
+        }
+        logger.info('Enabling the Argent artifacts list endpoint flag.');
+        const enableArtifacts = argentExec([
+          `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
+          'enable',
+          ARGENT_ARTIFACTS_LIST_ENDPOINT_FLAG,
+        ]);
+        await runArgentSetupCommandAsync(
+          enableArtifacts.command,
+          enableArtifacts.args,
+          { env, logger },
+          setupSignal
+        );
+
+        logger.info('Enabling the Argent tool-server event log flag.');
+        const enableEventLog = argentExec([
+          `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
+          'enable',
+          ARGENT_EVENT_LOG_FLAG,
+        ]);
+        await runArgentSetupCommandAsync(
+          enableEventLog.command,
+          enableEventLog.args,
+          { env, logger },
+          setupSignal
+        );
+
+        logger.info('Disabling the Argent video watermark flag.');
+        const disableVideoWatermark = argentExec([
+          `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
+          'disable',
+          ARGENT_VIDEO_WATERMARK_FLAG,
+        ]);
+        // The watermark is cosmetic, so a failure here must not fail the session.
+        try {
+          await runArgentSetupCommandAsync(
+            disableVideoWatermark.command,
+            disableVideoWatermark.args,
+            { env, logger },
+            setupSignal
+          );
+        } catch (err) {
+          setupSignal?.throwIfAborted();
+          logger.warn(
+            { err },
+            'Could not disable the Argent video watermark, so recorded videos may include it. Continuing the session.'
+          );
+        }
+
+        setupSignal?.throwIfAborted();
+        const startServer = argentExec([
+          `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
+          'server',
+          'start',
+          '--port',
+          '0',
+          '--idle-timeout',
+          '0',
+          '--force',
+        ]);
+        logger.info(
+          `Launching ${ARGENT_PACKAGE_NAME}@${versionSpec} tool-server via ${startServer.command}.`
+        );
+        // Keep Argent itself in foreground mode under the detached process. This preserves
+        // the npx/bun -> Argent CLI -> tool-server ancestry used to identify the matching state file.
+        const secrets: string[] = [];
+        argentServer = spawnDetached({
+          command: startServer.command,
+          args: startServer.args,
+          env: { ...env, ARGENT_EVENT_LOG: ARGENT_EVENT_LOG_PATH, ARGENT_EMULATOR_NO_WINDOW: '1' },
+          logger,
+          secrets,
+        });
+        if (argentServer.pid === undefined) {
+          throw new SystemError(
+            'Failed to start Argent: could not determine the PID of the launched process.'
+          );
+        }
+
         logger.info(`Waiting for argent tool-server state in ${ARGENT_STATE_DIR}.`);
         let toolServerPort: number;
         let toolServerToken: string | undefined;
@@ -239,6 +296,7 @@ export function createStartArgentRemoteSessionBuildFunction(
             ancestorPid: argentServer.pid,
             timeoutMs: STARTUP_TIMEOUT_MS,
             getExitError: argentServer.getExitError,
+            signal: setupSignal,
           });
           toolServerPort = toolServerState.port;
           toolServerToken = toolServerState.token;
@@ -253,6 +311,10 @@ export function createStartArgentRemoteSessionBuildFunction(
             }${output ? `\nArgent tool-server output:\n${output}` : ''}`
           );
         }
+        if (hostStartup) {
+          sessionHost = (await hostStartup).enforceValue();
+        }
+        setupSignal?.throwIfAborted();
         logger.info(`Argent tool-server is listening on port ${toolServerPort}.`);
         const artifactPollSignal = signal
           ? AbortSignal.any([signal, artifactPollAbortController.signal])
@@ -287,22 +349,7 @@ export function createStartArgentRemoteSessionBuildFunction(
         if (launchDescription) {
           logger.info(launchDescription);
         }
-        sessionHost = await startDeviceSessionHostAsync(ctx, {
-          separateLogPhase: true,
-          runtimePlatform,
-          env,
-          logger,
-          timeoutMs: STARTUP_TIMEOUT_MS,
-          disableShare: inputs.public_preview?.value === false,
-          privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
-          frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
-          corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
-          launchAppIdentifier: launch.launchAppIdentifier,
-          launchArgs: launch.launchArgs,
-          openUrl: launch.openUrl,
-          networkCapture,
-          networkCaptureFields,
-        });
+        sessionHost ??= (await (hostStartup ??= asyncResult(startHost()))).enforceValue();
         const webPreview = await sessionHost.openPreviewAsync({
           baseDomain: ngrokTunnelDomain,
           authtoken: ngrokAuthtoken,
@@ -313,7 +360,7 @@ export function createStartArgentRemoteSessionBuildFunction(
             : 'Private preview URL unavailable for this session.'
         );
 
-        await uploadRemoteSessionConfigWithLocalEgressAsync({
+        const sessionStart = await uploadRemoteSessionConfigWithLocalEgressAsync({
           env,
           signal,
           ctx,
@@ -327,6 +374,9 @@ export function createStartArgentRemoteSessionBuildFunction(
           },
           logger,
         });
+        if (sessionStart === 'stopped') {
+          return;
+        }
 
         await waitForDeviceRunSessionStoppedAsync({
           ctx,
@@ -339,13 +389,15 @@ export function createStartArgentRemoteSessionBuildFunction(
               ? {
                   maxIdleTimeMinutes,
                   getLastEventObservedAt: eventCollection.getLastEventObservedAt,
+                  getLastPreviewActivityAt: () => sessionHost?.getLastPreviewActivityAt(),
                 }
               : undefined,
         });
       } catch (error) {
         sessionFailed = true;
-        throw error;
+        throw setupSignal?.aborted ? setupSignal.reason : error;
       } finally {
+        startupAbortController.abort(new Error('Argent session ended.'));
         await finishRemoteSessionAsync({
           logger,
           sessionFailed,
@@ -377,11 +429,11 @@ export function createStartArgentRemoteSessionBuildFunction(
                     );
                   }
                 } finally {
-                  await argentServer.stopAsync();
+                  await argentServer?.stopAsync();
                 }
               })(),
             ],
-            ['session host', sessionHost?.finishAsync()],
+            ['session host', hostStartup?.then(result => result.value?.finishAsync())],
           ],
         });
       }
@@ -441,6 +493,31 @@ export function warnIfArgentPackageVersionCannotBeVerified({
   }
 }
 
+async function runArgentSetupCommandAsync(
+  command: string,
+  args: string[],
+  options: SpawnOptions,
+  signal?: AbortSignal
+): Promise<void> {
+  if (!signal) {
+    await spawn(command, args, options);
+    return;
+  }
+  signal.throwIfAborted();
+  const task = spawn(command, args, { ...options, detached: true });
+  const abort = (): void => killProcessGroup(task.child, 'SIGKILL');
+  signal.addEventListener('abort', abort, { once: true });
+  if (signal.aborted) {
+    abort();
+  }
+  try {
+    await task;
+    signal.throwIfAborted();
+  } finally {
+    signal.removeEventListener('abort', abort);
+  }
+}
+
 function parseArgentToolServerState(raw: string): ArgentToolServerState {
   let json: unknown;
   try {
@@ -463,13 +540,16 @@ export async function waitForArgentToolServerStateAsync({
   timeoutMs,
   pollIntervalMs = 1_000,
   getExitError,
+  signal,
 }: {
   stateDir: string;
   ancestorPid: number;
   timeoutMs: number;
   pollIntervalMs?: number;
   getExitError?: () => Error | undefined;
+  signal?: AbortSignal;
 }): Promise<ArgentToolServerState> {
+  signal?.throwIfAborted();
   const deadline = Date.now() + timeoutMs;
   let lastError: unknown;
   const throwIfExited = (): void => {
@@ -480,6 +560,7 @@ export async function waitForArgentToolServerStateAsync({
   };
 
   while (Date.now() < deadline) {
+    signal?.throwIfAborted();
     throwIfExited();
     let matchingState: ArgentToolServerState | undefined;
     try {
@@ -505,13 +586,19 @@ export async function waitForArgentToolServerStateAsync({
       lastError = err;
     }
     // Keep process failures outside the retryable state-file read errors.
+    signal?.throwIfAborted();
     throwIfExited();
     if (matchingState) {
       return matchingState;
     }
-    await sleepAsync(pollIntervalMs);
+    if (signal) {
+      await setTimeoutAsync(pollIntervalMs, undefined, { signal });
+    } else {
+      await sleepAsync(pollIntervalMs);
+    }
   }
 
+  signal?.throwIfAborted();
   throw new SystemError(
     `Timed out waiting for an argent tool-server state file belonging to process ${ancestorPid} in ${stateDir}${
       lastError instanceof Error ? `: ${lastError.message}` : ''

packages/build-tools/src/steps/functions/startSandbox.ts

@@ -1,4 +1,4 @@
-import { SystemError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import { BuildFunction, BuildStepInput, BuildStepInputValueTypeName } from '@expo/steps';
 import { graphql } from 'gql.tada';
 
@@ -32,6 +32,11 @@ export function createStartSandboxBuildFunction(ctx: CustomBuildContext): BuildF
         required: true,
         allowedValueTypeName: BuildStepInputValueTypeName.STRING,
       }),
+      BuildStepInput.createProvider({
+        id: 'max_duration_seconds',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.NUMBER,
+      }),
     ],
     fn: async (stepCtx, { inputs, signal, env }) => {
       // The daemon needs this credential, but shell commands do not.
@@ -44,6 +49,18 @@ export function createStartSandboxBuildFunction(ctx: CustomBuildContext): BuildF
         throw new SystemError('MCP server URL is required to start the sandbox daemon.');
       }
       const sandboxId = String(inputs.sandbox_id.value);
+      const maxDurationSeconds = inputs.max_duration_seconds?.value;
+      if (
+        maxDurationSeconds !== undefined &&
+        (typeof maxDurationSeconds !== 'number' ||
+          !Number.isFinite(maxDurationSeconds) ||
+          maxDurationSeconds <= 0)
+      ) {
+        throw new UserError(
+          'EAS_SANDBOX_INVALID_DURATION',
+          `Invalid sandbox maximum duration: ${String(maxDurationSeconds)}. Provide a finite number greater than zero, or omit max_duration_seconds.`
+        );
+      }
       const daemon = await startSandboxDaemonAsync({
         credential: sandboxToken,
         serverUrl: mcpServerUrl,
@@ -63,7 +80,21 @@ export function createStartSandboxBuildFunction(ctx: CustomBuildContext): BuildF
         stepCtx.logger.info('Sandbox daemon started.');
 
         await withLogPhaseAsync(stepCtx.logger, AWAIT_SANDBOX_STEP_NAME, async () => {
-          await waitForCancellationAsync(signal);
+          const timeoutSignal =
+            maxDurationSeconds === undefined
+              ? undefined
+              : AbortSignal.timeout(Math.ceil(maxDurationSeconds * 1000));
+          await waitForCompletionAsync(
+            AbortSignal.any([
+              ...(signal ? [signal] : []),
+              ...(timeoutSignal ? [timeoutSignal] : []),
+            ])
+          );
+          if (timeoutSignal?.aborted) {
+            stepCtx.logger.info(
+              `Sandbox reached its maximum runtime of ${maxDurationSeconds} seconds. Stopping.`
+            );
+          }
         });
       } finally {
         await daemon.stopAsync();
@@ -89,11 +120,11 @@ export async function markSandboxReadyAsync(
   }
 }
 
-async function waitForCancellationAsync(signal?: AbortSignal): Promise<void> {
-  if (signal?.aborted) {
+async function waitForCompletionAsync(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) {
     return;
   }
   await new Promise<void>(resolve => {
-    signal?.addEventListener('abort', () => resolve(), { once: true });
+    signal.addEventListener('abort', () => resolve(), { once: true });
   });
 }

packages/build-tools/src/steps/functions/startWebPreviewRemoteSession.ts

@@ -1,3 +1,4 @@
+import { UserError } from '@expo/eas-build-job';
 import {
   BuildFunction,
   BuildRuntimePlatform,
@@ -57,6 +58,11 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
         required: false,
         allowedValueTypeName: BuildStepInputValueTypeName.STRING,
       }),
+      BuildStepInput.createProvider({
+        id: 'max_idle_time_minutes',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.NUMBER,
+      }),
       BuildStepInput.createProvider({
         id: 'max_duration_seconds',
         required: false,
@@ -68,9 +74,20 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
       const ngrokTunnelDomain = getNgrokTunnelDomainOrThrow(stepEnv);
       const ngrokAuthtoken = getNgrokAuthtokenOrThrow(stepEnv);
       const env = omitNgrokAuthtoken(stepEnv);
+      const maxIdleTimeMinutes = inputs.max_idle_time_minutes?.value as number | undefined;
       const maxDurationSeconds = inputs.max_duration_seconds?.value as number | undefined;
       const packageVersion = inputs.package_version?.value as string | undefined;
       const { runtimePlatform } = global;
+      if (
+        maxIdleTimeMinutes !== undefined &&
+        maxIdleTimeMinutes > 0 &&
+        runtimePlatform !== BuildRuntimePlatform.DARWIN
+      ) {
+        throw new UserError(
+          'UNSUPPORTED_WEB_PREVIEW_IDLE_TIMEOUT',
+          'Web preview idle timeouts require iOS preview activity reporting. Omit max_idle_time_minutes for Android sessions.'
+        );
+      }
       if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
         await selectXcodeDeveloperDirectoryAsync({ env, logger });
       }
@@ -129,7 +146,7 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
             ? `Preview URL: ${webPreview.sharePageUrl} (server: ${webPreview.apiUrl}).`
             : 'Private preview URL unavailable for this session.'
         );
-        await uploadRemoteSessionConfigWithLocalEgressAsync({
+        const sessionStart = await uploadRemoteSessionConfigWithLocalEgressAsync({
           env,
           signal,
           ctx,
@@ -147,6 +164,9 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
           },
           logger,
         });
+        if (sessionStart === 'stopped') {
+          return;
+        }
 
         await waitForDeviceRunSessionStoppedAsync({
           ctx,
@@ -154,6 +174,14 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
           logger,
           maxDurationSeconds,
           signal,
+          idleTimeout:
+            maxIdleTimeMinutes !== undefined && maxIdleTimeMinutes > 0
+              ? {
+                  maxIdleTimeMinutes,
+                  getLastEventObservedAt: () => undefined,
+                  getLastPreviewActivityAt: () => sessionHost.getLastPreviewActivityAt(),
+                }
+              : undefined,
         });
       } finally {
         await sessionHost.finishAsync();

packages/build-tools/src/steps/functions/uploadArtifact.ts

@@ -1,9 +1,4 @@
-import {
-  GenericArtifactType,
-  Job,
-  ManagedArtifactType,
-  isGenericArtifact,
-} from '@expo/eas-build-job';
+import { Job, ManagedArtifactType } from '@expo/eas-build-job';
 import {
   BuildFunction,
   BuildStepInput,
@@ -33,7 +28,12 @@ export function createUploadArtifactBuildFunction(ctx: CustomBuildContext): Buil
           ManagedArtifactType.APPLICATION_ARCHIVE,
           ManagedArtifactType.BUILD_ARTIFACTS,
           ...Object.keys(artifactTypeInputToManagedArtifactType),
-          ...Object.values(GenericArtifactType),
+          // Keep accepting these legacy artifact types for compatibility.
+          'android-apk',
+          'android-aab',
+          'ios-simulator-app',
+          'ios-ipa',
+          'other',
         ],
         required: false,
         allowedValueTypeName: BuildStepInputValueTypeName.STRING,
@@ -126,12 +126,13 @@ export function createUploadArtifactBuildFunction(ctx: CustomBuildContext): Buil
         paths: artifactPaths,
         name: (inputs.name.value || inputs.key.value) as string,
       };
-      const artifact = isGenericArtifact(artifactSpec)
-        ? {
-            ...artifactSpec,
-            metadata: inputs.metadata.value as Record<string, unknown> | undefined,
-          }
-        : artifactSpec;
+      const artifact =
+        artifactSpec.type === null
+          ? {
+              ...artifactSpec,
+              metadata: inputs.metadata.value as Record<string, unknown> | undefined,
+            }
+          : artifactSpec;
 
       try {
         const { artifactId } = await ctx.runtimeApi.uploadArtifact({ artifact, logger });
@@ -141,7 +142,7 @@ export function createUploadArtifactBuildFunction(ctx: CustomBuildContext): Buil
         }
       } catch (error) {
         if (inputs.ignore_error.value) {
-          logger.error({ err: error }, `Failed to upload ${artifact.type}. Ignoring error.`);
+          logger.error({ err: error }, 'Failed to upload artifact. Ignoring error.');
           // Ignoring error.
           return;
         }
@@ -158,7 +159,7 @@ export function createUploadArtifactBuildFunction(ctx: CustomBuildContext): Buil
  * values. This makes sure we support all:
  * - kebab-case managed artifact types (the original)
  * - snake-caps-case managed artifact types (the mistake)
- * - generic artifact types.
+ * - workflow artifact types.
  */
 function parseArtifactTypeInput({
   inputValue,
@@ -166,19 +167,15 @@ function parseArtifactTypeInput({
 }: {
   inputValue: string;
   platform: Job['platform'];
-}): GenericArtifactType | ManagedArtifactType {
+}): ManagedArtifactType | null {
   if (!inputValue) {
     // In build jobs the default artifact type is application-archive.
-    return platform ? ManagedArtifactType.APPLICATION_ARCHIVE : GenericArtifactType.OTHER;
+    return platform ? ManagedArtifactType.APPLICATION_ARCHIVE : null;
   }
 
-  // Step's allowedValues ensures input is either
-  // a key of artifactTypeInputToManagedArtifactType
-  // or a value of an artifact type.
-  const translatedManagedArtifactType = artifactTypeInputToManagedArtifactType[inputValue];
-  if (translatedManagedArtifactType) {
-    return translatedManagedArtifactType;
-  }
-
-  return inputValue as GenericArtifactType | ManagedArtifactType;
+  return (
+    artifactTypeInputToManagedArtifactType[inputValue] ??
+    Object.values(ManagedArtifactType).find(type => type === inputValue) ??
+    null
+  );
 }

packages/build-tools/src/steps/functions/uploadToAsc.ts

@@ -262,6 +262,45 @@ export function createUploadToAscBuildFunction(): BuildFunction {
               }
             );
           }
+          if (isRedundantBinaryUploadError(errors)) {
+            throw new UserError(
+              'EAS_UPLOAD_TO_ASC_VERSION_DUPLICATE',
+              `Increment Build Number: Build number ${bundleVersion} for app version ${bundleShortVersion} has already been used. ` +
+                'App Store Connect requires unique build numbers within each app version (version train). ' +
+                'Increment it by setting ios.buildNumber in app.json, or set "autoIncrement": true in eas.json (recommended). Then rebuild and resubmit.' +
+                `\n\nApp Store Connect errors:\n${itemizeMessages(errors)}`,
+              {
+                docsUrl: 'https://docs.expo.dev/build-reference/app-versions/',
+                cause: state,
+              }
+            );
+          }
+          if (isMissingBackgroundTaskIdentifiersError(errors)) {
+            throw new UserError(
+              'EAS_UPLOAD_TO_ASC_MISSING_BG_TASK_IDENTIFIERS',
+              'Build upload was rejected by App Store Connect because Info.plist is missing `BGTaskSchedulerPermittedIdentifiers` while `UIBackgroundModes` includes `processing`. ' +
+                'In an Expo project, add `BGTaskSchedulerPermittedIdentifiers` to `ios.infoPlist` in your app config and include every background task identifier the app schedules. ' +
+                'If you do not use Continuous Native Generation (CNG), add the same key to the native target Info.plist. Then rebuild and submit again.' +
+                `\n\nApp Store Connect errors:\n${itemizeMessages(errors)}`,
+              {
+                docsUrl: 'https://docs.expo.dev/versions/latest/config/app/#infoplist',
+                cause: state,
+              }
+            );
+          }
+          if (isMissingAppIconsError(errors)) {
+            throw new UserError(
+              'EAS_UPLOAD_TO_ASC_MISSING_APP_ICONS',
+              'Build upload was rejected by App Store Connect because required app icons are missing or misconfigured in one of the iOS bundles. ' +
+                'In an Expo project, check your icon config (`expo.icon`, `ios.icon`) and any custom native targets or plugins that create extra bundles, such as watch extensions. ' +
+                'Make sure the affected target has the required icon assets and Info.plist icon keys (for example `CFBundleIconName` / `CFBundleIconFiles`), then rebuild and submit again.' +
+                `\n\nApp Store Connect errors:\n${itemizeMessages(errors)}`,
+              {
+                docsUrl: 'https://docs.expo.dev/develop/user-interface/splash-screen-and-app-icon/',
+                cause: state,
+              }
+            );
+          }
           if (isInvalidBundleIdentifierError(errors)) {
             const ipaInfoResult = await asyncResult(readIpaInfoAsync(ipaPath));
             const ipaBundleIdentifier = ipaInfoResult.ok
@@ -344,6 +383,21 @@ export function isSdkVersionIssueError(messages: { code: string }[]): boolean {
   return messages.length > 0 && messages.every(message => message.code === '90725');
 }
 
+export function isRedundantBinaryUploadError(messages: { code: string }[]): boolean {
+  return messages.length > 0 && messages.every(message => message.code === '90189');
+}
+
+export function isMissingBackgroundTaskIdentifiersError(messages: { code: string }[]): boolean {
+  return messages.length > 0 && messages.every(message => message.code === '90771');
+}
+
+export function isMissingAppIconsError(messages: { code: string }[]): boolean {
+  return (
+    messages.length > 0 &&
+    messages.every(message => ['90022', '90023', '90391', '90713'].includes(message.code))
+  );
+}
+
 export function isInvalidBundleIdentifierError(messages: { code: string }[]): boolean {
   return (
     messages.length > 0 && messages.every(message => ['90054', '90055'].includes(message.code))

packages/build-tools/src/steps/functions/useNpmToken.ts

@@ -1,9 +1,6 @@
 import { BuildFunction } from '@expo/steps';
-import fs from 'fs-extra';
-import path from 'path';
 
-import { NpmrcTemplate } from '../../templates/npmrc';
-import { findPackagerRootDir } from '../../utils/packageManager';
+import { setUpNpmrcAsync } from '../../utils/npmrc';
 
 export function createSetUpNpmrcBuildFunction(): BuildFunction {
   return new BuildFunction({
@@ -12,28 +9,12 @@ export function createSetUpNpmrcBuildFunction(): BuildFunction {
     name: 'Use NPM_TOKEN',
     __metricsId: 'eas/use_npm_token',
     fn: async (stepCtx, { env }) => {
-      const { logger } = stepCtx;
-      if (env.NPM_TOKEN) {
-        logger.info('We detected that you set the NPM_TOKEN environment variable');
-        const projectNpmrcPath = path.join(stepCtx.global.projectTargetDirectory, '.npmrc');
-        if (await fs.pathExists(projectNpmrcPath)) {
-          logger.info('.npmrc already exists in your project directory, skipping generation');
-        } else {
-          logger.info('Creating .npmrc in your project directory with the following contents:');
-          logger.info(NpmrcTemplate);
-          await fs.writeFile(projectNpmrcPath, NpmrcTemplate);
-        }
-      } else {
-        const projectNpmrcPath = path.join(findPackagerRootDir(stepCtx.workingDirectory), '.npmrc');
-        if (await fs.pathExists(projectNpmrcPath)) {
-          logger.info(
-            `.npmrc found at ${path.relative(
-              stepCtx.global.projectTargetDirectory,
-              projectNpmrcPath
-            )}`
-          );
-        }
-      }
+      await setUpNpmrcAsync({
+        projectTargetDirectory: stepCtx.global.projectTargetDirectory,
+        workingDirectory: stepCtx.workingDirectory,
+        env,
+        logger: stepCtx.logger,
+      });
     },
   });
 }

packages/build-tools/src/steps/utils/IosSimulatorRecordingUtils.ts

@@ -36,7 +36,7 @@ const SERVE_SIM_LEASE_FINALIZE_TIMEOUT_MS =
 const SERVE_SIM_FINISH_TIMEOUT_MS =
   SERVE_SIM_CONTROL_REQUEST_TIMEOUT_MS + SERVE_SIM_LEASE_FINALIZE_TIMEOUT_MS;
 const SERVE_SIM_FORCE_STOP_TIMEOUT_MS = 5_000;
-const SERVE_SIM_RECORDING_STARTED = 'serve-sim:recording-started';
+const SERVE_SIM_RECORDING_STARTED_LINE = /(?:^|\n)serve-sim:recording-started\r?\n/;
 // The serve-sim package the session host started; every recorder runs `record-video` from it.
 let serveSimPackageSpec: string | null = null;
 
@@ -507,14 +507,19 @@ function captureProcessOutput(recordingProcess: ChildProcess): {
 } {
   let output = '';
   let started = false;
-  const appendChunk = (chunk: Buffer | string): void => {
-    output = `${output}${chunk.toString()}`;
-    if (output.includes(SERVE_SIM_RECORDING_STARTED)) {
-      started = true;
-    }
-    output = output.slice(-16_384);
+  const captureStreamOutput = (stream: ChildProcess['stdout']): void => {
+    let streamOutput = '';
+    stream?.on('data', (chunk: Buffer | string) => {
+      const text = chunk.toString();
+      output = `${output}${text}`.slice(-16_384);
+      streamOutput = `${streamOutput}${text}`;
+      if (SERVE_SIM_RECORDING_STARTED_LINE.test(streamOutput)) {
+        started = true;
+      }
+      streamOutput = streamOutput.slice(-16_384);
+    });
   };
-  recordingProcess.stdout?.on('data', appendChunk);
-  recordingProcess.stderr?.on('data', appendChunk);
+  captureStreamOutput(recordingProcess.stdout);
+  captureStreamOutput(recordingProcess.stderr);
   return { getOutput: () => output, hasStarted: () => started };
 }

packages/build-tools/src/steps/utils/__tests__/IosSimulatorRecordingUtils.test.ts

@@ -144,7 +144,10 @@ test('starts serve-sim record-video and returns only a finalized recording', asy
   const finishing = IosSimulatorRecordingUtils.finishAsync({ logger });
   await setTimeout(20);
   expect(child.kill).not.toHaveBeenCalled();
-  stderr.write('serve-sim:recording-started\n');
+  child.stdout?.emit('data', 'Downloading');
+  stderr.write('serve-sim:recording-');
+  child.stdout?.emit('data', ' package');
+  stderr.write('started\r\n');
   stderr.write('x'.repeat(17_000));
   const recordings = await finishing;
 
@@ -362,6 +365,32 @@ test('keeps a recorder active after its package-manager wrapper exits', async ()
   expect(recordings).toHaveLength(1);
 });
 
+test('does not mistake bundled source in an error for a recording start', async () => {
+  let currentTime = Date.now();
+  jest.spyOn(Date, 'now').mockImplementation(() => currentTime);
+  jest
+    .mocked(readServeSimServersAsync)
+    .mockResolvedValue([{ udid, url: 'http://127.0.0.1:43563', token: 'session-token' }]);
+  const recorder = mockRecorder();
+
+  await IosSimulatorRecordingUtils.startAsync({ env, logger });
+  await waitForRecorderSpawnAsync();
+  recorder.child.stderr?.emit(
+    'data',
+    'const marker = "serve-sim:recording-started";\nError: No running serve-sim session found.\n'
+  );
+  recorder.fail(new Error('recorder exited before connecting'));
+
+  const finishing = IosSimulatorRecordingUtils.finishAsync({ logger });
+  try {
+    expect(await Promise.race([finishing.then(() => true), setTimeout(250, false)])).toBe(true);
+  } finally {
+    currentTime += 311_000;
+    await finishing;
+  }
+  expect(recorder.child.kill).not.toHaveBeenCalled();
+});
+
 test('does not signal a recorder that exits before it reports its start', async () => {
   let currentTime = Date.now();
   jest.spyOn(Date, 'now').mockImplementation(() => currentTime);

packages/build-tools/src/steps/utils/__tests__/agentRun.test.ts

@@ -186,6 +186,7 @@ describe(runAgentAsync, () => {
         '--package-lock=false',
         '--no-audit',
         '--no-fund',
+        '--no-update-notifier',
         '--registry',
         'https://npm-cache.expo.test',
         '@anthropic-ai/[email protected]',

packages/build-tools/src/steps/utils/__tests__/androidEmulatorLogs.test.ts

@@ -0,0 +1,322 @@
+import { type AndroidEmulatorLogSource } from '../../../utils/androidEmulatorLogSources';
+import { type BuildStepGlobalContext } from '@expo/steps';
+import fs from 'node:fs';
+import fsPromises, { mkdir, readFile, readdir, symlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { type CustomBuildContext } from '../../../customBuildContext';
+import {
+  collectAndroidEmulatorLogsAsync,
+  registerAndroidEmulatorLogDirectory,
+} from '../androidEmulatorLogs';
+import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
+
+jest.mock('../deviceRunSessionArtifacts');
+
+const ctx = {} as CustomBuildContext;
+const directory = path.join(os.tmpdir(), 'android-logs');
+const emulatorPath = path.join(directory, 'device-attempt-1-emulator.log');
+const logcatPath = path.join(directory, 'device-attempt-1-logcat.log');
+const upload = jest.mocked(uploadDeviceRunSessionArtifactAsync);
+let global: BuildStepGlobalContext;
+let logger: ReturnType<typeof createMockLogger>;
+let uploadedContents: Map<string, string>;
+
+beforeEach(async () => {
+  global = {} as BuildStepGlobalContext;
+  logger = createMockLogger();
+  uploadedContents = new Map();
+  await mkdir(directory, { recursive: true });
+  upload.mockReset().mockImplementation(async (_ctx, { filename, openStream }) => {
+    const chunks: Buffer[] = [];
+    for await (const chunk of openStream()) {
+      chunks.push(Buffer.from(chunk));
+    }
+    uploadedContents.set(filename, Buffer.concat(chunks).toString());
+  });
+});
+
+function collect(
+  maxBytes?: number,
+  sources: readonly AndroidEmulatorLogSource[] = ['emulator-output', 'device-logcat']
+): Promise<void> {
+  return collectAndroidEmulatorLogsAsync(ctx, {
+    global,
+    deviceRunSessionId: 'session',
+    logger,
+    maxBytes,
+    sources,
+  });
+}
+
+it('uploads only emulator output when sources are omitted', async () => {
+  await writeFile(emulatorPath, 'host output');
+  await writeFile(logcatPath, 'sensitive device output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  const open = jest.spyOn(fsPromises, 'open');
+  try {
+    await collectAndroidEmulatorLogsAsync(ctx, { global, deviceRunSessionId: 'session', logger });
+    expect([...uploadedContents.keys()]).toEqual([path.basename(emulatorPath)]);
+    expect(open).not.toHaveBeenCalledWith(logcatPath, expect.anything());
+  } finally {
+    open.mockRestore();
+  }
+});
+
+it('uploads only explicitly selected logcat and uploads nothing for an empty selection', async () => {
+  await writeFile(emulatorPath, 'host output');
+  await writeFile(logcatPath, 'device output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  await collect(undefined, []);
+  expect(upload).not.toHaveBeenCalled();
+  await collect(undefined, ['device-logcat']);
+  expect([...uploadedContents.keys()]).toEqual([path.basename(logcatPath)]);
+});
+
+it('honors different source selections during concurrent cleanup without duplicate uploads', async () => {
+  await writeFile(emulatorPath, 'host output');
+  await writeFile(logcatPath, 'device output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  await Promise.all([
+    collect(undefined, ['emulator-output']),
+    collect(undefined, ['emulator-output', 'device-logcat']),
+  ]);
+  expect([...uploadedContents.keys()].sort()).toEqual([
+    path.basename(emulatorPath),
+    path.basename(logcatPath),
+  ]);
+  expect(upload).toHaveBeenCalledTimes(2);
+});
+
+it('uploads both logs for every attempt from registered directories only', async () => {
+  await writeFile(emulatorPath, 'host output');
+  await writeFile(logcatPath, 'Android output');
+  await writeFile(path.join(directory, 'device-attempt-2-emulator.log'), 'retry output');
+  await writeFile(path.join(directory, 'unrelated.txt'), 'not a log');
+  const elsewhere = path.join(os.tmpdir(), 'unregistered');
+  await mkdir(elsewhere);
+  await writeFile(path.join(elsewhere, 'other-emulator.log'), 'another job');
+  await symlink(
+    path.join(elsewhere, 'other-emulator.log'),
+    path.join(directory, 'link-logcat.log')
+  );
+  registerAndroidEmulatorLogDirectory(global, directory);
+  await collect();
+
+  expect([...uploadedContents.values()]).toEqual(['host output', 'Android output', 'retry output']);
+  expect(upload).toHaveBeenCalledWith(
+    ctx,
+    expect.objectContaining({
+      filename: 'device-attempt-1-emulator.log',
+      kind: 'simulator-log',
+      metadata: expect.objectContaining({
+        platform: 'android',
+        source: 'emulator-output',
+        scope: 'emulator-process',
+        truncated: false,
+      }),
+      signal: expect.any(AbortSignal),
+      attempts: 2,
+    })
+  );
+  expect(upload).toHaveBeenCalledWith(
+    ctx,
+    expect.objectContaining({
+      filename: 'device-attempt-1-logcat.log',
+      metadata: expect.objectContaining({ source: 'device-logcat', scope: 'device' }),
+    })
+  );
+  expect(await readdir(os.tmpdir())).not.toEqual(
+    expect.arrayContaining([expect.stringMatching(/^eas-android-log-snapshot-/)])
+  );
+});
+
+it('keeps the latest bytes and records truncation', async () => {
+  await writeFile(emulatorPath, 'old output\ncrash\n');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  await collect(6);
+  expect(uploadedContents.get(path.basename(emulatorPath))).toBe('crash\n');
+  expect(upload).toHaveBeenCalledWith(
+    ctx,
+    expect.objectContaining({
+      size: 6,
+      name: expect.stringContaining('truncated, 6 bytes retained'),
+      metadata: expect.objectContaining({
+        originalSizeBytes: 17,
+        omittedBytes: 11,
+        truncated: true,
+      }),
+    })
+  );
+  expect(await readFile(emulatorPath, 'utf8')).toBe('old output\ncrash\n');
+});
+
+it('fixes the snapshot range before append and keeps upload retries identical', async () => {
+  await writeFile(emulatorPath, 'before');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  const createReadStream = fs.createReadStream;
+  const read = jest.spyOn(fs, 'createReadStream').mockImplementationOnce((filePath, options) => {
+    fs.appendFileSync(emulatorPath, ' during snapshot');
+    return createReadStream(filePath, options);
+  });
+  const contents: string[] = [];
+  upload.mockImplementationOnce(async (_ctx, { size, openStream }) => {
+    expect(size).toBe(6);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      await writeFile(emulatorPath, 'rewritten after snapshot');
+      const chunks: Buffer[] = [];
+      for await (const chunk of openStream()) {
+        chunks.push(Buffer.from(chunk));
+      }
+      contents.push(Buffer.concat(chunks).toString());
+    }
+  });
+  try {
+    await collect();
+    expect(contents).toEqual(['before', 'before']);
+  } finally {
+    read.mockRestore();
+  }
+});
+
+it('continues after a failed upload and retries only unsuccessful files on another collection', async () => {
+  await writeFile(emulatorPath, 'host output');
+  await writeFile(logcatPath, 'Android output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  upload.mockRejectedValueOnce(new Error('storage unavailable'));
+  await expect(collect()).resolves.toBeUndefined();
+  expect(upload).toHaveBeenCalledTimes(2);
+  expect(logger.warn).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.stringContaining('other logs will continue')
+  );
+  await collect();
+  expect(upload).toHaveBeenCalledTimes(3);
+  expect(upload.mock.calls[2][1].filename).toBe(path.basename(emulatorPath));
+  expect(upload.mock.calls[0][1].signal).not.toBe(upload.mock.calls[1][1].signal);
+});
+
+it('shares concurrent collection and skips successful uploads on repeated cleanup', async () => {
+  await writeFile(emulatorPath, 'host output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  registerAndroidEmulatorLogDirectory(global, directory);
+  await Promise.all([collect(), collect()]);
+  await collect();
+  expect(upload).toHaveBeenCalledTimes(1);
+});
+
+it('keeps successful uploads deduplicated when snapshot cleanup fails', async () => {
+  await writeFile(emulatorPath, 'host output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  const open = fsPromises.open;
+  const openFile = jest.spyOn(fsPromises, 'open').mockImplementationOnce(async (...args) => {
+    const file = await open(...args);
+    const close = file.close.bind(file);
+    file.close = async () => {
+      await close();
+      throw new Error('close failed');
+    };
+    return file;
+  });
+  const remove = jest.spyOn(fsPromises, 'rm').mockRejectedValueOnce(new Error('remove failed'));
+  try {
+    await expect(collect()).resolves.toBeUndefined();
+    await collect();
+    expect(upload).toHaveBeenCalledTimes(1);
+    expect(remove).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining('Could not close')
+    );
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining('Could not remove')
+    );
+  } finally {
+    openFile.mockRestore();
+    remove.mockRestore();
+  }
+});
+
+it('uses a fresh 30 second budget for the next file after an upload times out', async () => {
+  await writeFile(emulatorPath, 'host output');
+  await writeFile(logcatPath, 'Android output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  const controllers: AbortController[] = [];
+  const timeout = jest.spyOn(AbortSignal, 'timeout').mockImplementation(() => {
+    const controller = new AbortController();
+    controllers.push(controller);
+    return controller.signal;
+  });
+  upload.mockImplementationOnce(async (_ctx, { signal }) => {
+    controllers[0].abort(new Error('upload timed out'));
+    signal?.throwIfAborted();
+  });
+  try {
+    await expect(collect()).resolves.toBeUndefined();
+    expect(uploadedContents.get(path.basename(logcatPath))).toBe('Android output');
+    expect(timeout.mock.calls).toEqual([[30_000], [30_000]]);
+    expect(upload.mock.calls[1][1].signal?.aborted).toBe(false);
+  } finally {
+    timeout.mockRestore();
+  }
+});
+
+it('does not collect another workflow or empty files and tolerates missing directories', async () => {
+  registerAndroidEmulatorLogDirectory({} as BuildStepGlobalContext, directory);
+  await writeFile(emulatorPath, 'other workflow');
+  await collect();
+  expect(upload).not.toHaveBeenCalled();
+  await writeFile(emulatorPath, '');
+  registerAndroidEmulatorLogDirectory(global, path.join(os.tmpdir(), 'missing'));
+  registerAndroidEmulatorLogDirectory(global, directory);
+  await expect(collect()).resolves.toBeUndefined();
+  expect(upload).not.toHaveBeenCalled();
+  expect(logger.warn).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.stringContaining('Could not read')
+  );
+});
+
+it('handles a snapshot read failure and still uploads the other log', async () => {
+  await writeFile(emulatorPath, 'host output');
+  await writeFile(logcatPath, 'Android output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  const createReadStream = fs.createReadStream;
+  const read = jest.spyOn(fs, 'createReadStream').mockImplementationOnce((filePath, options) => {
+    const stream = createReadStream(filePath, options);
+    stream.destroy(new Error('source read failed'));
+    return stream;
+  });
+  try {
+    await expect(collect()).resolves.toBeUndefined();
+    expect(uploadedContents.get(path.basename(logcatPath))).toBe('Android output');
+    expect(upload).toHaveBeenCalledTimes(1);
+  } finally {
+    read.mockRestore();
+  }
+});
+
+it('aborts an upload on a genuine snapshot file read error and continues with the other log', async () => {
+  await writeFile(emulatorPath, 'host output');
+  await writeFile(logcatPath, 'Android output');
+  registerAndroidEmulatorLogDirectory(global, directory);
+  const readError = Object.assign(new Error('snapshot read failed'), { code: 'EIO' });
+  upload.mockImplementationOnce(async (_ctx, { openStream, signal }) => {
+    const stream = openStream();
+    await new Promise<void>(resolve => {
+      stream.once('error', () => resolve());
+      stream.destroy(readError);
+    });
+    expect(signal?.reason).toBe(readError);
+    signal?.throwIfAborted();
+  });
+  await expect(collect()).resolves.toBeUndefined();
+  expect(uploadedContents.get(path.basename(logcatPath))).toBe('Android output');
+  expect(logger.warn).toHaveBeenCalledWith(
+    { err: readError },
+    expect.stringContaining('other logs will continue')
+  );
+});

packages/build-tools/src/steps/utils/__tests__/androidEmulatorLogsUpload.test.ts

@@ -0,0 +1,149 @@
+import { type BuildStepGlobalContext } from '@expo/steps';
+import fs from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  createCustomBuildContextMock,
+  createGlobalContextMock,
+} from '../../../__tests__/utils/context';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { type CustomBuildContext } from '../../../customBuildContext';
+import {
+  collectAndroidEmulatorLogsAsync,
+  registerAndroidEmulatorLogDirectory,
+} from '../androidEmulatorLogs';
+import { requireDeviceRunSessionWorkerApi } from '../deviceRunSessionWorkerApi';
+
+jest.mock('../deviceRunSessionWorkerApi');
+jest.unmock('fs');
+jest.unmock('node:fs');
+jest.unmock('fs/promises');
+jest.unmock('node:fs/promises');
+jest.unmock('node-fetch');
+
+it('does not close a reused descriptor after a snapshot read failure', async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'android-log-descriptor-test-'));
+  const unrelatedPath = path.join(directory, 'unrelated.txt');
+  const readError = Object.assign(new Error('source read failed'), { code: 'EIO' });
+  const createReadStream = fs.createReadStream;
+  let sourceFd: number | undefined;
+  let reusedFd: number | undefined;
+  const read = jest.spyOn(fs, 'createReadStream').mockImplementationOnce((filePath, options) => {
+    if (!options || typeof options === 'string' || options.fd == null) {
+      throw new Error('Expected an open source file');
+    }
+    sourceFd = typeof options.fd === 'number' ? options.fd : options.fd.fd;
+    const stream = createReadStream(filePath, options);
+    stream.once('close', () => {
+      // Reuse the descriptor before the collector's final FileHandle.close().
+      reusedFd = fs.openSync(unrelatedPath, 'w');
+    });
+    stream.destroy(readError);
+    return stream;
+  });
+  try {
+    await writeFile(path.join(directory, 'device-emulator.log'), 'host output');
+    const global = createGlobalContextMock();
+    const logger = createMockLogger();
+    registerAndroidEmulatorLogDirectory(global, directory);
+
+    await collectAndroidEmulatorLogsAsync(createCustomBuildContextMock(), {
+      global,
+      deviceRunSessionId: 'session',
+      logger,
+    });
+
+    expect(reusedFd).toBe(sourceFd);
+    if (reusedFd === undefined) {
+      throw new Error('Expected the source descriptor to be reused');
+    }
+    expect(fs.writeSync(reusedFd, 'still open')).toBe(10);
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: readError },
+      expect.stringContaining('other logs will continue')
+    );
+    expect(requireDeviceRunSessionWorkerApi).not.toHaveBeenCalled();
+  } finally {
+    read.mockRestore();
+    if (reusedFd !== undefined) {
+      try {
+        fs.closeSync(reusedFd);
+      } catch {
+        // The regression closes this descriptor before the test can clean it up.
+      }
+    }
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+it('retries a capped log after an early storage error with real file streams and one artifact', async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'android-log-upload-test-'));
+  const maximumBytes = 20 * 1024 * 1024;
+  const payload = Buffer.alloc(maximumBytes + 6, 'a');
+  await writeFile(path.join(directory, 'device-emulator.log'), payload);
+  const global = {} as BuildStepGlobalContext;
+  const logger = createMockLogger();
+  registerAndroidEmulatorLogDirectory(global, directory);
+  let requests = 0;
+  let receivedBytes = 0;
+  const server = createServer((request, response) => {
+    requests++;
+    if (requests === 1) {
+      response.statusCode = 503;
+      response.flushHeaders();
+      return;
+    }
+    request.on('data', chunk => {
+      receivedBytes += chunk.length;
+    });
+    request.on('end', () => response.end());
+  });
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+  try {
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+      throw new Error('Missing test server address');
+    }
+    const createArtifactUploadSessionAsync = jest.fn().mockResolvedValue({
+      url: `http://127.0.0.1:${address.port}/log`,
+      headers: { 'Content-Length': String(maximumBytes) },
+    });
+    jest.mocked(requireDeviceRunSessionWorkerApi).mockReturnValue({
+      createArtifactUploadSessionAsync,
+    } as unknown as ReturnType<typeof requireDeviceRunSessionWorkerApi>);
+    const collect = async (): Promise<void> =>
+      await collectAndroidEmulatorLogsAsync({} as CustomBuildContext, {
+        global,
+        deviceRunSessionId: 'session',
+        logger,
+      });
+
+    await collect();
+    await collect();
+
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(requests).toBe(2);
+    expect(receivedBytes).toBe(maximumBytes);
+    expect(createArtifactUploadSessionAsync).toHaveBeenCalledTimes(1);
+    expect(createArtifactUploadSessionAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: expect.stringContaining('truncated, 20 MiB retained'),
+        size: maximumBytes,
+        metadata: expect.objectContaining({
+          originalSizeBytes: payload.length,
+          omittedBytes: 6,
+          truncated: true,
+        }),
+      }),
+      expect.objectContaining({ signal: expect.any(AbortSignal) })
+    );
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>(resolve => server.close(() => resolve()));
+    await rm(directory, { recursive: true, force: true });
+  }
+});

packages/build-tools/src/steps/utils/__tests__/deviceRunSessionPreview.test.ts

@@ -18,7 +18,14 @@ import {
 } from '../deviceRunSessionPreview';
 import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 
-jest.mock('node-fetch');
+jest.mock('node-fetch', () => {
+  const actual = jest.requireActual('node-fetch');
+  return {
+    __esModule: true,
+    ...actual,
+    default: jest.fn(),
+  };
+});
 jest.mock('@expo/turtle-spawn');
 jest.mock('../../../utils/turtleFetch');
 const { Response } = jest.requireActual('node-fetch') as typeof import('node-fetch');
@@ -87,8 +94,8 @@ describe(startDeviceRunSessionPreview, () => {
       'https://uploads.expo.test/preview',
       expect.objectContaining({
         method: 'PUT',
-        body: image,
-        headers: { 'content-type': 'image/webp' },
+        body: expect.any(Readable),
+        headers: { 'content-type': 'image/webp', 'content-length': String(image.length) },
       })
     );
     await jest.advanceTimersByTimeAsync(59_999);
@@ -130,9 +137,7 @@ describe(startDeviceRunSessionPreview, () => {
     await jest.advanceTimersByTimeAsync(0);
     expect(logger.warn).toHaveBeenCalledTimes(1);
     const [fields] = jest.mocked(logger.warn).mock.calls[0] as unknown as [{ err: Error }];
-    expect(fields.err.message).toBe(
-      'Session preview upload request failed (name: FetchError, type: request-timeout).'
-    );
+    expect(fields.err.message).toBe('Signed URL upload failed: network error.');
     expect(JSON.stringify(jest.mocked(logger.warn).mock.calls)).not.toContain('uploads.expo.test');
   });
 

packages/build-tools/src/steps/utils/__tests__/deviceRunSessionScreenRecordings.test.ffmpeg.ts

@@ -1,7 +1,7 @@
 import type { bunyan } from '@expo/logger';
 import type { BuildStepEnv } from '@expo/steps';
 import { execFileSync } from 'node:child_process';
-import { copyFile, mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { type IncomingMessage, type ServerResponse, createServer } from 'node:http';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
@@ -40,7 +40,14 @@ beforeEach(async () => {
         creationTokens.push(request.headers['expo-device-run-session-token'] as string | undefined);
         response.setHeader('Content-Type', 'application/json');
         response.end(
-          JSON.stringify({ data: { uploadSession: { url: `${url}/artifact`, headers: {} } } })
+          JSON.stringify({
+            data: {
+              uploadSession: {
+                url: `${url}/artifact/${encodeURIComponent(JSON.parse(body).filename)}`,
+                headers: {},
+              },
+            },
+          })
         );
       });
     } else {
@@ -156,10 +163,14 @@ it('recovers unlisted recordings from a killed host and flags the unfinished one
   ]);
   expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('empty/recording.mp4.partial'));
 
-  let putBytes = 0;
+  const uploaded = new Map<string, Buffer>();
   handle = (request, response) => {
-    request.on('data', chunk => (putBytes += chunk.length));
+    const chunks: Buffer[] = [];
+    request.on('data', chunk => {
+      chunks.push(chunk);
+    });
     request.on('end', () => {
+      uploaded.set(request.url!, Buffer.concat(chunks));
       response.statusCode = 200;
       response.end();
     });
@@ -171,10 +182,18 @@ it('recovers unlisted recordings from a killed host and flags the unfinished one
       recordings,
     })
   ).resolves.toBe(true);
-  expect(putBytes).toBe(3 * (await stat(path.join(cut, 'recording.mp4.partial'))).size);
-  expect(creationTokens).toEqual(['session-token', 'session-token', 'session-token']);
+  for (const recording of recordings) {
+    const manifest = await readFile(path.join(recording.directory, 'session.json'));
+    const recordingId = path.basename(recording.directory);
+    expect(uploaded.get(`/artifact/${recordingId}.json`)).toEqual(manifest);
+    expect(uploaded.get(`/artifact/${recordingId}.mp4`)).toEqual(
+      await readFile(path.join(recording.directory, JSON.parse(manifest.toString()).recording))
+    );
+  }
+  expect(creationTokens).toEqual(Array(6).fill('session-token'));
   const inputs = creationBodies
     .map(body => JSON.parse(body))
+    .filter(input => input.kind === 'screen-recording')
     .sort((a, b) => a.filename.localeCompare(b.filename));
   expect(inputs.map(input => input.filename)).toEqual(['cut.mp4', 'done.mp4', 'failed.mp4']);
   expect(inputs.map(input => input.name.includes(', partial)'))).toEqual([true, false, true]);
@@ -185,6 +204,16 @@ it('recovers unlisted recordings from a killed host and flags the unfinished one
     width: 128,
     height: 96,
   });
+  const manifests = creationBodies
+    .map(body => JSON.parse(body))
+    .filter(input => input.kind === 'screen-recording-metadata')
+    .sort((a, b) => a.filename.localeCompare(b.filename));
+  expect(manifests.map(input => input.filename)).toEqual(['cut.json', 'done.json', 'failed.json']);
+  expect(manifests.map(input => input.metadata.recordingFilename)).toEqual([
+    'cut.mp4',
+    'done.mp4',
+    'failed.mp4',
+  ]);
   expect(inputs[2].metadata).toMatchObject({
     partial: true,
     partialReason: 'Recording finalization exceeded 30000 ms.',

packages/build-tools/src/steps/utils/__tests__/deviceRunSessionScreenRecordings.test.ts

@@ -0,0 +1,141 @@
+import type { bunyan } from '@expo/logger';
+import { vol } from 'memfs';
+import { writeFile } from 'node:fs/promises';
+
+import type { CustomBuildContext } from '../../../customBuildContext';
+import { Sentry } from '../../../sentry';
+import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
+import { uploadDeviceRunSessionScreenRecordingsAsync } from '../deviceRunSessionScreenRecordings';
+
+jest.mock('../deviceRunSessionArtifacts');
+jest.mock('../../../sentry');
+
+const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
+const ctx = {} as CustomBuildContext;
+const recording = {
+  udid: 'simulator-id',
+  deviceName: 'iPhone Duo',
+  runtimeDisplayName: 'iOS 27.1',
+  directory: '/recordings/recording-id',
+};
+const manifest = {
+  firstFrameWallClock: { unixMs: 1_791_072_000_000, iso8601: '2026-10-04T00:00:00.000Z' },
+  width: 1440,
+  height: 1200,
+  recording: 'recording.mp4',
+};
+
+beforeEach(() => {
+  jest.mocked(uploadDeviceRunSessionArtifactAsync).mockReset().mockResolvedValue(undefined);
+});
+
+it.each([
+  {},
+  {
+    deviceStates: [
+      {
+        timeMs: 12.5,
+        state: {
+          width: 1200,
+          height: 1440,
+          orientation: 'landscape-left',
+          screen: 'inner',
+          hingeAngle: 90,
+          physicalOrientation: 'portrait',
+          tableMode: false,
+          contentRect: { x: 220, y: 0, width: 1000, height: 1200 },
+        },
+      },
+    ],
+    interruptions: [{ reason: 'simulatorReboot', pausedAtSeconds: 1, resumedAtSeconds: 2 }],
+    futureField: { label: '서울 🌲' },
+  },
+])('uploads the complete manifest unchanged beside its video (%j)', async extra => {
+  const contents = Buffer.from(JSON.stringify({ ...manifest, ...extra }, null, 2) + '\n');
+  vol.fromJSON({
+    [recording.directory + '/session.json']: contents.toString(),
+    [recording.directory + '/recording.mp4']: 'video',
+  });
+  jest.mocked(uploadDeviceRunSessionArtifactAsync).mockImplementation(async (_, input) => {
+    if (input.kind === 'screen-recording') {
+      await writeFile(recording.directory + '/session.json', '{}');
+    }
+  });
+
+  await expect(
+    uploadDeviceRunSessionScreenRecordingsAsync(ctx, {
+      logger,
+      deviceRunSessionId: 'session-id',
+      recordings: [recording],
+    })
+  ).resolves.toBe(true);
+
+  const inputs = jest
+    .mocked(uploadDeviceRunSessionArtifactAsync)
+    .mock.calls.map(([, input]) => input);
+  expect(inputs.map(input => input.filename)).toEqual(['recording-id.mp4', 'recording-id.json']);
+  expect(inputs[1]).toMatchObject({
+    deviceRunSessionId: 'session-id',
+    artifactId: 'recording-id-metadata',
+    kind: 'screen-recording-metadata',
+    metadata: {
+      __eas_type: 'screen-recording-metadata',
+      recordingFilename: 'recording-id.mp4',
+      udid: recording.udid,
+    },
+    size: contents.length,
+  });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of inputs[1].openStream()) {
+      chunks.push(Buffer.from(chunk));
+    }
+    expect(Buffer.concat(chunks)).toEqual(contents);
+  }
+});
+
+it('reports a metadata upload failure while keeping the video and uploading other recordings', async () => {
+  const other = { ...recording, directory: '/recordings/other-recording', udid: 'other-device' };
+  for (const item of [recording, other]) {
+    vol.fromJSON({
+      [item.directory + '/session.json']: JSON.stringify(manifest),
+      [item.directory + '/recording.mp4']: 'video',
+    });
+  }
+  jest.mocked(uploadDeviceRunSessionArtifactAsync).mockImplementation(async (_, input) => {
+    if (input.filename === 'recording-id.json') {
+      throw new Error('Storage unavailable');
+    }
+  });
+
+  await expect(
+    uploadDeviceRunSessionScreenRecordingsAsync(ctx, {
+      logger,
+      deviceRunSessionId: 'session-id',
+      recordings: [recording, other],
+    })
+  ).resolves.toBe(false);
+
+  expect(
+    jest.mocked(uploadDeviceRunSessionArtifactAsync).mock.calls.map(([, input]) => input.filename)
+  ).toEqual(
+    expect.arrayContaining([
+      'recording-id.mp4',
+      'recording-id.json',
+      'other-recording.mp4',
+      'other-recording.json',
+    ])
+  );
+  expect(Sentry.capture).toHaveBeenCalledWith(
+    'Could not upload device screen recording metadata',
+    expect.any(Error)
+  );
+  expect(Sentry.capture).not.toHaveBeenCalledWith(
+    'Could not upload device screen recording',
+    expect.any(Error)
+  );
+  expect(logger.warn).toHaveBeenCalledWith(
+    expect.objectContaining({ err: expect.any(Error) }),
+    `Could not upload screen recording metadata for ${recording.deviceName}.`
+  );
+});

packages/build-tools/src/steps/utils/__tests__/deviceRunSessionWorkerApi.test.ts

@@ -1,4 +1,5 @@
 import { SystemError } from '@expo/eas-build-job';
+import { FetchError } from 'node-fetch';
 
 import { CustomBuildContext } from '../../../customBuildContext';
 import { turtleFetch } from '../../../utils/turtleFetch';
@@ -11,6 +12,7 @@ import {
 } from '../deviceRunSessionWorkerApi';
 
 jest.mock('../../../utils/turtleFetch');
+jest.unmock('node-fetch');
 
 const { Response } = jest.requireActual('node-fetch') as typeof import('node-fetch');
 type Response = InstanceType<typeof Response>;
@@ -262,12 +264,12 @@ describe(DeviceRunSessionWorkerApi, () => {
   it('rejects an application response without the build field', async () => {
     jest.mocked(turtleFetch).mockResolvedValueOnce(jsonResponse({ data: { platform: 'ios' } }));
 
-    await expect(createApi().getApplicationAsync()).rejects.toThrow(
+    await expect(createApi().getApplicationAsync({ retries: 3 })).rejects.toThrow(
       'GET /v2/device-run-session-worker/application returned an unexpected response'
     );
   });
 
-  it('passes the signal, timeout, and retries to the request', async () => {
+  it('passes the signal and timeout without enabling nested retries', async () => {
     jest.mocked(turtleFetch).mockResolvedValueOnce(jsonResponse({ data: { iceServers: [] } }));
     const controller = new AbortController();
 
@@ -280,7 +282,7 @@ describe(DeviceRunSessionWorkerApi, () => {
     expect(jest.mocked(turtleFetch)).toHaveBeenCalledWith(
       expect.any(String),
       'POST',
-      expect.objectContaining({ signal: controller.signal, timeout: 5000, retries: 1 })
+      expect.objectContaining({ signal: controller.signal, timeout: 5000, retries: 0 })
     );
   });
 
@@ -319,7 +321,7 @@ describe(DeviceRunSessionWorkerApi, () => {
       );
 
     const error = await createApi()
-      .getSessionAsync()
+      .getSessionAsync({ retries: 0 })
       .catch(err => err);
 
     expect(error).toBeInstanceOf(DeviceRunSessionWorkerApiError);
@@ -330,14 +332,16 @@ describe(DeviceRunSessionWorkerApi, () => {
   });
 
   it('reports a request that failed before www responded', async () => {
-    jest.mocked(turtleFetch).mockRejectedValueOnce(new Error('socket hang up'));
+    const reason = new Error('socket hang up');
+    jest.mocked(turtleFetch).mockRejectedValueOnce(reason);
 
     const error = await createApi()
-      .getSessionAsync()
+      .getSessionAsync({ retries: 0 })
       .catch(err => err);
 
     expect(error).toBeInstanceOf(DeviceRunSessionWorkerApiError);
     expect(error.status).toBeUndefined();
+    expect(error.cause).toBe(reason);
     expect(error.message).toContain('failed before www responded: socket hang up');
   });
 
@@ -346,7 +350,7 @@ describe(DeviceRunSessionWorkerApi, () => {
       .mocked(turtleFetch)
       .mockResolvedValueOnce(jsonResponse({ data: { id: 'drs-id', status: 'STOPPED' } }));
 
-    await expect(createApi().getSessionAsync()).rejects.toThrow(
+    await expect(createApi().getSessionAsync({ retries: 3 })).rejects.toThrow(
       'GET /v2/device-run-session-worker/session returned an unexpected response'
     );
   });
@@ -354,8 +358,183 @@ describe(DeviceRunSessionWorkerApi, () => {
   it('rejects a successful response that is not JSON', async () => {
     jest.mocked(turtleFetch).mockResolvedValueOnce(new Response('ok', { status: 200 }));
 
-    await expect(createApi().getSessionAsync()).rejects.toThrow(
+    await expect(createApi().getSessionAsync({ retries: 3 })).rejects.toThrow(
       'GET /v2/device-run-session-worker/session returned a response that is not JSON.'
     );
   });
 });
+
+describe('device run session worker API retries', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.mocked(turtleFetch).mockReset();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it.each([429, 500, 502, 503, 504])(
+    'recovers from HTTP %s when starting a session',
+    async status => {
+      jest
+        .mocked(turtleFetch)
+        .mockResolvedValueOnce(new Response('unavailable', { status }))
+        .mockResolvedValueOnce(jsonResponse({ data: { id: 'drs-id', status: 'in-progress' } }));
+      const result = createApi().startAsync(
+        { remoteConfig: { url: 'https://preview.test' } },
+        { retries: 3, timeoutMs: 30_000 }
+      );
+      const assertion = expect(result).resolves.toEqual({ id: 'drs-id', status: 'in-progress' });
+      await jest.runAllTimersAsync();
+      await assertion;
+      expect(turtleFetch).toHaveBeenCalledTimes(2);
+      expect(jest.mocked(turtleFetch).mock.calls[1]).toEqual(
+        jest.mocked(turtleFetch).mock.calls[0]
+      );
+      expect(jest.mocked(turtleFetch).mock.calls[0][2]).toMatchObject({
+        retries: 0,
+        timeout: 30_000,
+      });
+    }
+  );
+
+  it('recovers from a network failure', async () => {
+    jest
+      .mocked(turtleFetch)
+      .mockRejectedValueOnce(new Error('socket hang up'))
+      .mockResolvedValueOnce(jsonResponse({ data: { build: null } }));
+    const assertion = expect(createApi().getApplicationAsync({ retries: 3 })).resolves.toEqual({
+      build: null,
+    });
+    await jest.runAllTimersAsync();
+    await assertion;
+    expect(turtleFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('exhausts three retries with exponential backoff', async () => {
+    jest
+      .mocked(turtleFetch)
+      .mockImplementation(async () => new Response('unavailable', { status: 503 }));
+    const assertion = expect(
+      createApi().startAsync({ remoteConfig: {} }, { retries: 3 })
+    ).rejects.toMatchObject({
+      status: 503,
+    });
+    await jest.advanceTimersByTimeAsync(0);
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+    await jest.advanceTimersByTimeAsync(1000);
+    expect(turtleFetch).toHaveBeenCalledTimes(2);
+    await jest.advanceTimersByTimeAsync(2000);
+    expect(turtleFetch).toHaveBeenCalledTimes(3);
+    await jest.advanceTimersByTimeAsync(4000);
+    await assertion;
+    expect(turtleFetch).toHaveBeenCalledTimes(4);
+  });
+
+  it.each([400, 401, 403, 404, 409])('does not retry HTTP %s', async status => {
+    jest.mocked(turtleFetch).mockResolvedValueOnce(new Response('refused', { status }));
+    await expect(
+      createApi().startAsync({ remoteConfig: {} }, { retries: 3 })
+    ).rejects.toMatchObject({ status });
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ['status polling', (api: DeviceRunSessionWorkerApi) => api.getSessionAsync()],
+    ['stop', (api: DeviceRunSessionWorkerApi) => api.stopAsync()],
+    [
+      'screenshot application metadata',
+      (api: DeviceRunSessionWorkerApi) => api.getApplicationAsync(),
+    ],
+    ['event log setup', (api: DeviceRunSessionWorkerApi) => api.createEventLogUploadSessionAsync()],
+    ['preview setup', (api: DeviceRunSessionWorkerApi) => api.createPreviewUploadSessionAsync()],
+    [
+      'TURN without an explicit retry option',
+      (api: DeviceRunSessionWorkerApi) => api.fetchTurnIceServersAsync(),
+    ],
+  ])('does not retry %s by default', async (_name, call) => {
+    jest.mocked(turtleFetch).mockResolvedValueOnce(new Response('unavailable', { status: 503 }));
+    await expect(call(createApi())).rejects.toMatchObject({ status: 503 });
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('honors an explicit retry count', async () => {
+    jest
+      .mocked(turtleFetch)
+      .mockImplementation(async () => new Response('unavailable', { status: 503 }));
+    const assertion = expect(
+      createApi().fetchTurnIceServersAsync({ retries: 1 })
+    ).rejects.toMatchObject({ status: 503 });
+    await jest.runAllTimersAsync();
+    await assertion;
+    expect(turtleFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not send another request after cancellation during backoff', async () => {
+    const controller = new AbortController();
+    jest.mocked(turtleFetch).mockResolvedValueOnce(new Response('unavailable', { status: 503 }));
+    const assertion = expect(
+      createApi().getApplicationAsync({ signal: controller.signal, retries: 3 })
+    ).rejects.toMatchObject({ name: 'AbortError' });
+    await jest.advanceTimersByTimeAsync(0);
+    controller.abort();
+    await jest.runAllTimersAsync();
+    await assertion;
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('device run session retry safety', () => {
+  beforeEach(() => {
+    jest.mocked(turtleFetch).mockReset();
+  });
+
+  it('does not replay artifact creation after a transient failure', async () => {
+    jest.mocked(turtleFetch).mockResolvedValueOnce(new Response('unavailable', { status: 503 }));
+    await expect(
+      createApi().createArtifactUploadSessionAsync({
+        name: 'report',
+        filename: 'report.json',
+        size: 1,
+      })
+    ).rejects.toMatchObject({ status: 503 });
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not send an already cancelled request', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      createApi().getApplicationAsync({ signal: controller.signal, retries: 3 })
+    ).rejects.toMatchObject({
+      name: 'AbortError',
+    });
+    expect(turtleFetch).not.toHaveBeenCalled();
+  });
+
+  it.each(['system', 'body-timeout'])(
+    'retries a response body transport failure (%s)',
+    async type => {
+      jest.useFakeTimers();
+      try {
+        const response = jsonResponse({});
+        jest
+          .spyOn(response, 'json')
+          .mockRejectedValueOnce(new FetchError('connection interrupted', type));
+        jest
+          .mocked(turtleFetch)
+          .mockResolvedValueOnce(response)
+          .mockResolvedValueOnce(jsonResponse({ data: { id: 'drs-id', status: 'in-progress' } }));
+        const assertion = expect(
+          createApi().startAsync({ remoteConfig: {} }, { retries: 3 })
+        ).resolves.toMatchObject({ status: 'in-progress' });
+        await jest.runAllTimersAsync();
+        await assertion;
+        expect(turtleFetch).toHaveBeenCalledTimes(2);
+      } finally {
+        jest.useRealTimers();
+      }
+    }
+  );
+});

packages/build-tools/src/steps/utils/__tests__/deviceRunSessionWorkerApiCallers.test.ts

@@ -7,6 +7,7 @@ import { setImmediate } from 'node:timers/promises';
 
 import { type CustomBuildContext } from '../../../customBuildContext';
 import RemoteLoggerStream from '../../../logging/RemoteLoggerStream';
+import { Sentry } from '../../../sentry';
 import { turtleFetch } from '../../../utils/turtleFetch';
 import { downloadBuildAsync } from '../../functions/downloadBuild';
 import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
@@ -151,10 +152,11 @@ describe('with a device run session token', () => {
     expect(ctx.graphqlClient.mutation).not.toHaveBeenCalled();
   });
 
-  it('starts the session through the worker API', async () => {
+  it('retries a transient failure when starting the session through the worker API', async () => {
     const ctx = createCtx({ withToken: true });
     jest
       .mocked(turtleFetch)
+      .mockResolvedValueOnce(jsonResponse({ errors: [{ message: 'Service unavailable' }] }, 503))
       .mockResolvedValueOnce(jsonResponse({ data: { id: 'drs-id', status: 'in-progress' } }));
 
     await uploadRemoteSessionConfigAsync({
@@ -165,9 +167,57 @@ describe('with a device run session token', () => {
     });
 
     expectWorkerApiCall('start', 'POST', { json: { remoteConfig: { type: 'agent-device' } } });
+    expect(turtleFetch).toHaveBeenCalledTimes(2);
     expect(ctx.graphqlClient.mutation).not.toHaveBeenCalled();
   });
 
+  it('handles the structured stopped code without matching the message', async () => {
+    const ctx = createCtx({ withToken: true });
+    jest.mocked(turtleFetch).mockResolvedValueOnce(
+      jsonResponse(
+        {
+          errors: [
+            { code: 'DEVICE_RUN_SESSION_ALREADY_STOPPED', message: 'A different explanation.' },
+          ],
+        },
+        400
+      )
+    );
+    await expect(
+      uploadRemoteSessionConfigAsync({
+        ctx,
+        deviceRunSessionId: 'drs-id',
+        remoteConfig: {},
+        logger,
+      })
+    ).resolves.toBe('stopped');
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+    expect(logger.info).toHaveBeenCalledWith(
+      'Device run session drs-id was stopped during startup.'
+    );
+  });
+
+  it.each([undefined, 'VALIDATION_ERROR'])('preserves an ordinary 400 with code %s', async code => {
+    const ctx = createCtx({ withToken: true });
+    jest
+      .mocked(turtleFetch)
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { errors: [{ code, message: 'Device run session has already stopped.' }] },
+          400
+        )
+      );
+    await expect(
+      uploadRemoteSessionConfigAsync({
+        ctx,
+        deviceRunSessionId: 'drs-id',
+        remoteConfig: {},
+        logger,
+      })
+    ).rejects.toBeInstanceOf(SystemError);
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+  });
+
   it('fails the start with a system error that does not contain the token', async () => {
     const ctx = createCtx({ withToken: true });
     jest
@@ -213,10 +263,52 @@ describe('with a device run session token', () => {
       '--turn-credential',
       'credential',
     ]);
-    expectWorkerApiCall('turn-ice-servers', 'POST', { timeout: 5000, retries: 1 });
+    expectWorkerApiCall('turn-ice-servers', 'POST', { timeout: 5000, retries: 0 });
     expect(jest.mocked(turtleFetch)).toHaveBeenCalledTimes(1);
   });
 
+  it('handles a stopped-session TURN response without a warning or retry', async () => {
+    const ctx = createCtx({ withToken: true });
+    jest
+      .mocked(turtleFetch)
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { errors: [{ code: 'DEVICE_RUN_SESSION_ALREADY_STOPPED', message: 'Stopped.' }] },
+          400
+        )
+      );
+
+    await expect(fetchWebPreviewTurnArgsAsync(ctx, { logger })).resolves.toEqual([]);
+
+    expect(logger.info).toHaveBeenCalledWith(
+      'Device run session was stopped before TURN credentials were fetched.'
+    );
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(Sentry.capture).not.toHaveBeenCalled();
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([undefined, 'VALIDATION_ERROR'])(
+    'still warns on a TURN failure with code %s',
+    async code => {
+      const ctx = createCtx({ withToken: true });
+      jest
+        .mocked(turtleFetch)
+        .mockResolvedValueOnce(
+          jsonResponse(
+            { errors: [{ code, message: 'Device run session has already stopped.' }] },
+            400
+          )
+        );
+
+      await expect(fetchWebPreviewTurnArgsAsync(ctx, { logger })).resolves.toEqual([]);
+
+      expect(logger.warn).toHaveBeenCalled();
+      expect(Sentry.capture).toHaveBeenCalled();
+      expect(turtleFetch).toHaveBeenCalledTimes(1);
+    }
+  );
+
   it('creates artifact upload sessions through the worker API', async () => {
     const ctx = createCtx({ withToken: true });
     jest.mocked(turtleFetch).mockResolvedValueOnce(
@@ -362,7 +454,9 @@ describe('with a device run session token', () => {
         robotAccessToken: ROBOT_ACCESS_TOKEN,
         extensions: ['app'],
       })
-    ).rejects.toThrow('Unexpected response from server (500): stop here');
+    ).rejects.toThrow(
+      `Failed to download the application archive for build ${BUILD_ID} (HTTP 500): stop here`
+    );
 
     expectWorkerApiCall('application', 'GET');
     expect(jest.mocked(fetch)).toHaveBeenCalledWith(
@@ -587,7 +681,9 @@ describe('without a device run session token', () => {
         robotAccessToken: ROBOT_ACCESS_TOKEN,
         extensions: ['app'],
       })
-    ).rejects.toThrow('Unexpected response from server (500)');
+    ).rejects.toThrow(
+      `Failed to download the application archive for build ${BUILD_ID} (HTTP 500): stop here`
+    );
 
     expect(ctx.graphqlClient.query).toHaveBeenCalled();
     expect(jest.mocked(fetch)).toHaveBeenCalledWith(

packages/build-tools/src/steps/utils/__tests__/deviceSessionHost.test.ts

@@ -12,7 +12,9 @@ import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
 import { verifyLocalEgressGuardAsync } from '../localEgressGuard';
 import { type ServeSimApplicationOptions } from '../remoteDeviceRunSession';
 
+import { readLocalEgressHandoffAsync } from '../localEgress';
 import { runServeSimActionAsync, stageServeSimAppAsync } from '../serveSimActions';
+import { startServeSimActivityPolling } from '../serveSimActivity';
 import { readServeSimServersAsync } from '../serveSimMetricsRecorder';
 import { Sentry } from '../../../sentry';
 import { turtleFetch } from '../../../utils/turtleFetch';
@@ -22,6 +24,7 @@ import {
   uploadDeviceRunSessionScreenRecordingsAsync,
 } from '../deviceRunSessionScreenRecordings';
 import {
+  captureDeviceRunSessionPreviewAsync,
   ensureMacosPreviewEncoderInstalledAsync,
   startDeviceRunSessionPreview,
 } from '../deviceRunSessionPreview';
@@ -44,6 +47,11 @@ jest.mock('../../../utils/IosSimulatorUtils', () => ({
 }));
 jest.mock('../localEgressGuard', () => ({ verifyLocalEgressGuardAsync: jest.fn() }));
 jest.mock('../serveSimActions');
+jest.mock('../serveSimActivity');
+jest.mock('../localEgress', () => ({
+  ...jest.requireActual('../localEgress'),
+  readLocalEgressHandoffAsync: jest.fn().mockResolvedValue(null),
+}));
 jest.mock('../deviceRunSessionArtifacts');
 jest.mock('../../../sentry');
 jest.mock('../serveSimMetricsRecorder', () => ({
@@ -61,6 +69,7 @@ jest.mock('../remoteDeviceRunSession', () => ({
 jest.mock('../deviceRunSessionPreview', () => ({
   ...jest.requireActual('../deviceRunSessionPreview'),
   ensureMacosPreviewEncoderInstalledAsync: jest.fn(),
+  captureDeviceRunSessionPreviewAsync: jest.fn(),
   startDeviceRunSessionPreview: jest.fn(),
 }));
 jest.mock('../deviceRunSessionScreenRecordings', () => ({
@@ -129,6 +138,7 @@ beforeEach(() => {
   jest.clearAllMocks();
   jest.mocked(IosSimulatorUtils.disableApsdAsync).mockReset().mockResolvedValue(undefined);
   jest.mocked(verifyLocalEgressGuardAsync).mockReset().mockResolvedValue(undefined);
+  jest.mocked(readLocalEgressHandoffAsync).mockReset().mockResolvedValue(null);
   stopSessionPreview.mockResolvedValue(undefined);
   jest.mocked(startDeviceRunSessionPreview).mockReturnValue({ stopAsync: stopSessionPreview });
   jest.mocked(ensureFfmpegInstalledOnceAsync).mockResolvedValue(undefined);
@@ -183,6 +193,91 @@ afterEach(async () => {
   );
 });
 
+it.each([undefined, '', 'invalid serial', 'all', 'booted'])(
+  'starts Hub without adding a device restriction for %j',
+  async previewDeviceId => {
+    const host = await startDeviceSessionHostAsync(ctx, {
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env,
+      logger,
+      timeoutMs: 10_000,
+      previewDeviceId,
+    });
+    try {
+      expect(jest.mocked(spawnDetached).mock.calls[0][0].args).not.toContain('--single-device');
+    } finally {
+      await host.finishAsync();
+    }
+  }
+);
+
+it('uses the supplied Android serial for Hub and thumbnails without selecting another device', async () => {
+  jest.mocked(turtleFetch).mockResolvedValue({
+    ok: true,
+    json: async () => ({ status: 'ready', device: 'no-device-id' }),
+  } as Awaited<ReturnType<typeof turtleFetch>>);
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.LINUX,
+    env,
+    logger,
+    timeoutMs: 10_000,
+    previewDeviceId: 'emulator-5556',
+  });
+  try {
+    const args = jest.mocked(spawnDetached).mock.calls[0][0].args;
+    expect(
+      args.slice(args.indexOf('--single-device'), args.indexOf('--single-device') + 2)
+    ).toEqual(['--single-device', 'emulator-5556']);
+    await new Promise(resolve => setImmediate(resolve));
+    await jest
+      .mocked(startDeviceRunSessionPreview)
+      .mock.calls[0][0].captureAsync(new AbortController().signal);
+    expect(captureDeviceRunSessionPreviewAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ device: 'emulator-5556' })
+    );
+  } finally {
+    await host.finishAsync();
+  }
+});
+
+it('pins an already-booted iOS preview without taking over boot or setup', async () => {
+  const udid = 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA';
+  jest.mocked(turtleFetch).mockResolvedValue({
+    ok: true,
+    json: async () => ({ status: 'ready', device: udid }),
+  } as Awaited<ReturnType<typeof turtleFetch>>);
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.DARWIN,
+    env,
+    logger,
+    timeoutMs: 10_000,
+    previewDeviceId: udid,
+  });
+  try {
+    const args = jest.mocked(spawnDetached).mock.calls[0][0].args;
+    expect(
+      args.slice(args.indexOf('--single-device'), args.indexOf('--single-device') + 2)
+    ).toEqual(['--single-device', udid]);
+    expect(IosSimulatorUtils.disableApsdAsync).not.toHaveBeenCalled();
+    expect(runServeSimActionAsync).not.toHaveBeenCalled();
+  } finally {
+    await host.finishAsync();
+  }
+});
+
+it('rejects readiness on a different Simulator from the selected preview target', async () => {
+  await expect(
+    startDeviceSessionHostAsync(ctx, {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env,
+      logger,
+      timeoutMs: 10_000,
+      previewDeviceId: 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA',
+    })
+  ).rejects.toThrow('but this session requested AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA');
+  expect(stopServer).toHaveBeenCalled();
+});
+
 it('targets the selected Simulator in the serve-sim invocation', () => {
   expect(createServeSimArgs({ port: 4321, iosSimulatorUdid: 'session-udid' }).slice(0, 4)).toEqual([
     '@expo/serve-sim@latest',
@@ -452,6 +547,62 @@ it('starts the readiness budget after refusals that exceed the normal startup de
   await rejected;
 });
 
+it('reports preview activity from serve-sim on iOS and stops polling when finished', async () => {
+  const observedAt = new Date('2026-10-19T12:00:00Z');
+  const stopActivity = jest.fn().mockResolvedValue(undefined);
+  jest.mocked(startServeSimActivityPolling).mockReturnValue({
+    getLastActivityObservedAt: () => observedAt,
+    stopAsync: stopActivity,
+  });
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.DARWIN,
+    env,
+    logger,
+    timeoutMs: 10_000,
+  });
+  const port = Number(
+    jest.mocked(spawnDetached).mock.calls[0][0].args[
+      jest.mocked(spawnDetached).mock.calls[0][0].args.indexOf('--port') + 1
+    ]
+  );
+
+  expect(startServeSimActivityPolling).toHaveBeenCalledWith({
+    port,
+    token: 'preview-token',
+    logger: expect.anything(),
+  });
+  expect(host.getLastPreviewActivityAt()).toBe(observedAt);
+
+  await host.finishAsync();
+  expect(stopActivity).toHaveBeenCalledTimes(1);
+});
+
+it('does not start polling preview activity when startup is cancelled', async () => {
+  const controller = new AbortController();
+  jest.mocked(IosSimulatorUtils.disableApsdAsync).mockImplementation(async () => {
+    controller.abort(new Error('cancelled'));
+  });
+  await expect(
+    startDeviceSessionHostAsync(ctx, {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      iosSimulatorUdid: 'emulator-5554',
+      env,
+      logger,
+      timeoutMs: 10_000,
+      signal: controller.signal,
+    })
+  ).rejects.toThrow();
+  expect(startServeSimActivityPolling).not.toHaveBeenCalled();
+});
+
+it('reports no preview activity on Android, where expo-device-hub keeps no event log', async () => {
+  const host = await startHostAsync();
+
+  expect(startServeSimActivityPolling).not.toHaveBeenCalled();
+  expect(host.getLastPreviewActivityAt()).toBeUndefined();
+  await host.finishAsync();
+});
+
 it('stops a host that became ready on a different Simulator', async () => {
   await expect(
     startDeviceSessionHostAsync(ctx, {
@@ -1319,8 +1470,37 @@ it('uses the existing step logger for startup and shutdown output', async () =>
   ).toBe(false);
 });
 
+it('passes the active local-egress address to serve-sim without tunnel credentials', async () => {
+  jest.mocked(readLocalEgressHandoffAsync).mockResolvedValue({
+    port: 8899,
+    url: 'https://tunnel.example',
+    token: 'tunnel-secret',
+    fingerprint: 'fingerprint',
+  });
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.DARWIN,
+    env,
+    logger,
+    timeoutMs: 10_000,
+    networkCapture: true,
+  });
+  const spawned = jest.mocked(spawnDetached).mock.calls[0][0];
+  expect(spawned.args).toEqual(
+    expect.arrayContaining(['--network-capture-proxy', 'http://127.0.0.1:8899'])
+  );
+  expect(spawned.args).toContain('--network-capture');
+  expect(JSON.stringify(spawned)).not.toContain('tunnel-secret');
+  await host.finishAsync();
+});
+
+it('does not read the iOS egress handoff for an Android host', async () => {
+  const host = await startHostAsync();
+  expect(readLocalEgressHandoffAsync).not.toHaveBeenCalled();
+  await host.finishAsync();
+});
+
 it.each([true, false])(
-  'waits for setup before launch or boot-only readiness (app: %s)',
+  'runs setup in parallel with app launch and readiness, then joins it at teardown (app: %s)',
   async hasApp => {
     const setup = deferred<void>();
     const prepared = deferred<ServeSimApplicationOptions | void>();
@@ -1375,70 +1555,78 @@ it.each([true, false])(
         ? { installAppPath: '/tmp/App.app', launchAppIdentifier: 'dev.example.other' }
         : undefined
     );
-    if (!hasApp) {
-      let queried = false;
-      ready.resolve({
-        ok: true,
-        json: async () => {
-          queried = true;
-          return { status: 'ready', device: 'emulator-5554' };
-        },
-      } as never);
-      let reported = false;
-      void starting.then(() => {
-        reported = true;
-      });
-      while (!queried) {
-        await new Promise(resolve => setImmediate(resolve));
+    if (hasApp) {
+      while (!jest.mocked(runServeSimActionAsync).mock.calls.length) {
+        await new Promise(resolve => setTimeout(resolve, 10));
       }
       await new Promise(resolve => setImmediate(resolve));
-      expect(reported).toBe(false);
+      expect(runServeSimActionAsync).toHaveBeenCalledTimes(2);
+    } else {
       expect(runServeSimActionAsync).not.toHaveBeenCalled();
-      setup.resolve();
-      const host = await starting;
-      expect(runServeSimActionAsync).not.toHaveBeenCalled();
-      await host.finishAsync();
-      return;
-    }
-    while (!jest.mocked(runServeSimActionAsync).mock.calls.length) {
-      await new Promise(resolve => setTimeout(resolve, 10));
-    }
-    await new Promise(resolve => setImmediate(resolve));
-    expect(runServeSimActionAsync).toHaveBeenCalledTimes(1);
-    setup.resolve();
-    while (jest.mocked(runServeSimActionAsync).mock.calls.length < 2) {
-      await new Promise(resolve => setTimeout(resolve, 10));
     }
     expect(
       jest
         .mocked(runServeSimActionAsync)
         .mock.calls.map(([options]) => [options.action, options.params])
-    ).toEqual([
-      ['app.install', { udid: 'emulator-5554', path: `${directory}/App.app` }],
-      [
-        'app.launch',
-        {
-          udid: 'emulator-5554',
-          bundleId: 'dev.example.other',
-          launchArgs: [],
-          openUrl: undefined,
-        },
-      ],
-    ]);
-    expect(runServeSimActionAsync).toHaveBeenCalledWith(
-      expect.objectContaining({ token: 'preview-token', timeoutMs: 120_000 })
-    );
-    expect(stageServeSimAppAsync).toHaveBeenCalledWith(
-      '/tmp/App.app',
-      env.TMPDIR ?? require('node:os').tmpdir()
+    ).toEqual(
+      hasApp
+        ? [
+            ['app.install', { udid: 'emulator-5554', path: `${directory}/App.app` }],
+            [
+              'app.launch',
+              {
+                udid: 'emulator-5554',
+                bundleId: 'dev.example.other',
+                launchArgs: [],
+                openUrl: undefined,
+              },
+            ],
+          ]
+        : []
     );
+    if (hasApp) {
+      expect(runServeSimActionAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ token: 'preview-token', timeoutMs: 120_000 })
+      );
+      expect(stageServeSimAppAsync).toHaveBeenCalledWith(
+        '/tmp/App.app',
+        env.TMPDIR ?? require('node:os').tmpdir()
+      );
+    }
+    let queried = false;
     ready.resolve({
       ok: true,
-      json: async () => ({ status: 'ready', device: 'emulator-5554' }),
+      json: async () => {
+        queried = true;
+        return { status: 'ready', device: 'emulator-5554' };
+      },
     } as never);
-    const host = await starting;
-    await host.finishAsync();
-    await expect(access(directory)).rejects.toThrow();
+    let reported = false;
+    void starting.then(() => {
+      reported = true;
+    });
+    while (!queried) {
+      await new Promise(resolve => setImmediate(resolve));
+    }
+    await new Promise(resolve => setImmediate(resolve));
+    try {
+      expect(reported).toBe(true);
+      const host = await starting;
+      let finished = false;
+      const finishing = host.finishAsync().then(() => {
+        finished = true;
+      });
+      await new Promise(resolve => setImmediate(resolve));
+      expect(finished).toBe(false);
+      setup.resolve();
+      await finishing;
+    } finally {
+      setup.resolve();
+      await (await starting).finishAsync();
+    }
+    if (hasApp) {
+      await expect(access(directory)).rejects.toThrow();
+    }
   }
 );
 
@@ -1583,7 +1771,8 @@ it('warns and continues launching when disabling push fails', async () => {
   await host.finishAsync();
 });
 
-it('cancels pending setup without launching and observes its late failure', async () => {
+it('cancels pending app preparation and observes late setup failure', async () => {
+  const application = deferred<ServeSimApplicationOptions>();
   const controller = new AbortController();
   let rejectSetup!: (error: Error) => void;
   jest.mocked(IosSimulatorUtils.disableApsdAsync).mockReturnValue(
@@ -1597,7 +1786,7 @@ it('cancels pending setup without launching and observes its late failure', asyn
     logger,
     timeoutMs: 2_000,
     iosSimulatorUdid: 'emulator-5554',
-    launchAppIdentifier: 'dev.example.app',
+    application: application.promise,
     signal: controller.signal,
   });
   const rejected = expect(starting).rejects.toThrow('session canceled');

packages/build-tools/src/steps/utils/__tests__/preinstalledWda.test.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+import * as processes from '../../../utils/processes';
 import { preparePreinstalledWdaAsync } from '../preinstalledWda';
 
 jest.mock('@expo/turtle-spawn', () => ({ __esModule: true, default: jest.fn() }));
@@ -78,3 +79,37 @@ it('does not enable preinstalled startup when the download produces no runner',
   jest.mocked(spawn).mockResolvedValue({ stdout: '' } as never);
   await expect(preparePreinstalledWdaAsync(options)).resolves.toEqual({});
 });
+
+it('drains an aborted WDA downloader before removing its partial artifact', async () => {
+  await fs.promises.mkdir(outdir, { recursive: true });
+  const controller = new AbortController();
+  const error = new Error('Simulator startup failed');
+  const child = { pid: 12345, kill: jest.fn() };
+  let closeDownloader!: (error: Error) => void;
+  jest.mocked(spawn).mockReturnValueOnce(
+    Object.assign(
+      new Promise((_resolve, reject) => {
+        closeDownloader = reject;
+      }),
+      { child }
+    ) as never
+  );
+  const killGroup = jest.spyOn(processes, 'killProcessGroup').mockImplementation(() => {});
+  const running = preparePreinstalledWdaAsync({ ...options, signal: controller.signal });
+  const settled = jest.fn();
+  const observed = running.then(settled, settled);
+  try {
+    controller.abort(error);
+    expect(killGroup).toHaveBeenCalledWith(child, 'SIGKILL');
+    expect(settled).not.toHaveBeenCalled();
+    expect(fs.existsSync(outdir)).toBe(true);
+    closeDownloader(new Error('download interrupted'));
+    await expect(running).rejects.toBe(error);
+    expect(fs.existsSync(outdir)).toBe(false);
+    expect(logger.warn).not.toHaveBeenCalled();
+  } finally {
+    closeDownloader(error);
+    await observed;
+    killGroup.mockRestore();
+  }
+});

packages/build-tools/src/steps/utils/__tests__/remoteDeviceRunSession.test.ts

@@ -18,6 +18,7 @@ import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { CustomBuildContext } from '../../../customBuildContext';
 import { Sentry } from '../../../sentry';
 import { turtleFetch } from '../../../utils/turtleFetch';
+import * as processes from '../../../utils/processes';
 import {
   IosSimulatorRecordingUtils,
   SERVE_SIM_STOP_GRACE_PERIOD_MS,
@@ -529,6 +530,22 @@ describe(describeServeSimLaunch, () => {
   });
 });
 
+it('only pins hosts when a valid device ID is supplied', () => {
+  const udid = 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA';
+  expect(createServeSimArgs({ port: 4321, iosSimulatorUdid: udid })).toEqual(
+    expect.arrayContaining(['--single-device', udid])
+  );
+  for (const iosSimulatorUdid of [undefined, '', 'booted', 'iPhone 17']) {
+    expect(createServeSimArgs({ port: 4321, iosSimulatorUdid })).not.toContain('--single-device');
+  }
+  expect(createExpoDeviceHubArgs({ port: 4321, device: 'emulator-5554' })).toEqual(
+    expect.arrayContaining(['--single-device', 'emulator-5554'])
+  );
+  for (const device of [undefined, '', 'all', 'booted', 'invalid serial']) {
+    expect(createExpoDeviceHubArgs({ port: 4321, device })).not.toContain('--single-device');
+  }
+});
+
 describe(createServeSimArgs, () => {
   it('uses the latest Expo package and applies the EAS streaming policy', () => {
     expect(
@@ -660,6 +677,14 @@ describe(createServeSimArgs, () => {
     );
   });
 
+  it('passes a capture proxy as one argument, including when capture will be enabled later', () => {
+    const proxy = 'http://user:p%40ss%[email protected]:8899';
+    const args = createServeSimArgs({ port: 4321, networkCaptureProxy: proxy });
+    expect(args.slice(-2)).toEqual(['--network-capture-proxy', proxy]);
+    expect(args).not.toContain('--network-capture');
+    expect(createServeSimArgs({ port: 4321 })).not.toContain('--network-capture-proxy');
+  });
+
   it('appends --network-capture when enabled, which also covers an already booted simulator', () => {
     const args = createServeSimArgs({ port: 4321, networkCapture: true });
     expect(args).toContain('--network-capture');
@@ -1930,6 +1955,47 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
       expect(logger.info).toHaveBeenCalledWith('Device run session drs-id was stopped.');
     });
 
+    it('keeps the session alive while preview input keeps arriving', async () => {
+      const ctx = createStatusCtxMock([...manyInProgressStatuses(), { status: 'stopped' }]);
+      const logger = createLoggerMock();
+
+      await waitForDeviceRunSessionStoppedAsync({
+        ctx,
+        deviceRunSessionId: 'drs-id',
+        logger,
+        idleTimeout: {
+          maxIdleTimeMinutes: 1,
+          getLastEventObservedAt: () => undefined,
+          getLastPreviewActivityAt: () => new Date(),
+        },
+      });
+
+      expect(workerApiCallCount('session')).toBe(21);
+      expect(workerApiCallCount('stop')).toBe(0);
+    });
+
+    it('counts idle time from the later of automation and preview activity', async () => {
+      const ctx = createStatusCtxMock(manyInProgressStatuses());
+      const logger = createLoggerMock();
+      const previewInputAt = new Date(Date.now() + 30_000);
+
+      await waitForDeviceRunSessionStoppedAsync({
+        ctx,
+        deviceRunSessionId: 'drs-id',
+        logger,
+        idleTimeout: {
+          maxIdleTimeMinutes: 1,
+          getLastEventObservedAt: () => undefined,
+          getLastPreviewActivityAt: () =>
+            Date.now() >= previewInputAt.getTime() ? previewInputAt : undefined,
+        },
+      });
+
+      // Idle from 30 s, so the stop comes at 90 s: 18 polls.
+      expect(workerApiCallCount('session')).toBe(18);
+      expect(workerApiCallCount('stop')).toBe(1);
+    });
+
     it('still returns when the session cannot be marked stopped', async () => {
       const ctx = createStatusCtxMock(manyInProgressStatuses(), {
         stopError: new Error('forbidden'),
@@ -2135,6 +2201,105 @@ describe(ensureFfmpegInstalledOnceAsync, () => {
     expect(spawnMock).toHaveBeenCalledTimes(3);
   });
 
+  it('retries one aborted FFmpeg install for two surviving shared callers after it drains', async () => {
+    const controller = new AbortController();
+    const error = new Error('Simulator startup failed');
+    const child = { pid: 12345, kill: jest.fn() };
+    let closeInstaller!: (error: Error) => void;
+    spawnMock.mockReturnValueOnce(
+      Object.assign(
+        new Promise((_resolve, reject) => {
+          closeInstaller = reject;
+        }),
+        { child }
+      ) as never
+    );
+    let finishReplacement!: () => void;
+    spawnMock.mockReturnValueOnce(
+      new Promise<void>(resolve => {
+        finishReplacement = resolve;
+      }) as never
+    );
+    spawnMock.mockReturnValue(spawnResolved());
+    const killGroup = jest.spyOn(processes, 'killProcessGroup').mockImplementation(() => {});
+    const options = {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: createPathEnv(),
+      logger: createLoggerMock(),
+    };
+    const owner = ensureFfmpegInstalledOnceAsync({ ...options, signal: controller.signal });
+    const surviving = [
+      ensureFfmpegInstalledOnceAsync(options),
+      ensureFfmpegInstalledOnceAsync({ ...options, signal: new AbortController().signal }),
+    ];
+    const settled = jest.fn();
+    const observed = owner.then(settled, settled);
+    const borrowersSettled = jest.fn();
+    const observedBorrowers = Promise.all(surviving).then(borrowersSettled, borrowersSettled);
+    try {
+      await new Promise<void>(resolve => setImmediate(resolve));
+      controller.abort(error);
+      expect(killGroup).toHaveBeenCalledWith(child, 'SIGKILL');
+      expect(settled).not.toHaveBeenCalled();
+      expect(spawnMock).toHaveBeenCalledTimes(1);
+      closeInstaller(new Error('brew interrupted'));
+      await expect(owner).rejects.toBe(error);
+      await new Promise<void>(resolve => setImmediate(resolve));
+      expect(spawnMock).toHaveBeenCalledTimes(2);
+      expect(borrowersSettled).not.toHaveBeenCalled();
+      finishReplacement();
+      await expect(Promise.all(surviving)).resolves.toEqual([undefined, undefined]);
+      expect(spawnMock).toHaveBeenCalledTimes(3);
+      expect(spawnMock).toHaveBeenLastCalledWith(...warmUpCall);
+      expect(options.logger.warn).not.toHaveBeenCalled();
+    } finally {
+      closeInstaller?.(error);
+      finishReplacement();
+      await Promise.all([observed, observedBorrowers]);
+      killGroup.mockRestore();
+    }
+  });
+
+  it('stops an aborted shared waiter without cancelling the installer owner', async () => {
+    let finishInstall!: () => void;
+    spawnMock.mockReturnValueOnce(
+      new Promise<void>(resolve => {
+        finishInstall = resolve;
+      }) as never
+    );
+    spawnMock.mockReturnValue(spawnResolved());
+    const killGroup = jest.spyOn(processes, 'killProcessGroup').mockImplementation(() => {});
+    const controller = new AbortController();
+    const error = new Error('Appium startup failed');
+    const options = {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: createPathEnv(),
+      logger: createLoggerMock(),
+    };
+    const owner = ensureFfmpegInstalledOnceAsync(options);
+    let ownerFinished = false;
+    const observedOwner = owner.then(() => {
+      ownerFinished = true;
+    });
+    const waiter = ensureFfmpegInstalledOnceAsync({ ...options, signal: controller.signal });
+    const observedWaiter = waiter.catch(() => {});
+    try {
+      await new Promise<void>(resolve => setImmediate(resolve));
+      controller.abort(error);
+      await expect(waiter).rejects.toBe(error);
+      expect(ownerFinished).toBe(false);
+      expect(killGroup).not.toHaveBeenCalled();
+      expect(spawnMock).toHaveBeenCalledTimes(1);
+      finishInstall();
+      await expect(owner).resolves.toBeUndefined();
+      expect(spawnMock).toHaveBeenLastCalledWith(...warmUpCall);
+    } finally {
+      finishInstall();
+      await Promise.all([observedOwner, observedWaiter]);
+      killGroup.mockRestore();
+    }
+  });
+
   it('still installs on linux when the apt index refresh fails', async () => {
     spawnMock
       .mockReturnValueOnce(spawnRejected()) // apt-get update
@@ -2172,6 +2337,30 @@ describe(ensureFfmpegInstalledOnceAsync, () => {
     expect(jest.mocked(Sentry).capture).toHaveBeenCalled();
   });
 
+  it('does not retry an ordinary shared FFmpeg install failure', async () => {
+    let failInstall!: (error: Error) => void;
+    spawnMock.mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failInstall = reject;
+      }) as never
+    );
+    const options = {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: createPathEnv(),
+      logger: createLoggerMock(),
+    };
+    const callers = [
+      ensureFfmpegInstalledOnceAsync(options),
+      ensureFfmpegInstalledOnceAsync(options),
+      ensureFfmpegInstalledOnceAsync({ ...options, signal: new AbortController().signal }),
+    ];
+    await new Promise<void>(resolve => setImmediate(resolve));
+    failInstall(new Error('Homebrew unavailable'));
+    await expect(Promise.all(callers)).resolves.toEqual([undefined, undefined, undefined]);
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(options.logger.warn).toHaveBeenCalledTimes(1);
+  });
+
   // The caller runs this with `void` and the worker installs no unhandledRejection
   // handler, so a rejection here would crash the process. `spawn` is not async and
   // can throw synchronously, which `asyncResult` cannot catch.

packages/build-tools/src/steps/utils/__tests__/sandboxArtifacts.test.ts

@@ -2,6 +2,14 @@ jest.unmock('fs');
 jest.unmock('fs/promises');
 jest.unmock('node:fs');
 jest.unmock('node:fs/promises');
+jest.mock('node-fetch', () => {
+  const actual = jest.requireActual('node-fetch');
+  return {
+    __esModule: true,
+    ...actual,
+    default: jest.fn(),
+  };
+});
 
 import { SandboxDaemonErrorCode, SystemError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
@@ -310,7 +318,7 @@ describe('sandbox artifact uploads', () => {
     expect(logger.error).toHaveBeenCalledTimes(1);
     const logged = inspect([logger.info.mock.calls, logger.error.mock.calls], { depth: 10 });
     expect(fetch).toHaveBeenCalledTimes(3);
-    expect(logged).toContain('Artifact PUT failed: ECONNRESET.');
+    expect(logged).toContain('Signed URL upload failed: ECONNRESET.');
     expect(logged).not.toContain('secret-signature');
   });
 

packages/build-tools/src/steps/utils/__tests__/serveSimActivity.test.ts

@@ -0,0 +1,196 @@
+import { type bunyan } from '@expo/logger';
+import { once } from 'node:events';
+import http from 'node:http';
+
+import { fetchLatestServeSimEventIdAsync, startServeSimActivityPolling } from '../serveSimActivity';
+
+const token = 'test-session-token';
+let server: http.Server;
+let port: number;
+let events: { id: number }[];
+let status: number;
+let requests: { url?: string; authorization?: string }[];
+let rawBody: string | undefined;
+
+function createLoggerMock(): bunyan {
+  return { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
+}
+
+beforeEach(async () => {
+  events = [];
+  status = 200;
+  requests = [];
+  rawBody = undefined;
+  server = http.createServer((req, res) => {
+    requests.push({ url: req.url, authorization: req.headers.authorization });
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(rawBody ?? JSON.stringify({ events: events.slice(-1) }));
+  });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  port = (server.address() as { port: number }).port;
+});
+
+afterEach(async () => {
+  await new Promise<void>(resolve => server.close(() => resolve()));
+});
+
+describe(fetchLatestServeSimEventIdAsync, () => {
+  it('reads the newest event ID with the session token', async () => {
+    events = [{ id: 3 }, { id: 7 }];
+    await expect(fetchLatestServeSimEventIdAsync({ port, token })).resolves.toBe(7);
+    expect(requests).toEqual([{ url: '/api/event-log?limit=1', authorization: `Bearer ${token}` }]);
+  });
+
+  it('returns undefined when serve-sim has logged no event', async () => {
+    await expect(fetchLatestServeSimEventIdAsync({ port, token })).resolves.toBeUndefined();
+  });
+
+  it.each([
+    ['unparseable JSON', 'not json'],
+    ['a body without an events array', '{}'],
+    ['an entry without a numeric ID', '{"events":[{"id":"7"}]}'],
+  ])('rejects %s', async (_, body) => {
+    rawBody = body;
+    await expect(fetchLatestServeSimEventIdAsync({ port, token })).rejects.toThrow(
+      'serve-sim event log'
+    );
+  });
+
+  it('rejects a refused request', async () => {
+    status = 401;
+    await expect(fetchLatestServeSimEventIdAsync({ port, token })).rejects.toThrow('401');
+  });
+});
+
+describe(startServeSimActivityPolling, () => {
+  async function waitForRequestsAsync(count: number): Promise<void> {
+    while (requests.length < count) {
+      await new Promise(resolve => setTimeout(resolve, 5));
+    }
+  }
+
+  it('reports activity only when a new event appears', async () => {
+    const polling = startServeSimActivityPolling({
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      expect(polling.getLastActivityObservedAt()).toBeUndefined();
+
+      events = [{ id: 1 }];
+      const before = Date.now();
+      await waitForRequestsAsync(requests.length + 2);
+      const firstSeen = polling.getLastActivityObservedAt();
+      expect(firstSeen?.getTime()).toBeGreaterThanOrEqual(before);
+
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBe(firstSeen);
+
+      events = [{ id: 1 }, { id: 2 }];
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).not.toBe(firstSeen);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports current activity while the event log fails, and warns once', async () => {
+    status = 500;
+    const logger = createLoggerMock();
+    const polling = startServeSimActivityPolling({ port, token, logger, pollIntervalMs: 10 });
+    try {
+      await waitForRequestsAsync(3);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+      const before = Date.now();
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+
+      status = 200;
+      events = [{ id: 4 }];
+      await waitForRequestsAsync(requests.length + 2);
+      const observedAt = polling.getLastActivityObservedAt();
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBe(observedAt);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('keeps the last observation while serve-sim refuses connections', async () => {
+    await new Promise<void>(resolve => server.close(() => resolve()));
+    server = http.createServer();
+    const polling = startServeSimActivityPolling({
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(polling.getLastActivityObservedAt()).toBeUndefined();
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports current activity when serve-sim drops the connection mid-response', async () => {
+    server.removeAllListeners('request');
+    server.on('request', (req, res) => {
+      requests.push({ url: req.url });
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': '100' });
+      res.write('{"events":');
+      setImmediate(() => res.socket?.destroy());
+    });
+    const polling = startServeSimActivityPolling({
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(3);
+      const before = Date.now();
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports current activity while serve-sim answers without an event log', async () => {
+    status = 404;
+    const polling = startServeSimActivityPolling({
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      const before = Date.now();
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+
+      status = 200;
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBeUndefined();
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('stops polling after stopAsync', async () => {
+    const polling = startServeSimActivityPolling({
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    await waitForRequestsAsync(1);
+    await polling.stopAsync();
+    const count = requests.length;
+    await new Promise(resolve => setTimeout(resolve, 50));
+    expect(requests.length).toBe(count);
+  });
+});

packages/build-tools/src/steps/utils/agentRun.ts

@@ -1,6 +1,5 @@
 import { SystemError, UserError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
-import turtleSpawn from '@expo/turtle-spawn';
 import { spawn } from 'node:child_process';
 import { once } from 'node:events';
 import fs from 'node:fs/promises';
@@ -13,6 +12,7 @@ import { type AgentCli, type AgentInvocation, type AgentLogMessage } from './age
 import { CLAUDE_CODE_CLI, prepareClaudeCodeAsync } from './agents/claude';
 import { CODEX_CLI, prepareCodexAsync } from './agents/codex';
 import { Sentry } from '../../sentry';
+import { installIsolatedNpmPackageAsync } from '../../utils/installIsolatedNpmPackageAsync';
 import { killProcessGroup } from '../../utils/processes';
 
 export type AgentKind = 'claude-code' | 'codex';
@@ -76,17 +76,13 @@ export async function runAgentAsync({
     const { packageSpec, bin, formatOutputLine } = AGENT_CLIS[agentKind];
     logger.info(`Installing ${packageSpec}.`);
     try {
-      await turtleSpawn(
-        'npm',
-        [
-          'install',
-          ...['--prefix', cliDirectory],
-          ...['--no-save', '--package-lock=false', '--no-audit', '--no-fund'],
-          ...(npmCacheUrl ? ['--registry', npmCacheUrl] : []),
-          packageSpec,
-        ],
-        { env: minimalEnv, signal }
-      );
+      await installIsolatedNpmPackageAsync({
+        packageSpec,
+        directory: cliDirectory,
+        npmCacheUrl,
+        pathEnv,
+        signal,
+      });
     } catch (error) {
       signal.throwIfAborted();
       throw new SystemError(

packages/build-tools/src/steps/utils/android/GooglePlayUtils.ts

@@ -144,6 +144,7 @@ export namespace GooglePlayUtils {
       signal?: AbortSignal;
     }
   ): Promise<void> {
+    const attempts: unknown[] = [];
     const sendCommitAsync = async ({
       changesNotSentForReview,
     }: {
@@ -161,6 +162,7 @@ export namespace GooglePlayUtils {
           throw new SystemError('Google did not confirm the committed edit.');
         }
       } catch (error) {
+        attempts.push(...(error instanceof AggregateError ? error.errors : [error]));
         if (error instanceof GooglePlayAuthRequestError) {
           throw error;
         }
@@ -168,8 +170,14 @@ export namespace GooglePlayUtils {
           !(error instanceof GooglePlayApiError) ||
           GooglePlayApiError.isRetryableStatus(error.status)
         ) {
+          const attemptMessages = attempts
+            .map(
+              (attempt, index) =>
+                `${index + 1}. ${attempt instanceof Error ? attempt.message : String(attempt)}`
+            )
+            .join('\n');
           throw new GooglePlayCommitOutcomeUnknownError(
-            `Could not confirm whether Google Play saved the release for ${packageName}. Check its release status at https://play.google.com/console/ before submitting again.`,
+            `Could not confirm whether Google Play saved the release for ${packageName}. Check its release status at https://play.google.com/console/ before submitting again.\n\nCommit attempts:\n${attemptMessages}`,
             { cause: error, metadata: GooglePlayApiError.getErrorMetadata(error) }
           );
         }
@@ -196,7 +204,7 @@ export namespace GooglePlayUtils {
             signal?.throwIfAborted();
             return isUploadStillProcessing(error);
           },
-          { retries: 5, factor: 2, minTimeout: 2000, maxTimeout: 32_000 },
+          { retries: 13, factor: 2, minTimeout: 2000, maxTimeout: 32_000 },
           ({ attemptNumber, maxAttemptsCount }) => {
             logger.warn(
               `Google Play is still processing the uploaded bundle. Retrying the same edit commit (attempt ${attemptNumber}/${maxAttemptsCount}).`
@@ -206,7 +214,7 @@ export namespace GooglePlayUtils {
       } catch (error) {
         if (isUploadStillProcessing(error)) {
           throw new SystemError(
-            `Google Play did not finish processing the uploaded bundle for ${packageName} after six commit attempts. Wait a few minutes, then check the release at https://play.google.com/console/ before submitting again.`,
+            `Google Play did not finish processing the uploaded bundle for ${packageName} within five minutes. Wait a few minutes, then check the release at https://play.google.com/console/ before submitting again.`,
             { cause: error, metadata: GooglePlayApiError.getErrorMetadata(error) }
           );
         }

packages/build-tools/src/steps/utils/android/__tests__/GooglePlaySubmission.test.ts

@@ -84,6 +84,41 @@ it.each([408, 429, 503])('retries a transient HTTP %s commit on the same edit',
   api().post(`${editPath}:commit`).query({}).reply(200, { id: 'edit' });
   await expect(commit()).resolves.toBeUndefined();
 });
+it('shows failed commit attempts in order across processing, HTTP, and network retries', async () => {
+  mockToken();
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .reply(400, { error: { message: pendingUploadMessage } });
+  api().post(`${editPath}:commit`).query({}).reply(503);
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .replyWithError(Object.assign(new Error('Lost commit response'), { code: 'ECONNRESET' }));
+  const message = 'You must let us know whether your app includes any health features.';
+  api().post(`${editPath}:commit`).query({}).reply(403, { error: { message } });
+  const error = await commit().catch(error => error);
+  const mapped = GooglePlayUtils.mapGooglePlayError(error, packageName);
+  expect(mapped).toBeInstanceOf(GooglePlayCommitOutcomeUnknownError);
+  expect((mapped as Error).message).toContain(`Google Play request failed (HTTP 403): ${message}`);
+  expect((mapped as Error).message).toContain('Could not confirm whether Google Play saved');
+  expect((mapped as Error).message).toContain('https://play.google.com/console/');
+  expect(mapped).toMatchObject({
+    metadata: { googlePlayErrorResponse: JSON.stringify({ error: { message } }) },
+    cause: expect.any(AggregateError),
+  });
+  const attempts = (mapped as Error).message.split('Commit attempts:\n')[1]?.split('\n');
+  expect(attempts).toEqual([
+    `1. Google Play request failed (HTTP 400): ${pendingUploadMessage}`,
+    '2. Google Play request failed (HTTP 503).',
+    '3. Google Play request failed before a response was received.',
+    `4. Google Play request failed (HTTP 403): ${message}`,
+  ]);
+  expect(((mapped as Error).cause as AggregateError).errors).toHaveLength(3);
+  expect(((mapped as Error).cause as AggregateError).errors[1]).toMatchObject({
+    cause: { code: 'ECONNRESET' },
+  });
+});
 it('preserves cancellation before commit is sent', async () => {
   const controller = new AbortController();
   const reason = new Error('cancelled before commit');
@@ -110,12 +145,12 @@ it.each([false, true])(
   }
 );
 
-it('stops waiting for bundle processing after six attempts', async () => {
+it('stops waiting for bundle processing after 14 attempts', async () => {
   mockToken();
   api()
     .post(`${editPath}:commit`)
     .query({})
-    .times(6)
+    .times(14)
     .reply(400, { error: { message: pendingUploadMessage } });
   const error = await commit().catch(error => error);
   expect(GooglePlayUtils.mapGooglePlayError(error, packageName)).toMatchObject({
@@ -250,7 +285,9 @@ it('keeps the last Google Play error response when the commit outcome is unknown
     .query({})
     .times(6)
     .reply(503, { error: { message: 'Backend error' } });
-  await expect(commit()).rejects.toMatchObject({
+  const error = await commit().catch(error => error);
+  expect(error.message).toContain('Google Play request failed (HTTP 503): Backend error');
+  expect(error).toMatchObject({
     metadata: {
       googlePlayRequestPath: `${editPath}:commit`,
       googlePlayErrorResponse: JSON.stringify({ error: { message: 'Backend error' } }),

packages/build-tools/src/steps/utils/androidEmulatorLogs.ts

@@ -0,0 +1,221 @@
+import { type bunyan } from '@expo/logger';
+import { type BuildStepGlobalContext } from '@expo/steps';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdtemp, open, readdir, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+
+import { type CustomBuildContext } from '../../customBuildContext';
+import { type AndroidEmulatorLogSource } from '../../utils/androidEmulatorLogSources';
+import { uploadDeviceRunSessionArtifactAsync } from './deviceRunSessionArtifacts';
+
+const MAX_BYTES_PER_FILE = 20 * 1024 * 1024;
+const UPLOAD_TIMEOUT_MS = 30_000;
+
+type Collection = {
+  directories: Set<string>;
+  uploaded: Set<string>;
+  collecting?: Promise<void>;
+};
+
+// A worker can execute more than one job in its lifetime. Only the workflow that
+// created a directory may collect it; never discover logs by scanning /tmp.
+const collections = new WeakMap<BuildStepGlobalContext, Collection>();
+
+export function registerAndroidEmulatorLogDirectory(
+  global: BuildStepGlobalContext,
+  directory: string
+): void {
+  let collection = collections.get(global);
+  if (!collection) {
+    collection = { directories: new Set(), uploaded: new Set() };
+    collections.set(global, collection);
+  }
+  collection.directories.add(directory);
+}
+
+export async function collectAndroidEmulatorLogsAsync(
+  ctx: CustomBuildContext,
+  {
+    global,
+    deviceRunSessionId,
+    logger,
+    maxBytes = MAX_BYTES_PER_FILE,
+    sources = ['emulator-output'],
+  }: {
+    global: BuildStepGlobalContext;
+    deviceRunSessionId: string;
+    logger: bunyan;
+    maxBytes?: number;
+    sources?: readonly AndroidEmulatorLogSource[];
+  }
+): Promise<void> {
+  const collection = collections.get(global);
+  if (!collection) {
+    logger.info('No Android emulator log directories registered; skipping upload.');
+    return;
+  }
+  while (collection.collecting) {
+    await collection.collecting;
+  }
+  collection.collecting = uploadRegisteredLogsAsync(ctx, {
+    collection,
+    deviceRunSessionId,
+    logger,
+    maxBytes,
+    sources,
+  });
+  try {
+    await collection.collecting;
+  } finally {
+    collection.collecting = undefined;
+  }
+}
+
+async function uploadRegisteredLogsAsync(
+  ctx: CustomBuildContext,
+  {
+    collection,
+    deviceRunSessionId,
+    logger,
+    maxBytes,
+    sources,
+  }: {
+    collection: Collection;
+    deviceRunSessionId: string;
+    logger: bunyan;
+    maxBytes: number;
+    sources: readonly AndroidEmulatorLogSource[];
+  }
+): Promise<void> {
+  for (const directory of collection.directories) {
+    try {
+      const entries = await readdir(directory, { withFileTypes: true });
+      for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const match = /-(emulator|logcat)\.log$/.exec(entry.name);
+        if (!entry.isFile() || !match) {
+          continue;
+        }
+        const source = match[1] === 'emulator' ? 'emulator-output' : 'device-logcat';
+        if (!sources.includes(source)) {
+          continue;
+        }
+        const filePath = path.join(directory, entry.name);
+        if (collection.uploaded.has(filePath)) {
+          continue;
+        }
+        try {
+          const uploaded = await uploadLogSnapshotAsync(ctx, {
+            deviceRunSessionId,
+            filePath,
+            source,
+            maxBytes,
+            signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+            logger,
+          });
+          if (uploaded) {
+            collection.uploaded.add(filePath);
+            logger.info(`Uploaded Android diagnostic log ${entry.name}.`);
+          }
+        } catch (err) {
+          logger.warn(
+            { err },
+            `Could not upload Android log ${entry.name}; other logs will continue.`
+          );
+        }
+      }
+    } catch (err) {
+      logger.warn({ err }, `Could not read Android emulator log directory ${directory}.`);
+    }
+  }
+}
+
+async function uploadLogSnapshotAsync(
+  ctx: CustomBuildContext,
+  {
+    deviceRunSessionId,
+    filePath,
+    source,
+    maxBytes,
+    signal,
+    logger,
+  }: {
+    deviceRunSessionId: string;
+    filePath: string;
+    source: AndroidEmulatorLogSource;
+    maxBytes: number;
+    signal: AbortSignal;
+    logger: bunyan;
+  }
+): Promise<boolean> {
+  const file = await open(filePath, 'r');
+  let snapshotDirectory: string | undefined;
+  try {
+    const { size: originalSizeBytes } = await file.stat();
+    if (originalSizeBytes === 0) {
+      return false;
+    }
+    snapshotDirectory = await mkdtemp(path.join(os.tmpdir(), 'eas-android-log-snapshot-'));
+    const filename = path.basename(filePath);
+    const snapshotPath = path.join(snapshotDirectory, filename);
+    const start = Math.max(0, originalSizeBytes - maxBytes);
+    // The emulator may still append. Fix both the range and upload contents now,
+    // so Content-Length and every retry describe the same snapshot.
+    await pipeline(
+      createReadStream(filePath, {
+        fd: file,
+        autoClose: false,
+        start,
+        end: originalSizeBytes - 1,
+      }),
+      createWriteStream(snapshotPath),
+      { signal }
+    );
+    const { size } = await stat(snapshotPath);
+    if (size === 0) {
+      return false;
+    }
+    const readController = new AbortController();
+    const retainedSize =
+      size >= 1024 * 1024 ? `${Number((size / (1024 * 1024)).toFixed(2))} MiB` : `${size} bytes`;
+    const truncationNote = size < originalSizeBytes ? `; truncated, ${retainedSize} retained` : '';
+    await uploadDeviceRunSessionArtifactAsync(ctx, {
+      deviceRunSessionId,
+      artifactId: filename,
+      name: `${source === 'emulator-output' ? 'Emulator output' : 'Android device logcat'} (${filename.replace(/-(emulator|logcat)\.log$/, '')}${truncationNote})`,
+      filename,
+      kind: 'simulator-log',
+      metadata: {
+        __eas_type: 'simulator-log',
+        platform: 'android',
+        source,
+        scope: source === 'emulator-output' ? 'emulator-process' : 'device',
+        originalSizeBytes,
+        omittedBytes: originalSizeBytes - size,
+        truncated: size < originalSizeBytes,
+      },
+      size,
+      openStream: () =>
+        createReadStream(snapshotPath).on('error', err => {
+          // The uploader aborts an unfinished body after an HTTP error. That
+          // cancels one attempt, not the file's remaining upload attempts.
+          if (err.name !== 'AbortError') {
+            readController.abort(err);
+          }
+        }),
+      signal: AbortSignal.any([signal, readController.signal]),
+      attempts: 2,
+    });
+    return true;
+  } finally {
+    await file.close().catch(err => {
+      logger.warn({ err }, `Could not close Android log ${filePath}.`);
+    });
+    if (snapshotDirectory) {
+      await rm(snapshotDirectory, { recursive: true, force: true }).catch(err => {
+        logger.warn({ err }, 'Could not remove the Android log upload snapshot.');
+      });
+    }
+  }
+}

packages/build-tools/src/steps/utils/artifactPut.ts

@@ -1,120 +0,0 @@
-import { SystemError } from '@expo/eas-build-job';
-import fetch, { Headers } from 'node-fetch';
-import type { Readable } from 'node:stream';
-import { finished } from 'node:stream/promises';
-import { setTimeout as delay } from 'node:timers/promises';
-
-import { AbortUtils } from '../../utils/AbortUtils';
-
-export type ArtifactUploadSession = { url: string; headers: unknown };
-export type ArtifactSource = { openStream: () => Readable };
-
-export async function putArtifactWithRetriesAsync(
-  {
-    uploadSession,
-    source,
-    signal,
-  }: {
-    uploadSession: ArtifactUploadSession;
-    source: ArtifactSource;
-    signal?: AbortSignal;
-  },
-  { attempts = 1 }: { attempts?: number } = {}
-): Promise<void> {
-  for (let attempt = 0; attempt < attempts; attempt++) {
-    signal?.throwIfAborted();
-    const stream = source.openStream();
-    // Upload time scales with file size, so the deadline bounds stalls, not the whole request.
-    const timeout = AbortUtils.resettableTimeout(90_000);
-    try {
-      await putArtifactAsync({
-        uploadSession,
-        stream,
-        signal: signal ? AbortSignal.any([signal, timeout.signal]) : timeout.signal,
-        onProgress: timeout.resetDeadline,
-      });
-      return;
-    } catch (error) {
-      signal?.throwIfAborted();
-      const retryable =
-        error instanceof ArtifactPutError
-          ? [408, 429, 500, 502, 503, 504].includes(error.status)
-          : timeout.signal.aborted || error instanceof ArtifactPutNetworkError;
-      if (!retryable || attempt + 1 === attempts) {
-        throw error;
-      }
-      await delay(500 * (attempt + 1), undefined, { signal });
-    } finally {
-      stream.destroy();
-      await finished(stream).catch(() => {});
-    }
-  }
-}
-
-async function putArtifactAsync({
-  uploadSession,
-  stream,
-  signal,
-  onProgress,
-}: {
-  uploadSession: ArtifactUploadSession;
-  stream: Readable;
-  signal: AbortSignal;
-  onProgress: () => void;
-}): Promise<void> {
-  const requestController = new AbortController();
-  try {
-    const responding = fetch(uploadSession.url, {
-      method: 'PUT',
-      headers: new Headers(uploadSession.headers as Record<string, string>),
-      body: stream,
-      signal: AbortSignal.any([signal, requestController.signal]),
-    });
-    // fetch has piped the body already, so this listener observes flow without starting it.
-    stream.on('data', onProgress);
-    let response;
-    try {
-      response = await responding;
-    } catch (error) {
-      signal.throwIfAborted();
-      throw error instanceof Error && error.name === 'FetchError'
-        ? new ArtifactPutNetworkError(error)
-        : error;
-    }
-    signal.throwIfAborted();
-    if (!response.ok) {
-      throw new ArtifactPutError(response);
-    }
-  } finally {
-    // node-fetch destroys the request body on abort, and its response stream is a PassThrough
-    // whose destruction leaves the socket open, so the request itself is aborted here.
-    requestController.abort();
-  }
-}
-
-export class ArtifactPutError extends SystemError {
-  readonly status: number;
-  readonly reason: string;
-
-  constructor(response: { status: number; statusText: string }) {
-    const reason = `HTTP ${response.status} ${response.statusText}`;
-    super(`Artifact PUT failed: ${reason}.`);
-    this.status = response.status;
-    this.reason = reason;
-  }
-}
-
-// node-fetch names the request URL in its message, and here that URL is signed. The message keeps
-// only the error code, and the original is not kept as the cause because loggers and Sentry print causes.
-export class ArtifactPutNetworkError extends SystemError {
-  readonly code: string | undefined;
-  readonly reason: string;
-
-  constructor(error: Error & { code?: unknown }) {
-    const code = typeof error.code === 'string' ? error.code : undefined;
-    const reason = code ?? 'network error';
-    super(`Artifact PUT failed: ${reason}.`);
-    this.code = code;
-    this.reason = reason;
-  }
-}

packages/build-tools/src/steps/utils/deviceRunSessionArtifacts.ts

@@ -1,13 +1,13 @@
 import { SystemError } from '@expo/eas-build-job';
+import type { Readable } from 'node:stream';
 
 import { CustomBuildContext } from '../../customBuildContext';
 import {
-  ArtifactPutError,
-  ArtifactPutNetworkError,
-  type ArtifactSource,
-  type ArtifactUploadSession,
-  putArtifactWithRetriesAsync,
-} from './artifactPut';
+  type SignedUrl,
+  SignedUrlUploadApiError,
+  SignedUrlUploadNetworkError,
+  uploadWithSignedUrl,
+} from '../../storage/uploadWithSignedUrl';
 import { withDeviceRunSessionTimeoutAsync } from './deviceRunSessionTimeout';
 import { requireDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
 
@@ -23,7 +23,11 @@ type ArtifactMetadata = {
 
 export async function uploadDeviceRunSessionArtifactAsync(
   ctx: CustomBuildContext,
-  options: ArtifactMetadata & ArtifactSource & { signal?: AbortSignal; attempts?: number }
+  options: ArtifactMetadata & {
+    openStream: () => Readable;
+    signal?: AbortSignal;
+    attempts?: number;
+  }
 ): Promise<void> {
   try {
     const uploadSession = await withDeviceRunSessionTimeoutAsync(
@@ -31,12 +35,12 @@ export async function uploadDeviceRunSessionArtifactAsync(
       async signal => await createDeviceRunSessionArtifactUploadSessionAsync(ctx, options, signal)
     );
     options.signal?.throwIfAborted();
-    await putArtifactWithRetriesAsync(
-      { uploadSession, source: options, signal: options.signal },
-      { attempts: options.attempts }
+    await uploadWithSignedUrl(
+      { signedUrl: uploadSession, srcGeneratorAsync: async () => options.openStream() },
+      { signal: options.signal, retries: (options.attempts ?? 1) - 1, retryIntervalMs: 500 }
     );
   } catch (error) {
-    if (error instanceof ArtifactPutError || error instanceof ArtifactPutNetworkError) {
+    if (error instanceof SignedUrlUploadApiError || error instanceof SignedUrlUploadNetworkError) {
       throw new DeviceRunSessionArtifactUploadError(options.artifactId, error.reason);
     }
     throw error;
@@ -53,9 +57,9 @@ async function createDeviceRunSessionArtifactUploadSessionAsync(
   ctx: CustomBuildContext,
   { deviceRunSessionId, artifactId, name, filename, kind, metadata, size }: ArtifactMetadata,
   signal: AbortSignal
-): Promise<ArtifactUploadSession> {
+): Promise<SignedUrl> {
   const workerApi = requireDeviceRunSessionWorkerApi(ctx);
-  let uploadSession: ArtifactUploadSession;
+  let uploadSession: SignedUrl;
   try {
     uploadSession = await workerApi.createArtifactUploadSessionAsync(
       {

packages/build-tools/src/steps/utils/deviceRunSessionPreview.ts

@@ -2,7 +2,6 @@ import { type bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import { BuildRuntimePlatform, type BuildStepEnv } from '@expo/steps';
 import spawn, { type SpawnOptions } from '@expo/turtle-spawn';
-import fetch from 'node-fetch';
 import { createWriteStream } from 'node:fs';
 import { pipeline } from 'node:stream/promises';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
@@ -10,6 +9,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { type CustomBuildContext } from '../../customBuildContext';
+import { uploadContentWithSignedUrl } from '../../storage/uploadWithSignedUrl';
 import { killProcessGroup } from '../../utils/processes';
 import { requireDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
 
@@ -17,31 +17,6 @@ const PREVIEW_INTERVAL_MS = 60_000;
 const PREVIEW_MAX_DIMENSION = 320;
 const PREVIEW_QUALITY = 70;
 const MAX_PREVIEW_SIZE_BYTES = 5 * 1024 * 1024;
-/**
- * node-fetch includes the request URL in its error messages, and this URL is a signed upload URL
- * that is valid for the whole session. Replace such errors with one that names only the failure.
- */
-async function putPreviewAsync(
-  uploadSession: { url: string; headers: Record<string, string> },
-  { image, signal }: { image: Buffer; signal: AbortSignal }
-): Promise<Awaited<ReturnType<typeof fetch>>> {
-  try {
-    return await fetch(uploadSession.url, {
-      method: 'PUT',
-      headers: uploadSession.headers,
-      body: image,
-      signal,
-      timeout: 30_000,
-    });
-  } catch (err) {
-    const { name, type, code } = err as { name?: unknown; type?: unknown; code?: unknown };
-    const details = Object.entries({ name, type, code })
-      .filter(([, value]) => typeof value === 'string' && value.length > 0)
-      .map(([key, value]) => `${key}: ${value}`)
-      .join(', ');
-    throw new Error(`Session preview upload request failed (${details || 'unknown error'}).`);
-  }
-}
 
 export function startDeviceRunSessionPreview({
   ctx,
@@ -75,10 +50,10 @@ export function startDeviceRunSessionPreview({
       if (controller.signal.aborted) {
         return;
       }
-      const response = await putPreviewAsync(uploadSession, { image, signal });
-      if (!response.ok) {
-        throw new Error(`Session preview upload failed: ${response.status} ${response.statusText}`);
-      }
+      await uploadContentWithSignedUrl(
+        { signedUrl: uploadSession, content: image },
+        { signal, retries: 0, stallTimeoutMs: 30_000 }
+      );
     } catch (err) {
       if (!controller.signal.aborted) {
         logger.warn({ err }, 'Could not refresh the session preview; retrying in 60 seconds.');

packages/build-tools/src/steps/utils/deviceRunSessionScreenRecordings.ts

@@ -5,6 +5,7 @@ import spawn from '@expo/turtle-spawn';
 import { createReadStream } from 'node:fs';
 import { readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { Readable } from 'node:stream';
 import limitFactory from 'promise-limit';
 import { z } from 'zod';
 
@@ -140,9 +141,8 @@ export async function uploadDeviceRunSessionScreenRecordingsAsync(
     recordings.map(recording =>
       limit(async () => {
         try {
-          const metadata = RecordingManifestSchema.parse(
-            JSON.parse(await readFile(path.join(recording.directory, 'session.json'), 'utf-8'))
-          );
+          const manifest = await readFile(path.join(recording.directory, 'session.json'));
+          const metadata = RecordingManifestSchema.parse(JSON.parse(manifest.toString('utf-8')));
           if (path.basename(metadata.recording) !== metadata.recording) {
             throw new Error('Recording filename must not contain a directory.');
           }
@@ -186,6 +186,31 @@ export async function uploadDeviceRunSessionScreenRecordingsAsync(
             openStream: () => createReadStream(recordingPath),
             attempts: 3,
           });
+          try {
+            await uploadDeviceRunSessionArtifactAsync(ctx, {
+              deviceRunSessionId,
+              artifactId: `${recordingId}-metadata`,
+              name: `${displayName} metadata`,
+              filename: `${recordingId}.json`,
+              kind: 'screen-recording-metadata',
+              metadata: {
+                __eas_type: 'screen-recording-metadata',
+                recordingFilename: `${recordingId}.mp4`,
+                udid: recording.udid,
+              },
+              size: manifest.length,
+              openStream: () => Readable.from(manifest),
+              attempts: 3,
+            });
+          } catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            Sentry.capture('Could not upload device screen recording metadata', error);
+            logger.warn(
+              { err: error },
+              `Could not upload screen recording metadata for ${recording.deviceName}.`
+            );
+            return false;
+          }
           return true;
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err));

packages/build-tools/src/steps/utils/deviceRunSessionWorkerApi.ts

@@ -1,9 +1,11 @@
 import { type EnvironmentSecret, EnvironmentSecretType, SystemError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
+import { FetchError } from 'node-fetch';
 import { z } from 'zod';
 
 import { type CustomBuildContext } from '../../customBuildContext';
+import { promiseRetryWithCondition } from '../../utils/promiseRetryWithCondition';
 import { turtleFetch } from '../../utils/turtleFetch';
 
 /**
@@ -75,7 +77,7 @@ type RequestOptions = {
   signal?: AbortSignal;
   /** node-fetch timeout of each attempt, in milliseconds. */
   timeoutMs?: number;
-  /** Additional attempts after a failed one. Defaults to none, so each call sends one request. */
+  /** Additional attempts for transient failures. Defaults to none; critical callers opt in. */
   retries?: number;
   logger?: bunyan;
 };
@@ -88,11 +90,17 @@ export class DeviceRunSessionWorkerApiError extends Error {
   constructor(
     message: string,
     /** The HTTP status of the response, or undefined when no response arrived. */
-    readonly status: number | undefined
+    readonly status: number | undefined,
+    options?: ErrorOptions,
+    readonly code?: string
   ) {
-    super(message);
+    super(message, options);
     this.name = 'DeviceRunSessionWorkerApiError';
   }
+
+  get isTransient(): boolean {
+    return this.status === undefined || this.status >= 500;
+  }
 }
 
 /**
@@ -184,16 +192,44 @@ export class DeviceRunSessionWorkerApi {
   }
 
   private async requestAsync<T>(
+    method: 'GET' | 'POST',
+    route: string,
+    dataSchema: z.ZodType<T>,
+    { retries = 0, ...options }: RequestOptions & { json?: Record<string, unknown> }
+  ): Promise<T> {
+    const request = () => {
+      options.signal?.throwIfAborted();
+      return this.requestOnceAsync(method, route, dataSchema, options);
+    };
+    if (retries === 0) {
+      return await request();
+    }
+    return await promiseRetryWithCondition(
+      request,
+      error =>
+        !options.signal?.aborted &&
+        error instanceof DeviceRunSessionWorkerApiError &&
+        (error.status === undefined || error.status === 429 || error.status >= 500),
+      { retries, factor: 2, minTimeout: 1000 },
+      ({ attemptNumber, maxAttemptsCount }) =>
+        options.logger?.warn(
+          `Retrying ${method} /v2/${DEVICE_RUN_SESSION_WORKER_PATH}${route} (attempt ${attemptNumber}/${maxAttemptsCount}).`
+        )
+    )();
+  }
+
+  private async requestOnceAsync<T>(
     method: 'GET' | 'POST',
     route: string,
     dataSchema: z.ZodType<T>,
     {
       signal,
       timeoutMs,
-      retries = 0,
       logger,
       json,
-    }: RequestOptions & { json?: Record<string, unknown> }
+    }: Omit<RequestOptions, 'retries'> & {
+      json?: Record<string, unknown>;
+    }
   ): Promise<T> {
     const routeDescription = `${method} /v2/${DEVICE_RUN_SESSION_WORKER_PATH}${route}`;
     const url = new URL(
@@ -207,7 +243,7 @@ export class DeviceRunSessionWorkerApi {
         ...(json ? { json } : {}),
         ...(signal ? { signal } : {}),
         ...(timeoutMs !== undefined ? { timeout: timeoutMs } : {}),
-        retries,
+        retries: 0,
         shouldThrowOnNotOk: false,
         logger,
       })
@@ -218,7 +254,8 @@ export class DeviceRunSessionWorkerApi {
         `${routeDescription} failed before www responded: ${
           reason instanceof Error ? reason.message : String(reason)
         }. Check the network connection of the worker.`,
-        undefined
+        undefined,
+        { cause: reason }
       );
     }
     const response = responseResult.value;
@@ -231,10 +268,21 @@ export class DeviceRunSessionWorkerApi {
         : response.statusText;
       throw new DeviceRunSessionWorkerApiError(
         `${routeDescription} failed with status ${response.status}: ${apiErrorMessage}`,
-        response.status
+        response.status,
+        undefined,
+        apiError?.success ? apiError.data.errors[0]?.code : undefined
       );
     }
     if (!bodyResult.ok) {
+      if (
+        bodyResult.reason instanceof FetchError &&
+        ['system', 'body-timeout'].includes(bodyResult.reason.type)
+      ) {
+        throw new DeviceRunSessionWorkerApiError(
+          `${routeDescription} failed while reading the response body.`,
+          undefined
+        );
+      }
       throw new DeviceRunSessionWorkerApiError(
         `${routeDescription} returned a response that is not JSON.`,
         response.status

packages/build-tools/src/steps/utils/deviceSessionHost.ts

@@ -40,6 +40,7 @@ import {
   spawnDetached,
   startNgrokTunnelAsync,
 } from './remoteDeviceRunSession';
+import { LOCAL_EGRESS_PROXY_HOST, readLocalEgressHandoffAsync } from './localEgress';
 import { withDeviceRunSessionTimeoutAsync } from './deviceRunSessionTimeout';
 import {
   IosSimulatorRecordingUtils,
@@ -48,11 +49,14 @@ import {
 import { SERVE_SIM_STATE_DIR, readServeSimServersAsync } from './serveSimMetricsRecorder';
 import { startLogPhase } from '../../utils/logPhase';
 import { runServeSimActionAsync, stageServeSimAppAsync } from './serveSimActions';
+import { type ServeSimActivityPolling, startServeSimActivityPolling } from './serveSimActivity';
 import { verifyLocalEgressGuardAsync } from './localEgressGuard';
 import { IosSimulatorUtils, type IosSimulatorUuid } from '../../utils/IosSimulatorUtils';
 import { createStartupTasks } from './startupTasks';
 
 const WEB_PREVIEW_HOST = '127.0.0.1';
+const IOS_SIMULATOR_UDID = /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+const ANDROID_DEVICE_SERIAL = /^(?!all$|booted$)[A-Za-z0-9][A-Za-z0-9._:-]*$/;
 const SERVE_SIM_PACKAGE_NAME = '@expo/serve-sim';
 const SERVE_SIM_MAX_DIMENSION = '1600';
 const SERVE_SIM_MJPEG_QUALITY = '0.55';
@@ -136,6 +140,7 @@ export function createServeSimArgs({
   openUrl,
   networkCapture = false,
   networkCaptureFields = [],
+  networkCaptureProxy,
 }: {
   port: number;
   turnArgs?: string[];
@@ -149,10 +154,14 @@ export function createServeSimArgs({
   installAppPath?: string;
   networkCapture?: boolean;
   networkCaptureFields?: string[];
+  networkCaptureProxy?: string;
 } & ServeSimLaunchOptions): string[] {
   return [
     createServeSimPackageSpec(packageVersion),
     ...(iosSimulatorUdid ? [iosSimulatorUdid] : []),
+    ...(iosSimulatorUdid && IOS_SIMULATOR_UDID.test(iosSimulatorUdid)
+      ? ['--single-device', iosSimulatorUdid]
+      : []),
     '--port',
     String(port),
     '--host',
@@ -188,11 +197,13 @@ export function createServeSimArgs({
           ...networkCaptureFields.flatMap(field => ['--network-capture-field', field]),
         ]
       : []),
+    ...(networkCaptureProxy !== undefined ? ['--network-capture-proxy', networkCaptureProxy] : []),
   ];
 }
 
 export function createExpoDeviceHubArgs({
   port,
+  device,
   turnArgs = [],
   websiteArgs = [],
   frameAncestorArgs: frameArgs = [],
@@ -201,6 +212,7 @@ export function createExpoDeviceHubArgs({
   recordingDirectory,
 }: {
   port: number;
+  device?: string;
   turnArgs?: string[];
   websiteArgs?: string[];
   frameAncestorArgs?: string[];
@@ -210,6 +222,7 @@ export function createExpoDeviceHubArgs({
 }): string[] {
   return [
     createExpoDeviceHubPackageSpec(packageVersion),
+    ...(device && ANDROID_DEVICE_SERIAL.test(device) ? ['--single-device', device] : []),
     '--port',
     String(port),
     '--host',
@@ -350,6 +363,8 @@ export type DeviceWebPreview = {
 
 export type DeviceSessionHost = {
   openPreviewAsync(options: { baseDomain: string; authtoken: string }): Promise<DeviceWebPreview>;
+  /** Last observed preview input. Always `undefined` on Android, which keeps no event log. */
+  getLastPreviewActivityAt(): Date | undefined;
   /**
    * Terminal and idempotent. Never rejects: a failed finalization, host stop or upload is logged
    * and reported, so callers need no error handling around it.
@@ -380,6 +395,8 @@ type DeviceSessionHostOptions = {
   /** Origins whose pages may call the preview host's API, in addition to the website origins. */
   corsOrigins?: string[];
   iosSimulatorUdid?: string;
+  /** Selected preview target; does not enable Simulator boot or setup. */
+  previewDeviceId?: string;
   installAppPath?: string;
   bootEnv?: Record<string, string>;
   application?: Promise<ServeSimApplicationOptions | void>;
@@ -424,6 +441,7 @@ async function startDeviceSessionHostInternalAsync(
     signal,
     packageVersion,
     iosSimulatorUdid,
+    previewDeviceId,
     installAppPath,
     application,
     onStartupError,
@@ -472,6 +490,10 @@ async function startDeviceSessionHostInternalAsync(
   if (isAndroid) {
     await ensureFfmpegInstalledOnceAsync({ runtimePlatform, env, logger });
   }
+  const deviceIdPattern = isAndroid ? ANDROID_DEVICE_SERIAL : IOS_SIMULATOR_UDID;
+  const validPreviewDevice =
+    previewDeviceId && deviceIdPattern.test(previewDeviceId) ? previewDeviceId : undefined;
+  const previewDevice = isAndroid ? validPreviewDevice : (iosSimulatorUdid ?? validPreviewDevice);
   const recording: AndroidSessionRecording | null = isAndroid
     ? {
         deviceRunSessionId: getDeviceRunSessionIdOrThrow(env),
@@ -493,11 +515,13 @@ async function startDeviceSessionHostInternalAsync(
     ? createExpoDeviceHubPackageSpec(packageVersion)
     : createServeSimPackageSpec(packageVersion);
   const turnArgs = await fetchWebPreviewTurnArgsAsync(ctx, { logger });
+  const localEgress = !isAndroid ? await readLocalEgressHandoffAsync() : null;
   const previewExec = resolvePackageExec(
     resolveConfiguredPackageManager(env, PackageManager.NPM),
     isAndroid
       ? createExpoDeviceHubArgs({
           port,
+          device: previewDevice,
           turnArgs,
           packageVersion,
           recordingDirectory: recording?.directory,
@@ -509,7 +533,7 @@ async function startDeviceSessionHostInternalAsync(
           port,
           turnArgs,
           packageVersion,
-          iosSimulatorUdid,
+          iosSimulatorUdid: previewDevice,
           websiteArgs: websiteOriginArgs(env),
           frameAncestorArgs: frameAncestorArgs(frameAncestors),
           corsOriginArgs: corsOriginArgs(corsOrigins),
@@ -522,6 +546,9 @@ async function startDeviceSessionHostInternalAsync(
           openUrl: iosSimulatorUdid ? undefined : openUrl,
           networkCapture,
           networkCaptureFields,
+          networkCaptureProxy: localEgress
+            ? `http://${LOCAL_EGRESS_PROXY_HOST}:${localEgress.port}`
+            : undefined,
         })
   );
   logger.info(
@@ -566,7 +593,7 @@ async function startDeviceSessionHostInternalAsync(
   }
 
   let stagedAppDirectory: string | undefined;
-  let beforeLaunch: ReturnType<typeof asyncResult<void>> | undefined;
+  let simulatorSetup: ReturnType<typeof asyncResult<void>> | undefined;
   const readinessController = new AbortController();
   const readinessSignal = AbortSignal.any([startup.signal, readinessController.signal]);
   let previewToken: string | undefined;
@@ -577,6 +604,7 @@ async function startDeviceSessionHostInternalAsync(
   const previewSetupController = new AbortController();
   let previewSetupTask: Promise<void> | undefined;
   let previewFailed = false;
+  let previewActivity: ServeSimActivityPolling | null = null;
 
   const host: DeviceSessionHost = {
     openPreviewAsync({ baseDomain, authtoken }) {
@@ -634,6 +662,9 @@ async function startDeviceSessionHostInternalAsync(
       });
       return opening;
     },
+    getLastPreviewActivityAt() {
+      return previewActivity?.getLastActivityObservedAt();
+    },
     finishAsync() {
       readinessController.abort(new Error('Simulator preview ended.'));
       return (finishTask ??= finishDeviceSessionHostAsync(ctx, {
@@ -642,6 +673,7 @@ async function startDeviceSessionHostInternalAsync(
           previewSetupController.abort();
           await previewSetupTask;
           await sessionPreview?.stopAsync();
+          await previewActivity?.stopAsync();
         },
         previewServer,
         screenshots,
@@ -654,7 +686,7 @@ async function startDeviceSessionHostInternalAsync(
         onStopped: successful => onFinished(successful && !previewFailed),
       })
         .finally(async () => {
-          await beforeLaunch;
+          await simulatorSetup;
           if (stagedAppDirectory) {
             await fs.promises.rm(stagedAppDirectory, { recursive: true, force: true });
           }
@@ -695,7 +727,8 @@ async function startDeviceSessionHostInternalAsync(
         );
       }
       signal?.throwIfAborted();
-      beforeLaunch = asyncResult(
+      // APSD cleanup runs alongside app startup and readiness; teardown joins the task.
+      simulatorSetup = asyncResult(
         startup.untilAborted(
           startup.run('Simulator setup', async taskLogger => {
             try {
@@ -733,7 +766,6 @@ async function startDeviceSessionHostInternalAsync(
         signal?.throwIfAborted();
         await action('app.install', { udid: iosSimulatorUdid, path: staged.path });
       }
-      (await beforeLaunch)?.enforceValue();
       if (app.launchAppIdentifier) {
         signal?.throwIfAborted();
         await action('app.launch', {
@@ -746,9 +778,9 @@ async function startDeviceSessionHostInternalAsync(
     }
     logger.info(`Waiting for ${serverName} to become ready.`);
     const device = (await readiness).enforceValue();
-    if (iosSimulatorUdid && device.toLowerCase() !== iosSimulatorUdid.toLowerCase()) {
+    if (!isAndroid && previewDevice && device.toLowerCase() !== previewDevice.toLowerCase()) {
       throw new SystemError(
-        `serve-sim became ready on ${device}, but this session requested ${iosSimulatorUdid}.`
+        `serve-sim became ready on ${device}, but this session requested ${previewDevice}.`
       );
     }
     hostReady = true;
@@ -769,6 +801,9 @@ async function startDeviceSessionHostInternalAsync(
     secrets.push(previewToken);
     if (!isAndroid) {
       IosSimulatorRecordingUtils.useServeSimPackage(packageSpec);
+      if (!finishTask) {
+        previewActivity = startServeSimActivityPolling({ port, token: previewToken, logger });
+      }
     }
     // Android installed FFmpeg before launching the host. The optional thumbnail must not delay
     // readiness on macOS, so it starts after its encoder is installed there.
@@ -788,7 +823,7 @@ async function startDeviceSessionHostInternalAsync(
           captureAsync: signal =>
             captureDeviceRunSessionPreviewAsync({
               runtimePlatform,
-              device,
+              device: previewDevice ?? device,
               env,
               signal,
             }),

packages/build-tools/src/steps/utils/ios/AscApiClient.ts

@@ -1,4 +1,4 @@
-import { UserError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import * as jose from 'jose';
@@ -617,6 +617,24 @@ export class AscApiClient {
       );
       if (parsedAscErrorResponse.ok) {
         const errors = parsedAscErrorResponse.value.errors.map(ascError => {
+          if (response.status === 401 && ascError.code === 'NOT_AUTHORIZED') {
+            return new UserError(
+              'EAS_ASC_INVALID_AUTH',
+              'App Store Connect rejected the API authentication credentials. ' +
+                'Check that the API key is active and belongs to the correct App Store Connect account. ' +
+                'If the key is stored in EAS credentials, replace or reconfigure it. ' +
+                'For a local key, check `key_id` and `key`, and `issuer_id` for a team key. Then try again.',
+              { cause: ascError, docsUrl: 'https://docs.expo.dev/submit/ios/' }
+            );
+          }
+          if (response.status === 500 && ascError.code === 'UNEXPECTED_ERROR') {
+            return new SystemError(
+              'App Store Connect returned an unexpected server error. ' +
+                'Check Apple’s service status at https://developer.apple.com/system-status/ and verify whether the requested operation completed in App Store Connect before trying again. ' +
+                'If the error continues, try again later or contact Apple Developer Support.',
+              { cause: ascError, trackingCode: 'EAS_ASC_SERVER_ERROR' }
+            );
+          }
           if (ascError.code === 'FORBIDDEN.REQUIRED_AGREEMENTS_MISSING_OR_EXPIRED') {
             return new UserError(
               'EAS_ASC_REQUIRED_AGREEMENTS_MISSING_OR_EXPIRED',

packages/build-tools/src/steps/utils/ios/__tests__/AscApiClient.test.ts

@@ -1,4 +1,4 @@
-import { UserError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import * as jose from 'jose';
 import nock from 'nock';
 
@@ -85,6 +85,57 @@ describe(AscApiClient, () => {
     }
   );
 
+  it.each([false, true])(
+    'explains NOT_AUTHORIZED without losing other errors (mixed: %s)',
+    async mixed => {
+      const known = { status: '401', code: 'NOT_AUTHORIZED' };
+      const other = { status: '401', code: 'OTHER_ERROR' };
+      const scope = nock('https://api.appstoreconnect.apple.com')
+        .get('/v1/apps/app')
+        .query(true)
+        .reply(401, { errors: mixed ? [known, other] : [known] });
+      const error = await client
+        .getAsync('/v1/apps/:id', { 'fields[apps]': ['bundleId', 'name'] }, { id: 'app' })
+        .catch(error => error);
+      const mapped = mixed ? error.errors[0] : error;
+      expect(mapped).toBeInstanceOf(UserError);
+      expect(mapped).toMatchObject({ errorCode: 'EAS_ASC_INVALID_AUTH', cause: known });
+      if (mixed) {
+        expect(error).toBeInstanceOf(AggregateError);
+        expect(error.errors[1]).toBeInstanceOf(AscApiRequestError);
+        expect(error.errors[1].code).toBe('OTHER_ERROR');
+      }
+      expect(scope.isDone()).toBe(true);
+    }
+  );
+
+  it.each([false, true])(
+    'explains UNEXPECTED_ERROR without losing other errors (mixed: %s)',
+    async mixed => {
+      const known = { status: '500', code: 'UNEXPECTED_ERROR' };
+      const other = { status: '500', code: 'OTHER_ERROR' };
+      const scope = nock('https://api.appstoreconnect.apple.com')
+        .get('/v1/apps/app')
+        .query(true)
+        .reply(500, { errors: mixed ? [known, other] : [known] });
+      const error = await client
+        .getAsync('/v1/apps/:id', { 'fields[apps]': ['bundleId', 'name'] }, { id: 'app' })
+        .catch(error => error);
+      const mapped = mixed ? error.errors[0] : error;
+      expect(mapped).toBeInstanceOf(SystemError);
+      expect(mapped).toMatchObject({
+        trackingCode: 'EAS_ASC_SERVER_ERROR',
+        cause: known,
+      });
+      if (mixed) {
+        expect(error).toBeInstanceOf(AggregateError);
+        expect(error.errors[1]).toBeInstanceOf(AscApiRequestError);
+        expect(error.errors[1].code).toBe('OTHER_ERROR');
+      }
+      expect(scope.isDone()).toBe(true);
+    }
+  );
+
   it('fetches app info', async () => {
     const appId = '1491144534';
     const responseFixture = require('./fixtures/apps/get-apps-200.json');

packages/build-tools/src/steps/utils/ios/__tests__/AscApiUtils.test.ts

@@ -391,7 +391,9 @@ describe('commitBuildUploadFileAsync', () => {
       .reply(status, { errors: [{ code }] });
     await expect(
       AscApiUtils.commitBuildUploadFileAsync({ client, fileId: 'file', logger })
-    ).rejects.toMatchObject({ status, code });
+    ).rejects.toMatchObject(
+      code === 'NOT_AUTHORIZED' ? { errorCode: 'EAS_ASC_INVALID_AUTH' } : { status, code }
+    );
   });
 
   it('does not commit when the initial state read fails', async () => {