v27.9.0

* [eas-cli] warn about EAS Simulator outages in simulator:start

* [eas-cli] name the simulator status page service Expo Simulators

.github/workflows/changelog.yml

@@ -28,7 +28,9 @@ jobs:
           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' }}
+      # The base branch, not `pull_request.base.sha`: that SHA can be older than the base that the
+      # checked-out merge commit contains, and the diff then includes other people's changes.
+      BASE_REF: origin/${{ github.base_ref || 'main' }}
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:

CHANGELOG.md

@@ -2,6 +2,81 @@
 
 This is the log of notable changes to EAS CLI and related packages.
 
+## [27.9.0](https://github.com/expo/eas-cli/releases/tag/v27.9.0) - 2026-11-12
+
+### 🎉 New features
+
+- [eas-cli] Warn about Expo Simulators and EAS Workflows outages from status.expo.dev before `eas simulator:start` creates a session, and describe degraded performance and maintenance correctly in all outage warnings. ([#4873](https://github.com/expo/eas-cli/pull/4873) by [@szdziedzic](https://github.com/szdziedzic))
+
+## [27.8.0](https://github.com/expo/eas-cli/releases/tag/v27.8.0) - 2026-11-12
+
+### 🎉 New features
+
+- [eas-cli] Tell accounts without EAS Simulator access that it is available on the Starter, Production, and Enterprise plans and link to the billing page, instead of pointing at the waitlist. `simulator:availability --json` now returns `billingUrl` instead of `waitlistUrl`. ([#4866](https://github.com/expo/eas-cli/pull/4866) by [@szdziedzic](https://github.com/szdziedzic))
+
+### 🐛 Bug fixes
+
+- [build-tools] Point expo-device-hub at the scrcpy server copy in the `turtle-v2` bucket in Android device sessions, so a failed GitHub release download no longer fails the session. expo-device-hub falls back to GitHub when the copy is missing. ([#4848](https://github.com/expo/eas-cli/pull/4848) by [@sjkim-expo](https://github.com/sjkim-expo))
+- [build-tools] Fix black iOS session preview artifacts on multi-display Simulators by capturing the active display through serve-sim. ([#4777](https://github.com/expo/eas-cli/pull/4777) by [@gwdp](https://github.com/gwdp))
+
+  Skip automatic previews on older serve-sim versions that cannot exclude them from idle activity.
+
+- [build-tools] Report flow tags with the Maestro test results of jobs that run `maestro-runner`. The tags are read from the runner's `report.json`. ([#4853](https://github.com/expo/eas-cli/pull/4853) by [@hSATAC](https://github.com/hSATAC))
+- [build-tools] Send the session preview size to `preview-upload-session` and refresh it when the size changes. ([#4864](https://github.com/expo/eas-cli/pull/4864) by [@hirbod](https://github.com/hirbod))
+- [eas-cli] Remove the "Android emulator support is still in development" warning from `eas simulator`. ([#4870](https://github.com/expo/eas-cli/pull/4870) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools] Send the width, height and source of simulator session screenshots (manual, agent-device and Argent, including Argent screenshot diffs) as artifact metadata, read from the image header. ([#4858](https://github.com/expo/eas-cli/pull/4858) by [@hirbod](https://github.com/hirbod))
+- [eas-cli][build-tools][eas-build-job] Fix sizes of 102.4 GB and larger being printed with a value about a million times too large, and share one `formatBytes` helper between `eas-cli` and `build-tools`. ([#4854](https://github.com/expo/eas-cli/pull/4854) by [@vonovak](https://github.com/vonovak))
+- [eas-cli] Package local Simulator app bundles for upload when the host supports gzip tar archives, and reject unsupported IPA and ZIP installs before uploading. ([#4684](https://github.com/expo/eas-cli/pull/4684) by [@gwdp](https://github.com/gwdp))
+
+  Fix packaging stalls for app bundles containing hard links and clean temporary archives when interrupted. Local app directories and `.tar.gz`/`.tgz` files require a host advertising archive support.
+
+- [eas-cli] Remove the `[EXPERIMENTAL]` label from `eas simulator` commands, except `eas simulator:egress` and the `--egress` flag. ([#4869](https://github.com/expo/eas-cli/pull/4869) by [@szdziedzic](https://github.com/szdziedzic))
+
+## [27.7.2](https://github.com/expo/eas-cli/releases/tag/v27.7.2) - 2026-11-10
+
+### 🐛 Bug fixes
+
+- [eas-cli] Add `--log-source` to `eas simulator` to select which Android logs a session records. ([#4823](https://github.com/expo/eas-cli/pull/4823) by [@vonovak](https://github.com/vonovak))
+- [build-tools] Start SSH session shells in the job's build directory instead of the worker's directory. ([#4843](https://github.com/expo/eas-cli/pull/4843) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- [eas-cli] Show that the ssh session has ended, instead of saying SSH was not enabled, when `eas workflow:ssh` is given the ID of a finished build. ([#4842](https://github.com/expo/eas-cli/pull/4842) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- [eas-cli] Show the ID argument and examples in `eas workflow:ssh --help`. ([#4829](https://github.com/expo/eas-cli/pull/4829) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+## [27.7.1](https://github.com/expo/eas-cli/releases/tag/v27.7.1) - 2026-11-10
+
+### 🐛 Bug fixes
+
+- [eas-cli][eas-json][build-tools][eas-build-job][steps][local-build-plugin][worker][simulator-launcher] Update `node-forge`, `tar`, `nanoid`, `minimatch`, `joi`, `ajv`, `yaml`, and `zod` to versions with fixes for published security advisories. ([#4847](https://github.com/expo/eas-cli/pull/4847) by [@tchayen](https://github.com/tchayen))
+- [build-tools] Strip the GitHub repository access token from the git remote before a sandbox agent starts. ([#4826](https://github.com/expo/eas-cli/pull/4826) by [@sswrk](https://github.com/sswrk))
+
+## [27.7.0](https://github.com/expo/eas-cli/releases/tag/v27.7.0) - 2026-11-10
+
+### 🎉 New features
+
+- [eas-cli] Add `--git-branch` and `--git-commit-hash` to `eas workflow:run` to record the branch and commit of the uploaded project. ([#4815](https://github.com/expo/eas-cli/pull/4815) by [@hSATAC](https://github.com/hSATAC))
+
+### 🐛 Bug fixes
+
+- [build-tools] Record Android emulator output and, when selected, device logcat during simulator sessions, and upload the last 20 MiB of each as a session artifact. ([#4822](https://github.com/expo/eas-cli/pull/4822) by [@vonovak](https://github.com/vonovak))
+- [eas-cli] Stop spinners from flickering when their text wraps onto a second line, such as the `simulator:start` queue message in a narrow terminal. ([#4850](https://github.com/expo/eas-cli/pull/4850) by [@brentvatne](https://github.com/brentvatne))
+
+## [27.6.0](https://github.com/expo/eas-cli/releases/tag/v27.6.0) - 2026-11-10
+
+### 🎉 New features
+
+- [build-tools] Reuse compatible prefetched Appium and XCUITest files without removing them during cleanup. Resolve explicit package versions, including `latest`, and reuse prepared tools only when they match. Use the launcher's runtime serve-sim version for warm adoption and recordings, including prereleases. ([#4837](https://github.com/expo/eas-cli/pull/4837) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add the `--property key=value` flag to `eas observe:events` to filter events by a property value. ([#4812](https://github.com/expo/eas-cli/pull/4812) by [@Ubax](https://github.com/Ubax))
+- [simulator-launcher] Prepare pinned Appium, XCUITest and WebDriverAgent files with `prefetch`. ([#4836](https://github.com/expo/eas-cli/pull/4836) by [@gwdp](https://github.com/gwdp))
+- [simulator-launcher] Add `simulator-launcher prefetch` to cache Expo Go downloads. ([#4834](https://github.com/expo/eas-cli/pull/4834) by [@gwdp](https://github.com/gwdp))
+- [simulator-launcher] Use caller-supplied serve-sim, agent-device and Argent versions and include exact version inputs in claims. ([#4845](https://github.com/expo/eas-cli/pull/4845) by [@gwdp](https://github.com/gwdp))
+- [simulator-launcher] Add `simulator-launcher warmup` so consumers can warm up Simulators, install Expo Go and prepare native tool caches. The command stops its tools and shuts down the selected Simulators before returning. ([#4838](https://github.com/expo/eas-cli/pull/4838) by [@gwdp](https://github.com/gwdp))
+
+### 🐛 Bug fixes
+
+- [build-tools] Stop waiting for `com.apple.datamigrator` to exit before an iOS Simulator on iOS 27.2 or later counts as ready; there it stays resident, so the wait never finished. Earlier runtimes keep the wait. Take the readiness screenshot from the first integrated screen when the device lists several, so the iPhone Duo on iOS 27.2 passes the check. ([#4816](https://github.com/expo/eas-cli/pull/4816) by [@hSATAC](https://github.com/hSATAC))
+- [eas-cli] Stop suggesting other event names in `eas observe:events` when an event name with `--session-id`, `--app-version`, `--build-number`, or `--update-id` returns no events. ([#4813](https://github.com/expo/eas-cli/pull/4813) by [@Ubax](https://github.com/Ubax))
+- [build-tools] Require the sandbox worker token for sandbox jobs and remove the sandbox GraphQL fallback. ([#4808](https://github.com/expo/eas-cli/pull/4808) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- [vm-tools] Run the macOS VM-tools service with interactive scheduling so Simulator startup and preview processes avoid launchd's default CPU and I/O throttling. ([#4833](https://github.com/expo/eas-cli/pull/4833) by [@gwdp](https://github.com/gwdp))
+
 ## [27.5.0](https://github.com/expo/eas-cli/releases/tag/v27.5.0) - 2026-11-05
 
 ### 🎉 New features

cli-versions.json

@@ -1,4 +1,4 @@
 {
-  "STAGING": "27.4.1",
-  "PRODUCTION": "27.4.1"
+  "STAGING": "27.8.0",
+  "PRODUCTION": "27.8.0"
 }

lerna.json

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

packages/build-tools/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @expo/build-tools
 
+## 27.9.0
+
+No changes in this release.
+
+## 27.8.0
+
+### Patch Changes
+
+- Point expo-device-hub at the scrcpy server copy in the `turtle-v2` bucket in Android device sessions, so a failed GitHub release download no longer fails the session. expo-device-hub falls back to GitHub when the copy is missing. ([#4848](https://github.com/expo/eas-cli/pull/4848) by [@sjkim-expo](https://github.com/sjkim-expo))
+- Fix black iOS session preview artifacts on multi-display Simulators by capturing the active display through serve-sim. ([#4777](https://github.com/expo/eas-cli/pull/4777) by [@gwdp](https://github.com/gwdp))
+
+  Skip automatic previews on older serve-sim versions that cannot exclude them from idle activity.
+
+- Report flow tags with the Maestro test results of jobs that run `maestro-runner`. The tags are read from the runner's `report.json`. ([#4853](https://github.com/expo/eas-cli/pull/4853) by [@hSATAC](https://github.com/hSATAC))
+- Send the session preview size to `preview-upload-session` and refresh it when the size changes. ([#4864](https://github.com/expo/eas-cli/pull/4864) by [@hirbod](https://github.com/hirbod))
+- Send the width, height and source of simulator session screenshots (manual, agent-device and Argent, including Argent screenshot diffs) as artifact metadata, read from the image header. ([#4858](https://github.com/expo/eas-cli/pull/4858) by [@hirbod](https://github.com/hirbod))
+- Fix sizes of 102.4 GB and larger being printed with a value about a million times too large, and share one `formatBytes` helper between `eas-cli` and `build-tools`. ([#4854](https://github.com/expo/eas-cli/pull/4854) by [@vonovak](https://github.com/vonovak))
+
+## 27.7.2
+
+### Patch Changes
+
+- Start SSH session shells in the job's build directory instead of the worker's directory. ([#4843](https://github.com/expo/eas-cli/pull/4843) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+## 27.7.1
+
+### Patch Changes
+
+- Update `node-forge`, `tar`, `nanoid`, `minimatch`, `joi`, `ajv`, `yaml`, and `zod` to versions with fixes for published security advisories. ([#4847](https://github.com/expo/eas-cli/pull/4847) by [@tchayen](https://github.com/tchayen))
+- Strip the GitHub repository access token from the git remote before a sandbox agent starts. ([#4826](https://github.com/expo/eas-cli/pull/4826) by [@sswrk](https://github.com/sswrk))
+
+## 27.7.0
+
+### Patch Changes
+
+- Record Android emulator output and, when selected, device logcat during simulator sessions, and upload the last 20 MiB of each as a session artifact. ([#4822](https://github.com/expo/eas-cli/pull/4822) by [@vonovak](https://github.com/vonovak))
+
+## 27.6.0
+
+### Minor Changes
+
+- Reuse compatible prefetched Appium and XCUITest files without removing them during cleanup. Resolve explicit package versions, including `latest`, and reuse prepared tools only when they match. Use the launcher's runtime serve-sim version for warm adoption and recordings, including prereleases. ([#4837](https://github.com/expo/eas-cli/pull/4837) by [@gwdp](https://github.com/gwdp))
+
+### Patch Changes
+
+- Stop waiting for `com.apple.datamigrator` to exit before an iOS Simulator on iOS 27.2 or later counts as ready; there it stays resident, so the wait never finished. Earlier runtimes keep the wait. Take the readiness screenshot from the first integrated screen when the device lists several, so the iPhone Duo on iOS 27.2 passes the check. ([#4816](https://github.com/expo/eas-cli/pull/4816) by [@hSATAC](https://github.com/hSATAC))
+- Require the sandbox worker token for sandbox jobs and remove the sandbox GraphQL fallback. ([#4808](https://github.com/expo/eas-cli/pull/4808) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
 ## 27.5.0
 
 ### Patch Changes

packages/build-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/build-tools",
-  "version": "27.5.0",
+  "version": "27.9.0",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",
@@ -42,17 +42,17 @@
   "dependencies": {
     "@expo/config": "55.0.10",
     "@expo/config-plugins": "55.0.7",
-    "@expo/downloader": "27.5.0",
-    "@expo/eas-build-job": "27.5.0",
+    "@expo/downloader": "27.9.0",
+    "@expo/eas-build-job": "27.9.0",
     "@expo/env": "^0.4.0",
-    "@expo/logger": "27.5.0",
+    "@expo/logger": "27.9.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": "27.5.0",
-    "@expo/template-file": "27.5.0",
-    "@expo/turtle-spawn": "27.5.0",
+    "@expo/steps": "27.9.0",
+    "@expo/template-file": "27.9.0",
+    "@expo/turtle-spawn": "27.9.0",
     "@expo/xcpretty": "^4.4.7",
     "@ngrok/ngrok": "1.7.0",
     "@sentry/node": "7.77.0",
@@ -63,11 +63,11 @@
     "fast-xml-parser": "^4.4.1",
     "fs-extra": "^11.2.0",
     "gql.tada": "^1.11.3",
-    "joi": "^17.13.1",
+    "joi": "^17.13.9",
     "jose": "5.10.0",
     "lodash": "^4.18.1",
     "node-fetch": "^2.7.0",
-    "node-forge": "^1.3.1",
+    "node-forge": "^1.4.3",
     "node-pty": "1.2.0-beta.15",
     "node-stream-zip": "1.15.0",
     "nullthrows": "^1.1.1",
@@ -77,11 +77,11 @@
     "resolve-from": "^5.0.0",
     "retry": "^0.13.1",
     "semver": "^7.6.2",
-    "tar": "7.5.19",
+    "tar": "7.5.22",
     "uuid": "9.0.1",
     "ws": "8.21.1",
-    "yaml": "^2.8.1",
-    "zod": "^4.3.5"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@expo/repack-app": "~0.9.0",

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

@@ -1,8 +1,8 @@
-import { UserError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import spawn from '@expo/turtle-spawn';
 import { vol } from 'memfs';
 
-import { fetchAndCheckoutRefAsync } from '../git';
+import { fetchAndCheckoutRefAsync, stripRepositoryCredentialsAsync } from '../git';
 
 jest.mock('@expo/turtle-spawn');
 
@@ -147,3 +147,64 @@ describe(fetchAndCheckoutRefAsync, () => {
     expect(error.message).not.toContain('ghs_secret123');
   });
 });
+
+describe(stripRepositoryCredentialsAsync, () => {
+  const token = 'ghs_secret123';
+
+  function mockRemoteUrl(url: string): void {
+    jest.mocked(spawn).mockResolvedValueOnce({ stdout: `${url}\n` } as never);
+  }
+
+  it('strips the token from the origin remote', async () => {
+    mockRemoteUrl(`https://x-access-token:${token}@github.com/expo/app.git`);
+
+    await stripRepositoryCredentialsAsync({ repositoryDirectory });
+
+    expect(spawn).toHaveBeenNthCalledWith(1, 'git', ['remote', 'get-url', 'origin'], {
+      cwd: repositoryDirectory,
+    });
+    expect(spawn).toHaveBeenNthCalledWith(
+      2,
+      'git',
+      ['remote', 'set-url', 'origin', 'https://github.com/expo/app.git'],
+      { cwd: repositoryDirectory }
+    );
+    expect(spawn).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps the host and port of a GitHub Enterprise remote', async () => {
+    mockRemoteUrl(`https://x-access-token:${token}@ghe.example.com:8443/org/app.git`);
+
+    await stripRepositoryCredentialsAsync({ repositoryDirectory });
+
+    expect(spawn).toHaveBeenNthCalledWith(
+      2,
+      'git',
+      ['remote', 'set-url', 'origin', 'https://ghe.example.com:8443/org/app.git'],
+      { cwd: repositoryDirectory }
+    );
+  });
+
+  it('does nothing when the origin remote carries no credentials', async () => {
+    mockRemoteUrl('https://github.com/expo/app.git');
+
+    await stripRepositoryCredentialsAsync({ repositoryDirectory });
+
+    expect(spawn).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws when the remote URL cannot be rewritten', async () => {
+    mockRemoteUrl(`https://x-access-token:${token}@github.com/expo/app.git`);
+    const gitError = Object.assign(new Error('git exited with non-zero code: 128'), {
+      stderr: "fatal: No such remote 'origin'",
+    });
+    jest.mocked(spawn).mockRejectedValueOnce(gitError);
+
+    const promise = stripRepositoryCredentialsAsync({ repositoryDirectory });
+
+    await expect(promise).rejects.toBeInstanceOf(SystemError);
+    await expect(promise).rejects.toMatchObject({ cause: gitError });
+    const error = await promise.catch(err => err);
+    expect(error.message).not.toContain(token);
+  });
+});

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

@@ -1,4 +1,4 @@
-import { ArchiveSource, ArchiveSourceType, UserError } from '@expo/eas-build-job';
+import { ArchiveSource, ArchiveSourceType, SystemError, UserError } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import spawn from '@expo/turtle-spawn';
 import fs from 'fs-extra';
@@ -99,6 +99,45 @@ export async function fetchAndCheckoutRefAsync({
   }
 }
 
+export async function stripRepositoryCredentialsAsync({
+  repositoryDirectory,
+}: {
+  repositoryDirectory: string;
+}): Promise<void> {
+  let remoteUrl: URL;
+  try {
+    const { stdout } = await spawn('git', ['remote', 'get-url', 'origin'], {
+      cwd: repositoryDirectory,
+    });
+    remoteUrl = new URL(stdout.trim());
+  } catch (err) {
+    throw new SystemError('Failed to read the origin remote URL of the project repository.', {
+      cause: err,
+    });
+  }
+
+  if (!remoteUrl.username && !remoteUrl.password) {
+    return;
+  }
+
+  try {
+    await spawn('git', ['remote', 'set-url', 'origin', stripCredentialsFromGitUrl(remoteUrl)], {
+      cwd: repositoryDirectory,
+    });
+  } catch (err) {
+    throw new SystemError('Failed to strip credentials from the origin remote URL.', {
+      cause: err,
+    });
+  }
+}
+
+function stripCredentialsFromGitUrl(url: URL): string {
+  const strippedUrl = new URL(url.toString());
+  strippedUrl.username = '';
+  strippedUrl.password = '';
+  return strippedUrl.toString();
+}
+
 function getSanitizedGitUrl(maybeGitUrl: string): string | null {
   try {
     const url = new URL(maybeGitUrl);

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

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

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

@@ -0,0 +1,48 @@
+import { BuildRuntimePlatform } from '@expo/steps';
+
+import {
+  createCustomBuildContextMock,
+  createGlobalContextMock,
+} from '../../../__tests__/utils/context';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { Sentry } from '../../../sentry';
+import { collectAndroidEmulatorLogsAsync } from '../../utils/androidEmulatorLogs';
+import { createCollectAndroidEmulatorLogsBuildFunction } from '../collectAndroidEmulatorLogs';
+
+jest.mock('../../../sentry');
+jest.mock('../../utils/androidEmulatorLogs');
+
+function createStep(callInputs: Record<string, unknown> = {}) {
+  const logger = createMockLogger();
+  const ctx = createCustomBuildContextMock();
+  const global = createGlobalContextMock({ logger });
+  const fn = createCollectAndroidEmulatorLogsBuildFunction(ctx);
+  const step = fn.createBuildStepFromFunctionCall(global, {
+    callInputs,
+    env: { DEVICE_RUN_SESSION_ID: 'session' },
+  });
+  return { ctx, global, logger, fn, step };
+}
+
+it('collects captured logs without a second source selection', async () => {
+  const { ctx, global, fn, step } = createStep();
+  expect(fn.supportedRuntimePlatforms).toEqual([BuildRuntimePlatform.LINUX]);
+  await step.executeAsync();
+  expect(collectAndroidEmulatorLogsAsync).toHaveBeenCalledWith(ctx, {
+    global,
+    deviceRunSessionId: 'session',
+    logger: expect.anything(),
+  });
+});
+
+it('reports collection failure without changing the session result', async () => {
+  jest
+    .mocked(collectAndroidEmulatorLogsAsync)
+    .mockRejectedValueOnce(new Error('collection failed'));
+  const { step } = createStep();
+  await expect(step.executeAsync()).resolves.toBeUndefined();
+  expect(Sentry.capture).toHaveBeenCalledWith(
+    'Could not collect Android emulator logs',
+    expect.any(Error)
+  );
+});

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

@@ -2,6 +2,7 @@ import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
 import fs from 'node:fs';
 
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import type { CustomBuildContext } from '../../../customBuildContext';
 import { Sentry } from '../../../sentry';
 import { AndroidEmulatorUtils } from '../../../utils/AndroidEmulatorUtils';
@@ -139,13 +140,20 @@ describe.each([
     corsOrigins?: string[]
   ) {
     const fn = createFunction({} as CustomBuildContext);
+    const global = createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.LINUX });
+    const defaults = new Map(
+      fn.inputProviders?.map(provider => {
+        const input = provider(global, 'Test session');
+        return [input.id, input.defaultValue];
+      })
+    );
     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.
+        // Match step execution: omitted inputs use their declared defaults.
         inputs: new Proxy(
           {
             public_preview: { value: publicPreview },
@@ -153,7 +161,7 @@ describe.each([
             cors_origins: { value: corsOrigins },
           } as Record<string, { value: unknown }>,
           {
-            get: (target, id: string) => target[id] ?? { value: undefined },
+            get: (target, id: string) => target[id] ?? { value: defaults.get(id) },
           }
         ),
         outputs: {},

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

@@ -15,6 +15,7 @@ import {
   parseMaestroResults,
   parseMaestroResultsFromFileAttrs,
   parseMaestroRunnerReport,
+  parseMaestroRunnerResults,
 } from '../maestroResultParser';
 
 describe(parseFailedFlowsFromMaestroRunnerReport, () => {
@@ -483,6 +484,271 @@ describe(parseMaestroResultsFromFileAttrs, () => {
   });
 });
 
+describe(parseMaestroRunnerResults, () => {
+  function runnerJUnit(testcases: { name: string; file: string; failed?: boolean }[]): string {
+    return [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<testsuites>',
+      '  <testsuite name="maestro-runner">',
+      ...testcases.flatMap(({ name, file, failed }) => [
+        `    <testcase id="${name}" name="${name}" classname="${name}" time="1.000" status="${failed ? 'ERROR' : 'SUCCESS'}">`,
+        '      <properties>',
+        `        <property name="file" value="${file}"/>`,
+        '        <property name="device.platform" value="android"/>',
+        '      </properties>',
+        ...(failed ? ['      <failure message="Element not found">tapOn</failure>'] : []),
+        '    </testcase>',
+      ]),
+      '  </testsuite>',
+      '</testsuites>',
+    ].join('\n');
+  }
+
+  it('adds the tags of each flow from the report.json of its attempt', async () => {
+    vol.fromJSON({
+      '/junit/android-maestro-junit-attempt-0.xml': runnerJUnit([
+        { name: 'sign-in', file: 'flows/auth/sign-in.yaml', failed: true },
+        { name: 'settings', file: 'flows/settings.yaml' },
+      ]),
+      '/tests/android-maestro-runner-attempt-0/report.json': JSON.stringify({
+        flows: [
+          {
+            name: 'sign-in',
+            sourceFile: 'flows/auth/sign-in.yaml',
+            status: 'failed',
+            tags: ['auth', 'smoke'],
+          },
+          { name: 'settings', sourceFile: 'flows/settings.yaml', status: 'passed' },
+        ],
+      }),
+      '/junit/android-maestro-junit-attempt-1.xml': runnerJUnit([
+        { name: 'sign-in', file: 'flows/auth/sign-in.yaml' },
+      ]),
+      '/tests/android-maestro-runner-attempt-1/report.json': JSON.stringify({
+        flows: [
+          {
+            name: 'sign-in',
+            sourceFile: 'flows/auth/sign-in.yaml',
+            status: 'passed',
+            tags: ['auth'],
+          },
+        ],
+      }),
+    });
+
+    const results = await parseMaestroRunnerResults({
+      junitDirectory: '/junit',
+      testsDirectory: '/tests',
+      workingDirectory: '/project',
+    });
+
+    expect(results).toEqual([
+      {
+        name: 'sign-in',
+        path: 'flows/auth/sign-in.yaml',
+        status: 'failed',
+        errorMessage: 'Element not found',
+        duration: 1000,
+        retryCount: 0,
+        tags: ['auth', 'smoke'],
+        properties: { file: 'flows/auth/sign-in.yaml', 'device.platform': 'android' },
+      },
+      expect.objectContaining({ path: 'flows/auth/sign-in.yaml', retryCount: 1, tags: ['auth'] }),
+      expect.objectContaining({ path: 'flows/settings.yaml', retryCount: 0, tags: [] }),
+    ]);
+  });
+
+  it('matches an absolute sourceFile with a JUnit path relative to the working directory', async () => {
+    vol.fromJSON({
+      '/junit/ios-maestro-junit-attempt-0.xml': runnerJUnit([
+        { name: 'sign-in', file: 'flows/sign-in.yaml' },
+      ]),
+      '/tests/ios-maestro-runner-attempt-0/report.json': JSON.stringify({
+        flows: [
+          {
+            name: 'sign-in',
+            sourceFile: '/project/flows/sign-in.yaml',
+            status: 'passed',
+            tags: ['auth'],
+          },
+        ],
+      }),
+    });
+
+    const results = await parseMaestroRunnerResults({
+      junitDirectory: '/junit',
+      testsDirectory: '/tests',
+      workingDirectory: '/project',
+    });
+
+    expect(results).toEqual([
+      expect.objectContaining({ path: 'flows/sign-in.yaml', tags: ['auth'] }),
+    ]);
+  });
+
+  it('matches a sourceFile under a symlinked directory with the JUnit path of its target', async () => {
+    vol.fromJSON({
+      '/project/flows/sign-in.yaml': '',
+      '/junit/ios-maestro-junit-attempt-0.xml': runnerJUnit([
+        { name: 'sign-in', file: 'flows/sign-in.yaml' },
+      ]),
+      '/tests/ios-maestro-runner-attempt-0/report.json': JSON.stringify({
+        flows: [
+          { name: 'sign-in', sourceFile: 'linked/sign-in.yaml', status: 'passed', tags: ['auth'] },
+        ],
+      }),
+    });
+    vol.symlinkSync('/project/flows', '/project/linked');
+
+    const results = await parseMaestroRunnerResults({
+      junitDirectory: '/junit',
+      testsDirectory: '/tests',
+      workingDirectory: '/project',
+    });
+
+    expect(results).toEqual([
+      expect.objectContaining({ path: 'flows/sign-in.yaml', tags: ['auth'] }),
+    ]);
+  });
+
+  it('matches a sourceFile whose symlink leaves the working directory by the path as given', async () => {
+    vol.fromJSON({
+      '/project/.keep': '',
+      '/shared/sign-in.yaml': '',
+      '/junit/ios-maestro-junit-attempt-0.xml': runnerJUnit([
+        { name: 'sign-in', file: 'linked/sign-in.yaml' },
+      ]),
+      '/tests/ios-maestro-runner-attempt-0/report.json': JSON.stringify({
+        flows: [
+          { name: 'sign-in', sourceFile: 'linked/sign-in.yaml', status: 'passed', tags: ['auth'] },
+        ],
+      }),
+    });
+    vol.symlinkSync('/shared', '/project/linked');
+
+    const results = await parseMaestroRunnerResults({
+      junitDirectory: '/junit',
+      testsDirectory: '/tests',
+      workingDirectory: '/project',
+    });
+
+    expect(results).toEqual([
+      expect.objectContaining({ path: 'linked/sign-in.yaml', tags: ['auth'] }),
+    ]);
+  });
+
+  it('does not follow a symlink from the bare file name that maestro-runner <= 1.1.17 writes', async () => {
+    vol.fromJSON({
+      '/project/flows/sign-in.yaml': '',
+      '/project/settings.yaml': '',
+      '/junit/ios-maestro-junit-attempt-0.xml': runnerJUnit([
+        { name: 'sign-in', file: 'sign-in.yaml' },
+        { name: 'settings', file: 'settings.yaml' },
+      ]),
+      '/tests/ios-maestro-runner-attempt-0/report.json': JSON.stringify({
+        flows: [
+          { name: 'sign-in', sourceFile: 'flows/sign-in.yaml', status: 'passed', tags: ['auth'] },
+          { name: 'settings', sourceFile: 'settings.yaml', status: 'passed', tags: ['settings'] },
+        ],
+      }),
+    });
+    vol.symlinkSync('/project/settings.yaml', '/project/sign-in.yaml');
+
+    const results = await parseMaestroRunnerResults({
+      junitDirectory: '/junit',
+      testsDirectory: '/tests',
+      workingDirectory: '/project',
+    });
+
+    expect(results).toEqual([
+      expect.objectContaining({ path: 'sign-in.yaml', tags: ['auth'] }),
+      expect.objectContaining({ path: 'settings.yaml', tags: ['settings'] }),
+    ]);
+  });
+
+  it('matches by file name when JUnit has only the file name and it is unique', async () => {
+    vol.fromJSON({
+      '/junit/ios-maestro-junit-attempt-0.xml': runnerJUnit([
+        { name: 'sign-in', file: 'sign-in.yaml' },
+      ]),
+      '/tests/ios-maestro-runner-attempt-0/report.json': JSON.stringify({
+        flows: [
+          {
+            name: 'sign-in',
+            sourceFile: 'flows/auth/sign-in.yaml',
+            status: 'passed',
+            tags: ['auth'],
+          },
+          {
+            name: 'settings',
+            sourceFile: 'flows/settings.yaml',
+            status: 'passed',
+            tags: ['settings'],
+          },
+        ],
+      }),
+    });
+
+    const results = await parseMaestroRunnerResults({
+      junitDirectory: '/junit',
+      testsDirectory: '/tests',
+      workingDirectory: '/project',
+    });
+
+    expect(results).toEqual([expect.objectContaining({ path: 'sign-in.yaml', tags: ['auth'] })]);
+  });
+
+  it('adds no tags when two flows of the attempt have the same file name', async () => {
+    vol.fromJSON({
+      '/junit/ios-maestro-junit-attempt-0.xml': runnerJUnit([
+        { name: 'sign-in', file: 'sign-in.yaml' },
+      ]),
+      '/tests/ios-maestro-runner-attempt-0/report.json': JSON.stringify({
+        flows: [
+          { name: 'a', sourceFile: 'flows/a/sign-in.yaml', status: 'passed', tags: ['a'] },
+          { name: 'b', sourceFile: 'flows/b/sign-in.yaml', status: 'passed', tags: ['b'] },
+        ],
+      }),
+    });
+
+    const results = await parseMaestroRunnerResults({
+      junitDirectory: '/junit',
+      testsDirectory: '/tests',
+      workingDirectory: '/project',
+    });
+
+    expect(results).toEqual([expect.objectContaining({ path: 'sign-in.yaml', tags: [] })]);
+  });
+
+  it.each([
+    { name: 'is not valid JSON', content: '{' },
+    { name: 'has an unknown shape', content: JSON.stringify({ flows: [{ name: 'sign-in' }] }) },
+    {
+      name: 'does not have the flow',
+      content: JSON.stringify({
+        flows: [{ name: 'other', sourceFile: 'flows/other.yaml', status: 'passed', tags: ['x'] }],
+      }),
+    },
+  ])('keeps the JUnit result without tags when report.json $name', async ({ content }) => {
+    vol.fromJSON({
+      '/junit/android-maestro-junit-attempt-0.xml': runnerJUnit([
+        { name: 'sign-in', file: 'flows/sign-in.yaml' },
+      ]),
+      '/tests/android-maestro-runner-attempt-0/report.json': content,
+    });
+
+    const results = await parseMaestroRunnerResults({
+      junitDirectory: '/junit',
+      testsDirectory: '/tests',
+      workingDirectory: '/project',
+    });
+
+    expect(results).toEqual([
+      expect.objectContaining({ name: 'sign-in', path: 'flows/sign-in.yaml', tags: [] }),
+    ]);
+  });
+});
+
 describe('junitFileHasFileAttrs', () => {
   it('returns true when every testcase has a non-empty file= attribute', async () => {
     vol.fromJSON({

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

@@ -358,6 +358,51 @@ describe(createReportMaestroTestResultsFunction, () => {
     );
   });
 
+  it('reports maestro-runner results with the tags from report.json', async () => {
+    vol.fromJSON({
+      '/junit/android-maestro-junit-attempt-0.xml': [
+        '<testsuites><testsuite name="maestro-runner">',
+        '  <testcase id="sign-in" name="sign-in" classname="sign-in" time="2.000" status="SUCCESS">',
+        '    <properties><property name="file" value="flows/sign-in.yaml"/></properties>',
+        '  </testcase>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+      '/tests/android-maestro-runner-attempt-0/report.json': JSON.stringify({
+        flows: [
+          {
+            name: 'sign-in',
+            sourceFile: 'flows/sign-in.yaml',
+            status: 'passed',
+            tags: ['auth', 'smoke'],
+          },
+        ],
+      }),
+    });
+    mockMutationFn.mockResolvedValue({
+      data: {
+        workflowDeviceTestCaseResult: {
+          createWorkflowDeviceTestCaseResults: [{ id: 'id-1' }],
+        },
+      },
+    });
+
+    await createStep().executeAsync();
+
+    const variables = (mockGraphqlClient.mutation as jest.Mock).mock.calls[0][1];
+    expect(variables.input.testCaseResults).toEqual([
+      {
+        name: 'sign-in',
+        path: 'flows/sign-in.yaml',
+        status: 'PASSED',
+        errorMessage: null,
+        duration: 2000,
+        retryCount: 0,
+        tags: ['auth', 'smoke'],
+        properties: { file: 'flows/sign-in.yaml' },
+      },
+    ]);
+  });
+
   it('uses default directories when inputs are not provided', async () => {
     vol.fromJSON({
       '/home/expo/.maestro/tests/report.xml': JUNIT_PASS,

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

@@ -4,6 +4,8 @@ import spawn from '@expo/turtle-spawn';
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
+import { AndroidEmulatorLogRing } from '../../../utils/androidEmulatorLogCapture';
+import { getAndroidEmulatorLogCapture } from '../../utils/androidEmulatorLogs';
 import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
 import { stopLocalEgressResourcesAsync } from '../../utils/localEgress';
 import {
@@ -35,6 +37,7 @@ jest.mock('../../utils/localEgressGuard', () => ({
   startLocalEgressGuardRelayAsync: jest.fn(),
 }));
 jest.mock('@expo/turtle-spawn');
+jest.mock('../../utils/androidEmulatorLogs');
 jest.mock('../../../utils/IosSimulatorUtils');
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
@@ -108,43 +111,28 @@ function runStep(
   inputValues: Record<string, unknown> = {},
   signal?: AbortSignal,
   stepCtx: CustomBuildContext = ctx,
-  warm = false
+  warm = false,
+  env: NodeJS.ProcessEnv = {}
 ): Promise<void> {
   const buildFunction = createStartAgentDeviceSessionBuildFunction(stepCtx, { warm });
   const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+  const global = createGlobalContextMock({
+    runtimePlatform,
+    staticContextContent: { job: { secrets: { robotAccessToken: 'robot-token' } } },
+  });
   const inputs = Object.fromEntries(
-    [
-      'device_identifier',
-      'system_image_package',
-      'lcd_width',
-      'lcd_height',
-      'lcd_density',
-      'install_app_path',
-      'build_id',
-      'application_archive_url',
-      'launch_app_identifier',
-      '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] }])
+    (buildFunction.inputProviders ?? []).map(provider => {
+      const input = provider(global, 'test');
+      input.set(inputValues[input.id]);
+      return [input.id, { value: input.rawValue }];
+    })
   );
   return buildFunction.fn!(
     {
       logger,
-      global: {
-        runtimePlatform,
-        staticContext: { job: { secrets: { robotAccessToken: 'robot-token' } } },
-      },
+      global,
     } as unknown as BuildStepContext,
-    { inputs, outputs: {}, env: {}, signal } as never
+    { inputs, outputs: {}, env, signal } as never
   ) as Promise<void>;
 }
 
@@ -173,6 +161,11 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
   }
 
   beforeEach(() => {
+    jest
+      .mocked(getAndroidEmulatorLogCapture)
+      .mockImplementation(
+        jest.requireActual('../../utils/androidEmulatorLogs').getAndroidEmulatorLogCapture
+      );
     deviceLaunch = undefined;
     jest.clearAllMocks();
     jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue(null);
@@ -437,6 +430,7 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
 
     expect(installBuildAsync).not.toHaveBeenCalled();
     expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(getAndroidEmulatorLogCapture).not.toHaveBeenCalled();
     expect(sessionDevice()).toEqual({
       iosSimulatorUdid: 'SELECTED-UDID',
       bootEnv: undefined,
@@ -444,6 +438,61 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     });
   });
 
+  it('defaults an omitted session log input to emulator output through the step boundary', async () => {
+    const buildFunction = createStartAgentDeviceSessionBuildFunction(ctx);
+    const global = createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.LINUX });
+    const step = buildFunction.createBuildStepFromFunctionCall(global, {
+      callInputs: {},
+      env: { DEVICE_RUN_SESSION_ID: 'session' },
+    });
+    await step.executeAsync();
+    expect(startAndroidEmulatorAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        logCapture: expect.objectContaining({ sources: ['emulator-output'] }),
+      })
+    );
+  });
+
+  it('passes an explicit empty source list and the workflow capture to Android boot', async () => {
+    const capture = new AndroidEmulatorLogRing({ sources: [] });
+    jest.mocked(getAndroidEmulatorLogCapture).mockReturnValue(capture);
+    const env = { DEVICE_RUN_SESSION_ID: 'session' };
+    await runStep(BuildRuntimePlatform.LINUX, { log_sources: [] }, undefined, ctx, false, env);
+    expect(getAndroidEmulatorLogCapture).toHaveBeenCalledWith(expect.anything(), env, []);
+    expect(startAndroidEmulatorAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ logCapture: capture })
+    );
+  });
+
+  it('rejects invalid Android log sources before boot or downloading', async () => {
+    await expect(
+      runStep(BuildRuntimePlatform.LINUX, {
+        log_sources: ['unknown'],
+        build_id: 'build-id',
+      })
+    ).rejects.toThrow();
+    expect(startAndroidEmulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects Android log sources on an iOS session before boot or downloading', async () => {
+    await expect(
+      runStep(BuildRuntimePlatform.DARWIN, {
+        log_sources: ['device-logcat'],
+        build_id: 'build-id',
+      })
+    ).rejects.toThrow('Input "log_sources" selects Android emulator logs');
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+    expect(IosSimulatorUtils.resolveUdidAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+  });
+
+  it('boots an iOS session with an explicit empty source list', async () => {
+    await runStep(BuildRuntimePlatform.DARWIN, { log_sources: [] });
+    expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalled();
+    expect(startAndroidEmulatorAsync).not.toHaveBeenCalled();
+  });
+
   it('boots the Android Emulator with the device inputs', async () => {
     await runStep(BuildRuntimePlatform.LINUX, {
       device_identifier: 'pixel_7',
@@ -470,6 +519,22 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     );
   });
 
+  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' }, undefined, ctx, false, {
+        DEVICE_RUN_SESSION_ID: 'session',
+      })
+    ).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('does not start work for an already cancelled step', async () => {
     const controller = new AbortController();
     controller.abort(new Error('cancelled'));
@@ -617,6 +682,7 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     expect(
       buildFunction.inputProviders?.map(provider => provider(globalCtx, 'Test step').id)
     ).toEqual([
+      'log_sources',
       'device_identifier',
       'system_image_package',
       'lcd_width',
@@ -821,6 +887,17 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledTimes(2);
   });
 
+  it('passes the resolved version to agent-device after a warm version mismatch', async () => {
+    jest
+      .mocked(runOnWarmIosSimulatorAsync)
+      .mockImplementation((_claim, run) => run(undefined, '999.1.0'));
+    await runStep(BuildRuntimePlatform.DARWIN, { package_version: 'latest' }, undefined, ctx, true);
+    expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ packageVersion: '999.1.0' })
+    );
+  });
+
   it('accepts only one application source', async () => {
     await expect(
       runStep(BuildRuntimePlatform.DARWIN, { install_app_path: '/tmp/App.app', build_id: 'id' })

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

@@ -9,6 +9,8 @@ import {
 } from '../../../utils/AndroidEmulatorUtils';
 import { retryAsync } from '../../../utils/retry';
 import { resolveAndroidEmulatorLocalEgressAsync } from '../../utils/androidLocalEgress';
+import { AndroidEmulatorLogRing } from '../../../utils/androidEmulatorLogCapture';
+import { getAndroidEmulatorLogCapture } from '../../utils/androidEmulatorLogs';
 import { createStartAndroidEmulatorBuildFunction } from '../startAndroidEmulator';
 
 jest.mock('@expo/turtle-spawn', () => ({
@@ -24,6 +26,8 @@ jest.mock('../../utils/androidLocalEgress', () => ({
   resolveAndroidEmulatorLocalEgressAsync: jest.fn(),
 }));
 
+jest.mock('../../utils/androidEmulatorLogs');
+
 jest.mock('../../../utils/AndroidEmulatorUtils', () => ({
   AndroidEmulatorUtils: {
     defaultSystemImagePackage: 'system-images;android-30;default;x86_64',
@@ -62,6 +66,11 @@ function createStartResult(serialId: string) {
 
 describe(createStartAndroidEmulatorBuildFunction, () => {
   beforeEach(() => {
+    jest
+      .mocked(getAndroidEmulatorLogCapture)
+      .mockImplementation(
+        jest.requireActual('../../utils/androidEmulatorLogs').getAndroidEmulatorLogCapture
+      );
     mockedMkdtemp.mockResolvedValue('/tmp/logcat-directory');
     mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);
     mockedAndroidUtils.getAvailableDevicesAsync.mockResolvedValue([]);
@@ -90,6 +99,30 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
     mockedMkdtemp.mockRestore();
   });
 
+  it('preserves an explicit empty source list and one capture through boot retries and clones', async () => {
+    mockedAndroidUtils.waitForReadyAsync.mockRejectedValueOnce(new Error('retry boot'));
+    const capture = new AndroidEmulatorLogRing({ sources: [] });
+    jest.mocked(getAndroidEmulatorLogCapture).mockReturnValue(capture);
+    await createStep(
+      { log_sources: [], count: 2 },
+      { DEVICE_RUN_SESSION_ID: 'session' }
+    ).executeAsync();
+    expect(getAndroidEmulatorLogCapture).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ DEVICE_RUN_SESSION_ID: 'session' }),
+      []
+    );
+    expect(mockedAndroidUtils.startAsync).toHaveBeenCalledTimes(4);
+    for (const [options] of mockedAndroidUtils.startAsync.mock.calls) {
+      expect(options.logCapture).toBe(capture);
+    }
+  });
+
+  it('rejects invalid sources before starting the emulator', async () => {
+    await expect(createStep({ log_sources: ['unknown'] }).executeAsync()).rejects.toThrow();
+    expect(mockedAndroidUtils.startAsync).not.toHaveBeenCalled();
+  });
+
   describe('local egress', () => {
     function createLocalEgress() {
       return {
@@ -111,6 +144,7 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
         deviceName: 'EasAndroidDevice01',
         env: expect.any(Object),
         logcatDirectory: '/tmp/logcat-directory',
+        logCapture: expect.objectContaining({ sources: ['emulator-output', 'device-logcat'] }),
       });
       expect(mockedAndroidUtils.waitForReadyAsync).toHaveBeenCalledWith({
         env: expect.any(Object),

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

@@ -1,7 +1,10 @@
 import { type WarmIosSession } from '../../utils/warmIosSession';
 import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
+import { vol } from 'memfs';
+import plist from 'plist';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import * as timersPromises from 'node:timers/promises';
 
@@ -9,6 +12,7 @@ import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
 import { AndroidEmulatorUtils } from '../../../utils/AndroidEmulatorUtils';
 import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import { PackageManager, resolveConfiguredPackageManager } from '../../../utils/packageManager';
 import * as processes from '../../../utils/processes';
 import { sleepAsync } from '../../../utils/retry';
 import { turtleFetch } from '../../../utils/turtleFetch';
@@ -98,6 +102,46 @@ jest.mock('../../utils/localEgressSession', () => ({
 }));
 
 const logger = { info: jest.fn(), warn: jest.fn() } as never;
+const preparedHome = path.join(os.homedir(), 'Library/Caches/expo-simulator-startup/appium');
+const preparedManifest = path.join(path.dirname(preparedHome), 'prepared.json');
+const preparedBin = path.join(preparedHome, 'node_modules', '.bin', 'appium');
+const preparedRunner = path.join(
+  preparedHome,
+  'preinstalled-wda',
+  'WebDriverAgentRunner-Runner.app'
+);
+
+const driverList = ['driver', 'list', '--installed', '--json'];
+
+/** Today's `driver list` output: the prepared home lists xcuitest, a new home lists nothing. */
+function driverListStdout(command: string): string {
+  return JSON.stringify(command === preparedBin ? { xcuitest: { installed: true } } : {});
+}
+
+/** Writes the Appium home that `simulator-launcher prefetch` prepares for reuse. */
+function writePreparedHome(): void {
+  fs.mkdirSync(path.dirname(preparedBin), { recursive: true });
+  fs.writeFileSync(preparedBin, '');
+  writeInstalledVersion('appium', '3.9.0');
+  writeInstalledVersion('appium-xcuitest-driver', '12.22.8');
+  fs.mkdirSync(preparedRunner, { recursive: true });
+  fs.writeFileSync(
+    path.join(preparedRunner, 'Info.plist'),
+    plist.build({ CFBundleExecutable: 'Runner' })
+  );
+  fs.writeFileSync(path.join(preparedRunner, 'Runner'), 'executable', { mode: 0o755 });
+  writePreparedManifest({ version: '3.9.0', xcuitest: '12.22.8', home: preparedHome });
+}
+
+function writePreparedManifest(appium: unknown): void {
+  fs.writeFileSync(preparedManifest, `${JSON.stringify({ tools: { appium } })}\n`);
+}
+
+function writeInstalledVersion(name: string, version: string): void {
+  const directory = path.join(preparedHome, 'node_modules', name);
+  fs.mkdirSync(directory, { recursive: true });
+  fs.writeFileSync(path.join(directory, 'package.json'), JSON.stringify({ name, version }));
+}
 
 describe(resolveAppium3VersionSpec, () => {
   it('uses the worker-supported Appium 3 version by default', () => {
@@ -172,9 +216,9 @@ describe(installAppiumAsync, () => {
   beforeEach(() => {
     jest.clearAllMocks();
     jest.mocked(watchDeviceRunSessionStartup).mockImplementation(createStartupWatchMock);
-    jest.mocked(spawn).mockImplementation((async (_command: string, args: string[]) => {
+    jest.mocked(spawn).mockImplementation((async (command: string, args: string[]) => {
       if (args.includes('--json')) {
-        return { stdout: JSON.stringify({}) };
+        return { stdout: driverListStdout(command) };
       }
       return { stdout: '' };
     }) as never);
@@ -208,6 +252,255 @@ describe(installAppiumAsync, () => {
     }
   });
 
+  it('uses the xcuitest home prefetched without installing', async () => {
+    writePreparedHome();
+    const info = jest.fn();
+    const result = await installAppiumAsync({
+      versionSpec: '^3',
+      driverName: 'xcuitest',
+      env: { EXISTING: 'value' },
+      logger: { info } as never,
+    });
+    expect(jest.mocked(spawn).mock.calls).toEqual([
+      [
+        preparedBin,
+        driverList,
+        { env: { EXISTING: 'value', APPIUM_HOME: preparedHome }, stdio: 'pipe' },
+      ],
+    ]);
+    expect(info).toHaveBeenCalledWith(
+      'Using the prefetched Appium home (appium 3.9.0, xcuitest 12.22.8).'
+    );
+    expect(result).toEqual({
+      appiumHome: preparedHome,
+      appiumBinPath: preparedBin,
+      appiumEnv: { EXISTING: 'value', APPIUM_HOME: preparedHome },
+      prepared: true,
+    });
+
+    const env = { EAS_OVERRIDE_PACKAGE_MANAGER: 'nope' };
+    const expected = (() => {
+      try {
+        resolveConfiguredPackageManager(env, PackageManager.NPM);
+      } catch (error) {
+        return error;
+      }
+    })();
+    const onError = jest.fn();
+    await expect(
+      installAppiumAsync({ versionSpec: '^3', driverName: 'xcuitest', env, logger, onError })
+    ).rejects.toEqual(expected);
+    expect(onError).toHaveBeenCalledWith(expected);
+    expect(jest.mocked(spawn).mock.calls.map(([, args]) => args)).toEqual([driverList, driverList]);
+  });
+
+  it('reuses WDA with binary bundle metadata', async () => {
+    writePreparedHome();
+    fs.writeFileSync(
+      path.join(preparedRunner, 'Info.plist'),
+      Buffer.from(
+        'YnBsaXN0MDDRAQJfEBJDRkJ1bmRsZUV4ZWN1dGFibGVWUnVubmVyCAsgAAAAAAAAAQEAAAAAAAAAAwAAAAAAAAAAAAAAAAAAACc=',
+        'base64'
+      )
+    );
+    const result = await installAppiumAsync({
+      versionSpec: '^3',
+      driverName: 'xcuitest',
+      env: {},
+      logger,
+    });
+    expect(result.prepared).toBe(true);
+  });
+
+  it.each([
+    ['a version spec it does not satisfy', { versionSpec: '3.5.0' }, () => {}],
+    ['the uiautomator2 driver', { driverName: 'uiautomator2' as const }, () => {}],
+    ['no prepared.json', {}, () => fs.rmSync(preparedManifest)],
+    ['an invalid prepared.json', {}, () => fs.writeFileSync(preparedManifest, 'not json')],
+    ['a prepared.json without xcuitest', {}, () => writePreparedManifest({ version: '3.9.0' })],
+    [
+      'an older per-tool manifest',
+      {},
+      () => {
+        fs.rmSync(preparedManifest);
+        fs.writeFileSync(
+          path.join(preparedHome, 'prepared.json'),
+          JSON.stringify({
+            appium: '3.9.0',
+            xcuitest: '12.22.8',
+            home: preparedHome,
+          })
+        );
+      },
+    ],
+    [
+      'a home prepared at another path',
+      {},
+      () =>
+        writePreparedManifest({
+          version: '3.9.0',
+          xcuitest: '12.22.8',
+          home: '/Users/other/appium',
+        }),
+    ],
+    ['another installed Appium', {}, () => writeInstalledVersion('appium', '2.19.0')],
+    [
+      'another installed xcuitest driver',
+      {},
+      () => writeInstalledVersion('appium-xcuitest-driver', '12.0.0'),
+    ],
+    [
+      'no xcuitest driver',
+      {},
+      () =>
+        fs.rmSync(path.join(preparedHome, 'node_modules', 'appium-xcuitest-driver'), {
+          recursive: true,
+        }),
+    ],
+    ['no runner', {}, () => fs.rmSync(preparedRunner, { recursive: true })],
+    ['no runner metadata', {}, () => fs.rmSync(path.join(preparedRunner, 'Info.plist'))],
+    [
+      'invalid runner metadata',
+      {},
+      () => fs.writeFileSync(path.join(preparedRunner, 'Info.plist'), 'invalid'),
+    ],
+    ['no runner executable', {}, () => fs.rmSync(path.join(preparedRunner, 'Runner'))],
+    [
+      'a non-executable runner binary',
+      {},
+      () => fs.chmodSync(path.join(preparedRunner, 'Runner'), 0o644),
+    ],
+    ['an empty runner binary', {}, () => fs.writeFileSync(path.join(preparedRunner, 'Runner'), '')],
+    [
+      'a directory as runner binary',
+      {},
+      () => {
+        fs.rmSync(path.join(preparedRunner, 'Runner'));
+        fs.mkdirSync(path.join(preparedRunner, 'Runner'));
+      },
+    ],
+    [
+      'an executable outside the bundle',
+      {},
+      () =>
+        fs.writeFileSync(
+          path.join(preparedRunner, 'Info.plist'),
+          plist.build({ CFBundleExecutable: '../outside' })
+        ),
+    ],
+    ['an unreadable runner', {}, () => fs.chmodSync(preparedRunner, 0o000)],
+    [
+      'a runner that is a file',
+      {},
+      () => {
+        fs.rmSync(preparedRunner, { recursive: true });
+        // Readable and executable, so only the directory check rejects it.
+        fs.writeFileSync(preparedRunner, '', { mode: 0o755 });
+      },
+    ],
+  ])('installs as before for %s', async (_name, options, breakHome) => {
+    writePreparedHome();
+    breakHome();
+    const before = vol.toJSON(preparedHome);
+    const versionSpec = 'versionSpec' in options ? options.versionSpec : '^3';
+    const resolveRequestedVersionAsync = jest.fn(async () => {
+      throw new Error('registry unavailable');
+    });
+    const result = await installAppiumAsync({
+      versionSpec,
+      resolveRequestedVersionAsync,
+      driverName: 'driverName' in options ? options.driverName : 'xcuitest',
+      env: {},
+      logger,
+    });
+    try {
+      expect(spawn).toHaveBeenNthCalledWith(
+        1,
+        'npm',
+        ['install', '--no-audit', `appium@${versionSpec}`],
+        expect.objectContaining({ cwd: result.appiumHome })
+      );
+      expect(path.basename(result.appiumHome)).toMatch(/^eas-appium-home-/);
+      expect(result.prepared).toBe(false);
+      expect(resolveRequestedVersionAsync).not.toHaveBeenCalled();
+      expect(vol.toJSON(preparedHome)).toEqual(before);
+    } finally {
+      await fs.promises.rm(result.appiumHome, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    ['a driver list without xcuitest', async () => ({ stdout: '{}' })],
+    ['a failed driver list', async () => Promise.reject(new Error('appium exited with 1.'))],
+  ])('installs as before after %s in the prepared home', async (_name, list) => {
+    writePreparedHome();
+    jest.mocked(spawn).mockImplementationOnce(list as never);
+    const before = vol.toJSON(preparedHome);
+    const result = await installAppiumAsync({
+      versionSpec: '^3',
+      driverName: 'xcuitest',
+      env: {},
+      logger,
+    });
+    try {
+      expect(jest.mocked(spawn).mock.calls.slice(0, 2)).toEqual([
+        [preparedBin, driverList, expect.objectContaining({ stdio: 'pipe' })],
+        [
+          'npm',
+          ['install', '--no-audit', 'appium@^3'],
+          expect.objectContaining({ cwd: result.appiumHome }),
+        ],
+      ]);
+      expect(result.prepared).toBe(false);
+      expect(vol.toJSON(preparedHome)).toEqual(before);
+    } finally {
+      await fs.promises.rm(result.appiumHome, { recursive: true, force: true });
+    }
+  });
+
+  it('kills the prepared-home driver list on a stop and installs nothing', async () => {
+    writePreparedHome();
+    const before = vol.toJSON(preparedHome);
+    const controller = new AbortController();
+    const failure = new Error('session stopped');
+    const child = { pid: 4242, kill: jest.fn() };
+    let finishList!: (error: Error) => void;
+    let listStarted!: () => void;
+    const started = new Promise<void>(resolve => {
+      listStarted = resolve;
+    });
+    jest.mocked(spawn).mockImplementationOnce(() => {
+      listStarted();
+      return Object.assign(
+        new Promise((_resolve, reject) => {
+          finishList = reject;
+        }),
+        { child }
+      ) as never;
+    });
+    const killGroup = jest.spyOn(processes, 'killProcessGroup').mockImplementation(() => {});
+    const running = installAppiumAsync({
+      versionSpec: '^3',
+      driverName: 'xcuitest',
+      env: {},
+      logger,
+      signal: controller.signal,
+    });
+    running.catch(() => {});
+    try {
+      await started;
+      controller.abort(failure);
+      expect(killGroup).toHaveBeenCalledWith(child, 'SIGKILL');
+      finishList(new Error('killed'));
+      await expect(running).rejects.toBe(failure);
+      expect(spawn).toHaveBeenCalledTimes(1);
+      expect(vol.toJSON(preparedHome)).toEqual(before);
+    } finally {
+      finishList?.(new Error('test cleanup'));
+      killGroup.mockRestore();
+    }
+  });
+
   it('installs Appium with bun add when EAS_OVERRIDE_PACKAGE_MANAGER is bun', async () => {
     const result = await installAppiumAsync({
       versionSpec: '3.5.0',
@@ -302,6 +595,115 @@ describe('createStartAppiumRemoteSessionBuildFunction', () => {
     });
   });
 
+  it.each(
+    [BuildRuntimePlatform.DARWIN, BuildRuntimePlatform.LINUX].flatMap(platform =>
+      ['^3', '3.x'].map(version => [platform, version] as const)
+    )
+  )(
+    'starts cold Appium on %s with cached installer range %s and no registry lookup',
+    async (runtimePlatform, packageVersion) => {
+      // Android must ignore prepared XCUITest files too.
+      if (runtimePlatform === BuildRuntimePlatform.LINUX) {
+        writePreparedHome();
+      }
+      jest.mocked(spawn).mockImplementation((async (_command: string, args: string[]) => {
+        if (args[0] === 'view') {
+          throw new Error('registry unavailable');
+        }
+        return { stdout: '{}' };
+      }) as never);
+      jest
+        .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+        .mockResolvedValue([{ udid: 'simulator' }] as never);
+      jest
+        .mocked(AndroidEmulatorUtils.getAttachedDevicesAsync)
+        .mockResolvedValue([{ serialId: 'emulator-5554', state: 'device' }] as never);
+      const launched = new Error('launch captured');
+      jest.mocked(spawnDetached).mockImplementation(() => {
+        throw launched;
+      });
+      const buildFunction = createStartAppiumRemoteSessionBuildFunction({} as CustomBuildContext);
+      await expect(
+        buildFunction.fn!(
+          { logger, global: { runtimePlatform } } as unknown as BuildStepContext,
+          {
+            inputs: {
+              package_version: { value: packageVersion },
+              max_idle_time_minutes: { value: undefined },
+            },
+            outputs: {},
+            env: {
+              DEVICE_RUN_SESSION_ID: 'session',
+              EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN: 'example.test',
+              NGROK_AUTHTOKEN: 'token',
+              EAS_OVERRIDE_PACKAGE_MANAGER: 'bun',
+            },
+          } as never
+        )
+      ).rejects.toBe(launched);
+      expect(jest.mocked(spawn).mock.calls.some(([, args]) => args[0] === 'view')).toBe(false);
+      expect(spawn).toHaveBeenCalledWith(
+        'bun',
+        ['add', `appium@${packageVersion}`],
+        expect.anything()
+      );
+    }
+  );
+
+  it.each(
+    ['latest', '^3', '3.x'].flatMap(requested =>
+      ['3.9.0', '3.10.0'].map(latest => [requested, latest])
+    )
+  )('checks %s before using the prepared Appium version (%s)', async (requested, latest) => {
+    writePreparedHome();
+    const before = vol.toJSON(preparedHome);
+    jest.mocked(spawn).mockImplementation((async (command: string, args: string[]) => ({
+      stdout:
+        args[0] === 'view'
+          ? JSON.stringify(latest)
+          : args.includes('--json')
+            ? driverListStdout(command)
+            : '',
+    })) as never);
+    jest
+      .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+      .mockResolvedValue([{ udid: 'simulator' }] as never);
+    const launched = new Error('launch captured');
+    jest.mocked(spawnDetached).mockImplementation(() => {
+      throw launched;
+    });
+    const buildFunction = createStartAppiumRemoteSessionBuildFunction({} as CustomBuildContext);
+    await expect(
+      buildFunction.fn!(
+        {
+          logger,
+          global: { runtimePlatform: BuildRuntimePlatform.DARWIN },
+        } as unknown as BuildStepContext,
+        {
+          inputs: {
+            package_version: { value: requested },
+            max_idle_time_minutes: { value: undefined },
+          },
+          outputs: {},
+          env: {
+            DEVICE_RUN_SESSION_ID: 'session',
+            EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN: 'example.test',
+            NGROK_AUTHTOKEN: 'token',
+          },
+        } as never
+      )
+    ).rejects.toBe(launched);
+    const installs = jest.mocked(spawn).mock.calls.filter(([, args]) => args[0] === 'install');
+    if (latest === '3.9.0') {
+      expect(installs).toHaveLength(0);
+      expect(jest.mocked(spawnDetached).mock.calls[0][0].env.APPIUM_HOME).toBe(preparedHome);
+    } else {
+      expect(installs).toHaveLength(1);
+      expect(installs[0][1]).toContain('[email protected]');
+    }
+    expect(vol.toJSON(preparedHome)).toEqual(before);
+  });
+
   it('claims the warm Simulator for Appium without its package version', async () => {
     jest.mocked(runOnWarmIosSimulatorAsync).mockResolvedValue(undefined);
     const buildFunction = createStartAppiumRemoteSessionBuildFunction({} as CustomBuildContext, {
@@ -369,8 +771,8 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
       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') ? '{}' : '',
+    jest.mocked(spawn).mockImplementation((async (command: string, args: string[]) => ({
+      stdout: args.includes('--json') ? driverListStdout(command) : '',
     })) as never);
     jest
       .mocked(AndroidEmulatorUtils.getAttachedDevicesAsync)
@@ -625,6 +1027,73 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
     return stopWarm;
   }
 
+  it.each(['cancelled lookup', 'AbortError lookup', 'resolved lookup'])(
+    'recovers from failed warm adoption with a %s',
+    async stage => {
+      writePreparedHome();
+      const stopWarm = mockWarmSession();
+      stopAppium.mockResolvedValue(undefined);
+      const adoptionError = new WarmSessionAdoptionError();
+      let failHost!: (error: Error) => void;
+      jest.mocked(startDeviceSessionHostAsync).mockReturnValueOnce(
+        new Promise((_resolve, reject) => {
+          failHost = reject;
+        })
+      );
+      let lookups = 0;
+      jest.mocked(spawn).mockImplementation((async (command, args, options) => {
+        if (args[0] !== 'view') {
+          return { stdout: args.includes('--json') ? driverListStdout(command) : '' };
+        }
+        lookups++;
+        if (lookups === 1 && stage !== 'resolved lookup') {
+          return await new Promise((_resolve, reject) => {
+            options!.signal!.addEventListener(
+              'abort',
+              () => {
+                reject(
+                  stage === 'AbortError lookup'
+                    ? new DOMException('Aborted', 'AbortError')
+                    : options!.signal!.reason
+                );
+              },
+              { once: true }
+            );
+            failHost(adoptionError);
+          });
+        }
+        return { stdout: JSON.stringify('3.9.0') };
+      }) as typeof spawn);
+      if (stage === 'resolved lookup') {
+        const process = jest.mocked(spawnDetached).getMockImplementation()!;
+        jest.mocked(spawnDetached).mockImplementationOnce(options => {
+          failHost(adoptionError);
+          return process(options);
+        });
+      }
+
+      await expect(
+        runSessionAsync(
+          logger,
+          undefined,
+          BuildRuntimePlatform.DARWIN,
+          {
+            boot_simulator: { value: true },
+            device_identifier: { value: 'iPhone 17' },
+            package_version: { value: '^3' },
+          },
+          true
+        )
+      ).resolves.toBeUndefined();
+
+      expect(lookups).toBe(stage === 'resolved lookup' ? 1 : 2);
+      expect(stopWarm).toHaveBeenCalledTimes(1);
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(2);
+      expect(spawnDetached).toHaveBeenCalledTimes(stage === 'resolved lookup' ? 2 : 1);
+      expect(fs.existsSync(preparedRunner)).toBe(true);
+    }
+  );
+
   it.each(['event collection', 'Appium process'])(
     'waits for warm %s teardown before finishing the session host',
     async stage => {
@@ -1102,6 +1571,31 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
     );
   });
 
+  it('a Darwin session uses the prepared Appium home and keeps it', async () => {
+    stopAppium.mockResolvedValue(undefined);
+    writePreparedHome();
+    jest.mocked(IosSimulatorUtils.getAvailableDevicesAsync).mockResolvedValue([
+      {
+        udid: 'chosen-ios-udid',
+        runtime: 'com.apple.CoreSimulator.SimRuntime.iOS-26-4',
+      } as never,
+    ]);
+    await runSessionAsync(
+      { info: jest.fn(), warn: jest.fn() },
+      undefined,
+      BuildRuntimePlatform.DARWIN
+    );
+    expect(jest.mocked(spawnDetached).mock.calls[0][0].env.APPIUM_HOME).toBe(preparedHome);
+    expect(preparePreinstalledWdaAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ appiumHome: preparedHome, prepared: true })
+    );
+    expect(jest.mocked(spawn).mock.calls.map(([command, args]) => [command, args])).toEqual([
+      [preparedBin, driverList],
+    ]);
+    expect(stopAppium).toHaveBeenCalledTimes(1);
+    expect(fs.existsSync(preparedManifest)).toBe(true);
+  });
+
   it('starts serve-sim on the selected iOS device while Appium installation is pending', async () => {
     stopAppium.mockResolvedValue(undefined);
     jest.mocked(selectXcodeDeveloperDirectoryAsync).mockClear();

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

@@ -322,6 +322,29 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
   });
 
+  it('uses the resolved Argent version after a warm mismatch', async () => {
+    jest
+      .mocked(runOnWarmIosSimulatorAsync)
+      .mockImplementation((_claim, run) => run(undefined, '999.1.0'));
+    await createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext, { warm: true }).fn!(
+      {
+        logger: { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() },
+        global: { runtimePlatform: BuildRuntimePlatform.DARWIN },
+      } as never,
+      {
+        inputs: {
+          package_version: { value: 'latest' },
+          max_idle_time_minutes: { value: undefined },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    expect(spawnDetached).toHaveBeenCalledWith(
+      expect.objectContaining({ args: expect.arrayContaining(['@swmansion/[email protected]']) })
+    );
+  });
+
   it('keeps watching startup when warm adoption retries cold', async () => {
     const ctx = {} as CustomBuildContext;
     const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };

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

@@ -1,14 +1,30 @@
-import { EnvironmentSecretType, SystemError, UserError } from '@expo/eas-build-job';
+import {
+  ArchiveSourceType,
+  EnvironmentSecretType,
+  SystemError,
+  UserError,
+} from '@expo/eas-build-job';
 import fetch from 'node-fetch';
 
+import { stripRepositoryCredentialsAsync } from '../../../common/git';
 import * as sandboxDaemon from '../../utils/sandboxDaemon';
 import { SandboxWorkerApi } from '../../utils/sandboxWorkerApi';
 import { createStartSandboxBuildFunction } from '../startSandbox';
 
 const { AbortError, Response } = jest.requireActual('node-fetch') as typeof import('node-fetch');
 
+jest.mock('../../../common/git');
+
+const checkedOutStepCtx = { logger: {}, global: { wasCheckedOut: () => true } } as any;
+const notCheckedOutStepCtx = { logger: {}, global: { wasCheckedOut: () => false } } as any;
+
+const URL_JOB = {
+  projectArchive: { type: ArchiveSourceType.URL, url: 'https://example.com/project.tar.gz' },
+};
+
 const context = {
   job: {
+    ...URL_JOB,
     secrets: {
       environmentSecrets: [
         {
@@ -183,67 +199,102 @@ describe('sandbox build functions', () => {
     expect(stopAsync).toHaveBeenCalledTimes(1);
   });
 
-  it('falls back to the legacy token and keeps the Expo token for commands without a worker token', async () => {
+  it('strips the repository credentials before starting the daemon for git sources', async () => {
     const startupError = new Error('stop after checking options');
     const start = jest
       .spyOn(sandboxDaemon, 'startSandboxDaemonAsync')
       .mockRejectedValue(startupError);
-    const fn = createStartSandboxBuildFunction({ ...context, job: {} } as any);
-
-    await expect(
-      fn.fn!({ logger: {} } as any, {
-        inputs,
-        outputs: {},
-        env: {
-          PREPARED_BY_EARLIER_STEP: 'value',
-          EXPO_TOKEN: 'expo-token',
-          __EAS_SANDBOX_MCP_TOKEN: 'legacy-token',
+    const fn = createStartSandboxBuildFunction({
+      ...context,
+      job: {
+        ...context.job,
+        projectArchive: {
+          type: ArchiveSourceType.GIT,
+          gitRef: 'refs/heads/main',
+          gitCommitHash: '0123456789abcdef0123456789abcdef01234567',
         },
-      })
-    ).rejects.toBe(startupError);
-    expect(start.mock.calls[0][0]).toMatchObject({ credential: 'legacy-token' });
-    expect(start.mock.calls[0][0].env).toEqual({
-      PREPARED_BY_EARLIER_STEP: 'value',
-      EXPO_TOKEN: 'expo-token',
+      },
+      projectTargetDirectory: '/workingdir/build',
+    } as any);
+
+    await expect(fn.fn!(checkedOutStepCtx, { inputs, outputs: {}, env: {} })).rejects.toBe(
+      startupError
+    );
+    expect(stripRepositoryCredentialsAsync).toHaveBeenCalledWith({
+      repositoryDirectory: '/workingdir/build',
+    });
+    expect(jest.mocked(stripRepositoryCredentialsAsync).mock.invocationCallOrder[0]).toBeLessThan(
+      start.mock.invocationCallOrder[0]
+    );
+  });
+
+  it('strips the repository credentials from the source directory before eas/checkout', async () => {
+    const startupError = new Error('stop after checking options');
+    jest.spyOn(sandboxDaemon, 'startSandboxDaemonAsync').mockRejectedValue(startupError);
+    const fn = createStartSandboxBuildFunction({
+      ...context,
+      job: {
+        ...context.job,
+        projectArchive: {
+          type: ArchiveSourceType.GIT,
+          gitRef: null,
+          gitCommitHash: '0123456789abcdef0123456789abcdef01234567',
+        },
+      },
+      projectSourceDirectory: '/workingdir/temporary-custom-build',
+      projectTargetDirectory: '/workingdir/build',
+    } as any);
+
+    await expect(fn.fn!(notCheckedOutStepCtx, { inputs, outputs: {}, env: {} })).rejects.toBe(
+      startupError
+    );
+    expect(stripRepositoryCredentialsAsync).toHaveBeenCalledWith({
+      repositoryDirectory: '/workingdir/temporary-custom-build',
     });
   });
 
-  it('marks the sandbox ready over GraphQL without a worker token', async () => {
-    const stopAsync = jest.fn(async () => {});
-    jest
-      .spyOn(sandboxDaemon, 'startSandboxDaemonAsync')
-      .mockResolvedValue({ ready: Promise.resolve(), stopAsync });
-    const mutation = jest.fn(() => ({
-      toPromise: async () => ({ data: { sandbox: { markSandboxReady: { id: 'sandbox-id' } } } }),
-    }));
-    const logger = { info: jest.fn(), child: jest.fn() };
-    logger.child.mockReturnValue(logger);
+  it('does not start the daemon when stripping the repository credentials fails', async () => {
+    const stripError = new SystemError('Failed to strip credentials from the origin remote URL.');
+    jest.mocked(stripRepositoryCredentialsAsync).mockRejectedValueOnce(stripError);
+    const start = jest.spyOn(sandboxDaemon, 'startSandboxDaemonAsync');
     const fn = createStartSandboxBuildFunction({
       ...context,
-      job: {},
-      graphqlClient: { mutation },
+      job: {
+        ...context.job,
+        projectArchive: {
+          type: ArchiveSourceType.GIT,
+          gitRef: null,
+          gitCommitHash: '0123456789abcdef0123456789abcdef01234567',
+        },
+      },
+      projectTargetDirectory: '/workingdir/build',
     } as any);
 
-    await fn.fn!({ logger } as any, {
-      inputs: { ...inputs, max_duration_seconds: { value: 0.0001 } },
-      outputs: {},
-      env: { __EAS_SANDBOX_MCP_TOKEN: 'legacy-token' },
-    });
-
-    expect(mutation).toHaveBeenCalledWith(
-      expect.anything(),
-      { sandboxId: 'sandbox-id' },
-      undefined
+    await expect(fn.fn!(checkedOutStepCtx, { inputs, outputs: {}, env: {} })).rejects.toBe(
+      stripError
     );
-    expect(fetch).not.toHaveBeenCalled();
-    expect(stopAsync).toHaveBeenCalledTimes(1);
+    expect(start).not.toHaveBeenCalled();
+  });
+
+  it('leaves the remote alone for non-git sources', async () => {
+    const startupError = new Error('stop after checking options');
+    jest.spyOn(sandboxDaemon, 'startSandboxDaemonAsync').mockRejectedValue(startupError);
+    const fn = createStartSandboxBuildFunction({
+      ...context,
+      projectTargetDirectory: '/workingdir/build',
+    } as any);
+
+    await expect(fn.fn!({ logger: {} } as any, { inputs, outputs: {}, env: {} })).rejects.toBe(
+      startupError
+    );
+    expect(stripRepositoryCredentialsAsync).not.toHaveBeenCalled();
   });
 
   it.each([
     {
-      missing: 'a sandbox worker token or a legacy token',
+      missing: 'the sandbox worker token',
       overrides: { job: {} },
-      message: 'This sandbox job has neither EAS_SANDBOX_WORKER_TOKEN nor __EAS_SANDBOX_MCP_TOKEN.',
+      message: 'This sandbox job has no EAS_SANDBOX_WORKER_TOKEN secret.',
     },
     {
       missing: 'the MCP server URL',

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

@@ -224,6 +224,20 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     );
   });
 
+  it('passes the resolved version to cold setup after a warm version mismatch', async () => {
+    jest
+      .mocked(runOnWarmIosSimulatorAsync)
+      .mockImplementation((_claim, run) => run(undefined, '0.14.0'));
+    await createStartWebPreviewRemoteSessionBuildFunction(ctx, { warm: true }).fn!(
+      { logger, global: { runtimePlatform: BuildRuntimePlatform.DARWIN } } as never,
+      { inputs: { package_version: { value: 'latest' } }, outputs: {}, env } as never
+    );
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ packageVersion: '0.14.0' })
+    );
+  });
+
   it('uses preview activity to reset the configured idle timeout', async () => {
     await runAsync(BuildRuntimePlatform.DARWIN, { max_idle_time_minutes: { value: 5 } });
     const { idleTimeout } = jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.calls[0][0];

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

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

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

@@ -1,4 +1,4 @@
-import { SystemError } from '@expo/eas-build-job';
+import { SystemError, formatBytes } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import {
@@ -15,7 +15,6 @@ import stream from 'stream';
 import { promisify } from 'util';
 import { z } from 'zod';
 
-import { formatBytes } from '../../utils/artifacts';
 import { decompressTarAsync, isFileTarGzAsync } from '../../utils/files';
 import { retryOnDNSFailure } from '../../utils/retryOnDNSFailure';
 

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

@@ -1,4 +1,4 @@
-import { SystemError, UserError } from '@expo/eas-build-job';
+import { SystemError, UserError, formatBytes } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import {
@@ -23,7 +23,6 @@ import bplistParser from 'bplist-parser';
 import plist from 'plist';
 
 import { CustomBuildContext } from '../../customBuildContext';
-import { formatBytes } from '../../utils/artifacts';
 import { decompressTarAsync, isFileTarGzAsync } from '../../utils/files';
 import { graphqlAbortContext } from '../../utils/graphqlAbort';
 import {

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

@@ -211,7 +211,9 @@ const MaestroRunnerRecordedFlowSchema = z.object({
   name: z.string().min(1),
   sourceFile: z.string().min(1),
   status: z.enum(['passed', 'failed']),
+  tags: z.array(z.string()).optional(),
 });
+type MaestroRunnerRecordedFlow = z.infer<typeof MaestroRunnerRecordedFlowSchema>;
 const MaestroRunnerReportSchema = z.object({
   flows: z
     .array(
@@ -379,6 +381,111 @@ export async function parseFailedFlowsFromFileAttrs(args: {
   return paths;
 }
 
+const MAESTRO_RUNNER_ATTEMPT_DIRECTORY_PATTERN = /-maestro-runner-attempt-(\d+)$/;
+
+export function maestroRunnerAttemptDirectoryName(args: {
+  platform: string;
+  attempt: number;
+}): string {
+  return `${args.platform}-maestro-runner-attempt-${args.attempt}`;
+}
+
+async function listMaestroRunnerAttemptDirectories(
+  testsDirectory: string
+): Promise<{ attempt: number; reportDirectory: string }[]> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(testsDirectory);
+  } catch {
+    return [];
+  }
+  return entries.flatMap(entry => {
+    const match = entry.match(MAESTRO_RUNNER_ATTEMPT_DIRECTORY_PATTERN);
+    return match
+      ? [{ attempt: parseInt(match[1], 10), reportDirectory: path.join(testsDirectory, entry) }]
+      : [];
+  });
+}
+
+export async function hasMaestroRunnerAttemptDirectories(testsDirectory: string): Promise<boolean> {
+  return (await listMaestroRunnerAttemptDirectories(testsDirectory)).length > 0;
+}
+
+export async function parseMaestroRunnerResults(args: {
+  junitDirectory: string;
+  testsDirectory: string;
+  workingDirectory: string;
+}): Promise<MaestroFlowResult[]> {
+  const results = await parseMaestroResultsFromFileAttrs(args.junitDirectory);
+
+  const attempts = await listMaestroRunnerAttemptDirectories(args.testsDirectory);
+  const flows = await Promise.all(
+    attempts.map(({ reportDirectory }) =>
+      parseMaestroRunnerFlowsWithPaths({
+        reportDirectory,
+        workingDirectory: args.workingDirectory,
+      })
+    )
+  );
+  const flowsByAttempt = new Map(attempts.map(({ attempt }, index) => [attempt, flows[index]]));
+  const realWorkingDirectory = await resolveRealPath(args.workingDirectory);
+
+  return results.map(result => {
+    const tags = findMaestroRunnerFlowTags({
+      flows: flowsByAttempt.get(result.retryCount) ?? [],
+      junitFlowPath: result.path,
+      workingDirectory: args.workingDirectory,
+      realWorkingDirectory,
+    });
+    return tags ? { ...result, tags } : result;
+  });
+}
+
+type MaestroRunnerFlowWithPaths = MaestroRunnerRecordedFlow & {
+  resolvedPath: string;
+  realPath: string;
+};
+
+// maestro-runner >= 1.1.18 resolves symlinks in the JUnit path, but not in report.json.
+async function parseMaestroRunnerFlowsWithPaths(args: {
+  reportDirectory: string;
+  workingDirectory: string;
+}): Promise<MaestroRunnerFlowWithPaths[]> {
+  const report = await parseMaestroRunnerReport(args.reportDirectory);
+  return await Promise.all(
+    (report?.flows ?? []).map(async flow => {
+      const resolvedPath = path.resolve(args.workingDirectory, flow.sourceFile);
+      return { ...flow, resolvedPath, realPath: await resolveRealPath(resolvedPath) };
+    })
+  );
+}
+
+async function resolveRealPath(filePath: string): Promise<string> {
+  const realPathResult = await asyncResult(fs.realpath(filePath));
+  return realPathResult.ok ? realPathResult.value : filePath;
+}
+
+function findMaestroRunnerFlowTags(args: {
+  flows: MaestroRunnerFlowWithPaths[];
+  junitFlowPath: string;
+  workingDirectory: string;
+  realWorkingDirectory: string;
+}): string[] | undefined {
+  const junitPath = path.resolve(args.workingDirectory, args.junitFlowPath);
+  const junitRealPath = path.resolve(args.realWorkingDirectory, args.junitFlowPath);
+  const samePath = args.flows.find(
+    flow => flow.resolvedPath === junitPath || flow.realPath === junitRealPath
+  );
+  if (samePath) {
+    return samePath.tags;
+  }
+  // maestro-runner <= 1.1.17 writes only the file name to JUnit.
+  const sameFileName = args.flows.filter(
+    flow => path.basename(flow.sourceFile) === args.junitFlowPath
+  );
+  return sameFileName.length === 1 ? sameFileName[0].tags : undefined;
+}
+
 export async function parseMaestroResults(
   junitDirectory: string,
   nameToPath: Map<string, string> | null

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

@@ -18,6 +18,7 @@ import { buildFlowNameToPathMap } from './maestroFlowDiscovery';
 import {
   copyLatestAttemptXml,
   junitFileHasFileAttrs,
+  maestroRunnerAttemptDirectoryName,
   mergeJUnitReports,
   parseFailedFlowNamesFromJUnitFile,
   parseFailedFlowsFromFileAttrs,
@@ -353,7 +354,7 @@ export function createMaestroTestsBuildFunction(ctx: CustomBuildContext): BuildF
         // maestro-runner writes all report formats and screenshot metadata here.
         const runnerOutputDirectory = path.join(
           testsDirectory,
-          `${platform}-maestro-runner-attempt-${attempt}`
+          maestroRunnerAttemptDirectoryName({ platform, attempt })
         );
         const outputPath = mayHaveJUnitReports
           ? path.join(junitReportDirectory, `${platform}-maestro-junit-attempt-${attempt}.xml`)

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

@@ -5,10 +5,12 @@ import { z } from 'zod';
 import { buildFlowNameToPathMap } from './maestroFlowDiscovery';
 import {
   MaestroFlowResult,
+  hasMaestroRunnerAttemptDirectories,
   isFileAttrRun,
   parseJUnitTestCases,
   parseMaestroResults,
   parseMaestroResultsFromFileAttrs,
+  parseMaestroRunnerResults,
 } from './maestroResultParser';
 import { CustomBuildContext } from '../../customBuildContext';
 
@@ -73,8 +75,15 @@ export function createReportMaestroTestResultsFunction(ctx: CustomBuildContext):
         // map testcase names back to paths.
         const usedFileAttrs = isFileAttrRun(await parseJUnitTestCases(junitDirectory));
 
+        const testsDirectory = (inputs.tests_directory.value as string | undefined) ?? '';
         let flowResults: MaestroFlowResult[];
-        if (usedFileAttrs) {
+        if (usedFileAttrs && (await hasMaestroRunnerAttemptDirectories(testsDirectory))) {
+          flowResults = await parseMaestroRunnerResults({
+            junitDirectory,
+            testsDirectory,
+            workingDirectory: stepsCtx.workingDirectory,
+          });
+        } else if (usedFileAttrs) {
           flowResults = await parseMaestroResultsFromFileAttrs(junitDirectory);
         } else {
           // Legacy (Maestro < 2.6.0) — DELETE this arm once the fleet is on >= 2.6.0.

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

@@ -1,4 +1,4 @@
-import { Platform } from '@expo/eas-build-job';
+import { Platform, formatBytes } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import {
@@ -17,7 +17,6 @@ import * as tar from 'tar';
 import { promisify } from 'util';
 import z from 'zod';
 
-import { formatBytes } from '../../utils/artifacts';
 import { PUBLIC_CACHE_KEY_PREFIX_BY_PLATFORM } from '../../utils/cacheKey';
 import { retryOnDNSFailure } from '../../utils/retryOnDNSFailure';
 import { TurtleFetchError, turtleFetch } from '../../utils/turtleFetch';

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

@@ -1,4 +1,4 @@
-import { Platform } from '@expo/eas-build-job';
+import { Platform, formatBytes } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import {
@@ -14,7 +14,6 @@ import os from 'os';
 import path from 'path';
 
 import { compressCacheAsync, uploadCacheAsync } from './saveCache';
-import { formatBytes } from '../../utils/artifacts';
 import {
   CcacheBuildTarget,
   generateDefaultBuildCacheKeyAsync,

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

@@ -1,4 +1,4 @@
-import { Platform } from '@expo/eas-build-job';
+import { Platform, formatBytes } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import { BuildFunction, BuildStepInput, BuildStepInputValueTypeName } from '@expo/steps';
@@ -12,7 +12,6 @@ import * as tar from 'tar';
 import z from 'zod';
 
 import { uploadWithSignedUrl } from '../../storage/uploadWithSignedUrl';
-import { formatBytes } from '../../utils/artifacts';
 import { retryOnDNSFailure } from '../../utils/retryOnDNSFailure';
 import { getCacheVersion } from '../utils/cache';
 

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

@@ -16,6 +16,8 @@ import {
   AndroidVirtualDeviceName,
 } from '../../utils/AndroidEmulatorUtils';
 import { watchDeviceRunSessionStartup } from '../utils/deviceRunSessionStartup';
+import { getAndroidEmulatorLogCapture } from '../utils/androidEmulatorLogs';
+import { parseLogSourcesInput } from '../utils/logSourcesInput';
 import { getDeviceRunSessionWorkerApi } from '../utils/deviceRunSessionWorkerApi';
 import { readIosApplicationIdentifierAsync } from '../utils/iosAppArtifact';
 import { resolveIosSessionStartupAsync } from '../utils/iosSimulatorSession';
@@ -71,6 +73,12 @@ export function createStartAgentDeviceSessionBuildFunction(
     name: 'Start agent-device session',
     __metricsId: warm ? 'eas/start_warm_agent_device_session' : 'eas/start_agent_device_session',
     inputProviders: [
+      // No default: an omitted input must stay distinguishable from an explicit selection.
+      BuildStepInput.createProvider({
+        id: 'log_sources',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+      }),
       // Device. On iOS a Simulator name or UDID, on Android an AVD hardware profile.
       BuildStepInput.createProvider({
         id: 'device_identifier',
@@ -188,6 +196,10 @@ export function createStartAgentDeviceSessionBuildFunction(
       } else {
         validateAndroidLaunchOptions({ launchArgs, openUrl });
       }
+      const logSources = parseLogSourcesInput(inputs.log_sources.value, {
+        runtimePlatform,
+        fallback: isIos ? [] : ['emulator-output'],
+      });
       const deviceIdentifier = inputs.device_identifier.value as string | undefined;
       const capture = parseNetworkCaptureInputs(
         {
@@ -205,7 +217,10 @@ export function createStartAgentDeviceSessionBuildFunction(
         logger,
         startup: { signal: startupSignal, abort: reason => startup.abort(reason) },
       });
-      const startSessionAsync = async (warmSession?: WarmIosSession): Promise<void> => {
+      const startSessionAsync = async (
+        warmSession?: WarmIosSession,
+        resolvedPackageVersion = inputs.package_version.value as string | undefined
+      ): Promise<void> => {
         const tasks = createStartupTasks(logger, startupSignal);
         let booted: Promise<void> | undefined;
         let sessionOwnsTeardown = false;
@@ -253,6 +268,7 @@ export function createStartAgentDeviceSessionBuildFunction(
                   lcdHeight: inputs.lcd_height.value as number | undefined,
                   lcdDensity: inputs.lcd_density.value as number | undefined,
                   logcatDirectory,
+                  logCapture: getAndroidEmulatorLogCapture(global, env, logSources),
                   env,
                   logger: taskLogger,
                 });
@@ -338,7 +354,7 @@ export function createStartAgentDeviceSessionBuildFunction(
             signal,
             runtimePlatform,
             sessionEnv,
-            packageVersion: inputs.package_version.value as string | undefined,
+            packageVersion: resolvedPackageVersion,
             // A missing or non-positive value disables the idle timeout (opt-in feature).
             maxIdleTimeMinutes: inputs.max_idle_time_minutes.value as number | undefined,
             maxDurationSeconds: inputs.max_duration_seconds.value as number | undefined,

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

@@ -20,8 +20,12 @@ import {
   AndroidEmulatorUtils,
   AndroidVirtualDeviceName,
 } from '../../utils/AndroidEmulatorUtils';
+import { type AndroidEmulatorLogCapture } from '../../utils/androidEmulatorLogCapture';
 import { retryAsync } from '../../utils/retry';
 import { resolveAndroidEmulatorLocalEgressAsync } from '../utils/androidLocalEgress';
+import { ALL_ANDROID_EMULATOR_LOG_SOURCES } from '../../utils/androidEmulatorLogSources';
+import { getAndroidEmulatorLogCapture } from '../utils/androidEmulatorLogs';
+import { parseLogSourcesInput } from '../utils/logSourcesInput';
 
 const ANDROID_STARTUP_ATTEMPT_TIMEOUT_MS = [60_000, 120_000, 180_000];
 const ANDROID_STARTUP_RETRIES_COUNT = ANDROID_STARTUP_ATTEMPT_TIMEOUT_MS.length - 1;
@@ -33,6 +37,12 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
     name: 'Start Android Emulator',
     __metricsId: 'eas/start_android_emulator',
     inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'log_sources',
+        required: false,
+        defaultValue: [...ALL_ANDROID_EMULATOR_LOG_SOURCES],
+        allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+      }),
       BuildStepInput.createProvider({
         id: 'device_name',
         required: false,
@@ -78,10 +88,15 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
         required: true,
       }),
     ],
-    fn: async ({ logger }, { inputs, outputs, env }) => {
+    fn: async ({ logger, global }, { inputs, outputs, env }) => {
+      const logSources = parseLogSourcesInput(inputs.log_sources.value, {
+        runtimePlatform: global.runtimePlatform,
+        fallback: ALL_ANDROID_EMULATOR_LOG_SOURCES,
+      });
       const logcatDirectory = await fs.promises.mkdtemp(
         path.join(os.tmpdir(), 'eas-android-emulator-logcat-')
       );
+      const logCapture = getAndroidEmulatorLogCapture(global, env, logSources);
       outputs.logcat_directory.set(logcatDirectory);
 
       const deviceName = `${inputs.device_name.value}` as AndroidVirtualDeviceName;
@@ -95,6 +110,7 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
           lcdHeight: inputs.lcd_height.value as number | undefined,
           lcdDensity: inputs.lcd_density.value as number | undefined,
           logcatDirectory,
+          logCapture,
           env,
           logger,
         });
@@ -133,6 +149,7 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
                   deviceName: cloneIdentifier,
                   env,
                   logcatDirectory,
+                  logCapture,
                 });
                 cloneSerialId = startResult.serialId;
 
@@ -202,6 +219,7 @@ export async function startAndroidEmulatorAsync({
   lcdHeight,
   lcdDensity,
   logcatDirectory,
+  logCapture,
   env,
   logger,
 }: {
@@ -212,6 +230,7 @@ export async function startAndroidEmulatorAsync({
   lcdHeight?: number;
   lcdDensity?: number;
   logcatDirectory: string;
+  logCapture: AndroidEmulatorLogCapture;
   env: BuildStepEnv;
   logger: bunyan;
 }): Promise<{
@@ -293,6 +312,7 @@ export async function startAndroidEmulatorAsync({
           deviceName,
           env,
           logcatDirectory,
+          logCapture,
           ...(localEgress ? { launchGate: localEgress.launchGate } : {}),
         });
         attemptSerialId = startResult.serialId;

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

@@ -14,6 +14,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { setTimeout as setTimeoutAsync } from 'node:timers/promises';
 import semver from 'semver';
+import bplistParser from 'bplist-parser';
+import plist from 'plist';
 import { z } from 'zod';
 
 import { type CustomBuildContext } from '../../customBuildContext';
@@ -43,6 +45,8 @@ import {
 import { killProcessGroup } from '../../utils/processes';
 import { sleepAsync } from '../../utils/retry';
 import { turtleFetch } from '../../utils/turtleFetch';
+import { resolveSimulatorPackageVersionAsync } from '../../utils/simulatorPackageVersion';
+import { readPreparedSimulatorToolAsync } from '../../utils/warmSimulator';
 import { startAppiumEventCollectionAsync } from '../utils/appiumEvents';
 import { preparePreinstalledWdaAsync } from '../utils/preinstalledWda';
 import { watchDeviceRunSessionStartup } from '../utils/deviceRunSessionStartup';
@@ -79,6 +83,12 @@ const AppiumInstalledDriversSchema = z.record(
   z.string(),
   z.object({ installed: z.boolean().optional() }).passthrough()
 );
+const PreparedAppiumSchema = z.object({
+  version: z.string(),
+  xcuitest: z.string(),
+  home: z.string(),
+});
+const PackageVersionSchema = z.object({ version: z.string() });
 
 export function createStartAppiumRemoteSessionBuildFunction(
   ctx: CustomBuildContext,
@@ -127,6 +137,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
         startup: { signal: watchSignal, abort: reason => startupStop.abort(reason) },
       });
       const deviceIdentifier = inputs.device_identifier?.value as string | undefined;
+      let requestedVersion: string | undefined;
       const startSessionAsync = async (warmSession?: WarmIosSession): Promise<void> => {
         const startupAbortController = new AbortController();
         const startupSignal = AbortSignal.any([watchSignal, startupAbortController.signal]);
@@ -149,7 +160,21 @@ export function createStartAppiumRemoteSessionBuildFunction(
           },
           { runtimePlatform }
         );
-        const versionSpec = resolveAppium3VersionSpec(packageVersion);
+        const resolveRequestedVersionAsync =
+          packageVersion === undefined
+            ? undefined
+            : async (): Promise<string> =>
+                (requestedVersion ??= await resolveSimulatorPackageVersionAsync(
+                  'appium',
+                  packageVersion,
+                  { env, signal: startupSignal }
+                ));
+        // Keep cold ranges on the configured installer's path. Tags need resolution to enforce Appium 3.
+        const versionSpec = resolveAppium3VersionSpec(
+          packageVersion !== undefined && !semver.validRange(packageVersion)
+            ? await resolveRequestedVersionAsync!()
+            : packageVersion
+        );
 
         logger.info(
           `Starting Appium remote session (version: ${versionSpec}, runtime: ${runtimePlatform}).`
@@ -211,6 +236,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
             asyncResult(
               installAppiumAsync({
                 versionSpec,
+                resolveRequestedVersionAsync,
                 driverName: device.driverName,
                 env,
                 logger,
@@ -231,7 +257,8 @@ export function createStartAppiumRemoteSessionBuildFunction(
             ),
           ]);
           const installation = appiumInstall.enforceValue();
-          appiumHome = installation.appiumHome;
+          // A prepared home is shared across sessions; remove only a job-owned home after a session.
+          appiumHome = installation.prepared ? undefined : installation.appiumHome;
           startupSignal?.throwIfAborted();
           const { appiumBinPath, appiumEnv } = installation;
           const wdaCapabilities = await preparePreinstalledWdaAsync({
@@ -243,7 +270,8 @@ export function createStartAppiumRemoteSessionBuildFunction(
                   })
                 )?.runtime
               : device.runtimeIdentifier,
-            appiumHome,
+            appiumHome: installation.appiumHome,
+            prepared: installation.prepared,
             appiumBinPath,
             appiumEnv,
             logger,
@@ -418,7 +446,8 @@ export function createStartAppiumRemoteSessionBuildFunction(
         watchSignal.throwIfAborted();
         if (warm && runtimePlatform === BuildRuntimePlatform.DARWIN) {
           await runOnWarmIosSimulatorAsync(
-            // package_version is the Appium version, which the job installs either way.
+            // package_version is the Appium version. The job installs it or uses the prepared
+            // home; the warm claim does not depend on it.
             {
               engine: 'appium',
               requestedDevice: deviceIdentifier,
@@ -503,6 +532,7 @@ export async function resolveAppiumDeviceAsync({
 
 export async function installAppiumAsync({
   versionSpec,
+  resolveRequestedVersionAsync,
   driverName,
   env,
   logger,
@@ -510,13 +540,53 @@ export async function installAppiumAsync({
   onError,
 }: {
   versionSpec: string;
+  resolveRequestedVersionAsync?: () => Promise<string>;
   driverName: AppiumDevice['driverName'];
   env: BuildStepEnv;
   logger: bunyan;
   signal?: AbortSignal;
   onError?: (error: unknown) => void;
-}): Promise<{ appiumHome: string; appiumBinPath: string; appiumEnv: BuildStepEnv }> {
+}): Promise<{
+  appiumHome: string;
+  appiumBinPath: string;
+  appiumEnv: BuildStepEnv;
+  prepared: boolean;
+}> {
   signal?.throwIfAborted();
+  let prepared =
+    driverName === 'xcuitest'
+      ? await readPreparedSimulatorToolAsync('appium', PreparedAppiumSchema)
+      : undefined;
+  if (
+    prepared &&
+    !(await isPreparedAppiumCompatibleAsync(prepared, { versionSpec, env, signal }))
+  ) {
+    prepared = undefined;
+  }
+  if (prepared && resolveRequestedVersionAsync) {
+    versionSpec = resolveAppium3VersionSpec(await resolveRequestedVersionAsync());
+    if (!semver.satisfies(prepared.version, versionSpec)) {
+      prepared = undefined;
+    }
+  }
+  if (prepared) {
+    try {
+      // An invalid package manager override fails as it does without a prepared home.
+      resolveConfiguredPackageManager(env, PackageManager.NPM);
+    } catch (error) {
+      onError?.(error);
+      throw error;
+    }
+    logger.info(
+      `Using the prefetched Appium home (appium ${prepared.version}, xcuitest ${prepared.xcuitest}).`
+    );
+    return {
+      appiumHome: prepared.home,
+      appiumBinPath: path.join(prepared.home, 'node_modules', '.bin', 'appium'),
+      appiumEnv: { ...env, APPIUM_HOME: prepared.home },
+      prepared: true,
+    };
+  }
   const appiumHome = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'eas-appium-home-'));
   try {
     signal?.throwIfAborted();
@@ -569,7 +639,7 @@ export async function installAppiumAsync({
         signal
       );
     }
-    return { appiumHome, appiumBinPath, appiumEnv };
+    return { appiumHome, appiumBinPath, appiumEnv, prepared: false };
   } catch (error) {
     onError?.(error);
     if (signal) {
@@ -580,6 +650,67 @@ export async function installAppiumAsync({
   }
 }
 
+/** A metadata hit still needs Appium-specific version, driver and runner checks before reuse. */
+async function isPreparedAppiumCompatibleAsync(
+  prepared: z.infer<typeof PreparedAppiumSchema>,
+  { versionSpec, env, signal }: { versionSpec: string; env: BuildStepEnv; signal?: AbortSignal }
+): Promise<boolean> {
+  const { home } = prepared;
+  if (home !== path.join(os.homedir(), 'Library', 'Caches', 'expo-simulator-startup', 'appium')) {
+    return false;
+  }
+  try {
+    const installedVersionAsync = async (name: string): Promise<string> =>
+      PackageVersionSchema.parse(
+        JSON.parse(
+          await fs.promises.readFile(path.join(home, 'node_modules', name, 'package.json'), 'utf8')
+        )
+      ).version;
+    if (
+      !semver.satisfies(prepared.version, versionSpec) ||
+      (await installedVersionAsync('appium')) !== prepared.version ||
+      (await installedVersionAsync('appium-xcuitest-driver')) !== prepared.xcuitest
+    ) {
+      return false;
+    }
+    const runner = path.join(home, 'preinstalled-wda', 'WebDriverAgentRunner-Runner.app');
+    await fs.promises.access(runner, fs.constants.R_OK | fs.constants.X_OK);
+    if (!(await fs.promises.stat(runner)).isDirectory()) {
+      return false;
+    }
+    const metadata = await fs.promises.readFile(path.join(runner, 'Info.plist'));
+    const info =
+      metadata.subarray(0, 8).toString('ascii') === 'bplist00'
+        ? bplistParser.parseBuffer(metadata)[0]
+        : plist.parse(metadata.toString('utf8'));
+    const executable = z
+      .object({ CFBundleExecutable: z.string().min(1) })
+      .parse(info).CFBundleExecutable;
+    if (path.basename(executable) !== executable || executable === '.' || executable === '..') {
+      return false;
+    }
+    const executablePath = path.join(runner, executable);
+    await fs.promises.access(executablePath, fs.constants.R_OK | fs.constants.X_OK);
+    const executableStat = await fs.promises.stat(executablePath);
+    if (!executableStat.isFile() || executableStat.size === 0) {
+      return false;
+    }
+    // Today's driver list shows that the Appium CLI runs from this home. It does not load the driver.
+    const { stdout } = await runAppiumSetupCommandAsync(
+      path.join(home, 'node_modules', '.bin', 'appium'),
+      ['driver', 'list', '--installed', '--json'],
+      { env: { ...env, APPIUM_HOME: home }, stdio: 'pipe' },
+      signal
+    );
+    if (!AppiumInstalledDriversSchema.parse(JSON.parse(stdout)).xcuitest?.installed) {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function runAppiumSetupCommandAsync(
   command: string,
   args: string[],

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

@@ -137,13 +137,6 @@ export function createStartArgentRemoteSessionBuildFunction(
       // A missing or non-positive value disables the idle timeout (opt-in feature).
       const maxIdleTimeMinutes = inputs.max_idle_time_minutes.value as number | undefined;
       const maxDurationSeconds = inputs.max_duration_seconds?.value as number | undefined;
-      validateControllerVersion({
-        packageName: ARGENT_PACKAGE_NAME,
-        minimumVersion: MIN_ARGENT_REMOTE_SESSION_VERSION,
-        packageVersion,
-        logger,
-      });
-      const versionSpec = packageVersion ?? 'latest';
       const { runtimePlatform } = global;
       const startupStop = new AbortController();
       const watchSignal = signal
@@ -156,7 +149,17 @@ export function createStartArgentRemoteSessionBuildFunction(
         startup: { signal: watchSignal, abort: reason => startupStop.abort(reason) },
       });
       const deviceIdentifier = inputs.device_identifier?.value as string | undefined;
-      const startSessionAsync = async (warmSession?: WarmIosSession): Promise<void> => {
+      const startSessionAsync = async (
+        warmSession?: WarmIosSession,
+        resolvedPackageVersion = packageVersion
+      ): Promise<void> => {
+        const versionSpec = resolvedPackageVersion ?? 'latest';
+        validateControllerVersion({
+          packageName: ARGENT_PACKAGE_NAME,
+          minimumVersion: MIN_ARGENT_REMOTE_SESSION_VERSION,
+          packageVersion: resolvedPackageVersion,
+          logger,
+        });
         const startupAbortController = new AbortController();
         const startupSignal = AbortSignal.any([watchSignal, startupAbortController.signal]);
         const { launch, iosStartup } = await resolveIosSessionStartupAsync({

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

@@ -1,11 +1,11 @@
-import { SystemError, UserError } from '@expo/eas-build-job';
+import { ArchiveSourceType, SystemError, UserError } from '@expo/eas-build-job';
 import { BuildFunction, BuildStepInput, BuildStepInputValueTypeName } from '@expo/steps';
 
+import { stripRepositoryCredentialsAsync } from '../../common/git';
 import { CustomBuildContext } from '../../customBuildContext';
 import { withLogPhaseAsync } from '../../utils/logPhase';
-import { getLegacySandboxConnection } from '../utils/legacySandboxApi';
 import { startSandboxDaemonAsync } from '../utils/sandboxDaemon';
-import { getSandboxWorkerApi } from '../utils/sandboxWorkerApi';
+import { requireSandboxWorkerApi } from '../utils/sandboxWorkerApi';
 
 const RECONNECT_DELAY_MS = 1_000;
 const AWAIT_SANDBOX_STEP_NAME = 'Await sandbox completion';
@@ -29,18 +29,7 @@ export function createStartSandboxBuildFunction(ctx: CustomBuildContext): BuildF
       }),
     ],
     fn: async (stepCtx, { inputs, signal, env }) => {
-      const workerApi = getSandboxWorkerApi(ctx);
-      const { sandboxApi, credential, commandEnv } = workerApi
-        ? {
-            sandboxApi: workerApi,
-            credential: workerApi.token,
-            commandEnv: env,
-          }
-        : getLegacySandboxConnection({
-            graphqlClient: ctx.graphqlClient,
-            env,
-            sandboxId: String(inputs.sandbox_id.value),
-          });
+      const workerApi = requireSandboxWorkerApi(ctx);
       const mcpServerUrl = ctx.mcpServerUrl;
       if (!mcpServerUrl) {
         throw new SystemError('MCP server URL is required to start the sandbox daemon.');
@@ -57,20 +46,29 @@ export function createStartSandboxBuildFunction(ctx: CustomBuildContext): BuildF
           `Invalid sandbox maximum duration: ${String(maxDurationSeconds)}. Provide a finite number greater than zero, or omit max_duration_seconds.`
         );
       }
+      if (ctx.job.projectArchive.type === ArchiveSourceType.GIT) {
+        // Scripts and commands inside the sandbox could read the token from .git/config.
+        await stripRepositoryCredentialsAsync({
+          repositoryDirectory: stepCtx.global.wasCheckedOut()
+            ? ctx.projectTargetDirectory
+            : ctx.projectSourceDirectory,
+        });
+      }
+
       const daemon = await startSandboxDaemonAsync({
-        credential,
+        credential: workerApi.token,
         serverUrl: mcpServerUrl,
         reconnectDelayMs: RECONNECT_DELAY_MS,
         logger: stepCtx.logger,
         signal,
         workingDirectory: stepCtx.workingDirectory,
-        env: commandEnv,
-        workerApi: sandboxApi,
+        env,
+        workerApi,
       });
       try {
         await daemon.ready;
         signal?.throwIfAborted();
-        await sandboxApi.markReadyAsync({ signal }).catch((error: unknown) => {
+        await workerApi.markReadyAsync({ signal }).catch((error: unknown) => {
           signal?.throwIfAborted();
           throw new SystemError(
             `Failed to mark sandbox ${String(inputs.sandbox_id.value)} as ready.`,

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

@@ -108,7 +108,10 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
         startup: { signal: watchSignal, abort: reason => startupStop.abort(reason) },
       });
       const deviceIdentifier = inputs.device_identifier?.value as string | undefined;
-      const startSessionAsync = async (warmSession?: WarmIosSession): Promise<void> => {
+      const startSessionAsync = async (
+        warmSession?: WarmIosSession,
+        resolvedPackageVersion = packageVersion
+      ): Promise<void> => {
         const startupAbortController = new AbortController();
         const startupSignal = AbortSignal.any([watchSignal, startupAbortController.signal]);
         const { launch, iosStartup } = await resolveIosSessionStartupAsync({
@@ -148,7 +151,7 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
             preview: { baseDomain: ngrokTunnelDomain, authtoken: ngrokAuthtoken },
             signal: startupSignal,
             onStartupError: error => startupAbortController.abort(error),
-            packageVersion,
+            packageVersion: resolvedPackageVersion,
             disableShare: inputs.public_preview?.value === false,
             privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
             frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),

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

@@ -217,8 +217,12 @@ describe(uploadAgentDeviceArtifactAsync, () => {
     );
   });
 
-  it('uploads a screenshot display rotation as artifact metadata', async () => {
-    const data = Buffer.from('png-data');
+  it('uploads the screenshot size, source and display rotation as artifact metadata', async () => {
+    const data = Buffer.from(
+      'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aF9sAAAAASUVORK5CYII=',
+      'base64'
+    );
+    const logger = createLoggerMock();
     const ctx = {} as unknown as CustomBuildContext;
 
     jest.mocked(fetch).mockResolvedValueOnce(new Response(Readable.from([data])));
@@ -232,7 +236,7 @@ describe(uploadAgentDeviceArtifactAsync, () => {
       deviceRunSessionId: 'drs-id',
       daemonUrl: 'http://127.0.0.1:1234',
       daemonToken: 'daemon-token',
-      logger: createLoggerMock(),
+      logger,
       artifact: {
         id: 'artifact-id',
         artifactType: 'screenshot',
@@ -245,12 +249,48 @@ describe(uploadAgentDeviceArtifactAsync, () => {
       ctx,
       expect.objectContaining({
         kind: 'screenshot',
-        metadata: { displayRotation: 'landscape-right' },
+        metadata: {
+          source: 'agent-device',
+          displayRotation: 'landscape-right',
+          width: 1,
+          height: 1,
+        },
       })
     );
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('uploads a screenshot without its size and warns when its header cannot be read', async () => {
+    const data = Buffer.from('not-an-image');
+    const logger = createLoggerMock();
+    const ctx = {} as unknown as CustomBuildContext;
+
+    jest.mocked(fetch).mockResolvedValueOnce(new Response(Readable.from([data])));
+    jest
+      .mocked(uploadDeviceRunSessionArtifactAsync)
+      .mockImplementationOnce(async (_ctx, { openStream }) => {
+        await readStreamAsync(openStream());
+      });
+
+    await uploadAgentDeviceArtifactAsync(ctx, {
+      deviceRunSessionId: 'drs-id',
+      daemonUrl: 'http://127.0.0.1:1234',
+      daemonToken: 'daemon-token',
+      logger,
+      artifact: { id: 'artifact-id', artifactType: 'screenshot', filename: 'shot.png' },
+    });
+
+    expect(jest.mocked(uploadDeviceRunSessionArtifactAsync)).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ kind: 'screenshot', metadata: { source: 'agent-device' } })
+    );
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ file: expect.stringMatching(/shot\.png$/) }),
+      expect.stringContaining('without its width and height')
+    );
   });
 
-  it('uploads no metadata when the artifact has no display rotation', async () => {
+  it('uploads no metadata for a non-screenshot artifact without a display rotation', async () => {
     const data = Buffer.from('artifact-data');
     const ctx = {} as unknown as CustomBuildContext;
 
@@ -266,7 +306,7 @@ describe(uploadAgentDeviceArtifactAsync, () => {
       daemonUrl: 'http://127.0.0.1:1234',
       daemonToken: 'daemon-token',
       logger: createLoggerMock(),
-      artifact: { id: 'artifact-id', artifactType: 'screenshot', filename: 'shot.png' },
+      artifact: { id: 'artifact-id', artifactType: 'screen-recording', filename: 'session.mp4' },
     });
 
     expect(jest.mocked(uploadDeviceRunSessionArtifactAsync).mock.calls[0][1]).not.toHaveProperty(

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

@@ -0,0 +1,279 @@
+import { type BuildStepGlobalContext } from '@expo/steps';
+import { once } from 'node:events';
+import fsPromises, {
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rm,
+  symlink,
+  writeFile,
+} from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { PassThrough, Readable } from 'node:stream';
+
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { type CustomBuildContext } from '../../../customBuildContext';
+import { MAX_ANDROID_LOG_BYTES_PER_SOURCE } from '../../../utils/androidEmulatorLogCapture';
+import {
+  ALL_ANDROID_EMULATOR_LOG_SOURCES,
+  type AndroidEmulatorLogSource,
+} from '../../../utils/androidEmulatorLogSources';
+import {
+  collectAndroidEmulatorLogsAsync,
+  getAndroidEmulatorLogCapture,
+} from '../androidEmulatorLogs';
+import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
+
+jest.mock('../deviceRunSessionArtifacts');
+jest.unmock('fs');
+jest.unmock('node:fs');
+jest.unmock('fs/promises');
+jest.unmock('node:fs/promises');
+
+const ctx = {} as CustomBuildContext;
+const sessionEnv = { DEVICE_RUN_SESSION_ID: 'session' };
+const upload = jest.mocked(uploadDeviceRunSessionArtifactAsync);
+let directory: string;
+let emulatorPath: string;
+let logcatPath: string;
+let emulatorRing: string;
+let logcatRing: string;
+let global: BuildStepGlobalContext;
+let logger: ReturnType<typeof createMockLogger>;
+let uploadedContents: Map<string, string>;
+
+beforeEach(async () => {
+  global = {} as BuildStepGlobalContext;
+  logger = createMockLogger();
+  uploadedContents = new Map();
+  directory = await mkdtemp(path.join(os.tmpdir(), 'android-log-collection-'));
+  emulatorPath = path.join(directory, 'device-attempt-1-emulator.log');
+  logcatPath = path.join(directory, 'device-attempt-1-logcat.log');
+  emulatorRing = path.join(directory, 'emulator-output.log');
+  logcatRing = path.join(directory, 'device-logcat.log');
+  upload.mockReset().mockImplementation(async (_ctx, { filename, openStream }) => {
+    const chunks: Buffer[] = [];
+    for await (const chunk of openStream()) {
+      chunks.push(Buffer.from(chunk));
+    }
+    uploadedContents.set(filename, Buffer.concat(chunks).toString());
+  });
+});
+
+afterEach(async () => {
+  jest.restoreAllMocks();
+  await rm(directory, { recursive: true, force: true });
+});
+
+/** `==== <launch> <ISO time> ====\n` precedes the first output of a launch. */
+const MARKER = String.raw`==== \S+ \S+ ====\n`;
+
+async function captureLaunch(
+  filePath: string,
+  source: AndroidEmulatorLogSource,
+  text: string,
+  workflow = global
+): Promise<void> {
+  const capture = getAndroidEmulatorLogCapture(
+    workflow,
+    sessionEnv,
+    ALL_ANDROID_EMULATOR_LOG_SOURCES
+  );
+  const input = Readable.from([Buffer.from(text)]);
+  capture.attach(input, filePath, source);
+  await once(input, 'end');
+  await capture.finishFileAsync(filePath);
+}
+
+function collect(): Promise<void> {
+  return collectAndroidEmulatorLogsAsync(ctx, {
+    global,
+    deviceRunSessionId: 'session',
+    logger,
+  });
+}
+
+it.each([
+  { env: {}, file: 'device-attempt-1-emulator.log', expectedBytes: 20 * 1024 * 1024 + 1 },
+  { env: sessionEnv, file: 'emulator-output.log', expectedBytes: 20 * 1024 * 1024 },
+])(
+  'retains $expectedBytes in $file with workflow environment $env',
+  async ({ env, file, expectedBytes }) => {
+    const capture = getAndroidEmulatorLogCapture(global, env, ALL_ANDROID_EMULATOR_LOG_SOURCES);
+    const input = Readable.from([Buffer.alloc(20 * 1024 * 1024 + 1, 'x')]);
+    capture.attach(input, emulatorPath, 'emulator-output');
+    await once(input, 'end');
+    await capture.finishAsync();
+    expect((await fsPromises.stat(path.join(directory, file))).size).toBe(expectedBytes);
+  }
+);
+
+it('uploads one artifact per source and ignores files outside the capture inventory', async () => {
+  await captureLaunch(emulatorPath, 'emulator-output', 'host output');
+  await captureLaunch(logcatPath, 'device-logcat', 'Android output');
+  await captureLaunch(
+    path.join(directory, 'retry-emulator.log'),
+    'emulator-output',
+    'retry output'
+  );
+  await writeFile(emulatorPath, 'not captured');
+  const elsewhere = path.join(directory, 'elsewhere');
+  await mkdir(elsewhere);
+  await writeFile(path.join(elsewhere, 'other-emulator.log'), 'another job');
+  await symlink(path.join(elsewhere, 'other-emulator.log'), logcatPath);
+  await collect();
+
+  expect([...uploadedContents.keys()]).toEqual(['emulator-output.log', 'device-logcat.log']);
+  expect(uploadedContents.get('emulator-output.log')).toMatch(
+    new RegExp(`^${MARKER}host output\\n${MARKER}retry output$`)
+  );
+  expect(uploadedContents.get('device-logcat.log')).toMatch(
+    new RegExp(`^${MARKER}Android output$`)
+  );
+  expect(upload).toHaveBeenCalledWith(
+    ctx,
+    expect.objectContaining({
+      filename: 'emulator-output.log',
+      kind: 'simulator-log',
+      metadata: expect.objectContaining({
+        platform: 'android',
+        source: 'emulator-output',
+        scope: 'emulator-process',
+        originalSizeBytes: uploadedContents.get('emulator-output.log')?.length,
+        omittedBytes: 0,
+        truncated: false,
+      }),
+      signal: expect.any(AbortSignal),
+      attempts: 2,
+    })
+  );
+  expect(upload).toHaveBeenCalledWith(
+    ctx,
+    expect.objectContaining({
+      filename: 'device-logcat.log',
+      metadata: expect.objectContaining({ source: 'device-logcat', scope: 'device' }),
+    })
+  );
+});
+
+it('seals a live producer before upload and keeps retry bodies identical without copying files', async () => {
+  const input = new PassThrough();
+  const capture = getAndroidEmulatorLogCapture(
+    global,
+    sessionEnv,
+    ALL_ANDROID_EMULATOR_LOG_SOURCES
+  );
+  capture.attach(input, emulatorPath, 'emulator-output');
+  input.write('before');
+  const contents: string[] = [];
+  upload.mockImplementationOnce(async (_ctx, { size, openStream, metadata }) => {
+    expect(metadata).toEqual(
+      expect.objectContaining({ originalSizeBytes: size, truncated: false })
+    );
+    for (let attempt = 0; attempt < 2; attempt++) {
+      input.write(' ignored after finalization');
+      const chunks: Buffer[] = [];
+      for await (const chunk of openStream()) {
+        chunks.push(Buffer.from(chunk));
+      }
+      contents.push(Buffer.concat(chunks).toString());
+    }
+  });
+  try {
+    await collect();
+    expect(contents).toHaveLength(2);
+    expect(contents[0]).toMatch(new RegExp(`^${MARKER}before$`));
+    expect(contents[1]).toBe(contents[0]);
+    expect(await readFile(emulatorRing, 'utf8')).toBe(contents[0]);
+    expect(await readdir(directory)).toEqual(['emulator-output.log']);
+    expect(input.readableFlowing).toBe(true);
+    const late = new PassThrough();
+    capture.attach(late, logcatPath, 'device-logcat');
+    late.end('not captured');
+    expect(late.readableFlowing).toBe(true);
+    await expect(fsPromises.stat(logcatRing)).rejects.toMatchObject({ code: 'ENOENT' });
+  } finally {
+    input.end();
+  }
+});
+
+it('continues with the other log after a failed upload and never repeats the collection', async () => {
+  await captureLaunch(emulatorPath, 'emulator-output', 'host output');
+  await captureLaunch(logcatPath, 'device-logcat', 'Android output');
+  upload.mockRejectedValueOnce(new Error('storage unavailable'));
+  await Promise.all([collect(), collect()]);
+  await collect();
+  expect(upload).toHaveBeenCalledTimes(2);
+  expect(uploadedContents.get('device-logcat.log')).toMatch(/Android output$/);
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.stringContaining('other logs will continue')
+  );
+});
+
+it('uses a fresh 30 second budget for the next file after an upload times out', async () => {
+  await captureLaunch(emulatorPath, 'emulator-output', 'host output');
+  await captureLaunch(logcatPath, 'device-logcat', 'Android output');
+  const controllers: AbortController[] = [];
+  const timeout = jest.spyOn(AbortSignal, 'timeout').mockImplementation(() => {
+    const controller = new AbortController();
+    controllers.push(controller);
+    return controller.signal;
+  });
+  upload.mockImplementationOnce(async (_ctx, { signal }) => {
+    controllers[0].abort(new Error('upload timed out'));
+    signal?.throwIfAborted();
+  });
+  await expect(collect()).resolves.toBeUndefined();
+  expect(uploadedContents.get('device-logcat.log')).toMatch(/Android output$/);
+  expect(timeout.mock.calls).toEqual([[30_000], [30_000]]);
+  expect(upload.mock.calls[1][1].signal?.aborted).toBe(false);
+});
+
+it('does not collect another workflow and warns when a captured file disappears', async () => {
+  const otherWorkflow = {} as BuildStepGlobalContext;
+  await captureLaunch(emulatorPath, 'emulator-output', 'other workflow', otherWorkflow);
+  await collect();
+  expect(upload).not.toHaveBeenCalled();
+  await getAndroidEmulatorLogCapture(otherWorkflow, sessionEnv, []).finishAsync();
+  await captureLaunch(path.join(directory, 'missing-emulator.log'), 'emulator-output', 'removed');
+  await rm(emulatorRing);
+  await expect(collect()).resolves.toBeUndefined();
+  expect(upload).not.toHaveBeenCalled();
+  expect(logger.warn).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.stringContaining('emulator-output.log')
+  );
+});
+
+it('uploads the tail of a truncated log with the retained size and omission metadata', async () => {
+  const capture = getAndroidEmulatorLogCapture(
+    global,
+    sessionEnv,
+    ALL_ANDROID_EMULATOR_LOG_SOURCES
+  );
+  const input = Readable.from([
+    Buffer.concat([Buffer.from('head: '), Buffer.alloc(MAX_ANDROID_LOG_BYTES_PER_SOURCE, 'b')]),
+  ]);
+  capture.attach(input, emulatorPath, 'emulator-output');
+  await once(input, 'end');
+  await collect();
+  const uploaded = uploadedContents.get('emulator-output.log');
+  expect(uploaded).toHaveLength(MAX_ANDROID_LOG_BYTES_PER_SOURCE);
+  expect(uploaded).not.toContain('head');
+  expect(uploaded).not.toContain('====');
+  const [, call] = upload.mock.calls[0];
+  const { originalSizeBytes } = call.metadata as { originalSizeBytes: number };
+  const omitted = originalSizeBytes - MAX_ANDROID_LOG_BYTES_PER_SOURCE;
+  expect(omitted).toBeGreaterThanOrEqual(6);
+  expect(call).toEqual(
+    expect.objectContaining({
+      size: MAX_ANDROID_LOG_BYTES_PER_SOURCE,
+      name: expect.stringContaining('truncated, last 20.0 MB retained'),
+      metadata: expect.objectContaining({ omittedBytes: omitted, truncated: true }),
+    })
+  );
+});

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

@@ -155,17 +155,18 @@ describe(uploadArgentArtifactAsync, () => {
     });
   });
 
-  async function uploadAsync(artifact: {
-    id: string;
-    kind?: string;
-    filename: string;
-    mimeType: string;
-    isDirectory?: boolean;
-  }): Promise<CustomBuildContext> {
+  async function uploadAsync(
+    artifact: {
+      id: string;
+      kind?: string;
+      filename: string;
+      mimeType: string;
+      isDirectory?: boolean;
+    },
+    data = Buffer.from('artifact-data')
+  ): Promise<CustomBuildContext> {
     const ctx = {} as unknown as CustomBuildContext;
-    jest
-      .mocked(fetch)
-      .mockResolvedValueOnce(new Response(Readable.from([Buffer.from('artifact-data')])));
+    jest.mocked(fetch).mockResolvedValueOnce(new Response(Readable.from([data])));
     jest
       .mocked(uploadDeviceRunSessionArtifactAsync)
       .mockImplementationOnce(async (_ctx, { openStream }) => {
@@ -200,6 +201,45 @@ describe(uploadArgentArtifactAsync, () => {
     );
   });
 
+  it.each([
+    { kind: undefined, expectedKind: 'screenshot' },
+    { kind: 'screenshot-diff', expectedKind: 'screenshot-diff' },
+  ])('sends the size of a $expectedKind read from its header', async ({ kind, expectedKind }) => {
+    const png = Buffer.alloc(33);
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(png);
+    png.writeUInt32BE(13, 8);
+    png.write('IHDR', 12, 'latin1');
+    png.writeUInt32BE(1179, 16);
+    png.writeUInt32BE(2556, 20);
+    const ctx = await uploadAsync(
+      { id: 'artifact-id', kind, filename: 'screen.png', mimeType: 'image/png' },
+      png
+    );
+
+    expect(jest.mocked(uploadDeviceRunSessionArtifactAsync)).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        kind: expectedKind,
+        metadata: { source: 'argent', width: 1179, height: 2556 },
+      })
+    );
+  });
+
+  it('sends no screenshot metadata for other artifacts', async () => {
+    await uploadAsync({ id: 'artifact-id', filename: 'session.mp4', mimeType: 'video/mp4' });
+    await uploadAsync({
+      id: 'artifact-id',
+      kind: 'screenshot',
+      filename: 'screenshots',
+      mimeType: 'image/png',
+      isDirectory: true,
+    });
+
+    for (const [, input] of jest.mocked(uploadDeviceRunSessionArtifactAsync).mock.calls) {
+      expect(input).not.toHaveProperty('metadata');
+    }
+  });
+
   it('uses the semantic kind reported by Argent', async () => {
     const ctx = await uploadAsync({
       id: 'artifact-id',

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

@@ -45,6 +45,17 @@ function createCtx(): CustomBuildContext {
   } as unknown as CustomBuildContext;
 }
 
+function webpPreview(width: number, height: number): Buffer {
+  const image = Buffer.alloc(30);
+  image.write('RIFF', 0, 'latin1');
+  image.writeUInt32LE(22, 4);
+  image.write('WEBPVP8X', 8, 'latin1');
+  image.writeUInt32LE(10, 16);
+  image.writeUIntLE(width - 1, 24, 3);
+  image.writeUIntLE(height - 1, 27, 3);
+  return image;
+}
+
 function uploadSessionResponse(): InstanceType<typeof Response> {
   return new Response(JSON.stringify({ data: { uploadSession } }), {
     headers: { 'content-type': 'application/json' },
@@ -226,6 +237,89 @@ describe('session preview upload session from the worker API', () => {
     expect(fetch).toHaveBeenCalledTimes(1);
   });
 
+  it('sends no metadata when the preview size cannot be read', async () => {
+    start();
+    await jest.advanceTimersByTimeAsync(0);
+    expect(turtleFetch).toHaveBeenCalledWith(
+      PREVIEW_UPLOAD_SESSION_URL,
+      'POST',
+      expect.not.objectContaining({ json: expect.anything() })
+    );
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('sends the preview size and refreshes it only when the size changes', async () => {
+    const captureAsync = jest
+      .fn<Promise<Buffer>, [AbortSignal]>()
+      .mockResolvedValueOnce(webpPreview(148, 320))
+      .mockResolvedValueOnce(webpPreview(148, 320))
+      .mockResolvedValue(webpPreview(320, 148));
+    preview = startDeviceRunSessionPreview({
+      ctx: createCtx(),
+      deviceRunSessionId: 'session-id',
+      captureAsync,
+      logger,
+    });
+    await jest.advanceTimersByTimeAsync(120_000);
+    expect(captureAsync).toHaveBeenCalledTimes(3);
+    expect(fetch).toHaveBeenCalledTimes(3);
+    expect(jest.mocked(turtleFetch).mock.calls.map(([, , options]) => options.json)).toEqual([
+      { metadata: { source: 'preview', width: 148, height: 320 } },
+      { metadata: { source: 'preview', width: 320, height: 148 } },
+    ]);
+    expect(jest.mocked(turtleFetch).mock.invocationCallOrder[1]).toBeGreaterThan(
+      jest.mocked(fetch).mock.invocationCallOrder[2]
+    );
+  });
+
+  it('keeps the stored size when the upload of a resized preview fails', async () => {
+    const captureAsync = jest
+      .fn<Promise<Buffer>, [AbortSignal]>()
+      .mockResolvedValueOnce(webpPreview(148, 320))
+      .mockResolvedValue(webpPreview(320, 148));
+    jest
+      .mocked(fetch)
+      .mockResolvedValueOnce(new Response('', { status: 200 }))
+      .mockResolvedValueOnce(new Response('', { status: 503 }));
+    preview = startDeviceRunSessionPreview({
+      ctx: createCtx(),
+      deviceRunSessionId: 'session-id',
+      captureAsync,
+      logger,
+    });
+    await jest.advanceTimersByTimeAsync(60_000);
+    await preview.stopAsync();
+    expect(fetch).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(turtleFetch).mock.calls.map(([, , options]) => options.json)).toEqual([
+      { metadata: { source: 'preview', width: 148, height: 320 } },
+    ]);
+  });
+
+  it('sends the size again after a failed size refresh', async () => {
+    const captureAsync = jest
+      .fn<Promise<Buffer>, [AbortSignal]>()
+      .mockResolvedValueOnce(webpPreview(148, 320))
+      .mockResolvedValueOnce(webpPreview(320, 148))
+      .mockResolvedValue(webpPreview(148, 320));
+    jest
+      .mocked(turtleFetch)
+      .mockImplementationOnce(async () => uploadSessionResponse())
+      .mockRejectedValueOnce(new Error('response lost'));
+    preview = startDeviceRunSessionPreview({
+      ctx: createCtx(),
+      deviceRunSessionId: 'session-id',
+      captureAsync,
+      logger,
+    });
+    await jest.advanceTimersByTimeAsync(120_000);
+    expect(jest.mocked(turtleFetch).mock.calls.map(([, , options]) => options.json)).toEqual([
+      { metadata: { source: 'preview', width: 148, height: 320 } },
+      { metadata: { source: 'preview', width: 320, height: 148 } },
+      { metadata: { source: 'preview', width: 148, height: 320 } },
+    ]);
+    expect(fetch).toHaveBeenCalledTimes(3);
+  });
+
   it('logs a failure and uploads nothing when the job has no device run session token', async () => {
     start({
       env: {},
@@ -315,10 +409,8 @@ describe(captureDeviceRunSessionPreviewAsync, () => {
           }) as ReturnType<typeof spawn>;
         }
         return (async () => {
-          if (command === 'xcrun') {
-            expect(args.slice(0, 4)).toEqual(['simctl', 'io', 'selected-device', 'screenshot']);
-            await writeFile(args[4], Uint8Array.from(png));
-          } else if (command === 'sips') {
+          expect(command).not.toBe('xcrun');
+          if (command === 'sips') {
             expect(args.slice(0, 2)).toEqual(['-Z', '320']);
             expect(await readFile(args[2])).toEqual(png);
             await writeFile(args[args.indexOf('--out') + 1], Uint8Array.from(resized));
@@ -340,6 +432,10 @@ describe(captureDeviceRunSessionPreviewAsync, () => {
         await captureDeviceRunSessionPreviewAsync({
           runtimePlatform,
           device,
+          captureIosScreenshotAsync: async (file, signal) => {
+            signal.throwIfAborted();
+            await writeFile(file, Uint8Array.from(png));
+          },
           env: {},
           signal: new AbortController().signal,
         })
@@ -372,6 +468,9 @@ describe(captureDeviceRunSessionPreviewAsync, () => {
       captureDeviceRunSessionPreviewAsync({
         runtimePlatform: BuildRuntimePlatform.DARWIN,
         device: 'device',
+        captureIosScreenshotAsync: async () => {
+          throw new Error('capture failed');
+        },
         env: {},
         signal: new AbortController().signal,
       })

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

@@ -0,0 +1,205 @@
+import type { bunyan } from '@expo/logger';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  createScreenshotMetadataAsync,
+  readImageSize,
+} from '../deviceRunSessionScreenshotMetadata';
+
+function png(width: number, height: number): Buffer {
+  const header = Buffer.alloc(33);
+  Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(header);
+  header.writeUInt32BE(13, 8);
+  header.write('IHDR', 12, 'latin1');
+  header.writeUInt32BE(width, 16);
+  header.writeUInt32BE(height, 20);
+  return header;
+}
+
+function webp(chunk: string, data: Buffer): Buffer {
+  const header = Buffer.alloc(20);
+  header.write('RIFF', 0, 'latin1');
+  header.writeUInt32LE(12 + data.length, 4);
+  header.write('WEBP', 8, 'latin1');
+  header.write(chunk, 12, 'latin1');
+  header.writeUInt32LE(data.length, 16);
+  return Buffer.concat([header, data]);
+}
+
+function vp8(width: number, height: number): Buffer {
+  const data = Buffer.alloc(10);
+  Buffer.from([0x9d, 0x01, 0x2a]).copy(data, 3);
+  data.writeUInt16LE(width, 6);
+  data.writeUInt16LE(height, 8);
+  return webp('VP8 ', data);
+}
+
+function vp8l(width: number, height: number): Buffer {
+  const data = Buffer.alloc(10);
+  data[0] = 0x2f;
+  data.writeUInt32LE((width - 1) | ((height - 1) << 14), 1);
+  return webp('VP8L', data);
+}
+
+function vp8x(width: number, height: number): Buffer {
+  const data = Buffer.alloc(10);
+  data.writeUIntLE(width - 1, 4, 3);
+  data.writeUIntLE(height - 1, 7, 3);
+  return webp('VP8X', data);
+}
+
+function jpegSegment(marker: number, payload: Buffer): Buffer {
+  const header = Buffer.from([0xff, marker, 0, 0]);
+  header.writeUInt16BE(payload.length + 2, 2);
+  return Buffer.concat([header, payload]);
+}
+
+function jpegFrame(marker: number, width: number, height: number, components = 3): Buffer {
+  const payload = Buffer.alloc(6 + 3 * components);
+  payload[0] = 8;
+  payload.writeUInt16BE(height, 1);
+  payload.writeUInt16BE(width, 3);
+  payload[5] = components;
+  return jpegSegment(marker, payload);
+}
+
+const JPEG_START = Buffer.from([0xff, 0xd8]);
+
+describe(readImageSize, () => {
+  it('reads the PNG IHDR size', () => {
+    expect(readImageSize(png(1179, 2556))).toEqual({ width: 1179, height: 2556 });
+  });
+
+  it('reads the lossy WebP frame size without its scale bits', () => {
+    expect(readImageSize(vp8(0x4000 | 1179, 0xc000 | 2556))).toEqual({
+      width: 1179,
+      height: 2556,
+    });
+  });
+
+  it('reads the lossless WebP size', () => {
+    expect(readImageSize(vp8l(1179, 2556))).toEqual({ width: 1179, height: 2556 });
+  });
+
+  it('reads the size of a minimal lossless WebP shorter than other WebP headers', () => {
+    const minimalLossless = Buffer.from(
+      '5249464614000000574542505650384c080000002f0fc00310888808',
+      'hex'
+    );
+    expect(readImageSize(minimalLossless)).toEqual({ width: 16, height: 16 });
+  });
+
+  it('reads the extended WebP canvas size', () => {
+    expect(readImageSize(vp8x(1179, 2556))).toEqual({ width: 1179, height: 2556 });
+  });
+
+  it('reads the JPEG frame size after other segments', () => {
+    const jpeg = Buffer.concat([
+      JPEG_START,
+      jpegSegment(0xe1, Buffer.alloc(300)),
+      Buffer.from([0xff]),
+      jpegSegment(0xc4, Buffer.alloc(20)),
+      jpegFrame(0xc2, 1179, 2556),
+    ]);
+    expect(readImageSize(jpeg)).toEqual({ width: 1179, height: 2556 });
+  });
+
+  it.each([
+    ['an empty buffer', Buffer.alloc(0)],
+    ['a truncated PNG', png(1179, 2556).subarray(0, 20)],
+    ['a PNG without IHDR first', Buffer.concat([png(1, 1).subarray(0, 12), Buffer.alloc(21)])],
+    ['a zero-width PNG', png(0, 2556)],
+    ['a truncated WebP', vp8x(1179, 2556).subarray(0, 26)],
+    ['a WebP with an unknown chunk', webp('ALPH', Buffer.alloc(10))],
+    ['a lossy WebP without a start code', webp('VP8 ', Buffer.alloc(10))],
+    [
+      'a JPEG truncated in its frame header',
+      Buffer.concat([JPEG_START, jpegFrame(0xc0, 1179, 2556)]).subarray(0, 8),
+    ],
+    [
+      'a JPEG truncated before its frame',
+      Buffer.concat([JPEG_START, jpegSegment(0xe1, Buffer.alloc(300))]),
+    ],
+    [
+      'a JPEG with scan data before a frame',
+      Buffer.concat([JPEG_START, jpegSegment(0xda, Buffer.alloc(10)), jpegFrame(0xc0, 1, 1)]),
+    ],
+    [
+      'a JPEG frame without components',
+      Buffer.concat([JPEG_START, jpegFrame(0xc0, 1179, 2556, 0)]),
+    ],
+    ['a JPEG frame shorter than its header', Buffer.from('ffd8ffc0000208049b09fc', 'hex')],
+    ['a JPEG frame longer than the read bytes', Buffer.from('ffd8ffc0ffff08049b09fc', 'hex')],
+    [
+      'a JPEG frame whose length does not match its components',
+      Buffer.concat([
+        JPEG_START,
+        jpegSegment(
+          0xc0,
+          Buffer.concat([Buffer.from([8, 0x09, 0xfc, 0x04, 0x9b, 3]), Buffer.alloc(6)])
+        ),
+      ]),
+    ],
+    ['a GIF', Buffer.from('GIF89a\x01\x00\x01\x00\x00\x00\x00', 'latin1')],
+    ['a log file', Buffer.from('2026-11-10T12:00:00Z app started\n'.repeat(4))],
+  ])('returns undefined for %s', (_description, header) => {
+    expect(readImageSize(header)).toBeUndefined();
+  });
+});
+
+describe(createScreenshotMetadataAsync, () => {
+  let directory: string;
+  let logger: bunyan;
+
+  beforeEach(async () => {
+    directory = await mkdtemp(path.join(os.tmpdir(), 'screenshot-metadata-test-'));
+    logger = { warn: jest.fn() } as unknown as bunyan;
+  });
+
+  afterEach(async () => {
+    await rm(directory, { recursive: true, force: true });
+  });
+
+  it('adds the image size to the screenshot metadata', async () => {
+    const file = path.join(directory, 'shot.png');
+    await writeFile(file, Buffer.concat([png(1179, 2556), Buffer.alloc(128 * 1024)]));
+    await expect(
+      createScreenshotMetadataAsync(file, {
+        source: 'agent-device',
+        displayRotation: 'landscape-left',
+        logger,
+      })
+    ).resolves.toEqual({
+      source: 'agent-device',
+      displayRotation: 'landscape-left',
+      width: 1179,
+      height: 2556,
+    });
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('warns and leaves out the size when the header is not a supported image', async () => {
+    const file = path.join(directory, 'shot.png');
+    await writeFile(file, 'not-an-image');
+    await expect(
+      createScreenshotMetadataAsync(file, { source: 'manual', logger })
+    ).resolves.toEqual({ source: 'manual' });
+    expect(logger.warn).toHaveBeenCalledWith(
+      { file },
+      'Uploading the screenshot without its width and height because it does not start with a complete PNG, WebP or JPEG header.'
+    );
+  });
+
+  it('warns and leaves out the size when the file cannot be read', async () => {
+    const file = path.join(directory, 'missing.png');
+    await expect(
+      createScreenshotMetadataAsync(file, { source: 'manual', logger })
+    ).resolves.toEqual({ source: 'manual' });
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: expect.objectContaining({ code: 'ENOENT' }), file },
+      'Uploading the screenshot without its width and height because its header could not be read.'
+    );
+  });
+});

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

@@ -8,12 +8,14 @@ import path from 'node:path';
 import type { CustomBuildContext } from '../../../customBuildContext';
 import { Sentry } from '../../../sentry';
 import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
+import { createScreenshotMetadataAsync } from '../deviceRunSessionScreenshotMetadata';
 import {
   startDeviceRunSessionScreenshotsAsync,
   uploadDeviceRunSessionScreenshotsAsync,
 } from '../deviceRunSessionScreenshots';
 
 jest.mock('../deviceRunSessionArtifacts');
+jest.mock('../deviceRunSessionScreenshotMetadata');
 jest.mock('../../../sentry');
 const ctx = {} as CustomBuildContext;
 const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
@@ -27,6 +29,9 @@ beforeEach(async () => {
   directory = await mkdtemp(path.join(os.tmpdir(), 'screenshots-test-'));
   uploaded = [];
   failedUploads = new Map();
+  jest
+    .mocked(createScreenshotMetadataAsync)
+    .mockResolvedValue({ source: 'manual', width: 1179, height: 2556 });
   jest
     .mocked(uploadDeviceRunSessionArtifactAsync)
     .mockImplementation(async (_ctx, { openStream }) => {
@@ -68,9 +73,13 @@ it('uploads completed captures with their bytes and stable IDs, ignoring partial
       filename: 'screenshot-2026-09-24T08-45-59-123Z.png',
       kind: 'screenshot',
       size: 11,
-      metadata: { __eas_type: 'screenshot' },
+      metadata: { __eas_type: 'screenshot', source: 'manual', width: 1179, height: 2556 },
     })
   );
+  expect(createScreenshotMetadataAsync).toHaveBeenCalledWith(path.join(directory, filename), {
+    source: 'manual',
+    logger,
+  });
   expect(await readdir(directory)).not.toContain(filename);
   expect((await lstat(path.join(directory, link))).isSymbolicLink()).toBe(true);
 });

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

@@ -152,6 +152,9 @@ it('publishes a manual preview PNG through the worker API and HTTP upload path',
       platform: 'ios',
       buildId: 'installed-build',
       gitCommitHash: installedCommit,
+      source: 'manual',
+      width: 1,
+      height: 1,
     },
   });
   await expect(stat(path.join(directory, filename))).rejects.toMatchObject({ code: 'ENOENT' });

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

@@ -13,6 +13,7 @@ import type { CustomBuildContext } from '../../../customBuildContext';
 import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
 import { findUnlistedDeviceScreenRecordingsAsync } from '../deviceRunSessionScreenRecordings';
 import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
+import { uploadDeviceRunSessionFileAsync } from '../uploadDeviceRunSessionFile';
 
 jest.unmock('node-fetch');
 jest.unmock('node:fs');
@@ -123,6 +124,41 @@ it('replays the full file after a transient PUT failure without recreating the u
   expect(streams.every(stream => stream.destroyed)).toBe(true);
 });
 
+it('retries a PUT that fails before reading the body without aborting the file stream', async () => {
+  let puts = 0;
+  let replayed = 0;
+  handle = (request, response) => {
+    puts++;
+    if (puts === 1) {
+      response.statusCode = 503;
+      response.flushHeaders();
+      return;
+    }
+    request.on('data', chunk => {
+      replayed += chunk.length;
+    });
+    request.on('end', () => response.end());
+  };
+  const file = path.join(directory, 'emulator.log');
+  const payload = Buffer.alloc(8 * 1024 * 1024, '*');
+  await writeFile(file, payload);
+  await expect(
+    uploadDeviceRunSessionFileAsync(ctx, {
+      filePath: file,
+      describe: () => ({
+        deviceRunSessionId: 'drs-id',
+        artifactId: 'log-id',
+        name: 'Emulator log',
+        filename: 'emulator.log',
+        kind: 'simulator-log',
+      }),
+      attempts: 2,
+    })
+  ).resolves.toBe(true);
+  expect(puts).toBe(2);
+  expect(replayed).toBe(payload.length);
+});
+
 it('keeps a slow PUT alive while its body is still flowing', async () => {
   jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'queueMicrotask'] });
   let received = 0;

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

@@ -176,6 +176,18 @@ describe(DeviceRunSessionWorkerApi, () => {
       data: { uploadSession: { url: 'https://uploads.test/preview', headers: {} } },
       expected: { url: 'https://uploads.test/preview', headers: {} },
     },
+    {
+      name: 'createPreviewUploadSessionAsync with metadata',
+      call: (api: DeviceRunSessionWorkerApi) =>
+        api.createPreviewUploadSessionAsync({
+          metadata: { source: 'preview', width: 148, height: 320 },
+        }),
+      method: 'POST',
+      route: 'preview-upload-session',
+      json: { metadata: { source: 'preview', width: 148, height: 320 } },
+      data: { uploadSession: { url: 'https://uploads.test/preview', headers: {} } },
+      expected: { url: 'https://uploads.test/preview', headers: {} },
+    },
     {
       name: 'fetchTurnIceServersAsync',
       call: (api: DeviceRunSessionWorkerApi) => api.fetchTurnIceServersAsync(),

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

@@ -9,6 +9,7 @@ import path from 'node:path';
 
 import type { CustomBuildContext } from '../../../customBuildContext';
 import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import { IosSimulatorRecordingUtils } from '../IosSimulatorRecordingUtils';
 import { verifyLocalEgressGuardAsync } from '../localEgressGuard';
 import { type ServeSimApplicationOptions } from '../remoteDeviceRunSession';
 
@@ -39,9 +40,14 @@ import {
   spawnDetached,
   startNgrokTunnelAsync,
 } from '../remoteDeviceRunSession';
-import { runServeSimActionAsync, stageServeSimAppAsync } from '../serveSimActions';
+import {
+  runServeSimActionAsync,
+  runServeSimActionWithResultAsync,
+  stageServeSimAppAsync,
+} from '../serveSimActions';
 import { startServeSimActivityPolling } from '../serveSimActivity';
 import { readServeSimServersAsync } from '../serveSimMetricsRecorder';
+import * as previewCapture from '../serveSimPreviewCapture';
 
 jest.mock('@ngrok/ngrok');
 jest.mock('@expo/turtle-spawn');
@@ -164,6 +170,12 @@ beforeEach(() => {
     .mockImplementation(async ({ artifactPath }) => installedBundleIds[artifactPath]);
   jest.mocked(verifyLocalEgressGuardAsync).mockReset().mockResolvedValue(undefined);
   jest.mocked(readLocalEgressHandoffAsync).mockReset().mockResolvedValue(null);
+  jest
+    .mocked(runServeSimActionWithResultAsync)
+    .mockReset()
+    .mockResolvedValue(
+      JSON.stringify({ 'screenshot.capture': { properties: { automation: { type: 'boolean' } } } })
+    );
   stopSessionPreview.mockResolvedValue(undefined);
   jest.mocked(startDeviceRunSessionPreview).mockReturnValue({ stopAsync: stopSessionPreview });
   jest.mocked(ensureFfmpegInstalledOnceAsync).mockResolvedValue(undefined);
@@ -1115,6 +1127,26 @@ it.each([
   await host.finishAsync();
 });
 
+it.each([
+  ['the turtle-v2 copy by default', undefined, 'https://storage.googleapis.com/turtle-v2/scrcpy'],
+  ['the step env value when it is set', 'https://mirror.test/scrcpy', 'https://mirror.test/scrcpy'],
+])(
+  'points expo-device-hub at %s for the scrcpy server',
+  async (_description, override, expected) => {
+    const host = await startDeviceSessionHostAsync(ctx, {
+      preview: { baseDomain, authtoken },
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: override ? { ...env, SERVE_EMU_SCRCPY_BASE_URL: override } : env,
+      logger,
+      separateLogPhase: true,
+      timeoutMs: 10_000,
+    });
+    const options = jest.mocked(spawnDetached).mock.calls[0][0];
+    expect(options.env.SERVE_EMU_SCRCPY_BASE_URL).toBe(expected);
+    await host.finishAsync();
+  }
+);
+
 it('lets the session add frame ancestors and CORS origins after the website origins', async () => {
   const host = await startDeviceSessionHostAsync(ctx, {
     preview: { baseDomain, authtoken },
@@ -1478,6 +1510,119 @@ it.each([BuildRuntimePlatform.LINUX, BuildRuntimePlatform.DARWIN])(
   }
 );
 
+it.each(['missing automation', 'invalid catalog', 'unavailable catalog'])(
+  'skips automated thumbnails with %s without stopping the iOS session',
+  async failure => {
+    if (failure === 'unavailable catalog') {
+      jest
+        .mocked(runServeSimActionWithResultAsync)
+        .mockRejectedValueOnce(new Error('unknown action'));
+    } else {
+      jest
+        .mocked(runServeSimActionWithResultAsync)
+        .mockResolvedValueOnce(
+          failure === 'invalid catalog'
+            ? 'invalid JSON'
+            : JSON.stringify({ 'screenshot.capture': { properties: {} } })
+        );
+    }
+    const host = await startDeviceSessionHostAsync(ctx, {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env,
+      logger,
+      timeoutMs: 10_000,
+      preview: { baseDomain, authtoken },
+    });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(runServeSimActionWithResultAsync).toHaveBeenCalledTimes(1);
+    expect(startDeviceRunSessionPreview).not.toHaveBeenCalled();
+    expect(ensureMacosPreviewEncoderInstalledAsync).not.toHaveBeenCalled();
+    expect(stopServer).not.toHaveBeenCalled();
+    await host.finishAsync();
+  }
+);
+
+it('cancels catalog inspection during shutdown without sending a thumbnail capture', async () => {
+  let inspectionSignal: AbortSignal | undefined;
+  jest.mocked(runServeSimActionWithResultAsync).mockImplementationOnce(async ({ signal }) => {
+    inspectionSignal = signal;
+    return await new Promise<string>((_resolve, reject) => {
+      signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+  });
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.DARWIN,
+    env,
+    logger,
+    timeoutMs: 10_000,
+    preview: { baseDomain, authtoken },
+  });
+  expect(inspectionSignal?.aborted).toBe(false);
+  await host.finishAsync();
+  expect(inspectionSignal?.aborted).toBe(true);
+  expect(startDeviceRunSessionPreview).not.toHaveBeenCalled();
+  expect(ensureMacosPreviewEncoderInstalledAsync).not.toHaveBeenCalled();
+  expect(stopServer).toHaveBeenCalledTimes(1);
+});
+
+it('finishes manual screenshots even when thumbnail cleanup fails', async () => {
+  const finishScreenshots = jest.fn().mockResolvedValue(undefined);
+  const collector = jest
+    .spyOn(screenshotCollector, 'startDeviceRunSessionScreenshotsAsync')
+    .mockResolvedValueOnce({
+      directory: '/tmp/manual-screenshots',
+      finishAsync: finishScreenshots,
+    });
+  const cleanup = jest.fn().mockRejectedValue(new Error('unlink refused'));
+  const factory = jest.spyOn(previewCapture, 'createServeSimPreviewCapture').mockReturnValueOnce({
+    isSupportedAsync: jest.fn().mockResolvedValue(true),
+    captureAsync: jest.fn(),
+    cleanupAfterHostStoppedAsync: cleanup,
+  });
+  try {
+    const host = await startDeviceSessionHostAsync(ctx, {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env,
+      logger,
+      timeoutMs: 10_000,
+      preview: { baseDomain, authtoken },
+    });
+    await new Promise(resolve => setImmediate(resolve));
+    await host.finishAsync();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(finishScreenshots).toHaveBeenCalledWith(true);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      'Could not remove session preview capture files.'
+    );
+  } finally {
+    factory.mockRestore();
+    collector.mockRestore();
+  }
+});
+
+it('drains thumbnail capture before stopping the iOS host', async () => {
+  const stopped = deferred<void>();
+  stopSessionPreview.mockReturnValueOnce(stopped.promise);
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.DARWIN,
+    env,
+    logger,
+    timeoutMs: 10_000,
+    preview: { baseDomain, authtoken },
+  });
+  await new Promise(resolve => setImmediate(resolve));
+  const finishing = host.finishAsync();
+  try {
+    await new Promise(resolve => setImmediate(resolve));
+    expect(stopServer).not.toHaveBeenCalled();
+  } finally {
+    stopped.resolve();
+    await finishing;
+  }
+  expect(stopServer).toHaveBeenCalledTimes(1);
+});
+
 it.each(['success', 'failure'])(
   'keeps macOS readiness nonblocking and drains encoder setup %s before ending the phase',
   async result => {
@@ -2193,6 +2338,58 @@ it.each([false, true])(
   }
 );
 
+it.each([
+  ['0.13.3', '@expo/[email protected]'],
+  [undefined, '@expo/serve-sim@latest'],
+])(
+  'uses the warm serve-sim version %s for adoption and recordings',
+  async (serveSimVersion, spec) => {
+    jest
+      .mocked(readServeSimServersAsync)
+      .mockResolvedValue([
+        { udid: 'emulator-5554', token: 'preview-token', url: 'http://127.0.0.1:3200' },
+      ]);
+    const recording = jest.spyOn(IosSimulatorRecordingUtils, 'useServeSimPackage');
+    const startAsync = jest.fn(async () => ({
+      pid: undefined,
+      getOutput: () => '',
+      getExitError: () => undefined,
+      stopAsync: stopServer,
+    }));
+    const host = await startDeviceSessionHostAsync(
+      ctx,
+      {
+        preview: { baseDomain, authtoken },
+        runtimePlatform: BuildRuntimePlatform.DARWIN,
+        env: { ...env, EAS_OVERRIDE_PACKAGE_MANAGER: 'bun' },
+        logger,
+        iosSimulatorUdid: 'emulator-5554',
+        timeoutMs: 1000,
+      },
+      {
+        port: 3200,
+        serveSimVersion,
+        turnArgs: Promise.resolve([]),
+        requiresPreviewRetirement: true,
+        startAsync,
+        stopAsync: stopServer,
+      }
+    );
+    try {
+      expect(startAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: 'bun',
+          args: expect.arrayContaining(['x', spec]),
+        })
+      );
+      expect(recording).toHaveBeenCalledWith(spec);
+    } finally {
+      await host.finishAsync();
+      recording.mockRestore();
+    }
+  }
+);
+
 it('opens the preview while a supplied server waits for TURN and its startup handshake', async () => {
   const turn = deferred<string[]>();
   const handshake = deferred<Awaited<ReturnType<typeof spawnDetached>>>();

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

@@ -1,120 +0,0 @@
-import { type Client, CombinedError } from '@urql/core';
-
-import { LegacySandboxApi } from '../legacySandboxApi';
-import { WorkerApiError } from '../workerApi';
-
-const ARTIFACT_ID = '0199c0de-7b3a-7c1e-8f00-1234567890ab';
-
-describe(LegacySandboxApi, () => {
-  let mutation: jest.Mock;
-  let api: LegacySandboxApi;
-
-  beforeEach(() => {
-    mutation = jest.fn();
-    api = new LegacySandboxApi({ mutation } as unknown as Client, 'sandbox-id');
-  });
-
-  function mockMutationResults(...results: unknown[]): void {
-    for (const result of results) {
-      mutation.mockReturnValueOnce({ toPromise: async () => result });
-    }
-  }
-
-  it('marks the sandbox ready and rethrows a GraphQL error', async () => {
-    const error = new CombinedError({ graphQLErrors: ['Sandbox has stopped.'] });
-    mockMutationResults({ data: {} }, { error });
-
-    await api.markReadyAsync();
-    await expect(api.markReadyAsync()).rejects.toBe(error);
-
-    expect(mutation).toHaveBeenCalledWith(
-      expect.anything(),
-      { sandboxId: 'sandbox-id' },
-      undefined
-    );
-  });
-
-  it('creates an upload session for the sandbox', async () => {
-    mockMutationResults({
-      data: {
-        sandbox: {
-          createArtifactUploadSession: {
-            artifact: { id: ARTIFACT_ID },
-            uploadSession: { url: 'https://uploads.expo.test/artifact', headers: { A: '1' } },
-          },
-        },
-      },
-    });
-
-    await expect(
-      api.createArtifactUploadSessionAsync({ name: 'Crash log', filename: 'crash.log', size: 5 })
-    ).resolves.toEqual({
-      artifact: { id: ARTIFACT_ID },
-      uploadSession: { url: 'https://uploads.expo.test/artifact', headers: { A: '1' } },
-    });
-    expect(mutation).toHaveBeenCalledWith(
-      expect.anything(),
-      { sandboxId: 'sandbox-id', input: { name: 'Crash log', filename: 'crash.log', size: 5 } },
-      expect.anything()
-    );
-  });
-
-  it.each([
-    { codes: ['VALIDATION_ERROR'], code: 'VALIDATION_ERROR' },
-    { codes: ['VALIDATION_ERROR', 'UNEXPECTED_ERROR'], code: undefined },
-  ])(
-    'reports upload session errors with codes $codes as a worker API error with code $code',
-    async ({ codes, code }) => {
-      mockMutationResults({
-        error: new CombinedError({
-          graphQLErrors: codes.map((errorCode, index) => ({
-            message: `Error ${index}.`,
-            extensions: { errorCode },
-          })),
-        }),
-      });
-
-      const error = await api
-        .createArtifactUploadSessionAsync({ name: 'Crash log', filename: 'crash.log', size: 5 })
-        .catch(err => err);
-
-      expect(error).toBeInstanceOf(WorkerApiError);
-      expect(error.code).toBe(code);
-      expect(error.message).toBe(codes.map((_, index) => `Error ${index}.`).join('\n'));
-    }
-  );
-
-  it('retries finalize after a server error and throws a failure that persists', async () => {
-    const persistent = new CombinedError({
-      graphQLErrors: ['Sandbox artifact "Crash log" has no uploaded file.'],
-      response: { status: 200 },
-    });
-    mockMutationResults(
-      {
-        error: new CombinedError({
-          networkError: new Error('Bad Gateway'),
-          response: { status: 502 },
-        }),
-      },
-      { error: persistent }
-    );
-
-    await expect(api.finalizeArtifactAsync(ARTIFACT_ID)).rejects.toBe(persistent);
-    expect(mutation).toHaveBeenCalledTimes(2);
-    expect(mutation).toHaveBeenLastCalledWith(
-      expect.anything(),
-      { artifactId: ARTIFACT_ID },
-      expect.anything()
-    );
-  });
-
-  it('rejects a finalized artifact without a download URL', async () => {
-    mockMutationResults({
-      data: { sandbox: { finalizeArtifact: { id: ARTIFACT_ID, downloadUrl: null } } },
-    });
-
-    await expect(api.finalizeArtifactAsync(ARTIFACT_ID)).rejects.toThrow(
-      `Finalized sandbox artifact ${ARTIFACT_ID} has no download URL.`
-    );
-  });
-});

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

@@ -54,6 +54,23 @@ it('downloads the driver-matched Simulator runner and retains its XCTest framewo
   ).toBe(true);
 });
 
+it('uses the runner of a prepared Appium home without a download', async () => {
+  await fs.promises.mkdir(runner, { recursive: true });
+  await expect(preparePreinstalledWdaAsync({ ...options, prepared: true })).resolves.toEqual({
+    'appium:usePreinstalledWDA': true,
+    'appium:prebuiltWDAPath': runner,
+  });
+  await expect(
+    preparePreinstalledWdaAsync({
+      ...options,
+      prepared: true,
+      runtimeIdentifier: 'com.apple.CoreSimulator.SimRuntime.iOS-16-4',
+    })
+  ).resolves.toEqual({});
+  expect(spawn).not.toHaveBeenCalled();
+  expect(fs.existsSync(runner)).toBe(true);
+});
+
 it.each([
   undefined,
   'com.apple.CoreSimulator.SimRuntime.iOS-16-4',

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

@@ -23,7 +23,6 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { inspect } from 'node:util';
 
 import { SandboxArtifactUploadManager, startSandboxArtifactUploadAsync } from '../sandboxArtifacts';
-import { type LegacySandboxApi } from '../legacySandboxApi';
 import { type SandboxWorkerApi } from '../sandboxWorkerApi';
 import { WorkerApiError } from '../workerApi';
 
@@ -66,7 +65,7 @@ describe('sandbox artifact uploads', () => {
     logger = { info: jest.fn(), error: jest.fn() };
     uploadArtifactAsync = async options =>
       await startSandboxArtifactUploadAsync({
-        workerApi: workerApi as unknown as SandboxWorkerApi | LegacySandboxApi,
+        workerApi: workerApi as unknown as SandboxWorkerApi,
         logger: logger as unknown as bunyan,
         ...options,
       });
@@ -390,7 +389,7 @@ describe('sandbox artifact uploads', () => {
 
   function createManager(signal: AbortSignal): SandboxArtifactUploadManager {
     return new SandboxArtifactUploadManager({
-      workerApi: workerApi as unknown as SandboxWorkerApi | LegacySandboxApi,
+      workerApi: workerApi as unknown as SandboxWorkerApi,
       logger: logger as unknown as bunyan,
       signal,
     });

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

@@ -6,7 +6,6 @@ import WebSocket, { WebSocketServer } from 'ws';
 
 import * as sandboxCommandImplementations from '../sandboxCommandImplementations';
 import { startSandboxDaemonAsync } from '../sandboxDaemon';
-import { type LegacySandboxApi } from '../legacySandboxApi';
 import { type SandboxWorkerApi } from '../sandboxWorkerApi';
 
 jest.unmock('@expo/logger');
@@ -17,7 +16,7 @@ jest.unmock('node:fs/promises');
 
 describe(startSandboxDaemonAsync.name, () => {
   const logger = Log.child({ buildStepId: 'sandbox-test' });
-  const workerApi = {} as SandboxWorkerApi | LegacySandboxApi;
+  const workerApi = {} as SandboxWorkerApi;
   it.each(['ftp://localhost', 'not a URL'])('reports invalid server URL %s', async serverUrl => {
     const errorLog = jest.spyOn(logger, 'error').mockImplementation(() => {});
     const daemon = await startSandboxDaemonAsync({

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

@@ -18,7 +18,6 @@ import {
   type SandboxDaemonCommandImplementations,
   createSandboxCommandImplementations,
 } from '../sandboxCommandImplementations';
-import { type LegacySandboxApi } from '../legacySandboxApi';
 import { type SandboxWorkerApi } from '../sandboxWorkerApi';
 
 const READ_FILE_LIMITS = { maxTextBytes: 40_000, maxImageBytes: 3_000_000 };
@@ -50,7 +49,7 @@ describe('sandbox daemon commands', () => {
       workingDirectory,
       env: process.env,
       signal: controller.signal,
-      workerApi: workerApi as unknown as SandboxWorkerApi | LegacySandboxApi,
+      workerApi: workerApi as unknown as SandboxWorkerApi,
       logger,
     });
     commandImplementations = commands.commandImplementations;
@@ -79,7 +78,7 @@ describe('sandbox daemon commands', () => {
       workingDirectory,
       env: process.env,
       signal: controller.signal,
-      workerApi: workerApi as unknown as SandboxWorkerApi | LegacySandboxApi,
+      workerApi: workerApi as unknown as SandboxWorkerApi,
       logger,
     });
     const command = commands.commandImplementations.execCommand({ cmd: 'printf should-not-run' });

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

@@ -16,7 +16,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { WebSocketServer } from 'ws';
 
-import { runServeSimActionAsync, stageServeSimAppAsync } from '../serveSimActions';
+import {
+  runServeSimActionAsync,
+  runServeSimActionWithResultAsync,
+  stageServeSimAppAsync,
+} from '../serveSimActions';
 
 jest.unmock('fs');
 jest.unmock('node:fs');
@@ -67,6 +71,18 @@ it('authenticates the upgrade, waits for ready, and sends the action once', asyn
   expect(actions).toEqual([{ id: 1, action: 'app.install', params: request().params }]);
 });
 
+it('returns stdout from an authenticated action for catalog inspection', async () => {
+  server.on('connection', socket => {
+    socket.on('message', () =>
+      socket.send(JSON.stringify({ id: 1, stdout: '{"actions":[]}', exitCode: 0 }))
+    );
+    socket.send(JSON.stringify({ ready: true }));
+  });
+  await expect(
+    runServeSimActionWithResultAsync({ ...request(), action: 'actions.describe', params: {} })
+  ).resolves.toBe('{"actions":[]}');
+});
+
 it.each([
   [{ id: 1, exitCode: 1, stderr: 'install refused' }, 'install refused'],
   [{ id: 1, error: 'unknown action app.install' }, 'unknown action'],
@@ -137,6 +153,55 @@ it('aborts an in-flight action without resending it', async () => {
   expect(attempts).toBe(1);
 });
 
+it('cancels before dispatch while waiting for ready in drain mode', async () => {
+  const controller = new AbortController();
+  const actions = jest.fn();
+  server.on('connection', socket => {
+    socket.on('message', actions);
+    controller.abort(new Error('stopped before ready'));
+    socket.send(JSON.stringify({ ready: true }));
+  });
+  await expect(
+    runServeSimActionAsync({
+      ...request(),
+      signal: controller.signal,
+      drainAfterDispatch: true,
+    })
+  ).rejects.toThrow('stopped before ready');
+  expect(actions).not.toHaveBeenCalled();
+});
+
+it('drains dispatched actions after cancellation in drain mode', async () => {
+  const controller = new AbortController();
+  let reply!: () => void;
+  let dispatched!: () => void;
+  const ready = new Promise<void>(resolve => {
+    dispatched = resolve;
+  });
+  server.on('connection', socket => {
+    socket.send(JSON.stringify({ ready: true }));
+    socket.on('message', () => {
+      reply = () => socket.send(JSON.stringify({ id: 1, stdout: 'completed', exitCode: 0 }));
+      dispatched();
+    });
+  });
+  let settled = false;
+  const action = runServeSimActionAsync({
+    ...request(),
+    signal: controller.signal,
+    drainAfterDispatch: true,
+  });
+  void action.finally(() => {
+    settled = true;
+  });
+  await ready;
+  controller.abort(new Error('stopped after dispatch'));
+  await new Promise(resolve => setImmediate(resolve));
+  expect(settled).toBe(false);
+  reply();
+  await expect(action).resolves.toBeUndefined();
+});
+
 it('does not connect when already aborted', async () => {
   const connected = jest.fn();
   server.on('connection', connected);

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

@@ -22,29 +22,17 @@ it('uploads NDJSON with explicit user-app scope', async () => {
       kind: 'simulator-log',
       filename: 'app-logs.ndjson',
       size: 11,
+      attempts: 1,
       metadata: expect.objectContaining({ scope: 'user-apps', udid: 'A' }),
     })
   );
 });
 
-it('skips empty and missing files', async () => {
-  await uploadServeSimLogsFileAsync(ctx, args);
-  await writeFile(filePath, '');
-  await uploadServeSimLogsFileAsync(ctx, args);
-  expect(uploadDeviceRunSessionArtifactAsync).not.toHaveBeenCalled();
-});
-
-it('aborts the upload on a file read error without an unhandled error', async () => {
+it('warns and resolves when the upload fails', async () => {
   await writeFile(filePath, '{}\n');
   jest
     .mocked(uploadDeviceRunSessionArtifactAsync)
-    .mockImplementationOnce(async (_ctx, { openStream, signal }) => {
-      const aborted = new Promise<void>((_resolve, reject) => {
-        signal!.addEventListener('abort', () => reject(signal!.reason), { once: true });
-      });
-      openStream().destroy(new Error('read failure'));
-      await aborted;
-    });
+    .mockRejectedValueOnce(new Error('storage unavailable'));
   await expect(uploadServeSimLogsFileAsync(ctx, args)).resolves.toBeUndefined();
   expect(logger.warn).toHaveBeenCalledWith(
     expect.objectContaining({ err: expect.any(Error) }),

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

@@ -0,0 +1,153 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { runServeSimActionAsync, runServeSimActionWithResultAsync } from '../serveSimActions';
+import { createServeSimPreviewCapture } from '../serveSimPreviewCapture';
+
+jest.mock('../serveSimActions');
+
+const signal = new AbortController().signal;
+const tmpdir = path.join(os.tmpdir(), 'host-tmp');
+const staging = path.join(tmpdir, 'serve-sim-screenshots');
+const destination = path.join(os.tmpdir(), 'screen.png');
+const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0xff, 0x00]);
+const options = { port: 1234, token: 'host-token', device: 'selected-udid', tmpdir };
+
+beforeEach(async () => {
+  await mkdir(staging, { recursive: true });
+  jest.mocked(runServeSimActionAsync).mockReset();
+});
+
+it('captures the selected active display and removes only its own staging', async () => {
+  await writeFile(path.join(staging, 'unrelated.png'), 'keep');
+  jest.mocked(runServeSimActionAsync).mockImplementation(async request => {
+    expect(request).toEqual({
+      port: 1234,
+      token: 'host-token',
+      action: 'screenshot.capture',
+      params: {
+        udid: 'selected-udid',
+        fileName: expect.stringMatching(/^serve-sim-screenshot-preview-.*\.png$/),
+        automation: true,
+      },
+      timeoutMs: 30_000,
+      signal,
+      drainAfterDispatch: true,
+    });
+    await writeFile(path.join(staging, request.params.fileName as string), png);
+    return;
+  });
+  const capture = createServeSimPreviewCapture(options);
+  await capture.captureAsync(destination, signal);
+  expect(await readFile(destination)).toEqual(png);
+  expect(await readdir(staging)).toEqual(['unrelated.png']);
+});
+
+it('drains an already sent action before honoring abort and deleting its output', async () => {
+  const controller = new AbortController();
+  let complete!: () => void;
+  const pending = new Promise<void>(resolve => {
+    complete = resolve;
+  });
+  let staged!: string;
+  jest.mocked(runServeSimActionAsync).mockImplementation(async request => {
+    staged = path.join(staging, request.params.fileName as string);
+    await pending;
+    await writeFile(staged, png);
+    return;
+  });
+  const capture = createServeSimPreviewCapture(options);
+  let settled = false;
+  const capturing = capture.captureAsync(destination, controller.signal);
+  void capturing.then(
+    () => {
+      settled = true;
+    },
+    () => {
+      settled = true;
+    }
+  );
+  controller.abort(new Error('session stopped'));
+  await Promise.resolve();
+  expect(settled).toBe(false);
+  complete();
+  await expect(capturing).rejects.toThrow('session stopped');
+  expect(await readdir(staging)).toEqual([]);
+});
+
+it.each(['timed out', 'connection closed'])(
+  'keeps a possibly writable file after %s until the host stops',
+  async message => {
+    let staged!: string;
+    jest.mocked(runServeSimActionAsync).mockImplementation(async request => {
+      staged = path.join(staging, request.params.fileName as string);
+      await writeFile(staged, 'reservation');
+      throw new Error(message);
+    });
+    const capture = createServeSimPreviewCapture(options);
+    await expect(capture.captureAsync(destination, signal)).rejects.toThrow(message);
+    expect(await readFile(staged, 'utf8')).toBe('reservation');
+    // The server may still write after the client's deadline or disconnect.
+    await writeFile(staged, png);
+    await capture.cleanupAfterHostStoppedAsync();
+    expect(await readdir(staging)).toEqual([]);
+  }
+);
+
+it('attempts every owned cleanup when one file cannot be removed', async () => {
+  let blocked!: string;
+  let count = 0;
+  jest.mocked(runServeSimActionAsync).mockImplementation(async request => {
+    const staged = path.join(staging, request.params.fileName as string);
+    if (count++ === 0) {
+      blocked = staged;
+      await mkdir(staged);
+    } else {
+      await writeFile(staged, png);
+    }
+    throw new Error('capture disconnected');
+  });
+  const capture = createServeSimPreviewCapture(options);
+  await expect(capture.captureAsync(destination, signal)).rejects.toThrow('disconnected');
+  await expect(capture.captureAsync(destination, signal)).rejects.toThrow('disconnected');
+  await expect(capture.cleanupAfterHostStoppedAsync()).rejects.toThrow(
+    'Could not remove preview captures'
+  );
+  expect(await readdir(staging)).toEqual([path.basename(blocked)]);
+});
+
+it('does not send a capture when already aborted', async () => {
+  const capture = createServeSimPreviewCapture(options);
+  await expect(
+    capture.captureAsync(destination, AbortSignal.abort(new Error('stopped')))
+  ).rejects.toThrow('stopped');
+  expect(runServeSimActionAsync).not.toHaveBeenCalled();
+});
+
+it.each([
+  [
+    { 'screenshot.capture': { properties: { automation: { type: 'boolean', default: false } } } },
+    true,
+  ],
+  [{ 'screenshot.capture': { properties: {} } }, false],
+  [{ 'screenshot.capture': { properties: { automation: { type: 'string' } } } }, false],
+  [{}, false],
+  [null, false],
+])(
+  'checks the catalog automation field before enabling captures (%j)',
+  async (catalog, supported) => {
+    jest.mocked(runServeSimActionWithResultAsync).mockResolvedValueOnce(JSON.stringify(catalog));
+    const capture = createServeSimPreviewCapture(options);
+    await expect(capture.isSupportedAsync(signal)).resolves.toBe(supported);
+    expect(runServeSimActionWithResultAsync).toHaveBeenCalledWith({
+      port: options.port,
+      token: options.token,
+      action: 'actions.describe',
+      params: {},
+      timeoutMs: 30_000,
+      signal,
+    });
+    expect(runServeSimActionAsync).not.toHaveBeenCalled();
+  }
+);

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

@@ -0,0 +1,79 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { type CustomBuildContext } from '../../../customBuildContext';
+import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
+import { uploadDeviceRunSessionFileAsync } from '../uploadDeviceRunSessionFile';
+
+jest.mock('../deviceRunSessionArtifacts');
+jest.unmock('fs');
+jest.unmock('node:fs');
+jest.unmock('fs/promises');
+jest.unmock('node:fs/promises');
+
+const ctx = {} as CustomBuildContext;
+const upload = jest.mocked(uploadDeviceRunSessionArtifactAsync);
+const describeFile = (size: number) => ({
+  deviceRunSessionId: 'session',
+  artifactId: 'log',
+  name: `log (${size} bytes)`,
+  filename: 'log.txt',
+  kind: 'simulator-log',
+});
+let directory: string;
+let filePath: string;
+
+beforeEach(async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'device-run-session-file-'));
+  filePath = path.join(directory, 'log.txt');
+});
+
+afterEach(async () => {
+  await rm(directory, { recursive: true, force: true });
+});
+
+function uploadFile(options: { signal?: AbortSignal; attempts?: number } = {}): Promise<boolean> {
+  return uploadDeviceRunSessionFileAsync(ctx, { filePath, describe: describeFile, ...options });
+}
+
+it('skips an empty file without uploading', async () => {
+  await writeFile(filePath, '');
+  expect(await uploadFile()).toBe(false);
+  expect(upload).not.toHaveBeenCalled();
+});
+
+it('rejects a missing file before uploading', async () => {
+  await expect(uploadFile()).rejects.toMatchObject({ code: 'ENOENT' });
+  expect(upload).not.toHaveBeenCalled();
+});
+
+it('describes the file by its size and forwards attempts and the caller signal', async () => {
+  await writeFile(filePath, 'abc');
+  const controller = new AbortController();
+  expect(await uploadFile({ signal: controller.signal, attempts: 2 })).toBe(true);
+  expect(upload).toHaveBeenCalledWith(
+    ctx,
+    expect.objectContaining({ name: 'log (3 bytes)', size: 3, attempts: 2, filename: 'log.txt' })
+  );
+  const { signal } = upload.mock.calls[0][1];
+  const reason = new Error('stop');
+  controller.abort(reason);
+  expect(signal?.reason).toBe(reason);
+});
+
+it('aborts the upload on a file read error and ignores an aborted request body', async () => {
+  await writeFile(filePath, '{}\n');
+  const readError = Object.assign(new Error('read failed'), { code: 'EIO' });
+  upload.mockImplementationOnce(async (_ctx, { openStream, signal }) => {
+    const aborted = openStream();
+    aborted.destroy(Object.assign(new Error('request body aborted'), { name: 'AbortError' }));
+    await new Promise<void>(resolve => aborted.once('close', resolve));
+    expect(signal?.aborted).toBe(false);
+    const failed = openStream();
+    failed.destroy(readError);
+    await new Promise<void>(resolve => failed.once('close', resolve));
+    expect(signal?.reason).toBe(readError);
+  });
+  expect(await uploadFile()).toBe(true);
+});

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

@@ -2,6 +2,8 @@ import { type bunyan } from '@expo/logger';
 import spawn from '@expo/turtle-spawn';
 
 import { type CustomBuildContext } from '../../../customBuildContext';
+import { resolveSimulatorPackageVersionAsync } from '../../../utils/simulatorPackageVersion';
+import { stopWarmSimulatorAsync } from '../../../utils/warmSimulator';
 import { IosSimulatorRecordingUtils } from '../IosSimulatorRecordingUtils';
 import { fetchWebPreviewTurnArgsAsync } from '../remoteDeviceRunSession';
 import {
@@ -12,6 +14,8 @@ import {
 import { type WarmIosSession, tryClaimWarmIosSessionAsync } from '../warmIosSession';
 
 jest.mock('@expo/turtle-spawn');
+jest.mock('../../../utils/simulatorPackageVersion');
+jest.mock('../../../utils/warmSimulator');
 jest.mock('../IosSimulatorRecordingUtils');
 jest.mock('../warmIosSession');
 jest.mock('../remoteDeviceRunSession', () => ({
@@ -63,9 +67,11 @@ beforeEach(() => {
 });
 
 it('adopts the warm device on the warm port with its recording, then prepares tools', async () => {
+  warm.serveSimVersion = '0.13.3';
   const server = createWarmDeviceSessionServer(ctx, logger, warm);
   expect(server).toMatchObject({
     port: 3200,
+    serveSimVersion: '0.13.3',
     requiresPreviewRetirement: true,
     preinstalledApp: warm.preinstalledExpoGo,
   });
@@ -125,7 +131,7 @@ describe(runOnWarmIosSimulatorAsync, () => {
     jest.mocked(tryClaimWarmIosSessionAsync).mockResolvedValue(undefined);
     const run = jest.fn().mockResolvedValue('cold');
     await expect(runOnWarmIosSimulatorAsync(claim, run)).resolves.toBe('cold');
-    expect(run).toHaveBeenCalledWith(undefined);
+    expect(run).toHaveBeenCalledWith(undefined, undefined);
   });
 
   it('runs on the claimed warm Simulator', async () => {
@@ -133,7 +139,7 @@ describe(runOnWarmIosSimulatorAsync, () => {
     const run = jest.fn().mockResolvedValue('warm');
     await expect(runOnWarmIosSimulatorAsync(claim, run)).resolves.toBe('warm');
     expect(run).toHaveBeenCalledTimes(1);
-    expect(run).toHaveBeenCalledWith(warm);
+    expect(run).toHaveBeenCalledWith(warm, undefined);
   });
 
   it('stops warmup and runs cold after an adoption failure', async () => {
@@ -144,7 +150,71 @@ describe(runOnWarmIosSimulatorAsync, () => {
       .mockResolvedValueOnce('cold');
     await expect(runOnWarmIosSimulatorAsync(claim, run)).resolves.toBe('cold');
     expect(warm.process.stopAsync).toHaveBeenCalledTimes(1);
-    expect(run).toHaveBeenLastCalledWith(undefined);
+    expect(run).toHaveBeenLastCalledWith(undefined, undefined);
+  });
+
+  it.each([true, false])(
+    'uses the resolved request for claim and setup (warm: %s)',
+    async reuse => {
+      jest.mocked(resolveSimulatorPackageVersionAsync).mockResolvedValue('0.14.0');
+      jest.mocked(tryClaimWarmIosSessionAsync).mockResolvedValue(reuse ? warm : undefined);
+      const request = { ...claim, env: { EAS_USE_WARM_SIMULATOR: '1' }, packageVersion: 'latest' };
+      const run = jest.fn().mockResolvedValue('done');
+      await expect(runOnWarmIosSimulatorAsync(request, run)).resolves.toBe('done');
+      expect(tryClaimWarmIosSessionAsync).toHaveBeenCalledWith({
+        ...request,
+        packageVersion: '0.14.0',
+      });
+      expect(run).toHaveBeenCalledWith(reuse ? warm : undefined, '0.14.0');
+    }
+  );
+
+  it('keeps the resolved version through an adoption failure', async () => {
+    jest.mocked(resolveSimulatorPackageVersionAsync).mockResolvedValue('0.14.0');
+    jest.mocked(tryClaimWarmIosSessionAsync).mockResolvedValue(warm);
+    const run = jest
+      .fn()
+      .mockRejectedValueOnce(new WarmSessionAdoptionError())
+      .mockResolvedValue('cold');
+    await runOnWarmIosSimulatorAsync(
+      { ...claim, env: { EAS_USE_WARM_SIMULATOR: '1' }, packageVersion: 'latest' },
+      run
+    );
+    expect(resolveSimulatorPackageVersionAsync).toHaveBeenCalledTimes(1);
+    expect(run.mock.calls).toEqual([
+      [warm, '0.14.0'],
+      [undefined, '0.14.0'],
+    ]);
+  });
+
+  it('stops warmup and fails when an explicit request cannot be resolved', async () => {
+    const error = new Error('lookup failed');
+    jest.mocked(resolveSimulatorPackageVersionAsync).mockRejectedValue(error);
+    const run = jest.fn();
+    await expect(
+      runOnWarmIosSimulatorAsync(
+        { ...claim, env: { EAS_USE_WARM_SIMULATOR: '1' }, packageVersion: 'latest' },
+        run
+      )
+    ).rejects.toBe(error);
+    expect(stopWarmSimulatorAsync).toHaveBeenCalledTimes(1);
+    expect(tryClaimWarmIosSessionAsync).not.toHaveBeenCalled();
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it('preserves lookup and cleanup failures without starting a session', async () => {
+    const lookup = new Error('lookup failed');
+    const cleanup = new Error('cleanup failed');
+    jest.mocked(resolveSimulatorPackageVersionAsync).mockRejectedValue(lookup);
+    jest.mocked(stopWarmSimulatorAsync).mockRejectedValue(cleanup);
+    const run = jest.fn();
+    await expect(
+      runOnWarmIosSimulatorAsync(
+        { ...claim, env: { EAS_USE_WARM_SIMULATOR: '1' }, packageVersion: 'latest' },
+        run
+      )
+    ).rejects.toMatchObject({ errors: [lookup, cleanup] });
+    expect(run).not.toHaveBeenCalled();
   });
 
   it('does not run cold after a failure during the session', async () => {

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

@@ -4,6 +4,7 @@ import path from 'node:path';
 
 import { runSimulatorLauncherAsync, stopWarmSimulatorAsync } from '../../../utils/warmSimulator';
 import { readLocalEgressHandoffAsync } from '../localEgress';
+import { runOnWarmIosSimulatorAsync } from '../warmDeviceSessionHost';
 import { tryClaimWarmIosSessionAsync } from '../warmIosSession';
 
 jest.mock('../../../utils/warmSimulator');
@@ -84,6 +85,24 @@ it('takes the preinstalled Expo Go that prepare-tools reports', async () => {
   expect(session!.preinstalledExpoGo).toEqual(expoGo);
 });
 
+it('keeps the exact serve-sim version from the launcher claim', async () => {
+  jest
+    .mocked(runSimulatorLauncherAsync)
+    .mockResolvedValueOnce(JSON.stringify({ ...claim, serveSimVersion: '0.13.3' }));
+  const session = await tryClaimWarmIosSessionAsync({ engine: 'serve-sim', env, logger });
+  expect(session?.serveSimVersion).toBe('0.13.3');
+});
+
+it('stops warmup when the claim contains an invalid serve-sim version', async () => {
+  jest
+    .mocked(runSimulatorLauncherAsync)
+    .mockResolvedValueOnce(JSON.stringify({ ...claim, serveSimVersion: 'latest' }));
+  await expect(
+    tryClaimWarmIosSessionAsync({ engine: 'serve-sim', env, logger })
+  ).resolves.toBeUndefined();
+  expect(stopWarmSimulatorAsync).toHaveBeenCalledTimes(1);
+});
+
 it('reads the agent-device server after tool preparation', async () => {
   jest
     .spyOn(fs, 'readFile')
@@ -121,7 +140,6 @@ it.each([
     {},
     () => jest.mocked(runSimulatorLauncherAsync).mockRejectedValue(new Error('no session')),
   ],
-  ['a pinned package version', { packageVersion: '1.2.3' }, () => {}],
   ['a job Simulator setting', { env: { ...env, SIMCTL_CHILD_FOO: '1' } }, () => {}],
   [
     'a local egress session',
@@ -149,3 +167,69 @@ it('stops the claimed session once', async () => {
   await Promise.all([session!.process.stopAsync(), session!.process.stopAsync()]);
   expect(stopWarmSimulatorAsync).toHaveBeenCalledTimes(1);
 });
+
+it.each([
+  ['serve-sim', 'serveSimVersion'],
+  ['agent-device', 'agentDeviceVersion'],
+  ['argent', 'argentVersion'],
+] as const)(
+  'reuses %s only when its recorded version matches the resolved request',
+  async (engine, field) => {
+    jest
+      .mocked(runSimulatorLauncherAsync)
+      .mockResolvedValue(JSON.stringify({ ...claim, [field]: '1.2.3' }));
+    await expect(
+      tryClaimWarmIosSessionAsync({ engine, packageVersion: '1.2.3', env, logger })
+    ).resolves.toBeDefined();
+    expect(stopWarmSimulatorAsync).not.toHaveBeenCalled();
+    await expect(
+      tryClaimWarmIosSessionAsync({ engine, packageVersion: '1.2.4', env, logger })
+    ).resolves.toBeUndefined();
+    expect(stopWarmSimulatorAsync).toHaveBeenCalledTimes(1);
+  }
+);
+
+it.each(['serve-sim', 'agent-device', 'argent'] as const)(
+  'uses normal setup for %s when older claims omit its version',
+  async engine => {
+    await expect(
+      tryClaimWarmIosSessionAsync({ engine, packageVersion: '1.2.3', env, logger })
+    ).resolves.toBeUndefined();
+    expect(stopWarmSimulatorAsync).toHaveBeenCalledTimes(1);
+  }
+);
+
+it('accepts a resolved prerelease pin for matching warm adoption', async () => {
+  jest
+    .mocked(runSimulatorLauncherAsync)
+    .mockResolvedValue(JSON.stringify({ ...claim, serveSimVersion: '0.13.4-beta.1+build.2' }));
+  await expect(
+    tryClaimWarmIosSessionAsync({
+      engine: 'serve-sim',
+      packageVersion: '0.13.4-beta.1+build.2',
+      env,
+      logger,
+    })
+  ).resolves.toMatchObject({ serveSimVersion: '0.13.4-beta.1+build.2' });
+  expect(stopWarmSimulatorAsync).not.toHaveBeenCalled();
+});
+
+it('preserves exact build metadata through job resolution and warm claim', async () => {
+  const version = '0.13.4-beta.1+build.2';
+  jest
+    .mocked(runSimulatorLauncherAsync)
+    .mockResolvedValueOnce(JSON.stringify({ ...claim, serveSimVersion: version }));
+  const run = jest.fn(async (session, resolvedVersion) => {
+    expect(session?.serveSimVersion).toBe(version);
+    expect(resolvedVersion).toBe(version);
+    return 'warm';
+  });
+  await expect(
+    runOnWarmIosSimulatorAsync(
+      { engine: 'serve-sim', packageVersion: `v${version}`, env, logger },
+      run
+    )
+  ).resolves.toBe('warm');
+  expect(run).toHaveBeenCalledTimes(1);
+  expect(stopWarmSimulatorAsync).not.toHaveBeenCalled();
+});

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

@@ -1,4 +1,4 @@
-import { SystemError } from '@expo/eas-build-job';
+import { SystemError, formatBytes } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
 import { createReadStream, createWriteStream } from 'node:fs';
 import { mkdtemp, rm, stat } from 'node:fs/promises';
@@ -11,8 +11,8 @@ import { z } from 'zod';
 
 import { CustomBuildContext } from '../../customBuildContext';
 import { Sentry } from '../../sentry';
-import { formatBytes } from '../../utils/artifacts';
 import { uploadDeviceRunSessionArtifactAsync } from './deviceRunSessionArtifacts';
+import { createScreenshotMetadataAsync } from './deviceRunSessionScreenshotMetadata';
 
 const AGENT_DEVICE_ARTIFACT_UPLOAD_POLL_INTERVAL_MS = 5_000;
 const AGENT_DEVICE_ARTIFACT_CLEANUP_TIMEOUT_MS = 30_000;
@@ -216,6 +216,17 @@ export async function uploadAgentDeviceArtifactAsync(
       signal,
     });
     const { size } = await stat(temporaryArtifactPath);
+    const display = artifact.displayRotation
+      ? { displayRotation: artifact.displayRotation }
+      : undefined;
+    const metadata =
+      artifact.artifactType === 'screenshot'
+        ? await createScreenshotMetadataAsync(temporaryArtifactPath, {
+            source: 'agent-device',
+            ...display,
+            logger,
+          })
+        : display;
     logger.info(`Uploading artifact ${artifact.filename} (${formatBytes(size)}).`);
     await uploadDeviceRunSessionArtifactAsync(ctx, {
       deviceRunSessionId,
@@ -223,9 +234,7 @@ export async function uploadAgentDeviceArtifactAsync(
       name: `${artifact.filename} (${artifact.id})`,
       filename: artifact.filename,
       kind: artifact.artifactType ?? undefined,
-      ...(artifact.displayRotation
-        ? { metadata: { displayRotation: artifact.displayRotation } }
-        : {}),
+      ...(metadata ? { metadata } : {}),
       size,
       openStream: () => createReadStream(temporaryArtifactPath),
       ...(signal ? { signal } : {}),

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

@@ -0,0 +1,144 @@
+import { formatBytes } from '@expo/eas-build-job';
+import { type bunyan } from '@expo/logger';
+import { type BuildStepGlobalContext } from '@expo/steps';
+import path from 'node:path';
+
+import { type CustomBuildContext } from '../../customBuildContext';
+import {
+  type AndroidEmulatorLogCapture,
+  AndroidEmulatorLogRing,
+  type FinalizedAndroidEmulatorLog,
+} from '../../utils/androidEmulatorLogCapture';
+import { AndroidEmulatorLogFiles } from '../../utils/androidEmulatorLogFiles';
+import { type AndroidEmulatorLogSource } from '../../utils/androidEmulatorLogSources';
+import { uploadDeviceRunSessionFileAsync } from './uploadDeviceRunSessionFile';
+
+const UPLOAD_TIMEOUT_MS = 30_000;
+const LOG_SOURCE_DETAILS = {
+  'emulator-output': { name: 'Emulator output', scope: 'emulator-process' },
+  'device-logcat': { name: 'Android device logcat', scope: 'device' },
+} satisfies Record<AndroidEmulatorLogSource, { name: string; scope: string }>;
+
+type Collection = {
+  capture: AndroidEmulatorLogCapture;
+  upload?: Promise<void>;
+};
+
+// A worker can execute more than one job; each workflow owns its capture and uploads.
+const collections = new WeakMap<BuildStepGlobalContext, Collection>();
+
+/** The first launch of a workflow fixes its source selection; later calls reuse the capture. */
+export function getAndroidEmulatorLogCapture(
+  global: BuildStepGlobalContext,
+  env: NodeJS.ProcessEnv,
+  sources: readonly AndroidEmulatorLogSource[]
+): AndroidEmulatorLogCapture {
+  let collection = collections.get(global);
+  if (!collection) {
+    collection = {
+      // Sessions upload a bounded ring per source; builds keep plain launch files.
+      capture: env.DEVICE_RUN_SESSION_ID
+        ? new AndroidEmulatorLogRing({ sources })
+        : new AndroidEmulatorLogFiles({ sources }),
+    };
+    collections.set(global, collection);
+  }
+  return collection.capture;
+}
+
+export async function collectAndroidEmulatorLogsAsync(
+  ctx: CustomBuildContext,
+  {
+    global,
+    deviceRunSessionId,
+    logger,
+  }: {
+    global: BuildStepGlobalContext;
+    deviceRunSessionId: string;
+    logger: bunyan;
+  }
+): Promise<void> {
+  const collection = collections.get(global);
+  if (!collection) {
+    logger.info('No Android emulator logs captured; skipping upload.');
+    return;
+  }
+  // Generated session workflows collect once. Repeated calls share that finalization/upload.
+  collection.upload ??= uploadCapturedLogsAsync(ctx, {
+    collection,
+    deviceRunSessionId,
+    logger,
+  });
+  await collection.upload;
+}
+
+async function uploadCapturedLogsAsync(
+  ctx: CustomBuildContext,
+  {
+    collection,
+    deviceRunSessionId,
+    logger,
+  }: {
+    collection: Collection;
+    deviceRunSessionId: string;
+    logger: bunyan;
+  }
+): Promise<void> {
+  const logs = await collection.capture.finishAsync();
+  for (const log of logs) {
+    const filename = path.basename(log.filePath);
+    try {
+      const uploaded = await uploadLogAsync(ctx, {
+        deviceRunSessionId,
+        log,
+        signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+      });
+      if (uploaded) {
+        logger.info(`Uploaded Android diagnostic log ${filename}.`);
+      }
+    } catch (err) {
+      logger.warn({ err }, `Could not upload Android log ${filename}; other logs will continue.`);
+    }
+  }
+}
+
+async function uploadLogAsync(
+  ctx: CustomBuildContext,
+  {
+    deviceRunSessionId,
+    log: { filePath, source, bytesSeen },
+    signal,
+  }: {
+    deviceRunSessionId: string;
+    log: FinalizedAndroidEmulatorLog;
+    signal: AbortSignal;
+  }
+): Promise<boolean> {
+  const filename = path.basename(filePath);
+  return await uploadDeviceRunSessionFileAsync(ctx, {
+    filePath,
+    describe: size => {
+      const truncationNote =
+        size < bytesSeen ? `; truncated, last ${formatBytes(size)} retained` : '';
+      return {
+        deviceRunSessionId,
+        artifactId: filename,
+        name: `${LOG_SOURCE_DETAILS[source].name} (${filename}${truncationNote})`,
+        filename,
+        kind: 'simulator-log',
+        metadata: {
+          __eas_type: 'simulator-log',
+          platform: 'android',
+          source,
+          scope: LOG_SOURCE_DETAILS[source].scope,
+          originalSizeBytes: bytesSeen,
+          // The capture keeps the newest bytes, so the omitted bytes are the head.
+          omittedBytes: bytesSeen - size,
+          truncated: size < bytesSeen,
+        },
+      };
+    },
+    signal,
+    attempts: 2,
+  });
+}

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

@@ -1,4 +1,4 @@
-import { SystemError } from '@expo/eas-build-job';
+import { SystemError, formatBytes } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
 import { createReadStream, createWriteStream } from 'node:fs';
 import { mkdtemp, rm, stat } from 'node:fs/promises';
@@ -11,8 +11,8 @@ import { z } from 'zod';
 
 import { CustomBuildContext } from '../../customBuildContext';
 import { Sentry } from '../../sentry';
-import { formatBytes } from '../../utils/artifacts';
 import { uploadDeviceRunSessionArtifactAsync } from './deviceRunSessionArtifacts';
+import { createScreenshotMetadataAsync } from './deviceRunSessionScreenshotMetadata';
 
 const ARGENT_ARTIFACT_UPLOAD_POLL_INTERVAL_MS = 5_000;
 const ARGENT_ARTIFACT_UPLOAD_CLEANUP_TIMEOUT_MS = 30_000;
@@ -208,13 +208,19 @@ export async function uploadArgentArtifactAsync(
       destinationPath: temporaryArtifactPath,
     });
     const { size } = await stat(temporaryArtifactPath);
+    const kind = getArgentArtifactKind(artifact);
+    const metadata =
+      (kind === 'screenshot' || kind === 'screenshot-diff') && !artifact.isDirectory
+        ? await createScreenshotMetadataAsync(temporaryArtifactPath, { source: 'argent', logger })
+        : undefined;
     logger.info(`Uploading artifact ${filename} (${formatBytes(size)}).`);
     await uploadDeviceRunSessionArtifactAsync(ctx, {
       deviceRunSessionId,
       artifactId: artifact.id,
       name: `${filename} (${artifact.id})`,
       filename,
-      kind: getArgentArtifactKind(artifact),
+      kind,
+      ...(metadata ? { metadata } : {}),
       size,
       openStream: () => createReadStream(temporaryArtifactPath),
     });

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

@@ -11,7 +11,7 @@ import {
 import { withDeviceRunSessionTimeoutAsync } from './deviceRunSessionTimeout';
 import { requireDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
 
-type ArtifactMetadata = {
+export type ArtifactMetadata = {
   deviceRunSessionId: string;
   artifactId: string;
   name: string;

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

@@ -11,6 +11,11 @@ import path from 'node:path';
 import { type CustomBuildContext } from '../../customBuildContext';
 import { uploadContentWithSignedUrl } from '../../storage/uploadWithSignedUrl';
 import { killProcessGroup } from '../../utils/processes';
+import {
+  type ImageSize,
+  type ScreenshotMetadata,
+  readImageSize,
+} from './deviceRunSessionScreenshotMetadata';
 import { requireDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
 
 const PREVIEW_INTERVAL_MS = 60_000;
@@ -20,7 +25,6 @@ const MAX_PREVIEW_SIZE_BYTES = 5 * 1024 * 1024;
 
 export function startDeviceRunSessionPreview({
   ctx,
-  deviceRunSessionId,
   captureAsync,
   logger,
 }: {
@@ -32,6 +36,7 @@ export function startDeviceRunSessionPreview({
   const controller = new AbortController();
   let timer: NodeJS.Timeout | undefined;
   let uploadSession: { url: string; headers: Record<string, string> } | undefined;
+  let storedSize: ImageSize | undefined;
   let pending: Promise<void>;
 
   const uploadAsync = async (): Promise<void> => {
@@ -44,8 +49,10 @@ export function startDeviceRunSessionPreview({
       if (image.length === 0 || image.length > MAX_PREVIEW_SIZE_BYTES) {
         throw new Error('Session preview is empty or exceeds the 5 MiB upload limit.');
       }
+      const size = readImageSize(image);
       if (!uploadSession) {
-        uploadSession = await createPreviewUploadSessionAsync(ctx, deviceRunSessionId, signal);
+        uploadSession = await createPreviewUploadSessionAsync(ctx, size, signal);
+        storedSize = size;
       }
       if (controller.signal.aborted) {
         return;
@@ -54,6 +61,16 @@ export function startDeviceRunSessionPreview({
         { signedUrl: uploadSession, content: image },
         { signal, retries: 0, stallTimeoutMs: 30_000 }
       );
+      if (
+        controller.signal.aborted ||
+        !size ||
+        (size.width === storedSize?.width && size.height === storedSize.height)
+      ) {
+        return;
+      }
+      storedSize = undefined;
+      uploadSession = await createPreviewUploadSessionAsync(ctx, size, signal);
+      storedSize = size;
     } catch (err) {
       if (!controller.signal.aborted) {
         logger.warn({ err }, 'Could not refresh the session preview; retrying in 60 seconds.');
@@ -80,10 +97,16 @@ export function startDeviceRunSessionPreview({
 
 async function createPreviewUploadSessionAsync(
   ctx: CustomBuildContext,
-  deviceRunSessionId: string,
+  size: ImageSize | undefined,
   signal: AbortSignal
 ): Promise<{ url: string; headers: Record<string, string> }> {
-  return await requireDeviceRunSessionWorkerApi(ctx).createPreviewUploadSessionAsync({ signal });
+  const metadata: ScreenshotMetadata | undefined = size
+    ? { source: 'preview', ...size }
+    : undefined;
+  return await requireDeviceRunSessionWorkerApi(ctx).createPreviewUploadSessionAsync(
+    { metadata },
+    { signal }
+  );
 }
 
 /**
@@ -141,18 +164,25 @@ export async function captureDeviceRunSessionPreviewAsync({
   device,
   env,
   signal,
+  captureIosScreenshotAsync,
 }: {
   runtimePlatform: BuildRuntimePlatform;
   device: string;
   env: BuildStepEnv;
   signal: AbortSignal;
+  captureIosScreenshotAsync?: (file: string, signal: AbortSignal) => Promise<void>;
 }): Promise<Buffer> {
   const directory = await mkdtemp(path.join(os.tmpdir(), 'session-preview-'));
   try {
     const options = { env, signal, timeout: 30_000, stdio: 'pipe' as const };
     const preview = path.join(directory, 'preview.webp');
     if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
-      await captureIosPreviewAsync({ device, directory, preview, options });
+      if (!captureIosScreenshotAsync) {
+        throw new Error(
+          'Cannot capture the iOS session preview: serve-sim screenshot capture is not configured.'
+        );
+      }
+      await captureIosPreviewAsync({ captureIosScreenshotAsync, directory, preview, options });
     } else {
       await captureAndroidPreviewAsync({ device, directory, preview, options });
     }
@@ -170,19 +200,20 @@ type CaptureOptions = {
 };
 
 async function captureIosPreviewAsync({
-  device,
+  captureIosScreenshotAsync,
   directory,
   preview,
   options,
 }: {
-  device: string;
+  captureIosScreenshotAsync: (file: string, signal: AbortSignal) => Promise<void>;
   directory: string;
   preview: string;
   options: CaptureOptions;
 }): Promise<void> {
   const screenshot = path.join(directory, 'screen.png');
   const resized = path.join(directory, 'resized.png');
-  await spawn('xcrun', ['simctl', 'io', device, 'screenshot', screenshot], options);
+  await captureIosScreenshotAsync(screenshot, options.signal);
+  options.signal.throwIfAborted();
   await spawn('sips', ['-Z', String(PREVIEW_MAX_DIMENSION), screenshot, '--out', resized], options);
   await spawn('cwebp', ['-quiet', '-q', String(PREVIEW_QUALITY), resized, '-o', preview], options);
 }

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

@@ -1,4 +1,4 @@
-import { SystemError } from '@expo/eas-build-job';
+import { SystemError, formatBytes } from '@expo/eas-build-job';
 import type { bunyan } from '@expo/logger';
 import type { BuildStepEnv } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
@@ -11,7 +11,6 @@ import { z } from 'zod';
 
 import { type CustomBuildContext } from '../../customBuildContext';
 import { Sentry } from '../../sentry';
-import { formatBytes } from '../../utils/artifacts';
 import { uploadDeviceRunSessionArtifactAsync } from './deviceRunSessionArtifacts';
 
 const RecordingsSchema = z.array(

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

@@ -0,0 +1,149 @@
+import type { bunyan } from '@expo/logger';
+import { open } from 'node:fs/promises';
+
+const IMAGE_HEADER_MAX_BYTES = 64 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export type ScreenshotSource = 'manual' | 'agent-device' | 'argent' | 'preview';
+
+export type ScreenshotMetadata = {
+  source: ScreenshotSource;
+  width?: number;
+  height?: number;
+  displayRotation?: string;
+};
+
+export type ImageSize = { width: number; height: number };
+
+export async function createScreenshotMetadataAsync(
+  file: string,
+  { logger, ...metadata }: Omit<ScreenshotMetadata, 'width' | 'height'> & { logger: bunyan }
+): Promise<ScreenshotMetadata> {
+  try {
+    const size = await readImageFileSizeAsync(file);
+    if (size) {
+      return { ...metadata, ...size };
+    }
+    logger.warn(
+      { file },
+      'Uploading the screenshot without its width and height because it does not start with a complete PNG, WebP or JPEG header.'
+    );
+  } catch (err) {
+    logger.warn(
+      { err, file },
+      'Uploading the screenshot without its width and height because its header could not be read.'
+    );
+  }
+  return metadata;
+}
+
+async function readImageFileSizeAsync(file: string): Promise<ImageSize | undefined> {
+  const handle = await open(file, 'r');
+  try {
+    const { buffer, bytesRead } = await handle.read(
+      Buffer.alloc(IMAGE_HEADER_MAX_BYTES),
+      0,
+      IMAGE_HEADER_MAX_BYTES,
+      0
+    );
+    return readImageSize(buffer.subarray(0, bytesRead));
+  } finally {
+    await handle.close();
+  }
+}
+
+export function readImageSize(header: Buffer): ImageSize | undefined {
+  const size = readPngSize(header) ?? readWebpSize(header) ?? readJpegSize(header);
+  return size && size.width > 0 && size.height > 0 ? size : undefined;
+}
+
+function readPngSize(header: Buffer): ImageSize | undefined {
+  if (
+    header.length < 24 ||
+    !header.subarray(0, 8).equals(PNG_SIGNATURE) ||
+    header.toString('latin1', 12, 16) !== 'IHDR'
+  ) {
+    return undefined;
+  }
+  return { width: header.readUInt32BE(16), height: header.readUInt32BE(20) };
+}
+
+function readWebpSize(header: Buffer): ImageSize | undefined {
+  if (
+    header.length < 16 ||
+    header.toString('latin1', 0, 4) !== 'RIFF' ||
+    header.toString('latin1', 8, 12) !== 'WEBP'
+  ) {
+    return undefined;
+  }
+  switch (header.toString('latin1', 12, 16)) {
+    case 'VP8 ':
+      if (header.length < 30 || header.readUIntBE(23, 3) !== 0x9d012a) {
+        return undefined;
+      }
+      return {
+        width: header.readUInt16LE(26) & 0x3fff,
+        height: header.readUInt16LE(28) & 0x3fff,
+      };
+    case 'VP8L': {
+      if (header.length < 25 || header[20] !== 0x2f) {
+        return undefined;
+      }
+      const bits = header.readUInt32LE(21);
+      return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+    }
+    case 'VP8X':
+      if (header.length < 30) {
+        return undefined;
+      }
+      return { width: header.readUIntLE(24, 3) + 1, height: header.readUIntLE(27, 3) + 1 };
+    default:
+      return undefined;
+  }
+}
+
+function readJpegSize(header: Buffer): ImageSize | undefined {
+  if (header.length < 4 || header[0] !== 0xff || header[1] !== 0xd8) {
+    return undefined;
+  }
+  let offset = 2;
+  while (offset + 4 <= header.length) {
+    if (header[offset] !== 0xff) {
+      return undefined;
+    }
+    const marker = header[offset + 1];
+    if (marker === 0xff) {
+      offset += 1;
+      continue;
+    }
+    if (marker === 0xd9 || marker === 0xda) {
+      return undefined;
+    }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+      offset += 2;
+      continue;
+    }
+    const segmentEnd = offset + 2 + header.readUInt16BE(offset + 2);
+    if (segmentEnd < offset + 4) {
+      return undefined;
+    }
+    if (isJpegStartOfFrame(marker)) {
+      return segmentEnd <= header.length
+        ? readJpegFrameSize(header.subarray(offset + 4, segmentEnd))
+        : undefined;
+    }
+    offset = segmentEnd;
+  }
+  return undefined;
+}
+
+function readJpegFrameSize(frame: Buffer): ImageSize | undefined {
+  if (frame.length < 6 || frame[5] === 0 || frame.length !== 6 + 3 * frame[5]) {
+    return undefined;
+  }
+  return { width: frame.readUInt16BE(3), height: frame.readUInt16BE(1) };
+}
+
+function isJpegStartOfFrame(marker: number): boolean {
+  return marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+}

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

@@ -1,3 +1,4 @@
+import { formatBytes } from '@expo/eas-build-job';
 import type { bunyan } from '@expo/logger';
 import { type FSWatcher, createReadStream, watch } from 'node:fs';
 import { mkdtemp, readFile, readdir, rm, rmdir, stat } from 'node:fs/promises';
@@ -7,8 +8,8 @@ import { z } from 'zod';
 
 import type { CustomBuildContext } from '../../customBuildContext';
 import { Sentry } from '../../sentry';
-import { formatBytes } from '../../utils/artifacts';
 import { uploadDeviceRunSessionArtifactAsync } from './deviceRunSessionArtifacts';
+import { createScreenshotMetadataAsync } from './deviceRunSessionScreenshotMetadata';
 import {
   type ScreenshotSession,
   loadScreenshotSessionAsync,
@@ -93,7 +94,10 @@ async function uploadScreenshotAsync(
     artifactId: name.slice(0, -4),
     name: artifactDetails.name,
     filename: artifactDetails.filename,
-    metadata: artifactDetails.metadata,
+    metadata: {
+      ...artifactDetails.metadata,
+      ...(await createScreenshotMetadataAsync(file, { source: 'manual', logger })),
+    },
     kind: 'screenshot',
     size,
     openStream: () => createReadStream(file),

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

@@ -126,13 +126,14 @@ export class DeviceRunSessionWorkerApi {
   }
 
   public async createPreviewUploadSessionAsync(
+    input: { metadata?: Record<string, unknown> } = {},
     options: WorkerApiRequestOptions = {}
   ): Promise<DeviceRunSessionUploadSession> {
     const { uploadSession } = await this.client.requestAsync(
       'POST',
       'preview-upload-session',
       UploadSessionSchema,
-      options
+      input.metadata ? { ...options, json: { metadata: input.metadata } } : options
     );
     return uploadSession;
   }

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

@@ -54,6 +54,7 @@ import {
   isPreinstalledExpoGoAsync,
   readIosApplicationIdentifierAsync,
 } from './iosAppArtifact';
+import { createServeSimPreviewCapture } from './serveSimPreviewCapture';
 import { type ServeSimActivityPolling, startServeSimActivityPolling } from './serveSimActivity';
 import { verifyLocalEgressGuardAsync } from './localEgressGuard';
 import { type IosSimulatorUuid } from '../../utils/IosSimulatorUtils';
@@ -72,6 +73,10 @@ const EXPO_DEVICE_HUB_PACKAGE_NAME = 'expo-device-hub';
 const EXPO_DEVICE_HUB_MAX_DIMENSION = '960';
 const EXPO_DEVICE_HUB_VIDEO_BITRATE = '6000000';
 const EXPO_DEVICE_HUB_VIDEO_FPS = '60';
+// expo-device-hub downloads the scrcpy server on first start. This copy keeps Android sessions
+// working when the GitHub release download fails; expo-device-hub falls back to GitHub when the
+// copy is missing.
+const SCRCPY_SERVER_MIRROR_BASE_URL = 'https://storage.googleapis.com/turtle-v2/scrcpy';
 // expo-device-hub's record of each running Hub, like serve-sim's: `server-<port>.json`.
 export const EXPO_DEVICE_HUB_STATE_DIR = path.join(os.tmpdir(), 'expo-device-hub');
 // On SIGTERM the Hub finalizes the recording itself, with this deadline before it force-exits,
@@ -432,6 +437,8 @@ export type DeviceSessionServerLaunch = {
  */
 export type DeviceSessionServer = {
   port: number;
+  /** The exact serve-sim version prepared by the warm launcher. */
+  serveSimVersion?: string;
   turnArgs: Promise<string[]>;
   /** Cold iOS setup runs after control readiness, alongside app installation and before launch. */
   setupSimulatorAsync?(options: { signal: AbortSignal; logger: bunyan }): Promise<void>;
@@ -584,6 +591,7 @@ async function startDeviceSessionHostInternalAsync(
       ? await createAndroidDeviceSessionServerAsync(ctx, { logger })
       : await createColdIosSessionAsync(ctx, { env, logger, iosSimulatorUdid }));
   const port = server.port;
+  packageVersion = server.serveSimVersion ?? packageVersion;
   const serverName = isAndroid ? 'expo-device-hub' : 'serve-sim';
   const packageSpec = isAndroid
     ? createExpoDeviceHubPackageSpec(packageVersion)
@@ -602,6 +610,7 @@ async function startDeviceSessionHostInternalAsync(
   const previewRetirementErrors: unknown[] = [];
   let finishTask: Promise<void> | null = null;
   let hostReady = false;
+  let iosPreviewCapture: ReturnType<typeof createServeSimPreviewCapture> | undefined;
   let sessionPreview: ReturnType<typeof startDeviceRunSessionPreview> | null = null;
   const previewSetupController = new AbortController();
   let previewSetupTask: Promise<void> | undefined;
@@ -768,6 +777,12 @@ async function startDeviceSessionHostInternalAsync(
         ...(recording ? { EXPO_DEVICE_HUB_RECORDING_CONTROL_TOKEN: recording.controlToken } : {}),
         // The Hub must write its token in the directory read by this host.
         ...(isAndroid ? { EXPO_DEVICE_HUB_STATE_DIR } : {}),
+        ...(isAndroid
+          ? {
+              SERVE_EMU_SCRCPY_BASE_URL:
+                env.SERVE_EMU_SCRCPY_BASE_URL || SCRCPY_SERVER_MIRROR_BASE_URL,
+            }
+          : {}),
       },
       logger,
     };
@@ -824,6 +839,7 @@ async function startDeviceSessionHostInternalAsync(
             await sessionPreview?.stopAsync();
             await previewActivity?.stopAsync();
           },
+          cleanupPreviewCaptureAsync: async () => iosPreviewCapture?.cleanupAfterHostStoppedAsync(),
           previewServer,
           screenshots,
           serverName,
@@ -989,6 +1005,18 @@ async function startDeviceSessionHostInternalAsync(
     // readiness on macOS, so it starts after its encoder is installed there.
     previewSetupTask = (async () => {
       if (!isAndroid) {
+        iosPreviewCapture = createServeSimPreviewCapture({
+          port,
+          token: previewToken!,
+          device,
+          tmpdir: serveSimTmpdir,
+        });
+        if (!(await iosPreviewCapture.isSupportedAsync(previewSetupController.signal))) {
+          logger.warn(
+            'This serve-sim version does not support automated screenshots; skipping session previews.'
+          );
+          return;
+        }
         await ensureMacosPreviewEncoderInstalledAsync({
           env,
           logger,
@@ -1002,6 +1030,7 @@ async function startDeviceSessionHostInternalAsync(
           logger,
           captureAsync: signal =>
             captureDeviceRunSessionPreviewAsync({
+              captureIosScreenshotAsync: iosPreviewCapture?.captureAsync,
               runtimePlatform,
               device: previewDevice ?? device,
               env,
@@ -1077,6 +1106,7 @@ async function finishDeviceSessionHostAsync(
   {
     previewRetirement,
     stopSessionPreviewAsync,
+    cleanupPreviewCaptureAsync,
     previewServer,
     screenshots,
     serverName,
@@ -1088,6 +1118,7 @@ async function finishDeviceSessionHostAsync(
   }: {
     previewRetirement: Promise<boolean>;
     stopSessionPreviewAsync: () => Promise<void>;
+    cleanupPreviewCaptureAsync: () => Promise<void>;
     previewServer: DetachedProcessHandle;
     screenshots: { finishAsync(hostStopped: boolean): Promise<void> };
     serverName: string;
@@ -1121,6 +1152,13 @@ async function finishDeviceSessionHostAsync(
   } catch (err) {
     logger.warn({ err }, `Could not stop the ${serverName} session host.`);
   }
+  if (hostStopped) {
+    try {
+      await cleanupPreviewCaptureAsync();
+    } catch (err) {
+      logger.warn({ err }, 'Could not remove session preview capture files.');
+    }
+  }
   const previewRetired = await previewRetirement;
   onStopped(hostStopped && !hostExited && previewRetired);
   await screenshots.finishAsync(hostStopped);

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

@@ -1,173 +0,0 @@
-import { type Env, SystemError } from '@expo/eas-build-job';
-import { type Client, CombinedError } from '@urql/core';
-import { graphql } from 'gql.tada';
-import { setTimeout as delay } from 'node:timers/promises';
-
-import { graphqlAbortContext } from '../../utils/graphqlAbort';
-import { type SandboxArtifactUploadSession } from './sandboxWorkerApi';
-import { WorkerApiError, type WorkerApiRequestOptions } from './workerApi';
-
-const MARK_SANDBOX_READY_MUTATION = graphql(`
-  mutation MarkSandboxReady($sandboxId: ID!) {
-    sandbox {
-      markSandboxReady(sandboxId: $sandboxId) {
-        id
-      }
-    }
-  }
-`);
-
-const CREATE_SANDBOX_ARTIFACT_UPLOAD_SESSION_MUTATION = graphql(`
-  mutation CreateSandboxArtifactUploadSession(
-    $sandboxId: ID!
-    $input: CreateSandboxArtifactUploadSessionInput!
-  ) {
-    sandbox {
-      createArtifactUploadSession(sandboxId: $sandboxId, input: $input) {
-        artifact {
-          id
-        }
-        uploadSession {
-          url
-          headers
-        }
-      }
-    }
-  }
-`);
-
-const FINALIZE_SANDBOX_ARTIFACT_MUTATION = graphql(`
-  mutation FinalizeSandboxArtifact($artifactId: ID!) {
-    sandbox {
-      finalizeArtifact(artifactId: $artifactId) {
-        id
-        downloadUrl
-      }
-    }
-  }
-`);
-
-const FINALIZE_ATTEMPTS = 3;
-const FINALIZE_TIMEOUT_MS = 15_000;
-
-export class LegacySandboxApi {
-  constructor(
-    private readonly graphqlClient: Client,
-    private readonly sandboxId: string
-  ) {}
-
-  public async markReadyAsync({ signal }: WorkerApiRequestOptions = {}): Promise<void> {
-    signal?.throwIfAborted();
-    const result = await this.graphqlClient
-      .mutation(
-        MARK_SANDBOX_READY_MUTATION,
-        { sandboxId: this.sandboxId },
-        graphqlAbortContext(signal)
-      )
-      .toPromise();
-    signal?.throwIfAborted();
-    if (result.error) {
-      throw result.error;
-    }
-  }
-
-  public async createArtifactUploadSessionAsync(
-    input: { name: string; filename: string; size: number },
-    { signal, timeoutMs }: WorkerApiRequestOptions = {}
-  ): Promise<SandboxArtifactUploadSession> {
-    const requestSignal = AbortSignal.any([
-      ...(signal ? [signal] : []),
-      ...(timeoutMs !== undefined ? [AbortSignal.timeout(timeoutMs)] : []),
-    ]);
-    const result = await this.graphqlClient
-      .mutation(
-        CREATE_SANDBOX_ARTIFACT_UPLOAD_SESSION_MUTATION,
-        { sandboxId: this.sandboxId, input },
-        graphqlAbortContext(requestSignal)
-      )
-      .toPromise();
-    requestSignal.throwIfAborted();
-    if (result.error) {
-      const { graphQLErrors } = result.error;
-      const codes = Array.from(new Set(graphQLErrors.map(error => error.extensions?.errorCode)));
-      throw new WorkerApiError(
-        graphQLErrors.length > 0
-          ? graphQLErrors.map(error => error.message).join('\n')
-          : result.error.message,
-        result.error.response?.status,
-        { cause: result.error },
-        codes.length === 1 && typeof codes[0] === 'string' ? codes[0] : undefined
-      );
-    }
-    const { artifact, uploadSession } = result.data!.sandbox.createArtifactUploadSession;
-    return {
-      artifact,
-      uploadSession: {
-        url: uploadSession.url,
-        headers: uploadSession.headers as Record<string, string>,
-      },
-    };
-  }
-
-  public async finalizeArtifactAsync(
-    artifactId: string,
-    { signal }: WorkerApiRequestOptions = {}
-  ): Promise<string> {
-    for (let attempt = 1; ; attempt++) {
-      const timeoutSignal = AbortSignal.timeout(FINALIZE_TIMEOUT_MS);
-      const finalizeSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-      try {
-        const result = await this.graphqlClient
-          .mutation(
-            FINALIZE_SANDBOX_ARTIFACT_MUTATION,
-            { artifactId },
-            graphqlAbortContext(finalizeSignal)
-          )
-          .toPromise();
-        finalizeSignal.throwIfAborted();
-        if (result.error) {
-          throw result.error;
-        }
-        const { downloadUrl } = result.data!.sandbox.finalizeArtifact;
-        if (downloadUrl === null) {
-          throw new SystemError(`Finalized sandbox artifact ${artifactId} has no download URL.`);
-        }
-        return downloadUrl;
-      } catch (error) {
-        signal?.throwIfAborted();
-        const retryable =
-          timeoutSignal.aborted ||
-          (error instanceof CombinedError && isTransientGraphqlError(error));
-        if (!retryable || attempt >= FINALIZE_ATTEMPTS) {
-          throw error;
-        }
-        await delay(500 * attempt, undefined, { signal });
-      }
-    }
-  }
-}
-
-export function getLegacySandboxConnection({
-  graphqlClient,
-  env,
-  sandboxId,
-}: {
-  graphqlClient: Client;
-  env: Env;
-  sandboxId: string;
-}): { sandboxApi: LegacySandboxApi; credential: string; commandEnv: Env } {
-  const { __EAS_SANDBOX_MCP_TOKEN: credential, ...commandEnv } = env;
-  if (!credential) {
-    throw new SystemError(
-      'This sandbox job has neither EAS_SANDBOX_WORKER_TOKEN nor __EAS_SANDBOX_MCP_TOKEN. ' +
-        'www gives one of them to every sandbox job. Start a new sandbox, and contact support if ' +
-        'it happens again.'
-    );
-  }
-  return { sandboxApi: new LegacySandboxApi(graphqlClient, sandboxId), credential, commandEnv };
-}
-
-function isTransientGraphqlError(error: CombinedError): boolean {
-  const status: number | undefined = error.response?.status;
-  return status === undefined ? error.networkError !== undefined : status >= 500;
-}

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

@@ -0,0 +1,31 @@
+import { UserError } from '@expo/eas-build-job';
+import { BuildRuntimePlatform } from '@expo/steps';
+
+import {
+  type AndroidEmulatorLogSource,
+  AndroidEmulatorLogSourcesSchema,
+} from '../../utils/androidEmulatorLogSources';
+
+/**
+ * `log_sources` is unprefixed like every other step input, so the platform
+ * rule is checked here at runtime, the way `network_capture` is.
+ */
+export function parseLogSourcesInput(
+  value: unknown,
+  {
+    runtimePlatform,
+    fallback,
+  }: { runtimePlatform: BuildRuntimePlatform; fallback: readonly AndroidEmulatorLogSource[] }
+): readonly AndroidEmulatorLogSource[] {
+  if (value === undefined) {
+    return fallback;
+  }
+  const sources = AndroidEmulatorLogSourcesSchema.parse(value);
+  if (sources.length > 0 && runtimePlatform === BuildRuntimePlatform.DARWIN) {
+    throw new UserError(
+      'EAS_LOG_SOURCES_INVALID_INPUT',
+      `Input "log_sources" selects Android emulator logs, and this session runs on iOS. Drop "log_sources", or run the session on Android.`
+    );
+  }
+  return sources;
+}

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

@@ -9,6 +9,7 @@ import { killProcessGroup } from '../../utils/processes';
 export async function preparePreinstalledWdaAsync({
   runtimeIdentifier,
   appiumHome,
+  prepared = false,
   appiumBinPath,
   appiumEnv,
   logger,
@@ -16,6 +17,8 @@ export async function preparePreinstalledWdaAsync({
 }: {
   runtimeIdentifier: string | undefined;
   appiumHome: string;
+  /** A prepared Appium home that already holds the runner. */
+  prepared?: boolean;
   appiumBinPath: string;
   appiumEnv: BuildStepEnv;
   logger: bunyan;
@@ -32,6 +35,13 @@ export async function preparePreinstalledWdaAsync({
 
   const outdir = path.join(appiumHome, 'preinstalled-wda');
   const runner = path.join(outdir, 'WebDriverAgentRunner-Runner.app');
+  if (prepared) {
+    logger.info('Using preinstalled WebDriverAgent to avoid xcodebuild during session creation.');
+    return {
+      'appium:usePreinstalledWDA': true,
+      'appium:prebuiltWDAPath': runner,
+    };
+  }
   try {
     // The driver selects the release matching its installed WDA and the host architecture.
     // Keep the Simulator runner intact; removing its XCTest frameworks breaks launch.

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

@@ -11,7 +11,6 @@ import { performance } from 'node:perf_hooks';
 import { Readable } from 'node:stream';
 
 import { SignedUrlUploadApiError, uploadWithSignedUrl } from '../../storage/uploadWithSignedUrl';
-import { type LegacySandboxApi } from './legacySandboxApi';
 import { type SandboxArtifactUploadSession, type SandboxWorkerApi } from './sandboxWorkerApi';
 import { WorkerApiError } from './workerApi';
 
@@ -29,7 +28,7 @@ export class SandboxArtifactUploadManager {
 
   public constructor(
     private readonly options: {
-      workerApi: SandboxWorkerApi | LegacySandboxApi;
+      workerApi: SandboxWorkerApi;
       logger: bunyan;
       signal: AbortSignal;
     }
@@ -88,7 +87,7 @@ export async function startSandboxArtifactUploadAsync({
   name,
   signal,
 }: {
-  workerApi: SandboxWorkerApi | LegacySandboxApi;
+  workerApi: SandboxWorkerApi;
   logger: bunyan;
   filePath: string;
   name: string;
@@ -157,7 +156,7 @@ export async function startSandboxArtifactUploadAsync({
 }
 
 async function createSandboxArtifactUploadSessionAsync(
-  workerApi: SandboxWorkerApi | LegacySandboxApi,
+  workerApi: SandboxWorkerApi,
   input: { name: string; filename: string; size: number },
   signal: AbortSignal
 ): Promise<SandboxArtifactUploadSession> {

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

@@ -13,7 +13,6 @@ import { performance } from 'node:perf_hooks';
 import { readBytesAsync, readTextAsync } from '../../utils/files';
 import { detectFileType } from '../../utils/files/filetypes';
 import { SandboxArtifactUploadManager } from './sandboxArtifacts';
-import { type LegacySandboxApi } from './legacySandboxApi';
 import { type SandboxWorkerApi } from './sandboxWorkerApi';
 import { ShellSessionManager } from './shellSessionManager';
 
@@ -37,7 +36,7 @@ export function createSandboxCommandImplementations({
   workingDirectory: string;
   env: NodeJS.ProcessEnv;
   signal: AbortSignal;
-  workerApi: SandboxWorkerApi | LegacySandboxApi;
+  workerApi: SandboxWorkerApi;
   logger: bunyan;
 }): {
   commandImplementations: SandboxDaemonCommandImplementations;

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

@@ -16,7 +16,6 @@ import {
   type SandboxDaemonCommandImplementations,
   createSandboxCommandImplementations,
 } from './sandboxCommandImplementations';
-import { type LegacySandboxApi } from './legacySandboxApi';
 import { type SandboxWorkerApi } from './sandboxWorkerApi';
 
 export interface SandboxDaemonOptions {
@@ -27,7 +26,7 @@ export interface SandboxDaemonOptions {
   signal?: AbortSignal;
   workingDirectory: string;
   env: NodeJS.ProcessEnv;
-  workerApi: SandboxWorkerApi | LegacySandboxApi;
+  workerApi: SandboxWorkerApi;
 }
 
 export interface SandboxDaemon {

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

@@ -1,4 +1,4 @@
-import { type Env, type EnvironmentSecret, type Job } from '@expo/eas-build-job';
+import { type Env, type EnvironmentSecret, type Job, SystemError } from '@expo/eas-build-job';
 import { z } from 'zod';
 
 import {
@@ -97,3 +97,19 @@ export function getSandboxWorkerApi(ctx: {
   const token = getSandboxWorkerTokenFromEnvironmentSecrets(ctx.job.secrets?.environmentSecrets);
   return token ? new SandboxWorkerApi(getExpoApiV2BaseUrl(ctx), token) : null;
 }
+
+export function requireSandboxWorkerApi(ctx: {
+  job: Job;
+  env: Env;
+  expoApiV2BaseUrl?: string;
+}): SandboxWorkerApi {
+  const workerApi = getSandboxWorkerApi(ctx);
+  if (!workerApi) {
+    throw new SystemError(
+      `This sandbox job has no ${SANDBOX_WORKER_TOKEN_ENV} secret. ` +
+        'www gives one to every sandbox job, and the worker needs it to call the sandbox API. ' +
+        'Start a new sandbox, and contact support if it happens again.'
+    );
+  }
+  return workerApi;
+}

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

@@ -30,13 +30,20 @@ export async function stageServeSimAppAsync(
   }
 }
 
-export async function runServeSimActionAsync({
+export async function runServeSimActionAsync(
+  options: Parameters<typeof runServeSimActionWithResultAsync>[0]
+): Promise<void> {
+  await runServeSimActionWithResultAsync(options);
+}
+
+export async function runServeSimActionWithResultAsync({
   port,
   token,
   action,
   params,
   timeoutMs,
   signal,
+  drainAfterDispatch = false,
 }: {
   port: number;
   token: string;
@@ -44,13 +51,15 @@ export async function runServeSimActionAsync({
   params: Record<string, unknown>;
   timeoutMs: number;
   signal?: AbortSignal;
-}): Promise<void> {
+  /** Abort before dispatch; once sent, wait for its reply or deadline because exec-ws cannot cancel it. */
+  drainAfterDispatch?: boolean;
+}): Promise<string> {
   signal?.throwIfAborted();
-  await new Promise<void>((resolve, reject) => {
+  return await new Promise<string>((resolve, reject) => {
     const socket = new WebSocket(`ws://127.0.0.1:${port}/exec-ws`, [`serve-sim.token.${token}`]);
     let settled = false;
     let sent = false;
-    const finish = (error?: unknown) => {
+    const finish = (error?: unknown, stdout = '') => {
       if (settled) {
         return;
       }
@@ -61,10 +70,14 @@ export async function runServeSimActionAsync({
       if (error) {
         reject(error);
       } else {
-        resolve();
+        resolve(stdout);
+      }
+    };
+    const aborted = () => {
+      if (!sent || !drainAfterDispatch) {
+        finish(signal?.reason ?? new Error('Serve-sim action aborted.'));
       }
     };
-    const aborted = () => finish(signal?.reason ?? new Error('Serve-sim action aborted.'));
     const timer = setTimeout(
       () => finish(new SystemError(`serve-sim ${action} timed out.`)),
       timeoutMs
@@ -75,6 +88,9 @@ export async function runServeSimActionAsync({
       finish(new SystemError(`serve-sim ${action} connection closed before completion.`))
     );
     socket.on('message', data => {
+      if (settled) {
+        return;
+      }
       let reply;
       try {
         reply = JSON.parse(data.toString());
@@ -90,7 +106,8 @@ export async function runServeSimActionAsync({
             ? undefined
             : new SystemError(
                 `serve-sim ${action} failed: ${(typeof reply.error === 'string' && reply.error) || (typeof reply.stderr === 'string' && reply.stderr) || 'invalid response'}`
-              )
+              ),
+          typeof reply.stdout === 'string' ? reply.stdout : ''
         );
       }
     });

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

@@ -1,9 +1,7 @@
 import { type bunyan } from '@expo/logger';
-import { createReadStream } from 'node:fs';
-import { stat } from 'node:fs/promises';
 
 import { type CustomBuildContext } from '../../customBuildContext';
-import { uploadDeviceRunSessionArtifactAsync } from './deviceRunSessionArtifacts';
+import { uploadDeviceRunSessionFileAsync } from './uploadDeviceRunSessionFile';
 
 export async function uploadServeSimLogsFileAsync(
   ctx: CustomBuildContext,
@@ -22,21 +20,22 @@ export async function uploadServeSimLogsFileAsync(
   }
 ): Promise<void> {
   try {
-    const { size } = await stat(filePath);
-    if (size === 0) {
-      return;
-    }
-    const fileController = new AbortController();
-    await uploadDeviceRunSessionArtifactAsync(ctx, {
-      deviceRunSessionId,
-      artifactId: `simulator-log-${udid}`,
-      name: `App logs (${udid.slice(0, 8)})`,
-      filename: 'app-logs.ndjson',
-      kind: 'simulator-log',
-      metadata: { __eas_type: 'simulator-log', udid, scope: 'user-apps', source: 'serve-sim/logs' },
-      size,
-      openStream: () => createReadStream(filePath).on('error', err => fileController.abort(err)),
-      signal: AbortSignal.any([fileController.signal, ...(signal ? [signal] : [])]),
+    await uploadDeviceRunSessionFileAsync(ctx, {
+      filePath,
+      describe: () => ({
+        deviceRunSessionId,
+        artifactId: `simulator-log-${udid}`,
+        name: `App logs (${udid.slice(0, 8)})`,
+        filename: 'app-logs.ndjson',
+        kind: 'simulator-log',
+        metadata: {
+          __eas_type: 'simulator-log',
+          udid,
+          scope: 'user-apps',
+          source: 'serve-sim/logs',
+        },
+      }),
+      signal,
     });
   } catch (err) {
     logger.warn(

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

@@ -1,10 +1,10 @@
+import { formatBytes } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
 import { createReadStream } from 'node:fs';
 import { stat } from 'node:fs/promises';
 
 import { CustomBuildContext } from '../../customBuildContext';
 import { Sentry } from '../../sentry';
-import { formatBytes } from '../../utils/artifacts';
 import { uploadDeviceRunSessionArtifactAsync } from './deviceRunSessionArtifacts';
 
 const METRICS_ARTIFACT_FILENAME = 'metrics.ndjson';

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

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import { copyFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { runServeSimActionAsync, runServeSimActionWithResultAsync } from './serveSimActions';
+
+export function createServeSimPreviewCapture({
+  port,
+  token,
+  device,
+  tmpdir,
+}: {
+  port: number;
+  token: string;
+  device: string;
+  tmpdir: string;
+}) {
+  const ownedFiles = new Set<string>();
+  return {
+    async isSupportedAsync(signal: AbortSignal): Promise<boolean> {
+      const result = await runServeSimActionWithResultAsync({
+        port,
+        token,
+        action: 'actions.describe',
+        params: {},
+        timeoutMs: 30_000,
+        signal,
+      });
+      const catalog: {
+        'screenshot.capture'?: { properties?: { automation?: { type?: unknown } } };
+      } | null = JSON.parse(result);
+      return catalog?.['screenshot.capture']?.properties?.automation?.type === 'boolean';
+    },
+    async captureAsync(destination: string, signal: AbortSignal): Promise<void> {
+      signal.throwIfAborted();
+      const fileName = `serve-sim-screenshot-preview-${randomUUID()}.png`;
+      const staged = path.join(tmpdir, 'serve-sim-screenshots', fileName);
+      ownedFiles.add(staged);
+      // Closing exec-ws does not cancel its host action. Drain a sent capture before honoring
+      // cancellation; on timeout/disconnect, leave its file alone until the host has stopped.
+      await runServeSimActionAsync({
+        port,
+        token,
+        action: 'screenshot.capture',
+        params: { udid: device, fileName, automation: true },
+        timeoutMs: 30_000,
+        signal,
+        drainAfterDispatch: true,
+      });
+      try {
+        signal.throwIfAborted();
+        await copyFile(staged, destination);
+      } finally {
+        await rm(staged, { force: true });
+        ownedFiles.delete(staged);
+      }
+    },
+    /** Call only after the host process group has stopped, including timed-out actions. */
+    async cleanupAfterHostStoppedAsync(): Promise<void> {
+      const results = await Promise.allSettled(
+        [...ownedFiles].map(async file => {
+          await rm(file, { force: true });
+          ownedFiles.delete(file);
+        })
+      );
+      const errors = results
+        .filter(result => result.status === 'rejected')
+        .map(result => result.reason);
+      if (errors.length) {
+        throw new AggregateError(errors, 'Could not remove preview captures.');
+      }
+    },
+  };
+}

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

@@ -0,0 +1,44 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+
+import { type CustomBuildContext } from '../../customBuildContext';
+import {
+  type ArtifactMetadata,
+  uploadDeviceRunSessionArtifactAsync,
+} from './deviceRunSessionArtifacts';
+
+/** Upload a finalized file, reopening it for each attempt. */
+export async function uploadDeviceRunSessionFileAsync(
+  ctx: CustomBuildContext,
+  {
+    filePath,
+    describe,
+    signal,
+    attempts = 1,
+  }: {
+    filePath: string;
+    describe: (size: number) => Omit<ArtifactMetadata, 'size'>;
+    signal?: AbortSignal;
+    attempts?: number;
+  }
+): Promise<boolean> {
+  const { size } = await stat(filePath);
+  if (size === 0) {
+    return false;
+  }
+  const readController = new AbortController();
+  await uploadDeviceRunSessionArtifactAsync(ctx, {
+    ...describe(size),
+    size,
+    openStream: () =>
+      createReadStream(filePath).on('error', err => {
+        // An HTTP error aborts one request body, not the remaining upload attempts.
+        if (err.name !== 'AbortError') {
+          readController.abort(err);
+        }
+      }),
+    signal: AbortSignal.any([readController.signal, ...(signal ? [signal] : [])]),
+    attempts,
+  });
+  return true;
+}

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

@@ -2,6 +2,8 @@ import type { bunyan } from '@expo/logger';
 import spawn from '@expo/turtle-spawn';
 
 import { type CustomBuildContext } from '../../customBuildContext';
+import { resolveSimulatorPackageVersionAsync } from '../../utils/simulatorPackageVersion';
+import { stopWarmSimulatorAsync } from '../../utils/warmSimulator';
 import { IosSimulatorRecordingUtils } from './IosSimulatorRecordingUtils';
 import { type DeviceSessionServer } from './deviceSessionHost';
 import { fetchWebPreviewTurnArgsAsync } from './remoteDeviceRunSession';
@@ -28,6 +30,7 @@ export function createWarmDeviceSessionServer(
   }
   return {
     port: warm.server.port,
+    serveSimVersion: warm.serveSimVersion,
     turnArgs: fetchWebPreviewTurnArgsAsync(ctx, { logger }),
     // Set by prepare-tools, which the host runs before it installs the app.
     get preinstalledApp() {
@@ -68,14 +71,34 @@ export function createWarmDeviceSessionServer(
  */
 export async function runOnWarmIosSimulatorAsync<T>(
   claim: Parameters<typeof tryClaimWarmIosSessionAsync>[0],
-  run: (warm?: WarmIosSession) => Promise<T>
+  run: (warm?: WarmIosSession, packageVersion?: string) => Promise<T>
 ): Promise<T> {
-  const warm = await tryClaimWarmIosSessionAsync(claim);
+  let packageVersion = claim.packageVersion;
+  if (packageVersion !== undefined && claim.env.EAS_USE_WARM_SIMULATOR === '1') {
+    try {
+      packageVersion = await resolveSimulatorPackageVersionAsync(
+        claim.engine,
+        packageVersion,
+        claim
+      );
+    } catch (error) {
+      try {
+        await stopWarmSimulatorAsync(claim.env);
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [error, cleanupError],
+          'Could not stop warmup after version resolution failed.'
+        );
+      }
+      throw error;
+    }
+  }
+  const warm = await tryClaimWarmIosSessionAsync({ ...claim, packageVersion });
   if (!warm) {
-    return await run(undefined);
+    return await run(undefined, packageVersion);
   }
   try {
-    return await run(warm);
+    return await run(warm, packageVersion);
   } catch (error) {
     try {
       await warm.process.stopAsync();
@@ -90,6 +113,6 @@ export async function runOnWarmIosSimulatorAsync<T>(
     }
     claim.logger.warn('Could not adopt the warm Simulator; starting a cold Simulator.');
     claim.signal?.throwIfAborted();
-    return await run(undefined);
+    return await run(undefined, packageVersion);
   }
 }

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

@@ -2,6 +2,7 @@ import { type bunyan } from '@expo/logger';
 import { type BuildStepEnv } from '@expo/steps';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import semver from 'semver';
 import { z } from 'zod';
 
 import { runSimulatorLauncherAsync, stopWarmSimulatorAsync } from '../../utils/warmSimulator';
@@ -9,7 +10,11 @@ import { readLocalEgressHandoffAsync } from './localEgress';
 import { type DetachedProcessHandle, isProcessRunning } from './remoteDeviceRunSession';
 
 const ServiceSchema = z.object({ pid: z.number(), port: z.number(), token: z.string() });
+const PackageVersionSchema = z.string().refine(version => semver.valid(version) !== null);
 const ClaimSchema = z.object({
+  serveSimVersion: PackageVersionSchema.optional(),
+  agentDeviceVersion: PackageVersionSchema.optional(),
+  argentVersion: PackageVersionSchema.optional(),
   device: z.object({ udid: z.string(), name: z.string() }),
   server: ServiceSchema,
   agentDeviceStateDir: z.string(),
@@ -53,10 +58,6 @@ export async function tryClaimWarmIosSessionAsync({
     return undefined;
   }
   try {
-    // Warm tools run the latest release with the VM's Simulator settings.
-    if (packageVersion && packageVersion !== 'latest') {
-      throw new Error('A pinned package_version needs a cold start.');
-    }
     const setting = Object.keys(env).find(
       name => name === 'SERVE_SIM_ADDITIONAL_DYLIBS' || name.startsWith('SIMCTL_CHILD_')
     );
@@ -71,6 +72,15 @@ export async function tryClaimWarmIosSessionAsync({
     const claim = ClaimSchema.parse(
       JSON.parse(await runSimulatorLauncherAsync(claimArgs, { env, signal }))
     );
+    const selectedVersion = {
+      'serve-sim': claim.serveSimVersion,
+      'agent-device': claim.agentDeviceVersion,
+      argent: claim.argentVersion,
+      appium: undefined,
+    }[engine];
+    if (packageVersion !== undefined && selectedVersion !== packageVersion) {
+      throw new Error('The warm tool does not match the requested package version.');
+    }
     logger.info(`Claimed the warm Simulator ${claim.device.name} (${claim.device.udid}).`);
     let stopping: Promise<void> | undefined;
     const session: WarmIosSession = {

packages/build-tools/src/utils/AndroidEmulatorUtils.ts

@@ -13,6 +13,7 @@ import { setTimeout } from 'node:timers/promises';
 import { z } from 'zod';
 
 import { Sentry } from '../sentry';
+import { type AndroidEmulatorLogCapture } from './androidEmulatorLogCapture';
 import { retryAsync } from './retry';
 
 /** Android Virtual Device is the device we run. */
@@ -327,19 +328,19 @@ export namespace AndroidEmulatorUtils {
     env,
     logcatDirectory,
     launchGate,
+    logCapture,
   }: {
     deviceName: AndroidVirtualDeviceName;
     env: NodeJS.ProcessEnv;
     logcatDirectory: string;
     launchGate?: AndroidEmulatorLaunchGate;
+    logCapture: AndroidEmulatorLogCapture;
   }): Promise<{
     emulatorPromise: SpawnPromise<SpawnResult>;
     serialId: AndroidDeviceSerialId;
-    logcatOutputPath: string;
-    emulatorOutputPath: string;
   }> {
-    let logcatOutputPath: string;
-    let emulatorOutputPath: string;
+    let logcatOutputPath: string | undefined;
+    let emulatorOutputPath: string | undefined;
     try {
       await fs.promises.mkdir(logcatDirectory, { recursive: true });
       const safeDeviceName = deviceName.replace(/[^a-zA-Z0-9_.-]/g, '_');
@@ -347,16 +348,21 @@ export namespace AndroidEmulatorUtils {
         .toString(16)
         .padStart(8, '0');
       const outputName = `${safeDeviceName}-${timestamp}-${randomBytes(2).toString('hex')}`;
-      logcatOutputPath = path.join(logcatDirectory, `${outputName}-logcat.log`);
-      emulatorOutputPath = path.join(logcatDirectory, `${outputName}-emulator.log`);
-      await fs.promises.writeFile(logcatOutputPath, '');
-      await fs.promises.writeFile(emulatorOutputPath, '');
+      if (logCapture.sources.includes('device-logcat')) {
+        logcatOutputPath = path.join(logcatDirectory, `${outputName}-logcat.log`);
+      }
+      if (logCapture.sources.includes('emulator-output')) {
+        emulatorOutputPath = path.join(logcatDirectory, `${outputName}-emulator.log`);
+      }
     } catch (err) {
       throw new SystemError(`Failed to prepare Android emulator output for ${deviceName}.`, {
         cause: err,
       });
     }
 
+    const logcatOutput = logcatOutputPath
+      ? await logCapture.prepareLogcatOutputAsync(logcatOutputPath)
+      : undefined;
     const emulatorCommand = `${process.env.ANDROID_HOME}/emulator/emulator`;
     const emulatorArgs = [
       '-no-window',
@@ -364,10 +370,7 @@ export namespace AndroidEmulatorUtils {
       '-writable-system',
       '-noaudio',
       '-no-snapshot-save',
-      '-logcat',
-      '*:v',
-      '-logcat-output',
-      logcatOutputPath,
+      ...(logcatOutput ? ['-logcat', '*:v', '-logcat-output', logcatOutput.path] : []),
       '-avd',
       deviceName,
       '-accel',
@@ -381,49 +384,37 @@ export namespace AndroidEmulatorUtils {
       // We don't need to wait for emulator to exit gracefully.
       ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL: '1',
     };
+    const outputStdio = emulatorOutputPath ? 'pipe' : 'ignore';
     const emulatorPromise = launchGate
       ? spawn(
           launchGate.wrapperCommand,
           [...launchGate.wrapperArgs, emulatorCommand, ...emulatorArgs, ...launchGate.emulatorArgs],
           {
             detached: true,
-            stdio: ['pipe', 'pipe', 'pipe'],
+            stdio: ['pipe', outputStdio, outputStdio],
             ignoreStdio: true,
             env: emulatorEnv,
           }
         )
       : spawn(emulatorCommand, emulatorArgs, {
           detached: true,
-          stdio: ['ignore', 'pipe', 'pipe'],
+          stdio: ['ignore', outputStdio, outputStdio],
           ignoreStdio: true,
           env: emulatorEnv,
         });
-    const emulatorOutputStream = fs.createWriteStream(emulatorOutputPath, { flags: 'a' });
-    let reportedEmulatorOutputError = false;
-    emulatorOutputStream.on('error', err => {
-      process.stderr.write(
-        `Failed to write Android emulator output to ${emulatorOutputPath}: ${err}\n`
-      );
-      if (!reportedEmulatorOutputError) {
-        reportedEmulatorOutputError = true;
-        Sentry.capture('Failed to write Android emulator process output', err, {
-          level: 'warning',
-          tags: {
-            errorCode: (err as NodeJS.ErrnoException).code ?? 'unknown',
-          },
-          extras: {
-            deviceName,
-            emulatorOutputPath,
-          },
-        });
+    if (logcatOutput) {
+      emulatorPromise.child.once('close', logcatOutput.close);
+    }
+    if (emulatorOutputPath) {
+      for (const input of [emulatorPromise.child.stdout, emulatorPromise.child.stderr]) {
+        if (input) {
+          logCapture.attach(input, emulatorOutputPath, 'emulator-output');
+        }
       }
-    });
-    // Only into the log file -- this process' stdout/stderr is not watched or uploaded.
-    emulatorPromise.child.stdout?.pipe(emulatorOutputStream, { end: false });
-    emulatorPromise.child.stderr?.pipe(emulatorOutputStream, { end: false });
-    emulatorPromise.child.once('close', () => {
-      emulatorOutputStream.end();
-    });
+      emulatorPromise.child.once('close', () => {
+        void logCapture.finishFileAsync(emulatorOutputPath);
+      });
+    }
     // Piped stdio creates socket handles in this process which, unlike inherited
     // file descriptors, keep the event loop alive for as long as the emulator runs.
     // We never stop the emulator explicitly, so without unref-ing these the process
@@ -473,7 +464,7 @@ export namespace AndroidEmulatorUtils {
 
     // We don't want to await the SpawnPromise here.
     // eslint-disable-next-line @typescript-eslint/return-await
-    return { emulatorPromise, serialId, logcatOutputPath, emulatorOutputPath };
+    return { emulatorPromise, serialId };
   }
 
   export async function waitForReadyAsync({

packages/build-tools/src/utils/IosSimulatorUtils.ts

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { setTimeout } from 'node:timers/promises';
+import semver from 'semver';
 import { z } from 'zod';
 
 import { retryAsync } from './retry';
@@ -202,7 +203,7 @@ export namespace IosSimulatorUtils {
     env: NodeJS.ProcessEnv;
   }): Promise<IosSimulatorUuid> {
     if (UDID_PATTERN.test(deviceIdentifier)) {
-      return deviceIdentifier as IosSimulatorUuid;
+      return deviceIdentifier.toUpperCase() as IosSimulatorUuid;
     }
     const devices = await getAvailableDevicesAsync({ env, filter: 'available' });
     const device = devices.find(candidate => candidate.name === deviceIdentifier);
@@ -284,9 +285,23 @@ export namespace IosSimulatorUtils {
     const readinessScreenshotPath = path.join(os.tmpdir(), 'eas-simulator-readiness.png');
     await retryAsync(
       async () => {
-        await spawn('xcrun', ['simctl', 'io', udid, 'screenshot', readinessScreenshotPath], {
-          env,
-        });
+        const { stdout: enumerateStdout } = await spawn(
+          'xcrun',
+          ['simctl', 'io', udid, 'enumerate'],
+          { env }
+        );
+        await spawn(
+          'xcrun',
+          [
+            'simctl',
+            'io',
+            udid,
+            'screenshot',
+            ...displayFlagForScreenshot(enumerateStdout),
+            readinessScreenshotPath,
+          ],
+          { env }
+        );
       },
       {
         retryOptions: {
@@ -298,22 +313,30 @@ export namespace IosSimulatorUtils {
     );
     await fs.promises.rm(readinessScreenshotPath, { force: true });
 
-    // Wait for data migration to complete before declaring the simulator ready
-    // Based on WebKit's approach: https://trac.webkit.org/changeset/231452/webkit
-    await retryAsync(
-      async () => {
-        const isDataMigrating = await isDataMigratorProcessRunning({ env });
-        if (isDataMigrating) {
-          throw new Error('com.apple.datamigrator still running');
-        }
-      },
-      {
-        retryOptions: {
-          retries: 30 * 60,
-          retryIntervalMs: 1_000,
-        },
-      }
+    const device = await getDeviceAsync({ udid, env });
+    const runtimes = await getAvailableRuntimesAsync({ env });
+    const iosVersion = semver.coerce(
+      runtimes.find(runtime => runtime.identifier === device?.runtime)?.version
     );
+    // From iOS 27.2 on, `com.apple.datamigrator` stays resident after the boot's data migration, so
+    // waiting for it to exit never ends; earlier runtimes exit it within about a minute of boot.
+    if (!iosVersion || semver.lt(iosVersion, '27.2.0')) {
+      // Based on WebKit's approach: https://trac.webkit.org/changeset/231452/webkit
+      await retryAsync(
+        async () => {
+          const isDataMigrating = await isDataMigratorProcessRunning({ env });
+          if (isDataMigrating) {
+            throw new Error('com.apple.datamigrator still running');
+          }
+        },
+        {
+          retryOptions: {
+            retries: 30 * 60,
+            retryIntervalMs: 1_000,
+          },
+        }
+      );
+    }
   }
 
   export async function disableApsdAsync({
@@ -522,6 +545,20 @@ async function isLaunchctlServiceLoadedAsync({
   }
 }
 
+/**
+ * `simctl io screenshot` refuses to choose between the iPhone Duo's two integrated screens on
+ * iOS 27.2, while the simctl in Xcode 15.3 rejects a numeric `--display` ("Device does not have a
+ * '1' display port"), so the flag is passed only when there is a choice to make.
+ */
+function displayFlagForScreenshot(enumerateStdout: string): string[] {
+  // `simctl io enumerate` lists each screen as an indented "(n) Name:" header followed by its fields.
+  const screens = enumerateStdout.split(/^ {4}\(\d+\) .*:$/m);
+  const integratedScreenIds = screens
+    .filter(screen => /^\s*Screen Type: Integrated$/m.test(screen))
+    .flatMap(screen => screen.match(/^\s*Screen ID: (\d+)$/m)?.[1] ?? []);
+  return integratedScreenIds.length > 1 ? [`--display=${integratedScreenIds[0]}`] : [];
+}
+
 function parseUdidFromBootstatusStdout(stdout: string): IosSimulatorUuid | null {
   const matches = stdout.match(/^Monitoring boot status for .+ \((.+)\)\.$/m);
   if (!matches) {

packages/build-tools/src/utils/__integration-tests__/AndroidEmulatorUtils.test.ts

@@ -13,6 +13,8 @@ import {
   AndroidVirtualDeviceName,
 } from '../AndroidEmulatorUtils';
 import { retryAsync } from '../retry';
+import { AndroidEmulatorLogFiles } from '../androidEmulatorLogFiles';
+import { ALL_ANDROID_EMULATOR_LOG_SOURCES } from '../androidEmulatorLogSources';
 
 // We need to use real fs for cloning devices to work.
 jest.unmock('fs');
@@ -78,6 +80,7 @@ describe('AndroidEmulatorUtils', () => {
         logger: createMockLogger({ logToConsole: true }),
       });
       ({ serialId } = await AndroidEmulatorUtils.startAsync({
+        logCapture: new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES }),
         deviceName,
         env: { ...process.env, ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL: '1' },
         logcatDirectory,
@@ -105,6 +108,7 @@ describe('AndroidEmulatorUtils', () => {
       logger: createMockLogger({ logToConsole: true }),
     });
     const { serialId, emulatorPromise } = await AndroidEmulatorUtils.startAsync({
+      logCapture: new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES }),
       deviceName,
       env: { ...process.env, ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL: '1' },
       logcatDirectory,
@@ -135,6 +139,7 @@ describe('AndroidEmulatorUtils', () => {
 
     const { serialId: serialIdClone, emulatorPromise: emulatorPromiseClone } =
       await AndroidEmulatorUtils.startAsync({
+        logCapture: new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES }),
         deviceName: cloneDeviceName,
         env: { ...process.env, ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL: '1' },
         logcatDirectory,
@@ -172,6 +177,7 @@ describe('AndroidEmulatorUtils', () => {
     });
 
     const { serialId, emulatorPromise } = await AndroidEmulatorUtils.startAsync({
+      logCapture: new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES }),
       deviceName,
       env: { ...process.env, ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL: '1' },
       logcatDirectory,
@@ -226,6 +232,7 @@ describe('AndroidEmulatorUtils', () => {
           });
 
           const startResult = await AndroidEmulatorUtils.startAsync({
+            logCapture: new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES }),
             deviceName,
             env: envForAttempt,
             logcatDirectory,
@@ -309,6 +316,7 @@ describe('AndroidEmulatorUtils', () => {
         logger,
       });
       const startResult = await AndroidEmulatorUtils.startAsync({
+        logCapture: new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES }),
         deviceName,
         env: { ...process.env, ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL: '1' },
         logcatDirectory: testLogcatDirectory,
@@ -319,7 +327,16 @@ describe('AndroidEmulatorUtils', () => {
       await AndroidEmulatorUtils.waitForReadyAsync({ serialId, env: process.env });
       await retryAsync(
         async () => {
-          const contents = await fs.promises.readFile(startResult.emulatorOutputPath, 'utf-8');
+          const filename = (await fs.promises.readdir(testLogcatDirectory)).find(file =>
+            file.endsWith('-emulator.log')
+          );
+          if (!filename) {
+            throw new Error('Missing emulator output');
+          }
+          const contents = await fs.promises.readFile(
+            path.join(testLogcatDirectory, filename),
+            'utf-8'
+          );
           if (!contents.includes('Android emulator version')) {
             throw new Error('Did not find the emulator version in emulator process output yet.');
           }
@@ -340,7 +357,16 @@ describe('AndroidEmulatorUtils', () => {
 
       await retryAsync(
         async () => {
-          const contents = await fs.promises.readFile(startResult.logcatOutputPath, 'utf-8');
+          const filename = (await fs.promises.readdir(testLogcatDirectory)).find(file =>
+            file.endsWith('-logcat.log')
+          );
+          if (!filename) {
+            throw new Error('Missing logcat output');
+          }
+          const contents = await fs.promises.readFile(
+            path.join(testLogcatDirectory, filename),
+            'utf-8'
+          );
           if (!contents.includes(marker)) {
             throw new Error(`Did not find marker ${marker} in logcat output yet.`);
           }
@@ -384,6 +410,7 @@ describe('AndroidEmulatorUtils', () => {
     });
 
     const { serialId, emulatorPromise } = await AndroidEmulatorUtils.startAsync({
+      logCapture: new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES }),
       deviceName,
       env: { ...process.env, ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL: '1' },
       logcatDirectory,

packages/build-tools/src/utils/__tests__/AndroidEmulatorUtils.test.ts

@@ -1,6 +1,6 @@
 import { SystemError } from '@expo/eas-build-job';
 import spawn from '@expo/turtle-spawn';
-import { EventEmitter, once } from 'node:events';
+import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
 import { Socket } from 'node:net';
 import os from 'node:os';
@@ -14,6 +14,17 @@ import {
   AndroidVirtualDeviceName,
 } from '../AndroidEmulatorUtils';
 import { retryAsync } from '../retry';
+import { AndroidEmulatorLogRing } from '../androidEmulatorLogCapture';
+import { AndroidEmulatorLogFiles } from '../androidEmulatorLogFiles';
+import {
+  ALL_ANDROID_EMULATOR_LOG_SOURCES,
+  AndroidEmulatorLogSourcesSchema,
+} from '../androidEmulatorLogSources';
+
+jest.unmock('fs');
+jest.unmock('node:fs');
+jest.unmock('fs/promises');
+jest.unmock('node:fs/promises');
 
 jest.mock('@expo/turtle-spawn', () => ({
   __esModule: true,
@@ -35,9 +46,11 @@ const mockedRetryAsync = jest.mocked(retryAsync);
 
 describe('AndroidEmulatorUtils', () => {
   let temporaryDirectories: string[] = [];
+  let homeDirectory: string;
 
-  beforeEach(() => {
-    temporaryDirectories = [];
+  beforeEach(async () => {
+    homeDirectory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'android-utils-home-'));
+    temporaryDirectories = [homeDirectory];
     jest.mocked(Sentry.capture).mockReset();
     mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);
     mockedRetryAsync.mockImplementation(async fn => await fn(0));
@@ -55,7 +68,7 @@ describe('AndroidEmulatorUtils', () => {
   describe(AndroidEmulatorUtils.createAsync, () => {
     it('applies an explicit LCD configuration after screen scaling', async () => {
       const deviceName = 'eas-simulator' as AndroidVirtualDeviceName;
-      const avdDirectory = `/home/expo/.android/avd/${deviceName}.avd`;
+      const avdDirectory = `${homeDirectory}/.android/avd/${deviceName}.avd`;
       await fs.promises.mkdir(avdDirectory, { recursive: true });
       await fs.promises.writeFile(
         `${avdDirectory}/config.ini`,
@@ -83,7 +96,7 @@ describe('AndroidEmulatorUtils', () => {
         lcdHeight: 1600,
         lcdDensity: 262,
         env: {
-          HOME: '/home/expo',
+          HOME: homeDirectory,
           ANDROID_EMULATOR_ADJUST_SCREEN: '1',
           ANDROID_EMULATOR_ADJUST_HEAP_SIZE: '0',
         },
@@ -141,7 +154,7 @@ describe('AndroidEmulatorUtils', () => {
       ['device-run-session-id', 4096],
     ])('configures memory for session %s without an LCD override', async (sessionId, ramSize) => {
       const deviceName = 'generic-emulator' as AndroidVirtualDeviceName;
-      const avdDirectory = `/home/expo/.android/avd/${deviceName}.avd`;
+      const avdDirectory = `${homeDirectory}/.android/avd/${deviceName}.avd`;
       const initialConfig = ['skin.path=pixel_9', 'showDeviceFrame=yes'].join('\n');
       await fs.promises.mkdir(avdDirectory, { recursive: true });
       await fs.promises.writeFile(`${avdDirectory}/config.ini`, initialConfig);
@@ -157,7 +170,7 @@ describe('AndroidEmulatorUtils', () => {
         lcdHeight: null,
         lcdDensity: null,
         env: {
-          HOME: '/home/expo',
+          HOME: homeDirectory,
           ANDROID_EMULATOR_ADJUST_HEAP_SIZE: '0',
           DEVICE_RUN_SESSION_ID: sessionId,
         },
@@ -172,6 +185,24 @@ describe('AndroidEmulatorUtils', () => {
   });
 
   describe(AndroidEmulatorUtils.startAsync, () => {
+    let buildCapture: AndroidEmulatorLogFiles;
+    beforeEach(() => {
+      buildCapture = new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES });
+    });
+    afterEach(async () => {
+      await buildCapture.finishAsync();
+    });
+
+    async function logFile(directory: string, source: 'logcat' | 'emulator'): Promise<string> {
+      const filename = (await fs.promises.readdir(directory)).find(file =>
+        file.endsWith(`-${source}.log`)
+      );
+      if (!filename) {
+        throw new Error(`Missing ${source} log in ${directory}`);
+      }
+      return path.join(directory, filename);
+    }
+
     function mockSuccessfulStart(deviceName: AndroidVirtualDeviceName) {
       // Under `stdio: 'pipe'` these are net.Sockets, which is what startAsync
       // narrows on before unref-ing them.
@@ -202,35 +233,31 @@ describe('AndroidEmulatorUtils', () => {
       return { child };
     }
 
-    it('captures logcat and emulator process output', async () => {
+    it('names log files after the device and detaches the emulator', async () => {
       const outputDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'logcat-staging-'));
       temporaryDirectories.push(outputDir);
       const deviceName = 'eas-simulator' as AndroidVirtualDeviceName;
       const { child } = mockSuccessfulStart(deviceName);
-      const createWriteStreamSpy = jest.spyOn(fs, 'createWriteStream');
 
-      const result = await AndroidEmulatorUtils.startAsync({
+      await AndroidEmulatorUtils.startAsync({
+        logCapture: buildCapture,
         deviceName,
         env: process.env,
         logcatDirectory: outputDir,
       });
+      child.emit('close');
+      await buildCapture.finishAsync();
 
-      expect(result.logcatOutputPath).toMatch(
+      expect(await logFile(outputDir, 'logcat')).toMatch(
         new RegExp(`^${outputDir}/eas-simulator-[a-f0-9]{8}-[a-f0-9]{4}-logcat\\.log$`)
       );
-      expect(result.emulatorOutputPath).toMatch(
+      expect(await logFile(outputDir, 'emulator')).toMatch(
         new RegExp(`^${outputDir}/eas-simulator-[a-f0-9]{8}-[a-f0-9]{4}-emulator\\.log$`)
       );
-      await expect(fs.promises.access(result.logcatOutputPath)).resolves.toBeUndefined();
-      await expect(fs.promises.access(result.emulatorOutputPath)).resolves.toBeUndefined();
       expect(mockedSpawn).toHaveBeenCalledWith(
         expect.stringMatching(/\/emulator\/emulator$/),
-        expect.arrayContaining(['-logcat', '*:v', '-logcat-output', result.logcatOutputPath]),
-        expect.objectContaining({
-          detached: true,
-          stdio: ['ignore', 'pipe', 'pipe'],
-          ignoreStdio: true,
-        })
+        expect.any(Array),
+        expect.objectContaining({ detached: true, ignoreStdio: true })
       );
       expect(mockedSpawn).not.toHaveBeenCalledWith(
         'adb',
@@ -242,28 +269,91 @@ describe('AndroidEmulatorUtils', () => {
       // for as long as the emulator runs.
       expect(child.stdout.unref).toHaveBeenCalled();
       expect(child.stderr.unref).toHaveBeenCalled();
-      const emulatorOutputStream = createWriteStreamSpy.mock.results[0].value;
-      const stderrWriteSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
-      const writeError = Object.assign(new Error('disk full'), { code: 'ENOSPC' });
-      emulatorOutputStream.emit('error', writeError);
-      emulatorOutputStream.emit('error', writeError);
-      expect(stderrWriteSpy).toHaveBeenCalledTimes(2);
-      expect(Sentry.capture).toHaveBeenCalledTimes(1);
-      expect(Sentry.capture).toHaveBeenCalledWith(
-        'Failed to write Android emulator process output',
-        writeError,
-        {
-          level: 'warning',
-          tags: { errorCode: 'ENOSPC' },
-          extras: {
-            deviceName,
-            emulatorOutputPath: result.emulatorOutputPath,
-          },
-        }
+    });
+
+    it.each([
+      { sources: [] },
+      { sources: ['emulator-output'] },
+      { sources: ['device-logcat'] },
+      { sources: ['emulator-output', 'device-logcat'] },
+    ])('records only $sources', async ({ sources }) => {
+      const outputDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'selected-logs-'));
+      temporaryDirectories.push(outputDir);
+      const deviceName = 'selected-emulator' as AndroidVirtualDeviceName;
+      const { child } = mockSuccessfulStart(deviceName);
+      const stdoutPipe = jest.spyOn(child.stdout, 'pipe');
+      const stderrPipe = jest.spyOn(child.stderr, 'pipe');
+      const capture = new AndroidEmulatorLogFiles({
+        sources: AndroidEmulatorLogSourcesSchema.parse(sources),
+      });
+      const prepare = jest.spyOn(capture, 'prepareLogcatOutputAsync');
+      await AndroidEmulatorUtils.startAsync({
+        logCapture: capture,
+        deviceName,
+        env: {},
+        logcatDirectory: outputDir,
+      });
+      const capturesOutput = sources.includes('emulator-output');
+      const capturesLogcat = sources.includes('device-logcat');
+      const [, args, options] = mockedSpawn.mock.calls[0];
+      expect(prepare).toHaveBeenCalledTimes(capturesLogcat ? 1 : 0);
+      expect(args.includes('-logcat')).toBe(capturesLogcat);
+      expect(args.includes('-logcat-output')).toBe(capturesLogcat);
+      expect(options?.stdio).toEqual([
+        'ignore',
+        capturesOutput ? 'pipe' : 'ignore',
+        capturesOutput ? 'pipe' : 'ignore',
+      ]);
+      expect(stdoutPipe).toHaveBeenCalledTimes(capturesOutput ? 1 : 0);
+      expect(stderrPipe).toHaveBeenCalledTimes(capturesOutput ? 1 : 0);
+      if (capturesOutput) {
+        child.stdout.emit('data', Buffer.from('stdout marker\n'));
+        child.stderr.emit('data', Buffer.from('stderr marker\n'));
+        child.emit('close');
+      }
+      await capture.finishAsync();
+      if (capturesOutput) {
+        await expect(
+          fs.promises.readFile(await logFile(outputDir, 'emulator'), 'utf8')
+        ).resolves.toBe('stdout marker\nstderr marker\n');
+      }
+      const files = await fs.promises.readdir(outputDir);
+      expect(files).toHaveLength(sources.length);
+      expect(files.some(file => file.endsWith('-logcat.log'))).toBe(capturesLogcat);
+      expect(files.some(file => file.endsWith('-emulator.log'))).toBe(capturesOutput);
+    });
+
+    it('routes a session logcat through the capture pipe and closes it with the emulator', async () => {
+      const outputDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'bounded-logs-'));
+      temporaryDirectories.push(outputDir);
+      const deviceName = 'bounded-emulator' as AndroidVirtualDeviceName;
+      const { child } = mockSuccessfulStart(deviceName);
+      const capture = new AndroidEmulatorLogRing({ sources: ['device-logcat'] });
+      const close = jest.fn();
+      const createPipe = jest.spyOn(capture, 'prepareLogcatOutputAsync').mockResolvedValue({
+        path: '/logcat.pipe',
+        close,
+        closed: Promise.resolve(),
+      });
+      await AndroidEmulatorUtils.startAsync({
+        deviceName,
+        env: {},
+        logcatDirectory: outputDir,
+        logCapture: capture,
+      });
+      expect(createPipe).toHaveBeenCalledWith(
+        expect.stringMatching(
+          new RegExp(`^${outputDir}/bounded-emulator-[a-f0-9]{8}-[a-f0-9]{4}-logcat\\.log$`)
+        )
       );
-      const emulatorOutputStreamClosed = once(emulatorOutputStream, 'close');
+      expect(mockedSpawn.mock.calls[0][1]).toEqual(
+        expect.arrayContaining(['-logcat-output', '/logcat.pipe'])
+      );
+      expect(close).not.toHaveBeenCalled();
       child.emit('close');
-      await emulatorOutputStreamClosed;
+      await capture.finishAsync();
+      expect(close).toHaveBeenCalledTimes(1);
+      expect(await fs.promises.readdir(outputDir)).toEqual([]);
     });
 
     it('spawns the emulator directly with the same arguments when there is no launch gate', async () => {
@@ -273,7 +363,8 @@ describe('AndroidEmulatorUtils', () => {
       mockSuccessfulStart(deviceName);
       const env = { ANDROID_EMULATOR_EXTRA_ARGS: '-gpu swiftshader_indirect' };
 
-      const result = await AndroidEmulatorUtils.startAsync({
+      await AndroidEmulatorUtils.startAsync({
+        logCapture: buildCapture,
         deviceName,
         env,
         logcatDirectory: outputDir,
@@ -294,7 +385,7 @@ describe('AndroidEmulatorUtils', () => {
             '-logcat',
             '*:v',
             '-logcat-output',
-            result.logcatOutputPath,
+            await logFile(outputDir, 'logcat'),
             '-avd',
             deviceName,
             '-accel',
@@ -331,7 +422,8 @@ describe('AndroidEmulatorUtils', () => {
           : gatedSpawn(command, args, options as any)) as any);
       const admitAsync = jest.fn().mockResolvedValue(undefined);
 
-      const result = await AndroidEmulatorUtils.startAsync({
+      await AndroidEmulatorUtils.startAsync({
+        logCapture: buildCapture,
         deviceName,
         env: {},
         logcatDirectory: outputDir,
@@ -358,7 +450,7 @@ describe('AndroidEmulatorUtils', () => {
           '-logcat',
           '*:v',
           '-logcat-output',
-          result.logcatOutputPath,
+          await logFile(outputDir, 'logcat'),
           '-avd',
           deviceName,
           '-accel',
@@ -395,6 +487,7 @@ describe('AndroidEmulatorUtils', () => {
 
       await expect(
         AndroidEmulatorUtils.startAsync({
+          logCapture: buildCapture,
           deviceName,
           env: {},
           logcatDirectory: outputDir,
@@ -419,6 +512,7 @@ describe('AndroidEmulatorUtils', () => {
       try {
         await expect(
           AndroidEmulatorUtils.startAsync({
+            logCapture: buildCapture,
             deviceName,
             env: process.env,
             logcatDirectory: outputDir,

packages/build-tools/src/utils/__tests__/IosSimulatorUtils.test.ts

@@ -252,24 +252,179 @@ describe('IosSimulatorUtils', () => {
   });
 
   describe(IosSimulatorUtils.waitForReadyAsync, () => {
+    const readinessScreenshotPath = path.join(os.tmpdir(), 'eas-simulator-readiness.png');
+
     it('takes the readiness screenshot into a writable temp file, not /dev/null', async () => {
-      await IosSimulatorUtils.waitForReadyAsync({
-        udid: 'test-udid' as any,
-        env: process.env,
-      });
+      mockSimulator({});
+
+      await IosSimulatorUtils.waitForReadyAsync({ udid: 'test-udid' as any, env: process.env });
 
       expect(mockedSpawn).toHaveBeenCalledWith(
         'xcrun',
-        [
-          'simctl',
-          'io',
-          'test-udid',
-          'screenshot',
-          path.join(os.tmpdir(), 'eas-simulator-readiness.png'),
-        ],
+        ['simctl', 'io', 'test-udid', 'screenshot', readinessScreenshotPath],
         { env: process.env }
       );
     });
+
+    it('names the first integrated screen when the device has several (iPhone Duo on iOS 27.2)', async () => {
+      // Connected screens from `xcrun simctl io <udid> enumerate` on an iPhone Duo (iOS 27.2).
+      mockSimulator({
+        version: '27.2',
+        connectedScreens: `    Connected Screens:
+    (1) LCD:
+        Screen ID: 1
+        Screen Type: Integrated
+    (2) TVOut:
+        Screen ID: 2
+        Screen Type: TVOut
+    (3) LCD-1:
+        Screen ID: 3
+        Screen Type: Integrated
+`,
+      });
+
+      await IosSimulatorUtils.waitForReadyAsync({ udid: 'test-udid' as any, env: process.env });
+
+      expect(mockedSpawn).toHaveBeenCalledWith(
+        'xcrun',
+        ['simctl', 'io', 'test-udid', 'screenshot', '--display=1', readinessScreenshotPath],
+        { env: process.env }
+      );
+    });
+
+    it('takes the first listed integrated screen, skipping screens that are not integrated', async () => {
+      mockSimulator({
+        connectedScreens: `    Connected Screens:
+    (1) TVOut:
+        Screen ID: 1
+        Screen Type: TVOut
+    (2) LCD-1:
+        Screen ID: 5
+        Screen Type: Integrated
+    (3) LCD:
+        Screen ID: 3
+        Screen Type: Integrated
+`,
+      });
+
+      await IosSimulatorUtils.waitForReadyAsync({ udid: 'test-udid' as any, env: process.env });
+
+      expect(mockedSpawn).toHaveBeenCalledWith(
+        'xcrun',
+        ['simctl', 'io', 'test-udid', 'screenshot', '--display=5', readinessScreenshotPath],
+        { env: process.env }
+      );
+    });
+
+    it('keeps the plain screenshot when the device has one integrated screen', async () => {
+      mockSimulator({
+        connectedScreens: `    Connected Screens:
+    (2) TVOut:
+        Screen ID: 2
+        Screen Type: TVOut
+    (1) LCD:
+        Screen ID: 1
+        Screen Type: Integrated
+`,
+      });
+
+      await IosSimulatorUtils.waitForReadyAsync({ udid: 'test-udid' as any, env: process.env });
+
+      expect(mockedSpawn).toHaveBeenCalledWith(
+        'xcrun',
+        ['simctl', 'io', 'test-udid', 'screenshot', readinessScreenshotPath],
+        { env: process.env }
+      );
+    });
+
+    it.each(['27.2', '27.3', '28.0'])(
+      'does not wait for com.apple.datamigrator to exit on iOS %s, where it stays resident',
+      async version => {
+        mockSimulator({ version, dataMigratorRunning: true });
+
+        await IosSimulatorUtils.waitForReadyAsync({ udid: 'test-udid' as any, env: process.env });
+
+        expect(mockedSpawn).not.toHaveBeenCalledWith('ps', expect.anything(), expect.anything());
+      }
+    );
+
+    it.each(['27.1', '26.3.1', '18.6'])(
+      'waits for com.apple.datamigrator to exit on iOS %s',
+      async version => {
+        mockSimulator({ version, dataMigratorRunning: true });
+
+        await expect(
+          IosSimulatorUtils.waitForReadyAsync({ udid: 'test-udid' as any, env: process.env })
+        ).rejects.toThrow('com.apple.datamigrator still running');
+        expect(mockedSpawn).toHaveBeenCalledWith('ps', ['-eo', 'pid,comm'], { env: process.env });
+      }
+    );
+
+    it('waits for com.apple.datamigrator to exit when the device is not listed', async () => {
+      mockSimulator({ listed: false, dataMigratorRunning: true });
+
+      await expect(
+        IosSimulatorUtils.waitForReadyAsync({ udid: 'test-udid' as any, env: process.env })
+      ).rejects.toThrow('com.apple.datamigrator still running');
+    });
+
+    it('waits for com.apple.datamigrator to exit when the runtime reports no version', async () => {
+      mockSimulator({ version: null, dataMigratorRunning: true });
+      await expect(
+        IosSimulatorUtils.waitForReadyAsync({ udid: 'test-udid' as any, env: process.env })
+      ).rejects.toThrow('com.apple.datamigrator still running');
+    });
+
+    function mockSimulator({
+      version = '26.4',
+      listed = true,
+      connectedScreens = '',
+      dataMigratorRunning = false,
+    }: {
+      version?: string | null;
+      listed?: boolean;
+      connectedScreens?: string;
+      dataMigratorRunning?: boolean;
+    }): void {
+      const runtime = 'com.apple.CoreSimulator.SimRuntime.iOS-26-4';
+      const otherRuntime = {
+        identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-27-2',
+        version: '27.2',
+      };
+      mockedSpawn.mockImplementation((async (command: string, args: string[]) => {
+        if (command === 'ps') {
+          return {
+            stdout: dataMigratorRunning
+              ? '  123 /sbin/launchd_sim\n  456 /Library/Developer/CoreSimulator/Volumes/iOS_23E244/XPCServices/com.apple.datamigrator.xpc/com.apple.datamigrator\n'
+              : '  123 /sbin/launchd_sim\n',
+            stderr: '',
+          } as any;
+        }
+        if (args.includes('runtimes')) {
+          return {
+            stdout: JSON.stringify({
+              runtimes: [
+                otherRuntime,
+                version === null ? { identifier: runtime } : { identifier: runtime, version },
+              ],
+            }),
+            stderr: '',
+          } as any;
+        }
+        if (args.includes('list')) {
+          return {
+            stdout: JSON.stringify({
+              devices: { [runtime]: listed ? [{ udid: 'test-udid' }] : [] },
+            }),
+            stderr: '',
+          } as any;
+        }
+        if (args.includes('enumerate')) {
+          return { stdout: connectedScreens, stderr: '' } as any;
+        }
+        return { stdout: '', stderr: '' } as any;
+      }) as any);
+    }
   });
 
   describe(IosSimulatorUtils.disableApsdAsync, () => {
@@ -427,6 +582,15 @@ describe('IosSimulatorUtils', () => {
       expect(mockedSpawn).not.toHaveBeenCalled();
     });
 
+    it('uppercases a udid given in lowercase, matching how simctl lists devices', async () => {
+      await expect(
+        IosSimulatorUtils.resolveUdidAsync({
+          deviceIdentifier: '8027f627-9534-4679-85bf-0f14aff228e8' as any,
+          env: process.env,
+        })
+      ).resolves.toBe('8027F627-9534-4679-85BF-0F14AFF228E8');
+    });
+
     it('resolves a device name to the first available device with that name', async () => {
       mockedSpawn.mockResolvedValue({
         stdout: JSON.stringify({

packages/build-tools/src/utils/__tests__/androidEmulatorLogCapture.test.ts

@@ -0,0 +1,271 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import fs, { type FileHandle } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { PassThrough, Readable } from 'node:stream';
+
+import { Sentry } from '../../sentry';
+import {
+  AndroidEmulatorLogRing,
+  MAX_ANDROID_LOG_BYTES_PER_SOURCE,
+} from '../androidEmulatorLogCapture';
+import { ALL_ANDROID_EMULATOR_LOG_SOURCES } from '../androidEmulatorLogSources';
+
+jest.unmock('fs');
+jest.unmock('node:fs');
+jest.unmock('fs/promises');
+jest.unmock('node:fs/promises');
+jest.mock('../../sentry', () => ({ Sentry: { capture: jest.fn() } }));
+
+let directory: string;
+beforeEach(async () => {
+  directory = await fs.mkdtemp(path.join(os.tmpdir(), 'android-capped-logs-'));
+});
+afterEach(async () => {
+  jest.restoreAllMocks();
+  await fs.rm(directory, { recursive: true, force: true });
+});
+
+function createCapture(maxBytes?: number): AndroidEmulatorLogRing {
+  return new AndroidEmulatorLogRing({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES, maxBytes });
+}
+
+/** `==== <name> <ISO time> ====\n` */
+function markerLength(name: string): number {
+  return name.length + 36;
+}
+
+async function record(
+  capture: AndroidEmulatorLogRing,
+  file: string,
+  text: string,
+  source: 'emulator-output' | 'device-logcat' = 'emulator-output'
+): Promise<void> {
+  const input = Readable.from([Buffer.from(text)]);
+  capture.attach(input, file, source);
+  await once(input, 'end');
+  await capture.finishFileAsync(file);
+}
+
+function trackOpenedFiles(): FileHandle[] {
+  const opened: FileHandle[] = [];
+  const open = fs.open;
+  jest.spyOn(fs, 'open').mockImplementation(async (file, flags, mode) => {
+    const handle = await open(file, flags, mode);
+    opened.push(handle);
+    return handle;
+  });
+  return opened;
+}
+
+it('keeps one ring per source across launches and names each launch that wrote', async () => {
+  const capture = createCapture(120);
+  const emulatorRing = path.join(directory, 'emulator-output.log');
+  const logcatRing = path.join(directory, 'device-logcat.log');
+  await record(capture, path.join(directory, 'first-emulator.log'), 'first!');
+  await record(capture, path.join(directory, 'retry-emulator.log'), 'second!!');
+  await record(capture, path.join(directory, 'one-logcat.log'), 'device log', 'device-logcat');
+  const logs = await capture.finishAsync();
+  const seen = markerLength('first-emulator') + 6 + 1 + markerLength('retry-emulator') + 8;
+  expect(logs).toEqual([
+    { filePath: emulatorRing, source: 'emulator-output', bytesSeen: seen },
+    { filePath: logcatRing, source: 'device-logcat', bytesSeen: markerLength('one-logcat') + 10 },
+  ]);
+  expect(await fs.readFile(emulatorRing, 'utf8')).toMatch(
+    /^==== first-emulator \S+ ====\nfirst!\n==== retry-emulator \S+ ====\nsecond!!$/
+  );
+  expect(await fs.readFile(logcatRing, 'utf8')).toMatch(/^==== one-logcat \S+ ====\ndevice log$/);
+  expect((await fs.readdir(directory)).sort()).toEqual([
+    'device-logcat.log',
+    'emulator-output.log',
+  ]);
+});
+
+it('keeps the tail of the final launch when the ring overflows', async () => {
+  const capture = createCapture(120);
+  await record(capture, path.join(directory, 'first-emulator.log'), 'first!');
+  await record(capture, path.join(directory, 'retry-emulator.log'), 'y'.repeat(100));
+  const [log] = await capture.finishAsync();
+  const result = await fs.readFile(log.filePath, 'utf8');
+  expect(result).toHaveLength(120);
+  expect(result.endsWith('y'.repeat(100))).toBe(true);
+  expect(result).not.toContain('first!');
+  expect(log.bytesSeen).toBeGreaterThan(120);
+});
+
+it('keeps the tail of a wrapped ring in order', async () => {
+  const capture = createCapture(10);
+  const file = path.join(directory, 'wrapped.log');
+  const input = new PassThrough();
+  capture.attach(input, file, 'emulator-output');
+  for (const piece of ['0123', '4567', '89ab', 'cdef']) {
+    input.write(piece);
+  }
+  const [log] = await capture.finishAsync();
+  expect(await fs.readFile(log.filePath, 'utf8')).toBe('6789abcdef');
+});
+
+it('lets overlapping launches of one source share the ring', async () => {
+  const capture = createCapture(400);
+  const a = new PassThrough();
+  const b = new PassThrough();
+  capture.attach(a, path.join(directory, 'clone-1.log'), 'emulator-output');
+  capture.attach(b, path.join(directory, 'clone-2.log'), 'emulator-output');
+  a.write('from clone 1 first\n');
+  b.write('from clone 2\n');
+  a.write('from clone 1 second\n');
+  const [log] = await capture.finishAsync();
+  const result = await fs.readFile(log.filePath, 'utf8');
+  expect(result).toMatch(/==== clone-1 \S+ ====\n/);
+  expect(result).toMatch(/==== clone-2 \S+ ====\n/);
+  expect(result).toContain('from clone 2\n');
+  expect(result.indexOf('from clone 1 first')).toBeLessThan(result.indexOf('from clone 1 second'));
+  expect(result).toHaveLength(log.bytesSeen);
+  a.end('ignored after cleanup');
+  b.end('also ignored');
+  expect(a.readableFlowing).toBe(true);
+  expect(b.readableFlowing).toBe(true);
+});
+
+it('drains a real FIFO beyond 20 MiB, retains the tail, and closes after the writer exits', async () => {
+  const file = path.join(directory, 'logcat.log');
+  const capture = createCapture();
+  const pipe = await capture.prepareLogcatOutputAsync(file);
+  expect((await fs.stat(pipe.path)).isFIFO()).toBe(true);
+  const writer = spawn(
+    process.execPath,
+    [
+      '-e',
+      `
+    const fs = require('node:fs');
+    const fd = fs.openSync(process.argv[1], 'w');
+    fs.writeSync(fd, 'BEGIN\\n');
+    const chunk = Buffer.alloc(64 * 1024, 'x');
+    for (let i = 0; i < 1024; i++) {
+      let offset = 0;
+      while (offset < chunk.length) offset += fs.writeSync(fd, chunk, offset);
+    }
+    fs.writeSync(fd, '\\nEND');
+    fs.closeSync(fd);
+  `,
+      pipe.path,
+    ],
+    { stdio: 'ignore' }
+  );
+  try {
+    expect(await once(writer, 'close')).toEqual([0, null]);
+    pipe.close();
+    pipe.close();
+    await pipe.closed;
+    const logs = await capture.finishAsync();
+    const ring = path.join(directory, 'device-logcat.log');
+    const result = await fs.readFile(ring);
+    expect(result.length).toBe(MAX_ANDROID_LOG_BYTES_PER_SOURCE);
+    expect(result.subarray(0, 4).toString()).toBe('xxxx');
+    expect(result.subarray(-4).toString()).toBe('\nEND');
+    expect(logs).toEqual([
+      {
+        filePath: ring,
+        source: 'device-logcat',
+        bytesSeen: 64 * 1024 * 1024 + 10 + markerLength('logcat'),
+      },
+    ]);
+    await expect(fs.stat(pipe.path)).rejects.toMatchObject({ code: 'ENOENT' });
+  } finally {
+    writer.kill();
+    pipe.close();
+  }
+}, 30_000);
+
+it('closes an unused logcat pipe when the emulator fails to launch', async () => {
+  const file = path.join(directory, 'empty.log');
+  const capture = createCapture();
+  const pipe = await capture.prepareLogcatOutputAsync(file);
+  pipe.close();
+  await pipe.closed;
+  await expect(fs.stat(pipe.path)).rejects.toMatchObject({ code: 'ENOENT' });
+  const ring = path.join(directory, 'device-logcat.log');
+  expect(await capture.finishAsync()).toEqual([
+    { filePath: ring, source: 'device-logcat', bytesSeen: 0 },
+  ]);
+  expect((await fs.stat(ring)).size).toBe(0);
+}, 5_000);
+
+it('keeps draining the FIFO after capture finishes while the emulator is alive', async () => {
+  const file = path.join(directory, 'live-logcat.log');
+  const capture = createCapture(10);
+  const output = await capture.prepareLogcatOutputAsync(file);
+  const writer = spawn(
+    process.execPath,
+    [
+      '-e',
+      `
+    const fs = require('node:fs');
+    const fd = fs.openSync(process.argv[1], 'w');
+    process.stdout.write('ready');
+    process.stdin.once('data', () => {
+      const chunk = Buffer.alloc(64 * 1024, 'x');
+      for (let i = 0; i < 128; i++) {
+        let offset = 0;
+        while (offset < chunk.length) offset += fs.writeSync(fd, chunk, offset);
+      }
+      fs.closeSync(fd);
+      process.stdin.destroy();
+    });
+  `,
+      output.path,
+    ],
+    { stdio: ['pipe', 'pipe', 'pipe'] }
+  );
+  try {
+    await once(writer.stdout, 'data');
+    await capture.finishAsync();
+    writer.stdin.end('go');
+    expect(await once(writer, 'close')).toEqual([0, null]);
+    output.close();
+    await output.closed;
+    expect((await fs.stat(path.join(directory, 'device-logcat.log'))).size).toBe(0);
+    await expect(fs.stat(output.path)).rejects.toMatchObject({ code: 'ENOENT' });
+  } finally {
+    writer.kill();
+    output.close();
+    await output.closed;
+  }
+}, 10_000);
+
+it('reports a disk write failure once and continues draining output', async () => {
+  const capture = createCapture(10);
+  const input = new PassThrough();
+  const file = path.join(directory, 'failed.log');
+  const diskError = Object.assign(new Error('full'), { code: 'ENOSPC' });
+  jest.spyOn(fs, 'open').mockRejectedValueOnce(diskError);
+  capture.attach(input, file, 'emulator-output');
+  input.write('first');
+  input.write('second');
+  await capture.finishAsync();
+  input.end('more');
+  expect(Sentry.capture).toHaveBeenCalledTimes(1);
+  expect(Sentry.capture).toHaveBeenCalledWith(
+    'Failed to write Android diagnostic log',
+    diskError,
+    expect.anything()
+  );
+  expect(input.readableFlowing).toBe(true);
+});
+
+it('closes the file and reports once when sealing fails', async () => {
+  const opened = trackOpenedFiles();
+  const capture = createCapture(10);
+  await record(capture, path.join(directory, 'wrapped.log'), '0123456789abcdef');
+  const diskError = Object.assign(new Error('full'), { code: 'ENOSPC' });
+  jest.spyOn(opened[0], 'truncate').mockRejectedValueOnce(diskError);
+  await capture.finishAsync();
+  expect(opened[0].fd).toBe(-1);
+  expect(Sentry.capture).toHaveBeenCalledTimes(1);
+  expect(Sentry.capture).toHaveBeenCalledWith(
+    'Failed to write Android diagnostic log',
+    diskError,
+    expect.anything()
+  );
+});

packages/build-tools/src/utils/__tests__/androidEmulatorLogFiles.test.ts

@@ -0,0 +1,89 @@
+import { once } from 'node:events';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PassThrough, Readable } from 'node:stream';
+
+import { Sentry } from '../../sentry';
+import { AndroidEmulatorLogFiles } from '../androidEmulatorLogFiles';
+import { ALL_ANDROID_EMULATOR_LOG_SOURCES } from '../androidEmulatorLogSources';
+
+jest.unmock('fs');
+jest.unmock('node:fs');
+jest.unmock('fs/promises');
+jest.unmock('node:fs/promises');
+jest.mock('../../sentry', () => ({ Sentry: { capture: jest.fn() } }));
+
+let directory: string;
+beforeEach(async () => {
+  directory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'android-build-logs-'));
+});
+afterEach(async () => {
+  jest.restoreAllMocks();
+  await fs.promises.rm(directory, { recursive: true, force: true });
+});
+
+function trackWriteStreams(): fs.WriteStream[] {
+  const streams: fs.WriteStream[] = [];
+  const createWriteStream = fs.createWriteStream;
+  jest.spyOn(fs, 'createWriteStream').mockImplementation((file, options) => {
+    const stream = createWriteStream(file, options);
+    streams.push(stream);
+    return stream;
+  });
+  return streams;
+}
+
+it('appends one plain file per launch, closes it when the launch ends, and finalizes nothing', async () => {
+  const streams = trackWriteStreams();
+  const capture = new AndroidEmulatorLogFiles({ sources: ALL_ANDROID_EMULATOR_LOG_SOURCES });
+  const first = path.join(directory, 'first-emulator.log');
+  const stdout = Readable.from([Buffer.from('out ')]);
+  const stderr = Readable.from([Buffer.from('err')]);
+  capture.attach(stdout, first, 'emulator-output');
+  capture.attach(stderr, first, 'emulator-output');
+  await Promise.all([once(stdout, 'end'), once(stderr, 'end')]);
+  await capture.finishFileAsync(first);
+  expect(streams).toHaveLength(1);
+  expect(streams[0].closed).toBe(true);
+  expect(await fs.promises.readFile(first, 'utf8')).toBe('out err');
+  const retry = path.join(directory, 'retry-emulator.log');
+  const input = Readable.from([Buffer.from('retry')]);
+  capture.attach(input, retry, 'emulator-output');
+  await once(input, 'end');
+  expect(await capture.finishAsync()).toEqual([]);
+  expect(streams[1].closed).toBe(true);
+  expect((await fs.promises.readdir(directory)).sort()).toEqual([
+    'first-emulator.log',
+    'retry-emulator.log',
+  ]);
+});
+
+it('gives the emulator the logcat file itself without creating a FIFO', async () => {
+  const capture = new AndroidEmulatorLogFiles({ sources: ['device-logcat'] });
+  const file = path.join(directory, 'build-logcat.log');
+  const output = await capture.prepareLogcatOutputAsync(file);
+  expect(output.path).toBe(file);
+  expect(await fs.promises.readdir(directory)).toEqual(['build-logcat.log']);
+  output.close();
+  await output.closed;
+  expect(await capture.finishAsync()).toEqual([]);
+});
+
+it('reports a write failure once and keeps draining the emulator', async () => {
+  const capture = new AndroidEmulatorLogFiles({ sources: ['emulator-output'] });
+  const input = new PassThrough();
+  const file = path.join(directory, 'missing-directory', 'failed.log');
+  capture.attach(input, file, 'emulator-output');
+  input.write('first');
+  await capture.finishFileAsync(file);
+  input.write('second');
+  input.end('more');
+  expect(Sentry.capture).toHaveBeenCalledTimes(1);
+  expect(Sentry.capture).toHaveBeenCalledWith(
+    'Failed to write Android diagnostic log',
+    expect.objectContaining({ code: 'ENOENT' }),
+    expect.anything()
+  );
+  expect(input.readableFlowing).toBe(true);
+});

packages/build-tools/src/utils/__tests__/simulatorPackageVersion.test.ts

@@ -0,0 +1,78 @@
+import spawn from '@expo/turtle-spawn';
+
+import { resolveSimulatorPackageVersionAsync } from '../simulatorPackageVersion';
+
+jest.mock('@expo/turtle-spawn');
+
+beforeEach(() => jest.resetAllMocks());
+
+it.each(['1.2.3', 'v1.2.3', '1.2.3-beta.1', '1.2.3-beta.1+build.2', 'v1.2.3+build.2'])(
+  'compares an exact request without a registry call (%s)',
+  async requested => {
+    await expect(
+      resolveSimulatorPackageVersionAsync('serve-sim', requested, { env: {} })
+    ).resolves.toBe(requested.replace(/^v/, ''));
+    expect(spawn).not.toHaveBeenCalled();
+  }
+);
+
+it.each([
+  ['serve-sim', '@expo/serve-sim'],
+  ['agent-device', 'agent-device'],
+  ['argent', '@swmansion/argent'],
+  ['appium', 'appium'],
+] as const)('checks the current dist-tag for %s', async (engine, name) => {
+  jest.mocked(spawn).mockResolvedValue({ stdout: '"1.2.4"' } as never);
+  const env = { NPM_CONFIG_REGISTRY: 'https://registry.example' };
+  const signal = new AbortController().signal;
+  await expect(
+    resolveSimulatorPackageVersionAsync(engine, 'latest', { env, signal })
+  ).resolves.toBe('1.2.4');
+  expect(spawn).toHaveBeenCalledWith(
+    'npm',
+    [
+      'view',
+      `${name}@latest`,
+      'version',
+      '--json',
+      '--prefer-online',
+      '--prefer-offline=false',
+      '--offline=false',
+      '--fetch-retries=0',
+    ],
+    { env, signal, stdio: 'pipe', timeout: 30_000 }
+  );
+});
+
+it('selects the newest matching version from range metadata without relying on output order', async () => {
+  jest.mocked(spawn).mockResolvedValue({ stdout: '["3.9.0","3.10.0","3.8.0"]' } as never);
+  await expect(resolveSimulatorPackageVersionAsync('appium', '^3', { env: {} })).resolves.toBe(
+    '3.10.0'
+  );
+});
+
+it.each(['not json', '{}', '[]', '"latest"'])(
+  'rejects unusable registry output (%s)',
+  async stdout => {
+    jest.mocked(spawn).mockResolvedValue({ stdout } as never);
+    await expect(
+      resolveSimulatorPackageVersionAsync('serve-sim', 'latest', { env: {} })
+    ).rejects.toThrow();
+  }
+);
+
+it('preserves registry lookup failures instead of trusting the prepared version', async () => {
+  const error = new Error('registry unavailable');
+  jest.mocked(spawn).mockRejectedValue(error);
+  await expect(resolveSimulatorPackageVersionAsync('argent', 'latest', { env: {} })).rejects.toBe(
+    error
+  );
+});
+
+it('does not look up a cancelled request', async () => {
+  const signal = AbortSignal.abort(new Error('cancelled'));
+  await expect(
+    resolveSimulatorPackageVersionAsync('serve-sim', 'latest', { env: {}, signal })
+  ).rejects.toThrow('cancelled');
+  expect(spawn).not.toHaveBeenCalled();
+});

packages/build-tools/src/utils/__tests__/upterm.test.ts

@@ -1,7 +1,10 @@
 import { SystemError } from '@expo/eas-build-job';
 import downloadFile from '@expo/downloader';
 import spawn from '@expo/turtle-spawn';
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
 
 import { createMockLogger } from '../../__tests__/utils/logger';
 import { BuildContext } from '../../context';
@@ -164,10 +167,14 @@ describe(startUptermHostAsync, () => {
     };
   }
 
-  function makeCtx(env: Record<string, string> = {}): BuildContext {
+  function makeCtx(
+    env: Record<string, string> = {},
+    buildDirectory = '/workingdir/build'
+  ): BuildContext {
     return {
       logger: createMockLogger(),
       env,
+      buildDirectory,
     } as unknown as BuildContext;
   }
 
@@ -227,6 +234,33 @@ describe(startUptermHostAsync, () => {
     );
   });
 
+  it('starts each client shell in the build directory', async () => {
+    const realFs = jest.requireActual<typeof import('node:fs')>('node:fs');
+    const tmpDir = realFs.mkdtempSync(path.join(os.tmpdir(), 'eas-upterm-join-'));
+    try {
+      const buildDirectory = path.join(tmpDir, "it's $HOME `pwd`", 'build');
+      realFs.mkdirSync(buildDirectory, { recursive: true });
+
+      await startUptermHostAsync(makeCtx({}, buildDirectory), { relayServerUrl: 'wss://r' });
+
+      const joinScriptCall = mockedFs.writeFile.mock.calls.find(
+        ([file]) => file === '/tmp/eas-ssh-1/join.sh'
+      );
+      const joinScriptPath = path.join(tmpDir, 'join.sh');
+      realFs.writeFileSync(joinScriptPath, String(joinScriptCall?.[1]));
+      const result = spawnSync('bash', [joinScriptPath], {
+        cwd: tmpDir,
+        env: { PATH: process.env.PATH, HOME: tmpDir },
+        input: 'pwd\n',
+        encoding: 'utf8',
+      });
+
+      expect(result.stdout.trim()).toBe(buildDirectory);
+    } finally {
+      realFs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   it('downloads from GCS into a fresh temp dir when upterm is not on PATH', async () => {
     uptermOnPath = false;
 

packages/build-tools/src/utils/__tests__/warmSimulator.test.ts

@@ -1,9 +1,18 @@
 import spawn from '@expo/turtle-spawn';
 import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { setTimeout as sleepAsync } from 'node:timers/promises';
+import { z } from 'zod';
 
-import { runSimulatorLauncherAsync, stopWarmSimulatorAsync } from '../warmSimulator';
+import {
+  readPreparedSimulatorToolAsync,
+  runSimulatorLauncherAsync,
+  stopWarmSimulatorAsync,
+} from '../warmSimulator';
 
 jest.mock('@expo/turtle-spawn');
+jest.mock('node:timers/promises');
 
 const originalPlatform = process.platform;
 
@@ -11,12 +20,86 @@ beforeEach(() => {
   Object.defineProperty(process, 'platform', { value: 'darwin' });
   jest.resetAllMocks();
   jest.mocked(spawn).mockResolvedValue({ stdout: '{"ok":true}' } as never);
+  jest.spyOn(os, 'uptime').mockReturnValue(600);
+  jest.spyOn(fs, 'access').mockRejectedValue(new Error('no startup script'));
+  jest.mocked(sleepAsync).mockResolvedValue(undefined);
 });
 afterEach(() => {
   jest.restoreAllMocks();
   Object.defineProperty(process, 'platform', { value: originalPlatform });
 });
 
+it('reads different prepared tool schemas without Appium-specific fields', async () => {
+  const directory = path.join(os.homedir(), 'Library', 'Caches', 'expo-simulator-startup');
+  const appium = { home: path.join(directory, 'appium'), version: '3.9.0', xcuitest: '12.22.8' };
+  const otherTool = { version: '2.4.0' };
+  const expoGo = { sdk: '55.0.0', url: 'https://example.test/ExpoGo.tar.gz' };
+  const read = jest
+    .spyOn(fs, 'readFile')
+    .mockResolvedValue(
+      JSON.stringify({ tools: { appium, 'other-tool': otherTool, 'expo-go': expoGo } })
+    );
+
+  await expect(
+    readPreparedSimulatorToolAsync(
+      'appium',
+      z.object({ home: z.string(), version: z.string(), xcuitest: z.string() })
+    )
+  ).resolves.toEqual(appium);
+  const prepared = await readPreparedSimulatorToolAsync(
+    'other-tool',
+    z.object({ version: z.string() })
+  );
+  expect(prepared?.version).toBe('2.4.0');
+  await expect(
+    readPreparedSimulatorToolAsync('expo-go', z.object({ sdk: z.string(), url: z.string() }))
+  ).resolves.toEqual(expoGo);
+  expect(read.mock.calls).toEqual([
+    [path.join(directory, 'prepared.json'), 'utf8'],
+    [path.join(directory, 'prepared.json'), 'utf8'],
+    [path.join(directory, 'prepared.json'), 'utf8'],
+  ]);
+  expect(spawn).not.toHaveBeenCalled();
+});
+
+it.each(['missing-tool', 'toString'])(
+  'does not invent %s metadata from schema defaults or inherited properties',
+  async tool => {
+    jest.spyOn(fs, 'readFile').mockResolvedValue('{"tools":{}}');
+    await expect(
+      readPreparedSimulatorToolAsync(tool, z.unknown().default({ version: '1.2.3' }))
+    ).resolves.toBeUndefined();
+  }
+);
+
+it.each(['missing', 'invalid JSON', 'invalid fields', 'missing tool', 'older format'])(
+  'ignores prepared tool metadata with %s',
+  async failure => {
+    const read = jest.spyOn(fs, 'readFile');
+    switch (failure) {
+      case 'missing':
+        read.mockRejectedValue(Object.assign(new Error('missing'), { code: 'ENOENT' }));
+        break;
+      case 'invalid JSON':
+        read.mockResolvedValue('not JSON');
+        break;
+      case 'invalid fields':
+        read.mockResolvedValue(JSON.stringify({ tools: { tool: { version: 42 } } }));
+        break;
+      case 'missing tool':
+        read.mockResolvedValue('{"tools":{}}');
+        break;
+      case 'older format':
+        read.mockResolvedValue('{"appium":"3.9.0","xcuitest":"12.22.8","home":"/old/home"}');
+        break;
+    }
+    await expect(
+      readPreparedSimulatorToolAsync('tool', z.object({ version: z.string() }))
+    ).resolves.toBeUndefined();
+    expect(spawn).not.toHaveBeenCalled();
+  }
+);
+
 it('runs the launcher version that start recorded and returns its output', async () => {
   jest.spyOn(fs, 'readFile').mockResolvedValue('{"launcherVersion":"27.1.0"}');
   await expect(runSimulatorLauncherAsync(['claim', 'serve-sim'], { env: {} })).resolves.toBe(
@@ -59,3 +142,79 @@ it('does nothing on other platforms', async () => {
   await stopWarmSimulatorAsync({});
   expect(spawn).not.toHaveBeenCalled();
 });
+
+const missing = Object.assign(new Error('missing'), { code: 'ENOENT' });
+const warmEnv = { EAS_USE_WARM_SIMULATOR: '1', EAS_OVERRIDE_PACKAGE_MANAGER: 'bun' };
+
+it('waits for startup to write state, then claims with the recorded launcher version', async () => {
+  jest.mocked(os.uptime).mockReturnValue(10);
+  jest.mocked(fs.access).mockResolvedValue();
+  jest
+    .spyOn(fs, 'readFile')
+    .mockRejectedValueOnce(missing)
+    .mockRejectedValueOnce(missing)
+    .mockResolvedValue('{"launcherVersion":"27.6.0"}');
+  await runSimulatorLauncherAsync(['claim', 'serve-sim'], { env: warmEnv });
+  expect(sleepAsync).toHaveBeenCalled();
+  expect(spawn).toHaveBeenCalledWith(
+    'bun',
+    ['x', '@expo/[email protected]', 'claim', 'serve-sim'],
+    expect.objectContaining({ env: warmEnv })
+  );
+});
+
+it.each([
+  ['a later session request', ['claim', 'serve-sim'], warmEnv, 300, true],
+  ['a system without startup', ['claim', 'serve-sim'], warmEnv, 10, false],
+  ['a job without warmup', ['claim', 'serve-sim'], {}, 10, true],
+  ['stop', ['stop'], warmEnv, 10, true],
+  ['prepare-tools', ['prepare-tools'], warmEnv, 10, true],
+])('does not wait for %s', async (_name, args, env, uptime, installed) => {
+  jest.mocked(os.uptime).mockReturnValue(uptime);
+  if (installed) {
+    jest.mocked(fs.access).mockResolvedValue();
+  }
+  jest.spyOn(fs, 'readFile').mockRejectedValue(missing);
+  await runSimulatorLauncherAsync(args, { env });
+  expect(sleepAsync).not.toHaveBeenCalled();
+  expect(spawn).toHaveBeenCalled();
+});
+
+it('times out before invoking claim so its caller can stop warmup before starting cold', async () => {
+  jest.mocked(os.uptime).mockReturnValue(10);
+  jest.mocked(fs.access).mockResolvedValue();
+  jest.spyOn(fs, 'readFile').mockRejectedValue(missing);
+  let now = 0;
+  jest.spyOn(Date, 'now').mockImplementation(() => now);
+  jest.mocked(sleepAsync).mockImplementation(async delay => {
+    now += delay ?? 0;
+  });
+  await expect(runSimulatorLauncherAsync(['claim', 'serve-sim'], { env: warmEnv })).rejects.toThrow(
+    'Timed out waiting for the warm Simulator launcher to start.'
+  );
+  expect(now).toBe(60_000);
+  expect(spawn).not.toHaveBeenCalled();
+  await stopWarmSimulatorAsync(warmEnv);
+  expect(spawn).toHaveBeenCalledWith(
+    'bun',
+    ['x', '@expo/simulator-launcher@latest', 'stop'],
+    expect.anything()
+  );
+});
+
+it('cancels the missing-state wait without invoking claim', async () => {
+  jest.mocked(os.uptime).mockReturnValue(10);
+  jest.mocked(fs.access).mockResolvedValue();
+  jest.spyOn(fs, 'readFile').mockRejectedValue(missing);
+  const controller = new AbortController();
+  jest.mocked(sleepAsync).mockImplementation(async () => {
+    controller.abort(new Error('cancelled'));
+  });
+  await expect(
+    runSimulatorLauncherAsync(['claim', 'serve-sim'], {
+      env: warmEnv,
+      signal: controller.signal,
+    })
+  ).rejects.toThrow('cancelled');
+  expect(spawn).not.toHaveBeenCalled();
+});

packages/build-tools/src/utils/androidEmulatorLogCapture.ts

@@ -0,0 +1,250 @@
+import fs from 'node:fs';
+import { type FileHandle } from 'node:fs/promises';
+import path from 'node:path';
+import { type Readable, Writable } from 'node:stream';
+import { finished } from 'node:stream/promises';
+
+import { Sentry } from '../sentry';
+import { type AndroidEmulatorLogSource } from './androidEmulatorLogSources';
+import { createAndroidLogcatPipeAsync } from './androidLogcatPipe';
+
+export const MAX_ANDROID_LOG_BYTES_PER_SOURCE = 20 * 1024 * 1024;
+
+export type FinalizedAndroidEmulatorLog = {
+  readonly filePath: string;
+  readonly source: AndroidEmulatorLogSource;
+  readonly bytesSeen: number;
+};
+
+export type AndroidLogcatOutput = {
+  /** Where the emulator writes its logcat: a FIFO for sessions, the file itself for builds. */
+  path: string;
+  close: () => void;
+  /**
+   * Resolves once the pipe reader exited and the FIFO is removed. Emulator
+   * launch does not wait for it, because the emulator can outlive log
+   * collection; tests use it to observe the cleanup.
+   */
+  closed: Promise<void>;
+};
+
+/** Records emulator output per launch file; `getAndroidEmulatorLogCapture` picks the writer. */
+export type AndroidEmulatorLogCapture = {
+  readonly sources: readonly AndroidEmulatorLogSource[];
+  attach(input: Readable, filePath: string, source: AndroidEmulatorLogSource): void;
+  finishFileAsync(filePath: string): Promise<void>;
+  finishAsync(): Promise<readonly FinalizedAndroidEmulatorLog[]>;
+  prepareLogcatOutputAsync(filePath: string): Promise<AndroidLogcatOutput>;
+};
+
+/** One ring of `maxBytes` bytes: `writePos` wraps and the newest `retained` bytes end at it. */
+type Ring = {
+  filePath: string;
+  source: AndroidEmulatorLogSource;
+  /** Runs one file operation after every earlier one on the same handle. */
+  run: (operation: (handle: FileHandle) => Promise<void>) => Promise<void>;
+  sealed?: Promise<void>;
+  bytesSeen: number;
+  writePos: number;
+  retained: number;
+};
+
+/** One emulator launch. Launches of a source can overlap: clones, or a late exit. */
+type Launch = {
+  ring: Ring;
+  stream: Writable;
+  inputs: Set<Readable>;
+  done: Promise<void>;
+};
+
+/**
+ * One budget per session, shared by all emulator launches and retries.
+ *
+ * Each source has one ring file, `<source>.log` beside the launch files, so
+ * the last `maxBytes` bytes of a source survive across launches and the tail
+ * of the final attempt is always kept. A marker line names each launch that
+ * produced output. Overlapping launches share the ring, so their lines can
+ * interleave. Logcat arrives through a named pipe so the budget applies to it.
+ */
+export class AndroidEmulatorLogRing implements AndroidEmulatorLogCapture {
+  readonly sources: readonly AndroidEmulatorLogSource[];
+  private readonly maxBytes: number;
+  private readonly rings = new Map<AndroidEmulatorLogSource, Ring>();
+  private readonly launches = new Map<string, Launch>();
+  private finishing = false;
+
+  constructor({
+    sources,
+    maxBytes = MAX_ANDROID_LOG_BYTES_PER_SOURCE,
+  }: {
+    sources: readonly AndroidEmulatorLogSource[];
+    maxBytes?: number;
+  }) {
+    this.sources = sources;
+    this.maxBytes = maxBytes;
+  }
+
+  attach(input: Readable, filePath: string, source: AndroidEmulatorLogSource): void {
+    if (this.finishing) {
+      input.resume();
+      return;
+    }
+    let launch = this.launches.get(filePath);
+    if (!launch) {
+      launch = this.startLaunch(filePath, this.ringFor(filePath, source));
+      this.launches.set(filePath, launch);
+    }
+    launch.inputs.add(input);
+    input.pipe(launch.stream, { end: false });
+  }
+
+  async finishFileAsync(filePath: string): Promise<void> {
+    const launch = this.launches.get(filePath);
+    if (!launch) {
+      return;
+    }
+    for (const input of launch.inputs) {
+      input.unpipe(launch.stream);
+      // Keep draining: closing a full log must never block or break the emulator.
+      input.resume();
+    }
+    launch.inputs.clear();
+    launch.stream.end();
+    await launch.done;
+  }
+
+  async finishAsync(): Promise<readonly FinalizedAndroidEmulatorLog[]> {
+    this.finishing = true;
+    await Promise.all([...this.launches.keys()].map(file => this.finishFileAsync(file)));
+    await Promise.all([...this.rings.values()].map(ring => this.sealAsync(ring)));
+    // Every writer is closed, so uploads can reopen these files on each retry.
+    return [...this.rings.values()].map(({ filePath, source, bytesSeen }) => ({
+      filePath,
+      source,
+      bytesSeen,
+    }));
+  }
+
+  async prepareLogcatOutputAsync(filePath: string): Promise<AndroidLogcatOutput> {
+    const pipe = await createAndroidLogcatPipeAsync(`${filePath}.pipe`);
+    this.attach(pipe.stream, filePath, 'device-logcat');
+    const closed = pipe.closed.then(() => this.finishFileAsync(filePath)).catch(() => {});
+    return { path: pipe.path, close: pipe.close, closed };
+  }
+
+  private ringFor(filePath: string, source: AndroidEmulatorLogSource): Ring {
+    let ring = this.rings.get(source);
+    if (!ring) {
+      ring = this.open(path.join(path.dirname(filePath), `${source}.log`), source);
+      this.rings.set(source, ring);
+    }
+    return ring;
+  }
+
+  private open(filePath: string, source: AndroidEmulatorLogSource): Ring {
+    const file = fs.promises.open(filePath, 'w+');
+    // Handle open errors even if the process never produces output.
+    void file.catch(() => {});
+    let failed = false;
+    const report = (err: unknown): void => {
+      if (!failed) {
+        failed = true;
+        Sentry.capture(
+          'Failed to write Android diagnostic log',
+          err instanceof Error ? err : new Error(String(err)),
+          {
+            level: 'warning',
+            extras: { filePath, source },
+          }
+        );
+      }
+    };
+    let queue: Promise<void> = Promise.resolve();
+    const run = (operation: (handle: FileHandle) => Promise<void>): Promise<void> => {
+      queue = queue
+        .then(() => file)
+        .then(operation)
+        .catch(report);
+      return queue;
+    };
+    return { filePath, source, run, bytesSeen: 0, writePos: 0, retained: 0 };
+  }
+
+  private startLaunch(filePath: string, ring: Ring): Launch {
+    let marked = false;
+    const stream = new Writable({
+      write: (chunk: Buffer, _encoding, callback) => {
+        if (!marked) {
+          marked = true;
+          // Written before the first chunk only, so a silent launch leaves no trace.
+          const name = path.basename(filePath, '.log');
+          const marker = `==== ${name} ${new Date().toISOString()} ====\n`;
+          void this.write(ring, Buffer.from(ring.bytesSeen > 0 ? `\n${marker}` : marker));
+        }
+        void this.write(ring, chunk).then(() => callback());
+      },
+    });
+    return { ring, stream, inputs: new Set(), done: finished(stream) };
+  }
+
+  /** Account synchronously, then queue the I/O, so overlapping launches share one ring consistently. */
+  private write(ring: Ring, chunk: Buffer): Promise<void> {
+    const max = this.maxBytes;
+    ring.bytesSeen += chunk.length;
+    const data = chunk.length > max ? chunk.subarray(chunk.length - max) : chunk;
+    const position = ring.writePos;
+    const head = Math.min(data.length, max - position);
+    ring.writePos = (position + data.length) % max;
+    ring.retained = Math.min(ring.retained + data.length, max);
+    return ring.run(async handle => {
+      await writeAtAsync(handle, data.subarray(0, head), position);
+      await writeAtAsync(handle, data.subarray(head), 0);
+    });
+  }
+
+  /** Rewrite the ring in log order, drop the overwritten bytes, and close the file. */
+  private sealAsync(ring: Ring): Promise<void> {
+    ring.sealed ??= ring.run(async handle => {
+      try {
+        const { retained } = ring;
+        let start = ring.writePos - retained;
+        if (start < 0) {
+          start += this.maxBytes;
+        }
+        if (start > 0) {
+          const tail = Buffer.alloc(retained);
+          const head = Math.min(retained, this.maxBytes - start);
+          await readAtAsync(handle, tail.subarray(0, head), start);
+          await readAtAsync(handle, tail.subarray(head), 0);
+          await writeAtAsync(handle, tail, 0);
+        }
+        await handle.truncate(retained);
+      } finally {
+        await handle.close();
+      }
+    });
+    return ring.sealed;
+  }
+}
+
+async function writeAtAsync(handle: FileHandle, data: Buffer, position: number): Promise<void> {
+  for (let offset = 0; offset < data.length; ) {
+    const { bytesWritten } = await handle.write(
+      data,
+      offset,
+      data.length - offset,
+      position + offset
+    );
+    offset += bytesWritten;
+  }
+}
+
+async function readAtAsync(handle: FileHandle, into: Buffer, position: number): Promise<void> {
+  for (let offset = 0; offset < into.length; ) {
+    const { bytesRead } = await handle.read(into, offset, into.length - offset, position + offset);
+    if (bytesRead === 0) {
+      throw new Error(`Android diagnostic log ended before offset ${position + into.length}`);
+    }
+    offset += bytesRead;
+  }
+}

packages/build-tools/src/utils/androidEmulatorLogFiles.ts

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import { type Readable } from 'node:stream';
+import { finished } from 'node:stream/promises';
+
+import { Sentry } from '../sentry';
+import {
+  type AndroidEmulatorLogCapture,
+  type AndroidLogcatOutput,
+  type FinalizedAndroidEmulatorLog,
+} from './androidEmulatorLogCapture';
+import { type AndroidEmulatorLogSource } from './androidEmulatorLogSources';
+
+type LaunchFile = { stream: fs.WriteStream; inputs: Set<Readable> };
+
+/**
+ * Ordinary builds: one plain file per launch, appended without a budget and
+ * closed when the launch ends. The emulator writes logcat to its file directly.
+ * Nothing is finalized or uploaded.
+ */
+export class AndroidEmulatorLogFiles implements AndroidEmulatorLogCapture {
+  readonly sources: readonly AndroidEmulatorLogSource[];
+  private readonly files = new Map<string, LaunchFile>();
+
+  constructor({ sources }: { sources: readonly AndroidEmulatorLogSource[] }) {
+    this.sources = sources;
+  }
+
+  attach(input: Readable, filePath: string, source: AndroidEmulatorLogSource): void {
+    let file = this.files.get(filePath);
+    if (!file) {
+      const inputs = new Set<Readable>();
+      const stream = fs.createWriteStream(filePath, { flags: 'a' });
+      stream.once('error', err => {
+        Sentry.capture('Failed to write Android diagnostic log', err, {
+          level: 'warning',
+          extras: { filePath, source },
+        });
+        // The pipe detaches on error; keep draining so the emulator never blocks.
+        for (const attached of inputs) {
+          attached.resume();
+        }
+      });
+      file = { stream, inputs };
+      this.files.set(filePath, file);
+    }
+    file.inputs.add(input);
+    input.pipe(file.stream, { end: false });
+  }
+
+  async finishFileAsync(filePath: string): Promise<void> {
+    const file = this.files.get(filePath);
+    if (!file) {
+      return;
+    }
+    for (const input of file.inputs) {
+      input.unpipe(file.stream);
+      input.resume();
+    }
+    file.inputs.clear();
+    file.stream.end();
+    // A write error was reported when it happened.
+    await finished(file.stream).catch(() => {});
+  }
+
+  async finishAsync(): Promise<readonly FinalizedAndroidEmulatorLog[]> {
+    await Promise.all([...this.files.keys()].map(file => this.finishFileAsync(file)));
+    return [];
+  }
+
+  async prepareLogcatOutputAsync(filePath: string): Promise<AndroidLogcatOutput> {
+    await fs.promises.writeFile(filePath, '');
+    return { path: filePath, close: () => {}, closed: Promise.resolve() };
+  }
+}

packages/build-tools/src/utils/androidEmulatorLogSources.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const AndroidEmulatorLogSourcesSchema = z.array(
+  z.enum(['emulator-output', 'device-logcat'])
+);
+export type AndroidEmulatorLogSource = z.infer<typeof AndroidEmulatorLogSourcesSchema>[number];
+
+// Existing build workflows capture both sources. Device sessions pass their selection explicitly.
+export const ALL_ANDROID_EMULATOR_LOG_SOURCES: readonly AndroidEmulatorLogSource[] = [
+  'emulator-output',
+  'device-logcat',
+];

packages/build-tools/src/utils/androidLogcatPipe.ts

@@ -0,0 +1,66 @@
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { Socket } from 'node:net';
+import { type Readable } from 'node:stream';
+import { promisify } from 'node:util';
+
+import { Sentry } from '../sentry';
+
+/** Bridge the emulator's path-based logcat output to a readable stream. */
+export async function createAndroidLogcatPipeAsync(
+  pipePath: string
+): Promise<{ path: string; stream: Readable; close: () => void; closed: Promise<void> }> {
+  await promisify(execFile)('mkfifo', ['-m', '600', pipePath]);
+  // The sentinel keeps the FIFO open before emulator launch. The reader signals
+  // after opening it, so even a failed launch can close the pipe without a race.
+  const sentinel = fs.openSync(pipePath, fs.constants.O_RDWR | fs.constants.O_NONBLOCK);
+  let sentinelOpen = true;
+  const close = (): void => {
+    if (sentinelOpen) {
+      sentinelOpen = false;
+      fs.closeSync(sentinel);
+    }
+  };
+  const reader = spawn(
+    'sh',
+    ['-c', 'exec 3<"$1" || exit 1; printf ready >&2; exec cat <&3', 'android-logcat', pipePath],
+    {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }
+  );
+  const ready = new Promise<void>((resolve, reject) => {
+    reader.once('error', reject);
+    reader.once('exit', () =>
+      reject(new Error('Android logcat reader exited before opening its pipe.'))
+    );
+    reader.stderr.once('data', () => resolve());
+  });
+  reader.on('error', err => {
+    close();
+    Sentry.capture('Failed to read Android logcat pipe', err, { level: 'warning' });
+  });
+  const closed = new Promise<void>(resolve => {
+    reader.once('close', () => {
+      close();
+      void fs.promises
+        .rm(pipePath, { force: true })
+        .catch(() => {})
+        .then(resolve);
+    });
+  });
+  try {
+    await ready;
+  } catch (err) {
+    close();
+    reader.kill();
+    await closed;
+    throw err;
+  }
+  reader.unref();
+  for (const stream of [reader.stdout, reader.stderr]) {
+    if (stream instanceof Socket) {
+      stream.unref();
+    }
+  }
+  return { path: pipePath, stream: reader.stdout, close, closed };
+}

packages/build-tools/src/utils/artifacts.ts

@@ -1,4 +1,4 @@
-import { BuildJob, Job, ManagedArtifactType } from '@expo/eas-build-job';
+import { BuildJob, Job, ManagedArtifactType, formatBytes } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import fg from 'fast-glob';
 import fs from 'fs-extra';
@@ -175,34 +175,3 @@ async function getArtifactSize(artifact: string): Promise<number | undefined> {
     return undefined;
   }
 }
-
-// same as in
-// https://github.com/expo/eas-cli/blob/f0e3b648a1634266e7d723bd49a84866ab9b5801/packages/eas-cli/src/utils/files.ts#L33-L60
-export function formatBytes(bytes: number): string {
-  if (bytes === 0) {
-    return `0`;
-  }
-  let multiplier = 1;
-  if (bytes < 1024 * multiplier) {
-    return `${Math.floor(bytes)} B`;
-  }
-  multiplier *= 1024;
-  if (bytes < 102.4 * multiplier) {
-    return `${(bytes / multiplier).toFixed(1)} KB`;
-  }
-  if (bytes < 1024 * multiplier) {
-    return `${Math.floor(bytes / 1024)} KB`;
-  }
-  multiplier *= 1024;
-  if (bytes < 102.4 * multiplier) {
-    return `${(bytes / multiplier).toFixed(1)} MB`;
-  }
-  if (bytes < 1024 * multiplier) {
-    return `${Math.floor(bytes / multiplier)} MB`;
-  }
-  multiplier *= 1024;
-  if (bytes < 102.4 * multiplier) {
-    return `${(bytes / multiplier).toFixed(1)} GB`;
-  }
-  return `${Math.floor(bytes / 1024)} GB`;
-}

packages/build-tools/src/utils/simulatorPackageVersion.ts

@@ -0,0 +1,48 @@
+import { type BuildStepEnv } from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+import semver from 'semver';
+import { z } from 'zod';
+
+const PackageNames = {
+  'serve-sim': '@expo/serve-sim',
+  'agent-device': 'agent-device',
+  argent: '@swmansion/argent',
+  appium: 'appium',
+};
+
+/** Resolve an explicit request once, so comparison and installation use the same version. */
+export async function resolveSimulatorPackageVersionAsync(
+  engine: keyof typeof PackageNames,
+  requested: string,
+  { env, signal }: { env: BuildStepEnv; signal?: AbortSignal }
+): Promise<string> {
+  signal?.throwIfAborted();
+  const exact = semver.parse(requested);
+  if (exact) {
+    return exact.version + (exact.build.length ? `+${exact.build.join('.')}` : '');
+  }
+  // Use npm's configured registry and revalidate metadata instead of trusting a cached dist-tag.
+  const { stdout } = await spawn(
+    'npm',
+    [
+      'view',
+      `${PackageNames[engine]}@${requested}`,
+      'version',
+      '--json',
+      '--prefer-online',
+      '--prefer-offline=false',
+      '--offline=false',
+      '--fetch-retries=0',
+    ],
+    { env, signal, stdio: 'pipe', timeout: 30_000 }
+  );
+  signal?.throwIfAborted();
+  const version = z.string().refine(value => semver.valid(value) !== null);
+  const versions = z.union([version, z.array(version)]).parse(JSON.parse(stdout));
+  const candidates = typeof versions === 'string' ? [versions] : versions;
+  const resolved = semver.rsort(candidates)[0];
+  if (!resolved) {
+    throw new Error(`Could not resolve the requested ${engine} package version.`);
+  }
+  return resolved;
+}

packages/build-tools/src/utils/upterm.ts

@@ -202,7 +202,12 @@ export async function startUptermHostAsync(
   await spawn('ssh-keygen', ['-t', 'ed25519', '-N', '', '-f', hostKeyPath, '-q'], {
     logger: ctx.logger,
   });
-  await fs.writeFile(forceCommandPath, '#!/usr/bin/env bash\nexec bash -l\n', { mode: 0o755 });
+  const quotedBuildDirectory = `'${ctx.buildDirectory.replaceAll("'", "'\\''")}'`;
+  await fs.writeFile(
+    forceCommandPath,
+    `#!/usr/bin/env bash\ncd -- ${quotedBuildDirectory}\nexec bash -l\n`,
+    { mode: 0o755 }
+  );
 
   let currentProcess: SpawnPromise<SpawnResult> | null = null;
 

packages/build-tools/src/utils/warmSimulator.ts

@@ -1,6 +1,10 @@
 import { type BuildStepEnv } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
 import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { setTimeout as sleepAsync } from 'node:timers/promises';
+import { type ZodType, z } from 'zod';
 
 import {
   PackageManager,
@@ -8,6 +12,28 @@ import {
   resolvePackageExec,
 } from './packageManager';
 
+/** Read one tool's prepared metadata; its consumer defines the schema and compatibility checks. */
+export async function readPreparedSimulatorToolAsync<T>(
+  tool: string,
+  schema: ZodType<T>
+): Promise<T | undefined> {
+  const manifestPath = path.join(
+    os.homedir(),
+    'Library',
+    'Caches',
+    'expo-simulator-startup',
+    'prepared.json'
+  );
+  try {
+    const manifest = z
+      .object({ tools: z.record(z.string(), z.unknown()) })
+      .parse(JSON.parse(await fs.readFile(manifestPath, 'utf8')));
+    return Object.hasOwn(manifest.tools, tool) ? schema.parse(manifest.tools[tool]) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Runs a Simulator launcher command with the version that `start` recorded, which warmup cached.
  * The output can contain credentials, so it is returned and never logged.
@@ -16,10 +42,29 @@ export async function runSimulatorLauncherAsync(
   launcherArgs: string[],
   { env, signal }: { env: BuildStepEnv; signal?: AbortSignal }
 ): Promise<string> {
-  const version = await fs
+  signal?.throwIfAborted();
+  const contents = await fs
     .readFile('/tmp/expo-simulator-startup.json', 'utf8')
-    .then(text => JSON.parse(text).launcherVersion)
-    .catch(() => undefined);
+    .catch(async error => {
+      if (
+        error.code === 'ENOENT' &&
+        launcherArgs[0] === 'claim' &&
+        env.EAS_USE_WARM_SIMULATOR === '1' &&
+        process.platform === 'darwin' &&
+        os.uptime() < 300 &&
+        (await fs.access('/usr/local/share/vm-tools/startup.sh').then(
+          () => true,
+          () => false
+        ))
+      ) {
+        return await waitForLauncherStateFileAsync(signal);
+      }
+      return undefined;
+    });
+  let version: unknown;
+  try {
+    version = JSON.parse(contents ?? '{}').launcherVersion;
+  } catch {}
   const { command, args } = resolvePackageExec(
     resolveConfiguredPackageManager(env, PackageManager.BUN),
     [
@@ -31,6 +76,27 @@ export async function runSimulatorLauncherAsync(
   return stdout;
 }
 
+/** A session request can arrive before startup writes launcher state. */
+async function waitForLauncherStateFileAsync(signal?: AbortSignal): Promise<string> {
+  const deadline = Date.now() + 60_000;
+  for (;;) {
+    signal?.throwIfAborted();
+    try {
+      return await fs.readFile('/tmp/expo-simulator-startup.json', 'utf8');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw error;
+      }
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      // The claim caller must still stop warmup before it can start cold.
+      throw new Error('Timed out waiting for the warm Simulator launcher to start.');
+    }
+    await sleepAsync(Math.min(250, remaining), undefined, { signal });
+  }
+}
+
 /** Stops warmup; resolves only after the launcher confirms cleanup. */
 export async function stopWarmSimulatorAsync(env: BuildStepEnv): Promise<void> {
   if (process.platform === 'darwin') {

packages/create-eas-build-function/CHANGELOG.md

@@ -1,5 +1,29 @@
 # create-eas-build-function
 
+## 27.9.0
+
+No changes in this release.
+
+## 27.8.0
+
+No changes in this release.
+
+## 27.7.2
+
+No changes in this release.
+
+## 27.7.1
+
+No changes in this release.
+
+## 27.7.0
+
+No changes in this release.
+
+## 27.6.0
+
+No changes in this release.
+
 ## 27.5.0
 
 No changes in this release.

packages/create-eas-build-function/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-eas-build-function",
-  "version": "27.5.0",
+  "version": "27.9.0",
   "description": "Create functions for use in EAS Build custom builds.",
   "keywords": [
     "expo",
@@ -35,7 +35,7 @@
     "clean": "rimraf ./build/ \"*.tsbuildinfo\""
   },
   "dependencies": {
-    "@expo/steps": "27.5.0"
+    "@expo/steps": "27.9.0"
   },
   "devDependencies": {
     "@expo/package-manager": "1.9.10",

packages/downloader/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @expo/downloader
 
+## 27.9.0
+
+No changes in this release.
+
+## 27.8.0
+
+No changes in this release.
+
+## 27.7.2
+
+No changes in this release.
+
+## 27.7.1
+
+No changes in this release.
+
+## 27.7.0
+
+No changes in this release.
+
+## 27.6.0
+
+No changes in this release.
+
 ## 27.5.0
 
 No changes in this release.