[eas-cli] Mark default devices in simulator:devices (#4895)

* [build-tools] Count Android web preview input toward the session idle timeout

* [build-tools] Count an expo-device-hub read timeout as unobservable, not as a down device

.changeset/android-preview-idle-activity.md

@@ -0,0 +1,5 @@
+---
+'@expo/build-tools': minor
+---
+
+Count Android web preview input as session activity, so `max_idle_time_minutes` works on Android sessions. `eas/start_serve_sim_remote_session` no longer rejects it on Android; the API does not accept an idle timeout for Android web-preview-only sessions yet.

.changeset/simulator-device-defaults.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': patch
+---
+
+Mark the default device for each platform in `eas simulator:devices` and include `isDefault` in JSON output.

.changeset/tunnel-stop-timeout-not-fatal.md

@@ -0,0 +1,5 @@
+---
+'@expo/build-tools': patch
+---
+
+A successful remote device run session no longer fails when its agent-device, Appium, or Argent tunnel does not stop within its time-out.

.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,82 @@
 
 This is the log of notable changes to EAS CLI and related packages.
 
+## [27.10.0](https://github.com/expo/eas-cli/releases/tag/v27.10.0) - 2026-11-13
+
+### 🎉 New features
+
+- [build-tools] Add the experimental `experimental_emulator_capture_version` input to `eas/start_android_emulator`. The Android Emulator then preloads that version of the `expo-emulator-capture` agent and uses the lavapipe renderer, and later steps start expo-device-hub with the emulator capture on. When the agent cannot install, the emulator starts as before. Only web preview sessions support the capture for now, so other session types fail with an error when the input is set. ([#4827](https://github.com/expo/eas-cli/pull/4827) by [@krystofwoldrich-agent](https://github.com/krystofwoldrich-agent))
+- [eas-cli] Add `eas simulator:devices` to list the devices Expo suggests for a simulator session. ([#4879](https://github.com/expo/eas-cli/pull/4879) by [@brentvatne](https://github.com/brentvatne))
+
+### 🐛 Bug fixes
+
+- [build-tools] Retry the first ngrok tunnel open of a device run session up to two times when ngrok rejects it with ERR_NGROK_802. The first open now waits 19 seconds instead of 15, so a tunnel that opens late is kept instead of closed. Startup can be cancelled during the retries, and a preview tunnel stops retrying when its session host finishes. ([#4874](https://github.com/expo/eas-cli/pull/4874) by [@szdziedzic](https://github.com/szdziedzic))
+- [eas-cli] Include the parent CLI command in telemetry to distinguish nested commands from direct usage. ([#4876](https://github.com/expo/eas-cli/pull/4876) by [@davidmokos](https://github.com/davidmokos))
+- [build-tools] Run worker SSH sessions as detached upterm sessions that reconnect on their own under the same session ID, and stop them with `upterm session stop`. ([#4857](https://github.com/expo/eas-cli/pull/4857) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- [build-tools] Run the command a client passes with `eas workflow:ssh <id> <command>` in worker SSH sessions, in the build directory. ([#4863](https://github.com/expo/eas-cli/pull/4863) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- [build-tools] Always download upterm for worker SSH sessions instead of using an `upterm` found on `PATH`. ([#4859](https://github.com/expo/eas-cli/pull/4859) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+### 🧹 Chores
+
+- [eas-cli][build-tools] Bump Node.js to 22.23.5 to fix the CVEs in the [November 2026 Node.js security releases](https://nodejs.org/en/blog/vulnerability/november-2026-security-releases). ([#4889](https://github.com/expo/eas-cli/pull/4889) by [@ramonclaudio](https://github.com/ramonclaudio))
+
+## [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

cli-versions.json

@@ -1,4 +1,4 @@
 {
-  "STAGING": "27.5.0",
-  "PRODUCTION": "27.5.0"
+  "STAGING": "27.10.0",
+  "PRODUCTION": "27.10.0"
 }

lerna.json

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

mise.toml

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

packages/build-tools/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @expo/build-tools
 
+## 27.10.0
+
+### Minor Changes
+
+- Add the experimental `experimental_emulator_capture_version` input to `eas/start_android_emulator`. The Android Emulator then preloads that version of the `expo-emulator-capture` agent and uses the lavapipe renderer, and later steps start expo-device-hub with the emulator capture on. When the agent cannot install, the emulator starts as before. Only web preview sessions support the capture for now, so other session types fail with an error when the input is set. ([#4827](https://github.com/expo/eas-cli/pull/4827) by [@krystofwoldrich-agent](https://github.com/krystofwoldrich-agent))
+
+### Patch Changes
+
+- Retry the first ngrok tunnel open of a device run session up to two times when ngrok rejects it with ERR_NGROK_802. The first open now waits 19 seconds instead of 15, so a tunnel that opens late is kept instead of closed. Startup can be cancelled during the retries, and a preview tunnel stops retrying when its session host finishes. ([#4874](https://github.com/expo/eas-cli/pull/4874) by [@szdziedzic](https://github.com/szdziedzic))
+- Run worker SSH sessions as detached upterm sessions that reconnect on their own under the same session ID, and stop them with `upterm session stop`. ([#4857](https://github.com/expo/eas-cli/pull/4857) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- Run the command a client passes with `eas workflow:ssh <id> <command>` in worker SSH sessions, in the build directory. ([#4863](https://github.com/expo/eas-cli/pull/4863) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+- Always download upterm for worker SSH sessions instead of using an `upterm` found on `PATH`. ([#4859](https://github.com/expo/eas-cli/pull/4859) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+## 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

packages/build-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/build-tools",
-  "version": "27.6.0",
+  "version": "27.10.0",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",
@@ -26,7 +26,7 @@
     "build:egress-guard": "resources/egress-guard/build.sh",
     "test:egress-guard": "resources/egress-guard/tests/run-policy-tests.sh && resources/egress-guard/tests/run-guard-tests.sh",
     "typecheck": "tsc",
-    "generate-appium-commands": "mise exec [email protected].4 -- node scripts/generate-appium-commands.js",
+    "generate-appium-commands": "mise exec [email protected].5 -- node scripts/generate-appium-commands.js",
     "prepack": "rimraf dist \"*.tsbuildinfo\" && yarn gql && tsc -p tsconfig.build.json",
     "jest-unit": "jest --config jest/unit-config.ts",
     "jest-integration": "jest --config jest/integration-config.ts",
@@ -42,17 +42,17 @@
   "dependencies": {
     "@expo/config": "55.0.10",
     "@expo/config-plugins": "55.0.7",
-    "@expo/downloader": "27.6.0",
-    "@expo/eas-build-job": "27.6.0",
+    "@expo/downloader": "27.10.0",
+    "@expo/eas-build-job": "27.10.0",
     "@expo/env": "^0.4.0",
-    "@expo/logger": "27.6.0",
+    "@expo/logger": "27.10.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.6.0",
-    "@expo/template-file": "27.6.0",
-    "@expo/turtle-spawn": "27.6.0",
+    "@expo/steps": "27.10.0",
+    "@expo/template-file": "27.10.0",
+    "@expo/turtle-spawn": "27.10.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__/startAgentDeviceRemoteSession-orchestration.test.ts

@@ -201,6 +201,21 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
     expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
   });
 
+  it('does not fail a session when only the agent-device tunnel cannot stop', async () => {
+    const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
+    const tunnelError = new Error('Ngrok tunnel stop timed out after 4000ms.');
+    mockTunnelStopAsync.mockRejectedValueOnce(tunnelError);
+
+    await expect(runAsync(logger, BuildRuntimePlatform.LINUX)).resolves.toBeUndefined();
+
+    expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+    expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: tunnelError },
+      'Could not stop the agent-device tunnel during remote session teardown.'
+    );
+  });
+
   it('uses the warm daemon after adoption and starts no daemon of its own', async () => {
     const logger = { info: jest.fn(), warn: jest.fn(), child: jest.fn().mockReturnThis() };
     const warmServer = { port: 3200 } as never;
@@ -918,6 +933,21 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
       await expect(session).rejects.toBe(failed);
     });
 
+    it('reports a startup Stop when only the agent-device tunnel cannot stop', async () => {
+      const stopped = new DeviceRunSessionStoppedError('stopped during startup');
+      let tasks!: StartupTasks;
+      const session = startSession(startup => {
+        tasks = startup;
+        return { booted: Promise.resolve(), ready: tasks.untilAborted(new Promise(() => {})) };
+      });
+      session.catch(() => {});
+      await flushAsync();
+      mockTunnelStopAsync.mockRejectedValueOnce(new Error('tunnel stop timed out'));
+      tasks.abort(stopped);
+      await expect(session).rejects.toBe(stopped);
+      expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
+    });
+
     it('retires startup monitoring after reporting and before lifetime waiting', async () => {
       const retired = deferred();
       const retiring = jest.fn(() => retired.promise);

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',

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

@@ -9,6 +9,9 @@ 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 { installEmulatorCaptureAsync } from '../../utils/emulatorCapture';
 import { createStartAndroidEmulatorBuildFunction } from '../startAndroidEmulator';
 
 jest.mock('@expo/turtle-spawn', () => ({
@@ -24,6 +27,13 @@ jest.mock('../../utils/androidLocalEgress', () => ({
   resolveAndroidEmulatorLocalEgressAsync: jest.fn(),
 }));
 
+jest.mock('../../utils/androidEmulatorLogs');
+
+jest.mock('../../utils/emulatorCapture', () => ({
+  ...jest.requireActual('../../utils/emulatorCapture'),
+  installEmulatorCaptureAsync: jest.fn(),
+}));
+
 jest.mock('../../../utils/AndroidEmulatorUtils', () => ({
   AndroidEmulatorUtils: {
     defaultSystemImagePackage: 'system-images;android-30;default;x86_64',
@@ -34,6 +44,7 @@ jest.mock('../../../utils/AndroidEmulatorUtils', () => ({
     waitForReadyAsync: jest.fn(),
     disableWindowAndTransitionAnimationsAsync: jest.fn(),
     deleteAsync: jest.fn(),
+    findFreeConsolePortAsync: jest.fn(),
   },
 }));
 
@@ -50,7 +61,12 @@ function createStep(callInputs?: Record<string, unknown>, envOverrides?: NodeJS.
   const step = fn.createBuildStepFromFunctionCall(globalCtx, {
     callInputs,
   });
-  return Object.assign(step, { logger });
+  return Object.assign(step, { logger, globalCtx });
+}
+
+/** The logger that the step function gets: a child of the base logger. */
+function stepLogger(step: ReturnType<typeof createStep>) {
+  return jest.mocked(step.logger.child).mock.results[0].value;
 }
 
 function createStartResult(serialId: string) {
@@ -62,6 +78,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 +111,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 +156,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),
@@ -436,4 +482,170 @@ describe(createStartAndroidEmulatorBuildFunction, () => {
       }
     );
   });
+
+  describe('experimental emulator capture', () => {
+    const LIBRARY = '/tmp/package/libexpo_emulator_capture.so';
+    const mockedInstall = jest.mocked(installEmulatorCaptureAsync);
+
+    function captureStart(port: number) {
+      return {
+        deviceName: 'EasAndroidDevice01',
+        env: expect.any(Object),
+        logcatDirectory: '/tmp/logcat-directory',
+        logCapture: expect.objectContaining({ sources: ['emulator-output', 'device-logcat'] }),
+        consolePort: port,
+        extraArgs: ['-gpu', 'lavapipe'],
+        extraEnv: {
+          LD_PRELOAD: LIBRARY,
+          EXPO_EMULATOR_CAPTURE_SOCKET: `/tmp/job/expo-emulator-capture/emulator-${port}.sock`,
+        },
+      };
+    }
+
+    beforeEach(() => {
+      mockedInstall.mockReset().mockResolvedValue(LIBRARY);
+      mockedAndroidUtils.findFreeConsolePortAsync
+        .mockReset()
+        .mockResolvedValueOnce(5554)
+        .mockResolvedValueOnce(5556);
+      mockedAndroidUtils.startAsync.mockResolvedValue(createStartResult('emulator-5554'));
+    });
+
+    it('preloads the agent and turns the capture on for expo-device-hub', async () => {
+      const step = createStep(
+        { experimental_emulator_capture_version: '0.1.0' },
+        { TMPDIR: '/tmp/job' }
+      );
+
+      await step.executeAsync();
+
+      expect(mockedInstall).toHaveBeenCalledWith({
+        version: '0.1.0',
+        env: expect.any(Object),
+        logger: expect.anything(),
+      });
+      expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith(captureStart(5554));
+      expect(step.globalCtx.env).toMatchObject({
+        EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE: '1',
+        EXPO_DEVICE_HUB_EMULATOR_CAPTURE_LIBRARY: LIBRARY,
+      });
+      expect(stepLogger(step).info).toHaveBeenCalledWith(
+        'emulator-5554 preloads [email protected] with -gpu lavapipe, and its agent socket is /tmp/job/expo-emulator-capture/emulator-5554.sock. Later steps start expo-device-hub with the emulator capture on.'
+      );
+    });
+
+    it('uses the temporary directory rule of Node when TMPDIR is empty', async () => {
+      await createStep(
+        { experimental_emulator_capture_version: '0.1.0' },
+        { TMPDIR: '', TMP: '/tmp/from-tmp' }
+      ).executeAsync();
+
+      expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          extraEnv: expect.objectContaining({
+            EXPO_EMULATOR_CAPTURE_SOCKET: '/tmp/from-tmp/expo-emulator-capture/emulator-5554.sock',
+          }),
+        })
+      );
+    });
+
+    it('uses /tmp when the job env names no temporary directory', async () => {
+      await createStep({ experimental_emulator_capture_version: '0.1.0' }).executeAsync();
+
+      expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          extraEnv: expect.objectContaining({
+            EXPO_EMULATOR_CAPTURE_SOCKET: '/tmp/expo-emulator-capture/emulator-5554.sock',
+          }),
+        })
+      );
+    });
+
+    it('does not turn the capture on when the emulator runs on another console port', async () => {
+      mockedAndroidUtils.startAsync.mockResolvedValue(createStartResult('emulator-5560'));
+      const step = createStep(
+        { experimental_emulator_capture_version: '0.1.0' },
+        { TMPDIR: '/tmp/job' }
+      );
+
+      await step.executeAsync();
+
+      expect(step.globalCtx.env.EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE).toBeUndefined();
+      expect(stepLogger(step).warn).toHaveBeenCalledWith(
+        expect.stringContaining('emulator-5560 does not use console port 5554')
+      );
+    });
+
+    it('keeps a library that the job already preloads, after the agent', async () => {
+      await createStep(
+        { experimental_emulator_capture_version: '0.1.0' },
+        { TMPDIR: '/tmp/job', LD_PRELOAD: '/opt/other.so' }
+      ).executeAsync();
+
+      expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          extraEnv: expect.objectContaining({ LD_PRELOAD: `${LIBRARY}:/opt/other.so` }),
+        })
+      );
+    });
+
+    it('chooses a new console port for each start attempt', async () => {
+      mockedAndroidUtils.startAsync
+        .mockRejectedValueOnce(new Error('emulator did not start'))
+        .mockResolvedValue(createStartResult('emulator-5556'));
+
+      await createStep(
+        { experimental_emulator_capture_version: '0.1.0' },
+        { TMPDIR: '/tmp/job' }
+      ).executeAsync();
+
+      expect(mockedAndroidUtils.startAsync).toHaveBeenNthCalledWith(2, captureStart(5556));
+    });
+
+    it('starts the emulator as without the input when the install fails', async () => {
+      mockedInstall.mockResolvedValue(undefined);
+      const step = createStep({ experimental_emulator_capture_version: '0.1.0' });
+
+      await step.executeAsync();
+
+      expect(mockedAndroidUtils.startAsync).toHaveBeenCalledWith({
+        deviceName: 'EasAndroidDevice01',
+        env: expect.any(Object),
+        logcatDirectory: '/tmp/logcat-directory',
+        logCapture: expect.objectContaining({ sources: ['emulator-output', 'device-logcat'] }),
+      });
+      expect(mockedAndroidUtils.findFreeConsolePortAsync).not.toHaveBeenCalled();
+      expect(step.globalCtx.env.EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE).toBeUndefined();
+      // The session step still rejects session types without the capture.
+      expect(step.globalCtx.env.EAS_EXPERIMENTAL_EMULATOR_CAPTURE_VERSION).toBe('0.1.0');
+    });
+
+    it('installs nothing without the input', async () => {
+      const step = createStep();
+
+      await step.executeAsync();
+
+      expect(mockedInstall).not.toHaveBeenCalled();
+      expect(mockedAndroidUtils.findFreeConsolePortAsync).not.toHaveBeenCalled();
+      expect(step.globalCtx.env.EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE).toBeUndefined();
+      expect(step.globalCtx.env.EAS_EXPERIMENTAL_EMULATOR_CAPTURE_VERSION).toBeUndefined();
+    });
+
+    it('rejects the capture for more than one emulator before it starts one', async () => {
+      await expect(
+        createStep({ experimental_emulator_capture_version: '0.1.0', count: 2 }).executeAsync()
+      ).rejects.toThrow('experimental_emulator_capture_version supports one emulator');
+
+      expect(mockedInstall).not.toHaveBeenCalled();
+      expect(mockedAndroidUtils.startAsync).not.toHaveBeenCalled();
+    });
+
+    it('rejects a version that is not an exact npm version or a dist-tag', async () => {
+      await expect(
+        createStep({ experimental_emulator_capture_version: 'npm:[email protected]' }).executeAsync()
+      ).rejects.toThrow('must be an npm version or dist-tag of expo-emulator-capture');
+
+      expect(mockedInstall).not.toHaveBeenCalled();
+    });
+  });
 });

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

@@ -850,6 +850,26 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
     );
   }
 
+  it('does not fail a session when only the Appium tunnel cannot stop', async () => {
+    const tunnelError = new Error('Ngrok tunnel stop timed out after 4000ms.');
+    const logger = { info: jest.fn(), warn: jest.fn() };
+    stopAppium.mockResolvedValueOnce(undefined);
+    jest.mocked(startNgrokTunnelAsync).mockResolvedValueOnce({
+      url: 'https://appium-abc.tunnel.example.com',
+      subdomainId: 'appium-abc',
+      stopAsync: jest.fn().mockRejectedValue(tunnelError),
+    });
+
+    await expect(runSessionAsync(logger)).resolves.toBeUndefined();
+
+    expect(stopAppium).toHaveBeenCalledTimes(1);
+    expect(finishHost).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: tunnelError },
+      'Could not stop the Appium tunnel during remote session teardown.'
+    );
+  });
+
   it('does not allocate Appium or a host after parent cancellation during Xcode selection', async () => {
     const controller = new AbortController();
     const failure = new Error('parent step cancelled');

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

@@ -667,7 +667,7 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     ['succeeded', false],
     ['failed', true],
   ])(
-    'fails after stopping the host and tools when the tools tunnel cannot close and the session %s',
+    'stops the host and tools when the tools tunnel cannot close and the session %s',
     async (_description, sessionFails) => {
       const closeError = new Error('ngrok close failed');
       const sessionError = new Error('session failed');
@@ -677,23 +677,26 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
       }
       const logger = { info: jest.fn(), warn: jest.fn() };
       const buildFunction = createStartArgentRemoteSessionBuildFunction({} as CustomBuildContext);
-      // The tunnel may still be serving, so its failure fails a session that otherwise succeeded.
-      await expect(
-        buildFunction.fn!(
-          {
-            logger,
-            global: { runtimePlatform: BuildRuntimePlatform.LINUX },
-          } as unknown as BuildStepContext,
-          {
-            inputs: {
-              package_version: { value: undefined },
-              max_idle_time_minutes: { value: undefined },
-            },
-            outputs: {},
-            env: {},
-          } as never
-        )
-      ).rejects.toBe(sessionFails ? sessionError : closeError);
+      // A stopped tunnel's proxy drops every connection, so its failure does not fail a session.
+      const running = buildFunction.fn!(
+        {
+          logger,
+          global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+        } as unknown as BuildStepContext,
+        {
+          inputs: {
+            package_version: { value: undefined },
+            max_idle_time_minutes: { value: undefined },
+          },
+          outputs: {},
+          env: {},
+        } as never
+      );
+      if (sessionFails) {
+        await expect(running).rejects.toBe(sessionError);
+      } else {
+        await expect(running).resolves.toBeUndefined();
+      }
       expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
       expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
       expect(mockStopAsync).toHaveBeenCalledTimes(1);
@@ -702,17 +705,13 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
         { err: closeError },
         'Could not stop the Argent tunnel during remote session teardown.'
       );
-      expect(jest.mocked(Sentry.capture).mock.calls).toEqual(
-        sessionFails
-          ? [
-              [
-                'Could not stop the Argent tunnel after the remote session failed',
-                closeError,
-                { level: 'warning' },
-              ],
-            ]
-          : []
-      );
+      expect(jest.mocked(Sentry.capture).mock.calls).toEqual([
+        [
+          `Could not stop the Argent tunnel after the remote session ${sessionFails ? 'failed' : 'ended'}`,
+          closeError,
+          { level: 'warning' },
+        ],
+      ]);
     }
   );
 

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,6 +199,97 @@ describe('sandbox build functions', () => {
     expect(stopAsync).toHaveBeenCalledTimes(1);
   });
 
+  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: {
+        ...context.job,
+        projectArchive: {
+          type: ArchiveSourceType.GIT,
+          gitRef: 'refs/heads/main',
+          gitCommitHash: '0123456789abcdef0123456789abcdef01234567',
+        },
+      },
+      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('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: {
+        ...context.job,
+        projectArchive: {
+          type: ArchiveSourceType.GIT,
+          gitRef: null,
+          gitCommitHash: '0123456789abcdef0123456789abcdef01234567',
+        },
+      },
+      projectTargetDirectory: '/workingdir/build',
+    } as any);
+
+    await expect(fn.fn!(checkedOutStepCtx, { inputs, outputs: {}, env: {} })).rejects.toBe(
+      stripError
+    );
+    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: 'the sandbox worker token',

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

@@ -238,18 +238,29 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     );
   });
 
-  it('uses preview activity to reset the configured idle timeout', async () => {
-    await runAsync(BuildRuntimePlatform.DARWIN, { max_idle_time_minutes: { value: 5 } });
-    const { idleTimeout } = jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.calls[0][0];
-    expect(idleTimeout?.maxIdleTimeMinutes).toBe(5);
-    expect(idleTimeout?.getLastEventObservedAt()).toBeUndefined();
-    const host = await jest.mocked(startDeviceSessionHostAsync).mock.results[0].value;
-    const observedAt = new Date();
-    jest.mocked(host.getLastPreviewActivityAt).mockReturnValue(observedAt);
-    expect(idleTimeout?.getLastPreviewActivityAt?.()).toBe(observedAt);
-    expect(stopAsync).toHaveBeenCalledTimes(1);
+  it('lets the session host use the experimental emulator capture', async () => {
+    await runAsync(BuildRuntimePlatform.LINUX);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ emulatorCapture: true })
+    );
   });
 
+  it.each([BuildRuntimePlatform.DARWIN, BuildRuntimePlatform.LINUX])(
+    'uses preview activity to reset the configured idle timeout on %s',
+    async runtimePlatform => {
+      await runAsync(runtimePlatform, { max_idle_time_minutes: { value: 5 } });
+      const { idleTimeout } = jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.calls[0][0];
+      expect(idleTimeout?.maxIdleTimeMinutes).toBe(5);
+      expect(idleTimeout?.getLastEventObservedAt()).toBeUndefined();
+      const host = await jest.mocked(startDeviceSessionHostAsync).mock.results[0].value;
+      const observedAt = new Date();
+      jest.mocked(host.getLastPreviewActivityAt).mockReturnValue(observedAt);
+      expect(idleTimeout?.getLastPreviewActivityAt?.()).toBe(observedAt);
+      expect(stopAsync).toHaveBeenCalledTimes(1);
+    }
+  );
+
   it.each([BuildRuntimePlatform.DARWIN, BuildRuntimePlatform.LINUX])(
     'leaves the idle timer disabled when omitted on %s',
     async runtimePlatform => {
@@ -269,16 +280,6 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     );
   });
 
-  it('rejects an Android idle timeout before starting the host', async () => {
-    await expect(
-      runAsync(BuildRuntimePlatform.LINUX, {
-        max_idle_time_minutes: { value: 5 },
-      })
-    ).rejects.toThrow('Omit max_idle_time_minutes for Android sessions.');
-    expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
-    expect(waitForDeviceRunSessionStoppedAsync).not.toHaveBeenCalled();
-  });
-
   it.each([BuildRuntimePlatform.DARWIN, BuildRuntimePlatform.LINUX])(
     'handles Stop while the %s host starts',
     async runtimePlatform => {
@@ -508,6 +509,7 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
           }
         : {}),
       packageVersion: '1.2.3',
+      emulatorCapture: true,
       disableShare: false,
       frameAncestors: [],
       corsOrigins: [],

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/startAgentDeviceRemoteSession.ts

@@ -26,6 +26,7 @@ import { type StartupTasks } from '../utils/startupTasks';
 import {
   type DetachedProcessHandle,
   DeviceRunSessionStoppedError,
+  TOOL_TUNNEL_TEARDOWN_OPTIONS,
   finishRemoteSessionAsync,
   getDeviceRunSessionIdOrThrow,
   getNgrokAuthtokenOrThrow,
@@ -213,6 +214,7 @@ export async function runAgentDeviceRemoteSessionAsync(
       authtoken: ngrokAuthtoken,
       healthCheck: { path: '/health' },
       logger: taskLogger,
+      signal: tasks.signal,
     });
     tasks.signal.throwIfAborted();
     taskLogger.info(`Tunnel is ready at ${agentDeviceTunnel.url}.`);
