[eas-cli] Fix multi-account review findings

- Make --account per-command: use an in-memory session override instead of
  persistently switching the active account
- Skip --account interception for commands that define their own account flag
  (project:init, chat, billing:manage, billing:subscribe)
- Support --account=value, reject flag-shaped values, stop at the -- terminator
- Error when --account is combined with EXPO_TOKEN
- Invalidate session secrets on the server in all multi-account logout paths
- Preserve unrelated top-level keys in ~/.expo/state.json on account writes
- Keep the v1 accounts map in sync when logging in or out with the flag off,
  so toggling the flag cannot resurrect a stale identity or drop accounts
- Guard v0->v1 migration against a legacy session with no userId
- Pass the browser flag through the add-account flows; error when logout
  username/--all are used without the feature flag

.github/workflows/update-appium-commands.yml

@@ -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

CHANGELOG.md

@@ -8,6 +8,55 @@ This is the log of notable changes to EAS CLI and related packages.
 
 ### 🎉 New features
 
+- [eas-cli] Add experimental multi-account support behind `EAS_EXPERIMENTAL_ACCOUNT_SWITCHER=1`: `account:list`, `account:switch`, a global `--account` flag, and multi-account `account:login`/`account:logout`. ([#3340](https://github.com/expo/eas-cli/pull/3340) by [@brentvatne](https://github.com/brentvatne))
+
+### 🐛 Bug fixes
+
+### 🧹 Chores
+
+## [22.6.0](https://github.com/expo/eas-cli/releases/tag/v22.6.0) - 2026-08-26
+
+### 🎉 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))
+
+## [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
+
 - [eas-cli] Add `--device` flag to `eas simulator` for selecting the virtual device to start. ([#4172](https://github.com/expo/eas-cli/pull/4172) by [@szdziedzic](https://github.com/szdziedzic))
 - [eas-cli] Add support for Appium EAS Simulator sessions. ([#4190](https://github.com/expo/eas-cli/pull/4190) by [@sjchmiela](https://github.com/sjchmiela))
 

cli-versions.json

@@ -1,4 +1,4 @@
 {
-  "STAGING": "22.0.0",
-  "PRODUCTION": "21.5.0"
+  "STAGING": "22.6.0",
+  "PRODUCTION": "22.4.0"
 }

lerna.json

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

packages/build-tools/package.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",

packages/build-tools/scripts/generate-appium-commands.js

@@ -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;
+});

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

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

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

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

packages/build-tools/src/index.ts

@@ -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';

packages/build-tools/src/ios/__tests__/xcode.test.ts

@@ -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,
+    });
+  });
+});

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

@@ -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;
+}

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

@@ -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(),

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

@@ -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({

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

@@ -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');
+  });
+});

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

@@ -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 });
+    }
+  });
 });

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

@@ -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();
+    }
+  );
+});

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

@@ -26,6 +26,7 @@ describe(readIpaInfoAsync, () => {
       bundleIdentifier: 'dev.expo.SmallestAppExample',
       bundleShortVersion: '1.0',
       bundleVersion: '1',
+      dtPlatformName: 'iphoneos',
     });
   });
 

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

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

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

@@ -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, '_');
+}

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

@@ -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 };
+}

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

@@ -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({

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

@@ -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;
+}

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

@@ -16,6 +16,10 @@ export type IpaInfo = {
   bundleIdentifier: string;
   bundleShortVersion: string;
   bundleVersion: string;
+  // `DTPlatformName` from the bundle's Info.plist (e.g. `iphoneos`, `appletvos`,
+  // `macosx`, `xros`), or null when absent. Used to pick the App Store Connect
+  // platform for the upload. See `AscApiUtils.ascPlatformFromDtPlatformName`.
+  dtPlatformName: string | null;
 };
 
 const INFO_PLIST_PATH_REGEXP = /^Payload\/[^/]+\.app\/Info\.plist$/;
@@ -91,10 +95,14 @@ export async function readIpaInfoAsync(ipaPath: string): Promise<IpaInfo> {
       );
     }
 
+    const dtPlatformName =
+      typeof infoPlist.DTPlatformName === 'string' ? infoPlist.DTPlatformName : null;
+
     return {
       bundleIdentifier,
       bundleShortVersion,
       bundleVersion,
+      dtPlatformName,
     };
   } catch (error) {
     if (error instanceof UserError) {

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

@@ -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,
+  };
+}

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

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

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

@@ -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');

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

@@ -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}`);
 

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

@@ -115,16 +115,27 @@ export function createUploadToAscBuildFunction(): BuildFunction {
         `Uploading Build to "${appResponse.data.attributes.name}" (${ascAppBundleIdentifier})...`
       );
 
+      // Derive the App Store Connect platform from the IPA itself so tvOS (and
+      // other) binaries are uploaded to the correct version train instead of the
+      // iOS one. Falls back to `IOS` if the platform cannot be read.
+      const ipaInfoResult = await asyncResult(readIpaInfoAsync(ipaPath));
+      const platform = ipaInfoResult.ok
+        ? AscApiUtils.ascPlatformFromDtPlatformName(ipaInfoResult.value.dtPlatformName)
+        : 'IOS';
+      stepsCtx.logger.info(`Detected App Store Connect platform: ${platform}`);
+
       stepsCtx.logger.info('Creating Build Upload...');
       const buildUploadResponse = await AscApiUtils.createBuildUploadAsync({
         client,
         appleAppIdentifier,
         bundleShortVersion,
         bundleVersion,
+        platform,
       });
 
       const buildUploadId = buildUploadResponse.data.id;
-      const buildUploadUrl = `https://appstoreconnect.apple.com/apps/${appleAppIdentifier}/testflight/ios/${buildUploadId}`;
+      const platformPathSegment = AscApiUtils.testFlightPlatformPathSegment(platform);
+      const buildUploadUrl = `https://appstoreconnect.apple.com/apps/${appleAppIdentifier}/testflight/${platformPathSegment}/${buildUploadId}`;
       outputs.build_upload_id.set(buildUploadId);
       outputs.build_upload_url.set(buildUploadUrl);
 

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

@@ -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);
+    }
+  );
+});

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

@@ -58,7 +58,10 @@ describe(startAppiumEventCollectionAsync, () => {
         producer: 'appium',
         type: 'operation.completed',
         durationMs: 25,
-        summary: 'getOrientation',
+        summary: 'Read the screen orientation',
+        data: {
+          command: 'getOrientation',
+        },
       },
     });
 

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

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

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

@@ -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, () => {

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

@@ -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;
+}

packages/build-tools/src/steps/utils/appiumCommands.generated.ts

@@ -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;

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

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

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

@@ -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;
   }

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

@@ -272,6 +272,10 @@ export type AscApiClientPostApi = {
   };
 };
 
