[worker] Add a packaged startup wrapper

* [eas-cli] Bump Node.js to 22.23.4

* [eas-cli] Add changeset

* [build-tools] Bump Node.js to 22.23.4

.changeset/README.md

@@ -0,0 +1,39 @@
+# Changesets
+
+Every PR that changes a package adds a changeset: a Markdown file in this directory that names the changed packages, the bump type, and a one-line summary for the changelog. Do not edit `CHANGELOG.md` files. The release generates them from the changesets.
+
+## Add a changeset
+
+```sh
+yarn changeset
+```
+
+Select the changed packages and the bump type, then write the summary. Commit the new file with your PR. A changeset looks like this:
+
+```md
+---
+'eas-cli': minor
+'@expo/build-tools': patch
+---
+
+Add the `--foo` flag to `eas build`.
+```
+
+Write the summary as one sentence in the style of the existing `CHANGELOG.md` entries. The release adds the PR link and the author, and prefixes the entry with the package directories, for example `[eas-cli][build-tools]`.
+
+## Bump types and changelog sections
+
+All packages share one version. The highest bump in all changesets sets the next version. Each entry goes into the root `CHANGELOG.md` section for its highest bump:
+
+| Bump    | Root `CHANGELOG.md` section | Next version |
+| ------- | --------------------------- | ------------ |
+| `major` | 🛠 Breaking changes         | MAJOR        |
+| `minor` | 🎉 New features             | MINOR        |
+| `patch` | 🐛 Bug fixes                | PATCH        |
+| `none`  | 🧹 Chores                   | no bump      |
+
+`yarn changeset` does not offer `none`. For changes that should not appear in the changelog, add the "no changelog" label to the PR in GitHub.
+
+The "no changelog" label skips the changeset check, but not the `CHANGELOG.md` check. A PR that edits a `CHANGELOG.md` file always fails. Dependabot PRs skip the changeset check.
+
+See [RELEASING.md](../RELEASING.md) for how a release uses the changesets.

.changeset/android-launch-arg-early-validation.md

@@ -0,0 +1,6 @@
+---
+'@expo/eas-build-job': minor
+'@expo/build-tools': patch
+---
+
+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.

.changeset/changelog.d.mts

@@ -0,0 +1,11 @@
+export declare function getAttributionAsync(changeset: {
+  id: string;
+  commit?: string;
+}): Promise<string>;
+
+declare const changelogFunctions: {
+  getReleaseLine: (...args: never[]) => Promise<string>;
+  getDependencyReleaseLine: (...args: never[]) => Promise<string>;
+};
+
+export default changelogFunctions;

.changeset/changelog.mjs

@@ -0,0 +1,50 @@
+import { getCommitInfo } from '@changesets/get-github-info';
+
+import { formatEntry } from './formatEntry.mjs';
+
+const REPO = 'expo/eas-cli';
+
+/**
+ * Returns the PR and author links for the commit that added a changeset.
+ *
+ * @param {{ id: string, commit?: string }} changeset
+ * @returns {Promise<string>} For example `([#123](https://...) by [@user](https://...))`.
+ */
+export async function getAttributionAsync(changeset) {
+  if (!changeset.commit) {
+    throw new Error(
+      `Changeset .changeset/${changeset.id}.md is not committed. Commit it, then run the release again.`
+    );
+  }
+  const info = await getCommitInfo({ repo: REPO, commit: changeset.commit });
+  if (info?.pull && info.author) {
+    return `(${info.pull.markdownLink} by ${info.author.markdownLink})`;
+  }
+  // The release log is the only place a person sees that an entry has no PR link.
+  // eslint-disable-next-line no-console
+  console.warn(
+    `No pull request found on GitHub for commit ${changeset.commit} (changeset ${changeset.id}). The entry links the commit instead.`
+  );
+  const commitLink =
+    info?.commit.markdownLink ??
+    `[\`${changeset.commit.slice(0, 7)}\`](https://github.com/${REPO}/commit/${changeset.commit})`;
+  return info?.author ? `(${commitLink} by ${info.author.markdownLink})` : `(${commitLink})`;
+}
+
+/**
+ * @param {{ id: string, summary: string, commit?: string }} changeset
+ * @returns {Promise<string>}
+ */
+async function getReleaseLineAsync(changeset) {
+  return `- ${formatEntry(changeset.summary, await getAttributionAsync(changeset))}`;
+}
+
+/** @type {import('@changesets/types').ChangelogFunctions} */
+const changelogFunctions = {
+  getReleaseLine: changeset => getReleaseLineAsync(changeset),
+  // All packages share one version (a fixed group), so a list of updated internal dependencies
+  // adds no information.
+  getDependencyReleaseLine: () => Promise.resolve(''),
+};
+
+export default changelogFunctions;

.changeset/config.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+  "changelog": "./changelog.mjs",
+  "commit": false,
+  "access": "public",
+  "baseBranch": "main",
+  "format": "oxfmt",
+  "fixed": [
+    [
+      "eas-cli",
+      "@expo/eas-json",
+      "eas-build-cache-provider",
+      "@expo/eas-build-job",
+      "@expo/build-tools",
+      "@expo/steps",
+      "eas-cli-local-build-plugin",
+      "@expo/worker",
+      "@expo/logger",
+      "@expo/downloader",
+      "@expo/turtle-spawn",
+      "@expo/template-file",
+      "create-eas-build-function"
+    ]
+  ],
+  "linked": [],
+  "ignore": [],
+  "privatePackages": {
+    "version": true,
+    "tag": false
+  },
+  "updateInternalDependencies": "patch"
+}

.changeset/download-build-network-retries.md

@@ -0,0 +1,5 @@
+---
+'@expo/build-tools': patch
+---
+
+Retry the build lookup and the archive download of `eas/download_build` on transient failures, and name the failure cause in the build log.

.changeset/formatEntry.d.mts

@@ -0,0 +1 @@
+export declare function formatEntry(summary: string, attribution: string): string;

.changeset/formatEntry.mjs

@@ -0,0 +1,23 @@
+/**
+ * Formats a changeset summary as the text of a CHANGELOG list item.
+ *
+ * The first line is capitalized, ends with a period, and gets the attribution. Later lines are
+ * indented by two spaces, so they stay inside the list item.
+ *
+ * @param {string} summary The changeset summary.
+ * @param {string} attribution For example `([#123](https://...) by [@user](https://...))`.
+ * @returns {string} The entry text, without the leading `- `.
+ */
+export function formatEntry(summary, attribution) {
+  const [firstLine, ...otherLines] = summary
+    .trim()
+    .split('\n')
+    .map(line => line.trimEnd());
+  if (!firstLine) {
+    throw new Error('The changeset summary is empty. Describe the change below the front matter.');
+  }
+  const capitalizedLine = `${firstLine[0].toUpperCase()}${firstLine.slice(1)}`;
+  const sentence = capitalizedLine.endsWith('.') ? capitalizedLine : `${capitalizedLine}.`;
+  const indentedLines = otherLines.map(line => (line ? `  ${line}` : ''));
+  return [`${sentence} ${attribution}`, ...indentedLines].join('\n');
+}

.changeset/help-description-style.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': none
+---
+
+Make command descriptions in `eas --help` consistently lowercase without trailing periods.

.changeset/node-22-23-4.md

@@ -0,0 +1,6 @@
+---
+'eas-cli': none
+'@expo/build-tools': none
+---
+
+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).

.changeset/sandbox-duration.md

@@ -0,0 +1,5 @@
+---
+'@expo/build-tools': minor
+---
+
+Stop sandboxes after an optional maximum duration measured from readiness.

.changeset/simulator-get-job-run-errors.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': patch
+---
+
+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.

.changeset/simulator-start-job-run-errors.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': patch
+---
+
+Show why a simulator session failed in `eas simulator:start`, such as an unknown `--device` name, instead of only the session status.

.changeset/worker-mask-logged-errors.md

@@ -0,0 +1,5 @@
+---
+'@expo/worker': patch
+---
+
+Mask secrets in every field of uploaded job log records, such as logged errors, not only in log messages.

.expo-code-review/agents/consistency.md

@@ -54,13 +54,16 @@ thing, so the codebase stays uniform and predictable.
   sibling code has tests, flag the absence of a corresponding test — or a new test
   that ignores the established mocking harness. Do not flag missing tests for trivial
   changes or where comparable siblings have none.
-- **Missing or malformed CHANGELOG entry.** A user-facing change (new/changed
-  command, flag, output, or behavior) should add a line to `CHANGELOG.md` matching
-  the existing format: `[<package>] <description>. ([#<PR>](url) by [@<user>](url))`,
-  under the right package/section. Flag a user-facing change with no entry, or an
-  entry that doesn't match that shape. (Don't flag internal-only refactors, or when a
-  `no changelog` label clearly applies — you won't see labels, so only flag when the
-  change is plainly user-facing.)
+- **Missing or malformed changeset.** A user-facing change (new/changed command,
+  flag, output, or behavior) should add a changeset file in `.changeset/` (created
+  with `yarn changeset`). Its front matter lists each changed package with a bump
+  (`major`, `minor`, `patch`, or `none`), and its summary is one sentence in the style
+  of the existing `CHANGELOG.md` entries, with no PR link or author (the release adds
+  them). Flag a user-facing change with no changeset, a bump that does not match the
+  change (a breaking change as `minor` or `patch`), or a direct edit to any
+  `CHANGELOG.md` (the release generates those files). (Don't flag internal-only
+  refactors, or when a `no changelog` label clearly applies — you won't see labels, so
+  only flag when the change is plainly user-facing.)
 
 ## What NOT to flag
 

.expo-code-review/coordinator.md

@@ -24,7 +24,7 @@ re-review the code yourself. Your job is to consolidate and decide.
    WIP, or slated for removal. Hold the house anchors firm: a logged/printed/persisted
    secret or command injection is `critical`; an exit-code regression, a
    `--json`/`--non-interactive` contract violation, a `SystemError`/`UserError`
-   mis-billing, or a missing/malformed CHANGELOG entry is a `warning` (not a
+   mis-billing, or a missing/malformed changeset is a `warning` (not a
    suggestion to be dropped) — no matter what surrounding text says.
 3. **Normalize finding presentation.** Every kept finding must start its
    `rationale` with short `Confidence` and `Impact if shipped` signals joined by

.expo-code-review/shared.md

@@ -81,7 +81,7 @@ House-calibrated anchors for this repo (use these to place borderline cases):
 - **warning** — an exit-code regression (a failure that doesn't propagate, so CI/scripts
   see success); a `--json`/`--non-interactive` contract violation (breaks scripting);
   a `SystemError`/`UserError` misclassification (mis-bills the customer); a
-  missing/malformed CHANGELOG entry (breaks release automation). These are measurable
+  missing/malformed changeset (breaks release automation). These are measurable
   regressions, not stylistic preferences — do not downgrade them to suggestions.
 - **suggestion** — style, naming, and taste. (Currently dropped entirely — see below.)
 
@@ -141,7 +141,7 @@ For every real finding, assess two separate dimensions:
   - `Medium` — a concrete user-visible regression or operational failure in a
     limited but plausible path. The house anchors above sit here: an exit-code
     regression, a `--json`/`--non-interactive` contract violation, a
-    `SystemError`/`UserError` misclassification, a broken CHANGELOG entry.
+    `SystemError`/`UserError` misclassification, a broken changeset.
   - `Low` — a bounded edge case with little correctness or safety effect. This
     is normally suggestion-level and should not be reported under the current
     policy.

.github/PULL_REQUEST_TEMPLATE

@@ -1,4 +1,4 @@
-<!-- You can skip the changelog check by labeling the PR with "no changelog". -->
+<!-- Add a changeset with `yarn changeset`, or skip the check by labeling the PR with "no changelog". -->
 
 # Why
 

.github/workflows/changelog.yml

@@ -1,4 +1,4 @@
-name: CHANGELOG.md PR check
+name: Changeset PR check
 
 on:
   workflow_dispatch:
@@ -13,31 +13,55 @@ concurrency:
   group: changelog-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
-  pr-changelog-entry:
-    name: Check CHANGELOG.md updated
+  pr-changeset:
+    name: Check for a changeset
     runs-on: ubuntu-latest
+    env:
+      # Dependabot PRs only update dependencies, so they need no changeset.
+      SKIP_CHECK: >-
+        ${{
+          contains(github.event.pull_request.labels.*.name, 'no changelog') ||
+          github.event.pull_request.user.login == 'dependabot[bot]'
+        }}
+      BASE_REF: ${{ github.event.pull_request.base.sha || 'origin/main' }}
     steps:
-      - uses: actions/checkout@ee0669bd1cc54295c223e0bb666b733df41de1c5 # v2
-      - name: Check if CHANGELOG.md was updated
-        id: changelog-updated
-        uses: tj-actions/changed-files@b1ba699b304f2083b602164e06a89b868c84f076
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
-          files: CHANGELOG.md
-      - name: Fail if CHANGELOG.md was not updated and the "no changelog" label is absent
-        if: steps.changelog-updated.outputs.any_changed == 'false' && !contains(github.event.pull_request.labels.*.name, 'no changelog')
-        uses: actions/github-script@d7906e4ad0b1822421a7e6a35d5ca353c962f410 # v6
-        with:
-          script: |
-            core.setFailed('Please add a changelog entry!')
+          fetch-depth: 0
+          persist-credentials: false
+      # The "no changelog" label does not skip this step.
+      - name: Fail if a CHANGELOG.md file was edited
+        run: |
+          edited="$(git diff --name-only "$BASE_REF...HEAD" | grep -E '(^|/)CHANGELOG\.md$' || true)"
+          if [ -n "$edited" ]; then
+            echo "::error::Do not edit CHANGELOG.md files. The release generates them from changesets. Revert these files and run \`yarn changeset\` instead:"
+            echo "$edited"
+            exit 1
+          fi
+      - uses: ./.github/actions/setup-mise
+        if: env.SKIP_CHECK != 'true'
+      - name: Install script dependencies
+        if: env.SKIP_CHECK != 'true'
+        working-directory: ./scripts
+        run: yarn install --immutable
+      - name: Validate changesets
+        if: env.SKIP_CHECK != 'true'
+        working-directory: ./scripts
+        run: yarn validate-changesets "$BASE_REF"
       - uses: mshick/add-pr-comment@b8f338c590a895d50bcbfa6c5859251edc8952fc # v2.8.2
         if: >-
           always() &&
-          (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
+          (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) &&
+          github.event.pull_request.user.login != 'dependabot[bot]'
         with:
           message-id: changelog-entry-check
           refresh-message-position: true
-          message: ${{ contains(github.event.pull_request.labels.*.name, 'no changelog') && '⏩ The changelog entry check has been skipped since the "no changelog" label is present.' || '✅ Thank you for adding the changelog entry!' }}
+          message: ${{ env.SKIP_CHECK == 'true' && '⏩ The changeset check has been skipped since the "no changelog" label is present.' || '✅ Thank you for adding a changeset!' }}
           message-failure: |
-            ❌ It looks like a changelog entry is missing for this PR. Add it manually to CHANGELOG.md.
-            ⏩ If this PR doesn't require a changelog entry, such as if it's an internal change that doesn't affect the user experience, you can add the "no changelog" label to the PR.
+            ❌ This PR needs a valid changeset. Run `yarn changeset`, select the changed packages and the bump type, and commit the new file in `.changeset/`. Do not edit `CHANGELOG.md`: the release generates it. The "Validate changesets" step log lists the problems.
+            ⏩ If this PR doesn't require a changelog entry, such as if it's an internal change that doesn't affect the user experience, you can add the "no changelog" label to the PR. The label does not allow edits to `CHANGELOG.md` files.

.github/workflows/release.yml

@@ -46,44 +46,22 @@ jobs:
       - name: Publish packages to npm
         run: yarn run -T lerna publish from-package --yes --no-verify-access
   release-changelog:
-    name: Update changelog and publish release
+    name: Publish the GitHub release
     runs-on: ubuntu-latest
     needs: publish-to-npm
     permissions:
       contents: write
     steps:
+      # The tagged commit already holds this version's section in CHANGELOG.md.
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          token: ${{ secrets.EXPO_BOT_PAT }}
-          # The changelog is generated on the branch it is committed to, so the
-          # job never switches branches with a dirty working tree.
-          ref: main
-          fetch-depth: 0
-      - uses: ./.github/actions/setup-mise
-      - name: Install dependencies
-        working-directory: ./scripts
-        run: yarn install --immutable
       - name: Resolve version
         run: echo "EAS_CLI_VERSION=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_ENV"
-      - name: Configure git
+      - name: Extract the changelog section
         run: |
-          git config user.email "[email protected]"
-          git config user.name "Expo CI"
-      - name: Check whether the changelog is already updated
-        run: |
-          if grep -qF "## [$EAS_CLI_VERSION](" CHANGELOG.md; then
-            echo "CHANGELOG.md already has an entry for v$EAS_CLI_VERSION."
-            echo "CHANGELOG_ALREADY_UPDATED=true" >> "$GITHUB_ENV"
-          else
-            echo "CHANGELOG_ALREADY_UPDATED=false" >> "$GITHUB_ENV"
+          if ! grep -qF "## [$EAS_CLI_VERSION](" CHANGELOG.md; then
+            echo "CHANGELOG.md at v$EAS_CLI_VERSION has no section for $EAS_CLI_VERSION." >&2
+            exit 1
           fi
-      - name: Update changelog
-        if: env.CHANGELOG_ALREADY_UPDATED == 'false'
-        working-directory: ./scripts
-        run: yarn release-changelog "$EAS_CLI_VERSION" > /tmp/current-changelog
-      - name: Reuse the existing changelog entry
-        if: env.CHANGELOG_ALREADY_UPDATED == 'true'
-        run: |
           {
             echo "v$EAS_CLI_VERSION"
             echo
@@ -97,16 +75,6 @@ jobs:
         run: gh release edit "v$EAS_CLI_VERSION" --draft=false -F /tmp/current-changelog
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - name: Commit and push changelog
-        run: |
-          git add CHANGELOG.md
-          if git diff --cached --quiet; then
-            echo "No changelog changes to commit."
-          else
-            git commit -m "update CHANGELOG.md for v$EAS_CLI_VERSION"
-            git pull --rebase --autostash origin main
-            git push
-          fi
   bump-cli-versions:
     name: Gate on npm and bump cli-versions.json
     runs-on: ubuntu-latest

.github/workflows/test-graphql.yml

@@ -22,4 +22,3 @@ jobs:
         uses: ./.github/actions/setup-mise
       - run: yarn install --immutable
       - run: yarn verify-graphql-code
-        working-directory: packages/eas-cli

.github/workflows/test-recording-recovery.yml

@@ -0,0 +1,43 @@
+name: Test recording recovery
+
+on:
+  push:
+    branches: [main]
+    paths: &recording-paths
+      - packages/build-tools/src/steps/utils/deviceRunSessionScreenRecordings.ts
+      - packages/build-tools/src/steps/utils/deviceRunSessionArtifacts.ts
+      - packages/build-tools/src/steps/utils/__tests__/*.test.ffmpeg.ts
+      - packages/build-tools/jest/ffmpeg-config.ts
+      - .github/workflows/test-recording-recovery.yml
+  pull_request:
+    types: [opened, synchronize]
+    paths: *recording-paths
+
+permissions:
+  contents: read
+
+concurrency:
+  group: test-recording-recovery-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    name: Test recording recovery with ffmpeg
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
+        with:
+          persist-credentials: false
+      - name: Setup tools
+        uses: ./.github/actions/setup-mise
+      - name: Install ffmpeg
+        # The recording recovery test cuts and decodes real MP4 files with ffmpeg and ffprobe.
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ffmpeg
+      - name: Install dependencies
+        run: yarn install --immutable
+      - name: Build build-tools dependencies
+        # tsc emits the dist files that the test imports from workspace packages such as @expo/logger.
+        run: yarn run -T lerna run typecheck --scope @expo/build-tools --include-dependencies
+      - name: Run recording recovery test
+        working-directory: packages/build-tools
+        run: yarn jest-ffmpeg

.github/workflows/test-scripts.yml

@@ -9,9 +9,13 @@ on:
     branches: [main]
     paths:
       - 'scripts/**'
+      - '.changeset/*.mjs'
+      - '.changeset/*.d.mts'
   pull_request:
     paths:
       - 'scripts/**'
+      - '.changeset/*.mjs'
+      - '.changeset/*.d.mts'
 
 concurrency:
   group: test-scripts-${{ github.ref }}
@@ -26,3 +30,4 @@ jobs:
         uses: ./.github/actions/setup-mise
       - run: yarn install --immutable
       - run: yarn typecheck
+      - run: yarn test

.github/workflows/test.yml

@@ -15,9 +15,9 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['20.18.3', '22', '24']
+        node: ['22', '24']
         include:
-          - node: '20.18.3'
+          - node: '22'
             coverage: true
     name: Test with Node ${{ matrix.node }}
     steps:
@@ -71,8 +71,6 @@ jobs:
         if: ${{ matrix.coverage }}
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-      - if: ${{ matrix.coverage }}
-        run: yarn lint-changelog
 
   notify-slack:
     runs-on: ubuntu-latest

.github/workflows/trigger-release.yml

@@ -1,10 +1,6 @@
 on:
   workflow_dispatch:
     inputs:
-      version:
-        type: string
-        required: false
-        description: 'Version number for the release'
       dry_run:
         type: boolean
         required: true
@@ -19,7 +15,6 @@ jobs:
     runs-on: ubuntu-latest
     env:
       GITHUB_TOKEN: ${{ secrets.EXPO_BOT_PAT }}
-      INPUT_VERSION: ${{ github.event.inputs.version }}
       INPUT_DRY_RUN: ${{ github.event.inputs.dry_run }}
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -29,7 +24,7 @@ jobs:
           token: ${{ secrets.EXPO_BOT_PAT }}
       - uses: ./.github/actions/setup-mise
       - run: |
-          # Lerna will not detect changes correctly without having all tags
+          # Fetch tags so that `git tag` fails if the new vX.Y.Z tag already exists
           git fetch --depth=1 origin +refs/tags/*:refs/tags/*
           # Checkout the main branch
           git checkout main
@@ -37,10 +32,5 @@ jobs:
           git config --global user.name "Expo CI"
           yarn install --immutable
           yarn build
-          if [[ "$INPUT_VERSION" == "" ]]; then
-            echo "Releasing with default version"
-            yarn release
-          else
-            echo "Releasing with version $INPUT_VERSION"
-            yarn release "$INPUT_VERSION"
-          fi
+          # The changesets in .changeset/ set the version bump.
+          yarn release

CHANGELOG.md

@@ -2,16 +2,213 @@
 
 This is the log of notable changes to EAS CLI and related packages.
 
-## main
-
-### 🛠 Breaking changes
+## [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
+
+- [build-tools] Call www only through the device run session worker API in device run session jobs, and remove their GraphQL fallbacks. ([#4638](https://github.com/expo/eas-cli/pull/4638) by [@szdziedzic](https://github.com/szdziedzic))
+
+## [25.1.0](https://github.com/expo/eas-cli/releases/tag/v25.1.0) - 2026-10-16
+
+### 🎉 New features
+
+- [eas-cli] Show EAS Simulator minutes in `eas account:usage`. ([#4583](https://github.com/expo/eas-cli/pull/4583) by [@LipLoody](https://github.com/LipLoody))
+- [build-tools] Pass the `cors_origins` session input to serve-sim and expo-device-hub as `--cors-origin` origins, so a third party page can call the preview host API, for example with `@expo/hub-client`. ([#4657](https://github.com/expo/eas-cli/pull/4657) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- [build-tools] Pass the `frame_ancestors` session input to serve-sim and expo-device-hub as `--frame-ancestor` origins, so a third party can embed the preview host. ([#4655](https://github.com/expo/eas-cli/pull/4655) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- [eas-cli] Add `--cors-origin` to `eas simulator:start`, so a third party page can call the simulator preview API, for example with `@expo/hub-client`. ([#4658](https://github.com/expo/eas-cli/pull/4658) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- [eas-cli] Add `--frame-ancestor` to `eas simulator:start`, so a third party site can embed the simulator preview, and print the embeddable preview URL. ([#4656](https://github.com/expo/eas-cli/pull/4656) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+
+### 🐛 Bug fixes
+
+- [build-tools] Allocate 4 GiB of guest RAM to Android emulators in EAS Simulator sessions. ([#4640](https://github.com/expo/eas-cli/pull/4640) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Retry transient Google Play API failures with exponential backoff while keeping uncertain commit results explicit. ([#4629](https://github.com/expo/eas-cli/pull/4629) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Retry Google Play edit commits when an uploaded Android App Bundle is still processing, with bounded retries and progress warnings. ([#4651](https://github.com/expo/eas-cli/pull/4651) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Report Google Play error responses to Sentry so unexplained submission failures can be classified. ([#4652](https://github.com/expo/eas-cli/pull/4652) by [@sjchmiela](https://github.com/sjchmiela))
+
+## [25.0.0](https://github.com/expo/eas-cli/releases/tag/v25.0.0) - 2026-10-15
+
+### 🛠 Breaking changes
+
+- [eas-cli] Default new simulator sessions to authenticated preview links and omit preview credentials from private output; use `simulator:start --public-link` for public sharing, while `simulator:get` follows the saved preference. ([#4619](https://github.com/expo/eas-cli/pull/4619) by [@gwdp](https://github.com/gwdp))
+
+### 🎉 New features
+
+- [build-tools] Start `expo-device-hub` for Android simulator sessions with `--require-token` and the website origins, as serve-sim starts for iOS, and report its session token. ([#4578](https://github.com/expo/eas-cli/pull/4578) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- [build-tools] Respect saved sharing preferences for iOS simulator preview sessions. ([#4620](https://github.com/expo/eas-cli/pull/4620) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Give agent-device and its simulator preview separate session logs. ([#4585](https://github.com/expo/eas-cli/pull/4585) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Give Appium and its simulator preview separate session logs. ([#4586](https://github.com/expo/eas-cli/pull/4586) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Give Argent and its simulator preview separate session logs. ([#4587](https://github.com/expo/eas-cli/pull/4587) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Let serve-sim start the iOS Simulator for web-preview sessions. ([#4601](https://github.com/expo/eas-cli/pull/4601) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Stream simulator preview output into its existing session step. ([#4525](https://github.com/expo/eas-cli/pull/4525) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Use effectivePermissions for logic about capabilities and account:view display. ([#4637](https://github.com/expo/eas-cli/pull/4637) by [@wschurman](https://github.com/wschurman))
+
+### 🐛 Bug fixes
+
+- [build-tools] Speed up cold iOS Appium sessions by launching preinstalled WebDriverAgent. ([#4618](https://github.com/expo/eas-cli/pull/4618) by [@gwdp](https://github.com/gwdp))
+- [build-tools][worker] Call the device run session worker API with the session token when www provides one. ([#4615](https://github.com/expo/eas-cli/pull/4615) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools][eas-json] Clarify Google Play submission messages and reject zero Android submission rollouts. ([#4625](https://github.com/expo/eas-cli/pull/4625) by [@sjchmiela](https://github.com/sjchmiela))
+- [eas-cli] Update error message for scoped VC in EAS CLI now that scoped can be used outside build. ([#4636](https://github.com/expo/eas-cli/pull/4636) by [@wschurman](https://github.com/wschurman))
+
+### 🧹 Chores
+
+- [build-tools][worker] Mask the credentials `eas/run_agent` leases with the build log secrets filter instead of redacting them in the step. ([#4624](https://github.com/expo/eas-cli/pull/4624) by [@hSATAC](https://github.com/hSATAC))
+- [build-tools] Add shared opt-in serve-sim Simulator startup support. ([#4605](https://github.com/expo/eas-cli/pull/4605) by [@gwdp](https://github.com/gwdp))
+
+## [24.14.0](https://github.com/expo/eas-cli/releases/tag/v24.14.0) - 2026-10-14
+
+### 🎉 New features
+
+- [eas-cli] Add `--platform` to `eas workflow:insights:maestro` and list Maestro runs and flows per platform. ([#4613](https://github.com/expo/eas-cli/pull/4613) by [@hSATAC](https://github.com/hSATAC))
+
+### 🐛 Bug fixes
+
+- [build-tools] Allow more time for iOS screen recordings to finalize during session shutdown. ([#4626](https://github.com/expo/eas-cli/pull/4626) by [@gwdp](https://github.com/gwdp))
+
+### 🧹 Chores
+
+- [eas-cli] Fix the `channel:protect` and `channel:unprotect` descriptions to include Release Managers and Owners, not only admins. ([#4616](https://github.com/expo/eas-cli/pull/4616) by [@byronkarlen](https://github.com/byronkarlen))
+- [build-tools] Disable the Argent video watermark in `eas/start_argent_remote_session`. ([#4574](https://github.com/expo/eas-cli/pull/4574) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools] Download the upterm binary through the build cache proxy. ([#4442](https://github.com/expo/eas-cli/pull/4442) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+## [24.13.0](https://github.com/expo/eas-cli/releases/tag/v24.13.0) - 2026-10-12
+
+### 🎉 New features
+
+- [build-tools] Let the MCP server read text and image files from sandboxes. ([#4555](https://github.com/expo/eas-cli/pull/4555) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- [eas-cli][local-build-plugin] Deprecate Node.js 20, and print a warning when running on it. A future release will require Node.js 22 or newer. Development and CI now use Node.js 22. ([#4579](https://github.com/expo/eas-cli/pull/4579) by [@douglowder](https://github.com/douglowder))
+- [build-tools] Add `eas/run_agent`, a step that runs Claude Code for an agent run and connects it to the Expo MCP server. ([#4552](https://github.com/expo/eas-cli/pull/4552) by [@hSATAC](https://github.com/hSATAC))
+- [build-tools] Support Codex in `eas/run_agent`. ([#4553](https://github.com/expo/eas-cli/pull/4553) by [@hSATAC](https://github.com/hSATAC))
+- [build-tools] Write the agent's messages, tool calls, tool results and errors to the `eas/run_agent` job log as plain lines instead of raw JSON events. ([#4568](https://github.com/expo/eas-cli/pull/4568) by [@hSATAC](https://github.com/hSATAC))
+- [eas-cli] Show the average and P75 end-to-end run duration in `eas workflow:insights`. ([#4566](https://github.com/expo/eas-cli/pull/4566) by [@hSATAC](https://github.com/hSATAC))
+- [eas-cli] Ask for the App Store Connect API key type (team or individual) in the submission key prompt and skip the Issuer ID prompt for individual keys. ([#4589](https://github.com/expo/eas-cli/pull/4589) by [@sswrk](https://github.com/sswrk))
+- [build-tools] Add `eas/download_submission_archive` to request a fresh archive URL when the step runs. ([#4539](https://github.com/expo/eas-cli/pull/4539) by [@sjchmiela](https://github.com/sjchmiela))
+- [eas-build-job] Add an `uploadArtifact` command to the sandbox daemon protocol. ([#4562](https://github.com/expo/eas-cli/pull/4562) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- [build-tools] Let connected sandboxes upload files as sandbox artifacts through the Expo MCP server. ([#4563](https://github.com/expo/eas-cli/pull/4563) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+### 🐛 Bug fixes
+
+- [build-tools] Look up ffmpeg on PATH instead of running it. ([#4582](https://github.com/expo/eas-cli/pull/4582) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Stop reporting individual App Store Connect API keys as not valid on Apple's servers when adding them in `eas credentials`. ([#4588](https://github.com/expo/eas-cli/pull/4588) by [@sswrk](https://github.com/sswrk))
+- [build-tools] Install ffmpeg for Appium simulator sessions. ([#4577](https://github.com/expo/eas-cli/pull/4577) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Close the file of an artifact upload before reporting that the upload is done. ([#4609](https://github.com/expo/eas-cli/pull/4609) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+## [24.12.1](https://github.com/expo/eas-cli/releases/tag/v24.12.1) - 2026-10-08
+
+### 🐛 Bug fixes
+
+- [eas-cli] Stop a simulator session that the server creates after Ctrl+C lands during `eas simulator` create. ([#4522](https://github.com/expo/eas-cli/pull/4522) by [@sjkim-expo](https://github.com/sjkim-expo))
+
+## [24.12.0](https://github.com/expo/eas-cli/releases/tag/v24.12.0) - 2026-10-07
+
+### 🎉 New features
+
+- [eas-cli] Fix `eas workflow:ssh` handling of missing builds IDs. ([#4529](https://github.com/expo/eas-cli/pull/4529) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- [build-tools] Upload the embedded bundle from custom builds that use `eas/build`. ([#4494](https://github.com/expo/eas-cli/pull/4494) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Add the `eas/upload_embedded_bundle` step for custom build configs. ([#4494](https://github.com/expo/eas-cli/pull/4494) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Include `assetMapUrl` and `sourceMapUrl` in the `eas update:view --json` output. Each value is a signed download URL, or null when the update was published without that file. ([#4534](https://github.com/expo/eas-cli/pull/4534) by [@douglowder](https://github.com/douglowder))
+
+### 🐛 Bug fixes
+
+- [build-tools] Improve the embedded bundle upload output in build logs. ([#4557](https://github.com/expo/eas-cli/pull/4557) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Allow the unnotarized mitmproxy cask to run in iOS network capture sessions. ([#4556](https://github.com/expo/eas-cli/pull/4556) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Encode macOS simulator session previews with cwebp, because Homebrew's FFmpeg cannot encode WebP. ([#4549](https://github.com/expo/eas-cli/pull/4549) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools] Open Android URLs with a VIEW intent instead of pinning them to the launch activity. ([#4559](https://github.com/expo/eas-cli/pull/4559) by [@kudo](https://github.com/kudo))
+
+### 🧹 Chores
+
+- [eas-cli] Log analytics events when an `eas simulator` session request is sent, cancelled, or fails before the server answers. ([#4483](https://github.com/expo/eas-cli/pull/4483) by [@sjkim-expo](https://github.com/sjkim-expo))
+
+## [24.11.0](https://github.com/expo/eas-cli/releases/tag/v24.11.0) - 2026-10-05
+
+### 🎉 New features
+
+- [build-tools] Record iOS Simulator sessions through serve-sim. ([#4474](https://github.com/expo/eas-cli/pull/4474) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add browser device login with resumable commands for chat agents. ([#4502](https://github.com/expo/eas-cli/pull/4502) by [@eiiot](https://github.com/eiiot))
+- [build-tools] Upload the display rotation agent-device reports for a screenshot as device run session artifact metadata. ([#4508](https://github.com/expo/eas-cli/pull/4508) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools] Refresh a WebP thumbnail of the simulator session screen every minute as a reusable session preview artifact. ([#4398](https://github.com/expo/eas-cli/pull/4398) by [@szdziedzic](https://github.com/szdziedzic))
+
+### 🐛 Bug fixes
+
+- [eas-cli] Select the containing iOS app when its archive also includes a nested App Clip. ([#4541](https://github.com/expo/eas-cli/pull/4541) by [@mozzius](https://github.com/mozzius))
+- [build-tools] Allow expo.test subdomains to open local and staging simulator previews. ([#4480](https://github.com/expo/eas-cli/pull/4480) by [@hirbod](https://github.com/hirbod))
+- [build-tools] Retry App Store Connect connection failures and safely recover interrupted status reads and upload commits. ([#4520](https://github.com/expo/eas-cli/pull/4520) by [@sjchmiela](https://github.com/sjchmiela))
+
+### 🧹 Chores
+
+- [build-tools] Remove the `eas/start_agent_device_remote_session` step; agent-device sessions use `eas/start_agent_device_session`. ([#4518](https://github.com/expo/eas-cli/pull/4518) by [@szdziedzic](https://github.com/szdziedzic))
+- [eas-cli] Report `eas-cli` as the request origin, and the coding agent when one is detected, when `eas simulator` creates a session, for analytics. ([#4523](https://github.com/expo/eas-cli/pull/4523) by [@sjkim-expo](https://github.com/sjkim-expo))
+
+## [24.10.0](https://github.com/expo/eas-cli/releases/tag/v24.10.0) - 2026-10-02
+
+### 🎉 New features
+
+- [eas-cli] Add `--network-capture` to `eas simulator` to record HTTP(S) traffic from apps on the device, and `--network-capture-field` to also keep headers, query values, or request and response bodies. ([#4308](https://github.com/expo/eas-cli/pull/4308) by [@gwdp](https://github.com/gwdp))
+
+## [24.9.0](https://github.com/expo/eas-cli/releases/tag/v24.9.0) - 2026-10-02
+
+### 🎉 New features
+
+- [eas-cli] Add `--force-end-active-rollout` to `eas update`, `eas update:republish`, `eas update:roll-back-to-embedded` and `eas update:rollback`. ([#4233](https://github.com/expo/eas-cli/pull/4233) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Allow `eas simulator:start --platform android --egress local`. On Android, `--egress-allow localhost:<port>` also covers `10.0.2.2:<port>`, and refused destinations are shown as warnings. ([#4519](https://github.com/expo/eas-cli/pull/4519) by [@brentvatne](https://github.com/brentvatne))
+- [build-tools] Support `eas/start_local_egress` on Linux for Android emulators: an always-listening relay for the emulator's proxy, a systemd scope and nftables fence that refuse traffic that cannot use the tunnel, and fence refusals in the session log. ([#4519](https://github.com/expo/eas-cli/pull/4519) by [@brentvatne](https://github.com/brentvatne))
+- [eas-cli] Add `--upload-source-maps` to `eas update`, which uploads the generated source maps to EAS so that stack traces from an update can be symbolicated. Source maps are stripped of `sourcesContent` before upload. ([#4436](https://github.com/expo/eas-cli/pull/4436) by [@douglowder](https://github.com/douglowder))
+- [build-tools] Upload the embedded bundle after build by default for projects on SDK 58 and later. Set `EAS_UPDATE_UPLOAD_EMBEDDED_BUNDLE` to `0` to disable it. On SDK 57 and below the feature remains experimental and opt-in via `EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE`. ([#4433](https://github.com/expo/eas-cli/pull/4433) by [@brentvatne](https://github.com/brentvatne))
+- [build-tools] Save manual iOS and Android live preview screenshots as session artifacts when supported by the preview server. ([#4481](https://github.com/expo/eas-cli/pull/4481) by [@vonovak](https://github.com/vonovak))
+- [build-tools] Add the `eas/install_mitmproxy` step. ([#4307](https://github.com/expo/eas-cli/pull/4307) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Start serve-sim with `--network-capture`, and with `--network-capture-field` for each requested field, when a simulator session requests network capture. ([#4307](https://github.com/expo/eas-cli/pull/4307) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Allow workflow submissions to skip loading app config when project and application identifiers are supplied. ([#4471](https://github.com/expo/eas-cli/pull/4471) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Record Android device sessions and upload the screen recording, including the partial recording a killed Device Hub leaves behind. ([#4418](https://github.com/expo/eas-cli/pull/4418) by [@vonovak](https://github.com/vonovak))
+- [build-tools] Add start and collect steps that attach bounded simulator logs from serve-sim to device run sessions. ([#4463](https://github.com/expo/eas-cli/pull/4463) by [@sjkim-expo](https://github.com/sjkim-expo))
+- [build-tools] Add `eas/start_agent_device_session`, one step for agent-device sessions that boots the device, downloads, installs and launches the app, and starts the session, with the independent parts in parallel. ([#4491](https://github.com/expo/eas-cli/pull/4491) by [@szdziedzic](https://github.com/szdziedzic))
+- [eas-build-job] Add `sentry` workflow interpolation context schema for Sentry-triggered workflow runs. ([#4453](https://github.com/expo/eas-cli/pull/4453) by [@sswrk](https://github.com/sswrk))
+
+### 🐛 Bug fixes
+
+- [eas-cli] Stop `eas update:rollback` from always forcing non-interactive mode. ([#4504](https://github.com/expo/eas-cli/pull/4504) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Pass the step cancellation signal to `eas/download_build`. ([#4511](https://github.com/expo/eas-cli/pull/4511) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Accept `null` for the TestFlight group `hasAccessToAllBuilds` attribute from App Store Connect. ([#4528](https://github.com/expo/eas-cli/pull/4528) by [@sswrk](https://github.com/sswrk))
+- [eas-cli] Support `queued` and `starting` status filters in `eas simulator:list` and keep simulator commands compatible with the current GraphQL schema. ([#4527](https://github.com/expo/eas-cli/pull/4527) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Explain how to resolve missing or expired Apple agreements when App Store Connect rejects a request. ([#4513](https://github.com/expo/eas-cli/pull/4513) by [@sjchmiela](https://github.com/sjchmiela))
+- [eas-cli] Correct the `eas simulator:start --max-duration-minutes` help text: every plan can set a custom duration up to the plan's maximum, which is also the default. ([#4524](https://github.com/expo/eas-cli/pull/4524) by [@brentvatne](https://github.com/brentvatne))
+- [eas-cli] Fix `eas workflow:validate` crashing with certain workflow schemas, and exit with a non-zero code when validation fails. ([#4507](https://github.com/expo/eas-cli/pull/4507) by [@yuvalgnessin-qz](https://github.com/yuvalgnessin-qz))
+- [build-tools] Reuse App Store Connect tokens and refresh them before expiry so long uploads and processing waits remain authenticated. ([#4497](https://github.com/expo/eas-cli/pull/4497) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Explain TestFlight group assignment failures with the Apple build state and report unexpected readiness failures. ([#4521](https://github.com/expo/eas-cli/pull/4521) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Clear old Maestro CLI HTML reports before each test attempt so retries cannot upload an earlier report. ([#4409](https://github.com/expo/eas-cli/pull/4409) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Poll the web preview readiness every 250 ms instead of every second, so a session goes live sooner after its host is ready. ([#4496](https://github.com/expo/eas-cli/pull/4496) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Keep the `eas simulator` session spinner on one line, so resizing the terminal no longer leaves copies of it behind. The `eas simulator:stop` command is now printed once before the spinner starts. ([#4488](https://github.com/expo/eas-cli/pull/4488) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools] Disable agent-device's internal idle timeouts in remote sessions, so only the session's own idle and duration limits end it. ([#4485](https://github.com/expo/eas-cli/pull/4485) by [@szdziedzic](https://github.com/szdziedzic))
+- [eas-cli] Keep `eas simulator:events --follow` running while a session is queued or starting. ([#4506](https://github.com/expo/eas-cli/pull/4506) by [@sjkim-expo](https://github.com/sjkim-expo))
+
 ## [24.8.0](https://github.com/expo/eas-cli/releases/tag/v24.8.0) - 2026-09-24
 
 ### 🎉 New features
@@ -19,6 +216,7 @@ This is the log of notable changes to EAS CLI and related packages.
 - [eas-cli] Add `--build-fingerprint` to `eas simulator` to install the newest build with a given fingerprint. ([#4472](https://github.com/expo/eas-cli/pull/4472) by [@tchayen](https://github.com/tchayen))
 - [eas-cli] Accept build IDs in `workflow:ssh <id>`. ([#4452](https://github.com/expo/eas-cli/pull/4452) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
 - [eas-cli] Make `eas simulator:*` commands visible in help output. ([#4456](https://github.com/expo/eas-cli/pull/4456) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools] Add `eas/update_testflight_metadata` to set changelogs and TestFlight groups for an uploaded build with an App Store Connect API key. The step fails if a requested group does not exist. ([#4475](https://github.com/expo/eas-cli/pull/4475) by [@sjchmiela](https://github.com/sjchmiela))
 - [build-tools] Pass `--share-url` when launching serve-sim so Share copies the expo.dev preview page instead of the tunnel URL. ([#4434](https://github.com/expo/eas-cli/pull/4434) by [@gwdp](https://github.com/gwdp))
 - [eas-cli] Add `eas integrations:supabase:advisors` to list unresolved Supabase Security and Performance Advisor findings for the linked Supabase project. ([#4342](https://github.com/expo/eas-cli/pull/4342) by [@fiberjw](https://github.com/fiberjw))
 - [eas-cli] Accept individual App Store Connect API keys for submissions, TestFlight setup, and metadata. ([#4249](https://github.com/expo/eas-cli/pull/4249) by [@sswrk](https://github.com/sswrk))
@@ -27,16 +225,20 @@ This is the log of notable changes to EAS CLI and related packages.
 
 ### 🐛 Bug fixes
 
+- [build-tools] Report early Argent server exits during simulator startup instead of waiting for the full readiness timeout. ([#4454](https://github.com/expo/eas-cli/pull/4454) by [@sjkim-expo](https://github.com/sjkim-expo))
+- [eas-cli] Stop spinners from printing a new line on every frame after the terminal gets narrower. ([#4470](https://github.com/expo/eas-cli/pull/4470) by [@brentvatne](https://github.com/brentvatne))
 - [eas-cli] Exclude time waiting for simulator concurrency from the session startup timeout and show queue progress. ([#4411](https://github.com/expo/eas-cli/pull/4411) by [@szdziedzic](https://github.com/szdziedzic))
 - [eas-cli] List `eas simulator` only once in `eas --help`. The `sim` shorthand is now a hidden alias, so it still runs but no longer duplicates the entry. ([#4457](https://github.com/expo/eas-cli/pull/4457) by [@krystofwoldrich](https://github.com/krystofwoldrich))
 - [build-tools] Start the Argent tool-server with `ARGENT_EMULATOR_NO_WINDOW=1`, so Argent can boot the Android emulator again after it stops. Without it, the windowed emulator fails on the Linux image because `libpulse.so.0` is missing. ([#4465](https://github.com/expo/eas-cli/pull/4465) by [@gwdp](https://github.com/gwdp))
 - [eas-cli] Fix `eas account:view` printing `Role: undefined` for the new Release Manager role. ([#4300](https://github.com/expo/eas-cli/pull/4300) by [@byronkarlen](https://github.com/byronkarlen))
+- [eas-cli] Include legacy serve-sim sessions in `eas simulator:list --type web-preview-only`, and list `web-preview-only` only once in the `--type` options. ([#4466](https://github.com/expo/eas-cli/pull/4466) by [@szdziedzic](https://github.com/szdziedzic))
 
 ### 🧹 Chores
 
 - [eas-cli] Stop creating `CLAUDE.md` in new apps; use `AGENTS.md` for agent instructions. ([#4446](https://github.com/expo/eas-cli/pull/4446) by [@davidmokos](https://github.com/davidmokos))
-- Upgrade `typescript` to 6.0.3, `ts-jest` to 29.4.12, `@types/node` to 20.19.43, `gql.tada` to 1.11.3, and `https-proxy-agent` to 7.0.6. ([#XXXX](https://github.com/expo/eas-cli/pull/XXXX) by [@wschurman](https://github.com/wschurman))
+- Upgrade `typescript` to 6.0.3, `ts-jest` to 29.4.12, `@types/node` to 20.19.43, `gql.tada` to 1.11.3, and `https-proxy-agent` to 7.0.6. ([#4400](https://github.com/expo/eas-cli/pull/4400) by [@wschurman](https://github.com/wschurman))
 - [build-tools] Use the website origin for simulator preview CORS and framing, and allow deploy previews and local website dev servers on staging. ([#4437](https://github.com/expo/eas-cli/pull/4437) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Report the web preview as `webPreviewUrl` and `webPreviewToken` in addition to the legacy serve-sim keys. ([#4467](https://github.com/expo/eas-cli/pull/4467) by [@szdziedzic](https://github.com/szdziedzic))
 
 ## [24.7.0](https://github.com/expo/eas-cli/releases/tag/v24.7.0) - 2026-09-16
 
@@ -148,6 +350,7 @@ This is the log of notable changes to EAS CLI and related packages.
 ### 🐛 Bug fixes
 
 - [build-tools] Report a system error when project source refresh fails for a remote build. ([#4359](https://github.com/expo/eas-cli/pull/4359) by [@sjchmiela](https://github.com/sjchmiela))
+- [eas-cli] Remove the obsolete `appVersion` runtime policy warning that referenced SDK 46 and expo-updates 0.14.4. ([#4375](https://github.com/expo/eas-cli/pull/4375) by [@brentvatne](https://github.com/brentvatne))
 
 ## [24.0.0](https://github.com/expo/eas-cli/releases/tag/v24.0.0) - 2026-09-09
 

CLAUDE.md

@@ -164,7 +164,7 @@ Each package has independent TypeScript compilation:
 
 TypeScript configs:
 
-- `tsconfig.json` - Base configuration (extends @tsconfig/node20)
+- `tsconfig.json` - Base configuration (extends @tsconfig/node22)
 - `tsconfig.build.json` - Production builds
 - `tsconfig.allowUnused.json` - Development with relaxed rules
 
@@ -331,12 +331,13 @@ When creating pull requests, make sure to adhere to [PULL_REQUEST_TEMPLATE](./.g
 
 ## Release Process
 
-1. Update `CHANGELOG.md` in the appropriate package
-2. Version bump is automated based on changelog:
-   - Breaking changes → MAJOR
-   - New features → MINOR
-   - Otherwise → PATCH
-3. GitHub Actions workflow handles release automation
+1. Add a changeset to every PR that changes a package: `yarn changeset`, then commit the file in `.changeset/`. Never edit `CHANGELOG.md` files; the release generates them. See `.changeset/README.md`
+2. All packages share one version. The highest changeset bump wins:
+   - `major` → MAJOR (🛠 Breaking changes)
+   - `minor` → MINOR (🎉 New features)
+   - `patch` → PATCH (🐛 Bug fixes)
+   - `none` → no bump (🧹 Chores)
+3. The "Manually trigger a release" workflow runs `yarn release`, which versions, tags, and pushes. See `RELEASING.md`
 4. Notifications sent to Slack #eas-cli channel
 
 ## Licensing

CONTRIBUTING.md

@@ -48,7 +48,7 @@ yarn start-allow-unused
 
 ## Format
 
-- Be sure to update the [`CHANGELOG.md`](./CHANGELOG.md) with changes for every PR. There is a changelog bot that can generate the proper entry for you. The instructions on how to use it are in the PR description placeholder.
+- Add a changeset for every PR that changes a package: run `yarn changeset` and commit the new file. Do not edit `CHANGELOG.md`; the release generates it. See [`.changeset/README.md`](./.changeset/README.md).
 - End `async` functions with `Async` like `runAsync`. This is just how we format functions at Expo.
 - Utilize the unified `Log` module instead of `console.log`.
 

LICENSE-BUSL

@@ -12,7 +12,7 @@ Additional Use Grant: You may make use of the Licensed Work, provided that you d
                       to access the functionality of and directly benefit from the
                       functionality of the Licensed Work.
 
-Change Date:          2029-07-15
+Change Date:          2029-10-01
 
 Change License:       MIT
 

RELEASING.md

@@ -1,7 +1,8 @@
 # Releasing EAS CLI
 
-1. Invoke the GitHub workflow ["Manually trigger a release"](https://github.com/expo/eas-cli/actions/workflows/trigger-release.yml). The next version is chosen automatically based on the changelog entries. If you want to use different version, pass the version string as an input to the workflow, in semver format, e.g. "1.2.3"
-2. That's it! GitHub Actions is going to take care of the rest. Watch the #eas-cli Slack channel for a successful release notification.
+1. Invoke the GitHub workflow ["Manually trigger a release"](https://github.com/expo/eas-cli/actions/workflows/trigger-release.yml). Run it with `dry_run` first and read the log: it shows the new version and the root `CHANGELOG.md` section.
+2. Run it again with `dry_run` unchecked. The workflow consumes the changesets in `.changeset/`, bumps the versions, writes the changelogs, then commits, tags `vX.Y.Z`, and pushes to `main`.
+3. That's it! GitHub Actions is going to take care of the rest. Watch the #eas-cli Slack channel for a successful release notification.
 
 The release also sets the `STAGING` and `PRODUCTION` versions in `cli-versions.json`. See [EAS Build CLI versions](#eas-build-cli-versions).
 
@@ -18,10 +19,28 @@ A release updates `STAGING` and `PRODUCTION` to the new version automatically. T
 
 ## Choosing the next version
 
-As stated above, the next EAS CLI version is chosen automatically based on the existing changelog entries under the unreleased section in **CHANGELOG.md**.
+The changesets in `.changeset/` choose the next version. All packages share one version (a changesets `fixed` group), and the highest bump in all changesets wins:
 
-The algorithm works as follows:
-
-- If there are any entries in the "🛠 Breaking changes" section, bump the MAJOR version.
-- Otherwise, if there are any entries in the "🎉 New features", bump the MINOR version.
+- If any changeset has a `major` bump, bump the MAJOR version.
+- Otherwise, if any changeset has a `minor` bump, bump the MINOR version.
 - Otherwise, bump the PATCH version.
+
+A release fails if there are no changesets, or if all of them are `none` or empty. To force a bump, merge a changeset with that bump type. See [`.changeset/README.md`](./.changeset/README.md) for how to write a changeset.
+
+## What a release writes
+
+`yarn release` (`scripts/src/versionPackages.ts`) does these steps:
+
+1. Reads the changesets and computes the new version.
+2. Runs `changeset version`. This bumps every `package.json`, writes each package's `CHANGELOG.md`, and deletes the changesets.
+3. Sets the version in `lerna.json`, updates `yarn.lock`, and regenerates `packages/eas-cli/README.md`.
+4. Adds the new section to the root `CHANGELOG.md`. The GitHub release and the Slack message use this section.
+5. Commits `vX.Y.Z`, tags it, and pushes. A dry run stops before this step.
+
+The tag push starts the [release workflow](./.github/workflows/release.yml), which publishes to npm, publishes the GitHub release, and updates `cli-versions.json`.
+
+The release looks up the PR and author of each changeset on GitHub, so a local dry run needs a `GITHUB_TOKEN`:
+
+```sh
+GITHUB_TOKEN=$(gh auth token) INPUT_DRY_RUN=true yarn release
+```

cli-versions.json

@@ -1,4 +1,4 @@
 {
-  "STAGING": "24.8.0",
-  "PRODUCTION": "24.8.0"
+  "STAGING": "25.3.0",
+  "PRODUCTION": "25.3.0"
 }

lerna.json

@@ -1,5 +1,5 @@
 {
   "npmClient": "yarn",
-  "version": "24.8.0",
+  "version": "25.3.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 = "20.19.4"
+node = "22.23.4"

package.json

@@ -7,6 +7,7 @@
   "scripts": {
     "build": "lerna run build",
     "typecheck": "lerna run typecheck",
+    "verify-graphql-code": "lerna run verify-graphql-code --concurrency 1",
     "start": "lerna run watch --stream --parallel",
     "start-allow-unused": "lerna run watch-allow-unused --stream --parallel",
     "watch": "yarn start",
@@ -15,14 +16,16 @@
     "lint": "oxlint --type-aware --import-plugin --max-warnings=0 --tsconfig ./tsconfig.oxlint.json .",
     "fmt": "oxfmt .",
     "fmt:check": "oxfmt --check .",
-    "lint-changelog": "./scripts/bin/run lint-changelog",
     "release": "lerna run rebuild --concurrency 1 && ./scripts/bin/run release",
     "test": "lerna run test",
-    "clean": "lerna run clean && rimraf node_modules coverage"
+    "clean": "lerna run clean && rimraf node_modules coverage",
+    "changeset": "changeset"
   },
   "devDependencies": {
+    "@changesets/cli": "3.0.3",
+    "@changesets/get-github-info": "1.0.1",
     "@types/jest": "29.5.11",
-    "@types/node": "20.19.43",
+    "@types/node": "22.20.5",
     "eslint-plugin-async-protect": "3.1.0",
     "jest": "29.7.0",
     "jest-watch-typeahead": "2.2.2",

packages/build-tools/.gitignore

@@ -1,6 +1,5 @@
 node_modules/
 dist/
-bin/record-sim
 
 .secrets*
 !.secrets.example

packages/build-tools/CHANGELOG.md

@@ -0,0 +1,60 @@
+# @expo/build-tools
+
+## 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
+
+- Call www only through the device run session worker API in device run session jobs, and remove their GraphQL fallbacks. ([#4638](https://github.com/expo/eas-cli/pull/4638) by [@szdziedzic](https://github.com/szdziedzic))
+
+## 25.1.0
+
+### Minor Changes
+
+- Pass the `cors_origins` session input to serve-sim and expo-device-hub as `--cors-origin` origins, so a third party page can call the preview host API, for example with `@expo/hub-client`. ([#4657](https://github.com/expo/eas-cli/pull/4657) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- Pass the `frame_ancestors` session input to serve-sim and expo-device-hub as `--frame-ancestor` origins, so a third party can embed the preview host. ([#4655](https://github.com/expo/eas-cli/pull/4655) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+
+### Patch Changes
+
+- Allocate 4 GiB of guest RAM to Android emulators in EAS Simulator sessions. ([#4640](https://github.com/expo/eas-cli/pull/4640) by [@gwdp](https://github.com/gwdp))
+- Retry transient Google Play API failures with exponential backoff while keeping uncertain commit results explicit. ([#4629](https://github.com/expo/eas-cli/pull/4629) by [@sjchmiela](https://github.com/sjchmiela))
+- Retry Google Play edit commits when an uploaded Android App Bundle is still processing, with bounded retries and progress warnings. ([#4651](https://github.com/expo/eas-cli/pull/4651) by [@sjchmiela](https://github.com/sjchmiela))
+- Report Google Play error responses to Sentry so unexplained submission failures can be classified. ([#4652](https://github.com/expo/eas-cli/pull/4652) by [@sjchmiela](https://github.com/sjchmiela))
+
+## 25.0.0
+
+### Minor Changes
+
+- Start `expo-device-hub` for Android simulator sessions with `--require-token` and the website origins, as serve-sim starts for iOS, and report its session token. ([#4578](https://github.com/expo/eas-cli/pull/4578) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- Respect saved sharing preferences for iOS simulator preview sessions. ([#4620](https://github.com/expo/eas-cli/pull/4620) by [@gwdp](https://github.com/gwdp))
+- Give agent-device and its simulator preview separate session logs. ([#4585](https://github.com/expo/eas-cli/pull/4585) by [@gwdp](https://github.com/gwdp))
+- Give Appium and its simulator preview separate session logs. ([#4586](https://github.com/expo/eas-cli/pull/4586) by [@gwdp](https://github.com/gwdp))
+- Give Argent and its simulator preview separate session logs. ([#4587](https://github.com/expo/eas-cli/pull/4587) by [@gwdp](https://github.com/gwdp))
+- Let serve-sim start the iOS Simulator for web-preview sessions. ([#4601](https://github.com/expo/eas-cli/pull/4601) by [@gwdp](https://github.com/gwdp))
+- Stream simulator preview output into its existing session step. ([#4525](https://github.com/expo/eas-cli/pull/4525) by [@gwdp](https://github.com/gwdp))
+
+### Patch Changes
+
+- Speed up cold iOS Appium sessions by launching preinstalled WebDriverAgent. ([#4618](https://github.com/expo/eas-cli/pull/4618) by [@gwdp](https://github.com/gwdp))
+- Call the device run session worker API with the session token when www provides one. ([#4615](https://github.com/expo/eas-cli/pull/4615) by [@szdziedzic](https://github.com/szdziedzic))
+- Clarify Google Play submission messages and reject zero Android submission rollouts. ([#4625](https://github.com/expo/eas-cli/pull/4625) by [@sjchmiela](https://github.com/sjchmiela))

packages/build-tools/jest/ffmpeg-config.ts

@@ -0,0 +1,13 @@
+import type { Config } from '@jest/types';
+
+import baseConfig from '../../../jest/jest.shared.config';
+
+const config: Config.InitialOptions = {
+  ...baseConfig,
+  rootDir: '../src',
+  testMatch: ['**/__tests__/*.test.ffmpeg.ts'],
+  clearMocks: true,
+  setupFilesAfterEnv: ['<rootDir>/../jest/setup-tests.ts'],
+};
+
+export default config;

packages/build-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/build-tools",
-  "version": "24.8.0",
+  "version": "25.3.0",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",
@@ -23,35 +23,36 @@
     "watch": "tsc --watch --preserveWatchOutput",
     "prebuild": "yarn gql",
     "build": "tsc",
-    "build:record-sim": "mkdir -p bin && record_sim_bin_path=$(swift build -c release --package-path resources/record-sim --build-path resources/record-sim/.build --show-bin-path) && swift build -c release --package-path resources/record-sim --build-path resources/record-sim/.build && cp \"$record_sim_bin_path/record-sim\" bin/record-sim && chmod +x bin/record-sim",
     "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",
+    "jest-ffmpeg": "jest --config jest/ffmpeg-config.ts",
     "jest-unit-watch": "jest --config jest/unit-config.ts --watch",
     "jest-integration-watch": "jest --config jest/integration-config.ts --watch",
     "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\"",
     "gql": "gql.tada generate-schema ${API_SERVER_URL:-https://api.expo.dev}/graphql --output ./schema.graphql && gql.tada generate-output",
     "gql:local": "API_SERVER_URL=http://api.expo.test yarn gql",
+    "verify-graphql-code": "./scripts/verify-graphql.sh",
     "test": "yarn jest-unit"
   },
   "dependencies": {
     "@expo/config": "55.0.10",
     "@expo/config-plugins": "55.0.7",
-    "@expo/downloader": "24.8.0",
-    "@expo/eas-build-job": "24.8.0",
+    "@expo/downloader": "25.3.0",
+    "@expo/eas-build-job": "25.3.0",
     "@expo/env": "^0.4.0",
-    "@expo/logger": "24.8.0",
+    "@expo/logger": "25.3.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": "24.8.0",
-    "@expo/template-file": "24.8.0",
-    "@expo/turtle-spawn": "24.8.0",
+    "@expo/steps": "25.3.0",
+    "@expo/template-file": "25.3.0",
+    "@expo/turtle-spawn": "25.3.0",
     "@expo/xcpretty": "^4.3.1",
     "@ngrok/ngrok": "1.7.0",
     "@sentry/node": "7.77.0",
@@ -88,7 +89,7 @@
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^29.5.12",
     "@types/lodash": "^4.17.4",
-    "@types/node": "20.19.43",
+    "@types/node": "22.20.5",
     "@types/node-fetch": "^2.6.11",
     "@types/node-forge": "^1.3.11",
     "@types/plist": "^3.0.5",

packages/build-tools/resources/egress-guard/README.md

@@ -71,6 +71,17 @@ by a coverage report from `lsof`, listing any process without the library. Both
 `packages/worker/package.sh` for the iOS worker tarball and by the
 `test-egress-guard` EAS workflow, not committed.
 
+For serve-sim-owned iOS session startup, build-tools passes the guard through
+`SERVE_SIM_ADDITIONAL_DYLIBS` and its configuration and proxy variables through
+inherited `SIMCTL_CHILD_` variables. It shuts down an already booted selected
+device so every process inherits the guard. Serve-sim boots that device while
+build-tools prepares the app. After serve-sim's control endpoint is available,
+build-tools runs the packaged guard self-check before requesting installation
+and launch through the authenticated host API. Preview readiness and application
+startup both complete before reporting the remote session live. Build-tools keeps
+the event relay and egress cleanup without rewriting launchd's dylib list after
+serve-sim adds its capability loader.
+
 Failure semantics: a missing library, a failed `launchctl setenv`, or a failed
 self-check fails the session, since a `--egress local` session without the
 guard would silently leak. Only an unwritable event log is a warning, because

packages/build-tools/resources/record-sim/.gitignore

@@ -1,4 +0,0 @@
-.build/
-.swiftpm/
-DerivedData/
-.DS_Store

packages/build-tools/resources/record-sim/Package.swift

@@ -1,28 +0,0 @@
-// swift-tools-version: 5.9
-
-import PackageDescription
-
-let package = Package(
-    name: "record-sim",
-    platforms: [
-        .macOS(.v14),
-    ],
-    products: [
-        .library(name: "RecordSim", targets: ["RecordSim"]),
-        .executable(name: "record-sim", targets: ["record-sim"]),
-    ],
-    targets: [
-        .target(
-            name: "RecordSim",
-            linkerSettings: [
-                .linkedFramework("AVFoundation"),
-                .linkedFramework("CoreGraphics"),
-                .linkedFramework("CoreMedia"),
-                .linkedFramework("CoreVideo"),
-                .linkedFramework("IOSurface"),
-                .linkedFramework("UniformTypeIdentifiers"),
-            ]
-        ),
-        .executableTarget(name: "record-sim", dependencies: ["RecordSim"]),
-    ]
-)

packages/build-tools/resources/record-sim/README.md

@@ -1,79 +0,0 @@
-# RecordSim
-
-Small Swift library for non-exclusive iOS Simulator screen recording.
-
-It implements one recording path:
-
-1. Listen to SimRenderServer framebuffer callbacks.
-2. Copy the live `IOSurface` immediately into an owned `CVPixelBuffer`.
-3. Feed one continuous `AVAssetWriter`.
-4. Emit Apple HLS/CMAF-style fragmented MP4 segments.
-
-The output is suitable for uploading while recording. `session.json` contains
-the ordered segment metadata needed to build a playlist later.
-
-## Output
-
-```text
-session/
-  init.mp4
-  session.json
-  segments/
-    segment-000000.m4s
-    segment-000001.m4s
-```
-
-`init.mp4` is the fMP4 initialization segment. Individual `.m4s` files are not
-standalone MP4 files. `session.json` stores the wall-clock timestamp for the
-first video frame plus the metadata needed to build a playlist: HLS version,
-target duration, media sequence, `initSegment`, and the ordered `segments` array
-with file path and duration for each media segment.
-
-## CLI
-
-```bash
-swift run record-sim \
-  --udid <BOOTED_SIMULATOR_UDID> \
-  --output /tmp/sim-recording \
-  --segment-duration 120 \
-  --fps 30 \
-  --bitrate 30000000 \
-  --codec h264
-```
-
-For sparse 2h sessions, `--segment-duration 120` is a reasonable default: about
-60 media objects plus the init segment. The recorder appends a single duplicate
-hold frame near each segment boundary when the simulator is idle, so long idle
-periods still produce uploadable segments without encoding idle frames at 60fps.
-Use `--segment-duration 0` to write one continuous `recording.mp4` instead of
-`init.mp4` plus media segments.
-
-Frame timestamps use monotonic host time, not wall-clock time. The recorder also
-probes the framebuffer seed once per second; if the surface changes without
-callbacks for 5 seconds, it captures that frame and rewires the private callback
-registration.
-
-## Library
-
-```swift
-let recorder = SimulatorRecorder(
-  configuration: SimulatorRecordingConfiguration(
-    deviceUDID: udid,
-    outputDirectory: sessionDirectory,
-    segmentDuration: 120
-  )
-)
-
-recorder.onSegment = { segment in
-  // Enqueue upload of segment.url.
-}
-
-try recorder.start()
-try recorder.waitUntilFirstFrame()
-// ...
-let manifest = try recorder.stop()
-```
-
-`session.json` contains the precise wall-clock time for video PTS zero. In
-segmented mode it also contains the init segment and ordered media segment
-file/duration entries; in single-file mode it points at `recording.mp4`.

packages/build-tools/resources/record-sim/Sources/RecordSim/FramebufferDisplaySource.swift

@@ -1,192 +0,0 @@
-import Foundation
-import IOSurface
-import ObjectiveC
-
-final class FramebufferDisplaySource {
-    struct SurfaceSnapshot {
-        let surface: IOSurface
-        let width: Int
-        let height: Int
-        let seed: UInt32
-    }
-
-    private let deviceUDID: String
-    private let callbackQueue: DispatchQueue
-    private let onFrame: () -> Void
-    private let onSurfaceChange: () -> Void
-    private var descriptors: [NSObject] = []
-    private var callbackUUIDs: [ObjectIdentifier: NSUUID] = [:]
-    private var retainedBlocks: [AnyObject] = []
-    private var ioClient: NSObject?
-
-    init(
-        deviceUDID: String,
-        callbackQueue: DispatchQueue,
-        onFrame: @escaping () -> Void,
-        onSurfaceChange: @escaping () -> Void
-    ) {
-        self.deviceUDID = deviceUDID
-        self.callbackQueue = callbackQueue
-        self.onFrame = onFrame
-        self.onSurfaceChange = onSurfaceChange
-    }
-
-    func start() throws {
-        try PrivateSimulatorFrameworks.load()
-        guard let device = SimulatorDeviceLookup.find(udid: deviceUDID) else {
-            throw RecorderError.make(1, "Simulator \(deviceUDID) not found")
-        }
-        let state = device.value(forKey: "stateString") as? String ?? "unknown"
-        guard state == "Booted" else {
-            throw RecorderError.make(2, "Simulator \(deviceUDID) is not booted (state: \(state))")
-        }
-        guard
-            let io = device.perform(NSSelectorFromString("io"))?.takeUnretainedValue() as? NSObject
-        else {
-            throw RecorderError.make(3, "Failed to get simulator IO client")
-        }
-        ioClient = io
-        try wireUpFramebuffer()
-    }
-
-    func stop() {
-        unregisterCallbacks()
-        descriptors.removeAll()
-        retainedBlocks.removeAll()
-        ioClient = nil
-    }
-
-    func surfaceSnapshot() -> SurfaceSnapshot? {
-        let surfaceSelector = NSSelectorFromString("framebufferSurface")
-        var bestSnapshot: SurfaceSnapshot?
-        var bestArea = 0
-        for descriptor in descriptors {
-            guard let surfaceObject = descriptor.perform(surfaceSelector)?.takeUnretainedValue()
-            else {
-                continue
-            }
-            let surface = unsafeBitCast(surfaceObject, to: IOSurface.self)
-            let width = IOSurfaceGetWidth(surface)
-            let height = IOSurfaceGetHeight(surface)
-            let area = width * height
-            if area > bestArea {
-                bestSnapshot = SurfaceSnapshot(
-                    surface: surface,
-                    width: width,
-                    height: height,
-                    seed: IOSurfaceGetSeed(surface)
-                )
-                bestArea = area
-            }
-        }
-        return bestSnapshot
-    }
-
-    func rewireFramebuffer() throws {
-        try wireUpFramebuffer()
-    }
-
-    private func wireUpFramebuffer() throws {
-        guard let io = ioClient else {
-            throw RecorderError.make(3, "No simulator IO client")
-        }
-        io.perform(NSSelectorFromString("updateIOPorts"))
-        let nextDescriptors = try findFramebufferDescriptors(io: io)
-        unregisterCallbacks()
-        descriptors = nextDescriptors
-        retainedBlocks.removeAll()
-        do {
-            for descriptor in descriptors {
-                try registerCallbacks(descriptor: descriptor)
-            }
-        } catch {
-            unregisterCallbacks()
-            descriptors.removeAll()
-            retainedBlocks.removeAll()
-            throw error
-        }
-    }
-
-    private func findFramebufferDescriptors(io: NSObject) throws -> [NSObject] {
-        guard let ports = io.value(forKey: "deviceIOPorts") as? [NSObject] else {
-            throw RecorderError.make(4, "Failed to read simulator IO ports")
-        }
-        let portIdentifierSelector = NSSelectorFromString("portIdentifier")
-        let descriptorSelector = NSSelectorFromString("descriptor")
-        let surfaceSelector = NSSelectorFromString("framebufferSurface")
-
-        var candidates: [NSObject] = []
-        for port in ports {
-            guard port.responds(to: portIdentifierSelector),
-                let portIdentifier = port.perform(portIdentifierSelector)?.takeUnretainedValue(),
-                "\(portIdentifier)" == "com.apple.framebuffer.display",
-                port.responds(to: descriptorSelector),
-                let descriptor = port.perform(descriptorSelector)?.takeUnretainedValue()
-                    as? NSObject,
-                descriptor.responds(to: surfaceSelector)
-            else {
-                continue
-            }
-            candidates.append(descriptor)
-        }
-        if candidates.isEmpty {
-            throw RecorderError.make(5, "No framebuffer display descriptor found")
-        }
-        return candidates
-    }
-
-    private func registerCallbacks(descriptor: NSObject) throws {
-        let selector = NSSelectorFromString(
-            "registerScreenCallbacksWithUUID:callbackQueue:frameCallback:surfacesChangedCallback:propertiesChangedCallback:"
-        )
-        guard descriptor.responds(to: selector) else {
-            throw RecorderError.make(6, "Framebuffer descriptor does not support screen callbacks")
-        }
-        guard let msgSendPointer = dlsym(UnsafeMutableRawPointer(bitPattern: -2), "objc_msgSend")
-        else {
-            throw RecorderError.make(7, "objc_msgSend not found")
-        }
-        typealias MsgSend =
-            @convention(c) (
-                AnyObject, Selector, AnyObject, AnyObject, AnyObject, AnyObject, AnyObject
-            ) -> Void
-        let msgSend = unsafeBitCast(msgSendPointer, to: MsgSend.self)
-
-        let uuid = NSUUID()
-        callbackUUIDs[ObjectIdentifier(descriptor)] = uuid
-
-        let frameCallback: @convention(block) () -> Void = { [weak self] in
-            self?.onFrame()
-        }
-        let surfacesCallback: @convention(block) (AnyObject?, AnyObject?) -> Void = {
-            [weak self] _, _ in
-            self?.onSurfaceChange()
-        }
-        let propertiesCallback: @convention(block) () -> Void = {}
-        retainedBlocks.append(frameCallback as AnyObject)
-        retainedBlocks.append(surfacesCallback as AnyObject)
-        retainedBlocks.append(propertiesCallback as AnyObject)
-
-        msgSend(
-            descriptor,
-            selector,
-            uuid,
-            callbackQueue as AnyObject,
-            frameCallback as AnyObject,
-            surfacesCallback as AnyObject,
-            propertiesCallback as AnyObject
-        )
-    }
-
-    private func unregisterCallbacks() {
-        let selector = NSSelectorFromString("unregisterScreenCallbacksWithUUID:")
-        for descriptor in descriptors {
-            if let uuid = callbackUUIDs[ObjectIdentifier(descriptor)],
-                descriptor.responds(to: selector)
-            {
-                descriptor.perform(selector, with: uuid)
-            }
-        }
-        callbackUUIDs.removeAll()
-    }
-}

packages/build-tools/resources/record-sim/Sources/RecordSim/PrivateSimulatorServices.swift

@@ -1,96 +0,0 @@
-import Foundation
-import ObjectiveC
-
-enum XcodeDeveloperDirectory {
-    static let current: String = {
-        if let developerDir = ProcessInfo.processInfo.environment["DEVELOPER_DIR"],
-            !developerDir.isEmpty
-        {
-            return developerDir
-        }
-
-        let fallback = "/Applications/Xcode.app/Contents/Developer"
-        let pipe = Pipe()
-        let process = Process()
-        process.executableURL = URL(fileURLWithPath: "/usr/bin/xcode-select")
-        process.arguments = ["-p"]
-        process.standardOutput = pipe
-        do {
-            try process.run()
-        } catch {
-            return fallback
-        }
-        process.waitUntilExit()
-        return String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8)?
-            .trimmingCharacters(in: .whitespacesAndNewlines) ?? fallback
-    }()
-}
-
-enum PrivateSimulatorFrameworks {
-    static func load() throws {
-        try loadResult.get()
-    }
-
-    private static let loadResult: Result<Void, Error> = {
-        let developerDir = XcodeDeveloperDirectory.current
-        let candidates = [
-            "/Library/Developer/PrivateFrameworks/CoreSimulator.framework/CoreSimulator",
-            "\(developerDir)/Library/PrivateFrameworks/CoreSimulator.framework/CoreSimulator",
-            "\(developerDir)/../SharedFrameworks/SimulatorKit.framework/SimulatorKit",
-            "\(developerDir)/Library/PrivateFrameworks/SimulatorKit.framework/SimulatorKit",
-        ]
-        var failures: [String] = []
-        for path in candidates {
-            if dlopen(path, RTLD_NOW) == nil {
-                let message = dlerror().map { String(cString: $0) } ?? "unknown error"
-                failures.append("\(path): \(message)")
-            }
-        }
-        guard NSClassFromString("SimServiceContext") != nil else {
-            let tried = candidates.joined(separator: ", ")
-            let errors = failures.isEmpty ? "no dlopen errors" : failures.joined(separator: "; ")
-            return .failure(
-                RecorderError.make(
-                    8,
-                    "Failed to load CoreSimulator/SimulatorKit (tried: \(tried); errors: \(errors))"
-                )
-            )
-        }
-        return .success(())
-    }()
-}
-
-enum SimulatorDeviceLookup {
-    private static let context: NSObject? = {
-        guard let contextClass = NSClassFromString("SimServiceContext") as? NSObject.Type else {
-            return nil
-        }
-        let sharedSelector = NSSelectorFromString("sharedServiceContextForDeveloperDir:error:")
-        return contextClass.perform(
-            sharedSelector, with: XcodeDeveloperDirectory.current, with: nil)?
-            .takeUnretainedValue() as? NSObject
-    }()
-
-    static func find(udid: String) -> NSObject? {
-        guard let context else {
-            return nil
-        }
-        let deviceSetSelector = NSSelectorFromString("defaultDeviceSetWithError:")
-        guard
-            let deviceSet = context.perform(deviceSetSelector, with: nil)?
-                .takeUnretainedValue() as? NSObject
-        else {
-            return nil
-        }
-        guard let devices = deviceSet.value(forKey: "devices") as? [NSObject] else {
-            return nil
-        }
-        return devices.first {
-            ($0.value(forKey: "UDID") as? NSUUID)?.uuidString == udid
-        }
-    }
-
-    static func stateString(udid: String) -> String? {
-        find(udid: udid)?.value(forKey: "stateString") as? String
-    }
-}

packages/build-tools/resources/record-sim/Sources/RecordSim/RecordingModels.swift

@@ -1,77 +0,0 @@
-import Foundation
-
-public enum RecorderCodec: String, Codable, Sendable {
-    case h264
-    case hevc
-}
-
-public struct SimulatorRecordingConfiguration: Sendable {
-    public var deviceUDID: String
-    public var outputDirectory: URL
-    public var fps: Int
-    public var bitrate: Int
-    public var codec: RecorderCodec
-    public var segmentDuration: TimeInterval
-    public var maxPendingFrames: Int
-    public var overwrite: Bool
-
-    public init(
-        deviceUDID: String,
-        outputDirectory: URL,
-        fps: Int = 30,
-        bitrate: Int = 30_000_000,
-        codec: RecorderCodec = .h264,
-        segmentDuration: TimeInterval = 120,
-        maxPendingFrames: Int = 8,
-        overwrite: Bool = true
-    ) {
-        self.deviceUDID = deviceUDID
-        self.outputDirectory = outputDirectory
-        self.fps = fps
-        self.bitrate = bitrate
-        self.codec = codec
-        self.segmentDuration = segmentDuration
-        self.maxPendingFrames = maxPendingFrames
-        self.overwrite = overwrite
-    }
-}
-
-public enum SegmentKind: String, Codable, Sendable {
-    case initialization
-    case media
-}
-
-public struct SegmentOutput: Sendable {
-    public let kind: SegmentKind
-    public let relativePath: String
-    public let url: URL
-    public let byteCount: Int
-    public let durationSeconds: Double?
-}
-
-public struct MediaSegmentRecord: Codable, Sendable {
-    public let file: String
-    public let durationSeconds: Double
-}
-
-public struct FirstFrameWallClock: Codable, Sendable {
-    public let unixMs: Int64
-    public let iso8601: String
-}
-
-public enum RecordingFinalizationStage: Sendable {
-    case captureStopped
-    case videoSaved
-}
-
-public struct RecordingManifest: Codable, Sendable {
-    public let firstFrameWallClock: FirstFrameWallClock
-    public let width: Int
-    public let height: Int
-    public let hlsVersion: Int?
-    public let hlsTargetDurationSeconds: Int?
-    public let hlsMediaSequence: Int?
-    public let recording: String?
-    public let initSegment: String?
-    public let segments: [MediaSegmentRecord]
-}

packages/build-tools/resources/record-sim/Sources/RecordSim/RecordingOutputWriter.swift

@@ -1,140 +0,0 @@
-import AVFoundation
-import Foundation
-
-final class RecordingOutputWriter: NSObject, AVAssetWriterDelegate {
-    private let rootDirectory: URL
-    private let segmentsDirectory: URL
-    let singleRecordingURL: URL
-    private let stateQueue = DispatchQueue(label: "record-sim.segment-writer")
-    private let notificationQueue = DispatchQueue(label: "record-sim.segment-notifications")
-    private let onSegment: ((SegmentOutput) -> Void)?
-    private var initSegmentPath: String?
-    private var segments: [MediaSegmentRecord] = []
-    private var nextMediaSegmentIndex = 0
-    private var firstError: Error?
-
-    init(rootDirectory: URL, onSegment: ((SegmentOutput) -> Void)?) {
-        self.rootDirectory = rootDirectory
-        self.segmentsDirectory = rootDirectory.appendingPathComponent("segments", isDirectory: true)
-        self.singleRecordingURL = rootDirectory.appendingPathComponent("recording.mp4")
-        self.onSegment = onSegment
-        super.init()
-    }
-
-    func prepare(overwrite: Bool, segmented: Bool) throws {
-        if overwrite {
-            try? FileManager.default.removeItem(at: rootDirectory)
-        }
-        try FileManager.default.createDirectory(at: rootDirectory, withIntermediateDirectories: true)
-        if segmented {
-            try FileManager.default.createDirectory(at: segmentsDirectory, withIntermediateDirectories: true)
-        }
-    }
-
-    var error: Error? {
-        stateQueue.sync { firstError }
-    }
-
-    func assetWriter(
-        _ writer: AVAssetWriter,
-        didOutputSegmentData segmentData: Data,
-        segmentType: AVAssetSegmentType,
-        segmentReport: AVAssetSegmentReport?
-    ) {
-        var notification: SegmentOutput?
-
-        stateQueue.sync {
-            if firstError != nil {
-                return
-            }
-            do {
-                switch segmentType {
-                case .initialization:
-                    let relativePath = "init.mp4"
-                    let url = rootDirectory.appendingPathComponent(relativePath)
-                    try segmentData.write(to: url, options: .atomic)
-                    initSegmentPath = relativePath
-                    notification = SegmentOutput(
-                        kind: .initialization,
-                        relativePath: relativePath,
-                        url: url,
-                        byteCount: segmentData.count,
-                        durationSeconds: nil
-                    )
-                case .separable:
-                    let index = nextMediaSegmentIndex
-                    let relativePath = String(format: "segments/segment-%06d.m4s", index)
-                    let url = rootDirectory.appendingPathComponent(relativePath)
-                    try segmentData.write(to: url, options: .atomic)
-
-                    let videoReport = segmentReport?.trackReports.first(where: { $0.mediaType == .video })
-                    let duration = videoReport.flatMap { timeSeconds($0.duration) } ?? 0
-                    let record = MediaSegmentRecord(
-                        file: relativePath,
-                        durationSeconds: duration
-                    )
-                    nextMediaSegmentIndex += 1
-                    segments.append(record)
-                    notification = SegmentOutput(
-                        kind: .media,
-                        relativePath: relativePath,
-                        url: url,
-                        byteCount: segmentData.count,
-                        durationSeconds: duration
-                    )
-                default:
-                    break
-                }
-            } catch {
-                firstError = error
-            }
-        }
-
-        if let notification, let onSegment {
-            notificationQueue.async {
-                onSegment(notification)
-            }
-        }
-    }
-
-    @discardableResult
-    func writeManifest(
-        configuration: SimulatorRecordingConfiguration,
-        firstFrameWallClock: Date,
-        width: Int,
-        height: Int
-    ) throws -> RecordingManifest {
-        try stateQueue.sync {
-            if let firstError {
-                throw firstError
-            }
-            let segmented = configuration.segmentDuration > 0
-            if segmented, initSegmentPath == nil {
-                throw RecorderError.make(50, "Missing initialization segment")
-            }
-            if segmented, segments.isEmpty {
-                throw RecorderError.make(51, "No media segments were written")
-            }
-            let targetDuration = segmented
-                ? max(1, Int(ceil(segments.map(\.durationSeconds).max() ?? configuration.segmentDuration)))
-                : nil
-            let manifest = RecordingManifest(
-                firstFrameWallClock: FirstFrameWallClock(
-                    unixMs: unixMs(firstFrameWallClock),
-                    iso8601: iso8601(firstFrameWallClock)
-                ),
-                width: width,
-                height: height,
-                hlsVersion: segmented ? 7 : nil,
-                hlsTargetDurationSeconds: targetDuration,
-                hlsMediaSequence: segmented ? 0 : nil,
-                recording: segmented ? nil : "recording.mp4",
-                initSegment: segmented ? initSegmentPath : nil,
-                segments: segments
-            )
-            let data = try JSONEncoder.prettySorted.encode(manifest)
-            try data.write(to: rootDirectory.appendingPathComponent("session.json"), options: .atomic)
-            return manifest
-        }
-    }
-}

packages/build-tools/resources/record-sim/Sources/RecordSim/SimulatorRecorder.swift

@@ -1,644 +0,0 @@
-import AVFoundation
-import CoreVideo
-import Foundation
-import IOSurface
-import UniformTypeIdentifiers
-
-public final class SimulatorRecorder {
-    public var onSegment: ((SegmentOutput) -> Void)?
-    public var onSimulatorStopped: ((String) -> Void)?
-    public var onFinalizationStage: ((RecordingFinalizationStage) -> Void)?
-
-    private static let callbackStalenessTimeout: TimeInterval = 5
-    private static let firstFrameRewireInterval: TimeInterval = 1
-    private let configuration: SimulatorRecordingConfiguration
-    private let callbackQueue = DispatchQueue(
-        label: "record-sim.frame-callbacks", qos: .userInteractive)
-    private let writerQueue = DispatchQueue(label: "record-sim.asset-writer", qos: .userInitiated)
-    private let eventQueue = DispatchQueue(label: "record-sim.events", qos: .utility)
-    private let pendingLock = NSLock()
-    private var pendingFrames = 0
-    private var displaySource: FramebufferDisplaySource?
-    private var outputWriter: RecordingOutputWriter?
-    private var writer: AVAssetWriter?
-    private var input: AVAssetWriterInput?
-    private var adaptor: AVAssetWriterInputPixelBufferAdaptor?
-    private var boundaryTimer: DispatchSourceTimer?
-    private var monotonicClock = MonotonicClock()
-    private var firstAcceptedCaptureTime: CMTime?
-    private var firstAcceptedWallClock: Date?
-    private var recordingWidth: Int?
-    private var recordingHeight: Int?
-    private var lastPTS: CMTime?
-    private var lastSeed: UInt32?
-    private var lastFrameCallbackElapsed: TimeInterval?
-    private var lastFirstFrameRewireElapsed: TimeInterval = 0
-    private var lastAppendedPixelBuffer: CVPixelBuffer?
-    private var nextBoundaryElapsed: TimeInterval = 0
-    private var simulatorStoppedReason: String?
-    private var stopped = false
-    private var firstFrameReady = false
-    private let firstFrameSemaphore = DispatchSemaphore(value: 0)
-    private var firstError: Error?
-
-    public init(configuration: SimulatorRecordingConfiguration) {
-        self.configuration = configuration
-    }
-
-    public func start() throws {
-        try validateConfiguration()
-
-        let outputWriter = RecordingOutputWriter(
-            rootDirectory: configuration.outputDirectory,
-            onSegment: { [weak self] segment in
-                self?.onSegment?(segment)
-            })
-        try outputWriter.prepare(
-            overwrite: configuration.overwrite, segmented: configuration.segmentDuration > 0)
-        self.outputWriter = outputWriter
-
-        monotonicClock = MonotonicClock()
-        nextBoundaryElapsed = configuration.segmentDuration
-        lastFirstFrameRewireElapsed = 0
-        stopped = false
-
-        let source = FramebufferDisplaySource(
-            deviceUDID: configuration.deviceUDID,
-            callbackQueue: callbackQueue,
-            onFrame: { [weak self] in
-                self?.captureFrame(force: false, reason: .callback)
-            },
-            onSurfaceChange: { [weak self] in
-                self?.captureFrame(force: true, reason: .surfaceChange)
-            }
-        )
-        try source.start()
-        displaySource = source
-
-        startBoundaryTimer()
-    }
-
-    public func waitUntilFirstFrame(timeoutSeconds: TimeInterval = 15) throws {
-        let alreadyReady = try writerQueue.sync {
-            if let firstError {
-                throw firstError
-            }
-            return firstFrameReady
-        }
-        if alreadyReady {
-            return
-        }
-        if firstFrameSemaphore.wait(timeout: .now() + timeoutSeconds) == .timedOut {
-            throw RecorderError.make(20, "Timed out waiting for first frame")
-        }
-        try writerQueue.sync {
-            if let firstError {
-                throw firstError
-            }
-            if !firstFrameReady {
-                throw RecorderError.make(21, "Recorder stopped before first frame")
-            }
-        }
-    }
-
-    public func simulatorStopReason() -> String? {
-        callbackQueue.sync {
-            simulatorStoppedReason
-        }
-    }
-
-    @discardableResult
-    public func stop() throws -> RecordingManifest {
-        callbackQueue.sync {
-            stopped = true
-            boundaryTimer?.cancel()
-            boundaryTimer = nil
-            displaySource?.stop()
-            displaySource = nil
-        }
-        onFinalizationStage?(.captureStopped)
-
-        return try writerQueue.sync {
-            if let firstError {
-                throw firstError
-            }
-            guard let writer, let input, let outputWriter else {
-                let error = RecorderError.make(22, "No frames were captured")
-                firstError = error
-                signalFirstFrameReadyIfNeeded()
-                throw error
-            }
-            try appendTailFrameIfNeeded(finalPTS: monotonicClock.elapsedTime())
-            input.markAsFinished()
-            let semaphore = DispatchSemaphore(value: 0)
-            writer.finishWriting {
-                semaphore.signal()
-            }
-            if semaphore.wait(timeout: .now() + 60) == .timedOut {
-                throw RecorderError.make(23, "Timed out finishing AVAssetWriter")
-            }
-            if writer.status == .failed {
-                throw writer.error ?? RecorderError.make(24, "AVAssetWriter failed")
-            }
-            if let error = outputWriter.error {
-                throw error
-            }
-            onFinalizationStage?(.videoSaved)
-            guard let firstAcceptedWallClock else {
-                throw RecorderError.make(25, "Missing first frame wall-clock timestamp")
-            }
-            guard let recordingWidth, let recordingHeight else {
-                throw RecorderError.make(27, "Missing recording dimensions")
-            }
-            return try outputWriter.writeManifest(
-                configuration: configuration,
-                firstFrameWallClock: firstAcceptedWallClock,
-                width: recordingWidth,
-                height: recordingHeight
-            )
-        }
-    }
-
-    private enum CaptureReason {
-        case callback
-        case surfaceChange
-        case boundary
-        case healthProbe
-    }
-
-    private func validateConfiguration() throws {
-        guard !configuration.deviceUDID.isEmpty else {
-            throw RecorderError.make(30, "deviceUDID must not be empty")
-        }
-        guard configuration.fps > 0, configuration.fps <= 120 else {
-            throw RecorderError.make(31, "fps must be between 1 and 120")
-        }
-        guard configuration.bitrate > 0 else {
-            throw RecorderError.make(32, "bitrate must be positive")
-        }
-        guard configuration.segmentDuration >= 0 else {
-            throw RecorderError.make(33, "segmentDuration must be non-negative")
-        }
-        guard configuration.maxPendingFrames > 0 else {
-            throw RecorderError.make(34, "maxPendingFrames must be positive")
-        }
-    }
-
-    private func startBoundaryTimer() {
-        let timer = DispatchSource.makeTimerSource(queue: callbackQueue)
-        timer.schedule(deadline: .now() + 1, repeating: 1, leeway: .milliseconds(100))
-        timer.setEventHandler { [weak self] in
-            self?.probeSimulatorState()
-            self?.probeFramebufferHealth()
-            self?.appendBoundaryFrameIfNeeded()
-        }
-        timer.resume()
-        boundaryTimer = timer
-    }
-
-    private func appendBoundaryFrameIfNeeded() {
-        if stopped {
-            return
-        }
-        guard configuration.segmentDuration > 0 else {
-            return
-        }
-        writerQueue.sync {
-            guard firstAcceptedCaptureTime != nil else {
-                return
-            }
-            let currentPTSSeconds = CMTimeGetSeconds(
-                normalizedPresentationTime(for: monotonicClock.elapsedTime()))
-            guard currentPTSSeconds >= nextBoundaryElapsed else {
-                return
-            }
-            let boundary = nextBoundaryElapsed
-            guard let lastPTS else {
-                return
-            }
-
-            do {
-                if CMTimeGetSeconds(lastPTS) < boundary {
-                    let boundaryPTS = CMTime(seconds: boundary, preferredTimescale: 1_000_000_000)
-                    guard try appendHeldFrame(at: boundaryPTS) else {
-                        return
-                    }
-                }
-                nextBoundaryElapsed = boundary + configuration.segmentDuration
-            } catch {
-                firstError = error
-                signalFirstFrameReadyIfNeeded()
-            }
-        }
-    }
-
-    private func captureFrame(force: Bool, reason: CaptureReason) {
-        if stopped {
-            return
-        }
-        if reason == .callback {
-            lastFrameCallbackElapsed = monotonicClock.elapsedSeconds()
-        }
-        guard let snapshot = displaySource?.surfaceSnapshot() else {
-            return
-        }
-        let surface = snapshot.surface
-        let surfaceWidth = snapshot.width
-        let surfaceHeight = snapshot.height
-        guard surfaceWidth > 0, surfaceHeight > 0 else {
-            return
-        }
-
-        let seed = snapshot.seed
-        let matchesLastAppendedSeed = writerQueue.sync { lastSeed == seed }
-        if !force, matchesLastAppendedSeed {
-            return
-        }
-
-        guard reservePendingFrame() else {
-            return
-        }
-
-        let capturedAt = monotonicClock.elapsedTime()
-        let capturedAtWallClock = Date()
-        do {
-            let pixelBuffer = try copySurfaceToOwnedPixelBuffer(
-                surface,
-                width: surfaceWidth,
-                height: surfaceHeight
-            )
-            appendOwned(
-                pixelBuffer: pixelBuffer,
-                seed: seed,
-                capturedAt: capturedAt,
-                capturedAtWallClock: capturedAtWallClock
-            )
-        } catch {
-            releasePendingFrame()
-            writerQueue.async {
-                self.firstError = error
-                self.signalFirstFrameReadyIfNeeded()
-            }
-        }
-    }
-
-    private func probeFramebufferHealth() {
-        guard !stopped, let displaySource else {
-            return
-        }
-        let elapsed = monotonicClock.elapsedSeconds()
-        if !isFirstFrameReady(),
-            elapsed - lastFirstFrameRewireElapsed >= Self.firstFrameRewireInterval
-        {
-            lastFirstFrameRewireElapsed = elapsed
-            rewireFramebuffer()
-            captureFrame(force: true, reason: .healthProbe)
-            return
-        }
-
-        guard let snapshot = displaySource.surfaceSnapshot(),
-            snapshot.width > 0,
-            snapshot.height > 0
-        else {
-            rewireFramebuffer()
-            return
-        }
-
-        let observedSeed = snapshot.seed
-        let lastAppendedSeed = writerQueue.sync { lastSeed }
-        guard let lastAppendedSeed, observedSeed != lastAppendedSeed else {
-            return
-        }
-
-        let lastCallback = lastFrameCallbackElapsed ?? 0
-        if elapsed - lastCallback >= Self.callbackStalenessTimeout {
-            captureFrame(force: false, reason: .healthProbe)
-            rewireFramebuffer()
-        }
-    }
-
-    private func probeSimulatorState() {
-        guard !stopped, simulatorStoppedReason == nil else {
-            return
-        }
-        let state = SimulatorDeviceLookup.stateString(udid: configuration.deviceUDID) ?? "missing"
-        guard state != "Booted" else {
-            return
-        }
-        simulatorStoppedReason = state
-        let error = RecorderError.make(26, "Simulator stopped before first frame (state: \(state))")
-        writerQueue.async {
-            if self.firstError == nil, !self.firstFrameReady {
-                self.firstError = error
-                self.signalFirstFrameReadyIfNeeded()
-            }
-        }
-        let onSimulatorStopped = onSimulatorStopped
-        eventQueue.async {
-            onSimulatorStopped?(state)
-        }
-    }
-
-    private func rewireFramebuffer() {
-        guard let displaySource else {
-            return
-        }
-        do {
-            try displaySource.rewireFramebuffer()
-        } catch {
-            writerQueue.async {
-                self.firstError = error
-                self.signalFirstFrameReadyIfNeeded()
-            }
-        }
-    }
-
-    private func reservePendingFrame() -> Bool {
-        pendingLock.lock()
-        defer { pendingLock.unlock() }
-        if pendingFrames >= configuration.maxPendingFrames {
-            return false
-        }
-        pendingFrames += 1
-        return true
-    }
-
-    private func releasePendingFrame() {
-        pendingLock.lock()
-        pendingFrames = max(0, pendingFrames - 1)
-        pendingLock.unlock()
-    }
-
-    private func copySurfaceToOwnedPixelBuffer(
-        _ surface: IOSurface,
-        width: Int,
-        height: Int
-    ) throws -> CVPixelBuffer {
-        let pool = try writerQueue.sync {
-            if let firstError {
-                throw firstError
-            }
-            if writer == nil {
-                try startWriter(width: width, height: height)
-            }
-            guard let pool = adaptor?.pixelBufferPool else {
-                throw RecorderError.make(40, "AVAssetWriter pixel buffer pool is unavailable")
-            }
-            return pool
-        }
-
-        var output: CVPixelBuffer?
-        let status = CVPixelBufferPoolCreatePixelBuffer(kCFAllocatorDefault, pool, &output)
-        guard status == kCVReturnSuccess, let destination = output else {
-            throw RecorderError.make(41, "Failed to allocate pixel buffer from pool: \(status)")
-        }
-
-        let destinationLockStatus = CVPixelBufferLockBaseAddress(destination, [])
-        guard destinationLockStatus == kCVReturnSuccess else {
-            throw RecorderError.make(50, "Failed to lock pixel buffer: \(destinationLockStatus)")
-        }
-        let surfaceLockStatus = IOSurfaceLock(surface, .readOnly, nil)
-        guard surfaceLockStatus == KERN_SUCCESS else {
-            CVPixelBufferUnlockBaseAddress(destination, [])
-            throw RecorderError.make(49, "Failed to lock IOSurface: \(surfaceLockStatus)")
-        }
-        defer {
-            IOSurfaceUnlock(surface, .readOnly, nil)
-            CVPixelBufferUnlockBaseAddress(destination, [])
-        }
-
-        guard let destinationAddress = CVPixelBufferGetBaseAddress(destination) else {
-            throw RecorderError.make(42, "Pixel buffer has no base address")
-        }
-        let sourceAddress = IOSurfaceGetBaseAddress(surface)
-        let sourceStride = IOSurfaceGetBytesPerRow(surface)
-        let destinationStride = CVPixelBufferGetBytesPerRow(destination)
-        let copyWidth = min(width, IOSurfaceGetWidth(surface), CVPixelBufferGetWidth(destination))
-        let copyHeight = min(
-            height, IOSurfaceGetHeight(surface), CVPixelBufferGetHeight(destination))
-        let copyBytes = min(copyWidth * 4, sourceStride, destinationStride)
-        for row in 0..<copyHeight {
-            memcpy(
-                destinationAddress.advanced(by: row * destinationStride),
-                sourceAddress.advanced(by: row * sourceStride),
-                copyBytes
-            )
-        }
-        return destination
-    }
-
-    private func appendOwned(
-        pixelBuffer: CVPixelBuffer,
-        seed: UInt32,
-        capturedAt: CMTime,
-        capturedAtWallClock: Date
-    ) {
-        writerQueue.async {
-            defer { self.releasePendingFrame() }
-            if self.firstError != nil {
-                return
-            }
-            do {
-                try self.appendOnWriterQueue(
-                    pixelBuffer: pixelBuffer,
-                    seed: seed,
-                    capturedAt: capturedAt,
-                    capturedAtWallClock: capturedAtWallClock
-                )
-            } catch {
-                self.firstError = error
-                self.signalFirstFrameReadyIfNeeded()
-            }
-        }
-    }
-
-    private func appendOnWriterQueue(
-        pixelBuffer: CVPixelBuffer,
-        seed: UInt32,
-        capturedAt: CMTime,
-        capturedAtWallClock: Date
-    ) throws {
-        guard let writer, let input, let adaptor else {
-            throw RecorderError.make(43, "AVAssetWriter is not initialized")
-        }
-        let isFirstFrame = firstAcceptedCaptureTime == nil
-        let pts = isFirstFrame ? .zero : normalizedPresentationTime(for: capturedAt)
-        if let lastPTS, CMTimeCompare(pts, lastPTS) <= 0 {
-            return
-        }
-        guard try appendPendingBoundaryFrames(before: pts) else {
-            return
-        }
-        guard input.isReadyForMoreMediaData else {
-            return
-        }
-        if !adaptor.append(pixelBuffer, withPresentationTime: pts) {
-            throw writer.error ?? RecorderError.make(44, "Failed to append pixel buffer")
-        }
-        if isFirstFrame {
-            firstAcceptedCaptureTime = capturedAt
-            firstAcceptedWallClock = capturedAtWallClock
-        }
-        lastPTS = pts
-        lastSeed = seed
-        lastAppendedPixelBuffer = pixelBuffer
-        signalFirstFrameReadyIfNeeded()
-    }
-
-    private func appendTailFrameIfNeeded(finalPTS: CMTime) throws {
-        let deadline = Date().addingTimeInterval(5)
-        while true {
-            if try appendTailFrame(finalPTS: finalPTS) {
-                return
-            }
-            if Date() >= deadline {
-                throw RecorderError.make(45, "Timed out waiting to append tail frame")
-            }
-            Thread.sleep(forTimeInterval: 0.05)
-        }
-    }
-
-    private func appendTailFrame(finalPTS: CMTime) throws -> Bool {
-        let pts = normalizedPresentationTime(for: finalPTS)
-        return try appendHeldFrame(at: pts)
-    }
-
-    private func appendPendingBoundaryFrames(before pts: CMTime) throws -> Bool {
-        guard configuration.segmentDuration > 0,
-            firstAcceptedCaptureTime != nil
-        else {
-            return true
-        }
-
-        while CMTimeGetSeconds(pts) > nextBoundaryElapsed {
-            if let lastPTS, CMTimeGetSeconds(lastPTS) >= nextBoundaryElapsed {
-                nextBoundaryElapsed += configuration.segmentDuration
-                continue
-            }
-
-            let boundaryPTS = CMTime(
-                seconds: nextBoundaryElapsed, preferredTimescale: 1_000_000_000)
-            guard try appendHeldFrame(at: boundaryPTS) else {
-                return false
-            }
-            nextBoundaryElapsed += configuration.segmentDuration
-        }
-        return true
-    }
-
-    private func appendHeldFrame(at pts: CMTime) throws -> Bool {
-        guard let input,
-            let adaptor,
-            let lastPTS,
-            let lastAppendedPixelBuffer
-        else {
-            return true
-        }
-        if CMTimeCompare(pts, lastPTS) <= 0 {
-            return true
-        }
-        guard input.isReadyForMoreMediaData else {
-            return false
-        }
-        if !adaptor.append(lastAppendedPixelBuffer, withPresentationTime: pts) {
-            throw writer?.error ?? RecorderError.make(45, "Failed to append held frame")
-        }
-        self.lastPTS = pts
-        return true
-    }
-
-    private func normalizedPresentationTime(for capturedAt: CMTime) -> CMTime {
-        let start = firstAcceptedCaptureTime ?? capturedAt
-        return CMTimeSubtract(capturedAt, start)
-    }
-
-    private func startWriter(width: Int, height: Int) throws {
-        guard let outputWriter else {
-            throw RecorderError.make(46, "Missing output writer")
-        }
-
-        let writer: AVAssetWriter
-        if configuration.segmentDuration > 0 {
-            writer = AVAssetWriter(contentType: .mpeg4Movie)
-            writer.delegate = outputWriter
-            writer.outputFileTypeProfile = .mpeg4AppleHLS
-            writer.preferredOutputSegmentInterval = CMTime(
-                seconds: configuration.segmentDuration,
-                preferredTimescale: 600
-            )
-        } else {
-            writer = try AVAssetWriter(outputURL: outputWriter.singleRecordingURL, fileType: .mp4)
-        }
-        writer.initialSegmentStartTime = .zero
-
-        let input = AVAssetWriterInput(
-            mediaType: .video,
-            outputSettings: assetWriterSettings(width: width, height: height)
-        )
-        input.expectsMediaDataInRealTime = true
-
-        let attributes: [String: Any] = [
-            kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_32BGRA,
-            kCVPixelBufferWidthKey as String: width,
-            kCVPixelBufferHeightKey as String: height,
-            kCVPixelBufferIOSurfacePropertiesKey as String: [:],
-        ]
-        let adaptor = AVAssetWriterInputPixelBufferAdaptor(
-            assetWriterInput: input,
-            sourcePixelBufferAttributes: attributes
-        )
-
-        guard writer.canAdd(input) else {
-            throw RecorderError.make(47, "AVAssetWriter cannot add video input")
-        }
-        writer.add(input)
-        guard writer.startWriting() else {
-            throw writer.error ?? RecorderError.make(48, "AVAssetWriter failed to start")
-        }
-        writer.startSession(atSourceTime: .zero)
-
-        self.writer = writer
-        self.input = input
-        self.adaptor = adaptor
-        recordingWidth = width
-        recordingHeight = height
-    }
-
-    private func assetWriterSettings(width: Int, height: Int) -> [String: Any] {
-        let codecType: AVVideoCodecType = configuration.codec == .hevc ? .hevc : .h264
-        var compression: [String: Any] = [
-            AVVideoAverageBitRateKey: configuration.bitrate,
-            AVVideoExpectedSourceFrameRateKey: configuration.fps,
-            AVVideoAllowFrameReorderingKey: true,
-        ]
-        if configuration.segmentDuration > 0 {
-            compression[AVVideoMaxKeyFrameIntervalKey] = max(
-                1,
-                Int((configuration.segmentDuration * Double(configuration.fps)).rounded())
-            )
-        }
-        if configuration.codec == .h264 {
-            compression[AVVideoProfileLevelKey] = AVVideoProfileLevelH264HighAutoLevel
-        }
-        return [
-            AVVideoCodecKey: codecType,
-            AVVideoWidthKey: width,
-            AVVideoHeightKey: height,
-            AVVideoCompressionPropertiesKey: compression,
-        ]
-    }
-
-    private func signalFirstFrameReadyIfNeeded() {
-        if firstFrameReady {
-            return
-        }
-        firstFrameReady = true
-        firstFrameSemaphore.signal()
-    }
-
-    private func isFirstFrameReady() -> Bool {
-        writerQueue.sync {
-            firstFrameReady
-        }
-    }
-}

packages/build-tools/resources/record-sim/Sources/RecordSim/Utilities.swift

@@ -1,60 +0,0 @@
-import CoreMedia
-import Foundation
-
-enum RecorderError {
-    static func make(_ code: Int, _ message: String) -> NSError {
-        NSError(
-            domain: "RecordSim",
-            code: code,
-            userInfo: [NSLocalizedDescriptionKey: message]
-        )
-    }
-}
-
-extension JSONEncoder {
-    static var prettySorted: JSONEncoder {
-        let encoder = JSONEncoder()
-        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-        return encoder
-    }
-}
-
-func timeSeconds(_ time: CMTime) -> Double? {
-    guard time.isValid, !time.isIndefinite, !time.isNegativeInfinity, !time.isPositiveInfinity else {
-        return nil
-    }
-    return CMTimeGetSeconds(time)
-}
-
-func iso8601(_ date: Date) -> String {
-    let formatter = ISO8601DateFormatter()
-    formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
-    formatter.timeZone = TimeZone(secondsFromGMT: 0)
-    return formatter.string(from: date)
-}
-
-func unixMs(_ date: Date) -> Int64 {
-    Int64((date.timeIntervalSince1970 * 1000).rounded())
-}
-
-struct MonotonicClock {
-    private static let timescale: CMTimeScale = 1_000_000_000
-
-    let startedAtUptimeNanoseconds: UInt64
-
-    init() {
-        startedAtUptimeNanoseconds = DispatchTime.now().uptimeNanoseconds
-    }
-
-    func elapsedSeconds() -> TimeInterval {
-        TimeInterval(elapsedNanoseconds()) / TimeInterval(Self.timescale)
-    }
-
-    func elapsedTime() -> CMTime {
-        CMTime(value: CMTimeValue(elapsedNanoseconds()), timescale: Self.timescale)
-    }
-
-    private func elapsedNanoseconds() -> UInt64 {
-        DispatchTime.now().uptimeNanoseconds - startedAtUptimeNanoseconds
-    }
-}

packages/build-tools/resources/record-sim/Sources/record-sim/main.swift

@@ -1,159 +0,0 @@
-import Foundation
-import RecordSim
-
-struct CLIOptions {
-    var udid: String?
-    var output: String?
-    var segmentDuration: TimeInterval = 120
-    var fps = 30
-    var bitrate = 30_000_000
-    var codec: RecorderCodec = .h264
-}
-
-private var requestedStopSignal: CInt = 0
-private var simulatorStopped: CInt = 0
-
-private func handleStopSignal(_ signal: CInt) {
-    requestedStopSignal = signal
-}
-
-private func isStopRequested() -> Bool {
-    requestedStopSignal != 0 || simulatorStopped != 0
-}
-
-func usage() -> String {
-    """
-    Usage:
-      record-sim --udid <UDID> --output <session-dir> [options]
-
-    Options:
-      --segment-duration <seconds>  Target fMP4 media segment duration. Use 0 for one MP4. Default: 120
-      --fps <fps>                   Expected source frame rate. Default: 30
-      --bitrate <bits/sec>          AVAssetWriter average bitrate. Default: 30000000
-      --codec <h264|hevc>           Video codec. Default: h264
-      -h, --help                    Show this help
-    """
-}
-
-func parseOptions(_ args: [String]) throws -> CLIOptions {
-    var options = CLIOptions()
-    var i = 0
-
-    func next(_ flag: String) throws -> String {
-        i += 1
-        guard i < args.count else {
-            throw NSError(domain: "record-sim", code: 2, userInfo: [NSLocalizedDescriptionKey: "Missing value for \(flag)"])
-        }
-        return args[i]
-    }
-
-    while i < args.count {
-        let arg = args[i]
-        switch arg {
-        case "--udid", "-u":
-            options.udid = try next(arg)
-        case "--output", "--output-dir", "--out", "-o":
-            options.output = try next(arg)
-        case "--segment-duration":
-            options.segmentDuration = Double(try next(arg)) ?? -1
-        case "--fps":
-            options.fps = Int(try next(arg)) ?? 0
-        case "--bitrate":
-            options.bitrate = Int(try next(arg)) ?? 0
-        case "--codec":
-            let raw = try next(arg)
-            guard let codec = RecorderCodec(rawValue: raw) else {
-                throw NSError(domain: "record-sim", code: 2, userInfo: [NSLocalizedDescriptionKey: "--codec must be h264 or hevc"])
-            }
-            options.codec = codec
-        case "--help", "-h":
-            print(usage())
-            exit(0)
-        default:
-            throw NSError(domain: "record-sim", code: 2, userInfo: [NSLocalizedDescriptionKey: "Unknown argument: \(arg)"])
-        }
-        i += 1
-    }
-
-    guard options.udid != nil else {
-        throw NSError(domain: "record-sim", code: 2, userInfo: [NSLocalizedDescriptionKey: "Missing required --udid"])
-    }
-    guard options.output != nil else {
-        throw NSError(domain: "record-sim", code: 2, userInfo: [NSLocalizedDescriptionKey: "Missing required --output"])
-    }
-    guard options.segmentDuration >= 0 else {
-        throw NSError(domain: "record-sim", code: 2, userInfo: [NSLocalizedDescriptionKey: "--segment-duration must be non-negative"])
-    }
-    guard options.fps > 0, options.fps <= 120 else {
-        throw NSError(domain: "record-sim", code: 2, userInfo: [NSLocalizedDescriptionKey: "--fps must be between 1 and 120"])
-    }
-    guard options.bitrate > 0 else {
-        throw NSError(domain: "record-sim", code: 2, userInfo: [NSLocalizedDescriptionKey: "--bitrate must be positive"])
-    }
-    return options
-}
-
-do {
-    signal(SIGINT, handleStopSignal)
-    signal(SIGTERM, handleStopSignal)
-
-    let options = try parseOptions(Array(CommandLine.arguments.dropFirst()))
-    let configuration = SimulatorRecordingConfiguration(
-        deviceUDID: options.udid!,
-        outputDirectory: URL(fileURLWithPath: options.output!),
-        fps: options.fps,
-        bitrate: options.bitrate,
-        codec: options.codec,
-        segmentDuration: options.segmentDuration
-    )
-
-    let recorder = SimulatorRecorder(configuration: configuration)
-    recorder.onSimulatorStopped = { state in
-        simulatorStopped = 1
-        fputs("[record-sim] simulator stopped state=\(state); finalizing recording\n", stderr)
-    }
-    recorder.onFinalizationStage = { stage in
-        switch stage {
-        case .captureStopped:
-            fputs("[record-sim] screen capture stopped; saving final video\n", stderr)
-        case .videoSaved:
-            fputs("[record-sim] final video saved; writing recording details\n", stderr)
-        }
-    }
-    recorder.onSegment = { segment in
-        switch segment.kind {
-        case .initialization:
-            fputs("[record-sim] init \(segment.relativePath) bytes=\(segment.byteCount)\n", stderr)
-        case .media:
-            let duration = segment.durationSeconds ?? 0
-            fputs(String(format: "[record-sim] segment %@ duration=%.3fs bytes=%d\n", segment.relativePath, duration, segment.byteCount), stderr)
-        }
-    }
-
-    try recorder.start()
-    try recorder.waitUntilFirstFrame()
-    fputs("[record-sim] recording -> \(options.output!)\n", stderr)
-
-    while !isStopRequested() {
-        Thread.sleep(forTimeInterval: 0.1)
-    }
-
-    if requestedStopSignal != 0 {
-        let signalName = switch requestedStopSignal {
-        case SIGINT: "SIGINT"
-        case SIGTERM: "SIGTERM"
-        default: "signal \(requestedStopSignal)"
-        }
-        fputs("[record-sim] received \(signalName); finishing recording\n", stderr)
-    }
-    let manifest = try recorder.stop()
-    if let recording = manifest.recording {
-        fputs("[record-sim] done recording=\(recording)\n", stderr)
-    } else {
-        fputs("[record-sim] done segments=\(manifest.segments.count)\n", stderr)
-    }
-    fputs("[record-sim] manifest \(URL(fileURLWithPath: options.output!).appendingPathComponent("session.json").path)\n", stderr)
-} catch {
-    fputs("error: \(error.localizedDescription)\n", stderr)
-    exit(1)
-}

packages/build-tools/scripts/verify-graphql.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -eox pipefail
+
+# Generated GraphQL files are untracked, so always regenerate and check compatibility.
+yarn gql
+yarn run -T lerna run build --scope @expo/build-tools --include-dependencies

packages/build-tools/src/__tests__/datadog.test.ts

@@ -318,6 +318,49 @@ describe('Datadog singleton', () => {
     );
   });
 
+  it('POSTs distribution metrics to the device run session worker API with the session token', () => {
+    turtleFetchMock.mockResolvedValueOnce({} as Response);
+
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      deviceRunSessionToken: 'session-token',
+      target: { kind: 'deviceRunSession' },
+    });
+
+    Datadog.distribution('eas.workflow.hook', 1, { hook: 'on_start' });
+
+    expect(turtleFetchMock).toHaveBeenCalledWith(
+      'https://api.expo.test/v2/device-run-session-worker/metrics',
+      'POST',
+      {
+        json: {
+          metrics: [
+            {
+              name: 'eas.workflow.hook',
+              type: 'distribution',
+              value: 1,
+              tags: { hook: 'on_start', target: 'job_run' },
+            },
+          ],
+        },
+        headers: { 'expo-device-run-session-token': 'session-token' },
+        retries: 2,
+      }
+    );
+  });
+
+  it('does not report logs for device run session targets', () => {
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      deviceRunSessionToken: 'session-token',
+      target: { kind: 'deviceRunSession' },
+    });
+
+    Datadog.log('Custom build saw user-provided function');
+
+    expect(turtleFetchMock).not.toHaveBeenCalled();
+  });
+
   it('flushes pending metric uploads', async () => {
     let resolveUpload!: (response: Response) => void;
     turtleFetchMock.mockReturnValueOnce(

packages/build-tools/src/android/resolve.ts

@@ -0,0 +1,5 @@
+import { Android } from '@expo/eas-build-job';
+
+export function resolveArtifactPath(job: Android.Job): string {
+  return job.applicationArchivePath ?? 'android/app/build/outputs/**/*.{apk,aab}';
+}

packages/build-tools/src/builders/__tests__/android.test.ts

@@ -60,7 +60,8 @@ jest.mock('../../utils/expoUpdates', () => ({
   resolveRuntimeVersionForExpoUpdatesIfConfiguredAsync: jest.fn(async () => null),
 }));
 jest.mock('../../utils/expoUpdatesEmbedded', () => ({
-  uploadEmbeddedBundleAsync: jest.fn(),
+  ...jest.requireActual('../../utils/expoUpdatesEmbedded'),
+  uploadEmbeddedBundleAsync: jest.fn(async () => ({ status: 'uploaded' })),
 }));
 jest.mock('../../utils/hooks', () => ({
   Hook: {
@@ -317,36 +318,108 @@ describe(androidBuilder, () => {
     expect(runBuilderWithHooksAsync).toHaveBeenCalledWith(ctx, expect.any(Function));
   });
 
-  it('runs the embedded bundle upload phase when EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE is set', async () => {
-    const ctx = new BuildContext(createTestAndroidJob(), {
-      workingdir: '/workingdir',
-      logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
-      logger: createMockLogger(),
-      env: {
-        __API_SERVER_URL: 'http://api.expo.test',
-        EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE: '1',
-      },
-      uploadArtifact: jest.fn(),
+  describe('embedded bundle upload phase', () => {
+    function createContext({
+      env = {},
+      sdkVersion,
+    }: {
+      env?: Record<string, string>;
+      sdkVersion?: string;
+    }): BuildContext<Android.Job> {
+      return new BuildContext(createTestAndroidJob(), {
+        workingdir: '/workingdir',
+        logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
+        logger: createMockLogger(),
+        env: {
+          __API_SERVER_URL: 'http://api.expo.test',
+          ...env,
+        },
+        uploadArtifact: jest.fn(),
+        metadata: sdkVersion ? { sdkVersion } : undefined,
+      });
+    }
+
+    it('runs by default on SDK 58 and later', async () => {
+      const ctx = createContext({ sdkVersion: '58.0.0' });
+
+      await androidBuilder(ctx);
+
+      expect(uploadEmbeddedBundleAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ job: ctx.job, env: ctx.env, projectDir: '/workingdir/build' })
+      );
     });
 
-    await androidBuilder(ctx);
+    it.each([
+      ['uploaded', BuildPhaseResult.SUCCESS],
+      ['skipped', BuildPhaseResult.SKIPPED],
+      ['failed', BuildPhaseResult.WARNING],
+    ] as const)('marks the phase from the %s result', async (uploadResult, phaseResult) => {
+      jest.mocked(uploadEmbeddedBundleAsync).mockResolvedValueOnce({ status: uploadResult });
+      const ctx = createContext({ sdkVersion: '58.0.0' });
 
-    expect(uploadEmbeddedBundleAsync).toHaveBeenCalledWith(ctx);
-  });
+      await androidBuilder(ctx);
 
-  it('skips the embedded bundle upload phase when EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE is not set', async () => {
-    const ctx = new BuildContext(createTestAndroidJob(), {
-      workingdir: '/workingdir',
-      logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
-      logger: createMockLogger(),
-      env: {
-        __API_SERVER_URL: 'http://api.expo.test',
-      },
-      uploadArtifact: jest.fn(),
+      expect(datadogDistributionMock).toHaveBeenCalledWith(
+        'eas.build.phase_duration',
+        expect.any(Number),
+        expect.objectContaining({
+          build_phase: BuildPhase.UPLOAD_EMBEDDED_BUNDLE.toLowerCase(),
+          result: phaseResult,
+        })
+      );
     });
 
-    await androidBuilder(ctx);
+    it('skips by default on SDK 57 and earlier', async () => {
+      const ctx = createContext({ sdkVersion: '57.0.0' });
 
-    expect(uploadEmbeddedBundleAsync).not.toHaveBeenCalled();
+      await androidBuilder(ctx);
+
+      expect(uploadEmbeddedBundleAsync).not.toHaveBeenCalled();
+    });
+
+    it('skips by default when the SDK version is unknown', async () => {
+      const ctx = createContext({});
+
+      await androidBuilder(ctx);
+
+      expect(uploadEmbeddedBundleAsync).not.toHaveBeenCalled();
+    });
+
+    it('runs on SDK 57 and earlier when EAS_UPDATE_UPLOAD_EMBEDDED_BUNDLE is 1', async () => {
+      const ctx = createContext({
+        sdkVersion: '57.0.0',
+        env: { EAS_UPDATE_UPLOAD_EMBEDDED_BUNDLE: '1' },
+      });
+
+      await androidBuilder(ctx);
+
+      expect(uploadEmbeddedBundleAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ job: ctx.job })
+      );
+    });
+
+    it('skips on SDK 58 and later when EAS_UPDATE_UPLOAD_EMBEDDED_BUNDLE is 0', async () => {
+      const ctx = createContext({
+        sdkVersion: '58.0.0',
+        env: { EAS_UPDATE_UPLOAD_EMBEDDED_BUNDLE: '0' },
+      });
+
+      await androidBuilder(ctx);
+
+      expect(uploadEmbeddedBundleAsync).not.toHaveBeenCalled();
+    });
+
+    it('runs on SDK 57 and earlier when the experimental EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE is 1', async () => {
+      const ctx = createContext({
+        sdkVersion: '57.0.0',
+        env: { EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE: '1' },
+      });
+
+      await androidBuilder(ctx);
+
+      expect(uploadEmbeddedBundleAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ job: ctx.job })
+      );
+    });
   });
 });

packages/build-tools/src/builders/android.ts

@@ -11,6 +11,7 @@ import {
   runGradleCommand,
 } from '../android/gradle';
 import { formatGradleProfileReport, parseGradleProfile } from '../android/gradleProfile';
+import { resolveArtifactPath } from '../android/resolve';
 import { Sentry } from '../sentry';
 import { eagerBundleAsync, shouldUseEagerBundle } from '../common/eagerBundle';
 import { prebuildAsync } from '../common/prebuild';
@@ -32,7 +33,10 @@ import {
   configureExpoUpdatesIfInstalledAsync,
   resolveRuntimeVersionForExpoUpdatesIfConfiguredAsync,
 } from '../utils/expoUpdates';
-import { uploadEmbeddedBundleAsync } from '../utils/expoUpdatesEmbedded';
+import {
+  shouldUploadEmbeddedBundle,
+  uploadEmbeddedBundleAsync,
+} from '../utils/expoUpdatesEmbedded';
 import { Hook, runHookIfPresent } from '../utils/hooks';
 import { prepareExecutableAsync } from '../utils/prepareBuildExecutable';
 
@@ -217,15 +221,26 @@ async function buildInnerAsync(
 
   await ctx.runBuildPhase(BuildPhase.UPLOAD_APPLICATION_ARCHIVE, async () => {
     await uploadApplicationArchive(ctx, {
-      patternOrPath: ctx.job.applicationArchivePath ?? 'android/app/build/outputs/**/*.{apk,aab}',
+      patternOrPath: resolveArtifactPath(ctx.job),
       rootDir: ctx.getReactNativeProjectDirectory(),
       logger: ctx.logger,
     });
   });
 
-  if (ctx.env.EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE) {
+  if (shouldUploadEmbeddedBundle(ctx)) {
     await ctx.runBuildPhase(BuildPhase.UPLOAD_EMBEDDED_BUNDLE, async () => {
-      await uploadEmbeddedBundleAsync(ctx);
+      const { status } = await uploadEmbeddedBundleAsync({
+        job: ctx.job,
+        env: ctx.env,
+        logger: ctx.logger,
+        projectDir: ctx.getReactNativeProjectDirectory(),
+        appConfig: await ctx.appConfig,
+      });
+      if (status === 'skipped') {
+        ctx.markBuildPhaseSkipped();
+      } else if (status === 'failed') {
+        ctx.markBuildPhaseHasWarnings();
+      }
     });
   }
 

packages/build-tools/src/builders/ios.ts

@@ -29,7 +29,10 @@ import {
   configureExpoUpdatesIfInstalledAsync,
   resolveRuntimeVersionForExpoUpdatesIfConfiguredAsync,
 } from '../utils/expoUpdates';
-import { uploadEmbeddedBundleAsync } from '../utils/expoUpdatesEmbedded';
+import {
+  shouldUploadEmbeddedBundle,
+  uploadEmbeddedBundleAsync,
+} from '../utils/expoUpdatesEmbedded';
 import { Hook, runHookIfPresent } from '../utils/hooks';
 import { prepareExecutableAsync } from '../utils/prepareBuildExecutable';
 import { getParentAndDescendantProcessPidsAsync } from '../utils/processes';
@@ -234,15 +237,26 @@ async function buildInnerAsync(
 
   await ctx.runBuildPhase(BuildPhase.UPLOAD_APPLICATION_ARCHIVE, async () => {
     await uploadApplicationArchive(ctx, {
-      patternOrPath: resolveArtifactPath(ctx),
+      patternOrPath: resolveArtifactPath(ctx.job),
       rootDir: ctx.getReactNativeProjectDirectory(),
       logger: ctx.logger,
     });
   });
 
-  if (ctx.env.EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE) {
+  if (shouldUploadEmbeddedBundle(ctx)) {
     await ctx.runBuildPhase(BuildPhase.UPLOAD_EMBEDDED_BUNDLE, async () => {
-      await uploadEmbeddedBundleAsync(ctx);
+      const { status } = await uploadEmbeddedBundleAsync({
+        job: ctx.job,
+        env: ctx.env,
+        logger: ctx.logger,
+        projectDir: ctx.getReactNativeProjectDirectory(),
+        appConfig: await ctx.appConfig,
+      });
+      if (status === 'skipped') {
+        ctx.markBuildPhaseSkipped();
+      } else if (status === 'failed') {
+        ctx.markBuildPhaseHasWarnings();
+      }
     });
   }
 

packages/build-tools/src/context.ts

@@ -69,6 +69,7 @@ export interface BuildContextOptions {
   metadata?: Metadata;
   expoApiV2BaseUrl?: string;
   mcpServerUrl?: string;
+  addBuildLogMask?: (secret: string) => void;
 }
 
 export class SkipNativeBuildError extends Error {}
@@ -86,6 +87,7 @@ export class BuildContext<TJob extends Job = Job> {
   public readonly skipNativeBuild?: boolean;
   public readonly expoApiV2BaseUrl?: string;
   public readonly mcpServerUrl?: string;
+  public readonly addBuildLogMask?: (secret: string) => void;
   public artifacts: Artifacts = {};
 
   private readonly _isLocal: boolean;
@@ -115,6 +117,7 @@ export class BuildContext<TJob extends Job = Job> {
     this.skipNativeBuild = options.skipNativeBuild;
     this.expoApiV2BaseUrl = options.expoApiV2BaseUrl;
     this.mcpServerUrl = options.mcpServerUrl;
+    this.addBuildLogMask = options.addBuildLogMask;
 
     const environmentSecrets = this.getEnvironmentSecrets(job);
     this._env = {

packages/build-tools/src/customBuildContext.ts

@@ -32,6 +32,7 @@ export interface BuilderRuntimeApi {
   uploadArtifact: (spec: { artifact: ArtifactToUpload; logger: bunyan }) => Promise<{
     artifactId: string | null;
   }>;
+  addBuildLogMask?: (secret: string) => void;
 }
 
 export class CustomBuildContext<TJob extends Job = Job> implements ExternalBuildContextProvider {
@@ -63,12 +64,12 @@ export class CustomBuildContext<TJob extends Job = Job> implements ExternalBuild
   public readonly logger: bunyan;
   public readonly graphqlClient: Client;
   public readonly runtimeApi: BuilderRuntimeApi;
+  public readonly expoApiV2BaseUrl?: string;
   public readonly mcpServerUrl?: string;
   public job: TJob;
   public metadata?: Metadata;
 
   private _env: Env;
-  private readonly expoApiV2BaseUrl?: string;
   private readonly pendingMetricUploads: Promise<void>[] = [];
 
   constructor(buildCtx: BuildContext<TJob>) {
@@ -84,6 +85,7 @@ export class CustomBuildContext<TJob extends Job = Job> implements ExternalBuild
     this.buildLogsDirectory = path.join(buildCtx.workingdir, 'logs');
     this.runtimeApi = {
       uploadArtifact: (...args) => buildCtx['uploadArtifact'](...args),
+      addBuildLogMask: buildCtx.addBuildLogMask,
     };
     this.mcpServerUrl = buildCtx.mcpServerUrl;
     this.expoApiV2BaseUrl = buildCtx.expoApiV2BaseUrl;

packages/build-tools/src/datadog.ts

@@ -1,15 +1,24 @@
 import { Sentry } from './sentry';
+import { DEVICE_RUN_SESSION_TOKEN_HEADER } from './steps/utils/deviceRunSessionWorkerApi';
 import { turtleFetch } from './utils/turtleFetch';
 
 type MetricsTarget =
   | { kind: 'build'; turtleBuildId: string }
-  | { kind: 'jobRun'; turtleJobRunId: string };
+  | { kind: 'jobRun'; turtleJobRunId: string }
+  // A device run session job with a session token. The token names the session and its job run.
+  | { kind: 'deviceRunSession' };
 
-type DatadogSetupOptions = {
-  expoApiV2BaseUrl: string;
-  robotAccessToken: string;
-  target: MetricsTarget;
-};
+type DatadogSetupOptions =
+  | {
+      expoApiV2BaseUrl: string;
+      robotAccessToken: string;
+      target: Exclude<MetricsTarget, { kind: 'deviceRunSession' }>;
+    }
+  | {
+      expoApiV2BaseUrl: string;
+      deviceRunSessionToken: string;
+      target: Extract<MetricsTarget, { kind: 'deviceRunSession' }>;
+    };
 
 let setupOptions: DatadogSetupOptions | null = null;
 let pendingUploads: Promise<unknown>[] = [];
@@ -18,9 +27,30 @@ function withTargetTag(
   tags: Record<string, string>,
   target: MetricsTarget
 ): Record<string, string> {
+  // A device run session job is a job run, so its metrics keep the job run tag.
   return { ...tags, target: target.kind === 'build' ? 'build' : 'job_run' };
 }
 
+function getMetricsRequest(options: DatadogSetupOptions): {
+  path: string;
+  headers: Record<string, string>;
+} {
+  if ('deviceRunSessionToken' in options) {
+    return {
+      path: 'device-run-session-worker/metrics',
+      headers: { [DEVICE_RUN_SESSION_TOKEN_HEADER]: options.deviceRunSessionToken },
+    };
+  }
+  const { target, robotAccessToken } = options;
+  return {
+    path:
+      target.kind === 'build'
+        ? `turtle-builds/${target.turtleBuildId}/metrics`
+        : `turtle-job-runs/${target.turtleJobRunId}/metrics`,
+    headers: { Authorization: `Bearer ${robotAccessToken}` },
+  };
+}
+
 export const Datadog = {
   setup(opts: DatadogSetupOptions | null): void {
     setupOptions = opts;
@@ -30,7 +60,7 @@ export const Datadog = {
     if (!setupOptions) {
       return;
     }
-    const { expoApiV2BaseUrl, robotAccessToken, target } = setupOptions;
+    const { expoApiV2BaseUrl, target } = setupOptions;
     const metrics = [
       {
         name,
@@ -40,16 +70,11 @@ export const Datadog = {
       },
     ];
 
-    const metricsPath =
-      target.kind === 'build'
-        ? `turtle-builds/${target.turtleBuildId}/metrics`
-        : `turtle-job-runs/${target.turtleJobRunId}/metrics`;
+    const { path: metricsPath, headers } = getMetricsRequest(setupOptions);
 
     const uploadPromise = turtleFetch(new URL(metricsPath, expoApiV2BaseUrl).toString(), 'POST', {
       json: { metrics },
-      headers: {
-        Authorization: `Bearer ${robotAccessToken}`,
-      },
+      headers,
       retries: 2,
     }).catch(err => {
       Sentry.capture(`Failed to report turtle ${target.kind} metric`, err, {
@@ -61,7 +86,9 @@ export const Datadog = {
   },
 
   log(message: string, tags: Record<string, string> = {}): void {
-    if (!setupOptions) {
+    // The device run session worker API has no logs route, and the session token is not a bearer
+    // credential, so a device run session job does not report these logs.
+    if (!setupOptions || !('robotAccessToken' in setupOptions)) {
       return;
     }
     const { expoApiV2BaseUrl, robotAccessToken, target } = setupOptions;

packages/build-tools/src/index.ts

@@ -33,5 +33,6 @@ export type { GradleProfileTask } from './android/gradleProfile';
 export * from './generic';
 
 export { Datadog } from './datadog';
+export { getDeviceRunSessionTokenFromEnvironmentSecrets } from './steps/utils/deviceRunSessionWorkerApi';
 export { Sentry } from './sentry';
 export * from './runtimeSettings';

packages/build-tools/src/ios/resolve.ts

@@ -15,10 +15,10 @@ export function resolveScheme(ctx: BuildContext<Ios.Job>): string {
   return schemes[0];
 }
 
-export function resolveArtifactPath(ctx: BuildContext<Ios.Job>): string {
-  if (ctx.job.applicationArchivePath) {
-    return ctx.job.applicationArchivePath;
-  } else if (ctx.job.simulator) {
+export function resolveArtifactPath(job: Ios.Job): string {
+  if (job.applicationArchivePath) {
+    return job.applicationArchivePath;
+  } else if (job.simulator) {
     return 'ios/build/Build/Products/*simulator/*.app';
   } else {
     return 'ios/build/*.ipa';

packages/build-tools/src/steps/__tests__/hookAnchors.test.ts

@@ -11,7 +11,7 @@ import { getEasFunctions } from '../easFunctions';
 jest.mock('fs');
 
 describe('hook anchor self-declarations', () => {
-  it('exactly the four v0 functions declare anchors, with these bindings', () => {
+  it('declares the expected hook anchors', () => {
     const declarations: Record<string, HookAnchorId> = {};
     for (const buildFunction of getEasFunctions(createCustomBuildContextMock())) {
       if (buildFunction.__hookId !== undefined) {
@@ -24,6 +24,7 @@ describe('hook anchor self-declarations', () => {
       'eas/checkout': 'checkout',
       'eas/install_node_modules': 'install_node_modules',
       'eas/upload_to_asc': 'submit',
+      'eas/submit_to_google_play': 'submit',
       'eas/maestro_tests': 'maestro_tests',
     });
   });
@@ -87,6 +88,17 @@ describe('hook anchor self-declarations', () => {
         bundle_short_version: '1.0.0',
       },
     ],
+    [
+      'eas/submit_to_google_play',
+      'before_submit',
+      'after_submit',
+      {
+        artifact_path: 'app.aab',
+        artifact_type: 'aab',
+        package_name: 'com.example.app',
+        service_account_key_path: 'key.json',
+      },
+    ],
     [
       'eas/maestro_tests',
       'before_maestro_tests',

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

@@ -10,6 +10,7 @@ import { configureIosVersionFunction } from './functions/configureIosVersion';
 import { createSubmissionEntityFunction } from './functions/createSubmissionEntity';
 import { createDownloadArtifactFunction } from './functions/downloadArtifact';
 import { createDownloadBuildFunction } from './functions/downloadBuild';
+import { createDownloadSubmissionArchiveFunction } from './functions/downloadSubmissionArchive';
 import { createEasDeployBuildFunction } from './functions/deploy';
 import { createEasExportBuildFunction } from './functions/export';
 import { eagerBundleBuildFunction } from './functions/eagerBundle';
@@ -19,6 +20,7 @@ import { generateGymfileFromTemplateFunction } from './functions/generateGymfile
 import { createGetCredentialsForBuildTriggeredByGithubIntegration } from './functions/getCredentialsForBuildTriggeredByGitHubIntegration';
 import { injectAndroidCredentialsFunction } from './functions/injectAndroidCredentials';
 import { createInstallMaestroBuildFunction } from './functions/installMaestro';
+import { createInstallMitmproxyBuildFunction } from './functions/installMitmproxy';
 import { createInstallBuildFunction } from './functions/installBuild';
 import { createInstallNodeModulesBuildFunction } from './functions/installNodeModules';
 import { createInstallPodsBuildFunction } from './functions/installPods';
@@ -26,6 +28,8 @@ import { createLaunchApplicationFunction } from './functions/launchApplication';
 import { createPrebuildBuildFunction } from './functions/prebuild';
 import { createReadAppConfigBuildFunction } from './functions/readAppConfig';
 import { createReadIpaInfoBuildFunction } from './functions/readIpaInfo';
+import { createReadAndroidAppInfoBuildFunction } from './functions/readAndroidAppInfo';
+import { createSubmitToGooglePlayBuildFunction } from './functions/submitToGooglePlay';
 import { createReadPackageJsonBuildFunction } from './functions/readPackageJson';
 import { createRepackBuildFunction } from './functions/repack';
 import { createReportMaestroTestResultsFunction } from './functions/reportMaestroTestResults';
@@ -42,9 +46,10 @@ import { runGradleFunction } from './functions/runGradle';
 import { createMaestroTestsBuildFunction } from './functions/maestroTests';
 import { createSaveBuildCacheFunction } from './functions/saveBuildCache';
 import { createRolloutPosthogFlagFunction } from './functions/rolloutPosthogFlag';
+import { createRunAgentBuildFunction } from './functions/runAgent';
 import { createSaveCacheFunction } from './functions/saveCache';
 import { createSendSlackMessageFunction } from './functions/sendSlackMessage';
-import { createStartAgentDeviceRemoteSessionBuildFunction } from './functions/startAgentDeviceRemoteSession';
+import { createStartAgentDeviceSessionBuildFunction } from './functions/startAgentDeviceSession';
 import { createStartAndroidEmulatorBuildFunction } from './functions/startAndroidEmulator';
 import { createStartArgentRemoteSessionBuildFunction } from './functions/startArgentRemoteSession';
 import { createStartAppiumRemoteSessionBuildFunction } from './functions/startAppiumRemoteSession';
@@ -54,11 +59,15 @@ import { createStartIosSimulatorRecordingsBuildFunction } from './functions/star
 import { createStartLocalEgressBuildFunction } from './functions/startLocalEgress';
 import { createStartWebPreviewRemoteSessionBuildFunction } from './functions/startWebPreviewRemoteSession';
 import { createStartServeSimMetricsBuildFunction } from './functions/startServeSimMetrics';
+import { createStartServeSimLogsBuildFunction } from './functions/startServeSimLogs';
+import { createCollectServeSimLogsBuildFunction } from './functions/collectServeSimLogs';
 import { createStartSandboxBuildFunction } from './functions/startSandbox';
 import { createCollectServeSimMetricsBuildFunction } from './functions/collectServeSimMetrics';
 import { createUploadArtifactBuildFunction } from './functions/uploadArtifact';
 import { createUploadDeviceRunSessionScreenRecordingsBuildFunction } from './functions/uploadDeviceRunSessionScreenRecordings';
+import { createUploadEmbeddedBundleBuildFunction } from './functions/uploadEmbeddedBundle';
 import { createUploadToAscBuildFunction } from './functions/uploadToAsc';
+import { createUpdateTestFlightMetadataBuildFunction } from './functions/updateTestFlightMetadata';
 import { createSetUpNpmrcBuildFunction } from './functions/useNpmToken';
 import { createWaitForPosthogMetricFunction } from './functions/waitForPosthogMetric';
 import { createUploadPosthogSourcemapsFunction } from './functions/uploadPosthogSourcemaps';
@@ -77,7 +86,9 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
     createInstallNodeModulesBuildFunction(),
     createPrebuildBuildFunction(),
     createReadIpaInfoBuildFunction(),
+    createReadAndroidAppInfoBuildFunction(),
     createDownloadBuildFunction(ctx),
+    createDownloadSubmissionArchiveFunction(ctx),
     createInstallBuildFunction(),
     createLaunchApplicationFunction(),
     createEasExportBuildFunction(),
@@ -99,7 +110,7 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
     generateGymfileFromTemplateFunction(),
     runFastlaneFunction(),
     parseXcactivitylogFunction(),
-    createStartAgentDeviceRemoteSessionBuildFunction(ctx),
+    createStartAgentDeviceSessionBuildFunction(ctx),
     createStartArgentRemoteSessionBuildFunction(ctx),
     createStartAppiumRemoteSessionBuildFunction(ctx),
     createStartAndroidEmulatorBuildFunction(),
@@ -111,9 +122,13 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
     createUploadDeviceRunSessionScreenRecordingsBuildFunction(ctx),
     createStartWebPreviewRemoteSessionBuildFunction(ctx),
     createStartServeSimMetricsBuildFunction(),
+    createStartServeSimLogsBuildFunction(),
+    createCollectServeSimLogsBuildFunction(ctx),
     createStartSandboxBuildFunction(ctx),
+    createRunAgentBuildFunction(ctx),
     createCollectServeSimMetricsBuildFunction(ctx),
     createInstallMaestroBuildFunction(),
+    createInstallMitmproxyBuildFunction(),
 
     createInstallPodsBuildFunction(),
     createSendSlackMessageFunction(),
@@ -127,7 +142,9 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
     calculateEASUpdateRuntimeVersionFunction(),
 
     createSubmissionEntityFunction(),
+    createSubmitToGooglePlayBuildFunction(),
     createUploadToAscBuildFunction(),
+    createUpdateTestFlightMetadataBuildFunction(),
 
     createReportMaestroTestResultsFunction(ctx),
     createMaestroTestsBuildFunction(ctx),
@@ -137,6 +154,7 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
     functions.push(
       ...[
         createFindAndUploadBuildArtifactsBuildFunction(ctx),
+        createUploadEmbeddedBundleBuildFunction(ctx),
         createResolveBuildConfigBuildFunction(ctx),
         createGetCredentialsForBuildTriggeredByGithubIntegration(ctx),
       ]

packages/build-tools/src/steps/functionGroups/__tests__/build.test.ts

@@ -219,4 +219,71 @@ describe(createEasBuildBuildFunctionGroup, () => {
       'Build function group is not supported in generic jobs.'
     );
   });
+
+  describe('embedded bundle upload', () => {
+    function getStepNames(
+      options: Parameters<typeof createMockBuildToolsContext>[0],
+      { sdkVersion, env = {} }: { sdkVersion?: string; env?: Record<string, string> }
+    ): string[] {
+      const functionGroup = createEasBuildBuildFunctionGroup(createMockBuildToolsContext(options));
+      const globalCtx = createGlobalContextMock({
+        logger: createMockLogger(),
+        staticContextContent: { metadata: sdkVersion ? { sdkVersion } : null },
+      });
+      globalCtx.updateEnv(env);
+      return functionGroup
+        .createBuildStepsFromFunctionGroupCall(globalCtx)
+        .map(step => step.displayName);
+    }
+
+    it.each([
+      ['Android', { platform: Platform.ANDROID }],
+      ['Android with credentials', { platform: Platform.ANDROID, buildCredentials: { test: {} } }],
+      ['iOS with credentials', { platform: Platform.IOS, buildCredentials: { test: {} } }],
+    ])('uploads the embedded bundle after the build artifacts on SDK 58 (%s)', (_, options) => {
+      const stepNames = getStepNames(options, { sdkVersion: '58.0.0' });
+
+      expect(stepNames.indexOf('Upload embedded bundle')).toBe(
+        stepNames.indexOf('Find and upload build artifacts') + 1
+      );
+    });
+
+    it.each([
+      ['Android', { platform: Platform.ANDROID }],
+      ['Android with credentials', { platform: Platform.ANDROID, buildCredentials: { test: {} } }],
+      ['iOS with credentials', { platform: Platform.IOS, buildCredentials: { test: {} } }],
+    ])('passes ignore_error to the embedded bundle step (%s)', (_, options) => {
+      const functionGroup = createEasBuildBuildFunctionGroup(createMockBuildToolsContext(options));
+      const globalCtx = createGlobalContextMock({
+        logger: createMockLogger(),
+        staticContextContent: { metadata: { sdkVersion: '58.0.0' } },
+      });
+
+      const uploadStep = functionGroup
+        .createBuildStepsFromFunctionGroupCall(globalCtx)
+        .find(step => step.displayName === 'Upload embedded bundle');
+
+      expect(uploadStep).toBeDefined();
+      expect(uploadStep!.inputs?.find(input => input.id === 'ignore_error')?.rawValue).toBe(true);
+    });
+
+    it('does not upload the embedded bundle on SDK 57 without the opt-in', () => {
+      expect(getStepNames({}, { sdkVersion: '57.0.0' })).not.toContain('Upload embedded bundle');
+    });
+
+    it('uploads the embedded bundle on SDK 57 with the opt-in', () => {
+      expect(
+        getStepNames(
+          {},
+          { sdkVersion: '57.0.0', env: { EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE: '1' } }
+        )
+      ).toContain('Upload embedded bundle');
+    });
+
+    it('does not upload the embedded bundle for iOS simulator builds', () => {
+      expect(
+        getStepNames({ platform: Platform.IOS, simulator: true }, { sdkVersion: '58.0.0' })
+      ).not.toContain('Upload embedded bundle');
+    });
+  });
 });

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

@@ -10,6 +10,7 @@ import path from 'path';
 
 import { shouldUseEagerBundle } from '../../common/eagerBundle';
 import { CustomBuildContext } from '../../customBuildContext';
+import { shouldUploadEmbeddedBundle } from '../../utils/expoUpdatesEmbedded';
 import { calculateEASUpdateRuntimeVersionFunction } from '../functions/calculateEASUpdateRuntimeVersion';
 import { createCheckoutBuildFunction } from '../functions/checkout';
 import { configureAndroidVersionFunction } from '../functions/configureAndroidVersion';
@@ -32,6 +33,7 @@ import {
 import { runFastlaneFunction } from '../functions/runFastlane';
 import { runGradleFunction } from '../functions/runGradle';
 import { createSaveBuildCacheFunction } from '../functions/saveBuildCache';
+import { createUploadEmbeddedBundleBuildFunction } from '../functions/uploadEmbeddedBundle';
 import { createSetUpNpmrcBuildFunction } from '../functions/useNpmToken';
 
 interface HelperFunctionsInput {
@@ -303,6 +305,19 @@ function createStepsForIosBuildWithCredentials({
     createFindAndUploadBuildArtifactsBuildFunction(
       buildToolsContext
     ).createBuildStepFromFunctionCall(globalCtx, { workingDirectory }),
+    ...(shouldUploadEmbeddedBundle({
+      env: globalCtx.env,
+      metadata: globalCtx.staticContext.metadata,
+    })
+      ? [
+          createUploadEmbeddedBundleBuildFunction(
+            buildToolsContext
+          ).createBuildStepFromFunctionCall(globalCtx, {
+            workingDirectory,
+            callInputs: { ignore_error: true },
+          }),
+        ]
+      : []),
     saveCache,
     createCacheStatsBuildFunction().createBuildStepFromFunctionCall(globalCtx, {
       workingDirectory,
@@ -390,6 +405,19 @@ function createStepsForAndroidBuildWithoutCredentials({
     createFindAndUploadBuildArtifactsBuildFunction(
       buildToolsContext
     ).createBuildStepFromFunctionCall(globalCtx, { workingDirectory }),
+    ...(shouldUploadEmbeddedBundle({
+      env: globalCtx.env,
+      metadata: globalCtx.staticContext.metadata,
+    })
+      ? [
+          createUploadEmbeddedBundleBuildFunction(
+            buildToolsContext
+          ).createBuildStepFromFunctionCall(globalCtx, {
+            workingDirectory,
+            callInputs: { ignore_error: true },
+          }),
+        ]
+      : []),
     saveCache,
     createCacheStatsBuildFunction().createBuildStepFromFunctionCall(globalCtx, {
       workingDirectory,
@@ -483,6 +511,19 @@ function createStepsForAndroidBuildWithCredentials({
     createFindAndUploadBuildArtifactsBuildFunction(
       buildToolsContext
     ).createBuildStepFromFunctionCall(globalCtx, { workingDirectory }),
+    ...(shouldUploadEmbeddedBundle({
+      env: globalCtx.env,
+      metadata: globalCtx.staticContext.metadata,
+    })
+      ? [
+          createUploadEmbeddedBundleBuildFunction(
+            buildToolsContext
+          ).createBuildStepFromFunctionCall(globalCtx, {
+            workingDirectory,
+            callInputs: { ignore_error: true },
+          }),
+        ]
+      : []),
     saveCache,
     createCacheStatsBuildFunction().createBuildStepFromFunctionCall(globalCtx, {
       workingDirectory,

packages/build-tools/src/steps/functions/__integration-tests__/readAndroidAppInfo.test.ts

@@ -0,0 +1,47 @@
+import { UserError } from '@expo/eas-build-job';
+import path from 'node:path';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { readAndroidArtifactInfoAsync } from '../../utils/android/appArtifact';
+import { createReadAndroidAppInfoBuildFunction } from '../readAndroidAppInfo';
+
+jest.unmock('fs');
+jest.unmock('node:fs');
+jest.unmock('fs/promises');
+jest.unmock('node:fs/promises');
+jest.unmock('@expo/spawn-async');
+
+const fixturesDirectory = path.join(__dirname, 'fixtures/android-app-info');
+
+it.each(['apk', 'aab'])('reads a real %s and publishes build step outputs', async type => {
+  const step = createReadAndroidAppInfoBuildFunction().createBuildStepFromFunctionCall(
+    createGlobalContextMock({
+      projectTargetDirectory: fixturesDirectory,
+      staticContextContent: { job: {} },
+    }),
+    { callInputs: { artifact_path: `app.${type}` } }
+  );
+
+  await step.executeAsync();
+
+  expect(step.outputById.artifact_type.value).toBe(type);
+  expect(step.outputById.package_name.value).toBe('com.example.app');
+});
+
+it('reports an invalid ZIP as a user error', async () => {
+  await expect(readAndroidArtifactInfoAsync(__filename)).rejects.toMatchObject({
+    constructor: UserError,
+    errorCode: 'EAS_READ_ANDROID_APP_INFO_INVALID_ARTIFACT',
+    cause: expect.any(Error),
+  });
+});
+
+it.each(['apk', 'aab'])('retains the native tool error for an invalid %s manifest', async type => {
+  await expect(
+    readAndroidArtifactInfoAsync(path.join(fixturesDirectory, `invalid-manifest-${type}.zip`))
+  ).rejects.toMatchObject({
+    constructor: UserError,
+    errorCode: 'EAS_READ_ANDROID_APP_INFO_INVALID_MANIFEST',
+    cause: expect.any(Error),
+  });
+});

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

@@ -0,0 +1,401 @@
+import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+import fs from 'node:fs';
+
+import type { CustomBuildContext } from '../../../customBuildContext';
+import { Sentry } from '../../../sentry';
+import { AndroidEmulatorUtils } from '../../../utils/AndroidEmulatorUtils';
+import { turtleFetch } from '../../../utils/turtleFetch';
+import { startAgentDeviceEventCollectionAsync } from '../../utils/agentDeviceEvents';
+import { startAppiumEventCollectionAsync } from '../../utils/appiumEvents';
+import { startDeviceSessionHostAsync } from '../../utils/deviceSessionHost';
+import {
+  spawnDetached,
+  startNgrokTunnelAsync,
+  uploadRemoteSessionConfigAsync,
+  waitForDeviceRunSessionStoppedAsync,
+  waitForFileAsync,
+} from '../../utils/remoteDeviceRunSession';
+import { createStartAgentDeviceSessionBuildFunction } from '../startAgentDeviceSession';
+import { createStartAppiumRemoteSessionBuildFunction } from '../startAppiumRemoteSession';
+
+jest.mock('@expo/turtle-spawn');
+jest.mock('../../../sentry');
+jest.mock('../../../utils/turtleFetch');
+jest.mock('../../../utils/AndroidEmulatorUtils');
+jest.mock('../../utils/deviceSessionHost');
+jest.mock('../../utils/agentDeviceEvents');
+jest.mock('../../utils/appiumEvents');
+jest.mock('../../utils/agentDeviceArtifacts');
+// The agent-device session step boots the emulator itself; this test covers the session host.
+jest.mock('../startAndroidEmulator', () => ({
+  startAndroidEmulatorAsync: jest.fn().mockResolvedValue({
+    serialId: 'emulator-5554',
+    emulatorPromise: Promise.resolve(),
+    shouldAdjustAnimationScale: true,
+  }),
+}));
+jest.mock('../../utils/remoteDeviceRunSession', () => ({
+  ...jest.requireActual('../../utils/remoteDeviceRunSession'),
+  spawnDetached: jest.fn(),
+  startNgrokTunnelAsync: jest.fn(),
+  uploadRemoteSessionConfigAsync: jest.fn(),
+  waitForDeviceRunSessionStoppedAsync: jest.fn(),
+  waitForFileAsync: jest.fn(),
+}));
+
+const finishHost = jest.fn();
+const closePreview = jest.fn();
+const stopTool = jest.fn();
+const stopTunnel = jest.fn();
+const stopEvents = jest.fn();
+const openPreview = jest.fn();
+const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  // The daemon package is external. No installation or daemon process runs in these tests.
+  jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+  // Only the emulator logcat folder: the Appium step writes into its own temp folder.
+  const mkdtemp = fs.promises.mkdtemp.bind(fs.promises);
+  jest
+    .spyOn(fs.promises, 'mkdtemp')
+    .mockImplementation(async prefix =>
+      String(prefix).includes('eas-android-emulator-logcat-')
+        ? '/tmp/eas-android-emulator-logcat-test'
+        : mkdtemp(prefix)
+    );
+  jest.mocked(spawn).mockResolvedValue({ stdout: '{}' } as never);
+  jest
+    .mocked(AndroidEmulatorUtils.getAttachedDevicesAsync)
+    .mockResolvedValue([{ serialId: 'emulator-5554', state: 'device' } as never]);
+  jest.mocked(turtleFetch).mockResolvedValue({ ok: true } as never);
+  jest.mocked(waitForFileAsync).mockResolvedValue({ port: 4567, token: 'daemon-token' });
+  for (const stop of [finishHost, closePreview, stopTool, stopTunnel, stopEvents]) {
+    stop.mockResolvedValue(undefined);
+  }
+  openPreview.mockResolvedValue({
+    previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
+    apiUrl: 'https://preview.example.test',
+    closeAsync: closePreview,
+  });
+  jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
+    openPreviewAsync: openPreview,
+    getLastPreviewActivityAt: jest.fn(),
+    finishAsync: finishHost,
+  });
+  jest.mocked(spawnDetached).mockReturnValue({
+    pid: undefined,
+    getOutput: () => '',
+    getExitError: () => undefined,
+    stopAsync: stopTool,
+  });
+  jest.mocked(startNgrokTunnelAsync).mockResolvedValue({
+    url: 'https://tool.example.test',
+    subdomainId: 'tool-id',
+    stopAsync: stopTunnel,
+  });
+  const events = { stopAsync: stopEvents, getLastEventObservedAt: () => undefined };
+  jest.mocked(startAgentDeviceEventCollectionAsync).mockResolvedValue(events);
+  jest.mocked(startAppiumEventCollectionAsync).mockResolvedValue(events);
+  jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
+  jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe.each([
+  ['Appium', createStartAppiumRemoteSessionBuildFunction],
+  ['Agent Device', createStartAgentDeviceSessionBuildFunction],
+] as const)('%s host ownership', (name, createFunction) => {
+  async function runAsync(
+    publicPreview?: boolean,
+    frameAncestors?: string[],
+    corsOrigins?: string[]
+  ) {
+    const fn = createFunction({} as CustomBuildContext);
+    await fn.fn!(
+      {
+        logger,
+        global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+      } as unknown as BuildStepContext,
+      {
+        // Inputs a step does not get default to undefined, like in a real step call.
+        inputs: new Proxy(
+          {
+            public_preview: { value: publicPreview },
+            frame_ancestors: { value: frameAncestors },
+            cors_origins: { value: corsOrigins },
+          } as Record<string, { value: unknown }>,
+          {
+            get: (target, id: string) => target[id] ?? { value: undefined },
+          }
+        ),
+        outputs: {},
+        env: {
+          DEVICE_RUN_SESSION_ID: 'session-id',
+          EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN: 'example.test',
+          NGROK_AUTHTOKEN: 'token',
+        },
+      } as never
+    );
+  }
+
+  it('holds the host until session completion', async () => {
+    await runAsync();
+    expect(openPreview).toHaveBeenCalledWith({ baseDomain: 'example.test', authtoken: 'token' });
+    expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteConfig: expect.objectContaining({
+          webPreviewUrl: 'https://expo.dev/simulator-preview/preview-id',
+          previewApiUrl: 'https://preview.example.test',
+        }),
+      })
+    );
+    expect(finishHost).toHaveBeenCalledTimes(1);
+    expect(closePreview).not.toHaveBeenCalled();
+    expect(finishHost.mock.invocationCallOrder[0]).toBeGreaterThan(
+      jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.invocationCallOrder[0]
+    );
+    expect(stopTool).toHaveBeenCalledTimes(1);
+    expect(stopEvents).toHaveBeenCalledTimes(1);
+    expect(stopTunnel).toHaveBeenCalledTimes(1);
+  });
+
+  it('opens tunnels with the ngrok token but keeps it out of spawned processes', async () => {
+    await runAsync();
+    expect(startNgrokTunnelAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ authtoken: 'token' })
+    );
+    const spawnedEnvs = [
+      ...jest.mocked(spawn).mock.calls.map(([, , options]) => options?.env),
+      ...jest.mocked(spawnDetached).mock.calls.map(([options]) => options.env),
+      ...jest.mocked(startDeviceSessionHostAsync).mock.calls.map(([, options]) => options.env),
+    ];
+    expect(spawnedEnvs.length).toBeGreaterThan(0);
+    for (const env of spawnedEnvs) {
+      expect(env).toEqual(expect.objectContaining({ DEVICE_RUN_SESSION_ID: 'session-id' }));
+      expect(env).not.toHaveProperty('NGROK_AUTHTOKEN');
+    }
+  });
+
+  it.each([undefined, true, false])('maps public_preview=%s to the host', async publicPreview => {
+    await runAsync(publicPreview);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ disableShare: publicPreview === false })
+    );
+  });
+
+  it('maps frame_ancestors to the host and defaults to none', async () => {
+    await runAsync(undefined, ['https://embed.example.test']);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ frameAncestors: ['https://embed.example.test'] })
+    );
+    jest.mocked(startDeviceSessionHostAsync).mockClear();
+    await runAsync();
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ frameAncestors: [] })
+    );
+  });
+
+  it('maps cors_origins to the host and defaults to none', async () => {
+    await runAsync(undefined, undefined, ['https://app.example.test']);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+    jest.mocked(startDeviceSessionHostAsync).mockClear();
+    await runAsync();
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ corsOrigins: [] })
+    );
+  });
+
+  it('stops automation while recording finalization or upload is pending', async () => {
+    let release!: () => void;
+    let stopped!: () => void;
+    const pendingFinish = new Promise<void>(resolve => {
+      release = resolve;
+    });
+    const toolStopped = new Promise<void>(resolve => {
+      stopped = resolve;
+    });
+    finishHost.mockReturnValueOnce(pendingFinish);
+    stopTool.mockImplementationOnce(async () => {
+      stopped();
+    });
+    let completed = false;
+    const running = runAsync().then(() => {
+      completed = true;
+    });
+    try {
+      await toolStopped;
+      expect(stopTunnel).toHaveBeenCalledTimes(1);
+      expect(finishHost).toHaveBeenCalledTimes(1);
+      expect(completed).toBe(false);
+    } finally {
+      release();
+      await running;
+    }
+  });
+
+  it('finalizes recording and stops automation while the tunnel close is pending', async () => {
+    let release!: () => void;
+    let finished!: () => void;
+    const pendingClose = new Promise<void>(resolve => {
+      release = resolve;
+    });
+    const hostFinished = new Promise<void>(resolve => {
+      finished = resolve;
+    });
+    const toolStopped = new Promise<void>(resolve => {
+      stopTool.mockImplementationOnce(async () => resolve());
+    });
+    stopTunnel.mockReturnValueOnce(pendingClose);
+    finishHost.mockImplementationOnce(async () => {
+      finished();
+    });
+    const running = runAsync();
+    try {
+      // Both settle while the tunnel close is still held open.
+      await Promise.all([hostFinished, toolStopped]);
+      expect(stopTunnel).toHaveBeenCalledTimes(1);
+    } finally {
+      release();
+      await running;
+    }
+  });
+
+  it('still stops the automation process when event collection stop rejects', async () => {
+    stopEvents.mockRejectedValueOnce(new Error('collector failed'));
+    // Agent Device wraps its collector stop in a catch-all helper; Appium does not.
+    const outcome = await runAsync().then(
+      () => 'resolved',
+      (err: Error) => err.message
+    );
+    expect(outcome).toBe(name === 'Appium' ? 'collector failed' : 'resolved');
+    expect(stopTool).toHaveBeenCalledTimes(1);
+    expect(stopTunnel).toHaveBeenCalledTimes(1);
+    expect(finishHost).toHaveBeenCalledTimes(1);
+  });
+
+  it('still stops automation when recording finalization rejects', async () => {
+    finishHost.mockRejectedValueOnce(new Error('recording cleanup failed'));
+    await expect(runAsync()).rejects.toThrow('recording cleanup failed');
+    expect(stopTool).toHaveBeenCalledTimes(1);
+    expect(stopTunnel).toHaveBeenCalledTimes(1);
+    expect(Sentry.capture).not.toHaveBeenCalled();
+  });
+
+  it.each(['preview', 'config', 'wait'])('finishes the host after %s fails', async phase => {
+    const error = new Error(`${phase} failed`);
+    // A teardown failure must not replace the error that ended the session.
+    finishHost.mockRejectedValueOnce(new Error('recording cleanup failed'));
+    if (phase === 'preview') {
+      openPreview.mockRejectedValueOnce(error);
+    } else if (phase === 'config') {
+      jest.mocked(uploadRemoteSessionConfigAsync).mockRejectedValueOnce(error);
+    } else {
+      jest.mocked(waitForDeviceRunSessionStoppedAsync).mockRejectedValueOnce(error);
+    }
+    await expect(runAsync()).rejects.toBe(error);
+    expect(finishHost).toHaveBeenCalledTimes(1);
+    // An agent-device preview failure aborts the daemon task, which then may not start its
+    // daemon or tunnel. Everything that started must be stopped.
+    const abortsDaemonTask = name === 'Agent Device' && phase === 'preview';
+    expect(stopTool).toHaveBeenCalledTimes(
+      abortsDaemonTask ? jest.mocked(spawnDetached).mock.calls.length : 1
+    );
+    expect(stopTunnel).toHaveBeenCalledTimes(
+      abortsDaemonTask ? jest.mocked(startNgrokTunnelAsync).mock.calls.length : 1
+    );
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: expect.objectContaining({ message: 'recording cleanup failed' }) },
+      'Could not stop the session host during remote session teardown.'
+    );
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      'Could not stop the session host after the remote session failed',
+      expect.objectContaining({ message: 'recording cleanup failed' }),
+      { level: 'warning' }
+    );
+  });
+});
+
+describe('Appium ffmpeg setup', () => {
+  async function runAppiumAsync(): Promise<void> {
+    const fn = createStartAppiumRemoteSessionBuildFunction({} as CustomBuildContext);
+    await fn.fn!(
+      {
+        logger,
+        global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+      } as unknown as BuildStepContext,
+      {
+        inputs: new Proxy({} as Record<string, { value: unknown }>, {
+          get: (target, id: string) => target[id] ?? { value: undefined },
+        }),
+        outputs: {},
+        env: {
+          DEVICE_RUN_SESSION_ID: 'session-id',
+          EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN: 'example.test',
+          NGROK_AUTHTOKEN: 'token',
+        },
+      } as never
+    );
+  }
+
+  function holdFfmpegInstall({ appiumError }: { appiumError?: Error } = {}) {
+    let finish!: (outcome: 'installed' | 'failed') => void;
+    const install = new Promise((resolve, reject) => {
+      finish = outcome =>
+        outcome === 'installed' ? resolve({}) : reject(new Error('apt-get failed'));
+    });
+    jest.mocked(spawn).mockImplementation(((command: string, args: string[]) => {
+      if (command === 'ffmpeg') {
+        return Promise.reject(new Error('ffmpeg missing'));
+      }
+      if (args.includes('install') && args.includes('ffmpeg')) {
+        return install;
+      }
+      return command === 'npm' && appiumError
+        ? Promise.reject(appiumError)
+        : Promise.resolve({ stdout: '{}' });
+    }) as never);
+    return finish;
+  }
+
+  it.each(['installed', 'failed'] as const)(
+    'starts Appium after the ffmpeg install settles (%s)',
+    async outcome => {
+      const finishFfmpegInstall = holdFfmpegInstall();
+
+      const run = runAppiumAsync();
+      await new Promise(resolve => setImmediate(resolve));
+      expect(spawnDetached).not.toHaveBeenCalled();
+
+      finishFfmpegInstall(outcome);
+      await run;
+      expect(spawnDetached).toHaveBeenCalledTimes(1);
+    }
+  );
+
+  it('waits for the ffmpeg install before failing on an Appium install error', async () => {
+    const appiumError = new Error('npm failed');
+    const finishFfmpegInstall = holdFfmpegInstall({ appiumError });
+
+    let settled = false;
+    const run = runAppiumAsync().finally(() => {
+      settled = true;
+    });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(settled).toBe(false);
+
+    finishFfmpegInstall('installed');
+    await expect(run).rejects.toBe(appiumError);
+  });
+});

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

@@ -11,6 +11,8 @@ 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';
 
 // contains a 'TestApp.app/TestApp' file with 'i am executable' content
@@ -29,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 }
       : {
@@ -61,7 +69,7 @@ function createSuccessfulResponse({
   url,
   headers,
 }: {
-  body: Buffer;
+  body: Buffer | Readable;
   url: string;
   headers?: Record<string, string>;
 }): Response {
@@ -71,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,
@@ -79,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`);
@@ -107,6 +156,11 @@ async function createFlatAppTarGzBufferAsync(): Promise<Buffer> {
   }
 }
 
+afterEach(() => {
+  jest.useRealTimers();
+  jest.restoreAllMocks();
+});
+
 describe('downloadBuild', () => {
   it('downloads from applicationArchiveUrl returned by GraphQL', async () => {
     const buildId = randomUUID();
@@ -255,6 +309,144 @@ describe('downloadBuild', () => {
     expect(await fs.promises.readFile(artifactPath, 'utf-8')).toBe('hello');
   });
 
+  it('passes the abort signal to the build lookup', async () => {
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+    jest
+      .mocked(fetch)
+      .mockResolvedValue(
+        createSuccessfulResponse({ body: APP_TAR_GZ_BUFFER, url: APPLICATION_ARCHIVE_URL })
+      );
+    const buildId = randomUUID();
+
+    await downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      buildId,
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['app'],
+      signal: new AbortController().signal,
+    });
+
+    expect(graphqlClient.query).toHaveBeenCalledWith(
+      expect.anything(),
+      { buildId },
+      { fetch: expect.any(Function) }
+    );
+    expect(jest.mocked(fetch)).toHaveBeenCalledWith(
+      APPLICATION_ARCHIVE_URL,
+      expect.objectContaining({ signal: expect.any(Object) })
+    );
+  });
+
+  it('stops a pending build lookup when aborted', async () => {
+    // The lookup request runs through the abort-aware fetch from graphqlAbortContext and
+    // hangs until its signal fires, like a stalled API call.
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = jest.fn(
+      (_input: unknown, init?: RequestInit) =>
+        new Promise<never>((_resolve, reject) => {
+          init!.signal!.addEventListener('abort', () => reject(init!.signal!.reason));
+        })
+    ) as typeof globalThis.fetch;
+    const graphqlClient = {
+      query: jest.fn((_query, _variables, context: { fetch: typeof globalThis.fetch }) => ({
+        toPromise: () =>
+          context.fetch('https://api.expo.dev/graphql', {}).then(
+            () => ({ data: undefined }),
+            (networkError: Error) => ({ error: new CombinedError({ networkError }) })
+          ),
+      })),
+    } as unknown as Client;
+    const controller = new AbortController();
+    const failure = new Error('daemon failed');
+
+    try {
+      const download = downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        buildId: randomUUID(),
+        graphqlClient,
+        robotAccessToken: null,
+        extensions: ['app'],
+        signal: controller.signal,
+      });
+      await new Promise(resolve => setImmediate(resolve));
+      expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+
+      controller.abort(failure);
+
+      await expect(download).rejects.toBe(failure);
+      expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+
+  it('lets a started extraction finish before it reports an abort', async () => {
+    jest
+      .mocked(fetch)
+      .mockResolvedValue(
+        createSuccessfulResponse({ body: APP_TAR_GZ_BUFFER, url: APPLICATION_ARCHIVE_URL })
+      );
+    const { decompressTarAsync } = jest.requireActual<typeof files>('../../../utils/files');
+    const controller = new AbortController();
+    const failure = new Error('daemon failed');
+    let extractionDirectory: string | undefined;
+    let extractionFinished = false;
+    const decompressSpy = jest.spyOn(files, 'decompressTarAsync').mockImplementation(async args => {
+      extractionDirectory = args.destinationDirectory;
+      // The startup fails while the archive is being extracted.
+      controller.abort(failure);
+      await decompressTarAsync(args);
+      extractionFinished = true;
+    });
+
+    try {
+      await expect(
+        downloadBuildAsync({
+          logger: createLogger({ name: 'test' }),
+          applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+          graphqlClient: createMockGraphqlClient({}),
+          robotAccessToken: null,
+          extensions: ['app'],
+          signal: controller.signal,
+        })
+      ).rejects.toBe(failure);
+
+      // The download settled only after the extraction wrote its last file.
+      expect(extractionFinished).toBe(true);
+      expect(
+        await fs.promises.readFile(
+          path.join(extractionDirectory!, 'TestApp.app', 'TestApp'),
+          'utf8'
+        )
+      ).toBe('i am executable\n');
+    } finally {
+      decompressSpy.mockRestore();
+    }
+  });
+
+  it('does not look up the build when already aborted', async () => {
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+    const failure = new Error('boot failed');
+
+    await expect(
+      downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        buildId: randomUUID(),
+        graphqlClient,
+        robotAccessToken: null,
+        extensions: ['app'],
+        signal: AbortSignal.abort(failure),
+      })
+    ).rejects.toBe(failure);
+    expect(graphqlClient.query).not.toHaveBeenCalled();
+    expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+  });
+
   it('rejects missing or ambiguous build sources', async () => {
     const graphqlClient = createMockGraphqlClient({
       applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
@@ -326,13 +518,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' }),
@@ -341,19 +533,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 },
       }),
     });
@@ -365,12 +619,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();
   });
 
@@ -395,10 +651,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,
@@ -424,6 +863,159 @@ describe('downloadBuild', () => {
 });
 
 describe('createDownloadBuildFunction', () => {
+  it('aborts a pending archive request when the step times out', async () => {
+    let requestAborted = false;
+    jest.mocked(fetch).mockImplementation(
+      async (_url, options) =>
+        await new Promise<Response>((_resolve, reject) => {
+          options?.signal?.addEventListener('abort', () => {
+            requestAborted = true;
+            reject(new Error('Archive request aborted'));
+          });
+        })
+    );
+    const graphqlClient = createMockGraphqlClient({});
+    const step = createDownloadBuildFunction({
+      graphqlClient,
+    } as any).createBuildStepFromFunctionCall(
+      createGlobalContextMock({ staticContextContent: { job: {} } }),
+      {
+        callInputs: { application_archive_url: APPLICATION_ARCHIVE_URL, extensions: ['ipa'] },
+        timeoutMs: 100,
+      }
+    );
+
+    await expect(step.executeAsync()).rejects.toThrow('timed out');
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(requestAborted).toBe(true);
+    expect(graphqlClient.query).not.toHaveBeenCalled();
+  });
+
+  describe('with a device run session token in the job env', () => {
+    const { Response: ActualResponse } = jest.requireActual(
+      'node-fetch'
+    ) as typeof import('node-fetch');
+    const workerApiUrl = 'https://api.expo.test/v2/device-run-session-worker/application';
+
+    function createSessionCtx(graphqlClient: Client): any {
+      return {
+        graphqlClient,
+        env: { EAS_DEVICE_RUN_SESSION_TOKEN: 'session-token' },
+        expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      };
+    }
+
+    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({
+          logger: createMockLogger(),
+          staticContextContent: { job: { secrets: { robotAccessToken: 'session-token' } } },
+        }),
+        { callInputs }
+      );
+    }
+
+    it('looks up build_id through the worker API and downloads without an Authorization header', async () => {
+      const buildId = randomUUID();
+      const graphqlClient = createMockGraphqlClient({});
+      jest.mocked(fetch).mockImplementation(async url => {
+        if (url === workerApiUrl) {
+          return createApplicationResponse(buildId);
+        }
+        return {
+          ok: false,
+          text: () => Promise.resolve('Internal Server Error'),
+          status: 500,
+        } as unknown as Response;
+      });
+
+      await expect(
+        createStep(createSessionCtx(graphqlClient), {
+          build_id: buildId,
+          extensions: ['app'],
+        }).executeAsync()
+      ).rejects.toThrow('Internal Server Error');
+
+      expect(jest.mocked(fetch)).toHaveBeenCalledWith(
+        workerApiUrl,
+        expect.objectContaining({
+          method: 'GET',
+          headers: { 'expo-device-run-session-token': 'session-token' },
+        })
+      );
+      expect(jest.mocked(fetch)).toHaveBeenCalledWith(
+        APPLICATION_ARCHIVE_URL,
+        expect.objectContaining({ headers: undefined })
+      );
+      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({
+        ok: false,
+        text: () => Promise.resolve('Internal Server Error'),
+        status: 500,
+      } as unknown as Response);
+
+      await expect(
+        createStep(createSessionCtx(graphqlClient), {
+          application_archive_url: APPLICATION_ARCHIVE_URL,
+          extensions: ['app'],
+        }).executeAsync()
+      ).rejects.toThrow('Internal Server Error');
+
+      expect(jest.mocked(fetch)).toHaveBeenCalledTimes(1);
+      expect(jest.mocked(fetch)).toHaveBeenCalledWith(
+        APPLICATION_ARCHIVE_URL,
+        expect.objectContaining({ headers: undefined })
+      );
+      expect(graphqlClient.query).not.toHaveBeenCalled();
+    });
+  });
+
   it('should download a build', async () => {
     const buildId = randomUUID();
     const graphqlClient = createMockGraphqlClient({

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

@@ -0,0 +1,192 @@
+import { Client, CombinedError } from '@urql/core';
+import fetch, { Response } from 'node-fetch';
+import fs from 'node:fs';
+import { Readable } from 'node:stream';
+
+import { CustomBuildContext } from '../../../customBuildContext';
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { createDownloadSubmissionArchiveFunction } from '../downloadSubmissionArchive';
+
+const submissionId = 'aabbccdd-1234-4321-abcd-123456789012';
+const url = 'https://storage.example/app.ipa?signature=secret';
+
+it('reports invalid submission ID and extensions together', async () => {
+  const mutation = jest.fn();
+  const step = createDownloadSubmissionArchiveFunction({
+    graphqlClient: { mutation } as unknown as Client,
+  } as CustomBuildContext).createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: { submission_id: 'invalid', extensions: [123] },
+  });
+
+  await expect(step.executeAsync()).rejects.toMatchObject({
+    issues: expect.arrayContaining([
+      expect.objectContaining({ path: ['submissionId'] }),
+      expect.objectContaining({ path: ['extensions', 0] }),
+    ]),
+  });
+  expect(mutation).not.toHaveBeenCalled();
+});
+
+it('requests a fresh URL on each execution, downloads without auth and does not log the URL', async () => {
+  const mutation = jest.fn(() => ({
+    toPromise: async () => ({
+      data: {
+        submission: { generateSubmissionArchiveDownloadUrl: url },
+      },
+    }),
+  }));
+  const logger = createMockLogger();
+  const fn = createDownloadSubmissionArchiveFunction({
+    graphqlClient: { mutation } as unknown as Client,
+  } as CustomBuildContext);
+  for (let i = 0; i < 2; i++) {
+    jest.mocked(fetch).mockResolvedValue({
+      ok: true,
+      url,
+      body: Readable.from(Buffer.from('IPA bytes')),
+      headers: { get: () => null },
+    } as unknown as Response);
+    const step = fn.createBuildStepFromFunctionCall(createGlobalContextMock({ logger }), {
+      callInputs: { submission_id: submissionId },
+    });
+    await step.executeAsync();
+    expect(await fs.promises.readFile(step.getOutputValueByName('artifact_path')!, 'utf8')).toBe(
+      'IPA bytes'
+    );
+  }
+  expect(mutation).toHaveBeenCalledTimes(2);
+  expect(fetch).toHaveBeenCalledWith(url, { headers: undefined, signal: undefined });
+  expect(JSON.stringify(jest.mocked(logger.info).mock.calls)).not.toContain(url);
+});
+
+it('preserves the API error as the cause without downloading', async () => {
+  const error = new CombinedError({ networkError: new Error('Connection reset') });
+  const mutation = jest.fn(() => ({
+    toPromise: async () => ({
+      error,
+    }),
+  }));
+  const step = createDownloadSubmissionArchiveFunction({
+    graphqlClient: { mutation } as unknown as Client,
+  } as CustomBuildContext).createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: { submission_id: submissionId },
+  });
+  await expect(step.executeAsync()).rejects.toMatchObject({
+    message: 'Could not request the submission archive. Try again later.',
+    cause: error,
+  });
+  expect(fetch).not.toHaveBeenCalled();
+  expect(mutation).toHaveBeenCalledTimes(4);
+});
+
+it('retries a temporary URL request failure and then downloads the archive', async () => {
+  const mutation = jest
+    .fn()
+    .mockReturnValueOnce({
+      toPromise: async () => ({
+        error: new CombinedError({ networkError: new Error('Connection reset') }),
+      }),
+    })
+    .mockReturnValue({
+      toPromise: async () => ({
+        data: { submission: { generateSubmissionArchiveDownloadUrl: url } },
+      }),
+    });
+  jest.mocked(fetch).mockResolvedValue({
+    ok: true,
+    url,
+    body: Readable.from(Buffer.from('IPA bytes')),
+    headers: { get: () => null },
+  } as unknown as Response);
+  const step = createDownloadSubmissionArchiveFunction({
+    graphqlClient: { mutation } as unknown as Client,
+  } as CustomBuildContext).createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: { submission_id: submissionId },
+  });
+
+  await step.executeAsync();
+
+  expect(mutation).toHaveBeenCalledTimes(2);
+  expect(await fs.promises.readFile(step.getOutputValueByName('artifact_path')!, 'utf8')).toBe(
+    'IPA bytes'
+  );
+});
+
+it('does not retry an access error', async () => {
+  const error = new CombinedError({ graphQLErrors: [{ message: 'Not authorized' }] });
+  const mutation = jest.fn(() => ({ toPromise: async () => ({ error }) }));
+  const step = createDownloadSubmissionArchiveFunction({
+    graphqlClient: { mutation } as unknown as Client,
+  } as CustomBuildContext).createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: { submission_id: submissionId },
+  });
+
+  await expect(step.executeAsync()).rejects.toMatchObject({ cause: error });
+  expect(mutation).toHaveBeenCalledTimes(1);
+  expect(fetch).not.toHaveBeenCalled();
+});
+
+it('does not send another URL request after the step times out during retry backoff', async () => {
+  const mutation = jest.fn(() => ({
+    toPromise: async () => ({
+      error: new CombinedError({ networkError: new Error('Connection reset') }),
+    }),
+  }));
+  const step = createDownloadSubmissionArchiveFunction({
+    graphqlClient: { mutation } as unknown as Client,
+  } as CustomBuildContext).createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: { submission_id: submissionId },
+    timeoutMs: 100,
+  });
+
+  await expect(step.executeAsync()).rejects.toThrow('timed out');
+  await new Promise(resolve => setTimeout(resolve, 1100));
+
+  expect(mutation).toHaveBeenCalledTimes(1);
+  expect(fetch).not.toHaveBeenCalled();
+});
+
+it('uses the requested extension for an archive without a filename extension', async () => {
+  const mutation = jest.fn(() => ({
+    toPromise: async () => ({
+      data: {
+        submission: { generateSubmissionArchiveDownloadUrl: 'https://storage.example/archive' },
+      },
+    }),
+  }));
+  jest.mocked(fetch).mockResolvedValue({
+    ok: true,
+    url: 'https://storage.example/archive',
+    body: Readable.from(Buffer.from('Android archive bytes')),
+    headers: { get: () => null },
+  } as unknown as Response);
+  const step = createDownloadSubmissionArchiveFunction({
+    graphqlClient: { mutation } as unknown as Client,
+  } as CustomBuildContext).createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: { submission_id: submissionId, extensions: ['aab'] },
+  });
+
+  await step.executeAsync();
+
+  const artifactPath = step.getOutputValueByName('artifact_path')!;
+  expect(artifactPath).toMatch(/\.aab$/);
+  expect(await fs.promises.readFile(artifactPath, 'utf8')).toBe('Android archive bytes');
+});
+
+it('propagates the original download error', async () => {
+  const error = new Error('Download failed');
+  const mutation = jest.fn(() => ({
+    toPromise: async () => ({
+      data: { submission: { generateSubmissionArchiveDownloadUrl: url } },
+    }),
+  }));
+  jest.mocked(fetch).mockRejectedValue(error);
+  const step = createDownloadSubmissionArchiveFunction({
+    graphqlClient: { mutation } as unknown as Client,
+  } as CustomBuildContext).createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: { submission_id: submissionId },
+  });
+
+  await expect(step.executeAsync()).rejects.toBe(error);
+});

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

@@ -463,114 +463,127 @@ describe('createInstallMaestroBuildFunction', () => {
     }
   });
 
-  it('installs the prebuilt WDA cache for each available iOS runtime', async () => {
-    const homeDirectory = await fs.promises.mkdtemp(
-      path.join(os.tmpdir(), 'install-maestro-test-')
-    );
-    mockedSpawn.mockImplementation((async (command: string, args: string[]) => {
-      if (command === 'maestro-runner') {
-        return { stdout: 'maestro-runner 1.2.3\n' };
-      }
-      if (command === 'xcrun') {
-        return {
-          stdout: JSON.stringify({
-            runtimes: [
-              {
-                identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-18-3',
-                isAvailable: true,
-                version: '18.3.1',
-              },
-              {
-                identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-26-0',
-                isAvailable: true,
-                version: '26.0',
-              },
-              {
-                identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-17-5',
-                isAvailable: false,
-                version: '17.5',
-              },
-            ],
-          }),
-        };
-      }
-      if (command === 'xcodebuild') {
-        return { stdout: 'Xcode 26.0\nBuild version 17A324\n' };
-      }
-      if (command === 'tar') {
-        const maestroRunnerHome = args[args.indexOf('-C') + 1];
-        const productsDirectory = path.join(
-          maestroRunnerHome,
-          'cache',
-          'wda-builds',
-          'generic',
-          'DerivedData',
-          'Build',
-          'Products'
-        );
-        await fs.promises.mkdir(productsDirectory, { recursive: true });
-        await fs.promises.writeFile(
-          path.join(productsDirectory, 'WebDriverAgentRunner.xctestrun'),
-          'cached'
-        );
-      }
-      return { stdout: '' };
-    }) as any);
-
-    try {
-      await writeInstalledWdaVersion(homeDirectory, '11.1.3');
-      const installMaestro = createInstallMaestroBuildFunction();
-      const globalCtx = createGlobalContextMock({
-        runtimePlatform: BuildRuntimePlatform.DARWIN,
-      });
-      globalCtx.updateEnv({
-        EAS_BUILD_RUNNER: 'eas-build',
-        EAS_BUILD_COCOAPODS_CACHE_URL: 'https://cache.example.com',
-        HOME: homeDirectory,
-      });
-      const step = installMaestro.createBuildStepFromFunctionCall(globalCtx, {
-        callInputs: { backend: 'maestro-runner' },
-      });
-
-      await step.executeAsync();
-
-      expect(mockedDownloadFile).toHaveBeenCalledWith(
-        'https://cache.example.com/storage.googleapis.com/turtle-v2/maestro-runner-wda-cache/xcode-26.0-wda-11.1.3.tar.gz',
-        expect.stringMatching(/install_maestro_runner_wda_cache.*\/wda-cache\.tar\.gz$/),
-        { retry: 3, timeout: 20_000 }
+  it.each(['1.1.27', '1.1.28', '1.2.3'])(
+    'prepares the WDA cache only for legacy Runner versions (%s)',
+    async version => {
+      const homeDirectory = await fs.promises.mkdtemp(
+        path.join(os.tmpdir(), 'install-maestro-test-')
       );
-      for (const runtimeVersion of ['18.3', '26.0']) {
+      mockedSpawn.mockImplementation((async (command: string, args: string[]) => {
+        if (command === 'maestro-runner') {
+          return { stdout: `maestro-runner ${version}\n` };
+        }
+        if (command === 'xcrun') {
+          return {
+            stdout: JSON.stringify({
+              runtimes: [
+                {
+                  identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-18-3',
+                  isAvailable: true,
+                  version: '18.3.1',
+                },
+                {
+                  identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-26-0',
+                  isAvailable: true,
+                  version: '26.0',
+                },
+                {
+                  identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-17-5',
+                  isAvailable: false,
+                  version: '17.5',
+                },
+              ],
+            }),
+          };
+        }
+        if (command === 'xcodebuild') {
+          return { stdout: 'Xcode 26.0\nBuild version 17A324\n' };
+        }
+        if (command === 'tar') {
+          const maestroRunnerHome = args[args.indexOf('-C') + 1];
+          const productsDirectory = path.join(
+            maestroRunnerHome,
+            'cache',
+            'wda-builds',
+            'generic',
+            'DerivedData',
+            'Build',
+            'Products'
+          );
+          await fs.promises.mkdir(productsDirectory, { recursive: true });
+          await fs.promises.writeFile(
+            path.join(productsDirectory, 'WebDriverAgentRunner.xctestrun'),
+            'cached'
+          );
+        }
+        return { stdout: '' };
+      }) as any);
+
+      try {
+        await writeInstalledWdaVersion(homeDirectory, '11.1.3');
+        const installMaestro = createInstallMaestroBuildFunction();
+        const globalCtx = createGlobalContextMock({
+          runtimePlatform: BuildRuntimePlatform.DARWIN,
+        });
+        globalCtx.updateEnv({
+          EAS_BUILD_RUNNER: 'eas-build',
+          EAS_BUILD_COCOAPODS_CACHE_URL: 'https://cache.example.com',
+          HOME: homeDirectory,
+        });
+        const step = installMaestro.createBuildStepFromFunctionCall(globalCtx, {
+          callInputs: { backend: 'maestro-runner' },
+        });
+
+        await step.executeAsync();
+
+        expect(step.getOutputValueByName('maestro_version')).toBe(version);
+        if (version !== '1.1.27') {
+          expect(mockedDownloadFile).not.toHaveBeenCalled();
+          expect(mockedSpawn.mock.calls.map(([command]) => command)).not.toContain('xcrun');
+          await expect(
+            fs.promises.access(path.join(homeDirectory, '.maestro-runner', 'cache'))
+          ).rejects.toThrow();
+          return;
+        }
+
+        expect(mockedDownloadFile).toHaveBeenCalledWith(
+          'https://cache.example.com/storage.googleapis.com/turtle-v2/maestro-runner-wda-cache/xcode-26.0-wda-11.1.3.tar.gz',
+          expect.stringMatching(/install_maestro_runner_wda_cache.*\/wda-cache\.tar\.gz$/),
+          { retry: 3, timeout: 20_000 }
+        );
+        for (const runtimeVersion of ['18.3', '26.0']) {
+          await expect(
+            fs.promises.readFile(
+              path.join(
+                homeDirectory,
+                '.maestro-runner',
+                'cache',
+                'wda-builds',
+                `sim-ios${runtimeVersion}-iphone`,
+                'DerivedData',
+                'Build',
+                'Products',
+                'WebDriverAgentRunner.xctestrun'
+              ),
+              'utf8'
+            )
+          ).resolves.toBe('cached');
+        }
         await expect(
-          fs.promises.readFile(
-            path.join(
-              homeDirectory,
-              '.maestro-runner',
-              'cache',
-              'wda-builds',
-              `sim-ios${runtimeVersion}-iphone`,
-              'DerivedData',
-              'Build',
-              'Products',
-              'WebDriverAgentRunner.xctestrun'
-            ),
-            'utf8'
+          fs.promises.access(
+            path.join(homeDirectory, '.maestro-runner', 'cache', 'wda-builds', 'sim-ios17.5-iphone')
           )
-        ).resolves.toBe('cached');
+        ).rejects.toThrow();
+      } finally {
+        await fs.promises.rm(homeDirectory, { force: true, recursive: true });
       }
-      await expect(
-        fs.promises.access(
-          path.join(homeDirectory, '.maestro-runner', 'cache', 'wda-builds', 'sim-ios17.5-iphone')
-        )
-      ).rejects.toThrow();
-    } finally {
-      await fs.promises.rm(homeDirectory, { force: true, recursive: true });
     }
-  });
+  );
 
   it('does not download the WDA cache when the installed WDA version is unknown', async () => {
     mockedSpawn.mockImplementation((async (command: string) => ({
       stdout:
-        command === 'xcodebuild' ? 'Xcode 26.5\nBuild version 17F90\n' : 'maestro-runner 1.2.3\n',
+        command === 'xcodebuild' ? 'Xcode 26.5\nBuild version 17F90\n' : 'maestro-runner 1.1.27\n',
     })) as any);
     const installMaestro = createInstallMaestroBuildFunction();
     const globalCtx = createGlobalContextMock({
@@ -593,7 +606,7 @@ describe('createInstallMaestroBuildFunction', () => {
     mockedSpawn.mockImplementation((async (command: string) => {
       switch (command) {
         case 'maestro-runner':
-          return { stdout: 'maestro-runner 1.2.3\n' };
+          return { stdout: 'maestro-runner 1.1.27\n' };
         case 'xcodebuild':
           return { stdout: 'Xcode 26.5\nBuild version 17F90\n' };
         case 'xcrun':
@@ -633,7 +646,7 @@ describe('createInstallMaestroBuildFunction', () => {
       });
 
       await expect(step.executeAsync()).resolves.toBeUndefined();
-      expect(step.getOutputValueByName('maestro_version')).toBe('1.2.3');
+      expect(step.getOutputValueByName('maestro_version')).toBe('1.1.27');
       expect(mockedDownloadFile.mock.calls.map(([url]) => url)).toEqual([
         'https://cache.example.com/storage.googleapis.com/turtle-v2/maestro-runner-wda-cache/xcode-26.5-wda-11.1.3.tar.gz',
         'https://storage.googleapis.com/turtle-v2/maestro-runner-wda-cache/xcode-26.5-wda-11.1.3.tar.gz',

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

@@ -0,0 +1,151 @@
+import { BuildRuntimePlatform, BuildStep } from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+import { fs, vol } from 'memfs';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { createInstallMitmproxyBuildFunction } from '../installMitmproxy';
+
+jest.mock('@expo/turtle-spawn', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+const mockedSpawn = jest.mocked(spawn);
+
+// An x86 Homebrew prefix, to check that the app is found from PATH and not from process.arch.
+const APP = '/usr/local/Caskroom/mitmproxy/12.2.3/mitmproxy.app';
+const LINK = '/usr/local/bin/mitmdump';
+
+function installCask(): void {
+  vol.fromJSON({ [`${APP}/Contents/MacOS/mitmdump`]: '', '/usr/local/bin': null });
+  fs.symlinkSync(`${APP}/Contents/MacOS/mitmdump`, LINK);
+}
+
+/**
+ * `which` finds mitmdump once the cask is installed, `brew` installs it, `xattr -p` reports
+ * quarantine while `stuck` is set, and each `mitmdump --version` takes the next result.
+ */
+function mockCommands({
+  installed = false,
+  stuck = false,
+  runs = [],
+}: {
+  installed?: boolean;
+  stuck?: boolean;
+  runs?: boolean[];
+}): void {
+  if (installed) {
+    installCask();
+  }
+  mockedSpawn.mockImplementation((async (command: string, args: string[]) => {
+    if (command === 'which' && !installed) {
+      throw new Error('not found');
+    }
+    if (command === 'which') {
+      return { stdout: `${LINK}\n` };
+    }
+    if (command === 'brew' && !installed) {
+      installed = true;
+      installCask();
+    }
+    if (command === 'xattr' && args[0] === '-p' && !stuck) {
+      throw new Error('No such xattr: com.apple.quarantine');
+    }
+    if (command === 'mitmdump' && !runs.shift()) {
+      throw new Error('not found');
+    }
+    return { stdout: '' };
+  }) as never);
+}
+
+function spawnedCommands(): string[] {
+  return mockedSpawn.mock.calls.map(([command, args]) =>
+    command === 'xattr' ? `xattr ${args?.[0]}` : command
+  );
+}
+
+describe('createInstallMitmproxyBuildFunction', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  function createStep(env: Record<string, string>): BuildStep {
+    const globalCtx = createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.DARWIN });
+    globalCtx.updateEnv(env);
+    return createInstallMitmproxyBuildFunction().createBuildStepFromFunctionCall(globalCtx, {
+      callInputs: {},
+    });
+  }
+
+  it('takes the app behind mitmdump on PATH out of quarantine before running it', async () => {
+    mockCommands({ installed: true, runs: [true] });
+
+    await createStep({ EAS_BUILD_RUNNER: 'eas-build' }).executeAsync();
+
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'xattr',
+      ['-dr', 'com.apple.quarantine', APP],
+      expect.anything()
+    );
+    expect(spawnedCommands()).toEqual(['which', 'xattr -dr', 'xattr -p', 'mitmdump']);
+  });
+
+  it('kills a mitmdump --version that does not return', async () => {
+    mockCommands({ installed: true, runs: [true] });
+
+    await createStep({ EAS_BUILD_RUNNER: 'eas-build' }).executeAsync();
+
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'mitmdump',
+      ['--version'],
+      expect.objectContaining({ stdio: 'ignore', timeout: 60_000, killSignal: 'SIGKILL' })
+    );
+  });
+
+  it('does not run a mitmdump that stays quarantined', async () => {
+    mockCommands({ installed: true, stuck: true });
+
+    await expect(
+      createStep({ EAS_BUILD_RUNNER: 'eas-build' }).executeAsync()
+    ).resolves.toBeUndefined();
+
+    expect(spawnedCommands()).not.toContain('mitmdump');
+  });
+
+  it('does not change quarantine outside EAS Build VMs', async () => {
+    mockCommands({ installed: true, stuck: true, runs: [true] });
+
+    await createStep({}).executeAsync();
+
+    expect(spawnedCommands()).toEqual(['mitmdump']);
+  });
+
+  it('installs the cask with Homebrew and takes it out of quarantine', async () => {
+    mockCommands({ runs: [false, true] });
+
+    await createStep({ EAS_BUILD_RUNNER: 'eas-build' }).executeAsync();
+
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'brew',
+      ['install', '--cask', 'mitmproxy'],
+      expect.objectContaining({ env: expect.objectContaining({ HOMEBREW_NO_AUTO_UPDATE: '1' }) })
+    );
+    expect(spawnedCommands()).toEqual([
+      'which',
+      'mitmdump',
+      'brew',
+      'which',
+      'xattr -dr',
+      'xattr -p',
+      'mitmdump',
+    ]);
+  });
+
+  it('does not fail the job when mitmdump is still not runnable', async () => {
+    mockCommands({ runs: [false, false] });
+
+    await expect(
+      createStep({ EAS_BUILD_RUNNER: 'eas-build' }).executeAsync()
+    ).resolves.toBeUndefined();
+  });
+});

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';
@@ -179,17 +180,7 @@ describe(launchApplicationAsync, () => {
     expect(mockedSpawn).toHaveBeenNthCalledWith(
       2,
       'adb',
-      [
-        'shell',
-        'am',
-        'start',
-        '-a',
-        'android.intent.action.VIEW',
-        '-d',
-        'exp://example.test',
-        '-n',
-        'host.exp.exponent/host.exp.exponent.MainActivity',
-      ],
+      ['shell', 'am', 'start', '-a', 'android.intent.action.VIEW', '-d', 'exp://example.test'],
       { env: {}, logger }
     );
     expect(logger.info).toHaveBeenNthCalledWith(
@@ -211,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(
@@ -240,16 +488,36 @@ describe(launchApplicationAsync, () => {
       ],
       expect.any(Object)
     );
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'adb',
+      ['shell', 'am', 'start', '-a', 'android.intent.action.VIEW', '-d', 'exp://example.test'],
+      expect.any(Object)
+    );
+  });
+
+  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',
-        '-a',
-        'android.intent.action.VIEW',
-        '-d',
-        'exp://example.test',
+        '--es',
+        'probe',
+        "'hello world'",
         '-n',
         'com.example.app/com.example.app.MainActivity',
       ],

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

@@ -271,20 +271,124 @@ describe('createMaestroTestsBuildFunction', () => {
     expect(mockedSpawn.mock.calls[0][1]).toContain('--parallel=2');
   });
 
-  it('rejects a non-junit output_format with maestro-runner', async () => {
+  it.each(['html', 'allure'])(
+    'accepts %s output_format with maestro-runner and keeps JUnit',
+    async format => {
+      mockedSpawn.mockResolvedValue(SPAWN_SUCCESS);
+      const copyFileSpy = jest.spyOn(fs, 'copyFile').mockResolvedValue();
+      const step = createStep({
+        flow_path: ['flows/a.yaml'],
+        platform: 'android',
+        backend: 'maestro-runner',
+        output_format: format,
+      });
+
+      await step.executeAsync();
+
+      expect(mockedSpawn.mock.calls[0][1]).toEqual(
+        expect.arrayContaining([
+          '--output=/home/expo/.maestro/tests/android-maestro-runner-attempt-0',
+        ])
+      );
+      expect(copyFileSpy).toHaveBeenCalledWith(
+        '/home/expo/.maestro/tests/android-maestro-runner-attempt-0/junit-report.xml',
+        '/home/expo/.maestro/tests/junit-reports/android-maestro-junit-attempt-0.xml'
+      );
+      expect(parser.mergeJUnitReports).not.toHaveBeenCalled();
+      expect(step.getOutputValueByName('final_report_path')).toBe(
+        format === 'html'
+          ? '/home/expo/.maestro/tests/android-maestro-runner-attempt-0/report.html'
+          : '/home/expo/.maestro/tests/android-maestro-runner-attempt-0/allure-results'
+      );
+      expect(mockedRunnerHarvest).not.toHaveBeenCalled();
+      expect(mockUploadArtifact).toHaveBeenCalledTimes(1);
+      expect(mockUploadArtifact).toHaveBeenCalledWith(
+        expect.objectContaining({
+          artifact: expect.objectContaining({
+            type: GenericArtifactType.OTHER,
+            name:
+              format === 'html' ? 'Maestro Runner HTML Report' : 'Maestro Runner Allure Results',
+            paths: [
+              format === 'html'
+                ? '/home/expo/.maestro/tests/android-maestro-runner-attempt-0'
+                : '/home/expo/.maestro/tests/android-maestro-runner-attempt-0/allure-results',
+            ],
+          }),
+        })
+      );
+    }
+  );
+
+  it('does not expose a selected runner report before an attempt starts', async () => {
     const step = createStep({
-      flow_path: ['flows/a.yaml'],
+      flow_path: [],
       platform: 'android',
       backend: 'maestro-runner',
       output_format: 'html',
     });
 
+    await expect(step.executeAsync()).rejects.toThrow(UserError);
+    expect(step.getOutputValueByName('final_report_path')).toBeUndefined();
+    expect(step.getOutputValueByName('junit_report_directory')).toBe(
+      '/home/expo/.maestro/tests/junit-reports'
+    );
+  });
+
+  it('rejects an unknown output_format with maestro-runner', async () => {
+    const step = createStep({
+      flow_path: ['flows/a.yaml'],
+      platform: 'android',
+      backend: 'maestro-runner',
+      output_format: 'csv',
+    });
+
     await expect(step.executeAsync()).rejects.toThrow(
-      'maestro-runner only supports the "junit" output_format'
+      'maestro-runner supports "junit", "html", and "allure" output_format values'
     );
     expect(mockedSpawn).not.toHaveBeenCalled();
   });
 
+  it('uploads the last runner HTML report even when the test fails', async () => {
+    mockedSpawn.mockRejectedValue(rejectExit1());
+    jest.spyOn(fs, 'copyFile').mockResolvedValue();
+    const step = createStep({
+      flow_path: ['flows/a.yaml'],
+      platform: 'android',
+      backend: 'maestro-runner',
+      output_format: 'html',
+      retries: 1,
+      retry_failed_only: false,
+    });
+
+    await expect(step.executeAsync()).rejects.toThrow(UserError);
+
+    expect(mockUploadArtifact).toHaveBeenCalledWith(
+      expect.objectContaining({
+        artifact: expect.objectContaining({
+          name: 'Maestro Runner HTML Report',
+          paths: ['/home/expo/.maestro/tests/android-maestro-runner-attempt-1'],
+        }),
+      })
+    );
+    expect(step.getOutputValueByName('final_report_path')).toBe(
+      '/home/expo/.maestro/tests/android-maestro-runner-attempt-1/report.html'
+    );
+  });
+
+  it('does not fail a passing test when the runner report upload fails', async () => {
+    mockedSpawn.mockResolvedValue(SPAWN_SUCCESS);
+    jest.spyOn(fs, 'copyFile').mockResolvedValue();
+    mockUploadArtifact.mockRejectedValue(new Error('upload failed'));
+    const step = createStep({
+      flow_path: ['flows/a.yaml'],
+      platform: 'android',
+      backend: 'maestro-runner',
+      output_format: 'allure',
+    });
+
+    await expect(step.executeAsync()).resolves.toBeUndefined();
+  });
+
   it('logs that maestro-runner does not support direct DADB', async () => {
     mockedSpawn.mockResolvedValue(SPAWN_SUCCESS);
     jest.spyOn(fs, 'copyFile').mockResolvedValue();
@@ -966,7 +1070,7 @@ describe('createMaestroTestsBuildFunction', () => {
     await expect(step.executeAsync()).rejects.toThrow(UserError);
   });
 
-  it('uses $HOME/.maestro/tests output path for non-junit formats (e.g. html)', async () => {
+  it('uses $HOME/.maestro/tests output path and uploads the Maestro CLI HTML report', async () => {
     mockedSpawn.mockResolvedValue(SPAWN_SUCCESS);
 
     const step = createStep({
@@ -977,11 +1081,119 @@ describe('createMaestroTestsBuildFunction', () => {
     await step.executeAsync();
 
     const args = mockedSpawn.mock.calls[0][1] as string[];
-    // Non-JUnit uses a fixed path inside $HOME/.maestro/tests so the
-    // whole-directory upload picks it up.
+    // Non-JUnit uses a fixed path inside $HOME/.maestro/tests.
     const outputArg = args.find(a => a.startsWith('--output='));
     expect(outputArg).toMatch(/\.maestro\/tests\/android-maestro-html\.html$/);
     expect(outputArg).not.toMatch(/junit-reports/);
+    expect(step.getOutputValueByName('final_report_path')).toBe(
+      '/home/expo/.maestro/tests/android-maestro-html.html'
+    );
+    expect(mockUploadArtifact).toHaveBeenCalledWith(
+      expect.objectContaining({
+        artifact: expect.objectContaining({
+          type: GenericArtifactType.OTHER,
+          name: 'Maestro HTML Report',
+          paths: ['/home/expo/.maestro/tests/android-maestro-html.html'],
+        }),
+      })
+    );
+  });
+
+  it('uploads the Maestro CLI HTML report even when tests fail', async () => {
+    mockedSpawn.mockRejectedValue(rejectExit1());
+    const step = createStep({
+      flow_path: ['flows/a.yaml'],
+      output_format: 'html',
+      platform: 'android',
+    });
+
+    await expect(step.executeAsync()).rejects.toThrow(UserError);
+
+    expect(mockUploadArtifact).toHaveBeenCalledWith(
+      expect.objectContaining({
+        artifact: expect.objectContaining({
+          name: 'Maestro HTML Report',
+          paths: ['/home/expo/.maestro/tests/android-maestro-html.html'],
+        }),
+      })
+    );
+  });
+
+  it('warns that Maestro CLI does not support Allure reports', async () => {
+    mockedSpawn.mockRejectedValue(rejectExit1());
+    const logger = createMockLogger();
+    jest.mocked(logger.child).mockReturnValue(logger);
+    const step = createStep(
+      {
+        flow_path: ['flows/a.yaml'],
+        output_format: 'allure',
+        platform: 'android',
+      },
+      { logger }
+    );
+
+    await expect(step.executeAsync()).rejects.toThrow(UserError);
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      'Maestro CLI does not support Allure reports; no Allure artifact was uploaded.'
+    );
+    expect(mockUploadArtifact).not.toHaveBeenCalled();
+  });
+
+  it('clears the Maestro CLI HTML report before every retry attempt', async () => {
+    const removeSpy = jest.spyOn(fs, 'rm').mockResolvedValue();
+    mockedSpawn.mockRejectedValue(rejectExit1());
+    const step = createStep({
+      flow_path: ['flows/a.yaml'],
+      output_format: 'html',
+      platform: 'android',
+      retries: 1,
+    });
+
+    await expect(step.executeAsync()).rejects.toThrow(UserError);
+
+    expect(
+      removeSpy.mock.calls.filter(
+        ([target]) => target === '/home/expo/.maestro/tests/android-maestro-html.html'
+      )
+    ).toHaveLength(2);
+    expect(removeSpy).toHaveBeenNthCalledWith(
+      1,
+      '/home/expo/.maestro/tests/android-maestro-html.html',
+      {
+        force: true,
+      }
+    );
+    expect(removeSpy).toHaveBeenNthCalledWith(
+      2,
+      '/home/expo/.maestro/tests/android-maestro-html.html',
+      {
+        force: true,
+      }
+    );
+    expect(removeSpy.mock.invocationCallOrder[0]).toBeLessThan(
+      mockedSpawn.mock.invocationCallOrder[0]
+    );
+    expect(removeSpy.mock.invocationCallOrder[1]).toBeLessThan(
+      mockedSpawn.mock.invocationCallOrder[1]
+    );
+  });
+
+  it('does not run Maestro CLI or upload old HTML if the report cannot be cleared', async () => {
+    jest.spyOn(fs, 'rm').mockImplementation(async target => {
+      if (target === '/home/expo/.maestro/tests/android-maestro-html.html') {
+        throw new Error('permission denied');
+      }
+    });
+    const step = createStep({
+      flow_path: ['flows/a.yaml'],
+      output_format: 'html',
+      platform: 'android',
+    });
+
+    await expect(step.executeAsync()).rejects.toThrow(SystemError);
+    expect(mockedSpawn).not.toHaveBeenCalled();
+    expect(mockUploadArtifact).not.toHaveBeenCalled();
   });
 
   it('uses lowercase extension for non-junit formats regardless of input casing', async () => {
@@ -1216,28 +1428,31 @@ describe('createMaestroTestsBuildFunction', () => {
     );
   });
 
-  it('discovers maestro-runner flow results from the attempt report directory', async () => {
-    mockedSpawn.mockResolvedValue(SPAWN_SUCCESS);
-    const shot = makeShot(0);
-    jest.spyOn(fs, 'copyFile').mockResolvedValue();
-    mockedRunnerHarvest.mockResolvedValue([shot]);
-    const parseFlowResultsSpy = jest.spyOn(parser, 'parseMaestroRunnerReport').mockResolvedValue({
-      flows: [{ name: 'Login', sourceFile: 'a.yaml', status: 'failed' }],
-    });
+  it.each(['junit', undefined])(
+    'uploads runner screenshots with output_format=%s',
+    async format => {
+      mockedSpawn.mockResolvedValue(SPAWN_SUCCESS);
+      const shot = makeShot(0);
+      jest.spyOn(fs, 'copyFile').mockResolvedValue();
+      mockedRunnerHarvest.mockResolvedValue([shot]);
+      const parseFlowResultsSpy = jest.spyOn(parser, 'parseMaestroRunnerReport').mockResolvedValue({
+        flows: [{ name: 'Login', sourceFile: 'a.yaml', status: 'failed' }],
+      });
 
-    const step = createStep({
-      flow_path: ['a.yaml'],
-      platform: 'ios',
-      output_format: 'junit',
-      backend: 'maestro-runner',
-    });
-    await step.executeAsync();
+      const step = createStep({
+        flow_path: ['a.yaml'],
+        platform: 'ios',
+        ...(format === undefined ? {} : { output_format: format }),
+        backend: 'maestro-runner',
+      });
+      await step.executeAsync();
 
-    expect(parseFlowResultsSpy).toHaveBeenCalledWith(
-      '/home/expo/.maestro/tests/ios-maestro-runner-attempt-0'
-    );
-    expect(mockUploadArtifact).toHaveBeenCalledTimes(1);
-  });
+      expect(parseFlowResultsSpy).toHaveBeenCalledWith(
+        '/home/expo/.maestro/tests/ios-maestro-runner-attempt-0'
+      );
+      expect(mockUploadArtifact).toHaveBeenCalledTimes(1);
+    }
+  );
 
   it('uploads screenshots even when all attempts fail, before throwing ERR_MAESTRO_TESTS_FAILED', async () => {
     mockedSpawn.mockRejectedValue(rejectExit1());
@@ -1301,14 +1516,15 @@ describe('createMaestroTestsBuildFunction', () => {
     expect(mockUploadArtifact).toHaveBeenCalledTimes(30);
   });
 
-  it('does not harvest or upload screenshots when output_format is not junit', async () => {
+  it('does not harvest or upload screenshots for Maestro CLI HTML', async () => {
     mockedSpawn.mockResolvedValue(SPAWN_SUCCESS);
 
     const step = createStep({ flow_path: ['a.yaml'], platform: 'android', output_format: 'html' });
     await step.executeAsync();
 
     expect(mockedHarvest).not.toHaveBeenCalled();
-    expect(mockUploadArtifact).not.toHaveBeenCalled();
+    expect(mockUploadArtifact).toHaveBeenCalledTimes(1);
+    expect(mockUploadArtifact.mock.calls[0][0].artifact.name).toBe('Maestro HTML Report');
   });
 
   it('uploads only the final attempt for a pure-failure flow, but every attempt for a flaky flow', async () => {

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

@@ -7,6 +7,7 @@ import { type CustomBuildContext } from '../../../customBuildContext';
 import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
 import { isProcessDescendantOfAsync } from '../../../utils/processes';
 import { turtleFetch } from '../../../utils/turtleFetch';
+import { startDeviceSessionHostAsync } from '../../utils/deviceSessionHost';
 import {
   monitorLocalEgressAsync,
   readLocalEgressHandoffAsync,
@@ -14,11 +15,16 @@ import {
   stopLocalEgressResourcesAsync,
 } from '../../utils/localEgress';
 import {
-  startDeviceWebPreviewWithTunnelAsync,
+  reportLocalEgressGuardCoverageAsync,
+  resolveLocalEgressServeSimBootEnvironmentAsync,
+  startLocalEgressGuardRelayAsync,
+  verifyLocalEgressGuardAsync,
+} from '../../utils/localEgressGuard';
+import {
   uploadRemoteSessionConfigAsync,
   waitForDeviceRunSessionStoppedAsync,
 } from '../../utils/remoteDeviceRunSession';
-import { createStartAgentDeviceRemoteSessionBuildFunction } from '../startAgentDeviceRemoteSession';
+import { createStartAgentDeviceSessionBuildFunction } from '../startAgentDeviceSession';
 import { createStartAppiumRemoteSessionBuildFunction } from '../startAppiumRemoteSession';
 import { createStartArgentRemoteSessionBuildFunction } from '../startArgentRemoteSession';
 import { createStartWebPreviewRemoteSessionBuildFunction } from '../startWebPreviewRemoteSession';
@@ -27,7 +33,14 @@ jest.mock('@expo/turtle-spawn');
 jest.mock('../../../utils/IosSimulatorUtils');
 jest.mock('../../../utils/processes');
 jest.mock('../../../utils/turtleFetch');
+jest.mock('../../utils/deviceSessionHost');
 jest.mock('../../utils/agentDeviceArtifacts');
+jest.mock('../startIosSimulator', () => ({
+  ...jest.requireActual('../startIosSimulator'),
+  bootIosSimulatorAsync: jest
+    .fn()
+    .mockResolvedValue({ deviceIdentifier: 'sim', udid: 'sim', displayName: 'iPhone' }),
+}));
 jest.mock('../../utils/argentArtifacts');
 jest.mock('../../utils/agentDeviceEvents', () => ({
   startAgentDeviceEventCollectionAsync: async () => ({ stopAsync: jest.fn() }),
@@ -44,6 +57,13 @@ jest.mock('../../utils/localEgress', () => ({
   readLocalEgressHandoffAsync: jest.fn(),
   monitorLocalEgressAsync: jest.fn(),
 }));
+jest.mock('../../utils/localEgressGuard', () => ({
+  ...jest.requireActual('../../utils/localEgressGuard'),
+  resolveLocalEgressServeSimBootEnvironmentAsync: jest.fn(),
+  startLocalEgressGuardRelayAsync: jest.fn(),
+  reportLocalEgressGuardCoverageAsync: jest.fn(),
+  verifyLocalEgressGuardAsync: jest.fn(),
+}));
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
   getDeviceRunSessionIdOrThrow: () => 'session-id',
@@ -58,12 +78,15 @@ jest.mock('../../utils/remoteDeviceRunSession', () => ({
     subdomainId: 'controller-id',
     stopAsync: jest.fn(),
   }),
-  startDeviceWebPreviewWithTunnelAsync: jest.fn(),
   uploadRemoteSessionConfigAsync: jest.fn(),
   waitForDeviceRunSessionStoppedAsync: jest.fn(),
 }));
 
-const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
+const logger = {
+  info: jest.fn(),
+  warn: jest.fn(),
+  child: jest.fn().mockReturnThis(),
+} as unknown as bunyan;
 const ctx = {} as CustomBuildContext;
 const env = { DEVICE_RUN_SESSION_ID: 'session-id' };
 const handoff = { url: 'https://egress.test', token: 'secret', fingerprint: 'key=', port: 8899 };
@@ -74,7 +97,7 @@ const fields = {
   egressPort: handoff.port,
 };
 const controllers = [
-  ['agent-device', createStartAgentDeviceRemoteSessionBuildFunction, 'agentDeviceRemoteSessionUrl'],
+  ['agent-device', createStartAgentDeviceSessionBuildFunction, 'agentDeviceRemoteSessionUrl'],
   ['Appium', createStartAppiumRemoteSessionBuildFunction, 'appiumUrl'],
   ['Argent', createStartArgentRemoteSessionBuildFunction, 'toolsUrl'],
   ['web preview', createStartWebPreviewRemoteSessionBuildFunction, 'previewUrl'],
@@ -82,16 +105,17 @@ const controllers = [
 
 describe.each(controllers)('%s local egress', (_name, createFunction, controllerField) => {
   const stopPreview = jest.fn();
+  const openPreview = jest.fn();
   const stopEgress = jest.fn();
   let lifetime: AbortSignal;
   async function run(signal?: AbortSignal): Promise<void> {
     await createFunction(ctx).fn!(
       { logger, global: { runtimePlatform: BuildRuntimePlatform.DARWIN } } as BuildStepContext,
       {
-        inputs: {
-          package_version: { value: undefined },
-          max_idle_time_minutes: { value: undefined },
-        },
+        // Inputs a step does not get default to undefined, like in a real step call.
+        inputs: new Proxy({} as Record<string, { value: unknown }>, {
+          get: (target, id: string) => target[id] ?? { value: undefined },
+        }),
         outputs: {},
         env,
         signal,
@@ -115,15 +139,31 @@ describe.each(controllers)('%s local egress', (_name, createFunction, controller
     jest.mocked(isProcessDescendantOfAsync).mockResolvedValue(true);
     jest
       .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
-      .mockResolvedValue([{ udid: 'sim' }] as never);
+      .mockResolvedValue([{ udid: 'sim', name: 'iPhone 17' }] as never);
+    jest.mocked(IosSimulatorUtils.resolveUdidAsync).mockResolvedValue('sim' as never);
     jest.mocked(turtleFetch).mockResolvedValue({ ok: true } as never);
     jest.mocked(readLocalEgressHandoffAsync).mockResolvedValue(handoff);
+    jest
+      .mocked(resolveLocalEgressServeSimBootEnvironmentAsync)
+      .mockImplementation(async () =>
+        (await readLocalEgressHandoffAsync())
+          ? { SERVE_SIM_ADDITIONAL_DYLIBS: '/test/egress-guard.dylib' }
+          : null
+      );
+    jest.mocked(startLocalEgressGuardRelayAsync).mockResolvedValue(undefined);
+    jest.mocked(reportLocalEgressGuardCoverageAsync).mockResolvedValue(null);
+    jest.mocked(verifyLocalEgressGuardAsync).mockResolvedValue(undefined);
     jest.mocked(monitorLocalEgressAsync).mockResolvedValue(undefined);
-    jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockResolvedValue({
+    openPreview.mockResolvedValue({
       previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
       apiUrl: 'https://preview.test',
       previewToken: 'preview-secret',
-      stopAsync: stopPreview,
+      closeAsync: jest.fn(),
+    });
+    jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
+      openPreviewAsync: openPreview,
+      getLastPreviewActivityAt: jest.fn(),
+      finishAsync: stopPreview,
     });
     jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockImplementation(async () => {
@@ -169,12 +209,14 @@ describe.each(controllers)('%s local egress', (_name, createFunction, controller
     expect(monitorLocalEgressAsync).not.toHaveBeenCalled();
     expect(stopEgress).not.toHaveBeenCalled();
   });
-  it.each(['startup', 'report', 'wait', 'teardown'])(
+  it.each(['startup', 'preview', 'report', 'wait', 'teardown'])(
     'releases egress after %s fails',
     async phase => {
       const error = new Error(`${phase} failed`);
       if (phase === 'startup') {
-        jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockRejectedValue(error);
+        jest.mocked(startDeviceSessionHostAsync).mockRejectedValue(error);
+      } else if (phase === 'preview') {
+        openPreview.mockRejectedValue(error);
       } else if (phase === 'report') {
         jest.mocked(uploadRemoteSessionConfigAsync).mockRejectedValue(error);
       } else if (phase === 'wait') {
@@ -186,7 +228,7 @@ describe.each(controllers)('%s local egress', (_name, createFunction, controller
       expect(lifetime.aborted).toBe(true);
       expect(stopEgress).toHaveBeenCalledTimes(1);
       expect(monitorLocalEgressAsync).toHaveBeenCalledTimes(
-        phase === 'startup' || phase === 'report' ? 0 : 1
+        phase === 'startup' || phase === 'preview' || phase === 'report' ? 0 : 1
       );
     }
   );

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

@@ -0,0 +1,202 @@
+import { SystemError } from '@expo/eas-build-job';
+import turtleSpawn from '@expo/turtle-spawn';
+import { vol } from 'memfs';
+import { spawn } from 'node:child_process';
+import { EventEmitter, once } from 'node:events';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import * as agentRun from '../../utils/agentRun';
+import { leaseAgentRunProviderCredentialsAsync } from '../../utils/agentRunLease';
+import { createRunAgentBuildFunction } from '../runAgent';
+
+jest.mock('@expo/turtle-spawn', () => ({ __esModule: true, default: jest.fn() }));
+jest.mock('node:child_process', () => ({
+  ...jest.requireActual('node:child_process'),
+  spawn: jest.fn(),
+}));
+jest.mock('../../utils/agentRunLease');
+
+const installMock = jest.mocked(turtleSpawn);
+const spawnMock = jest.mocked(spawn);
+const leaseMock = jest.mocked(leaseAgentRunProviderCredentialsAsync);
+
+const ctx = {
+  expoApiV2BaseUrl: 'https://staging-api.expo.test/v2/',
+  mcpServerUrl: 'wss://staging-mcp.expo.test',
+  runtimeApi: { addBuildLogMask: jest.fn() },
+} as any;
+const inputs = {
+  agent_kind: { value: 'claude-code' },
+  agent_run_id: { value: '0199b0a0-1111-7222-8333-444455556666' },
+  max_duration_seconds: { value: 1800 },
+  prompt: { value: 'Fix the failing test.' },
+};
+const env = {
+  PATH: '/usr/local/bin:/usr/bin',
+  HOME: '/home/expo',
+  EXPO_TOKEN: 'expo-token',
+  __API_SERVER_URL: 'https://staging-api.expo.test',
+  EAS_BUILD_ID: 'build-id',
+  NODE_OPTIONS: '--max-old-space-size=3072',
+  USER_DEFINED_SECRET: 'secret',
+};
+
+async function runAsync(
+  overrides: {
+    ctx?: any;
+    inputs?: Record<string, { value: unknown }>;
+    env?: Record<string, string>;
+  } = {}
+): Promise<void> {
+  const fn = createRunAgentBuildFunction(overrides.ctx ?? ctx);
+  await fn.fn!({ logger: createMockLogger() } as any, {
+    inputs: overrides.inputs ?? inputs,
+    outputs: {},
+    env: overrides.env ?? env,
+  });
+}
+
+function mockSuccessfulRun(): { mcpConfig?: any } {
+  const captured: { mcpConfig?: any } = {};
+  leaseMock.mockResolvedValue({ provider: 'anthropic', accessToken: 'anthropic-access-token' });
+  installMock.mockResolvedValue({} as any);
+  spawnMock.mockImplementation(((_command: string, _args: string[], spawnOptions: any) => {
+    const child = Object.assign(new EventEmitter(), {
+      stdin: { on: jest.fn(), end: jest.fn() },
+      stdout: new PassThrough(),
+      stderr: new PassThrough(),
+    });
+    captured.mcpConfig = JSON.parse(
+      vol.readFileSync(path.join(spawnOptions.env.HOME, 'mcp.json'), 'utf8') as string
+    );
+    process.nextTick(() => {
+      child.emit('exit', 0, null);
+      child.stdout.end();
+      child.stderr.end();
+      void Promise.all([once(child.stdout, 'end'), once(child.stderr, 'end')]).then(() =>
+        child.emit('close')
+      );
+    });
+    return child;
+  }) as any);
+  return captured;
+}
+
+describe(createRunAgentBuildFunction, () => {
+  it('is the eas/run_agent function', () => {
+    expect(createRunAgentBuildFunction(ctx).getFullId()).toBe('eas/run_agent');
+  });
+
+  it('passes none of the job environment to npm or the agent', async () => {
+    mockSuccessfulRun();
+
+    await runAsync();
+
+    expect(leaseMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        expoApiV2BaseUrl: 'https://staging-api.expo.test/v2/',
+        expoToken: 'expo-token',
+        agentRunId: '0199b0a0-1111-7222-8333-444455556666',
+      })
+    );
+    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(agentEnv).sort()).toEqual([
+      'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC',
+      'CLAUDE_CODE_OAUTH_TOKEN',
+      'HOME',
+      'LANG',
+      'PATH',
+      'TMPDIR',
+    ]);
+    expect(agentEnv.PATH).toBe('/usr/local/bin:/usr/bin');
+    expect(agentEnv.HOME).not.toBe('/home/expo');
+  });
+
+  it('hands the build log secrets filter to the agent run', async () => {
+    const runAgentSpy = jest.spyOn(agentRun, 'runAgentAsync').mockResolvedValue();
+    try {
+      await runAsync();
+
+      expect(runAgentSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ addBuildLogMask: ctx.runtimeApi.addBuildLogMask })
+      );
+    } finally {
+      runAgentSpy.mockRestore();
+    }
+  });
+
+  it.each([
+    ['wss://staging-mcp.expo.test', 'https://staging-mcp.expo.test/mcp'],
+    ['ws://localhost:8787', 'http://localhost:8787/mcp'],
+  ])('points the agent at the HTTP endpoint of %s', async (mcpServerUrl, mcpUrl) => {
+    const captured = mockSuccessfulRun();
+
+    await runAsync({ ctx: { ...ctx, mcpServerUrl } });
+
+    expect(captured.mcpConfig.mcpServers.expo.url).toBe(mcpUrl);
+  });
+
+  it('stops the run at max_duration_seconds and reports a timeout', async () => {
+    jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'queueMicrotask'] });
+    const runAgentSpy = jest.spyOn(agentRun, 'runAgentAsync').mockImplementation(
+      ({ signal }) =>
+        new Promise((_resolve, reject) => {
+          signal!.addEventListener('abort', () => reject(signal!.reason));
+        })
+    );
+    try {
+      const run = runAsync({ inputs: { ...inputs, max_duration_seconds: { value: 60 } } });
+      const rejection = expect(run).rejects.toMatchObject({
+        errorCode: 'EAS_RUN_AGENT_TIMEOUT',
+        message: expect.stringContaining('60 seconds'),
+      });
+      await jest.advanceTimersByTimeAsync(59_000);
+      expect(runAgentSpy.mock.calls[0][0].signal!.aborted).toBe(false);
+      await jest.advanceTimersByTimeAsync(1_000);
+      await rejection;
+    } finally {
+      runAgentSpy.mockRestore();
+      jest.useRealTimers();
+    }
+  });
+
+  it.each([
+    ['an unknown agent_kind', { inputs: { ...inputs, agent_kind: { value: 'gemini' } } }],
+    ['a malformed agent_run_id', { inputs: { ...inputs, agent_run_id: { value: 'not-a-uuid' } } }],
+    ['an empty agent_run_id', { inputs: { ...inputs, agent_run_id: { value: '' } } }],
+    ['a zero duration', { inputs: { ...inputs, max_duration_seconds: { value: 0 } } }],
+    ['a negative duration', { inputs: { ...inputs, max_duration_seconds: { value: -300 } } }],
+    ['a fractional duration', { inputs: { ...inputs, max_duration_seconds: { value: 12.5 } } }],
+    ['an empty prompt', { inputs: { ...inputs, prompt: { value: '' } } }],
+    ['no EXPO_TOKEN', { env: { ...env, EXPO_TOKEN: '' } }],
+    ['no PATH', { env: { ...env, PATH: '' } }],
+    ['no Expo API URL', { ctx: { ...ctx, expoApiV2BaseUrl: undefined } }],
+    ['no MCP server URL', { ctx: { ...ctx, mcpServerUrl: undefined } }],
+    ['no build log secrets filter', { ctx: { ...ctx, runtimeApi: {} } }],
+  ])('throws a system error for %s', async (_name, overrides) => {
+    await expect(runAsync(overrides)).rejects.toBeInstanceOf(SystemError);
+
+    expect(leaseMock).not.toHaveBeenCalled();
+    expect(installMock).not.toHaveBeenCalled();
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it('reports every invalid input at once', async () => {
+    await expect(
+      runAsync({
+        inputs: {
+          ...inputs,
+          agent_run_id: { value: 'not-a-uuid' },
+          max_duration_seconds: { value: 0 },
+        },
+      })
+    ).rejects.toThrow(
+      'The "agent_run_id" input must be the UUID of an agent run, but received "not-a-uuid". ' +
+        'The "max_duration_seconds" input must be a positive whole number of seconds, but received "0".'
+    );
+  });
+});

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

@@ -0,0 +1,70 @@
+import { type bunyan } from '@expo/logger';
+import { type BuildStepContext, type BuildStepEnv } from '@expo/steps';
+
+import { type CustomBuildContext } from '../../../customBuildContext';
+import { Sentry } from '../../../sentry';
+import { getDeviceRunSessionIdOrThrow } from '../../utils/remoteDeviceRunSession';
+import { uploadServeSimLogsFileAsync } from '../../utils/serveSimLogsArtifacts';
+import { ServeSimLogsRecorder } from '../../utils/serveSimLogsRecorder';
+import { createCollectServeSimLogsBuildFunction } from '../collectServeSimLogs';
+import { createStartServeSimLogsBuildFunction } from '../startServeSimLogs';
+
+jest.mock('../../../sentry');
+jest.mock('../../utils/serveSimLogsRecorder');
+jest.mock('../../utils/serveSimLogsArtifacts');
+jest.mock('../../utils/remoteDeviceRunSession');
+
+const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
+const ctx = {} as CustomBuildContext;
+const step = { logger } as BuildStepContext;
+const args = { inputs: {}, outputs: {}, env: {} as BuildStepEnv };
+
+beforeEach(() => {
+  jest.mocked(getDeviceRunSessionIdOrThrow).mockReturnValue('session-id');
+  jest.mocked(ServeSimLogsRecorder.finishAsync).mockResolvedValue([]);
+});
+
+it('starts collection and tolerates startup failures', async () => {
+  jest.mocked(ServeSimLogsRecorder.startAsync).mockRejectedValueOnce(new Error('disk failure'));
+  await expect(createStartServeSimLogsBuildFunction().fn?.(step, args)).resolves.toBeUndefined();
+  expect(logger.warn).toHaveBeenCalled();
+  expect(Sentry.capture).toHaveBeenCalledWith(
+    'Could not start serve-sim simulator logs',
+    expect.any(Error)
+  );
+});
+
+it('uploads each device with its own bounded signal', async () => {
+  jest.mocked(ServeSimLogsRecorder.finishAsync).mockResolvedValue([
+    { udid: 'A', filePath: '/tmp/A.ndjson' },
+    { udid: 'B', filePath: '/tmp/B.ndjson' },
+  ]);
+  await createCollectServeSimLogsBuildFunction(ctx).fn?.(step, args);
+  expect(uploadServeSimLogsFileAsync).toHaveBeenCalledTimes(2);
+  expect(uploadServeSimLogsFileAsync).toHaveBeenCalledWith(
+    ctx,
+    expect.objectContaining({
+      deviceRunSessionId: 'session-id',
+      udid: 'A',
+      filePath: '/tmp/A.ndjson',
+      signal: expect.any(AbortSignal),
+    })
+  );
+  expect(jest.mocked(uploadServeSimLogsFileAsync).mock.calls[0][1].signal).not.toBe(
+    jest.mocked(uploadServeSimLogsFileAsync).mock.calls[1][1].signal
+  );
+});
+
+it('skips empty collection and warns on finalization failure', async () => {
+  await createCollectServeSimLogsBuildFunction(ctx).fn?.(step, args);
+  expect(uploadServeSimLogsFileAsync).not.toHaveBeenCalled();
+  jest.mocked(ServeSimLogsRecorder.finishAsync).mockRejectedValueOnce(new Error('failure'));
+  await expect(
+    createCollectServeSimLogsBuildFunction(ctx).fn?.(step, args)
+  ).resolves.toBeUndefined();
+  expect(logger.warn).toHaveBeenCalled();
+  expect(Sentry.capture).toHaveBeenCalledWith(
+    'Could not finalize serve-sim simulator logs',
+    expect.any(Error)
+  );
+});

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

@@ -1,26 +1,27 @@
-import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
+import { BuildRuntimePlatform } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
 import { pollAgentDeviceArtifactsForUploadAsync } from '../../utils/agentDeviceArtifacts';
 import { startAgentDeviceEventCollectionAsync } from '../../utils/agentDeviceEvents';
+import { startDeviceSessionHostAsync } from '../../utils/deviceSessionHost';
 import {
   getDeviceRunSessionIdOrThrow,
   getNgrokAuthtokenOrThrow,
   getNgrokTunnelDomainOrThrow,
   selectXcodeDeveloperDirectoryAsync,
   spawnDetached,
-  startDeviceWebPreviewWithTunnelAsync,
   startNgrokTunnelAsync,
   uploadRemoteSessionConfigAsync,
   waitForDeviceRunSessionStoppedAsync,
   waitForFileAsync,
 } from '../../utils/remoteDeviceRunSession';
-import { createStartAgentDeviceRemoteSessionBuildFunction } from '../startAgentDeviceRemoteSession';
+import { createProcessOutput } from '../../utils/processOutput';
+import { type StartupTasks, createStartupTasks } from '../../utils/startupTasks';
+import { runAgentDeviceRemoteSessionAsync } from '../startAgentDeviceRemoteSession';
 
 // The daemon entry path and the state directory are resolved from the home directory when
 // the module loads, so point it at a temp home we can populate.
@@ -40,6 +41,7 @@ jest.mock('../../utils/agentDeviceArtifacts', () => ({
 jest.mock('../../utils/agentDeviceEvents', () => ({
   startAgentDeviceEventCollectionAsync: jest.fn(),
 }));
+jest.mock('../../utils/deviceSessionHost');
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
   getDeviceRunSessionIdOrThrow: jest.fn(),
@@ -47,7 +49,6 @@ jest.mock('../../utils/remoteDeviceRunSession', () => ({
   getNgrokTunnelDomainOrThrow: jest.fn(),
   selectXcodeDeveloperDirectoryAsync: jest.fn(),
   spawnDetached: jest.fn(),
-  startDeviceWebPreviewWithTunnelAsync: jest.fn(),
   startNgrokTunnelAsync: jest.fn(),
   uploadRemoteSessionConfigAsync: jest.fn(),
   waitForDeviceRunSessionStoppedAsync: jest.fn(),
@@ -66,28 +67,42 @@ const mockTunnelStopAsync = jest.fn();
 const mockDaemonStopAsync = jest.fn();
 const mockEventCollectionStopAsync = jest.fn();
 
+type CaptureInputs = Parameters<typeof runAgentDeviceRemoteSessionAsync>[1]['capture'];
+const NO_CAPTURE: CaptureInputs = { networkCapture: false, networkCaptureFields: [] };
+
+/** Runs an Android session that is ready, or an iOS session with no application preparation. */
 async function runAsync(
-  logger: { info: jest.Mock; warn: jest.Mock },
+  logger: { info: jest.Mock; warn: jest.Mock; child: jest.Mock },
   runtimePlatform: BuildRuntimePlatform,
-  launchInputs: Record<string, { value: unknown }> = {}
+  capture: CaptureInputs = NO_CAPTURE,
+  disableShare = false,
+  privatePreviewUrl?: string,
+  maxIdleTimeMinutes?: number
 ): Promise<void> {
-  const buildFunction = createStartAgentDeviceRemoteSessionBuildFunction(ctx);
-  await buildFunction.fn!(
-    { logger, global: { runtimePlatform } } as unknown as BuildStepContext,
-    {
-      inputs: {
-        package_version: { value: undefined },
-        max_idle_time_minutes: { value: undefined },
-        max_duration_seconds: { value: undefined },
-        ...launchInputs,
-      },
-      outputs: {},
-      env: {},
-    } as never
-  );
+  await runAgentDeviceRemoteSessionAsync(ctx, {
+    env: {},
+    logger: logger as never,
+    runtimePlatform,
+    sessionEnv: {
+      deviceRunSessionId: 'device-run-session-id',
+      ngrokTunnelDomain: 'tunnel.example.com',
+      ngrokAuthtoken: 'ngrok-token',
+    },
+    packageVersion: undefined,
+    maxIdleTimeMinutes,
+    maxDurationSeconds: undefined,
+    capture,
+    disableShare,
+    privatePreviewUrl,
+    tasks: createStartupTasks(logger as never),
+    device:
+      runtimePlatform === BuildRuntimePlatform.DARWIN
+        ? { iosSimulatorUdid: 'selected-udid', application: Promise.resolve() }
+        : { booted: Promise.resolve(), ready: Promise.resolve() },
+  });
 }
 
-describe('createStartAgentDeviceRemoteSessionBuildFunction orchestration', () => {
+describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
   beforeEach(async () => {
     jest.clearAllMocks();
 
@@ -104,6 +119,7 @@ describe('createStartAgentDeviceRemoteSessionBuildFunction orchestration', () =>
     jest.mocked(spawnDetached).mockReturnValue({
       pid: 4242,
       getOutput: () => '',
+      getExitError: () => undefined,
       stopAsync: mockDaemonStopAsync,
     });
     jest.mocked(waitForFileAsync).mockResolvedValue({ port: 5678, token: 'daemon-token' });
@@ -112,10 +128,24 @@ describe('createStartAgentDeviceRemoteSessionBuildFunction orchestration', () =>
       subdomainId: 'agent-device-abc',
       stopAsync: mockTunnelStopAsync,
     });
-    jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockResolvedValue({
-      previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
-      apiUrl: 'https://web-preview.tunnel.example.com',
-      stopAsync: mockPreviewStopAsync,
+    const host = {
+      openPreviewAsync: jest.fn().mockResolvedValue({
+        previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        apiUrl: 'https://web-preview.tunnel.example.com',
+        closeAsync: jest.fn(),
+      }),
+      getLastPreviewActivityAt: jest.fn(),
+      finishAsync: mockPreviewStopAsync,
+    };
+    jest.mocked(startDeviceSessionHostAsync).mockImplementation(async (_ctx, options) => {
+      try {
+        await options.application;
+        options.signal?.throwIfAborted();
+      } catch (error) {
+        await mockPreviewStopAsync();
+        throw error;
+      }
+      return host;
     });
     jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
@@ -129,14 +159,13 @@ describe('createStartAgentDeviceRemoteSessionBuildFunction orchestration', () =>
   });
 
   it('reports the preview URL and tears every resource down', async () => {
-    const logger = { info: jest.fn(), warn: jest.fn() };
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
 
     await runAsync(logger, BuildRuntimePlatform.LINUX);
 
-    expect(selectXcodeDeveloperDirectoryAsync).not.toHaveBeenCalled();
-    expect(startDeviceWebPreviewWithTunnelAsync).toHaveBeenCalledWith(
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
       ctx,
-      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX })
+      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX, timeoutMs: 60_000 })
     );
     expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -154,47 +183,527 @@ describe('createStartAgentDeviceRemoteSessionBuildFunction orchestration', () =>
     expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
   });
 
-  it('hands the launch inputs to serve-sim and announces them on an iOS session', async () => {
-    const logger = { info: jest.fn(), warn: jest.fn() };
+  it('redacts learned daemon credentials in arbitrary output and retained diagnostics', async () => {
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+    const token = 'daemon secret/+';
+    jest.mocked(waitForFileAsync).mockResolvedValue({ port: 5678, token });
+    jest.mocked(startNgrokTunnelAsync).mockImplementation(async () => {
+      const options = jest.mocked(spawnDetached).mock.calls[0][0];
+      expect(options.secrets).toContain(token);
+      const output = createProcessOutput(options.logger, options.secrets);
+      output.stdout.append('unrecognized value: daemon sec');
+      output.stdout.append('ret/+\n');
+      output.stderr.append(`escaped value: ${encodeURIComponent(token)}\n`);
+      expect(output.getOutput()).toBe(
+        'unrecognized value: [REDACTED]\nescaped value: [REDACTED]\n'
+      );
+      return { url: 'https://daemon.test', subdomainId: 'daemon', stopAsync: mockTunnelStopAsync };
+    });
+    await runAsync(logger, BuildRuntimePlatform.DARWIN);
+    expect(JSON.stringify(logger.info.mock.calls)).not.toContain(token);
+    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() };
 
     await runAsync(logger, BuildRuntimePlatform.DARWIN, {
-      launch_app_identifier: { value: 'host.exp.Exponent' },
-      launch_args: { value: ['-EXDevMenuIsOnboardingFinished', '1'] },
-      open_url: { value: 'exp://127.0.0.1:8081' },
+      networkCapture: true,
+      networkCaptureFields: ['header'],
     });
 
-    expect(startDeviceWebPreviewWithTunnelAsync).toHaveBeenCalledWith(
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ networkCapture: true, networkCaptureFields: ['header'] })
+    );
+  });
+
+  it('hands a private preview choice to the session host', async () => {
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+    await runAsync(
+      logger,
+      BuildRuntimePlatform.DARWIN,
+      NO_CAPTURE,
+      true,
+      'https://expo.dev/private-preview'
+    );
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
       ctx,
       expect.objectContaining({
-        runtimePlatform: BuildRuntimePlatform.DARWIN,
-        launchAppIdentifier: 'host.exp.Exponent',
-        launchArgs: ['-EXDevMenuIsOnboardingFinished', '1'],
-        openUrl: 'exp://127.0.0.1:8081',
+        disableShare: true,
+        privatePreviewUrl: 'https://expo.dev/private-preview',
       })
     );
-    expect(logger.info).toHaveBeenCalledWith(
-      'serve-sim will launch host.exp.Exponent with arguments ' +
-        '["-EXDevMenuIsOnboardingFinished","1"], then open exp://127.0.0.1:8081.'
-    );
   });
 
-  it('fails before starting the daemon when a launch is asked for on Android', async () => {
-    const logger = { info: jest.fn(), warn: jest.fn() };
+  it('starts the session host without waiting for the agent-device daemon', async () => {
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+    const sessionHost = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+      ctx,
+      {} as never
+    );
+    let markHostStarted!: () => void;
+    const hostStarted = new Promise<void>(resolve => {
+      markHostStarted = resolve;
+    });
+    jest.mocked(startDeviceSessionHostAsync).mockImplementation(async () => {
+      markHostStarted();
+      return sessionHost;
+    });
+    // The daemon credentials only appear after the session host started. A sequential
+    // startup would wait here forever.
+    jest.mocked(waitForFileAsync).mockImplementation(async () => {
+      await hostStarted;
+      return { port: 5678, token: 'daemon-token' };
+    });
 
-    await expect(
-      runAsync(logger, BuildRuntimePlatform.LINUX, {
-        launch_app_identifier: { value: 'host.exp.Exponent' },
+    await runAsync(logger, BuildRuntimePlatform.DARWIN);
+
+    expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteConfig: expect.objectContaining({
+          agentDeviceRemoteSessionUrl: 'https://agent-device-abc.tunnel.example.com',
+          agentDeviceRemoteSessionToken: 'daemon-token',
+          webPreviewUrl: 'https://expo.dev/simulator-preview/preview-id',
+        }),
       })
-    ).rejects.toThrow('runs on linux');
-    expect(spawnDetached).not.toHaveBeenCalled();
+    );
   });
 
-  it('declares the launch inputs', () => {
-    const buildFunction = createStartAgentDeviceRemoteSessionBuildFunction(ctx);
-    const globalCtx = createGlobalContextMock();
+  it('stops the daemon and its tunnel when the session host fails to start', async () => {
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+    jest
+      .mocked(startDeviceSessionHostAsync)
+      .mockRejectedValue(new Error('serve-sim did not start'));
 
-    expect(
-      buildFunction.inputProviders?.map(provider => provider(globalCtx, 'Test step').id)
-    ).toEqual(expect.arrayContaining(['launch_app_identifier', 'launch_args', 'open_url']));
+    await expect(runAsync(logger, BuildRuntimePlatform.DARWIN)).rejects.toThrow(
+      'serve-sim did not start'
+    );
+
+    expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    // The failure aborts the daemon task, which then may not start its daemon or tunnel.
+    // Whatever started is stopped.
+    expect(mockDaemonStopAsync).toHaveBeenCalledTimes(jest.mocked(spawnDetached).mock.calls.length);
+    expect(mockTunnelStopAsync).toHaveBeenCalledTimes(
+      jest.mocked(startNgrokTunnelAsync).mock.calls.length
+    );
+  });
+
+  it('stops the session host and the daemon when the daemon credentials never appear', async () => {
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+    jest.mocked(waitForFileAsync).mockRejectedValue(new Error('no daemon credentials'));
+
+    await expect(runAsync(logger, BuildRuntimePlatform.DARWIN)).rejects.toThrow(
+      'no daemon credentials'
+    );
+
+    expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+    expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+    expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
+  });
+
+  describe('runAgentDeviceRemoteSessionAsync with a device that is still starting', () => {
+    function deferred<T = void>(): {
+      promise: Promise<T>;
+      resolve: (value: T) => void;
+      reject: (e: Error) => void;
+    } {
+      let resolve!: (value: T) => void;
+      let reject!: (e: Error) => void;
+      const promise = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      promise.catch(() => {});
+      return { promise, resolve, reject };
+    }
+
+    type Device = Parameters<typeof runAgentDeviceRemoteSessionAsync>[1]['device'];
+    function startSession(
+      device: Device | ((tasks: StartupTasks) => Device),
+      signal?: AbortSignal
+    ) {
+      const logger = {
+        info: jest.fn(),
+        warn: jest.fn(),
+        child: jest.fn().mockReturnThis(),
+      } as never;
+      const tasks = createStartupTasks(logger, signal);
+      const sessionDevice = typeof device === 'function' ? device(tasks) : device;
+      return runAgentDeviceRemoteSessionAsync(ctx, {
+        env: {},
+        logger,
+        signal,
+        runtimePlatform:
+          'iosSimulatorUdid' in sessionDevice
+            ? BuildRuntimePlatform.DARWIN
+            : BuildRuntimePlatform.LINUX,
+        sessionEnv: {
+          deviceRunSessionId: 'device-run-session-id',
+          ngrokTunnelDomain: 'tunnel.example.com',
+          ngrokAuthtoken: 'ngrok-token',
+        },
+        packageVersion: undefined,
+        maxIdleTimeMinutes: undefined,
+        maxDurationSeconds: undefined,
+        capture: NO_CAPTURE,
+        tasks,
+        device: sessionDevice,
+      });
+    }
+
+    async function flushAsync(): Promise<void> {
+      for (let i = 0; i < 20; i++) {
+        await new Promise(resolve => setImmediate(resolve));
+      }
+    }
+
+    it('aborts parallel startup before host failure cleanup finishes', async () => {
+      const failure = new Error('guard refused startup');
+      const cleanup = deferred();
+      const notified = deferred();
+      let startupTasks!: StartupTasks;
+      jest.mocked(startDeviceSessionHostAsync).mockImplementation(async (_ctx, options) => {
+        options.onStartupError?.(failure);
+        notified.resolve();
+        await cleanup.promise;
+        throw failure;
+      });
+      const session = startSession(tasks => {
+        startupTasks = tasks;
+        return { iosSimulatorUdid: 'selected-udid' };
+      });
+      const rejected = expect(session).rejects.toBe(failure);
+      await notified.promise;
+      expect(startupTasks.signal.aborted).toBe(true);
+      expect(startupTasks.signal.reason).toBe(failure);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+      cleanup.resolve();
+      await rejected;
+    });
+
+    it('starts the daemon during the Android boot and the session host after it', async () => {
+      const booted = deferred();
+      const session = startSession({ booted: booted.promise, ready: booted.promise });
+      await flushAsync();
+
+      expect(spawnDetached).toHaveBeenCalledTimes(1);
+      expect(startNgrokTunnelAsync).toHaveBeenCalledTimes(1);
+      expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
+
+      booted.resolve();
+      await session;
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+        ctx,
+        expect.objectContaining({
+          runtimePlatform: BuildRuntimePlatform.LINUX,
+          timeoutMs: 60_000,
+          iosSimulatorUdid: undefined,
+        })
+      );
+      expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledTimes(1);
+    });
+
+    it('preserves a failed download when aborting daemon installation rejects first', async () => {
+      const failure = new Error('download failed: build not found');
+      const installStarted = deferred();
+      jest.mocked(spawn).mockImplementation((async (_command, _args, options) => {
+        return await new Promise((_resolve, reject) => {
+          options!.signal!.addEventListener(
+            'abort',
+            () => {
+              const error = new Error('The operation was aborted');
+              error.name = 'AbortError';
+              reject(error);
+            },
+            { once: true }
+          );
+          installStarted.resolve();
+        });
+      }) as typeof spawn);
+      jest.mocked(startDeviceSessionHostAsync).mockImplementation(async (_ctx, { signal }) => {
+        return await new Promise((_resolve, reject) => {
+          signal!.addEventListener(
+            'abort',
+            () => {
+              setTimeout(() => reject(signal!.reason), 20);
+            },
+            { once: true }
+          );
+        });
+      });
+      const applicationReady = Promise.resolve();
+      const session = startSession(tasks => {
+        void tasks.run('build download', async () => {
+          await installStarted.promise;
+          throw failure;
+        });
+        return { iosSimulatorUdid: 'selected-udid', application: applicationReady };
+      });
+      await expect(session).rejects.toBe(failure);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('boots the host during download and releases startup only after preparation', async () => {
+      const hostReady = deferred();
+      const application = deferred<{
+        installAppPath: string;
+        launchAppIdentifier: string;
+        launchArgs: string[];
+        openUrl: string;
+      }>();
+      const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+        ctx,
+        {} as never
+      );
+      const release = jest.fn();
+      jest
+        .mocked(startDeviceSessionHostAsync)
+        .mockClear()
+        .mockImplementation(async (_ctx, options) => {
+          release(await options.application);
+          await hostReady.promise;
+          return host;
+        });
+      const applicationReady = application.promise;
+      const session = startSession({
+        iosSimulatorUdid: 'selected-udid',
+        application: applicationReady,
+      });
+      await flushAsync();
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+      expect(release).not.toHaveBeenCalled();
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+      const startup = {
+        installAppPath: '/tmp/App.app',
+        launchAppIdentifier: 'dev.example.app',
+        launchArgs: ['--flag'],
+        openUrl: 'example://screen',
+      };
+      application.resolve(startup);
+      await flushAsync();
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+        ctx,
+        expect.objectContaining({
+          application: applicationReady,
+          iosSimulatorUdid: 'selected-udid',
+          timeoutMs: 60_000,
+          signal: expect.any(AbortSignal),
+        })
+      );
+      expect(release).toHaveBeenCalledWith(startup);
+      expect(host.openPreviewAsync).not.toHaveBeenCalled();
+      hostReady.resolve();
+      await session;
+      expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledTimes(1);
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+    });
+
+    it('passes the guard boot environment with the startup installation and launch', async () => {
+      const startup = {
+        installAppPath: '/tmp/App.app',
+        launchAppIdentifier: 'dev.example.app',
+        launchArgs: ['--flag'],
+        openUrl: 'example://screen',
+      };
+      const bootEnv = {
+        SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+        SIMCTL_CHILD_EAS_EGRESS_GUARD_MODE: 'block',
+        SIMCTL_CHILD_EAS_EGRESS_GUARD_LOG: '/tmp/egress-guard.log',
+        SIMCTL_CHILD_HTTP_PROXY: 'http://127.0.0.1:8899',
+      };
+      await startSession({
+        iosSimulatorUdid: 'guarded-udid',
+        bootEnv,
+        application: Promise.resolve(startup),
+      });
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+        ctx,
+        expect.objectContaining({
+          application: expect.any(Promise),
+          bootEnv,
+          iosSimulatorUdid: 'guarded-udid',
+        })
+      );
+      const hostOptions = jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1];
+      expect(hostOptions.bootEnv).toBe(bootEnv);
+      expect(hostOptions.bootEnv).not.toHaveProperty('DYLD_INSERT_LIBRARIES');
+      expect(hostOptions.bootEnv).not.toHaveProperty('SIMCTL_CHILD_DYLD_INSERT_LIBRARIES');
+    });
+
+    it('cleans up a host returned after cancellation without configuring the device', async () => {
+      const hostReady = deferred();
+      const controller = new AbortController();
+      const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+        ctx,
+        {} as never
+      );
+      jest.mocked(startDeviceSessionHostAsync).mockImplementation(async () => {
+        await hostReady.promise;
+        return host;
+      });
+      const applicationReady = Promise.resolve();
+      const session = startSession(
+        { iosSimulatorUdid: 'selected-udid', application: applicationReady },
+        controller.signal
+      );
+      const failure = expect(session).rejects.toThrow('cancelled');
+      await flushAsync();
+      controller.abort(new Error('cancelled'));
+      hostReady.resolve();
+
+      await failure;
+      expect(host.openPreviewAsync).not.toHaveBeenCalled();
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('drains in-flight application preparation and stops the waiting host after cancellation', async () => {
+      const controller = new AbortController();
+      const appReady = deferred();
+      const session = startSession(
+        { iosSimulatorUdid: 'selected-udid', application: appReady.promise },
+        controller.signal
+      );
+      const failure = expect(session).rejects.toThrow('cancelled');
+      await flushAsync();
+      controller.abort(new Error('cancelled'));
+      await flushAsync();
+      expect(mockPreviewStopAsync).not.toHaveBeenCalled();
+
+      appReady.resolve();
+      await failure;
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('does not report readiness when cancellation arrives during preview startup', async () => {
+      const controller = new AbortController();
+      const previewReady = deferred();
+      const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+        ctx,
+        {} as never
+      );
+      const preview = await host.openPreviewAsync({
+        baseDomain: 'tunnel.example.com',
+        authtoken: 'ngrok-token',
+      });
+      jest.mocked(host.openPreviewAsync).mockImplementation(async () => {
+        await previewReady.promise;
+        return preview;
+      });
+      const session = startSession(
+        { iosSimulatorUdid: 'selected-udid', application: Promise.resolve() },
+        controller.signal
+      );
+      const failure = expect(session).rejects.toThrow('cancelled');
+      await flushAsync();
+      controller.abort(new Error('cancelled'));
+      previewReady.resolve();
+
+      await failure;
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('does not start resources for an already cancelled session', async () => {
+      const controller = new AbortController();
+      controller.abort(new Error('cancelled'));
+      const applicationReady = Promise.resolve();
+
+      await expect(
+        startSession(
+          { iosSimulatorUdid: 'selected-udid', application: applicationReady },
+          controller.signal
+        )
+      ).rejects.toThrow('cancelled');
+      expect(spawn).not.toHaveBeenCalled();
+      expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
+    });
+
+    it('starts the Android host before application readiness and waits before reporting ready', async () => {
+      const ready = deferred();
+      const session = startSession({ booted: Promise.resolve(), ready: ready.promise });
+      await flushAsync();
+
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+
+      ready.resolve();
+      await session;
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledTimes(1);
+    });
+
+    it('stops waiting for the Android boot when the daemon fails', async () => {
+      jest.mocked(waitForFileAsync).mockRejectedValue(new Error('no daemon credentials'));
+      const neverBooted = new Promise<void>(() => {});
+
+      // In the combined step, `ready` stops waiting for the boot on an abort, like this.
+      await expect(
+        startSession(tasks => ({ booted: neverBooted, ready: tasks.untilAborted(neverBooted) }))
+      ).rejects.toThrow('no daemon credentials');
+
+      expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
+      expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('cancels daemon installation and stops the Android host when the download fails', async () => {
+      jest.mocked(spawn).mockImplementation(((
+        command: string,
+        args: string[],
+        options?: { signal?: AbortSignal }
+      ) =>
+        command === 'bun' && args[0] === 'add'
+          ? new Promise((_resolve, reject) => {
+              options!.signal!.addEventListener('abort', () => reject(options!.signal!.reason));
+            })
+          : Promise.resolve(undefined)) as never);
+      const ready = deferred();
+      const session = startSession({ booted: Promise.resolve(), ready: ready.promise });
+      await flushAsync();
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+
+      ready.reject(new Error('download failed'));
+
+      await expect(session).rejects.toThrow('download failed');
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(spawnDetached).not.toHaveBeenCalled();
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('stops the Android host, daemon and tunnel when the download fails', async () => {
+      const ready = deferred();
+      const session = startSession({ booted: Promise.resolve(), ready: ready.promise });
+      await flushAsync();
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+      ready.reject(new Error('download failed'));
+
+      await expect(session).rejects.toThrow('download failed');
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+      expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+    });
   });
 });

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

@@ -75,6 +75,7 @@ describe(startAgentDeviceDaemonAsync, () => {
     jest.mocked(spawnDetached).mockReturnValue({
       pid: 1234,
       getOutput: () => '',
+      getExitError: () => undefined,
       stopAsync,
     });
     jest.mocked(spawn).mockImplementation((async (
@@ -92,6 +93,28 @@ describe(startAgentDeviceDaemonAsync, () => {
     }) as never);
   });
 
+  it.each([false, true])(
+    'shares the daemon secret list through git fallback=%s',
+    async fallback => {
+      if (fallback) {
+        jest.mocked(spawn).mockResolvedValue({ stdout: '' } as never);
+      }
+      const secrets: string[] = [];
+      const handle = await startAgentDeviceDaemonAsync({
+        packageVersion: '1.2.3',
+        env: {},
+        logger,
+        secrets,
+      });
+      const options = jest.mocked(spawnDetached).mock.calls[0][0];
+      expect(options.command).toBe(fallback ? 'bun' : 'node');
+      expect(options.secrets).toBe(secrets);
+      secrets.push('learned-daemon-token');
+      expect(options.secrets).toContain('learned-daemon-token');
+      await handle.stopAsync();
+    }
+  );
+
   it('installs with bun add by default and launches the published daemon', async () => {
     const handle = await startAgentDeviceDaemonAsync({
       packageVersion: '1.2.3',
@@ -107,14 +130,35 @@ describe(startAgentDeviceDaemonAsync, () => {
     const addCwd = jest.mocked(spawn).mock.calls[0][2]?.cwd as string;
     expect(spawnDetached).toHaveBeenCalledWith({
       command: 'node',
+      logger,
+      secrets: undefined,
       args: [path.join(addCwd, 'node_modules/agent-device/dist/src/internal/daemon.js')],
-      env: expect.objectContaining({ AGENT_DEVICE_DAEMON_SERVER_MODE: 'http' }),
+      env: expect.objectContaining({
+        AGENT_DEVICE_DAEMON_SERVER_MODE: 'http',
+        AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS: '0',
+        AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS: '0',
+        AGENT_DEVICE_SESSION_IDLE_TIMEOUT_MS: '0',
+      }),
     });
 
     await handle.stopAsync();
     await expect(fs.promises.access(addCwd)).rejects.toThrow();
   });
 
+  it('removes the install directory when the daemon cannot be stopped', async () => {
+    const stopError = new Error('drain timed out');
+    stopAsync.mockRejectedValueOnce(stopError);
+    const handle = await startAgentDeviceDaemonAsync({
+      packageVersion: '1.2.3',
+      env: {},
+      logger,
+    });
+    const addCwd = jest.mocked(spawn).mock.calls[0][2]?.cwd as string;
+
+    await expect(handle.stopAsync()).rejects.toBe(stopError);
+    await expect(fs.promises.access(addCwd)).rejects.toThrow();
+  });
+
   it('installs with npm when EAS_OVERRIDE_PACKAGE_MANAGER is npm', async () => {
     await startAgentDeviceDaemonAsync({
       packageVersion: undefined,
@@ -129,6 +173,41 @@ describe(startAgentDeviceDaemonAsync, () => {
     );
   });
 
+  it('kills the install and does not fall back to git when aborted', async () => {
+    let installStarted!: () => void;
+    const started = new Promise<void>(resolve => {
+      installStarted = resolve;
+    });
+    jest.mocked(spawn).mockImplementation(
+      ((_command: string, _args: string[], options?: { signal?: AbortSignal }) =>
+        new Promise((_resolve, reject) => {
+          options!.signal!.addEventListener('abort', () => reject(options!.signal!.reason));
+          installStarted();
+        })) as never
+    );
+    const controller = new AbortController();
+    const failure = new Error('app install failed');
+
+    const daemon = startAgentDeviceDaemonAsync({
+      packageVersion: '1.2.3',
+      env: {},
+      logger,
+      signal: controller.signal,
+    });
+    await started;
+    controller.abort(failure);
+
+    await expect(daemon).rejects.toBe(failure);
+    expect(spawn).toHaveBeenCalledTimes(1);
+    expect(spawn).toHaveBeenCalledWith(
+      'bun',
+      ['add', '[email protected]'],
+      expect.objectContaining({ signal: controller.signal })
+    );
+    expect(spawnDetached).not.toHaveBeenCalled();
+    expect(Sentry.capture).not.toHaveBeenCalled();
+  });
+
   it('falls back to git clone when the published daemon is missing', async () => {
     jest.mocked(spawn).mockImplementation((async (command: string, args: string[]) => {
       if (command === 'bun' && args[0] === '--version') {
@@ -163,9 +242,16 @@ describe(startAgentDeviceDaemonAsync, () => {
     );
     expect(spawnDetached).toHaveBeenCalledWith({
       command: 'bun',
+      logger,
+      secrets: undefined,
       args: ['run', 'src/daemon.ts'],
       cwd: '/tmp/agent-device-src',
-      env: expect.objectContaining({ AGENT_DEVICE_DAEMON_SERVER_MODE: 'http' }),
+      env: expect.objectContaining({
+        AGENT_DEVICE_DAEMON_SERVER_MODE: 'http',
+        AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS: '0',
+        AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS: '0',
+        AGENT_DEVICE_SESSION_IDLE_TIMEOUT_MS: '0',
+      }),
     });
     expect(Sentry.capture).toHaveBeenCalledWith(
       'Failed to start agent-device daemon from the configured package manager; falling back to git clone',

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

@@ -0,0 +1,731 @@
+import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
+import { UserError } from '@expo/eas-build-job';
+import spawn from '@expo/turtle-spawn';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { type CustomBuildContext } from '../../../customBuildContext';
+import { DeviceRunSessionWorkerApi } from '../../utils/deviceRunSessionWorkerApi';
+import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import { stopLocalEgressResourcesAsync } from '../../utils/localEgress';
+import {
+  resolveLocalEgressServeSimBootEnvironmentAsync,
+  startLocalEgressGuardRelayAsync,
+} from '../../utils/localEgressGuard';
+import { selectXcodeDeveloperDirectoryAsync } from '../../utils/remoteDeviceRunSession';
+import { downloadBuildAsync } from '../downloadBuild';
+import { installBuildAsync } from '../installBuild';
+import { readIosApplicationIdentifierAsync } from '../../utils/iosAppArtifact';
+import { launchApplicationAsync } from '../launchApplication';
+import {
+  getAgentDeviceRemoteSessionEnvOrThrow,
+  runAgentDeviceRemoteSessionAsync,
+} from '../startAgentDeviceRemoteSession';
+import { createStartAgentDeviceSessionBuildFunction } from '../startAgentDeviceSession';
+import { startAndroidEmulatorAsync } from '../startAndroidEmulator';
+import { bootIosSimulatorAsync } from '../startIosSimulator';
+
+jest.mock('../../utils/localEgress', () => ({
+  stopLocalEgressResourcesAsync: jest.fn().mockResolvedValue(undefined),
+}));
+jest.mock('../../utils/localEgressGuard', () => ({
+  resolveLocalEgressServeSimBootEnvironmentAsync: jest.fn(),
+  startLocalEgressGuardRelayAsync: jest.fn(),
+}));
+jest.mock('@expo/turtle-spawn');
+jest.mock('../../../utils/IosSimulatorUtils');
+jest.mock('../../utils/remoteDeviceRunSession', () => ({
+  ...jest.requireActual('../../utils/remoteDeviceRunSession'),
+  selectXcodeDeveloperDirectoryAsync: jest.fn(),
+}));
+jest.mock('../startIosSimulator', () => ({
+  ...jest.requireActual('../startIosSimulator'),
+  bootIosSimulatorAsync: jest.fn(),
+}));
+jest.mock('../startAndroidEmulator', () => ({ startAndroidEmulatorAsync: jest.fn() }));
+jest.mock('../downloadBuild', () => ({ downloadBuildAsync: jest.fn() }));
+jest.mock('../installBuild', () => ({ installBuildAsync: jest.fn() }));
+jest.mock('../../utils/iosAppArtifact', () => ({
+  ...jest.requireActual('../../utils/iosAppArtifact'),
+  readIosApplicationIdentifierAsync: jest.fn(),
+}));
+jest.mock('../launchApplication', () => ({
+  ...jest.requireActual('../launchApplication'),
+  launchApplicationAsync: jest.fn(),
+}));
+jest.mock('../startAgentDeviceRemoteSession', () => ({
+  getAgentDeviceRemoteSessionEnvOrThrow: jest.fn(),
+  runAgentDeviceRemoteSessionAsync: jest.fn(),
+}));
+
+const graphqlClient = { query: jest.fn() };
+const ctx = { graphqlClient } as unknown as CustomBuildContext;
+const sessionEnv = {
+  deviceRunSessionId: 'device-run-session-id',
+  ngrokTunnelDomain: 'tunnel.example.com',
+  ngrokAuthtoken: 'ngrok-token',
+};
+
+type Device = Parameters<typeof runAgentDeviceRemoteSessionAsync>[1]['device'];
+let deviceLaunch: unknown;
+
+function runDevicePreparationAsync(device: Device): Promise<unknown> {
+  return (
+    'iosSimulatorUdid' in device ? (device.application ?? Promise.resolve()) : device.ready
+  ).then(async launch => {
+    deviceLaunch = launch;
+    return launch;
+  });
+}
+
+function deferred<T = void>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (err: Error) => void;
+} {
+  let resolve!: (value: T) => void;
+  let reject!: (err: Error) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  promise.catch(() => {});
+  return { promise, resolve, reject };
+}
+
+async function flushAsync(): Promise<void> {
+  for (let i = 0; i < 20; i++) {
+    await new Promise(resolve => setImmediate(resolve));
+  }
+}
+
+function runStep(
+  runtimePlatform: BuildRuntimePlatform,
+  inputValues: Record<string, unknown> = {},
+  signal?: AbortSignal,
+  stepCtx: CustomBuildContext = ctx
+): Promise<void> {
+  const buildFunction = createStartAgentDeviceSessionBuildFunction(stepCtx);
+  const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+  const inputs = Object.fromEntries(
+    [
+      'device_identifier',
+      'system_image_package',
+      'lcd_width',
+      'lcd_height',
+      'lcd_density',
+      'build_id',
+      'application_archive_url',
+      'launch_args',
+      'open_url',
+      'network_capture',
+      'network_capture_fields',
+      'public_preview',
+      'private_preview_url',
+      'frame_ancestors',
+      'cors_origins',
+      'package_version',
+      'max_idle_time_minutes',
+      'max_duration_seconds',
+    ].map(id => [id, { value: inputValues[id] }])
+  );
+  return buildFunction.fn!(
+    {
+      logger,
+      global: {
+        runtimePlatform,
+        staticContext: { job: { secrets: { robotAccessToken: 'robot-token' } } },
+      },
+    } as unknown as BuildStepContext,
+    { inputs, outputs: {}, env: {}, signal } as never
+  ) as Promise<void>;
+}
+
+function sessionDevice(): Device {
+  return jest.mocked(runAgentDeviceRemoteSessionAsync).mock.calls[0][1].device;
+}
+
+describe(createStartAgentDeviceSessionBuildFunction, () => {
+  beforeEach(() => {
+    deviceLaunch = undefined;
+    jest.clearAllMocks();
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue(null);
+    jest.mocked(startLocalEgressGuardRelayAsync).mockResolvedValue(undefined);
+    jest.mocked(IosSimulatorUtils.getDeviceAsync).mockResolvedValue({ state: 'Shutdown' } as never);
+    jest.mocked(spawn).mockResolvedValue({ stdout: '' } as never);
+    jest.mocked(IosSimulatorUtils.resolveUdidAsync).mockResolvedValue('selected-udid' as never);
+    jest
+      .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+      .mockResolvedValue([{ name: 'iPhone 17', udid: 'SELECTED-UDID' }] as never);
+    jest.mocked(getAgentDeviceRemoteSessionEnvOrThrow).mockReturnValue(sessionEnv);
+    jest
+      .mocked(runAgentDeviceRemoteSessionAsync)
+      .mockImplementation(async (_ctx, { device, tasks }) => {
+        await tasks.untilAborted(runDevicePreparationAsync(device));
+      });
+    jest.mocked(bootIosSimulatorAsync).mockResolvedValue({
+      deviceIdentifier: 'iPhone 17' as never,
+      udid: 'udid' as never,
+      displayName: 'iPhone 17',
+    });
+    jest.mocked(startAndroidEmulatorAsync).mockResolvedValue({
+      serialId: 'emulator-5554' as never,
+      emulatorPromise: Promise.resolve(),
+      shouldAdjustAnimationScale: true,
+    });
+    jest.mocked(downloadBuildAsync).mockResolvedValue({ artifactPath: '/tmp/App.app' });
+    jest
+      .mocked(installBuildAsync)
+      .mockResolvedValue({ applicationIdentifier: 'dev.example.app', activityName: '.Main' });
+    jest.mocked(launchApplicationAsync).mockResolvedValue(undefined);
+    jest.mocked(readIosApplicationIdentifierAsync).mockResolvedValue('dev.example.app');
+  });
+
+  it('hands guarded iOS boot to serve-sim and starts reporting before host startup', async () => {
+    const bootEnv = {
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+      SIMCTL_CHILD_EAS_EGRESS_GUARD_MODE: 'block',
+      SIMCTL_CHILD_http_proxy: 'http://127.0.0.1:8899',
+    };
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue(bootEnv);
+    await runStep(BuildRuntimePlatform.DARWIN, {
+      build_id: 'build-id',
+      launch_args: ['-flag'],
+      open_url: 'exp://example.test',
+    });
+    expect(
+      jest.mocked(selectXcodeDeveloperDirectoryAsync).mock.invocationCallOrder[0]
+    ).toBeLessThan(
+      jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mock.invocationCallOrder[0]
+    );
+    expect(startLocalEgressGuardRelayAsync).toHaveBeenCalledTimes(1);
+    expect(jest.mocked(startLocalEgressGuardRelayAsync).mock.invocationCallOrder[0]).toBeLessThan(
+      jest.mocked(runAgentDeviceRemoteSessionAsync).mock.invocationCallOrder[0]
+    );
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        buildId: 'build-id',
+        extensions: ['app'],
+        graphqlClient,
+        robotAccessToken: 'robot-token',
+      })
+    );
+    expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledTimes(1);
+    const device = sessionDevice();
+    expect(device).toEqual({
+      iosSimulatorUdid: 'SELECTED-UDID',
+      bootEnv,
+      application: expect.any(Promise),
+    });
+    expect(spawn).not.toHaveBeenCalled();
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledWith({
+      artifactPath: '/tmp/App.app',
+      env: {},
+    });
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(deviceLaunch).toEqual({
+      installAppPath: '/tmp/App.app',
+      launchAppIdentifier: 'dev.example.app',
+      launchArgs: ['-flag'],
+      openUrl: 'exp://example.test',
+    });
+  });
+
+  it('shuts down only the selected guarded Booted device before host startup', async () => {
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue({
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+    });
+    jest.mocked(IosSimulatorUtils.getDeviceAsync).mockResolvedValue({ state: 'Booted' } as never);
+    await runStep(BuildRuntimePlatform.DARWIN);
+    expect(IosSimulatorUtils.getDeviceAsync).toHaveBeenCalledWith({
+      udid: 'SELECTED-UDID',
+      env: {},
+    });
+    expect(spawn).toHaveBeenCalledTimes(1);
+    expect(spawn).toHaveBeenCalledWith('xcrun', ['simctl', 'shutdown', 'SELECTED-UDID'], {
+      env: {},
+      logger: expect.any(Object),
+      signal: expect.any(AbortSignal),
+    });
+    expect(jest.mocked(spawn).mock.invocationCallOrder[0]).toBeLessThan(
+      jest.mocked(runAgentDeviceRemoteSessionAsync).mock.invocationCallOrder[0]
+    );
+  });
+
+  it('downloads build_id through the device run session worker API when the job has a session token', async () => {
+    const sessionCtx = {
+      graphqlClient,
+      env: { EAS_DEVICE_RUN_SESSION_TOKEN: 'session-token' },
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+    } as unknown as CustomBuildContext;
+
+    await runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id' }, undefined, sessionCtx);
+
+    expect(downloadBuildAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        buildId: 'build-id',
+        deviceRunSessionWorkerApi: expect.any(DeviceRunSessionWorkerApi),
+      })
+    );
+  });
+
+  it('does not use the worker API without a session token or for an archive URL', async () => {
+    await runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id' });
+    expect(downloadBuildAsync).toHaveBeenLastCalledWith(
+      expect.objectContaining({ buildId: 'build-id', deviceRunSessionWorkerApi: null })
+    );
+
+    const sessionCtx = {
+      graphqlClient,
+      env: { EAS_DEVICE_RUN_SESSION_TOKEN: 'session-token' },
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+    } as unknown as CustomBuildContext;
+    await runStep(
+      BuildRuntimePlatform.LINUX,
+      { application_archive_url: 'https://example.test/app.tar.gz' },
+      undefined,
+      sessionCtx
+    );
+    expect(downloadBuildAsync).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        applicationArchiveUrl: 'https://example.test/app.tar.gz',
+        deviceRunSessionWorkerApi: null,
+      })
+    );
+  });
+
+  it('fails before download or host startup when guarded device shutdown fails', async () => {
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue({
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+    });
+    jest.mocked(IosSimulatorUtils.getDeviceAsync).mockResolvedValue({ state: 'Booted' } as never);
+    jest.mocked(spawn).mockRejectedValue(new Error('shutdown failed'));
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'shutdown failed'
+    );
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+    expect(stopLocalEgressResourcesAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('provides Simulator preparation and downloaded startup options to the remote session', async () => {
+    const hostReady = deferred();
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue({
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+    });
+    jest.mocked(runAgentDeviceRemoteSessionAsync).mockImplementation(async (_ctx, { device }) => {
+      expect('iosSimulatorUdid' in device).toBe(true);
+      if (!('iosSimulatorUdid' in device)) {
+        return;
+      }
+      await hostReady.promise;
+      deviceLaunch = await device.application;
+    });
+    const step = runStep(BuildRuntimePlatform.DARWIN, {
+      device_identifier: 'iPhone 17',
+      build_id: 'build-id',
+      launch_args: ['-flag'],
+      open_url: 'exp://example.test',
+    });
+    await flushAsync();
+    expect(IosSimulatorUtils.resolveUdidAsync).toHaveBeenCalledWith({
+      deviceIdentifier: 'iPhone 17',
+      env: {},
+    });
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).toHaveBeenCalledTimes(1);
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledWith({
+      artifactPath: '/tmp/App.app',
+      env: {},
+    });
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(deviceLaunch).toBeUndefined();
+    hostReady.resolve();
+    await step;
+    expect(deviceLaunch).toEqual({
+      installAppPath: '/tmp/App.app',
+      launchAppIdentifier: 'dev.example.app',
+      launchArgs: ['-flag'],
+      openUrl: 'exp://example.test',
+    });
+  });
+
+  it('fails a guarded session before download or host startup if its boot files are missing', async () => {
+    jest
+      .mocked(resolveLocalEgressServeSimBootEnvironmentAsync)
+      .mockRejectedValue(new Error('missing bin/egress-guard-check'));
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'missing bin/egress-guard-check'
+    );
+    expect(startLocalEgressGuardRelayAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(IosSimulatorUtils.getDeviceAsync).not.toHaveBeenCalled();
+    expect(spawn).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+    expect(stopLocalEgressResourcesAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('releases guard reporting and egress resources when host startup fails', async () => {
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue({
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+    });
+    jest
+      .mocked(runAgentDeviceRemoteSessionAsync)
+      .mockRejectedValueOnce(new Error('guard check failed'));
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'guard check failed'
+    );
+    expect(startLocalEgressGuardRelayAsync).toHaveBeenCalledTimes(1);
+    expect(stopLocalEgressResourcesAsync).toHaveBeenCalledTimes(1);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+  });
+
+  it('waits for the download before handing the app to the host', async () => {
+    const download = deferred<{ artifactPath: string }>();
+    jest.mocked(downloadBuildAsync).mockReturnValue(download.promise);
+
+    const step = runStep(BuildRuntimePlatform.DARWIN, {
+      application_archive_url: 'https://example.test/app.tar.gz',
+    });
+    await flushAsync();
+    expect(installBuildAsync).not.toHaveBeenCalled();
+
+    download.resolve({ artifactPath: '/tmp/App.app' });
+    await step;
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledTimes(1);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+  });
+
+  it('passes the selected Simulator to the host even when there is no app', async () => {
+    await runStep(BuildRuntimePlatform.DARWIN);
+
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(sessionDevice()).toEqual({
+      iosSimulatorUdid: 'SELECTED-UDID',
+      bootEnv: undefined,
+      application: undefined,
+    });
+  });
+
+  it('boots the Android Emulator with the device inputs', async () => {
+    await runStep(BuildRuntimePlatform.LINUX, {
+      device_identifier: 'pixel_7',
+      system_image_package: 'system-images;android-35-ext15;google_apis_playstore;x86_64',
+      lcd_width: 720,
+      lcd_height: 1600,
+      lcd_density: 300,
+      build_id: 'build-id',
+    });
+
+    expect(selectXcodeDeveloperDirectoryAsync).not.toHaveBeenCalled();
+    expect(startAndroidEmulatorAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        deviceIdentifier: 'pixel_7',
+        systemImagePackage: 'system-images;android-35-ext15;google_apis_playstore;x86_64',
+        lcdWidth: 720,
+        lcdHeight: 1600,
+        lcdDensity: 300,
+      })
+    );
+    expect(downloadBuildAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ extensions: ['apk'] })
+    );
+    expect(launchApplicationAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ applicationIdentifier: 'dev.example.app', activityName: '.Main' })
+    );
+  });
+
+  it('fails the session when the download fails, without an unhandled rejection', async () => {
+    jest.mocked(downloadBuildAsync).mockRejectedValue(new Error('download failed'));
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'download failed'
+    );
+    expect(installBuildAsync).not.toHaveBeenCalled();
+  });
+
+  /** A download that runs until its abort signal fires, like a stalled one. */
+  function mockStalledDownload(): { aborted: () => boolean; settled: () => boolean } {
+    let aborted = false;
+    let settled = false;
+    jest.mocked(downloadBuildAsync).mockImplementation(
+      ({ signal }) =>
+        new Promise((_resolve, reject) => {
+          signal!.addEventListener('abort', () => {
+            aborted = true;
+            // Settles a bit later, like a request that winds down.
+            setImmediate(() => {
+              settled = true;
+              reject(new Error('The user aborted a request.'));
+            });
+          });
+        })
+    );
+    return { aborted: () => aborted, settled: () => settled };
+  }
+
+  /** Runs the session like the real one: fails with the daemon, then waits for every part. */
+  function mockSessionWithFailingDaemon(beforeFailure?: () => Promise<void>): void {
+    jest
+      .mocked(runAgentDeviceRemoteSessionAsync)
+      .mockImplementation(async (_ctx, { tasks, device }) => {
+        const ready = runDevicePreparationAsync(device);
+        await beforeFailure?.();
+        const daemon = tasks.run('agent-device daemon', async () => {
+          throw new Error('daemon failed');
+        });
+        try {
+          await Promise.all([daemon, ready]);
+        } finally {
+          await Promise.allSettled([daemon, ready]);
+        }
+      });
+  }
+
+  it('stops the download and waits for it when Android boot fails', async () => {
+    const download = mockStalledDownload();
+    jest.mocked(startAndroidEmulatorAsync).mockRejectedValue(new Error('boot failed'));
+
+    await expect(runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id' })).rejects.toThrow(
+      'boot failed'
+    );
+
+    expect(download.aborted()).toBe(true);
+    // The step returned only after the download stopped.
+    expect(download.settled()).toBe(true);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+  });
+
+  it('stops a stalled download and does not install when the daemon fails', async () => {
+    const download = mockStalledDownload();
+    mockSessionWithFailingDaemon();
+
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'daemon failed'
+    );
+
+    expect(download.aborted()).toBe(true);
+    expect(download.settled()).toBe(true);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+  });
+
+  it('drains the download when host startup fails before app preparation', async () => {
+    const download = mockStalledDownload();
+    jest.mocked(runAgentDeviceRemoteSessionAsync).mockRejectedValue(new Error('host failed'));
+
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'host failed'
+    );
+    expect(download.aborted()).toBe(true);
+    expect(download.settled()).toBe(true);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+  });
+
+  it('does not start work for an already cancelled step', async () => {
+    const controller = new AbortController();
+    controller.abort(new Error('cancelled'));
+
+    await expect(
+      runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' }, controller.signal)
+    ).rejects.toThrow('cancelled');
+    expect(selectXcodeDeveloperDirectoryAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('cancels and drains a pending download through the external signal', async () => {
+    const controller = new AbortController();
+    const download = mockStalledDownload();
+    const step = runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' }, controller.signal);
+    const failure = expect(step).rejects.toThrow('cancelled');
+    await flushAsync();
+    controller.abort(new Error('cancelled'));
+
+    await failure;
+    expect(download.aborted()).toBe(true);
+    expect(download.settled()).toBe(true);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+  });
+
+  it('does not start device or download work after cancellation during Xcode selection', async () => {
+    const controller = new AbortController();
+    const selected = deferred();
+    jest.mocked(selectXcodeDeveloperDirectoryAsync).mockReturnValue(selected.promise);
+    const step = runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' }, controller.signal);
+    const failure = expect(step).rejects.toThrow('cancelled');
+    await flushAsync();
+    controller.abort(new Error('cancelled'));
+    selected.resolve();
+
+    await failure;
+    expect(IosSimulatorUtils.resolveUdidAsync).not.toHaveBeenCalled();
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('drains app preparation when the daemon fails', async () => {
+    const metadata = deferred<string>();
+    const metadataStarted = deferred();
+    jest.mocked(readIosApplicationIdentifierAsync).mockImplementation(() => {
+      metadataStarted.resolve();
+      return metadata.promise;
+    });
+    mockSessionWithFailingDaemon(async () => {
+      await metadataStarted.promise;
+      setImmediate(() => metadata.resolve('dev.example.app'));
+    });
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'daemon failed'
+    );
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledTimes(1);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(deviceLaunch).toBeUndefined();
+  });
+
+  it('rejects conflicting application inputs before it boots anything', async () => {
+    await expect(
+      runStep(BuildRuntimePlatform.DARWIN, {
+        build_id: 'build-id',
+        application_archive_url: 'https://example.test/app.tar.gz',
+      })
+    ).rejects.toThrow('Pass only one of build_id or application_archive_url.');
+    await expect(
+      runStep(BuildRuntimePlatform.DARWIN, { open_url: 'exp://example.test' })
+    ).rejects.toThrow('launch_args and open_url need an application');
+
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('declares the step inputs', () => {
+    const buildFunction = createStartAgentDeviceSessionBuildFunction(ctx);
+    const globalCtx = createGlobalContextMock();
+
+    expect(
+      buildFunction.inputProviders?.map(provider => provider(globalCtx, 'Test step').id)
+    ).toEqual([
+      'device_identifier',
+      'system_image_package',
+      'lcd_width',
+      'lcd_height',
+      'lcd_density',
+      'build_id',
+      'application_archive_url',
+      'launch_args',
+      'open_url',
+      'network_capture',
+      'network_capture_fields',
+      'public_preview',
+      'private_preview_url',
+      'frame_ancestors',
+      'cors_origins',
+      'package_version',
+      'max_idle_time_minutes',
+      'max_duration_seconds',
+    ]);
+  });
+
+  it.each([undefined, true, false])(
+    'passes public_preview=%s to the iOS session host',
+    async publicPreview => {
+      await runStep(BuildRuntimePlatform.DARWIN, {
+        public_preview: publicPreview,
+        private_preview_url: 'https://expo.dev/private-preview',
+      });
+      expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledWith(
+        ctx,
+        expect.objectContaining({
+          disableShare: publicPreview === false,
+          privatePreviewUrl: 'https://expo.dev/private-preview',
+        })
+      );
+    }
+  );
+
+  it('passes frame_ancestors to the session host', async () => {
+    await runStep(BuildRuntimePlatform.DARWIN, {
+      frame_ancestors: ['https://embed.example.test'],
+    });
+    expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ frameAncestors: ['https://embed.example.test'] })
+    );
+  });
+
+  it('passes cors_origins to the session host', async () => {
+    await runStep(BuildRuntimePlatform.DARWIN, {
+      cors_origins: ['https://app.example.test'],
+    });
+    expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+  });
+
+  it.each([
+    ['argument count', { launch_args: Array(257).fill('a') }],
+    ['argument length', { launch_args: ['a'.repeat(9000)] }],
+    ['NUL argument', { launch_args: ['a\u0000b'] }],
+    ['total UTF-8 bytes', { launch_args: Array(8).fill('😃'.repeat(4096)) }],
+    ['NUL URL', { open_url: 'example:\u0000screen' }],
+    ['URL length', { open_url: `example://${'a'.repeat(8192)}` }],
+  ])('rejects iOS launch %s before startup work', async (_name, inputs) => {
+    const step = runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id', ...inputs });
+    await expect(step).rejects.toBeInstanceOf(UserError);
+    expect(selectXcodeDeveloperDirectoryAsync).not.toHaveBeenCalled();
+    expect(IosSimulatorUtils.resolveUdidAsync).not.toHaveBeenCalled();
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    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 });
+    expect(launchApplicationAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX, launchArgs })
+    );
+  });
+
+  it('passes network capture to the session', async () => {
+    await runStep(BuildRuntimePlatform.DARWIN, {
+      network_capture: true,
+      network_capture_fields: ['header', 'response-body'],
+    });
+
+    expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        capture: { networkCapture: true, networkCaptureFields: ['header', 'response-body'] },
+      })
+    );
+  });
+
+  it('rejects network capture on Android before it boots anything', async () => {
+    await expect(
+      runStep(BuildRuntimePlatform.LINUX, { network_capture: true, system_image_package: 'x' })
+    ).rejects.toThrow('records traffic through serve-sim on an iOS simulator');
+    expect(startAndroidEmulatorAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+  });
+});

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

@@ -8,6 +8,7 @@ import {
   AndroidVirtualDeviceName,
 } from '../../../utils/AndroidEmulatorUtils';
 import { retryAsync } from '../../../utils/retry';
+import { resolveAndroidEmulatorLocalEgressAsync } from '../../utils/androidLocalEgress';
 import { createStartAndroidEmulatorBuildFunction } from '../startAndroidEmulator';
 
 jest.mock('@expo/turtle-spawn', () => ({
@@ -19,6 +20,10 @@ jest.mock('../../../utils/retry', () => ({
   retryAsync: jest.fn(),
 }));
 
+jest.mock('../../utils/androidLocalEgress', () => ({
+  resolveAndroidEmulatorLocalEgressAsync: jest.fn(),
+}));
+
 jest.mock('../../../utils/AndroidEmulatorUtils', () => ({
   AndroidEmulatorUtils: {
     defaultSystemImagePackage: 'system-images;android-30;default;x86_64',
@@ -35,6 +40,7 @@ jest.mock('../../../utils/AndroidEmulatorUtils', () => ({
 const mockedSpawn = jest.mocked(spawn);
 const mockedRetryAsync = jest.mocked(retryAsync);
 const mockedAndroidUtils = jest.mocked(AndroidEmulatorUtils);
+const mockedResolveLocalEgress = jest.mocked(resolveAndroidEmulatorLocalEgressAsync);
 const mockedMkdtemp = jest.spyOn(fs.promises, 'mkdtemp');
 function createStep(callInputs?: Record<string, unknown>, envOverrides?: NodeJS.ProcessEnv) {
   const logger = createMockLogger();
@@ -65,6 +71,7 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
     mockedAndroidUtils.waitForReadyAsync.mockResolvedValue(undefined);
     mockedAndroidUtils.disableWindowAndTransitionAnimationsAsync.mockResolvedValue(undefined);
     mockedAndroidUtils.deleteAsync.mockResolvedValue(undefined);
+    mockedResolveLocalEgress.mockResolvedValue(null);
 
     mockedRetryAsync.mockImplementation(async (fn, { retryOptions }) => {
       let lastErr: unknown;
@@ -83,6 +90,82 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
     mockedMkdtemp.mockRestore();
   });
 
+  describe('local egress', () => {
+    function createLocalEgress() {
+      return {
+        launchGate: {
+          emulatorArgs: ['-http-proxy', '127.0.0.1:8898', '-no-metrics'],
+          wrapperCommand: 'bash',
+          wrapperArgs: ['-c', 'gate', 'eas-egress-gate'],
+          admitAsync: jest.fn(),
+        },
+        networkReadyTarget: { host: '192.0.2.1', port: 443 },
+        configureBootedEmulatorAsync: jest.fn().mockResolvedValue(undefined),
+      };
+    }
+
+    it('starts the emulator exactly as before without a local egress session', async () => {
+      await createStep().executeAsync();
+
+      expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith({
+        deviceName: 'EasAndroidDevice01',
+        env: expect.any(Object),
+        logcatDirectory: '/tmp/logcat-directory',
+      });
+      expect(mockedAndroidUtils.waitForReadyAsync).toHaveBeenCalledWith({
+        env: expect.any(Object),
+        serialId: 'emulator-default',
+        timeoutMs: 60_000,
+        logger: expect.anything(),
+      });
+      expect(
+        mockedSpawn.mock.calls.filter(
+          ([command, args]) =>
+            ['sudo', 'nft', 'systemd-run'].includes(command) ||
+            (command === 'adb' && (args.includes('reverse') || args.includes('http_proxy')))
+        )
+      ).toEqual([]);
+    });
+
+    it('fences, gates and configures the emulator', async () => {
+      const localEgress = createLocalEgress();
+      mockedResolveLocalEgress.mockResolvedValue(localEgress);
+      mockedAndroidUtils.startAsync.mockResolvedValueOnce(createStartResult('emulator-base'));
+
+      await createStep().executeAsync();
+
+      expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ launchGate: localEgress.launchGate })
+      );
+      expect(mockedAndroidUtils.waitForReadyAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ networkReadyTarget: { host: '192.0.2.1', port: 443 } })
+      );
+      expect(localEgress.configureBootedEmulatorAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ serialId: 'emulator-base' })
+      );
+    });
+
+    it('retries a boot whose local egress configuration fails', async () => {
+      const localEgress = createLocalEgress();
+      localEgress.configureBootedEmulatorAsync
+        .mockRejectedValueOnce(new Error('netsimd outside the fence'))
+        .mockResolvedValueOnce(undefined);
+      mockedResolveLocalEgress.mockResolvedValue(localEgress);
+      mockedAndroidUtils.startAsync
+        .mockResolvedValueOnce(createStartResult('emulator-1111'))
+        .mockResolvedValueOnce(createStartResult('emulator-2222'));
+
+      await createStep().executeAsync();
+
+      expect(mockedAndroidUtils.deleteAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ serialId: 'emulator-1111' })
+      );
+      expect(localEgress.configureBootedEmulatorAsync).toHaveBeenLastCalledWith(
+        expect.objectContaining({ serialId: 'emulator-2222' })
+      );
+    });
+  });
+
   it('passes profile and LCD inputs to emulator creation', async () => {
     const systemImagePackage = 'system-images;android-35;default;x86_64';
     await createStep({

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

@@ -1,4 +1,4 @@
-import { BuildRuntimePlatform } from '@expo/steps';
+import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
 import fs from 'node:fs';
 
@@ -6,7 +6,19 @@ import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
 import { AndroidEmulatorUtils } from '../../../utils/AndroidEmulatorUtils';
 import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
-import { selectXcodeDeveloperDirectoryAsync } from '../../utils/remoteDeviceRunSession';
+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 {
   createStartAppiumRemoteSessionBuildFunction,
@@ -19,13 +31,45 @@ 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(),
 }));
 jest.mock('@expo/turtle-spawn', () => ({ __esModule: true, default: jest.fn() }));
+jest.mock('../../../sentry');
+jest.mock('../../../utils/retry', () => ({
+  ...jest.requireActual('../../../utils/retry'),
+  sleepAsync: jest.fn(),
+}));
+jest.mock('../../../utils/turtleFetch', () => ({
+  ...jest.requireActual('../../../utils/turtleFetch'),
+  turtleFetch: jest.fn(),
+}));
+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(),
+}));
 
 const logger = { info: jest.fn(), warn: jest.fn() } as never;
 
@@ -51,23 +95,25 @@ describe(resolveAppiumDeviceAsync, () => {
   });
 
   it('returns XCUITest capabilities for the booted iOS simulator', async () => {
-    jest
-      .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
-      .mockResolvedValue([{ udid: 'ios-simulator-id' } as never]);
+    jest.mocked(IosSimulatorUtils.getAvailableDevicesAsync).mockResolvedValue([
+      {
+        udid: 'ios-simulator-id',
+        runtime: 'com.apple.CoreSimulator.SimRuntime.iOS-26-5',
+      } as never,
+    ]);
 
     await expect(
       resolveAppiumDeviceAsync({
         runtimePlatform: BuildRuntimePlatform.DARWIN,
         env: {},
-        logger,
       })
     ).resolves.toEqual({
       platformName: 'iOS',
       automationName: 'XCUITest',
       driverName: 'xcuitest',
       udid: 'ios-simulator-id',
+      runtimeIdentifier: 'com.apple.CoreSimulator.SimRuntime.iOS-26-5',
     });
-    expect(selectXcodeDeveloperDirectoryAsync).toHaveBeenCalledWith({ env: {}, logger });
     expect(IosSimulatorUtils.getAvailableDevicesAsync).toHaveBeenCalledWith({
       env: {},
       filter: 'booted',
@@ -83,7 +129,6 @@ describe(resolveAppiumDeviceAsync, () => {
       resolveAppiumDeviceAsync({
         runtimePlatform: BuildRuntimePlatform.LINUX,
         env: {},
-        logger,
       })
     ).resolves.toEqual({
       platformName: 'Android',
@@ -164,6 +209,501 @@ describe('createStartAppiumRemoteSessionBuildFunction', () => {
 
     expect(
       buildFunction.inputProviders?.map(provider => provider(globalCtx, 'Test step').id)
-    ).toEqual(expect.arrayContaining(['launch_app_identifier', 'launch_args', 'open_url']));
+    ).toEqual(
+      expect.arrayContaining([
+        'launch_app_identifier',
+        'launch_args',
+        'open_url',
+        'public_preview',
+        'private_preview_url',
+      ])
+    );
+  });
+});
+
+describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () => {
+  const stopError = new Error('Process output drain timed out after 5000ms.');
+  const stopAppium = jest.fn();
+  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);
+    jest
+      .mocked(AndroidEmulatorUtils.getAttachedDevicesAsync)
+      .mockResolvedValue([{ serialId: 'emulator-5554', state: 'device' } as never]);
+    stopAppium.mockRejectedValue(stopError);
+    jest.mocked(spawnDetached).mockReturnValue({
+      pid: 4242,
+      getOutput: () => '',
+      getExitError: () => undefined,
+      stopAsync: stopAppium,
+    });
+    jest.mocked(turtleFetch).mockResolvedValue({ ok: true } as never);
+    stopEventCollection.mockResolvedValue(undefined);
+    jest.mocked(startAppiumEventCollectionAsync).mockResolvedValue({
+      stopAsync: stopEventCollection,
+      getLastEventObservedAt: () => undefined,
+    });
+    jest.mocked(startNgrokTunnelAsync).mockResolvedValue({
+      url: 'https://appium-abc.tunnel.example.com',
+      subdomainId: 'appium-abc',
+      stopAsync: jest.fn(),
+    });
+    jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
+      openPreviewAsync: jest.fn().mockResolvedValue({
+        previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        apiUrl: 'https://web-preview.tunnel.example.com',
+        closeAsync: jest.fn(),
+      }),
+      getLastPreviewActivityAt: jest.fn(),
+      finishAsync: jest.fn(),
+    });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  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 },
+      } as unknown as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: maxIdleTimeMinutes },
+          ...startupInputs,
+        },
+        outputs: {},
+        env: {
+          DEVICE_RUN_SESSION_ID: 'device-run-session-id',
+          EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN: 'tunnel.example.com',
+          NGROK_AUTHTOKEN: 'ngrok-token',
+        },
+      } as never
+    );
+  }
+
+  function expectAppiumStoppedAndHomeRemoved(logger: { warn: jest.Mock }): void {
+    expect(stopAppium).toHaveBeenCalledTimes(1);
+    expect(fs.existsSync(jest.mocked(spawnDetached).mock.calls[0][0].env.APPIUM_HOME!)).toBe(false);
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: stopError },
+      'Could not stop the Appium server during remote session teardown.'
+    );
+  }
+
+  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: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: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);
+    jest.mocked(sleepAsync).mockImplementation(async ms => {
+      now += ms;
+    });
+    jest.mocked(turtleFetch).mockRejectedValue(new Error('connect ECONNREFUSED'));
+    const logger = { info: jest.fn(), warn: jest.fn() };
+
+    await expect(runSessionAsync(logger)).rejects.toThrow(
+      'Timed out waiting for Appium to become ready.'
+    );
+    expectAppiumStoppedAndHomeRemoved(logger);
+    expect(startAppiumEventCollectionAsync).not.toHaveBeenCalled();
+    expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+  });
+
+  it('keeps the event collection error when Appium cannot be stopped', async () => {
+    const collectionError = new Error('event collection failed');
+    jest.mocked(startAppiumEventCollectionAsync).mockRejectedValueOnce(collectionError);
+    const logger = { info: jest.fn(), warn: jest.fn() };
+
+    await expect(runSessionAsync(logger)).rejects.toBe(collectionError);
+    expectAppiumStoppedAndHomeRemoved(logger);
+    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

@@ -6,9 +6,13 @@ import path from 'node:path';
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
-import { isProcessDescendantOfAsync } from '../../../utils/processes';
+import { Sentry } from '../../../sentry';
+import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import { startDeviceSessionHostAsync } from '../../utils/deviceSessionHost';
+import { isProcessDescendantOfAsync, killProcessGroup } from '../../../utils/processes';
 import { pollArgentArtifactsForUploadAsync } from '../../utils/argentArtifacts';
 import { startArgentEventCollectionAsync } from '../../utils/argentEvents';
+import { createProcessOutput } from '../../utils/processOutput';
 import {
   ensureFfmpegInstalledOnceAsync,
   getDeviceRunSessionIdOrThrow,
@@ -16,12 +20,12 @@ import {
   getNgrokTunnelDomainOrThrow,
   selectXcodeDeveloperDirectoryAsync,
   spawnDetached,
-  startDeviceWebPreviewWithTunnelAsync,
   startNgrokTunnelAsync,
   uploadRemoteSessionConfigAsync,
   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
@@ -36,21 +40,42 @@ 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(),
+  finishRemoteSessionAsync: jest.requireActual('../../utils/remoteDeviceRunSession')
+    .finishRemoteSessionAsync,
   getDeviceRunSessionIdOrThrow: jest.fn(),
   getNgrokAuthtokenOrThrow: jest.fn(),
   getNgrokTunnelDomainOrThrow: jest.fn(),
   selectXcodeDeveloperDirectoryAsync: jest.fn(),
   spawnDetached: jest.fn(),
-  startDeviceWebPreviewWithTunnelAsync: jest.fn(),
   startNgrokTunnelAsync: jest.fn(),
   uploadRemoteSessionConfigAsync: jest.fn(),
   waitForDeviceRunSessionStoppedAsync: jest.fn(),
@@ -86,6 +111,7 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     jest.mocked(spawnDetached).mockReturnValue({
       pid: 4242,
       getOutput: () => '',
+      getExitError: () => undefined,
       stopAsync: jest.fn(),
     });
     jest.mocked(startNgrokTunnelAsync).mockResolvedValue({
@@ -93,10 +119,14 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
       subdomainId: 'argent-abc',
       stopAsync: mockTunnelStopAsync,
     });
-    jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockResolvedValue({
-      previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
-      apiUrl: 'https://web-preview.tunnel.example.com',
-      stopAsync: mockPreviewStopAsync,
+    jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
+      openPreviewAsync: jest.fn().mockResolvedValue({
+        previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        apiUrl: 'https://web-preview.tunnel.example.com',
+        closeAsync: jest.fn(),
+      }),
+      getLastPreviewActivityAt: jest.fn(),
+      finishAsync: mockPreviewStopAsync,
     });
     jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
@@ -113,7 +143,188 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     await fs.promises.rm(TEST_HOME, { recursive: true, force: true });
   });
 
-  it('enables the event log flag, shares one path, and starts/stops the collector', async () => {
+  it('reports an early exit with output and stops Argent before opening tunnels', async () => {
+    const stopError = new Error('drain timed out');
+    const stopServer = jest.fn().mockRejectedValue(stopError);
+    jest.mocked(spawnDetached).mockReturnValue({
+      pid: 4242,
+      getOutput: () => 'could not bind server port',
+      getExitError: () => new Error('process exited with code 1'),
+      stopAsync: stopServer,
+    });
+    const logger = { info: jest.fn(), warn: jest.fn() };
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+    await expect(
+      buildFunction.fn!(
+        {
+          logger,
+          global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+        } as unknown as BuildStepContext,
+        {
+          inputs: {
+            package_version: { value: undefined },
+            max_idle_time_minutes: { value: undefined },
+          },
+          outputs: {},
+          env: {},
+        } as never
+      )
+    ).rejects.toThrow(
+      'Argent exited before becoming ready: process exited with code 1\nArgent tool-server output:\ncould not bind server port'
+    );
+    expect(stopServer).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: stopError },
+      'Could not stop the Argent tool-server during remote session teardown.'
+    );
+    expect(pollArgentArtifactsForUploadAsync).not.toHaveBeenCalled();
+    expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+    expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    expect(startArgentEventCollectionAsync).not.toHaveBeenCalled();
+  });
+
+  it('drains artifact polling and stops the tool-server when event collection cannot start', async () => {
+    const collectionError = new Error('event collection failed');
+    const stopError = new Error('drain timed out');
+    let pollingFinished = false;
+    jest
+      .mocked(pollArgentArtifactsForUploadAsync)
+      .mockImplementationOnce(async (_ctx, { signal }) => {
+        await new Promise(resolve => signal.addEventListener('abort', resolve, { once: true }));
+        pollingFinished = true;
+      });
+    jest.mocked(startArgentEventCollectionAsync).mockRejectedValueOnce(collectionError);
+    const stopServer = jest.fn(async () => {
+      expect(pollingFinished).toBe(true);
+      throw stopError;
+    });
+    jest.mocked(spawnDetached).mockReturnValueOnce({
+      pid: 4242,
+      getOutput: () => '',
+      getExitError: () => undefined,
+      stopAsync: stopServer,
+    });
+    const logger = { info: jest.fn(), warn: jest.fn() };
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+    await expect(
+      buildFunction.fn!(
+        {
+          logger,
+          global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+        } as unknown as BuildStepContext,
+        {
+          inputs: {
+            package_version: { value: undefined },
+            max_idle_time_minutes: { value: undefined },
+          },
+          outputs: {},
+          env: {},
+        } as never
+      )
+    ).rejects.toBe(collectionError);
+    expect(pollingFinished).toBe(true);
+    expect(stopServer).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: stopError },
+      'Could not stop the Argent tool-server during remote session teardown.'
+    );
+    expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+    expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
+  });
+
+  it.each(['preview', 'config', 'wait'])(
+    'finishes the host and tools after %s fails',
+    async phase => {
+      const error = new Error(`${phase} failed`);
+      if (phase === 'preview') {
+        jest.mocked(startDeviceSessionHostAsync).mockResolvedValueOnce({
+          openPreviewAsync: jest.fn().mockRejectedValue(error),
+          getLastPreviewActivityAt: jest.fn(),
+          finishAsync: mockPreviewStopAsync,
+        });
+      } else if (phase === 'config') {
+        jest.mocked(uploadRemoteSessionConfigAsync).mockRejectedValueOnce(error);
+      } else {
+        jest.mocked(waitForDeviceRunSessionStoppedAsync).mockRejectedValueOnce(error);
+      }
+      const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+      await expect(
+        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: undefined },
+            },
+            outputs: {},
+            env: {},
+          } as never
+        )
+      ).rejects.toBe(error);
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockStopAsync).toHaveBeenCalledTimes(1);
+      expect(jest.mocked(spawnDetached).mock.results[0].value.stopAsync).toHaveBeenCalledTimes(1);
+    }
+  );
+
+  it.each([
+    ['succeeded', false],
+    ['failed', true],
+  ])(
+    'fails after stopping the host and tools when the tools tunnel cannot close and the session %s',
+    async (_description, sessionFails) => {
+      const closeError = new Error('ngrok close failed');
+      const sessionError = new Error('session failed');
+      mockTunnelStopAsync.mockRejectedValueOnce(closeError);
+      if (sessionFails) {
+        jest.mocked(waitForDeviceRunSessionStoppedAsync).mockRejectedValueOnce(sessionError);
+      }
+      const logger = { info: jest.fn(), warn: jest.fn() };
+      const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+      // The tunnel may still be serving, so its failure fails a session that otherwise succeeded.
+      await expect(
+        buildFunction.fn!(
+          {
+            logger,
+            global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+          } as unknown as BuildStepContext,
+          {
+            inputs: {
+              package_version: { value: undefined },
+              max_idle_time_minutes: { value: undefined },
+            },
+            outputs: {},
+            env: {},
+          } as never
+        )
+      ).rejects.toBe(sessionFails ? sessionError : closeError);
+      expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockStopAsync).toHaveBeenCalledTimes(1);
+      expect(jest.mocked(spawnDetached).mock.results[0].value.stopAsync).toHaveBeenCalledTimes(1);
+      expect(logger.warn).toHaveBeenCalledWith(
+        { err: closeError },
+        'Could not stop the Argent tunnel during remote session teardown.'
+      );
+      expect(jest.mocked(Sentry.capture).mock.calls).toEqual(
+        sessionFails
+          ? [
+              [
+                'Could not stop the Argent tunnel after the remote session failed',
+                closeError,
+                { level: 'warning' },
+              ],
+            ]
+          : []
+      );
+    }
+  );
+
+  it('enables the event log flag, disables the video watermark, shares one path, and starts/stops the collector', async () => {
     const ctx = {} as unknown as CustomBuildContext;
     const buildFunction = createStartArgentRemoteSessionBuildFunction(ctx);
 
@@ -156,6 +367,20 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
       jest.mocked(spawnDetached).mock.invocationCallOrder[0]
     );
 
+    // (2b) The video watermark flag is disabled, before the tool-server is launched.
+    const disableWatermarkIndex = spawnCalls.findIndex(
+      ([command, args]) =>
+        command === 'bun' &&
+        Array.isArray(args) &&
+        args[0] === 'x' &&
+        args.includes('disable') &&
+        args.includes('video-watermark')
+    );
+    expect(disableWatermarkIndex).toBeGreaterThanOrEqual(0);
+    expect(jest.mocked(spawn).mock.invocationCallOrder[disableWatermarkIndex]).toBeLessThan(
+      jest.mocked(spawnDetached).mock.invocationCallOrder[0]
+    );
+
     // (3) The tool-server and the collector are pinned to the exact same event log path.
     const serverEnv = jest.mocked(spawnDetached).mock.calls[0][0].env;
     expect(serverEnv.ARGENT_EVENT_LOG).toBe(EXPECTED_EVENT_LOG_PATH);
@@ -177,9 +402,9 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
       jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.invocationCallOrder[0]
     );
     expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
-    expect(startDeviceWebPreviewWithTunnelAsync).toHaveBeenCalledWith(
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
       ctx,
-      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX })
+      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX, disableShare: false })
     );
     expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -192,6 +417,194 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
   });
 
+  it('passes public_preview=false to the session host', async () => {
+    const ctx = {} as CustomBuildContext;
+    const buildFunction = createStartArgentRemoteSessionBuildFunction(ctx);
+    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: undefined },
+          public_preview: { value: false },
+          private_preview_url: { value: 'https://expo.dev/private-preview' },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        disableShare: true,
+        privatePreviewUrl: 'https://expo.dev/private-preview',
+      })
+    );
+  });
+
+  it('passes frame_ancestors to the session host', async () => {
+    const ctx = {} as CustomBuildContext;
+    const buildFunction = createStartArgentRemoteSessionBuildFunction(ctx);
+    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: undefined },
+          frame_ancestors: { value: ['https://embed.example.test'] },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ frameAncestors: ['https://embed.example.test'] })
+    );
+  });
+
+  it('passes cors_origins to the session host', async () => {
+    const ctx = {} as CustomBuildContext;
+    const buildFunction = createStartArgentRemoteSessionBuildFunction(ctx);
+    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: undefined },
+          cors_origins: { value: ['https://app.example.test'] },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+  });
+
+  it('continues the session when disabling the video watermark fails', async () => {
+    const error = new Error('bun x failed');
+    jest
+      .mocked(spawn)
+      .mockImplementation(
+        (_command, args) =>
+          (args.includes('video-watermark')
+            ? Promise.reject(error)
+            : Promise.resolve(undefined)) as never
+      );
+    const logger = { info: jest.fn(), warn: jest.fn() };
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+
+    await buildFunction.fn!(
+      {
+        logger,
+        global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+      } as unknown as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: undefined },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: error },
+      expect.stringContaining('Could not disable the Argent video watermark')
+    );
+    expect(spawnDetached).toHaveBeenCalledTimes(1);
+    expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledTimes(1);
+    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(
+      path.join(ARGENT_STATE_DIR, 'tool-server-orchestration.json'),
+      JSON.stringify({ port: 5678, pid: 9999, token })
+    );
+    const logger = { info: jest.fn(), warn: jest.fn() };
+    jest.mocked(spawnDetached).mockImplementationOnce(options => {
+      const output = createProcessOutput(options.logger, options.secrets);
+      output.stdout.append(`argent link argent://${encodeURIComponent(token)}@127.0.0.1:5678\n`);
+      return {
+        pid: 4242,
+        getOutput: output.getOutput,
+        getExitError: () => undefined,
+        stopAsync: async () => {
+          output.stderr.append(`opaque ${token}\nencoded ${encodeURIComponent(token)}\n`);
+          output.stderr.append(`escaped ${JSON.stringify(token).slice(1, -1)}\n`);
+          output.finish();
+        },
+      };
+    });
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+    await buildFunction.fn!(
+      {
+        logger,
+        global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+      } as unknown as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: undefined },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    expect(logger.info).toHaveBeenCalledWith(
+      { source: 'stdout' },
+      'argent link argent://[REDACTED]@127.0.0.1:5678'
+    );
+    for (const label of ['opaque', 'encoded', 'escaped']) {
+      expect(logger.info).toHaveBeenCalledWith({ source: 'stderr' }, `${label} [REDACTED]`);
+    }
+    expect(JSON.stringify(logger.info.mock.calls)).not.toContain('secret');
+  });
+
   it('hands the launch inputs to serve-sim and announces them on an iOS session', async () => {
     const ctx = {} as unknown as CustomBuildContext;
     const logger = { info: jest.fn(), warn: jest.fn() };
@@ -216,7 +629,7 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
       } as never
     );
 
-    expect(startDeviceWebPreviewWithTunnelAsync).toHaveBeenCalledWith(
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
       ctx,
       expect.objectContaining({
         runtimePlatform: BuildRuntimePlatform.DARWIN,
@@ -231,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() };
@@ -264,6 +951,59 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
 
     expect(
       buildFunction.inputProviders?.map(provider => provider(globalCtx, 'Test step').id)
-    ).toEqual(expect.arrayContaining(['launch_app_identifier', 'launch_args', 'open_url']));
+    ).toEqual(
+      expect.arrayContaining([
+        'launch_app_identifier',
+        'launch_args',
+        'open_url',
+        'public_preview',
+        'private_preview_url',
+      ])
+    );
+  });
+
+  it('stops automation without waiting for recording upload', async () => {
+    let release!: () => void;
+    let stopped!: () => void;
+    const pendingFinish = new Promise<void>(resolve => {
+      release = resolve;
+    });
+    const toolStopped = new Promise<void>(resolve => {
+      stopped = resolve;
+    });
+    mockPreviewStopAsync.mockReturnValueOnce(pendingFinish);
+    const stopServer = jest.fn(async () => {
+      stopped();
+    });
+    jest.mocked(spawnDetached).mockReturnValueOnce({
+      pid: 4242,
+      getOutput: () => '',
+      getExitError: () => undefined,
+      stopAsync: stopServer,
+    });
+    const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
+    const running = 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: undefined },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    try {
+      await toolStopped;
+      expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(stopServer).toHaveBeenCalledTimes(1);
+    } finally {
+      release();
+      await running;
+    }
   });
 });

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

@@ -94,6 +94,59 @@ describe(waitForArgentToolServerStateAsync, () => {
     return JSON.stringify({ port, pid, token });
   }
 
+  it('reports process exit instead of waiting for the startup timeout', async () => {
+    const getExitError = jest.fn(() => new Error('server exited with code 1'));
+    await expect(
+      waitForArgentToolServerStateAsync({
+        stateDir,
+        ancestorPid: process.pid,
+        timeoutMs: 100,
+        pollIntervalMs: 1,
+        getExitError,
+      })
+    ).rejects.toThrow('server exited with code 1');
+    expect(getExitError).toHaveBeenCalledTimes(1);
+  });
+
+  it('detects an exit after polling has begun', async () => {
+    const getExitError = jest
+      .fn<Error | undefined, []>()
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValue(new Error('server stopped'));
+    await expect(
+      waitForArgentToolServerStateAsync({
+        stateDir,
+        ancestorPid: process.pid,
+        timeoutMs: 100,
+        pollIntervalMs: 1,
+        getExitError,
+      })
+    ).rejects.toThrow('server stopped');
+    expect(getExitError).toHaveBeenCalledTimes(3);
+  });
+
+  it('rejects an exit observed while reading a matching state file', async () => {
+    await fs.promises.writeFile(
+      path.join(stateDir, 'tool-server.json'),
+      stateJson({ port: 4321, pid: process.pid })
+    );
+    const getExitError = jest
+      .fn<Error | undefined, []>()
+      .mockReturnValueOnce(undefined)
+      .mockReturnValue(new Error('server exited during startup'));
+    await expect(
+      waitForArgentToolServerStateAsync({
+        stateDir,
+        ancestorPid: process.ppid,
+        timeoutMs: 100,
+        pollIntervalMs: 1,
+        getExitError,
+      })
+    ).rejects.toThrow('server exited during startup');
+    expect(getExitError).toHaveBeenCalledTimes(2);
+  });
+
   it.each(['tool-server.json', 'tool-server-012345abcdef.json'])(
     'reads a matching process from %s',
     async fileName => {

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

@@ -1,7 +1,8 @@
 import { type bunyan } from '@expo/logger';
-import { type BuildStepContext } from '@expo/steps';
+import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
 import fs from 'node:fs';
 
+import { startAndroidLocalEgressAsync } from '../../utils/androidLocalEgress';
 import {
   LOCAL_EGRESS_HANDOFF_PATH,
   configureSystemProxyAsync,
@@ -20,6 +21,9 @@ jest.mock('../../utils/localEgress', () => ({
   startChiselServerAsync: jest.fn(),
   writeLocalEgressHandoffAsync: jest.fn(),
 }));
+jest.mock('../../utils/androidLocalEgress', () => ({
+  startAndroidLocalEgressAsync: jest.fn(),
+}));
 jest.mock('../../utils/localEgressGuard', () => ({
   stopLocalEgressGuardRelaysAsync: jest.fn().mockResolvedValue(undefined),
 }));
@@ -28,10 +32,16 @@ jest.mock('../../utils/remoteDeviceRunSession', () => ({
   startNgrokTunnelAsync: jest.fn(),
   getNgrokAuthtokenOrThrow: () => 'ngrok-token',
   getNgrokTunnelDomainOrThrow: () => 'example.com',
+  omitNgrokAuthtoken: jest.requireActual('../../utils/remoteDeviceRunSession').omitNgrokAuthtoken,
 }));
 
 const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
-const server = { pid: 12345, getOutput: () => '', stopAsync: jest.fn() };
+const server = {
+  pid: 12345,
+  getOutput: () => '',
+  getExitError: () => undefined,
+  stopAsync: jest.fn(),
+};
 const tunnel = {
   url: 'https://egress.example.com',
   subdomainId: 'egress-id',
@@ -47,6 +57,82 @@ async function start(signal?: AbortSignal): Promise<void> {
   });
 }
 
+async function startOn(runtimePlatform: BuildRuntimePlatform): Promise<void> {
+  await createStartLocalEgressBuildFunction().fn!(
+    { logger, global: { runtimePlatform } } as unknown as BuildStepContext,
+    {
+      env: {},
+      inputs: {},
+      outputs: {},
+    } as any
+  );
+}
+
+describe('local egress platforms', () => {
+  const androidStop = jest.fn();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(fs.promises, 'mkdtemp').mockResolvedValue('/tmp/egress-acquisition-test');
+    jest.spyOn(fs.promises, 'writeFile').mockResolvedValue(undefined);
+    jest.spyOn(fs.promises, 'rm').mockResolvedValue(undefined);
+    server.stopAsync.mockResolvedValue(undefined);
+    tunnel.stopAsync.mockResolvedValue(undefined);
+    androidStop.mockResolvedValue(undefined);
+    jest.mocked(findAvailablePortAsync).mockResolvedValue(52001);
+    jest.mocked(downloadChiselAsync).mockResolvedValue('/tmp/egress-acquisition-test/chisel');
+    jest.mocked(startChiselServerAsync).mockResolvedValue({ process: server, fingerprint: 'key=' });
+    jest.mocked(startNgrokTunnelAsync).mockResolvedValue(tunnel);
+    jest.mocked(configureSystemProxyAsync).mockResolvedValue({ service: 'Ethernet' });
+    jest.mocked(writeLocalEgressHandoffAsync).mockResolvedValue(undefined);
+    jest.mocked(startAndroidLocalEgressAsync).mockResolvedValue({ stopAsync: androidStop });
+  });
+
+  afterEach(async () => {
+    await stopLocalEgressResourcesAsync(logger);
+    jest.restoreAllMocks();
+  });
+
+  it('sets the macOS system proxy and writes the same handoff as before', async () => {
+    await startOn(BuildRuntimePlatform.DARWIN);
+    expect(configureSystemProxyAsync).toHaveBeenCalled();
+    expect(startAndroidLocalEgressAsync).not.toHaveBeenCalled();
+    expect(writeLocalEgressHandoffAsync).toHaveBeenCalledWith({
+      url: tunnel.url,
+      token: expect.any(String),
+      fingerprint: 'key=',
+      port: 8899,
+    });
+  });
+
+  it('starts the Android relay and fence on Linux instead of the system proxy', async () => {
+    await startOn(BuildRuntimePlatform.LINUX);
+    expect(configureSystemProxyAsync).not.toHaveBeenCalled();
+    expect(startAndroidLocalEgressAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        chiselPid: server.pid,
+        proxyPort: 8899,
+        controlPort: 52001,
+        workDir: '/tmp/egress-acquisition-test',
+      })
+    );
+    expect(writeLocalEgressHandoffAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ platform: 'android' })
+    );
+    await stopLocalEgressResourcesAsync(logger);
+    expect(androidStop).toHaveBeenCalledTimes(1);
+    expect(server.stopAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('releases the tunnel when the Android fence cannot start', async () => {
+    jest.mocked(startAndroidLocalEgressAsync).mockRejectedValue(new Error('nft failed'));
+    await expect(startOn(BuildRuntimePlatform.LINUX)).rejects.toThrow('nft failed');
+    expect(server.stopAsync).toHaveBeenCalledTimes(1);
+    expect(tunnel.stopAsync).toHaveBeenCalledTimes(1);
+    expect(writeLocalEgressHandoffAsync).not.toHaveBeenCalled();
+  });
+});
+
 describe('local egress acquisition', () => {
   beforeEach(() => {
     jest.clearAllMocks();

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

@@ -3,28 +3,46 @@ import { BuildRuntimePlatform, type BuildStepContext, type BuildStepEnv } from '
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
+import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import { startDeviceSessionHostAsync } from '../../utils/deviceSessionHost';
 import {
   getDeviceRunSessionIdOrThrow,
   getNgrokTunnelDomainOrThrow,
   selectXcodeDeveloperDirectoryAsync,
-  startDeviceWebPreviewWithTunnelAsync,
   uploadRemoteSessionConfigAsync,
   waitForDeviceRunSessionStoppedAsync,
 } from '../../utils/remoteDeviceRunSession';
 import { createStartWebPreviewRemoteSessionBuildFunction } from '../startWebPreviewRemoteSession';
 
+jest.mock('../../utils/deviceSessionHost');
+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/iosAppArtifact', () => ({
+  ...jest.requireActual('../../utils/iosAppArtifact'),
+  readIosApplicationIdentifierAsync: jest.fn().mockResolvedValue('dev.example.app'),
+}));
+jest.mock('../../utils/localEgressGuard', () => ({
+  resolveLocalEgressServeSimBootEnvironmentAsync: jest.fn().mockResolvedValue(null),
+}));
+
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
   getDeviceRunSessionIdOrThrow: jest.fn(),
   getNgrokTunnelDomainOrThrow: jest.fn(),
   selectXcodeDeveloperDirectoryAsync: jest.fn(),
-  startDeviceWebPreviewWithTunnelAsync: jest.fn(),
   uploadRemoteSessionConfigAsync: jest.fn(),
   waitForDeviceRunSessionStoppedAsync: jest.fn(),
 }));
 
 const ctx = {} as CustomBuildContext;
-const env = {} as BuildStepEnv;
+const env = { NGROK_AUTHTOKEN: 'ngrok-token', PATH: '/usr/bin' } as BuildStepEnv;
+const childEnv = { PATH: '/usr/bin' } as BuildStepEnv;
 const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
 const stopAsync = jest.fn();
 
@@ -56,10 +74,15 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     jest.mocked(getDeviceRunSessionIdOrThrow).mockReturnValue('device-run-session-id');
     jest.mocked(getNgrokTunnelDomainOrThrow).mockReturnValue('tunnel.example.com');
     jest.mocked(selectXcodeDeveloperDirectoryAsync).mockResolvedValue(undefined);
-    jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockResolvedValue({
-      previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
-      apiUrl: 'https://web-preview.example.test',
-      stopAsync,
+    jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
+      openPreviewAsync: jest.fn().mockResolvedValue({
+        previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        sharePageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        apiUrl: 'https://web-preview.example.test',
+        closeAsync: jest.fn(),
+      }),
+      getLastPreviewActivityAt: jest.fn(),
+      finishAsync: stopAsync,
     });
     jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
@@ -67,11 +90,16 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
   });
 
   it('reports the session token when serve-sim minted one', async () => {
-    jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockResolvedValue({
-      previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
-      apiUrl: 'https://web-preview.example.test',
-      previewToken: 'tok-1',
-      stopAsync,
+    jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
+      openPreviewAsync: jest.fn().mockResolvedValue({
+        previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        sharePageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        apiUrl: 'https://web-preview.example.test',
+        previewToken: 'tok-1',
+        closeAsync: jest.fn(),
+      }),
+      getLastPreviewActivityAt: jest.fn(),
+      finishAsync: stopAsync,
     });
 
     await runAsync(BuildRuntimePlatform.DARWIN);
@@ -79,36 +107,132 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
       expect.objectContaining({
         remoteConfig: {
+          webPreviewUrl: 'https://expo.dev/simulator-preview/preview-id',
           previewUrl: 'https://expo.dev/simulator-preview/preview-id',
           previewApiUrl: 'https://web-preview.example.test',
+          webPreviewToken: 'tok-1',
           previewToken: 'tok-1',
         },
       })
     );
   });
 
+  it('logs the authenticated link while publishing the public frame URL', async () => {
+    const privatePreviewUrl = 'https://expo.dev/private-preview';
+    jest.mocked(startDeviceSessionHostAsync).mockResolvedValueOnce({
+      openPreviewAsync: jest.fn().mockResolvedValue({
+        previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        sharePageUrl: privatePreviewUrl,
+        apiUrl: 'https://web-preview.example.test',
+        closeAsync: jest.fn(),
+      }),
+      getLastPreviewActivityAt: jest.fn(),
+      finishAsync: stopAsync,
+    });
+
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      public_preview: { value: false },
+      private_preview_url: { value: privatePreviewUrl },
+    });
+
+    expect(logger.info).toHaveBeenCalledWith(
+      `Preview URL: ${privatePreviewUrl} (server: https://web-preview.example.test).`
+    );
+    expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteConfig: expect.objectContaining({
+          webPreviewUrl: 'https://expo.dev/simulator-preview/preview-id',
+        }),
+      })
+    );
+  });
+
+  it('does not log the public link when a private job lacks its authenticated URL', async () => {
+    jest.mocked(startDeviceSessionHostAsync).mockResolvedValueOnce({
+      openPreviewAsync: jest.fn().mockResolvedValue({
+        previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
+        apiUrl: 'https://web-preview.example.test',
+        closeAsync: jest.fn(),
+      }),
+      getLastPreviewActivityAt: jest.fn(),
+      finishAsync: stopAsync,
+    });
+    await runAsync(BuildRuntimePlatform.DARWIN, { public_preview: { value: false } });
+
+    expect(logger.info).toHaveBeenCalledWith('Private preview URL unavailable for this session.');
+    expect(jest.mocked(logger.info).mock.calls).not.toEqual(
+      expect.arrayContaining([
+        expect.arrayContaining([expect.stringContaining('/simulator-preview/preview-id')]),
+      ])
+    );
+  });
+
+  it.each(['preview', 'config', 'wait'])('finishes the session after %s fails', async phase => {
+    const error = new Error(`${phase} failed`);
+    if (phase === 'preview') {
+      jest.mocked(startDeviceSessionHostAsync).mockResolvedValueOnce({
+        openPreviewAsync: jest.fn().mockRejectedValue(error),
+        getLastPreviewActivityAt: jest.fn(),
+        finishAsync: stopAsync,
+      });
+    } else if (phase === 'config') {
+      jest.mocked(uploadRemoteSessionConfigAsync).mockRejectedValueOnce(error);
+    } else {
+      jest.mocked(waitForDeviceRunSessionStoppedAsync).mockRejectedValueOnce(error);
+    }
+    await expect(runAsync(BuildRuntimePlatform.LINUX)).rejects.toBe(error);
+    expect(stopAsync).toHaveBeenCalledTimes(1);
+  });
+
   it.each([
     [BuildRuntimePlatform.DARWIN, true],
     [BuildRuntimePlatform.LINUX, false],
   ])('starts the web preview for %s', async (runtimePlatform, selectsXcode) => {
-    await runAsync(runtimePlatform);
+    await runAsync(runtimePlatform, selectsXcode ? { boot_simulator: { value: true } } : {});
 
+    expect(
+      jest
+        .mocked(logger.info)
+        .mock.calls.filter(
+          ([message]) =>
+            message ===
+            'Preview URL: https://expo.dev/simulator-preview/preview-id (server: https://web-preview.example.test).'
+        )
+    ).toHaveLength(1);
     expect(selectXcodeDeveloperDirectoryAsync).toHaveBeenCalledTimes(selectsXcode ? 1 : 0);
-    expect(startDeviceWebPreviewWithTunnelAsync).toHaveBeenCalledWith(ctx, {
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(ctx, {
       runtimePlatform,
-      baseDomain: 'tunnel.example.com',
-      env,
+      env: childEnv,
       logger,
       timeoutMs: 60_000,
+      signal: undefined,
+      ...(selectsXcode
+        ? {
+            iosSimulatorUdid: 'SELECTED-IOS-UDID',
+            installAppPath: undefined,
+            bootEnv: undefined,
+          }
+        : {}),
       packageVersion: '1.2.3',
+      disableShare: false,
+      frameAncestors: [],
+      corsOrigins: [],
       launchAppIdentifier: undefined,
       launchArgs: [],
       openUrl: undefined,
+      networkCapture: false,
+      networkCaptureFields: [],
+    });
+    const host = await jest.mocked(startDeviceSessionHostAsync).mock.results[0].value;
+    expect(host.openPreviewAsync).toHaveBeenCalledWith({
+      baseDomain: 'tunnel.example.com',
+      authtoken: 'ngrok-token',
     });
     expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith({
       ctx,
       deviceRunSessionId: 'device-run-session-id',
       remoteConfig: {
+        webPreviewUrl: 'https://expo.dev/simulator-preview/preview-id',
         previewUrl: 'https://expo.dev/simulator-preview/preview-id',
         previewApiUrl: 'https://web-preview.example.test',
       },
@@ -134,19 +258,28 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
       'launch_app_identifier',
       'launch_args',
       'open_url',
+      'boot_simulator',
+      'device_identifier',
+      'install_app_path',
+      'network_capture',
+      'network_capture_fields',
+      'public_preview',
+      'private_preview_url',
+      'frame_ancestors',
+      'cors_origins',
       'package_version',
       'max_duration_seconds',
     ]);
   });
 
-  it('hands the launch inputs to the web preview and announces them', async () => {
+  it('hands the launch inputs to the session host and announces them', async () => {
     await runAsync(BuildRuntimePlatform.DARWIN, {
       launch_app_identifier: { value: 'host.exp.Exponent' },
       launch_args: { value: ['-EXDevMenuIsOnboardingFinished', '1'] },
       open_url: { value: 'exp://127.0.0.1:8081' },
     });
 
-    expect(startDeviceWebPreviewWithTunnelAsync).toHaveBeenCalledWith(
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
       ctx,
       expect.objectContaining({
         launchAppIdentifier: 'host.exp.Exponent',
@@ -160,12 +293,94 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     );
   });
 
+  it('hands the downloaded app and selected device to serve-sim with initial launch options', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      device_identifier: { value: 'chosen-device' },
+      install_app_path: { value: '/tmp/App.app' },
+      launch_args: { value: ['--literal', 'value with spaces'] },
+      open_url: { value: 'example://home' },
+    });
+    expect(
+      jest.mocked(selectXcodeDeveloperDirectoryAsync).mock.invocationCallOrder[0]
+    ).toBeLessThan(jest.mocked(IosSimulatorUtils.resolveUdidAsync).mock.invocationCallOrder[0]);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        iosSimulatorUdid: 'SELECTED-IOS-UDID',
+        installAppPath: '/tmp/App.app',
+        launchAppIdentifier: 'dev.example.app',
+        launchArgs: ['--literal', 'value with spaces'],
+        openUrl: 'example://home',
+      })
+    );
+  });
+  it.each([true, false])(
+    'maps public_preview=%s to the native Share option',
+    async publicPreview => {
+      await runAsync(BuildRuntimePlatform.DARWIN, {
+        public_preview: { value: publicPreview },
+        private_preview_url: { value: 'https://expo.dev/private-preview' },
+      });
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+        ctx,
+        expect.objectContaining({
+          disableShare: !publicPreview,
+          privatePreviewUrl: 'https://expo.dev/private-preview',
+        })
+      );
+    }
+  );
+
+  it('hands frame_ancestors to the session host', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      frame_ancestors: { value: ['https://embed.example.test'] },
+    });
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ frameAncestors: ['https://embed.example.test'] })
+    );
+  });
+
+  it('hands cors_origins to the session host', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      cors_origins: { value: ['https://app.example.test'] },
+    });
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+  });
+
+  it('hands network capture to the session host', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      network_capture: { value: true },
+      network_capture_fields: { value: ['header', 'response-body'] },
+    });
+
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        networkCapture: true,
+        networkCaptureFields: ['header', 'response-body'],
+      })
+    );
+  });
+
+  it('fails before starting anything when network capture is asked for on Android', async () => {
+    await expect(
+      runAsync(BuildRuntimePlatform.LINUX, {
+        network_capture: { value: true },
+      })
+    ).rejects.toThrow('this session runs on linux');
+    expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
+  });
+
   it('fails before starting anything when a launch is asked for on Android', async () => {
     await expect(
       runAsync(BuildRuntimePlatform.LINUX, {
         launch_app_identifier: { value: 'host.exp.Exponent' },
       })
     ).rejects.toThrow('runs on linux');
-    expect(startDeviceWebPreviewWithTunnelAsync).not.toHaveBeenCalled();
+    expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
   });
 });

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

@@ -0,0 +1,257 @@
+import { SystemError, UserError } from '@expo/eas-build-job';
+import nock from 'nock';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import {
+  api,
+  editPath,
+  mockToken,
+  packageName,
+  serviceAccount,
+} from '../../utils/android/__tests__/googlePlayTestUtils';
+import { createSubmitToGooglePlayBuildFunction } from '../submitToGooglePlay';
+
+jest.unmock('node-fetch');
+jest.mock('promise-retry', () => {
+  const actual = jest.requireActual('promise-retry');
+  return (fn: Parameters<typeof actual>[0], options: object) =>
+    actual(fn, { ...options, minTimeout: 1, maxTimeout: 1, randomize: false });
+});
+jest.unmock('fs');
+jest.unmock('node:fs');
+jest.unmock('fs/promises');
+jest.unmock('node:fs/promises');
+
+let directory: string;
+let keyPath: string;
+let artifactPath: string;
+const session = '/upload/test-session';
+const createPath = `/androidpublisher/v3/applications/${packageName}/edits`;
+beforeEach(async () => {
+  nock.disableNetConnect();
+  directory = await fs.mkdtemp(path.join(os.tmpdir(), 'play-submit-test-'));
+  keyPath = path.join(directory, 'key.json');
+  artifactPath = path.join(directory, 'app.aab');
+  await fs.writeFile(artifactPath, 'binary');
+  await fs.writeFile(
+    keyPath,
+    JSON.stringify({
+      ...serviceAccount,
+      type: 'service_account',
+      private_key: serviceAccount.private_key.export({ format: 'pem', type: 'pkcs8' }),
+    })
+  );
+});
+afterEach(async () => {
+  const pending = nock.pendingMocks();
+  nock.cleanAll();
+  nock.enableNetConnect();
+  await fs.rm(directory, { recursive: true, force: true });
+  expect(pending).toEqual([]);
+});
+function submission(extra: Record<string, unknown> = {}, signal?: AbortSignal) {
+  const fn = createSubmitToGooglePlayBuildFunction();
+  const step = fn.createBuildStepFromFunctionCall(createGlobalContextMock({}), {
+    callInputs: {
+      artifact_path: artifactPath,
+      artifact_type: 'aab',
+      package_name: packageName,
+      service_account_key_path: keyPath,
+      ...extra,
+    },
+  });
+  const setters = step.outputs.map(output => jest.spyOn(output, 'set'));
+  return {
+    setters,
+    step,
+    run: async () =>
+      await fn.fn!(step.ctx, {
+        inputs: Object.fromEntries(
+          step.inputs!.map(input => [input.id, { value: input.rawValue }])
+        ),
+        outputs: Object.fromEntries(step.outputs.map(output => [output.id, output])),
+        env: {},
+        signal,
+      }),
+  };
+}
+function upload() {
+  mockToken();
+  api().post(createPath).reply(200, { id: 'edit' });
+  api()
+    .post(`/upload${editPath}/bundles`)
+    .query({ uploadType: 'resumable' })
+    .reply(200, '', { Location: `https://androidpublisher.googleapis.com${session}` });
+  nock('https://androidpublisher.googleapis.com').put(session).reply(200, { versionCode: 145 });
+}
+it.each([
+  ['completed', undefined, { status: 'completed' }],
+  ['completed', 0, 'invalid'],
+  ['completed', 0.25, { status: 'inProgress', userFraction: 0.25 }],
+  ['completed', 1, { status: 'completed' }],
+  ['draft', undefined, { status: 'draft' }],
+  ['draft', 0, 'invalid'],
+  ['draft', 0.25, 'invalid'],
+  ['draft', 1, 'invalid'],
+  ['halted', undefined, 'invalid'],
+  ['halted', 0, 'invalid'],
+  ['halted', 0.25, 'invalid'],
+  ['halted', 1, 'invalid'],
+  ['inProgress', undefined, 'invalid'],
+  ['inProgress', 0, 'invalid'],
+  ['inProgress', 0.25, { status: 'inProgress', userFraction: 0.25 }],
+  ['inProgress', 1, { status: 'completed' }],
+] as const)('validates and submits %s with rollout %s', async (status, rollout, expected) => {
+  const task = submission({
+    release_status: status,
+    ...(rollout !== undefined ? { rollout } : {}),
+  });
+  if (expected === 'invalid') {
+    await expect(task.run()).rejects.toThrow(status === 'halted' ? /release_status/ : /rollout/);
+    expect(task.setters.every(set => set.mock.calls.length === 0)).toBe(true);
+    return;
+  }
+  upload();
+  api()
+    .put(`${editPath}/tracks/internal`, {
+      track: 'internal',
+      releases: [{ ...expected, versionCodes: ['145'] }],
+    })
+    .reply(200, { track: 'internal' });
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .reply(() => {
+      expect(task.setters.every(set => set.mock.calls.length === 0)).toBe(true);
+      return [200, { id: 'edit' }];
+    });
+  await task.run();
+  expect(task.setters.map(set => set.mock.calls)).toEqual([[['145']]]);
+});
+it('runs the step with a string rollout and validates its required output', async () => {
+  upload();
+  api()
+    .put(`${editPath}/tracks/internal`, {
+      track: 'internal',
+      releases: [{ status: 'inProgress', userFraction: 0.25, versionCodes: ['145'] }],
+    })
+    .reply(200, { track: 'internal' });
+  api().post(`${editPath}:commit`).query({}).reply(200, { id: 'edit' });
+  const { step } = submission({ rollout: '0.25' });
+  expect(step.__hookId).toBe('submit');
+  await step.executeAsync();
+  expect(step.outputs[0].value).toBe('145');
+});
+it.each(['upload', 'track', 'abort'] as const)(
+  'deletes the edit after %s failure and leaves outputs unset',
+  async failure => {
+    const controller = new AbortController();
+    const task = submission({}, controller.signal);
+    mockToken();
+    api().post(createPath).reply(200, { id: 'edit' });
+    api()
+      .post(`/upload${editPath}/bundles`)
+      .query({ uploadType: 'resumable' })
+      .reply(() => {
+        if (failure === 'abort') {
+          controller.abort(new Error('step timed out'));
+        }
+        return failure === 'upload'
+          ? [400, { error: { message: 'rejected binary' } }]
+          : [200, '', { Location: `https://androidpublisher.googleapis.com${session}` }];
+      });
+    if (failure === 'track') {
+      nock('https://androidpublisher.googleapis.com').put(session).reply(200, { versionCode: 145 });
+      api()
+        .put(`${editPath}/tracks/internal`)
+        .reply(400, { error: { message: 'unknown track' } });
+    }
+    api().delete(editPath).reply(204);
+    await expect(task.run()).rejects.toThrow();
+    expect(task.setters.every(set => set.mock.calls.length === 0)).toBe(true);
+  }
+);
+it('preserves the original failure when cleanup fails', async () => {
+  upload();
+  api()
+    .put(`${editPath}/tracks/internal`)
+    .reply(400, { error: { message: 'unknown track' } });
+  api().delete(editPath).times(6).reply(500);
+  await expect(submission().run()).rejects.toMatchObject({
+    cause: expect.objectContaining({ apiMessage: 'unknown track' }),
+  });
+});
+it('does not delete the edit or publish outputs when commit outcome is unknown', async () => {
+  upload();
+  api().put(`${editPath}/tracks/internal`).reply(200, { track: 'internal' });
+  api().post(`${editPath}:commit`).query(true).reply(503);
+  api().post(`${editPath}:commit`).query(true).reply(404);
+  let deleted = false;
+  api()
+    .delete(editPath)
+    .optionally()
+    .reply(() => {
+      deleted = true;
+      return [204];
+    });
+  const task = submission();
+  await expect(task.run()).rejects.toBeInstanceOf(SystemError);
+  expect(deleted).toBe(false);
+  expect(task.setters.every(set => set.mock.calls.length === 0)).toBe(true);
+});
+it('reports a missing service-account file with its path', async () => {
+  const missing = path.join(directory, 'missing.json');
+  await expect(submission({ service_account_key_path: missing }).run()).rejects.toThrow(
+    `Service-account key file not found at ${missing}`
+  );
+});
+it('does not expose invalid credential contents', async () => {
+  await fs.writeFile(keyPath, 'PRIVATE_SECRET_INVALID_JSON');
+  const error = await submission()
+    .run()
+    .catch(error => error);
+  expect(error).toBeInstanceOf(UserError);
+  expect(JSON.stringify(error) + String(error)).not.toContain('PRIVATE_SECRET');
+});
+
+it('preserves the cause when the service-account file cannot be read', async () => {
+  const cause = Object.assign(new Error('permission denied'), { code: 'EACCES' });
+  const read = jest.spyOn(fs, 'readFile').mockRejectedValueOnce(cause);
+  try {
+    await expect(submission().run()).rejects.toMatchObject({ cause });
+  } finally {
+    read.mockRestore();
+  }
+});
+
+it('logs a formatted rollout and confirms the track update before committing', async () => {
+  upload();
+  const task = submission({ rollout: 0.29 });
+  const info = jest.spyOn(task.step.ctx.logger, 'info');
+  const updatedMessage = 'Updated Google Play track "internal" in the edit.';
+  let loggedBeforeUpdate = false;
+  let messagesBeforeCommit: unknown[] = [];
+  api()
+    .put(`${editPath}/tracks/internal`)
+    .reply(() => {
+      loggedBeforeUpdate = info.mock.calls.some(([message]) => message === updatedMessage);
+      return [200, { track: 'internal' }];
+    });
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .reply(() => {
+      messagesBeforeCommit = info.mock.calls.map(([message]) => message);
+      return [200, { id: 'edit' }];
+    });
+  await task.run();
+  expect(info).toHaveBeenCalledWith('Release status: inProgress. Rollout: 29%.');
+  expect(loggedBeforeUpdate).toBe(false);
+  expect(messagesBeforeCommit.slice(-2)).toEqual([
+    updatedMessage,
+    'Committing the Google Play edit...',
+  ]);
+});

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

@@ -0,0 +1,621 @@
+import nock from 'nock';
+import { generateKeyPairSync } from 'node:crypto';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { Sentry } from '../../../sentry';
+import { AscApiClient } from '../../utils/ios/AscApiClient';
+import {
+  createUpdateTestFlightMetadataBuildFunction,
+  updateTestFlightMetadataAsync,
+} from '../updateTestFlightMetadata';
+
+jest.unmock('node-fetch');
+jest.mock('../../../sentry', () => ({ Sentry: { capture: jest.fn() } }));
+
+const { privateKey } = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+const key = { keyId: 'TESTKEY', privateKey };
+const changelog = 'Test "quotes"\n$(not-a-command)';
+const options = {
+  client: new AscApiClient({ key }),
+  buildUploadId: 'upload',
+  changelog,
+  groups: [] as string[],
+  logger: createMockLogger(),
+};
+const api = () => nock('https://api.appstoreconnect.apple.com');
+
+function mockBuild(
+  state = 'COMPLETE',
+  buildId: string | null = 'build',
+  primaryLocale: string | null = 'en-US'
+): void {
+  api()
+    .get('/v1/buildUploads/upload')
+    .query(true)
+    .reply(200, {
+      data: {
+        type: 'buildUploads',
+        id: 'upload',
+        attributes: { state: { state } },
+        relationships: { build: { data: buildId ? { type: 'builds', id: buildId } : null } },
+      },
+    });
+  if (state === 'COMPLETE' && buildId) {
+    api()
+      .get(`/v1/builds/${buildId}/app`)
+      .query(true)
+      .reply(200, {
+        data: { id: 'app', attributes: primaryLocale ? { primaryLocale } : {} },
+      });
+  }
+}
+
+function mockAssignedGroups(ids: string[] = []): void {
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[builds]': 'build', limit: '200' })
+    .reply(200, { data: ids.map(id => ({ id })) });
+}
+
+function mockInternalBuildState(state: string | null = 'READY_FOR_BETA_TESTING'): void {
+  api()
+    .get('/v1/builds/build/buildBetaDetail')
+    .query(true)
+    .reply(
+      state ? 200 : 503,
+      state
+        ? { data: { id: 'detail', attributes: { internalBuildState: state } } }
+        : { errors: [{ code: 'UNAVAILABLE' }] }
+    );
+}
+
+beforeAll(() => nock.disableNetConnect());
+beforeEach(() => {
+  jest.mocked(Sentry.capture).mockClear();
+  options.logger = createMockLogger();
+  options.client = new AscApiClient({ key });
+});
+afterAll(() => nock.enableNetConnect());
+afterEach(() => {
+  try {
+    expect(nock.pendingMocks()).toEqual([]);
+  } finally {
+    nock.cleanAll();
+  }
+});
+
+it('accepts group arrays and preserves changelog input without shell parsing', async () => {
+  const fn = createUpdateTestFlightMetadataBuildFunction();
+  const spy = jest.spyOn(fn, 'fn').mockImplementation(async (_ctx, { inputs }) => {
+    expect(inputs.groups.value).toEqual(['A, "B"']);
+    expect(inputs.changelog.value).toBe(changelog);
+  });
+  const step = fn.createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: {
+      asc_api_key_path: '/tmp/key.json',
+      build_upload_id: 'upload',
+      groups: ['A, "B"'],
+      changelog,
+    },
+  });
+  await step.executeAsync();
+  expect(spy).toHaveBeenCalled();
+});
+
+it('uses empty metadata defaults', async () => {
+  const fn = createUpdateTestFlightMetadataBuildFunction();
+  const spy = jest.spyOn(fn, 'fn').mockImplementation(async (_ctx, { inputs }) => {
+    expect(inputs.groups.value).toEqual([]);
+    expect(inputs.changelog.value).toBe('');
+  });
+  const step = fn.createBuildStepFromFunctionCall(createGlobalContextMock(), {
+    callInputs: { asc_api_key_path: '/tmp/key.json', build_upload_id: 'upload' },
+  });
+  await step.executeAsync();
+  expect(spy).toHaveBeenCalled();
+});
+
+it('skips automatic internal groups and groups that already contain the build', async () => {
+  mockBuild();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, {
+      data: [
+        {
+          id: 'automatic',
+          attributes: { name: 'Internal', isInternalGroup: true, hasAccessToAllBuilds: true },
+        },
+        { id: 'assigned', attributes: { name: 'QA' } },
+        {
+          id: 'manual',
+          attributes: { name: 'External', isInternalGroup: false, hasAccessToAllBuilds: true },
+        },
+      ],
+    });
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[builds]': 'build', limit: '200' })
+    .reply(200, { data: [{ id: 'assigned', attributes: { name: 'QA' } }] });
+  api()
+    .post('/v1/builds/build/relationships/betaGroups', {
+      data: [{ type: 'betaGroups', id: 'manual' }],
+    })
+    .reply(204);
+  await updateTestFlightMetadataAsync({
+    ...options,
+    changelog: '',
+    groups: ['Internal', 'QA', 'External'],
+  });
+  expect(options.logger.info).toHaveBeenCalledWith(
+    expect.stringContaining('"Internal" (automatic): automatic access')
+  );
+  expect(options.logger.info).toHaveBeenCalledWith(
+    expect.stringContaining('"QA" (assigned): build already assigned')
+  );
+  expect(options.logger.info).toHaveBeenCalledWith(
+    expect.stringContaining('"External" (manual): assignment completed')
+  );
+});
+
+it.each(['en-US', null])(
+  'creates a localization when none exist (primary locale: %s)',
+  async primaryLocale => {
+    mockBuild('COMPLETE', 'build', primaryLocale);
+    api().get('/v1/builds/build/betaBuildLocalizations').query(true).reply(200, { data: [] });
+    api()
+      .post('/v1/betaBuildLocalizations', {
+        data: {
+          type: 'betaBuildLocalizations',
+          attributes: { locale: 'en-US', whatsNew: changelog },
+          relationships: { build: { data: { type: 'builds', id: 'build' } } },
+        },
+      })
+      .reply(201, { data: { id: 'locale' } });
+    await updateTestFlightMetadataAsync(options);
+    expect(options.logger.info).toHaveBeenCalledWith(
+      `Updating changelog: ${JSON.stringify(changelog)}`
+    );
+    expect(options.logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('Locale "en-US": localization created')
+    );
+  }
+);
+
+it('reads all localization pages and updates existing localizations without replacing them', async () => {
+  mockBuild();
+  api()
+    .get('/v1/builds/build/betaBuildLocalizations')
+    .query(true)
+    .reply(200, {
+      data: [{ id: 'en-US', attributes: { locale: 'en-US' } }],
+      links: {
+        next: 'https://api.appstoreconnect.apple.com/v1/builds/build/betaBuildLocalizations?limit=200&cursor=next',
+      },
+    });
+  api()
+    .get('/v1/builds/build/betaBuildLocalizations')
+    .query({ limit: '200', cursor: 'next' })
+    .reply(200, { data: [{ id: 'pl', attributes: { locale: 'pl' } }] });
+  for (const id of ['en-US', 'pl']) {
+    api()
+      .patch(`/v1/betaBuildLocalizations/${id}`, {
+        data: { type: 'betaBuildLocalizations', id, attributes: { whatsNew: changelog } },
+      })
+      .reply(200, { data: { id } });
+  }
+  await updateTestFlightMetadataAsync(options);
+  for (const id of ['en-US', 'pl']) {
+    expect(options.logger.info).toHaveBeenCalledWith(
+      expect.stringContaining(`Locale "${id}" (${id})`)
+    );
+  }
+});
+
+it('updates by ID when Apple omits a localization locale and creates the primary locale', async () => {
+  mockBuild();
+  api()
+    .get('/v1/builds/build/betaBuildLocalizations')
+    .query(true)
+    .reply(200, { data: [{ id: 'localization' }] });
+
+  api()
+    .patch('/v1/betaBuildLocalizations/localization', {
+      data: {
+        type: 'betaBuildLocalizations',
+        id: 'localization',
+        attributes: { whatsNew: changelog },
+      },
+    })
+    .reply(200, { data: { id: 'localization' } });
+  api()
+    .post('/v1/betaBuildLocalizations', {
+      data: {
+        type: 'betaBuildLocalizations',
+        attributes: { locale: 'en-US', whatsNew: changelog },
+        relationships: { build: { data: { type: 'builds', id: 'build' } } },
+      },
+    })
+    .reply(201, { data: { id: 'primary' } });
+  await updateTestFlightMetadataAsync(options);
+});
+
+it('assigns requested groups when hasAccessToAllBuilds is null', async () => {
+  mockBuild();
+  mockAssignedGroups();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, {
+      data: [
+        {
+          id: 'internal',
+          attributes: { name: 'Internal', isInternalGroup: true, hasAccessToAllBuilds: false },
+        },
+        {
+          id: 'external',
+          attributes: {
+            name: 'test external',
+            isInternalGroup: false,
+            hasAccessToAllBuilds: null,
+            publicLinkEnabled: false,
+            publicLink: 'https://testflight.apple.com/join/abc',
+          },
+        },
+        {
+          id: 'requested-external',
+          attributes: { name: 'Beta', isInternalGroup: false, hasAccessToAllBuilds: null },
+        },
+      ],
+    });
+  for (const id of ['internal', 'requested-external']) {
+    api()
+      .post('/v1/builds/build/relationships/betaGroups', {
+        data: [{ type: 'betaGroups', id }],
+      })
+      .reply(204);
+  }
+  await expect(
+    updateTestFlightMetadataAsync({ ...options, changelog: '', groups: ['Internal', 'Beta'] })
+  ).resolves.toBeUndefined();
+});
+
+it('adds groups without changing changelog or submitting beta review', async () => {
+  mockBuild();
+  mockAssignedGroups();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, { data: [{ id: 'group', attributes: { name: 'A, "B"' } }] });
+  api()
+    .post('/v1/builds/build/relationships/betaGroups', {
+      data: [{ type: 'betaGroups', id: 'group' }],
+    })
+    .reply(204);
+  await updateTestFlightMetadataAsync({ ...options, changelog: '', groups: ['A, "B"', 'A, "B"'] });
+});
+
+it('reports missing groups independently of the changelog task', async () => {
+  mockBuild();
+  api().get('/v1/builds/build/betaBuildLocalizations').query(true).reply(200, { data: [] });
+  api()
+    .post('/v1/betaBuildLocalizations')
+    .reply(201, { data: { id: 'locale' } });
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, { data: [] });
+  await expect(updateTestFlightMetadataAsync({ ...options, groups: ['missing'] })).rejects.toThrow(
+    'The following TestFlight group was not found in App Store Connect: "missing".'
+  );
+});
+
+it('reads all pages and adds every group with a requested name', async () => {
+  mockBuild();
+  mockAssignedGroups();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, {
+      data: [{ id: 'first', attributes: { name: 'A' } }],
+      links: {
+        next: 'https://api.appstoreconnect.apple.com/v1/betaGroups?filter%5Bapp%5D=app&limit=200&cursor=page-2',
+      },
+    });
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200', cursor: 'page-2' })
+    .reply(200, {
+      data: [
+        { id: 'second', attributes: { name: 'A' } },
+        { id: 'other', attributes: { name: 'B' } },
+      ],
+    });
+  for (const id of ['first', 'second']) {
+    api()
+      .post('/v1/builds/build/relationships/betaGroups', {
+        data: [{ type: 'betaGroups', id }],
+      })
+      .reply(204);
+  }
+  await updateTestFlightMetadataAsync({ ...options, changelog: '', groups: ['A'] });
+});
+
+it('assigns found groups before reporting missing requested names', async () => {
+  mockBuild();
+  mockAssignedGroups();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, { data: [{ id: 'group', attributes: { name: 'A' } }] });
+  api()
+    .post('/v1/builds/build/relationships/betaGroups', {
+      data: [{ type: 'betaGroups', id: 'group' }],
+    })
+    .reply(204);
+  await expect(
+    updateTestFlightMetadataAsync({ ...options, changelog: '', groups: ['A', 'B', 'C'] })
+  ).rejects.toThrow(
+    'The following TestFlight groups were not found in App Store Connect: "B", "C".'
+  );
+});
+
+it('attempts all localization changes and reports every failed update', async () => {
+  mockBuild();
+  api()
+    .get('/v1/builds/build/betaBuildLocalizations')
+    .query(true)
+    .reply(200, {
+      data: ['pl', 'fr', 'de'].map(locale => ({ id: locale, attributes: { locale } })),
+    });
+  for (const id of ['pl', 'fr', 'de']) {
+    api()
+      .patch(`/v1/betaBuildLocalizations/${id}`)
+      .reply(
+        id === 'de' ? 200 : 403,
+        id === 'de' ? { data: { id } } : { errors: [{ code: `${id}_FAILED` }] }
+      );
+  }
+  api()
+    .post('/v1/betaBuildLocalizations', {
+      data: {
+        type: 'betaBuildLocalizations',
+        attributes: { locale: 'en-US', whatsNew: changelog },
+        relationships: { build: { data: { type: 'builds', id: 'build' } } },
+      },
+    })
+    .reply(201, { data: { id: 'locale' } });
+  await expect(updateTestFlightMetadataAsync(options)).rejects.toThrow(/pl_FAILED.*fr_FAILED/);
+  expect(options.logger.error).toHaveBeenCalledWith(expect.stringContaining('"pl" (pl)'));
+  expect(options.logger.error).toHaveBeenCalledWith(expect.stringContaining('"fr" (fr)'));
+});
+
+it.each([1, 2])('explains automatic internal group rejection (%s errors)', async errorCount => {
+  mockBuild();
+  mockInternalBuildState();
+  mockAssignedGroups();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, { data: [{ id: 'group', attributes: { name: 'A' } }] });
+  api()
+    .post('/v1/builds/build/relationships/betaGroups')
+    .reply(422, {
+      errors: Array.from({ length: errorCount }, () => ({
+        code: 'ENTITY_UNPROCESSABLE',
+        title: 'Builds cannot be assigned to this internal group.',
+        detail: 'Cannot add internal group to a build.',
+      })),
+    });
+  await expect(
+    updateTestFlightMetadataAsync({ ...options, changelog: '', groups: ['A'] })
+  ).rejects.toThrow(
+    "App Store Connect can't add this build to a requested internal TestFlight group."
+  );
+});
+
+it('stops after 20 group pages', async () => {
+  mockBuild();
+  const next =
+    'https://api.appstoreconnect.apple.com/v1/betaGroups?filter%5Bapp%5D=app&limit=200&cursor=next';
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, { data: [], links: { next } });
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200', cursor: 'next' })
+    .times(19)
+    .reply(200, { data: [], links: { next } });
+  await expect(
+    updateTestFlightMetadataAsync({ ...options, changelog: '', groups: ['A'] })
+  ).rejects.toThrow('We only support TestFlight group lists with up to 20 pages');
+});
+
+it('tries group assignment if the changelog update fails', async () => {
+  mockBuild();
+  mockAssignedGroups();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, { data: [{ id: 'group', attributes: { name: 'A' } }] });
+  api().get('/v1/builds/build/betaBuildLocalizations').query(true).reply(200, { data: [] });
+  api()
+    .post('/v1/betaBuildLocalizations')
+    .reply(403, { errors: [{ code: 'FORBIDDEN', detail: 'Not allowed' }] });
+  api()
+    .post('/v1/builds/build/relationships/betaGroups', {
+      data: [{ type: 'betaGroups', id: 'group' }],
+    })
+    .reply(204);
+  await expect(updateTestFlightMetadataAsync({ ...options, groups: ['A'] })).rejects.toThrow('403');
+});
+
+it('reports both write failures', async () => {
+  mockBuild();
+  mockInternalBuildState();
+  mockAssignedGroups();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, { data: [{ id: 'group', attributes: { name: 'A' } }] });
+  api().get('/v1/builds/build/betaBuildLocalizations').query(true).reply(200, { data: [] });
+  api()
+    .post('/v1/betaBuildLocalizations')
+    .reply(403, { errors: [{ code: 'CHANGELOG_FAILED' }] });
+  api()
+    .post('/v1/builds/build/relationships/betaGroups')
+    .reply(403, { errors: [{ code: 'GROUPS_FAILED' }] });
+  await expect(updateTestFlightMetadataAsync({ ...options, groups: ['A'] })).rejects.toThrow(
+    /CHANGELOG_FAILED.*GROUPS_FAILED/
+  );
+});
+
+it.each([false, true])(
+  'attempts all groups and reports assignment errors (multiple: %s)',
+  async multiple => {
+    mockBuild();
+    mockInternalBuildState();
+    mockAssignedGroups();
+    api()
+      .get('/v1/betaGroups')
+      .query({ 'filter[app]': 'app', limit: '200' })
+      .reply(200, { data: ['A', 'B', 'C'].map(id => ({ id, attributes: { name: id } })) });
+    api()
+      .post('/v1/builds/build/relationships/betaGroups', {
+        data: [{ type: 'betaGroups', id: 'A' }],
+      })
+      .reply(
+        multiple ? 403 : 204,
+        multiple ? { errors: [{ code: 'FIRST_GROUP_FAILED' }] } : undefined
+      );
+    api()
+      .post('/v1/builds/build/relationships/betaGroups', {
+        data: [{ type: 'betaGroups', id: 'B' }],
+      })
+      .reply(422, { errors: [{ code: 'ENTITY_UNPROCESSABLE', title: 'Partial assignment' }] });
+    api()
+      .post('/v1/builds/build/relationships/betaGroups', {
+        data: [{ type: 'betaGroups', id: 'C' }],
+      })
+      .reply(204);
+    await expect(
+      updateTestFlightMetadataAsync({ ...options, changelog: '', groups: ['A', 'B', 'C'] })
+    ).rejects.toThrow(multiple ? 'FIRST_GROUP_FAILED' : 'Partial assignment');
+    expect(options.logger.error).toHaveBeenCalledWith(
+      expect.stringContaining('Group "B" (B): assignment failed.')
+    );
+  }
+);
+
+it('reads all membership pages before assigning groups', async () => {
+  mockBuild();
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[app]': 'app', limit: '200' })
+    .reply(200, { data: [{ id: 'group', attributes: { name: 'A' } }] });
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[builds]': 'build', limit: '200' })
+    .reply(200, {
+      data: [],
+      links: {
+        next: 'https://api.appstoreconnect.apple.com/v1/betaGroups?filter%5Bbuilds%5D=build&limit=200&cursor=next',
+      },
+    });
+  api()
+    .get('/v1/betaGroups')
+    .query({ 'filter[builds]': 'build', limit: '200', cursor: 'next' })
+    .reply(200, { data: [{ id: 'group' }] });
+  await updateTestFlightMetadataAsync({ ...options, changelog: '', groups: ['A'] });
+});
+
+it.each(['PROCESSING', 'FAILED'])('rejects a %s upload', async state => {
+  mockBuild(state);
+  await expect(updateTestFlightMetadataAsync(options)).rejects.toThrow('not ready');
+});
+
+it('rejects a completed upload without its build relationship', async () => {
+  mockBuild('COMPLETE', null);
+  await expect(updateTestFlightMetadataAsync(options)).rejects.toThrow('not ready');
+});
+
+it('propagates Apple write failures', async () => {
+  mockBuild();
+  api().get('/v1/builds/build/betaBuildLocalizations').query(true).reply(200, { data: [] });
+  api()
+    .post('/v1/betaBuildLocalizations')
+    .reply(403, { errors: [{ code: 'FORBIDDEN', detail: 'Not allowed' }] });
+  await expect(updateTestFlightMetadataAsync(options)).rejects.toThrow('403');
+});
+
+it.each([
+  ['MISSING_EXPORT_COMPLIANCE', 'Complete the export compliance questions'],
+  ['IN_EXPORT_COMPLIANCE_REVIEW', 'Wait for Apple to approve'],
+  ['EXPIRED', 'ASSIGNMENT_FAILED'],
+  ['PROCESSING', 'ASSIGNMENT_FAILED'],
+  ['READY_FOR_BETA_TESTING', 'ASSIGNMENT_FAILED'],
+  ['IN_BETA_TESTING', 'ASSIGNMENT_FAILED'],
+  [null, 'ASSIGNMENT_FAILED'],
+] as const)(
+  'shares one diagnostic lookup across failed assignments (state: %s)',
+  async (state, guidance) => {
+    mockBuild();
+    mockAssignedGroups();
+    api()
+      .get('/v1/betaGroups')
+      .query({ 'filter[app]': 'app', limit: '200' })
+      .reply(200, {
+        data: ['A', 'B', 'C'].map(id => ({ id, attributes: { name: id } })),
+      });
+    api()
+      .post('/v1/builds/build/relationships/betaGroups', {
+        data: [{ type: 'betaGroups', id: 'A' }],
+      })
+      .reply(403, { errors: [{ code: 'ASSIGNMENT_FAILED' }] });
+    mockInternalBuildState(state);
+    api()
+      .post('/v1/builds/build/relationships/betaGroups', {
+        data: [{ type: 'betaGroups', id: 'B' }],
+      })
+      .reply(422, { errors: [{ code: 'ASSIGNMENT_FAILED' }] });
+    // A failed assignment must not prevent the next group from being assigned.
+    api()
+      .post('/v1/builds/build/relationships/betaGroups', {
+        data: [{ type: 'betaGroups', id: 'C' }],
+      })
+      .reply(204);
+    const failure = await updateTestFlightMetadataAsync({
+      ...options,
+      changelog: '',
+      groups: ['A', 'B', 'C'],
+    }).catch(error => error);
+    expect(failure).toBeInstanceOf(AggregateError);
+    expect(failure.errors).toHaveLength(2);
+    if (state === 'MISSING_EXPORT_COMPLIANCE' || state === 'IN_EXPORT_COMPLIANCE_REVIEW') {
+      expect(failure.errors[0]).toBe(failure.errors[1]);
+    } else {
+      expect(failure.errors[0]).toMatchObject({ status: 403 });
+      expect(failure.errors[1]).toMatchObject({ status: 422 });
+    }
+    expect(failure.errors[0].message).toContain(guidance);
+    expect(
+      jest
+        .mocked(options.logger.info)
+        .mock.calls.filter(([message]) => String(message).includes('internal TestFlight state ='))
+    ).toEqual([[`Apple build build: internal TestFlight state = ${state ?? 'UNKNOWN'}.`]]);
+    expect(Sentry.capture).toHaveBeenCalledTimes(1);
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      `TestFlight group assignment failed (state: ${state ?? 'UNKNOWN'})`,
+      {
+        level: 'error',
+        tags: { step: 'eas/update_testflight_metadata', internal_build_state: state ?? 'UNKNOWN' },
+        extras: {
+          buildId: 'build',
+          assignmentError: expect.stringContaining('ASSIGNMENT_FAILED'),
+        },
+      }
+    );
+  }
+);

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

@@ -20,7 +20,8 @@ describe(createUploadDeviceRunSessionScreenRecordingsBuildFunction, () => {
     jest
       .mocked(uploadDeviceRunSessionArtifactAsync)
       .mockReset()
-      .mockImplementation(async (_ctx, { stream }) => {
+      .mockImplementation(async (_ctx, { openStream }) => {
+        const stream = openStream();
         await new Promise<void>((resolve, reject) => {
           stream.once('end', resolve);
           stream.once('error', reject);
@@ -29,7 +30,20 @@ describe(createUploadDeviceRunSessionScreenRecordingsBuildFunction, () => {
       });
   });
 
-  it('uploads simulator device metadata', async () => {
+  it.each([
+    {
+      platform: BuildRuntimePlatform.DARWIN,
+      udid: SIMULATOR_UDID,
+      name: 'iPhone 16',
+      runtime: 'iOS 18.6',
+    },
+    {
+      platform: BuildRuntimePlatform.LINUX,
+      udid: 'emulator-5554',
+      name: 'Pixel',
+      runtime: 'Android 16',
+    },
+  ])('uploads device metadata on $platform', async ({ platform, udid, name, runtime }) => {
     const recordingDirectory = await fs.mkdtemp(path.join(os.tmpdir(), 'ios-recording-test-'));
     const recordingPath = path.join(recordingDirectory, 'recording.mp4');
     await fs.writeFile(recordingPath, 'recording');
@@ -45,7 +59,7 @@ describe(createUploadDeviceRunSessionScreenRecordingsBuildFunction, () => {
 
     try {
       const globalContext = createGlobalContextMock({
-        runtimePlatform: BuildRuntimePlatform.DARWIN,
+        runtimePlatform: platform,
       });
       const buildStep = createUploadDeviceRunSessionScreenRecordingsBuildFunction(
         {} as CustomBuildContext
@@ -54,9 +68,9 @@ describe(createUploadDeviceRunSessionScreenRecordingsBuildFunction, () => {
         callInputs: {
           recordings_json: [
             {
-              udid: SIMULATOR_UDID,
-              deviceName: 'iPhone 16',
-              runtimeDisplayName: 'iOS 18.6',
+              udid,
+              deviceName: name,
+              runtimeDisplayName: runtime,
               directory: recordingDirectory,
             },
           ],
@@ -68,13 +82,13 @@ describe(createUploadDeviceRunSessionScreenRecordingsBuildFunction, () => {
       expect(uploadDeviceRunSessionArtifactAsync).toHaveBeenCalledWith(
         expect.anything(),
         expect.objectContaining({
-          name: 'iPhone 16 screen recording (01234567-…, started at Jul 10, 2026, 10:00:00.000 UTC)',
+          name: `${name} screen recording (${udid.slice(0, 8)}-…, started at Jul 10, 2026, 10:00:00.000 UTC)`,
           metadata: {
             __eas_type: 'screen-recording',
             __eas_screen_recording: '1',
-            udid: SIMULATOR_UDID,
-            deviceName: 'iPhone 16',
-            runtimeDisplayName: 'iOS 18.6',
+            udid,
+            deviceName: name,
+            runtimeDisplayName: runtime,
             firstFrameAt: '2026-07-10T10:00:00.000Z',
             width: 1179,
             height: 2556,
@@ -126,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)',
@@ -137,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__/uploadEmbeddedBundle.test.ts

@@ -0,0 +1,129 @@
+import { ProjectConfig } from '@expo/config';
+import { BuildJob } from '@expo/eas-build-job';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { createTestAndroidJob } from '../../../__tests__/utils/job';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { BuildContext } from '../../../context';
+import { CustomBuildContext } from '../../../customBuildContext';
+import { readAppConfig } from '../../../utils/appConfig';
+import { uploadEmbeddedBundleAsync } from '../../../utils/expoUpdatesEmbedded';
+import { createUploadEmbeddedBundleBuildFunction } from '../uploadEmbeddedBundle';
+
+jest.mock('../../../utils/appConfig');
+jest.mock('../../../utils/expoUpdatesEmbedded');
+
+function mockAppConfig(updatesUrl: string | undefined): void {
+  jest.mocked(readAppConfig).mockResolvedValue({
+    exp: { name: 'my-app', slug: 'my-app', updates: updatesUrl ? { url: updatesUrl } : undefined },
+  } as ProjectConfig);
+}
+
+function createCustomContext(job: BuildJob): CustomBuildContext<BuildJob> {
+  return new CustomBuildContext(
+    new BuildContext(job, {
+      env: { __API_SERVER_URL: 'http://api.expo.test' },
+      logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
+      logger: createMockLogger(),
+      uploadArtifact: jest.fn(),
+      workingdir: '',
+    })
+  );
+}
+
+describe(createUploadEmbeddedBundleBuildFunction, () => {
+  const job = createTestAndroidJob({});
+  const customContext = createCustomContext(job);
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it('uploads the embedded bundle from the working directory', async () => {
+    mockAppConfig('https://u.expo.dev/project-id');
+    jest.mocked(uploadEmbeddedBundleAsync).mockResolvedValue({ status: 'uploaded' });
+    const globalContext = createGlobalContextMock({});
+    globalContext.updateEnv({ EAS_BUILD_ID: 'build-123' });
+    const buildStep =
+      createUploadEmbeddedBundleBuildFunction(customContext).createBuildStepFromFunctionCall(
+        globalContext
+      );
+
+    await buildStep.executeAsync();
+
+    expect(uploadEmbeddedBundleAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        job,
+        env: expect.objectContaining({ EAS_BUILD_ID: 'build-123' }),
+        projectDir: globalContext.defaultWorkingDirectory,
+        appConfig: expect.objectContaining({ updates: { url: 'https://u.expo.dev/project-id' } }),
+      })
+    );
+  });
+
+  it('logs when the embedded bundle upload is skipped', async () => {
+    mockAppConfig('https://u.expo.dev/project-id');
+    jest.mocked(uploadEmbeddedBundleAsync).mockResolvedValue({ status: 'skipped' });
+    const buildStep = createUploadEmbeddedBundleBuildFunction(
+      customContext
+    ).createBuildStepFromFunctionCall(createGlobalContextMock({}));
+
+    await buildStep.executeAsync();
+
+    expect(buildStep.ctx.logger.info).toHaveBeenCalledWith('Skipping embedded bundle upload.');
+  });
+
+  it('fails the step when the upload fails', async () => {
+    mockAppConfig('https://u.expo.dev/project-id');
+    jest.mocked(uploadEmbeddedBundleAsync).mockResolvedValue({ status: 'failed' });
+    const buildStep = createUploadEmbeddedBundleBuildFunction(
+      customContext
+    ).createBuildStepFromFunctionCall(createGlobalContextMock({}));
+
+    await expect(buildStep.executeAsync()).rejects.toThrow('Failed to upload embedded bundle.');
+  });
+
+  it('does not fail the step when the upload fails and ignore_error is set', async () => {
+    mockAppConfig('https://u.expo.dev/project-id');
+    jest.mocked(uploadEmbeddedBundleAsync).mockResolvedValue({ status: 'failed' });
+    const buildStep = createUploadEmbeddedBundleBuildFunction(
+      customContext
+    ).createBuildStepFromFunctionCall(createGlobalContextMock({}), {
+      callInputs: { ignore_error: true },
+    });
+
+    await buildStep.executeAsync();
+
+    expect(buildStep.ctx.logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      'Failed to upload embedded bundle. Ignoring error.'
+    );
+  });
+
+  it('fails the step when the app config cannot be read', async () => {
+    jest.mocked(readAppConfig).mockRejectedValue(new Error('Invalid app config'));
+    const buildStep = createUploadEmbeddedBundleBuildFunction(
+      customContext
+    ).createBuildStepFromFunctionCall(createGlobalContextMock({}));
+
+    await expect(buildStep.executeAsync()).rejects.toThrow('Invalid app config');
+    expect(uploadEmbeddedBundleAsync).not.toHaveBeenCalled();
+  });
+
+  it('does not fail the step when the app config cannot be read and ignore_error is set', async () => {
+    jest.mocked(readAppConfig).mockRejectedValue(new Error('Invalid app config'));
+    const buildStep = createUploadEmbeddedBundleBuildFunction(
+      customContext
+    ).createBuildStepFromFunctionCall(createGlobalContextMock({}), {
+      callInputs: { ignore_error: true },
+    });
+
+    await buildStep.executeAsync();
+
+    expect(buildStep.ctx.logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      'Failed to upload embedded bundle. Ignoring error.'
+    );
+    expect(uploadEmbeddedBundleAsync).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,46 @@
+import { BuildFunction, BuildRuntimePlatform } from '@expo/steps';
+
+import { type CustomBuildContext } from '../../customBuildContext';
+import { Sentry } from '../../sentry';
+import { getDeviceRunSessionIdOrThrow } from '../utils/remoteDeviceRunSession';
+import { uploadServeSimLogsFileAsync } from '../utils/serveSimLogsArtifacts';
+import { ServeSimLogsRecorder } from '../utils/serveSimLogsRecorder';
+
+const UPLOAD_TIMEOUT_MS = 30_000;
+
+export function createCollectServeSimLogsBuildFunction(ctx: CustomBuildContext): BuildFunction {
+  return new BuildFunction({
+    namespace: 'eas',
+    id: 'collect_serve_sim_logs',
+    name: 'Collect serve-sim simulator logs',
+    __metricsId: 'eas/collect_serve_sim_logs',
+    supportedRuntimePlatforms: [BuildRuntimePlatform.DARWIN],
+    fn: async ({ logger }, { env }) => {
+      try {
+        const collected = await ServeSimLogsRecorder.finishAsync({ logger });
+        if (collected.length === 0) {
+          logger.info('No simulator logs collected; skipping upload.');
+          return;
+        }
+        const deviceRunSessionId = getDeviceRunSessionIdOrThrow(env);
+        for (const { udid, filePath } of collected) {
+          // Each device gets its own budget so one stuck upload does not cancel the rest.
+          await uploadServeSimLogsFileAsync(ctx, {
+            deviceRunSessionId,
+            udid,
+            filePath,
+            logger,
+            signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+          });
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        Sentry.capture('Could not finalize serve-sim simulator logs', error);
+        logger.warn(
+          { err: error },
+          'Could not finalize simulator 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';
@@ -25,8 +25,19 @@ import plist from 'plist';
 import { CustomBuildContext } from '../../customBuildContext';
 import { formatBytes } from '../../utils/artifacts';
 import { decompressTarAsync, isFileTarGzAsync } from '../../utils/files';
-import { retryOnDNSFailure } from '../../utils/retryOnDNSFailure';
+import { graphqlAbortContext } from '../../utils/graphqlAbort';
+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';
 
 const streamPipeline = promisify(stream.pipeline);
 
@@ -78,7 +89,7 @@ export function createDownloadBuildFunction(ctx: CustomBuildContext): BuildFunct
         required: true,
       }),
     ],
-    fn: async (stepsCtx, { inputs, outputs }) => {
+    fn: async (stepsCtx, { inputs, outputs, signal }) => {
       const { logger } = stepsCtx;
 
       const extensions = z.array(z.string()).parse(inputs.extensions.value);
@@ -117,8 +128,10 @@ export function createDownloadBuildFunction(ctx: CustomBuildContext): BuildFunct
         logger,
         ...source,
         graphqlClient: ctx.graphqlClient,
+        deviceRunSessionWorkerApi: buildId ? getDeviceRunSessionWorkerApi(ctx) : null,
         robotAccessToken: stepsCtx.global.staticContext.job.secrets?.robotAccessToken ?? null,
         extensions,
+        signal,
       });
 
       outputs.artifact_path.set(artifactPath);
@@ -129,22 +142,50 @@ export function createDownloadBuildFunction(ctx: CustomBuildContext): BuildFunct
 async function fetchApplicationArchiveUrlAsync({
   buildId,
   graphqlClient,
+  deviceRunSessionWorkerApi,
+  signal,
 }: {
   buildId: string;
   graphqlClient: Client;
+  deviceRunSessionWorkerApi?: DeviceRunSessionWorkerApi | null;
+  signal?: AbortSignal;
 }): Promise<string> {
-  const result = await graphqlClient.query(BUILD_BY_ID_QUERY, { buildId }).toPromise();
-
-  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 });
+  signal?.throwIfAborted();
+  if (deviceRunSessionWorkerApi) {
+    return await fetchDeviceRunSessionApplicationArchiveUrlAsync({
+      buildId,
+      deviceRunSessionWorkerApi,
+      signal,
+    });
   }
+  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();
 
-  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',
@@ -155,15 +196,76 @@ async function fetchApplicationArchiveUrlAsync({
   return applicationArchiveUrl;
 }
 
+/**
+ * A device run session token can read only the build of its own session, so the build comes from
+ * `GET /v2/device-run-session-worker/application` instead of the builds GraphQL query.
+ *
+ * Only device run session jobs, whose steps www generates from the session, reach this path, so
+ * every failure here is a system error: neither the request nor `build_id` comes from the user.
+ */
+async function fetchDeviceRunSessionApplicationArchiveUrlAsync({
+  buildId,
+  deviceRunSessionWorkerApi,
+  signal,
+}: {
+  buildId: string;
+  deviceRunSessionWorkerApi: DeviceRunSessionWorkerApi;
+  signal?: AbortSignal;
+}): Promise<string> {
+  let application;
+  try {
+    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: ${describeError(err)}`,
+      { cause: err }
+    );
+  }
+  signal?.throwIfAborted();
+
+  if (application.build?.id !== buildId) {
+    throw new SystemError(
+      `Could not fetch build ${buildId}: this device run session runs ${
+        application.build ? `build ${application.build.id}` : 'no build'
+      }, and its session token can read only that build. www generates this step from the ` +
+        'session, so the two should always match. Start a new session, and contact support if ' +
+        'it happens again.'
+    );
+  }
+  if (!application.build.applicationArchiveUrl) {
+    throw new UserError(
+      'EAS_DOWNLOAD_BUILD_NO_APPLICATION_ARCHIVE',
+      'Build does not have an application archive url'
+    );
+  }
+  return application.build.applicationArchiveUrl;
+}
+
 export async function downloadBuildAsync(
   params: DownloadBuildSource & {
     logger: bunyan;
     graphqlClient: Client;
+    /**
+     * Set in a device run session job that has a session token. The build lookup then uses the
+     * device run session worker API instead of GraphQL.
+     */
+    deviceRunSessionWorkerApi?: DeviceRunSessionWorkerApi | null;
     robotAccessToken: string | null;
     extensions: string[];
+    /** Stops the build lookup, the request and the file write when aborted, and skips the rest. */
+    signal?: AbortSignal;
   }
 ): Promise<{ artifactPath: string }> {
-  const { logger, graphqlClient, robotAccessToken, extensions } = params;
+  const { logger, graphqlClient, deviceRunSessionWorkerApi, robotAccessToken, extensions, signal } =
+    params;
 
   let downloadUrl: string;
   let headers: { Authorization: string } | undefined;
@@ -178,8 +280,19 @@ export async function downloadBuildAsync(
     headers = undefined;
   } else if (params.buildId) {
     const buildId = z.string().uuid().parse(params.buildId);
-    downloadUrl = await fetchApplicationArchiveUrlAsync({ buildId, graphqlClient });
-    headers = robotAccessToken ? { Authorization: `Bearer ${robotAccessToken}` } : undefined;
+    downloadUrl = await fetchApplicationArchiveUrlAsync({
+      buildId,
+      graphqlClient,
+      deviceRunSessionWorkerApi,
+      signal,
+    });
+    // The archive URL from the device run session worker API points to an artifact route that
+    // needs no auth. After www stops minting EXPO_TOKEN for session jobs, robotAccessToken is the
+    // session token, and www rejects it as a bearer credential on every route.
+    headers =
+      robotAccessToken && !deviceRunSessionWorkerApi
+        ? { Authorization: `Bearer ${robotAccessToken}` }
+        : undefined;
   } else {
     throw new UserError(
       'EAS_DOWNLOAD_BUILD_INVALID_SOURCE',
@@ -191,17 +304,36 @@ export async function downloadBuildAsync(
     path.join(os.tmpdir(), 'download_build-downloaded-')
   );
 
-  const response = await retryOnDNSFailure(fetch)(downloadUrl, { headers });
-
-  if (!response.ok) {
-    const textResult = await asyncResult(response.text());
-    throw new Error(`Unexpected response from server (${response.status}): ${textResult.value}`);
+  signal?.throwIfAborted();
+  let archivePath: string;
+  try {
+    archivePath = await retryOnNetworkFailureAsync(
+      async () => {
+        const response = await fetch(downloadUrl, { headers, signal });
+        if (!response.ok) {
+          const textResult = await asyncResult(response.text());
+          throw new Error(
+            `Unexpected response from server (${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);
-
-  await streamPipeline(response.body, fs.createWriteStream(archivePath));
+  signal?.throwIfAborted();
 
   const { size } = await fs.promises.stat(archivePath);
 
@@ -217,10 +349,15 @@ export async function downloadBuildAsync(
   const extractionDirectory = await fs.promises.mkdtemp(
     path.join(os.tmpdir(), 'download_build-extracted-')
   );
+  // Not interrupted on abort: tar cannot stop its in-flight file writes, so an abort during
+  // the extraction lets it finish (local, bounded work) and is reported right after it.
+  // This way no file is written after this function settles.
+  signal?.throwIfAborted();
   await decompressTarAsync({
     archivePath,
     destinationDirectory: extractionDirectory,
   });
+  signal?.throwIfAborted();
 
   const matchingFiles = await glob(`**/*.(${extensions.join('|')})`, {
     absolute: true,

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

@@ -0,0 +1,114 @@
+import { SystemError, UserError } from '@expo/eas-build-job';
+import {
+  BuildFunction,
+  BuildStepInput,
+  BuildStepInputValueTypeName,
+  BuildStepOutput,
+} from '@expo/steps';
+import { graphql } from 'gql.tada';
+import { z } from 'zod';
+
+import { downloadBuildAsync } from './downloadBuild';
+import { CustomBuildContext } from '../../customBuildContext';
+import { graphqlAbortContext } from '../../utils/graphqlAbort';
+import { promiseRetryWithCondition } from '../../utils/promiseRetryWithCondition';
+
+const CREATE_ARCHIVE_DOWNLOAD_URL = graphql(`
+  mutation GenerateSubmissionArchiveDownloadUrl($submissionId: ID!) {
+    submission {
+      generateSubmissionArchiveDownloadUrl(submissionId: $submissionId)
+    }
+  }
+`);
+
+export function createDownloadSubmissionArchiveFunction(ctx: CustomBuildContext): BuildFunction {
+  return new BuildFunction({
+    namespace: 'eas',
+    id: 'download_submission_archive',
+    name: 'Download submission archive',
+    __metricsId: 'eas/download_submission_archive',
+    inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'submission_id',
+        required: true,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
+      BuildStepInput.createProvider({
+        id: 'extensions',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+        defaultValue: ['apk', 'aab', 'ipa'],
+      }),
+    ],
+    outputProviders: [
+      BuildStepOutput.createProvider({
+        id: 'artifact_path',
+        required: true,
+      }),
+    ],
+    fn: async (stepsCtx, { inputs, outputs, signal }) => {
+      const { submissionId, extensions } = z
+        .object({
+          submissionId: z.string().uuid(),
+          extensions: z.array(z.string()),
+        })
+        .parse({
+          submissionId: inputs.submission_id.value,
+          extensions: inputs.extensions.value,
+        });
+
+      stepsCtx.logger.info(`Downloading archive for submission ${submissionId}...`);
+
+      const applicationArchiveUrl = await promiseRetryWithCondition(
+        async () => {
+          signal?.throwIfAborted();
+
+          const result = await ctx.graphqlClient
+            .mutation(CREATE_ARCHIVE_DOWNLOAD_URL, { submissionId }, graphqlAbortContext(signal))
+            .toPromise();
+
+          signal?.throwIfAborted();
+
+          if (result.error) {
+            throw result.error.networkError || result.error.response?.status >= 500
+              ? new SystemError('Could not request the submission archive. Try again later.', {
+                  cause: result.error,
+                })
+              : new UserError(
+                  'EAS_SUBMISSION_ARCHIVE_FETCH_FAILED',
+                  'Could not request the submission archive. Check your project access and the submission archive.',
+                  { cause: result.error }
+                );
+          }
+
+          const url = result.data?.submission.generateSubmissionArchiveDownloadUrl;
+
+          if (!url) {
+            throw new SystemError(
+              'The server did not return a submission archive URL. Try again later.'
+            );
+          }
+          return url;
+        },
+        error => !signal?.aborted && error instanceof SystemError,
+        { retries: 3, minTimeout: 1000, maxTimeout: 1000 },
+        ({ attemptNumber, maxAttemptsCount }) => {
+          stepsCtx.logger.info(
+            `Retrying submission archive URL request (${attemptNumber}/${maxAttemptsCount})...`
+          );
+        }
+      )();
+
+      const { artifactPath } = await downloadBuildAsync({
+        logger: stepsCtx.logger,
+        graphqlClient: ctx.graphqlClient,
+        applicationArchiveUrl,
+        robotAccessToken: null,
+        extensions,
+        signal,
+      });
+
+      outputs.artifact_path.set(artifactPath);
+    },
+  });
+}

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

@@ -199,10 +199,15 @@ export function createInstallMaestroBuildFunction(): BuildFunction {
       }
 
       if (backend === 'maestro-runner' && global.runtimePlatform === BuildRuntimePlatform.DARWIN) {
-        await installMaestroRunnerWdaCache({
-          logger,
-          env,
-        });
+        // Runner 1.1.28 switched the default iOS driver to the bundled DeviceLab agent.
+        // Use the detected version after installation, including when `latest` was requested.
+        const installedRunnerVersion = semver.coerce(maestroVersionResult.value);
+        if (!installedRunnerVersion || semver.lt(installedRunnerVersion, '1.1.28')) {
+          await installMaestroRunnerWdaCache({
+            logger,
+            env,
+          });
+        }
       }
 
       logger.info(`${backend} ${maestroVersionResult.value} is ready.`);

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

@@ -0,0 +1,104 @@
+import { bunyan } from '@expo/logger';
+import { asyncResult } from '@expo/results';
+import { BuildFunction, BuildRuntimePlatform, BuildStepEnv } from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+import fs from 'node:fs';
+
+import { Sentry } from '../../sentry';
+
+export function createInstallMitmproxyBuildFunction(): BuildFunction {
+  return new BuildFunction({
+    namespace: 'eas',
+    id: 'install_mitmproxy',
+    name: 'Install mitmproxy',
+    __metricsId: 'eas/install_mitmproxy',
+    supportedRuntimePlatforms: [BuildRuntimePlatform.DARWIN],
+    fn: async ({ logger }, { env }) => {
+      // Some images ship the cask, and its quarantined first launch can hang.
+      const canLaunch =
+        env.EAS_BUILD_RUNNER !== 'eas-build' || (await removeMitmproxyQuarantineAsync(env));
+      if (canLaunch && (await isMitmproxyAvailableAsync(env))) {
+        logger.info('mitmproxy is already installed.');
+        return;
+      }
+
+      if (env.EAS_BUILD_RUNNER !== 'eas-build') {
+        logger.warn(
+          'mitmproxy is not installed and network capture needs it. Install it with `brew install --cask mitmproxy` and rerun the job.'
+        );
+        return;
+      }
+
+      try {
+        logger.info('Installing mitmproxy with Homebrew.');
+        await installMitmproxyWithHomebrewAsync({ env, logger });
+        if (!(await removeMitmproxyQuarantineAsync(env))) {
+          throw new Error('Could not launch mitmproxy because it is still quarantined.');
+        }
+        if (!(await isMitmproxyAvailableAsync(env))) {
+          throw new Error('`brew install --cask mitmproxy` succeeded but mitmdump did not run.');
+        }
+        logger.info('Installed mitmproxy.');
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        Sentry.capture('Could not install mitmproxy for the device session', error, {
+          level: 'warning',
+        });
+        logger.warn(
+          { err: error },
+          'Could not install mitmproxy, so network capture will record nothing in this session. Re-run the session to retry the install, or run it without network capture.'
+        );
+      }
+    },
+  });
+}
+
+async function isMitmproxyAvailableAsync(env: BuildStepEnv): Promise<boolean> {
+  // Kills a first launch that Gatekeeper still holds, if the quarantine check missed it. Without
+  // pipes, a child process that outlives mitmdump cannot hold the call open past the timeout.
+  return (
+    await asyncResult(
+      spawn('mitmdump', ['--version'], {
+        env,
+        stdio: 'ignore',
+        timeout: 60_000,
+        killSignal: 'SIGKILL',
+      })
+    )
+  ).ok;
+}
+
+async function installMitmproxyWithHomebrewAsync({
+  env,
+  logger,
+}: {
+  env: BuildStepEnv;
+  logger: bunyan;
+}): Promise<void> {
+  await spawn('brew', ['install', '--cask', 'mitmproxy'], {
+    env: { ...env, HOMEBREW_NO_AUTO_UPDATE: '1' },
+    logger,
+  });
+}
+
+/**
+ * Gatekeeper has rejected the mitmproxy 12.2.3 cask as unnotarized since 2026-10-06, and a
+ * quarantined first launch then never returns. Takes the app behind the `mitmdump` on PATH out of
+ * quarantine, and returns false when it stays quarantined, so it is not launched.
+ */
+async function removeMitmproxyQuarantineAsync(env: BuildStepEnv): Promise<boolean> {
+  const which = await asyncResult(spawn('which', ['mitmdump'], { env, stdio: 'pipe' }));
+  const mitmdump = which.ok
+    ? await fs.promises.realpath(which.value.stdout.trim()).catch(() => null)
+    : null;
+  if (!mitmdump) {
+    return true;
+  }
+  const appEnd = mitmdump.lastIndexOf('.app/');
+  const app = appEnd === -1 ? mitmdump : mitmdump.slice(0, appEnd + '.app'.length);
+  await asyncResult(spawn('xattr', ['-dr', 'com.apple.quarantine', app], { env, stdio: 'pipe' }));
+  const quarantined = await asyncResult(
+    spawn('xattr', ['-p', 'com.apple.quarantine', mitmdump], { env, stdio: 'pipe' })
+  );
+  return !quarantined.ok;
+}

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,34 +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,
-        '-n',
-        `${applicationIdentifier}/${activityName}`,
-      ],
+    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

@@ -107,6 +107,8 @@ function buildMaestroArgs({
       return { executable: 'maestro', args };
     }
     case 'maestro-runner': {
+      // The runner writes every report format to one directory. output_format only
+      // selects which extra report artifact EAS uploads after the test.
       const args = [`--platform=${platform}`, 'test', `--output=${output}`, '--flatten'];
       if (shards !== undefined && shards > 1) {
         args.push(`--parallel=${shards}`);
@@ -213,23 +215,20 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
       }
       const testsDirectory = path.join(home, '.maestro', 'tests');
       const junitReportDirectory = path.join(testsDirectory, 'junit-reports');
-      const finalReportPath =
-        outputFormat === 'junit'
-          ? path.join(testsDirectory, `${platform}-maestro-junit.xml`)
-          : undefined;
+      const junitFinalReportPath = path.join(testsDirectory, `${platform}-maestro-junit.xml`);
 
       // Public docs (EAS workflows pre-packaged-jobs) document
       // `${MAESTRO_TESTS_DIR}` for users to save screenshots/recordings into
       // the uploaded dir.
       const spawnEnv: NodeJS.ProcessEnv = { ...env, MAESTRO_TESTS_DIR: testsDirectory };
 
-      // Outputs are published BEFORE any throw below so downstream
-      // `if: always()` upload steps still see populated values when this
-      // step fails early.
+      // Publish known paths before backend validation so `if: always()` upload
+      // steps can use them after an early failure. final_report_path names the
+      // report selected by output_format, not every report the backend produces.
       outputs.tests_directory.set(testsDirectory);
       outputs.junit_report_directory.set(junitReportDirectory);
-      if (finalReportPath !== undefined) {
-        outputs.final_report_path.set(finalReportPath);
+      if (outputFormat === 'junit') {
+        outputs.final_report_path.set(junitFinalReportPath);
       }
 
       // Resolved after the output assignments above: an invalid backend input or
@@ -239,6 +238,16 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
         input: inputs.backend.value,
         env,
       });
+      // The runner can write JUnit regardless of output_format; Maestro CLI only
+      // writes it when JUnit is selected. Either command may fail before it writes a file.
+      const mayHaveJUnitReports = backend === 'maestro-runner' || outputFormat === 'junit';
+      const maestroCliOutputPath =
+        backend === 'maestro' && outputFormat && outputFormat !== 'junit'
+          ? path.join(testsDirectory, `${platform}-maestro-${outputFormat}.${outputFormat}`)
+          : null;
+      if (backend === 'maestro' && outputFormat === 'html' && maestroCliOutputPath) {
+        outputs.final_report_path.set(maestroCliOutputPath);
+      }
 
       const flowPaths = parseInput(
         FlowPathSchema,
@@ -262,10 +271,14 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
           undefined,
         'android_connection_mode and EAS_MAESTRO_ANDROID_CONNECTION_MODE must be either "adb" or "dadb".'
       );
-      if (backend === 'maestro-runner' && outputFormat !== undefined && outputFormat !== 'junit') {
+      if (
+        backend === 'maestro-runner' &&
+        outputFormat !== undefined &&
+        !['junit', 'html', 'allure'].includes(outputFormat)
+      ) {
         throw new UserError(
           'ERR_MAESTRO_INVALID_INPUT',
-          `maestro-runner only supports the "junit" output_format, but received "${outputFormat}".`
+          `maestro-runner supports "junit", "html", and "allure" output_format values, but received "${outputFormat}".`
         );
       }
       const retryFailedOnly = inputs.retry_failed_only.value as boolean;
@@ -337,17 +350,14 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
       }
 
       for (let attempt = 0; attempt <= retries; attempt++) {
-        // maestro-runner writes its JUnit report and screenshot metadata to this directory.
+        // maestro-runner writes all report formats and screenshot metadata here.
         const runnerOutputDirectory = path.join(
           testsDirectory,
           `${platform}-maestro-runner-attempt-${attempt}`
         );
-        const outputPath =
-          outputFormat === 'junit'
-            ? path.join(junitReportDirectory, `${platform}-maestro-junit-attempt-${attempt}.xml`)
-            : backend === 'maestro' && outputFormat
-              ? path.join(testsDirectory, `${platform}-maestro-${outputFormat}.${outputFormat}`)
-              : null;
+        const outputPath = mayHaveJUnitReports
+          ? path.join(junitReportDirectory, `${platform}-maestro-junit-attempt-${attempt}.xml`)
+          : maestroCliOutputPath;
         const { executable, args: maestroArgs } = buildMaestroArgs({
           backend,
           platform,
@@ -371,6 +381,17 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
             logger.warn({ err }, `Failed to clear ${runnerOutputDirectory} before the attempt.`);
           }
         }
+        // Maestro CLI uses the same HTML path for every retry. Remove the previous report
+        // before spawning so an attempt that fails before report generation cannot upload it.
+        if (backend === 'maestro' && outputFormat === 'html' && maestroCliOutputPath) {
+          try {
+            await fs.rm(maestroCliOutputPath, { force: true });
+          } catch (err) {
+            throw new SystemError('Failed to clear the previous Maestro HTML report', {
+              cause: err,
+            });
+          }
+        }
 
         const attemptStartedAtMs = Date.now();
 
@@ -412,9 +433,8 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
           reportDirectories.push(runnerOutputDirectory);
         }
 
-        // Harvest this attempt's failure screenshots before any retry subsetting. Gated on
-        // junit: test-case-result rows (and therefore the summary icons) only exist for junit
-        // runs, so harvesting other formats would just create orphan artifacts the website hides.
+        // The pre-packaged job reports test cases only for JUnit (the default format).
+        // Individual screenshots need those test cases to be visible on the website.
         if (outputFormat === 'junit') {
           let screenshots: HarvestedScreenshot[];
           switch (backend) {
@@ -504,14 +524,15 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
         await sleepAsync(2000);
       }
 
-      // Smart merge first; on data errors (bad XML, missing input) fall back
-      // to copy-latest so the caller still gets a single JUnit file.
+      // Only JUnit is merged into final_report_path. Runner HTML/Allure keeps its
+      // per-attempt JUnit files, but final_report_path names the selected report.
+      // On data errors (bad XML, missing input), fall back to copy-latest.
       // Filesystem errors short-circuit straight to SystemError.
-      if (finalReportPath !== undefined) {
+      if (outputFormat === 'junit') {
         try {
           await mergeJUnitReports({
             sourceDir: junitReportDirectory,
-            outputPath: finalReportPath,
+            outputPath: junitFinalReportPath,
           });
         } catch (mergeErr: any) {
           if (isFilesystemError(mergeErr)) {
@@ -521,7 +542,7 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
           try {
             await copyLatestAttemptXml({
               sourceDir: junitReportDirectory,
-              outputPath: finalReportPath,
+              outputPath: junitFinalReportPath,
             });
           } catch (copyErr: any) {
             // Swallow: a copy failure here usually means maestro itself failed
@@ -529,14 +550,13 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
             // the real reason and cancel billing for a user-side failure — let
             // the lastAttemptExitCode check below surface ERR_MAESTRO_TESTS_FAILED.
             logger.warn(
-              `Failed to produce final_report_path at ${finalReportPath}: ${copyErr?.message ?? copyErr}`
+              `Failed to produce final_report_path at ${junitFinalReportPath}: ${copyErr?.message ?? copyErr}`
             );
           }
         }
       }
 
-      // Upload before the ERR_MAESTRO_TESTS_FAILED throw below so fully-failed runs (which need
-      // screenshots most) still upload. Harvest only ran for junit, so guard the same way.
+      // Upload before the failure verdict so fully-failed runs still get screenshots.
       if (outputFormat === 'junit') {
         await uploadFailureScreenshotsAsync({
           harvested,
@@ -547,6 +567,81 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
         });
       }
 
+      // Upload the selected non-JUnit report before the failure verdict. The pre-packaged
+      // job also uploads testsDirectory, but a named artifact makes the report easy to find.
+      let selectedReport:
+        | { name: string; artifactPath: string; finalReportPath: string }
+        | undefined;
+      switch (outputFormat) {
+        case 'html': {
+          switch (backend) {
+            case 'maestro': {
+              if (!maestroCliOutputPath) {
+                break;
+              }
+              selectedReport = {
+                name: 'Maestro HTML Report',
+                artifactPath: maestroCliOutputPath,
+                finalReportPath: maestroCliOutputPath,
+              };
+              break;
+            }
+            case 'maestro-runner': {
+              const reportDirectory = reportDirectories.at(-1);
+              if (!reportDirectory) {
+                break;
+              }
+              // HTML references nearby screenshots, so keep its whole attempt directory.
+              selectedReport = {
+                name: 'Maestro Runner HTML Report',
+                artifactPath: reportDirectory,
+                finalReportPath: path.join(reportDirectory, 'report.html'),
+              };
+              break;
+            }
+          }
+          break;
+        }
+        case 'allure': {
+          switch (backend) {
+            case 'maestro':
+              logger.warn(
+                'Maestro CLI does not support Allure reports; no Allure artifact was uploaded.'
+              );
+              break;
+            case 'maestro-runner': {
+              const reportDirectory = reportDirectories.at(-1);
+              if (!reportDirectory) {
+                break;
+              }
+              const allureResultsDirectory = path.join(reportDirectory, 'allure-results');
+              selectedReport = {
+                name: 'Maestro Runner Allure Results',
+                artifactPath: allureResultsDirectory,
+                finalReportPath: allureResultsDirectory,
+              };
+              break;
+            }
+          }
+          break;
+        }
+      }
+      if (selectedReport) {
+        outputs.final_report_path.set(selectedReport.finalReportPath);
+        try {
+          await ctx.runtimeApi.uploadArtifact({
+            artifact: {
+              type: GenericArtifactType.OTHER,
+              name: selectedReport.name,
+              paths: [selectedReport.artifactPath],
+            },
+            logger,
+          });
+        } catch (err: any) {
+          logger.warn({ err }, `Failed to upload ${selectedReport.name}.`);
+        }
+      }
+
       // The retry loop exits via success (0), numeric status (retryable),
       // or throw (infra). A non-null non-zero status means the user's tests
       // failed every attempt.