v22.6.0

[build-tools] Increase serve-sim bitrate to 6 Mbps (#4291 )
* [build-tools] Increase serve-sim bitrate to 16 Mbps * [build-tools] Add serve-sim bitrate changelog entry * [build-tools] Set serve-sim bitrate to 6 Mbps
2026-11-15 03:38:08 -10:00 · 2026-08-26 23:49:36 +00:00 · 2026-08-27 01:45:23 +02:00 · 2026-08-26 23:34:56 +00:00 · 2026-08-26 16:25:12 -07:00 · 2026-08-26 08:09:27 -07:00
94 changed files with 8129 additions and 426 deletions
@@ -0,0 +1,90 @@
+name: Update Appium command list
+
+on:
+  schedule:
+    - cron: '0 6 * * 1' # Every Monday at 06:00 UTC
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/update-appium-commands.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    name: Regenerate Appium command list
+    outputs:
+      changed: ${{ steps.diff.outputs.changed }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - name: Setup tools
+        uses: ./.github/actions/setup-mise
+      - name: Install dependencies
+        run: yarn install --immutable
+      - name: Regenerate the Appium command list
+        # The generator installs Appium, XCUITest, and UiAutomator2 on demand,
+        # so it always picks up the latest supported command sets.
+        run: yarn workspace @expo/build-tools generate-appium-commands
+      - name: Check whether the command list changed
+        id: diff
+        run: |
+          if git diff --quiet -- packages/build-tools/src/steps/utils/appiumCommands.generated.ts; then
+            echo 'changed=false' >> "$GITHUB_OUTPUT"
+          else
+            echo 'changed=true' >> "$GITHUB_OUTPUT"
+          fi
+      - name: Upload the generated command list
+        if: steps.diff.outputs.changed == 'true'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: appium-command-list
+          path: packages/build-tools/src/steps/utils/appiumCommands.generated.ts
+          if-no-files-found: error
+          retention-days: 1
+
+  publish:
+    needs: generate
+    if: needs.generate.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    name: Publish Appium command list update
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - name: Download the generated command list
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: appium-command-list
+          path: packages/build-tools/src/steps/utils
+      - name: Open a pull request
+        env:
+          GH_TOKEN: ${{ secrets.EXPO_BOT_PAT }}
+        run: |
+          branch=bot/update-appium-commands
+          title='[build-tools] Update Appium command list'
+          body=$'Automated update of the Appium, XCUITest, and UiAutomator2 command list.\n\nIf this PR adds new commands, typechecking will fail until a curated summary is added for each of them in `packages/build-tools/src/steps/utils/appiumCommandSummary.ts`.'
+
+          gh auth setup-git
+          if git ls-remote --exit-code --heads origin "$branch" >/dev/null; then
+            git fetch origin "refs/heads/$branch:refs/remotes/origin/$branch"
+          fi
+
+          git config user.name 'Expo Bot'
+          git config user.email [email protected]
+          git checkout -B "$branch"
+          git add packages/build-tools/src/steps/utils/appiumCommands.generated.ts
+          git commit -m "$title"
+          git push --force-with-lease origin "$branch"
+
+          if gh pr view "$branch" --json state --jq '.state' 2>/dev/null | grep -q OPEN; then
+            gh pr edit "$branch" --title "$title" --body "$body" --add-reviewer sjchmiela
+          else
+            gh pr create --base main --head "$branch" --title "$title" --body "$body" \
+              --label 'no changelog' --reviewer sjchmiela
+          fi
@@ -8,10 +8,43 @@ This is the log of notable changes to EAS CLI and related packages.

 ### 🎉 New features

+- [eas-cli] Add an opt-in `--max-idle-time-minutes` flag to `eas simulator`; the session stops automatically after that many minutes without activity. ([#4156](https://github.com/expo/eas-cli/pull/4156) by [@szdziedzic](https://github.com/szdziedzic))
+- [eas-cli] Add experimental `--resource-class` flag to `eas simulator`. ([#4268](https://github.com/expo/eas-cli/pull/4268) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Add worker-side SSH session helpers (upterm relay + session create/report/close). ([#4030](https://github.com/expo/eas-cli/pull/4030) by [@gwdp](https://github.com/gwdp))
+- [worker] Wire an SSH session into the build lifecycle behind the workflow ssh flag. ([#4031](https://github.com/expo/eas-cli/pull/4031) by [@gwdp](https://github.com/gwdp))
+
 ### 🐛 Bug fixes

+- [build-tools] Increase the serve-sim video bitrate to 6 Mbps for higher-quality simulator previews. ([#4291](https://github.com/expo/eas-cli/pull/4291) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools] Preapprove custom URL schemes before opening them in iOS Simulator sessions to avoid the first-use confirmation prompt. ([#4274](https://github.com/expo/eas-cli/pull/4274) by [@szdziedzic](https://github.com/szdziedzic))
+
 ### 🧹 Chores

+## [22.4.0](https://github.com/expo/eas-cli/releases/tag/v22.4.0) - 2026-08-24
+
+### 🎉 New features
+
+- [eas-cli] Add `--launch-arg`, `--open-url`, and Expo Go `--sdk-version` options to `eas simulator`. ([#4264](https://github.com/expo/eas-cli/pull/4264) by [@szdziedzic](https://github.com/szdziedzic))
+- [build-tools] Pass launch arguments and a URL to open when launching applications in simulator sessions. ([#4263](https://github.com/expo/eas-cli/pull/4263) by [@szdziedzic](https://github.com/szdziedzic))
+- [eas-cli] Add `eas billing:subscribe <plan>` to start a Stripe checkout for an EAS plan, and `eas billing:manage` to open the Stripe customer portal. ([#4007](https://github.com/expo/eas-cli/pull/4007) by [@jonsamp](https://github.com/jonsamp))
+
+### 🐛 Bug fixes
+
+- [build-tools] Support downloading iOS simulator archives whose app bundle contents are stored at the archive root. ([#4262](https://github.com/expo/eas-cli/pull/4262) by [@szdziedzic](https://github.com/szdziedzic))
+
+## [22.3.0](https://github.com/expo/eas-cli/releases/tag/v22.3.0) - 2026-08-24
+
+### 🎉 New features
+
+- [build-tools] Add `ios_signing_backend` option to the repack step. ([#4239](https://github.com/expo/eas-cli/pull/4239) by [@gabrieldonadel](https://github.com/gabrieldonadel))
+- [build-tools] Support an optional `package_version` input on `eas/start_serve_sim_remote_session`, so a simulator session can pin the `@expo/serve-sim` version instead of always running `latest`. ([#4253](https://github.com/expo/eas-cli/pull/4253) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Add composable custom build functions for downloading, installing, and launching application archives in simulator sessions. ([#4222](https://github.com/expo/eas-cli/pull/4222) by [@szdziedzic](https://github.com/szdziedzic))
+- [eas-cli] Add `--build-id`, `--application-archive-url`, and `--expo-go` to `eas simulator` to install and launch an application before the session is ready. ([#4223](https://github.com/expo/eas-cli/pull/4223) by [@szdziedzic](https://github.com/szdziedzic))
+
+### 🐛 Bug fixes
+
+- [build-tools] Upload tvOS (and other non-iOS) IPAs to the App Store Connect platform declared in the bundle's `DTPlatformName`, instead of always uploading to the iOS train. ([#4234](https://github.com/expo/eas-cli/pull/4234) by [@douglowder](https://github.com/douglowder))
+
 ## [22.2.0](https://github.com/expo/eas-cli/releases/tag/v22.2.0) - 2026-08-20

 ### 🎉 New features
@@ -25,7 +58,6 @@ This is the log of notable changes to EAS CLI and related packages.
 - [eas-cli] Send the expected `Content-MD5` checksum with GCS signed URL uploads so GCS rejects corrupted uploads. ([#4208](https://github.com/expo/eas-cli/pull/4208) by [@wschurman](https://github.com/wschurman))
 - [eas-cli] Resolve the `eas go` SDK version to its repack target, so `--sdk-version 57` no longer fails with "No Expo Go repack target is published for SDK 57". ([#4215](https://github.com/expo/eas-cli/pull/4215) by [@gwdp](https://github.com/gwdp))
 - [eas-cli] Handle missing fingerprint source in fingerprint:compare command. ([#4210](https://github.com/expo/eas-cli/pull/4210) by [@wschurman](https://github.com/wschurman))
- [build-tools] Upload tvOS (and other non-iOS) IPAs to the App Store Connect platform declared in the bundle's `DTPlatformName`, instead of always uploading to the iOS train. ([#4234](https://github.com/expo/eas-cli/pull/4234) by [@douglowder](https://github.com/douglowder))

 ### 🧹 Chores

@@ -1,4 +1,4 @@
 {
-  "STAGING": "22.2.0",
-  "PRODUCTION": "21.5.0"
+  "STAGING": "22.4.0",
+  "PRODUCTION": "22.4.0"
 }
@@ -1,5 +1,5 @@
 {
  "npmClient": "yarn",
-  "version": "22.2.0",
+  "version": "22.6.0",
  "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
@@ -1,6 +1,6 @@
 {
  "name": "@expo/build-tools",
-  "version": "22.2.0",
+  "version": "22.6.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
  "author": "Expo <[email protected]>",
@@ -25,6 +25,7 @@
    "build": "tsc",
    "build:record-sim": "mkdir -p bin && record_sim_bin_path=$(swift build -c release --package-path resources/record-sim --build-path resources/record-sim/.build --show-bin-path) && swift build -c release --package-path resources/record-sim --build-path resources/record-sim/.build && cp \"$record_sim_bin_path/record-sim\" bin/record-sim && chmod +x bin/record-sim",
    "typecheck": "tsc",
+    "generate-appium-commands": "mise exec [email protected] -- 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",
@@ -46,7 +47,7 @@
    "@expo/plist": "^0.3.5",
    "@expo/results": "^1.0.0",
    "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "22.1.0",
+    "@expo/steps": "22.4.0",
    "@expo/template-file": "22.0.0",
    "@expo/turtle-spawn": "22.0.0",
    "@expo/xcpretty": "^4.3.1",
@@ -54,6 +55,7 @@
    "@sentry/node": "7.77.0",
    "@urql/core": "^6.0.1",
    "bplist-parser": "0.3.2",
+    "content-disposition": "1.0.1",
    "fast-glob": "^3.3.2",
    "fast-xml-parser": "^4.4.1",
    "fs-extra": "^11.2.0",
@@ -77,7 +79,8 @@
    "zod": "^4.3.5"
  },
  "devDependencies": {
-    "@expo/repack-app": "~0.6.1",
+    "@expo/repack-app": "~0.9.0",
+    "@types/content-disposition": "0.5.9",
    "@types/fs-extra": "^11.0.4",
    "@types/jest": "^29.5.12",
    "@types/lodash": "^4.17.4",
@@ -0,0 +1,130 @@
+// Regenerates src/steps/utils/appiumCommands.generated.ts from Appium and the
+// XCUITest and UiAutomator2 drivers, so TypeScript can verify that we handle
+// every command that can appear in Appium event timings.
+//
+// Appium and its drivers are NOT dependencies of this package. Like repack, we
+// install them on demand into a temp directory just for this script, so nothing
+// heavy ships with @expo/build-tools.
+//
+// Run with: yarn workspace @expo/build-tools generate-appium-commands
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+// Track the Appium 3 line, matching the appium@^3 the worker installs for
+// simulator sessions (see startAppiumRemoteSession.ts).
+const APPIUM_VERSION = '^3';
+const DRIVERS = [
+  {
+    packageName: 'appium-xcuitest-driver',
+    exportName: 'XCUITestDriver',
+    typeName: 'XCUITestAppiumCommand',
+  },
+  {
+    packageName: 'appium-uiautomator2-driver',
+    exportName: 'AndroidUiautomator2Driver',
+    typeName: 'UiAutomator2AppiumCommand',
+  },
+];
+
+function renderCommandType(typeName, commands) {
+  return `export type ${typeName} =\n${commands.map(command => `  | ${serializeStringLiteral(command)}`).join('\n')};`;
+}
+
+function serializeStringLiteral(value) {
+  const jsonContents = JSON.stringify(value).slice(1, -1).replaceAll('\\"', '"');
+  return `'${jsonContents.replaceAll("'", "\\'")}'`;
+}
+
+function readRouteCommands(methodMap) {
+  return Object.values(methodMap).flatMap(route =>
+    Object.values(route).map(method => method.command)
+  );
+}
+
+async function readDriverCommands({ packageName, exportName }, sandbox) {
+  const packageJsonPath = require.resolve(`${packageName}/package.json`, { paths: [sandbox] });
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const modulePath = path.join(path.dirname(packageJsonPath), packageJson.exports['.'].import);
+  const driverModule = await import(pathToFileURL(modulePath).href);
+  const Driver = driverModule[exportName];
+  return [
+    ...readRouteCommands(Driver.newMethodMap),
+    ...Object.values(Driver.executeMethodMap).map(method => method.command),
+  ];
+}
+
+async function main() {
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'appium-command-generator-'));
+  try {
+    fs.writeFileSync(
+      path.join(sandbox, 'package.json'),
+      `${JSON.stringify({ name: 'appium-command-generator-sandbox', private: true })}\n`
+    );
+    execFileSync(
+      'npm',
+      [
+        'install',
+        '--prefix',
+        sandbox,
+        `appium@${APPIUM_VERSION}`,
+        ...DRIVERS.map(({ packageName }) => packageName),
+      ],
+      { stdio: 'inherit' }
+    );
+
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { ALL_COMMANDS } = require(require.resolve('@appium/base-driver', { paths: [sandbox] }));
+    const baseDriverCommands = [...new Set(ALL_COMMANDS)].sort();
+    const baseDriverCommandSet = new Set(baseDriverCommands);
+    const driverCommands = await Promise.all(
+      DRIVERS.map(async driver => ({
+        typeName: driver.typeName,
+        commands: [...new Set(await readDriverCommands(driver, sandbox))]
+          .filter(command => !baseDriverCommandSet.has(command))
+          .sort(),
+      }))
+    );
+    const commands = [
+      ...new Set([...baseDriverCommands, ...driverCommands.flatMap(({ commands }) => commands)]),
+    ];
+
+    const outputPath = path.join(
+      __dirname,
+      '..',
+      'src',
+      'steps',
+      'utils',
+      'appiumCommands.generated.ts'
+    );
+    const contents = `// AUTO-GENERATED. Do not edit by hand.
+// Run \`yarn workspace @expo/build-tools generate-appium-commands\` to refresh this
+// list from Appium, XCUITest, and UiAutomator2 (installed on demand by the generator).
+${renderCommandType('BaseDriverAppiumCommand', baseDriverCommands)}
+
+${driverCommands
+  .map(({ typeName, commands: commandsForDriver }) =>
+    renderCommandType(typeName, commandsForDriver)
+  )
+  .join('\n\n')}
+
+export type AppiumCommand =
+  | BaseDriverAppiumCommand
+  | XCUITestAppiumCommand
+  | UiAutomator2AppiumCommand;
+`;
+    fs.writeFileSync(outputPath, contents);
+    // eslint-disable-next-line no-console
+    console.log(`Wrote ${commands.length} Appium commands to ${outputPath}`);
+  } finally {
+    fs.rmSync(sandbox, { recursive: true, force: true });
+  }
+}
+
+main().catch(error => {
+  // eslint-disable-next-line no-console
+  console.error(error);
+  process.exitCode = 1;
+});
@@ -98,7 +98,7 @@ async function buildInnerAsync(
    await restoreCcacheAsync({
      logger: ctx.logger,
      workingDirectory,
-      platform: ctx.job.platform,
+      target: { platform: ctx.job.platform },
      env: ctx.env,
      secrets: ctx.job.secrets,
    });
@@ -238,7 +238,7 @@ async function buildInnerAsync(
    await saveCcacheAsync({
      logger: ctx.logger,
      workingDirectory,
-      platform: ctx.job.platform,
+      target: { platform: ctx.job.platform },
      evictUsedBefore,
      env: ctx.env,
      secrets: ctx.job.secrets,
@@ -103,7 +103,7 @@ async function buildInnerAsync(
      await restoreCcacheAsync({
        logger: ctx.logger,
        workingDirectory,
-        platform: ctx.job.platform,
+        target: { platform: ctx.job.platform, simulator: ctx.job.simulator === true },
        env: ctx.env,
        secrets: ctx.job.secrets,
      });
@@ -245,7 +245,7 @@ async function buildInnerAsync(
    await saveCcacheAsync({
      logger: ctx.logger,
      workingDirectory,
-      platform: ctx.job.platform,
+      target: { platform: ctx.job.platform, simulator: ctx.job.simulator === true },
      evictUsedBefore,
      env: ctx.env,
      secrets: ctx.job.secrets,
@@ -18,6 +18,9 @@ export {

 export { PackageManager } from './utils/packageManager';

+export * as TurtleSshSession from './utils/turtleSshSession';
+export { formatSecondsForLog } from './utils/formatDuration';
+
 export { findAndUploadXcodeBuildLogsAsync } from './ios/xcodeBuildLogs';

 export { Hook, runHookIfPresent } from './utils/hooks';
@@ -0,0 +1,46 @@
+import { SystemError } from '@expo/eas-build-job';
+import spawn from '@expo/turtle-spawn';
+
+import { getXcodeVersionAsync } from '../xcode';
+
+jest.mock('@expo/turtle-spawn', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+const mockedSpawn = jest.mocked(spawn);
+
+describe(getXcodeVersionAsync, () => {
+  it('returns the Xcode version', async () => {
+    mockedSpawn.mockResolvedValue({
+      stdout: 'Xcode 26.0\nBuild version 17A324\n',
+    } as any);
+
+    await expect(getXcodeVersionAsync({ env: process.env })).resolves.toBe('26.0');
+    expect(mockedSpawn).toHaveBeenCalledWith('xcodebuild', ['-version'], {
+      stdio: 'pipe',
+      env: process.env,
+    });
+  });
+
+  it('throws when the Xcode version cannot be parsed', async () => {
+    mockedSpawn.mockResolvedValue({ stdout: 'unexpected output' } as any);
+
+    await expect(getXcodeVersionAsync({ env: process.env })).rejects.toThrow(
+      'Failed to determine Xcode version'
+    );
+  });
+
+  it('wraps errors from xcodebuild in a SystemError', async () => {
+    const cause = new Error('xcode-select: error: invalid developer directory');
+    mockedSpawn.mockRejectedValue(cause);
+
+    const promise = getXcodeVersionAsync({ env: process.env });
+
+    await expect(promise).rejects.toBeInstanceOf(SystemError);
+    await expect(promise).rejects.toMatchObject({
+      message: 'Failed to get Xcode version',
+      cause,
+    });
+  });
+});
@@ -0,0 +1,16 @@
+import { SystemError } from '@expo/eas-build-job';
+import spawn from '@expo/turtle-spawn';
+
+export async function getXcodeVersionAsync({ env }: { env: NodeJS.ProcessEnv }): Promise<string> {
+  let stdout: string;
+  try {
+    ({ stdout } = await spawn('xcodebuild', ['-version'], { stdio: 'pipe', env }));
+  } catch (error) {
+    throw new SystemError('Failed to get Xcode version', { cause: error });
+  }
+  const version = /^Xcode\s+(\d+(?:\.\d+)*)$/m.exec(stdout)?.[1];
+  if (!version) {
+    throw new SystemError(`Failed to determine Xcode version from: ${stdout.trim()}`);
+  }
+  return version;
+}
@@ -19,8 +19,10 @@ import { generateGymfileFromTemplateFunction } from './functions/generateGymfile
 import { createGetCredentialsForBuildTriggeredByGithubIntegration } from './functions/getCredentialsForBuildTriggeredByGitHubIntegration';
 import { injectAndroidCredentialsFunction } from './functions/injectAndroidCredentials';
 import { createInstallMaestroBuildFunction } from './functions/installMaestro';
+import { createInstallBuildFunction } from './functions/installBuild';
 import { createInstallNodeModulesBuildFunction } from './functions/installNodeModules';
 import { createInstallPodsBuildFunction } from './functions/installPods';
+import { createLaunchApplicationFunction } from './functions/launchApplication';
 import { createPrebuildBuildFunction } from './functions/prebuild';
 import { createReadAppConfigBuildFunction } from './functions/readAppConfig';
 import { createReadIpaInfoBuildFunction } from './functions/readIpaInfo';
@@ -74,6 +76,8 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
    createPrebuildBuildFunction(),
    createReadIpaInfoBuildFunction(),
    createDownloadBuildFunction(ctx),
+    createInstallBuildFunction(),
+    createLaunchApplicationFunction(),
    createEasExportBuildFunction(),
    createEasDeployBuildFunction(),
    createRepackBuildFunction(),
@@ -4,8 +4,10 @@ import { Client, CombinedError } from '@urql/core';
 import fetch, { Response } from 'node-fetch';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { Readable } from 'node:stream';
+import * as tar from 'tar';

 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { createMockLogger } from '../../../__tests__/utils/logger';
@@ -19,6 +21,9 @@ const APP_TAR_GZ_BUFFER = Buffer.from(
  'base64'
 );

+const FLAT_APP_INFO_PLIST_BASE64 =
+  'YnBsaXN0MDDSAQIDBF8QEkNGQnVuZGxlRXhlY3V0YWJsZV8QE0NGQnVuZGxlUGFja2FnZVR5cGVXVGVzdEFwcFRBUFBMCA0iOEAAAAAAAAABAQAAAAAAAAAFAAAAAAAAAAAAAAAAAAAARQ==';
+
 const APPLICATION_ARCHIVE_URL = `https://expo.dev/artifacts/eas/${randomUUID()}.tar.gz`;

 function createMockGraphqlClient({
@@ -51,6 +56,57 @@ function createMockGraphqlClient({
  } as unknown as Client;
 }

+function createSuccessfulResponse({
+  body,
+  url,
+  headers,
+}: {
+  body: Buffer;
+  url: string;
+  headers?: Record<string, string>;
+}): Response {
+  const normalizedHeaders = Object.fromEntries(
+    Object.entries(headers ?? {}).map(([name, value]) => [name.toLowerCase(), value])
+  );
+
+  return {
+    ok: true,
+    body: Readable.from(body),
+    url,
+    headers: {
+      get: (name: string): string | null => normalizedHeaders[name.toLowerCase()] ?? null,
+    },
+  } as unknown as Response;
+}
+
+async function createFlatAppTarGzBufferAsync(): Promise<Buffer> {
+  const sourceDirectory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'flat-app-source-'));
+  const archivePath = path.join(os.tmpdir(), `${randomUUID()}.tar.gz`);
+
+  try {
+    await Promise.all([
+      fs.promises.writeFile(path.join(sourceDirectory, 'Info.plist'), FLAT_APP_INFO_PLIST_BASE64, {
+        encoding: 'base64',
+      }),
+      fs.promises.writeFile(path.join(sourceDirectory, 'TestApp'), 'i am executable\n'),
+    ]);
+    await tar.create(
+      {
+        cwd: sourceDirectory,
+        file: archivePath,
+        gzip: true,
+      },
+      ['Info.plist', 'TestApp']
+    );
+    return await fs.promises.readFile(archivePath);
+  } finally {
+    await Promise.all([
+      fs.promises.rm(sourceDirectory, { recursive: true, force: true }),
+      fs.promises.rm(archivePath, { force: true }),
+    ]);
+  }
+}
+
 describe('downloadBuild', () => {
  it('downloads from applicationArchiveUrl returned by GraphQL', async () => {
    const buildId = randomUUID();
@@ -58,11 +114,12 @@ describe('downloadBuild', () => {
      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
    });

-    jest.mocked(fetch).mockResolvedValue({
-      ok: true,
-      body: Readable.from(APP_TAR_GZ_BUFFER),
-      url: APPLICATION_ARCHIVE_URL,
-    } as unknown as Response);
+    jest.mocked(fetch).mockResolvedValue(
+      createSuccessfulResponse({
+        body: APP_TAR_GZ_BUFFER,
+        url: APPLICATION_ARCHIVE_URL,
+      })
+    );

    const { artifactPath } = await downloadBuildAsync({
      logger: createLogger({ name: 'test' }),
@@ -82,17 +139,39 @@ describe('downloadBuild', () => {
    );
  });

+  it('downloads an archive containing app bundle contents at its root', async () => {
+    jest.mocked(fetch).mockResolvedValue(
+      createSuccessfulResponse({
+        body: await createFlatAppTarGzBufferAsync(),
+        url: APPLICATION_ARCHIVE_URL,
+      })
+    );
+
+    const { artifactPath } = await downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+      graphqlClient: createMockGraphqlClient({}),
+      robotAccessToken: null,
+      extensions: ['app'],
+    });
+
+    expect(path.extname(artifactPath)).toBe('.app');
+    expect(await fs.promises.readFile(path.join(artifactPath, 'TestApp'), 'utf8')).toBe(
+      'i am executable\n'
+    );
+  });
+
  it('should handle a straight-up file', async () => {
    const applicationArchiveUrl = `https://expo.dev/artifacts/eas/${randomUUID()}.apk`;
    const graphqlClient = createMockGraphqlClient({
      applicationArchiveUrl,
    });

-    jest.mocked(fetch).mockResolvedValue({
-      ok: true,
-      body: Readable.from(Buffer.from('hello')),
-      url: applicationArchiveUrl,
-    } as unknown as Response);
+    jest
+      .mocked(fetch)
+      .mockResolvedValue(
+        createSuccessfulResponse({ body: Buffer.from('hello'), url: applicationArchiveUrl })
+      );

    const { artifactPath } = await downloadBuildAsync({
      logger: createLogger({ name: 'test' }),
@@ -106,6 +185,128 @@ describe('downloadBuild', () => {
    expect(await fs.promises.readFile(artifactPath, 'utf-8')).toBe('hello');
  });

+  it('downloads a direct application archive URL without querying GraphQL or forwarding the EAS token', async () => {
+    const applicationArchiveUrl = `https://artifacts.example.test/${randomUUID()}.apk`;
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+
+    jest
+      .mocked(fetch)
+      .mockResolvedValue(
+        createSuccessfulResponse({ body: Buffer.from('hello'), url: applicationArchiveUrl })
+      );
+
+    const { artifactPath } = await downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      applicationArchiveUrl,
+      graphqlClient,
+      robotAccessToken: 'scoped-eas-token',
+      extensions: ['apk'],
+    });
+
+    expect(graphqlClient.query).not.toHaveBeenCalled();
+    expect(jest.mocked(fetch)).toHaveBeenCalledWith(
+      applicationArchiveUrl,
+      expect.objectContaining({ headers: undefined })
+    );
+    expect(await fs.promises.readFile(artifactPath, 'utf-8')).toBe('hello');
+  });
+
+  it('uses the Content-Disposition filename for an extensionless URL', async () => {
+    const applicationArchiveUrl = 'https://artifacts.example.test/download';
+    jest.mocked(fetch).mockResolvedValue(
+      createSuccessfulResponse({
+        body: Buffer.from('hello'),
+        url: applicationArchiveUrl,
+        headers: { 'content-disposition': 'attachment; filename="app.apk"' },
+      })
+    );
+
+    const { artifactPath } = await downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      applicationArchiveUrl,
+      graphqlClient: createMockGraphqlClient({}),
+      robotAccessToken: null,
+      extensions: ['apk'],
+    });
+
+    expect(path.basename(artifactPath)).toBe('app.apk');
+    expect(await fs.promises.readFile(artifactPath, 'utf-8')).toBe('hello');
+  });
+
+  it('uses the expected extension when the URL has no filename', async () => {
+    const applicationArchiveUrl = 'https://artifacts.example.test/';
+    jest
+      .mocked(fetch)
+      .mockResolvedValue(
+        createSuccessfulResponse({ body: Buffer.from('hello'), url: applicationArchiveUrl })
+      );
+
+    const { artifactPath } = await downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      applicationArchiveUrl,
+      graphqlClient: createMockGraphqlClient({}),
+      robotAccessToken: null,
+      extensions: ['apk'],
+    });
+
+    expect(path.basename(artifactPath)).toBe('application.apk');
+    expect(await fs.promises.readFile(artifactPath, 'utf-8')).toBe('hello');
+  });
+
+  it('rejects missing or ambiguous build sources', async () => {
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+
+    await expect(
+      // @ts-expect-error Verify the runtime guard for callers without TypeScript.
+      downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        graphqlClient,
+        robotAccessToken: null,
+        extensions: ['app'],
+      })
+    ).rejects.toMatchObject({
+      errorCode: 'EAS_DOWNLOAD_BUILD_INVALID_SOURCE',
+      message: 'Pass buildId or applicationArchiveUrl.',
+    });
+
+    await expect(
+      // @ts-expect-error Verify the runtime guard for callers without TypeScript.
+      downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        buildId: randomUUID(),
+        applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+        graphqlClient,
+        robotAccessToken: null,
+        extensions: ['app'],
+      })
+    ).rejects.toMatchObject({
+      errorCode: 'EAS_DOWNLOAD_BUILD_INVALID_SOURCE',
+      message: 'Pass only one of buildId or applicationArchiveUrl.',
+    });
+
+    expect(graphqlClient.query).not.toHaveBeenCalled();
+    expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+  });
+
+  it('rejects a non-HTTP application archive URL', async () => {
+    await expect(
+      downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        applicationArchiveUrl: 'file:///tmp/app.apk',
+        graphqlClient: createMockGraphqlClient({}),
+        robotAccessToken: null,
+        extensions: ['apk'],
+      })
+    ).rejects.toMatchObject({
+      errorCode: 'EAS_DOWNLOAD_BUILD_INVALID_APPLICATION_ARCHIVE_URL',
+      message: 'application_archive_url must be a valid HTTP or HTTPS URL.',
+    });
+  });
+
  it('throws UserError when the build has no application archive url', async () => {
    const graphqlClient = createMockGraphqlClient({ applicationArchiveUrl: null });

@@ -203,11 +404,12 @@ describe('downloadBuild', () => {
      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
    });

-    jest.mocked(fetch).mockResolvedValue({
-      ok: true,
-      body: Readable.from(APP_TAR_GZ_BUFFER),
-      url: APPLICATION_ARCHIVE_URL,
-    } as unknown as Response);
+    jest.mocked(fetch).mockResolvedValue(
+      createSuccessfulResponse({
+        body: APP_TAR_GZ_BUFFER,
+        url: APPLICATION_ARCHIVE_URL,
+      })
+    );

    await expect(
      downloadBuildAsync({
@@ -0,0 +1,158 @@
+import { BuildRuntimePlatform } from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { createInstallBuildFunction, installBuildAsync } from '../installBuild';
+
+jest.mock('@expo/turtle-spawn', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+const mockedSpawn = jest.mocked(spawn);
+const temporaryDirectories: string[] = [];
+
+async function makeTemporaryDirectoryAsync(): Promise<string> {
+  const temporaryDirectory = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), 'install-build-test-')
+  );
+  temporaryDirectories.push(temporaryDirectory);
+  return temporaryDirectory;
+}
+
+describe(installBuildAsync, () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);
+  });
+
+  afterAll(async () => {
+    await Promise.all(
+      temporaryDirectories.map(temporaryDirectory =>
+        fs.promises.rm(temporaryDirectory, { recursive: true, force: true })
+      )
+    );
+  });
+
+  it('installs an iOS Simulator .app', async () => {
+    const temporaryDirectory = await makeTemporaryDirectoryAsync();
+    const artifactPath = path.join(temporaryDirectory, 'Example.app');
+    await fs.promises.mkdir(artifactPath);
+    const logger = createMockLogger();
+    mockedSpawn.mockResolvedValueOnce({ stdout: 'com.example.app\n', stderr: '' } as any);
+
+    const result = await installBuildAsync({
+      artifactPath,
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: {},
+      logger,
+    });
+
+    expect(result).toEqual({ applicationIdentifier: 'com.example.app' });
+    expect(mockedSpawn.mock.calls).toEqual([
+      [
+        'plutil',
+        ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', path.join(artifactPath, 'Info.plist')],
+        { stdio: 'pipe', env: {} },
+      ],
+      ['xcrun', ['simctl', 'install', 'booted', artifactPath], { env: {}, logger }],
+    ]);
+  });
+
+  it('installs an Android Emulator .apk', async () => {
+    const temporaryDirectory = await makeTemporaryDirectoryAsync();
+    const artifactPath = path.join(temporaryDirectory, 'example.apk');
+    await fs.promises.writeFile(artifactPath, 'apk');
+    const logger = createMockLogger();
+    mockedSpawn.mockResolvedValueOnce({
+      stdout:
+        "package: name='com.example.app'\nlaunchable-activity: name='com.example.app.MainActivity'\n",
+      stderr: '',
+    } as any);
+
+    const result = await installBuildAsync({
+      artifactPath,
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: {},
+      logger,
+    });
+
+    expect(result).toEqual({
+      applicationIdentifier: 'com.example.app',
+      activityName: 'com.example.app.MainActivity',
+    });
+    expect(mockedSpawn.mock.calls).toEqual([
+      ['aapt2', ['dump', 'badging', artifactPath], { stdio: 'pipe', env: {} }],
+      ['adb', ['install', '-r', artifactPath], { env: {}, logger }],
+    ]);
+  });
+
+  it.each([
+    [BuildRuntimePlatform.DARWIN, 'example.ipa'],
+    [BuildRuntimePlatform.LINUX, 'example.aab'],
+  ])('rejects an incompatible %s artifact', async (runtimePlatform, filename) => {
+    const temporaryDirectory = await makeTemporaryDirectoryAsync();
+    const artifactPath = path.join(temporaryDirectory, filename);
+    await fs.promises.writeFile(artifactPath, 'artifact');
+
+    await expect(
+      installBuildAsync({
+        artifactPath,
+        runtimePlatform,
+        env: {},
+        logger: createMockLogger(),
+      })
+    ).rejects.toMatchObject({ errorCode: 'EAS_INSTALL_BUILD_INVALID_ARTIFACT' });
+
+    expect(mockedSpawn).not.toHaveBeenCalled();
+  });
+
+  it('installs an Android artifact without a launchable activity', async () => {
+    const temporaryDirectory = await makeTemporaryDirectoryAsync();
+    const artifactPath = path.join(temporaryDirectory, 'example.apk');
+    await fs.promises.writeFile(artifactPath, 'apk');
+    const logger = createMockLogger();
+    mockedSpawn.mockResolvedValue({
+      stdout: "package: name='com.example.app'\n",
+      stderr: '',
+    } as any);
+
+    const result = await installBuildAsync({
+      artifactPath,
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: {},
+      logger,
+    });
+
+    expect(result).toEqual({ applicationIdentifier: 'com.example.app' });
+    expect(mockedSpawn.mock.calls).toEqual([
+      ['aapt2', ['dump', 'badging', artifactPath], { stdio: 'pipe', env: {} }],
+      ['adb', ['install', '-r', artifactPath], { env: {}, logger }],
+    ]);
+  });
+
+  it('exposes the installed application identifier and activity as step outputs', async () => {
+    const temporaryDirectory = await makeTemporaryDirectoryAsync();
+    const artifactPath = path.join(temporaryDirectory, 'example.apk');
+    await fs.promises.writeFile(artifactPath, 'apk');
+    mockedSpawn.mockResolvedValueOnce({
+      stdout:
+        "package: name='com.example.app'\nlaunchable-activity: name='com.example.app.MainActivity'\n",
+      stderr: '',
+    } as any);
+
+    const installBuild = createInstallBuildFunction();
+    const buildStep = installBuild.createBuildStepFromFunctionCall(
+      createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.LINUX }),
+      { callInputs: { artifact_path: artifactPath } }
+    );
+    await buildStep.executeAsync();
+
+    expect(buildStep.outputById.application_identifier.value).toBe('com.example.app');
+    expect(buildStep.outputById.activity_name.value).toBe('com.example.app.MainActivity');
+  });
+});
@@ -1,6 +1,10 @@
+import downloadFile from '@expo/downloader';
 import { SystemError, UserError } from '@expo/eas-build-job';
 import spawn from '@expo/turtle-spawn';
 import { BuildRuntimePlatform } from '@expo/steps';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';

 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { Datadog } from '../../../datadog';
@@ -11,6 +15,11 @@ jest.mock('@expo/turtle-spawn', () => ({
  default: jest.fn(),
 }));

+jest.mock('@expo/downloader', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
 jest.mock('../../../datadog', () => ({
  Datadog: {
    distribution: jest.fn(),
@@ -18,10 +27,24 @@ jest.mock('../../../datadog', () => ({
 }));

 const mockedSpawn = jest.mocked(spawn);
+const mockedDownloadFile = jest.mocked(downloadFile);
+
+async function writeInstalledWdaVersion(homeDirectory: string, version: string): Promise<void> {
+  const wdaDirectory = path.join(
+    homeDirectory,
+    '.maestro-runner',
+    'drivers',
+    'ios',
+    'WebDriverAgent'
+  );
+  await fs.promises.mkdir(wdaDirectory, { recursive: true });
+  await fs.promises.writeFile(path.join(wdaDirectory, 'package.json'), JSON.stringify({ version }));
+}

 describe('createInstallMaestroBuildFunction', () => {
  beforeEach(() => {
    jest.clearAllMocks();
+    mockedDownloadFile.mockResolvedValue(undefined);
    // `maestro --version` reports an installed version; `java -version` succeeds.
    // With no requested version and Maestro present, the step skips installation.
    mockedSpawn.mockImplementation((async (command: string) => ({
@@ -439,4 +462,184 @@ describe('createInstallMaestroBuildFunction', () => {
      process.env.PATH = originalPath;
    }
  });
+
+  it('installs the prebuilt WDA cache for each available iOS runtime', async () => {
+    const homeDirectory = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), 'install-maestro-test-')
+    );
+    mockedSpawn.mockImplementation((async (command: string, args: string[]) => {
+      if (command === 'maestro-runner') {
+        return { stdout: 'maestro-runner 1.2.3\n' };
+      }
+      if (command === 'xcrun') {
+        return {
+          stdout: JSON.stringify({
+            runtimes: [
+              {
+                identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-18-3',
+                isAvailable: true,
+                version: '18.3.1',
+              },
+              {
+                identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-26-0',
+                isAvailable: true,
+                version: '26.0',
+              },
+              {
+                identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-17-5',
+                isAvailable: false,
+                version: '17.5',
+              },
+            ],
+          }),
+        };
+      }
+      if (command === 'xcodebuild') {
+        return { stdout: 'Xcode 26.0\nBuild version 17A324\n' };
+      }
+      if (command === 'tar') {
+        const maestroRunnerHome = args[args.indexOf('-C') + 1];
+        const productsDirectory = path.join(
+          maestroRunnerHome,
+          'cache',
+          'wda-builds',
+          'generic',
+          'DerivedData',
+          'Build',
+          'Products'
+        );
+        await fs.promises.mkdir(productsDirectory, { recursive: true });
+        await fs.promises.writeFile(
+          path.join(productsDirectory, 'WebDriverAgentRunner.xctestrun'),
+          'cached'
+        );
+      }
+      return { stdout: '' };
+    }) as any);
+
+    try {
+      await writeInstalledWdaVersion(homeDirectory, '11.1.3');
+      const installMaestro = createInstallMaestroBuildFunction();
+      const globalCtx = createGlobalContextMock({
+        runtimePlatform: BuildRuntimePlatform.DARWIN,
+      });
+      globalCtx.updateEnv({
+        EAS_BUILD_RUNNER: 'eas-build',
+        EAS_BUILD_COCOAPODS_CACHE_URL: 'https://cache.example.com',
+        HOME: homeDirectory,
+      });
+      const step = installMaestro.createBuildStepFromFunctionCall(globalCtx, {
+        callInputs: { backend: 'maestro-runner' },
+      });
+
+      await step.executeAsync();
+
+      expect(mockedDownloadFile).toHaveBeenCalledWith(
+        'https://cache.example.com/storage.googleapis.com/turtle-v2/maestro-runner-wda-cache/xcode-26.0-wda-11.1.3.tar.gz',
+        expect.stringMatching(/install_maestro_runner_wda_cache.*\/wda-cache\.tar\.gz$/),
+        { retry: 3, timeout: 20_000 }
+      );
+      for (const runtimeVersion of ['18.3', '26.0']) {
+        await expect(
+          fs.promises.readFile(
+            path.join(
+              homeDirectory,
+              '.maestro-runner',
+              'cache',
+              'wda-builds',
+              `sim-ios${runtimeVersion}-iphone`,
+              'DerivedData',
+              'Build',
+              'Products',
+              'WebDriverAgentRunner.xctestrun'
+            ),
+            'utf8'
+          )
+        ).resolves.toBe('cached');
+      }
+      await expect(
+        fs.promises.access(
+          path.join(homeDirectory, '.maestro-runner', 'cache', 'wda-builds', 'sim-ios17.5-iphone')
+        )
+      ).rejects.toThrow();
+    } finally {
+      await fs.promises.rm(homeDirectory, { force: true, recursive: true });
+    }
+  });
+
+  it('does not download the WDA cache when the installed WDA version is unknown', async () => {
+    mockedSpawn.mockImplementation((async (command: string) => ({
+      stdout:
+        command === 'xcodebuild' ? 'Xcode 26.5\nBuild version 17F90\n' : 'maestro-runner 1.2.3\n',
+    })) as any);
+    const installMaestro = createInstallMaestroBuildFunction();
+    const globalCtx = createGlobalContextMock({
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+    });
+    globalCtx.updateEnv({ EAS_BUILD_RUNNER: 'eas-build', HOME: '/home/expo' });
+    const step = installMaestro.createBuildStepFromFunctionCall(globalCtx, {
+      callInputs: { backend: 'maestro-runner' },
+    });
+
+    await step.executeAsync();
+
+    // The installed WDA version is unknown (no package.json under $HOME), so the
+    // cache download is skipped before resolving the Xcode/runtime versions.
+    expect(mockedDownloadFile).not.toHaveBeenCalled();
+    expect(mockedSpawn.mock.calls.map(([command]) => command)).not.toContain('xcrun');
+  });
+
+  it('continues when the prebuilt WDA cache is not available', async () => {
+    mockedSpawn.mockImplementation((async (command: string) => {
+      switch (command) {
+        case 'maestro-runner':
+          return { stdout: 'maestro-runner 1.2.3\n' };
+        case 'xcodebuild':
+          return { stdout: 'Xcode 26.5\nBuild version 17F90\n' };
+        case 'xcrun':
+          return {
+            stdout: JSON.stringify({
+              runtimes: [
+                {
+                  identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-26-5',
+                  isAvailable: true,
+                  version: '26.5',
+                },
+              ],
+            }),
+          };
+        default:
+          return { stdout: '' };
+      }
+    }) as any);
+    mockedDownloadFile.mockRejectedValue(new Error('HTTP 404'));
+    const homeDirectory = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), 'install-maestro-test-')
+    );
+
+    try {
+      await writeInstalledWdaVersion(homeDirectory, '11.1.3');
+      const installMaestro = createInstallMaestroBuildFunction();
+      const globalCtx = createGlobalContextMock({
+        runtimePlatform: BuildRuntimePlatform.DARWIN,
+      });
+      globalCtx.updateEnv({
+        EAS_BUILD_RUNNER: 'eas-build',
+        EAS_BUILD_COCOAPODS_CACHE_URL: 'https://cache.example.com',
+        HOME: homeDirectory,
+      });
+      const step = installMaestro.createBuildStepFromFunctionCall(globalCtx, {
+        callInputs: { backend: 'maestro-runner' },
+      });
+
+      await expect(step.executeAsync()).resolves.toBeUndefined();
+      expect(step.getOutputValueByName('maestro_version')).toBe('1.2.3');
+      expect(mockedDownloadFile.mock.calls.map(([url]) => url)).toEqual([
+        'https://cache.example.com/storage.googleapis.com/turtle-v2/maestro-runner-wda-cache/xcode-26.5-wda-11.1.3.tar.gz',
+        'https://storage.googleapis.com/turtle-v2/maestro-runner-wda-cache/xcode-26.5-wda-11.1.3.tar.gz',
+      ]);
+    } finally {
+      await fs.promises.rm(homeDirectory, { force: true, recursive: true });
+    }
+  });
 });
@@ -0,0 +1,320 @@
+import { BuildRuntimePlatform } from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { createLaunchApplicationFunction, launchApplicationAsync } from '../launchApplication';
+
+jest.mock('@expo/turtle-spawn', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+const mockedSpawn = jest.mocked(spawn);
+
+describe(launchApplicationAsync, () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);
+  });
+
+  it('launches an iOS Simulator application by bundle identifier', async () => {
+    const logger = createMockLogger();
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'com.example.app',
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: {},
+      logger,
+    });
+
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'xcrun',
+      ['simctl', 'launch', 'booted', 'com.example.app'],
+      { env: {}, logger }
+    );
+  });
+
+  it('passes launch arguments and opens a URL on iOS', async () => {
+    const logger = createMockLogger();
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'host.exp.Exponent',
+      launchArgs: ['--uitesting', 'true'],
+      openUrl: 'exp://example.test',
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: {},
+      logger,
+    });
+
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      1,
+      'xcrun',
+      ['simctl', 'launch', 'booted', 'host.exp.Exponent', '--uitesting', 'true'],
+      { env: {}, logger }
+    );
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      2,
+      'xcrun',
+      [
+        'simctl',
+        'spawn',
+        'booted',
+        'defaults',
+        'write',
+        'com.apple.launchservices.schemeapproval',
+        'com.apple.CoreSimulator.CoreSimulatorBridge-->exp',
+        '-string',
+        'host.exp.Exponent',
+      ],
+      { env: {}, logger }
+    );
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      3,
+      'xcrun',
+      ['simctl', 'openurl', 'booted', 'exp://example.test'],
+      { env: {}, logger }
+    );
+  });
+
+  it('opens a web URL on iOS without preapproving its scheme', async () => {
+    const logger = createMockLogger();
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'com.example.app',
+      openUrl: 'https://example.test',
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: {},
+      logger,
+    });
+
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      1,
+      'xcrun',
+      ['simctl', 'launch', 'booted', 'com.example.app'],
+      { env: {}, logger }
+    );
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      2,
+      'xcrun',
+      ['simctl', 'openurl', 'booted', 'https://example.test'],
+      { env: {}, logger }
+    );
+    expect(mockedSpawn).toHaveBeenCalledTimes(2);
+  });
+
+  it('opens a custom URL on iOS when scheme preapproval fails', async () => {
+    const logger = createMockLogger();
+    const approvalError = new Error('Scheme approval is unavailable.');
+    mockedSpawn
+      .mockResolvedValueOnce({ stdout: '', stderr: '' } as any)
+      .mockRejectedValueOnce(approvalError);
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'host.exp.Exponent',
+      openUrl: 'exp://example.test',
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env: {},
+      logger,
+    });
+
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      3,
+      'xcrun',
+      ['simctl', 'openurl', 'booted', 'exp://example.test'],
+      { env: {}, logger }
+    );
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: approvalError },
+      'Could not preapprove the exp URL scheme for host.exp.Exponent. Opening the URL anyway; the Simulator might require manual confirmation.'
+    );
+  });
+
+  it('launches an Android Emulator application by package and activity', async () => {
+    const logger = createMockLogger();
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'com.example.app',
+      activityName: 'com.example.app.MainActivity',
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: {},
+      logger,
+    });
+
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'adb',
+      ['shell', 'am', 'start', '-n', 'com.example.app/com.example.app.MainActivity'],
+      { env: {}, logger }
+    );
+  });
+
+  it('passes launch arguments and opens a URL on Android', async () => {
+    const logger = createMockLogger();
+
+    await launchApplicationAsync({
+      applicationIdentifier: 'host.exp.exponent',
+      activityName: 'host.exp.exponent.MainActivity',
+      launchArgs: ['--ez', 'isTest', 'true'],
+      openUrl: 'exp://example.test',
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env: {},
+      logger,
+    });
+
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      1,
+      'adb',
+      [
+        'shell',
+        'am',
+        'start',
+        '--ez',
+        'isTest',
+        'true',
+        '-n',
+        'host.exp.exponent/host.exp.exponent.MainActivity',
+      ],
+      { env: {}, logger }
+    );
+    expect(mockedSpawn).toHaveBeenNthCalledWith(
+      2,
+      'adb',
+      [
+        'shell',
+        'am',
+        'start',
+        '-a',
+        'android.intent.action.VIEW',
+        '-d',
+        'exp://example.test',
+        '-n',
+        'host.exp.exponent/host.exp.exponent.MainActivity',
+      ],
+      { env: {}, logger }
+    );
+    expect(logger.info).toHaveBeenNthCalledWith(
+      1,
+      'Launching host.exp.exponent with arguments ["--ez","isTest","true"].'
+    );
+  });
+
+  it('requires an activity when launching an Android application', async () => {
+    await expect(
+      launchApplicationAsync({
+        applicationIdentifier: 'com.example.app',
+        runtimePlatform: BuildRuntimePlatform.LINUX,
+        env: {},
+        logger: createMockLogger(),
+      })
+    ).rejects.toMatchObject({ errorCode: 'EAS_LAUNCH_APPLICATION_MISSING_ACTIVITY' });
+
+    expect(mockedSpawn).not.toHaveBeenCalled();
+  });
+
+  it('launches using application metadata passed to the build step', async () => {
+    const launchApplication = createLaunchApplicationFunction();
+    const buildStep = launchApplication.createBuildStepFromFunctionCall(
+      createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.LINUX }),
+      {
+        callInputs: {
+          application_identifier: 'com.example.app',
+          activity_name: 'com.example.app.MainActivity',
+          launch_args: ['--ez', 'isTest', 'true'],
+          open_url: 'exp://example.test',
+        },
+      }
+    );
+    await buildStep.executeAsync();
+
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'adb',
+      [
+        'shell',
+        'am',
+        'start',
+        '--ez',
+        'isTest',
+        'true',
+        '-n',
+        'com.example.app/com.example.app.MainActivity',
+      ],
+      expect.any(Object)
+    );
+    expect(mockedSpawn).toHaveBeenCalledWith(
+      'adb',
+      [
+        'shell',
+        'am',
+        'start',
+        '-a',
+        'android.intent.action.VIEW',
+        '-d',
+        'exp://example.test',
+        '-n',
+        'com.example.app/com.example.app.MainActivity',
+      ],
+      expect.any(Object)
+    );
+  });
+
+  it.each([{}, ['valid', 42]])('rejects invalid launch arguments (%j)', async launchArgs => {
+    const launchApplication = createLaunchApplicationFunction();
+    const buildStep = launchApplication.createBuildStepFromFunctionCall(
+      createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.DARWIN }),
+      {
+        callInputs: {
+          application_identifier: 'com.example.app',
+          launch_args: launchArgs,
+        },
+      }
+    );
+
+    await expect(buildStep.executeAsync()).rejects.toMatchObject({
+      errorCode: 'EAS_LAUNCH_APPLICATION_INVALID_INPUT',
+      message: 'Input "launch_args" must be an array of strings.',
+    });
+    expect(mockedSpawn).not.toHaveBeenCalled();
+  });
+
+  it('rejects an invalid URL to open', async () => {
+    const launchApplication = createLaunchApplicationFunction();
+    const buildStep = launchApplication.createBuildStepFromFunctionCall(
+      createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.DARWIN }),
+      {
+        callInputs: {
+          application_identifier: 'com.example.app',
+          open_url: 'not a URL',
+        },
+      }
+    );
+
+    await expect(buildStep.executeAsync()).rejects.toMatchObject({
+      errorCode: 'EAS_LAUNCH_APPLICATION_INVALID_INPUT',
+      message: 'Input "open_url" must be a valid URL.',
+    });
+    expect(mockedSpawn).not.toHaveBeenCalled();
+  });
+
+  it.each(['application_identifier', 'activity_name'])(
+    'reports an empty %s input as a user error',
+    async inputName => {
+      const launchApplication = createLaunchApplicationFunction();
+      const buildStep = launchApplication.createBuildStepFromFunctionCall(
+        createGlobalContextMock({ runtimePlatform: BuildRuntimePlatform.LINUX }),
+        {
+          callInputs: {
+            application_identifier: 'com.example.app',
+            activity_name: 'com.example.app.MainActivity',
+            [inputName]: '',
+          },
+        }
+      );
+
+      await expect(buildStep.executeAsync()).rejects.toMatchObject({
+        errorCode: 'EAS_LAUNCH_APPLICATION_INVALID_INPUT',
+        message: `Input "${inputName}" must be a non-empty string. Pass the "${inputName}" output from eas/install_build.`,
+      });
+      expect(mockedSpawn).not.toHaveBeenCalled();
+    }
+  );
+});
@@ -1,4 +1,5 @@
 import { type bunyan } from '@expo/logger';
+import assert from 'node:assert';
 import fg from 'fast-glob';
 import { vol } from 'memfs';
 import path from 'node:path';
@@ -193,22 +194,53 @@ describe(resolveIosSigningOptionsAsync, () => {
    const signingOptions = await resolveIosSigningOptionsAsync({
      job,
      logger: mockLogger,
+      tmpDir: '/tmp',
    });

    expect(signingOptions).not.toBeNull();
-    expect(signingOptions?.keychainPath).toEqual('/tmp/ios_keychain');
-    expect(signingOptions?.signingIdentity).toEqual('Test App Certificate');
-    expect(signingOptions?.provisioningProfile).toEqual({
-      'com.example.testapp': '/tmp/ios_provisioning_profile',
+    expect(signingOptions).toMatchObject({
+      keychainPath: '/tmp/ios_keychain',
+      signingIdentity: 'Test App Certificate',
+      provisioningProfile: {
+        'com.example.testapp': '/tmp/ios_provisioning_profile',
+      },
    });
  });

+  it('should resolve zsign signing options without touching the keychain', async () => {
+    const job = createTestIosJob();
+    const tmpDir = '/tmp';
+    vol.mkdirSync(tmpDir, { recursive: true });
+    const credentialsManagerSpy = jest.spyOn(IosCredentialsManager.prototype, 'prepare');
+
+    const signingOptions = await resolveIosSigningOptionsAsync({
+      job,
+      logger: mockLogger,
+      backend: 'zsign',
+      tmpDir,
+    });
+
+    expect(credentialsManagerSpy).not.toHaveBeenCalled();
+    expect(signingOptions).toMatchObject({
+      backend: 'zsign',
+      keyPassword: job.secrets?.buildCredentials?.['testapp'].distributionCertificate.password,
+    });
+    assert(signingOptions?.backend === 'zsign');
+    expect(signingOptions.certificatePath).toMatch(/\/tmp\/dist-cert-.*\.p12/);
+    expect(vol.existsSync(signingOptions.certificatePath)).toBe(true);
+    assert(typeof signingOptions.provisioningProfile === 'object');
+    const profilePath = signingOptions.provisioningProfile['testapp'];
+    expect(profilePath).toMatch(/\/tmp\/profile-testapp-.*\.mobileprovision/);
+    expect(vol.existsSync(profilePath)).toBe(true);
+  });
+
  it('should return undefined if no build credentials are provided', async () => {
    // @ts-expect-error: createTestIosJob does not support buildCredentials as null
    const job = createTestIosJob({ buildCredentials: null });
    const signingOptions = await resolveIosSigningOptionsAsync({
      job,
      logger: mockLogger,
+      tmpDir: '/tmp',
    });
    expect(signingOptions).toBeUndefined();
  });
@@ -219,6 +251,7 @@ describe(resolveIosSigningOptionsAsync, () => {
    const signingOptions = await resolveIosSigningOptionsAsync({
      job,
      logger: mockLogger,
+      tmpDir: '/tmp',
    });
    expect(signingOptions).toBeUndefined();
  });
@@ -8,15 +8,19 @@ import {
  BuildStepOutput,
 } from '@expo/steps';
 import { Client } from '@urql/core';
+import contentDisposition from 'content-disposition';
 import { glob } from 'fast-glob';
 import { graphql } from 'gql.tada';
 import fetch from 'node-fetch';
+import assert from 'node:assert';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import stream from 'stream';
 import { promisify } from 'util';
 import { z } from 'zod';
+import bplistParser from 'bplist-parser';
+import plist from 'plist';

 import { CustomBuildContext } from '../../customBuildContext';
 import { formatBytes } from '../../utils/artifacts';
@@ -26,6 +30,10 @@ import { pluralize } from '../../utils/strings';

 const streamPipeline = promisify(stream.pipeline);

+type DownloadBuildSource =
+  | { buildId: string; applicationArchiveUrl?: never }
+  | { buildId?: never; applicationArchiveUrl: string };
+
 const BUILD_BY_ID_QUERY = graphql(`
  query DownloadBuildByIdQuery($buildId: ID!) {
    builds {
@@ -49,7 +57,12 @@ export function createDownloadBuildFunction(ctx: CustomBuildContext): BuildFunct
    inputProviders: [
      BuildStepInput.createProvider({
        id: 'build_id',
-        required: true,
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
+      BuildStepInput.createProvider({
+        id: 'application_archive_url',
+        required: false,
        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
      }),
      BuildStepInput.createProvider({
@@ -70,12 +83,39 @@ export function createDownloadBuildFunction(ctx: CustomBuildContext): BuildFunct

      const extensions = z.array(z.string()).parse(inputs.extensions.value);
      logger.info(`Expected extensions: [${extensions.join(', ')}]`);
-      const buildId = z.string().uuid().parse(inputs.build_id.value);
-      logger.info(`Downloading build ${buildId}...`);
+      const buildId = inputs.build_id.value
+        ? z.string().uuid().parse(inputs.build_id.value)
+        : undefined;
+      const applicationArchiveUrl = inputs.application_archive_url.value
+        ? parseHttpApplicationArchiveUrl(inputs.application_archive_url.value)
+        : undefined;
+
+      let source: DownloadBuildSource;
+      if (buildId) {
+        if (applicationArchiveUrl) {
+          throw new UserError(
+            'EAS_DOWNLOAD_BUILD_INVALID_SOURCE',
+            'Pass only one of build_id or application_archive_url.'
+          );
+        }
+        source = { buildId };
+      } else {
+        if (!applicationArchiveUrl) {
+          throw new UserError(
+            'EAS_DOWNLOAD_BUILD_INVALID_SOURCE',
+            'Pass build_id or application_archive_url.'
+          );
+        }
+        source = { applicationArchiveUrl };
+      }
+
+      logger.info(
+        buildId ? `Downloading build ${buildId}...` : `Downloading application archive...`
+      );

      const { artifactPath } = await downloadBuildAsync({
        logger,
-        buildId,
+        ...source,
        graphqlClient: ctx.graphqlClient,
        robotAccessToken: stepsCtx.global.staticContext.job.secrets?.robotAccessToken ?? null,
        extensions,
@@ -115,39 +155,50 @@ async function fetchApplicationArchiveUrlAsync({
  return applicationArchiveUrl;
 }

-export async function downloadBuildAsync({
-  logger,
-  buildId,
-  graphqlClient,
-  robotAccessToken,
-  extensions,
-}: {
-  logger: bunyan;
-  buildId: string;
-  graphqlClient: Client;
-  robotAccessToken: string | null;
-  extensions: string[];
-}): Promise<{ artifactPath: string }> {
+export async function downloadBuildAsync(
+  params: DownloadBuildSource & {
+    logger: bunyan;
+    graphqlClient: Client;
+    robotAccessToken: string | null;
+    extensions: string[];
+  }
+): Promise<{ artifactPath: string }> {
+  const { logger, graphqlClient, robotAccessToken, extensions } = params;
+
+  let downloadUrl: string;
+  let headers: { Authorization: string } | undefined;
+  if (params.applicationArchiveUrl) {
+    if (params.buildId) {
+      throw new UserError(
+        'EAS_DOWNLOAD_BUILD_INVALID_SOURCE',
+        'Pass only one of buildId or applicationArchiveUrl.'
+      );
+    }
+    downloadUrl = parseHttpApplicationArchiveUrl(params.applicationArchiveUrl);
+    headers = undefined;
+  } else if (params.buildId) {
+    const buildId = z.string().uuid().parse(params.buildId);
+    downloadUrl = await fetchApplicationArchiveUrlAsync({ buildId, graphqlClient });
+    headers = robotAccessToken ? { Authorization: `Bearer ${robotAccessToken}` } : undefined;
+  } else {
+    throw new UserError(
+      'EAS_DOWNLOAD_BUILD_INVALID_SOURCE',
+      'Pass buildId or applicationArchiveUrl.'
+    );
+  }
+
  const downloadDestinationDirectory = await fs.promises.mkdtemp(
    path.join(os.tmpdir(), 'download_build-downloaded-')
  );

-  const downloadUrl = await fetchApplicationArchiveUrlAsync({ buildId, graphqlClient });
-
-  const response = await retryOnDNSFailure(fetch)(downloadUrl, {
-    headers: robotAccessToken ? { Authorization: `Bearer ${robotAccessToken}` } : undefined,
-  });
+  const response = await retryOnDNSFailure(fetch)(downloadUrl, { headers });

  if (!response.ok) {
    const textResult = await asyncResult(response.text());
    throw new Error(`Unexpected response from server (${response.status}): ${textResult.value}`);
  }

-  // URL may contain percent-encoded characters, e.g. my%20file.apk
-  // this replaces all non-alphanumeric characters (excluding dot) with underscore
-  const archiveFilename = path
-    .basename(new URL(response.url).pathname)
-    .replace(/([^a-z0-9.-]+)/gi, '_');
+  const archiveFilename = resolveArchiveFilename({ response, extensions });
  const archivePath = path.join(downloadDestinationDirectory, archiveFilename);

  await streamPipeline(response.body, fs.createWriteStream(archivePath));
@@ -177,6 +228,18 @@ export async function downloadBuildAsync({
    onlyFiles: false,
    onlyDirectories: false,
  });
+  let matchingFilesRoot = extractionDirectory;
+
+  if (
+    matchingFiles.length === 0 &&
+    extensions.includes('app') &&
+    (await isIosAppBundleAsync(extractionDirectory))
+  ) {
+    const appBundlePath = `${extractionDirectory}.app`;
+    await fs.promises.rename(extractionDirectory, appBundlePath);
+    matchingFiles.push(appBundlePath);
+    matchingFilesRoot = path.dirname(appBundlePath);
+  }

  if (matchingFiles.length === 0) {
    throw new UserError(
@@ -189,8 +252,68 @@ export async function downloadBuildAsync({
    `Found ${matchingFiles.length} matching ${pluralize(
      matchingFiles.length,
      'entry'
-    )}:\n${matchingFiles.map(f => `- ${path.relative(extractionDirectory, f)}`).join('\n')}`
+    )}:\n${matchingFiles.map(f => `- ${path.relative(matchingFilesRoot, f)}`).join('\n')}`
  );

  return { artifactPath: matchingFiles[0] };
 }
+
+async function isIosAppBundleAsync(directory: string): Promise<boolean> {
+  try {
+    const infoPlist = await fs.promises.readFile(path.join(directory, 'Info.plist'));
+    const isBinaryPlist = infoPlist.subarray(0, 8).toString('ascii') === 'bplist00';
+    const parsedInfoPlist = (
+      isBinaryPlist
+        ? bplistParser.parseBuffer(infoPlist)[0]
+        : plist.parse(infoPlist.toString('utf8'))
+    ) as Record<string, unknown> | undefined;
+
+    return parsedInfoPlist?.CFBundlePackageType === 'APPL';
+  } catch {
+    return false;
+  }
+}
+
+function parseHttpApplicationArchiveUrl(value: unknown): string {
+  try {
+    const applicationArchiveUrl = z.string().parse(value);
+    const parsedUrl = new URL(applicationArchiveUrl);
+    assert(parsedUrl.protocol === 'http:' || parsedUrl.protocol === 'https:');
+    return applicationArchiveUrl;
+  } catch {
+    throw new UserError(
+      'EAS_DOWNLOAD_BUILD_INVALID_APPLICATION_ARCHIVE_URL',
+      'application_archive_url must be a valid HTTP or HTTPS URL.'
+    );
+  }
+}
+
+function resolveArchiveFilename({
+  response,
+  extensions,
+}: {
+  response: Awaited<ReturnType<typeof fetch>>;
+  extensions: string[];
+}): string {
+  const contentDispositionHeader = response.headers.get('content-disposition');
+  let headerFilename: string | undefined;
+  if (contentDispositionHeader) {
+    try {
+      headerFilename = contentDisposition.parse(contentDispositionHeader).parameters.filename;
+    } catch {
+      // Ignore malformed Content-Disposition headers and fall back to the response URL.
+    }
+  }
+
+  const urlFilename = path.basename(new URL(response.url).pathname);
+  let archiveFilename = path.basename(headerFilename ?? urlFilename ?? '');
+  if (!archiveFilename || archiveFilename === '.' || archiveFilename === '..') {
+    archiveFilename = 'application';
+  }
+  if (!path.extname(archiveFilename) && extensions.length === 1) {
+    archiveFilename = `${archiveFilename}.${extensions[0]}`;
+  }
+
+  // URL and header filenames may contain percent-encoded or unsafe filesystem characters.
+  return archiveFilename.replace(/([^a-z0-9.-]+)/gi, '_');
+}
@@ -0,0 +1,124 @@
+import { UserError } from '@expo/eas-build-job';
+import { bunyan } from '@expo/logger';
+import {
+  BuildFunction,
+  BuildRuntimePlatform,
+  BuildStepEnv,
+  BuildStepInput,
+  BuildStepInputValueTypeName,
+  BuildStepOutput,
+} from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+
+export function createInstallBuildFunction(): BuildFunction {
+  return new BuildFunction({
+    namespace: 'eas',
+    id: 'install_build',
+    name: 'Install build',
+    __metricsId: 'eas/install_build',
+    inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'artifact_path',
+        required: true,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
+    ],
+    outputProviders: [
+      BuildStepOutput.createProvider({
+        id: 'application_identifier',
+        required: true,
+      }),
+      BuildStepOutput.createProvider({
+        id: 'activity_name',
+        required: false,
+      }),
+    ],
+    fn: async ({ global, logger }, { inputs, outputs, env }) => {
+      const artifactPath = z.string().min(1).parse(inputs.artifact_path.value);
+      const { applicationIdentifier, activityName } = await installBuildAsync({
+        artifactPath,
+        runtimePlatform: global.runtimePlatform,
+        env,
+        logger,
+      });
+      outputs.application_identifier.set(applicationIdentifier);
+      if (activityName) {
+        outputs.activity_name.set(activityName);
+      }
+    },
+  });
+}
+
+export async function installBuildAsync({
+  artifactPath,
+  runtimePlatform,
+  env,
+  logger,
+}: {
+  artifactPath: string;
+  runtimePlatform: BuildRuntimePlatform;
+  env: BuildStepEnv;
+  logger: bunyan;
+}): Promise<{ applicationIdentifier: string; activityName?: string }> {
+  const artifactStat = await fs.promises.stat(artifactPath).catch(err => {
+    throw new UserError(
+      'EAS_INSTALL_BUILD_INVALID_ARTIFACT',
+      `Build artifact does not exist at ${artifactPath}.`,
+      { cause: err }
+    );
+  });
+
+  if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
+    if (path.extname(artifactPath) !== '.app' || !artifactStat.isDirectory()) {
+      throw new UserError(
+        'EAS_INSTALL_BUILD_INVALID_ARTIFACT',
+        'iOS Simulator sessions require a .app build artifact.'
+      );
+    }
+
+    const infoPlistPath = path.join(artifactPath, 'Info.plist');
+    const { stdout } = await spawn(
+      'plutil',
+      ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', infoPlistPath],
+      { stdio: 'pipe', env }
+    );
+    const applicationIdentifier = stdout.trim();
+    if (!applicationIdentifier) {
+      throw new UserError(
+        'EAS_INSTALL_BUILD_MISSING_IDENTIFIER',
+        `Could not read CFBundleIdentifier from ${infoPlistPath}.`
+      );
+    }
+
+    logger.info(`Installing ${artifactPath} on the iOS Simulator.`);
+    await spawn('xcrun', ['simctl', 'install', 'booted', artifactPath], { env, logger });
+    return { applicationIdentifier };
+  }
+
+  if (path.extname(artifactPath) !== '.apk' || !artifactStat.isFile()) {
+    throw new UserError(
+      'EAS_INSTALL_BUILD_INVALID_ARTIFACT',
+      'Android Emulator sessions require an .apk build artifact.'
+    );
+  }
+
+  const { stdout } = await spawn('aapt2', ['dump', 'badging', artifactPath], {
+    stdio: 'pipe',
+    env,
+  });
+  const applicationIdentifier = stdout.match(/package: name='([^']+)'/)?.[1];
+  const activityName = stdout.match(/launchable-activity: name='([^']+)'/)?.[1];
+  if (!applicationIdentifier) {
+    throw new UserError(
+      'EAS_INSTALL_BUILD_MISSING_IDENTIFIER',
+      `Could not read an Android application identifier from ${artifactPath}.`
+    );
+  }
+
+  logger.info(`Installing ${artifactPath} on the Android Emulator.`);
+  await spawn('adb', ['install', '-r', artifactPath], { env, logger });
+  return { applicationIdentifier, activityName };
+}
@@ -1,3 +1,4 @@
+import downloadFile from '@expo/downloader';
 import { SystemError, UserError } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
@@ -19,6 +20,11 @@ import semver from 'semver';

 import { MaestroBackend, resolveMaestroBackend } from './maestroBackend';
 import { Datadog } from '../../datadog';
+import { getXcodeVersionAsync } from '../../ios/xcode';
+import { IosSimulatorUtils } from '../../utils/IosSimulatorUtils';
+import { getProxiedDownloadUrl } from '../../utils/download';
+
+const MAESTRO_RUNNER_WDA_CACHE_DOWNLOAD_TIMEOUT_MS = 20_000;

 export function createInstallMaestroBuildFunction(): BuildFunction {
  return new BuildFunction({
@@ -148,11 +154,13 @@ export function createInstallMaestroBuildFunction(): BuildFunction {
              (requestedVersion === undefined &&
                (!currentMaestroRunnerVersion || semver.gt(currentMaestroRunnerVersion, '1.1.15'))))
          ) {
-            const xcodeVersion = await getXcodeVersion({ env });
+            // `getXcodeVersionAsync` returns the raw version (e.g. "16.4"), which
+            // `semver.coerce` normalizes (e.g. "16.4.0") for comparison and display.
+            const xcodeVersion = semver.coerce(await getXcodeVersionAsync({ env }));

            // maestro-runner 1.1.16 added `arch` to its xcodebuild destination. Xcode versions
            // below 26 reject that option, so use the last compatible maestro-runner version.
-            if (semver.lt(xcodeVersion, '26.0.0')) {
+            if (xcodeVersion && semver.lt(xcodeVersion, '26.0.0')) {
              if (requestedMaestroRunnerVersion) {
                throw new UserError(
                  'ERR_MAESTRO_INVALID_INPUT',
@@ -190,6 +198,13 @@ export function createInstallMaestroBuildFunction(): BuildFunction {
        throw new Error(`Failed to ensure ${backend} is installed.`);
      }

+      if (backend === 'maestro-runner' && global.runtimePlatform === BuildRuntimePlatform.DARWIN) {
+        await installMaestroRunnerWdaCache({
+          logger,
+          env,
+        });
+      }
+
      logger.info(`${backend} ${maestroVersionResult.value} is ready.`);
      outputs.maestro_version.set(maestroVersionResult.value);

@@ -201,19 +216,140 @@ export function createInstallMaestroBuildFunction(): BuildFunction {
  });
 }

-async function getXcodeVersion({ env }: { env: BuildStepEnv }): Promise<string> {
-  let stdout: string;
-  try {
-    ({ stdout } = await spawn('xcodebuild', ['-version'], { stdio: 'pipe', env }));
-  } catch (error) {
-    throw new SystemError('Failed to get Xcode version', { cause: error });
+async function installMaestroRunnerWdaCache({
+  logger,
+  env,
+}: {
+  logger: bunyan;
+  env: BuildStepEnv;
+}): Promise<void> {
+  if (!env.HOME) {
+    logger.warn(
+      'Skipping the prebuilt WebDriverAgent cache because the $HOME environment variable is empty.'
+    );
+    return;
  }
+  const maestroRunnerHome = path.join(env.HOME, '.maestro-runner');

-  const xcodeVersion = semver.coerce(/^Xcode\s+(\S+)/m.exec(stdout)?.[1])?.version;
-  if (!xcodeVersion) {
-    throw new SystemError(`Failed to parse Xcode version from xcodebuild output: ${stdout.trim()}`);
+  try {
+    const wdaVersion = await getMaestroRunnerWdaVersion({ maestroRunnerHome });
+    if (!wdaVersion) {
+      logger.info(
+        'Skipping the prebuilt WebDriverAgent cache because the installed WDA version is unknown.'
+      );
+      return;
+    }
+    const xcodeVersion = await getXcodeVersionAsync({ env });
+    const iosRuntimes = await IosSimulatorUtils.getAvailableRuntimesAsync({ env });
+    const iosRuntimeIdentifierPrefix = 'com.apple.CoreSimulator.SimRuntime.iOS-';
+    // maestro-runner derives its WDA cache key from the runtime identifier, not from the runtime
+    // version. These values can differ for patched runtimes, for example the iOS-26-3 identifier
+    // can report version 26.3.1.
+    const iosRuntimeVersions = [
+      ...new Set(
+        iosRuntimes.map(runtime =>
+          runtime.identifier.slice(iosRuntimeIdentifierPrefix.length).replaceAll('-', '.')
+        )
+      ),
+    ];
+    if (iosRuntimeVersions.length === 0) {
+      logger.info(
+        'Skipping the prebuilt WebDriverAgent cache because no iOS runtime is available.'
+      );
+      return;
+    }
+
+    const tempDirectory = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), 'install_maestro_runner_wda_cache')
+    );
+    try {
+      const archivePath = path.join(tempDirectory, 'wda-cache.tar.gz');
+      const directArchiveUrl =
+        `https://storage.googleapis.com/turtle-v2/maestro-runner-wda-cache/` +
+        `xcode-${encodeURIComponent(xcodeVersion)}-wda-${encodeURIComponent(wdaVersion)}.tar.gz`;
+      const proxiedArchiveUrl = getProxiedDownloadUrl({
+        directUrl: directArchiveUrl,
+        proxyBaseUrl: env.EAS_BUILD_COCOAPODS_CACHE_URL,
+      });
+
+      logger.info(`Downloading the prebuilt WebDriverAgent cache for Xcode ${xcodeVersion}`);
+      if (proxiedArchiveUrl) {
+        try {
+          await downloadFile(proxiedArchiveUrl, archivePath, {
+            retry: 3,
+            timeout: MAESTRO_RUNNER_WDA_CACHE_DOWNLOAD_TIMEOUT_MS,
+          });
+        } catch (err) {
+          logger.debug(
+            { err },
+            'Failed to download the prebuilt WebDriverAgent cache via the proxy; falling back to the direct URL.'
+          );
+          await downloadFile(directArchiveUrl, archivePath, {
+            retry: 3,
+            timeout: MAESTRO_RUNNER_WDA_CACHE_DOWNLOAD_TIMEOUT_MS,
+          });
+        }
+      } else {
+        await downloadFile(directArchiveUrl, archivePath, {
+          retry: 3,
+          timeout: MAESTRO_RUNNER_WDA_CACHE_DOWNLOAD_TIMEOUT_MS,
+        });
+      }
+      await fs.promises.mkdir(maestroRunnerHome, { recursive: true });
+      await spawn('tar', ['-xzf', archivePath, '-C', maestroRunnerHome], { logger, env });
+
+      const genericProductsDirectory = path.join(
+        maestroRunnerHome,
+        'cache',
+        'wda-builds',
+        'generic',
+        'DerivedData',
+        'Build',
+        'Products'
+      );
+      for (const runtimeVersion of iosRuntimeVersions) {
+        const productsDirectory = path.join(
+          maestroRunnerHome,
+          'cache',
+          'wda-builds',
+          `sim-ios${runtimeVersion}-iphone`,
+          'DerivedData',
+          'Build',
+          'Products'
+        );
+        await fs.promises.cp(genericProductsDirectory, productsDirectory, { recursive: true });
+      }
+
+      logger.info(
+        `Installed the prebuilt WebDriverAgent cache for iOS ${iosRuntimeVersions.join(', ')}.`
+      );
+    } finally {
+      await fs.promises.rm(tempDirectory, { force: true, recursive: true });
+    }
+  } catch (err: any) {
+    logger.warn(
+      { err },
+      'Failed to install the prebuilt WebDriverAgent cache. maestro-runner will build WebDriverAgent when it is needed.'
+    );
+  }
+}
+
+async function getMaestroRunnerWdaVersion({
+  maestroRunnerHome,
+}: {
+  maestroRunnerHome: string;
+}): Promise<string | null> {
+  try {
+    const packageJson = JSON.parse(
+      await fs.promises.readFile(
+        path.join(maestroRunnerHome, 'drivers', 'ios', 'WebDriverAgent', 'package.json'),
+        'utf8'
+      )
+    );
+    return typeof packageJson.version === 'string' ? packageJson.version : null;
+  } catch {
+    return null;
  }
-  return xcodeVersion;
 }

 async function getMaestroVersion({
@@ -0,0 +1,219 @@
+import { UserError } from '@expo/eas-build-job';
+import { bunyan } from '@expo/logger';
+import {
+  BuildFunction,
+  BuildRuntimePlatform,
+  BuildStepEnv,
+  BuildStepInput,
+  BuildStepInputValueTypeName,
+} from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+
+const IOS_URL_SCHEME_APPROVAL_DOMAIN = 'com.apple.launchservices.schemeapproval';
+const IOS_URL_SCHEME_APPROVAL_KEY_PREFIX = 'com.apple.CoreSimulator.CoreSimulatorBridge-->';
+
+export function createLaunchApplicationFunction(): BuildFunction {
+  return new BuildFunction({
+    namespace: 'eas',
+    id: 'launch_application',
+    name: 'Launch application',
+    __metricsId: 'eas/launch_application',
+    inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'application_identifier',
+        required: true,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
+      BuildStepInput.createProvider({
+        id: 'activity_name',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
+      BuildStepInput.createProvider({
+        id: 'launch_args',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+      }),
+      BuildStepInput.createProvider({
+        id: 'open_url',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
+    ],
+    fn: async ({ global, logger }, { inputs, env }) => {
+      const applicationIdentifier = parseNonEmptyStringInput(
+        inputs.application_identifier.value,
+        'application_identifier'
+      );
+      const activityName =
+        inputs.activity_name.value === undefined
+          ? undefined
+          : parseNonEmptyStringInput(inputs.activity_name.value, 'activity_name');
+      const launchArgs = parseLaunchArgsInput(inputs.launch_args.value);
+      const openUrl =
+        inputs.open_url.value === undefined ? undefined : parseOpenUrlInput(inputs.open_url.value);
+      await launchApplicationAsync({
+        applicationIdentifier,
+        activityName,
+        launchArgs,
+        openUrl,
+        runtimePlatform: global.runtimePlatform,
+        env,
+        logger,
+      });
+    },
+  });
+}
+
+export async function launchApplicationAsync({
+  applicationIdentifier,
+  activityName,
+  launchArgs = [],
+  openUrl,
+  runtimePlatform,
+  env,
+  logger,
+}: {
+  applicationIdentifier: string;
+  activityName?: string;
+  launchArgs?: string[];
+  openUrl?: string;
+  runtimePlatform: BuildRuntimePlatform;
+  env: BuildStepEnv;
+  logger: bunyan;
+}): Promise<void> {
+  if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
+    logApplicationLaunch(logger, applicationIdentifier, launchArgs);
+    await spawn('xcrun', ['simctl', 'launch', 'booted', applicationIdentifier, ...launchArgs], {
+      env,
+      logger,
+    });
+    if (openUrl) {
+      await preapproveIosUrlSchemeAsync({ applicationIdentifier, openUrl, env, logger });
+      logger.info(`Opening ${openUrl} in ${applicationIdentifier}.`);
+      await spawn('xcrun', ['simctl', 'openurl', 'booted', openUrl], { env, logger });
+    }
+    return;
+  }
+
+  if (!activityName) {
+    throw new UserError(
+      'EAS_LAUNCH_APPLICATION_MISSING_ACTIVITY',
+      'Launching an Android application requires activity_name.'
+    );
+  }
+
+  logApplicationLaunch(logger, applicationIdentifier, launchArgs);
+  // Android does not support process arguments like iOS. Pass raw `am start` Intent
+  // arguments instead, such as `--es key value` or `--ez key true`.
+  await spawn(
+    'adb',
+    ['shell', 'am', 'start', ...launchArgs, '-n', `${applicationIdentifier}/${activityName}`],
+    {
+      env,
+      logger,
+    }
+  );
+  if (openUrl) {
+    logger.info(`Opening ${openUrl} in ${applicationIdentifier}.`);
+    await spawn(
+      'adb',
+      [
+        'shell',
+        'am',
+        'start',
+        '-a',
+        'android.intent.action.VIEW',
+        '-d',
+        openUrl,
+        '-n',
+        `${applicationIdentifier}/${activityName}`,
+      ],
+      { env, logger }
+    );
+  }
+}
+
+async function preapproveIosUrlSchemeAsync({
+  applicationIdentifier,
+  openUrl,
+  env,
+  logger,
+}: {
+  applicationIdentifier: string;
+  openUrl: string;
+  env: BuildStepEnv;
+  logger: bunyan;
+}): Promise<void> {
+  const urlScheme = new URL(openUrl).protocol.slice(0, -1);
+  if (urlScheme === 'http' || urlScheme === 'https') {
+    return;
+  }
+
+  try {
+    await spawn(
+      'xcrun',
+      [
+        'simctl',
+        'spawn',
+        'booted',
+        'defaults',
+        'write',
+        IOS_URL_SCHEME_APPROVAL_DOMAIN,
+        `${IOS_URL_SCHEME_APPROVAL_KEY_PREFIX}${urlScheme}`,
+        '-string',
+        applicationIdentifier,
+      ],
+      { env, logger }
+    );
+  } catch (error) {
+    logger.warn(
+      { err: error },
+      `Could not preapprove the ${urlScheme} URL scheme for ${applicationIdentifier}. Opening the URL anyway; the Simulator might require manual confirmation.`
+    );
+  }
+}
+
+function logApplicationLaunch(
+  logger: bunyan,
+  applicationIdentifier: string,
+  launchArgs: string[]
+): void {
+  const argumentsDescription =
+    launchArgs.length > 0 ? ` with arguments ${JSON.stringify(launchArgs)}` : '';
+  logger.info(`Launching ${applicationIdentifier}${argumentsDescription}.`);
+}
+
+function parseNonEmptyStringInput(value: unknown, inputName: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new UserError(
+      'EAS_LAUNCH_APPLICATION_INVALID_INPUT',
+      `Input "${inputName}" must be a non-empty string. Pass the "${inputName}" output from eas/install_build.`
+    );
+  }
+  return value;
+}
+
+function parseLaunchArgsInput(value: unknown): string[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value) || !value.every(argument => typeof argument === 'string')) {
+    throw new UserError(
+      'EAS_LAUNCH_APPLICATION_INVALID_INPUT',
+      'Input "launch_args" must be an array of strings.'
+    );
+  }
+  return value;
+}
+
+function parseOpenUrlInput(value: unknown): string {
+  const openUrl = parseNonEmptyStringInput(value, 'open_url');
+  if (!URL.canParse(openUrl)) {
+    throw new UserError(
+      'EAS_LAUNCH_APPLICATION_INVALID_INPUT',
+      'Input "open_url" must be a valid URL.'
+    );
+  }
+  return openUrl;
+}
@@ -62,6 +62,12 @@ export function createRepackBuildFunction(): BuildFunction {
        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
        required: false,
      }),
+      BuildStepInput.createProvider({
+        id: 'ios_signing_backend',
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+        required: false,
+        allowedValues: ['fastlane', 'zsign'],
+      }),
      BuildStepInput.createProvider({
        id: 'repack_version',
        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
@@ -144,12 +150,14 @@ export function createRepackBuildFunction(): BuildFunction {
            iosSigningOptions: await resolveIosSigningOptionsAsync({
              job: stepsCtx.global.staticContext.job,
              logger: stepsCtx.logger,
+              backend: inputs.ios_signing_backend.value as 'fastlane' | 'zsign' | undefined,
              useAppEntitlements: inputs.ios_signing_use_source_app_entitlements.value as
                | boolean
                | undefined,
              entitlementsPath: inputs.ios_signing_app_entitlements_path.value as
                | string
                | undefined,
+              tmpDir,
            }),
            logger: stepsCtx.logger,
            spawnAsync: repackSpawnAsync,
@@ -297,24 +305,51 @@ export async function resolveAndroidSigningOptionsAsync({
 }

 /**
- * Resolves iOS signing options from the job secrets.
+ * Resolves iOS signing options from the job secrets, dispatching on the
+ * requested signing backend.
 */
 export async function resolveIosSigningOptionsAsync({
  job,
  logger,
+  backend,
  useAppEntitlements,
  entitlementsPath,
+  tmpDir,
 }: {
  job: Job;
  logger: bunyan;
+  backend?: 'fastlane' | 'zsign';
  useAppEntitlements?: boolean;
  entitlementsPath?: string;
+  tmpDir: string;
 }): Promise<IosSigningOptions | undefined> {
  const iosJob = job as Ios.Job;
  const buildCredentials = iosJob.secrets?.buildCredentials;
  if (iosJob.simulator || buildCredentials == null) {
    return undefined;
  }
+  const commonOptions = { buildCredentials, logger, useAppEntitlements, entitlementsPath };
+  return backend === 'zsign'
+    ? await createIosZsignOptionsAsync({ ...commonOptions, tmpDir })
+    : await createIosFastlaneOptionsAsync(commonOptions);
+}
+
+/**
+ * Creates signing options for the fastlane backend: certificates are imported
+ * into a temporary keychain and provisioning profiles are parsed with the
+ * macOS `security` tool.
+ */
+async function createIosFastlaneOptionsAsync({
+  buildCredentials,
+  logger,
+  useAppEntitlements,
+  entitlementsPath,
+}: {
+  buildCredentials: Ios.BuildCredentials;
+  logger: bunyan;
+  useAppEntitlements?: boolean;
+  entitlementsPath?: string;
+}): Promise<IosSigningOptions> {
  const credentialsManager = new IosCredentialsManager(buildCredentials);
  const credentials = await credentialsManager.prepare(logger);

@@ -330,3 +365,53 @@ export async function resolveIosSigningOptionsAsync({
    entitlementsPath,
  };
 }
+
+/**
+ * Creates signing options for the zsign backend. The distribution certificate
+ * secret is already a PKCS#12 file, so it goes to disk as-is together with the
+ * provisioning profiles.
+ */
+async function createIosZsignOptionsAsync({
+  buildCredentials,
+  logger,
+  useAppEntitlements,
+  entitlementsPath,
+  tmpDir,
+}: {
+  buildCredentials: Ios.BuildCredentials;
+  logger: bunyan;
+  useAppEntitlements?: boolean;
+  entitlementsPath?: string;
+  tmpDir: string;
+}): Promise<IosSigningOptions> {
+  const targets = Object.entries(buildCredentials);
+  const [targetName, targetCredentials] = targets[0];
+  logger.info(`Using the distribution certificate from target '${targetName}' for zsign`);
+
+  const certificatePath = path.join(tmpDir, `dist-cert-${randomUUID()}.p12`);
+  await fs.promises.writeFile(
+    certificatePath,
+    new Uint8Array(Buffer.from(targetCredentials.distributionCertificate.dataBase64, 'base64'))
+  );
+
+  // zsign matches profiles to bundles by the app-id suffix itself, so the
+  // record keys are informational only.
+  const provisioningProfile: Record<string, string> = {};
+  for (const [target, credentials] of targets) {
+    const profilePath = path.join(tmpDir, `profile-${target}-${randomUUID()}.mobileprovision`);
+    await fs.promises.writeFile(
+      profilePath,
+      new Uint8Array(Buffer.from(credentials.provisioningProfileBase64, 'base64'))
+    );
+    provisioningProfile[target] = profilePath;
+  }
+
+  return {
+    backend: 'zsign',
+    certificatePath,
+    keyPassword: targetCredentials.distributionCertificate.password,
+    provisioningProfile,
+    useAppEntitlements,
+    entitlementsPath,
+  };
+}
@@ -15,8 +15,9 @@ import path from 'path';
 import { sendCcacheStatsAsync } from './ccacheStats';
 import { decompressCacheAsync, downloadCacheAsync, downloadPublicCacheAsync } from './restoreCache';
 import {
-  CACHE_KEY_PREFIX_BY_PLATFORM,
+  CcacheBuildTarget,
  generateDefaultBuildCacheKeyAsync,
+  getCcacheKeyPrefix,
  getCcachePath,
 } from '../../utils/cacheKey';
 import { Datadog } from '../../datadog';
@@ -35,6 +36,11 @@ export function createRestoreBuildCacheFunction(): BuildFunction {
        required: false,
        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
      }),
+      BuildStepInput.createProvider({
+        id: 'simulator',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.BOOLEAN,
+      }),
    ],
    fn: async (stepCtx, { env, inputs }) => {
      const { logger } = stepCtx;
@@ -48,10 +54,20 @@ export function createRestoreBuildCacheFunction(): BuildFunction {
        );
      }

+      const target: CcacheBuildTarget =
+        platform === Platform.IOS
+          ? {
+              platform,
+              simulator:
+                (inputs.simulator.value as boolean | undefined) ??
+                (stepCtx.global.staticContext.job.platform === Platform.IOS &&
+                  stepCtx.global.staticContext.job.simulator === true),
+            }
+          : { platform };
      await restoreCcacheAsync({
        logger,
        workingDirectory,
-        platform,
+        target,
        env,
        secrets: stepCtx.global.staticContext.job.secrets,
      });
@@ -92,13 +108,13 @@ export function createCacheStatsBuildFunction(): BuildFunction {
 export async function restoreCcacheAsync({
  logger,
  workingDirectory,
-  platform,
+  target,
  env,
  secrets,
 }: {
  logger: bunyan;
  workingDirectory: string;
-  platform: Platform;
+  target: CcacheBuildTarget;
  env: Record<string, string | undefined>;
  secrets?: { robotAccessToken?: string };
 }): Promise<void> {
@@ -136,7 +152,7 @@ export async function restoreCcacheAsync({
      })
    );

-    const cacheKey = await generateDefaultBuildCacheKeyAsync(workingDirectory, platform);
+    const cacheKey = await generateDefaultBuildCacheKeyAsync(workingDirectory, target);
    logger.info(`Restoring cache key: ${cacheKey}`);

    const jobId = nullthrows(env.EAS_BUILD_ID, 'EAS_BUILD_ID is not set');
@@ -147,8 +163,8 @@ export async function restoreCcacheAsync({
      robotAccessToken,
      paths: [cachePath],
      key: cacheKey,
-      keyPrefixes: [CACHE_KEY_PREFIX_BY_PLATFORM[platform]],
-      platform,
+      keyPrefixes: [getCcacheKeyPrefix(target)],
+      platform: target.platform,
    });

    await decompressCacheAsync({
@@ -175,7 +191,7 @@ export async function restoreCcacheAsync({
          expoApiServerURL,
          robotAccessToken,
          paths: [cachePath],
-          platform,
+          platform: target.platform,
        });
        await decompressCacheAsync({
          archivePath,
@@ -15,7 +15,11 @@ import path from 'path';

 import { compressCacheAsync, uploadCacheAsync } from './saveCache';
 import { formatBytes } from '../../utils/artifacts';
-import { generateDefaultBuildCacheKeyAsync, getCcachePath } from '../../utils/cacheKey';
+import {
+  CcacheBuildTarget,
+  generateDefaultBuildCacheKeyAsync,
+  getCcachePath,
+} from '../../utils/cacheKey';
 import { generateGradleCacheKeyAsync } from '../../utils/gradleCacheKey';

 export function createSaveBuildCacheFunction(evictUsedBefore: Date): BuildFunction {
@@ -30,6 +34,11 @@ export function createSaveBuildCacheFunction(evictUsedBefore: Date): BuildFuncti
        required: false,
        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
      }),
+      BuildStepInput.createProvider({
+        id: 'simulator',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.BOOLEAN,
+      }),
    ],
    fn: async (stepCtx, { env, inputs }) => {
      const { logger } = stepCtx;
@@ -43,10 +52,20 @@ export function createSaveBuildCacheFunction(evictUsedBefore: Date): BuildFuncti
        );
      }

+      const target: CcacheBuildTarget =
+        platform === Platform.IOS
+          ? {
+              platform,
+              simulator:
+                (inputs.simulator.value as boolean | undefined) ??
+                (stepCtx.global.staticContext.job.platform === Platform.IOS &&
+                  stepCtx.global.staticContext.job.simulator === true),
+            }
+          : { platform };
      await saveCcacheAsync({
        logger,
        workingDirectory,
-        platform,
+        target,
        evictUsedBefore,
        env,
        secrets: stepCtx.global.staticContext.job.secrets,
@@ -67,14 +86,14 @@ export function createSaveBuildCacheFunction(evictUsedBefore: Date): BuildFuncti
 export async function saveCcacheAsync({
  logger,
  workingDirectory,
-  platform,
+  target,
  evictUsedBefore,
  env,
  secrets,
 }: {
  logger: bunyan;
  workingDirectory: string;
-  platform: Platform;
+  target: CcacheBuildTarget;
  evictUsedBefore: Date;
  env: Record<string, string | undefined>;
  secrets?: { robotAccessToken?: string };
@@ -99,7 +118,7 @@ export async function saveCcacheAsync({
  }

  try {
-    const cacheKey = await generateDefaultBuildCacheKeyAsync(workingDirectory, platform);
+    const cacheKey = await generateDefaultBuildCacheKeyAsync(workingDirectory, target);
    logger.info(`Saving cache key: ${cacheKey}`);

    const jobId = nullthrows(env.EAS_BUILD_ID, 'EAS_BUILD_ID is not set');
@@ -143,7 +162,7 @@ export async function saveCcacheAsync({
      key: cacheKey,
      paths: [cachePath],
      size,
-      platform,
+      platform: target.platform,
    });
  } catch (err) {
    logger.error({ err }, 'Failed to save cache');
@@ -27,6 +27,11 @@ export function createStartServeSimRemoteSessionBuildFunction(
    __metricsId: 'eas/start_serve_sim_remote_session',
    supportedRuntimePlatforms: [BuildRuntimePlatform.DARWIN],
    inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'package_version',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
      BuildStepInput.createProvider({
        id: 'max_duration_seconds',
        required: false,
@@ -37,6 +42,7 @@ export function createStartServeSimRemoteSessionBuildFunction(
      const deviceRunSessionId = getDeviceRunSessionIdOrThrow(env);
      const ngrokTunnelDomain = getNgrokTunnelDomainOrThrow(env);
      const maxDurationSeconds = inputs.max_duration_seconds?.value as number | undefined;
+      const packageVersion = inputs.package_version?.value as string | undefined;

      logger.info('Starting serve-sim remote session.');

@@ -47,6 +53,7 @@ export function createStartServeSimRemoteSessionBuildFunction(
        env,
        logger,
        timeoutMs: STARTUP_TIMEOUT_MS,
+        packageVersion,
      });
      logger.info(`Preview URL: ${serveSim.previewUrl}`);

@@ -0,0 +1,38 @@
+import { APPIUM_COMMAND_SUMMARIES, humanizeAppiumCommand } from '../appiumCommandSummary';
+
+// Coverage of the generated Appium and driver command sets is enforced at compile time by the
+// `Record<AppiumCommand, string>` type in appiumCommandSummary.ts, so it is not
+// re-checked here.
+
+describe('APPIUM_COMMAND_SUMMARIES', () => {
+  it('has a non-empty summary that differs from the command name for every entry', () => {
+    for (const [command, summary] of Object.entries(APPIUM_COMMAND_SUMMARIES)) {
+      expect(summary).toBeTruthy();
+      expect(summary).not.toBe(command);
+    }
+  });
+});
+
+describe(humanizeAppiumCommand, () => {
+  it.each([
+    ['getWindowRect', 'Read the screen size'],
+    ['getScreenshot', 'Took a screenshot'],
+    ['getPageSource', 'Read the screen contents'],
+    ['click', 'Tapped an element'],
+    ['setValue', 'Typed into an element'],
+    ['createSession', 'Started the session'],
+    ['deleteSession', 'Ended the session'],
+    ['postAcceptAlert', 'Accepted an alert'],
+    ['mobileScroll', 'Scrolled the screen'],
+    ['openNotifications', 'Opened notifications'],
+  ])('maps the known command %s to a curated summary', (command, expected) => {
+    expect(humanizeAppiumCommand(command)).toBe(expected);
+  });
+
+  it.each(['proxyReqRes', 'mobile: scroll', 'getDeviceInfo', 'toString', 'constructor', ''])(
+    'returns the raw command %p when it has no curated summary',
+    command => {
+      expect(humanizeAppiumCommand(command)).toBe(command);
+    }
+  );
+});
@@ -58,7 +58,10 @@ describe(startAppiumEventCollectionAsync, () => {
        producer: 'appium',
        type: 'operation.completed',
        durationMs: 25,
-        summary: 'getOrientation',
+        summary: 'Read the screen orientation',
+        data: {
+          command: 'getOrientation',
+        },
      },
    });

@@ -67,10 +67,17 @@ describe(listArgentArtifactsAsync, () => {
          artifacts: [
            {
              id: 'artifact-id',
+              kind: 'native-profile-report',
              filename: 'report.json',
              mimeType: 'application/json',
              isDirectory: false,
            },
+            {
+              id: 'legacy-artifact-id',
+              filename: 'screen.png',
+              mimeType: 'image/png',
+              isDirectory: false,
+            },
          ],
        })
      )
@@ -84,10 +91,17 @@ describe(listArgentArtifactsAsync, () => {
    expect(artifacts).toEqual([
      {
        id: 'artifact-id',
+        kind: 'native-profile-report',
        filename: 'report.json',
        mimeType: 'application/json',
        isDirectory: false,
      },
+      {
+        id: 'legacy-artifact-id',
+        filename: 'screen.png',
+        mimeType: 'image/png',
+        isDirectory: false,
+      },
    ]);
    expect(jest.mocked(fetch)).toHaveBeenCalledWith('http://127.0.0.1:1234/artifacts', {
      headers: { Authorization: 'Bearer tools-token' },
@@ -143,6 +157,7 @@ describe(uploadArgentArtifactAsync, () => {

  async function uploadAsync(artifact: {
    id: string;
+    kind?: string;
    filename: string;
    mimeType: string;
    isDirectory?: boolean;
@@ -185,7 +200,42 @@ describe(uploadArgentArtifactAsync, () => {
    );
  });

-  it('leaves directory artifacts unclassified because they are uploaded as a tarball', async () => {
+  it('uses the semantic kind reported by Argent', async () => {
+    const ctx = await uploadAsync({
+      id: 'artifact-id',
+      kind: 'native-profile-report',
+      filename: 'native-profile-report.md',
+      mimeType: 'text/markdown',
+    });
+
+    expect(jest.mocked(uploadDeviceRunSessionArtifactAsync)).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        filename: 'native-profile-report.md',
+        kind: 'native-profile-report',
+      })
+    );
+  });
+
+  it('keeps the semantic kind when a directory is uploaded as a tarball', async () => {
+    const ctx = await uploadAsync({
+      id: 'artifact-id',
+      kind: 'native-profile-trace',
+      filename: 'native-profile.trace',
+      mimeType: 'application/octet-stream',
+      isDirectory: true,
+    });
+
+    expect(jest.mocked(uploadDeviceRunSessionArtifactAsync)).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        filename: 'native-profile.trace.tar.gz',
+        kind: 'native-profile-trace',
+      })
+    );
+  });
+
+  it('leaves an older unclassified directory artifact without a kind', async () => {
    const ctx = await uploadAsync({
      id: 'artifact-id',
      filename: 'screenshots',
@@ -136,7 +136,7 @@ describe(createServeSimArgs, () => {
      '--mjpeg-quality',
      '0.55',
      '--video-bitrate',
-      '3000000',
+      '6000000',
      '--video-fps',
      '60',
      '--turn-url',
@@ -157,6 +157,20 @@ describe(createServeSimArgs, () => {
      'https://expo.dev',
    ]);
  });
+
+  it('pins the requested package version', () => {
+    expect(createServeSimArgs({ port: 4321, packageVersion: '0.1.38' }).slice(0, 2)).toEqual([
+      '--yes',
+      '@expo/[email protected]',
+    ]);
+  });
+
+  it('pins a dist-tag', () => {
+    expect(createServeSimArgs({ port: 4321, packageVersion: 'next' }).slice(0, 2)).toEqual([
+      '--yes',
+      '@expo/serve-sim@next',
+    ]);
+  });
 });

 describe(metricsCorsOriginToServeSimArgs, () => {
@@ -0,0 +1,418 @@
+import { type AppiumCommand } from './appiumCommands.generated';
+
+export const APPIUM_COMMAND_SUMMARIES: Record<AppiumCommand, string> = {
+  // Session lifecycle
+  createSession: 'Started the session',
+  deleteSession: 'Ended the session',
+  getSession: 'Read the session details',
+  getStatus: 'Checked the server status',
+  getAppiumSessions: 'Listed Appium sessions',
+  getAppiumSessionCapabilities: 'Read the session capabilities',
+  getTimeouts: 'Read timeouts',
+  timeouts: 'Set timeouts',
+  getSettings: 'Read Appium settings',
+  updateSettings: 'Updated Appium settings',
+  listCommands: 'Listed available commands',
+  listExtensions: 'Listed available extensions',
+  receiveAsyncResponse: 'Received an async response',
+
+  // Screen and media
+  getScreenshot: 'Took a screenshot',
+  getElementScreenshot: 'Took a screenshot of an element',
+  getPageSource: 'Read the screen contents',
+  printPage: 'Printed the page',
+
+  // Window and orientation
+  getWindowRect: 'Read the screen size',
+  setWindowRect: 'Resized the window',
+  maximizeWindow: 'Maximized the window',
+  minimizeWindow: 'Minimized the window',
+  fullScreenWindow: 'Made the window full screen',
+  getWindowHandle: 'Read the current window',
+  getWindowHandles: 'Listed open windows',
+  setWindow: 'Switched window',
+  closeWindow: 'Closed the window',
+  createNewWindow: 'Opened a new window',
+  setFrame: 'Switched to a frame',
+  switchToParentFrame: 'Switched to the parent frame',
+  getOrientation: 'Read the screen orientation',
+  setOrientation: 'Changed the screen orientation',
+  getRotation: 'Read the device rotation',
+  setRotation: 'Rotated the device',
+
+  // Device
+  getDeviceTime: 'Read the device time',
+  getGeoLocation: 'Read the device location',
+  setGeoLocation: 'Set the device location',
+  getNetworkConnection: 'Read the network connection',
+  setNetworkConnection: 'Changed the network connection',
+  setDevicePosture: 'Set the device posture',
+  clearDevicePosture: 'Cleared the device posture',
+  setPermissions: 'Set app permissions',
+
+  // Element discovery
+  findElement: 'Found an element',
+  findElements: 'Found elements',
+  findElementFromElement: 'Found a nested element',
+  findElementsFromElement: 'Found nested elements',
+  findElementFromShadowRoot: 'Found an element in a shadow root',
+  findElementsFromShadowRoot: 'Found elements in a shadow root',
+  elementShadowRoot: 'Read an element shadow root',
+  active: 'Read the focused element',
+
+  // Element interaction
+  click: 'Tapped an element',
+  clear: 'Cleared an element',
+  setValue: 'Typed into an element',
+  getText: 'Read element text',
+  getName: 'Read an element tag',
+  getAttribute: 'Read an element attribute',
+  getProperty: 'Read an element property',
+  getCssProperty: 'Read an element style',
+  getComputedLabel: 'Read an element label',
+  getComputedRole: 'Read an element role',
+  getElementRect: 'Read an element position and size',
+  elementDisplayed: 'Checked if an element was visible',
+  elementEnabled: 'Checked if an element was enabled',
+  elementSelected: 'Checked if an element was selected',
+
+  // Gestures
+  performActions: 'Performed a gesture',
+  releaseActions: 'Finished a gesture',
+
+  // App management
+  installApp: 'Installed an app',
+  removeApp: 'Removed an app',
+  isAppInstalled: 'Checked if an app was installed',
+  activateApp: 'Activated an app',
+  terminateApp: 'Terminated an app',
+  queryAppState: 'Read the app state',
+  background: 'Sent the app to the background',
+
+  // Contexts
+  getContexts: 'Listed available contexts',
+  getCurrentContext: 'Read the current context',
+  setContext: 'Switched context',
+
+  // Web navigation
+  setUrl: 'Opened a URL',
+  getUrl: 'Read the current URL',
+  back: 'Navigated back',
+  forward: 'Navigated forward',
+  refresh: 'Refreshed the page',
+  title: 'Read the page title',
+
+  // Cookies
+  getCookie: 'Read a cookie',
+  getCookies: 'Read all cookies',
+  setCookie: 'Set a cookie',
+  deleteCookie: 'Deleted a cookie',
+  deleteCookies: 'Deleted all cookies',
+
+  // Alerts
+  getAlertText: 'Read an alert',
+  setAlertText: 'Typed into an alert',
+  postAcceptAlert: 'Accepted an alert',
+  postDismissAlert: 'Dismissed an alert',
+
+  // Keyboard and input methods
+  hideKeyboard: 'Hid the keyboard',
+  isKeyboardShown: 'Checked if the keyboard was shown',
+  activateIMEEngine: 'Activated an input method',
+  deactivateIMEEngine: 'Deactivated the input method',
+  getActiveIMEEngine: 'Read the active input method',
+  availableIMEEngines: 'Listed input methods',
+  isIMEActivated: 'Checked if an input method was active',
+
+  // Clipboard (driver-level, not declared by base-driver)
+  getClipboard: 'Read the clipboard',
+  setClipboard: 'Wrote to the clipboard',
+
+  // Files
+  pushFile: 'Pushed a file to the device',
+  pullFile: 'Pulled a file from the device',
+  pullFolder: 'Pulled a folder from the device',
+
+  // Logs
+  getLog: 'Read device logs',
+  getLogTypes: 'Listed log types',
+  getLogEvents: 'Read logged events',
+  logCustomEvent: 'Logged a custom event',
+  generateTestReport: 'Generated a test report',
+
+  // Scripts
+  execute: 'Ran a script command',
+  executeAsync: 'Ran an async script command',
+  executeCdp: 'Ran a Chrome DevTools command',
+
+  // Web authentication (virtual authenticators)
+  addVirtualAuthenticator: 'Added a virtual authenticator',
+  removeVirtualAuthenticator: 'Removed a virtual authenticator',
+  addAuthCredential: 'Added an auth credential',
+  getAuthCredential: 'Read auth credentials',
+  removeAuthCredential: 'Removed an auth credential',
+  removeAllAuthCredentials: 'Removed all auth credentials',
+  setUserAuthVerified: 'Set the user verification state',
+
+  // Federated sign-in (FedCM)
+  fedCMGetAccounts: 'Listed federated sign-in accounts',
+  fedCMSelectAccount: 'Selected a federated sign-in account',
+  fedCMGetDialogType: 'Read the federated sign-in dialog type',
+  fedCMGetTitle: 'Read the federated sign-in dialog title',
+  fedCMClickDialogButton: 'Clicked a federated sign-in dialog button',
+  fedCMCancelDialog: 'Canceled the federated sign-in dialog',
+  fedCMResetCooldown: 'Reset the federated sign-in cooldown',
+  fedCMSetDelayEnabled: 'Toggled the federated sign-in delay',
+
+  // Virtual sensors and pressure sources
+  createVirtualSensor: 'Created a virtual sensor',
+  updateVirtualSensorReading: 'Updated a virtual sensor reading',
+  getVirtualSensorInfo: 'Read virtual sensor info',
+  deleteVirtualSensor: 'Removed a virtual sensor',
+  createVirtualPressureSource: 'Created a virtual pressure source',
+  updateVirtualPressureSource: 'Updated a virtual pressure source',
+  deleteVirtualPressureSource: 'Removed a virtual pressure source',
+
+  // Privacy / experimental web platform
+  getGlobalPrivacyControl: 'Read the Global Privacy Control setting',
+  setGlobalPrivacyControl: 'Set the Global Privacy Control setting',
+  setStorageAccess: 'Set storage access',
+  setRPHRegistrationMode: 'Set the protocol handler registration mode',
+  setSPCTransactionMode: 'Set the payment transaction mode',
+
+  // Driver routes and compatibility commands
+  asyncScriptTimeout: 'Set the async script timeout',
+  closeApp: 'Closed the app',
+  disableConditionInducer: 'Disabled the condition inducer',
+  enableConditionInducer: 'Enabled the condition inducer',
+  fingerprint: 'Simulated a fingerprint',
+  getCurrentActivity: 'Read the current activity',
+  getCurrentPackage: 'Read the current package',
+  getDisplayDensity: 'Read the display density',
+  getLocation: 'Read an element location',
+  getLocationInView: 'Read an element location in view',
+  getPerformanceData: 'Read performance data',
+  getPerformanceDataTypes: 'Listed performance data types',
+  getScreenInfo: 'Read screen information',
+  getSize: 'Read an element size',
+  getStrings: 'Read app strings',
+  getSystemBars: 'Read system bar information',
+  getViewportRect: 'Read the viewport size',
+  getViewportScreenshot: 'Took a viewport screenshot',
+  getWindowSize: 'Read the window size',
+  gsmCall: 'Simulated a phone call',
+  gsmSignal: 'Changed the cellular signal',
+  gsmVoice: 'Changed the cellular voice state',
+  implicitWait: 'Set the element lookup timeout',
+  isLocationServicesEnabled: 'Checked if location services were enabled',
+  isLocked: 'Checked if the device was locked',
+  keyevent: 'Sent a key event',
+  keys: 'Sent keyboard input',
+  launchApp: 'Launched the app',
+  listConditionInducers: 'Listed condition inducers',
+  lock: 'Locked the device',
+  longPressKeyCode: 'Long-pressed a key',
+  networkSpeed: 'Changed the network speed',
+  openNotifications: 'Opened notifications',
+  powerAC: 'Changed the charging state',
+  powerCapacity: 'Changed the battery level',
+  pressKeyCode: 'Pressed a key',
+  replaceValue: 'Replaced an element value',
+  reset: 'Reset the app',
+  sendSMS: 'Simulated a text message',
+  sensorSet: 'Changed a sensor value',
+  setStylusHandwriting: 'Changed stylus handwriting mode',
+  setValueImmediate: 'Typed into an element immediately',
+  startActivity: 'Started an activity',
+  startAudioRecording: 'Started audio recording',
+  startRecordingScreen: 'Started screen recording',
+  stopAudioRecording: 'Stopped audio recording',
+  stopRecordingScreen: 'Stopped screen recording',
+  submit: 'Submitted an element',
+  toggleData: 'Toggled mobile data',
+  toggleEnrollTouchId: 'Changed Touch ID enrollment',
+  toggleFlightMode: 'Toggled airplane mode',
+  toggleLocationServices: 'Toggled location services',
+  toggleWiFi: 'Toggled Wi-Fi',
+  touchId: 'Simulated Touch ID',
+  unlock: 'Unlocked the device',
+
+  // Driver mobile commands
+  mobileAcceptAlert: 'Accepted an alert',
+  mobileActivateApp: 'Activated an app',
+  mobileBackgroundApp: 'Sent the app to the background',
+  mobileBluetooth: 'Changed Bluetooth state',
+  mobileBroadcast: 'Sent an Android broadcast',
+  mobileCalibrateWebToRealCoordinatesTranslation: 'Calibrated web coordinates',
+  mobileChangePermissions: 'Changed app permissions',
+  mobileClearApp: 'Cleared app data',
+  mobileClearKeychains: 'Cleared keychains',
+  mobileClickGesture: 'Performed a click gesture',
+  mobileConfigureLocalization: 'Changed device localization',
+  mobileDeepLink: 'Opened a deep link',
+  mobileDeleteFile: 'Deleted a device file',
+  mobileDeleteFolder: 'Deleted a device folder',
+  mobileDeviceidle: 'Changed device idle state',
+  mobileDisableVoiceOver: 'Disabled VoiceOver',
+  mobileDismissAlert: 'Dismissed an alert',
+  mobileDoubleClickGesture: 'Performed a double-click gesture',
+  mobileDoubleTap: 'Double-tapped the screen',
+  mobileDragFromToForDuration: 'Dragged between screen points',
+  mobileDragFromToWithVelocity: 'Dragged with a set velocity',
+  mobileDragGesture: 'Performed a drag gesture',
+  mobileEnableVoiceOver: 'Enabled VoiceOver',
+  mobileEnrollBiometric: 'Changed biometric enrollment',
+  mobileExecEmuConsoleCommand: 'Ran an emulator console command',
+  mobileExpectNotification: 'Waited for a notification',
+  mobileFingerprint: 'Simulated a fingerprint',
+  mobileFlingGesture: 'Performed a fling gesture',
+  mobileForcePress: 'Force-pressed the screen',
+  mobileGetActionHistory: 'Read scheduled action history',
+  mobileGetActiveAppInfo: 'Read active app information',
+  mobileGetAppearance: 'Read the device appearance',
+  mobileGetBatteryInfo: 'Read battery information',
+  mobileGetChromeCapabilities: 'Read Chrome capabilities',
+  mobileGetConnectivity: 'Read device connectivity',
+  mobileGetContentSize: 'Read scrollable content size',
+  mobileGetContexts: 'Listed available contexts',
+  mobileGetDeviceInfo: 'Read device information',
+  mobileGetDeviceTime: 'Read the device time',
+  mobileGetDeclaredOrientation: 'Read the declared device orientation',
+  mobileGetGeolocation: 'Read the device location',
+  mobileGetIncreaseContrast: 'Read the Increase Contrast setting',
+  mobileGetNotifications: 'Read notifications',
+  mobileGetPasteboard: 'Read the pasteboard',
+  mobileGetPerformanceData: 'Read app performance data',
+  mobileGetPermission: 'Read an app permission',
+  mobileGetPermissions: 'Read app permissions',
+  mobileGetSimulatedLocation: 'Read the simulated location',
+  mobileGetSource: 'Read the screen contents',
+  mobileGetUiMode: 'Read the Android UI mode',
+  mobileGetXctestScreenRecordingInfo: 'Read XCTest screen recording information',
+  mobileGsmCall: 'Simulated a phone call',
+  mobileGsmSignal: 'Changed the cellular signal',
+  mobileGsmVoice: 'Changed the cellular voice state',
+  mobileHandleAlert: 'Handled an alert',
+  mobileHideKeyboard: 'Hid the keyboard',
+  mobileInjectEmulatorCameraImage: 'Injected an emulator camera image',
+  mobileInstallApp: 'Installed an app',
+  mobileInstallCertificate: 'Installed a certificate',
+  mobileInstallMultipleApks: 'Installed multiple APKs',
+  mobileInstallXCTestBundle: 'Installed an XCTest bundle',
+  mobileIsAppInstalled: 'Checked if an app was installed',
+  mobileIsBiometricEnrolled: 'Checked biometric enrollment',
+  mobileIsMediaProjectionRecordingRunning: 'Checked media projection recording',
+  mobileIsVoiceOverEnabled: 'Checked if VoiceOver was enabled',
+  mobileKeys: 'Sent keyboard input',
+  mobileKillApp: 'Stopped an app',
+  mobileLaunchApp: 'Launched an app',
+  mobileListApps: 'Listed installed apps',
+  mobileListCertificates: 'Listed certificates',
+  mobileListDisplays: 'Listed displays',
+  mobileListSms: 'Listed text messages',
+  mobileListWindows: 'Listed app windows',
+  mobileListXCTestBundles: 'Listed XCTest bundles',
+  mobileLongClickGesture: 'Performed a long-click gesture',
+  mobileNetworkSpeed: 'Changed the network speed',
+  mobileNfc: 'Changed NFC state',
+  mobilePerformAccessibilityAudit: 'Ran an accessibility audit',
+  mobilePerformEditorAction: 'Performed a keyboard editor action',
+  mobilePerformHandGesture: 'Performed a hand gesture',
+  mobilePerformIndigoHidEvent: 'Performed an Indigo HID event',
+  mobilePerformIoHidEvent: 'Performed an IOHID event',
+  mobilePerformStatusBarCommand: 'Performed a status bar command',
+  mobilePinch: 'Pinched the screen',
+  mobilePinchCloseGesture: 'Performed a pinch-close gesture',
+  mobilePinchOpenGesture: 'Performed a pinch-open gesture',
+  mobilePowerAc: 'Changed the charging state',
+  mobilePowerCapacity: 'Changed the battery level',
+  mobilePressButton: 'Pressed a device button',
+  mobilePressKey: 'Pressed a key',
+  mobilePullFile: 'Pulled a file from the device',
+  mobilePullFolder: 'Pulled a folder from the device',
+  mobilePushFile: 'Pushed a file to the device',
+  mobilePushNotification: 'Sent a push notification',
+  mobileQueryAppState: 'Read the app state',
+  mobileRefreshGpsCache: 'Refreshed the GPS cache',
+  mobileRemoveApp: 'Removed an app',
+  mobileRemoveCertificate: 'Removed a certificate',
+  mobileReplaceElementValue: 'Replaced an element value',
+  mobileResetAccessibilityCache: 'Reset the accessibility cache',
+  mobileResetGeolocation: 'Reset the device location',
+  mobileResetLocationService: 'Reset location services',
+  mobileResetPermission: 'Reset an app permission',
+  mobileResetSimulatedLocation: 'Reset the simulated location',
+  mobileRotateDigitalCrown: 'Rotated the Digital Crown',
+  mobileRotateElement: 'Rotated an element',
+  mobileRunXCTest: 'Ran an XCTest bundle',
+  mobileScheduleAction: 'Scheduled a device action',
+  mobileScreenshots: 'Took display screenshots',
+  mobileScroll: 'Scrolled the screen',
+  mobileScrollBackTo: 'Scrolled back to an element',
+  mobileScrollGesture: 'Performed a scroll gesture',
+  mobileScrollToElement: 'Scrolled to an element',
+  mobileSelectPickerWheelValue: 'Changed a picker wheel value',
+  mobileSendBiometricMatch: 'Simulated biometric authentication',
+  mobileSendMemoryWarning: 'Sent a memory warning',
+  mobileSendSms: 'Simulated a text message',
+  mobileSendTrimMemory: 'Sent an Android memory trim event',
+  mobileSetAppearance: 'Changed the device appearance',
+  mobileSetConnectivity: 'Changed device connectivity',
+  mobileSetContentSize: 'Changed the content size',
+  mobileSetGeolocation: 'Set the device location',
+  mobileSetIncreaseContrast: 'Changed the Increase Contrast setting',
+  mobileSetPasteboard: 'Wrote to the pasteboard',
+  mobileSetPermissions: 'Set app permissions',
+  mobileSetSimulatedLocation: 'Set a simulated location',
+  mobileSetUiMode: 'Changed the Android UI mode',
+  mobileShake: 'Shook the device',
+  mobileShell: 'Ran an Android shell command',
+  mobileSimctl: 'Ran a simctl command',
+  mobileSiriCommand: 'Sent a Siri command',
+  mobileStartActivity: 'Started an activity',
+  mobileStartLogsBroadcast: 'Started log streaming',
+  mobileStartMediaProjectionRecording: 'Started media projection recording',
+  mobileStartNetworkMonitor: 'Started network monitoring',
+  mobileStartPerfRecord: 'Started performance recording',
+  mobileStartScreenRecording: 'Started screen recording',
+  mobileStartScreenStreaming: 'Started screen streaming',
+  mobileStartService: 'Started a service',
+  mobileStartSystemMonitor: 'Started system monitoring',
+  mobileStartXctestScreenRecording: 'Started XCTest screen recording',
+  mobileStopLogsBroadcast: 'Stopped log streaming',
+  mobileStopMediaProjectionRecording: 'Stopped media projection recording',
+  mobileStopNetworkMonitor: 'Stopped network monitoring',
+  mobileStopPerfRecord: 'Stopped performance recording',
+  mobileStopScreenRecording: 'Stopped screen recording',
+  mobileStopScreenStreaming: 'Stopped screen streaming',
+  mobileStopService: 'Stopped a service',
+  mobileStopSystemMonitor: 'Stopped system monitoring',
+  mobileStopXctestScreenRecording: 'Stopped XCTest screen recording',
+  mobileSwipe: 'Swiped the screen',
+  mobileSwipeGesture: 'Performed a swipe gesture',
+  mobileTap: 'Tapped the screen',
+  mobileTapWithNumberOfTaps: 'Tapped the screen multiple times',
+  mobileTerminateApp: 'Terminated an app',
+  mobileTouchAndHold: 'Touched and held the screen',
+  mobileTwoFingerTap: 'Tapped with two fingers',
+  mobileType: 'Typed text',
+  mobileUnlock: 'Unlocked the device',
+  mobileUnscheduleAction: 'Canceled a scheduled action',
+  mobileUpdateSafariPreferences: 'Updated Safari preferences',
+  mobileViewPortRect: 'Read the viewport size',
+  mobileViewportScreenshot: 'Took a viewport screenshot',
+  mobileVoiceOverCurrentSpeech: 'Read current VoiceOver speech',
+  mobileVoiceOverMove: 'Moved the VoiceOver cursor',
+};
+
+/**
+ * Translate a raw Appium command name into a short, human-readable summary.
+ *
+ * If a command has no curated summary, the raw command name is returned
+ * unchanged — we intentionally do not guess a phrasing.
+ */
+export function humanizeAppiumCommand(command: string): string {
+  return Object.hasOwn(APPIUM_COMMAND_SUMMARIES, command)
+    ? (APPIUM_COMMAND_SUMMARIES as Record<string, string>)[command]
+    : command;
+}
@@ -0,0 +1,401 @@
+// AUTO-GENERATED. Do not edit by hand.
+// Run `yarn workspace @expo/build-tools generate-appium-commands` to refresh this
+// list from Appium, XCUITest, and UiAutomator2 (installed on demand by the generator).
+export type BaseDriverAppiumCommand =
+  | 'activateApp'
+  | 'activateIMEEngine'
+  | 'active'
+  | 'addAuthCredential'
+  | 'addVirtualAuthenticator'
+  | 'availableIMEEngines'
+  | 'back'
+  | 'clear'
+  | 'clearDevicePosture'
+  | 'click'
+  | 'closeWindow'
+  | 'createNewWindow'
+  | 'createSession'
+  | 'createVirtualPressureSource'
+  | 'createVirtualSensor'
+  | 'deactivateIMEEngine'
+  | 'deleteCookie'
+  | 'deleteCookies'
+  | 'deleteSession'
+  | 'deleteVirtualPressureSource'
+  | 'deleteVirtualSensor'
+  | 'elementDisplayed'
+  | 'elementEnabled'
+  | 'elementSelected'
+  | 'elementShadowRoot'
+  | 'execute'
+  | 'executeAsync'
+  | 'executeCdp'
+  | 'fedCMCancelDialog'
+  | 'fedCMClickDialogButton'
+  | 'fedCMGetAccounts'
+  | 'fedCMGetDialogType'
+  | 'fedCMGetTitle'
+  | 'fedCMResetCooldown'
+  | 'fedCMSelectAccount'
+  | 'fedCMSetDelayEnabled'
+  | 'findElement'
+  | 'findElementFromElement'
+  | 'findElementFromShadowRoot'
+  | 'findElements'
+  | 'findElementsFromElement'
+  | 'findElementsFromShadowRoot'
+  | 'forward'
+  | 'fullScreenWindow'
+  | 'generateTestReport'
+  | 'getActiveIMEEngine'
+  | 'getAlertText'
+  | 'getAppiumSessionCapabilities'
+  | 'getAppiumSessions'
+  | 'getAttribute'
+  | 'getAuthCredential'
+  | 'getComputedLabel'
+  | 'getComputedRole'
+  | 'getContexts'
+  | 'getCookie'
+  | 'getCookies'
+  | 'getCssProperty'
+  | 'getCurrentContext'
+  | 'getDeviceTime'
+  | 'getElementRect'
+  | 'getElementScreenshot'
+  | 'getGeoLocation'
+  | 'getGlobalPrivacyControl'
+  | 'getLog'
+  | 'getLogEvents'
+  | 'getLogTypes'
+  | 'getName'
+  | 'getNetworkConnection'
+  | 'getOrientation'
+  | 'getPageSource'
+  | 'getProperty'
+  | 'getRotation'
+  | 'getScreenshot'
+  | 'getSession'
+  | 'getSettings'
+  | 'getStatus'
+  | 'getText'
+  | 'getTimeouts'
+  | 'getUrl'
+  | 'getVirtualSensorInfo'
+  | 'getWindowHandle'
+  | 'getWindowHandles'
+  | 'getWindowRect'
+  | 'hideKeyboard'
+  | 'installApp'
+  | 'isAppInstalled'
+  | 'isIMEActivated'
+  | 'isKeyboardShown'
+  | 'listCommands'
+  | 'listExtensions'
+  | 'logCustomEvent'
+  | 'maximizeWindow'
+  | 'minimizeWindow'
+  | 'performActions'
+  | 'postAcceptAlert'
+  | 'postDismissAlert'
+  | 'printPage'
+  | 'pullFile'
+  | 'pullFolder'
+  | 'pushFile'
+  | 'queryAppState'
+  | 'receiveAsyncResponse'
+  | 'refresh'
+  | 'releaseActions'
+  | 'removeAllAuthCredentials'
+  | 'removeApp'
+  | 'removeAuthCredential'
+  | 'removeVirtualAuthenticator'
+  | 'setAlertText'
+  | 'setContext'
+  | 'setCookie'
+  | 'setDevicePosture'
+  | 'setFrame'
+  | 'setGeoLocation'
+  | 'setGlobalPrivacyControl'
+  | 'setNetworkConnection'
+  | 'setOrientation'
+  | 'setPermissions'
+  | 'setRPHRegistrationMode'
+  | 'setRotation'
+  | 'setSPCTransactionMode'
+  | 'setStorageAccess'
+  | 'setUrl'
+  | 'setUserAuthVerified'
+  | 'setValue'
+  | 'setWindow'
+  | 'setWindowRect'
+  | 'switchToParentFrame'
+  | 'terminateApp'
+  | 'timeouts'
+  | 'title'
+  | 'updateSettings'
+  | 'updateVirtualPressureSource'
+  | 'updateVirtualSensorReading';
+
+export type XCUITestAppiumCommand =
+  | 'asyncScriptTimeout'
+  | 'background'
+  | 'closeApp'
+  | 'disableConditionInducer'
+  | 'enableConditionInducer'
+  | 'getClipboard'
+  | 'getLocation'
+  | 'getLocationInView'
+  | 'getScreenInfo'
+  | 'getSize'
+  | 'getStrings'
+  | 'getViewportRect'
+  | 'getViewportScreenshot'
+  | 'getWindowSize'
+  | 'implicitWait'
+  | 'isLocked'
+  | 'keys'
+  | 'launchApp'
+  | 'listConditionInducers'
+  | 'lock'
+  | 'mobileActivateApp'
+  | 'mobileCalibrateWebToRealCoordinatesTranslation'
+  | 'mobileClearApp'
+  | 'mobileClearKeychains'
+  | 'mobileConfigureLocalization'
+  | 'mobileDeepLink'
+  | 'mobileDeleteFile'
+  | 'mobileDeleteFolder'
+  | 'mobileDisableVoiceOver'
+  | 'mobileDoubleTap'
+  | 'mobileDragFromToForDuration'
+  | 'mobileDragFromToWithVelocity'
+  | 'mobileEnableVoiceOver'
+  | 'mobileEnrollBiometric'
+  | 'mobileExpectNotification'
+  | 'mobileForcePress'
+  | 'mobileGetActiveAppInfo'
+  | 'mobileGetAppearance'
+  | 'mobileGetBatteryInfo'
+  | 'mobileGetContentSize'
+  | 'mobileGetContexts'
+  | 'mobileGetDeviceInfo'
+  | 'mobileGetDeviceTime'
+  | 'mobileGetIncreaseContrast'
+  | 'mobileGetPasteboard'
+  | 'mobileGetPermission'
+  | 'mobileGetSimulatedLocation'
+  | 'mobileGetSource'
+  | 'mobileGetXctestScreenRecordingInfo'
+  | 'mobileHandleAlert'
+  | 'mobileHideKeyboard'
+  | 'mobileInstallApp'
+  | 'mobileInstallCertificate'
+  | 'mobileInstallXCTestBundle'
+  | 'mobileIsAppInstalled'
+  | 'mobileIsBiometricEnrolled'
+  | 'mobileIsVoiceOverEnabled'
+  | 'mobileKeys'
+  | 'mobileKillApp'
+  | 'mobileLaunchApp'
+  | 'mobileListApps'
+  | 'mobileListCertificates'
+  | 'mobileListXCTestBundles'
+  | 'mobilePerformAccessibilityAudit'
+  | 'mobilePerformHandGesture'
+  | 'mobilePerformIndigoHidEvent'
+  | 'mobilePerformIoHidEvent'
+  | 'mobilePinch'
+  | 'mobilePressButton'
+  | 'mobilePullFile'
+  | 'mobilePullFolder'
+  | 'mobilePushFile'
+  | 'mobilePushNotification'
+  | 'mobileQueryAppState'
+  | 'mobileRemoveApp'
+  | 'mobileRemoveCertificate'
+  | 'mobileResetLocationService'
+  | 'mobileResetPermission'
+  | 'mobileResetSimulatedLocation'
+  | 'mobileRotateDigitalCrown'
+  | 'mobileRotateElement'
+  | 'mobileRunXCTest'
+  | 'mobileScroll'
+  | 'mobileScrollToElement'
+  | 'mobileSelectPickerWheelValue'
+  | 'mobileSendBiometricMatch'
+  | 'mobileSendMemoryWarning'
+  | 'mobileSetAppearance'
+  | 'mobileSetContentSize'
+  | 'mobileSetIncreaseContrast'
+  | 'mobileSetPasteboard'
+  | 'mobileSetPermissions'
+  | 'mobileSetSimulatedLocation'
+  | 'mobileShake'
+  | 'mobileSimctl'
+  | 'mobileSiriCommand'
+  | 'mobileStartLogsBroadcast'
+  | 'mobileStartNetworkMonitor'
+  | 'mobileStartPerfRecord'
+  | 'mobileStartScreenRecording'
+  | 'mobileStartSystemMonitor'
+  | 'mobileStartXctestScreenRecording'
+  | 'mobileStopLogsBroadcast'
+  | 'mobileStopNetworkMonitor'
+  | 'mobileStopPerfRecord'
+  | 'mobileStopScreenRecording'
+  | 'mobileStopSystemMonitor'
+  | 'mobileStopXctestScreenRecording'
+  | 'mobileSwipe'
+  | 'mobileTap'
+  | 'mobileTapWithNumberOfTaps'
+  | 'mobileTerminateApp'
+  | 'mobileTouchAndHold'
+  | 'mobileTwoFingerTap'
+  | 'mobileUpdateSafariPreferences'
+  | 'mobileVoiceOverCurrentSpeech'
+  | 'mobileVoiceOverMove'
+  | 'reset'
+  | 'setClipboard'
+  | 'setValueImmediate'
+  | 'startAudioRecording'
+  | 'startRecordingScreen'
+  | 'stopAudioRecording'
+  | 'stopRecordingScreen'
+  | 'submit'
+  | 'toggleEnrollTouchId'
+  | 'touchId'
+  | 'unlock';
+
+export type UiAutomator2AppiumCommand =
+  | 'background'
+  | 'fingerprint'
+  | 'getClipboard'
+  | 'getCurrentActivity'
+  | 'getCurrentPackage'
+  | 'getDisplayDensity'
+  | 'getLocation'
+  | 'getLocationInView'
+  | 'getPerformanceData'
+  | 'getPerformanceDataTypes'
+  | 'getSize'
+  | 'getStrings'
+  | 'getSystemBars'
+  | 'getWindowSize'
+  | 'gsmCall'
+  | 'gsmSignal'
+  | 'gsmVoice'
+  | 'implicitWait'
+  | 'isLocationServicesEnabled'
+  | 'isLocked'
+  | 'keyevent'
+  | 'keys'
+  | 'lock'
+  | 'longPressKeyCode'
+  | 'mobileAcceptAlert'
+  | 'mobileBackgroundApp'
+  | 'mobileBluetooth'
+  | 'mobileBroadcast'
+  | 'mobileChangePermissions'
+  | 'mobileClearApp'
+  | 'mobileClickGesture'
+  | 'mobileDeepLink'
+  | 'mobileDeleteFile'
+  | 'mobileDeviceidle'
+  | 'mobileDismissAlert'
+  | 'mobileDoubleClickGesture'
+  | 'mobileDragGesture'
+  | 'mobileExecEmuConsoleCommand'
+  | 'mobileFingerprint'
+  | 'mobileFlingGesture'
+  | 'mobileGetActionHistory'
+  | 'mobileGetBatteryInfo'
+  | 'mobileGetChromeCapabilities'
+  | 'mobileGetConnectivity'
+  | 'mobileGetContexts'
+  | 'mobileGetDeclaredOrientation'
+  | 'mobileGetDeviceInfo'
+  | 'mobileGetDeviceTime'
+  | 'mobileGetGeolocation'
+  | 'mobileGetNotifications'
+  | 'mobileGetPerformanceData'
+  | 'mobileGetPermissions'
+  | 'mobileGetUiMode'
+  | 'mobileGsmCall'
+  | 'mobileGsmSignal'
+  | 'mobileGsmVoice'
+  | 'mobileInjectEmulatorCameraImage'
+  | 'mobileInstallApp'
+  | 'mobileInstallMultipleApks'
+  | 'mobileIsAppInstalled'
+  | 'mobileIsMediaProjectionRecordingRunning'
+  | 'mobileListApps'
+  | 'mobileListDisplays'
+  | 'mobileListSms'
+  | 'mobileListWindows'
+  | 'mobileLongClickGesture'
+  | 'mobileNetworkSpeed'
+  | 'mobileNfc'
+  | 'mobilePerformEditorAction'
+  | 'mobilePerformStatusBarCommand'
+  | 'mobilePinchCloseGesture'
+  | 'mobilePinchOpenGesture'
+  | 'mobilePowerAc'
+  | 'mobilePowerCapacity'
+  | 'mobilePressKey'
+  | 'mobileRefreshGpsCache'
+  | 'mobileRemoveApp'
+  | 'mobileReplaceElementValue'
+  | 'mobileResetAccessibilityCache'
+  | 'mobileResetGeolocation'
+  | 'mobileScheduleAction'
+  | 'mobileScreenshots'
+  | 'mobileScroll'
+  | 'mobileScrollBackTo'
+  | 'mobileScrollGesture'
+  | 'mobileSendSms'
+  | 'mobileSendTrimMemory'
+  | 'mobileSetConnectivity'
+  | 'mobileSetGeolocation'
+  | 'mobileSetUiMode'
+  | 'mobileShell'
+  | 'mobileStartActivity'
+  | 'mobileStartLogsBroadcast'
+  | 'mobileStartMediaProjectionRecording'
+  | 'mobileStartScreenStreaming'
+  | 'mobileStartService'
+  | 'mobileStopLogsBroadcast'
+  | 'mobileStopMediaProjectionRecording'
+  | 'mobileStopScreenStreaming'
+  | 'mobileStopService'
+  | 'mobileSwipeGesture'
+  | 'mobileTerminateApp'
+  | 'mobileType'
+  | 'mobileUnlock'
+  | 'mobileUnscheduleAction'
+  | 'mobileViewPortRect'
+  | 'mobileViewportScreenshot'
+  | 'networkSpeed'
+  | 'openNotifications'
+  | 'powerAC'
+  | 'powerCapacity'
+  | 'pressKeyCode'
+  | 'replaceValue'
+  | 'sendSMS'
+  | 'sensorSet'
+  | 'setClipboard'
+  | 'setStylusHandwriting'
+  | 'setValueImmediate'
+  | 'startActivity'
+  | 'startRecordingScreen'
+  | 'stopRecordingScreen'
+  | 'toggleData'
+  | 'toggleFlightMode'
+  | 'toggleLocationServices'
+  | 'toggleWiFi'
+  | 'unlock';
+
+export type AppiumCommand =
+  | BaseDriverAppiumCommand
+  | XCUITestAppiumCommand
+  | UiAutomator2AppiumCommand;
@@ -7,6 +7,7 @@ import { z } from 'zod';

 import { type CustomBuildContext } from '../../customBuildContext';
 import { turtleFetch } from '../../utils/turtleFetch';
+import { humanizeAppiumCommand } from './appiumCommandSummary';
 import {
  type DeviceRunSessionEventCollection,
  type DeviceRunSessionEventSource,
@@ -146,7 +147,7 @@ function createAppiumEventSource(eventFile: string): DeviceRunSessionEventSource
          type: 'operation.completed',
          operationId,
          durationMs: Math.max(0, command.endTime - command.startTime),
-          summary: command.cmd,
+          summary: humanizeAppiumCommand(command.cmd),
          data: {
            command: command.cmd,
            appiumSessionId: command.appiumSessionId,
@@ -18,11 +18,11 @@ const ARGENT_ARTIFACT_UPLOAD_POLL_INTERVAL_MS = 5_000;
 const ARGENT_ARTIFACT_UPLOAD_CLEANUP_TIMEOUT_MS = 30_000;
 const ARGENT_ARTIFACT_FETCH_TIMEOUT_MS = 10_000;

-// Kinds the EAS dashboard groups device run session artifacts by. Only media types the dashboard
-// renders specially are mapped; anything else stays unclassified and lands in its "Other" group.
-// Note that these kinds only affect grouping and labelling. The dashboard gates its inline video
-// player on the `__eas_screen_recording` metadata flag, which Argent artifacts deliberately do not
-// set, so a `screen-recording` kind here does not add a player to the session page.
+// Fallback kinds for Argent versions that do not include a semantic artifact kind. Only media types
+// the EAS dashboard renders specially can be inferred safely. Note that these kinds only affect
+// grouping and labelling. The dashboard gates its inline video player on the
+// `__eas_screen_recording` metadata flag, which Argent artifacts deliberately do not set, so a
+// `screen-recording` kind here does not add a player to the session page.
 const ARGENT_ARTIFACT_KIND_BY_MIME_TYPE = new Map<string, string>([
  ['image/png', 'screenshot'],
  ['image/jpeg', 'screenshot'],
@@ -32,6 +32,9 @@ const ARGENT_ARTIFACT_KIND_BY_MIME_TYPE = new Map<string, string>([

 const ArgentArtifactSchema = z.object({
  id: z.string(),
+  // Optional for compatibility with older Argent tool servers. Keep this open to new kinds so a
+  // newer Argent version can add a category without requiring an EAS worker release first.
+  kind: z.string().optional(),
  filename: z.string(),
  mimeType: z.string(),
  isDirectory: z.boolean().optional(),
@@ -43,8 +46,12 @@ const ArgentArtifactsListResponseSchema = z.object({
 type ArgentArtifact = z.infer<typeof ArgentArtifactSchema>;

 function getArgentArtifactKind(artifact: ArgentArtifact): string | undefined {
+  if (artifact.kind) {
+    return artifact.kind;
+  }
  // Directories are repackaged as a tarball before upload, so the reported media type describes the
-  // contents rather than the file we actually store.
+  // contents rather than the file we actually store. A semantic kind above remains valid because it
+  // describes what the artifact represents, not its transport format.
  if (artifact.isDirectory) {
    return undefined;
  }
@@ -9,6 +9,7 @@ import path from 'path';
 import { z } from 'zod';

 import { Sentry } from '../../../sentry';
+import { getProxiedDownloadUrl } from '../../../utils/download';

 const DEFAULT_XCLOGPARSER_VERSION = 'v0.2.47';
 const XCLOGPARSER_DOWNLOAD_URL = 'https://storage.googleapis.com/turtle-v2/xclogparser';
@@ -294,24 +295,6 @@ function getXclogparserZipName(version: string): string {
  return `XCLogParser-macOS-x86-64-arm64-${version}.zip`;
 }

-function getProxiedDownloadUrl({
-  directUrl,
-  proxyBaseUrl,
-}: {
-  directUrl: string;
-  proxyBaseUrl?: string;
-}): string | null {
-  if (!proxyBaseUrl) {
-    return null;
-  }
-
-  const parsedUrl = new URL(directUrl);
-  return directUrl.replace(
-    `${parsedUrl.protocol}//${parsedUrl.host}`,
-    `${proxyBaseUrl}/${parsedUrl.host}`
-  );
-}
-
 export function isCompileStep(step: Partial<XcactivitylogStep>): boolean {
  const detailStepType = step.detailStepType ?? '';
  const signature = step.signature ?? '';
@@ -19,11 +19,11 @@ import { sleepAsync } from '../../utils/retry';
 import { turtleFetch } from '../../utils/turtleFetch';

 const XCODE_DEVELOPER_DIR = '/Applications/Xcode.app/Contents/Developer';
-const SERVE_SIM_PACKAGE_SPEC = '@expo/serve-sim@latest';
+const SERVE_SIM_PACKAGE_NAME = '@expo/serve-sim';
 const SERVE_SIM_HOST = '127.0.0.1';
 const SERVE_SIM_MAX_DIMENSION = '1280';
 const SERVE_SIM_MJPEG_QUALITY = '0.55';
-const SERVE_SIM_VIDEO_BITRATE = '3000000';
+const SERVE_SIM_VIDEO_BITRATE = '6000000';
 const SERVE_SIM_VIDEO_FPS = '60';

 const START_DEVICE_RUN_SESSION_MUTATION = graphql(`
@@ -596,18 +596,24 @@ export function metricsCorsOriginToServeSimArgs(env: BuildStepEnv): string[] {
  return args;
 }

+function createServeSimPackageSpec(packageVersion: string | undefined): string {
+  return `${SERVE_SIM_PACKAGE_NAME}@${packageVersion ?? 'latest'}`;
+}
+
 export function createServeSimArgs({
  port,
  turnArgs = [],
  metricsCorsArgs = [],
+  packageVersion,
 }: {
  port: number;
  turnArgs?: string[];
  metricsCorsArgs?: string[];
+  packageVersion?: string;
 }): string[] {
  return [
    '--yes',
-    SERVE_SIM_PACKAGE_SPEC,
+    createServeSimPackageSpec(packageVersion),
    '--port',
    String(port),
    '--host',
@@ -700,20 +706,24 @@ export async function startServeSimWithTunnelAsync(
    env,
    logger,
    timeoutMs,
+    packageVersion,
  }: {
    baseDomain: string;
    env: BuildStepEnv;
    logger: bunyan;
    timeoutMs: number;
+    packageVersion?: string;
  }
 ): Promise<ServeSimPreviewHandle> {
  const port = await findAvailablePortAsync();
-  logger.info(`Launching ${SERVE_SIM_PACKAGE_SPEC} on ${SERVE_SIM_HOST}:${port}.`);
+  logger.info(
+    `Launching ${createServeSimPackageSpec(packageVersion)} on ${SERVE_SIM_HOST}:${port}.`
+  );
  const turnArgs = await fetchServeSimTurnArgsAsync(ctx, { env, logger });
  const metricsCorsArgs = metricsCorsOriginToServeSimArgs(env);
  const serveSim = spawnDetached({
    command: 'npx',
-    args: createServeSimArgs({ port, turnArgs, metricsCorsArgs }),
+    args: createServeSimArgs({ port, turnArgs, metricsCorsArgs, packageVersion }),
    env,
  });

@@ -44,6 +44,32 @@ export namespace IosSimulatorUtils {
    };
  };

+  export type IosSimulatorRuntime = {
+    identifier: string;
+    isAvailable?: boolean;
+    version?: string;
+  };
+
+  type XcrunSimctlListRuntimesJsonOutput = {
+    runtimes: (Omit<IosSimulatorRuntime, 'identifier'> & { identifier?: string })[];
+  };
+
+  export async function getAvailableRuntimesAsync({
+    env,
+  }: {
+    env: NodeJS.ProcessEnv;
+  }): Promise<IosSimulatorRuntime[]> {
+    const { stdout } = await spawn('xcrun', ['simctl', 'list', 'runtimes', '--json'], { env });
+    const { runtimes } = JSON.parse(stdout) as XcrunSimctlListRuntimesJsonOutput;
+
+    return runtimes.flatMap(runtime =>
+      runtime.isAvailable !== false &&
+      runtime.identifier?.startsWith('com.apple.CoreSimulator.SimRuntime.iOS-')
+        ? [{ ...runtime, identifier: runtime.identifier }]
+        : []
+    );
+  }
+
  export async function getAvailableDevicesAsync({
    env,
    filter,
@@ -23,6 +23,41 @@ describe('IosSimulatorUtils', () => {
    mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);
  });

+  describe(IosSimulatorUtils.getAvailableRuntimesAsync, () => {
+    it('returns available iOS runtimes', async () => {
+      mockedSpawn.mockResolvedValue({
+        stdout: JSON.stringify({
+          runtimes: [
+            {
+              identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-18-3',
+              isAvailable: true,
+              version: '18.3.1',
+            },
+            {
+              identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-17-5',
+              isAvailable: false,
+              version: '17.5',
+            },
+          ],
+        }),
+        stderr: '',
+      } as any);
+
+      await expect(
+        IosSimulatorUtils.getAvailableRuntimesAsync({ env: process.env })
+      ).resolves.toEqual([
+        {
+          identifier: 'com.apple.CoreSimulator.SimRuntime.iOS-18-3',
+          isAvailable: true,
+          version: '18.3.1',
+        },
+      ]);
+      expect(mockedSpawn).toHaveBeenCalledWith('xcrun', ['simctl', 'list', 'runtimes', '--json'], {
+        env: process.env,
+      });
+    });
+  });
+
  describe(IosSimulatorUtils.getAvailableDevicesAsync, () => {
    it('adds a human-readable runtime display name', async () => {
      mockedSpawn.mockResolvedValue({
@@ -0,0 +1,18 @@
+import { Platform } from '@expo/eas-build-job';
+
+import { getCcacheKeyPrefix } from '../cacheKey';
+
+describe(getCcacheKeyPrefix, () => {
+  it('uses separate prefixes for iOS device and simulator builds', () => {
+    expect(getCcacheKeyPrefix({ platform: Platform.IOS, simulator: false })).toBe(
+      'ios-device-ccache-'
+    );
+    expect(getCcacheKeyPrefix({ platform: Platform.IOS, simulator: true })).toBe(
+      'ios-simulator-ccache-'
+    );
+  });
+
+  it('does not change the Android prefix', () => {
+    expect(getCcacheKeyPrefix({ platform: Platform.ANDROID })).toBe('android-ccache-');
+  });
+});
@@ -0,0 +1,27 @@
+import { getProxiedDownloadUrl } from '../download';
+
+describe(getProxiedDownloadUrl, () => {
+  it('returns null when no proxy base URL is set', () => {
+    expect(
+      getProxiedDownloadUrl({ directUrl: 'https://storage.googleapis.com/bucket/object' })
+    ).toBeNull();
+  });
+
+  it('rewrites the origin to the proxy base URL', () => {
+    expect(
+      getProxiedDownloadUrl({
+        directUrl: 'https://storage.googleapis.com/bucket/object',
+        proxyBaseUrl: 'https://cache.example.com',
+      })
+    ).toBe('https://cache.example.com/storage.googleapis.com/bucket/object');
+  });
+
+  it('normalizes a proxy base URL with a trailing slash', () => {
+    expect(
+      getProxiedDownloadUrl({
+        directUrl: 'https://storage.googleapis.com/bucket/object',
+        proxyBaseUrl: 'https://cache.example.com/',
+      })
+    ).toBe('https://cache.example.com/storage.googleapis.com/bucket/object');
+  });
+});
@@ -0,0 +1,17 @@
+import { formatSecondsForLog } from '../formatDuration';
+
+describe(formatSecondsForLog, () => {
+  it.each([
+    [0, '0 seconds'],
+    [1, '1 second'],
+    [45, '45 seconds'],
+    [60, '1 minute'],
+    [90, '1 minute 30 seconds'],
+    [120, '2 minutes'],
+    [3600, '1 hour'],
+    [3661, '1 hour 1 minute 1 second'],
+    [7200, '2 hours'],
+  ] as const)('formats %i as %s', (seconds, expected) => {
+    expect(formatSecondsForLog(seconds)).toBe(expected);
+  });
+});
@@ -0,0 +1,43 @@
+import { ChildProcess } from 'node:child_process';
+
+import { isChildProcessAlive } 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
+    );
+  });
+
+  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('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 dead once we have killed it', () => {
+    expect(isChildProcessAlive(child({ exitCode: null, signalCode: null, killed: true }))).toBe(
+      false
+    );
+  });
+});
@@ -0,0 +1,503 @@
+import { SshSettings, SystemError } from '@expo/eas-build-job';
+
+import { createMockLogger } from '../../__tests__/utils/logger';
+import { BuildContext } from '../../context';
+import { sleepAsync } from '../retry';
+import {
+  SshSessionHandle,
+  getSshIdleTimeoutSeconds,
+  getSshRelayServerUrl,
+  isSshEnabled,
+  startSshSessionAsync,
+  superviseSshSessionAsync,
+} from '../turtleSshSession';
+import { SshConnectionConfig, UptermHost, startUptermHostAsync } from '../upterm';
+
+jest.mock('../retry', () => ({
+  sleepAsync: jest.fn().mockResolvedValue(undefined),
+}));
+jest.mock('../upterm', () => ({
+  ...jest.requireActual('../upterm'),
+  startUptermHostAsync: jest.fn(),
+}));
+
+const mockedStartUptermHost = jest.mocked(startUptermHostAsync);
+
+function sshJob(idleTimeoutSeconds: number): { ssh: SshSettings } {
+  return { ssh: { idleTimeoutSeconds, relayServerUrl: 'wss://relay.expo.dev' } };
+}
+
+function superviseHandle(
+  overrides: Partial<SshSessionHandle> &
+    Pick<SshSessionHandle, 'getConnectedClientCountAsync' | 'ensureConnectedAsync'>
+): SshSessionHandle {
+  return {
+    stopAsync: async () => {},
+    ...overrides,
+  };
+}
+
+describe(isSshEnabled, () => {
+  it('is true when job.ssh is present', () => {
+    expect(isSshEnabled(sshJob(0))).toBe(true);
+  });
+
+  it('is false otherwise', () => {
+    expect(isSshEnabled({})).toBe(false);
+  });
+});
+
+describe(getSshIdleTimeoutSeconds, () => {
+  it('returns idleTimeoutSeconds from job.ssh', () => {
+    expect(getSshIdleTimeoutSeconds(sshJob(900))).toBe(900);
+    expect(getSshIdleTimeoutSeconds(sshJob(0))).toBe(0);
+    expect(getSshIdleTimeoutSeconds(sshJob(3600))).toBe(3600);
+  });
+
+  it('defaults to 0 when job.ssh is missing', () => {
+    expect(getSshIdleTimeoutSeconds({})).toBe(0);
+  });
+
+  it('throws when the value is not an integer in range', () => {
+    for (const idleTimeoutSeconds of [300.5, -1, 3601]) {
+      expect(() => getSshIdleTimeoutSeconds(sshJob(idleTimeoutSeconds))).toThrow(SystemError);
+    }
+  });
+});
+
+describe(getSshRelayServerUrl, () => {
+  it('returns the relay url from the job ssh settings', () => {
+    expect(getSshRelayServerUrl(sshJob(0))).toBe('wss://relay.expo.dev');
+  });
+
+  it('throws when the job carries no relay url', () => {
+    expect(() => getSshRelayServerUrl({})).toThrow(/no relay server URL/);
+  });
+});
+
+describe(startSshSessionAsync, () => {
+  const config1: SshConnectionConfig = {
+    type: 'upterm-v1',
+    host: 'relay.expo.dev',
+    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 } };
+  let mutation: jest.Mock;
+  let ctx: BuildContext;
+
+  function makeHost(overrides: Partial<UptermHost> = {}): UptermHost {
+    const host: UptermHost = {
+      connectionConfig: config1,
+      getConnectedClientCountAsync: jest.fn().mockResolvedValue(3),
+      isAlive: jest.fn().mockReturnValue(true),
+      redialAsync: jest.fn(async () => {
+        host.connectionConfig = config2;
+        return config2;
+      }),
+      stopAsync: jest.fn().mockResolvedValue(undefined),
+      ...overrides,
+    };
+    return host;
+  }
+
+  beforeEach(() => {
+    createOrUpdateResult = {
+      data: {
+        turtleSshSession: {
+          createOrUpdateTurtleSshSession: {
+            id: 'ts-1',
+            sessionSettings: { idleTimeoutSeconds: 900 },
+          },
+        },
+      },
+    };
+    mutation = jest.fn().mockReturnValue({ toPromise: async () => createOrUpdateResult });
+    ctx = {
+      logger: createMockLogger(),
+      graphqlClient: { mutation },
+    } as unknown as BuildContext;
+  });
+
+  it('creates or updates the session and returns a handle plus idle timeout that delegates to the host', async () => {
+    const host = makeHost();
+    mockedStartUptermHost.mockResolvedValue(host);
+
+    const { handle, idleTimeoutSeconds } = await startSshSessionAsync(ctx, {
+      target,
+      relayServerUrl: 'wss://relay.expo.dev',
+      idleTimeoutSeconds: 900,
+    });
+
+    expect(mutation).toHaveBeenCalledWith(expect.anything(), {
+      target: { type: 'JOB_RUN', id: 'jr-1' },
+      connectionConfig: { ...config1, reconnecting: false, type: 'UPTERM_V1' },
+      sessionSettings: { idleTimeoutSeconds: 900 },
+    });
+    expect(idleTimeoutSeconds).toBe(900);
+    await handle.getConnectedClientCountAsync();
+    expect(host.getConnectedClientCountAsync).toHaveBeenCalled();
+    await handle.stopAsync();
+    expect(host.stopAsync).toHaveBeenCalled();
+  });
+
+  it('reports a build target', async () => {
+    const host = makeHost();
+    mockedStartUptermHost.mockResolvedValue(host);
+
+    await startSshSessionAsync(ctx, {
+      target: { type: 'BUILD', id: 'b-1' },
+      relayServerUrl: 'wss://relay.expo.dev',
+      idleTimeoutSeconds: 900,
+    });
+
+    expect(mutation).toHaveBeenCalledWith(expect.anything(), {
+      target: { type: 'BUILD', id: 'b-1' },
+      connectionConfig: { ...config1, reconnecting: false, type: 'UPTERM_V1' },
+      sessionSettings: { idleTimeoutSeconds: 900 },
+    });
+  });
+
+  it('throws and tears down the dialed host when creating or updating the session fails', async () => {
+    const host = makeHost();
+    mockedStartUptermHost.mockResolvedValue(host);
+    createOrUpdateResult = { error: { message: 'boom' } };
+
+    await expect(
+      startSshSessionAsync(ctx, {
+        target,
+        relayServerUrl: 'wss://r',
+        idleTimeoutSeconds: 300,
+      })
+    ).rejects.toThrow('boom');
+    expect(host.stopAsync).toHaveBeenCalled();
+  });
+
+  it('still rethrows when teardown after a create/update failure also fails', async () => {
+    const host = makeHost({
+      stopAsync: jest.fn().mockRejectedValue(new Error('already gone')),
+    });
+    mockedStartUptermHost.mockResolvedValue(host);
+    createOrUpdateResult = { error: { message: 'boom' } };
+
+    await expect(
+      startSshSessionAsync(ctx, {
+        target,
+        relayServerUrl: 'wss://r',
+        idleTimeoutSeconds: 300,
+      })
+    ).rejects.toThrow('boom');
+    expect(host.stopAsync).toHaveBeenCalled();
+  });
+
+  it('throws "no data returned" when create or update succeeds without a payload', async () => {
+    const host = makeHost();
+    mockedStartUptermHost.mockResolvedValue(host);
+    createOrUpdateResult = {};
+
+    await expect(
+      startSshSessionAsync(ctx, {
+        target,
+        relayServerUrl: 'wss://r',
+        idleTimeoutSeconds: 300,
+      })
+    ).rejects.toThrow(/no data returned/);
+    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);
+
+    const { handle } = await startSshSessionAsync(ctx, {
+      target,
+      relayServerUrl: 'wss://r',
+      idleTimeoutSeconds: 300,
+    });
+    await handle.ensureConnectedAsync();
+
+    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(mutation).toHaveBeenLastCalledWith(expect.anything(), {
+      target: { type: 'JOB_RUN', id: 'jr-1' },
+      connectionConfig: { ...config2, reconnecting: false, type: 'UPTERM_V1' },
+      sessionSettings: { idleTimeoutSeconds: 300 },
+    });
+  });
+
+  it('continues redial when the reconnecting status update fails', async () => {
+    const host = makeHost({ isAlive: jest.fn().mockReturnValue(false) });
+    mockedStartUptermHost.mockResolvedValue(host);
+    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 () => createOrUpdateResult })
+      .mockReturnValueOnce({ toPromise: async () => ({ error: { message: 'flaky' } }) })
+      .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();
+
+    expect(host.redialAsync).toHaveBeenCalledTimes(1);
+    expect(mutation).toHaveBeenLastCalledWith(expect.anything(), {
+      target: { type: 'JOB_RUN', id: 'jr-1' },
+      connectionConfig: { ...config2, reconnecting: false, type: 'UPTERM_V1' },
+      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);
+  });
+});
+
+describe(superviseSshSessionAsync, () => {
+  const logger = createMockLogger();
+  const mockedSleep = jest.mocked(sleepAsync);
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockedSleep.mockResolvedValue(undefined);
+  });
+
+  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;
+        },
+      }),
+      idleTimeoutSeconds: 0,
+      hasJobFinished: () => false,
+      logger,
+    });
+    expect(polls).toBe(5);
+  });
+
+  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;
+        },
+      }),
+      idleTimeoutSeconds: 0,
+      hasJobFinished: () => true,
+      logger,
+    });
+    expect(polls).toBe(1);
+    expect(logger.info).toHaveBeenCalledWith(
+      'The job finished and no SSH client is connected. Closing the session.'
+    );
+  });
+
+  it('waits for a connected client to disconnect before closing with a 0 idle timeout', async () => {
+    const clientCounts = [1, 1, 0];
+    let polls = 0;
+    await superviseSshSessionAsync({
+      handle: superviseHandle({
+        ensureConnectedAsync: async () => {},
+        getConnectedClientCountAsync: async () => {
+          polls += 1;
+          return clientCounts.shift() ?? 0;
+        },
+      }),
+      idleTimeoutSeconds: 0,
+      hasJobFinished: () => true,
+      logger,
+    });
+    expect(polls).toBe(3);
+  });
+
+  it('starts the idle countdown when the job finishes, not when the session opens', async () => {
+    jest.useFakeTimers();
+    jest.setSystemTime(0);
+    try {
+      let jobHasFinished = false;
+      let polls = 0;
+      mockedSleep.mockImplementation(async () => {
+        jest.setSystemTime(Date.now() + 60_000);
+      });
+      await superviseSshSessionAsync({
+        handle: superviseHandle({
+          ensureConnectedAsync: async () => {},
+          getConnectedClientCountAsync: async () => {
+            polls += 1;
+            if (polls >= 5) {
+              jobHasFinished = true;
+            }
+            return 0;
+          },
+        }),
+        idleTimeoutSeconds: 300,
+        hasJobFinished: () => jobHasFinished,
+        logger,
+      });
+      // Nobody connects, so the 4 idle minutes spent during the job must not count towards the
+      // 5 minute timeout: it closes 5 minutes after the job finished, on the 10th poll.
+      expect(polls).toBe(10);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  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,
+      }),
+      idleTimeoutSeconds: 0,
+      hasJobFinished: () => true,
+      logger,
+    });
+    expect(logger.info).toHaveBeenCalledWith('SSH clients connected: 1');
+    expect(logger.info).toHaveBeenCalledWith('SSH clients connected: 2');
+    expect(logger.info).toHaveBeenCalledWith('SSH clients connected: 1');
+    expect(logger.info).toHaveBeenCalledWith('SSH clients connected: 0');
+  });
+
+  it('closes the session when the relay connection cannot be restored', async () => {
+    let clientCountCalls = 0;
+    await superviseSshSessionAsync({
+      handle: superviseHandle({
+        ensureConnectedAsync: async () => {
+          throw new SystemError('relay down');
+        },
+        getConnectedClientCountAsync: async () => {
+          clientCountCalls += 1;
+          return 1;
+        },
+      }),
+      idleTimeoutSeconds: 300,
+      hasJobFinished: () => false,
+      logger,
+    });
+    expect(clientCountCalls).toBe(0);
+  });
+
+  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;
+        },
+      }),
+      idleTimeoutSeconds: 0,
+      hasJobFinished: () => true,
+      logger,
+    });
+    expect(polls).toBeGreaterThan(3);
+  });
+
+  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.'
+          );
+        },
+      }),
+      idleTimeoutSeconds: 300,
+      hasJobFinished: () => false,
+      logger,
+    });
+    expect(polls).toBe(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.anything(),
+      'Could not read the SSH client count. Closing the session.'
+    );
+  });
+});
@@ -0,0 +1,466 @@
+import { SystemError } from '@expo/eas-build-job';
+import downloadFile from '@expo/downloader';
+import spawn from '@expo/turtle-spawn';
+import fs from 'node:fs/promises';
+
+import { createMockLogger } from '../../__tests__/utils/logger';
+import { BuildContext } from '../../context';
+import { sleepAsync } from '../retry';
+import {
+  connectionConfigFromUptermSession,
+  redactConnectionSecrets,
+  redactSpawnErrorForLog,
+  resolveUptermGcsObjectName,
+  startUptermHostAsync,
+} from '../upterm';
+
+jest.mock('@expo/turtle-spawn', () => ({ __esModule: true, default: jest.fn() }));
+jest.mock('@expo/downloader', () => ({ __esModule: true, default: jest.fn() }));
+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(),
+  },
+}));
+
+describe(resolveUptermGcsObjectName, () => {
+  it('maps worker platforms to GCS object names', () => {
+    expect(resolveUptermGcsObjectName('darwin', 'arm64')).toBe('upterm-darwin-arm64');
+    expect(resolveUptermGcsObjectName('linux', 'x64')).toBe('upterm-linux-amd64');
+  });
+
+  it('rejects unsupported platforms', () => {
+    expect(() => resolveUptermGcsObjectName('darwin', 'x64')).toThrow(/only available/);
+    expect(() => resolveUptermGcsObjectName('linux', 'arm64')).toThrow(/only available/);
+  });
+});
+
+describe(connectionConfigFromUptermSession, () => {
+  it('parses sessionId and host from session current fields', () => {
+    expect(
+      connectionConfigFromUptermSession({
+        sessionId: 'TOKENabc123',
+        host: 'ssh://relay.expo.dev:22',
+      })
+    ).toEqual({
+      type: 'upterm-v1',
+      host: 'relay.expo.dev',
+      secret: 'TOKENabc123',
+    });
+  });
+
+  it('accepts a bare hostname', () => {
+    expect(connectionConfigFromUptermSession({ sessionId: 'tok', host: 'relay.expo.dev' })).toEqual(
+      {
+        type: 'upterm-v1',
+        host: 'relay.expo.dev',
+        secret: 'tok',
+      }
+    );
+  });
+
+  it('keeps a non-default port so the CLI can pass it to ssh -p', () => {
+    expect(
+      connectionConfigFromUptermSession({
+        sessionId: 'tok',
+        host: 'ssh://relay.expo.dev:2222',
+      })
+    ).toEqual({
+      type: 'upterm-v1',
+      host: 'relay.expo.dev:2222',
+      secret: 'tok',
+    });
+  });
+
+  it('returns null when the host is not a parseable url', () => {
+    expect(connectionConfigFromUptermSession({ sessionId: 'tok', host: 'ssh://' })).toBeNull();
+    expect(connectionConfigFromUptermSession({ sessionId: 'tok', host: 'ssh://[' })).toBeNull();
+  });
+});
+
+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 control characters (incl. ESC) while keeping newlines', () => {
+    // ESC alone is enough to neutralize CSI; leftover printable "[31m" is harmless in logs.
+    expect(redactConnectionSecrets('ok\n\u001b[31mfail\u001b[0m\r\nbad\u0007')).toBe(
+      'ok\n[31mfail[0m\nbad'
+    );
+  });
+});
+
+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;
+
+  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 makeCtx(env: Record<string, string> = {}): BuildContext {
+    return {
+      logger: createMockLogger(),
+      env,
+    } as unknown as BuildContext;
+  }
+
+  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,
+    });
+    mockedSleep.mockResolvedValue(undefined);
+    mockedFs.mkdir.mockResolvedValue(undefined as never);
+    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;
+      }
+      if (Array.isArray(args) && args[0] === 'host') {
+        return hostProcess as never;
+      }
+      if (Array.isArray(args) && args[0] === 'session') {
+        return Promise.resolve({ stdout: sessionStdout, stderr: '' }) as never;
+      }
+      return Promise.resolve({ stdout: '', stderr: '' }) as never;
+    }) 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',
+      host: 'relay.expo.dev',
+      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' }) })
+    );
+  });
+
+  it('downloads from GCS into a fresh temp dir when upterm is not on PATH', async () => {
+    uptermOnPath = false;
+
+    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://relay.expo.dev' });
+
+    expect(host.connectionConfig.secret).toBe('TOKENx');
+    expect(mockedDownloadFile).toHaveBeenCalledWith(
+      expect.stringMatching(/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('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);
+
+    await expect(startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' })).rejects.toThrow(
+      /network down/
+    );
+  });
+
+  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/
+      );
+      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();
+
+    expect(process.kill).toHaveBeenCalledWith(-4242, 'SIGTERM');
+    expect(mockedFs.rm).toHaveBeenCalledWith('/tmp/eas-ssh-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');
+    });
+
+    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+    await host.stopAsync();
+
+    expect(hostProcess.child.kill).toHaveBeenCalled();
+  });
+
+  it('skips process.kill when the host process has no pid', async () => {
+    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+    hostProcess.child.pid = undefined as unknown as number;
+    await host.stopAsync();
+
+    expect(process.kill).not.toHaveBeenCalled();
+    expect(hostProcess.child.kill).not.toHaveBeenCalled();
+  });
+
+  it('redialAsync re-establishes the connection', async () => {
+    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+    const config = await host.redialAsync();
+
+    expect(config).toEqual({
+      type: 'upterm-v1',
+      host: 'relay.expo.dev',
+      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();
+        };
+      });
+    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;
+    });
+
+    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',
+      host: 'relay.expo.dev',
+      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 () => {
+      const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+      mockedFs.readdir.mockResolvedValue([] as never);
+      await expect(host.getConnectedClientCountAsync()).rejects.toThrow(/client count/i);
+    });
+
+    it('returns the client count reported by the admin socket', async () => {
+      const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+      sessionStdout = JSON.stringify({
+        sessionId: 'TOKENx',
+        host: 'relay.expo.dev',
+        clientCount: 4,
+      });
+      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('throws when the reported count is not a number (after retries)', async () => {
+      const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+      sessionStdout = JSON.stringify({
+        sessionId: 'TOKENx',
+        host: 'relay.expo.dev',
+        clientCount: 'nope',
+      });
+      await expect(host.getConnectedClientCountAsync()).rejects.toThrow(/client count/i);
+    });
+
+    it('throws when the socket dir cannot be read (after retries)', 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);
+    });
+  });
+});
@@ -7,17 +7,24 @@ import path from 'path';

 import { findPackagerRootDir } from './packageManager';

-const IOS_CACHE_KEY_PREFIX = 'ios-ccache-';
+const IOS_DEVICE_CACHE_KEY_PREFIX = 'ios-device-ccache-';
+const IOS_SIMULATOR_CACHE_KEY_PREFIX = 'ios-simulator-ccache-';
 const ANDROID_CACHE_KEY_PREFIX = 'android-ccache-';
 const PUBLIC_IOS_CACHE_KEY_PREFIX = 'public-ios-ccache-';
 const PUBLIC_ANDROID_CACHE_KEY_PREFIX = 'public-android-ccache-';
 const DARWIN_CACHE_PATH = 'Library/Caches/ccache';
 const LINUX_CACHE_PATH = '.cache/ccache';

-export const CACHE_KEY_PREFIX_BY_PLATFORM: Record<Platform, string> = {
-  [Platform.ANDROID]: ANDROID_CACHE_KEY_PREFIX,
-  [Platform.IOS]: IOS_CACHE_KEY_PREFIX,
-};
+export type CcacheBuildTarget =
+  | { platform: Platform.ANDROID }
+  | { platform: Platform.IOS; simulator: boolean };
+
+export function getCcacheKeyPrefix(target: CcacheBuildTarget): string {
+  if (target.platform === Platform.IOS) {
+    return target.simulator ? IOS_SIMULATOR_CACHE_KEY_PREFIX : IOS_DEVICE_CACHE_KEY_PREFIX;
+  }
+  return ANDROID_CACHE_KEY_PREFIX;
+}

 export const PUBLIC_CACHE_KEY_PREFIX_BY_PLATFORM: Record<Platform, string> = {
  [Platform.ANDROID]: PUBLIC_ANDROID_CACHE_KEY_PREFIX,
@@ -36,7 +43,7 @@ export function getCcachePath(env: Record<string, string | undefined>): string {

 export async function generateDefaultBuildCacheKeyAsync(
  workingDirectory: string,
-  platform: Platform
+  target: CcacheBuildTarget
 ): Promise<string> {
  // This will resolve which package manager and use the relevant lock file
  // The lock file hash is the key and ensures cache is fresh
@@ -45,7 +52,7 @@ export async function generateDefaultBuildCacheKeyAsync(
  const lockPath = path.join(packagerRunDir, manager.lockFile);

  try {
-    return `${CACHE_KEY_PREFIX_BY_PLATFORM[platform]}${hashFiles([lockPath])}`;
+    return `${getCcacheKeyPrefix(target)}${hashFiles([lockPath])}`;
  } catch (err: any) {
    throw new Error(`Failed to read lockfile for cache key generation: ${err.message}`);
  }
@@ -0,0 +1,17 @@
+export function getProxiedDownloadUrl({
+  directUrl,
+  proxyBaseUrl,
+}: {
+  directUrl: string;
+  proxyBaseUrl?: string;
+}): string | null {
+  if (!proxyBaseUrl) {
+    return null;
+  }
+
+  const parsedUrl = new URL(directUrl);
+  return directUrl.replace(
+    `${parsedUrl.protocol}//${parsedUrl.host}`,
+    `${proxyBaseUrl.replace(/\/$/, '')}/${parsedUrl.host}`
+  );
+}
@@ -0,0 +1,16 @@
+export function formatSecondsForLog(totalSeconds: number): string {
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  const parts: string[] = [];
+  if (hours > 0) {
+    parts.push(hours === 1 ? '1 hour' : `${hours} hours`);
+  }
+  if (minutes > 0) {
+    parts.push(minutes === 1 ? '1 minute' : `${minutes} minutes`);
+  }
+  if (seconds > 0 || parts.length === 0) {
+    parts.push(seconds === 1 ? '1 second' : `${seconds} seconds`);
+  }
+  return parts.join(' ');
+}
@@ -1,5 +1,26 @@
+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;
+}
+
+/**
+ * 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).
+ */
+export function killProcessGroup(child: ChildProcess): void {
+  if (child.pid == null) {
+    return;
+  }
+  try {
+    process.kill(-child.pid, 'SIGTERM');
+  } catch {
+    child.kill();
+  }
+}
+
 async function getChildrenPidsAsync(parentPids: number[]): Promise<number[]> {
  try {
    const result = await spawn('pgrep', ['-P', parentPids.join(',')], {
@@ -0,0 +1,250 @@
+import { Job, SshSettings, SystemError } from '@expo/eas-build-job';
+import { bunyan } from '@expo/logger';
+import { graphql } from 'gql.tada';
+
+import { formatSecondsForLog } from './formatDuration';
+import { sleepAsync } from './retry';
+import { SshConnectionConfig, 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;
+
+const CREATE_OR_UPDATE_TURTLE_SSH_SESSION_MUTATION = graphql(`
+  mutation CreateOrUpdateTurtleSshSession(
+    $target: TurtleSshTargetInput!
+    $connectionConfig: TurtleSshConnectionConfigInput!
+    $sessionSettings: TurtleSshSessionSettingsInput!
+  ) {
+    turtleSshSession {
+      createOrUpdateTurtleSshSession(
+        target: $target
+        connectionConfig: $connectionConfig
+        sessionSettings: $sessionSettings
+      ) {
+        id
+        sessionSettings {
+          idleTimeoutSeconds
+        }
+      }
+    }
+  }
+`);
+
+export type TurtleSshTarget = { type: 'BUILD' | 'JOB_RUN'; id: string };
+
+export function isSshEnabled(job: Pick<Job, 'ssh'>): boolean {
+  return job.ssh != null;
+}
+
+export function getSshIdleTimeoutSeconds(job: Pick<Job, 'ssh'>): number {
+  const idleTimeoutSeconds = job.ssh?.idleTimeoutSeconds ?? DEFAULT_SSH_IDLE_TIMEOUT_SECONDS;
+  if (
+    !Number.isInteger(idleTimeoutSeconds) ||
+    idleTimeoutSeconds < 0 ||
+    idleTimeoutSeconds > MAX_SSH_IDLE_TIMEOUT_SECONDS
+  ) {
+    throw new SystemError(
+      `SSH idle timeout must be an integer between 0 and ${MAX_SSH_IDLE_TIMEOUT_SECONDS} seconds, got ${idleTimeoutSeconds}.`,
+      { trackingCode: 'SSH_IDLE_TIMEOUT_INVALID' }
+    );
+  }
+  return idleTimeoutSeconds;
+}
+
+export function getSshRelayServerUrl(job: Pick<Job, 'ssh'>): string {
+  const relayServerUrl = job.ssh?.relayServerUrl;
+  if (!relayServerUrl) {
+    throw new SystemError('SSH is enabled but no relay server URL was configured on the job.', {
+      trackingCode: 'SSH_RELAY_SERVER_URL_MISSING',
+    });
+  }
+  return relayServerUrl;
+}
+
+export type SshSessionHandle = {
+  getConnectedClientCountAsync: () => Promise<number>;
+  ensureConnectedAsync: () => Promise<void>;
+  stopAsync: () => Promise<void>;
+};
+
+export type StartedSshSession = {
+  handle: SshSessionHandle;
+  idleTimeoutSeconds: number;
+};
+
+async function createOrUpdateSessionAsync(
+  ctx: BuildContext,
+  {
+    target,
+    connectionConfig,
+    idleTimeoutSeconds,
+  }: {
+    target: TurtleSshTarget;
+    connectionConfig: SshConnectionConfig & { reconnecting?: boolean };
+    idleTimeoutSeconds: number;
+  }
+): Promise<{ idleTimeoutSeconds: number }> {
+  const result = await ctx.graphqlClient
+    .mutation(CREATE_OR_UPDATE_TURTLE_SSH_SESSION_MUTATION, {
+      target,
+      connectionConfig: {
+        ...connectionConfig,
+        type: 'UPTERM_V1',
+      },
+      sessionSettings: { idleTimeoutSeconds },
+    })
+    .toPromise();
+  if (result.error || !result.data) {
+    throw new SystemError(
+      `Failed to create or update the SSH session: ${result.error?.message ?? 'no data returned'}`,
+      { cause: result.error }
+    );
+  }
+  const session = result.data.turtleSshSession.createOrUpdateTurtleSshSession;
+  return { idleTimeoutSeconds: session.sessionSettings.idleTimeoutSeconds };
+}
+
+export async function startSshSessionAsync(
+  ctx: BuildContext,
+  {
+    target,
+    relayServerUrl,
+    idleTimeoutSeconds: requestedIdleTimeoutSeconds,
+  }: {
+    target: TurtleSshTarget;
+  } & SshSettings
+): Promise<StartedSshSession> {
+  const logger = ctx.logger;
+  const host = await startUptermHostAsync(ctx, { relayServerUrl });
+  let idleTimeoutSeconds: number;
+  try {
+    ({ idleTimeoutSeconds } = await createOrUpdateSessionAsync(ctx, {
+      target,
+      connectionConfig: { ...host.connectionConfig, reconnecting: false },
+      idleTimeoutSeconds: requestedIdleTimeoutSeconds,
+    }));
+  } catch (err) {
+    await host.stopAsync().catch(() => {});
+    throw err;
+  }
+
+  const ensureConnectedAsync = async (): Promise<void> => {
+    if (host.isAlive()) {
+      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);
+        }
+      }
+    }
+    throw new SystemError(
+      `The SSH relay connection dropped and could not be restored after ${MAX_SSH_REDIALS} attempts.`
+    );
+  };
+
+  return {
+    handle: {
+      getConnectedClientCountAsync: () => host.getConnectedClientCountAsync(),
+      ensureConnectedAsync,
+      stopAsync: () => host.stopAsync(),
+    },
+    idleTimeoutSeconds,
+  };
+}
+
+export async function superviseSshSessionAsync({
+  handle,
+  idleTimeoutSeconds,
+  hasJobFinished,
+  logger,
+}: {
+  handle: SshSessionHandle;
+  idleTimeoutSeconds: number;
+  hasJobFinished: () => boolean;
+  logger: bunyan;
+}): Promise<void> {
+  const idleTimeoutMs = idleTimeoutSeconds * 1_000;
+  let idleSince: number | null = null;
+  let previousClientCount = 0;
+
+  for (;;) {
+    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();
+    } catch (err) {
+      logger.warn({ err }, 'Could not read the SSH client count. Closing the session.');
+      Sentry.capture(
+        'Could not read the SSH client count',
+        err instanceof Error ? err : undefined,
+        {
+          tags: { trackingCode: 'SSH_CLIENT_COUNT_UNREADABLE' },
+        }
+      );
+      return;
+    }
+    if (connectedClientCount !== previousClientCount) {
+      logger.info(`SSH clients connected: ${connectedClientCount}`);
+      previousClientCount = connectedClientCount;
+    }
+
+    const jobHasFinished = hasJobFinished();
+    if (connectedClientCount > 0 || !jobHasFinished) {
+      idleSince = null;
+    } else if (idleSince === null) {
+      idleSince = Date.now();
+    }
+
+    if (jobHasFinished && connectedClientCount === 0) {
+      if (idleTimeoutSeconds === 0) {
+        logger.info('The job finished and no SSH client is connected. Closing the session.');
+        return;
+      }
+      if (idleSince !== null && Date.now() - idleSince >= idleTimeoutMs) {
+        logger.info(
+          `No SSH client connected for ${formatSecondsForLog(idleTimeoutSeconds)} after the job finished. Closing the session.`
+        );
+        return;
+      }
+    }
+    await sleepAsync(CLIENT_COUNT_POLL_INTERVAL_MS);
+  }
+}
@@ -0,0 +1,318 @@
+import { Env, SystemError } from '@expo/eas-build-job';
+import downloadFile from '@expo/downloader';
+import spawn, { SpawnPromise, SpawnResult } from '@expo/turtle-spawn';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+
+import { isChildProcessAlive, killProcessGroup } from './processes';
+import { sleepAsync } from './retry';
+import { BuildContext } from '../context';
+
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g;
+
+export function resolveUptermGcsObjectName(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch
+): string {
+  if (platform === 'darwin' && arch === 'arm64') {
+    return 'upterm-darwin-arm64';
+  }
+  if (platform === 'linux' && arch === 'x64') {
+    return 'upterm-linux-amd64';
+  }
+  throw new SystemError(
+    `SSH upterm is only available on darwin/arm64 and linux/x64 (got ${platform}/${arch}).`
+  );
+}
+
+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;
+const DEFAULT_SSH_PORT = '22';
+
+export type SshConnectionConfig = {
+  type: 'upterm-v1';
+  host: string;
+  secret: string;
+};
+
+export type UptermHost = {
+  connectionConfig: SshConnectionConfig;
+  getConnectedClientCountAsync: () => Promise<number>;
+  isAlive: () => boolean;
+  redialAsync: () => Promise<SshConnectionConfig>;
+  stopAsync: () => Promise<void>;
+};
+
+const UptermSessionJsonZ = z.object({
+  sessionId: z.string().min(1),
+  host: z.string().min(1),
+  clientCount: z.number().optional(),
+});
+type UptermSessionJson = z.infer<typeof UptermSessionJsonZ>;
+
+export function connectionConfigFromUptermSession(
+  parsed: Pick<UptermSessionJson, 'sessionId' | 'host'>
+): SshConnectionConfig | null {
+  let host = parsed.host;
+  if (host.includes('://')) {
+    let url: URL;
+    try {
+      url = new URL(host);
+    } catch {
+      return null;
+    }
+    host = url.port && url.port !== DEFAULT_SSH_PORT ? `${url.hostname}:${url.port}` : url.hostname;
+  }
+  if (!host) {
+    return null;
+  }
+  return { type: 'upterm-v1', host, secret: parsed.sessionId };
+}
+
+/**
+ * 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.
+ */
+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>');
+  }
+  return redacted.replace(/([a-z][a-z0-9+.-]*:\/\/)[^@\s/]+@/gi, '$1<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): Promise<string> {
+  try {
+    await spawn('upterm', ['version'], { stdio: 'pipe', env });
+    return 'upterm';
+  } catch {}
+
+  const objectName = resolveUptermGcsObjectName();
+  const downloadDir = await fs.mkdtemp(path.join(os.tmpdir(), 'eas-upterm-'));
+  const uptermPath = path.join(downloadDir, objectName);
+  const url = `${UPTERM_GCS_BASE_URL}/${objectName}`;
+  try {
+    await downloadFile(url, uptermPath, { retry: 3, timeout: UPTERM_DOWNLOAD_TIMEOUT_MS });
+    await fs.chmod(uptermPath, 0o755);
+  } 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 ${url}. ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    );
+  }
+  return uptermPath;
+}
+
+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> {
+  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;
+  } catch {
+    return null;
+  }
+}
+
+async function waitForConnectionConfigAsync(
+  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) {
+        const connectionConfig = connectionConfigFromUptermSession(session);
+        if (connectionConfig) {
+          return connectionConfig;
+        }
+      }
+    }
+    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);
+  }
+}
+
+export async function startUptermHostAsync(
+  ctx: BuildContext,
+  { relayServerUrl }: { relayServerUrl: string }
+): Promise<UptermHost> {
+  const uptermPath = await resolveUptermPathAsync(ctx.env);
+
+  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');
+
+  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 });
+
+  let currentProcess: SpawnPromise<SpawnResult> | null = null;
+
+  const stopCurrentProcessAsync = async (): Promise<void> => {
+    const previousProcess = currentProcess;
+    currentProcess = null;
+    if (!previousProcess) {
+      return;
+    }
+    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> => {
+    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;
+      }
+      if (attempt < CLIENT_COUNT_READ_ATTEMPTS) {
+        await sleepAsync(CLIENT_COUNT_READ_RETRY_MS);
+      }
+    }
+    throw new SystemError('Could not read the SSH client count from the upterm admin socket.', {
+      trackingCode: 'SSH_CLIENT_COUNT_UNREADABLE',
+    });
+  };
+
+  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;
+    },
+    stopAsync,
+  };
+}
@@ -1,6 +1,6 @@
 {
  "name": "create-eas-build-function",
-  "version": "22.2.0",
+  "version": "22.4.0",
  "description": "Create functions for use in EAS Build custom builds.",
  "keywords": [
    "expo",
@@ -35,7 +35,7 @@
    "clean": "rimraf ./build/ \"*.tsbuildinfo\""
  },
  "dependencies": {
-    "@expo/steps": "22.1.0"
+    "@expo/steps": "22.4.0"
  },
  "devDependencies": {
    "@expo/package-manager": "1.9.10",
@@ -14158,6 +14158,35 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "customEvent",
+            "description": "A single custom event by the `id` of an `AppObserveCustomEvent`. Null when the app has no\nsuch event, including when it has aged out of retention.",
+            "args": [
+              {
+                "name": "id",
+                "description": null,
+                "type": {
+                  "kind": "NON_NULL",
+                  "name": null,
+                  "ofType": {
+                    "kind": "SCALAR",
+                    "name": "ID",
+                    "ofType": null
+                  }
+                },
+                "defaultValue": null,
+                "isDeprecated": false,
+                "deprecationReason": null
+              }
+            ],
+            "type": {
+              "kind": "OBJECT",
+              "name": "AppObserveCustomEvent",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "customEventCounts",
            "description": null,
@@ -14396,6 +14425,26 @@
                "isDeprecated": false,
                "deprecationReason": null
              },
+              {
+                "name": "platforms",
+                "description": "Filter to these platforms. Cannot be set together with platform.",
+                "type": {
+                  "kind": "LIST",
+                  "name": null,
+                  "ofType": {
+                    "kind": "NON_NULL",
+                    "name": null,
+                    "ofType": {
+                      "kind": "ENUM",
+                      "name": "AppObservePlatform",
+                      "ofType": null
+                    }
+                  }
+                },
+                "defaultValue": null,
+                "isDeprecated": false,
+                "deprecationReason": null
+              },
              {
                "name": "startTime",
                "description": null,
@@ -14453,6 +14502,26 @@
                "isDeprecated": false,
                "deprecationReason": null
              },
+              {
+                "name": "platforms",
+                "description": "Filter to these platforms. Cannot be set together with platform.",
+                "type": {
+                  "kind": "LIST",
+                  "name": null,
+                  "ofType": {
+                    "kind": "NON_NULL",
+                    "name": null,
+                    "ofType": {
+                      "kind": "ENUM",
+                      "name": "AppObservePlatform",
+                      "ofType": null
+                    }
+                  }
+                },
+                "defaultValue": null,
+                "isDeprecated": false,
+                "deprecationReason": null
+              },
              {
                "name": "startTime",
                "description": null,
@@ -14618,6 +14687,35 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "event",
+            "description": "A single metric event by the `id` of an `AppObserveEvent`. Null when the app has no such\nevent, including when it has aged out of retention or the id is not one this API issued.\n\n`sessionEventCount` and `userEventCount` are always null here: they are aggregates over a\ntime range, and a single event does not supply one.",
+            "args": [
+              {
+                "name": "id",
+                "description": null,
+                "type": {
+                  "kind": "NON_NULL",
+                  "name": null,
+                  "ofType": {
+                    "kind": "SCALAR",
+                    "name": "ID",
+                    "ofType": null
+                  }
+                },
+                "defaultValue": null,
+                "isDeprecated": false,
+                "deprecationReason": null
+              }
+            ],
+            "type": {
+              "kind": "OBJECT",
+              "name": "AppObserveEvent",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "events",
            "description": null,
@@ -15028,7 +15126,7 @@
          },
          {
            "name": "updates",
-            "description": null,
+            "description": "Update download activity (the Recent updates list). Not available on the free tier or legacy plans.",
            "args": [
              {
                "name": "input",
@@ -16394,12 +16492,28 @@
            "name": "platform",
            "description": null,
            "type": {
-              "kind": "NON_NULL",
+              "kind": "ENUM",
+              "name": "AppObservePlatform",
+              "ofType": null
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform. One of platform or platforms is required.",
+            "type": {
+              "kind": "LIST",
              "name": null,
              "ofType": {
-                "kind": "ENUM",
-                "name": "AppObservePlatform",
-                "ofType": null
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
              }
            },
            "defaultValue": null,
@@ -16659,6 +16773,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "propertyFilters",
            "description": null,
@@ -17524,6 +17658,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "startTime",
            "description": null,
@@ -17797,6 +17951,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "severity",
            "description": "Restrict to fatal-only or non-fatal-only errors.",
@@ -18268,6 +18442,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "startTime",
            "description": null,
@@ -18561,6 +18755,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "startTime",
            "description": null,
@@ -19312,6 +19526,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "routeName",
            "description": null,
@@ -19705,6 +19939,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "routeNames",
            "description": null,
@@ -20094,6 +20348,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "startTime",
            "description": null,
@@ -20470,6 +20744,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "startTime",
            "description": null,
@@ -20510,7 +20804,7 @@
          },
          {
            "name": "downloadCount",
-            "description": "Downloads recorded in range across platforms; null when none were recorded (and always for the embedded bundle).",
+            "description": "Downloads recorded in range across platforms; null when none were recorded\n(and always for the embedded bundle). Download data is paid-only: on the\nfree tier and legacy plans this is always null.",
            "args": [],
            "type": {
              "kind": "SCALAR",
@@ -20522,7 +20816,7 @@
          },
          {
            "name": "downloads",
-            "description": "One entry per platform with downloads in range; empty for the embedded bundle.",
+            "description": "One entry per platform with downloads in range; empty for the embedded bundle and on the free tier and legacy plans.",
            "args": [],
            "type": {
              "kind": "NON_NULL",
@@ -21499,6 +21793,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "startTime",
            "description": null,
@@ -21896,6 +22210,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "routeName",
            "description": null,
@@ -22403,6 +22737,26 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "platforms",
+            "description": "Filter to these platforms. Cannot be set together with platform.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "ENUM",
+                  "name": "AppObservePlatform",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "startTime",
            "description": null,
@@ -37211,6 +37565,30 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "applicationArchiveUrl",
+            "description": "Application archive URL to download, install, and launch before the simulator session\nbecomes available. Mutually exclusive with buildId and expoGo.",
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "buildId",
+            "description": "EAS Build to install and launch before the simulator session becomes available.\nMutually exclusive with applicationArchiveUrl and expoGo.",
+            "type": {
+              "kind": "SCALAR",
+              "name": "ID",
+              "ofType": null
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "deviceIdentifier",
            "description": "Identifier of the virtual device to start for the session. On iOS this is a\nSimulator device name or UDID (e.g. \"iPhone 16 Pro\"). On Android this is an\nAVD hardware profile id (e.g. \"pixel_7\"). If omitted, the runner picks a\ndefault device.",
@@ -37223,6 +37601,38 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "expoGo",
+            "description": "Install and launch Expo Go before the simulator session becomes available. The server resolves\nthe platform-specific application archive. Mutually exclusive with buildId and\napplicationArchiveUrl.",
+            "type": {
+              "kind": "SCALAR",
+              "name": "Boolean",
+              "ofType": null
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "launchArgs",
+            "description": "Arguments passed to the installed application when it is launched. Requires buildId,\napplicationArchiveUrl, or expoGo.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "SCALAR",
+                  "name": "String",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "maxIdleTimeMinutes",
            "description": "Stop the session automatically after this many minutes without observed\nsession activity. Must be positive and smaller than the session's maximum\nduration (2 hours, or maxRunTimeMinutes when set). Only supported for\nagent-device, argent, and Appium sessions. If omitted, the session has no idle\ntimeout.",
@@ -37259,6 +37669,18 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "openUrl",
+            "description": "Expo or development-client URL to open after launching the installed application. Requires\nbuildId, applicationArchiveUrl, or expoGo.",
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "packageVersion",
            "description": "The version of the package backing the device run session (e.g. \"0.1.3-alpha.3\").\nIf omitted, consumers treat the session as pinned to \"latest\".",
@@ -37287,6 +37709,30 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "resourceClass",
+            "description": null,
+            "type": {
+              "kind": "ENUM",
+              "name": "DeviceRunSessionResourceClass",
+              "ofType": null
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "sdkVersion",
+            "description": "Expo SDK version used to select an Expo Go application archive. Only supported when expoGo is\ntrue. If omitted, the current Expo Go archive for the platform is used.",
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "type",
            "description": null,
@@ -42767,6 +43213,18 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "applicationArchiveUrl",
+            "description": "Direct application archive URL installed and launched for this session. Null when\nthe session uses an EAS Build or starts without an app.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "artifacts",
            "description": null,
@@ -42791,6 +43249,18 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "build",
+            "description": "EAS Build installed and launched for this session. Null when the session uses\na direct application archive URL or starts without an app.",
+            "args": [],
+            "type": {
+              "kind": "OBJECT",
+              "name": "Build",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "createdAt",
            "description": null,
@@ -43644,6 +44114,29 @@
          }
        ]
      },
+      {
+        "kind": "ENUM",
+        "name": "DeviceRunSessionResourceClass",
+        "description": null,
+        "fields": null,
+        "inputFields": null,
+        "interfaces": null,
+        "enumValues": [
+          {
+            "name": "LARGE",
+            "description": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "MEDIUM",
+            "description": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          }
+        ],
+        "possibleTypes": null
+      },
      {
        "kind": "ENUM",
        "name": "DeviceRunSessionStatus",
@@ -74943,24 +75436,16 @@
                "deprecationReason": null
              },
              {
-                "name": "turtleBuildId",
+                "name": "target",
                "description": null,
                "type": {
-                  "kind": "SCALAR",
-                  "name": "ID",
-                  "ofType": null
-                },
-                "defaultValue": null,
-                "isDeprecated": false,
-                "deprecationReason": null
-              },
-              {
-                "name": "turtleJobRunId",
-                "description": null,
-                "type": {
-                  "kind": "SCALAR",
-                  "name": "ID",
-                  "ofType": null
+                  "kind": "NON_NULL",
+                  "name": null,
+                  "ofType": {
+                    "kind": "INPUT_OBJECT",
+                    "name": "TurtleSshTargetInput",
+                    "ofType": null
+                  }
                },
                "defaultValue": null,
                "isDeprecated": false,
@@ -75039,6 +75524,72 @@
        "enumValues": null,
        "possibleTypes": null
      },
+      {
+        "kind": "INPUT_OBJECT",
+        "name": "TurtleSshTargetInput",
+        "description": null,
+        "fields": null,
+        "inputFields": [
+          {
+            "name": "id",
+            "description": null,
+            "type": {
+              "kind": "NON_NULL",
+              "name": null,
+              "ofType": {
+                "kind": "SCALAR",
+                "name": "ID",
+                "ofType": null
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "type",
+            "description": null,
+            "type": {
+              "kind": "NON_NULL",
+              "name": null,
+              "ofType": {
+                "kind": "ENUM",
+                "name": "TurtleSshTargetType",
+                "ofType": null
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          }
+        ],
+        "interfaces": null,
+        "enumValues": null,
+        "possibleTypes": null
+      },
+      {
+        "kind": "ENUM",
+        "name": "TurtleSshTargetType",
+        "description": null,
+        "fields": null,
+        "inputFields": null,
+        "interfaces": null,
+        "enumValues": [
+          {
+            "name": "BUILD",
+            "description": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "JOB_RUN",
+            "description": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          }
+        ],
+        "possibleTypes": null
+      },
      {
        "kind": "ENUM",
        "name": "TurtleSshTransportType",
@@ -94596,6 +95147,18 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "cancelReason",
+            "description": "Why the server canceled this run. Null for manually canceled runs and for\nruns canceled before the reason was recorded.",
+            "args": [],
+            "type": {
+              "kind": "UNION",
+              "name": "WorkflowRunCancelReason",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "createdAt",
            "description": null,
@@ -94960,6 +95523,45 @@
        "enumValues": null,
        "possibleTypes": null
      },
+      {
+        "kind": "UNION",
+        "name": "WorkflowRunCancelReason",
+        "description": null,
+        "fields": null,
+        "inputFields": null,
+        "interfaces": null,
+        "enumValues": null,
+        "possibleTypes": [
+          {
+            "kind": "OBJECT",
+            "name": "WorkflowRunCancelReasonConcurrencyGroup",
+            "ofType": null
+          }
+        ]
+      },
+      {
+        "kind": "OBJECT",
+        "name": "WorkflowRunCancelReasonConcurrencyGroup",
+        "description": null,
+        "fields": [
+          {
+            "name": "cancelingWorkflowRun",
+            "description": "The newer run in the same concurrency group whose creation canceled this run.\nNull if that run no longer exists.",
+            "args": [],
+            "type": {
+              "kind": "OBJECT",
+              "name": "WorkflowRun",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          }
+        ],
+        "inputFields": null,
+        "interfaces": [],
+        "enumValues": null,
+        "possibleTypes": null
+      },
      {
        "kind": "OBJECT",
        "name": "WorkflowRunEdge",
@@ -95541,6 +96143,12 @@
            "description": null,
            "isDeprecated": false,
            "deprecationReason": null
+          },
+          {
+            "name": "WAITING",
+            "description": null,
+            "isDeprecated": false,
+            "deprecationReason": null
          }
        ],
        "possibleTypes": null
@@ -1,6 +1,6 @@
 {
  "name": "eas-cli",
-  "version": "22.2.0",
+  "version": "22.6.0",
  "description": "EAS command line tool",
  "keywords": [
    "cli",
@@ -64,7 +64,7 @@
    "@expo/results": "1.0.0",
    "@expo/rudder-sdk-node": "1.1.1",
    "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "22.1.0",
+    "@expo/steps": "22.4.0",
    "@expo/timeago.js": "1.0.0",
    "@oclif/core": "^4.8.3",
    "@oclif/plugin-autocomplete": "^3.2.40",
@@ -110,6 +110,7 @@
    "node-forge": "1.4.0",
    "node-stream-zip": "1.15.0",
    "nullthrows": "1.1.1",
+    "open": "8.4.0",
    "ora": "5.1.0",
    "pkg-dir": "4.2.0",
    "pngjs": "7.0.0",
@@ -189,6 +190,9 @@
      "account": {
        "description": "manage account"
      },
+      "billing": {
+        "description": "manage account billing and subscriptions"
+      },
      "branch": {
        "description": "manage update branches"
      },
@@ -1,17 +1,17 @@
 import { getConfigFilePaths } from '@expo/config';

 import { getWorkflowRunUrl } from '../../build/utils/url';
-import Go from '../../commands/go';
+import Go, { toRepackTargetSdkVersion } from '../../commands/go';
 import { WorkflowRunStatus } from '../../graphql/generated';
 import { WorkflowRunMutation } from '../../graphql/mutations/WorkflowRunMutation';
 import { WorkflowRunQuery } from '../../graphql/queries/WorkflowRunQuery';
 import Log from '../../log';
 import { selectAsync } from '../../prompts';
+import { detectProjectSdkVersionAsync } from '../../project/detectProjectSdkVersionAsync';
 import { getPrivateExpoConfigAsync } from '../../project/expoConfig';
 import { uploadAccountScopedFileAsync } from '../../project/uploadAccountScopedFileAsync';
 import { uploadAccountScopedProjectSourceAsync } from '../../project/uploadAccountScopedProjectSourceAsync';
 import { ensureActorHasPrimaryAccount } from '../../user/actions';
-import { detectProjectSdkVersionAsync, toRepackTargetSdkVersion } from '../../commands/go';
 import { mockTestCommand } from './utils';

 jest.mock('@expo/config', () => ({
@@ -15,12 +15,21 @@ const PLATFORM_TO_ANALYTICS_PLATFORM: Partial<Record<NodeJS.Platform, string>> =
  linux: 'Linux',
 };

-export type AnalyticsEvent = CommandEvent | BuildEvent | SubmissionEvent | MetadataEvent;
+export type AnalyticsEvent =
+  | CommandEvent
+  | BuildEvent
+  | SubmissionEvent
+  | MetadataEvent
+  | BillingEvent;

 export enum CommandEvent {
  ACTION = 'action', // generic event type which is used to determine the 'daily active user' stat, include an `action: eas ${subcommand}` property inside of the event properties object
 }

+export enum BillingEvent {
+  SUBSCRIBE_COMMAND = 'billing cli subscribe command',
+}
+
 export enum SubmissionEvent {
  SUBMIT_COMMAND = 'submit cli submit command',
  SUBMIT_COMMAND_ATTEMPT = 'submit cli attempt',
@@ -0,0 +1,49 @@
+import { ApiV2Client } from '../../api';
+import { BillingClient } from '../billingClient';
+
+jest.mock('../../api');
+
+describe(BillingClient, () => {
+  const postAsync = jest.fn();
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.mocked(ApiV2Client).mockImplementation(() => ({ postAsync }) as unknown as ApiV2Client);
+  });
+
+  it('unwraps the apiv2 `data` envelope for a checkout session', async () => {
+    postAsync.mockResolvedValue({
+      data: {
+        id: 'cs_123',
+        clientSecret: null,
+        url: 'https://checkout.stripe.com/pay',
+      },
+    });
+
+    const client = new BillingClient({ accessToken: 'token', sessionSecret: null });
+    const session = await client.createCheckoutSessionAsync('account-id', 'STARTER');
+
+    expect(session).toEqual({
+      id: 'cs_123',
+      clientSecret: null,
+      url: 'https://checkout.stripe.com/pay',
+    });
+    expect(postAsync).toHaveBeenCalledWith('stripe-auth/checkout', {
+      body: { accountId: 'account-id', planType: 'STARTER' },
+    });
+  });
+
+  it('unwraps the apiv2 `data` envelope for a customer portal session', async () => {
+    postAsync.mockResolvedValue({
+      data: { customerPortal: { url: 'https://billing.stripe.com' } },
+    });
+
+    const client = new BillingClient({ accessToken: 'token', sessionSecret: null });
+    const session = await client.createCustomerPortalSessionAsync('account-id');
+
+    expect(session).toEqual({ url: 'https://billing.stripe.com' });
+    expect(postAsync).toHaveBeenCalledWith('stripe-auth/customer-portal', {
+      body: { accountId: 'account-id' },
+    });
+  });
+});
@@ -0,0 +1,96 @@
+import { ExpoGraphqlClient } from '../../commandUtils/context/contextUtils/createGraphqlClient';
+import { Permission, Role } from '../../graphql/generated';
+import { AccountQuery } from '../../graphql/queries/AccountQuery';
+import { Actor } from '../../user/User';
+import { resolveBillingAccountAsync } from '../resolveAccount';
+
+jest.mock('../../graphql/queries/AccountQuery');
+
+describe(resolveBillingAccountAsync, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(null);
+  });
+
+  function account(name: string, role: Role): Actor['accounts'][number] {
+    return {
+      id: `${name}-id`,
+      name,
+      viewerUserPermission: { role },
+    } as Actor['accounts'][number];
+  }
+
+  function actor(accounts: Actor['accounts']): Actor {
+    return { id: 'actor-id', accounts } as Actor;
+  }
+
+  async function resolveAsync(
+    accounts: Actor['accounts'],
+    accountName?: string
+  ): ReturnType<typeof resolveBillingAccountAsync> {
+    return await resolveBillingAccountAsync({
+      graphqlClient,
+      actor: actor(accounts),
+      accountName,
+      nonInteractive: true,
+      subscriptionFilter: 'unsubscribed',
+    });
+  }
+
+  it('automatically selects the only account with billing permission', async () => {
+    await expect(
+      resolveAsync([account('viewer', Role.ViewOnly), account('admin', Role.Admin)])
+    ).resolves.toEqual({ id: 'admin-id', name: 'admin', subscription: null });
+  });
+
+  it.each([
+    ['account owners', Role.Owner],
+    ['custom roles with admin permission', Role.HasAdmin],
+  ])('allows %s to manage billing', async (_case, role) => {
+    await expect(resolveAsync([account('team', role)])).resolves.toEqual({
+      id: 'team-id',
+      name: 'team',
+      subscription: null,
+    });
+  });
+
+  it('allows the owner of a personal account to manage billing', async () => {
+    const ownerAccount = {
+      ...account('personal', Role.ViewOnly),
+      ownerUserActor: { __typename: 'User', id: 'actor-id', username: 'personal' },
+    } as Actor['accounts'][number];
+
+    await expect(resolveAsync([ownerAccount])).resolves.toEqual({
+      id: 'personal-id',
+      name: 'personal',
+      subscription: null,
+    });
+  });
+
+  it('rejects an explicitly selected account without billing permission', async () => {
+    await expect(resolveAsync([account('developer', Role.Developer)], 'developer')).rejects.toThrow(
+      'You must be an Owner or Admin of account "developer" to manage billing.'
+    );
+    expect(AccountQuery.getByNameAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects an account lookup without billing permission', async () => {
+    jest.mocked(AccountQuery.getByNameAsync).mockResolvedValue({
+      id: 'viewer-id',
+      name: 'viewer',
+      viewerUserPermission: { id: 'viewer-permission-id', permissions: [Permission.View] },
+    });
+
+    await expect(resolveAsync([], 'viewer')).rejects.toThrow(
+      'You must be an Owner or Admin of account "viewer" to manage billing.'
+    );
+  });
+
+  it('fails when no account has billing permission', async () => {
+    await expect(resolveAsync([account('viewer', Role.ViewOnly)])).rejects.toThrow(
+      'You must be an Owner or Admin of at least one account to manage billing.'
+    );
+  });
+});
@@ -0,0 +1,37 @@
+import { ApiV2Client } from '../api';
+import type { CheckoutPlanType } from './plans';
+
+export type CheckoutSession = {
+  id: string;
+  clientSecret: string | null;
+  url: string | null;
+};
+
+export type CustomerPortalSession = {
+  url: string;
+};
+
+export class BillingClient {
+  private readonly apiV2Client: ApiV2Client;
+
+  constructor(authInfo: { accessToken: string | null; sessionSecret: string | null }) {
+    this.apiV2Client = new ApiV2Client(authInfo);
+  }
+
+  async createCheckoutSessionAsync(
+    accountId: string,
+    planType: CheckoutPlanType
+  ): Promise<CheckoutSession> {
+    const { data } = await this.apiV2Client.postAsync('stripe-auth/checkout', {
+      body: { accountId, planType },
+    });
+    return data;
+  }
+
+  async createCustomerPortalSessionAsync(accountId: string): Promise<CustomerPortalSession> {
+    const { data } = await this.apiV2Client.postAsync('stripe-auth/customer-portal', {
+      body: { accountId },
+    });
+    return data.customerPortal;
+  }
+}
@@ -0,0 +1,30 @@
+import Log, { link } from '../log';
+import { ora } from '../ora';
+
+import openBrowser = require('open');
+
+export async function openOrPrintUrlAsync(
+  url: string,
+  { label, open }: { label: string; open: boolean }
+): Promise<void> {
+  if (!open) {
+    Log.log(`${label}: ${link(url)}`);
+    return;
+  }
+
+  const spinner = ora(`Opening ${label.toLowerCase()}`).start();
+  let opened = false;
+  try {
+    await openBrowser(url);
+    opened = true;
+  } catch (error) {
+    Log.debug(`Failed to open a web browser: ${error}`);
+  }
+
+  if (opened) {
+    spinner.succeed(`Opened ${label.toLowerCase()} in your browser`);
+  } else {
+    spinner.fail('Unable to open a web browser automatically.');
+  }
+  Log.log(`${label}: ${link(url)}`);
+}
@@ -0,0 +1,23 @@
+export const SUBSCRIBABLE_PLANS = {
+  starter: { planType: 'STARTER', label: 'Starter' },
+  production: { planType: 'PRODUCTION', label: 'Production' },
+} as const;
+
+export type PlanSlug = keyof typeof SUBSCRIBABLE_PLANS;
+export type CheckoutPlanType = (typeof SUBSCRIBABLE_PLANS)[PlanSlug]['planType'];
+
+export const PLAN_SLUGS = Object.keys(SUBSCRIBABLE_PLANS) as PlanSlug[];
+
+export const FREE_PLAN_PRICE_ID = 'price_free';
+
+export function formatStarterSubscribeCommand(accountName?: string): string {
+  return `eas billing:subscribe starter${accountName ? ` --account ${accountName}` : ''}`;
+}
+
+export function hasPaidSubscription(
+  subscription: {
+    planId?: string | null;
+  } | null
+): boolean {
+  return subscription?.planId != null && subscription.planId !== FREE_PLAN_PRICE_ID;
+}
@@ -0,0 +1,151 @@
+import { ExpoGraphqlClient } from '../commandUtils/context/contextUtils/createGraphqlClient';
+import { Permission, Role } from '../graphql/generated';
+import { AccountQuery, type AccountSubscriptionInfo } from '../graphql/queries/AccountQuery';
+import { hasPaidSubscription } from './plans';
+import { Actor } from '../user/User';
+import { ExpoChoice, selectAsync } from '../prompts';
+
+export type BillingAccount = {
+  id: string;
+  name: string;
+  subscription: AccountSubscriptionInfo | null;
+};
+
+type SubscriptionFilter = 'subscribed' | 'unsubscribed';
+
+function billingPermissionError(accountName: string): Error {
+  return new Error(`You must be an Owner or Admin of account "${accountName}" to manage billing.`);
+}
+
+function hasBillingRole(actor: Actor, account: Actor['accounts'][number]): boolean {
+  if (account.ownerUserActor?.id === actor.id) {
+    return true;
+  }
+  const { role } = account.viewerUserPermission;
+  return role === Role.Admin || role === Role.Owner || role === Role.HasAdmin;
+}
+
+async function getAccountWithSubscriptionAsync(
+  graphqlClient: ExpoGraphqlClient,
+  account: { id: string; name: string }
+): Promise<BillingAccount> {
+  const subscription = await AccountQuery.getSubscriptionAsync(graphqlClient, account.id);
+  return { id: account.id, name: account.name, subscription };
+}
+
+function toAccountChoice(account: BillingAccount, disabled: boolean): ExpoChoice<BillingAccount> {
+  const fallback = hasPaidSubscription(account.subscription) ? 'Paid' : 'Free';
+  return {
+    title: account.name,
+    value: account,
+    description: `Current plan: ${account.subscription?.name ?? fallback}`,
+    disabled,
+  };
+}
+
+async function resolveNamedAccountAsync(
+  graphqlClient: ExpoGraphqlClient,
+  actor: Actor,
+  accountName: string
+): Promise<{ id: string; name: string }> {
+  const ownAccount = actor.accounts.find(account => account.name === accountName);
+  if (ownAccount) {
+    if (!hasBillingRole(actor, ownAccount)) {
+      throw billingPermissionError(ownAccount.name);
+    }
+    return ownAccount;
+  }
+
+  const account = await AccountQuery.getByNameAsync(graphqlClient, accountName).catch(() => null);
+  if (!account) {
+    const availableAccounts = actor.accounts
+      .filter(candidate => hasBillingRole(actor, candidate))
+      .map(candidate => candidate.name)
+      .join(', ');
+    throw new Error(
+      `Account "${accountName}" not found or you don't have access. Available accounts: ${availableAccounts}`
+    );
+  }
+
+  const { permissions } = account.viewerUserPermission;
+  if (!permissions.includes(Permission.Admin) && !permissions.includes(Permission.Own)) {
+    throw billingPermissionError(account.name);
+  }
+  return account;
+}
+
+export async function resolveBillingAccountAsync({
+  graphqlClient,
+  actor,
+  accountName,
+  nonInteractive,
+  subscriptionFilter,
+}: {
+  graphqlClient: ExpoGraphqlClient;
+  actor: Actor;
+  accountName: string | undefined;
+  nonInteractive: boolean;
+  subscriptionFilter: SubscriptionFilter;
+}): Promise<BillingAccount> {
+  if (accountName) {
+    const namedAccount = await resolveNamedAccountAsync(graphqlClient, actor, accountName);
+    const account = await getAccountWithSubscriptionAsync(graphqlClient, namedAccount);
+    if (subscriptionFilter === 'subscribed' && !hasPaidSubscription(account.subscription)) {
+      throw new Error(
+        `Account "${account.name}" does not have an active paid plan. Run eas billing:subscribe to subscribe.`
+      );
+    }
+    return account;
+  }
+
+  const billingAccounts = actor.accounts.filter(account => hasBillingRole(actor, account));
+  if (billingAccounts.length === 0) {
+    throw new Error('You must be an Owner or Admin of at least one account to manage billing.');
+  }
+
+  const accounts = await Promise.all(
+    billingAccounts.map(account => getAccountWithSubscriptionAsync(graphqlClient, account))
+  );
+  if (subscriptionFilter === 'unsubscribed' && accounts.length === 1) {
+    return accounts[0];
+  }
+
+  const subscribedAccounts = accounts.filter(account => hasPaidSubscription(account.subscription));
+  const unsubscribedAccounts = accounts.filter(
+    account => !hasPaidSubscription(account.subscription)
+  );
+  const eligibleAccounts =
+    subscriptionFilter === 'subscribed' ? subscribedAccounts : unsubscribedAccounts;
+
+  if (eligibleAccounts.length === 0) {
+    throw new Error(
+      subscriptionFilter === 'subscribed'
+        ? 'No available accounts have an active paid plan. Run eas billing:subscribe to subscribe an account.'
+        : 'All available accounts already have a paid plan. Run eas billing:manage to change an existing subscription.'
+    );
+  }
+
+  if (eligibleAccounts.length === 1) {
+    return eligibleAccounts[0];
+  }
+
+  if (nonInteractive) {
+    throw new Error(
+      'The --account flag must be provided when running in `--non-interactive` mode and you can manage billing for more than one eligible account.'
+    );
+  }
+
+  const disabledAccounts = subscriptionFilter === 'unsubscribed' ? subscribedAccounts : [];
+  return await selectAsync(
+    'Select an account:',
+    [
+      ...eligibleAccounts.map(account => toAccountChoice(account, false)),
+      ...disabledAccounts.map(account => toAccountChoice(account, true)),
+    ],
+    {
+      initial: eligibleAccounts[0],
+      warningMessageForDisabledEntries:
+        'This account already has a paid plan. Run eas billing:manage to change it.',
+    }
+  );
+}
@@ -295,39 +295,41 @@ describe(Build.name, () => {
      describe('for EAS_BUILD_FREE_TIER_LIMIT_EXCEEDED', () => {
        it('throws correct EasCommandError subclass', async () => {
          const platform = Platform.ANDROID;
+          const accountName = 'test-account';
          const graphQLError = getGraphQLError('Error 1', 'EAS_BUILD_FREE_TIER_LIMIT_EXCEEDED');
          const graphQLErrors = [graphQLError];
          const error = new CombinedError({ graphQLErrors });

          const handleBuildRequestErrorThrownError = getError<EasBuildFreeTierLimitExceededError>(
            () => {
-              handleBuildRequestError(error, platform);
+              handleBuildRequestError(error, platform, accountName);
            }
          );

          assertReThrownError(
            handleBuildRequestErrorThrownError,
            EasBuildFreeTierLimitExceededError,
-            'Error 1'
+            'Error 1\nRun eas billing:subscribe starter --account test-account to upgrade to the Starter plan.'
          );
        });
      });
      describe('for EAS_BUILD_FREE_TIER_IOS_LIMIT_EXCEEDED', () => {
        it('throws correct EasCommandError subclass', async () => {
          const platform = Platform.ANDROID;
+          const accountName = 'test-account';
          const graphQLError = getGraphQLError('Error 1', 'EAS_BUILD_FREE_TIER_IOS_LIMIT_EXCEEDED');
          const graphQLErrors = [graphQLError];
          const error = new CombinedError({ graphQLErrors });

          const handleBuildRequestErrorThrownError =
            getError<EasBuildFreeTierIosLimitExceededError>(() => {
-              handleBuildRequestError(error, platform);
+              handleBuildRequestError(error, platform, accountName);
            });

          assertReThrownError(
            handleBuildRequestErrorThrownError,
            EasBuildFreeTierIosLimitExceededError,
-            'Error 1'
+            'Error 1\nRun eas billing:subscribe starter --account test-account to upgrade to the Starter plan.'
          );
        });
      });
@@ -43,6 +43,7 @@ import {
 import { BuildEvent } from '../analytics/AnalyticsManager';
 import { withAnalyticsAsync } from '../analytics/common';
 import { getExpoWebsiteBaseUrl } from '../api';
+import { formatStarterSubscribeCommand } from '../billing/plans';
 import { ExpoGraphqlClient } from '../commandUtils/context/contextUtils/createGraphqlClient';
 import { EasCommandError } from '../commandUtils/errors';
 import { createFingerprintAsync } from '../fingerprint/cli';
@@ -209,7 +210,7 @@ export async function prepareBuildRequestForPlatformAsync<
        });
        return await sendBuildRequestAsync(builder, job, graphqlMetadata, buildParams);
      } catch (error: any) {
-        handleBuildRequestError(error, job.platform);
+        handleBuildRequestError(error, job.platform, ctx.accountName);
      }
    } else {
      throw new Error('Unknown localBuildMode.');
@@ -230,7 +231,11 @@ const SERVER_SIDE_DEFINED_ERRORS: Record<string, typeof EasCommandError> = {
  VALIDATION_ERROR: RequestValidationError,
 };

-export function handleBuildRequestError(error: any, platform: Platform): never {
+export function handleBuildRequestError(
+  error: any,
+  platform: Platform,
+  accountName?: string
+): never {
  logBuildRequestErrorDebugInfo(error);

  const graphQLErrors: GraphQLError[] = Array.isArray(error?.graphQLErrors)
@@ -241,7 +246,15 @@ export function handleBuildRequestError(error: any, platform: Platform): never {
    | undefined;
  if (graphQLErrorCode && graphQLErrorCode in SERVER_SIDE_DEFINED_ERRORS) {
    const ErrorClass: typeof EasCommandError = SERVER_SIDE_DEFINED_ERRORS[graphQLErrorCode];
-    throw new ErrorClass(graphQLErrors[0]?.message);
+    const message = graphQLErrors[0]?.message;
+    const isFreeTierLimitError =
+      graphQLErrorCode === 'EAS_BUILD_FREE_TIER_LIMIT_EXCEEDED' ||
+      graphQLErrorCode === 'EAS_BUILD_FREE_TIER_IOS_LIMIT_EXCEEDED';
+    throw new ErrorClass(
+      isFreeTierLimitError
+        ? `${message}\nRun ${formatStarterSubscribeCommand(accountName)} to upgrade to the Starter plan.`
+        : message
+    );
  } else if (graphQLErrorCode === 'EAS_BUILD_DOWN_FOR_MAINTENANCE') {
    throw new EasBuildDownForMaintenanceError(
      `EAS Build is down for maintenance. Try again later. Check ${link(
@@ -0,0 +1,163 @@
+import open from 'open';
+
+import { getMockOclifConfig } from '../../../__tests__/commands/utils';
+import { BillingClient } from '../../../billing/billingClient';
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { Role } from '../../../graphql/generated';
+import { AccountQuery } from '../../../graphql/queries/AccountQuery';
+import { ora } from '../../../ora';
+import { selectAsync } from '../../../prompts';
+import { printJsonOnlyOutput } from '../../../utils/json';
+import BillingManage from '../manage';
+
+jest.mock('open');
+jest.mock('../../../billing/billingClient');
+jest.mock('../../../graphql/queries/AccountQuery');
+jest.mock('../../../log');
+jest.mock('../../../prompts');
+jest.mock('../../../utils/json');
+jest.mock('../../../ora');
+
+function billingAccount(
+  id: string,
+  name: string
+): { id: string; name: string; viewerUserPermission: { role: Role } } {
+  return { id, name, viewerUserPermission: { role: Role.Admin } };
+}
+
+const STARTER_SUBSCRIPTION = { id: 'sub_1', name: 'Starter', planId: 'price_paid' };
+
+describe(BillingManage, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+  const account = billingAccount('account-id', 'testaccount');
+
+  const createCustomerPortalSessionAsync = jest.fn();
+
+  function createCommand(
+    argv: string[],
+    accounts: ReturnType<typeof billingAccount>[] = [account]
+  ): BillingManage {
+    const command = new BillingManage(argv, mockConfig);
+    jest.spyOn(command as any, 'getContextAsync').mockResolvedValue({
+      loggedIn: {
+        graphqlClient,
+        actor: { id: 'actor-id', accounts },
+        authenticationInfo: { accessToken: 'token', sessionSecret: null },
+      },
+    } as never);
+    return command;
+  }
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(STARTER_SUBSCRIPTION);
+    jest.mocked(ora).mockReturnValue({
+      start: jest.fn().mockReturnThis(),
+      succeed: jest.fn().mockReturnThis(),
+      fail: jest.fn().mockReturnThis(),
+    } as any);
+    jest
+      .mocked(BillingClient)
+      .mockImplementation(() => ({ createCustomerPortalSessionAsync }) as unknown as BillingClient);
+  });
+
+  it('creates a customer portal session and prints the URL as JSON', async () => {
+    createCustomerPortalSessionAsync.mockResolvedValue({
+      url: 'https://billing.stripe.com/session/abc',
+    });
+
+    await createCommand(['--json']).runAsync();
+
+    expect(createCustomerPortalSessionAsync).toHaveBeenCalledWith('account-id');
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith({
+      customerPortalUrl: 'https://billing.stripe.com/session/abc',
+    });
+  });
+
+  it('opens the customer portal in a browser when interactive, without re-encoding the URL', async () => {
+    const url = 'https://billing.stripe.com/session/abc%2Fdef';
+    createCustomerPortalSessionAsync.mockResolvedValue({ url });
+    jest.mocked(open).mockResolvedValue({} as never);
+
+    await createCommand([]).runAsync();
+
+    expect(open).toHaveBeenCalledWith(url);
+  });
+
+  it('prints the customer portal URL without opening a browser with --no-open', async () => {
+    createCustomerPortalSessionAsync.mockResolvedValue({
+      url: 'https://billing.stripe.com/session/abc',
+    });
+
+    await createCommand(['--no-open']).runAsync();
+
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it('only shows accounts with active paid plans', async () => {
+    const freeAccount = billingAccount('free-account-id', 'free-account');
+    const productionAccount = billingAccount('production-account-id', 'production-account');
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockImplementation(async (_client, accountId) =>
+      accountId === freeAccount.id
+        ? null
+        : {
+            id: `subscription-${accountId}`,
+            name: accountId === productionAccount.id ? 'Production' : 'Starter',
+            planId: `price-${accountId}`,
+          }
+    );
+    jest.mocked(selectAsync).mockImplementation(async (_message, choices) => choices[1].value);
+    createCustomerPortalSessionAsync.mockResolvedValue({
+      url: 'https://billing.stripe.com/session',
+    });
+
+    await createCommand([], [account, freeAccount, productionAccount]).runAsync();
+
+    expect(selectAsync).toHaveBeenCalledWith(
+      'Select an account:',
+      [
+        {
+          title: 'testaccount',
+          value: {
+            id: 'account-id',
+            name: 'testaccount',
+            subscription: {
+              id: 'subscription-account-id',
+              name: 'Starter',
+              planId: 'price-account-id',
+            },
+          },
+          description: 'Current plan: Starter',
+          disabled: false,
+        },
+        {
+          title: 'production-account',
+          value: {
+            id: 'production-account-id',
+            name: 'production-account',
+            subscription: {
+              id: 'subscription-production-account-id',
+              name: 'Production',
+              planId: 'price-production-account-id',
+            },
+          },
+          description: 'Current plan: Production',
+          disabled: false,
+        },
+      ],
+      expect.any(Object)
+    );
+    expect(createCustomerPortalSessionAsync).toHaveBeenCalledWith('production-account-id');
+  });
+
+  it('rejects an account without an active paid plan', async () => {
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(null);
+
+    await expect(createCommand(['--account', 'testaccount']).runAsync()).rejects.toThrow(
+      'Account "testaccount" does not have an active paid plan. Run eas billing:subscribe to subscribe.'
+    );
+
+    expect(createCustomerPortalSessionAsync).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,308 @@
+import open from 'open';
+
+import { getMockOclifConfig } from '../../../__tests__/commands/utils';
+import { BillingClient } from '../../../billing/billingClient';
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { Role } from '../../../graphql/generated';
+import { AccountQuery } from '../../../graphql/queries/AccountQuery';
+import Log, { link } from '../../../log';
+import { ora } from '../../../ora';
+import { selectAsync } from '../../../prompts';
+import { printJsonOnlyOutput } from '../../../utils/json';
+import BillingSubscribe from '../subscribe';
+
+jest.mock('open');
+jest.mock('../../../billing/billingClient');
+jest.mock('../../../graphql/queries/AccountQuery');
+jest.mock('../../../log');
+jest.mock('../../../prompts');
+jest.mock('../../../utils/json');
+jest.mock('../../../ora');
+
+function billingAccount(
+  id: string,
+  name: string
+): { id: string; name: string; viewerUserPermission: { role: Role } } {
+  return { id, name, viewerUserPermission: { role: Role.Admin } };
+}
+
+const STARTER_SUBSCRIPTION = { id: 'sub_1', name: 'Starter', planId: 'price_paid' };
+const FREE_SUBSCRIPTION = { id: 'sub_free', name: 'Free', planId: 'price_free' };
+
+describe(BillingSubscribe, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+  const account = billingAccount('account-id', 'testaccount');
+
+  const createCheckoutSessionAsync = jest.fn();
+  const logEvent = jest.fn();
+
+  function createCommand(
+    argv: string[],
+    accounts: ReturnType<typeof billingAccount>[] = [account]
+  ): BillingSubscribe {
+    const command = new BillingSubscribe(argv, mockConfig);
+    jest.spyOn(command as any, 'getContextAsync').mockResolvedValue({
+      analytics: { logEvent },
+      loggedIn: {
+        graphqlClient,
+        actor: { id: 'actor-id', accounts },
+        authenticationInfo: { accessToken: 'token', sessionSecret: null },
+      },
+    } as never);
+    return command;
+  }
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(null);
+    jest.mocked(ora).mockReturnValue({
+      start: jest.fn().mockReturnThis(),
+      succeed: jest.fn().mockReturnThis(),
+      fail: jest.fn().mockReturnThis(),
+    } as any);
+    jest
+      .mocked(BillingClient)
+      .mockImplementation(() => ({ createCheckoutSessionAsync }) as unknown as BillingClient);
+  });
+
+  it('creates a checkout session for a plan and prints the URL as JSON', async () => {
+    createCheckoutSessionAsync.mockResolvedValue({
+      id: 'cs_123',
+      url: 'https://checkout.stripe.com/c/pay/cs_123',
+    });
+
+    await createCommand(['starter', '--json']).runAsync();
+
+    expect(createCheckoutSessionAsync).toHaveBeenCalledWith('account-id', 'STARTER');
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith({
+      checkoutUrl: 'https://checkout.stripe.com/c/pay/cs_123',
+      alreadySubscribed: false,
+    });
+  });
+
+  it('maps each plan slug to its server PlanType', async () => {
+    createCheckoutSessionAsync.mockResolvedValue({ id: 'cs', url: 'https://checkout' });
+
+    await createCommand(['production', '--json']).runAsync();
+
+    expect(createCheckoutSessionAsync).toHaveBeenCalledWith('account-id', 'PRODUCTION');
+  });
+
+  it('prompts for a plan when one is not provided', async () => {
+    jest.mocked(selectAsync).mockResolvedValue('production');
+    createCheckoutSessionAsync.mockResolvedValue({ id: 'cs', url: 'https://checkout' });
+
+    await createCommand([]).runAsync();
+
+    expect(selectAsync).toHaveBeenCalledWith('Select a plan:', [
+      { title: 'Starter', value: 'starter' },
+      { title: 'Production', value: 'production' },
+    ]);
+    expect(createCheckoutSessionAsync).toHaveBeenCalledWith('account-id', 'PRODUCTION');
+    expect(jest.mocked(AccountQuery.getSubscriptionAsync).mock.invocationCallOrder[0]).toBeLessThan(
+      jest.mocked(selectAsync).mock.invocationCallOrder[0]
+    );
+  });
+
+  it('prompts for an account before prompting for a plan', async () => {
+    jest
+      .mocked(selectAsync)
+      .mockImplementationOnce(async (_message, choices) => choices[0].value)
+      .mockResolvedValueOnce('production');
+    createCheckoutSessionAsync.mockResolvedValue({ id: 'cs', url: 'https://checkout' });
+
+    await createCommand(
+      [],
+      [account, billingAccount('second-account-id', 'second-account')]
+    ).runAsync();
+
+    expect(jest.mocked(selectAsync).mock.calls.map(([message]) => message)).toEqual([
+      'Select an account:',
+      'Select a plan:',
+    ]);
+  });
+
+  it('requires a plan in non-interactive mode', async () => {
+    await expect(createCommand(['--non-interactive']).runAsync()).rejects.toThrow(
+      'The plan argument is required in non-interactive mode.'
+    );
+
+    expect(selectAsync).not.toHaveBeenCalled();
+  });
+
+  it('shows current plans and disables subscribed accounts in the account prompt', async () => {
+    const subscribedAccount = billingAccount('subscribed-id', 'subscribed');
+    const freeAccount = billingAccount('free-id', 'free');
+    const secondFreeAccount = billingAccount('second-free-id', 'second-free');
+    jest
+      .mocked(AccountQuery.getSubscriptionAsync)
+      .mockImplementation(async (_client, accountId) =>
+        accountId === subscribedAccount.id ? STARTER_SUBSCRIPTION : null
+      );
+    jest.mocked(selectAsync).mockImplementation(async (_message, choices) => choices[0].value);
+    createCheckoutSessionAsync.mockResolvedValue({ id: 'cs', url: 'https://checkout' });
+
+    await createCommand(
+      ['starter'],
+      [subscribedAccount, freeAccount, secondFreeAccount]
+    ).runAsync();
+
+    expect(selectAsync).toHaveBeenCalledWith(
+      'Select an account:',
+      [
+        {
+          title: 'free',
+          value: { id: 'free-id', name: 'free', subscription: null },
+          description: 'Current plan: Free',
+          disabled: false,
+        },
+        {
+          title: 'second-free',
+          value: { id: 'second-free-id', name: 'second-free', subscription: null },
+          description: 'Current plan: Free',
+          disabled: false,
+        },
+        {
+          title: 'subscribed',
+          value: {
+            id: 'subscribed-id',
+            name: 'subscribed',
+            subscription: STARTER_SUBSCRIPTION,
+          },
+          description: 'Current plan: Starter',
+          disabled: true,
+        },
+      ],
+      {
+        initial: { id: 'free-id', name: 'free', subscription: null },
+        warningMessageForDisabledEntries:
+          'This account already has a paid plan. Run eas billing:manage to change it.',
+      }
+    );
+    expect(createCheckoutSessionAsync).toHaveBeenCalledWith('free-id', 'STARTER');
+  });
+
+  it.each([
+    ['an explicitly selected account is', ['production', '--account', 'testaccount', '--json']],
+    ['the only account is', ['production', '--json']],
+  ])('returns the current plan when %s already subscribed', async (_case, argv) => {
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(STARTER_SUBSCRIPTION);
+
+    await createCommand(argv).runAsync();
+
+    expect(createCheckoutSessionAsync).not.toHaveBeenCalled();
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith({
+      alreadySubscribed: true,
+      currentPlan: 'Starter',
+    });
+  });
+
+  it('reports an explicitly selected subscribed account before prompting for a plan', async () => {
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(STARTER_SUBSCRIPTION);
+
+    await createCommand(['--account', 'testaccount']).runAsync();
+
+    expect(selectAsync).not.toHaveBeenCalled();
+    expect(createCheckoutSessionAsync).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(
+      'Account testaccount is already subscribed to the Starter plan.'
+    );
+    expect(Log.log).toHaveBeenCalledWith('To change or cancel your plan, run eas billing:manage.');
+  });
+
+  it('treats the free plan as not subscribed', async () => {
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(FREE_SUBSCRIPTION);
+    createCheckoutSessionAsync.mockResolvedValue({ id: 'cs', url: 'https://checkout' });
+
+    await createCommand(['starter', '--json']).runAsync();
+
+    expect(createCheckoutSessionAsync).toHaveBeenCalledWith('account-id', 'STARTER');
+  });
+
+  it.each([['--non-interactive'], ['--no-open']])(
+    'prints the checkout URL without opening a browser with %s',
+    async flag => {
+      createCheckoutSessionAsync.mockResolvedValue({
+        id: 'cs',
+        url: 'https://checkout.stripe.com/pay',
+      });
+
+      await createCommand(['starter', flag]).runAsync();
+
+      expect(open).not.toHaveBeenCalled();
+      expect(printJsonOnlyOutput).not.toHaveBeenCalled();
+      expect(link).toHaveBeenCalledWith('https://checkout.stripe.com/pay');
+    }
+  );
+
+  it('returns structured JSON with the checkout URL and does not open a browser', async () => {
+    createCheckoutSessionAsync.mockResolvedValue({
+      id: 'cs',
+      url: 'https://checkout.stripe.com/pay',
+    });
+
+    await createCommand(['starter', '--json']).runAsync();
+
+    expect(open).not.toHaveBeenCalled();
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith({
+      checkoutUrl: 'https://checkout.stripe.com/pay',
+      alreadySubscribed: false,
+    });
+  });
+
+  it.each([
+    ['checkout', null],
+    ['already subscribed', STARTER_SUBSCRIPTION],
+  ])(
+    'does not emit null JSON values, which printJsonOnlyOutput strips (%s)',
+    async (_case, subscription) => {
+      jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(subscription);
+      createCheckoutSessionAsync.mockResolvedValue({ id: 'cs', url: 'https://checkout' });
+
+      await createCommand(['starter', '--json']).runAsync();
+
+      const [payload] = jest.mocked(printJsonOnlyOutput).mock.calls[0];
+      expect(Object.values(payload)).not.toContain(null);
+    }
+  );
+
+  it.each([
+    ['--json', true],
+    ['--no-open', false],
+  ])('reports the subscribe command to analytics (%s)', async (flag, json) => {
+    createCheckoutSessionAsync.mockResolvedValue({ id: 'cs', url: 'https://checkout' });
+
+    await createCommand(['production', flag]).runAsync();
+
+    expect(logEvent).toHaveBeenCalledWith('billing cli subscribe command', {
+      account_id: 'account-id',
+      json,
+      non_interactive: json,
+      already_subscribed: false,
+      plan: 'production',
+    });
+  });
+
+  it('reports an idempotent subscribe to analytics without a plan', async () => {
+    jest.mocked(AccountQuery.getSubscriptionAsync).mockResolvedValue(STARTER_SUBSCRIPTION);
+
+    await createCommand(['production', '--json']).runAsync();
+
+    expect(logEvent).toHaveBeenCalledWith('billing cli subscribe command', {
+      account_id: 'account-id',
+      json: true,
+      non_interactive: true,
+      already_subscribed: true,
+    });
+  });
+
+  it('throws when the checkout session has no URL', async () => {
+    createCheckoutSessionAsync.mockResolvedValue({ id: 'cs', url: null });
+
+    await expect(createCommand(['starter', '--json']).runAsync()).rejects.toThrow(
+      'The checkout session did not include a URL.'
+    );
+    expect(Log.log).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,75 @@
+import { Flags } from '@oclif/core';
+
+import { BillingClient } from '../../billing/billingClient';
+import { openOrPrintUrlAsync } from '../../billing/openUrl';
+import { resolveBillingAccountAsync } from '../../billing/resolveAccount';
+import EasCommand from '../../commandUtils/EasCommand';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../commandUtils/flags';
+import { ora } from '../../ora';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
+
+export default class BillingManage extends EasCommand {
+  static override description = 'manage billing for an account with an active paid EAS plan';
+
+  static override flags = {
+    account: Flags.string({
+      char: 'a',
+      description:
+        'Account with an active paid plan to manage. Defaults to your account when only one is eligible.',
+    }),
+    'no-open': Flags.boolean({
+      description: 'Only print the customer portal URL instead of opening it in a browser',
+    }),
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(BillingManage);
+    const { json, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+    if (json) {
+      enableJsonOutput();
+    }
+
+    const {
+      loggedIn: { graphqlClient, actor, authenticationInfo },
+    } = await this.getContextAsync(BillingManage, { nonInteractive });
+
+    const account = await resolveBillingAccountAsync({
+      graphqlClient,
+      actor,
+      accountName: flags.account,
+      nonInteractive,
+      subscriptionFilter: 'subscribed',
+    });
+
+    const billingClient = new BillingClient(authenticationInfo);
+
+    const spinner = ora(`Creating a customer portal session for ${account.name}`).start();
+    let portalUrl: string;
+    try {
+      const { url } = await billingClient.createCustomerPortalSessionAsync(account.id);
+      portalUrl = url;
+      spinner.succeed(`Created a customer portal session for ${account.name}`);
+    } catch (error) {
+      spinner.fail('Failed to create a customer portal session');
+      throw error;
+    }
+
+    if (json) {
+      printJsonOnlyOutput({ customerPortalUrl: portalUrl });
+      return;
+    }
+
+    await openOrPrintUrlAsync(portalUrl, {
+      label: 'Customer portal',
+      open: !flags['no-open'] && !nonInteractive,
+    });
+  }
+}
@@ -0,0 +1,150 @@
+import { Args, Flags } from '@oclif/core';
+
+import { BillingEvent } from '../../analytics/AnalyticsManager';
+import { BillingClient } from '../../billing/billingClient';
+import { openOrPrintUrlAsync } from '../../billing/openUrl';
+import { PLAN_SLUGS, PlanSlug, SUBSCRIBABLE_PLANS, hasPaidSubscription } from '../../billing/plans';
+import { resolveBillingAccountAsync } from '../../billing/resolveAccount';
+import EasCommand from '../../commandUtils/EasCommand';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../commandUtils/flags';
+import Log from '../../log';
+import { ora } from '../../ora';
+import { selectAsync } from '../../prompts';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
+
+export default class BillingSubscribe extends EasCommand {
+  static override description = 'subscribe a Free account to an EAS plan';
+
+  static override args = {
+    PLAN: Args.string({
+      description: 'plan to subscribe to. Required in non-interactive mode.',
+      required: false,
+      options: [...PLAN_SLUGS],
+    }),
+  };
+
+  static override flags = {
+    account: Flags.string({
+      char: 'a',
+      description: 'Account to subscribe. Defaults to your account when you only have one.',
+    }),
+    'no-open': Flags.boolean({
+      description: 'Only print the checkout page URL instead of opening it in a browser',
+    }),
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.LoggedIn,
+    ...this.ContextOptions.Analytics,
+  };
+
+  async runAsync(): Promise<void> {
+    const {
+      args: { PLAN },
+      flags,
+    } = await this.parse(BillingSubscribe);
+    const { json, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+    if (json) {
+      enableJsonOutput();
+    }
+
+    let planSlug = PLAN as PlanSlug | undefined;
+
+    const {
+      analytics,
+      loggedIn: { graphqlClient, actor, authenticationInfo },
+    } = await this.getContextAsync(BillingSubscribe, { nonInteractive });
+
+    const account = await resolveBillingAccountAsync({
+      graphqlClient,
+      actor,
+      accountName: flags.account,
+      nonInteractive,
+      subscriptionFilter: 'unsubscribed',
+    });
+
+    const analyticsProperties = {
+      account_id: account.id,
+      json,
+      non_interactive: nonInteractive,
+    };
+
+    const { subscription } = account;
+
+    if (hasPaidSubscription(subscription)) {
+      analytics.logEvent(BillingEvent.SUBSCRIBE_COMMAND, {
+        ...analyticsProperties,
+        already_subscribed: true,
+      });
+      if (json) {
+        printJsonOnlyOutput({
+          alreadySubscribed: true,
+          currentPlan: subscription?.name ?? null,
+        });
+        return;
+      }
+      Log.warn(
+        `Account ${account.name} is already subscribed${
+          subscription?.name ? ` to the ${subscription.name} plan` : ''
+        }.`
+      );
+      Log.log('To change or cancel your plan, run eas billing:manage.');
+      return;
+    }
+
+    if (!planSlug && nonInteractive) {
+      throw new Error('The plan argument is required in non-interactive mode.');
+    }
+
+    if (!planSlug) {
+      planSlug = await selectAsync(
+        'Select a plan:',
+        PLAN_SLUGS.map(slug => ({
+          title: SUBSCRIBABLE_PLANS[slug].label,
+          value: slug,
+        }))
+      );
+    }
+
+    const plan = SUBSCRIBABLE_PLANS[planSlug];
+
+    analytics.logEvent(BillingEvent.SUBSCRIBE_COMMAND, {
+      ...analyticsProperties,
+      already_subscribed: false,
+      plan: planSlug,
+    });
+
+    const billingClient = new BillingClient(authenticationInfo);
+
+    const spinner = ora(`Creating a checkout session for the ${plan.label} plan`).start();
+    let checkoutUrl: string;
+    try {
+      const session = await billingClient.createCheckoutSessionAsync(account.id, plan.planType);
+      if (!session.url) {
+        throw new Error('The checkout session did not include a URL.');
+      }
+      checkoutUrl = session.url;
+      spinner.succeed(`Created a checkout session for the ${plan.label} plan`);
+    } catch (error) {
+      spinner.fail('Failed to create a checkout session');
+      throw error;
+    }
+
+    if (json) {
+      printJsonOnlyOutput({ checkoutUrl, alreadySubscribed: false });
+      return;
+    }
+
+    Log.log(
+      `Complete your subscription to the ${plan.label} plan for ${account.name} in Stripe checkout.`
+    );
+    await openOrPrintUrlAsync(checkoutUrl, {
+      label: 'Checkout page',
+      open: !flags['no-open'] && !nonInteractive,
+    });
+  }
+}
@@ -1,4 +1,4 @@
-import { ExpoConfig, getConfigFilePaths } from '@expo/config';
+import { ExpoConfig } from '@expo/config';
 import { App } from '@expo/apple-utils';
 import { Flags } from '@oclif/core';
 import chalk from 'chalk';
@@ -30,7 +30,7 @@ import { WorkflowRunQuery } from '../graphql/queries/WorkflowRunQuery';
 import Log, { learnMore } from '../log';
 import { confirmAsync, selectAsync } from '../prompts';
 import { ora } from '../ora';
-import { getPrivateExpoConfigAsync } from '../project/expoConfig';
+import { detectProjectSdkVersionAsync } from '../project/detectProjectSdkVersionAsync';
 import { findProjectIdByAccountNameAndSlugNullableAsync } from '../project/fetchOrCreateProjectIDForWriteToConfigWithConfirmationAsync';
 import { uploadAccountScopedFileAsync } from '../project/uploadAccountScopedFileAsync';
 import { uploadAccountScopedProjectSourceAsync } from '../project/uploadAccountScopedProjectSourceAsync';
@@ -48,20 +48,6 @@ function deriveBundleIdSlug(bundleId: string): string {
  return bundleId.split('.').filter(Boolean).pop()!;
 }

-export async function detectProjectSdkVersionAsync(
-  projectDir: string
-): Promise<string | undefined> {
-  const paths = getConfigFilePaths(projectDir);
-  if (!paths.staticConfigPath && !paths.dynamicConfigPath) {
-    return;
-  }
-  try {
-    return (await getPrivateExpoConfigAsync(projectDir)).sdkVersion;
-  } catch {
-    return;
-  }
-}
-
 export function toRepackTargetSdkVersion(sdkVersion: string | undefined): string | undefined {
  const coerced = semver.coerce(sdkVersion);
  return coerced ? `${coerced.major}.0.0` : sdkVersion;
@@ -6,6 +6,7 @@ import {
  AppPlatform,
  CreateDeviceRunSessionMutation,
  DeviceRunSessionByIdQuery,
+  DeviceRunSessionResourceClass,
  DeviceRunSessionStatus,
  DeviceRunSessionType,
  JobRunStatus,
@@ -23,6 +24,7 @@ import {
  loadSimulatorEnvAsync,
  resetSimulatorEnvAsync,
 } from '../../../simulator/env';
+import { resolveExpoGoSdkVersionAsync } from '../../../simulator/expoGo';
 import Simulator from '../index';

 jest.mock('fs-extra');
@@ -45,6 +47,7 @@ jest.mock('../../../simulator/env', () => ({
  loadSimulatorEnvAsync: jest.fn(),
  resetSimulatorEnvAsync: jest.fn(),
 }));
+jest.mock('../../../simulator/expoGo');
 jest.mock('../../../prompts');
 jest.mock('../../../ora', () => ({
  ora: jest.fn(() => {
@@ -78,6 +81,7 @@ const mockAvailabilityByAppIdAsync = jest.mocked(DeviceRunSessionAvailabilityQue
 const mockByIdAsync = jest.mocked(DeviceRunSessionQuery.byIdAsync);
 const mockLoadSimulatorEnvAsync = jest.mocked(loadSimulatorEnvAsync);
 const mockResetSimulatorEnvAsync = jest.mocked(resetSimulatorEnvAsync);
+const mockResolveExpoGoSdkVersionAsync = jest.mocked(resolveExpoGoSdkVersionAsync);
 const mockOra = jest.mocked(ora);
 const mockPromptAsync = jest.mocked(promptAsync);

@@ -161,6 +165,7 @@ describe(Simulator, () => {
    mockByIdAsync.mockResolvedValue(makeDeviceRunSession());
    mockLoadSimulatorEnvAsync.mockResolvedValue();
    mockResetSimulatorEnvAsync.mockResolvedValue();
+    mockResolveExpoGoSdkVersionAsync.mockResolvedValue('55.0.0');
    jest.mocked(fs.writeFile).mockResolvedValue(undefined as never);
  });

@@ -392,6 +397,26 @@ describe(Simulator, () => {
    });
  });

+  it('passes --max-idle-time-minutes to the createDeviceRunSession mutation', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--max-idle-time-minutes',
+      '30',
+    ]);
+    await command.runAsync();
+
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(graphqlClient, {
+      appId: 'project-123',
+      name: undefined,
+      packageVersion: undefined,
+      platform: AppPlatform.Ios,
+      type: DeviceRunSessionType.AgentDevice,
+      maxIdleTimeMinutes: 30,
+    });
+  });
+
  it(`throws when ${EAS_SIMULATOR_SESSION_ID} is already present with --no-force`, async () => {
    process.env[EAS_SIMULATOR_SESSION_ID] = 'existing-session';

@@ -498,6 +523,219 @@ describe(Simulator, () => {
    );
  });

+  it('omits resourceClass when --resource-class is not set', async () => {
+    const { command } = createCommand(['--platform', 'ios', '--non-interactive']);
+    await command.runAsync();
+
+    expect(mockCreateDeviceRunSessionAsync.mock.calls[0][1]).not.toHaveProperty('resourceClass');
+  });
+
+  it.each([
+    ['large', DeviceRunSessionResourceClass.Large],
+    ['medium', DeviceRunSessionResourceClass.Medium],
+  ] as const)(
+    'forwards --resource-class %s to the create mutation',
+    async (flag, resourceClass) => {
+      const { command } = createCommand([
+        '--platform',
+        'ios',
+        '--non-interactive',
+        '--resource-class',
+        flag,
+      ]);
+      await command.runAsync();
+
+      expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+        graphqlClient,
+        expect.objectContaining({ resourceClass })
+      );
+    }
+  );
+
+  it('forwards --build-id to the create mutation', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--build-id',
+      '  8d8b713c-1834-4bd3-91e6-46f895422cbc  ',
+    ]);
+    await command.runAsync();
+
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      expect.objectContaining({ buildId: '8d8b713c-1834-4bd3-91e6-46f895422cbc' })
+    );
+  });
+
+  it('forwards --application-archive-url to the create mutation', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'android',
+      '--non-interactive',
+      '--application-archive-url',
+      '  https://example.test/builds/app.apk  ',
+    ]);
+    await command.runAsync();
+
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      expect.objectContaining({
+        applicationArchiveUrl: 'https://example.test/builds/app.apk',
+      })
+    );
+  });
+
+  it.each([
+    ['ios', AppPlatform.Ios],
+    ['android', AppPlatform.Android],
+  ] as const)(
+    'forwards Expo Go and the project SDK for %s when --expo-go is passed',
+    async (platformFlag, appPlatform) => {
+      const { command } = createCommand([
+        '--platform',
+        platformFlag,
+        '--non-interactive',
+        '--expo-go',
+      ]);
+
+      await command.runAsync();
+
+      expect(mockResolveExpoGoSdkVersionAsync).toHaveBeenCalledWith({
+        projectDir,
+        sdkVersion: undefined,
+      });
+      expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+        graphqlClient,
+        expect.objectContaining({
+          expoGo: true,
+          sdkVersion: '55.0.0',
+          platform: appPlatform,
+        })
+      );
+      expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+        graphqlClient,
+        expect.not.objectContaining({ applicationArchiveUrl: expect.anything() })
+      );
+    }
+  );
+
+  it('uses --sdk-version to select Expo Go', async () => {
+    mockResolveExpoGoSdkVersionAsync.mockResolvedValueOnce('57.0.0');
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--expo-go',
+      '--sdk-version',
+      '57.0.0',
+    ]);
+
+    await command.runAsync();
+
+    expect(mockResolveExpoGoSdkVersionAsync).toHaveBeenCalledWith({
+      projectDir,
+      sdkVersion: '57.0.0',
+    });
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      expect.objectContaining({ expoGo: true, sdkVersion: '57.0.0' })
+    );
+  });
+
+  it('forwards repeated launch arguments and a URL to open', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--build-id',
+      '8d8b713c-1834-4bd3-91e6-46f895422cbc',
+      '--launch-arg',
+      '--uitesting',
+      '--launch-arg',
+      'true',
+      '--open-url',
+      '  exp://example.test  ',
+    ]);
+
+    await command.runAsync();
+
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      expect.objectContaining({
+        launchArgs: ['--uitesting', 'true'],
+        openUrl: 'exp://example.test',
+      })
+    );
+  });
+
+  it.each([
+    ['--launch-arg', '--uitesting'],
+    ['--open-url', 'exp://example.test'],
+  ])('rejects %s without an application source', async (launchFlag, launchValue) => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      launchFlag,
+      launchValue,
+    ]);
+
+    await expect(command.runAsync()).rejects.toThrow(
+      'Launch options require an application source.'
+    );
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects --sdk-version without --expo-go', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--sdk-version',
+      '57',
+    ]);
+
+    await expect(command.runAsync()).rejects.toThrow(
+      'The --sdk-version flag can only be used with --expo-go.'
+    );
+    expect(mockResolveExpoGoSdkVersionAsync).not.toHaveBeenCalled();
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects passing --build-id and --application-archive-url together', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--build-id',
+      '8d8b713c-1834-4bd3-91e6-46f895422cbc',
+      '--application-archive-url',
+      'https://example.test/builds/app.tar.gz',
+    ]);
+
+    await expect(command.runAsync()).rejects.toThrow();
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['--build-id', '8d8b713c-1834-4bd3-91e6-46f895422cbc'],
+    ['--application-archive-url', 'https://example.test/builds/app.tar.gz'],
+  ])('rejects passing --expo-go with %s', async (sourceFlag, sourceValue) => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--expo-go',
+      sourceFlag,
+      sourceValue,
+    ]);
+
+    await expect(command.runAsync()).rejects.toThrow();
+    expect(mockResolveExpoGoSdkVersionAsync).not.toHaveBeenCalled();
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
  it('stops the simulator session when interrupted before the session is ready', async () => {
    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(code => {
      throw new Error(`process.exit(${code})`);
@@ -28,7 +28,10 @@ import {
  resetSimulatorEnvAsync,
  writeSimulatorEnvAsync,
 } from '../../simulator/env';
+import { resolveExpoGoSdkVersionAsync } from '../../simulator/expoGo';
 import {
+  DEVICE_RUN_SESSION_RESOURCE_CLASS_BY_FLAG_VALUE,
+  DEVICE_RUN_SESSION_RESOURCE_CLASS_FLAG_VALUES,
  DEVICE_RUN_SESSION_TYPE_BY_FLAG_VALUE,
  DEVICE_RUN_SESSION_TYPE_FLAG_VALUES,
  DeviceRunSessionRemoteConfig,
@@ -72,6 +75,33 @@ export default class Simulator extends EasCommand {
      description:
        'Virtual device to start for the session. On iOS, a Simulator device name or UDID (e.g. "iPhone 16 Pro"). On Android, an AVD hardware profile id (e.g. "pixel_7"). Defaults to a device chosen by the runner.',
    }),
+    'build-id': Flags.string({
+      description: 'EAS Build to install and launch before the simulator session is ready.',
+      exclusive: ['application-archive-url', 'expo-go'],
+    }),
+    'application-archive-url': Flags.string({
+      description:
+        'Application archive URL to download, install, and launch before the simulator session is ready.',
+      exclusive: ['build-id', 'expo-go'],
+    }),
+    'expo-go': Flags.boolean({
+      description:
+        "Install and launch Expo Go matching the current project's Expo SDK before the simulator session is ready.",
+      exclusive: ['build-id', 'application-archive-url'],
+    }),
+    'sdk-version': Flags.string({
+      description:
+        'Expo SDK version used to select Expo Go when --expo-go is passed. Defaults to the current project SDK.',
+    }),
+    'launch-arg': Flags.string({
+      description:
+        'Argument passed to the installed application when it launches. Repeat for multiple arguments.',
+      multiple: true,
+    }),
+    'open-url': Flags.string({
+      description:
+        'Expo or development-client URL to open in the installed application after it launches.',
+    }),
    type: Flags.option({
      description: 'Type of simulator session to create',
      options: Object.values(DEVICE_RUN_SESSION_TYPE_FLAG_VALUES),
@@ -86,6 +116,16 @@ export default class Simulator extends EasCommand {
        'Maximum duration of the simulator session in minutes before it is automatically stopped. Only customizable on paid plans. Defaults to a value derived from the job run priority when omitted.',
      min: 0,
    }),
+    'max-idle-time-minutes': Flags.integer({
+      description:
+        'Stop the simulator session automatically after this many minutes without session activity. When omitted, the session has no idle timeout and runs until its maximum duration.',
+      min: 0,
+    }),
+    'resource-class': Flags.option({
+      description: 'The instance type that will be used to run this simulator session',
+      hidden: true,
+      options: Object.values(DEVICE_RUN_SESSION_RESOURCE_CLASS_FLAG_VALUES),
+    })(),
    force: Flags.boolean({
      description:
        '[default: true] Create a new simulator session even when an existing simulator session is present in the environment.',
@@ -139,6 +179,28 @@ export default class Simulator extends EasCommand {
    // --name as if it had been omitted rather than surfacing a validation error.
    const name = flags.name?.trim() || undefined;
    const deviceIdentifier = flags.device?.trim() || undefined;
+    const buildId = flags['build-id']?.trim() || undefined;
+    const applicationArchiveUrlFromFlag = flags['application-archive-url']?.trim() || undefined;
+    const sdkVersionFromFlag = flags['sdk-version']?.trim() || undefined;
+    const launchArgs = flags['launch-arg'];
+    const openUrl = flags['open-url']?.trim() || undefined;
+    const resourceClass = flags['resource-class']
+      ? DEVICE_RUN_SESSION_RESOURCE_CLASS_BY_FLAG_VALUE[flags['resource-class']]
+      : undefined;
+
+    if (sdkVersionFromFlag && !flags['expo-go']) {
+      throw new EasCommandError('The --sdk-version flag can only be used with --expo-go.');
+    }
+    if (
+      (launchArgs?.length || openUrl) &&
+      !buildId &&
+      !applicationArchiveUrlFromFlag &&
+      !flags['expo-go']
+    ) {
+      throw new EasCommandError(
+        'Launch options require an application source. Pass --build-id, --application-archive-url, or --expo-go.'
+      );
+    }

    await loadSimulatorEnvAsync(projectDir);
    const existingDeviceRunSessionId = process.env[EAS_SIMULATOR_SESSION_ID];
@@ -149,6 +211,9 @@ export default class Simulator extends EasCommand {
    }

    const platform = await resolvePlatformAsync(flags.platform, nonInteractive);
+    const expoGoSdkVersion = flags['expo-go']
+      ? await resolveExpoGoSdkVersionAsync({ projectDir, sdkVersion: sdkVersionFromFlag })
+      : undefined;

    if (existingDeviceRunSessionId) {
      Log.warn(
@@ -171,7 +236,16 @@ export default class Simulator extends EasCommand {
        type: DEVICE_RUN_SESSION_TYPE_BY_FLAG_VALUE[flags.type],
        packageVersion: flags['package-version'],
        deviceIdentifier,
+        ...(buildId ? { buildId } : {}),
+        ...(applicationArchiveUrlFromFlag
+          ? { applicationArchiveUrl: applicationArchiveUrlFromFlag }
+          : {}),
+        ...(expoGoSdkVersion ? { expoGo: true, sdkVersion: expoGoSdkVersion } : {}),
+        ...(launchArgs?.length ? { launchArgs } : {}),
+        ...(openUrl ? { openUrl } : {}),
+        ...(resourceClass ? { resourceClass } : {}),
        maxRunTimeMinutes: flags['max-duration-minutes'],
+        maxIdleTimeMinutes: flags['max-idle-time-minutes'],
      });
      deviceRunSessionId = session.id;
      nullthrows(session.turtleJobRun?.id, 'Expected simulator session to start');
@@ -2173,6 +2173,11 @@ export type AppNotificationPreferenceInput = {
 export type AppObserve = {
  __typename?: 'AppObserve';
  appVersions: Array<AppObserveAppVersion>;
+  /**
+   * A single custom event by the `id` of an `AppObserveCustomEvent`. Null when the app has no
+   * such event, including when it has aged out of retention.
+   */
+  customEvent?: Maybe<AppObserveCustomEvent>;
  customEventCounts: AppObserveCustomEventCounts;
  customEventList: AppObserveCustomEventListConnection;
  customEventNames: AppObserveCustomEventNames;
@@ -2185,6 +2190,14 @@ export type AppObserve = {
  errorStats: AppObserveErrorStats;
  /** Time-bucketed exception counts split into fatal vs non-fatal, for the stacked-bar chart. */
  errorTimeSeries: AppObserveErrorTimeSeries;
+  /**
+   * A single metric event by the `id` of an `AppObserveEvent`. Null when the app has no such
+   * event, including when it has aged out of retention or the id is not one this API issued.
+   *
+   * `sessionEventCount` and `userEventCount` are always null here: they are aggregates over a
+   * time range, and a single event does not supply one.
+   */
+  event?: Maybe<AppObserveEvent>;
  events: AppObserveEventsConnection;
  /** Highest Expo SDK version seen in telemetry over the trailing 30 days; null when none was reported. */
  latestExpoSdkVersion?: Maybe<Scalars['String']['output']>;
@@ -2208,6 +2221,7 @@ export type AppObserve = {
   * universe used by `appVersions` headline counts.
   */
  uniqueActiveUserCount: Scalars['Int']['output'];
+  /** Update download activity (the Recent updates list). Not available on the free tier or legacy plans. */
  updates: AppObserveUpdatesConnection;
 };

@@ -2217,6 +2231,11 @@ export type AppObserveAppVersionsArgs = {
 };


+export type AppObserveCustomEventArgs = {
+  id: Scalars['ID']['input'];
+};
+
+
 export type AppObserveCustomEventCountsArgs = {
  input: AppObserveCustomEventCountsInput;
 };
@@ -2242,6 +2261,7 @@ export type AppObserveCustomEventNamesArgs = {
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
  orderBy?: InputMaybe<AppObserveCustomEventNamesOrderBy>;
  platform?: InputMaybe<AppObservePlatform>;
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -2249,6 +2269,7 @@ export type AppObserveCustomEventNamesArgs = {
 export type AppObserveEnvironmentsArgs = {
  endTime?: InputMaybe<Scalars['DateTime']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime?: InputMaybe<Scalars['DateTime']['input']>;
 };

@@ -2273,6 +2294,11 @@ export type AppObserveErrorTimeSeriesArgs = {
 };


+export type AppObserveEventArgs = {
+  id: Scalars['ID']['input'];
+};
+
+
 export type AppObserveEventsArgs = {
  after?: InputMaybe<Scalars['String']['input']>;
  before?: InputMaybe<Scalars['String']['input']>;
@@ -2479,7 +2505,9 @@ export type AppObserveCustomEventCountsInput = {
  environment?: InputMaybe<Scalars['String']['input']>;
  eventName: Scalars['String']['input'];
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
-  platform: AppObservePlatform;
+  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. One of platform or platforms is required. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -2508,6 +2536,8 @@ export type AppObserveCustomEventListFilter = {
  eventName?: InputMaybe<Scalars['String']['input']>;
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  propertyFilters?: InputMaybe<Array<AppObserveCustomEventPropertyFilter>>;
  sessionId?: InputMaybe<Scalars['String']['input']>;
  startTime?: InputMaybe<Scalars['DateTime']['input']>;
@@ -2615,6 +2645,8 @@ export type AppObserveErrorGroupBreakdownInput = {
  fingerprint: Scalars['String']['input'];
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -2647,6 +2679,8 @@ export type AppObserveErrorGroupsInput = {
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
  orderBy?: InputMaybe<AppObserveErrorGroupsOrderBy>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  /** Restrict to fatal-only or non-fatal-only errors. */
  severity?: InputMaybe<AppObserveErrorSeverity>;
  /** Restrict to a capture source (e.g. global). */
@@ -2710,6 +2744,8 @@ export type AppObserveErrorStatsInput = {
  environment?: InputMaybe<Scalars['String']['input']>;
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -2746,6 +2782,8 @@ export type AppObserveErrorTimeSeriesInput = {
  fingerprint?: InputMaybe<Scalars['String']['input']>;
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -2817,6 +2855,8 @@ export type AppObserveEventsFilter = {
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
  metricName?: InputMaybe<Scalars['String']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  routeName?: InputMaybe<Scalars['String']['input']>;
  sessionId?: InputMaybe<Scalars['String']['input']>;
  startTime?: InputMaybe<Scalars['DateTime']['input']>;
@@ -2871,6 +2911,8 @@ export type AppObserveNavigationRoutesFilter = {
  endTime: Scalars['DateTime']['input'];
  environment?: InputMaybe<Scalars['String']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  routeNames?: InputMaybe<Array<Scalars['String']['input']>>;
  startTime: Scalars['DateTime']['input'];
 };
@@ -2924,6 +2966,8 @@ export type AppObserveOverviewEngagementInput = {
  endTime: Scalars['DateTime']['input'];
  environment?: InputMaybe<Scalars['String']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -2971,6 +3015,8 @@ export type AppObserveOverviewStabilityInput = {
  endTime: Scalars['DateTime']['input'];
  environment?: InputMaybe<Scalars['String']['input']>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -2978,9 +3024,13 @@ export type AppObserveOverviewUpdate = {
  __typename?: 'AppObserveOverviewUpdate';
  /** Null for the embedded bundle. */
  appUpdateId?: Maybe<Scalars['ID']['output']>;
-  /** Downloads recorded in range across platforms; null when none were recorded (and always for the embedded bundle). */
+  /**
+   * Downloads recorded in range across platforms; null when none were recorded
+   * (and always for the embedded bundle). Download data is paid-only: on the
+   * free tier and legacy plans this is always null.
+   */
  downloadCount?: Maybe<Scalars['Int']['output']>;
-  /** One entry per platform with downloads in range; empty for the embedded bundle. */
+  /** One entry per platform with downloads in range; empty for the embedded bundle and on the free tier and legacy plans. */
  downloads: Array<AppObserveOverviewUpdateDownload>;
  eventCount: Scalars['Int']['output'];
  firstSeenAt: Scalars['DateTime']['output'];
@@ -3092,6 +3142,8 @@ export type AppObserveReleasesInput = {
  environment?: InputMaybe<Scalars['String']['input']>;
  metricNames?: InputMaybe<Array<Scalars['String']['input']>>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -3129,6 +3181,8 @@ export type AppObserveTimeSeriesInput = {
  isEmbeddedUpdate?: InputMaybe<Scalars['Boolean']['input']>;
  metricName: Scalars['String']['input'];
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  routeName?: InputMaybe<Scalars['String']['input']>;
  startTime: Scalars['DateTime']['input'];
 };
@@ -3180,6 +3234,8 @@ export type AppObserveUpdatesInput = {
  first?: InputMaybe<Scalars['Int']['input']>;
  orderBy?: InputMaybe<AppObserveUpdatesOrderBy>;
  platform?: InputMaybe<AppObservePlatform>;
+  /** Filter to these platforms. Cannot be set together with platform. */
+  platforms?: InputMaybe<Array<AppObservePlatform>>;
  startTime: Scalars['DateTime']['input'];
 };

@@ -5234,6 +5290,16 @@ export type CreateDeviceRunSessionEventLogUploadSessionResult = {

 export type CreateDeviceRunSessionInput = {
  appId: Scalars['ID']['input'];
+  /**
+   * Application archive URL to download, install, and launch before the simulator session
+   * becomes available. Mutually exclusive with buildId and expoGo.
+   */
+  applicationArchiveUrl?: InputMaybe<Scalars['String']['input']>;
+  /**
+   * EAS Build to install and launch before the simulator session becomes available.
+   * Mutually exclusive with applicationArchiveUrl and expoGo.
+   */
+  buildId?: InputMaybe<Scalars['ID']['input']>;
  /**
   * Identifier of the virtual device to start for the session. On iOS this is a
   * Simulator device name or UDID (e.g. "iPhone 16 Pro"). On Android this is an
@@ -5241,6 +5307,17 @@ export type CreateDeviceRunSessionInput = {
   * default device.
   */
  deviceIdentifier?: InputMaybe<Scalars['String']['input']>;
+  /**
+   * Install and launch Expo Go before the simulator session becomes available. The server resolves
+   * the platform-specific application archive. Mutually exclusive with buildId and
+   * applicationArchiveUrl.
+   */
+  expoGo?: InputMaybe<Scalars['Boolean']['input']>;
+  /**
+   * Arguments passed to the installed application when it is launched. Requires buildId,
+   * applicationArchiveUrl, or expoGo.
+   */
+  launchArgs?: InputMaybe<Array<Scalars['String']['input']>>;
  /**
   * Stop the session automatically after this many minutes without observed
   * session activity. Must be positive and smaller than the session's maximum
@@ -5261,12 +5338,23 @@ export type CreateDeviceRunSessionInput = {
   * session is unnamed and clients fall back to identifying it by id.
   */
  name?: InputMaybe<Scalars['String']['input']>;
+  /**
+   * Expo or development-client URL to open after launching the installed application. Requires
+   * buildId, applicationArchiveUrl, or expoGo.
+   */
+  openUrl?: InputMaybe<Scalars['String']['input']>;
  /**
   * The version of the package backing the device run session (e.g. "0.1.3-alpha.3").
   * If omitted, consumers treat the session as pinned to "latest".
   */
  packageVersion?: InputMaybe<Scalars['String']['input']>;
  platform: AppPlatform;
+  resourceClass?: InputMaybe<DeviceRunSessionResourceClass>;
+  /**
+   * Expo SDK version used to select an Expo Go application archive. Only supported when expoGo is
+   * true. If omitted, the current Expo Go archive for the platform is used.
+   */
+  sdkVersion?: InputMaybe<Scalars['String']['input']>;
  type: DeviceRunSessionType;
 };

@@ -6012,7 +6100,17 @@ export type DeploymentsMutationDeleteWorkerDeploymentByIdentifierArgs = {
 export type DeviceRunSession = {
  __typename?: 'DeviceRunSession';
  app: App;
+  /**
+   * Direct application archive URL installed and launched for this session. Null when
+   * the session uses an EAS Build or starts without an app.
+   */
+  applicationArchiveUrl?: Maybe<Scalars['String']['output']>;
  artifacts: Array<DeviceRunSessionArtifact>;
+  /**
+   * EAS Build installed and launched for this session. Null when the session uses
+   * a direct application archive URL or starts without an app.
+   */
+  build?: Maybe<Build>;
  createdAt: Scalars['DateTime']['output'];
  finishedAt?: Maybe<Scalars['DateTime']['output']>;
  id: Scalars['ID']['output'];
@@ -6145,6 +6243,11 @@ export type DeviceRunSessionQueryByIdArgs = {

 export type DeviceRunSessionRemoteConfig = AgentDeviceRunSessionRemoteConfig | AppiumRunSessionRemoteConfig | ArgentRunSessionRemoteConfig | ServeSimRunSessionRemoteConfig;

+export enum DeviceRunSessionResourceClass {
+  Large = 'LARGE',
+  Medium = 'MEDIUM'
+}
+
 export enum DeviceRunSessionStatus {
  Errored = 'ERRORED',
  InProgress = 'IN_PROGRESS',
@@ -10613,8 +10716,7 @@ export type TurtleSshSessionMutation = {
 export type TurtleSshSessionMutationCreateOrUpdateTurtleSshSessionArgs = {
  connectionConfig: TurtleSshConnectionConfigInput;
  sessionSettings: TurtleSshSessionSettingsInput;
-  turtleBuildId?: InputMaybe<Scalars['ID']['input']>;
-  turtleJobRunId?: InputMaybe<Scalars['ID']['input']>;
+  target: TurtleSshTargetInput;
 };

 export type TurtleSshSessionSettings = {
@@ -10626,6 +10728,16 @@ export type TurtleSshSessionSettingsInput = {
  idleTimeoutSeconds: Scalars['Int']['input'];
 };

+export type TurtleSshTargetInput = {
+  id: Scalars['ID']['input'];
+  type: TurtleSshTargetType;
+};
+
+export enum TurtleSshTargetType {
+  Build = 'BUILD',
+  JobRun = 'JOB_RUN'
+}
+
 export enum TurtleSshTransportType {
  UptermV1 = 'UPTERM_V1'
 }
@@ -13246,6 +13358,11 @@ export type WorkflowRun = ActivityTimelineProjectActivity & {
  __typename?: 'WorkflowRun';
  activityTimestamp: Scalars['DateTime']['output'];
  actor?: Maybe<Actor>;
+  /**
+   * Why the server canceled this run. Null for manually canceled runs and for
+   * runs canceled before the reason was recorded.
+   */
+  cancelReason?: Maybe<WorkflowRunCancelReason>;
  createdAt: Scalars['DateTime']['output'];
  durationSeconds?: Maybe<Scalars['Int']['output']>;
  errors: Array<WorkflowRunError>;
@@ -13272,6 +13389,17 @@ export type WorkflowRun = ActivityTimelineProjectActivity & {
  workflowRevision?: Maybe<WorkflowRevision>;
 };

+export type WorkflowRunCancelReason = WorkflowRunCancelReasonConcurrencyGroup;
+
+export type WorkflowRunCancelReasonConcurrencyGroup = {
+  __typename?: 'WorkflowRunCancelReasonConcurrencyGroup';
+  /**
+   * The newer run in the same concurrency group whose creation canceled this run.
+   * Null if that run no longer exists.
+   */
+  cancelingWorkflowRun?: Maybe<WorkflowRun>;
+};
+
 export type WorkflowRunEdge = {
  __typename?: 'WorkflowRunEdge';
  cursor: Scalars['String']['output'];
@@ -13361,7 +13489,8 @@ export enum WorkflowRunStatus {
  Failure = 'FAILURE',
  InProgress = 'IN_PROGRESS',
  New = 'NEW',
-  Success = 'SUCCESS'
+  Success = 'SUCCESS',
+  Waiting = 'WAITING'
 }

 export type WorkflowRunTimeRangeInput = {
@@ -14647,7 +14776,7 @@ export type AccountByNameQueryVariables = Exact<{
 }>;


-export type AccountByNameQuery = { __typename?: 'RootQuery', account: { __typename?: 'AccountQuery', byName: { __typename?: 'Account', id: string, name: string } } };
+export type AccountByNameQuery = { __typename?: 'RootQuery', account: { __typename?: 'AccountQuery', byName: { __typename?: 'Account', id: string, name: string, viewerUserPermission: { __typename?: 'UserPermission', id: string, permissions: Array<Permission> } } } };

 export type AccountFullUsageQueryVariables = Exact<{
  accountId: Scalars['String']['input'];
@@ -14675,6 +14804,13 @@ export type AccountBillingPeriodQueryVariables = Exact<{

 export type AccountBillingPeriodQuery = { __typename?: 'RootQuery', account: { __typename?: 'AccountQuery', byId: { __typename?: 'Account', id: string, name: string, billingPeriod: { __typename?: 'BillingPeriod', id: string, start: any, end: any, anchor: any } } } };

+export type AccountSubscriptionQueryVariables = Exact<{
+  accountId: Scalars['String']['input'];
+}>;
+
+
+export type AccountSubscriptionQuery = { __typename?: 'RootQuery', account: { __typename?: 'AccountQuery', byId: { __typename?: 'Account', id: string, subscription?: { __typename?: 'SubscriptionDetails', id: string, name?: string | null, planId?: string | null } | null } } };
+
 export type AppByIdQueryVariables = Exact<{
  appId: Scalars['String']['input'];
 }>;
@@ -4,8 +4,12 @@ import gql from 'graphql-tag';
 import { ExpoGraphqlClient } from '../../commandUtils/context/contextUtils/createGraphqlClient';
 import { withErrorHandlingAsync } from '../client';
 import {
+  AccountByNameQuery as AccountByNameQueryType,
+  AccountByNameQueryVariables,
  AccountFullUsageQuery as AccountFullUsageQueryType,
  AccountFullUsageQueryVariables,
+  AccountSubscriptionQuery as AccountSubscriptionQueryType,
+  AccountSubscriptionQueryVariables,
  AccountUsageForOverageWarningQuery,
  AccountUsageForOverageWarningQueryVariables,
 } from '../generated';
@@ -17,21 +21,28 @@ import {
 } from '../types/Account';

 export type AccountFullUsageData = NonNullable<AccountFullUsageQueryType['account']['byId']>;
+export type AccountSubscriptionInfo = NonNullable<
+  NonNullable<AccountSubscriptionQueryType['account']['byId']>['subscription']
+>;

 export const AccountQuery = {
  async getByNameAsync(
    graphqlClient: ExpoGraphqlClient,
    accountName: string
-  ): Promise<{ id: string; name: string } | null> {
+  ): Promise<AccountByNameQueryType['account']['byName'] | null> {
    const data = await withErrorHandlingAsync(
      graphqlClient
-        .query<{ account: { byName: { id: string; name: string } | null } }>(
+        .query<AccountByNameQueryType, AccountByNameQueryVariables>(
          gql`
            query AccountByName($accountName: String!) {
              account {
                byName(accountName: $accountName) {
                  id
                  name
+                  viewerUserPermission {
+                    id
+                    permissions
+                  }
                }
              }
            }
@@ -276,4 +287,34 @@ export const AccountQuery = {
      end: new Date(end),
    };
  },
+
+  async getSubscriptionAsync(
+    graphqlClient: ExpoGraphqlClient,
+    accountId: string
+  ): Promise<AccountSubscriptionInfo | null> {
+    const data = await withErrorHandlingAsync(
+      graphqlClient
+        .query<AccountSubscriptionQueryType, AccountSubscriptionQueryVariables>(
+          gql`
+            query AccountSubscription($accountId: String!) {
+              account {
+                byId(accountId: $accountId) {
+                  id
+                  subscription {
+                    id
+                    name
+                    planId
+                  }
+                }
+              }
+            }
+          `,
+          { accountId },
+          { additionalTypenames: ['Account', 'SubscriptionDetails'] }
+        )
+        .toPromise()
+    );
+
+    return data.account.byId?.subscription ?? null;
+  },
 };
@@ -0,0 +1,17 @@
+import { getConfigFilePaths } from '@expo/config';
+
+import { getPrivateExpoConfigAsync } from './expoConfig';
+
+export async function detectProjectSdkVersionAsync(
+  projectDir: string
+): Promise<string | undefined> {
+  const paths = getConfigFilePaths(projectDir);
+  if (!paths.staticConfigPath && !paths.dynamicConfigPath) {
+    return;
+  }
+  try {
+    return (await getPrivateExpoConfigAsync(projectDir)).sdkVersion;
+  } catch {
+    return;
+  }
+}
@@ -0,0 +1,50 @@
+import { detectProjectSdkVersionAsync } from '../../project/detectProjectSdkVersionAsync';
+import { resolveExpoGoSdkVersionAsync } from '../expoGo';
+
+jest.mock('../../project/detectProjectSdkVersionAsync');
+
+const projectDir = '/test/project';
+const mockDetectProjectSdkVersionAsync = jest.mocked(detectProjectSdkVersionAsync);
+
+describe(resolveExpoGoSdkVersionAsync, () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockDetectProjectSdkVersionAsync.mockResolvedValue('55.0.0');
+  });
+
+  it('normalizes the detected project SDK version', async () => {
+    await expect(resolveExpoGoSdkVersionAsync({ projectDir })).resolves.toBe('55.0.0');
+    expect(mockDetectProjectSdkVersionAsync).toHaveBeenCalledWith(projectDir);
+  });
+
+  it.each([
+    ['57', '57.0.0'],
+    ['57.0.0', '57.0.0'],
+    ['57.0.9', '57.0.0'],
+  ])('normalizes an explicit SDK version (%s)', async (sdkVersion, expectedSdkVersion) => {
+    await expect(resolveExpoGoSdkVersionAsync({ projectDir, sdkVersion })).resolves.toBe(
+      expectedSdkVersion
+    );
+    expect(mockDetectProjectSdkVersionAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects an invalid explicit SDK version', async () => {
+    await expect(
+      resolveExpoGoSdkVersionAsync({ projectDir, sdkVersion: 'not-a-version' })
+    ).rejects.toThrow(
+      'Unable to parse Expo SDK version "not-a-version". Pass a major or semantic version, such as --sdk-version 57.'
+    );
+    expect(mockDetectProjectSdkVersionAsync).not.toHaveBeenCalled();
+  });
+
+  it.each([undefined, 'UNVERSIONED'])(
+    'rejects an undetectable SDK version (%s)',
+    async sdkVersion => {
+      mockDetectProjectSdkVersionAsync.mockResolvedValue(sdkVersion);
+
+      await expect(resolveExpoGoSdkVersionAsync({ projectDir })).rejects.toThrow(
+        "Unable to determine this project's Expo SDK version, so Expo Go could not be selected."
+      );
+    }
+  );
+});
@@ -1,5 +1,6 @@
-import { DeviceRunSessionType } from '../../graphql/generated';
+import { DeviceRunSessionResourceClass, DeviceRunSessionType } from '../../graphql/generated';
 import {
+  DEVICE_RUN_SESSION_RESOURCE_CLASS_BY_FLAG_VALUE,
  DEVICE_RUN_SESSION_TYPE_BY_FLAG_VALUE,
  formatRemoteSessionInstructions,
  getRemoteSessionEnvironmentVariables,
@@ -37,3 +38,14 @@ describe('Appium simulator configuration', () => {
    expect(instructions).not.toContain('https://appium.example.test');
  });
 });
+
+describe('simulator resource class flags', () => {
+  it('maps CLI values to the GraphQL enum', () => {
+    expect(DEVICE_RUN_SESSION_RESOURCE_CLASS_BY_FLAG_VALUE.large).toBe(
+      DeviceRunSessionResourceClass.Large
+    );
+    expect(DEVICE_RUN_SESSION_RESOURCE_CLASS_BY_FLAG_VALUE.medium).toBe(
+      DeviceRunSessionResourceClass.Medium
+    );
+  });
+});
@@ -0,0 +1,28 @@
+import semver from 'semver';
+
+import { EasCommandError } from '../commandUtils/errors';
+import { detectProjectSdkVersionAsync } from '../project/detectProjectSdkVersionAsync';
+
+export async function resolveExpoGoSdkVersionAsync({
+  projectDir,
+  sdkVersion: sdkVersionFromFlag,
+}: {
+  projectDir: string;
+  sdkVersion?: string;
+}): Promise<string> {
+  const sdkVersion = sdkVersionFromFlag ?? (await detectProjectSdkVersionAsync(projectDir));
+  const sdkMajorVersion = semver.coerce(sdkVersion)?.major;
+  if (!sdkMajorVersion) {
+    if (sdkVersionFromFlag) {
+      throw new EasCommandError(
+        `Unable to parse Expo SDK version "${sdkVersionFromFlag}". Pass a major or semantic version, such as --sdk-version 57.`
+      );
+    }
+    throw new EasCommandError(
+      "Unable to determine this project's Expo SDK version, so Expo Go could not be selected. " +
+        'Make sure the project has Expo installed and a valid app config, or use --build-id or --application-archive-url instead.'
+    );
+  }
+
+  return `${sdkMajorVersion}.0.0`;
+}
@@ -1,4 +1,8 @@
-import { DeviceRunSessionByIdQuery, DeviceRunSessionType } from '../graphql/generated';
+import {
+  DeviceRunSessionByIdQuery,
+  DeviceRunSessionResourceClass,
+  DeviceRunSessionType,
+} from '../graphql/generated';
 import { link } from '../log';

 type DeviceRunSessionByIdResult = DeviceRunSessionByIdQuery['deviceRunSessions']['byId'];
@@ -37,6 +41,23 @@ export function deviceRunSessionTypeToFlagValue(type: DeviceRunSessionType): str
  return DEVICE_RUN_SESSION_TYPE_FLAG_VALUES[type];
 }

+export const DEVICE_RUN_SESSION_RESOURCE_CLASS_FLAG_VALUES: Record<
+  DeviceRunSessionResourceClass,
+  string
+> = {
+  [DeviceRunSessionResourceClass.Large]: 'large',
+  [DeviceRunSessionResourceClass.Medium]: 'medium',
+};
+
+export const DEVICE_RUN_SESSION_RESOURCE_CLASS_BY_FLAG_VALUE = Object.fromEntries(
+  (
+    Object.entries(DEVICE_RUN_SESSION_RESOURCE_CLASS_FLAG_VALUES) as [
+      DeviceRunSessionResourceClass,
+      string,
+    ][]
+  ).map(([resourceClass, value]) => [value, resourceClass])
+) as Record<string, DeviceRunSessionResourceClass>;
+
 export function getRemoteSessionEnvironmentVariables(
  remoteConfig: DeviceRunSessionRemoteConfig
 ): Record<string, string> {
@@ -462,6 +462,11 @@ describe('displayOverageWarning', () => {
    expect(mockWarn).toHaveBeenCalledWith(
      expect.stringContaining('Upgrade your plan to continue service.')
    );
+    expect(mockWarn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Run eas billing:subscribe starter --account test-account to upgrade to the Starter plan.'
+      )
+    );
    expect(mockWarn).toHaveBeenCalledWith(expect.stringMatching(/█+░+/));
  });

@@ -505,6 +510,11 @@ describe('displayOverageWarning', () => {
    expect(mockWarn).toHaveBeenCalledWith(
      expect.stringContaining('New builds are blocked until your billing period resets.')
    );
+    expect(mockWarn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Run eas billing:subscribe starter --account test-account to upgrade to the Starter plan.'
+      )
+    );
  });

  it('at tier: displays a paid-plan limit-reached message with pay-as-you-go warning', () => {
@@ -543,6 +553,11 @@ describe('displayOverageWarning', () => {
    expect(mockWarn).toHaveBeenCalledWith(
      expect.stringContaining('New builds are blocked until your billing period resets.')
    );
+    expect(mockWarn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Run eas billing:subscribe starter --account test-account to upgrade to the Starter plan.'
+      )
+    );
  });

  it('over tier: displays a paid-plan overage count and accrued cost', () => {
@@ -1,5 +1,6 @@
 import chalk from 'chalk';

+import { formatStarterSubscribeCommand } from '../../billing/plans';
 import { ExpoGraphqlClient } from '../../commandUtils/context/contextUtils/createGraphqlClient';
 import { AccountQuery } from '../../graphql/queries/AccountQuery';
 import Log, { link } from '../../log';
@@ -136,6 +137,7 @@ export function displayOverageWarning({
  overageCostCents: number;
 }): void {
  const billingUrl = `https://expo.dev/accounts/${name}/settings/billing`;
+  const upgradeHint = ` Run ${formatStarterSubscribeCommand(name)} to upgrade to the Starter plan.`;

  if (tier === 'approaching') {
    const percentUsed = calculatePercentUsed(planValue, limit);
@@ -149,7 +151,8 @@ export function displayOverageWarning({
    Log.warn(
      hasFreePlan
        ? "You won't be able to start new builds once you reach the limit. " +
-            link(billingUrl, { text: 'Upgrade your plan to continue service.', dim: false })
+            link(billingUrl, { text: 'Upgrade your plan to continue service.', dim: false }) +
+            upgradeHint
        : 'Additional usage beyond your limit will be charged at pay-as-you-go rates. ' +
            link(billingUrl, { text: 'See usage in billing.', dim: false })
    );
@@ -163,7 +166,8 @@ export function displayOverageWarning({
    Log.warn(
      hasFreePlan
        ? 'New builds are blocked until your billing period resets. ' +
-            link(billingUrl, { text: 'Upgrade your plan to continue building.', dim: false })
+            link(billingUrl, { text: 'Upgrade your plan to continue building.', dim: false }) +
+            upgradeHint
        : 'Additional builds will be charged at pay-as-you-go rates. ' +
            link(billingUrl, { text: 'See usage in billing.', dim: false })
    );
@@ -1,6 +1,6 @@
 {
  "name": "eas-cli-local-build-plugin",
-  "version": "22.2.0",
+  "version": "22.6.0",
  "description": "Tool for running EAS compatible builds on a local machine.",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
@@ -26,7 +26,7 @@
    "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\""
  },
  "dependencies": {
-    "@expo/build-tools": "22.2.0",
+    "@expo/build-tools": "22.6.0",
    "@expo/eas-build-job": "22.0.0",
    "@expo/logger": "22.0.0",
    "@expo/spawn-async": "^1.7.2",
@@ -1,6 +1,6 @@
 {
  "name": "@expo/steps",
-  "version": "22.1.0",
+  "version": "22.4.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
  "author": "Expo <[email protected]>",
@@ -12,7 +12,7 @@ import type { BuildStepOutputAccessor } from './BuildStep';
 import { BuildStepGlobalContext } from './BuildStepContext';
 import { BuildStepEnv } from './BuildStepEnv';
 import { BuildStepInput } from './BuildStepInput';
-import { BuildStepRuntimeError } from './errors';
+import { BuildStepConditionEvaluationError, BuildStepRuntimeError } from './errors';
 import {
  resolveInterpolatedTarget,
  stringifyInterpolatedResult,
@@ -77,7 +77,20 @@ export class BuildStepCompositeFunctionScope {
    if (this.parent && !this.parent.isActive(evaluate, runByDefault)) {
      return false;
    }
-    this.cachedIsActive ??= this.evaluateCallIfCondition(evaluate, runByDefault);
+    if (this.cachedIsActive === undefined) {
+      try {
+        this.cachedIsActive = this.evaluateCallIfCondition(evaluate, runByDefault);
+      } catch (err) {
+        // An unevaluable gate skips the call, cache the skip before throwing.
+        // Only the first child reports the error, the rest skip silently.
+        this.cachedIsActive = false;
+        throw new BuildStepConditionEvaluationError(
+          `composite function call "${this.compositeFunctionPath}"`,
+          this.ifCondition ?? '',
+          { cause: err instanceof Error ? err : undefined }
+        );
+      }
+    }
    return this.cachedIsActive;
  }

@@ -7,6 +7,7 @@ import { BuildStep } from './BuildStep';
 import { BuildStepGlobalContext } from './BuildStepContext';
 import { CompositeBuildStep } from './CompositeBuildStep';
 import { StepMetricResult } from './StepMetrics';
+import { BuildStepConditionEvaluationError } from './errors';
 import { AnchorHooks, HookEntry } from './hooks';
 import { evaluateIfCondition } from './utils/jsepEval';

@@ -279,15 +280,17 @@ export async function executeHookStepsAsync(
  return { failedLocally, firstError };
 }

-// Shared wording for unevaluable `if:` gates. Callers pass the step's own
-// `if:`, but the throw may come from a composite call-site `if:` evaluated via
-// the step's scope. In that case the quoted condition is not the one that failed.
+// Shared wording for unevaluable `if:` gates.
 function logConditionEvaluationError(
  logger: bunyan,
  err: unknown,
  subject: string,
  ifCondition: string | undefined
 ): void {
+  if (err instanceof BuildStepConditionEvaluationError) {
+    ({ subject, ifCondition } = err);
+    err = err.cause ?? err;
+  }
  logger.error({ err });
  logger.error(
    `Runner failed to evaluate if it should execute ${subject}${
@@ -2,16 +2,26 @@ import { JobInterpolationContext } from '@expo/eas-build-job';
 import { instance, mock, when } from 'ts-mockito';

 import { createGlobalContextMock } from './utils/context';
+import { getError } from './utils/error';
 import { BuildStep } from '../BuildStep';
 import { BuildStepCompositeFunctionScope } from '../BuildStepCompositeFunctionScope';
 import { BuildStepInput, BuildStepInputValueTypeName } from '../BuildStepInput';
 import { BuildStepOutput } from '../BuildStepOutput';
+import { BuildStepConditionEvaluationError } from '../errors';
 import { interpolateJobContext } from '../interpolation';

 describe(BuildStepCompositeFunctionScope, () => {
  const baseContext = {} as unknown as JobInterpolationContext;

-  function makeScope(): BuildStepCompositeFunctionScope {
+  function makeScope({
+    ifCondition,
+    parent,
+    compositeFunctionPath = 'test-action',
+  }: {
+    ifCondition?: string;
+    parent?: BuildStepCompositeFunctionScope;
+    compositeFunctionPath?: string;
+  } = {}): BuildStepCompositeFunctionScope {
    const ctx = createGlobalContextMock();

    const versionOutput = mock<BuildStepOutput>();
@@ -29,7 +39,9 @@ describe(BuildStepCompositeFunctionScope, () => {
    greeting.set('hello');
    return new BuildStepCompositeFunctionScope({
      ctx,
-      compositeFunctionPath: 'test-action',
+      parent,
+      ifCondition,
+      compositeFunctionPath,
      inputs: new Map([['greeting', greeting]]),
      providedInputKeys: new Set(['greeting']),
      childrenByLocalId: new Map([['build', instance(innerStep)]]),
@@ -69,5 +81,46 @@ describe(BuildStepCompositeFunctionScope, () => {
      expect(scope.isActive(neverEvaluate, true)).toBe(true);
      expect(scope.isActive(neverEvaluate, false)).toBe(true);
    });
+
+    it('wraps an evaluation failure with the call as subject, its condition, and the raw cause', () => {
+      const rawError = new Error('boom');
+      const scope = makeScope({ ifCondition: '${{ broken }}' });
+      const error = getError(() =>
+        scope.isActive(() => {
+          throw rawError;
+        }, true)
+      );
+      expect(error).toBeInstanceOf(BuildStepConditionEvaluationError);
+      expect(error.subject).toBe('composite function call "test-action"');
+      expect(error.ifCondition).toBe('${{ broken }}');
+      expect(error.cause).toBe(rawError);
+    });
+
+    it('reports an evaluation failure once; later calls skip without re-evaluating', () => {
+      let evaluations = 0;
+      const evaluate = (): boolean => {
+        evaluations += 1;
+        throw new Error('boom');
+      };
+      const scope = makeScope({ ifCondition: '${{ broken }}' });
+      expect(() => scope.isActive(evaluate, true)).toThrow(BuildStepConditionEvaluationError);
+      expect(scope.isActive(evaluate, true)).toBe(false);
+      expect(evaluations).toBe(1);
+    });
+
+    it('propagates a parent call-site failure naming the parent scope, not the child', () => {
+      const parent = makeScope({
+        ifCondition: '${{ broken }}',
+        compositeFunctionPath: 'parent-action',
+      });
+      const child = makeScope({ parent });
+      const error = getError(() =>
+        child.isActive(() => {
+          throw new Error('boom');
+        }, true)
+      );
+      expect(error).toBeInstanceOf(BuildStepConditionEvaluationError);
+      expect(error.subject).toBe('composite function call "parent-action"');
+    });
  });
 });
@@ -4,6 +4,7 @@ import { Hooks, Step } from '@expo/eas-build-job';

 import { makeCatalog } from './StepsConfigParser-composite-functions-test-utils';
 import { createGlobalContextMock } from './utils/context';
+import { createRecordingLogger } from './utils/logger';
 import { BuildFunction } from '../BuildFunction';
 import { BuildFunctionGroup } from '../BuildFunctionGroup';
 import { BuildStepStatus } from '../BuildStep';
@@ -13,17 +14,20 @@ import { BuildStepOutput } from '../BuildStepOutput';
 import { BuildWorkflow } from '../BuildWorkflow';
 import { StepsConfigParser } from '../StepsConfigParser';
 import { WorkflowHookMetric } from '../StepMetrics';
-import { BuildStepRuntimeError } from '../errors';
+import { BuildStepConditionEvaluationError, BuildStepRuntimeError } from '../errors';

 describe('BuildWorkflow hook execution', () => {
  let ctx: BuildStepGlobalContext;
  let executionLog: string[];
  let metrics: WorkflowHookMetric[];
+  let loggedMessages: string[];

  beforeEach(async () => {
    executionLog = [];
    metrics = [];
+    loggedMessages = [];
    ctx = createGlobalContextMock({
+      logger: createRecordingLogger(loggedMessages),
      reportWorkflowHookMetric: metric => metrics.push(metric),
    });
    await fs.mkdir(ctx.defaultWorkingDirectory, { recursive: true });
@@ -650,6 +654,44 @@ describe('BuildWorkflow hook execution', () => {
      ]);
    });

+    it('attributes a broken composite call-site if: to the call, logs it once, and skips the anchor', async () => {
+      const workflow = await parseAsync({
+        steps: [{ uses: 'eas/install_node_modules' }],
+        hooks: {
+          before_install_node_modules: [
+            {
+              uses: './.eas/functions/setup',
+              id: 'setup',
+              if: '${{ nonexistent.object.property }}',
+            },
+          ],
+        },
+        externalFunctions: [anchorFunction(), recordingFunction('one'), recordingFunction('two')],
+        compositeFunctionCatalog: {
+          './.eas/functions/setup': {
+            runs: {
+              steps: [
+                { id: 'first', uses: 'test/one' },
+                { id: 'second', uses: 'test/two', if: '${{ always() }}' },
+              ],
+            },
+          },
+        },
+      });
+      await expect(workflow.executeAsync()).rejects.toThrow(BuildStepConditionEvaluationError);
+      expect(executionLog).toEqual([]);
+      expect(hookStepStatuses(workflow)['setup__first']).toBe(BuildStepStatus.SKIPPED);
+      expect(hookStepStatuses(workflow)['setup__second']).toBe(BuildStepStatus.SKIPPED);
+      expect(workflow.buildSteps[0].status).toBe(BuildStepStatus.SKIPPED);
+      expect(metrics).toEqual([]);
+
+      const gateMessages = loggedMessages.filter(m => m.includes('Runner failed to evaluate'));
+      expect(gateMessages).toHaveLength(1);
+      expect(gateMessages[0]).toContain('composite function call "./.eas/functions/setup"');
+      expect(gateMessages[0]).toContain('${{ nonexistent.object.property }}');
+      expect(loggedMessages.join('\n')).not.toContain('${{ always() }}');
+    });
+
    it('skips every step of a composite call whose if condition is false and reports no metric', async () => {
      const workflow = await parseAsync({
        steps: [{ uses: 'eas/install_node_modules' }],
@@ -10,13 +10,18 @@ import {
 } from './StepsConfigParser-composite-functions-test-utils';
 import { createGlobalContextMock } from './utils/context';
 import { getErrorAsync } from './utils/error';
+import { createRecordingLogger } from './utils/logger';
 import { BuildFunction } from '../BuildFunction';
 import { StepsConfigParser } from '../StepsConfigParser';
 import { BuildStepStatus } from '../BuildStep';
 import { BuildStepInput, BuildStepInputValueTypeName } from '../BuildStepInput';
 import { BuildStepOutput } from '../BuildStepOutput';
 import { BuildWorkflow } from '../BuildWorkflow';
-import { BuildConfigError, BuildStepRuntimeError } from '../errors';
+import {
+  BuildConfigError,
+  BuildStepConditionEvaluationError,
+  BuildStepRuntimeError,
+} from '../errors';

 describe('StepsConfigParser local composite functions', () => {
  describe('step reference scoping', () => {
@@ -1252,4 +1257,73 @@ describe('StepsConfigParser local composite functions', () => {
      expect(show?.getOutputValueByName('out')).toBe('hello');
    });
  });
+  describe('call-site if evaluation errors', () => {
+    it('attributes a broken call-site if: to the composite call and logs it once', async () => {
+      const messages: string[] = [];
+      const workflow = await parseCompositeFunctions({
+        ctx: createGlobalContextMock({ logger: createRecordingLogger(messages) }),
+        catalog: {
+          [SETUP]: {
+            runs: {
+              steps: [
+                { id: 'first', uses: 'eas/echo', if: '${{ always() }}' },
+                { id: 'second', uses: 'eas/echo' },
+              ],
+            },
+          },
+        },
+        steps: [{ uses: SETUP, id: 'setup', if: '${{ nonexistent.object.property }}' }],
+        externalFunctions: [echoFunction()],
+      });
+
+      const error = await getErrorAsync(() => workflow.executeAsync());
+      expect(error).toBeInstanceOf(BuildStepConditionEvaluationError);
+      expect(error.ifCondition).toBe('${{ nonexistent.object.property }}');
+
+      for (const id of ['setup__first', 'setup__second']) {
+        expect(workflow.buildSteps.find(s => s.id === id)?.status).toBe(BuildStepStatus.SKIPPED);
+      }
+
+      const gateMessages = messages.filter(m => m.includes('Runner failed to evaluate'));
+      expect(gateMessages).toHaveLength(1);
+      expect(gateMessages[0]).toContain(`composite function call "${SETUP}"`);
+      expect(gateMessages[0]).toContain('${{ nonexistent.object.property }}');
+      expect(messages.join('\n')).not.toContain('${{ always() }}');
+    });
+
+    it('names the outer call when its broken if: gates a nested composite, still logging once', async () => {
+      const messages: string[] = [];
+      const workflow = await parseCompositeFunctions({
+        ctx: createGlobalContextMock({ logger: createRecordingLogger(messages) }),
+        catalog: {
+          './.eas/functions/outer': {
+            runs: {
+              steps: [
+                { uses: './.eas/functions/inner', id: 'nested' },
+                { id: 'tail', uses: 'eas/echo' },
+              ],
+            },
+          },
+          './.eas/functions/inner': {
+            runs: { steps: [{ id: 'leaf', uses: 'eas/echo' }] },
+          },
+        },
+        steps: [
+          { uses: './.eas/functions/outer', id: 'top', if: '${{ nonexistent.object.property }}' },
+        ],
+        externalFunctions: [echoFunction()],
+      });
+
+      const error = await getErrorAsync(() => workflow.executeAsync());
+      expect(error).toBeInstanceOf(BuildStepConditionEvaluationError);
+
+      for (const id of ['top__nested__leaf', 'top__tail']) {
+        expect(workflow.buildSteps.find(s => s.id === id)?.status).toBe(BuildStepStatus.SKIPPED);
+      }
+
+      const gateMessages = messages.filter(m => m.includes('Runner failed to evaluate'));
+      expect(gateMessages).toHaveLength(1);
+      expect(gateMessages[0]).toContain('composite function call "./.eas/functions/outer"');
+    });
+  });
 });
@@ -2,6 +2,7 @@ import { CompositeFunctionCatalog, CompositeFunctionConfigZ, Step } from '@expo/

 import { createGlobalContextMock } from './utils/context';
 import { BuildFunction } from '../BuildFunction';
+import { BuildStepGlobalContext } from '../BuildStepContext';
 import { BuildFunctionGroup } from '../BuildFunctionGroup';
 import { BuildStepInput, BuildStepInputValueTypeName } from '../BuildStepInput';
 import { BuildStepOutput } from '../BuildStepOutput';
@@ -23,8 +24,9 @@ export async function parseCompositeFunctions(options: {
  steps: Step[];
  externalFunctions?: BuildFunction[];
  externalFunctionGroups?: BuildFunctionGroup[];
+  ctx?: BuildStepGlobalContext;
 }): Promise<BuildWorkflow> {
-  const ctx = createGlobalContextMock();
+  const ctx = options.ctx ?? createGlobalContextMock();
  const parser = new StepsConfigParser(ctx, {
    steps: options.steps,
    hooks: undefined,
@@ -11,3 +11,20 @@ export function createMockLogger(): bunyan {
  } as unknown as bunyan;
  return logger;
 }
+
+export function createRecordingLogger(sink: string[]): bunyan {
+  const record = (...args: unknown[]): void => {
+    const message = args.find(arg => typeof arg === 'string');
+    if (typeof message === 'string') {
+      sink.push(message);
+    }
+  };
+  const logger = {
+    info: jest.fn(record),
+    debug: jest.fn(record),
+    error: jest.fn(record),
+    warn: jest.fn(record),
+    child: jest.fn(() => logger),
+  } as unknown as bunyan;
+  return logger;
+}
@@ -23,6 +23,18 @@ export class BuildInternalError extends Error {}

 export class BuildStepRuntimeError extends UserError {}

+export class BuildStepConditionEvaluationError extends UserError {
+  constructor(
+    public readonly subject: string,
+    public readonly ifCondition: string,
+    extra?: {
+      cause?: Error;
+    }
+  ) {
+    super(`Failed to evaluate the if condition "${ifCondition}" of ${subject}.`, extra);
+  }
+}
+
 export class BuildWorkflowError extends UserError {
  constructor(
    public override readonly message: string,
@@ -1,6 +1,6 @@
 {
  "name": "@expo/worker",
-  "version": "22.2.0",
+  "version": "22.6.0",
  "private": true,
  "scripts": {
    "start": "yarn watch",
@@ -19,7 +19,7 @@
  },
  "dependencies": {
    "@babel/core": "7.24.7",
-    "@expo/build-tools": "22.2.0",
+    "@expo/build-tools": "22.6.0",
    "@expo/config-plugins": "55.0.7",
    "@expo/config-types": "55.0.5",
    "@expo/downloader": "22.0.0",
@@ -28,7 +28,7 @@
    "@expo/results": "1.0.0",
    "@expo/rudder-sdk-node": "1.1.1",
    "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "22.1.0",
+    "@expo/steps": "22.4.0",
    "@expo/template-file": "22.0.0",
    "@expo/turtle-spawn": "22.0.0",
    "@hapi/boom": "10.0.1",
@@ -0,0 +1,235 @@
+import { TurtleSshSession } from '@expo/build-tools';
+import { BuildPhase, BuildPhaseResult, LogMarker } from '@expo/eas-build-job';
+
+import { startSshSessionPhaseAsync } from '../sshSession';
+
+jest.mock('@expo/build-tools', () => ({
+  TurtleSshSession: {
+    getSshRelayServerUrl: jest.fn(() => 'wss://relay.expo.dev'),
+    getSshIdleTimeoutSeconds: jest.fn(() => 0),
+    startSshSessionAsync: jest.fn(),
+    superviseSshSessionAsync: jest.fn(),
+  },
+  formatSecondsForLog: jest.fn(() => '15 minutes'),
+}));
+
+const mocked = jest.mocked(TurtleSshSession);
+
+function createLogger(): any {
+  const logger: any = {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  };
+  logger.child = jest.fn(() => logger);
+  return logger;
+}
+
+function createContext({ logger }: { logger: any }): any {
+  return {
+    env: { __WORKFLOW_JOB_ID: 'wj-1' },
+    job: { ssh: { idleTimeoutSeconds: 0, relayServerUrl: 'wss://relay.expo.dev' } },
+    logger,
+    markBuildPhaseHasWarnings: jest.fn(),
+    // The real implementation runs the phase body and honors doNotMarkEnd; for these tests we only
+    // need the body to run.
+    runBuildPhase: jest.fn(async (_phase: BuildPhase, body: () => Promise<void>) => {
+      await body();
+    }),
+  };
+}
+
+function endPhaseCalls(logger: any): any[] {
+  return logger.info.mock.calls.filter(
+    ([meta]: any[]) =>
+      meta != null && typeof meta === 'object' && meta.marker === LogMarker.END_PHASE
+  );
+}
+
+describe(startSshSessionPhaseAsync, () => {
+  let handle: {
+    getConnectedClientCountAsync: jest.Mock;
+    ensureConnectedAsync: jest.Mock;
+    stopAsync: jest.Mock;
+  };
+
+  beforeEach(() => {
+    handle = {
+      getConnectedClientCountAsync: jest.fn(async () => 0),
+      ensureConnectedAsync: jest.fn(async () => {}),
+      stopAsync: jest.fn(async () => {}),
+    };
+    mocked.startSshSessionAsync.mockResolvedValue({ handle, idleTimeoutSeconds: 0 } as any);
+    mocked.superviseSshSessionAsync.mockResolvedValue(undefined as any);
+  });
+
+  it('opens the session inside SSH_SESSION and leaves the phase open', async () => {
+    const logger = createLogger();
+    const ctx = createContext({ logger });
+
+    const { done } = await startSshSessionPhaseAsync({
+      ctx,
+      buildId: 'jr-1',
+      logger,
+      hasJobFinished: () => false,
+    });
+
+    expect(ctx.runBuildPhase).toHaveBeenCalledWith(BuildPhase.SSH_SESSION, expect.any(Function), {
+      doNotMarkEnd: true,
+    });
+    expect(mocked.startSshSessionAsync).toHaveBeenCalledWith(ctx, {
+      target: { type: 'JOB_RUN', id: 'jr-1' },
+      relayServerUrl: 'wss://relay.expo.dev',
+      idleTimeoutSeconds: 0,
+    });
+    expect(logger.info).toHaveBeenCalledWith(
+      'SSH session ready. Connect with: eas workflow:ssh jr-1'
+    );
+    expect(done).toBeInstanceOf(Promise);
+    await done;
+  });
+
+  it('mentions the idle timeout when it is non-zero', async () => {
+    const logger = createLogger();
+    const ctx = createContext({ logger });
+    mocked.getSshIdleTimeoutSeconds.mockReturnValue(900);
+    mocked.startSshSessionAsync.mockResolvedValue({ handle, idleTimeoutSeconds: 900 } as any);
+
+    const { done } = await startSshSessionPhaseAsync({
+      ctx,
+      buildId: 'jr-1',
+      logger,
+      hasJobFinished: () => true,
+    });
+    await done;
+
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('then closes after 15 minutes with no client connected')
+    );
+  });
+
+  it('returns before the session ends so the job is not blocked', async () => {
+    const logger = createLogger();
+    const ctx = createContext({ logger });
+    let releaseSupervision = (): void => {};
+    mocked.superviseSshSessionAsync.mockImplementation(
+      () =>
+        new Promise<void>(resolve => {
+          releaseSupervision = resolve;
+        })
+    );
+
+    const { done } = await startSshSessionPhaseAsync({
+      ctx,
+      buildId: 'jr-1',
+      logger,
+      hasJobFinished: () => false,
+    });
+
+    expect(done).toBeDefined();
+    expect(handle.stopAsync).not.toHaveBeenCalled();
+    releaseSupervision();
+    await done;
+    expect(handle.stopAsync).toHaveBeenCalled();
+  });
+
+  it('tears the tunnel down and closes the phase once supervision returns', async () => {
+    const logger = createLogger();
+    const ctx = createContext({ logger });
+
+    const { done } = await startSshSessionPhaseAsync({
+      ctx,
+      buildId: 'jr-1',
+      logger,
+      hasJobFinished: () => true,
+    });
+    await done;
+
+    expect(handle.stopAsync).toHaveBeenCalled();
+    expect(endPhaseCalls(logger)).toEqual([
+      [expect.objectContaining({ result: BuildPhaseResult.SUCCESS }), expect.any(String)],
+    ]);
+  });
+
+  it('passes the job-finished signal through to the supervisor', async () => {
+    const logger = createLogger();
+    const ctx = createContext({ logger });
+    let jobFinished = false;
+
+    const { done } = await startSshSessionPhaseAsync({
+      ctx,
+      buildId: 'jr-1',
+      logger,
+      hasJobFinished: () => jobFinished,
+    });
+    await done;
+
+    const { hasJobFinished, handle: passedHandle } =
+      mocked.superviseSshSessionAsync.mock.calls[0][0];
+    expect(hasJobFinished()).toBe(false);
+    jobFinished = true;
+    expect(hasJobFinished()).toBe(true);
+    expect(passedHandle).toBe(handle);
+  });
+
+  it('closes the phase with a warning when supervision throws', async () => {
+    const logger = createLogger();
+    const ctx = createContext({ logger });
+    mocked.superviseSshSessionAsync.mockRejectedValue(new Error('relay went away'));
+
+    const { done } = await startSshSessionPhaseAsync({
+      ctx,
+      buildId: 'jr-1',
+      logger,
+      hasJobFinished: () => true,
+    });
+    await done;
+
+    expect(handle.stopAsync).toHaveBeenCalled();
+    expect(endPhaseCalls(logger)).toEqual([
+      [expect.objectContaining({ result: BuildPhaseResult.WARNING }), expect.any(String)],
+    ]);
+  });
+
+  it('warns when tearing down the tunnel fails after supervision', async () => {
+    const logger = createLogger();
+    const ctx = createContext({ logger });
+    handle.stopAsync.mockRejectedValue(new Error('already gone'));
+
+    const { done } = await startSshSessionPhaseAsync({
+      ctx,
+      buildId: 'jr-1',
+      logger,
+      hasJobFinished: () => true,
+    });
+    await done;
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: expect.any(Error) },
+      'Failed to tear down the SSH tunnel.'
+    );
+    expect(endPhaseCalls(logger)).toEqual([
+      [expect.objectContaining({ result: BuildPhaseResult.SUCCESS }), expect.any(String)],
+    ]);
+  });
+
+  it('lets the job continue and closes the phase when the session cannot be opened', async () => {
+    const logger = createLogger();
+    const ctx = createContext({ logger });
+    mocked.startSshSessionAsync.mockRejectedValue(new Error('no relay'));
+
+    const { done } = await startSshSessionPhaseAsync({
+      ctx,
+      buildId: 'jr-1',
+      logger,
+      hasJobFinished: () => false,
+    });
+
+    expect(done).toBeUndefined();
+    expect(ctx.markBuildPhaseHasWarnings).toHaveBeenCalled();
+    expect(mocked.superviseSshSessionAsync).not.toHaveBeenCalled();
+    expect(endPhaseCalls(logger)).toEqual([
+      [expect.objectContaining({ result: BuildPhaseResult.WARNING }), expect.any(String)],
+    ]);
+  });
+});
@@ -1,4 +1,10 @@
-import { Artifacts, BuildContext, Builders, runGenericJobAsync } from '@expo/build-tools';
+import {
+  Artifacts,
+  BuildContext,
+  Builders,
+  TurtleSshSession,
+  runGenericJobAsync,
+} from '@expo/build-tools';
 import {
  Android,
  BuildJob,
@@ -17,6 +23,7 @@ import config from './config';
 import { displayWorkerRuntimeInfo } from './displayRuntimeInfo';
 import { Analytics, Event, logProjectDependenciesAsync } from './external/analytics';
 import { prepareRuntimeEnvironment } from './runtimeEnvironment';
+import { startSshSessionPhaseAsync } from './sshSession';
 import { cleanUpWorkingdir } from './workingdir';

 export async function build({
@@ -29,6 +36,8 @@ export async function build({
  analytics: Analytics;
 }): Promise<Artifacts> {
  const { job, logger } = ctx;
+  let sshSessionDone: Promise<void> | undefined;
+  let hasJobFinished = false;
  try {
    analytics.logEvent(Event.WORKER_BUILD_START, {});

@@ -49,6 +58,15 @@ export async function build({
      }
    });

+    if (TurtleSshSession.isSshEnabled(ctx.job)) {
+      ({ done: sshSessionDone } = await startSshSessionPhaseAsync({
+        ctx,
+        buildId,
+        logger,
+        hasJobFinished: () => hasJobFinished,
+      }));
+    }
+
    let artifacts: Artifacts;

    switch (job.platform) {
@@ -89,6 +107,9 @@ export async function build({
    }
    throw err;
  } finally {
+    // Lets the SSH supervisor start its idle countdown and tear the tunnel down.
+    hasJobFinished = true;
+    await sshSessionDone;
    if (config.env === 'development') {
      await cleanUpWorkingdir();
    }
@@ -0,0 +1,88 @@
+import { BuildContext, TurtleSshSession, formatSecondsForLog } from '@expo/build-tools';
+import { BuildPhase, BuildPhaseResult, LogMarker } from '@expo/eas-build-job';
+import { bunyan } from '@expo/logger';
+import { performance } from 'node:perf_hooks';
+
+export async function startSshSessionPhaseAsync({
+  ctx,
+  buildId,
+  logger,
+  hasJobFinished,
+}: {
+  ctx: BuildContext;
+  buildId: string;
+  logger: bunyan;
+  hasJobFinished: () => boolean;
+}): Promise<{ done?: Promise<void> }> {
+  let done: Promise<void> | undefined;
+
+  await ctx.runBuildPhase(
+    BuildPhase.SSH_SESSION,
+    async () => {
+      const phaseStartedAt = performance.now();
+      try {
+        ctx.logger.info('Opening an SSH session for this job.');
+        const target = {
+          type: ctx.job.platform ? ('BUILD' as const) : ('JOB_RUN' as const),
+          id: buildId,
+        };
+        const { handle, idleTimeoutSeconds } = await TurtleSshSession.startSshSessionAsync(ctx, {
+          target,
+          relayServerUrl: TurtleSshSession.getSshRelayServerUrl(ctx.job),
+          idleTimeoutSeconds: TurtleSshSession.getSshIdleTimeoutSeconds(ctx.job),
+        });
+        ctx.logger.info(`SSH session ready. Connect with: eas workflow:ssh ${buildId}`);
+        ctx.logger.info(
+          idleTimeoutSeconds === 0
+            ? 'It stays open for the whole job and closes once the job finishes and no client is connected.'
+            : `It stays open for the whole job, then closes after ${formatSecondsForLog(idleTimeoutSeconds)} with no client connected. The worker stays up until then.`
+        );
+
+        const sshLogger = logger.child({ phase: BuildPhase.SSH_SESSION });
+        done = (async () => {
+          let result = BuildPhaseResult.SUCCESS;
+          try {
+            await TurtleSshSession.superviseSshSessionAsync({
+              handle,
+              idleTimeoutSeconds,
+              hasJobFinished,
+              logger: sshLogger,
+            });
+          } catch (err) {
+            result = BuildPhaseResult.WARNING;
+            sshLogger.warn({ err }, 'The SSH session ended unexpectedly.');
+          } finally {
+            await handle.stopAsync().catch(err => {
+              sshLogger.warn({ err }, 'Failed to tear down the SSH tunnel.');
+            });
+            sshLogger.info(
+              {
+                marker: LogMarker.END_PHASE,
+                result,
+                durationMs: Math.round(performance.now() - phaseStartedAt),
+              },
+              `End phase: ${BuildPhase.SSH_SESSION}`
+            );
+          }
+        })();
+      } catch (err) {
+        ctx.logger.warn(
+          { err },
+          'Failed to open the SSH session. The job will continue without it.'
+        );
+        ctx.markBuildPhaseHasWarnings();
+        ctx.logger.info(
+          {
+            marker: LogMarker.END_PHASE,
+            result: BuildPhaseResult.WARNING,
+            durationMs: Math.round(performance.now() - phaseStartedAt),
+          },
+          `End phase: ${BuildPhase.SSH_SESSION}`
+        );
+      }
+    },
+    { doNotMarkEnd: true }
+  );
+
+  return { done };
+}
@@ -2291,7 +2291,7 @@ __metadata:
  languageName: node
  linkType: hard

-"@expo/build-tools@npm:22.2.0, @expo/build-tools@workspace:packages/build-tools":
+"@expo/build-tools@npm:22.6.0, @expo/build-tools@workspace:packages/build-tools":
  version: 0.0.0-use.local
  resolution: "@expo/build-tools@workspace:packages/build-tools"
  dependencies:
@@ -2303,15 +2303,16 @@ __metadata:
    "@expo/logger": "npm:22.0.0"
    "@expo/package-manager": "npm:1.9.10"
    "@expo/plist": "npm:^0.3.5"
-    "@expo/repack-app": "npm:~0.6.1"
+    "@expo/repack-app": "npm:~0.9.0"
    "@expo/results": "npm:^1.0.0"
    "@expo/spawn-async": "npm:1.7.2"
-    "@expo/steps": "npm:22.1.0"
+    "@expo/steps": "npm:22.4.0"
    "@expo/template-file": "npm:22.0.0"
    "@expo/turtle-spawn": "npm:22.0.0"
    "@expo/xcpretty": "npm:^4.3.1"
    "@ngrok/ngrok": "npm:1.7.0"
    "@sentry/node": "npm:7.77.0"
+    "@types/content-disposition": "npm:0.5.9"
    "@types/fs-extra": "npm:^11.0.4"
    "@types/jest": "npm:^29.5.12"
    "@types/lodash": "npm:^4.17.4"
@@ -2326,6 +2327,7 @@ __metadata:
    "@urql/core": "npm:^6.0.1"
    bplist-parser: "npm:0.3.2"
    bunyan: "npm:^1.8.15"
+    content-disposition: "npm:1.0.1"
    fast-glob: "npm:^3.3.2"
    fast-xml-parser: "npm:^4.4.1"
    fs-extra: "npm:^11.2.0"
@@ -2818,15 +2820,16 @@ __metadata:
  languageName: node
  linkType: hard

-"@expo/repack-app@npm:~0.6.1":
-  version: 0.6.1
-  resolution: "@expo/repack-app@npm:0.6.1"
+"@expo/repack-app@npm:~0.9.0":
+  version: 0.9.0
+  resolution: "@expo/repack-app@npm:0.9.0"
  dependencies:
    commander: "npm:^14.0.2"
    picocolors: "npm:^1.1.1"
+    zsign-wasm: "npm:^0.0.2"
  bin:
    repack-app: bin/cli.js
-  checksum: 10c0/fdf3088b4f327393056631270bf90a67ba949e7994892a62abc985bd9478119ab2f1d5be35fa1efb6bd1d2780c49a3dbb87cb669d9c65b44e3d9a0b41fbf091f
+  checksum: 10c0/0a493d97b80b98a1a90172baf81d7efee6b65399bf15171aae9c6505be3eedd4e59d05a8a33b3a6b6b720a2a96b7c2c5043c8ec92e390a5f917e2dd139d88aab
  languageName: node
  linkType: hard

@@ -2884,7 +2887,7 @@ __metadata:
  languageName: node
  linkType: hard

-"@expo/steps@npm:22.1.0, @expo/steps@workspace:packages/steps":
+"@expo/steps@npm:22.4.0, @expo/steps@workspace:packages/steps":
  version: 0.0.0-use.local
  resolution: "@expo/steps@workspace:packages/steps"
  dependencies:
@@ -2959,7 +2962,7 @@ __metadata:
  resolution: "@expo/worker@workspace:packages/worker"
  dependencies:
    "@babel/core": "npm:7.24.7"
-    "@expo/build-tools": "npm:22.2.0"
+    "@expo/build-tools": "npm:22.6.0"
    "@expo/config-plugins": "npm:55.0.7"
    "@expo/config-types": "npm:55.0.5"
    "@expo/downloader": "npm:22.0.0"
@@ -2968,7 +2971,7 @@ __metadata:
    "@expo/results": "npm:1.0.0"
    "@expo/rudder-sdk-node": "npm:1.1.1"
    "@expo/spawn-async": "npm:1.7.2"
-    "@expo/steps": "npm:22.1.0"
+    "@expo/steps": "npm:22.4.0"
    "@expo/template-file": "npm:22.0.0"
    "@expo/turtle-spawn": "npm:22.0.0"
    "@hapi/boom": "npm:10.0.1"
@@ -7084,7 +7087,7 @@ __metadata:
  languageName: node
  linkType: hard

-"@types/content-disposition@npm:*":
+"@types/content-disposition@npm:*, @types/content-disposition@npm:0.5.9":
  version: 0.5.9
  resolution: "@types/content-disposition@npm:0.5.9"
  checksum: 10c0/9fd520dae1a9c7b85909e59f548f905a670a6e2f83642f9734d1b05126f64ac8c8e2c282a663edf27d58bc34fbbacf46a4d4a95d3802b42106174a19a68175c8
@@ -9492,7 +9495,7 @@ __metadata:
  languageName: node
  linkType: hard

-"content-disposition@npm:~1.0.1":
+"content-disposition@npm:1.0.1, content-disposition@npm:~1.0.1":
  version: 1.0.1
  resolution: "content-disposition@npm:1.0.1"
  checksum: 10c0/bd7ff1fe8d2542d3a2b9a29428cc3591f6ac27bb5595bba2c69664408a68f9538b14cbd92479796ea835b317a09a527c8c7209c4200381dedb0c34d3b658849e
@@ -9724,7 +9727,7 @@ __metadata:
  resolution: "create-eas-build-function@workspace:packages/create-eas-build-function"
  dependencies:
    "@expo/package-manager": "npm:1.9.10"
-    "@expo/steps": "npm:22.1.0"
+    "@expo/steps": "npm:22.4.0"
    "@jest/globals": "npm:^29.7.0"
    "@types/jest": "npm:^29.5.12"
    "@types/node": "npm:20.14.2"
@@ -10297,7 +10300,7 @@ __metadata:
  version: 0.0.0-use.local
  resolution: "eas-cli-local-build-plugin@workspace:packages/local-build-plugin"
  dependencies:
-    "@expo/build-tools": "npm:22.2.0"
+    "@expo/build-tools": "npm:22.6.0"
    "@expo/eas-build-job": "npm:22.0.0"
    "@expo/logger": "npm:22.0.0"
    "@expo/spawn-async": "npm:^1.7.2"
@@ -10371,7 +10374,7 @@ __metadata:
    "@expo/results": "npm:1.0.0"
    "@expo/rudder-sdk-node": "npm:1.1.1"
    "@expo/spawn-async": "npm:1.7.2"
-    "@expo/steps": "npm:22.1.0"
+    "@expo/steps": "npm:22.4.0"
    "@expo/timeago.js": "npm:1.0.0"
    "@graphql-codegen/cli": "npm:6.3.1"
    "@graphql-codegen/introspection": "npm:5.0.2"
@@ -10448,6 +10451,7 @@ __metadata:
    node-forge: "npm:1.4.0"
    node-stream-zip: "npm:1.15.0"
    nullthrows: "npm:1.1.1"
+    open: "npm:8.4.0"
    ora: "npm:5.1.0"
    pkg-dir: "npm:4.2.0"
    pngjs: "npm:7.0.0"
@@ -12327,6 +12331,13 @@ __metadata:
  languageName: node
  linkType: hard

+"immediate@npm:~3.0.5":
+  version: 3.0.6
+  resolution: "immediate@npm:3.0.6"
+  checksum: 10c0/f8ba7ede69bee9260241ad078d2d535848745ff5f6995c7c7cb41cfdc9ccc213f66e10fa5afb881f90298b24a3f7344b637b592beb4f54e582770cdce3f1f039
+  languageName: node
+  linkType: hard
+
 "immutable@npm:^5.1.5":
  version: 5.1.9
  resolution: "immutable@npm:5.1.9"
@@ -13769,6 +13780,18 @@ __metadata:
  languageName: node
  linkType: hard

+"jszip@npm:^3.10.1":
+  version: 3.10.1
+  resolution: "jszip@npm:3.10.1"
+  dependencies:
+    lie: "npm:~3.3.0"
+    pako: "npm:~1.0.2"
+    readable-stream: "npm:~2.3.6"
+    setimmediate: "npm:^1.0.5"
+  checksum: 10c0/58e01ec9c4960383fb8b38dd5f67b83ccc1ec215bf74c8a5b32f42b6e5fb79fada5176842a11409c4051b5b94275044851814a31076bf49e1be218d3ef57c863
+  languageName: node
+  linkType: hard
+
 "just-diff-apply@npm:^5.2.0":
  version: 5.5.0
  resolution: "just-diff-apply@npm:5.5.0"
@@ -14011,6 +14034,15 @@ __metadata:
  languageName: node
  linkType: hard

+"lie@npm:~3.3.0":
+  version: 3.3.0
+  resolution: "lie@npm:3.3.0"
+  dependencies:
+    immediate: "npm:~3.0.5"
+  checksum: 10c0/56dd113091978f82f9dc5081769c6f3b947852ecf9feccaf83e14a123bc630c2301439ce6182521e5fbafbde88e88ac38314327a4e0493a1bea7e0699a7af808
+  languageName: node
+  linkType: hard
+
 "lilconfig@npm:^3.1.3":
  version: 3.1.3
  resolution: "lilconfig@npm:3.1.3"
@@ -15802,7 +15834,7 @@ __metadata:
  languageName: node
  linkType: hard

-"open@npm:^8.0.4, open@npm:^8.4.0":
+"open@npm:8.4.0, open@npm:^8.0.4, open@npm:^8.4.0":
  version: 8.4.0
  resolution: "open@npm:8.4.0"
  dependencies:
@@ -16196,6 +16228,13 @@ __metadata:
  languageName: node
  linkType: hard

+"pako@npm:~1.0.2":
+  version: 1.0.11
+  resolution: "pako@npm:1.0.11"
+  checksum: 10c0/86dd99d8b34c3930345b8bbeb5e1cd8a05f608eeb40967b293f72fe469d0e9c88b783a8777e4cc7dc7c91ce54c5e93d88ff4b4f060e6ff18408fd21030d9ffbe
+  languageName: node
+  linkType: hard
+
 "param-case@npm:^3.0.4":
  version: 3.0.4
  resolution: "param-case@npm:3.0.4"
@@ -17456,6 +17495,13 @@ __metadata:
  languageName: node
  linkType: hard

+"setimmediate@npm:^1.0.5":
+  version: 1.0.5
+  resolution: "setimmediate@npm:1.0.5"
+  checksum: 10c0/5bae81bfdbfbd0ce992893286d49c9693c82b1bcc00dcaaf3a09c8f428fdeacf4190c013598b81875dfac2b08a572422db7df779a99332d0fce186d15a3e4d49
+  languageName: node
+  linkType: hard
+
 "setprototypeof@npm:1.2.0, setprototypeof@npm:~1.2.0":
  version: 1.2.0
  resolution: "setprototypeof@npm:1.2.0"
@@ -19992,3 +20038,12 @@ __metadata:
  checksum: 10c0/5a2db7e59177a3d7e202543f5136cb87b97b047b77c8a3d824098d3fa8b80d3aa40a0a5f296965c3b82dfdccdd05dbbfacce91347f16a39c675680fd7b1ab109
  languageName: node
  linkType: hard
+
+"zsign-wasm@npm:^0.0.2":
+  version: 0.0.2
+  resolution: "zsign-wasm@npm:0.0.2"
+  dependencies:
+    jszip: "npm:^3.10.1"
+  checksum: 10c0/f8919b66031c93970987fa9ac0e742cc7975e4c4c6fbf60fa477e1154109a50a4bf907b75dff8afe72b457df49ce5d060e3a3b93ba3c92b8c453d85206058f22
+  languageName: node
+  linkType: hard
Author	SHA1	Message	Date
Expo CI	89fe2cb3e1	v22.6.0	2026-08-26 23:49:36 +00:00
Szymon Dziedzic	0e8e8cc0aa	[build-tools] Increase serve-sim bitrate to 6 Mbps (#4291 ) * [build-tools] Increase serve-sim bitrate to 16 Mbps * [build-tools] Add serve-sim bitrate changelog entry * [build-tools] Set serve-sim bitrate to 6 Mbps	2026-08-27 01:45:23 +02:00
Gabe Debes	6d7cef80a3	[eas-cli] add experimental support to resource class on simulator sessions (#4268 ) * [eas-cli] let simulator sessions request a large resource class * [eas-cli] add changelog for hidden --resource-class * [eas-cli] call --resource-class experimental in the changelog * [eas-cli] oxfmt simulator resource-class test * [eas-cli] regenerate graphql for resource class	2026-08-26 23:34:56 +00:00
Gabe Debes	5a744b73f5	[worker] Wire SSH session into build (#4031 ) * [worker] wire ssh session into build * Rename SSH phase sessionPromise to done. Same anti-flatten object wrapper; clearer that callers await tunnel teardown. * Cover SSH phase supervise callbacks and teardown failure paths. * [worker] Stop baking upterm into the worker package build-tools resolves upterm from PATH or downloads darwin-arm64 / linux-amd64 from gs://turtle-v2/upterm at runtime. * [worker] align ssh phase with build-tools api * [worker] build the ssh target from the job type	2026-08-26 16:25:12 -07:00
Gabe Debes	b8b53e262a	[build-tools] Add worker-side SSH session helper (#4030 ) * [build-tools] add worker-side ssh session helper * Keep host.connectionConfig current and simplify SSH reconnect. Update connectionConfig on every redial, linearize ensureConnectedAsync, and parse upterm session objects without a JSON stringify round-trip. * Reuse SshSettings instead of inlining idleTimeout/relay fields. * Cover remaining SSH helper branches in unit tests. Invalid upterm host URLs, missing process pid, stdout chunks, unknown client counts during the job, and turtleBuild targets. * Format unknownGraceMs ternary for oxfmt. * [build-tools] Drop dup changelog entry; redact upterm exit logs * [build-tools] gitignore baked upterm binaries * [build-tools] Cover SSH helpers; drop upterm gitignore; restore review fixes Zod-parse upterm session JSON and move isChildProcessAlive into processes.ts (claimed in review but never landed). Expand unit coverage and stop gitignoring baked upterm binaries now that the worker fetches from GCS. * [build-tools] Resolve upterm from PATH or GCS instead of baking Restore the orphaned review-fix tip: prefer an image/PATH upterm, else download darwin-arm64 / linux-amd64 from gs://turtle-v2/upterm. Keeps the stricter zod session parse, process-group/admin-socket comments, and GCS cache/path unit coverage. * [build-tools] Redact upterm tokens from ws:// relay URLs too * [build-tools] Align upterm PATH probe with job env; scrub controls in logs * [build-tools] address SSH review feedback * [build-tools] address second round of SSH review feedback * [build-tools] send a discriminated target on the ssh session mutation * [build-tools] sort ssh test imports	2026-08-26 08:09:27 -07:00
Expo CI	3f74ea369d	v22.5.0	2026-08-26 14:49:23 +00:00
Szymon DziedzicandClaude Fable 5	28f80da648	[eas-cli] Add --max-idle-time-minutes flag to eas simulator (#4156 ) Co-authored-by: Claude Fable 5 <[email protected]>	2026-08-26 16:39:07 +02:00
Szymon Dziedzic	a7260dfed3	[eas-cli] Bump CLI environment versions to 22.4.0 (#4286 )	2026-08-26 14:30:58 +02:00
Stanisław Chmiela	5cd1b5eee3	[build-tools] Preserve Argent artifact kinds (#4280 ) # Why Argent now exposes artifact kind!! # How Extended the schema. Kept mime-types though I'd be more than happy to remove it (mime types can lie). # Test Plan CI should pass.	2026-08-26 13:46:20 +02:00
Stanisław Chmiela	9d627c6917	[build-tools] Humanize Appium command summaries (#4227 ) # Why We currently present Appium session events as HTTP methods which is not too human-readable (`getWindowRect`). # How Added a GHA workflow which runs weekly and submits a pull request adding to an `AppiumCommand` type so TSC fails and we need to add descriptions to commands. # Test Plan CI should pass.	2026-08-26 13:46:07 +02:00
Szymon Dziedzic	66dbcaf432	[build-tools] Bypass simulator URL confirmation (#4274 ) * [build-tools] bypass simulator URL confirmation * [build-tools] add URL confirmation fix changelog * [build-tools] make URL preapproval best effort	2026-08-25 00:49:48 +02:00
Expo CI	39c39ad4bf	v22.4.0	2026-08-24 21:35:36 +00:00
Szymon Dziedzic	1ad3822421	[eas-cli] Add simulator launch options (#4264 ) * [eas-cli] add simulator launch options * [eas-cli] add simulator launch options changelog * [eas-cli] resolve simulator Expo Go archives server-side * [eas-cli] rename simulator open URL flag * [eas-cli] rename simulator open URL GraphQL field	2026-08-24 23:33:13 +02:00
Szymon Dziedzic	0929787398	[build-tools] Support simulator application launch options (#4263 ) * [build-tools] support simulator application launch options * [build-tools] add simulator launch options changelog * [build-tools] rename launch application open URL input * [build-tools] clarify simulator launch arguments	2026-08-24 23:19:30 +02:00
Szymon Dziedzic	756016a433	[build-tools] Support flat app bundle archives (#4262 ) * [build-tools] Support flat app bundle archives * [build-tools] Add flat app archive changelog	2026-08-24 23:07:07 +02:00
Jon Samp	c6e3c332ac	[eas-cli] Add eas billing:subscribe and billing:manage commands (#4007 )	2026-08-24 14:44:44 -05:00
Stanisław Chmiela	7c95a6b4b2	[build-tools] Restore maestro-runner WDA cache (#4195 ) ## Why `maestro-runner` needs WDA driver to run tests. By default it compiles it on first run which takes a minute. ## How Compiled WDA on all images, uploaded to `turtle-v2` GCS and added optimistic download to `eas/install_maestro`. See https://github.com/expo/turtle-v2/pull/2603. ## Test plan https://staging.expo.dev/accounts/expo-services/projects/workflows-testing/workflows/01a0009e-b171-7497-9335-af1fc470a8d5	2026-08-24 21:32:24 +02:00
Szymon Świerk	16d234b11d	[steps] Report a broken composite `if:` on the call, not an inner step (#4216 ) * [steps] Report a broken composite if: on the call, not an inner step * [steps] Simplify condition evaluation error handling by building the erro message in the error constructor	2026-08-24 18:52:39 +02:00
Expo CI	70066fc8be	v22.3.0	2026-08-24 14:45:57 +00:00
Szymon Dziedzic	d27691adef	[eas-cli] Add simulator build source flags (#4223 ) * [eas-cli] Add simulator build source flags * [eas-cli] align simulator application archive input * [eas-cli] add simulator build flags changelog * [eas-cli] add Expo Go simulator source * [eas-cli] rename Expo Go simulator flag * [eas-cli] rename application archive URL flag * [eas-cli] parse Expo Go download output	2026-08-24 16:42:15 +02:00
Stanisław Chmiela	97d64f4054	[build-tools] Separate iOS ccache by destination (#4238 ) # Why Looks like ccache cache built for iOS simulator is not helpful for iOS device builds and vice versa. Context: https://exponent-internal.slack.com/archives/C08PBDW7ZC3/p1787242902697509?thread_ts=1787171142.251299&cid=C08PBDW7ZC3 # How Separated `ios-device-ccache-` and `ios-simulator-ccache-` ccaches. # Test Plan - Before: the [simulator build](https://staging.expo.dev/accounts/expo-services/projects/worker-system-tests/builds/5b9eccae-58a7-4a20-919e-61fbbd8ab68d) restored the [device build’s](https://staging.expo.dev/accounts/expo-services/projects/worker-system-tests/builds/026d0b35-0a6d-418d-bf34-488ed68f7d19) cache, got 0 hits, and could not save its own cache because the key already existed. - After: the [device](https://staging.expo.dev/accounts/expo-services/projects/worker-system-tests/builds/02279218-8450-4679-b377-aec998dff0dd) and [simulator](https://staging.expo.dev/accounts/expo-services/projects/worker-system-tests/builds/0e6892fd-a9ee-4a90-ba23-97c7a17ad1e9) builds used separate keys. The simulator build got 48 direct hits.	2026-08-24 15:59:02 +02:00
Szymon Dziedzic	1fe8f24313	[build-tools] Install builds in simulator sessions (#4222 ) * [build-tools] Install builds in simulator sessions * [build-tools] split simulator app setup functions * [build-tools] add simulator app setup changelog * [build-tools] decouple application launch from artifact * [build-tools] simplify build source validation * [build-tools] enforce build source input type * [build-tools] address simulator install review feedback	2026-08-24 15:08:14 +02:00
Gabe Debes	790231ea18	[build-tools] Support pinning the serve-sim version in a simulator session (#4253 )	2026-08-21 17:18:48 -07:00
Gabriel Donadel Dall'Agnol	1f24d00ee9	[build-tools] Add ios_signing_backend option to the repack step (#4239 ) * [build-tools] Add ios_signing_backend option to the repack step * Update CHANGELOG.md * split out a dedicated resolver for resolveIosSigningOptionsAsync	2026-08-21 19:58:25 +02:00