+// https://developer.apple.com/documentation/appstoreconnectapi/platform
+export type AscPlatform =
+  AscApiClientPostApi['/v1/buildUploads']['request']['data']['attributes']['platform'];
+
 export type AscApiClientPatchApi = {
   [Path in keyof typeof PatchApi]: {
     request: z.input<(typeof PatchApi)[Path]['request']>;

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

@@ -5,9 +5,44 @@ import {
   AscApiClientGetApi,
   AscApiClientPostApi,
   AscApiRequestError,
+  AscPlatform,
 } from './AscApiClient';
 
 export namespace AscApiUtils {
+  /**
+   * Maps a bundle's `DTPlatformName` (from its Info.plist) to the App Store
+   * Connect platform used for a build upload. Unknown or missing values fall
+   * back to `IOS` to preserve the previous default.
+   */
+  export function ascPlatformFromDtPlatformName(dtPlatformName: string | null): AscPlatform {
+    switch (dtPlatformName) {
+      case 'appletvos':
+        return 'TV_OS';
+      case 'macosx':
+        return 'MAC_OS';
+      case 'xros':
+        return 'VISION_OS';
+      case 'iphoneos':
+      default:
+        return 'IOS';
+    }
+  }
+
+  /** The App Store Connect TestFlight URL path segment for a platform. */
+  export function testFlightPlatformPathSegment(platform: AscPlatform): string {
+    switch (platform) {
+      case 'TV_OS':
+        return 'tvos';
+      case 'MAC_OS':
+        return 'macos';
+      case 'VISION_OS':
+        return 'visionos';
+      case 'IOS':
+      default:
+        return 'ios';
+    }
+  }
+
   export async function getAppInfoAsync({
     client,
     appleAppIdentifier,
@@ -61,18 +96,20 @@ export namespace AscApiUtils {
     appleAppIdentifier,
     bundleShortVersion,
     bundleVersion,
+    platform,
   }: {
     client: Pick<AscApiClient, 'postAsync'>;
     appleAppIdentifier: string;
     bundleShortVersion: string;
     bundleVersion: string;
+    platform: AscPlatform;
   }): Promise<AscApiClientPostApi['/v1/buildUploads']['response']> {
     try {
       return await client.postAsync('/v1/buildUploads', {
         data: {
           type: 'buildUploads',
           attributes: {
-            platform: 'IOS',
+            platform,
             cfBundleShortVersionString: bundleShortVersion,
             cfBundleVersion: bundleVersion,
           },

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

@@ -148,6 +148,7 @@ describe('AscApiUtils', () => {
           appleAppIdentifier: '1491144534',
           bundleShortVersion: '1.2.3',
           bundleVersion: '42',
+          platform: 'IOS',
         })
       ).rejects.toEqual(
         expect.objectContaining({
@@ -176,10 +177,40 @@ describe('AscApiUtils', () => {
           appleAppIdentifier: '1491144534',
           bundleShortVersion: '1.2.3',
           bundleVersion: '42',
+          platform: 'IOS',
         })
       ).resolves.toEqual(response);
     });
 
+    it('sends the requested platform in the build upload attributes', async () => {
+      const response = {
+        data: {
+          type: 'buildUploads',
+          id: 'fdf9c476-aaa4-4ead-b91c-6e3cc3a47805',
+        },
+      } as const;
+      const client = {
+        postAsync: jest.fn().mockResolvedValue(response),
+      };
+
+      await AscApiUtils.createBuildUploadAsync({
+        client,
+        appleAppIdentifier: '1491144534',
+        bundleShortVersion: '1.2.3',
+        bundleVersion: '42',
+        platform: 'TV_OS',
+      });
+
+      expect(client.postAsync).toHaveBeenCalledWith(
+        '/v1/buildUploads',
+        expect.objectContaining({
+          data: expect.objectContaining({
+            attributes: expect.objectContaining({ platform: 'TV_OS' }),
+          }),
+        })
+      );
+    });
+
     it('rethrows when error payload includes mixed error codes', async () => {
       const payload = {
         errors: [
@@ -208,8 +239,32 @@ describe('AscApiUtils', () => {
           appleAppIdentifier: '1491144534',
           bundleShortVersion: '1.2.3',
           bundleVersion: '42',
+          platform: 'IOS',
         })
       ).rejects.toBe(mixedError);
     });
   });
+
+  describe('ascPlatformFromDtPlatformName', () => {
+    it('maps known DTPlatformName values to App Store Connect platforms', () => {
+      expect(AscApiUtils.ascPlatformFromDtPlatformName('iphoneos')).toBe('IOS');
+      expect(AscApiUtils.ascPlatformFromDtPlatformName('appletvos')).toBe('TV_OS');
+      expect(AscApiUtils.ascPlatformFromDtPlatformName('macosx')).toBe('MAC_OS');
+      expect(AscApiUtils.ascPlatformFromDtPlatformName('xros')).toBe('VISION_OS');
+    });
+
+    it('falls back to IOS for unknown or missing values', () => {
+      expect(AscApiUtils.ascPlatformFromDtPlatformName(null)).toBe('IOS');
+      expect(AscApiUtils.ascPlatformFromDtPlatformName('watchos')).toBe('IOS');
+    });
+  });
+
+  describe('testFlightPlatformPathSegment', () => {
+    it('returns the TestFlight URL segment for each platform', () => {
+      expect(AscApiUtils.testFlightPlatformPathSegment('IOS')).toBe('ios');
+      expect(AscApiUtils.testFlightPlatformPathSegment('TV_OS')).toBe('tvos');
+      expect(AscApiUtils.testFlightPlatformPathSegment('MAC_OS')).toBe('macos');
+      expect(AscApiUtils.testFlightPlatformPathSegment('VISION_OS')).toBe('visionos');
+    });
+  });
 });

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

@@ -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 ?? '';

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

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

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

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

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

@@ -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({

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

@@ -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-');
+  });
+});

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

@@ -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');
+  });
+});

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

@@ -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);
+  });
+});

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

@@ -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
+    );
+  });
+});

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

@@ -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.'
+    );
+  });
+});

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

@@ -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);
+    });
+  });
+});

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

@@ -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}`);
   }

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

@@ -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}`
+  );
+}

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

@@ -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(' ');
+}

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

@@ -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(',')], {

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

@@ -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);
+  }
+}

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

@@ -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,
+  };
+}

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

@@ -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",

packages/eas-cli/graphql.schema.json

@@ -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

packages/eas-cli/package.json

@@ -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"
       },

packages/eas-cli/src/__tests__/commands/go-test.ts

@@ -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', () => ({

packages/eas-cli/src/analytics/AnalyticsManager.ts

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

packages/eas-cli/src/billing/__tests__/billingClient.test.ts

@@ -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' },
+    });
+  });
+});

packages/eas-cli/src/billing/__tests__/resolveAccount.test.ts

@@ -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.'
+    );
+  });
+});

packages/eas-cli/src/billing/billingClient.ts

@@ -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;
+  }
+}

packages/eas-cli/src/billing/openUrl.ts