@@ -351,7 +353,7 @@ export async function runAgentDeviceRemoteSessionAsync(
             ? [['startup cleanup', Promise.reject(result.reason)]]
             : []
         ),
-        ['agent-device tunnel', agentDeviceTunnel?.stopAsync()],
+        ['agent-device tunnel', agentDeviceTunnel?.stopAsync(), TOOL_TUNNEL_TEARDOWN_OPTIONS],
         ['agent-device daemon', toolTeardown],
         [
           'session host',

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(
         {
@@ -256,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,
                 });

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

@@ -20,8 +20,17 @@ 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 {
+  EMULATOR_CAPTURE_REQUESTED_ENV,
+  installEmulatorCaptureAsync,
+  parseExperimentalEmulatorCaptureVersionInput,
+} from '../utils/emulatorCapture';
+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 +42,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,
@@ -71,6 +86,12 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
         defaultValue: 1,
         allowedValueTypeName: BuildStepInputValueTypeName.NUMBER,
       }),
+      // Experimental: the expo-emulator-capture version that the emulator preloads.
+      BuildStepInput.createProvider({
+        id: 'experimental_emulator_capture_version',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
     ],
     outputProviders: [
       BuildStepOutput.createProvider({
@@ -78,14 +99,41 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
         required: true,
       }),
     ],
-    fn: async ({ logger }, { inputs, outputs, env }) => {
+    fn: async ({ logger, global }, { inputs, outputs, env }) => {
+      const count = Number(inputs.count.value ?? 1);
+      const emulatorCaptureVersion = parseExperimentalEmulatorCaptureVersionInput(
+        inputs.experimental_emulator_capture_version.value
+      );
+      if (emulatorCaptureVersion && count > 1) {
+        throw new UserError(
+          'EAS_EMULATOR_CAPTURE_INVALID_INPUT',
+          'experimental_emulator_capture_version supports one emulator. Remove it, or set count to 1.'
+        );
+      }
+      const logSources = parseLogSourcesInput(inputs.log_sources.value, {
+        runtimePlatform: global.runtimePlatform,
+        fallback: ALL_ANDROID_EMULATOR_LOG_SOURCES,
+      });
+      if (emulatorCaptureVersion) {
+        // Marks the request for the session step, which rejects session types that cannot use
+        // the capture. The mark does not depend on the install, so the rejection does not either.
+        global.updateEnv({
+          ...global.env,
+          [EMULATOR_CAPTURE_REQUESTED_ENV]: emulatorCaptureVersion,
+        });
+      }
+      const emulatorCaptureLibrary = emulatorCaptureVersion
+        ? await installEmulatorCaptureAsync({ version: emulatorCaptureVersion, env, logger })
+        : undefined;
+
       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;
-      const { serialId, emulatorPromise, shouldAdjustAnimationScale } =
+      const { serialId, emulatorPromise, shouldAdjustAnimationScale, emulatorCaptureSocketPath } =
         await startAndroidEmulatorAsync({
           deviceName,
           systemImagePackage: `${inputs.system_image_package.value}`,
@@ -95,11 +143,24 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
           lcdHeight: inputs.lcd_height.value as number | undefined,
           lcdDensity: inputs.lcd_density.value as number | undefined,
           logcatDirectory,
+          logCapture,
           env,
           logger,
+          emulatorCaptureLibrary,
         });
+      if (emulatorCaptureLibrary && emulatorCaptureSocketPath) {
+        // The session step starts expo-device-hub with the job env. A Hub version without the
+        // emulator capture ignores these variables.
+        global.updateEnv({
+          ...global.env,
+          EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE: '1',
+          EXPO_DEVICE_HUB_EMULATOR_CAPTURE_LIBRARY: emulatorCaptureLibrary,
+        });
+        logger.info(
+          `${serialId} preloads expo-emulator-capture@${emulatorCaptureVersion} with -gpu lavapipe, and its agent socket is ${emulatorCaptureSocketPath}. Later steps start expo-device-hub with the emulator capture on.`
+        );
+      }
 
-      const count = Number(inputs.count.value ?? 1);
       if (count > 1) {
         logger.info(`Requested ${count} emulators, shutting down ${deviceName} for cloning.`);
         await spawn('adb', ['-s', serialId, 'shell', 'reboot', '-p'], {
@@ -133,6 +194,7 @@ export function createStartAndroidEmulatorBuildFunction(): BuildFunction {
                   deviceName: cloneIdentifier,
                   env,
                   logcatDirectory,
+                  logCapture,
                 });
                 cloneSerialId = startResult.serialId;
 
@@ -202,8 +264,10 @@ export async function startAndroidEmulatorAsync({
   lcdHeight,
   lcdDensity,
   logcatDirectory,
+  logCapture,
   env,
   logger,
+  emulatorCaptureLibrary,
 }: {
   deviceName: AndroidVirtualDeviceName;
   systemImagePackage: string;
@@ -212,12 +276,17 @@ export async function startAndroidEmulatorAsync({
   lcdHeight?: number;
   lcdDensity?: number;
   logcatDirectory: string;
+  logCapture: AndroidEmulatorLogCapture;
   env: BuildStepEnv;
   logger: bunyan;
+  /** The expo-emulator-capture agent library that the emulator preloads (experimental). */
+  emulatorCaptureLibrary?: string;
 }): Promise<{
   serialId: AndroidDeviceSerialId;
   emulatorPromise: Promise<unknown>;
   shouldAdjustAnimationScale: boolean;
+  /** The capture agent's socket, when the emulator preloads the agent on the expected serial. */
+  emulatorCaptureSocketPath?: string;
 }> {
   if (env.EAS_NO_EMULATOR_HOST_SUPPORT_CHECK !== '1') {
     await assertAndroidEmulatorHostSupportAsync({ env });
@@ -265,8 +334,16 @@ export async function startAndroidEmulatorAsync({
     }
   );
 
+  // expo-device-hub gets the job env and finds the agent sockets in `<tmpdir>/expo-emulator-capture`,
+  // where Node's os.tmpdir() applies this rule to that env. On EAS, TMPDIR is not set.
+  const captureSocketDirectory = path.join(
+    env.TMPDIR || env.TMP || env.TEMP || '/tmp',
+    'expo-emulator-capture'
+  );
   let emulatorPromise = null;
   let serialId = null;
+  // Set by the attempt that starts; the cast keeps the type wide after the retry callback.
+  let captureLaunch = undefined as { consolePort: number; socketPath: string } | undefined;
   await retryAsync(
     async attemptCount => {
       const timeoutMs = ANDROID_STARTUP_ATTEMPT_TIMEOUT_MS[attemptCount];
@@ -289,11 +366,37 @@ export async function startAndroidEmulatorAsync({
         });
 
         logger.info(`Starting emulator device${attemptSuffix}.`);
+        // expo-device-hub finds the capture agent's socket by the serial, so the console port,
+        // which sets the serial, is chosen before the start, again for each attempt.
+        const consolePort = emulatorCaptureLibrary
+          ? await AndroidEmulatorUtils.findFreeConsolePortAsync()
+          : undefined;
+        const launch =
+          consolePort !== undefined
+            ? {
+                consolePort,
+                socketPath: path.join(captureSocketDirectory, `emulator-${consolePort}.sock`),
+              }
+            : undefined;
         const startResult = await AndroidEmulatorUtils.startAsync({
           deviceName,
           env,
           logcatDirectory,
+          logCapture,
           ...(localEgress ? { launchGate: localEgress.launchGate } : {}),
+          ...(emulatorCaptureLibrary && launch
+            ? {
+                consolePort: launch.consolePort,
+                // The Linux agent kept 60 fps with the lavapipe renderer.
+                extraArgs: ['-gpu', 'lavapipe'],
+                extraEnv: {
+                  // A library that the job already preloads stays preloaded, after the agent.
+                  LD_PRELOAD: [emulatorCaptureLibrary, env.LD_PRELOAD].filter(Boolean).join(':'),
+                  // The agent creates the directory.
+                  EXPO_EMULATOR_CAPTURE_SOCKET: launch.socketPath,
+                },
+              }
+            : {}),
         });
         attemptSerialId = startResult.serialId;
         await AndroidEmulatorUtils.waitForReadyAsync({
@@ -315,6 +418,7 @@ export async function startAndroidEmulatorAsync({
 
         serialId = attemptSerialId;
         emulatorPromise = startResult.emulatorPromise;
+        captureLaunch = launch;
       } catch (err) {
         logger.warn({ err }, `${deviceName} failed to start on attempt ${attempt}/${maxAttempts}.`);
         try {
@@ -348,7 +452,19 @@ export async function startAndroidEmulatorAsync({
   if (!serialId || !emulatorPromise) {
     throw new Error(`Failed to start emulator ${deviceName}.`);
   }
-  return { serialId, emulatorPromise, shouldAdjustAnimationScale };
+  // The Hub looks for the socket by serial. $ANDROID_EMULATOR_EXTRA_ARGS can override -port.
+  if (captureLaunch && serialId !== `emulator-${captureLaunch.consolePort}`) {
+    logger.warn(
+      `${serialId} does not use console port ${captureLaunch.consolePort}, so expo-device-hub cannot find its capture agent socket ${captureLaunch.socketPath}. The session streams without the emulator capture. Remove -port from $ANDROID_EMULATOR_EXTRA_ARGS.`
+    );
+    captureLaunch = undefined;
+  }
+  return {
+    serialId,
+    emulatorPromise,
+    shouldAdjustAnimationScale,
+    emulatorCaptureSocketPath: captureLaunch?.socketPath,
+  };
 }
 
 async function assertAndroidEmulatorHostSupportAsync({

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

@@ -52,6 +52,7 @@ import { preparePreinstalledWdaAsync } from '../utils/preinstalledWda';
 import { watchDeviceRunSessionStartup } from '../utils/deviceRunSessionStartup';
 import {
   DeviceRunSessionStoppedError,
+  TOOL_TUNNEL_TEARDOWN_OPTIONS,
   createCorsOriginsInputProvider,
   createFrameAncestorsInputProvider,
   createIosSessionStartupInputProviders,
@@ -328,6 +329,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
             authtoken: ngrokAuthtoken,
             healthCheck: { path: '/status' },
             logger,
+            signal: startupSignal,
           });
 
           // The preview host uses the same device selected for Appium.
@@ -415,7 +417,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
             logger,
             sessionFailed,
             teardown: [
-              ['Appium tunnel', appiumTunnel?.stopAsync()],
+              ['Appium tunnel', appiumTunnel?.stopAsync(), TOOL_TUNNEL_TEARDOWN_OPTIONS],
               ['Appium server', appiumTeardown],
               [
                 'session host',

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

@@ -44,6 +44,7 @@ import { ARGENT_EVENT_LOG_FILENAME, startArgentEventCollectionAsync } from '../u
 import { watchDeviceRunSessionStartup } from '../utils/deviceRunSessionStartup';
 import {
   DeviceRunSessionStoppedError,
+  TOOL_TUNNEL_TEARDOWN_OPTIONS,
   createCorsOriginsInputProvider,
   createFrameAncestorsInputProvider,
   createIosSessionStartupInputProviders,
@@ -386,6 +387,7 @@ export function createStartArgentRemoteSessionBuildFunction(
             rewriteHostHeader: true,
             healthCheck: { path: '/tools', statuses: [200, 401] },
             logger,
+            signal: startupSignal,
           });
           const publicToolsUrl = toolsTunnel.url;
           logger.info(`Tunnel is ready at ${publicToolsUrl}.`);
@@ -481,7 +483,7 @@ export function createStartArgentRemoteSessionBuildFunction(
             logger,
             sessionFailed,
             teardown: [
-              ['Argent tunnel', toolsTunnel?.stopAsync()],
+              ['Argent tunnel', toolsTunnel?.stopAsync(), TOOL_TUNNEL_TEARDOWN_OPTIONS],
               ['Argent tool-server', toolTeardown],
               [
                 'session host',

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

@@ -170,6 +170,7 @@ export function createStartLocalEgressBuildFunction(): BuildFunction {
             baseDomain: ngrokTunnelDomain,
             authtoken: ngrokAuthtoken,
             logger,
+            signal: startupSignal,
           }),
           startupSignal,
           async listener => await listener?.stopAsync(),

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

@@ -1,6 +1,7 @@
-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 { startSandboxDaemonAsync } from '../utils/sandboxDaemon';
@@ -45,6 +46,15 @@ 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: workerApi.token,
         serverUrl: mcpServerUrl,

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

@@ -1,4 +1,3 @@
-import { UserError } from '@expo/eas-build-job';
 import {
   BuildFunction,
   BuildRuntimePlatform,
@@ -87,16 +86,6 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
       const maxDurationSeconds = inputs.max_duration_seconds?.value as number | undefined;
       const packageVersion = inputs.package_version?.value as string | undefined;
       const { runtimePlatform } = global;
-      if (
-        maxIdleTimeMinutes !== undefined &&
-        maxIdleTimeMinutes > 0 &&
-        runtimePlatform !== BuildRuntimePlatform.DARWIN
-      ) {
-        throw new UserError(
-          'UNSUPPORTED_WEB_PREVIEW_IDLE_TIMEOUT',
-          'Web preview idle timeouts require iOS preview activity reporting. Omit max_idle_time_minutes for Android sessions.'
-        );
-      }
       const startupStop = new AbortController();
       const watchSignal = signal
         ? AbortSignal.any([signal, startupStop.signal])
@@ -152,6 +141,7 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
             signal: startupSignal,
             onStartupError: error => startupAbortController.abort(error),
             packageVersion: resolvedPackageVersion,
+            emulatorCapture: true,
             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

@@ -40,9 +40,14 @@ import {
   spawnDetached,
   startNgrokTunnelAsync,
 } from '../remoteDeviceRunSession';
-import { runServeSimActionAsync, stageServeSimAppAsync } from '../serveSimActions';
-import { startServeSimActivityPolling } from '../serveSimActivity';
+import {
+  runServeSimActionAsync,
+  runServeSimActionWithResultAsync,
+  stageServeSimAppAsync,
+} from '../serveSimActions';
+import { startPreviewActivityPolling } from '../previewActivity';
 import { readServeSimServersAsync } from '../serveSimMetricsRecorder';
+import * as previewCapture from '../serveSimPreviewCapture';
 
 jest.mock('@ngrok/ngrok');
 jest.mock('@expo/turtle-spawn');
@@ -54,7 +59,7 @@ jest.mock('../serveSimActions');
 jest.mock('../iosAppArtifact', () => ({
   readIosApplicationIdentifierAsync: jest.fn(),
 }));
-jest.mock('../serveSimActivity');
+jest.mock('../previewActivity');
 jest.mock('../localEgress', () => ({
   ...jest.requireActual('../localEgress'),
   readLocalEgressHandoffAsync: jest.fn().mockResolvedValue(null),
@@ -165,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);
@@ -633,7 +644,7 @@ it('starts the readiness budget after refusals that exceed the normal startup de
 it('reports preview activity from serve-sim on iOS and stops polling when finished', async () => {
   const observedAt = new Date('2026-10-19T12:00:00Z');
   const stopActivity = jest.fn().mockResolvedValue(undefined);
-  jest.mocked(startServeSimActivityPolling).mockReturnValue({
+  jest.mocked(startPreviewActivityPolling).mockReturnValue({
     getLastActivityObservedAt: () => observedAt,
     stopAsync: stopActivity,
   });
@@ -650,7 +661,8 @@ it('reports preview activity from serve-sim on iOS and stops polling when finish
     ]
   );
 
-  expect(startServeSimActivityPolling).toHaveBeenCalledWith({
+  expect(startPreviewActivityPolling).toHaveBeenCalledWith({
+    server: 'serve-sim',
     port,
     token: 'preview-token',
     logger: expect.anything(),
@@ -677,15 +689,33 @@ it('does not start polling preview activity when startup is cancelled', async ()
       signal: controller.signal,
     })
   ).rejects.toThrow();
-  expect(startServeSimActivityPolling).not.toHaveBeenCalled();
+  expect(startPreviewActivityPolling).not.toHaveBeenCalled();
 });
 
-it('reports no preview activity on Android, where expo-device-hub keeps no event log', async () => {
+it('reports preview activity from expo-device-hub on Android and stops polling when finished', async () => {
+  const observedAt = new Date('2026-11-13T12:00:00Z');
+  const stopActivity = jest.fn().mockResolvedValue(undefined);
+  jest.mocked(startPreviewActivityPolling).mockReturnValue({
+    getLastActivityObservedAt: () => observedAt,
+    stopAsync: stopActivity,
+  });
   const host = await startHostAsync();
+  const port = Number(
+    jest.mocked(spawnDetached).mock.calls[0][0].args[
+      jest.mocked(spawnDetached).mock.calls[0][0].args.indexOf('--port') + 1
+    ]
+  );
+
+  expect(startPreviewActivityPolling).toHaveBeenCalledWith({
+    server: 'expo-device-hub',
+    port,
+    token: expect.any(String),
+    logger: expect.anything(),
+  });
+  expect(host.getLastPreviewActivityAt()).toBe(observedAt);
 
-  expect(startServeSimActivityPolling).not.toHaveBeenCalled();
-  expect(host.getLastPreviewActivityAt()).toBeUndefined();
   await host.finishAsync();
+  expect(stopActivity).toHaveBeenCalledTimes(1);
 });
 
 it('stops a host that became ready on a different Simulator', async () => {
@@ -845,6 +875,73 @@ it('drains an in-flight tunnel when finishing and rejects new opens', async () =
   expect(stopServer).toHaveBeenCalledTimes(1);
 });
 
+it('does not retry a rejected preview tunnel open after finishing', async () => {
+  const host = await startHostAsync();
+  await (await host.openPreviewAsync()).closeAsync();
+  const forwardCalls = jest.mocked(ngrok.forward).mock.calls.length;
+  const tunnel = deferred<Awaited<ReturnType<typeof ngrok.forward>>>();
+  jest.mocked(ngrok.forward).mockReturnValueOnce(tunnel.promise);
+  const opening = host.openPreviewAsync();
+  const finishing = host.finishAsync();
+  tunnel.reject(
+    new Error('failed to start listener: internal server error error_code: ERR_NGROK_802')
+  );
+  await expect(opening).rejects.toThrow('ERR_NGROK_802');
+  await finishing;
+  expect(jest.mocked(ngrok.forward).mock.calls.length).toBe(forwardCalls + 1);
+  expect(logger.warn).not.toHaveBeenCalledWith(
+    expect.anything(),
+    expect.stringContaining('; retrying.')
+  );
+  expect(stopServer).toHaveBeenCalledTimes(1);
+});
+
+it('does not retry a rejected preview tunnel open after startup fails', async () => {
+  jest.useFakeTimers({ doNotFake: ['setImmediate'] });
+  const forwardCalls = jest.mocked(ngrok.forward).mock.calls.length;
+  jest
+    .mocked(ngrok.forward)
+    .mockRejectedValueOnce(
+      new Error('failed to start listener: internal server error error_code: ERR_NGROK_802')
+    );
+  const startGate = deferred<void>();
+  const startupError = new Error('startup failure');
+  const startAsync = jest.fn(async () => {
+    await startGate.promise;
+    throw startupError;
+  });
+  const outcome = startDeviceSessionHostAsync(
+    ctx,
+    {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      preview: { baseDomain, authtoken },
+      env,
+      logger,
+      timeoutMs: 30_000,
+    },
+    {
+      port: 3200,
+      turnArgs: Promise.resolve([]),
+      requiresPreviewRetirement: true,
+      startAsync,
+      stopAsync: stopServer,
+    }
+  ).catch(error => error);
+  const retrying = () =>
+    jest
+      .mocked(logger.warn)
+      .mock.calls.some(([, message]) => String(message).endsWith('; retrying.'));
+  for (let i = 0; i < 50 && !retrying(); i++) {
+    await new Promise(resolve => setImmediate(resolve));
+  }
+  expect(retrying()).toBe(true);
+  startGate.resolve();
+  await jest.advanceTimersByTimeAsync(5_000);
+  expect(await outcome).toBe(startupError);
+  expect(jest.mocked(ngrok.forward).mock.calls.length).toBe(forwardCalls + 1);
+  expect(stopServer).toHaveBeenCalledTimes(1);
+});
+
 it('keeps cleanup and upload best-effort when tunnel close and finalization fail', async () => {
   jest.mocked(spawnDetached).mockImplementationOnce(options => {
     directories.push(options.args[options.args.indexOf('--android-recording-directory') + 1]);
@@ -1116,6 +1213,75 @@ it.each([
   await host.finishAsync();
 });
 
+it('keeps the experimental emulator capture off in expo-device-hub by default', async () => {
+  const host = await startHostAsync();
+  const options = jest.mocked(spawnDetached).mock.calls[0][0];
+  expect(options.env.EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE).toBe('0');
+  await host.finishAsync();
+});
+
+it('rejects an emulator capture request in a session type without the capture', async () => {
+  await expect(
+    startDeviceSessionHostAsync(ctx, {
+      preview: { baseDomain, authtoken },
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: { ...env, EAS_EXPERIMENTAL_EMULATOR_CAPTURE_VERSION: '0.1.0' },
+      logger,
+      separateLogPhase: true,
+      timeoutMs: 10_000,
+    })
+  ).rejects.toThrow(
+    'The experimental emulator capture ([email protected]) works only in web preview sessions for now.'
+  );
+  expect(spawnDetached).not.toHaveBeenCalled();
+  expect(startNgrokTunnelAsync).not.toHaveBeenCalled();
+});
+
+it('passes the emulator capture that the emulator start turned on to expo-device-hub', async () => {
+  const host = await startDeviceSessionHostAsync(ctx, {
+    preview: { baseDomain, authtoken },
+    runtimePlatform: BuildRuntimePlatform.LINUX,
+    env: {
+      ...env,
+      EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE: '1',
+      EXPO_DEVICE_HUB_EMULATOR_CAPTURE_LIBRARY: '/tmp/package/libexpo_emulator_capture.so',
+      EAS_EXPERIMENTAL_EMULATOR_CAPTURE_VERSION: '0.1.0',
+    },
+    logger,
+    separateLogPhase: true,
+    timeoutMs: 10_000,
+    emulatorCapture: true,
+  });
+  const options = jest.mocked(spawnDetached).mock.calls[0][0];
+  expect(options.env).toMatchObject({
+    EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE: '1',
+    EXPO_DEVICE_HUB_EMULATOR_CAPTURE_LIBRARY: '/tmp/package/libexpo_emulator_capture.so',
+  });
+  // The env turns the capture on, because an expo-device-hub without it rejects unknown flags.
+  expect(options.args).not.toContain('--experimental-emulator-capture');
+  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 },
@@ -1163,6 +1329,7 @@ it('leaves iOS recording to its existing build steps', async () => {
   const options = jest.mocked(spawnDetached).mock.calls[0][0];
   expect(options.args).not.toContain('--android-recording-directory');
   expect(options.env.EXPO_DEVICE_HUB_RECORDING_CONTROL_TOKEN).toBeUndefined();
+  expect(options.env.EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE).toBeUndefined();
   await host.finishAsync();
   expect(jest.mocked(turtleFetch).mock.calls.some(([, method]) => method === 'POST')).toBe(false);
   expect(uploadDeviceRunSessionScreenRecordingsAsync).not.toHaveBeenCalled();
@@ -1479,6 +1646,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 => {

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

@@ -0,0 +1,122 @@
+import { UserError } from '@expo/eas-build-job';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { installIsolatedNpmPackageAsync } from '../../../utils/installIsolatedNpmPackageAsync';
+import {
+  installEmulatorCaptureAsync,
+  parseExperimentalEmulatorCaptureVersionInput,
+} from '../emulatorCapture';
+
+jest.mock('../../../utils/installIsolatedNpmPackageAsync', () => ({
+  installIsolatedNpmPackageAsync: jest.fn(),
+}));
+
+const TEMPORARY_DIRECTORY = '/tmp/eas-test';
+const AGENT = 'node_modules/expo-emulator-capture/dist/linux-x64/libexpo_emulator_capture.so';
+const mockedInstall = jest.mocked(installIsolatedNpmPackageAsync);
+const { platform, arch } = process;
+
+function setHost(hostPlatform: NodeJS.Platform, hostArch: string): void {
+  Object.defineProperty(process, 'platform', { value: hostPlatform });
+  Object.defineProperty(process, 'arch', { value: hostArch });
+}
+
+beforeEach(() => {
+  jest.spyOn(os, 'tmpdir').mockReturnValue(TEMPORARY_DIRECTORY);
+  fs.mkdirSync(TEMPORARY_DIRECTORY, { recursive: true });
+  mockedInstall.mockReset();
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+  setHost(platform, arch);
+});
+
+describe(parseExperimentalEmulatorCaptureVersionInput, () => {
+  it.each([undefined, null, ''])('turns the capture off for %p', value => {
+    expect(parseExperimentalEmulatorCaptureVersionInput(value)).toBeUndefined();
+  });
+
+  it.each(['0.1.0', '0.1.0-canary-20261106-2b670aa', 'canary', 'latest'])('accepts %s', value => {
+    expect(parseExperimentalEmulatorCaptureVersionInput(value)).toBe(value);
+  });
+
+  it.each([
+    '^0.1.0',
+    '../0.1.0',
+    'npm:[email protected]',
+    'file:/tmp/agent',
+    '0.1.0 ',
+    '-0.1.0',
+    'x'.repeat(129),
+    1,
+  ])('rejects %p', value => {
+    expect(() => parseExperimentalEmulatorCaptureVersionInput(value)).toThrow(UserError);
+  });
+});
+
+describe(installEmulatorCaptureAsync, () => {
+  const env = { PATH: '/usr/bin', EAS_BUILD_NPM_CACHE_URL: 'https://npm-cache.example' };
+
+  it('installs the package in its own directory and returns its agent library', async () => {
+    setHost('linux', 'x64');
+    mockedInstall.mockImplementation(async ({ directory }) => {
+      fs.mkdirSync(path.dirname(path.join(directory, AGENT)), { recursive: true });
+      fs.writeFileSync(path.join(directory, AGENT), '');
+    });
+    const logger = createMockLogger();
+
+    const library = await installEmulatorCaptureAsync({ version: '0.1.0', env, logger });
+
+    expect(mockedInstall).toHaveBeenCalledWith({
+      packageSpec: '[email protected]',
+      directory: expect.stringMatching(/^\/tmp\/eas-test\/eas-emulator-capture-package-/),
+      npmCacheUrl: 'https://npm-cache.example',
+      pathEnv: '/usr/bin',
+      logger,
+      signal: expect.any(AbortSignal),
+    });
+    expect(library).toBe(path.join(mockedInstall.mock.calls[0][0].directory, AGENT));
+  });
+
+  it('returns undefined when the install fails', async () => {
+    setHost('linux', 'x64');
+    mockedInstall.mockRejectedValue(new Error('npm error 404'));
+    const logger = createMockLogger();
+
+    await expect(
+      installEmulatorCaptureAsync({ version: '0.1.0', env, logger })
+    ).resolves.toBeUndefined();
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      expect.stringContaining('Could not install [email protected]')
+    );
+  });
+
+  it('returns undefined when the package has no Linux agent library', async () => {
+    setHost('linux', 'x64');
+    mockedInstall.mockResolvedValue(undefined);
+    const logger = createMockLogger();
+
+    await expect(
+      installEmulatorCaptureAsync({ version: 'latest', env, logger })
+    ).resolves.toBeUndefined();
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('expo-emulator-capture@latest has no Linux x86-64 agent at')
+    );
+  });
+
+  it('returns undefined on a host that is not Linux x86-64', async () => {
+    setHost('darwin', 'arm64');
+    const logger = createMockLogger();
+
+    await expect(
+      installEmulatorCaptureAsync({ version: '0.1.0', env, logger })
+    ).resolves.toBeUndefined();
+    expect(mockedInstall).not.toHaveBeenCalled();
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('Linux x86-64'));
+  });
+});

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

@@ -563,26 +563,276 @@ it('does not queue more native opens while a timed-out open is still pending', a
   expect(replacement.close).toHaveBeenCalledTimes(1);
 });
 
-it('bounds initial tunnel creation and retires a late listener', async () => {
+const ERR_802 = 'failed to start listener: internal server error error_code: ERR_NGROK_802';
+
+it('bounds initial tunnel creation, does not retry a timed-out open, and retires a late listener', async () => {
   let resolveOpening!: (value: ngrok.Listener) => void;
   jest
     .mocked(ngrok.forward)
     .mockReset()
-    .mockReturnValueOnce(
-      new Promise(resolve => {
-        resolveOpening = resolve;
-      })
-    );
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)))
+    .mockResolvedValue(replacement as never);
   const opening = startNgrokTunnelAsync(options);
-  const rejected = expect(opening).rejects.toThrow('Ngrok tunnel open timed out');
-  await jest.advanceTimersByTimeAsync(15_000);
+  const rejected = expect(opening).rejects.toThrow('Ngrok tunnel open timed out after 19000ms');
+  await jest.advanceTimersByTimeAsync(19_000);
   await rejected;
+  // ngrok runs opens one at a time, so a retry would only wait behind the stuck open.
+  expect(ngrok.forward).toHaveBeenCalledTimes(1);
+  expect(logger.warn).not.toHaveBeenCalledWith(
+    expect.anything(),
+    expect.stringContaining('); retrying.')
+  );
   resolveOpening(initial as never);
   await jest.advanceTimersByTimeAsync(0);
   expect(initial.close).toHaveBeenCalledTimes(1);
+  expect(logger.info).toHaveBeenCalledWith(
+    expect.objectContaining({ outcome: 'opened', elapsedMs: 19_000 }),
+    'ngrok tunnel open for web-preview-fixed.example.test opened after 19000 ms, after it timed out or was cancelled.'
+  );
 });
 
-it('retries a rejected close after initial tunnel creation timed out', async () => {
+it('keeps a first open that settles after the reopen time-out', async () => {
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)))
+    .mockResolvedValue(replacement as never);
+  const opening = startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(16_000);
+  resolveOpening(initial as never);
+  const tunnel = await opening;
+  try {
+    expect(tunnel.url).toBe(url);
+    expect(ngrok.forward).toHaveBeenCalledTimes(1);
+    expect(initial.close).not.toHaveBeenCalled();
+  } finally {
+    await tunnel.stopAsync();
+  }
+  expect(initial.close).toHaveBeenCalledTimes(1);
+});
+
+it('fails without a retry when the first open fails for another reason after 15 seconds', async () => {
+  let rejectOpening!: (error: Error) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockReturnValueOnce(new Promise((_, reject) => (rejectOpening = reject)))
+    .mockResolvedValue(replacement as never);
+  const error = new Error('invalid authtoken');
+  const opening = startNgrokTunnelAsync(options);
+  const rejected = expect(opening).rejects.toBe(error);
+  await jest.advanceTimersByTimeAsync(16_000);
+  rejectOpening(error);
+  await rejected;
+  await jest.advanceTimersByTimeAsync(10_000);
+  expect(ngrok.forward).toHaveBeenCalledTimes(1);
+});
+
+it('does not retry a timed-out open that ngrok rejects later', async () => {
+  let rejectOpening!: (error: Error) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockReturnValueOnce(new Promise((_, reject) => (rejectOpening = reject)))
+    .mockResolvedValue(replacement as never);
+  const opening = startNgrokTunnelAsync(options);
+  const rejected = expect(opening).rejects.toThrow('Ngrok tunnel open timed out');
+  await jest.advanceTimersByTimeAsync(19_000);
+  await rejected;
+  rejectOpening(new Error(ERR_802));
+  await jest.advanceTimersByTimeAsync(10_000);
+  expect(ngrok.forward).toHaveBeenCalledTimes(1);
+});
+
+it('retries an initial open that ngrok rejects on a new agent session', async () => {
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockRejectedValueOnce(new Error(ERR_802))
+    .mockResolvedValue(initial as never);
+  const opening = startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(1_000);
+  const tunnel = await opening;
+  try {
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(ngrok.forward).mock.calls[0][0]).not.toHaveProperty('force_new_session');
+    expect(jest.mocked(ngrok.forward).mock.calls[1][0]).toMatchObject({ force_new_session: true });
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ attempt: 1 }),
+      'Could not open ngrok tunnel web-preview-fixed.example.test (attempt 1 of 3); retrying.'
+    );
+    expect(tunnel.url).toBe(url);
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('retries an initial open whose error carries the ngrok error code', async () => {
+  const error = Object.assign(new Error('failed to start listener'), {
+    errorCode: 'ERR_NGROK_802',
+  });
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockRejectedValueOnce(error)
+    .mockResolvedValue(initial as never);
+  const opening = startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(1_000);
+  const tunnel = await opening;
+  try {
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('gives a retry the reopen time-out', async () => {
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockRejectedValueOnce(new Error(ERR_802))
+    .mockReturnValueOnce(new Promise(() => {}));
+  const opening = startNgrokTunnelAsync(options);
+  const rejected = expect(opening).rejects.toThrow('Ngrok tunnel open timed out after 15000ms');
+  await jest.advanceTimersByTimeAsync(1_000 + 15_000);
+  await rejected;
+  expect(ngrok.forward).toHaveBeenCalledTimes(2);
+});
+
+it('fails after three rejected initial opens', async () => {
+  jest.mocked(ngrok.forward).mockReset().mockRejectedValue(new Error(ERR_802));
+  const opening = startNgrokTunnelAsync(options);
+  const rejected = expect(opening).rejects.toThrow('ERR_NGROK_802');
+  await jest.advanceTimersByTimeAsync(1_000 + 2_000);
+  await rejected;
+  expect(ngrok.forward).toHaveBeenCalledTimes(3);
+  expect(jest.mocked(ngrok.forward).mock.calls[2][0]).toMatchObject({ force_new_session: true });
+});
+
+it.each([
+  ['another reason', 'invalid authtoken'],
+  ['a longer error code', 'internal server error error_code: ERR_NGROK_8021'],
+])('does not retry an initial open that fails for %s', async (_, message) => {
+  jest.mocked(ngrok.forward).mockReset().mockRejectedValue(new Error(message));
+  await expect(startNgrokTunnelAsync(options)).rejects.toThrow(message);
+  expect(ngrok.forward).toHaveBeenCalledTimes(1);
+});
+
+it('fails with the abort reason when the caller aborts during the retry backoff', async () => {
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockRejectedValueOnce(new Error(ERR_802))
+    .mockResolvedValue(initial as never);
+  const startup = new AbortController();
+  const reason = new Error('startup aborted');
+  const opening = startNgrokTunnelAsync({ ...options, signal: startup.signal });
+  const rejected = expect(opening).rejects.toBe(reason);
+  await jest.advanceTimersByTimeAsync(500);
+  startup.abort(reason);
+  await rejected;
+  await jest.advanceTimersByTimeAsync(10_000);
+  expect(ngrok.forward).toHaveBeenCalledTimes(1);
+});
+
+it('does not open when the caller aborts while the local target starts', async () => {
+  const startup = new AbortController();
+  const reason = new Error('startup aborted');
+  const opening = startNgrokTunnelAsync({ ...options, signal: startup.signal });
+  startup.abort(reason);
+  await expect(opening).rejects.toBe(reason);
+  expect(ngrok.forward).not.toHaveBeenCalled();
+});
+
+it.each([1, 2])(
+  'fails with the abort reason and retires the late listener when the caller aborts while open %s is pending',
+  async pendingAttempt => {
+    let resolveOpening!: (value: ngrok.Listener) => void;
+    const pending = new Promise<ngrok.Listener>(resolve => (resolveOpening = resolve));
+    const forward = jest.mocked(ngrok.forward).mockReset();
+    if (pendingAttempt === 2) {
+      forward.mockRejectedValueOnce(new Error(ERR_802));
+    }
+    forward.mockReturnValueOnce(pending as never).mockResolvedValue(replacement as never);
+    const startup = new AbortController();
+    const reason = new Error('startup aborted');
+    const opening = startNgrokTunnelAsync({ ...options, signal: startup.signal });
+    const rejected = expect(opening).rejects.toBe(reason);
+    await jest.advanceTimersByTimeAsync(5_000);
+    expect(ngrok.forward).toHaveBeenCalledTimes(pendingAttempt);
+    startup.abort(reason);
+    await rejected;
+    resolveOpening(initial as never);
+    await jest.advanceTimersByTimeAsync(0);
+    expect(initial.close).toHaveBeenCalledTimes(1);
+    await jest.advanceTimersByTimeAsync(30_000);
+    expect(ngrok.forward).toHaveBeenCalledTimes(pendingAttempt);
+  }
+);
+
+it('stops retrying without a new open when the retry signal aborts during the backoff', async () => {
+  const error = new Error(ERR_802);
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockRejectedValueOnce(error)
+    .mockResolvedValue(initial as never);
+  const retries = new AbortController();
+  const opening = startNgrokTunnelAsync({ ...options, retrySignal: retries.signal });
+  const rejected = expect(opening).rejects.toBe(error);
+  await jest.advanceTimersByTimeAsync(500);
+  retries.abort();
+  await rejected;
+  await jest.advanceTimersByTimeAsync(10_000);
+  expect(ngrok.forward).toHaveBeenCalledTimes(1);
+});
+
+it('lets the open in progress finish when the retry signal aborts', async () => {
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
+  const retries = new AbortController();
+  const opening = startNgrokTunnelAsync({ ...options, retrySignal: retries.signal });
+  await jest.advanceTimersByTimeAsync(5_000);
+  retries.abort();
+  resolveOpening(initial as never);
+  const tunnel = await opening;
+  try {
+    expect(tunnel.url).toBe(url);
+    expect(initial.close).not.toHaveBeenCalled();
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('stops listening for the startup signal after startup fails', async () => {
+  jest.mocked(ngrok.forward).mockReset().mockRejectedValue(new Error('invalid authtoken'));
+  const startup = new AbortController();
+  const removeEventListener = jest.spyOn(startup.signal, 'removeEventListener');
+  await expect(startNgrokTunnelAsync({ ...options, signal: startup.signal })).rejects.toThrow(
+    'invalid authtoken'
+  );
+  expect(removeEventListener).toHaveBeenCalledWith('abort', expect.any(Function));
+});
+
+it('keeps the tunnel open when the startup signal aborts after startup', async () => {
+  const startup = new AbortController();
+  const tunnel = await startNgrokTunnelAsync({ ...options, signal: startup.signal });
+  try {
+    startup.abort();
+    await jest.advanceTimersByTimeAsync(15_000);
+    expect(initial.close).not.toHaveBeenCalled();
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+  } finally {
+    await tunnel.stopAsync();
+  }
+  expect(initial.close).toHaveBeenCalledTimes(1);
+});
+
+it('retries a rejected close of a late listener after initial tunnel creation timed out', async () => {
   let resolveOpening!: (value: ngrok.Listener) => void;
   jest
     .mocked(ngrok.forward)
@@ -590,7 +840,7 @@ it('retries a rejected close after initial tunnel creation timed out', async ()
     .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
   const opening = startNgrokTunnelAsync(options);
   const rejected = expect(opening).rejects.toThrow('Ngrok tunnel open timed out');
-  await jest.advanceTimersByTimeAsync(15_000);
+  await jest.advanceTimersByTimeAsync(19_000);
   await rejected;
   initial.close.mockRejectedValueOnce(new Error('temporary unlisten failure'));
   resolveOpening(initial as never);
@@ -816,8 +1066,10 @@ it.each(['resolve', 'reject'])(
     const opening = startNgrokTunnelAsync(options);
     const rejected = expect(opening).rejects.toThrow('open timed out');
     await new Promise<void>(resolve => setImmediate(resolve));
-    await jest.advanceTimersByTimeAsync(15_000);
+    // The first open times out, and startup does not retry it while it is still pending.
+    await jest.advanceTimersByTimeAsync(19_000);
     await rejected;
+    expect(ngrok.forward).toHaveBeenCalledTimes(1);
     const targetPort = (jest.mocked(ngrok.forward).mock.calls[0][0] as ngrok.Config).addr as number;
     if (outcome === 'resolve') {
       resolveOpening(replacement as never);

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

@@ -0,0 +1,527 @@
+import { type bunyan } from '@expo/logger';
+import { once } from 'node:events';
+import http from 'node:http';
+
+import {
+  readExpoDeviceHubInputLogAsync,
+  readServeSimInputLogAsync,
+  startPreviewActivityPolling,
+} from '../previewActivity';
+
+const token = 'test-session-token';
+let server: http.Server;
+let port: number;
+let events: { id: number; at?: string; timestamp?: string }[];
+let status: number;
+let requests: { url?: string; authorization?: string }[];
+let rawBody: string | undefined;
+let replaying: boolean;
+let replayStartedAt: string | null;
+
+function createLoggerMock(): bunyan {
+  return { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
+}
+
+beforeEach(async () => {
+  events = [];
+  status = 200;
+  requests = [];
+  rawBody = undefined;
+  replaying = false;
+  replayStartedAt = null;
+  server = http.createServer((req, res) => {
+    requests.push({ url: req.url, authorization: req.headers.authorization });
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(rawBody ?? JSON.stringify({ events: events.slice(-1), replaying, replayStartedAt }));
+  });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  port = (server.address() as { port: number }).port;
+});
+
+afterEach(async () => {
+  await new Promise<void>(resolve => server.close(() => resolve()));
+});
+
+describe(readServeSimInputLogAsync, () => {
+  it('reads the newest event ID with the session token', async () => {
+    events = [{ id: 3 }, { id: 7 }];
+    await expect(readServeSimInputLogAsync({ port, token })).resolves.toEqual({
+      latestEventId: 7,
+      latestEventAt: undefined,
+      replaying: false,
+      replayStartedAt: undefined,
+    });
+    expect(requests).toEqual([{ url: '/api/event-log?limit=1', authorization: `Bearer ${token}` }]);
+  });
+
+  it('returns undefined when serve-sim has logged no event', async () => {
+    await expect(readServeSimInputLogAsync({ port, token })).resolves.toEqual({
+      latestEventId: undefined,
+      latestEventAt: undefined,
+      replaying: false,
+      replayStartedAt: undefined,
+    });
+  });
+
+  it.each([
+    ['unparseable JSON', 'not json'],
+    ['a body without an events array', '{}'],
+    ['an entry without a numeric ID', '{"events":[{"id":"7"}]}'],
+  ])('rejects %s', async (_, body) => {
+    rawBody = body;
+    await expect(readServeSimInputLogAsync({ port, token })).rejects.toThrow('serve-sim event log');
+  });
+
+  it('rejects a refused request', async () => {
+    status = 401;
+    await expect(readServeSimInputLogAsync({ port, token })).rejects.toThrow('401');
+  });
+});
+
+describe(readExpoDeviceHubInputLogAsync, () => {
+  it('reads the newest entry time from either server', async () => {
+    events = [{ id: 2, timestamp: '2026-11-13T12:00:02.000Z' }];
+    await expect(readServeSimInputLogAsync({ port, token })).resolves.toMatchObject({
+      latestEventId: 2,
+      latestEventAt: '2026-11-13T12:00:02.000Z',
+    });
+    events = [{ id: 3, at: '2026-11-13T12:00:03.000Z' }];
+    await expect(readExpoDeviceHubInputLogAsync({ port, token })).resolves.toMatchObject({
+      latestEventId: 3,
+      latestEventAt: '2026-11-13T12:00:03.000Z',
+    });
+  });
+
+  it('reads the newest recorded Android input through the hub with the session token', async () => {
+    events = [{ id: 3 }, { id: 9 }];
+    await expect(readExpoDeviceHubInputLogAsync({ port, token })).resolves.toEqual({
+      latestEventId: 9,
+      latestEventAt: undefined,
+      replaying: false,
+      replayStartedAt: undefined,
+    });
+    expect(requests).toEqual([
+      { url: '/vendor/serve-emu/api/session?limit=1', authorization: `Bearer ${token}` },
+    ]);
+  });
+
+  it('reports a running replay and when it started', async () => {
+    replaying = true;
+    replayStartedAt = '2026-11-13T12:00:00.000Z';
+    await expect(readExpoDeviceHubInputLogAsync({ port, token })).resolves.toEqual({
+      latestEventId: undefined,
+      latestEventAt: undefined,
+      replaying: true,
+      replayStartedAt: '2026-11-13T12:00:00.000Z',
+    });
+  });
+
+  it('reads replay state from the paged response shape', async () => {
+    rawBody = JSON.stringify({
+      events: [{ id: 4, at: '2026-11-13T12:00:01.000Z' }],
+      session: { replaying: true, replayStartedAt: '2026-11-13T12:00:00.000Z' },
+    });
+    await expect(readExpoDeviceHubInputLogAsync({ port, token })).resolves.toEqual({
+      latestEventId: 4,
+      latestEventAt: '2026-11-13T12:00:01.000Z',
+      replaying: true,
+      replayStartedAt: '2026-11-13T12:00:00.000Z',
+    });
+  });
+
+  it('returns no event ID when the hub has recorded no input', async () => {
+    await expect(readExpoDeviceHubInputLogAsync({ port, token })).resolves.toEqual({
+      latestEventId: undefined,
+      latestEventAt: undefined,
+      replaying: false,
+      replayStartedAt: undefined,
+    });
+  });
+
+  it.each([
+    ['unparseable JSON', 'not json'],
+    ['a body without an events array', '{}'],
+    ['an entry without a numeric ID', '{"events":[{"id":"9"}]}'],
+  ])('rejects %s', async (_, body) => {
+    rawBody = body;
+    await expect(readExpoDeviceHubInputLogAsync({ port, token })).rejects.toThrow(
+      'expo-device-hub input log'
+    );
+  });
+});
+
+describe(startPreviewActivityPolling, () => {
+  async function waitForRequestsAsync(count: number): Promise<void> {
+    while (requests.length < count) {
+      await new Promise(resolve => setTimeout(resolve, 5));
+    }
+  }
+
+  it('reports activity only when a new event appears', async () => {
+    const polling = startPreviewActivityPolling({
+      server: 'serve-sim',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      expect(polling.getLastActivityObservedAt()).toBeUndefined();
+
+      events = [{ id: 1 }];
+      const before = Date.now();
+      await waitForRequestsAsync(requests.length + 2);
+      const firstSeen = polling.getLastActivityObservedAt();
+      expect(firstSeen?.getTime()).toBeGreaterThanOrEqual(before);
+
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBe(firstSeen);
+
+      events = [{ id: 1 }, { id: 2 }];
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).not.toBe(firstSeen);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports current activity while the event log fails, and warns once', async () => {
+    status = 500;
+    const logger = createLoggerMock();
+    const polling = startPreviewActivityPolling({
+      server: 'serve-sim',
+      port,
+      token,
+      logger,
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(3);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+      const before = Date.now();
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+
+      status = 200;
+      events = [{ id: 4 }];
+      await waitForRequestsAsync(requests.length + 2);
+      const observedAt = polling.getLastActivityObservedAt();
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBe(observedAt);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('keeps the last observation while serve-sim refuses connections', async () => {
+    await new Promise<void>(resolve => server.close(() => resolve()));
+    server = http.createServer();
+    const polling = startPreviewActivityPolling({
+      server: 'serve-sim',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(polling.getLastActivityObservedAt()).toBeUndefined();
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports current activity when serve-sim drops the connection mid-response', async () => {
+    server.removeAllListeners('request');
+    server.on('request', (req, res) => {
+      requests.push({ url: req.url });
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': '100' });
+      res.write('{"events":');
+      setImmediate(() => res.socket?.destroy());
+    });
+    const polling = startPreviewActivityPolling({
+      server: 'serve-sim',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(3);
+      const before = Date.now();
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports current activity while serve-sim answers without an event log', async () => {
+    status = 404;
+    const polling = startPreviewActivityPolling({
+      server: 'serve-sim',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      const before = Date.now();
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+
+      status = 200;
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBeUndefined();
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports Android preview input from expo-device-hub', async () => {
+    const polling = startPreviewActivityPolling({
+      server: 'expo-device-hub',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      expect(polling.getLastActivityObservedAt()).toBeUndefined();
+      expect(requests[0].url).toBe('/vendor/serve-emu/api/session?limit=1');
+
+      events = [{ id: 1 }];
+      const before = Date.now();
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports activity while expo-device-hub replays recorded input', async () => {
+    replaying = true;
+    const polling = startPreviewActivityPolling({
+      server: 'expo-device-hub',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      const before = Date.now();
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports a replay that started and finished between two reads', async () => {
+    events = [{ id: 1 }];
+    const polling = startPreviewActivityPolling({
+      server: 'expo-device-hub',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      const observedAt = polling.getLastActivityObservedAt();
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBe(observedAt);
+
+      replayStartedAt = '2026-11-13T12:00:00.000Z';
+      await waitForRequestsAsync(requests.length + 2);
+      const replayObservedAt = polling.getLastActivityObservedAt();
+      expect(replayObservedAt).not.toBe(observedAt);
+
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBe(replayObservedAt);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('counts input in a new recording that repeats the last ID between two reads', async () => {
+    events = [{ id: 1, at: '2026-11-13T12:00:00.000Z' }];
+    const polling = startPreviewActivityPolling({
+      server: 'expo-device-hub',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      const firstSeen = polling.getLastActivityObservedAt();
+      expect(firstSeen).toBeDefined();
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).toBe(firstSeen);
+
+      events = [{ id: 1, at: '2026-11-13T12:05:00.000Z' }];
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).not.toBe(firstSeen);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('counts input in a new recording whose IDs start again', async () => {
+    events = [{ id: 1 }];
+    const polling = startPreviewActivityPolling({
+      server: 'expo-device-hub',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      const firstSeen = polling.getLastActivityObservedAt();
+      expect(firstSeen).toBeDefined();
+
+      events = [];
+      await waitForRequestsAsync(requests.length + 2);
+      events = [{ id: 1 }];
+      await waitForRequestsAsync(requests.length + 2);
+      expect(polling.getLastActivityObservedAt()).not.toBe(firstSeen);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it.each([
+    ['before its headers', 'headers'],
+    ['after its headers', 'body'],
+  ] as const)(
+    'reports current activity while an expo-device-hub read times out %s',
+    async (_, stall) => {
+      events = [{ id: 1 }];
+      let stalled = false;
+      server.removeAllListeners('request');
+      server.on('request', (req, res) => {
+        requests.push({ url: req.url });
+        if (stalled && stall === 'headers') {
+          return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        if (stalled) {
+          res.write('{"events":[');
+          return;
+        }
+        res.end(JSON.stringify({ events, replaying: false, replayStartedAt: null }));
+      });
+      const logger = createLoggerMock();
+      const polling = startPreviewActivityPolling({
+        server: 'expo-device-hub',
+        port,
+        token,
+        logger,
+        pollIntervalMs: 10,
+        requestTimeoutMs: 100,
+      });
+      try {
+        while (polling.getLastActivityObservedAt() === undefined) {
+          await new Promise(resolve => setTimeout(resolve, 5));
+        }
+        const observedAt = polling.getLastActivityObservedAt();
+
+        stalled = true;
+        // The next request starts only after the stalled read times out.
+        await waitForRequestsAsync(requests.length + 2);
+        const reportedAt = polling.getLastActivityObservedAt();
+        expect(reportedAt).not.toBe(observedAt);
+        expect(jest.mocked(logger.warn).mock.calls[0][1]).toContain(
+          'idle timeout does not stop this session'
+        );
+      } finally {
+        await polling.stopAsync();
+        server.closeAllConnections();
+      }
+    }
+  );
+
+  it('warns about an unreadable log after an earlier device outage', async () => {
+    const logger = createLoggerMock();
+    status = 503;
+    const polling = startPreviewActivityPolling({
+      server: 'expo-device-hub',
+      port,
+      token,
+      logger,
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+
+      status = 500;
+      await waitForRequestsAsync(requests.length + 2);
+      expect(logger.warn).toHaveBeenCalledTimes(2);
+      expect(jest.mocked(logger.warn).mock.calls[1][1]).toContain(
+        'idle timeout does not stop this session'
+      );
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('keeps the last observation while expo-device-hub has no device', async () => {
+    events = [{ id: 1 }];
+    const polling = startPreviewActivityPolling({
+      server: 'expo-device-hub',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      const observedAt = polling.getLastActivityObservedAt();
+      expect(observedAt).toBeDefined();
+
+      status = 503;
+      await waitForRequestsAsync(requests.length + 3);
+      expect(polling.getLastActivityObservedAt()).toBe(observedAt);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('reports current activity when serve-sim answers 503', async () => {
+    status = 503;
+    const polling = startPreviewActivityPolling({
+      server: 'serve-sim',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    try {
+      await waitForRequestsAsync(2);
+      const before = Date.now();
+      expect(polling.getLastActivityObservedAt()?.getTime()).toBeGreaterThanOrEqual(before);
+    } finally {
+      await polling.stopAsync();
+    }
+  });
+
+  it('stops polling after stopAsync', async () => {
+    const polling = startPreviewActivityPolling({
+      server: 'serve-sim',
+      port,
+      token,
+      logger: createLoggerMock(),
+      pollIntervalMs: 10,
+    });
+    await waitForRequestsAsync(1);
+    await polling.stopAsync();
+    const count = requests.length;
+    await new Promise(resolve => setTimeout(resolve, 50));
+    expect(requests.length).toBe(count);
+  });
+});

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

@@ -29,6 +29,7 @@ import { sleepAsync } from '../../../utils/retry';
 import { uploadDeviceRunSessionScreenRecordingsAsync } from '../deviceRunSessionScreenRecordings';
 import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 import {
+  TOOL_TUNNEL_TEARDOWN_OPTIONS,
   createCorsOriginsInputProvider,
   createFrameAncestorsInputProvider,
   createIosSessionStartupInputProviders,
@@ -38,6 +39,7 @@ import {
   describeServeSimLaunch,
   ensureFfmpegInstalledOnceAsync,
   fetchWebPreviewTurnArgsAsync,
+  finishRemoteSessionAsync,
   parseCorsOriginsInput,
   parseFrameAncestorsInput,
   parseServeSimLaunchInputs,
@@ -226,6 +228,89 @@ function createEnvMock(): BuildStepEnv {
   return { DEVICE_RUN_SESSION_ID: 'drs-id' } as unknown as BuildStepEnv;
 }
 
+describe(finishRemoteSessionAsync, () => {
+  const tunnelError = new Error('tunnel stop timed out');
+  const serverError = new Error('server stop failed');
+
+  beforeEach(() => {
+    jest.mocked(Sentry).capture.mockReset();
+  });
+
+  it('does not fail a successful session when only a tunnel cannot stop', async () => {
+    const logger = { warn: jest.fn() } as unknown as bunyan;
+    await expect(
+      finishRemoteSessionAsync({
+        logger,
+        sessionFailed: false,
+        teardown: [
+          ['Appium tunnel', Promise.reject(tunnelError), TOOL_TUNNEL_TEARDOWN_OPTIONS],
+          ['Appium server', Promise.resolve()],
+        ],
+      })
+    ).resolves.toBeUndefined();
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: tunnelError },
+      'Could not stop the Appium tunnel during remote session teardown.'
+    );
+    expect(jest.mocked(Sentry).capture.mock.calls).toEqual([
+      [
+        'Could not stop the Appium tunnel after the remote session ended',
+        tunnelError,
+        { level: 'warning' },
+      ],
+    ]);
+  });
+
+  it('fails a successful session with the first failure that fails the session', async () => {
+    const logger = { warn: jest.fn() } as unknown as bunyan;
+    await expect(
+      finishRemoteSessionAsync({
+        logger,
+        sessionFailed: false,
+        teardown: [
+          ['Appium tunnel', Promise.reject(tunnelError), TOOL_TUNNEL_TEARDOWN_OPTIONS],
+          ['Appium server', Promise.reject(serverError)],
+        ],
+      })
+    ).rejects.toBe(serverError);
+    expect(logger.warn).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(Sentry).capture.mock.calls).toEqual([
+      [
+        'Could not stop the Appium tunnel after the remote session ended',
+        tunnelError,
+        { level: 'warning' },
+      ],
+    ]);
+  });
+
+  it('reports every teardown failure to Sentry when the session failed', async () => {
+    const logger = { warn: jest.fn() } as unknown as bunyan;
+    await expect(
+      finishRemoteSessionAsync({
+        logger,
+        sessionFailed: true,
+        teardown: [
+          ['Appium tunnel', Promise.reject(tunnelError), TOOL_TUNNEL_TEARDOWN_OPTIONS],
+          ['Appium server', Promise.reject(serverError)],
+          ['session host', undefined],
+        ],
+      })
+    ).resolves.toBeUndefined();
+    expect(jest.mocked(Sentry).capture.mock.calls).toEqual([
+      [
+        'Could not stop the Appium tunnel after the remote session failed',
+        tunnelError,
+        { level: 'warning' },
+      ],
+      [
+        'Could not stop the Appium server after the remote session failed',
+        serverError,
+        { level: 'warning' },
+      ],
+    ]);
+  });
+});
+
 describe(createIosSessionStartupInputProviders, () => {
   it('declares optional inputs so existing workflows do not opt into owned startup', () => {
     const inputs = createIosSessionStartupInputProviders().map(provider =>

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__/serveSimActivity.test.ts

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

packages/build-tools/src/steps/utils/__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/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

@@ -42,6 +42,7 @@ import {
 } from './remoteDeviceRunSession';
 import { LOCAL_EGRESS_PROXY_HOST, readLocalEgressHandoffAsync } from './localEgress';
 import { withDeviceRunSessionTimeoutAsync } from './deviceRunSessionTimeout';
+import { EMULATOR_CAPTURE_REQUESTED_ENV } from './emulatorCapture';
 import {
   IosSimulatorRecordingUtils,
   SERVE_SIM_STOP_GRACE_PERIOD_MS,
@@ -54,7 +55,8 @@ import {
   isPreinstalledExpoGoAsync,
   readIosApplicationIdentifierAsync,
 } from './iosAppArtifact';
-import { type ServeSimActivityPolling, startServeSimActivityPolling } from './serveSimActivity';
+import { createServeSimPreviewCapture } from './serveSimPreviewCapture';
+import { type PreviewActivityPolling, startPreviewActivityPolling } from './previewActivity';
 import { verifyLocalEgressGuardAsync } from './localEgressGuard';
 import { type IosSimulatorUuid } from '../../utils/IosSimulatorUtils';
 import { createColdIosSessionAsync } from './coldIosSession';
@@ -72,6 +74,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,
@@ -370,7 +376,7 @@ export type DeviceWebPreview = {
 export type DeviceSessionHost = {
   /** The preview tunnel opened during startup, or a new one after closeAsync. */
   openPreviewAsync(): Promise<DeviceWebPreview>;
-  /** Last observed preview input. Always `undefined` on Android, which keeps no event log. */
+  /** Last observed preview input from the serve-sim (iOS) or expo-device-hub (Android) input log. */
   getLastPreviewActivityAt(): Date | undefined;
   /**
    * Terminal and idempotent. Finalization, host-stop and upload failures are logged and reported.
@@ -412,6 +418,11 @@ export type DeviceSessionHostOptions = {
   onStartupError?: (error: unknown) => void;
   networkCapture?: boolean;
   networkCaptureFields?: string[];
+  /**
+   * This session type runs an expo-device-hub that can use the experimental emulator capture.
+   * Only web preview sets it; the host rejects a capture request from any other session type.
+   */
+  emulatorCapture?: boolean;
 } & ServeSimLaunchOptions;
 
 export type DeviceSessionServerLaunch = {
@@ -525,6 +536,7 @@ async function startDeviceSessionHostInternalAsync(
     networkCaptureFields = [],
     bootEnv = {},
     preview,
+    emulatorCapture = false,
   }: DeviceSessionHostOptions,
   onFinished: (successful: boolean) => void,
   artifactLogger: bunyan,
@@ -532,6 +544,15 @@ async function startDeviceSessionHostInternalAsync(
 ): Promise<DeviceSessionHost> {
   signal?.throwIfAborted();
   const isAndroid = runtimePlatform === BuildRuntimePlatform.LINUX;
+  const requestedEmulatorCapture = env[EMULATOR_CAPTURE_REQUESTED_ENV];
+  if (isAndroid && requestedEmulatorCapture && !emulatorCapture) {
+    // Other session types run the latest expo-device-hub, which ignores the capture, so the
+    // session would start without the capture that it asked for.
+    throw new UserError(
+      'EAS_EMULATOR_CAPTURE_UNSUPPORTED_SESSION',
+      `The experimental emulator capture (expo-emulator-capture@${requestedEmulatorCapture}) works only in web preview sessions for now. Remove experimental_emulator_capture_version from eas/start_android_emulator, or start a web preview session.`
+    );
+  }
   if (
     Object.keys(bootEnv).length > 0 &&
     (runtimePlatform !== BuildRuntimePlatform.DARWIN || !iosSimulatorUdid)
@@ -603,13 +624,17 @@ async function startDeviceSessionHostInternalAsync(
   let previewToken: string | undefined;
   let previewTask: Promise<DeviceWebPreview> | null = null;
   const previewRetirementErrors: unknown[] = [];
+  // Stops new attempts to open the preview tunnel when the host finishes. An attempt in progress
+  // continues, so preview retirement still waits for it and closes its listener.
+  const previewRetryController = new AbortController();
   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;
   let previewFailed = false;
-  let previewActivity: ServeSimActivityPolling | null = null;
+  let previewActivity: PreviewActivityPolling | null = null;
 
   function openPreviewAsync(): Promise<DeviceWebPreview> {
     if (finishTask) {
@@ -629,6 +654,7 @@ async function startDeviceSessionHostInternalAsync(
         authtoken: preview.authtoken,
         healthCheck: { path: isAndroid ? '/readyz' : '/healthz' },
         logger,
+        retrySignal: previewRetryController.signal,
       });
       if (finishTask) {
         await withDeviceRunSessionTimeoutAsync(
@@ -766,11 +792,23 @@ async function startDeviceSessionHostInternalAsync(
       env: {
         ...env,
         ...bootEnv,
+        // The emulator start turns the experimental emulator capture on in the job env. Otherwise
+        // keep it off, so a Hub build with the capture on by default does not try to attach the
+        // agent with a debugger.
+        ...(isAndroid && env.EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE === undefined
+          ? { EXPO_DEVICE_HUB_EXPERIMENTAL_EMULATOR_CAPTURE: '0' }
+          : {}),
         ...(isAndroid ? {} : { TMPDIR: serveSimTmpdir, SERVE_SIM_STATE_DIR: serveSimStateDir }),
         EXPO_DEVICE_HUB_SCREENSHOT_DIRECTORY: screenshots.directory,
         ...(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,
     };
@@ -787,6 +825,7 @@ async function startDeviceSessionHostInternalAsync(
     startup.abort(error);
     // Mark the opening tunnel as retired; its late-open path closes it.
     finishTask = Promise.resolve();
+    previewRetryController.abort();
     await Promise.allSettled([simulatorSetup, retirePreviewAsync()]);
     let hostStopped = true;
     try {
@@ -814,6 +853,7 @@ async function startDeviceSessionHostInternalAsync(
     finishAsync() {
       readinessController.abort(new Error('Simulator preview ended.'));
       return (finishTask ??= (async () => {
+        previewRetryController.abort();
         const previewRetirement = retirePreviewAsync();
         if (server.requiresPreviewRetirement) {
           // Confirm the tunnel is closed before stop, so the next session cannot reach this one.
@@ -827,6 +867,7 @@ async function startDeviceSessionHostInternalAsync(
             await sessionPreview?.stopAsync();
             await previewActivity?.stopAsync();
           },
+          cleanupPreviewCaptureAsync: async () => iosPreviewCapture?.cleanupAfterHostStoppedAsync(),
           previewServer,
           screenshots,
           serverName,
@@ -984,14 +1025,31 @@ async function startDeviceSessionHostInternalAsync(
     secrets.push(previewToken);
     if (!isAndroid) {
       IosSimulatorRecordingUtils.useServeSimPackage(packageSpec);
-      if (!finishTask) {
-        previewActivity = startServeSimActivityPolling({ port, token: previewToken, logger });
-      }
+    }
+    if (!finishTask) {
+      previewActivity = startPreviewActivityPolling({
+        server: isAndroid ? 'expo-device-hub' : 'serve-sim',
+        port,
+        token: previewToken,
+        logger,
+      });
     }
     // Android installed FFmpeg before launching the host. The optional thumbnail must not delay
     // readiness on macOS, so it starts after its encoder is installed there.
     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,
@@ -1005,6 +1063,7 @@ async function startDeviceSessionHostInternalAsync(
           logger,
           captureAsync: signal =>
             captureDeviceRunSessionPreviewAsync({
+              captureIosScreenshotAsync: iosPreviewCapture?.captureAsync,
               runtimePlatform,
               device: previewDevice ?? device,
               env,
@@ -1080,6 +1139,7 @@ async function finishDeviceSessionHostAsync(
   {
     previewRetirement,
     stopSessionPreviewAsync,
+    cleanupPreviewCaptureAsync,
     previewServer,
     screenshots,
     serverName,
@@ -1091,6 +1151,7 @@ async function finishDeviceSessionHostAsync(
   }: {
     previewRetirement: Promise<boolean>;
     stopSessionPreviewAsync: () => Promise<void>;
+    cleanupPreviewCaptureAsync: () => Promise<void>;
     previewServer: DetachedProcessHandle;
     screenshots: { finishAsync(hostStopped: boolean): Promise<void> };
     serverName: string;
@@ -1124,6 +1185,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/emulatorCapture.ts

@@ -0,0 +1,99 @@
+import { UserError } from '@expo/eas-build-job';
+import { type bunyan } from '@expo/logger';
+import { type BuildStepEnv } from '@expo/steps';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { installIsolatedNpmPackageAsync } from '../../utils/installIsolatedNpmPackageAsync';
+
+// Experimental emulator capture. The Android Emulator preloads the expo-emulator-capture agent,
+// which serves the emulator screen as H.264 on a Unix socket, and expo-device-hub streams the
+// screen from that socket. The step input names the agent version, so a new agent release needs
+// no change in build-tools or in the backend, while the package keeps its library at this path.
+
+const PACKAGE_NAME = 'expo-emulator-capture';
+/**
+ * `eas/start_android_emulator` sets this job env variable to the requested agent version. The
+ * session host rejects it in every session type except web preview, the only one that runs an
+ * expo-device-hub version that can use the capture for now.
+ */
+export const EMULATOR_CAPTURE_REQUESTED_ENV = 'EAS_EXPERIMENTAL_EMULATOR_CAPTURE_VERSION';
+const LINUX_AGENT_LIBRARY = path.join(
+  'node_modules',
+  PACKAGE_NAME,
+  'dist',
+  'linux-x64',
+  'libexpo_emulator_capture.so'
+);
+/**
+ * An npm version, a simple range such as `0.1.x`, or a dist-tag: letters, digits, `.`, `_` and `-`.
+ * It keeps out specs that install another package, such as `npm:`, `file:` or git URLs. eas-cli
+ * and www check the same pattern.
+ */
+const VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z._-]{0,127}$/;
+/** The registry normally answers in seconds; a stalled install must not hold the emulator. */
+const INSTALL_TIMEOUT_MS = 5 * 60_000;
+
+/** The expo-emulator-capture version to preload, or undefined when the capture is off. */
+export function parseExperimentalEmulatorCaptureVersionInput(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  if (typeof value !== 'string' || !VERSION_PATTERN.test(value)) {
+    throw new UserError(
+      'EAS_EMULATOR_CAPTURE_INVALID_VERSION',
+      `experimental_emulator_capture_version must be an npm version or dist-tag of ${PACKAGE_NAME}, made of letters, digits, ".", "_" and "-".`
+    );
+  }
+  return value;
+}
+
+/**
+ * Installs the agent package and returns the path of its library. Returns undefined after a
+ * warning when the agent cannot run on this host or the install fails. The emulator then starts
+ * as it does without the capture.
+ */
+export async function installEmulatorCaptureAsync({
+  version,
+  env,
+  logger,
+}: {
+  version: string;
+  env: BuildStepEnv;
+  logger: bunyan;
+}): Promise<string | undefined> {
+  if (process.platform !== 'linux' || process.arch !== 'x64') {
+    logger.warn(
+      `The experimental emulator capture runs only on Linux x86-64 hosts. The emulator starts without ${PACKAGE_NAME}.`
+    );
+    return undefined;
+  }
+  let directory: string;
+  try {
+    directory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'eas-emulator-capture-package-'));
+    logger.info(`Installing ${PACKAGE_NAME}@${version} for the experimental emulator capture.`);
+    await installIsolatedNpmPackageAsync({
+      packageSpec: `${PACKAGE_NAME}@${version}`,
+      directory,
+      npmCacheUrl: env.EAS_BUILD_NPM_CACHE_URL,
+      pathEnv: env.PATH,
+      logger,
+      signal: AbortSignal.timeout(INSTALL_TIMEOUT_MS),
+    });
+  } catch (err) {
+    logger.warn(
+      { err },
+      `Could not install ${PACKAGE_NAME}@${version}. The emulator starts without it.`
+    );
+    return undefined;
+  }
+  const library = path.join(directory, LINUX_AGENT_LIBRARY);
+  if (!fs.existsSync(library)) {
+    logger.warn(
+      `${PACKAGE_NAME}@${version} has no Linux x86-64 agent at ${library}. The emulator starts without it.`
+    );
+    return undefined;
+  }
+  return library;
+}

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/ngrokTunnel.ts

@@ -12,10 +12,23 @@ import { withDeviceRunSessionTimeoutAsync } from './deviceRunSessionTimeout';
 const PROBE_INTERVAL_MS = 15_000;
 const FAILURE_THRESHOLD = 3;
 const STOP_TIMEOUT_MS = 4_000;
+const OPEN_TIMEOUT_MS = 15_000;
+// @ngrok/ngrok runs one open at a time, so nothing can open again until a timed-out open
+// settles. The first open waits longer instead, and keeps a listener that arrives late. Retries
+// use OPEN_TIMEOUT_MS, so all attempts fit in the 60-second preview opening bound.
+const FIRST_OPEN_TIMEOUT_MS = 19_000;
+const INITIAL_OPEN_ATTEMPTS = 3;
+const INITIAL_OPEN_RETRY_DELAY_MS = 1_000;
+/** ngrok error codes for failed control-plane requests that can succeed on a retry. */
+const RETRYABLE_NGROK_ERROR_CODES = new Set(['ERR_NGROK_802']);
 
 export type NgrokTunnelHandle = {
   url: string;
   subdomainId: string;
+  /**
+   * Stops the tunnel. The local proxy drops every connection at once; then the listeners close.
+   * Rejects when the stop does not complete within the stop time-out.
+   */
   stopAsync: () => Promise<void>;
 };
 
@@ -28,6 +41,8 @@ export async function startNgrokTunnelAsync({
   rewriteHostHeader,
   healthCheck,
   logger,
+  signal: startupSignal,
+  retrySignal,
 }: {
   port: number;
   subdomainPrefix: string;
@@ -37,11 +52,21 @@ export async function startNgrokTunnelAsync({
   rewriteHostHeader?: boolean;
   healthCheck?: { path: string; statuses?: number[] };
   logger: bunyan;
+  /** Cancels startup, including retries of the first open. It has no effect after startup. */
+  signal?: AbortSignal;
+  /**
+   * Stops new attempts of the first open without cancelling the attempt in progress, so the
+   * caller can still wait for that attempt and close its listener. The first attempt always starts.
+   */
+  retrySignal?: AbortSignal;
 }): Promise<NgrokTunnelHandle> {
+  startupSignal?.throwIfAborted();
   const domain = `${subdomainPrefix}-${subdomainId}.${baseDomain}`;
   const controller = new AbortController();
   const { signal } = controller;
   const sockets = new Set<Socket>();
+  // After an abort, this proxy drops every connection, even while an ngrok listener is still open.
+  // Session teardown relies on this (TOOL_TUNNEL_TEARDOWN_OPTIONS), so keep it when changing this.
   const target = createServer({ allowHalfOpen: true }, client => {
     if (signal.aborted) {
       client.destroy();
@@ -154,10 +179,18 @@ export async function startNgrokTunnelAsync({
     }
   }
 
-  async function openAsync(forceNewSession = false): Promise<ngrok.Listener> {
+  /**
+   * No open is queued behind a pending one: @ngrok/ngrok runs every forward behind one
+   * process-wide lock, so a new open cannot start until the pending one settles.
+   */
+  async function openAsync({
+    forceNewSession = false,
+    timeoutMs = OPEN_TIMEOUT_MS,
+  }: { forceNewSession?: boolean; timeoutMs?: number } = {}): Promise<ngrok.Listener> {
     if (pendingOpen) {
       throw new SystemError(`A previous ngrok tunnel open for ${domain} is still pending.`);
     }
+    const startedAt = Date.now();
     let acquired: ngrok.Listener | undefined;
     let retirement: Promise<void> | undefined;
     const retireAcquired = () => {
@@ -167,7 +200,7 @@ export async function startNgrokTunnelAsync({
     };
     try {
       return await withDeviceRunSessionTimeoutAsync(
-        { name: 'Ngrok tunnel open', timeoutMs: 15_000, signal },
+        { name: 'Ngrok tunnel open', timeoutMs, signal },
         async openSignal => {
           openSignal.throwIfAborted();
           const opening = ngrok
@@ -184,13 +217,28 @@ export async function startNgrokTunnelAsync({
               pendingOpen = undefined;
             });
           pendingOpen = opening;
-          void opening
-            .then(() => {
+          // Records how long a timed-out or cancelled open takes to settle, to tune the time-out.
+          const logLateSettlement = (outcome: 'opened' | 'failed', err?: unknown) => {
+            const elapsedMs = Date.now() - startedAt;
+            logger.info(
+              { err, outcome, elapsedMs },
+              `ngrok tunnel open for ${domain} ${outcome} after ${elapsedMs} ms, after it timed out or was cancelled.`
+            );
+          };
+          void opening.then(
+            () => {
               if (openSignal.aborted) {
+                logLateSettlement('opened');
                 retireAcquired();
               }
-            })
-            .catch(() => releaseTarget());
+            },
+            err => {
+              if (openSignal.aborted) {
+                logLateSettlement('failed', err);
+              }
+              releaseTarget();
+            }
+          );
           const listener = await opening;
           openSignal.throwIfAborted();
           return listener;
@@ -202,10 +250,56 @@ export async function startNgrokTunnelAsync({
     }
   }
 
+  // ngrok sometimes rejects an open because a control-plane request failed (for example
+  // ERR_NGROK_802), so a rejected first open is retried before the session fails. A timed-out
+  // open is not retried: it still holds the ngrok lock, so a retry would only wait behind it.
+  async function openInitialAsync(): Promise<ngrok.Listener> {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await openAsync({
+          // ERR_NGROK_802 is a server error while the endpoint binds on the shared agent session,
+          // so a retry connects a new session, which can reach a different ngrok server.
+          // @ngrok/ngrok 1.7.0 replaces its shared session but does not close the old one: the old
+          // session and its listeners stay connected until the process exits.
+          forceNewSession: attempt > 1,
+          timeoutMs: attempt === 1 ? FIRST_OPEN_TIMEOUT_MS : OPEN_TIMEOUT_MS,
+        });
+      } catch (err) {
+        // A cancelled startup fails with the caller's reason, so the caller can tell it from an error.
+        signal.throwIfAborted();
+        if (
+          attempt >= INITIAL_OPEN_ATTEMPTS ||
+          !isRetryableNgrokError(err) ||
+          retrySignal?.aborted
+        ) {
+          throw err;
+        }
+        logger.warn(
+          { err, attempt },
+          `Could not open ngrok tunnel ${domain} (attempt ${attempt} of ${INITIAL_OPEN_ATTEMPTS}); retrying.`
+        );
+        await waitAsync(
+          INITIAL_OPEN_RETRY_DELAY_MS * attempt,
+          retrySignal ? AbortSignal.any([signal, retrySignal]) : signal
+        );
+        signal.throwIfAborted();
+        if (retrySignal?.aborted) {
+          throw err;
+        }
+      }
+    }
+  }
+
+  // Added after the target listens, so the finally below always removes it.
+  const abortStartup = () => controller.abort(startupSignal?.reason);
+  startupSignal?.addEventListener('abort', abortStartup, { once: true });
+  if (startupSignal?.aborted) {
+    abortStartup();
+  }
   logger.info(`Starting ngrok tunnel ${domain} -> http://localhost:${port}.`);
   let publicUrl: string | null;
   try {
-    currentListener = await openAsync();
+    currentListener = await openInitialAsync();
     publicUrl = currentListener.url();
     if (!publicUrl) {
       await closeAsync(currentListener, signal);
@@ -216,6 +310,8 @@ export async function startNgrokTunnelAsync({
     controller.abort();
     releaseTarget();
     throw error;
+  } finally {
+    startupSignal?.removeEventListener('abort', abortStartup);
   }
 
   const url = publicUrl;
@@ -299,7 +395,7 @@ export async function startNgrokTunnelAsync({
       }
       attempts++;
       try {
-        const reopened = await openAsync(/* forceNewSession */ true);
+        const reopened = await openAsync({ forceNewSession: true });
         if (reopened.url() !== url) {
           await closeAsync(reopened, signal);
           throw new SystemError(
@@ -350,6 +446,26 @@ export async function startNgrokTunnelAsync({
   };
 }
 
+function isRetryableNgrokError(err: unknown): boolean {
+  const code = getNgrokErrorCode(err);
+  return code !== null && RETRYABLE_NGROK_ERROR_CODES.has(code);
+}
+
+/**
+ * The ngrok error code of a failed open. @ngrok/ngrok sets `errorCode` from the message. When it is
+ * missing, the code is read from the message here.
+ */
+function getNgrokErrorCode(err: unknown): string | null {
+  if (!(err instanceof Error)) {
+    return null;
+  }
+  const { errorCode } = err as { errorCode?: unknown };
+  if (typeof errorCode === 'string') {
+    return errorCode;
+  }
+  return /\berror_code: (ERR_NGROK_\d+)\b/.exec(err.message)?.[1] ?? null;
+}
+
 function waitAsync(ms: number, signal: AbortSignal): Promise<boolean> {
   if (signal.aborted) {
     return Promise.resolve(false);

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

@@ -0,0 +1,261 @@
+import { type bunyan } from '@expo/logger';
+
+const POLL_INTERVAL_MS = 5_000;
+const REQUEST_TIMEOUT_MS = 5_000;
+// expo-device-hub serves serve-emu, which records Android preview input, under this prefix.
+const EXPO_DEVICE_HUB_SERVE_EMU_PREFIX = '/vendor/serve-emu';
+
+/** The preview server whose input log counts as session activity. */
+export type PreviewActivityServer = 'serve-sim' | 'expo-device-hub';
+
+export type PreviewActivityPolling = {
+  /**
+   * When a new input log entry (input or host action, not stream traffic) was first seen. Reports
+   * now while a read fails for a reason other than a refused connection or a device-unavailable
+   * answer, so an unobservable session stays active.
+   */
+  getLastActivityObservedAt: () => Date | undefined;
+  stopAsync: () => Promise<void>;
+};
+
+/** What one read of the server's input log shows. */
+export type PreviewInputLogState = {
+  /** The newest entry's ID, or undefined when the log is empty. */
+  latestEventId: number | undefined;
+  /**
+   * When the server logged the newest entry. A new recording starts its IDs again at 1, so the ID
+   * alone can repeat for new input.
+   */
+  latestEventAt: string | undefined;
+  /** The server is replaying recorded input, which it does not log again. */
+  replaying: boolean;
+  /**
+   * When the latest replay started, kept after it ends, so a replay that runs entirely between two
+   * reads still shows up as a change.
+   */
+  replayStartedAt: string | undefined;
+};
+
+type ReadInputLogAsync = (options: {
+  port: number;
+  token: string;
+  signal?: AbortSignal;
+}) => Promise<PreviewInputLogState>;
+
+const READ_INPUT_LOG: Record<PreviewActivityServer, ReadInputLogAsync> = {
+  'serve-sim': readServeSimInputLogAsync,
+  'expo-device-hub': readExpoDeviceHubInputLogAsync,
+};
+
+/**
+ * The server is up but has no device to take input, such as an offline emulator. Like a down
+ * server, it receives no input, so the last observation stands.
+ */
+class PreviewDeviceUnavailableError extends Error {}
+
+/** Nothing listens on the port. A reset or dropped response can come from a running server. */
+function isServerDownError(err: unknown): boolean {
+  if (err instanceof PreviewDeviceUnavailableError) {
+    return true;
+  }
+  // Not `instanceof`: undici errors can come from another realm.
+  let error: unknown = err;
+  for (let depth = 0; depth < 5 && typeof error === 'object' && error !== null; depth++) {
+    const { code, cause } = error as { code?: unknown; cause?: unknown };
+    if (code === 'ECONNREFUSED') {
+      return true;
+    }
+    error = cause;
+  }
+  return false;
+}
+
+/**
+ * A changed newest event ID, a new replay, or a running replay counts as activity, timed by the
+ * local clock.
+ */
+export function startPreviewActivityPolling({
+  server,
+  port,
+  token,
+  logger,
+  pollIntervalMs = POLL_INTERVAL_MS,
+  requestTimeoutMs = REQUEST_TIMEOUT_MS,
+}: {
+  server: PreviewActivityServer;
+  port: number;
+  token: string;
+  logger: bunyan;
+  pollIntervalMs?: number;
+  requestTimeoutMs?: number;
+}): PreviewActivityPolling {
+  const readInputLogAsync = READ_INPUT_LOG[server];
+  const controller = new AbortController();
+  let lastEventKey: string | undefined;
+  let lastReplayStartedAt: string | undefined;
+  let lastActivityObservedAt: Date | undefined;
+  let eventLogUnavailable = false;
+  let didWarnUnavailable = false;
+  let didWarnDown = false;
+  let timer: NodeJS.Timeout | undefined;
+  let pending: Promise<void> = Promise.resolve();
+
+  const pollAsync = async (): Promise<void> => {
+    try {
+      const { latestEventId, latestEventAt, replaying, replayStartedAt } = await readInputLogAsync({
+        port,
+        token,
+        signal: AbortSignal.any([controller.signal, AbortSignal.timeout(requestTimeoutMs)]),
+      });
+      eventLogUnavailable = false;
+      const eventKey =
+        latestEventId === undefined ? undefined : `${latestEventId}@${latestEventAt ?? ''}`;
+      if (eventKey !== undefined && eventKey !== lastEventKey) {
+        lastActivityObservedAt = new Date();
+      }
+      lastEventKey = eventKey;
+      if (replayStartedAt !== undefined && replayStartedAt !== lastReplayStartedAt) {
+        lastReplayStartedAt = replayStartedAt;
+        lastActivityObservedAt = new Date();
+      }
+      if (replaying) {
+        lastActivityObservedAt = new Date();
+      }
+    } catch (err) {
+      if (controller.signal.aborted) {
+        return;
+      }
+      // Only a down server or device, which receives no input either, keeps the last observation.
+      // A timeout proves neither: expo-device-hub holds the read while it changes the capture
+      // source, and the open preview keeps taking input meanwhile.
+      eventLogUnavailable = !isServerDownError(err);
+      if (eventLogUnavailable && !didWarnUnavailable) {
+        didWarnUnavailable = true;
+        logger.warn(
+          { err },
+          `Could not read the ${server} input log. Preview input cannot be observed, so the ` +
+            'idle timeout does not stop this session while the log cannot be read.'
+        );
+      } else if (!eventLogUnavailable && !didWarnDown) {
+        didWarnDown = true;
+        logger.warn({ err }, `Could not read ${server} preview activity.`);
+      }
+    }
+  };
+  const tick = (): void => {
+    pending = pollAsync().finally(() => {
+      if (!controller.signal.aborted) {
+        timer = setTimeout(tick, pollIntervalMs);
+        timer.unref();
+      }
+    });
+  };
+  tick();
+  return {
+    getLastActivityObservedAt: () => (eventLogUnavailable ? new Date() : lastActivityObservedAt),
+    stopAsync: async () => {
+      controller.abort();
+      clearTimeout(timer);
+      await pending;
+    },
+  };
+}
+
+export async function readServeSimInputLogAsync({
+  port,
+  token,
+  signal,
+}: {
+  port: number;
+  token: string;
+  signal?: AbortSignal;
+}): Promise<PreviewInputLogState> {
+  return await readInputLogAsync({
+    url: `http://127.0.0.1:${port}/api/event-log?limit=1`,
+    token,
+    signal,
+    logName: 'serve-sim event log',
+  });
+}
+
+/**
+ * Reads serve-emu's session recording through expo-device-hub. It records browser preview and REST
+ * input: touches, keys, text, navigation buttons, and location. It does not record input sent with
+ * `record: false` (the preview's Reload button) or actions such as rotation and screenshots, so
+ * those alone do not keep a session active. Controller commands count through the session's own
+ * event stream. The hub scopes the request to its single device.
+ */
+export async function readExpoDeviceHubInputLogAsync({
+  port,
+  token,
+  signal,
+}: {
+  port: number;
+  token: string;
+  signal?: AbortSignal;
+}): Promise<PreviewInputLogState> {
+  return await readInputLogAsync({
+    // The hub returns the whole recording and ignores `limit`; serve-emu's paged route honors it.
+    url: `http://127.0.0.1:${port}${EXPO_DEVICE_HUB_SERVE_EMU_PREFIX}/api/session?limit=1`,
+    token,
+    signal,
+    logName: 'expo-device-hub input log',
+    // The hub answers 503 while it cannot reach the emulator.
+    deviceUnavailableStatus: 503,
+  });
+}
+
+async function readInputLogAsync({
+  url,
+  token,
+  signal,
+  logName,
+  deviceUnavailableStatus,
+}: {
+  url: string;
+  token: string;
+  signal?: AbortSignal;
+  logName: string;
+  deviceUnavailableStatus?: number;
+}): Promise<PreviewInputLogState> {
+  const response = await fetch(url, {
+    headers: { Authorization: `Bearer ${token}` },
+    signal,
+  });
+  if (!response.ok) {
+    await response.body?.cancel();
+    const message = `${logName} request failed: ${response.status}`;
+    throw response.status === deviceUnavailableStatus
+      ? new PreviewDeviceUnavailableError(message)
+      : new Error(message);
+  }
+  const text = await response.text();
+  type ReplayState = { replaying?: unknown; replayStartedAt?: unknown };
+  // The hub route returns the recorder snapshot; serve-emu's paged route nests it under `session`.
+  let body: ({ events?: unknown; session?: ReplayState } & ReplayState) | undefined;
+  try {
+    body = JSON.parse(text);
+  } catch {}
+  if (!Array.isArray(body?.events)) {
+    throw new Error(`${logName} response has no events array.`);
+  }
+  const replayState: ReplayState = body.session ?? body;
+  const replaying = replayState.replaying === true;
+  const replayStartedAt =
+    typeof replayState.replayStartedAt === 'string' ? replayState.replayStartedAt : undefined;
+  if (body.events.length === 0) {
+    return { latestEventId: undefined, latestEventAt: undefined, replaying, replayStartedAt };
+  }
+  const latest = body.events.at(-1) as { id?: unknown; at?: unknown; timestamp?: unknown } | null;
+  if (typeof latest?.id !== 'number') {
+    throw new Error(`${logName} entry has no numeric ID.`);
+  }
+  // serve-emu names the time `at`; serve-sim names it `timestamp`.
+  const at = latest.at ?? latest.timestamp;
+  return {
+    latestEventId: latest.id,
+    latestEventAt: typeof at === 'string' ? at : undefined,
+    replaying,
+    replayStartedAt,
+  };
+}

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

@@ -649,34 +649,66 @@ export async function stopDetachedProcessAsync(
 }
 
 /**
- * Runs every named teardown to completion and logs each failure. The first failure is rethrown
- * only when the session body succeeded, so a teardown error cannot replace the error that ended it.
+ * Teardown options for the stop of a tool tunnel (agent-device, Appium, or Argent) at the end of a
+ * session. The stop first makes the tunnel's local proxy drop every connection (see
+ * `startNgrokTunnelAsync`), so a listener that does not close in time cannot reach the session. The
+ * worker process exits after the job, and this closes the process's ngrok sessions. The warm-host
+ * preview tunnel does not use these options: its retirement still fails the session.
+ */
+export const TOOL_TUNNEL_TEARDOWN_OPTIONS = { failsSession: false } as const;
+
+/** A named task that `finishRemoteSessionAsync` waits for when a remote session ends. */
+export type RemoteSessionTeardown = [
+  name: string,
+  task: Promise<unknown> | undefined,
+  options?: {
+    /**
+     * False when a failure of this task cannot affect the user or a later session, so it is
+     * logged and reported to Sentry but does not fail a session that succeeded. Defaults to true.
+     */
+    failsSession?: boolean;
+  },
+];
+
+/**
+ * Runs every named teardown to completion and logs each failure. The first failure of a task that
+ * fails the session is rethrown only when the session body succeeded, so a teardown error cannot
+ * replace the error that ended it.
  */
 export async function finishRemoteSessionAsync({
   teardown,
   sessionFailed,
   logger,
 }: {
-  teardown: [name: string, task: Promise<unknown> | undefined][];
+  teardown: RemoteSessionTeardown[];
   sessionFailed: boolean;
   logger: bunyan;
 }): Promise<void> {
   const results = await Promise.allSettled(teardown.map(([, task]) => task));
-  const failures = results.flatMap((result, index) =>
-    result.status === 'rejected' ? [{ name: teardown[index][0], err: result.reason }] : []
-  );
-  for (const { name, err } of failures) {
+  const failures = results.flatMap((result, index) => {
+    if (result.status !== 'rejected') {
+      return [];
+    }
+    const [name, , options] = teardown[index];
+    return [{ name, err: result.reason, failsSession: options?.failsSession ?? true }];
+  });
+  for (const { name, err, failsSession } of failures) {
     logger.warn({ err }, `Could not stop the ${name} during remote session teardown.`);
-    if (sessionFailed) {
-      // The session error is what the step reports, so a swallowed teardown failure goes to Sentry.
+    if (sessionFailed || !failsSession) {
+      // The step does not report this failure, so it goes to Sentry.
       const error = err instanceof Error ? err : new Error(String(err));
-      Sentry.capture(`Could not stop the ${name} after the remote session failed`, error, {
-        level: 'warning',
-      });
+      Sentry.capture(
+        sessionFailed
+          ? `Could not stop the ${name} after the remote session failed`
+          : `Could not stop the ${name} after the remote session ended`,
+        error,
+        { level: 'warning' }
+      );
     }
   }
-  if (!sessionFailed && failures.length > 0) {
-    throw failures[0].err;
+  const sessionFailure = failures.find(({ failsSession }) => failsSession);
+  if (!sessionFailed && sessionFailure) {
+    throw sessionFailure.err;
   }
 }
 

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/serveSimActivity.ts

@@ -1,131 +0,0 @@
-import { type bunyan } from '@expo/logger';
-
-const POLL_INTERVAL_MS = 5_000;
-const REQUEST_TIMEOUT_MS = 5_000;
-
-export type ServeSimActivityPolling = {
-  /**
-   * When a new event log entry (input or host action, not stream traffic) was first seen. Reports
-   * now while the log is unreadable but serve-sim is up, so an unobservable session stays active.
-   */
-  getLastActivityObservedAt: () => Date | undefined;
-  stopAsync: () => Promise<void>;
-};
-
-/** Nothing listens on the port. A reset or dropped response can come from a running serve-sim. */
-function isServeSimDownError(err: unknown): boolean {
-  // Not `instanceof`: undici errors can come from another realm.
-  let error: unknown = err;
-  for (let depth = 0; depth < 5 && typeof error === 'object' && error !== null; depth++) {
-    const { code, cause } = error as { code?: unknown; cause?: unknown };
-    if (code === 'ECONNREFUSED') {
-      return true;
-    }
-    error = cause;
-  }
-  return false;
-}
-
-/** A changed newest event ID counts as activity, timed by the local clock. */
-export function startServeSimActivityPolling({
-  port,
-  token,
-  logger,
-  pollIntervalMs = POLL_INTERVAL_MS,
-}: {
-  port: number;
-  token: string;
-  logger: bunyan;
-  pollIntervalMs?: number;
-}): ServeSimActivityPolling {
-  const controller = new AbortController();
-  let lastEventId: number | undefined;
-  let lastActivityObservedAt: Date | undefined;
-  let eventLogUnavailable = false;
-  let didWarn = false;
-  let timer: NodeJS.Timeout | undefined;
-  let pending: Promise<void> = Promise.resolve();
-
-  const pollAsync = async (): Promise<void> => {
-    try {
-      const eventId = await fetchLatestServeSimEventIdAsync({
-        port,
-        token,
-        signal: AbortSignal.any([controller.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]),
-      });
-      eventLogUnavailable = false;
-      if (eventId !== undefined && eventId !== lastEventId) {
-        lastEventId = eventId;
-        lastActivityObservedAt = new Date();
-      }
-    } catch (err) {
-      if (controller.signal.aborted) {
-        return;
-      }
-      // Only a down serve-sim, which receives no input either, keeps the last observation.
-      eventLogUnavailable = !isServeSimDownError(err);
-      if (!didWarn) {
-        didWarn = true;
-        logger.warn(
-          { err },
-          eventLogUnavailable
-            ? 'Could not read the serve-sim event log. Preview input cannot be observed, so the ' +
-                'idle timeout does not stop this session.'
-            : 'Could not read serve-sim preview activity.'
-        );
-      }
-    }
-  };
-  const tick = (): void => {
-    pending = pollAsync().finally(() => {
-      if (!controller.signal.aborted) {
-        timer = setTimeout(tick, pollIntervalMs);
-        timer.unref();
-      }
-    });
-  };
-  tick();
-  return {
-    getLastActivityObservedAt: () => (eventLogUnavailable ? new Date() : lastActivityObservedAt),
-    stopAsync: async () => {
-      controller.abort();
-      clearTimeout(timer);
-      await pending;
-    },
-  };
-}
-
-export async function fetchLatestServeSimEventIdAsync({
-  port,
-  token,
-  signal,
-}: {
-  port: number;
-  token: string;
-  signal?: AbortSignal;
-}): Promise<number | undefined> {
-  const response = await fetch(`http://127.0.0.1:${port}/api/event-log?limit=1`, {
-    headers: { Authorization: `Bearer ${token}` },
-    signal,
-  });
-  if (!response.ok) {
-    await response.body?.cancel();
-    throw new Error(`serve-sim event log request failed: ${response.status}`);
-  }
-  const text = await response.text();
-  let body: { events?: unknown } | undefined;
-  try {
-    body = JSON.parse(text);
-  } catch {}
-  if (!Array.isArray(body?.events)) {
-    throw new Error('serve-sim event log response has no events array.');
-  }
-  if (body.events.length === 0) {
-    return undefined;
-  }
-  const id = (body.events.at(-1) as { id?: unknown } | null)?.id;
-  if (typeof id !== 'number') {
-    throw new Error('serve-sim event log entry has no numeric ID.');
-  }
-  return id;
-}

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/utils/AndroidEmulatorUtils.ts

@@ -6,13 +6,14 @@ import assert from 'assert';
 import FastGlob from 'fast-glob';
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
-import { Socket } from 'node:net';
+import { Socket, createServer } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 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. */
@@ -34,6 +35,8 @@ export type AndroidEmulatorLaunchGate = {
 
 export namespace AndroidEmulatorUtils {
   const RETRY_INTERVAL_MS = 1_000;
+  const FIRST_CONSOLE_PORT = 5554;
+  const LAST_CONSOLE_PORT = 5584;
 
   export const defaultSystemImagePackage = `system-images;android-30;default;${
     process.arch === 'arm64' ? 'arm64-v8a' : 'x86_64'
@@ -327,19 +330,31 @@ export namespace AndroidEmulatorUtils {
     env,
     logcatDirectory,
     launchGate,
+    logCapture,
+    consolePort,
+    extraArgs = [],
+    extraEnv = {},
   }: {
     deviceName: AndroidVirtualDeviceName;
     env: NodeJS.ProcessEnv;
     logcatDirectory: string;
     launchGate?: AndroidEmulatorLaunchGate;
+    logCapture: AndroidEmulatorLogCapture;
+    /**
+     * The console port, from `findFreeConsolePortAsync`. It sets the serial (`emulator-<port>`)
+     * before the start. Without it, the emulator picks a free port itself.
+     */
+    consolePort?: number;
+    /** Emulator arguments before $ANDROID_EMULATOR_EXTRA_ARGS, which can still override them. */
+    extraArgs?: string[];
+    /** Environment variables for the emulator process only. */
+    extraEnv?: Record<string, string>;
   }): 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 +362,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,66 +384,54 @@ export namespace AndroidEmulatorUtils {
       '-writable-system',
       '-noaudio',
       '-no-snapshot-save',
-      '-logcat',
-      '*:v',
-      '-logcat-output',
-      logcatOutputPath,
+      ...(logcatOutput ? ['-logcat', '*:v', '-logcat-output', logcatOutput.path] : []),
       '-avd',
       deviceName,
       '-accel',
       'on',
+      ...(consolePort !== undefined ? ['-port', String(consolePort)] : []),
+      ...extraArgs,
       ...(typeof env.ANDROID_EMULATOR_EXTRA_ARGS === 'string'
         ? env.ANDROID_EMULATOR_EXTRA_ARGS.split(' ')
         : []),
     ];
     const emulatorEnv = {
       ...env,
+      ...extraEnv,
       // 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 +481,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({
@@ -623,6 +631,30 @@ export namespace AndroidEmulatorUtils {
     return { outputPath };
   }
 
+  /**
+   * A free console port: an even port from 5554 to 5584, the range that adb scans, whose next
+   * port, for adb, is free too.
+   */
+  export async function findFreeConsolePortAsync(): Promise<number> {
+    for (let port = FIRST_CONSOLE_PORT; port <= LAST_CONSOLE_PORT; port += 2) {
+      if ((await isPortFreeAsync(port)) && (await isPortFreeAsync(port + 1))) {
+        return port;
+      }
+    }
+    throw new Error(
+      `No emulator console port from ${FIRST_CONSOLE_PORT} to ${LAST_CONSOLE_PORT} is free.`
+    );
+  }
+
+  async function isPortFreeAsync(port: number): Promise<boolean> {
+    return await new Promise(resolve => {
+      const server = createServer();
+      server.unref();
+      server.once('error', () => resolve(false));
+      server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+    });
+  }
+
   export async function stopAsync({
     serialId,
     env,

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,8 +1,8 @@
 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 { type Server, Socket, createServer } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -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',
@@ -317,6 +408,43 @@ describe('AndroidEmulatorUtils', () => {
       ).toEqual([]);
     });
 
+    it('adds the console port and extra arguments before $ANDROID_EMULATOR_EXTRA_ARGS', async () => {
+      const outputDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'logcat-staging-'));
+      temporaryDirectories.push(outputDir);
+      const deviceName = 'eas-simulator' as AndroidVirtualDeviceName;
+      mockSuccessfulStart(deviceName);
+      const env = { ANDROID_EMULATOR_EXTRA_ARGS: '-gpu swiftshader_indirect' };
+
+      await AndroidEmulatorUtils.startAsync({
+        logCapture: buildCapture,
+        deviceName,
+        env,
+        logcatDirectory: outputDir,
+        consolePort: 5556,
+        extraArgs: ['-gpu', 'lavapipe'],
+        extraEnv: { LD_PRELOAD: '/tmp/libexpo_emulator_capture.so' },
+      });
+
+      const [, args, options] = mockedSpawn.mock.calls.find(([command]) =>
+        command.endsWith('/emulator/emulator')
+      )!;
+      expect(args.slice(-8)).toEqual([
+        '-accel',
+        'on',
+        '-port',
+        '5556',
+        '-gpu',
+        'lavapipe',
+        '-gpu',
+        'swiftshader_indirect',
+      ]);
+      expect(options?.env).toEqual({
+        ...env,
+        LD_PRELOAD: '/tmp/libexpo_emulator_capture.so',
+        ANDROID_EMULATOR_WAIT_TIME_BEFORE_KILL: '1',
+      });
+    });
+
     it('starts the emulator behind the launch gate and releases it once admitted', async () => {
       const outputDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'logcat-staging-'));
       temporaryDirectories.push(outputDir);
@@ -331,7 +459,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 +487,7 @@ describe('AndroidEmulatorUtils', () => {
           '-logcat',
           '*:v',
           '-logcat-output',
-          result.logcatOutputPath,
+          await logFile(outputDir, 'logcat'),
           '-avd',
           deviceName,
           '-accel',
@@ -395,6 +524,7 @@ describe('AndroidEmulatorUtils', () => {
 
       await expect(
         AndroidEmulatorUtils.startAsync({
+          logCapture: buildCapture,
           deviceName,
           env: {},
           logcatDirectory: outputDir,
@@ -419,6 +549,7 @@ describe('AndroidEmulatorUtils', () => {
       try {
         await expect(
           AndroidEmulatorUtils.startAsync({
+            logCapture: buildCapture,
             deviceName,
             env: process.env,
             logcatDirectory: outputDir,
@@ -435,6 +566,60 @@ describe('AndroidEmulatorUtils', () => {
     });
   });
 
+  describe(AndroidEmulatorUtils.findFreeConsolePortAsync, () => {
+    /** Listens on the port, or returns null when another process already uses it. */
+    async function occupyAsync(port: number): Promise<Server | null> {
+      const server = createServer();
+      return await new Promise(resolve => {
+        server.once('error', () => resolve(null));
+        server.listen(port, '127.0.0.1', () => resolve(server));
+      });
+    }
+
+    async function closeAsync(servers: (Server | null)[]): Promise<void> {
+      await Promise.all(
+        servers.map(server => (server ? new Promise(resolve => server.close(resolve)) : null))
+      );
+    }
+
+    it('returns an even console port that adb scans', async () => {
+      const port = await AndroidEmulatorUtils.findFreeConsolePortAsync();
+
+      expect(port % 2).toBe(0);
+      expect(port).toBeGreaterThanOrEqual(5554);
+      expect(port).toBeLessThanOrEqual(5584);
+    });
+
+    it('skips a console port whose adb port is in use', async () => {
+      const port = await AndroidEmulatorUtils.findFreeConsolePortAsync();
+      const adbServer = await occupyAsync(port + 1);
+      try {
+        expect(adbServer).not.toBeNull();
+        const next = await AndroidEmulatorUtils.findFreeConsolePortAsync();
+
+        expect(next).not.toBe(port);
+        expect(next % 2).toBe(0);
+      } finally {
+        await closeAsync([adbServer]);
+      }
+    });
+
+    it('throws when no console port is free', async () => {
+      const servers: (Server | null)[] = [];
+      try {
+        for (let port = 5555; port <= 5585; port += 2) {
+          servers.push(await occupyAsync(port));
+        }
+
+        await expect(AndroidEmulatorUtils.findFreeConsolePortAsync()).rejects.toThrow(
+          'No emulator console port from 5554 to 5584 is free.'
+        );
+      } finally {
+        await closeAsync(servers);
+      }
+    });
+  });
+
   describe(AndroidEmulatorUtils.waitForReadyAsync, () => {
     it('checks boot completion and verifies network with netcat to 1.1.1.1:443', async () => {
       mockedSpawn.mockImplementation((async (_command: string, args: string[]) => {

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__/processes.test.ts

@@ -1,44 +1,28 @@
-import { ChildProcess } from 'node:child_process';
+import { isProcessGroupRunning, isProcessRunning } from '../processes';
 
-import { isChildProcessAlive, isProcessGroupRunning } from '../processes';
-
-function child(partial: {
-  exitCode: number | null;
-  signalCode: NodeJS.Signals | null;
-  killed: boolean;
-}): ChildProcess {
-  return partial as ChildProcess;
-}
-
-describe(isChildProcessAlive, () => {
-  it('is alive while the process is running', () => {
-    expect(isChildProcessAlive(child({ exitCode: null, signalCode: null, killed: false }))).toBe(
-      true
-    );
+describe(isProcessRunning, () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
   });
 
-  it('is dead after a normal exit', () => {
-    expect(isChildProcessAlive(child({ exitCode: 0, signalCode: null, killed: false }))).toBe(
-      false
-    );
-    expect(isChildProcessAlive(child({ exitCode: 1, signalCode: null, killed: false }))).toBe(
-      false
-    );
+  it('signals the process, not its group', () => {
+    const kill = jest.spyOn(process, 'kill').mockReturnValue(true);
+    expect(isProcessRunning(4321)).toBe(true);
+    expect(kill).toHaveBeenCalledWith(4321, 0);
   });
 
-  it('is dead after an external signal termination (the regression case)', () => {
-    expect(
-      isChildProcessAlive(child({ exitCode: null, signalCode: 'SIGTERM', killed: false }))
-    ).toBe(false);
-    expect(
-      isChildProcessAlive(child({ exitCode: null, signalCode: 'SIGKILL', killed: false }))
-    ).toBe(false);
+  it('is not running once the process is gone', () => {
+    jest.spyOn(process, 'kill').mockImplementation(() => {
+      throw Object.assign(new Error('No such process'), { code: 'ESRCH' });
+    });
+    expect(isProcessRunning(4321)).toBe(false);
   });
 
-  it('is dead once we have killed it', () => {
-    expect(isChildProcessAlive(child({ exitCode: null, signalCode: null, killed: true }))).toBe(
-      false
-    );
+  it('is running when the process exists but cannot be signaled', () => {
+    jest.spyOn(process, 'kill').mockImplementation(() => {
+      throw Object.assign(new Error('Operation not permitted'), { code: 'EPERM' });
+    });
+    expect(isProcessRunning(4321)).toBe(true);
   });
 });
 

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

@@ -11,7 +11,12 @@ import {
   startSshSessionAsync,
   superviseSshSessionAsync,
 } from '../turtleSshSession';
-import { SshConnectionConfig, UptermHost, startUptermHostAsync } from '../upterm';
+import {
+  SshConnectionConfig,
+  UptermHost,
+  UptermSessionStatus,
+  startUptermHostAsync,
+} from '../upterm';
 
 jest.mock('../retry', () => ({
   sleepAsync: jest.fn().mockResolvedValue(undefined),
@@ -28,13 +33,14 @@ function sshJob(idleTimeoutSeconds: number): { ssh: SshSettings } {
 }
 
 function superviseHandle(
-  overrides: Partial<SshSessionHandle> &
-    Pick<SshSessionHandle, 'getConnectedClientCountAsync' | 'ensureConnectedAsync'>
+  readStatusAsync: () => Promise<UptermSessionStatus>,
+  reportReconnectingAsync: (reconnecting: boolean) => Promise<void> = async () => {}
 ): SshSessionHandle {
-  return {
-    stopAsync: async () => {},
-    ...overrides,
-  };
+  return { readStatusAsync, reportReconnectingAsync, stopAsync: async () => {} };
+}
+
+function ready(connectedClientCount: number): UptermSessionStatus {
+  return { state: 'ready', connectedClientCount };
 }
 
 describe(isSshEnabled, () => {
@@ -77,7 +83,6 @@ describe(getSshRelayServerUrl, () => {
 
 describe(startSshSessionAsync, () => {
   const config1: SshConnectionConfig = { type: 'upterm-v1', secret: 'secret-1' };
-  const config2: SshConnectionConfig = { ...config1, secret: 'secret-2' };
   const target = { type: 'JOB_RUN', id: 'jr-1' } as const;
 
   let createOrUpdateResult: { data?: unknown; error?: { message: string } };
@@ -85,18 +90,17 @@ describe(startSshSessionAsync, () => {
   let ctx: BuildContext;
 
   function makeHost(overrides: Partial<UptermHost> = {}): UptermHost {
-    const host: UptermHost = {
+    return {
       connectionConfig: config1,
-      getConnectedClientCountAsync: jest.fn().mockResolvedValue(3),
-      isAlive: jest.fn().mockReturnValue(true),
-      redialAsync: jest.fn(async () => {
-        host.connectionConfig = config2;
-        return config2;
-      }),
+      startedReconnecting: false,
+      readStatusAsync: jest.fn().mockResolvedValue(ready(3)),
       stopAsync: jest.fn().mockResolvedValue(undefined),
       ...overrides,
     };
-    return host;
+  }
+
+  function reportedReconnecting(): boolean[] {
+    return mutation.mock.calls.map(([, vars]) => vars.connectionConfig.reconnecting);
   }
 
   beforeEach(() => {
@@ -133,8 +137,7 @@ describe(startSshSessionAsync, () => {
       sessionSettings: { idleTimeoutSeconds: 900 },
     });
     expect(idleTimeoutSeconds).toBe(900);
-    await handle.getConnectedClientCountAsync();
-    expect(host.getConnectedClientCountAsync).toHaveBeenCalled();
+    expect(await handle.readStatusAsync()).toEqual(ready(3));
     await handle.stopAsync();
     expect(host.stopAsync).toHaveBeenCalled();
   });
@@ -203,117 +206,61 @@ describe(startSshSessionAsync, () => {
     expect(host.stopAsync).toHaveBeenCalled();
   });
 
-  it('ensureConnected is a no-op while the host is alive', async () => {
-    const host = makeHost({ isAlive: jest.fn().mockReturnValue(true) });
-    mockedStartUptermHost.mockResolvedValue(host);
+  it('tells www about reconnecting only when it changes, with the same session id', async () => {
+    mockedStartUptermHost.mockResolvedValue(makeHost());
 
     const { handle } = await startSshSessionAsync(ctx, {
       target,
       relayServerUrl: 'wss://r',
       idleTimeoutSeconds: 300,
     });
-    await handle.ensureConnectedAsync();
+    for (const reconnecting of [false, true, true, false, false]) {
+      await handle.reportReconnectingAsync(reconnecting);
+    }
 
-    expect(host.redialAsync).not.toHaveBeenCalled();
-    expect(mutation).toHaveBeenCalledTimes(1);
-  });
-
-  it('marks reconnecting, redials, then reports the fresh config', async () => {
-    const host = makeHost({ isAlive: jest.fn().mockReturnValue(false) });
-    mockedStartUptermHost.mockResolvedValue(host);
-
-    const { handle } = await startSshSessionAsync(ctx, {
-      target,
-      relayServerUrl: 'wss://r',
-      idleTimeoutSeconds: 300,
-    });
-    await handle.ensureConnectedAsync();
-
-    expect(host.redialAsync).toHaveBeenCalledTimes(1);
-    expect(mutation).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({
-        connectionConfig: expect.objectContaining({ reconnecting: true }),
-      })
-    );
+    expect(reportedReconnecting()).toEqual([false, true, false]);
     expect(mutation).toHaveBeenLastCalledWith(expect.anything(), {
       target: { type: 'JOB_RUN', id: 'jr-1' },
-      connectionConfig: { type: 'UPTERM_V1', secret: 'secret-2', reconnecting: false },
+      connectionConfig: { type: 'UPTERM_V1', secret: 'secret-1', reconnecting: false },
       sessionSettings: { idleTimeoutSeconds: 300 },
     });
   });
 
-  it('continues redial when the reconnecting status update fails', async () => {
-    const host = makeHost({ isAlive: jest.fn().mockReturnValue(false) });
-    mockedStartUptermHost.mockResolvedValue(host);
+  it('sends the start status in the create call and tracks changes from it', async () => {
+    mockedStartUptermHost.mockResolvedValue(makeHost({ startedReconnecting: true }));
+
+    const { handle } = await startSshSessionAsync(ctx, {
+      target,
+      relayServerUrl: 'wss://r',
+      idleTimeoutSeconds: 300,
+    });
+    for (const reconnecting of [true, false, false]) {
+      await handle.reportReconnectingAsync(reconnecting);
+    }
+
+    expect(reportedReconnecting()).toEqual([true, false]);
+  });
+
+  it('retries a failed report on the next call and drops it when the state flips back first', async () => {
+    mockedStartUptermHost.mockResolvedValue(makeHost());
     mutation
-      .mockReturnValueOnce({ toPromise: async () => createOrUpdateResult }) // initial create
-      .mockReturnValueOnce({
-        toPromise: async () => {
-          throw new Error('www unreachable');
-        },
-      }) // reconnecting=true best-effort
-      .mockReturnValue({ toPromise: async () => createOrUpdateResult }); // post-redial
-
-    const { handle } = await startSshSessionAsync(ctx, {
-      target,
-      relayServerUrl: 'wss://r',
-      idleTimeoutSeconds: 300,
-    });
-    await handle.ensureConnectedAsync();
-
-    expect(host.redialAsync).toHaveBeenCalledTimes(1);
-  });
-
-  it('retries only the report (no second redial) when reporting the fresh config fails', async () => {
-    let alive = false;
-    const host = makeHost({
-      isAlive: jest.fn(() => alive),
-    });
-    host.redialAsync = jest.fn(async () => {
-      alive = true;
-      host.connectionConfig = config2;
-      return config2;
-    });
-    mockedStartUptermHost.mockResolvedValue(host);
-    mutation = jest
-      .fn()
       .mockReturnValueOnce({ toPromise: async () => createOrUpdateResult })
+      .mockReturnValueOnce({ toPromise: async () => ({ error: { message: 'www down' } }) })
       .mockReturnValueOnce({ toPromise: async () => createOrUpdateResult })
-      .mockReturnValueOnce({ toPromise: async () => ({ error: { message: 'flaky' } }) })
+      .mockReturnValueOnce({ toPromise: async () => ({ error: { message: 'www down' } }) })
       .mockReturnValue({ toPromise: async () => createOrUpdateResult });
-    ctx = { logger: createMockLogger(), graphqlClient: { mutation } } as unknown as BuildContext;
 
     const { handle } = await startSshSessionAsync(ctx, {
       target,
       relayServerUrl: 'wss://r',
       idleTimeoutSeconds: 300,
     });
-    await handle.ensureConnectedAsync();
+    for (const reconnecting of [true, true, false, true, false]) {
+      await handle.reportReconnectingAsync(reconnecting);
+    }
 
-    expect(host.redialAsync).toHaveBeenCalledTimes(1);
-    expect(mutation).toHaveBeenLastCalledWith(expect.anything(), {
-      target: { type: 'JOB_RUN', id: 'jr-1' },
-      connectionConfig: { type: 'UPTERM_V1', secret: 'secret-2', reconnecting: false },
-      sessionSettings: { idleTimeoutSeconds: 300 },
-    });
-  });
-
-  it('throws once the redial budget is exhausted', async () => {
-    const host = makeHost({
-      isAlive: jest.fn().mockReturnValue(false),
-      redialAsync: jest.fn().mockRejectedValue(new Error('relay down')),
-    });
-    mockedStartUptermHost.mockResolvedValue(host);
-
-    const { handle } = await startSshSessionAsync(ctx, {
-      target,
-      relayServerUrl: 'wss://r',
-      idleTimeoutSeconds: 300,
-    });
-
-    await expect(handle.ensureConnectedAsync()).rejects.toThrow(/after 10 attempts/);
-    expect(host.redialAsync).toHaveBeenCalledTimes(10);
+    // create, true (fails), true, false (fails), nothing while www still has true, false.
+    expect(reportedReconnecting()).toEqual([false, true, true, false, false]);
   });
 });
 
@@ -329,33 +276,23 @@ describe(superviseSshSessionAsync, () => {
   it('keeps the session open while the job is running, even with a 0 idle timeout', async () => {
     let polls = 0;
     await superviseSshSessionAsync({
-      handle: superviseHandle({
-        ensureConnectedAsync: async () => {
-          if (polls >= 5) {
-            throw new SystemError('stop the loop');
-          }
-        },
-        getConnectedClientCountAsync: async () => {
-          polls += 1;
-          return 0;
-        },
+      handle: superviseHandle(async () => {
+        polls += 1;
+        return polls > 5 ? { state: 'gone', reason: 'ending' } : ready(0);
       }),
       idleTimeoutSeconds: 0,
       hasJobFinished: () => false,
       logger,
     });
-    expect(polls).toBe(5);
+    expect(polls).toBe(6);
   });
 
   it('closes as soon as the job finishes when the idle timeout is 0', async () => {
     let polls = 0;
     await superviseSshSessionAsync({
-      handle: superviseHandle({
-        ensureConnectedAsync: async () => {},
-        getConnectedClientCountAsync: async () => {
-          polls += 1;
-          return 0;
-        },
+      handle: superviseHandle(async () => {
+        polls += 1;
+        return ready(0);
       }),
       idleTimeoutSeconds: 0,
       hasJobFinished: () => true,
@@ -371,12 +308,9 @@ describe(superviseSshSessionAsync, () => {
     const clientCounts = [1, 1, 0];
     let polls = 0;
     await superviseSshSessionAsync({
-      handle: superviseHandle({
-        ensureConnectedAsync: async () => {},
-        getConnectedClientCountAsync: async () => {
-          polls += 1;
-          return clientCounts.shift() ?? 0;
-        },
+      handle: superviseHandle(async () => {
+        polls += 1;
+        return ready(clientCounts.shift() ?? 0);
       }),
       idleTimeoutSeconds: 0,
       hasJobFinished: () => true,
@@ -395,15 +329,12 @@ describe(superviseSshSessionAsync, () => {
         jest.setSystemTime(Date.now() + 60_000);
       });
       await superviseSshSessionAsync({
-        handle: superviseHandle({
-          ensureConnectedAsync: async () => {},
-          getConnectedClientCountAsync: async () => {
-            polls += 1;
-            if (polls >= 5) {
-              jobHasFinished = true;
-            }
-            return 0;
-          },
+        handle: superviseHandle(async () => {
+          polls += 1;
+          if (polls >= 5) {
+            jobHasFinished = true;
+          }
+          return ready(0);
         }),
         idleTimeoutSeconds: 300,
         hasJobFinished: () => jobHasFinished,
@@ -420,10 +351,7 @@ describe(superviseSshSessionAsync, () => {
   it('logs the connected client count whenever it changes', async () => {
     const clientCounts = [1, 2, 1, 0];
     await superviseSshSessionAsync({
-      handle: superviseHandle({
-        ensureConnectedAsync: async () => {},
-        getConnectedClientCountAsync: async () => clientCounts.shift() ?? 0,
-      }),
+      handle: superviseHandle(async () => ready(clientCounts.shift() ?? 0)),
       idleTimeoutSeconds: 0,
       hasJobFinished: () => true,
       logger,
@@ -434,57 +362,78 @@ describe(superviseSshSessionAsync, () => {
     expect(logger.info).toHaveBeenCalledWith('SSH clients connected: 0');
   });
 
-  it('closes the session when the relay connection cannot be restored', async () => {
-    let clientCountCalls = 0;
+  it('keeps the session open while upterm reconnects, then closes it once it is gone for good', async () => {
+    const statuses: UptermSessionStatus[] = [
+      { state: 'reconnecting', connectedClientCount: 0 },
+      { state: 'reconnecting', connectedClientCount: 0 },
+      { state: 'gone', reason: 'disconnected (reconnect_unsupported)' },
+      ready(1),
+    ];
+    const reportReconnectingAsync = jest.fn(async () => {});
+    let polls = 0;
     await superviseSshSessionAsync({
-      handle: superviseHandle({
-        ensureConnectedAsync: async () => {
-          throw new SystemError('relay down');
-        },
-        getConnectedClientCountAsync: async () => {
-          clientCountCalls += 1;
-          return 1;
-        },
-      }),
+      handle: superviseHandle(async () => {
+        polls += 1;
+        return statuses.shift() ?? ready(1);
+      }, reportReconnectingAsync),
       idleTimeoutSeconds: 300,
       hasJobFinished: () => false,
       logger,
     });
-    expect(clientCountCalls).toBe(0);
+    expect(polls).toBe(3);
+    expect(reportReconnectingAsync.mock.calls).toEqual([[true], [true]]);
+    expect(logger.warn).toHaveBeenCalledWith(
+      'Could not restore the SSH relay connection (disconnected (reconnect_unsupported)). Closing the session.'
+    );
+  });
+
+  it('reports the reconnecting state of every poll and logs only its changes', async () => {
+    const reconnecting: UptermSessionStatus = { state: 'reconnecting', connectedClientCount: 0 };
+    const statuses: UptermSessionStatus[] = [
+      ready(0),
+      reconnecting,
+      reconnecting,
+      ready(0),
+      { state: 'gone', reason: 'ending' },
+    ];
+    const reportReconnectingAsync = jest.fn(async () => {});
+    await superviseSshSessionAsync({
+      handle: superviseHandle(async () => statuses.shift() ?? ready(0), reportReconnectingAsync),
+      idleTimeoutSeconds: 300,
+      hasJobFinished: () => false,
+      logger,
+    });
+    expect(reportReconnectingAsync.mock.calls).toEqual([[false], [true], [true], [false]]);
+    expect(
+      jest
+        .mocked(logger.warn)
+        .mock.calls.filter(
+          ([message]) => message === 'The SSH relay connection dropped. Reconnecting...'
+        )
+    ).toHaveLength(1);
+    expect(logger.info).toHaveBeenCalledWith('The SSH relay connection was restored.');
   });
 
   it('does not close while a client stays connected, even past the idle timeout', async () => {
     let polls = 0;
     await superviseSshSessionAsync({
-      handle: superviseHandle({
-        ensureConnectedAsync: async () => {
-          if (polls > 3) {
-            throw new SystemError('stop the loop');
-          }
-        },
-        getConnectedClientCountAsync: async () => {
-          polls += 1;
-          return 1;
-        },
+      handle: superviseHandle(async () => {
+        polls += 1;
+        return polls > 4 ? { state: 'gone', reason: 'ending' } : ready(1);
       }),
       idleTimeoutSeconds: 0,
       hasJobFinished: () => true,
       logger,
     });
-    expect(polls).toBeGreaterThan(3);
+    expect(polls).toBe(5);
   });
 
   it('closes when the client count cannot be read', async () => {
     let polls = 0;
     await superviseSshSessionAsync({
-      handle: superviseHandle({
-        ensureConnectedAsync: async () => {},
-        getConnectedClientCountAsync: async () => {
-          polls += 1;
-          throw new SystemError(
-            'Could not read the SSH client count from the upterm admin socket.'
-          );
-        },
+      handle: superviseHandle(async () => {
+        polls += 1;
+        throw new SystemError('Could not read the SSH client count from the upterm admin socket.');
       }),
       idleTimeoutSeconds: 300,
       hasJobFinished: () => false,

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

@@ -1,14 +1,15 @@
-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';
 import { sleepAsync } from '../retry';
 import {
   redactConnectionSecrets,
-  redactSpawnErrorForLog,
   resolveUptermGcsObjectName,
   startUptermHostAsync,
 } from '../upterm';
@@ -19,16 +20,38 @@ jest.mock('../retry', () => ({ sleepAsync: jest.fn() }));
 jest.mock('node:fs/promises', () => ({
   __esModule: true,
   default: {
-    access: jest.fn(),
-    mkdir: jest.fn(),
     chmod: jest.fn(),
     mkdtemp: jest.fn(),
     writeFile: jest.fn(),
     rm: jest.fn(),
-    readdir: jest.fn(),
   },
 }));
 
+const SESSION_ID = 'pJbIEKJ3dhB4qIUMoNku';
+
+const DETACH_JSON = JSON.stringify(
+  {
+    name: 'eas-1a2b3c4',
+    launchId: '71c3af039c2557ea',
+    status: 'ready',
+    sessionId: SESSION_ID,
+    adminSocket: '/tmp/eas-ssh-1/upterm/sessions/eas-1a2b3c4/admin.sock',
+    attachSocket: '/tmp/eas-ssh-1/upterm/sessions/eas-1a2b3c4/attach.sock',
+    pid: 73366,
+    command: 'bash -lc sleep 21600',
+    forceCommand: '/tmp/eas-ssh-1/join.sh',
+    sshCommand: `ssh ${SESSION_ID}@relay.expo.dev -p 2222`,
+    joinCommand: `upterm join ssh://${SESSION_ID}@relay.expo.dev:2222`,
+    sshConfig: `Host eas-1a2b3c4\n  HostName relay.expo.dev\n  User ${SESSION_ID}\n  Port 2222`,
+    host: 'ssh://relay.expo.dev:2222',
+    clientCount: 0,
+    guestCount: 0,
+    reconnect: 'supported',
+  },
+  null,
+  2
+);
+
 describe(resolveUptermGcsObjectName, () => {
   it('maps worker platforms to GCS object names', () => {
     expect(resolveUptermGcsObjectName('darwin', 'arm64')).toBe('upterm-darwin-arm64');
@@ -42,36 +65,11 @@ describe(resolveUptermGcsObjectName, () => {
 });
 
 describe(redactConnectionSecrets, () => {
-  it('strips the userinfo secret from a connection string', () => {
-    expect(
-      redactConnectionSecrets('Connect: upterm proxy wss://[email protected] now')
-    ).toBe('Connect: upterm proxy wss://<redacted>@relay.expo.dev now');
-  });
-
-  it('strips the bare token that trails the ssh ProxyCommand line', () => {
-    const line =
-      "ssh -o ProxyCommand='upterm proxy wss://[email protected]' [email protected]";
-    const redacted = redactConnectionSecrets(line);
-    expect(redacted).not.toContain('TOKENabc123');
-    expect(redacted).toBe(
-      "ssh -o ProxyCommand='upterm proxy wss://<redacted>@uptermd.upterm.dev' <redacted>@uptermd.upterm.dev"
-    );
-  });
-
-  it('strips the bare token for ws:// relay URLs too', () => {
-    const line =
-      "ssh -o ProxyCommand='upterm proxy ws://[email protected]' [email protected]";
-    const redacted = redactConnectionSecrets(line);
-    expect(redacted).not.toContain('TOKENabc123');
-    expect(redacted).toBe(
-      "ssh -o ProxyCommand='upterm proxy ws://<redacted>@relay.local' <redacted>@relay.local"
-    );
-  });
-
-  it('leaves output without userinfo untouched', () => {
-    expect(redactConnectionSecrets('dialing wss://relay.expo.dev')).toBe(
-      'dialing wss://relay.expo.dev'
-    );
+  it('strips the session id from every field of the --detach JSON output', () => {
+    const redacted = redactConnectionSecrets(DETACH_JSON);
+    expect(redacted).not.toContain(SESSION_ID);
+    expect(redacted).toContain('"sshCommand": "ssh <redacted>@relay.expo.dev -p 2222"');
+    expect(redacted).toContain('User <redacted>');
   });
 
   it('strips control characters (incl. ESC) while keeping newlines', () => {
@@ -82,177 +80,196 @@ describe(redactConnectionSecrets, () => {
   });
 });
 
-describe(redactSpawnErrorForLog, () => {
-  it('redacts secrets in message, stdout, and stderr', () => {
-    expect(
-      redactSpawnErrorForLog({
-        message: 'failed wss://[email protected]',
-        stdout: 'upterm proxy wss://[email protected]',
-        stderr: 'ssh dial error: wss://[email protected]',
-        code: 1,
-      })
-    ).toEqual({
-      message: 'failed wss://<redacted>@relay.expo.dev',
-      stdout: 'upterm proxy wss://<redacted>@relay.expo.dev',
-      stderr: 'ssh dial error: wss://<redacted>@relay.expo.dev',
-      code: 1,
-    });
-  });
-
-  it('passes through non-objects', () => {
-    expect(redactSpawnErrorForLog('boom')).toBe('boom');
-    expect(redactSpawnErrorForLog(null)).toBeNull();
-  });
-
-  it('leaves non-string message/stdout/stderr fields alone', () => {
-    expect(
-      redactSpawnErrorForLog({
-        message: 42,
-        stdout: Buffer.from('x'),
-        code: 1,
-      })
-    ).toEqual({
-      message: 42,
-      stdout: Buffer.from('x'),
-      code: 1,
-    });
-  });
-});
-
 describe(startUptermHostAsync, () => {
   const mockedSpawn = jest.mocked(spawn);
-  const mockedSleep = jest.mocked(sleepAsync);
   const mockedFs = jest.mocked(fs);
   const mockedDownloadFile = jest.mocked(downloadFile);
 
-  let hostProcess: {
-    child: {
-      stdout: { on: (event: string, cb: (chunk: Buffer) => void) => void };
-      stderr: { on: jest.Mock };
-      pid: number;
-      kill: jest.Mock;
-      unref: jest.Mock;
-      exitCode: number | null;
-      signalCode: NodeJS.Signals | null;
-      killed: boolean;
-    };
-    catch: (cb: (err: unknown) => void) => Promise<void>;
-  };
-  let sessionStdout: string;
-  let uptermOnPath = true;
+  type SpawnCall = { cmd: string; args: string[]; options: any };
+  let calls: SpawnCall[];
+  let hostResult: () => Promise<{ stdout: string; stderr: string }>;
+  let currentResult: () => Promise<{ stdout: string; stderr: string }>;
+  let stopResult: () => Promise<{ stdout: string; stderr: string }>;
+  let daemonRunning: boolean;
+  let uptermOnPath: boolean;
 
-  function makeHostProcess(): typeof hostProcess {
-    return {
-      child: {
-        stdout: {
-          on: jest.fn((_event: string, cb: (chunk: Buffer) => void) => {
-            cb(Buffer.from('host output'));
-          }),
-        },
-        stderr: { on: jest.fn() },
-        pid: 4242,
-        kill: jest.fn(),
-        unref: jest.fn(),
-        exitCode: null,
-        signalCode: null,
-        killed: false,
-      },
-      catch: cb => {
-        cb(new Error('exited'));
-        return Promise.resolve();
-      },
-    };
+  function ok(stdout: string): () => Promise<{ stdout: string; stderr: string }> {
+    return async () => ({ stdout, stderr: '' });
   }
 
-  function makeCtx(env: Record<string, string> = {}): BuildContext {
+  function current(fields: Record<string, unknown>): string {
+    return JSON.stringify({ sessionId: SESSION_ID, host: 'ssh://relay.expo.dev:2222', ...fields });
+  }
+
+  function makeCtx(
+    env: Record<string, string> = {},
+    buildDirectory = '/workingdir/build'
+  ): BuildContext {
     return {
       logger: createMockLogger(),
       env,
+      buildDirectory,
     } as unknown as BuildContext;
   }
 
+  function callsOf(...prefix: string[]): SpawnCall[] {
+    return calls.filter(c => prefix.every((arg, i) => c.args[i] === arg));
+  }
+
   beforeEach(() => {
     jest.clearAllMocks();
-    jest.spyOn(process, 'kill').mockReturnValue(true);
-    hostProcess = makeHostProcess();
-    uptermOnPath = true;
-    sessionStdout = JSON.stringify({
-      sessionId: 'TOKENx',
-      host: 'ssh://relay.expo.dev:22',
-      clientCount: 0,
+    calls = [];
+    daemonRunning = true;
+    uptermOnPath = false;
+    hostResult = ok(DETACH_JSON);
+    currentResult = ok(current({ status: 'ready', guestCount: 0 }));
+    stopResult = ok('session eas-1a2b3c4 stopped\n');
+    jest.spyOn(process, 'kill').mockImplementation(() => {
+      if (daemonRunning) {
+        return true;
+      }
+      throw Object.assign(new Error('No such process'), { code: 'ESRCH' });
     });
-    mockedSleep.mockResolvedValue(undefined);
-    mockedFs.mkdir.mockResolvedValue(undefined as never);
+    jest.mocked(sleepAsync).mockResolvedValue(undefined);
     mockedFs.chmod.mockResolvedValue(undefined as never);
     mockedFs.mkdtemp.mockImplementation((async (prefix: string) =>
       String(prefix).includes('eas-upterm') ? '/tmp/eas-upterm-1' : '/tmp/eas-ssh-1') as never);
     mockedFs.writeFile.mockResolvedValue(undefined as never);
     mockedFs.rm.mockResolvedValue(undefined as never);
-    mockedFs.readdir.mockResolvedValue(['default.sock'] as never);
     mockedDownloadFile.mockResolvedValue(undefined as never);
-    mockedSpawn.mockImplementation(((cmd: string, args: string[]) => {
-      if (cmd === 'upterm' && Array.isArray(args) && args[0] === 'version') {
-        if (!uptermOnPath) {
-          return Promise.reject(new Error('not found')) as never;
-        }
-        return Promise.resolve({ stdout: 'upterm version 0.24.0\n', stderr: '' }) as never;
+    mockedSpawn.mockImplementation(((cmd: string, args: string[], options: unknown) => {
+      calls.push({ cmd, args, options });
+      if (cmd === 'upterm' && args[0] === 'version') {
+        return uptermOnPath
+          ? Promise.resolve({ stdout: 'Upterm version 0.0.0', stderr: '' })
+          : Promise.reject(new Error('spawn upterm ENOENT'));
       }
-      if (Array.isArray(args) && args[0] === 'host') {
-        return hostProcess as never;
+      if (args[0] === 'host') {
+        return hostResult();
       }
-      if (Array.isArray(args) && args[0] === 'session') {
-        return Promise.resolve({ stdout: sessionStdout, stderr: '' }) as never;
+      if (args[0] === 'session' && args[1] === 'current') {
+        return currentResult();
       }
-      return Promise.resolve({ stdout: '', stderr: '' }) as never;
+      if (args[0] === 'session' && args[1] === 'stop') {
+        return stopResult();
+      }
+      return Promise.resolve({ stdout: '', stderr: '' });
     }) as never);
   });
 
-  it('uses upterm on PATH, dials, and returns a handle with the parsed config', async () => {
-    const env = { PATH: '/job/bin', CUSTOM: '1' };
-    const host = await startUptermHostAsync(makeCtx(env), {
-      relayServerUrl: 'wss://relay.expo.dev',
-    });
-
-    expect(host.connectionConfig).toEqual({ type: 'upterm-v1', secret: 'TOKENx' });
-    expect(host.isAlive()).toBe(true);
-    expect(mockedDownloadFile).not.toHaveBeenCalled();
-    expect(mockedSpawn).toHaveBeenCalledWith('upterm', ['version'], {
-      stdio: 'pipe',
-      env,
-    });
-    expect(mockedSpawn).toHaveBeenCalledWith(
-      'upterm',
-      expect.arrayContaining(['host']),
-      expect.objectContaining({ env: expect.objectContaining({ CUSTOM: '1', PATH: '/job/bin' }) })
-    );
+  afterEach(() => {
+    jest.restoreAllMocks();
   });
 
-  it('downloads from GCS into a fresh temp dir when upterm is not on PATH', async () => {
-    uptermOnPath = false;
+  it('starts a detached session under a short unique name and takes the session id from its JSON', async () => {
+    const host = await startUptermHostAsync(makeCtx({ CUSTOM: '1' }), {
+      relayServerUrl: 'wss://relay.expo.dev',
+    });
+    await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://relay.expo.dev' });
 
-    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://relay.expo.dev' });
+    expect(host.connectionConfig).toEqual({ type: 'upterm-v1', secret: SESSION_ID });
+    const [first, second] = callsOf('host');
+    const nameOf = (call: SpawnCall): string => call.args[call.args.indexOf('--name') + 1];
+    expect(nameOf(first).length).toBeLessThanOrEqual(11);
+    expect(nameOf(first)).not.toBe(nameOf(second));
+    expect(first.args).toEqual(
+      expect.arrayContaining(['--accept', '--detach', '--output', 'json'])
+    );
+    expect(first.args.slice(first.args.indexOf('--'))).toEqual([
+      '--',
+      'bash',
+      '-lc',
+      'sleep 21600',
+    ]);
+    expect(first.options).toMatchObject({
+      env: { CUSTOM: '1', XDG_RUNTIME_DIR: '/tmp/eas-ssh-1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  });
 
-    expect(host.connectionConfig.secret).toBe('TOKENx');
+  it('reports whether the session was already reconnecting when it started', async () => {
+    hostResult = ok(DETACH_JSON.replace('"status": "ready"', '"status": "reconnecting"'));
+    const reconnecting = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+    hostResult = ok(DETACH_JSON);
+    const ready = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+
+    expect(reconnecting.startedReconnecting).toBe(true);
+    expect(ready.startedReconnecting).toBe(false);
+  });
+
+  it('downloads upterm from GCS even when one is on PATH', async () => {
+    uptermOnPath = true;
+
+    await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://relay.expo.dev' });
+
+    expect(calls.some(c => c.cmd === 'upterm')).toBe(false);
     expect(mockedDownloadFile).toHaveBeenCalledWith(
-      expect.stringMatching(/storage\.googleapis\.com\/turtle-v2\/upterm\/upterm-/),
+      'https://storage.googleapis.com/turtle-v2/upterm/' + resolveUptermGcsObjectName(),
       expect.stringContaining('/tmp/eas-upterm-1'),
       expect.objectContaining({ retry: 3 })
     );
-    expect(mockedSpawn).toHaveBeenCalledWith(
-      expect.stringContaining('/tmp/eas-upterm-1'),
-      expect.arrayContaining(['host']),
-      expect.anything()
-    );
+    expect(callsOf('host')[0].cmd).toContain('/tmp/eas-upterm-1');
+  });
+
+  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("runs the client's command in the build directory and returns its exit status", 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, SSH_ORIGINAL_COMMAND: 'pwd; exit 3' },
+        input: '',
+        encoding: 'utf8',
+      });
+
+      expect(result.stdout.trim()).toBe(buildDirectory);
+      expect(result.status).toBe(3);
+    } finally {
+      realFs.rmSync(tmpDir, { recursive: true, force: true });
+    }
   });
 
   it('downloads through the cache proxy when one is configured', async () => {
-    uptermOnPath = false;
-
     await startUptermHostAsync(
       makeCtx({ EAS_BUILD_COCOAPODS_CACHE_URL: 'http://10.0.0.1:8081/repository/proxy' }),
-      {
-        relayServerUrl: 'wss://relay.expo.dev',
-      }
+      { relayServerUrl: 'wss://relay.expo.dev' }
     );
 
     expect(mockedDownloadFile).toHaveBeenCalledTimes(1);
@@ -266,53 +283,33 @@ describe(startUptermHostAsync, () => {
   });
 
   it('falls back to the direct URL when the proxied download fails', async () => {
-    uptermOnPath = false;
     mockedDownloadFile.mockRejectedValueOnce(new Error('502 Bad Gateway') as never);
 
-    const host = await startUptermHostAsync(
+    await startUptermHostAsync(
       makeCtx({ EAS_BUILD_COCOAPODS_CACHE_URL: 'http://10.0.0.1:8081/repository/proxy' }),
       { relayServerUrl: 'wss://relay.expo.dev' }
     );
 
-    expect(host.connectionConfig.secret).toBe('TOKENx');
     expect(mockedDownloadFile).toHaveBeenCalledTimes(2);
     expect(mockedDownloadFile).toHaveBeenLastCalledWith(
       expect.stringMatching(/^https:\/\/storage\.googleapis\.com\/turtle-v2\/upterm\/upterm-/),
       expect.stringContaining('/tmp/eas-upterm-1'),
       expect.objectContaining({ retry: 3 })
     );
-    expect(mockedSpawn).toHaveBeenCalledWith(
-      expect.stringContaining('/tmp/eas-upterm-1'),
-      expect.arrayContaining(['host']),
-      expect.anything()
-    );
   });
 
   it('names the direct URL when both the proxied and the direct download fail', async () => {
-    uptermOnPath = false;
     mockedDownloadFile.mockRejectedValue(new Error('403 Forbidden') as never);
 
     await expect(
       startUptermHostAsync(
         makeCtx({ EAS_BUILD_COCOAPODS_CACHE_URL: 'http://10.0.0.1:8081/repository/proxy' }),
-        {
-          relayServerUrl: 'wss://r',
-        }
+        { relayServerUrl: 'wss://r' }
       )
     ).rejects.toThrow(/could not be downloaded from https:\/\/storage\.googleapis\.com/);
   });
 
-  it('throws when upterm is missing from PATH and the GCS download fails', async () => {
-    uptermOnPath = false;
-    mockedDownloadFile.mockRejectedValue(new Error('403 Forbidden') as never);
-
-    await expect(startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' })).rejects.toThrow(
-      /could not be downloaded/
-    );
-  });
-
   it('still throws when download fails with a non-Error and temp cleanup also fails', async () => {
-    uptermOnPath = false;
     mockedDownloadFile.mockRejectedValue('network down' as never);
     mockedFs.rm.mockRejectedValue(new Error('EPERM') as never);
 
@@ -321,162 +318,180 @@ describe(startUptermHostAsync, () => {
     );
   });
 
-  it('keeps polling until upterm reports a session id', async () => {
-    sessionStdout = JSON.stringify({ host: 'ssh://relay.expo.dev:22', clientCount: 0 });
-    mockedSleep.mockImplementationOnce(async () => {
-      sessionStdout = JSON.stringify({
-        sessionId: 'TOKENy',
-        host: 'ssh://relay.expo.dev:22',
-        clientCount: 0,
-      });
-    });
-
-    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-
-    expect(host.connectionConfig).toEqual({ type: 'upterm-v1', secret: 'TOKENy' });
-  });
-
-  it('tears down and rethrows when the host never registers with the relay', async () => {
-    jest.useFakeTimers();
-    jest.setSystemTime(0);
-    try {
-      mockedFs.readdir.mockResolvedValue([] as never);
-      mockedSleep.mockImplementation(async () => {
-        jest.setSystemTime(Date.now() + 61_000);
-      });
-
-      await expect(startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' })).rejects.toThrow(
-        /did not register/
+  it('stops the session and removes the state and download dirs when upterm cannot start it', async () => {
+    hostResult = () =>
+      Promise.reject(
+        Object.assign(new Error('upterm exited with non-zero code: 1'), {
+          status: 1,
+          signal: null,
+          stdout: '',
+          stderr:
+            'upterm: session eas-3418b73 could not start: ssh://127.0.0.1:32222: Permission denied (publickey); the 1 identity offered was refused.',
+        })
       );
-      expect(process.kill).toHaveBeenCalledWith(-4242, 'SIGTERM');
-      expect(mockedFs.rm).toHaveBeenCalledWith('/tmp/eas-ssh-1', expect.anything());
-    } finally {
-      jest.useRealTimers();
-    }
-  });
 
-  it('stopAsync kills the process and removes the state dir', async () => {
-    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-    await host.stopAsync();
+    const error = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' }).catch(
+      e => e
+    );
 
-    expect(process.kill).toHaveBeenCalledWith(-4242, 'SIGTERM');
+    expect(error.message).toMatch(/could not register with the relay/);
+    expect(error.message).toContain('Permission denied (publickey)');
+    expect(callsOf('session', 'stop')).toHaveLength(1);
     expect(mockedFs.rm).toHaveBeenCalledWith('/tmp/eas-ssh-1', expect.anything());
+    expect(mockedFs.rm).toHaveBeenCalledWith('/tmp/eas-upterm-1', expect.anything());
   });
 
-  it('falls back to child.kill when process.kill on the process group fails', async () => {
-    jest.spyOn(process, 'kill').mockImplementation(() => {
-      throw new Error('ESRCH');
-    });
+  it('reports a start that ran into its timeout as not registered in time', async () => {
+    hostResult = () =>
+      Promise.reject(
+        Object.assign(new Error('upterm exited with signal: SIGTERM'), {
+          status: null,
+          signal: 'SIGTERM',
+          stdout: '',
+          stderr: '',
+        })
+      );
 
-    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+    await expect(startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' })).rejects.toThrow(
+      /did not register with the relay within 60s/
+    );
+    expect(callsOf('host')[0].options).toMatchObject({ timeout: 60_000 });
+  });
+
+  it('stops a session whose start JSON says guests cannot reach it', async () => {
+    hostResult = ok(DETACH_JSON.replace('"status": "ready"', '"status": "disconnected"'));
+
+    const error = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' }).catch(
+      e => e
+    );
+
+    expect(error.message).toMatch(/did not report a usable session/);
+    expect(error.message).not.toContain(SESSION_ID);
+    expect(callsOf('session', 'stop')).toHaveLength(1);
+  });
+
+  it('stopAsync stops the session by name with the start environment and removes the state and download dirs', async () => {
+    const host = await startUptermHostAsync(makeCtx({ CUSTOM: '1' }), {
+      relayServerUrl: 'wss://r',
+    });
     await host.stopAsync();
 
-    expect(hostProcess.child.kill).toHaveBeenCalled();
+    const name = callsOf('host')[0].args[callsOf('host')[0].args.indexOf('--name') + 1];
+    const [stop] = callsOf('session', 'stop');
+    expect(stop.args).toEqual(['session', 'stop', name]);
+    expect(stop.options.env).toMatchObject({ CUSTOM: '1', XDG_RUNTIME_DIR: '/tmp/eas-ssh-1' });
+    expect(mockedFs.rm).toHaveBeenCalledWith('/tmp/eas-ssh-1', expect.anything());
+    expect(mockedFs.rm).toHaveBeenCalledWith('/tmp/eas-upterm-1', expect.anything());
   });
 
-  it('skips process.kill when the host process has no pid', async () => {
+  it('stopAsync throws the stop output but still removes the state and download dirs when the stop fails', async () => {
     const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-    hostProcess.child.pid = undefined as unknown as number;
-    await host.stopAsync();
+    stopResult = () =>
+      Promise.reject(
+        Object.assign(new Error('exited with non-zero code: 1'), {
+          stdout: '',
+          stderr: "upterm: session eas-1a2b3c4 isn't answering on its admin socket (pid 73366)",
+        })
+      );
 
-    expect(process.kill).not.toHaveBeenCalled();
-    expect(hostProcess.child.kill).not.toHaveBeenCalled();
+    await expect(host.stopAsync()).rejects.toThrow(/isn't answering on its admin socket/);
+    expect(mockedFs.rm).toHaveBeenCalledWith('/tmp/eas-ssh-1', expect.anything());
+    expect(mockedFs.rm).toHaveBeenCalledWith('/tmp/eas-upterm-1', expect.anything());
   });
 
-  it('redialAsync re-establishes the connection', async () => {
-    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-    const config = await host.redialAsync();
+  describe('readStatusAsync', () => {
+    it('reads the status and client count from the admin socket the start JSON named', async () => {
+      const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+      currentResult = ok(current({ status: 'reconnecting', guestCount: 2 }));
 
-    expect(config).toEqual({ type: 'upterm-v1', secret: 'TOKENx' });
-    expect(host.connectionConfig).toEqual(config);
-  });
-
-  it('redialAsync waits for the old process to exit before clearing its socket dir', async () => {
-    const order: string[] = [];
-    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-
-    // Keep the give-up timer pending so only the process exit can unblock the redial.
-    mockedSleep.mockImplementation(() => new Promise<void>(() => {}));
-    let resolveExit: (() => void) | undefined;
-    hostProcess.catch = () =>
-      new Promise<void>(resolve => {
-        resolveExit = () => {
-          order.push('exited');
-          resolve();
-        };
+      expect(await host.readStatusAsync()).toEqual({
+        state: 'reconnecting',
+        connectedClientCount: 2,
       });
-    mockedFs.rm.mockImplementation((() => {
-      order.push('rm');
-      return Promise.resolve(undefined);
-    }) as never);
-    jest.spyOn(process, 'kill').mockImplementation(() => {
-      order.push('kill');
-      // A real SIGTERM is asynchronous, so the exit lands after the kill returns.
-      setImmediate(() => resolveExit?.());
-      return true;
+      expect(callsOf('session', 'current')[0].args).toEqual([
+        'session',
+        'current',
+        '--admin-socket',
+        '/tmp/eas-ssh-1/upterm/sessions/eas-1a2b3c4/admin.sock',
+        '--output',
+        'json',
+      ]);
     });
 
-    await host.redialAsync();
-
-    expect(order).toEqual(['kill', 'exited', 'rm']);
-  });
-
-  it('redialAsync gives up waiting when the old process does not exit', async () => {
-    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-    hostProcess.catch = () => new Promise<void>(() => {});
-
-    await expect(host.redialAsync()).resolves.toEqual({ type: 'upterm-v1', secret: 'TOKENx' });
-    expect(mockedSleep).toHaveBeenCalledWith(5_000);
-  });
-
-  it('continues when the previous socket dir cannot be cleared', async () => {
-    mockedFs.rm.mockImplementation(((dir: string) =>
-      dir === '/tmp/eas-ssh-1/upterm'
-        ? Promise.reject(new Error('busy'))
-        : Promise.resolve(undefined)) as never);
-
-    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-
-    expect(host.connectionConfig.secret).toBe('TOKENx');
-  });
-
-  describe('getConnectedClientCountAsync', () => {
-    it('throws when no admin socket exists yet (after retries)', async () => {
+    it("counts guests only, not the session's own terminals", async () => {
       const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-      mockedFs.readdir.mockResolvedValue([] as never);
-      await expect(host.getConnectedClientCountAsync()).rejects.toThrow(/client count/i);
+      currentResult = ok(current({ status: 'ready', clientCount: 1, guestCount: 0 }));
+
+      expect(await host.readStatusAsync()).toEqual({ state: 'ready', connectedClientCount: 0 });
     });
 
-    it('returns the client count reported by the admin socket', async () => {
+    it.each([
+      [
+        { status: 'disconnected', tunnelReason: 'reconnect_unsupported' },
+        'disconnected (reconnect_unsupported)',
+      ],
+      [{ status: 'ending' }, 'ending'],
+    ])('treats %j as gone for good', async (fields, reason) => {
       const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-      sessionStdout = JSON.stringify({
-        sessionId: 'TOKENx',
-        host: 'relay.expo.dev',
-        clientCount: 4,
+      currentResult = ok(current({ guestCount: 0, ...fields }));
+
+      expect(await host.readStatusAsync()).toEqual({ state: 'gone', reason });
+    });
+
+    it.each([
+      'relay_key_changed',
+      'auth_refused',
+      'proof_refused',
+      'agent_refused',
+      'relay_unsupported',
+    ])('treats a reconnect blocked by %s as gone for good', async tunnelReason => {
+      const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+      currentResult = ok(current({ status: 'reconnecting', tunnelReason, guestCount: 0 }));
+
+      expect(await host.readStatusAsync()).toEqual({
+        state: 'gone',
+        reason: `reconnecting (${tunnelReason})`,
       });
-      expect(await host.getConnectedClientCountAsync()).toBe(4);
     });
 
-    it('throws when the count query fails (after retries)', async () => {
-      const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-      mockedSpawn.mockImplementation((() => Promise.reject(new Error('socket gone'))) as never);
-      await expect(host.getConnectedClientCountAsync()).rejects.toThrow(/client count/i);
-    });
+    it.each(['network', 'relay_error', 'agent_unavailable'])(
+      'keeps a session reconnecting after %s',
+      async tunnelReason => {
+        const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+        currentResult = ok(current({ status: 'reconnecting', tunnelReason, guestCount: 0 }));
 
-    it('throws when the reported count is not a number (after retries)', async () => {
+        expect(await host.readStatusAsync()).toEqual({
+          state: 'reconnecting',
+          connectedClientCount: 0,
+        });
+      }
+    );
+
+    it('reports the session as gone when the read fails and the session process has exited', async () => {
       const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-      sessionStdout = JSON.stringify({
-        sessionId: 'TOKENx',
-        host: 'relay.expo.dev',
-        clientCount: 'nope',
+      currentResult = () => Promise.reject(new Error('exited with non-zero code: 4'));
+      daemonRunning = false;
+
+      expect(await host.readStatusAsync()).toEqual({
+        state: 'gone',
+        reason: 'the upterm session process exited',
       });
-      await expect(host.getConnectedClientCountAsync()).rejects.toThrow(/client count/i);
+      expect(process.kill).toHaveBeenCalledWith(73366, 0);
     });
 
-    it('throws when the socket dir cannot be read (after retries)', async () => {
+    it('retries a failed read while the session process runs, then throws', async () => {
       const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
-      mockedFs.readdir.mockRejectedValue(new Error('no dir') as never);
-      await expect(host.getConnectedClientCountAsync()).rejects.toThrow(/client count/i);
+      currentResult = () => Promise.reject(new Error('deadline exceeded'));
+
+      await expect(host.readStatusAsync()).rejects.toThrow(/client count/i);
+      expect(callsOf('session', 'current')).toHaveLength(4);
+    });
+
+    it('does not guess at a status it does not know', async () => {
+      const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+      currentResult = ok(current({ status: 'starting', guestCount: 0 }));
+
+      await expect(host.readStatusAsync()).rejects.toThrow(/client count/i);
     });
   });
 });

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/processes.ts

@@ -1,9 +1,13 @@
-import { ChildProcess } from 'node:child_process';
-
 import spawn from '@expo/turtle-spawn';
 
-export function isChildProcessAlive(child: ChildProcess): boolean {
-  return child.exitCode === null && child.signalCode === null && !child.killed;
+/** Whether the process `pid` exists. EPERM means it does. */
+export function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error: any) {
+    return error?.code === 'EPERM';
+  }
 }
 
 /** Whether any process in the group led by `pgid` exists. EPERM means it does. */
@@ -18,7 +22,7 @@ export function isProcessGroupRunning(pgid: number): boolean {
 
 /**
  * Kill a detached spawn's process group. Negated pid targets the group so bash/sleep
- * children cannot survive after the parent is gone (e.g. across upterm redial).
+ * children cannot survive after the parent is gone.
  */
 export function killProcessGroup(
   child: { pid?: number; kill(signal?: NodeJS.Signals): void },

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

@@ -4,12 +4,10 @@ import { graphql } from 'gql.tada';
 
 import { formatSecondsForLog } from './formatDuration';
 import { sleepAsync } from './retry';
-import { SshConnectionConfig, startUptermHostAsync } from './upterm';
+import { SshConnectionConfig, UptermSessionStatus, startUptermHostAsync } from './upterm';
 import { BuildContext } from '../context';
 import { Sentry } from '../sentry';
 
-const MAX_SSH_REDIALS = 10;
-const REDIAL_BACKOFF_MS = 6_000;
 const CLIENT_COUNT_POLL_INTERVAL_MS = 5_000;
 const MAX_SSH_IDLE_TIMEOUT_SECONDS = 3600;
 const DEFAULT_SSH_IDLE_TIMEOUT_SECONDS = 0;
@@ -67,8 +65,8 @@ export function getSshRelayServerUrl(job: Pick<Job, 'ssh'>): string {
 }
 
 export type SshSessionHandle = {
-  getConnectedClientCountAsync: () => Promise<number>;
-  ensureConnectedAsync: () => Promise<void>;
+  readStatusAsync: () => Promise<UptermSessionStatus>;
+  reportReconnectingAsync: (reconnecting: boolean) => Promise<void>;
   stopAsync: () => Promise<void>;
 };
 
@@ -125,7 +123,7 @@ export async function startSshSessionAsync(
   try {
     ({ idleTimeoutSeconds } = await createOrUpdateSessionAsync(ctx, {
       target,
-      connectionConfig: { ...host.connectionConfig, reconnecting: false },
+      connectionConfig: { ...host.connectionConfig, reconnecting: host.startedReconnecting },
       idleTimeoutSeconds: requestedIdleTimeoutSeconds,
     }));
   } catch (err) {
@@ -133,44 +131,27 @@ export async function startSshSessionAsync(
     throw err;
   }
 
-  const ensureConnectedAsync = async (): Promise<void> => {
-    if (host.isAlive()) {
+  let reportedReconnecting = host.startedReconnecting;
+  const reportReconnectingAsync = async (reconnecting: boolean): Promise<void> => {
+    if (reconnecting === reportedReconnecting) {
       return;
     }
-    for (let attempt = 1; attempt <= MAX_SSH_REDIALS; attempt++) {
-      try {
-        if (!host.isAlive()) {
-          logger.warn('The SSH relay connection dropped. Reconnecting...');
-          await createOrUpdateSessionAsync(ctx, {
-            target,
-            connectionConfig: { ...host.connectionConfig, reconnecting: true },
-            idleTimeoutSeconds: requestedIdleTimeoutSeconds,
-          }).catch(() => {});
-          await host.redialAsync();
-        }
-        await createOrUpdateSessionAsync(ctx, {
-          target,
-          connectionConfig: { ...host.connectionConfig, reconnecting: false },
-          idleTimeoutSeconds: requestedIdleTimeoutSeconds,
-        });
-        logger.info('The SSH relay connection was restored.');
-        return;
-      } catch (err) {
-        logger.warn({ err }, `SSH reconnect attempt ${attempt} of ${MAX_SSH_REDIALS} failed.`);
-        if (attempt < MAX_SSH_REDIALS) {
-          await sleepAsync(REDIAL_BACKOFF_MS);
-        }
-      }
+    try {
+      await createOrUpdateSessionAsync(ctx, {
+        target,
+        connectionConfig: { ...host.connectionConfig, reconnecting },
+        idleTimeoutSeconds: requestedIdleTimeoutSeconds,
+      });
+      reportedReconnecting = reconnecting;
+    } catch (err) {
+      logger.debug({ err }, 'Failed to report the SSH relay connection state.');
     }
-    throw new SystemError(
-      `The SSH relay connection dropped and could not be restored after ${MAX_SSH_REDIALS} attempts.`
-    );
   };
 
   return {
     handle: {
-      getConnectedClientCountAsync: () => host.getConnectedClientCountAsync(),
-      ensureConnectedAsync,
+      readStatusAsync: () => host.readStatusAsync(),
+      reportReconnectingAsync,
       stopAsync: () => host.stopAsync(),
     },
     idleTimeoutSeconds,
@@ -191,25 +172,12 @@ export async function superviseSshSessionAsync({
   const idleTimeoutMs = idleTimeoutSeconds * 1_000;
   let idleSince: number | null = null;
   let previousClientCount = 0;
+  let previousReconnecting = false;
 
   for (;;) {
+    let status: UptermSessionStatus;
     try {
-      await handle.ensureConnectedAsync();
-    } catch (err) {
-      logger.warn({ err }, 'Could not restore the SSH relay connection. Closing the session.');
-      Sentry.capture(
-        'Could not restore the SSH relay connection',
-        err instanceof Error ? err : undefined,
-        {
-          tags: { trackingCode: 'SSH_RELAY_RECONNECT_FAILED' },
-        }
-      );
-      return;
-    }
-
-    let connectedClientCount: number;
-    try {
-      connectedClientCount = await handle.getConnectedClientCountAsync();
+      status = await handle.readStatusAsync();
     } catch (err) {
       logger.warn({ err }, 'Could not read the SSH client count. Closing the session.');
       Sentry.capture(
@@ -221,6 +189,28 @@ export async function superviseSshSessionAsync({
       );
       return;
     }
+    if (status.state === 'gone') {
+      logger.warn(
+        `Could not restore the SSH relay connection (${status.reason}). Closing the session.`
+      );
+      Sentry.capture(`Could not restore the SSH relay connection (${status.reason})`, {
+        tags: { trackingCode: 'SSH_RELAY_RECONNECT_FAILED' },
+      });
+      return;
+    }
+
+    const reconnecting = status.state === 'reconnecting';
+    if (reconnecting !== previousReconnecting) {
+      if (reconnecting) {
+        logger.warn('The SSH relay connection dropped. Reconnecting...');
+      } else {
+        logger.info('The SSH relay connection was restored.');
+      }
+      previousReconnecting = reconnecting;
+    }
+    await handle.reportReconnectingAsync(reconnecting);
+
+    const { connectedClientCount } = status;
     if (connectedClientCount !== previousClientCount) {
       logger.info(`SSH clients connected: ${connectedClientCount}`);
       previousClientCount = connectedClientCount;

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

@@ -1,18 +1,27 @@
 import { Env, SystemError } from '@expo/eas-build-job';
 import downloadFile from '@expo/downloader';
 import { bunyan } from '@expo/logger';
-import spawn, { SpawnPromise, SpawnResult } from '@expo/turtle-spawn';
+import spawn, { SpawnResult } from '@expo/turtle-spawn';
+import { randomBytes } from 'node:crypto';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { z } from 'zod';
 
 import { getProxiedDownloadUrl } from './download';
-import { isChildProcessAlive, killProcessGroup } from './processes';
+import { isProcessRunning } from './processes';
 import { sleepAsync } from './retry';
 import { BuildContext } from '../context';
 
 const CONTROL_CHARACTERS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g;
+const BLOCKED_TUNNEL_REASONS = new Set([
+  'agent_refused',
+  'auth_refused',
+  'proof_refused',
+  'relay_key_changed',
+  'relay_unsupported',
+]);
+const SESSION_ID_JSON_FIELD = /"sessionId"\s*:\s*"([^"]+)"/g;
 
 export function resolveUptermGcsObjectName(
   platform: NodeJS.Platform = process.platform,
@@ -32,9 +41,7 @@ export function resolveUptermGcsObjectName(
 const UPTERM_GCS_BASE_URL = 'https://storage.googleapis.com/turtle-v2/upterm';
 const UPTERM_DOWNLOAD_TIMEOUT_MS = 60_000;
 const UPTERM_KEEPALIVE_SLEEP_SECONDS = 6 * 60 * 60;
-const CONNECTION_POLL_INTERVAL_MS = 500;
 const CONNECTION_STARTUP_TIMEOUT_MS = 60_000;
-const PROCESS_EXIT_TIMEOUT_MS = 5_000;
 const CLIENT_COUNT_READ_ATTEMPTS = 4;
 const CLIENT_COUNT_READ_RETRY_MS = 500;
 
@@ -43,61 +50,47 @@ export type SshConnectionConfig = {
   secret: string;
 };
 
+export type UptermSessionStatus =
+  | { state: 'ready' | 'reconnecting'; connectedClientCount: number }
+  | { state: 'gone'; reason: string };
+
 export type UptermHost = {
   connectionConfig: SshConnectionConfig;
-  getConnectedClientCountAsync: () => Promise<number>;
-  isAlive: () => boolean;
-  redialAsync: () => Promise<SshConnectionConfig>;
+  startedReconnecting: boolean;
+  readStatusAsync: () => Promise<UptermSessionStatus>;
   stopAsync: () => Promise<void>;
 };
 
-const UptermSessionJsonZ = z.object({
+const UptermStartedJsonZ = z.object({
   sessionId: z.string().min(1),
-  clientCount: z.number().optional(),
+  adminSocket: z.string().min(1),
+  pid: z.number().int().positive(),
+  status: z.enum(['ready', 'reconnecting']),
+});
+
+const UptermCurrentSessionJsonZ = z.object({
+  guestCount: z.number(),
+  status: z.string(),
+  tunnelReason: z.string().optional(),
 });
-type UptermSessionJson = z.infer<typeof UptermSessionJsonZ>;
 
 /**
- * Strip upterm session secrets out of text before it reaches a log or an error message. upterm
- * prints the session id as the userinfo of the connect line it advertises
- * (`upterm proxy ws(s)://<sessionId>@host`) and repeats it bare as the ssh destination on the
- * same line. Control characters are dropped first so they cannot split a token mid-match. The
- * loop lifts the id out of the proxy URL and removes every occurrence of it; the final replace
- * blanks userinfo in any other URL as a catch-all.
+ * Strip upterm session secrets out of text before it reaches a log or an error message. The
+ * session id is the secret: any id in a `sessionId` field of upterm's JSON output is removed
+ * everywhere. Control characters are dropped first so they cannot split a token mid-match.
  */
 export function redactConnectionSecrets(text: string): string {
   let redacted = text.replace(CONTROL_CHARACTERS, '');
-  for (const [, token] of redacted.matchAll(/upterm proxy wss?:\/\/([^@\s]+)@/g)) {
-    redacted = redacted.split(token).join('<redacted>');
+  for (const [, id] of redacted.matchAll(SESSION_ID_JSON_FIELD)) {
+    redacted = redacted.split(id).join('<redacted>');
   }
-  return redacted.replace(/([a-z][a-z0-9+.-]*:\/\/)[^@\s/]+@/gi, '$1<redacted>@');
+  return redacted;
 }
 
-export function redactSpawnErrorForLog(err: unknown): unknown {
-  if (!err || typeof err !== 'object') {
-    return err;
-  }
-  const spawnErr = err as { message?: unknown; stdout?: unknown; stderr?: unknown };
-  return {
-    ...spawnErr,
-    ...(typeof spawnErr.message === 'string'
-      ? { message: redactConnectionSecrets(spawnErr.message) }
-      : {}),
-    ...(typeof spawnErr.stdout === 'string'
-      ? { stdout: redactConnectionSecrets(spawnErr.stdout) }
-      : {}),
-    ...(typeof spawnErr.stderr === 'string'
-      ? { stderr: redactConnectionSecrets(spawnErr.stderr) }
-      : {}),
-  };
-}
-
-export async function resolveUptermPathAsync(env: Env, logger: bunyan): Promise<string> {
-  try {
-    await spawn('upterm', ['version'], { stdio: 'pipe', env });
-    return 'upterm';
-  } catch {}
-
+export async function resolveUptermAsync(
+  env: Env,
+  logger: bunyan
+): Promise<{ uptermPath: string; downloadDir: string }> {
   const objectName = resolveUptermGcsObjectName();
   const downloadDir = await fs.mkdtemp(path.join(os.tmpdir(), 'eas-upterm-'));
   const uptermPath = path.join(downloadDir, objectName);
@@ -115,7 +108,7 @@ export async function resolveUptermPathAsync(env: Env, logger: bunyan): Promise<
   if (proxiedUrl) {
     try {
       await downloadAsync(proxiedUrl);
-      return uptermPath;
+      return { uptermPath, downloadDir };
     } catch (err) {
       logger.debug(
         { err },
@@ -130,61 +123,60 @@ export async function resolveUptermPathAsync(env: Env, logger: bunyan): Promise<
   } catch (err) {
     await fs.rm(downloadDir, { recursive: true, force: true }).catch(() => {});
     throw new SystemError(
-      `The upterm SSH client was not on PATH and could not be downloaded from ${directUrl}. ${
+      `The upterm SSH client could not be downloaded from ${directUrl}. ${
         err instanceof Error ? err.message : String(err)
       }`
     );
   }
-  return uptermPath;
+  return { uptermPath, downloadDir };
 }
 
-async function findAdminSocketPathAsync(uptermSocketDir: string): Promise<string | null> {
-  // Use this dial's own admin socket, not upterm's default, which can still point at a previous
-  // dial's session after a redial and break client-count reads.
-  const entries = await fs.readdir(uptermSocketDir).catch(() => [] as string[]);
-  const socketName = entries.find(entry => entry.endsWith('.sock'));
-  return socketName ? path.join(uptermSocketDir, socketName) : null;
-}
-
-async function readCurrentSessionJsonAsync(
-  uptermPath: string,
-  adminSocketPath: string
-): Promise<UptermSessionJson | null> {
+function parseJson(text: string): unknown {
   try {
-    const result = await spawn(
-      uptermPath,
-      ['session', 'current', '--admin-socket', adminSocketPath, '--output', 'json'],
-      { stdio: 'pipe' }
-    );
-    const parsed = UptermSessionJsonZ.safeParse(JSON.parse(result.stdout));
-    return parsed.success ? parsed.data : null;
+    return JSON.parse(text);
   } catch {
-    return null;
+    return undefined;
   }
 }
 
-async function waitForConnectionConfigAsync(
+function spawnOutput(err: unknown): string {
+  const { stdout, stderr } = err as Partial<SpawnResult>;
+  return redactConnectionSecrets(`${stderr ?? ''}${stdout ?? ''}`);
+}
+
+async function readCurrentSessionStatusAsync(
   uptermPath: string,
-  uptermSocketDir: string,
-  getHostOutput: () => string
-): Promise<SshConnectionConfig> {
-  const deadline = Date.now() + CONNECTION_STARTUP_TIMEOUT_MS;
-  for (;;) {
-    const adminSocketPath = await findAdminSocketPathAsync(uptermSocketDir);
-    if (adminSocketPath) {
-      const session = await readCurrentSessionJsonAsync(uptermPath, adminSocketPath);
-      if (session) {
-        return { type: 'upterm-v1', secret: session.sessionId };
+  adminSocketPath: string,
+  env: Env
+): Promise<UptermSessionStatus | null> {
+  let stdout: string;
+  try {
+    ({ stdout } = await spawn(
+      uptermPath,
+      ['session', 'current', '--admin-socket', adminSocketPath, '--output', 'json'],
+      { stdio: 'pipe', env }
+    ));
+  } catch {
+    return null;
+  }
+  const parsed = UptermCurrentSessionJsonZ.safeParse(parseJson(stdout));
+  if (!parsed.success) {
+    return null;
+  }
+  const { status, guestCount, tunnelReason } = parsed.data;
+  switch (status) {
+    case 'reconnecting':
+      if (tunnelReason && BLOCKED_TUNNEL_REASONS.has(tunnelReason)) {
+        return { state: 'gone', reason: `${status} (${tunnelReason})` };
       }
-    }
-    if (Date.now() >= deadline) {
-      throw new SystemError(
-        `The upterm client did not register with the relay within ${
-          CONNECTION_STARTUP_TIMEOUT_MS / 1_000
-        }s. Output:\n${redactConnectionSecrets(getHostOutput())}`
-      );
-    }
-    await sleepAsync(CONNECTION_POLL_INTERVAL_MS);
+      return { state: status, connectedClientCount: guestCount };
+    case 'ready':
+      return { state: status, connectedClientCount: guestCount };
+    case 'disconnected':
+    case 'ending':
+      return { state: 'gone', reason: tunnelReason ? `${status} (${tunnelReason})` : status };
+    default:
+      return null;
   }
 }
 
@@ -192,43 +184,95 @@ export async function startUptermHostAsync(
   ctx: BuildContext,
   { relayServerUrl }: { relayServerUrl: string }
 ): Promise<UptermHost> {
-  const uptermPath = await resolveUptermPathAsync(ctx.env, ctx.logger);
+  const { uptermPath, downloadDir } = await resolveUptermAsync(ctx.env, ctx.logger);
 
   const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), 'eas-ssh-'));
   const hostKeyPath = path.join(stateDir, 'id_host');
   const forceCommandPath = path.join(stateDir, 'join.sh');
-  const uptermSocketDir = path.join(stateDir, 'upterm');
+  const sessionName = `eas-${randomBytes(4).toString('hex').slice(0, 7)}`;
+  const env: Env = { ...ctx.env, XDG_RUNTIME_DIR: stateDir };
 
   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}\nif [ -n "$SSH_ORIGINAL_COMMAND" ]; then\n  exec bash -lc "$SSH_ORIGINAL_COMMAND"\nfi\nexec bash -l\n`,
+    { mode: 0o755 }
+  );
 
-  let currentProcess: SpawnPromise<SpawnResult> | null = null;
-
-  const stopCurrentProcessAsync = async (): Promise<void> => {
-    const previousProcess = currentProcess;
-    currentProcess = null;
-    if (!previousProcess) {
-      return;
+  const stopAsync = async (): Promise<void> => {
+    try {
+      await spawn(uptermPath, ['session', 'stop', sessionName], { stdio: 'pipe', env });
+    } catch (err) {
+      throw new SystemError(`Failed to stop the upterm session. Output:\n${spawnOutput(err)}`);
+    } finally {
+      await fs.rm(stateDir, { recursive: true, force: true });
+      await fs.rm(downloadDir, { recursive: true, force: true });
     }
-    killProcessGroup(previousProcess.child);
-    await Promise.race([
-      previousProcess.catch(() => {}),
-      sleepAsync(PROCESS_EXIT_TIMEOUT_MS).then(() => {
-        ctx.logger.debug('The previous upterm host process did not exit in time.');
-      }),
-    ]);
   };
 
-  const getConnectedClientCountAsync = async (): Promise<number> => {
+  let started: z.infer<typeof UptermStartedJsonZ>;
+  try {
+    ctx.logger.debug('Connecting to the SSH relay.');
+    let stdout: string;
+    try {
+      // --force-command is what each connecting SSH client runs: the client's command, or a login
+      // shell. The `sleep` after `--` is the session's own command, which keeps it up while nobody
+      // is connected.
+      ({ stdout } = await spawn(
+        uptermPath,
+        [
+          'host',
+          '--server',
+          relayServerUrl,
+          '--accept',
+          '--skip-host-key-check',
+          '-i',
+          hostKeyPath,
+          '--force-command',
+          forceCommandPath,
+          '--detach',
+          '--name',
+          sessionName,
+          '--output',
+          'json',
+          '--',
+          'bash',
+          '-lc',
+          `sleep ${UPTERM_KEEPALIVE_SLEEP_SECONDS}`,
+        ],
+        { env, stdio: ['ignore', 'pipe', 'pipe'], timeout: CONNECTION_STARTUP_TIMEOUT_MS }
+      ));
+    } catch (err) {
+      const failure = (err as Partial<SpawnResult>).signal
+        ? `did not register with the relay within ${CONNECTION_STARTUP_TIMEOUT_MS / 1_000}s`
+        : 'could not register with the relay';
+      throw new SystemError(`The upterm client ${failure}. Output:\n${spawnOutput(err)}`);
+    }
+    const parsed = UptermStartedJsonZ.safeParse(parseJson(stdout));
+    if (!parsed.success) {
+      throw new SystemError(
+        `The upterm client did not report a usable session. Output:\n${redactConnectionSecrets(
+          stdout
+        )}`
+      );
+    }
+    started = parsed.data;
+  } catch (err) {
+    await stopAsync().catch(() => {});
+    throw err;
+  }
+
+  const readStatusAsync = async (): Promise<UptermSessionStatus> => {
     for (let attempt = 1; attempt <= CLIENT_COUNT_READ_ATTEMPTS; attempt++) {
-      const adminSocketPath = await findAdminSocketPathAsync(uptermSocketDir);
-      const session = adminSocketPath
-        ? await readCurrentSessionJsonAsync(uptermPath, adminSocketPath)
-        : null;
-      if (session && typeof session.clientCount === 'number') {
-        return session.clientCount;
+      const status = await readCurrentSessionStatusAsync(uptermPath, started.adminSocket, env);
+      if (status) {
+        return status;
+      }
+      if (!isProcessRunning(started.pid)) {
+        return { state: 'gone', reason: 'the upterm session process exited' };
       }
       if (attempt < CLIENT_COUNT_READ_ATTEMPTS) {
         await sleepAsync(CLIENT_COUNT_READ_RETRY_MS);
@@ -239,79 +283,10 @@ export async function startUptermHostAsync(
     });
   };
 
-  const dialAsync = async (): Promise<SshConnectionConfig> => {
-    await stopCurrentProcessAsync();
-    await fs.rm(uptermSocketDir, { recursive: true, force: true }).catch(err => {
-      ctx.logger.debug({ err }, 'Failed to clear the previous SSH socket directory.');
-    });
-
-    ctx.logger.debug('Connecting to the SSH relay.');
-    // --force-command is what each connecting SSH client runs (a login shell). The `sleep` after
-    // `--` is the host-side process that keeps `upterm host` up while nobody is connected.
-    const uptermProcess = spawn(
-      uptermPath,
-      [
-        'host',
-        '--server',
-        relayServerUrl,
-        '--accept',
-        '--skip-host-key-check',
-        '-i',
-        hostKeyPath,
-        '--force-command',
-        forceCommandPath,
-        '--',
-        'bash',
-        '-lc',
-        `sleep ${UPTERM_KEEPALIVE_SLEEP_SECONDS}`,
-      ],
-      {
-        // upterm puts its admin socket under XDG_RUNTIME_DIR; point it at our state dir so we can
-        // find it for `session current` and clean it up on stop/redial.
-        env: { ...ctx.env, XDG_RUNTIME_DIR: stateDir },
-        stdio: ['ignore', 'pipe', 'pipe'],
-        detached: true,
-      }
-    );
-    uptermProcess.catch(err =>
-      ctx.logger.debug({ err: redactSpawnErrorForLog(err) }, 'The upterm host process exited.')
-    );
-    uptermProcess.child.unref();
-    currentProcess = uptermProcess;
-
-    let output = '';
-    const appendChunk = (chunk: Buffer | string): void => {
-      output += chunk.toString();
-    };
-    uptermProcess.child.stdout?.on('data', appendChunk);
-    uptermProcess.child.stderr?.on('data', appendChunk);
-
-    return await waitForConnectionConfigAsync(uptermPath, uptermSocketDir, () => output);
-  };
-
-  const stopAsync = async (): Promise<void> => {
-    await stopCurrentProcessAsync();
-    await fs.rm(stateDir, { recursive: true, force: true });
-  };
-
-  let connectionConfig: SshConnectionConfig;
-  try {
-    connectionConfig = await dialAsync();
-  } catch (err) {
-    await stopAsync();
-    throw err;
-  }
-
   return {
-    get connectionConfig() {
-      return connectionConfig;
-    },
-    getConnectedClientCountAsync,
-    isAlive: () => currentProcess != null && isChildProcessAlive(currentProcess.child),
-    redialAsync: async () => {
-      connectionConfig = await dialAsync();
-      return connectionConfig;
-    },
+    connectionConfig: { type: 'upterm-v1', secret: started.sessionId },
+    startedReconnecting: started.status === 'reconnecting',
+    readStatusAsync,
     stopAsync,
   };
 }

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

@@ -1,5 +1,29 @@
 # create-eas-build-function
 
+## 27.10.0
+
+No changes in this release.
+
+## 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.

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

@@ -1,6 +1,6 @@
 {
   "name": "create-eas-build-function",
-  "version": "27.6.0",
+  "version": "27.10.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.6.0"
+    "@expo/steps": "27.10.0"
   },
   "devDependencies": {
     "@expo/package-manager": "1.9.10",

packages/downloader/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @expo/downloader
 
+## 27.10.0
+
+No changes in this release.
+
+## 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.