@@ -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)}`);
+}

packages/eas-cli/src/billing/plans.ts

@@ -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;
+}

packages/eas-cli/src/billing/resolveAccount.ts

@@ -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.',
+    }
+  );
+}

packages/eas-cli/src/build/__tests__/handleBuildRequestError-test.ts

@@ -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.'
           );
         });
       });

packages/eas-cli/src/build/build.ts

@@ -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(

packages/eas-cli/src/commandUtils/EasCommand.ts

@@ -30,6 +30,7 @@ import Log, { link } from '../log';
 import Sentry from '../sentry';
 import SessionManager from '../user/SessionManager';
 import { getActorDisplayName } from '../user/User';
+import { isMultiAccountEnabled } from '../utils/easCli';
 import { Client } from '../vcs/vcs';
 
 export type ContextInput<
@@ -224,11 +225,75 @@ export default abstract class EasCommand extends Command {
 
   protected abstract runAsync(): Promise<any>;
 
+  /**
+   * Parse and remove the --account flag from command line arguments.
+   * This is a global flag available on all commands when multi-account is enabled.
+   * We remove it from this.argv so child commands don't see it during their parse().
+   * Commands that declare their own `account` flag (with different semantics,
+   * e.g. `project:init`) are skipped so their flag keeps working.
+   */
+  private parseAndRemoveAccountFlag(): string | undefined {
+    if (this.ctor.flags && 'account' in this.ctor.flags) {
+      return undefined;
+    }
+
+    const terminatorIndex = this.argv.indexOf('--');
+    const searchEnd = terminatorIndex === -1 ? this.argv.length : terminatorIndex;
+
+    for (let i = 0; i < searchEnd; i++) {
+      const arg = this.argv[i];
+      if (arg === '--account') {
+        const value = i + 1 < searchEnd ? this.argv[i + 1] : undefined;
+        if (!value || value.startsWith('-')) {
+          throw new Error('The --account flag requires a username value.');
+        }
+        this.argv.splice(i, 2);
+        return value;
+      }
+      if (arg.startsWith('--account=')) {
+        const value = arg.slice('--account='.length);
+        if (!value) {
+          throw new Error('The --account flag requires a username value.');
+        }
+        this.argv.splice(i, 1);
+        return value;
+      }
+    }
+    return undefined;
+  }
+
   // eslint-disable-next-line async-protect/async-suffix
   async run(): Promise<any> {
     this.analyticsInternal = await createAnalyticsAsync();
     this.sessionManagerInternal = new SessionManager(this.analytics);
 
+    // Handle --account flag for per-command account selection
+    if (isMultiAccountEnabled()) {
+      const accountFlag = this.parseAndRemoveAccountFlag();
+      if (accountFlag) {
+        if (this.sessionManager.getAccessToken()) {
+          throw new Error(
+            'EXPO_TOKEN is set in your environment and is used for all EAS authentication, so --account has no effect. Unset EXPO_TOKEN to select an account with --account.'
+          );
+        }
+        const accounts = this.sessionManager.getAllAccounts();
+        const targetAccount = accounts.find(a => a.username === accountFlag);
+        if (!targetAccount) {
+          const availableAccounts = accounts.map(a => a.username).join(', ') || 'none';
+          throw new Error(
+            `Account '${accountFlag}' not found. Available accounts: ${availableAccounts}`
+          );
+        }
+        if (
+          !targetAccount.isActive &&
+          !this.sessionManager.useAccountForProcessByUsername(accountFlag)
+        ) {
+          throw new Error(`Account '${accountFlag}' not found.`);
+        }
+        Log.log(chalk.dim(`Using account: ${accountFlag}`));
+      }
+    }
+
     // this is needed for logEvent call below as it identifies the user in the analytics system
     // if possible
     const actor = await this.sessionManager.getUserAsync();

packages/eas-cli/src/commands/account/list.ts

@@ -0,0 +1,63 @@
+import chalk from 'chalk';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import Log from '../../log';
+import { fromNow } from '../../utils/date';
+import { isMultiAccountEnabled } from '../../utils/easCli';
+
+export default class AccountList extends EasCommand {
+  static override description = 'list all logged-in Expo accounts';
+
+  static override contextDefinition = {
+    ...this.ContextOptions.SessionManagment,
+  };
+
+  // Hide this command when the feature flag is disabled
+  static override get hidden(): boolean {
+    return !isMultiAccountEnabled();
+  }
+
+  async runAsync(): Promise<void> {
+    if (!isMultiAccountEnabled()) {
+      Log.error(
+        'Multi-account listing is not enabled. Set EAS_EXPERIMENTAL_ACCOUNT_SWITCHER=1 to enable.'
+      );
+      process.exit(1);
+    }
+
+    const { sessionManager } = await this.getContextAsync(AccountList, { nonInteractive: true });
+
+    if (sessionManager.getAccessToken()) {
+      Log.log(chalk.yellow('Using EXPO_TOKEN from environment for authentication.'));
+      Log.log('Account switching is not available when using EXPO_TOKEN.');
+      return;
+    }
+
+    const accounts = sessionManager.getAllAccounts();
+
+    if (accounts.length === 0) {
+      Log.log('No accounts logged in.');
+      Log.log(`Run ${chalk.bold('eas login')} to log in.`);
+      return;
+    }
+
+    Log.log('Logged-in accounts:');
+    Log.newLine();
+
+    for (const account of accounts) {
+      const marker = account.isActive ? chalk.green('●') : chalk.dim('○');
+      const activeLabel = account.isActive ? chalk.dim(' (active)') : '';
+      const username = account.isActive ? chalk.bold(account.username) : account.username;
+
+      Log.log(`${marker} ${username}${activeLabel}`);
+
+      if (account.lastUsedAt) {
+        const lastUsed = fromNow(new Date(account.lastUsedAt));
+        Log.log(chalk.dim(`  └─ Last used: ${lastUsed} ago`));
+      }
+    }
+
+    Log.newLine();
+    Log.log(`Use ${chalk.bold('eas account:switch')} to change accounts.`);
+  }
+}

packages/eas-cli/src/commands/account/login.ts

@@ -3,8 +3,10 @@ import chalk from 'chalk';
 
 import EasCommand from '../../commandUtils/EasCommand';
 import Log from '../../log';
-import { confirmAsync } from '../../prompts';
-import { getActorDisplayName } from '../../user/User';
+import { confirmAsync, selectAsync } from '../../prompts';
+import SessionManager from '../../user/SessionManager';
+import { Actor, getActorDisplayName } from '../../user/User';
+import { isMultiAccountEnabled } from '../../utils/easCli';
 
 export default class AccountLogin extends EasCommand {
   static override description = 'log in with your Expo account';
@@ -47,6 +49,13 @@ export default class AccountLogin extends EasCommand {
     }
 
     if (actor) {
+      if (isMultiAccountEnabled()) {
+        // Multi-account mode: offer options
+        await this.handleMultiAccountLoginAsync(sessionManager, actor, { sso, browser });
+        return;
+      }
+
+      // Legacy mode: simple confirmation
       Log.warn(`You are already logged in as ${chalk.bold(getActorDisplayName(actor))}.`);
 
       const shouldContinue = await confirmAsync({
@@ -60,4 +69,58 @@ export default class AccountLogin extends EasCommand {
     await sessionManager.showLoginPromptAsync({ sso, browser });
     Log.log('Logged in');
   }
+
+  private async handleMultiAccountLoginAsync(
+    sessionManager: SessionManager,
+    actor: Actor,
+    { sso, browser }: { sso: boolean; browser: boolean }
+  ): Promise<void> {
+    const accounts = sessionManager.getAllAccounts();
+    const currentUsername = getActorDisplayName(actor);
+
+    Log.log(`You're logged in as ${chalk.bold(currentUsername)}.`);
+
+    const choices: { title: string; value: string }[] = [
+      {
+        title: 'Add another account',
+        value: 'add',
+      },
+    ];
+
+    // Add switch options for other accounts
+    const otherAccounts = accounts.filter(a => !a.isActive);
+    if (otherAccounts.length > 0) {
+      for (const account of otherAccounts) {
+        choices.push({
+          title: `Switch to ${account.username}`,
+          value: `switch:${account.username}`,
+        });
+      }
+    }
+
+    choices.push({
+      title: 'Cancel',
+      value: 'cancel',
+    });
+
+    const action = await selectAsync('What would you like to do?', choices);
+
+    if (action === 'cancel') {
+      Errors.error('Aborted', { exit: 1 });
+    }
+
+    if (action === 'add') {
+      await sessionManager.showLoginPromptAsync({ sso, browser });
+      const newAccounts = sessionManager.getAllAccounts();
+      Log.log('Logged in');
+      Log.log(`You now have ${newAccounts.length} account${newAccounts.length > 1 ? 's' : ''}.`);
+      return;
+    }
+
+    if (action.startsWith('switch:')) {
+      const username = action.slice('switch:'.length);
+      await sessionManager.switchAccountByUsernameAsync(username);
+      Log.log(`Switched to ${chalk.bold(username)}`);
+    }
+  }
 }

packages/eas-cli/src/commands/account/logout.ts

@@ -1,17 +1,120 @@
+import { Args, Flags } from '@oclif/core';
+import chalk from 'chalk';
+
 import EasCommand from '../../commandUtils/EasCommand';
 import Log from '../../log';
+import { confirmAsync } from '../../prompts';
+import { isMultiAccountEnabled } from '../../utils/easCli';
 
 export default class AccountLogout extends EasCommand {
   static override description = 'log out';
   static override aliases = ['logout'];
 
+  static override args = {
+    username: Args.string({
+      description: 'Username of the account to log out (multi-account mode only)',
+      required: false,
+    }),
+  };
+
+  static override flags = {
+    all: Flags.boolean({
+      description: 'Log out of all accounts (multi-account mode only)',
+      default: false,
+    }),
+  };
+
   static override contextDefinition = {
     ...this.ContextOptions.SessionManagment,
   };
 
   async runAsync(): Promise<void> {
+    const { args, flags } = await this.parse(AccountLogout);
     const { sessionManager } = await this.getContextAsync(AccountLogout, { nonInteractive: false });
-    await sessionManager.logoutAsync();
-    Log.log('Logged out');
+
+    if (!isMultiAccountEnabled()) {
+      if (args.username || flags.all) {
+        Log.error(
+          'Logging out a specific account requires the experimental account switcher. Set EAS_EXPERIMENTAL_ACCOUNT_SWITCHER=1 to enable it.'
+        );
+        process.exit(1);
+      }
+
+      // Legacy behavior
+      await sessionManager.logoutAsync();
+      Log.log('Logged out');
+      return;
+    }
+
+    // Multi-account mode
+    const accounts = sessionManager.getAllAccounts();
+
+    if (accounts.length === 0) {
+      Log.log('Not logged in to any accounts.');
+      return;
+    }
+
+    // Handle --all flag
+    if (flags.all) {
+      const confirmed = await confirmAsync({
+        message: `Log out of all ${accounts.length} account${accounts.length > 1 ? 's' : ''}?`,
+      });
+
+      if (!confirmed) {
+        Log.log('Aborted');
+        return;
+      }
+
+      await sessionManager.removeAllAccountsAsync();
+      Log.log('Logged out of all accounts');
+      return;
+    }
+
+    // Handle specific username argument
+    if (args.username) {
+      const account = accounts.find(a => a.username === args.username);
+      if (!account) {
+        Log.error(`Account '${args.username}' not found.`);
+        Log.log('Logged-in accounts:');
+        accounts.forEach(a => {
+          Log.log(`  • ${a.username}${a.isActive ? ' (active)' : ''}`);
+        });
+        process.exit(1);
+      }
+
+      await sessionManager.removeAccountAsync(account.userId);
+      Log.log(`Logged out of ${chalk.bold(args.username)}`);
+
+      // Show remaining accounts info
+      const remainingAccounts = sessionManager.getAllAccounts();
+      if (remainingAccounts.length > 0) {
+        const activeAccount = remainingAccounts.find(a => a.isActive);
+        if (activeAccount) {
+          Log.log(`Active account is now: ${chalk.bold(activeAccount.username)}`);
+        }
+      }
+      return;
+    }
+
+    // Default: log out of active account
+    const activeAccount = accounts.find(a => a.isActive);
+    if (!activeAccount) {
+      Log.log('No active account to log out of.');
+      return;
+    }
+
+    await sessionManager.removeAccountAsync(activeAccount.userId);
+    Log.log(`Logged out of ${chalk.bold(activeAccount.username)}`);
+
+    // Show remaining accounts info
+    const remainingAccounts = sessionManager.getAllAccounts();
+    if (remainingAccounts.length > 0) {
+      const newActiveAccount = remainingAccounts.find(a => a.isActive);
+      if (newActiveAccount) {
+        Log.log(`Active account is now: ${chalk.bold(newActiveAccount.username)}`);
+      }
+    } else {
+      Log.log('No accounts remaining. Run `eas login` to log in.');
+    }
   }
 }

packages/eas-cli/src/commands/account/switch.ts

@@ -0,0 +1,98 @@
+import { Args } from '@oclif/core';
+import chalk from 'chalk';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import Log from '../../log';
+import { selectAsync } from '../../prompts';
+import { isMultiAccountEnabled } from '../../utils/easCli';
+
+export default class AccountSwitch extends EasCommand {
+  static override description = 'switch to a different Expo account';
+
+  static override args = {
+    username: Args.string({
+      description: 'Username of the account to switch to',
+      required: false,
+    }),
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.SessionManagment,
+  };
+
+  // Hide this command when the feature flag is disabled
+  static override get hidden(): boolean {
+    return !isMultiAccountEnabled();
+  }
+
+  async runAsync(): Promise<void> {
+    if (!isMultiAccountEnabled()) {
+      Log.error(
+        'Multi-account switching is not enabled. Set EAS_EXPERIMENTAL_ACCOUNT_SWITCHER=1 to enable.'
+      );
+      process.exit(1);
+    }
+
+    const { args } = await this.parse(AccountSwitch);
+    const { sessionManager } = await this.getContextAsync(AccountSwitch, { nonInteractive: false });
+
+    const accounts = sessionManager.getAllAccounts();
+
+    if (accounts.length === 0) {
+      Log.warn('No accounts logged in. Run `eas login` to log in.');
+      process.exit(1);
+    }
+
+    if (accounts.length === 1) {
+      Log.log(`Only one account is logged in: ${chalk.bold(accounts[0].username)}`);
+      Log.log('Run `eas login` to add another account.');
+      return;
+    }
+
+    let targetUsername = args.username;
+
+    if (!targetUsername) {
+      // Interactive mode: show account picker
+      const choices = accounts.map(account => {
+        const title = account.isActive
+          ? `${account.username} ${chalk.dim('(active)')}`
+          : account.username;
+        return { title, value: account.username };
+      });
+
+      choices.push({
+        title: chalk.dim('Add new account...'),
+        value: '__add_new__',
+      });
+
+      targetUsername = await selectAsync('Select an account:', choices);
+
+      if (targetUsername === '__add_new__') {
+        // Match the default `eas login` behavior (browser-based login)
+        await sessionManager.showLoginPromptAsync({ browser: true });
+        Log.log('Logged in');
+        return;
+      }
+    }
+
+    // Check if already active
+    const targetAccount = accounts.find(a => a.username === targetUsername);
+    if (!targetAccount) {
+      Log.error(`Account '${targetUsername}' not found.`);
+      Log.log('Available accounts:');
+      accounts.forEach(a => {
+        Log.log(`  • ${a.username}${a.isActive ? ' (active)' : ''}`);
+      });
+      process.exit(1);
+    }
+
+    if (targetAccount.isActive) {
+      Log.log(`Already using account ${chalk.bold(targetUsername)}`);
+      return;
+    }
+
+    // Switch to the account
+    await sessionManager.switchAccountByUsernameAsync(targetUsername);
+    Log.log(`Switched to ${chalk.bold(targetUsername)}`);
+  }
+}

packages/eas-cli/src/commands/account/view.ts

@@ -4,6 +4,7 @@ import EasCommand from '../../commandUtils/EasCommand';
 import { Role } from '../../graphql/generated';
 import Log from '../../log';
 import { Actor, getActorDisplayName } from '../../user/User';
+import { isMultiAccountEnabled } from '../../utils/easCli';
 
 export default class AccountView extends EasCommand {
   static override description = 'show the username you are logged in as';
@@ -11,39 +12,53 @@ export default class AccountView extends EasCommand {
 
   static override contextDefinition = {
     ...this.ContextOptions.MaybeLoggedIn,
+    ...this.ContextOptions.SessionManagment,
   };
 
   async runAsync(): Promise<void> {
     const {
       maybeLoggedIn: { actor, authenticationInfo },
+      sessionManager,
     } = await this.getContextAsync(AccountView, { nonInteractive: true });
-    if (actor) {
-      const displayName = getActorDisplayName(actor);
-      const loggedInAs = authenticationInfo.accessToken
-        ? `${displayName} (authenticated using EXPO_TOKEN)`
-        : displayName;
-      Log.log(chalk.green(loggedInAs));
-      if ('email' in actor) {
-        Log.log(actor.email);
-      }
 
-      // personal account is included, only show if more accounts that personal account
-      // but do show personal account in list if there are more
-      const accountExcludingPersonalAccount = actor.accounts.filter(
-        account => !('username' in actor) || account.name !== actor.username
-      );
-      if (accountExcludingPersonalAccount.length > 0) {
-        Log.newLine();
-        Log.log('Accounts:');
-        actor.accounts.forEach(account => {
-          const roleOnAccount = AccountView.getRoleOnAccount(actor, account);
-          Log.log(`• ${account.name} (Role: ${AccountView.getLabelForRole(roleOnAccount)})`);
-        });
-      }
-    } else {
+    if (!actor) {
       Log.warn('Not logged in');
       process.exit(1);
     }
+
+    const displayName = getActorDisplayName(actor);
+    const loggedInAs = authenticationInfo.accessToken
+      ? `${displayName} (authenticated using EXPO_TOKEN)`
+      : displayName;
+    Log.log(chalk.green(loggedInAs));
+    if ('email' in actor) {
+      Log.log(actor.email);
+    }
+
+    // Show other logged-in accounts if multi-account is enabled
+    if (isMultiAccountEnabled() && !authenticationInfo.accessToken) {
+      const accounts = sessionManager.getAllAccounts();
+      const otherAccounts = accounts.filter(a => !a.isActive);
+
+      if (otherAccounts.length > 0) {
+        const otherUsernames = otherAccounts.map(a => a.username).join(', ');
+        Log.log(chalk.dim(`Also logged in: ${otherUsernames}`));
+      }
+    }
+
+    // personal account is included, only show if more accounts that personal account
+    // but do show personal account in list if there are more
+    const accountExcludingPersonalAccount = actor.accounts.filter(
+      account => !('username' in actor) || account.name !== actor.username
+    );
+    if (accountExcludingPersonalAccount.length > 0) {
+      Log.newLine();
+      Log.log('Accounts:');
+      actor.accounts.forEach(account => {
+        const roleOnAccount = AccountView.getRoleOnAccount(actor, account);
+        Log.log(`• ${account.name} (Role: ${AccountView.getLabelForRole(roleOnAccount)})`);
+      });
+    }
   }
 
   private static getRoleOnAccount(actor: Actor, account: Actor['accounts'][0]): Role {

packages/eas-cli/src/commands/billing/__tests__/manage.test.ts

@@ -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();
+  });
+});

packages/eas-cli/src/commands/billing/__tests__/subscribe.test.ts

@@ -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();
+  });
+});

packages/eas-cli/src/commands/billing/manage.ts

@@ -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,
+    });
+  }
+}

packages/eas-cli/src/commands/billing/subscribe.ts

@@ -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,
+    });
+  }
+}

packages/eas-cli/src/commands/go.ts

@@ -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;

packages/eas-cli/src/commands/simulator/__tests__/index.test.ts

@@ -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})`);

packages/eas-cli/src/commands/simulator/index.ts

@@ -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');

packages/eas-cli/src/graphql/generated.ts

@@ -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'];
 }>;

packages/eas-cli/src/graphql/queries/AccountQuery.ts

@@ -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;
+  },
 };

packages/eas-cli/src/project/detectProjectSdkVersionAsync.ts

@@ -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;
+  }
+}

packages/eas-cli/src/simulator/__tests__/expoGo.test.ts

@@ -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."
+      );
+    }
+  );
+});

packages/eas-cli/src/simulator/__tests__/utils.test.ts

@@ -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
+    );
+  });
+});

packages/eas-cli/src/simulator/expoGo.ts

@@ -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`;
+}

packages/eas-cli/src/simulator/utils.ts

@@ -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> {

packages/eas-cli/src/user/SessionManager.ts

@@ -1,7 +1,9 @@
 import JsonFile from '@expo/json-file';
 import { Errors } from '@oclif/core';
 import chalk from 'chalk';
+import fs from 'fs-extra';
 import nullthrows from 'nullthrows';
+import path from 'path';
 
 import { fetchSessionSecretAndUserAsync } from './fetchSessionSecretAndUser';
 import { fetchSessionSecretAndUserFromBrowserAuthFlowAsync } from './fetchSessionSecretAndUserFromBrowserAuthFlow';
@@ -13,21 +15,61 @@ import { CurrentUserQuery } from '../graphql/generated';
 import { UserQuery } from '../graphql/queries/UserQuery';
 import Log, { learnMore } from '../log';
 import { promptAsync } from '../prompts';
+import { isMultiAccountEnabled } from '../utils/easCli';
 import { getStateJsonPath } from '../utils/paths';
 
-type UserSettingsData = {
-  auth?: SessionData;
-};
+type ConnectionType = 'Username-Password-Authentication' | 'Browser-Flow-Authentication';
 
-type SessionData = {
+/**
+ * Legacy session data format (v0 schema).
+ * These fields are also used for Expo CLI backward compatibility.
+ */
+type LegacySessionData = {
   sessionSecret: string;
-
-  // These fields are potentially used by Expo CLI.
   userId: string;
   username: string;
-  currentConnection: 'Username-Password-Authentication' | 'Browser-Flow-Authentication';
+  currentConnection: ConnectionType;
 };
 
+/**
+ * Account data with timestamps for multi-account support (v1 schema).
+ */
+type AccountData = {
+  sessionSecret: string;
+  userId: string;
+  username: string;
+  currentConnection: ConnectionType;
+  addedAt: string;
+  lastUsedAt: string;
+};
+
+/**
+ * State file format for v0 (legacy single-account).
+ */
+type StateDataV0 = {
+  auth?: LegacySessionData;
+};
+
+/**
+ * State file format for v1 (multi-account).
+ */
+type StateDataV1 = {
+  version: 1;
+  auth: {
+    activeAccountId: string | null;
+    accounts: Record<string, AccountData>;
+    // Legacy fields for Expo CLI backward compatibility
+    sessionSecret?: string;
+    userId?: string;
+    username?: string;
+    currentConnection?: ConnectionType;
+  };
+};
+
+type StateData = StateDataV0 | StateDataV1;
+
+type SessionData = LegacySessionData;
+
 export type LoggedInAuthenticationInfo =
   | {
       accessToken: string;
@@ -40,9 +82,26 @@ export type LoggedInAuthenticationInfo =
 
 type Actor = NonNullable<CurrentUserQuery['meActor']>;
 
+/**
+ * Publicly exposed account info for multi-account features.
+ */
+export type StoredAccount = {
+  userId: string;
+  username: string;
+  isActive: boolean;
+  addedAt?: string;
+  lastUsedAt?: string;
+};
+
 export default class SessionManager {
   private currentActor: Actor | undefined;
 
+  /**
+   * When set, this stored account is used for the rest of the process instead of the
+   * active account from the state file. Never persisted (used by the global --account flag).
+   */
+  private perProcessAccountOverrideUserId: string | undefined;
+
   constructor(private readonly analytics: AnalyticsWithOrchestration) {}
 
   public getAccessToken(): string | null {
@@ -50,12 +109,16 @@ export default class SessionManager {
   }
 
   public getSessionSecret(): string | null {
-    return this.getSession()?.sessionSecret ?? null;
+    return this.getActiveSession()?.sessionSecret ?? null;
   }
 
-  private getSession(): SessionData | null {
+  // ============================================
+  // State File Reading
+  // ============================================
+
+  private readStateFile(): StateData | null {
     try {
-      return JsonFile.read<UserSettingsData>(getStateJsonPath())?.auth ?? null;
+      return JsonFile.read<StateData>(getStateJsonPath()) ?? null;
     } catch (error: any) {
       if (error.code === 'ENOENT') {
         return null;
@@ -64,25 +127,550 @@ export default class SessionManager {
     }
   }
 
+  private isV1Schema(state: StateData | null): state is StateDataV1 {
+    return (
+      state !== null &&
+      'version' in state &&
+      state.version === 1 &&
+      state.auth?.accounts !== undefined
+    );
+  }
+
+  /**
+   * Get the active session data, reading from appropriate schema.
+   * For v1 schema, reads from the active account in the accounts object.
+   * For v0 schema, reads from legacy fields.
+   */
+  private getActiveSession(): SessionData | null {
+    const state = this.readStateFile();
+    if (!state) {
+      return null;
+    }
+
+    // For v1 schema with multi-account enabled, read from the active account
+    if (isMultiAccountEnabled() && this.isV1Schema(state)) {
+      const overrideId = this.perProcessAccountOverrideUserId;
+      const activeId =
+        overrideId && state.auth.accounts[overrideId] ? overrideId : state.auth.activeAccountId;
+      if (activeId && state.auth.accounts[activeId]) {
+        const account = state.auth.accounts[activeId];
+        return {
+          sessionSecret: account.sessionSecret,
+          userId: account.userId,
+          username: account.username,
+          currentConnection: account.currentConnection,
+        };
+      }
+    }
+
+    // Read from legacy fields (v0 schema or fallback)
+    const auth = state.auth;
+    if (!auth?.sessionSecret) {
+      return null;
+    }
+
+    return {
+      sessionSecret: auth.sessionSecret,
+      userId: auth.userId!,
+      username: auth.username!,
+      currentConnection: auth.currentConnection!,
+    };
+  }
+
+  // ============================================
+  // State File Writing
+  // ============================================
+
+  /**
+   * Write session data, preserving existing schema structure.
+   * - If multi-account disabled: only update legacy fields
+   * - If multi-account enabled: update accounts object + legacy fields
+   */
   private async setSessionAsync(sessionData?: SessionData): Promise<void> {
-    await JsonFile.setAsync(getStateJsonPath(), 'auth', sessionData, {
-      default: {},
-      ensureDir: true,
-    });
+    const statePath = getStateJsonPath();
+
+    if (!sessionData) {
+      // Logout: clear session data
+      if (isMultiAccountEnabled()) {
+        await this.clearActiveAccountAsync();
+        return;
+      }
+
+      const state = this.readStateFile();
+      if (this.isV1Schema(state)) {
+        // Preserve other stored accounts: drop only the logged-out account and legacy fields
+        const loggedOutUserId = state.auth.userId ?? state.auth.activeAccountId;
+        const { [loggedOutUserId ?? '']: _removed, ...remainingAccounts } = state.auth.accounts;
+        await this.writeStateFileAsync({
+          ...state,
+          auth: {
+            activeAccountId: null,
+            accounts: remainingAccounts,
+          },
+        });
+      } else {
+        await JsonFile.setAsync(statePath, 'auth', undefined, {
+          default: {},
+          ensureDir: true,
+        });
+      }
+      return;
+    }
+
+    const state = this.readStateFile();
+    if (!isMultiAccountEnabled() && !this.isV1Schema(state)) {
+      // Feature disabled and no v1 structure: plain legacy write
+      const existingAuth = state?.auth ?? {};
+
+      const updatedAuth = {
+        ...existingAuth,
+        sessionSecret: sessionData.sessionSecret,
+        userId: sessionData.userId,
+        username: sessionData.username,
+        currentConnection: sessionData.currentConnection,
+      };
+
+      await this.writeStateFileAsync({ ...state, auth: updatedAuth });
+      return;
+    }
+
+    // Feature enabled, or a v1 state file already exists: keep the accounts
+    // object and the legacy fields in sync so that toggling the feature flag
+    // never resurrects a stale identity.
+    await this.addOrUpdateAccountAsync(sessionData);
+  }
+
+  /**
+   * Write state file atomically with proper permissions.
+   */
+  private async writeStateFileAsync(state: StateData): Promise<void> {
+    const statePath = getStateJsonPath();
+    const dir = path.dirname(statePath);
+    await fs.ensureDir(dir);
+
+    // Write atomically: write to temp file, then rename
+    const tempPath = `${statePath}.tmp.${process.pid}`;
+    await fs.writeJson(tempPath, state, { spaces: 2 });
+    await fs.rename(tempPath, statePath);
+
+    // Ensure restrictive permissions (owner read/write only)
+    try {
+      await fs.chmod(statePath, 0o600);
+    } catch {
+      // Ignore chmod errors on platforms that don't support it
+    }
+  }
+
+  // ============================================
+  // Multi-Account Methods (Feature Flag Gated)
+  // ============================================
+
+  /**
+   * Get all stored accounts.
+   * Returns single account array when multi-account is disabled.
+   */
+  public getAllAccounts(): StoredAccount[] {
+    const state = this.readStateFile();
+
+    if (!isMultiAccountEnabled() || !this.isV1Schema(state)) {
+      // Return single account from legacy fields
+      const session = this.getActiveSession();
+      if (!session) {
+        return [];
+      }
+      return [
+        {
+          userId: session.userId,
+          username: session.username,
+          isActive: true,
+        },
+      ];
+    }
+
+    // Multi-account enabled with v1 schema
+    const accounts = Object.values(state.auth.accounts);
+    const activeId = state.auth.activeAccountId;
+
+    return accounts.map(account => ({
+      userId: account.userId,
+      username: account.username,
+      isActive: account.userId === activeId,
+      addedAt: account.addedAt,
+      lastUsedAt: account.lastUsedAt,
+    }));
+  }
+
+  /**
+   * Check if a user is already logged in (by userId).
+   */
+  public isAccountLoggedIn(userId: string): boolean {
+    const accounts = this.getAllAccounts();
+    return accounts.some(a => a.userId === userId);
+  }
+
+  /**
+   * Check if a user is already logged in (by username).
+   */
+  public isAccountLoggedInByUsername(username: string): boolean {
+    const accounts = this.getAllAccounts();
+    return accounts.some(a => a.username === username);
+  }
+
+  /**
+   * Get the active account, or null if not logged in.
+   */
+  public getActiveAccount(): StoredAccount | null {
+    const accounts = this.getAllAccounts();
+    return accounts.find(a => a.isActive) ?? null;
+  }
+
+  /**
+   * Add or update an account in multi-account mode.
+   * If the account already exists (by userId), update its session.
+   * Always sets the new/updated account as active.
+   */
+  private async addOrUpdateAccountAsync(sessionData: SessionData): Promise<void> {
+    const state = this.readStateFile();
+    const now = new Date().toISOString();
+
+    let newState: StateDataV1;
+
+    if (this.isV1Schema(state)) {
+      // Update existing v1 schema
+      const existingAccount = state.auth.accounts[sessionData.userId];
+      newState = {
+        ...state,
+        version: 1,
+        auth: {
+          ...state.auth,
+          activeAccountId: sessionData.userId,
+          accounts: {
+            ...state.auth.accounts,
+            [sessionData.userId]: {
+              sessionSecret: sessionData.sessionSecret,
+              userId: sessionData.userId,
+              username: sessionData.username,
+              currentConnection: sessionData.currentConnection,
+              addedAt: existingAccount?.addedAt ?? now,
+              lastUsedAt: now,
+            },
+          },
+          // Sync legacy fields
+          sessionSecret: sessionData.sessionSecret,
+          userId: sessionData.userId,
+          username: sessionData.username,
+          currentConnection: sessionData.currentConnection,
+        },
+      };
+    } else {
+      // Migrate from v0 to v1
+      newState = {
+        ...state,
+        version: 1,
+        auth: {
+          activeAccountId: sessionData.userId,
+          accounts: {
+            [sessionData.userId]: {
+              sessionSecret: sessionData.sessionSecret,
+              userId: sessionData.userId,
+              username: sessionData.username,
+              currentConnection: sessionData.currentConnection,
+              addedAt: now,
+              lastUsedAt: now,
+            },
+          },
+          // Sync legacy fields
+          sessionSecret: sessionData.sessionSecret,
+          userId: sessionData.userId,
+          username: sessionData.username,
+          currentConnection: sessionData.currentConnection,
+        },
+      };
+
+      // If there was an existing session in v0, preserve it as a separate account
+      if (
+        state?.auth?.sessionSecret &&
+        state.auth.userId &&
+        state.auth.userId !== sessionData.userId
+      ) {
+        newState.auth.accounts[state.auth.userId] = {
+          sessionSecret: state.auth.sessionSecret,
+          userId: state.auth.userId,
+          username: state.auth.username,
+          currentConnection: state.auth.currentConnection,
+          addedAt: now,
+          lastUsedAt: now,
+        };
+      }
+    }
+
+    await this.writeStateFileAsync(newState);
+  }
+
+  /**
+   * Switch to a different account by userId.
+   * Only available when multi-account is enabled.
+   */
+  public async switchAccountAsync(userId: string): Promise<void> {
+    if (!isMultiAccountEnabled()) {
+      throw new Error('Multi-account switching is not enabled');
+    }
+
+    const state = this.readStateFile();
+    if (!this.isV1Schema(state)) {
+      throw new Error('No accounts to switch to');
+    }
+
+    const account = state.auth.accounts[userId];
+    if (!account) {
+      throw new Error(`Account not found: ${userId}`);
+    }
+
+    const now = new Date().toISOString();
+    const newState: StateDataV1 = {
+      ...state,
+      auth: {
+        ...state.auth,
+        activeAccountId: userId,
+        accounts: {
+          ...state.auth.accounts,
+          [userId]: {
+            ...account,
+            lastUsedAt: now,
+          },
+        },
+        // Sync legacy fields
+        sessionSecret: account.sessionSecret,
+        userId: account.userId,
+        username: account.username,
+        currentConnection: account.currentConnection,
+      },
+    };
+
+    await this.writeStateFileAsync(newState);
+
+    // Clear cached actor since we switched
+    this.currentActor = undefined;
+  }
+
+  /**
+   * Use a stored account for the rest of this process without persisting a switch
+   * to the state file. Used by the global --account flag for per-command account
+   * selection. Returns false if no such account is stored.
+   */
+  public useAccountForProcessByUsername(username: string): boolean {
+    if (!isMultiAccountEnabled()) {
+      return false;
+    }
+
+    const state = this.readStateFile();
+    if (!this.isV1Schema(state)) {
+      return false;
+    }
+
+    const account = Object.values(state.auth.accounts).find(a => a.username === username);
+    if (!account) {
+      return false;
+    }
+
+    this.perProcessAccountOverrideUserId = account.userId;
+    this.currentActor = undefined;
+    return true;
+  }
+
+  /**
+   * Switch to a different account by username.
+   * Only available when multi-account is enabled.
+   */
+  public async switchAccountByUsernameAsync(username: string): Promise<void> {
+    if (!isMultiAccountEnabled()) {
+      throw new Error('Multi-account switching is not enabled');
+    }
+
+    const state = this.readStateFile();
+    if (!this.isV1Schema(state)) {
+      throw new Error('No accounts to switch to');
+    }
+
+    const account = Object.values(state.auth.accounts).find(a => a.username === username);
+    if (!account) {
+      throw new Error(`Account not found: ${username}`);
+    }
+
+    await this.switchAccountAsync(account.userId);
+  }
+
+  /**
+   * Remove an account by userId. Invalidates its session secret on the server (best-effort).
+   * If removing the active account, switches to the most recently used remaining account.
+   */
+  public async removeAccountAsync(userId: string): Promise<void> {
+    if (!isMultiAccountEnabled()) {
+      // When disabled, just clear everything
+      await this.invalidateCurrentSessionOnServerAsync();
+      await JsonFile.setAsync(getStateJsonPath(), 'auth', undefined, {
+        default: {},
+        ensureDir: true,
+      });
+      this.currentActor = undefined;
+      return;
+    }
+
+    const state = this.readStateFile();
+    if (!this.isV1Schema(state)) {
+      // V0 schema: just clear
+      await this.invalidateCurrentSessionOnServerAsync();
+      await JsonFile.setAsync(getStateJsonPath(), 'auth', undefined, {
+        default: {},
+        ensureDir: true,
+      });
+      this.currentActor = undefined;
+      return;
+    }
+
+    const { [userId]: removed, ...remainingAccounts } = state.auth.accounts;
+    if (!removed) {
+      return; // Account not found, nothing to do
+    }
+
+    await this.invalidateSessionSecretOnServerAsync(removed.sessionSecret);
+
+    const wasActive = state.auth.activeAccountId === userId;
+    let newActiveId: string | null = state.auth.activeAccountId;
+
+    if (wasActive) {
+      // Find the most recently used remaining account
+      const remaining = Object.values(remainingAccounts);
+      if (remaining.length > 0) {
+        remaining.sort(
+          (a, b) => new Date(b.lastUsedAt).getTime() - new Date(a.lastUsedAt).getTime()
+        );
+        newActiveId = remaining[0].userId;
+      } else {
+        newActiveId = null;
+      }
+    }
+
+    const newActiveAccount = newActiveId ? remainingAccounts[newActiveId] : null;
+
+    const newState: StateDataV1 = {
+      ...state,
+      version: 1,
+      auth: {
+        activeAccountId: newActiveId,
+        accounts: remainingAccounts,
+        // Sync legacy fields to new active account (or clear if none)
+        sessionSecret: newActiveAccount?.sessionSecret,
+        userId: newActiveAccount?.userId,
+        username: newActiveAccount?.username,
+        currentConnection: newActiveAccount?.currentConnection,
+      },
+    };
+
+    await this.writeStateFileAsync(newState);
+    this.currentActor = undefined;
+  }
+
+  /**
+   * Remove all accounts (logout all). Invalidates their session secrets on the
+   * server (best-effort).
+   */
+  public async removeAllAccountsAsync(): Promise<void> {
+    if (!isMultiAccountEnabled()) {
+      await this.invalidateCurrentSessionOnServerAsync();
+      await JsonFile.setAsync(getStateJsonPath(), 'auth', undefined, {
+        default: {},
+        ensureDir: true,
+      });
+      this.currentActor = undefined;
+      return;
+    }
+
+    const state = this.readStateFile();
+    if (!this.isV1Schema(state)) {
+      await this.invalidateCurrentSessionOnServerAsync();
+      await JsonFile.setAsync(getStateJsonPath(), 'auth', undefined, {
+        default: {},
+        ensureDir: true,
+      });
+      this.currentActor = undefined;
+      return;
+    }
+
+    for (const account of Object.values(state.auth.accounts)) {
+      await this.invalidateSessionSecretOnServerAsync(account.sessionSecret);
+    }
+
+    const newState: StateDataV1 = {
+      ...state,
+      version: 1,
+      auth: {
+        activeAccountId: null,
+        accounts: {},
+        // Clear legacy fields
+        sessionSecret: undefined,
+        userId: undefined,
+        username: undefined,
+        currentConnection: undefined,
+      },
+    };
+
+    await this.writeStateFileAsync(newState);
+    this.currentActor = undefined;
+  }
+
+  /**
+   * Clear the active account (used by logout when multi-account enabled).
+   */
+  private async clearActiveAccountAsync(): Promise<void> {
+    const state = this.readStateFile();
+
+    if (!this.isV1Schema(state)) {
+      // V0 schema: just clear
+      await this.invalidateCurrentSessionOnServerAsync();
+      await JsonFile.setAsync(getStateJsonPath(), 'auth', undefined, {
+        default: {},
+        ensureDir: true,
+      });
+      return;
+    }
+
+    const activeId = state.auth.activeAccountId;
+    if (!activeId) {
+      return; // Already no active account
+    }
+
+    await this.removeAccountAsync(activeId);
+  }
+
+  /**
+   * Best-effort invalidation of a session secret on the server.
+   */
+  private async invalidateSessionSecretOnServerAsync(sessionSecret: string): Promise<void> {
+    const apiV2Client = new ApiV2Client({ accessToken: null, sessionSecret });
+    try {
+      await apiV2Client.postAsync('auth/logout', { body: {} });
+    } catch (e) {
+      // Best-effort: clear the local session even if the server request fails
+      Log.debug('Failed to invalidate session secret on server:', e);
+    }
+  }
+
+  private async invalidateCurrentSessionOnServerAsync(): Promise<void> {
+    const sessionSecret = this.getSessionSecret();
+    if (sessionSecret) {
+      await this.invalidateSessionSecretOnServerAsync(sessionSecret);
+    }
   }
 
   public async logoutAsync(): Promise<void> {
-    const sessionSecret = this.getSessionSecret();
-    if (sessionSecret) {
-      const apiV2Client = new ApiV2Client({ accessToken: null, sessionSecret });
-      try {
-        await apiV2Client.postAsync('auth/logout', { body: {} });
-      } catch (e) {
-        // Best-effort: clear the local session even if the server request fails
-        Log.debug('Failed to invalidate session secret on server:', e);
-      }
-    }
     this.currentActor = undefined;
+    if (isMultiAccountEnabled()) {
+      // Clearing the active account invalidates its session secret on the server.
+      await this.setSessionAsync(undefined);
+      return;
+    }
+    await this.invalidateCurrentSessionOnServerAsync();
     await this.setSessionAsync(undefined);
   }
 

packages/eas-cli/src/user/__tests__/SessionManager-test.ts

@@ -48,6 +48,8 @@ beforeEach(() => {
   jest.resetModules();
   jest.clearAllMocks();
   process.env = { ...OLD_ENV }; // Make a copy
+  // Tests must not depend on the experimental flag being set in the ambient shell
+  delete process.env.EAS_EXPERIMENTAL_ACCOUNT_SWITCHER;
 });
 
 afterEach(() => {
@@ -55,17 +57,17 @@ afterEach(() => {
 });
 
 describe(SessionManager, () => {
-  describe('getSession', () => {
+  describe('getActiveSession', () => {
     it('returns null when session is not stored', () => {
       const sessionManager = new SessionManager(analytics);
-      expect(sessionManager['getSession']()).toBeNull();
+      expect(sessionManager['getActiveSession']()).toBeNull();
     });
 
     it('returns stored session data', async () => {
       await fs.mkdirp(path.dirname(getStateJsonPath()));
       await fs.writeJSON(getStateJsonPath(), { auth: authStub });
       const sessionManager = new SessionManager(analytics);
-      expect(sessionManager['getSession']()).toMatchObject(authStub);
+      expect(sessionManager['getActiveSession']()).toMatchObject(authStub);
     });
   });
 
@@ -392,4 +394,123 @@ describe(SessionManager, () => {
       ).rejects.toThrowError('Cancelled login');
     });
   });
+
+  describe('multi-account (EAS_EXPERIMENTAL_ACCOUNT_SWITCHER=1)', () => {
+    const loginAsUserAsync = async (
+      sessionManager: SessionManager,
+      { id, username }: { id: string; username: string }
+    ): Promise<void> => {
+      jest.mocked(fetchSessionSecretAndUserAsync).mockResolvedValueOnce({
+        sessionSecret: `SECRET_${id}`,
+        id,
+        username,
+      });
+      await sessionManager['loginAsync']({ username, password: 'PASSWORD' });
+    };
+
+    beforeEach(() => {
+      process.env.EAS_EXPERIMENTAL_ACCOUNT_SWITCHER = '1';
+    });
+
+    it('migrates v0 state to v1 on login, preserving the old session and unrelated top-level keys', async () => {
+      await fs.mkdirp(path.dirname(getStateJsonPath()));
+      await fs.writeJSON(getStateJsonPath(), {
+        uuid: 'SOME_UUID',
+        auth: {
+          sessionSecret: 'OLD_SECRET',
+          userId: 'OLD_USER_ID',
+          username: 'OLD_USERNAME',
+          currentConnection: 'Username-Password-Authentication',
+        },
+      });
+
+      const sessionManager = new SessionManager(analytics);
+      await loginAsUserAsync(sessionManager, { id: 'USER_ID', username: 'USERNAME' });
+
+      const state = await fs.readJSON(getStateJsonPath());
+      expect(state.uuid).toBe('SOME_UUID');
+      expect(state.version).toBe(1);
+      expect(state.auth.activeAccountId).toBe('USER_ID');
+      expect(Object.keys(state.auth.accounts).sort()).toEqual(['OLD_USER_ID', 'USER_ID']);
+      expect(state.auth.sessionSecret).toBe('SECRET_USER_ID');
+      expect(state.auth.username).toBe('USERNAME');
+    });
+
+    it('uses an account for the process without persisting a switch', async () => {
+      const sessionManager = new SessionManager(analytics);
+      await loginAsUserAsync(sessionManager, { id: 'ID_A', username: 'user-a' });
+      await loginAsUserAsync(sessionManager, { id: 'ID_B', username: 'user-b' });
+
+      expect(sessionManager['getSessionSecret']()).toBe('SECRET_ID_B');
+
+      expect(sessionManager.useAccountForProcessByUsername('user-a')).toBe(true);
+      expect(sessionManager['getSessionSecret']()).toBe('SECRET_ID_A');
+
+      const state = await fs.readJSON(getStateJsonPath());
+      expect(state.auth.activeAccountId).toBe('ID_B');
+      expect(state.auth.sessionSecret).toBe('SECRET_ID_B');
+
+      expect(sessionManager.useAccountForProcessByUsername('nonexistent')).toBe(false);
+    });
+
+    it('invalidates the session secret on the server when removing an account', async () => {
+      const apiV2PostSpy = jest.spyOn(ApiV2Client.prototype, 'postAsync');
+      const sessionManager = new SessionManager(analytics);
+      await loginAsUserAsync(sessionManager, { id: 'ID_A', username: 'user-a' });
+      await loginAsUserAsync(sessionManager, { id: 'ID_B', username: 'user-b' });
+
+      await sessionManager.removeAccountAsync('ID_A');
+
+      expect(apiV2PostSpy).toHaveBeenCalledWith('auth/logout', { body: {} });
+      const state = await fs.readJSON(getStateJsonPath());
+      expect(Object.keys(state.auth.accounts)).toEqual(['ID_B']);
+      expect(state.auth.activeAccountId).toBe('ID_B');
+    });
+
+    it('invalidates all session secrets on the server when removing all accounts', async () => {
+      const apiV2PostSpy = jest.spyOn(ApiV2Client.prototype, 'postAsync');
+      const sessionManager = new SessionManager(analytics);
+      await loginAsUserAsync(sessionManager, { id: 'ID_A', username: 'user-a' });
+      await loginAsUserAsync(sessionManager, { id: 'ID_B', username: 'user-b' });
+
+      await sessionManager.removeAllAccountsAsync();
+
+      expect(apiV2PostSpy).toHaveBeenCalledTimes(2);
+      const state = await fs.readJSON(getStateJsonPath());
+      expect(state.auth.accounts).toEqual({});
+      expect(state.auth.activeAccountId).toBeNull();
+      expect(sessionManager['getSessionSecret']()).toBeNull();
+    });
+
+    it('keeps the v1 accounts map in sync when logging in with the flag off', async () => {
+      const sessionManager = new SessionManager(analytics);
+      await loginAsUserAsync(sessionManager, { id: 'ID_A', username: 'user-a' });
+
+      delete process.env.EAS_EXPERIMENTAL_ACCOUNT_SWITCHER;
+      await loginAsUserAsync(sessionManager, { id: 'ID_B', username: 'user-b' });
+
+      const state = await fs.readJSON(getStateJsonPath());
+      expect(state.auth.activeAccountId).toBe('ID_B');
+      expect(Object.keys(state.auth.accounts).sort()).toEqual(['ID_A', 'ID_B']);
+
+      // Re-enabling the flag must not resurrect the stale identity
+      process.env.EAS_EXPERIMENTAL_ACCOUNT_SWITCHER = '1';
+      expect(sessionManager['getActiveSession']()).toMatchObject({ userId: 'ID_B' });
+    });
+
+    it('preserves other stored accounts when logging out with the flag off', async () => {
+      const sessionManager = new SessionManager(analytics);
+      await loginAsUserAsync(sessionManager, { id: 'ID_A', username: 'user-a' });
+      await loginAsUserAsync(sessionManager, { id: 'ID_B', username: 'user-b' });
+
+      delete process.env.EAS_EXPERIMENTAL_ACCOUNT_SWITCHER;
+      await sessionManager.logoutAsync();
+
+      expect(sessionManager['getSessionSecret']()).toBeNull();
+      const state = await fs.readJSON(getStateJsonPath());
+      expect(state.auth.activeAccountId).toBeNull();
+      expect(Object.keys(state.auth.accounts)).toEqual(['ID_A']);
+      expect(state.auth.sessionSecret).toBeUndefined();
+    });
+  });
 });

packages/eas-cli/src/utils/easCli.ts

@@ -1,3 +1,13 @@
 const packageJSON = require('../../package.json');
 
 export const easCliVersion: string = packageJSON.version;
+
+/**
+ * Check if the experimental account switcher feature is enabled.
+ * This allows users to log in to multiple accounts and switch between them.
+ *
+ * Enable with: EAS_EXPERIMENTAL_ACCOUNT_SWITCHER=1
+ */
+export function isMultiAccountEnabled(): boolean {
+  return process.env.EAS_EXPERIMENTAL_ACCOUNT_SWITCHER === '1';
+}

packages/eas-cli/src/utils/usage/__tests__/checkForOverages-test.ts

@@ -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', () => {

packages/eas-cli/src/utils/usage/checkForOverages.ts

@@ -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 })
     );

packages/local-build-plugin/package.json

@@ -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",

packages/steps/package.json

@@ -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]>",

packages/steps/src/BuildStepCompositeFunctionScope.ts

@@ -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;
   }
 

packages/steps/src/BuildWorkflow.ts

@@ -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}${

packages/steps/src/__tests__/BuildStepCompositeFunctionScope-test.ts

@@ -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"');
+    });
   });
 });

packages/steps/src/__tests__/BuildWorkflow-hooks-test.ts

@@ -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' }],