[build-tools] - bubble validation error for when caches exceed max size

2026-11-13 20:28:08 -10:00 · 2026-06-11 10:34:23 -04:00 · 2026-06-10 17:03:32 -04:00 · 2026-06-10 16:48:58 -04:00 · 2026-06-10 14:29:55 +02:00 · 2026-06-10 12:21:53 +02:00
142 changed files with 11379 additions and 1877 deletions
@@ -10,8 +10,51 @@ This is the log of notable changes to EAS CLI and related packages.

 ### 🐛 Bug fixes

+- [expo-cocoapods-proxy] Fix iOS worker tarball build failing on macOS Tahoe due to bundler incompatibility with RubyGems 4. ([#3824](https://github.com/expo/eas-cli/pull/3824) by [@gwdp](https://github.com/gwdp))
+
 ### 🧹 Chores

+## [20.1.0](https://github.com/expo/eas-cli/releases/tag/v20.1.0) - 2026-06-05
+
+### 🎉 New features
+
+- [eas-cli] Add `eas update:embedded:view` command. ([#3810](https://github.com/expo/eas-cli/pull/3810) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add `eas update:embedded:list` command. ([#3811](https://github.com/expo/eas-cli/pull/3811) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add `eas update:embedded:delete` command. ([#3809](https://github.com/expo/eas-cli/pull/3809) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Auto-upload embedded bundle after build when `EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE` is set. ([#3767](https://github.com/expo/eas-cli/pull/3767) by [@gwdp](https://github.com/gwdp))
+
+## [20.0.0](https://github.com/expo/eas-cli/releases/tag/v20.0.0) - 2026-05-29
+
+### 🛠 Breaking changes
+
+- [eas-cli] Rename observe commands: `observe:logs` → `observe:events` (events emitted via `logEvent`), previous `observe:events` → `observe:metrics` (individual performance metric samples), previous `observe:metrics` → `observe:metrics-summary` (aggregated stats by app version). ([#3778](https://github.com/expo/eas-cli/pull/3778) by [@kadikraman](https://github.com/kadikraman))
+
+### 🎉 New features
+
+- [eas-cli] `eas go` now prompts to select an Expo SDK version interactively when `--sdk-version` is not provided. ([#3768](https://github.com/expo/eas-cli/pull/3768) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add `eas update:embedded:upload` command. ([#3720](https://github.com/expo/eas-cli/pull/3720) by [@gwdp](https://github.com/gwdp))
+
+### 🐛 Bug fixes
+
+- [build-tools] Fix `eas/start_ios_simulator` hanging on Xcode 26.4 by writing the readiness screenshot to a temp file instead of `/dev/null`. ([#3794](https://github.com/expo/eas-cli/pull/3794) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Disable `apsd` in the iOS Simulator after boot to stop a push-registration log storm that pegs `diagnosticd` CPU for the lifetime of the Simulator. ([#3795](https://github.com/expo/eas-cli/pull/3795) by [@gwdp](https://github.com/gwdp))
+
+## [19.1.0](https://github.com/expo/eas-cli/releases/tag/v19.1.0) - 2026-05-25
+
+### 🎉 New features
+
+- [eas-cli] Add `--refresh-ad-hoc-provisioning-profile` flag to refresh managed ad-hoc provisioning profiles from App Store Connect before gathering build credentials in non-interactive mode. ([#3716](https://github.com/expo/eas-cli/pull/3716) by [@sswrk](https://github.com/sswrk))
+- [eas-build-job] Add optional `refreshAdHocProvisioningProfile` field to iOS build jobs. ([#3717](https://github.com/expo/eas-cli/pull/3717) by [@sswrk](https://github.com/sswrk))
+- [build-tools] Pass `refreshAdHocProvisioningProfile` through `eas build:internal` for git-based integration builds. ([#3770](https://github.com/expo/eas-cli/pull/3770) by [@sswrk](https://github.com/sswrk))
+
+## [19.0.8](https://github.com/expo/eas-cli/releases/tag/v19.0.8) - 2026-05-21
+
+### 🐛 Bug fixes
+
+- [eas-cli] `eas go` now pre-selects the SDK version from the current project's `app.json` or `app.config.js` when available. ([#3776](https://github.com/expo/eas-cli/pull/3776) by [@gwdp](https://github.com/gwdp))
+
+## [19.0.7](https://github.com/expo/eas-cli/releases/tag/v19.0.7) - 2026-05-21
+
 ## [19.0.6](https://github.com/expo/eas-cli/releases/tag/v19.0.6) - 2026-05-21

 ### 🐛 Bug fixes
@@ -1,5 +1,5 @@
 {
  "npmClient": "yarn",
-  "version": "19.0.7",
+  "version": "20.1.0",
  "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
@@ -3,4 +3,6 @@ _.path = "./tools/bin"
 MISE_NODE_COREPACK = "true"

 [tools]
+gcloud = "570.0.0"
+jq = "1.8.1"
 node = "20.19.4"
@@ -1,6 +1,6 @@
 {
  "name": "@expo/build-tools",
-  "version": "19.0.6",
+  "version": "20.1.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
  "author": "Expo <[email protected]>",
@@ -37,19 +37,20 @@
  "dependencies": {
    "@expo/config": "55.0.10",
    "@expo/config-plugins": "55.0.7",
-    "@expo/downloader": "19.0.0",
-    "@expo/eas-build-job": "19.0.0",
+    "@expo/downloader": "20.0.0",
+    "@expo/eas-build-job": "20.1.0",
    "@expo/env": "^0.4.0",
-    "@expo/logger": "19.0.0",
+    "@expo/logger": "20.0.0",
    "@expo/package-manager": "1.9.10",
    "@expo/plist": "^0.2.0",
    "@expo/results": "^1.0.0",
    "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "19.0.0",
-    "@expo/template-file": "19.0.0",
-    "@expo/turtle-spawn": "19.0.0",
+    "@expo/steps": "20.1.0",
+    "@expo/template-file": "20.0.0",
+    "@expo/turtle-spawn": "20.0.0",
    "@expo/xcpretty": "^4.3.1",
    "@google-cloud/storage": "^7.11.2",
+    "@ngrok/ngrok": "1.7.0",
    "@sentry/node": "7.77.0",
    "@urql/core": "^6.0.1",
    "bplist-parser": "0.3.2",
@@ -76,7 +77,7 @@
    "zod": "^4.3.5"
  },
  "devDependencies": {
-    "@expo/repack-app": "~0.4.1",
+    "@expo/repack-app": "~0.6.1",
    "@types/fs-extra": "^11.0.4",
    "@types/jest": "^29.5.12",
    "@types/lodash": "^4.17.4",
@@ -22,13 +22,13 @@ describe('Datadog singleton', () => {
    Datadog.setup(null);
  });

-  it('POSTs distribution metrics to the turtle build metrics endpoint', () => {
+  it('POSTs distribution metrics to the turtle build metrics endpoint for build targets', () => {
    turtleFetchMock.mockResolvedValueOnce({} as Response);

    Datadog.setup({
      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
-      turtleBuildId: 'build-id',
      robotAccessToken: 'token-abc',
+      target: { kind: 'build', turtleBuildId: 'build-id' },
    });

    Datadog.distribution('eas.build.phase_duration', 1234, {
@@ -51,6 +51,7 @@ describe('Datadog singleton', () => {
                build_phase: 'install_dependencies',
                platform: 'ios',
                result: 'success',
+                target: 'build',
              },
            },
          ],
@@ -61,20 +62,121 @@ describe('Datadog singleton', () => {
    );
  });

+  it('POSTs distribution metrics to the turtle job run metrics endpoint for jobRun targets', () => {
+    turtleFetchMock.mockResolvedValueOnce({} as Response);
+
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      robotAccessToken: 'token-abc',
+      target: { kind: 'jobRun', turtleJobRunId: 'job-run-id' },
+    });
+
+    Datadog.distribution('eas.maestro.install', 1, {
+      maestro_version: '2.1.0',
+    });
+
+    expect(turtleFetchMock).toHaveBeenCalledWith(
+      'https://api.expo.test/v2/turtle-job-runs/job-run-id/metrics',
+      'POST',
+      {
+        json: {
+          metrics: [
+            {
+              name: 'eas.maestro.install',
+              type: 'distribution',
+              value: 1,
+              tags: {
+                maestro_version: '2.1.0',
+                target: 'job_run',
+              },
+            },
+          ],
+        },
+        headers: { Authorization: 'Bearer token-abc' },
+        retries: 2,
+      }
+    );
+  });
+
+  it('POSTs logs to the turtle build logs endpoint with buildId for build targets', () => {
+    turtleFetchMock.mockResolvedValueOnce({} as Response);
+
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      robotAccessToken: 'token-abc',
+      target: { kind: 'build', turtleBuildId: 'build-id' },
+    });
+
+    Datadog.log('artifact dry-run matched', {
+      event: 'find_artifacts_absolute_path_dry_run',
+      status: 'match',
+    });
+
+    expect(turtleFetchMock).toHaveBeenCalledWith(
+      'https://api.expo.test/v2/turtle-builds/logs',
+      'POST',
+      {
+        json: {
+          buildId: 'build-id',
+          message: 'artifact dry-run matched',
+          tags: {
+            event: 'find_artifacts_absolute_path_dry_run',
+            status: 'match',
+            target: 'build',
+          },
+        },
+        headers: { Authorization: 'Bearer token-abc' },
+        shouldThrowOnNotOk: false,
+      }
+    );
+  });
+
+  it('POSTs logs to the turtle job run logs endpoint with jobRunId for jobRun targets', () => {
+    turtleFetchMock.mockResolvedValueOnce({} as Response);
+
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      robotAccessToken: 'token-abc',
+      target: { kind: 'jobRun', turtleJobRunId: 'job-run-id' },
+    });
+
+    Datadog.log('Gradle cache restored (hit)', {
+      cache_type: 'gradle',
+    });
+
+    expect(turtleFetchMock).toHaveBeenCalledWith(
+      'https://api.expo.test/v2/turtle-job-runs/logs',
+      'POST',
+      {
+        json: {
+          jobRunId: 'job-run-id',
+          message: 'Gradle cache restored (hit)',
+          tags: {
+            cache_type: 'gradle',
+            target: 'job_run',
+          },
+        },
+        headers: { Authorization: 'Bearer token-abc' },
+        shouldThrowOnNotOk: false,
+      }
+    );
+  });
+
  it('is a no-op when setup is null', () => {
    Datadog.setup(null);

    Datadog.distribution('eas.build.phase_duration', 1);
+    Datadog.log('artifact dry-run matched');

    expect(turtleFetchMock).not.toHaveBeenCalled();
  });

-  it('swallows upload failures', async () => {
+  it('swallows metric upload failures for build targets', async () => {
    turtleFetchMock.mockRejectedValueOnce(new Error('network down'));
    Datadog.setup({
      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
-      turtleBuildId: 'build-id',
      robotAccessToken: 'token-abc',
+      target: { kind: 'build', turtleBuildId: 'build-id' },
    });

    Datadog.distribution('eas.build.phase_duration', 1);
@@ -86,7 +188,96 @@ describe('Datadog singleton', () => {
      expect.any(Error),
      expect.objectContaining({
        extras: {
-          metrics: [{ name: 'eas.build.phase_duration', type: 'distribution', value: 1, tags: {} }],
+          metrics: [
+            {
+              name: 'eas.build.phase_duration',
+              type: 'distribution',
+              value: 1,
+              tags: { target: 'build' },
+            },
+          ],
+        },
+      })
+    );
+  });
+
+  it('labels metric upload failures for jobRun targets with the jobRun kind', async () => {
+    turtleFetchMock.mockRejectedValueOnce(new Error('network down'));
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      robotAccessToken: 'token-abc',
+      target: { kind: 'jobRun', turtleJobRunId: 'job-run-id' },
+    });
+
+    Datadog.distribution('eas.maestro.install', 1);
+    await flushPromises();
+
+    expect(sentryCaptureMock).toHaveBeenCalledWith(
+      'Failed to report turtle jobRun metric',
+      expect.any(Error),
+      expect.objectContaining({
+        extras: {
+          metrics: [
+            {
+              name: 'eas.maestro.install',
+              type: 'distribution',
+              value: 1,
+              tags: { target: 'job_run' },
+            },
+          ],
+        },
+      })
+    );
+  });
+
+  it('swallows log upload failures for build targets', async () => {
+    turtleFetchMock.mockRejectedValueOnce(new Error('network down'));
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      robotAccessToken: 'token-abc',
+      target: { kind: 'build', turtleBuildId: 'build-id' },
+    });
+
+    Datadog.log('artifact dry-run matched');
+    await flushPromises();
+
+    expect(turtleFetchMock).toHaveBeenCalled();
+    expect(sentryCaptureMock).toHaveBeenCalledWith(
+      'Failed to report turtle build log',
+      expect.any(Error),
+      expect.objectContaining({
+        extras: {
+          log: {
+            buildId: 'build-id',
+            message: 'artifact dry-run matched',
+            tags: { target: 'build' },
+          },
+        },
+      })
+    );
+  });
+
+  it('labels log upload failures for jobRun targets with the jobRun kind', async () => {
+    turtleFetchMock.mockRejectedValueOnce(new Error('network down'));
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      robotAccessToken: 'token-abc',
+      target: { kind: 'jobRun', turtleJobRunId: 'job-run-id' },
+    });
+
+    Datadog.log('Gradle cache restored (hit)');
+    await flushPromises();
+
+    expect(sentryCaptureMock).toHaveBeenCalledWith(
+      'Failed to report turtle jobRun log',
+      expect.any(Error),
+      expect.objectContaining({
+        extras: {
+          log: {
+            jobRunId: 'job-run-id',
+            message: 'Gradle cache restored (hit)',
+            tags: { target: 'job_run' },
+          },
        },
      })
    );
@@ -97,19 +288,29 @@ describe('Datadog singleton', () => {

    Datadog.setup({
      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
-      turtleBuildId: 'first-build-id',
      robotAccessToken: 'first-token',
+      target: { kind: 'build', turtleBuildId: 'first-build-id' },
    });
    Datadog.setup({
      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
-      turtleBuildId: 'second-build-id',
      robotAccessToken: 'second-token',
+      target: { kind: 'jobRun', turtleJobRunId: 'job-run-id' },
    });

    Datadog.distribution('eas.build.phase_duration', 1);
+    Datadog.log('artifact dry-run matched');

-    expect(turtleFetchMock).toHaveBeenCalledWith(
-      'https://api.expo.test/v2/turtle-builds/second-build-id/metrics',
+    expect(turtleFetchMock).toHaveBeenNthCalledWith(
+      1,
+      'https://api.expo.test/v2/turtle-job-runs/job-run-id/metrics',
+      'POST',
+      expect.objectContaining({
+        headers: { Authorization: 'Bearer second-token' },
+      })
+    );
+    expect(turtleFetchMock).toHaveBeenNthCalledWith(
+      2,
+      'https://api.expo.test/v2/turtle-job-runs/logs',
      'POST',
      expect.objectContaining({
        headers: { Authorization: 'Bearer second-token' },
@@ -126,8 +327,8 @@ describe('Datadog singleton', () => {
    );
    Datadog.setup({
      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
-      turtleBuildId: 'build-id',
      robotAccessToken: 'token-abc',
+      target: { kind: 'build', turtleBuildId: 'build-id' },
    });

    let flushed = false;
@@ -143,6 +344,62 @@ describe('Datadog singleton', () => {

    expect(flushed).toBe(true);
  });
+
+  it('flushes pending log uploads', async () => {
+    let resolveUpload!: (response: Response) => void;
+    turtleFetchMock.mockReturnValueOnce(
+      new Promise<Response>(resolve => {
+        resolveUpload = resolve;
+      })
+    );
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      robotAccessToken: 'token-abc',
+      target: { kind: 'build', turtleBuildId: 'build-id' },
+    });
+
+    let flushed = false;
+    Datadog.log('artifact dry-run matched');
+    const flushPromise = Datadog.flushAsync().then(() => {
+      flushed = true;
+    });
+    await Promise.resolve();
+    expect(flushed).toBe(false);
+
+    resolveUpload({} as Response);
+    await flushPromise;
+
+    expect(flushed).toBe(true);
+  });
+
+  it('only awaits uploads enqueued since the previous flush', async () => {
+    let resolveSecondUpload!: (response: Response) => void;
+    turtleFetchMock.mockReturnValueOnce(new Promise<Response>(() => {})).mockReturnValueOnce(
+      new Promise<Response>(resolve => {
+        resolveSecondUpload = resolve;
+      })
+    );
+    Datadog.setup({
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+      robotAccessToken: 'token-abc',
+      target: { kind: 'build', turtleBuildId: 'build-id' },
+    });
+
+    // The first upload never settles; the first flush rotates it out of the queue.
+    Datadog.distribution('eas.build.phase_duration', 1);
+    void Datadog.flushAsync();
+
+    Datadog.distribution('eas.build.phase_duration', 2);
+    let flushed = false;
+    const flushPromise = Datadog.flushAsync().then(() => {
+      flushed = true;
+    });
+
+    resolveSecondUpload({} as Response);
+    await flushPromise;
+
+    expect(flushed).toBe(true);
+  });
 });

 async function flushPromises(): Promise<void> {
@@ -0,0 +1,317 @@
+import fetch from 'node-fetch';
+
+import { RuntimeSettings } from '../runtimeSettings';
+import { Sentry } from '../sentry';
+
+jest.mock('node-fetch', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+jest.mock('../sentry', () => ({
+  Sentry: {
+    capture: jest.fn(),
+  },
+}));
+
+describe('runtimeSettings', () => {
+  const logger = {
+    info: jest.fn(),
+    warn: jest.fn(),
+  };
+  const originalCacheUrls = {
+    EAS_NPM_CACHE_URL: process.env.EAS_NPM_CACHE_URL,
+    EAS_NODEJS_CACHE_URL: process.env.EAS_NODEJS_CACHE_URL,
+    EAS_MAVEN_CACHE_URL: process.env.EAS_MAVEN_CACHE_URL,
+    EAS_COCOAPODS_CACHE_URL: process.env.EAS_COCOAPODS_CACHE_URL,
+  };
+  const originalPlatform = process.platform;
+
+  afterEach(() => {
+    jest.mocked(fetch).mockReset();
+    jest.restoreAllMocks();
+    jest.mocked(Sentry.capture).mockReset();
+    logger.info.mockReset();
+    logger.warn.mockReset();
+    restoreEnv('EAS_NPM_CACHE_URL', originalCacheUrls.EAS_NPM_CACHE_URL);
+    restoreEnv('EAS_NODEJS_CACHE_URL', originalCacheUrls.EAS_NODEJS_CACHE_URL);
+    restoreEnv('EAS_MAVEN_CACHE_URL', originalCacheUrls.EAS_MAVEN_CACHE_URL);
+    restoreEnv('EAS_COCOAPODS_CACHE_URL', originalCacheUrls.EAS_COCOAPODS_CACHE_URL);
+    mockProcessPlatform(originalPlatform);
+  });
+
+  beforeEach(async () => {
+    jest.mocked(fetch).mockResolvedValue(response({}));
+    await RuntimeSettings.loadAsync({ environment: 'staging', logger: logger as any });
+    jest.mocked(fetch).mockReset();
+    logger.info.mockReset();
+    logger.warn.mockReset();
+  });
+
+  it('fetches runtime settings from the staging and production buckets', async () => {
+    jest.mocked(fetch).mockResolvedValue(response({}));
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      logger: logger as any,
+      cacheUrlFallbacks: {
+        npm: 'https://fallback-npm.example',
+      },
+    });
+    await RuntimeSettings.loadAsync({ environment: 'production', logger: logger as any });
+    await RuntimeSettings.loadAsync({ environment: 'test', logger: logger as any });
+
+    expect(fetch).toHaveBeenNthCalledWith(
+      1,
+      'https://storage.googleapis.com/eas-workflows-staging/runtime-settings.json',
+      {
+        signal: expect.anything(),
+      }
+    );
+    expect(fetch).toHaveBeenNthCalledWith(
+      2,
+      'https://storage.googleapis.com/eas-workflows-production/runtime-settings.json',
+      {
+        signal: expect.anything(),
+      }
+    );
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not use caches by default when remote settings are unavailable', async () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+    jest.mocked(fetch).mockResolvedValue(response({}, 404));
+
+    await RuntimeSettings.loadAsync({ environment: 'staging', logger: logger as any });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+    expect(RuntimeSettings.isUsingIosPrecompiledModulesEnabled()).toBe(false);
+    expect(logger.warn).toHaveBeenCalled();
+    expect(Sentry.capture).toHaveBeenCalledWith('Failed to fetch worker runtime settings', {
+      extras: {
+        status: 404,
+        url: 'https://storage.googleapis.com/eas-workflows-staging/runtime-settings.json',
+      },
+      level: 'warning',
+    });
+  });
+
+  it('does not override existing settings when remote settings are invalid', async () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+    jest
+      .mocked(fetch)
+      .mockResolvedValueOnce(response({ caches: { linux: { npm: true } } }))
+      .mockResolvedValueOnce(response({ iosPrecompiledModules: 'enabled' }));
+
+    await RuntimeSettings.loadAsync({ environment: 'staging', logger: logger as any });
+    await RuntimeSettings.loadAsync({ environment: 'staging', logger: logger as any });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBe('https://npm.example');
+    expect(RuntimeSettings.isUsingIosPrecompiledModulesEnabled()).toBe(false);
+    expect(logger.warn).toHaveBeenCalled();
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      'Failed to load worker runtime settings',
+      expect.any(Error),
+      {
+        extras: {
+          url: 'https://storage.googleapis.com/eas-workflows-staging/runtime-settings.json',
+        },
+        level: 'warning',
+      }
+    );
+  });
+
+  it('accepts partial runtime settings and ignores unknown fields', async () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+    process.env.EAS_NODEJS_CACHE_URL = 'https://node.example';
+    process.env.EAS_MAVEN_CACHE_URL = 'https://maven.example';
+    process.env.EAS_COCOAPODS_CACHE_URL = 'https://pods.example';
+    jest.mocked(fetch).mockResolvedValue(
+      response({
+        caches: {
+          linux: { npm: false, nodejs: true, maven: true },
+          darwin: { npm: true, maven: true, cocoapods: false },
+        },
+        iosPrecompiledModules: true,
+        unknownFutureSetting: true,
+      })
+    );
+
+    await RuntimeSettings.loadAsync({ environment: 'staging', logger: logger as any });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+    expect(RuntimeSettings.getNodeJsCacheUrl()).toBe('https://node.example');
+    expect(RuntimeSettings.getMavenCacheUrl()).toBe('https://maven.example');
+    mockProcessPlatform('darwin');
+    expect(RuntimeSettings.getMavenCacheUrl()).toBe('https://maven.example');
+    expect(RuntimeSettings.getCocoapodsCacheUrl()).toBeNull();
+    expect(RuntimeSettings.getNpmCacheUrl()).toBe('https://npm.example');
+    expect(RuntimeSettings.isUsingIosPrecompiledModulesEnabled()).toBe(true);
+  });
+
+  it('uses Maven and CocoaPods caches when enabled for the current platform and their environment variables exist', async () => {
+    process.env.EAS_MAVEN_CACHE_URL = 'https://maven.example';
+    process.env.EAS_COCOAPODS_CACHE_URL = 'https://pods.example';
+    jest.mocked(fetch).mockResolvedValue(
+      response({
+        caches: {
+          linux: { maven: true },
+          darwin: { maven: true, cocoapods: true },
+        },
+      })
+    );
+
+    await RuntimeSettings.loadAsync({ environment: 'staging', logger: logger as any });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getMavenCacheUrl()).toBe('https://maven.example');
+    mockProcessPlatform('darwin');
+    expect(RuntimeSettings.getMavenCacheUrl()).toBe('https://maven.example');
+    expect(RuntimeSettings.getCocoapodsCacheUrl()).toBe('https://pods.example');
+  });
+
+  it('uses cache URL fallbacks when enabled cache environment variables are not set', async () => {
+    jest.mocked(fetch).mockResolvedValue(
+      response({
+        caches: {
+          linux: { npm: true, nodejs: true, maven: true },
+          darwin: { cocoapods: true },
+        },
+      })
+    );
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      logger: logger as any,
+      cacheUrlFallbacks: {
+        npm: 'https://fallback-npm.example',
+        nodejs: 'https://fallback-node.example',
+        maven: 'https://fallback-maven.example',
+        cocoapods: 'https://fallback-pods.example',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBe('https://fallback-npm.example');
+    expect(RuntimeSettings.getNodeJsCacheUrl()).toBe('https://fallback-node.example');
+    expect(RuntimeSettings.getMavenCacheUrl()).toBe('https://fallback-maven.example');
+    mockProcessPlatform('darwin');
+    expect(RuntimeSettings.getCocoapodsCacheUrl()).toBe('https://fallback-pods.example');
+  });
+
+  it('prefers cache URL environment variables over fallbacks', async () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+    jest.mocked(fetch).mockResolvedValue(
+      response({
+        caches: {
+          linux: { npm: true },
+        },
+      })
+    );
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      logger: logger as any,
+      cacheUrlFallbacks: {
+        npm: 'https://fallback-npm.example',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBe('https://npm.example');
+  });
+
+  it('does not use cache URL fallbacks when runtime settings disable caches', async () => {
+    jest.mocked(fetch).mockResolvedValue(
+      response({
+        caches: {
+          linux: { npm: false },
+        },
+      })
+    );
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      logger: logger as any,
+      cacheUrlFallbacks: {
+        npm: 'https://fallback-npm.example',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+  });
+
+  it('clears cache URL fallbacks when loading without them', async () => {
+    jest.mocked(fetch).mockResolvedValue(response({ caches: { linux: { npm: true } } }));
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      logger: logger as any,
+      cacheUrlFallbacks: {
+        npm: 'https://fallback-npm.example',
+      },
+    });
+    await RuntimeSettings.loadAsync({ environment: 'staging', logger: logger as any });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+  });
+
+  it('does not use caches when runtime settings are not loaded', () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+
+    jest.isolateModules(() => {
+      const { RuntimeSettings } = require('../runtimeSettings');
+
+      expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+      expect(RuntimeSettings.isUsingIosPrecompiledModulesEnabled()).toBe(false);
+    });
+  });
+
+  it('reports when loaded runtime settings omit the current platform cache settings', async () => {
+    jest.mocked(fetch).mockResolvedValue(response({ caches: { linux: { npm: true } } }));
+    mockProcessPlatform('darwin');
+
+    await RuntimeSettings.loadAsync({ environment: 'staging', logger: logger as any });
+
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'Runtime settings are missing cache settings for platform "darwin"',
+      }),
+      {
+        extras: {
+          configuredPlatforms: ['linux'],
+          platform: 'darwin',
+        },
+        level: 'error',
+      }
+    );
+  });
+});
+
+function restoreEnv(key: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+}
+
+function mockProcessPlatform(platform: NodeJS.Platform): void {
+  Object.defineProperty(process, 'platform', {
+    configurable: true,
+    value: platform,
+  });
+}
+
+function response(body: unknown, status = 200): any {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  };
+}
@@ -4,7 +4,9 @@ import { vol } from 'memfs';
 import { createTestAndroidJob } from '../../__tests__/utils/job';
 import { createMockLogger } from '../../__tests__/utils/logger';
 import { BuildContext } from '../../context';
+import { Datadog } from '../../datadog';
 import { restoreCredentials } from '../../android/credentials';
+import { uploadEmbeddedBundleAsync } from '../../utils/expoUpdatesEmbedded';
 import androidBuilder from '../android';
 import { runBuilderWithHooksAsync } from '../common';
 import {
@@ -56,6 +58,9 @@ jest.mock('../../utils/expoUpdates', () => ({
  configureExpoUpdatesIfInstalledAsync: jest.fn(),
  resolveRuntimeVersionForExpoUpdatesIfConfiguredAsync: jest.fn(async () => null),
 }));
+jest.mock('../../utils/expoUpdatesEmbedded', () => ({
+  uploadEmbeddedBundleAsync: jest.fn(),
+}));
 jest.mock('../../utils/hooks', () => ({
  Hook: {
    POST_INSTALL: 'POST_INSTALL',
@@ -67,8 +72,11 @@ jest.mock('../../utils/prepareBuildExecutable', () => ({
  prepareExecutableAsync: jest.fn(),
 }));

+const datadogDistributionMock = jest.spyOn(Datadog, 'distribution');
+
 describe(androidBuilder, () => {
  beforeEach(() => {
+    jest.clearAllMocks();
    vol.fromJSON(
      {
        '/workingdir/env/.gitkeep': '',
@@ -138,7 +146,6 @@ describe(androidBuilder, () => {
  });

  it('marks the configure Android version phase as warning for legacy eas-build.gradle', async () => {
-    const reportBuildPhaseStats = jest.fn();
    const job: Android.Job = {
      ...createTestAndroidJob(),
      secrets: {
@@ -157,23 +164,23 @@ describe(androidBuilder, () => {
        __API_SERVER_URL: 'http://api.expo.test',
      },
      uploadArtifact: jest.fn(),
-      reportBuildPhaseStats,
    });
    vol.mkdirSync('/workingdir/build/android/app', { recursive: true });
    vol.writeFileSync('/workingdir/build/android/app/eas-build.gradle', '// Legacy content');

    await androidBuilder(ctx);

-    expect(reportBuildPhaseStats).toHaveBeenCalledWith(
+    expect(datadogDistributionMock).toHaveBeenCalledWith(
+      'eas.build.phase_duration',
+      expect.any(Number),
      expect.objectContaining({
-        buildPhase: BuildPhase.CONFIGURE_ANDROID_VERSION,
+        build_phase: BuildPhase.CONFIGURE_ANDROID_VERSION.toLowerCase(),
        result: BuildPhaseResult.WARNING,
      })
    );
  });

  it('marks the prepare credentials phase as warning for legacy eas-build.gradle', async () => {
-    const reportBuildPhaseStats = jest.fn();
    const ctx = new BuildContext(createTestAndroidJob(), {
      workingdir: '/workingdir',
      logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
@@ -182,23 +189,23 @@ describe(androidBuilder, () => {
        __API_SERVER_URL: 'http://api.expo.test',
      },
      uploadArtifact: jest.fn(),
-      reportBuildPhaseStats,
    });
    vol.mkdirSync('/workingdir/build/android/app', { recursive: true });
    vol.writeFileSync('/workingdir/build/android/app/eas-build.gradle', '// Legacy content');

    await androidBuilder(ctx);

-    expect(reportBuildPhaseStats).toHaveBeenCalledWith(
+    expect(datadogDistributionMock).toHaveBeenCalledWith(
+      'eas.build.phase_duration',
+      expect.any(Number),
      expect.objectContaining({
-        buildPhase: BuildPhase.PREPARE_CREDENTIALS,
+        build_phase: BuildPhase.PREPARE_CREDENTIALS.toLowerCase(),
        result: BuildPhaseResult.WARNING,
      })
    );
  });

  it('injects credentials and version config when both are configured', async () => {
-    const reportBuildPhaseStats = jest.fn();
    const job: Android.Job = {
      ...createTestAndroidJob(),
      version: {
@@ -214,7 +221,6 @@ describe(androidBuilder, () => {
        __API_SERVER_URL: 'http://api.expo.test',
      },
      uploadArtifact: jest.fn(),
-      reportBuildPhaseStats,
    });
    vol.mkdirSync('/workingdir/build/android/app', { recursive: true });
    vol.writeFileSync('/workingdir/build/android/app/eas-build.gradle', '// Legacy content');
@@ -234,15 +240,19 @@ describe(androidBuilder, () => {
        versionName: '1.2.3',
      }
    );
-    expect(reportBuildPhaseStats).toHaveBeenCalledWith(
+    expect(datadogDistributionMock).toHaveBeenCalledWith(
+      'eas.build.phase_duration',
+      expect.any(Number),
      expect.objectContaining({
-        buildPhase: BuildPhase.PREPARE_CREDENTIALS,
+        build_phase: BuildPhase.PREPARE_CREDENTIALS.toLowerCase(),
        result: BuildPhaseResult.WARNING,
      })
    );
-    expect(reportBuildPhaseStats).toHaveBeenCalledWith(
+    expect(datadogDistributionMock).toHaveBeenCalledWith(
+      'eas.build.phase_duration',
+      expect.any(Number),
      expect.objectContaining({
-        buildPhase: BuildPhase.CONFIGURE_ANDROID_VERSION,
+        build_phase: BuildPhase.CONFIGURE_ANDROID_VERSION.toLowerCase(),
        result: BuildPhaseResult.WARNING,
      })
    );
@@ -263,4 +273,37 @@ describe(androidBuilder, () => {

    expect(runBuilderWithHooksAsync).toHaveBeenCalledWith(ctx, expect.any(Function));
  });
+
+  it('runs the embedded bundle upload phase when EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE is set', async () => {
+    const ctx = new BuildContext(createTestAndroidJob(), {
+      workingdir: '/workingdir',
+      logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
+      logger: createMockLogger(),
+      env: {
+        __API_SERVER_URL: 'http://api.expo.test',
+        EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE: '1',
+      },
+      uploadArtifact: jest.fn(),
+    });
+
+    await androidBuilder(ctx);
+
+    expect(uploadEmbeddedBundleAsync).toHaveBeenCalledWith(ctx);
+  });
+
+  it('skips the embedded bundle upload phase when EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE is not set', async () => {
+    const ctx = new BuildContext(createTestAndroidJob(), {
+      workingdir: '/workingdir',
+      logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
+      logger: createMockLogger(),
+      env: {
+        __API_SERVER_URL: 'http://api.expo.test',
+      },
+      uploadArtifact: jest.fn(),
+    });
+
+    await androidBuilder(ctx);
+
+    expect(uploadEmbeddedBundleAsync).not.toHaveBeenCalled();
+  });
 });
@@ -32,6 +32,7 @@ import {
  configureExpoUpdatesIfInstalledAsync,
  resolveRuntimeVersionForExpoUpdatesIfConfiguredAsync,
 } from '../utils/expoUpdates';
+import { uploadEmbeddedBundleAsync } from '../utils/expoUpdatesEmbedded';
 import { Hook, runHookIfPresent } from '../utils/hooks';
 import { prepareExecutableAsync } from '../utils/prepareBuildExecutable';

@@ -208,6 +209,12 @@ async function buildAsync(ctx: BuildContext<Android.Job>): Promise<void> {
    });
  });

+  if (ctx.env.EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE) {
+    await ctx.runBuildPhase(BuildPhase.UPLOAD_EMBEDDED_BUNDLE, async () => {
+      await uploadEmbeddedBundleAsync(ctx);
+    });
+  }
+
  await ctx.runBuildPhase(BuildPhase.SAVE_CACHE, async () => {
    if (ctx.isLocal) {
      ctx.logger.info('Local builds do not support saving cache.');
@@ -25,6 +25,7 @@ import {
  configureExpoUpdatesIfInstalledAsync,
  resolveRuntimeVersionForExpoUpdatesIfConfiguredAsync,
 } from '../utils/expoUpdates';
+import { uploadEmbeddedBundleAsync } from '../utils/expoUpdatesEmbedded';
 import { Hook, runHookIfPresent } from '../utils/hooks';
 import { prepareExecutableAsync } from '../utils/prepareBuildExecutable';
 import { getParentAndDescendantProcessPidsAsync } from '../utils/processes';
@@ -181,13 +182,16 @@ async function buildAsync(ctx: BuildContext<Ios.Job>): Promise<void> {
    }
    try {
      const { derivedDataPath, workspacePath } = nullthrows(fastlaneResult);
-      await parseAndReportXcactivitylog({
+      const { skipped } = await parseAndReportXcactivitylog({
        derivedDataPath,
        workspacePath,
        logger: ctx.logger,
        proxyBaseUrl: ctx.env.EAS_BUILD_COCOAPODS_CACHE_URL,
        env: ctx.env,
      });
+      if (skipped) {
+        ctx.markBuildPhaseSkipped();
+      }
    } catch (err: any) {
      Sentry.capture('Failed to parse xcactivitylog', err);
      ctx.markBuildPhaseSkipped();
@@ -206,6 +210,12 @@ async function buildAsync(ctx: BuildContext<Ios.Job>): Promise<void> {
    });
  });

+  if (ctx.env.EAS_UPDATE_EXPERIMENTAL_UPLOAD_EMBEDDED_BUNDLE) {
+    await ctx.runBuildPhase(BuildPhase.UPLOAD_EMBEDDED_BUNDLE, async () => {
+      await uploadEmbeddedBundleAsync(ctx);
+    });
+  }
+
  await ctx.runBuildPhase(BuildPhase.SAVE_CACHE, async () => {
    if (ctx.isLocal) {
      ctx.logger.info('Local builds do not support saving cache.');
@@ -1,4 +1,4 @@
-import { BuildJob } from '@expo/eas-build-job';
+import { ArchiveSourceType, BuildJob, Platform, Workflow } from '@expo/eas-build-job';
 import spawn from '@expo/turtle-spawn';

 import { resolveEnvFromBuildProfileAsync, runEasBuildInternalAsync } from '../easBuildInternal';
@@ -15,7 +15,7 @@ jest.mock('../../utils/easCli', () => ({

 describe('easBuildInternal', () => {
  beforeEach(() => {
-    jest.resetAllMocks();
+    jest.clearAllMocks();
    jest.mocked(resolveEasCommandPrefixAndEnvAsync).mockResolvedValue({
      cmd: 'npx',
      args: ['-y', 'eas-cli@latest'],
@@ -69,4 +69,131 @@ describe('easBuildInternal', () => {
    expect(resolveEasCommandPrefixAndEnvAsync).toHaveBeenCalledWith();
    expect(spawn).not.toHaveBeenCalled();
  });
+
+  it('passes --refresh-ad-hoc-provisioning-profile to build:internal for iOS jobs with refreshAdHocProvisioningProfile', async () => {
+    const logger = {
+      info: jest.fn(),
+      warn: jest.fn(),
+      error: jest.fn(),
+      child: jest.fn(),
+    } as any;
+
+    const internalJob = {
+      platform: Platform.IOS,
+      type: Workflow.GENERIC,
+      triggeredBy: 'EAS_CLI',
+      projectArchive: { type: ArchiveSourceType.URL, url: 'https://example.com' },
+      projectRootDirectory: '.',
+      secrets: {
+        buildCredentials: {
+          testapp: {
+            distributionCertificate: {
+              dataBase64: 'YmluYXJ5Y29udGVudDE=',
+              password: 'distCertPassword',
+            },
+            provisioningProfileBase64: 'MnRuZXRub2N5cmFuaWI=',
+          },
+        },
+      },
+      initiatingUserId: 'user-id',
+      appId: 'app-id',
+    };
+
+    jest.mocked(spawn).mockResolvedValue({
+      stdout: Buffer.from(
+        JSON.stringify({
+          job: internalJob,
+          metadata: {},
+        })
+      ),
+      stderr: Buffer.from(''),
+    } as any);
+
+    const job = {
+      platform: Platform.IOS,
+      buildProfile: 'preview',
+      refreshAdHocProvisioningProfile: true,
+      appId: 'app-id',
+      initiatingUserId: 'user-id',
+      secrets: { robotAccessToken: 'token' },
+    } as unknown as BuildJob;
+
+    await runEasBuildInternalAsync({
+      job,
+      logger,
+      env: {},
+      cwd: '/tmp/project',
+    });
+
+    expect(spawn).toHaveBeenCalledWith(
+      'npx',
+      expect.arrayContaining([
+        'build:internal',
+        '--platform',
+        Platform.IOS,
+        '--profile',
+        'preview',
+        '--refresh-ad-hoc-provisioning-profile',
+      ]),
+      expect.any(Object)
+    );
+  });
+
+  it('preserves refreshAdHocProvisioningProfile from the incoming job', async () => {
+    const logger = {
+      info: jest.fn(),
+      warn: jest.fn(),
+      error: jest.fn(),
+      child: jest.fn(),
+    } as any;
+
+    const internalJob = {
+      platform: Platform.IOS,
+      type: Workflow.GENERIC,
+      triggeredBy: 'EAS_CLI',
+      projectArchive: { type: ArchiveSourceType.URL, url: 'https://example.com' },
+      projectRootDirectory: '.',
+      secrets: {
+        buildCredentials: {
+          testapp: {
+            distributionCertificate: {
+              dataBase64: 'YmluYXJ5Y29udGVudDE=',
+              password: 'distCertPassword',
+            },
+            provisioningProfileBase64: 'MnRuZXRub2N5cmFuaWI=',
+          },
+        },
+      },
+      initiatingUserId: 'user-id',
+      appId: 'app-id',
+    };
+
+    jest.mocked(spawn).mockResolvedValue({
+      stdout: Buffer.from(
+        JSON.stringify({
+          job: internalJob,
+          metadata: {},
+        })
+      ),
+      stderr: Buffer.from(''),
+    } as any);
+
+    const job = {
+      platform: Platform.IOS,
+      buildProfile: 'preview',
+      refreshAdHocProvisioningProfile: true,
+      appId: 'app-id',
+      initiatingUserId: 'user-id',
+      secrets: { robotAccessToken: 'token' },
+    } as unknown as BuildJob;
+
+    const { newJob } = await runEasBuildInternalAsync({
+      job,
+      logger,
+      env: {},
+      cwd: '/tmp/project',
+    });
+
+    expect((newJob as any).refreshAdHocProvisioningProfile).toBe(true);
+  });
 });
@@ -0,0 +1,94 @@
+import { EventEmitter } from 'events';
+
+import spawnAsync from '@expo/spawn-async';
+import { ExpoRunFormatter } from '@expo/xcpretty';
+import fg from 'fast-glob';
+
+import { createMockLogger } from '../../__tests__/utils/logger';
+import { Sentry } from '../../sentry';
+import { XcodeBuildLogger } from '../xcpretty';
+
+jest.mock('@expo/spawn-async');
+jest.mock('@expo/xcpretty');
+jest.mock('fast-glob');
+jest.mock('../../sentry', () => ({
+  Sentry: {
+    setup: jest.fn(),
+    capture: jest.fn(),
+    flush: jest.fn(),
+  },
+}));
+
+describe(XcodeBuildLogger, () => {
+  let stdout: EventEmitter;
+  let formatter: { pipe: jest.Mock; getBuildSummary: jest.Mock };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    stdout = new EventEmitter();
+    const spawnPromise = Object.assign(new Promise(() => {}), {
+      child: { stdout, kill: jest.fn() },
+    });
+    jest.mocked(spawnAsync).mockReturnValue(spawnPromise as any);
+
+    formatter = {
+      pipe: jest.fn(),
+      getBuildSummary: jest.fn().mockReturnValue('summary'),
+    };
+    jest.mocked(ExpoRunFormatter.create).mockReturnValue(formatter as any);
+
+    jest.mocked(fg).mockResolvedValue(['build.log'] as any);
+  });
+
+  async function startWatchingAsync(logger: ReturnType<typeof createMockLogger>): Promise<void> {
+    const buildLogger = new XcodeBuildLogger(logger, '/project');
+    await buildLogger.watchLogFiles('/logs');
+  }
+
+  it('logs formatted lines', async () => {
+    const logger = createMockLogger();
+    await startWatchingAsync(logger);
+
+    formatter.pipe.mockReturnValue(['line1', 'line2']);
+    stdout.emit('data', 'raw xcodebuild output');
+
+    expect(formatter.pipe).toHaveBeenCalledWith('raw xcodebuild output');
+    expect(logger.info).toHaveBeenCalledWith('line1');
+    expect(logger.info).toHaveBeenCalledWith('line2');
+    expect(Sentry.capture).not.toHaveBeenCalled();
+  });
+
+  it('falls back to raw logs when the formatter throws', async () => {
+    const logger = createMockLogger();
+    await startWatchingAsync(logger);
+
+    formatter.pipe.mockImplementation(() => {
+      throw new RangeError('Invalid array length');
+    });
+    stdout.emit('data', 'offending output');
+
+    expect(logger.info).toHaveBeenCalledWith('offending output');
+  });
+
+  it('reports the formatter error to Sentry only once', async () => {
+    const logger = createMockLogger();
+    await startWatchingAsync(logger);
+
+    const error = new RangeError('Invalid array length');
+    formatter.pipe.mockImplementation(() => {
+      throw error;
+    });
+    stdout.emit('data', 'offending output');
+    stdout.emit('data', 'more offending output');
+
+    expect(logger.info).toHaveBeenCalledWith('offending output');
+    expect(logger.info).toHaveBeenCalledWith('more offending output');
+    expect(Sentry.capture).toHaveBeenCalledTimes(1);
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      'xcpretty formatter failed to parse xcodebuild logs',
+      error,
+      { extras: { data: 'offending output' } }
+    );
+  });
+});
@@ -1,4 +1,12 @@
-import { BuildJob, Env, Metadata, sanitizeBuildJob, sanitizeMetadata } from '@expo/eas-build-job';
+import {
+  BuildJob,
+  Env,
+  Ios,
+  Metadata,
+  Platform,
+  sanitizeBuildJob,
+  sanitizeMetadata,
+} from '@expo/eas-build-job';
 import { PipeMode, bunyan } from '@expo/logger';
 import { BuildStepEnv } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
@@ -42,6 +50,11 @@ export async function runEasBuildInternalAsync<TJob extends BuildJob>({
    autoSubmitArgs.push('--auto-submit');
  }

+  const refreshAdHocProvisioningProfileArgs = [];
+  if (job.platform === Platform.IOS && job.refreshAdHocProvisioningProfile === true) {
+    refreshAdHocProvisioningProfileArgs.push('--refresh-ad-hoc-provisioning-profile');
+  }
+
  try {
    const result = await spawn(
      cmd,
@@ -53,6 +66,7 @@ export async function runEasBuildInternalAsync<TJob extends BuildJob>({
        '--profile',
        buildProfile,
        ...autoSubmitArgs,
+        ...refreshAdHocProvisioningProfileArgs,
      ],
      {
        cwd,
@@ -138,6 +152,9 @@ function validateEasBuildInternalResult<TJob extends BuildJob>({
    // We want to retain values that we have set on the job.
    appId: oldJob.appId,
    initiatingUserId: oldJob.initiatingUserId,
+    ...(oldJob.platform === Platform.IOS && oldJob.refreshAdHocProvisioningProfile === true
+      ? { refreshAdHocProvisioningProfile: true }
+      : null),
  }) as TJob;
  assert(newJob.platform === oldJob.platform, 'eas-cli returned a job for a wrong platform');
  const newMetadata = sanitizeMetadata(value.metadata);
@@ -6,11 +6,14 @@ import fg from 'fast-glob';
 import fs from 'fs-extra';
 import path from 'path';

+import { Sentry } from '../sentry';
+
 const CHECK_FILE_INTERVAL_MS = 1000;

 export class XcodeBuildLogger {
  private loggerError?: Error;
  private flushing: boolean = false;
+  private reportedFormatterError: boolean = false;
  private logReaderPromise?: SpawnPromise<SpawnResult>;
  private logsPath?: string;

@@ -60,9 +63,21 @@ export class XcodeBuildLogger {
      this.logReaderPromise = spawnAsync('tail', ['-n', '+0', '-f', logsPath], { stdio: 'pipe' });
      assert(this.logReaderPromise.child.stdout, 'stdout is not available');
      this.logReaderPromise.child.stdout.on('data', (data: string) => {
-        const lines = formatter.pipe(data.toString());
-        for (const line of lines) {
-          this.logger.info(line);
+        try {
+          const lines = formatter.pipe(data.toString());
+          for (const line of lines) {
+            this.logger.info(line);
+          }
+        } catch (err: any) {
+          // The formatter can throw on unexpected xcodebuild output. Fall back to
+          // raw logs instead of crashing the process with an uncaught exception.
+          if (!this.reportedFormatterError) {
+            this.reportedFormatterError = true;
+            Sentry.capture('xcpretty formatter failed to parse xcodebuild logs', err, {
+              extras: { data: data.toString().slice(-2000) },
+            });
+          }
+          this.logger.info(data.toString());
        }
      });
      await this.logReaderPromise;
@@ -2,7 +2,6 @@ import { ExpoConfig } from '@expo/config';
 import {
  BuildPhase,
  BuildPhaseResult,
-  BuildPhaseStats,
  Env,
  EnvironmentSecretType,
  GenericArtifactType,
@@ -65,7 +64,6 @@ export interface BuildContextOptions {
    err?: Error,
    options?: { tags?: Record<string, string>; extras?: Record<string, string> }
  ) => void;
-  reportBuildPhaseStats?: (stats: BuildPhaseStats) => void;
  skipNativeBuild?: boolean;
  metadata?: Metadata;
  expoApiV2BaseUrl?: string;
@@ -98,7 +96,6 @@ export class BuildContext<TJob extends Job = Job> {
  private buildPhaseSkipped = false;
  private buildPhaseHasWarnings = false;
  private _appConfig?: Promise<ExpoConfig>;
-  private readonly reportBuildPhaseStats?: (stats: BuildPhaseStats) => void;
  public readonly graphqlClient: Client;

  constructor(job: TJob, options: BuildContextOptions) {
@@ -114,7 +111,6 @@ export class BuildContext<TJob extends Job = Job> {
    this._metadata = options.metadata;
    this.skipNativeBuild = options.skipNativeBuild;
    this.expoApiV2BaseUrl = options.expoApiV2BaseUrl;
-    this.reportBuildPhaseStats = options.reportBuildPhaseStats;

    const environmentSecrets = this.getEnvironmentSecrets(job);
    this._env = {
@@ -355,7 +351,6 @@ export class BuildContext<TJob extends Job = Job> {
    }
    await this.collectAndUpdateEnvVariablesAsync();

-    this.reportBuildPhaseStats?.({ buildPhase: this.buildPhase, result, durationMs });
    if (this.job.platform) {
      Datadog.distribution('eas.build.phase_duration', durationMs, {
        build_phase: this.buildPhase.toLowerCase(),
@@ -1,14 +1,25 @@
 import { Sentry } from './sentry';
 import { turtleFetch } from './utils/turtleFetch';

+type MetricsTarget =
+  | { kind: 'build'; turtleBuildId: string }
+  | { kind: 'jobRun'; turtleJobRunId: string };
+
 type DatadogSetupOptions = {
  expoApiV2BaseUrl: string;
-  turtleBuildId: string;
  robotAccessToken: string;
+  target: MetricsTarget;
 };

 let setupOptions: DatadogSetupOptions | null = null;
-let pendingMetricUploads: Promise<unknown>[] = [];
+let pendingUploads: Promise<unknown>[] = [];
+
+function withTargetTag(
+  tags: Record<string, string>,
+  target: MetricsTarget
+): Record<string, string> {
+  return { ...tags, target: target.kind === 'build' ? 'build' : 'job_run' };
+}

 export const Datadog = {
  setup(opts: DatadogSetupOptions | null): void {
@@ -19,36 +30,68 @@ export const Datadog = {
    if (!setupOptions) {
      return;
    }
-    const { expoApiV2BaseUrl, turtleBuildId, robotAccessToken } = setupOptions;
+    const { expoApiV2BaseUrl, robotAccessToken, target } = setupOptions;
    const metrics = [
      {
        name,
        type: 'distribution' as const,
        value,
-        tags,
+        tags: withTargetTag(tags, target),
      },
    ];

-    const uploadPromise = turtleFetch(
-      new URL(`turtle-builds/${turtleBuildId}/metrics`, expoApiV2BaseUrl).toString(),
-      'POST',
-      {
-        json: { metrics },
-        headers: {
-          Authorization: `Bearer ${robotAccessToken}`,
-        },
-        retries: 2,
-      }
-    ).catch(err => {
-      Sentry.capture('Failed to report turtle build metric', err, {
+    const metricsPath =
+      target.kind === 'build'
+        ? `turtle-builds/${target.turtleBuildId}/metrics`
+        : `turtle-job-runs/${target.turtleJobRunId}/metrics`;
+
+    const uploadPromise = turtleFetch(new URL(metricsPath, expoApiV2BaseUrl).toString(), 'POST', {
+      json: { metrics },
+      headers: {
+        Authorization: `Bearer ${robotAccessToken}`,
+      },
+      retries: 2,
+    }).catch(err => {
+      Sentry.capture(`Failed to report turtle ${target.kind} metric`, err, {
        extras: { metrics },
      });
    });

-    pendingMetricUploads.push(uploadPromise);
+    pendingUploads.push(uploadPromise);
+  },
+
+  log(message: string, tags: Record<string, string> = {}): void {
+    if (!setupOptions) {
+      return;
+    }
+    const { expoApiV2BaseUrl, robotAccessToken, target } = setupOptions;
+    const tagsWithTarget = withTargetTag(tags, target);
+    const log =
+      target.kind === 'build'
+        ? { buildId: target.turtleBuildId, message, tags: tagsWithTarget }
+        : { jobRunId: target.turtleJobRunId, message, tags: tagsWithTarget };
+    const logsPath = target.kind === 'build' ? 'turtle-builds/logs' : 'turtle-job-runs/logs';
+
+    const uploadPromise = turtleFetch(new URL(logsPath, expoApiV2BaseUrl).toString(), 'POST', {
+      json: log,
+      headers: {
+        Authorization: `Bearer ${robotAccessToken}`,
+      },
+      shouldThrowOnNotOk: false,
+    }).catch(err => {
+      Sentry.capture(`Failed to report turtle ${target.kind} log`, err, {
+        extras: { log },
+      });
+    });
+
+    pendingUploads.push(uploadPromise);
  },

  async flushAsync(): Promise<void> {
-    await Promise.allSettled(pendingMetricUploads);
+    // Rotate so each flush only awaits its own batch; uploads enqueued during the
+    // await land in the fresh array for a later flush.
+    const uploads = pendingUploads;
+    pendingUploads = [];
+    await Promise.allSettled(uploads);
  },
 };
@@ -27,3 +27,4 @@ export * from './generic';

 export { Datadog } from './datadog';
 export { Sentry } from './sentry';
+export * from './runtimeSettings';
@@ -9,6 +9,7 @@ exports[`fastfile createFastfileForResigningBuild should create Fastfile with al
      "com.example.app" => "/path/to/profiles/main.mobileprovision",
      "com.example.app.widget" => "/path/to/profiles/widget.mobileprovision",
    },
+    use_app_entitlements: true,
    keychain_path: "/Users/expo/Library/Keychains/login.keychain"
  )
 end
@@ -22,6 +23,7 @@ exports[`fastfile createFastfileForResigningBuild should handle empty provisioni
    signing_identity: "iPhone Distribution",
    provisioning_profile: {
    },
+    use_app_entitlements: true,
    keychain_path: "/tmp/keychain"
  )
 end
@@ -39,6 +41,7 @@ exports[`fastfile createFastfileForResigningBuild should handle multiple provisi
      "com.example.app.extension" => "/profiles/extension.mobileprovision",
      "com.example.app.intents" => "/profiles/intents.mobileprovision",
    },
+    use_app_entitlements: true,
    keychain_path: "/tmp/keychain"
  )
 end
@@ -53,6 +56,7 @@ exports[`fastfile createFastfileForResigningBuild should handle paths with speci
    provisioning_profile: {
      "com.example.app" => "/path/with spaces/profile (1).mobileprovision",
    },
+    use_app_entitlements: true,
    keychain_path: "/Users/expo/Library/Keychains/login keychain.keychain"
  )
 end
@@ -67,6 +71,7 @@ exports[`fastfile createFastfileForResigningBuild should handle single provision
    provisioning_profile: {
      "com.example.app" => "/tmp/profile.mobileprovision",
    },
+    use_app_entitlements: true,
    keychain_path: "/tmp/keychain"
  )
 end
@@ -81,6 +86,7 @@ exports[`fastfile createFastfileForResigningBuild should produce valid Ruby synt
    provisioning_profile: {
      "com.example.app" => "/path/to/profile.mobileprovision",
    },
+    use_app_entitlements: true,
    keychain_path: "/tmp/keychain"
  )
 end
@@ -26,10 +26,12 @@ function makeIosBuildContext({
  expoVersion,
  cocoapodsCacheUrl,
  usePrecompiledModules = true,
+  expoUsePrecompiledModules,
 }: {
  expoVersion?: string;
  cocoapodsCacheUrl?: string;
  usePrecompiledModules?: boolean;
+  expoUsePrecompiledModules?: string;
 }): BuildContext<Ios.Job> {
  vol.fromJSON({
    [path.join(IOS_DIR, '.keep')]: '',
@@ -57,6 +59,9 @@ function makeIosBuildContext({
    logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
    env: {
      __API_SERVER_URL: 'http://api.expo.test',
+      ...(expoUsePrecompiledModules
+        ? { EXPO_USE_PRECOMPILED_MODULES: expoUsePrecompiledModules }
+        : {}),
      ...(cocoapodsCacheUrl ? { EAS_BUILD_COCOAPODS_CACHE_URL: cocoapodsCacheUrl } : {}),
    },
    uploadArtifact: jest.fn(),
@@ -176,4 +181,23 @@ describe(installPods, () => {
    ).toBeUndefined();
    expect(ctx.logger.info).not.toHaveBeenCalled();
  });
+
+  it('does not override EXPO_USE_PRECOMPILED_MODULES=0 even when builder flag is enabled', async () => {
+    const ctx = makeIosBuildContext({
+      expoVersion: '999.0.0',
+      usePrecompiledModules: true,
+      expoUsePrecompiledModules: '0',
+    });
+
+    await installPods(ctx, {});
+
+    expect((spawn as jest.Mock).mock.calls[0][2].env.EXPO_USE_PRECOMPILED_MODULES).toBe('0');
+    expect(
+      (spawn as jest.Mock).mock.calls[0][2].env.EXPO_PRECOMPILED_MODULES_BASE_URL
+    ).toBeUndefined();
+    expect(ctx.logger.info).toHaveBeenCalledWith(
+      'EXPO_USE_PRECOMPILED_MODULES=0 is set; not enabling precompiled modules use.'
+    );
+    expect(getInstalledExpoPackageVersionAsync).not.toHaveBeenCalled();
+  });
 });
@@ -10,8 +10,8 @@ import type { Credentials } from './credentials/manager';
 import { createFastfileForResigningBuild } from './fastfile';
 import { createGymfileForArchiveBuild, createGymfileForSimulatorBuild } from './gymfile';
 import { isTVOS } from './tvos';
-import { XcodeBuildLogger } from './xcpretty';
 import { COMMON_FASTLANE_ENV } from '../common/fastlane';
+import { XcodeBuildLogger } from '../common/xcpretty';
 import { BuildContext, SkipNativeBuildError } from '../context';

 export async function runFastlaneGym<TJob extends Ios.Job>(
@@ -46,7 +46,12 @@ export async function installPods<TJob extends Ios.Job>(
 async function resolvePrecompiledModulesPodInstallEnvAsync<TJob extends Ios.Job>(
  ctx: BuildContext<TJob>
 ): Promise<Env> {
-  if (ctx.job.builderEnvironment?.env?.EAS_USE_PRECOMPILED_MODULES !== '1') {
+  if (ctx.env.EXPO_USE_PRECOMPILED_MODULES === '0') {
+    ctx.logger.info('EXPO_USE_PRECOMPILED_MODULES=0 is set; not enabling precompiled modules use.');
+    return {};
+  }
+
+  if (ctx.env.EAS_USE_PRECOMPILED_MODULES !== '1') {
    return {};
  }

@@ -0,0 +1,128 @@
+import { type bunyan } from '@expo/logger';
+import fetch from 'node-fetch';
+import { z } from 'zod';
+
+import { Sentry } from './sentry';
+
+const ENVIRONMENT_TO_RUNTIME_SETTINGS_URL: Record<string, string | undefined> = {
+  staging: 'https://storage.googleapis.com/eas-workflows-staging/runtime-settings.json',
+  production: 'https://storage.googleapis.com/eas-workflows-production/runtime-settings.json',
+};
+
+const RuntimeSettingsSchema = z
+  .object({
+    caches: z.record(
+      z.string(),
+      z
+        .object({
+          npm: z.boolean(),
+          nodejs: z.boolean(),
+          maven: z.boolean(),
+          cocoapods: z.boolean(),
+        })
+        .partial()
+    ),
+    iosPrecompiledModules: z.boolean(),
+  })
+  .partial();
+
+type CacheUrlFallbacks = {
+  npm?: string | null;
+  nodejs?: string | null;
+  maven?: string | null;
+  cocoapods?: string | null;
+};
+
+let runtimeSettings: z.infer<typeof RuntimeSettingsSchema> = {};
+let cacheUrlFallbacks: CacheUrlFallbacks = {};
+
+export namespace RuntimeSettings {
+  export async function loadAsync({
+    environment,
+    logger,
+    cacheUrlFallbacks: nextCacheUrlFallbacks = {},
+  }: {
+    environment: string;
+    logger: bunyan;
+    cacheUrlFallbacks?: CacheUrlFallbacks;
+  }): Promise<void> {
+    cacheUrlFallbacks = nextCacheUrlFallbacks;
+    const url = ENVIRONMENT_TO_RUNTIME_SETTINGS_URL[environment];
+    if (!url) {
+      return;
+    }
+
+    try {
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(1000),
+      });
+
+      if (!response.ok) {
+        logger.warn(
+          { url, status: response.status },
+          'Failed to fetch worker runtime settings, using defaults'
+        );
+        Sentry.capture('Failed to fetch worker runtime settings', {
+          extras: { url, status: response.status },
+          level: 'warning',
+        });
+        return;
+      }
+
+      runtimeSettings = RuntimeSettingsSchema.parse(await response.json());
+      if (runtimeSettings.caches && !runtimeSettings.caches[process.platform]) {
+        Sentry.capture(
+          new Error(
+            `Runtime settings are missing cache settings for platform "${process.platform}"`
+          ),
+          {
+            extras: {
+              configuredPlatforms: Object.keys(runtimeSettings.caches),
+              platform: process.platform,
+            },
+            level: 'error',
+          }
+        );
+      }
+      logger.info({ url, settings: runtimeSettings }, 'Loaded worker runtime settings');
+    } catch (err) {
+      logger.warn({ err, url }, 'Failed to load worker runtime settings, using defaults');
+      Sentry.capture(
+        'Failed to load worker runtime settings',
+        err instanceof Error ? err : new Error(String(err)),
+        {
+          extras: { url },
+          level: 'warning',
+        }
+      );
+    }
+  }
+
+  export function isUsingIosPrecompiledModulesEnabled(): boolean {
+    return runtimeSettings.iosPrecompiledModules ?? false;
+  }
+
+  export function getNpmCacheUrl(): string | null {
+    return runtimeSettings.caches?.[process.platform]?.npm
+      ? process.env.EAS_NPM_CACHE_URL || cacheUrlFallbacks.npm || null
+      : null;
+  }
+
+  export function getNodeJsCacheUrl(): string | null {
+    return runtimeSettings.caches?.[process.platform]?.nodejs
+      ? process.env.EAS_NODEJS_CACHE_URL || cacheUrlFallbacks.nodejs || null
+      : null;
+  }
+
+  export function getMavenCacheUrl(): string | null {
+    return runtimeSettings.caches?.[process.platform]?.maven
+      ? process.env.EAS_MAVEN_CACHE_URL || cacheUrlFallbacks.maven || null
+      : null;
+  }
+
+  export function getCocoapodsCacheUrl(): string | null {
+    return runtimeSettings.caches?.[process.platform]?.cocoapods
+      ? process.env.EAS_COCOAPODS_CACHE_URL || cacheUrlFallbacks.cocoapods || null
+      : null;
+  }
+}
@@ -0,0 +1,90 @@
+import spawn from '@expo/turtle-spawn';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { Datadog } from '../../../datadog';
+import { createInstallMaestroBuildFunction } from '../installMaestro';
+
+jest.mock('@expo/turtle-spawn', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+jest.mock('../../../datadog', () => ({
+  Datadog: {
+    distribution: jest.fn(),
+  },
+}));
+
+const mockedSpawn = jest.mocked(spawn);
+
+describe('createInstallMaestroBuildFunction', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // `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) => ({
+      stdout: command === 'maestro' ? '1.41.0\n' : '',
+    })) as any);
+  });
+
+  it('reports the detected Maestro version to Datadog on EAS Build VMs', async () => {
+    const installMaestro = createInstallMaestroBuildFunction();
+    const globalCtx = createGlobalContextMock();
+    globalCtx.updateEnv({ EAS_BUILD_RUNNER: 'eas-build' });
+    const step = installMaestro.createBuildStepFromFunctionCall(globalCtx, { callInputs: {} });
+
+    await step.executeAsync();
+
+    expect(step.getOutputValueByName('maestro_version')).toBe('1.41.0');
+    expect(Datadog.distribution).toHaveBeenCalledWith('eas.maestro.install', 1, {
+      maestro_version: '1.41.0',
+    });
+  });
+
+  it('does not report to Datadog outside EAS Build VMs', async () => {
+    const installMaestro = createInstallMaestroBuildFunction();
+    const step = installMaestro.createBuildStepFromFunctionCall(createGlobalContextMock(), {
+      callInputs: {},
+    });
+
+    await step.executeAsync();
+
+    expect(Datadog.distribution).not.toHaveBeenCalled();
+  });
+
+  it('extracts the version when `maestro --version` prints an analytics notice', async () => {
+    mockedSpawn.mockImplementation((async (command: string) => ({
+      stdout:
+        command === 'maestro'
+          ? 'Anonymous analytics enabled. To opt out, set MAESTRO_CLI_NO_ANALYTICS environment variable to any value before running Maestro.\n2.0.10\n'
+          : '',
+    })) as any);
+
+    const installMaestro = createInstallMaestroBuildFunction();
+    const globalCtx = createGlobalContextMock();
+    globalCtx.updateEnv({ EAS_BUILD_RUNNER: 'eas-build' });
+    const step = installMaestro.createBuildStepFromFunctionCall(globalCtx, { callInputs: {} });
+
+    await step.executeAsync();
+
+    expect(step.getOutputValueByName('maestro_version')).toBe('2.0.10');
+    expect(Datadog.distribution).toHaveBeenCalledWith('eas.maestro.install', 1, {
+      maestro_version: '2.0.10',
+    });
+  });
+
+  it('uses the trailing version when the notice itself contains an earlier version-like string', async () => {
+    mockedSpawn.mockImplementation((async (command: string) => ({
+      stdout: command === 'maestro' ? 'Analytics schema v2.0.0 enabled.\n2.0.10\n' : '',
+    })) as any);
+
+    const installMaestro = createInstallMaestroBuildFunction();
+    const globalCtx = createGlobalContextMock();
+    globalCtx.updateEnv({ EAS_BUILD_RUNNER: 'eas-build' });
+    const step = installMaestro.createBuildStepFromFunctionCall(globalCtx, { callInputs: {} });
+
+    await step.executeAsync();
+
+    expect(step.getOutputValueByName('maestro_version')).toBe('2.0.10');
+  });
+});
@@ -0,0 +1,76 @@
+import spawn from '@expo/turtle-spawn';
+
+import { createGlobalContextMock } from '../../../__tests__/utils/context';
+import { createMockLogger } from '../../../__tests__/utils/logger';
+import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import { createStartIosSimulatorBuildFunction } from '../startIosSimulator';
+
+jest.mock('@expo/turtle-spawn', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+jest.mock('../../../utils/IosSimulatorUtils', () => ({
+  IosSimulatorUtils: {
+    getAvailableDevicesAsync: jest.fn(),
+    getDeviceAsync: jest.fn(),
+    cloneAsync: jest.fn(),
+    startAsync: jest.fn(),
+    waitForReadyAsync: jest.fn(),
+    disableApsdAsync: jest.fn(),
+  },
+}));
+
+const mockedSpawn = jest.mocked(spawn);
+const mockedUtils = jest.mocked(IosSimulatorUtils);
+
+function createStep(callInputs?: Record<string, unknown>) {
+  const logger = createMockLogger();
+  const fn = createStartIosSimulatorBuildFunction();
+  const globalCtx = createGlobalContextMock({ logger });
+  const step = fn.createBuildStepFromFunctionCall(globalCtx, { callInputs });
+  return Object.assign(step, { logger });
+}
+
+describe(createStartIosSimulatorBuildFunction, () => {
+  beforeEach(() => {
+    mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);
+    mockedUtils.getAvailableDevicesAsync.mockResolvedValue([]);
+    mockedUtils.getDeviceAsync.mockResolvedValue(null);
+    mockedUtils.cloneAsync.mockResolvedValue(undefined);
+    mockedUtils.startAsync.mockResolvedValue({ udid: 'test-udid' as any });
+    mockedUtils.waitForReadyAsync.mockResolvedValue(undefined);
+    mockedUtils.disableApsdAsync.mockResolvedValue(undefined);
+  });
+
+  it('disables apsd on the main device and every clone', async () => {
+    mockedUtils.startAsync
+      .mockResolvedValueOnce({ udid: 'base' as any })
+      .mockResolvedValueOnce({ udid: 'clone-1' as any })
+      .mockResolvedValueOnce({ udid: 'clone-2' as any });
+
+    await createStep({ device_identifier: 'iPhone 15', count: 2 }).executeAsync();
+
+    expect(mockedUtils.disableApsdAsync).toHaveBeenCalledWith({
+      udid: 'base',
+      env: expect.any(Object),
+    });
+    expect(mockedUtils.disableApsdAsync).toHaveBeenCalledWith({
+      udid: 'clone-1',
+      env: expect.any(Object),
+    });
+    expect(mockedUtils.disableApsdAsync).toHaveBeenCalledWith({
+      udid: 'clone-2',
+      env: expect.any(Object),
+    });
+  });
+
+  it('continues when disabling apsd fails', async () => {
+    mockedUtils.disableApsdAsync.mockRejectedValue(new Error('apsd disable failed'));
+
+    await createStep({ device_identifier: 'iPhone 15', count: 2 }).executeAsync();
+
+    // Startup is not aborted: readiness is still awaited for each device.
+    expect(mockedUtils.waitForReadyAsync).toHaveBeenCalled();
+  });
+});
@@ -15,6 +15,8 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';

+import { Datadog } from '../../datadog';
+
 export function createInstallMaestroBuildFunction(): BuildFunction {
  return new BuildFunction({
    namespace: 'eas',
@@ -123,13 +125,24 @@ export function createInstallMaestroBuildFunction(): BuildFunction {

      logger.info(`Maestro ${maestroVersionResult.value} is ready.`);
      outputs.maestro_version.set(maestroVersionResult.value);
+
+      Datadog.distribution('eas.maestro.install', 1, {
+        maestro_version: maestroVersionResult.value,
+      });
    },
  });
 }

 async function getMaestroVersion({ env }: { env: BuildStepEnv }): Promise<string> {
-  const maestroVersion = await spawn('maestro', ['--version'], { stdio: 'pipe', env });
-  return maestroVersion.stdout.trim();
+  const { stdout } = await spawn('maestro', ['--version'], { stdio: 'pipe', env });
+  // `maestro --version` can print an analytics notice to stdout before the version,
+  // e.g. "Anonymous analytics enabled. To opt out, set MAESTRO_CLI_NO_ANALYTICS...\n2.0.10".
+  // Take the last version-looking token: the real version is printed after the notice, so
+  // this stays correct even if the notice itself contains a version-like string. Keeps the
+  // step output and the eas.maestro.install metric tag clean. Best-effort only: fall back to
+  // the raw output if none is found, so we never fail the build over a version string.
+  const versions = stdout.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g);
+  return versions?.at(-1) ?? stdout.trim();
 }

 async function installMaestro({
@@ -57,6 +57,16 @@ export function createRepackBuildFunction(): BuildFunction {
        allowedValueTypeName: BuildStepInputValueTypeName.BOOLEAN,
        required: false,
      }),
+      BuildStepInput.createProvider({
+        id: 'ios_signing_use_source_app_entitlements',
+        allowedValueTypeName: BuildStepInputValueTypeName.BOOLEAN,
+        required: false,
+      }),
+      BuildStepInput.createProvider({
+        id: 'ios_signing_app_entitlements_path',
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+        required: false,
+      }),
      BuildStepInput.createProvider({
        id: 'repack_version',
        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
@@ -138,6 +148,12 @@ export function createRepackBuildFunction(): BuildFunction {
            iosSigningOptions: await resolveIosSigningOptionsAsync({
              job: stepsCtx.global.staticContext.job,
              logger: stepsCtx.logger,
+              useAppEntitlements: inputs.ios_signing_use_source_app_entitlements.value as
+                | boolean
+                | undefined,
+              entitlementsPath: inputs.ios_signing_app_entitlements_path.value as
+                | string
+                | undefined,
            }),
            logger: stepsCtx.logger,
            spawnAsync: repackSpawnAsync,
@@ -275,9 +291,13 @@ export async function resolveAndroidSigningOptionsAsync({
 export async function resolveIosSigningOptionsAsync({
  job,
  logger,
+  useAppEntitlements,
+  entitlementsPath,
 }: {
  job: Job;
  logger: bunyan;
+  useAppEntitlements?: boolean;
+  entitlementsPath?: string;
 }): Promise<IosSigningOptions | undefined> {
  const iosJob = job as Ios.Job;
  const buildCredentials = iosJob.secrets?.buildCredentials;
@@ -295,5 +315,7 @@ export async function resolveIosSigningOptionsAsync({
    provisioningProfile,
    keychainPath: credentials.keychainPath,
    signingIdentity: credentials.applicationTargetProvisioningProfile.data.certificateCommonName,
+    useAppEntitlements,
+    entitlementsPath,
  };
 }
@@ -19,6 +19,7 @@ import {
  generateDefaultBuildCacheKeyAsync,
  getCcachePath,
 } from '../../utils/cacheKey';
+import { Datadog } from '../../datadog';
 import { GRADLE_CACHE_KEY_PREFIX, generateGradleCacheKeyAsync } from '../../utils/gradleCacheKey';
 import { TurtleFetchError, turtleFetch } from '../../utils/turtleFetch';

@@ -282,22 +283,10 @@ export async function restoreGradleCacheAsync({
      `Gradle cache restored to ${gradleCachesPath} (${hitType === 'direct_hit' ? 'direct hit' : 'prefix match'})`
    );

-    try {
-      await turtleFetch(new URL('v2/turtle-builds/logs', expoApiServerURL).toString(), 'POST', {
-        json: {
-          buildId: jobId,
-          message: `Gradle cache restored (${hitType})`,
-          tags: {
-            event: 'gradle_cache_restored',
-            cache_hit_type: hitType,
-          },
-        },
-        headers: {
-          Authorization: `Bearer ${robotAccessToken}`,
-        },
-        shouldThrowOnNotOk: false,
-      });
-    } catch {}
+    Datadog.log(`Gradle cache restored (${hitType})`, {
+      event: 'gradle_cache_restored',
+      cache_hit_type: hitType,
+    });
  } catch (err: unknown) {
    if (err instanceof TurtleFetchError && err.response?.status === 404) {
      logger.info('No Gradle cache found for this key');
@@ -141,6 +141,10 @@ export async function uploadCacheAsync({
      return;
    }
    const textResult = await asyncResult(response.text());
+    const errorMessage = extractValidationErrorMessage(textResult.value);
+    if (errorMessage) {
+      throw new Error(errorMessage);
+    }
    throw new Error(`Unexpected response from server (${response.status}): ${textResult.value}`);
  }

@@ -231,6 +235,19 @@ export async function uploadPublicCacheAsync({
  logger.info(`Uploaded cache archive to ${archivePath} (${formatBytes(size)}).`);
 }

+function extractValidationErrorMessage(body: string | undefined): string | undefined {
+  if (!body) {
+    return undefined;
+  }
+  try {
+    const { errors } = JSON.parse(body);
+    if (errors?.[0]?.code === 'VALIDATION_ERROR') {
+      return errors[0].message;
+    }
+  } catch {}
+  return undefined;
+}
+
 export async function compressCacheAsync({
  paths,
  workingDirectory,
@@ -1,27 +1,32 @@
 import { SystemError } from '@expo/eas-build-job';
-import { bunyan } from '@expo/logger';
+import { type bunyan } from '@expo/logger';
 import {
  BuildFunction,
  BuildRuntimePlatform,
-  BuildStepEnv,
+  type BuildStepEnv,
  BuildStepInput,
  BuildStepInputValueTypeName,
 } 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 { CustomBuildContext } from '../../customBuildContext';
+import { type CustomBuildContext } from '../../customBuildContext';
+import { Sentry } from '../../sentry';
 import {
-  ensureCloudflaredInstalledAsync,
+  type DetachedProcessHandle,
  getDeviceRunSessionIdOrThrow,
+  getNgrokAuthtokenOrThrow,
+  getNgrokTunnelDomainOrThrow,
  spawnDetached,
+  startNgrokTunnelAsync,
  startServeSimWithTunnelAsync,
  uploadRemoteSessionConfigAsync,
  waitForFileAsync,
-  waitForMatchInOutputAsync,
 } from '../utils/remoteDeviceRunSession';

+const AGENT_DEVICE_PACKAGE_NAME = 'agent-device';
 const AGENT_DEVICE_REPO_URL = 'https://github.com/callstackincubator/agent-device.git';
 const SRC_DIR = '/tmp/agent-device-src';
 const DAEMON_JSON_PATH = path.join(os.homedir(), '.agent-device', 'daemon.json');
@@ -44,10 +49,13 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
      }),
    ],
    fn: async ({ logger, global }, { inputs, env }) => {
-      // Fail fast before any expensive setup if the orchestrator-injected
-      // DEVICE_RUN_SESSION_ID env var is missing — without it we cannot
-      // report the remote config back to the API server.
+      // Fail fast before any expensive setup if the injected env
+      // vars are missing: DEVICE_RUN_SESSION_ID (to report the remote config
+      // back to the API server), EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN (base domain
+      // for our ngrok tunnels), and NGROK_AUTHTOKEN (to authenticate them).
      const deviceRunSessionId = getDeviceRunSessionIdOrThrow(env);
+      const ngrokTunnelDomain = getNgrokTunnelDomainOrThrow(env);
+      const ngrokAuthtoken = getNgrokAuthtokenOrThrow(env);

      const packageVersion = inputs.package_version.value as string | undefined;
      const { runtimePlatform } = global;
@@ -60,57 +68,21 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
        await spawn('sudo', ['xcode-select', '-s', XCODE_DEVELOPER_DIR], { env, logger });
      }

-      logger.info('Ensuring cloudflared is installed.');
-      const cloudflaredCommand = await ensureCloudflaredInstalledAsync({
-        runtimePlatform,
-        env,
-        logger,
-      });
-
-      logger.info(
-        packageVersion
-          ? `Cloning agent-device @ v${packageVersion} into ${SRC_DIR}.`
-          : `Cloning agent-device (latest) into ${SRC_DIR}.`
-      );
-      await cloneAgentDeviceAsync({ packageVersion, env, logger });
-
-      logger.info('Installing agent-device dependencies.');
-      await spawn('bun', ['install', '--production'], {
-        cwd: SRC_DIR,
-        env,
-        logger,
-      });
-
      logger.info('Launching agent-device daemon.');
-      spawnDetached({
-        command: 'bun',
-        args: ['run', 'src/daemon.ts'],
-        cwd: SRC_DIR,
-        env: { ...env, AGENT_DEVICE_DAEMON_SERVER_MODE: 'http' },
-      });
+      const daemonProcess = await startAgentDeviceDaemonAsync({ packageVersion, env, logger });

      logger.info(`Waiting for daemon credentials at ${DAEMON_JSON_PATH}.`);
-      const { port: daemonPort, token: daemonToken } = await waitForFileAsync({
-        filePath: DAEMON_JSON_PATH,
-        timeoutMs: STARTUP_TIMEOUT_MS,
-        description: 'agent-device daemon credentials',
-        parse: parseDaemonInfo,
+      const { port: daemonPort, token: daemonToken } = await waitForDaemonInfoAsync({
+        daemonProcess,
      });
      logger.info(`Daemon is listening on port ${daemonPort}; loaded auth token.`);

-      logger.info(`Starting cloudflared tunnel to http://localhost:${daemonPort}.`);
-      const cloudflared = spawnDetached({
-        command: cloudflaredCommand,
-        args: ['tunnel', '--url', `http://localhost:${daemonPort}`],
-        env,
-      });
-
-      logger.info('Waiting for a public tunnel URL.');
-      const agentDeviceRemoteSessionUrl = await waitForMatchInOutputAsync({
-        process: cloudflared,
-        pattern: /https:\/\/[a-z0-9-]+\.trycloudflare\.com/,
-        timeoutMs: STARTUP_TIMEOUT_MS,
-        description: 'cloudflared tunnel',
+      const agentDeviceRemoteSessionUrl = await startNgrokTunnelAsync({
+        port: daemonPort,
+        subdomainPrefix: 'agent-device',
+        baseDomain: ngrokTunnelDomain,
+        authtoken: ngrokAuthtoken,
+        logger,
      });
      logger.info(`Tunnel is ready at ${agentDeviceRemoteSessionUrl}.`);

@@ -119,6 +91,7 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
      let webPreviewUrl: string | undefined;
      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
        const { previewUrl } = await startServeSimWithTunnelAsync({
+          baseDomain: ngrokTunnelDomain,
          env,
          logger,
          timeoutMs: STARTUP_TIMEOUT_MS,
@@ -146,6 +119,93 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
  });
 }

+async function startAgentDeviceDaemonAsync({
+  packageVersion,
+  env,
+  logger,
+}: {
+  packageVersion: string | undefined;
+  env: BuildStepEnv;
+  logger: bunyan;
+}): Promise<DetachedProcessHandle> {
+  const packageSpec = createAgentDevicePackageSpec(packageVersion);
+  try {
+    logger.info(`Installing ${packageSpec} globally with Bun.`);
+    await spawn('bun', ['add', '--global', packageSpec], {
+      env,
+      logger,
+    });
+
+    const daemonPath = getGlobalAgentDeviceDaemonPath(env);
+    if (!fs.existsSync(daemonPath)) {
+      throw new SystemError(`Expected agent-device daemon entry at ${daemonPath}.`);
+    }
+
+    logger.info(`Launching daemon from ${daemonPath}.`);
+    return spawnDetached({
+      command: 'node',
+      args: [daemonPath],
+      env: { ...env, AGENT_DEVICE_DAEMON_SERVER_MODE: 'http' },
+    });
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    const bunVersion = await getBunVersionForDiagnosticsAsync(env);
+    Sentry.capture(
+      'Failed to start agent-device daemon from global Bun package; falling back to git clone',
+      error,
+      {
+        level: 'warning',
+        tags: {
+          phase: 'agent-device-daemon-start',
+          fallback: 'git-clone',
+        },
+        extras: {
+          packageSpec,
+          packageVersion: packageVersion ?? 'latest',
+          bunVersion,
+          bunInstallConfigured: Boolean(env.BUN_INSTALL?.trim()),
+        },
+      }
+    );
+    logger.warn(
+      `Failed to start daemon from global ${packageSpec}; falling back to git clone: ${error.message}`
+    );
+    return await startAgentDeviceDaemonFromGitAsync({ packageVersion, env, logger });
+  }
+}
+
+async function startAgentDeviceDaemonFromGitAsync({
+  packageVersion,
+  env,
+  logger,
+}: {
+  packageVersion: string | undefined;
+  env: BuildStepEnv;
+  logger: bunyan;
+}): Promise<DetachedProcessHandle> {
+  logger.info(
+    packageVersion
+      ? `Cloning agent-device @ v${packageVersion} into ${SRC_DIR}.`
+      : `Cloning agent-device (latest) into ${SRC_DIR}.`
+  );
+  await cloneAgentDeviceAsync({ packageVersion, env, logger });
+
+  logger.info('Installing agent-device dependencies.');
+  await spawn('bun', ['install', '--production'], {
+    cwd: SRC_DIR,
+    env,
+    logger,
+  });
+
+  logger.info('Launching daemon from cloned agent-device source.');
+  return spawnDetached({
+    command: 'bun',
+    args: ['run', 'src/daemon.ts'],
+    cwd: SRC_DIR,
+    env: { ...env, AGENT_DEVICE_DAEMON_SERVER_MODE: 'http' },
+  });
+}
+
 async function cloneAgentDeviceAsync({
  packageVersion,
  env,
@@ -162,6 +222,63 @@ async function cloneAgentDeviceAsync({
  });
 }

+async function waitForDaemonInfoAsync({
+  daemonProcess,
+}: {
+  daemonProcess: DetachedProcessHandle;
+}): Promise<{ port: number; token: string }> {
+  try {
+    return await waitForFileAsync({
+      filePath: DAEMON_JSON_PATH,
+      timeoutMs: STARTUP_TIMEOUT_MS,
+      description: 'agent-device daemon credentials',
+      parse: parseDaemonInfo,
+    });
+  } catch (err) {
+    const output = daemonProcess.getOutput();
+    throw new SystemError(
+      `${
+        err instanceof Error
+          ? err.message
+          : `Timed out waiting for agent-device daemon credentials.`
+      }${output ? `\nagent-device daemon output:\n${output}` : ''}`
+    );
+  }
+}
+
+async function getBunVersionForDiagnosticsAsync(env: BuildStepEnv): Promise<string> {
+  try {
+    const result = await spawn('bun', ['--version'], { stdio: 'pipe', env, cwd: os.tmpdir() });
+    return result.stdout.trim() || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function createAgentDevicePackageSpec(packageVersion: string | undefined): string {
+  const versionSpec = packageVersion ? packageVersion.replace(/^v(?=\d)/, '') : 'latest';
+  return `${AGENT_DEVICE_PACKAGE_NAME}@${versionSpec}`;
+}
+
+function getGlobalAgentDeviceDaemonPath(env: BuildStepEnv): string {
+  return path.join(
+    getBunInstallDirectory(env),
+    'install',
+    'global',
+    'node_modules',
+    AGENT_DEVICE_PACKAGE_NAME,
+    'dist',
+    'src',
+    'internal',
+    'daemon.js'
+  );
+}
+
+function getBunInstallDirectory(env: BuildStepEnv): string {
+  const bunInstall = env.BUN_INSTALL?.trim();
+  return bunInstall ? bunInstall : path.join(os.homedir(), '.bun');
+}
+
 function parseDaemonInfo(raw: string): { port: number; token: string } {
  const parsed = JSON.parse(raw) as unknown;
  if (
@@ -13,13 +13,14 @@ import { z } from 'zod';

 import { CustomBuildContext } from '../../customBuildContext';
 import {
-  ensureCloudflaredInstalledAsync,
  getDeviceRunSessionIdOrThrow,
+  getNgrokAuthtokenOrThrow,
+  getNgrokTunnelDomainOrThrow,
  spawnDetached,
+  startNgrokTunnelAsync,
  startServeSimWithTunnelAsync,
  uploadRemoteSessionConfigAsync,
  waitForFileAsync,
-  waitForMatchInOutputAsync,
 } from '../utils/remoteDeviceRunSession';

 const ARGENT_PACKAGE_NAME = '@swmansion/argent';
@@ -45,10 +46,13 @@ export function createStartArgentRemoteSessionBuildFunction(
      }),
    ],
    fn: async ({ logger, global }, { inputs, env }) => {
-      // Fail fast before any expensive setup if the orchestrator-injected
-      // DEVICE_RUN_SESSION_ID env var is missing — without it we cannot
-      // report the remote config back to the API server.
+      // Fail fast before any expensive setup if the injected env
+      // vars are missing: DEVICE_RUN_SESSION_ID (to report the remote config
+      // back to the API server), EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN (base domain
+      // for our ngrok tunnels), and NGROK_AUTHTOKEN (to authenticate them).
      const deviceRunSessionId = getDeviceRunSessionIdOrThrow(env);
+      const ngrokTunnelDomain = getNgrokTunnelDomainOrThrow(env);
+      const ngrokAuthtoken = getNgrokAuthtokenOrThrow(env);

      const packageVersion = inputs.package_version.value as string | undefined;
      const versionSpec = packageVersion ?? 'latest';
@@ -62,13 +66,6 @@ export function createStartArgentRemoteSessionBuildFunction(
        await spawn('sudo', ['xcode-select', '-s', XCODE_DEVELOPER_DIR], { env, logger });
      }

-      logger.info('Ensuring cloudflared is installed.');
-      const cloudflaredCommand = await ensureCloudflaredInstalledAsync({
-        runtimePlatform,
-        env,
-        logger,
-      });
-
      // Stale state from a previous run would mask the new server's port.
      await fs.promises.rm(ARGENT_STATE_FILE, { force: true });

@@ -92,19 +89,12 @@ export function createStartArgentRemoteSessionBuildFunction(
      });
      logger.info(`Argent tool-server is listening on port ${toolServerPort}.`);

-      logger.info(`Starting cloudflared tunnel to http://localhost:${toolServerPort}.`);
-      const cloudflared = spawnDetached({
-        command: cloudflaredCommand,
-        args: ['tunnel', '--url', `http://localhost:${toolServerPort}`],
-        env,
-      });
-
-      logger.info('Waiting for a public tunnel URL.');
-      const toolsUrl = await waitForMatchInOutputAsync({
-        process: cloudflared,
-        pattern: /https:\/\/[a-z0-9-]+\.trycloudflare\.com/,
-        timeoutMs: STARTUP_TIMEOUT_MS,
-        description: 'cloudflared tunnel',
+      const toolsUrl = await startNgrokTunnelAsync({
+        port: toolServerPort,
+        subdomainPrefix: 'argent',
+        baseDomain: ngrokTunnelDomain,
+        authtoken: ngrokAuthtoken,
+        logger,
      });
      logger.info(`Tunnel is ready at ${toolsUrl}.`);

@@ -112,6 +102,7 @@ export function createStartArgentRemoteSessionBuildFunction(
      let webPreviewUrl: string | undefined;
      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
        const serveSim = await startServeSimWithTunnelAsync({
+          baseDomain: ngrokTunnelDomain,
          env,
          logger,
          timeoutMs: STARTUP_TIMEOUT_MS,
@@ -65,6 +65,12 @@ export function createStartIosSimulatorBuildFunction(): BuildFunction {
        env,
      });

+      try {
+        await IosSimulatorUtils.disableApsdAsync({ udid, env });
+      } catch (err) {
+        logger.warn({ err }, 'Failed to disable apsd in the Simulator.');
+      }
+
      await IosSimulatorUtils.waitForReadyAsync({ udid, env });

      logger.info('');
@@ -96,6 +102,12 @@ export function createStartIosSimulatorBuildFunction(): BuildFunction {
            env,
          });

+          try {
+            await IosSimulatorUtils.disableApsdAsync({ udid: cloneUdid, env });
+          } catch (err) {
+            logger.warn({ err }, 'Failed to disable apsd in the Simulator.');
+          }
+
          await IosSimulatorUtils.waitForReadyAsync({
            udid: cloneUdid,
            env,
@@ -4,7 +4,7 @@ import spawn from '@expo/turtle-spawn';
 import { CustomBuildContext } from '../../customBuildContext';
 import {
  getDeviceRunSessionIdOrThrow,
-  ensureBrewPackageInstalledAsync,
+  getNgrokTunnelDomainOrThrow,
  startServeSimWithTunnelAsync,
  uploadRemoteSessionConfigAsync,
 } from '../utils/remoteDeviceRunSession';
@@ -23,16 +23,15 @@ export function createStartServeSimRemoteSessionBuildFunction(
    supportedRuntimePlatforms: [BuildRuntimePlatform.DARWIN],
    fn: async ({ logger }, { env }) => {
      const deviceRunSessionId = getDeviceRunSessionIdOrThrow(env);
+      const ngrokTunnelDomain = getNgrokTunnelDomainOrThrow(env);

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

      logger.info(`Selecting Xcode developer directory: ${XCODE_DEVELOPER_DIR}.`);
      await spawn('sudo', ['xcode-select', '-s', XCODE_DEVELOPER_DIR], { env, logger });

-      logger.info('Ensuring cloudflared is installed.');
-      await ensureBrewPackageInstalledAsync({ name: 'cloudflared', env, logger });
-
      const { previewUrl, streamUrl } = await startServeSimWithTunnelAsync({
+        baseDomain: ngrokTunnelDomain,
        env,
        logger,
        timeoutMs: STARTUP_TIMEOUT_MS,
@@ -200,13 +200,21 @@ const TEST_ENV = { PATH: '/custom/bin:/usr/bin' };
 function mockFilesystem({
  tempDir = '/tmp/xclogparser-123',
  jsonOutput = JSON.stringify(FIXTURE_TWO_MODULES),
+  buildLogEntries = ['12345-abc.xcactivitylog'] as string[] | Error,
 }: {
  tempDir?: string;
  jsonOutput?: string;
+  buildLogEntries?: string[] | Error;
 } = {}) {
  jest.spyOn(fs, 'mkdtemp').mockImplementation(async () => tempDir);
  jest.spyOn(fs, 'chmod').mockImplementation(async () => undefined);
  jest.spyOn(fs, 'readFile').mockImplementation(async () => jsonOutput);
+  jest.spyOn(fs, 'readdir').mockImplementation((async () => {
+    if (buildLogEntries instanceof Error) {
+      throw buildLogEntries;
+    }
+    return buildLogEntries;
+  }) as any);
  jest.spyOn(fs, 'rm').mockImplementation(async () => undefined);

  return {
@@ -234,13 +242,14 @@ describe('parseAndReportXcactivitylog', () => {
    mockedSpawn.mockRejectedValueOnce(new Error('xclogparser not found'));
    mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);

-    await parseAndReportXcactivitylog({
+    const result = await parseAndReportXcactivitylog({
      derivedDataPath: '/tmp/derived-data',
      workspacePath: '/tmp/workspace',
      logger,
      env: TEST_ENV,
    });

+    expect(result).toEqual({ skipped: false });
    expect(mockedSpawn).toHaveBeenNthCalledWith(1, 'xclogparser', ['version'], {
      stdio: 'pipe',
      env: TEST_ENV,
@@ -378,14 +387,14 @@ describe('parseAndReportXcactivitylog', () => {
        logger,
        env: TEST_ENV,
      })
-    ).resolves.toBeUndefined();
+    ).resolves.toEqual({ skipped: true });

    expect(logger.info).toHaveBeenCalledWith('Build performance analysis skipped.');
    expect(logger.warn).not.toHaveBeenCalled();
    expect(Sentry.capture).toHaveBeenCalledWith(
      'Build performance analysis failed during "parsing_xclogparser_output"',
      expect.any(Error),
-      { tags: { phase: 'parsing_xclogparser_output' } }
+      expect.objectContaining({ tags: { phase: 'parsing_xclogparser_output' } })
    );
  });

@@ -409,14 +418,14 @@ describe('parseAndReportXcactivitylog', () => {
        logger,
        env: TEST_ENV,
      })
-    ).resolves.toBeUndefined();
+    ).resolves.toEqual({ skipped: true });

    expect(logger.info).toHaveBeenCalledWith('Build performance analysis skipped.');
    expect(logger.warn).not.toHaveBeenCalled();
    expect(Sentry.capture).toHaveBeenCalledWith(
      'Build performance analysis failed during "parsing_xclogparser_output"',
      expect.any(Error),
-      { tags: { phase: 'parsing_xclogparser_output' } }
+      expect.objectContaining({ tags: { phase: 'parsing_xclogparser_output' } })
    );
  });

@@ -437,14 +446,154 @@ describe('parseAndReportXcactivitylog', () => {
        logger,
        env: TEST_ENV,
      })
-    ).resolves.toBeUndefined();
+    ).resolves.toEqual({ skipped: true });

    expect(logger.info).toHaveBeenCalledWith('Build performance analysis skipped.');
    expect(logger.warn).not.toHaveBeenCalled();
    expect(Sentry.capture).toHaveBeenCalledWith(
      'Build performance analysis failed during "running_xclogparser"',
      expect.objectContaining({ message: 'spawn xclogparser ENOENT' }),
-      { tags: { phase: 'running_xclogparser' } }
+      expect.objectContaining({ tags: { phase: 'running_xclogparser' } })
+    );
+  });
+
+  it('surfaces spawn error stderr/stdout/status/signal as Sentry extras', async () => {
+    const logger = createMockLogger();
+    mockFilesystem();
+
+    const spawnError: any = new Error('xclogparser exited with non-zero code: 1');
+    spawnError.stderr = 'XCLogParser fatal: missing xcactivitylog\n';
+    spawnError.stdout = 'some stdout';
+    spawnError.status = 1;
+    spawnError.signal = null;
+
+    mockedDownloadFile.mockResolvedValue(undefined);
+    mockedSpawn
+      .mockRejectedValueOnce(new Error('xclogparser not found')) // version detect
+      .mockResolvedValueOnce({ stdout: '', stderr: '' } as any) // unzip
+      .mockRejectedValueOnce(spawnError); // xclogparser run
+
+    await parseAndReportXcactivitylog({
+      derivedDataPath: '/tmp/derived-data',
+      workspacePath: '/tmp/workspace',
+      logger,
+      env: TEST_ENV,
+    });
+
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      'Build performance analysis failed during "running_xclogparser"',
+      expect.any(Error),
+      {
+        tags: { phase: 'running_xclogparser' },
+        extras: {
+          exitStatus: 1,
+          signal: null,
+          stderr: 'XCLogParser fatal: missing xcactivitylog\n',
+          stdout: 'some stdout',
+        },
+      }
+    );
+  });
+
+  it('skips with actionable guidance when Logs/Build has no .xcactivitylog files', async () => {
+    const logger = createMockLogger();
+    mockFilesystem({ buildLogEntries: [] });
+
+    const result = await parseAndReportXcactivitylog({
+      derivedDataPath: '/tmp/derived-data',
+      workspacePath: '/tmp/workspace',
+      logger,
+      env: TEST_ENV,
+    });
+
+    expect(result).toEqual({ skipped: true });
+    expect(mockedSpawn).not.toHaveBeenCalled();
+    expect(mockedDownloadFile).not.toHaveBeenCalled();
+    expect(Sentry.capture).not.toHaveBeenCalled();
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining(
+        `Build performance analysis skipped: no .xcactivitylog files found at ${path.join(
+          '/tmp/derived-data',
+          'Logs',
+          'Build'
+        )}.`
+      )
+    );
+    expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('custom ios/Gymfile'));
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('derived_data_path("./build")')
+    );
+    expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('result_bundle(true)'));
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('result_bundle_path("./build/result-bundle.xcresult")')
+    );
+  });
+
+  it('skips when Logs/Build directory does not exist', async () => {
+    const logger = createMockLogger();
+    const enoent: any = new Error('ENOENT');
+    enoent.code = 'ENOENT';
+    mockFilesystem({ buildLogEntries: enoent });
+
+    const result = await parseAndReportXcactivitylog({
+      derivedDataPath: '/tmp/derived-data',
+      workspacePath: '/tmp/workspace',
+      logger,
+      env: TEST_ENV,
+    });
+
+    expect(result).toEqual({ skipped: true });
+    expect(mockedSpawn).not.toHaveBeenCalled();
+    expect(mockedDownloadFile).not.toHaveBeenCalled();
+    expect(Sentry.capture).not.toHaveBeenCalled();
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('Build performance analysis skipped: no .xcactivitylog files found')
+    );
+  });
+
+  it('captures to Sentry and skips when readdir fails with a non-ENOENT error', async () => {
+    const logger = createMockLogger();
+    const eacces: any = new Error('EACCES: permission denied');
+    eacces.code = 'EACCES';
+    mockFilesystem({ buildLogEntries: eacces });
+
+    const result = await parseAndReportXcactivitylog({
+      derivedDataPath: '/tmp/derived-data',
+      workspacePath: '/tmp/workspace',
+      logger,
+      env: TEST_ENV,
+    });
+
+    expect(result).toEqual({ skipped: true });
+    expect(mockedSpawn).not.toHaveBeenCalled();
+    expect(mockedDownloadFile).not.toHaveBeenCalled();
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      'Build performance analysis failed during "checking_xcactivitylog_existence"',
+      expect.objectContaining({ code: 'EACCES' }),
+      expect.objectContaining({
+        tags: { phase: 'checking_xcactivitylog_existence' },
+      })
+    );
+    expect(logger.info).toHaveBeenCalledWith('Build performance analysis skipped.');
+    expect(logger.info).not.toHaveBeenCalledWith(expect.stringContaining('custom ios/Gymfile'));
+  });
+
+  it('ignores non-xcactivitylog entries in Logs/Build when deciding to skip', async () => {
+    const logger = createMockLogger();
+    mockFilesystem({ buildLogEntries: ['LogStoreManifest.plist', 'some-other-file.txt'] });
+
+    const result = await parseAndReportXcactivitylog({
+      derivedDataPath: '/tmp/derived-data',
+      workspacePath: '/tmp/workspace',
+      logger,
+      env: TEST_ENV,
+    });
+
+    expect(result).toEqual({ skipped: true });
+    expect(mockedSpawn).not.toHaveBeenCalled();
+    expect(Sentry.capture).not.toHaveBeenCalled();
+    expect(logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('Build performance analysis skipped: no .xcactivitylog files found')
    );
  });

@@ -463,14 +612,14 @@ describe('parseAndReportXcactivitylog', () => {
        logger,
        env: TEST_ENV,
      })
-    ).resolves.toBeUndefined();
+    ).resolves.toEqual({ skipped: true });

    expect(logger.info).toHaveBeenCalledWith('Build performance analysis skipped.');
    expect(logger.warn).not.toHaveBeenCalled();
    expect(Sentry.capture).toHaveBeenCalledWith(
      'Build performance analysis failed during "downloading_xclogparser"',
      expect.objectContaining({ message: 'network unreachable' }),
-      { tags: { phase: 'downloading_xclogparser' } }
+      expect.objectContaining({ tags: { phase: 'downloading_xclogparser' } })
    );
  });

@@ -492,7 +641,7 @@ describe('parseAndReportXcactivitylog', () => {
        logger,
        env: TEST_ENV,
      })
-    ).resolves.toBeUndefined();
+    ).resolves.toEqual({ skipped: false });

    expect(logger.debug).not.toHaveBeenCalled();
    expect(logger.warn).not.toHaveBeenCalled();
@@ -3,8 +3,8 @@ import { BuildStepEnv } from '@expo/steps';
 import spawn, { SpawnResult } from '@expo/turtle-spawn';
 import path from 'path';

-import { XcodeBuildLogger } from './xcpretty';
 import { COMMON_FASTLANE_ENV } from '../../../common/fastlane';
+import { XcodeBuildLogger } from '../../../common/xcpretty';

 export async function runFastlaneGym({
  workingDir,
@@ -16,9 +16,9 @@ const XCLOGPARSER_DOWNLOAD_TIMEOUT_MS = 20_000;
 const XCLOGPARSER_OUTPUT_FILENAME = 'xcactivitylog.json';

 /**
- * Never throws — best-effort observability that does not affect build status.
- * Failures route to Sentry via `Sentry.capture` for engineering triage;
- * users see only a generic skip message.
+ * Catches all internal failures (logged + routed to Sentry); returns
+ * `{ skipped: true }` when analysis did not produce a report so callers can
+ * mark the build phase skipped.
 */
 export async function parseAndReportXcactivitylog({
  derivedDataPath,
@@ -34,10 +34,38 @@ export async function parseAndReportXcactivitylog({
  logger: bunyan;
  proxyBaseUrl?: string;
  env: BuildStepEnv;
-}): Promise<void> {
+}): Promise<{ skipped: boolean }> {
  let tempDir: string | undefined;
-  let phase = 'creating_temp_directory';
+  let phase = 'checking_xcactivitylog_existence';
  try {
+    const logsBuildDir = path.join(derivedDataPath, 'Logs', 'Build');
+    let buildLogEntries: string[];
+    try {
+      buildLogEntries = await fs.readdir(logsBuildDir);
+    } catch (err: any) {
+      if (err?.code !== 'ENOENT') {
+        throw err;
+      }
+      buildLogEntries = [];
+    }
+    const hasActivityLog = buildLogEntries.some(entry => entry.endsWith('.xcactivitylog'));
+    if (!hasActivityLog) {
+      logger.info(
+        [
+          `Build performance analysis skipped: no .xcactivitylog files found at ${logsBuildDir}.`,
+          '',
+          'This typically happens when your project has a custom ios/Gymfile. To enable',
+          'build performance analysis, add the following lines to your Gymfile:',
+          '',
+          '    derived_data_path("./build")',
+          '    result_bundle(true)',
+          '    result_bundle_path("./build/result-bundle.xcresult")',
+        ].join('\n')
+      );
+      return { skipped: true };
+    }
+
+    phase = 'creating_temp_directory';
    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'xclogparser-'));

    phase = 'resolving_xclogparser';
@@ -79,10 +107,20 @@ export async function parseAndReportXcactivitylog({
    );

    logger.info(formatReport(data));
+    return { skipped: false };
  } catch (err: any) {
    logger.info('Build performance analysis skipped.');
    const msg = `Build performance analysis failed during "${phase}"`;
-    Sentry.capture(msg, err, { tags: { phase } });
+    Sentry.capture(msg, err, {
+      tags: { phase },
+      extras: {
+        exitStatus: err?.status,
+        signal: err?.signal,
+        stderr: err?.stderr?.slice(-4000),
+        stdout: err?.stdout?.slice(-4000),
+      },
+    });
+    return { skipped: true };
  } finally {
    if (tempDir) {
      await asyncResult(fs.rm(tempDir, { force: true, recursive: true }));
@@ -1,91 +0,0 @@
-import { bunyan } from '@expo/logger';
-import spawnAsync, { SpawnPromise, SpawnResult } from '@expo/spawn-async';
-import { ExpoRunFormatter } from '@expo/xcpretty';
-import assert from 'assert';
-import fg from 'fast-glob';
-import fs from 'fs-extra';
-import path from 'path';
-
-const CHECK_FILE_INTERVAL_MS = 1000;
-
-export class XcodeBuildLogger {
-  private loggerError?: Error;
-  private flushing: boolean = false;
-  private logReaderPromise?: SpawnPromise<SpawnResult>;
-  private logsPath?: string;
-
-  constructor(
-    private readonly logger: bunyan,
-    private readonly projectRoot: string
-  ) {}
-
-  public async watchLogFiles(logsDirectory: string): Promise<void> {
-    while (!this.flushing) {
-      const logsFilename = await this.getBuildLogFilename(logsDirectory);
-      if (logsFilename) {
-        this.logsPath = path.join(logsDirectory, logsFilename);
-        void this.startBuildLogger(this.logsPath);
-        return;
-      }
-      await new Promise(res => setTimeout(res, CHECK_FILE_INTERVAL_MS));
-    }
-  }
-
-  public async flush(): Promise<void> {
-    this.flushing = true;
-    if (this.loggerError) {
-      throw this.loggerError;
-    }
-    if (this.logReaderPromise) {
-      this.logReaderPromise.child.kill('SIGINT');
-      try {
-        await this.logReaderPromise;
-      } catch {}
-    }
-    if (this.logsPath) {
-      await this.findBundlerErrors(this.logsPath);
-    }
-  }
-  private async getBuildLogFilename(logsDirectory: string): Promise<string | undefined> {
-    const paths = await fg('*.log', { cwd: logsDirectory });
-    return paths.length >= 1 ? paths[0] : undefined;
-  }
-
-  private async startBuildLogger(logsPath: string): Promise<void> {
-    try {
-      const formatter = ExpoRunFormatter.create(this.projectRoot, {
-        // TODO: Can provide xcode project name for better parsing
-        isDebug: false,
-      });
-      this.logReaderPromise = spawnAsync('tail', ['-n', '+0', '-f', logsPath], { stdio: 'pipe' });
-      assert(this.logReaderPromise.child.stdout, 'stdout is not available');
-      this.logReaderPromise.child.stdout.on('data', (data: string) => {
-        const lines = formatter.pipe(data.toString());
-        for (const line of lines) {
-          this.logger.info(line);
-        }
-      });
-      await this.logReaderPromise;
-
-      this.logger.info(formatter.getBuildSummary());
-    } catch (err: any) {
-      if (!this.flushing) {
-        this.loggerError = err;
-      }
-    }
-  }
-
-  private async findBundlerErrors(logsPath: string): Promise<void> {
-    try {
-      const logFile = await fs.readFile(logsPath, 'utf-8');
-      const match = logFile.match(
-        /Welcome to Metro!\s* Fast - Scalable - Integrated\s*([\s\S]*)Run CLI with --verbose flag for more details.\nCommand PhaseScriptExecution failed with a nonzero exit code/
-      );
-      if (match) {
-        this.logger.info(match[1]);
-      }
-    } catch (err) {
-      this.logger.error({ err }, 'Failed to read Xcode logs');
-    }
-  }
-}
@@ -1,17 +1,15 @@
 import { SystemError } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
-import { BuildRuntimePlatform, BuildStepEnv } from '@expo/steps';
+import { BuildStepEnv } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
+import * as ngrok from '@ngrok/ngrok';
 import { graphql } from 'gql.tada';
+import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';

 import { CustomBuildContext } from '../../customBuildContext';
 import { sleepAsync } from '../../utils/retry';

-const TRYCLOUDFLARE_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
-const CLOUDFLARED_LINUX_INSTALL_PATH = '/usr/local/bin/cloudflared';
-
 const START_DEVICE_RUN_SESSION_MUTATION = graphql(`
  mutation StartDeviceRunSession($deviceRunSessionId: ID!, $remoteConfig: JSONObject!) {
    deviceRunSession {
@@ -31,13 +29,37 @@ export function getDeviceRunSessionIdOrThrow(env: BuildStepEnv): string {
  if (!deviceRunSessionId) {
    throw new SystemError(
      'DEVICE_RUN_SESSION_ID is not set. ' +
-        'This step must run as part of a device run session created by the API server, ' +
+        'This step must run as part of a device run session ' +
        'which injects DEVICE_RUN_SESSION_ID into the job environment.'
    );
  }
  return deviceRunSessionId;
 }

+export function getNgrokTunnelDomainOrThrow(env: BuildStepEnv): string {
+  const baseDomain = env.EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN;
+  if (!baseDomain) {
+    throw new SystemError(
+      'EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN is not set. ' +
+        'This step must run as part of a device run session ' +
+        'which injects EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN into the job environment.'
+    );
+  }
+  return baseDomain;
+}
+
+export function getNgrokAuthtokenOrThrow(env: BuildStepEnv): string {
+  const authtoken = env.NGROK_AUTHTOKEN;
+  if (!authtoken) {
+    throw new SystemError(
+      'NGROK_AUTHTOKEN is not set. ' +
+        'This step must run as part of a device run session ' +
+        'which injects NGROK_AUTHTOKEN into the job environment.'
+    );
+  }
+  return authtoken;
+}
+
 export async function uploadRemoteSessionConfigAsync({
  ctx,
  deviceRunSessionId,
@@ -62,22 +84,6 @@ export async function uploadRemoteSessionConfigAsync({
  }
 }

-export async function ensureBrewPackageInstalledAsync({
-  name,
-  env,
-  logger,
-}: {
-  name: string;
-  env: BuildStepEnv;
-  logger: bunyan;
-}): Promise<void> {
-  await spawn(
-    'bash',
-    ['-c', `command -v ${name} >/dev/null 2>&1 || HOMEBREW_NO_AUTO_UPDATE=1 brew install ${name}`],
-    { env, logger }
-  );
-}
-
 export type DetachedProcessHandle = {
  getOutput: () => string;
 };
@@ -115,10 +121,12 @@ export function spawnDetached({
 }

 export async function startServeSimWithTunnelAsync({
+  baseDomain,
  env,
  logger,
  timeoutMs,
 }: {
+  baseDomain: string;
  env: BuildStepEnv;
  logger: bunyan;
  timeoutMs: number;
@@ -129,12 +137,16 @@ export async function startServeSimWithTunnelAsync({
    args: [
      'serve-sim-szdziedzic@latest',
      '--tunnel',
-      '--tunnel-protocol',
-      'quic',
+      '--tunnel-provider',
+      'ngrok',
+      '--tunnel-domain',
+      baseDomain,
      '--stream-max-dimension',
      '1280',
      '--stream-quality',
      '0.55',
+      '--codec',
+      'webrtc',
    ],
    env,
  });
@@ -143,8 +155,8 @@ export async function startServeSimWithTunnelAsync({
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const output = serveSim.getOutput();
-    const previewUrl = matchLabeledUrl(output, 'Tunnel');
-    const streamUrl = matchLabeledUrl(output, 'Stream');
+    const previewUrl = matchLabeledUrl({ output, label: 'Tunnel', baseDomain });
+    const streamUrl = matchLabeledUrl({ output, label: 'Stream', baseDomain });
    if (previewUrl && streamUrl) {
      return { previewUrl, streamUrl };
    }
@@ -155,90 +167,49 @@ export async function startServeSimWithTunnelAsync({
  );
 }

-function matchLabeledUrl(content: string, label: string): string | null {
-  const labelPattern = new RegExp(`${label}:\\s*(${TRYCLOUDFLARE_URL_PATTERN.source})`);
-  const match = labelPattern.exec(content);
+function matchLabeledUrl({
+  output,
+  label,
+  baseDomain,
+}: {
+  output: string;
+  label: string;
+  baseDomain: string;
+}): string | null {
+  const labelPattern = new RegExp(
+    `${label}:\\s*(https:\\/\\/[a-z0-9-]+\\.${escapeRegExp(baseDomain)})`
+  );
+  const match = labelPattern.exec(output);
  return match ? match[1] : null;
 }

-export async function ensureCloudflaredInstalledAsync({
-  runtimePlatform,
-  env,
+export async function startNgrokTunnelAsync({
+  port,
+  subdomainPrefix,
+  baseDomain,
+  authtoken,
  logger,
 }: {
-  runtimePlatform: BuildRuntimePlatform;
-  env: BuildStepEnv;
+  port: number;
+  subdomainPrefix: string;
+  baseDomain: string;
+  authtoken: string;
  logger: bunyan;
 }): Promise<string> {
-  if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
-    await ensureBrewPackageInstalledAsync({ name: 'cloudflared', env, logger });
-    return 'cloudflared';
+  const domain = `${subdomainPrefix}-${randomBytes(8).toString('hex')}.${baseDomain}`;
+  logger.info(`Starting ngrok tunnel ${domain} -> http://localhost:${port}.`);
+  // Run the ngrok agent in-process via the SDK; it keeps the session alive until
+  // the process exits, and the step blocks forever to hold it open.
+  const listener = await ngrok.forward({ addr: port, authtoken, domain });
+  const url = listener.url();
+  if (!url) {
+    throw new SystemError(`ngrok tunnel for ${domain} did not return a public URL.`);
  }
-  if (await isCommandAvailableAsync({ command: 'cloudflared', env })) {
-    return 'cloudflared';
-  }
-  const cloudflaredArch = cloudflaredLinuxArchForNodeArch(os.arch());
-  const downloadUrl = `https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${cloudflaredArch}`;
-  logger.info(`Downloading cloudflared from ${downloadUrl} to ${CLOUDFLARED_LINUX_INSTALL_PATH}.`);
-  await spawn('sudo', ['curl', '-fsSL', '-o', CLOUDFLARED_LINUX_INSTALL_PATH, downloadUrl], {
-    env,
-    logger,
-  });
-  await spawn('sudo', ['chmod', '+x', CLOUDFLARED_LINUX_INSTALL_PATH], { env, logger });
-  // Return the absolute install path so the tunnel command works even when
-  // /usr/local/bin is not on the step's PATH.
-  return CLOUDFLARED_LINUX_INSTALL_PATH;
+  return url;
 }

-function cloudflaredLinuxArchForNodeArch(arch: string): 'amd64' | 'arm64' {
-  if (arch === 'x64') {
-    return 'amd64';
-  }
-  if (arch === 'arm64') {
-    return 'arm64';
-  }
-  throw new SystemError(
-    `Unsupported architecture for cloudflared on Linux: "${arch}". Expected "x64" or "arm64".`
-  );
-}
-
-async function isCommandAvailableAsync({
-  command,
-  env,
-}: {
-  command: string;
-  env: BuildStepEnv;
-}): Promise<boolean> {
-  try {
-    await spawn('bash', ['-c', `command -v ${command}`], { env, ignoreStdio: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function waitForMatchInOutputAsync({
-  process,
-  pattern,
-  timeoutMs,
-  description,
-}: {
-  process: DetachedProcessHandle;
-  pattern: RegExp;
-  timeoutMs: number;
-  description: string;
-}): Promise<string> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const match = pattern.exec(process.getOutput());
-    if (match) {
-      return match[1] ?? match[0];
-    }
-    await sleepAsync(1_000);
-  }
-  throw new SystemError(
-    `Timed out waiting for ${description} to start. Last output:\n${process.getOutput() || '<empty>'}`
-  );
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

 export async function waitForFileAsync<T>({
@@ -5,6 +5,7 @@ export const FastfileResignTemplate = `lane :do_resign do
    provisioning_profile: {<% _.forEach(PROFILES, function(profile) { %>
      "<%- profile.BUNDLE_ID %>" => "<%- profile.PATH %>",<% }); %>
    },
+    use_app_entitlements: true,
    keychain_path: "<%- KEYCHAIN_PATH %>"
  )
 end
@@ -122,9 +122,10 @@ export namespace IosSimulatorUtils {
    udid: IosSimulatorUuid;
    env: NodeJS.ProcessEnv;
  }): Promise<void> {
+    const readinessScreenshotPath = path.join(os.tmpdir(), 'eas-simulator-readiness.png');
    await retryAsync(
      async () => {
-        await spawn('xcrun', ['simctl', 'io', udid, 'screenshot', '/dev/null'], {
+        await spawn('xcrun', ['simctl', 'io', udid, 'screenshot', readinessScreenshotPath], {
          env,
        });
      },
@@ -136,6 +137,7 @@ export namespace IosSimulatorUtils {
        },
      }
    );
+    await fs.promises.rm(readinessScreenshotPath, { force: true });

    // Wait for data migration to complete before declaring the simulator ready
    // Based on WebKit's approach: https://trac.webkit.org/changeset/231452/webkit
@@ -155,6 +157,25 @@ export namespace IosSimulatorUtils {
    );
  }

+  export async function disableApsdAsync({
+    udid,
+    env,
+  }: {
+    udid: IosSimulatorUuid;
+    env: NodeJS.ProcessEnv;
+  }): Promise<void> {
+    await spawn(
+      'xcrun',
+      ['simctl', 'spawn', udid, 'launchctl', 'disable', 'system/com.apple.apsd'],
+      { env }
+    );
+    await spawn(
+      'xcrun',
+      ['simctl', 'spawn', udid, 'launchctl', 'bootout', 'system/com.apple.apsd'],
+      { env }
+    );
+  }
+
  export async function collectLogsAsync({
    deviceIdentifier,
    env,
@@ -0,0 +1,64 @@
+import spawn from '@expo/turtle-spawn';
+import os from 'node:os';
+import path from 'node:path';
+
+import { IosSimulatorUtils } from '../IosSimulatorUtils';
+import { retryAsync } from '../retry';
+
+jest.mock('@expo/turtle-spawn', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+jest.mock('../retry', () => ({
+  retryAsync: jest.fn(async fn => await fn(0)),
+}));
+
+const mockedSpawn = jest.mocked(spawn);
+
+describe('IosSimulatorUtils', () => {
+  beforeEach(() => {
+    mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);
+  });
+
+  describe(IosSimulatorUtils.waitForReadyAsync, () => {
+    it('takes the readiness screenshot into a writable temp file, not /dev/null', async () => {
+      await IosSimulatorUtils.waitForReadyAsync({
+        udid: 'test-udid' as any,
+        env: process.env,
+      });
+
+      expect(mockedSpawn).toHaveBeenCalledWith(
+        'xcrun',
+        [
+          'simctl',
+          'io',
+          'test-udid',
+          'screenshot',
+          path.join(os.tmpdir(), 'eas-simulator-readiness.png'),
+        ],
+        { env: process.env }
+      );
+    });
+  });
+
+  describe(IosSimulatorUtils.disableApsdAsync, () => {
+    it('disables and boots out apsd in the simulator', async () => {
+      await IosSimulatorUtils.disableApsdAsync({
+        udid: 'test-udid' as any,
+        env: process.env,
+      });
+
+      expect(mockedSpawn).toHaveBeenCalledWith(
+        'xcrun',
+        ['simctl', 'spawn', 'test-udid', 'launchctl', 'disable', 'system/com.apple.apsd'],
+        { env: process.env }
+      );
+      expect(mockedSpawn).toHaveBeenCalledWith(
+        'xcrun',
+        ['simctl', 'spawn', 'test-udid', 'launchctl', 'bootout', 'system/com.apple.apsd'],
+        { env: process.env }
+      );
+    });
+  });
+});
@@ -71,6 +71,26 @@ describe(findArtifacts, () => {
    expect(paths.length).toBe(2);
  });

+  test('with absolute glob pattern', async () => {
+    await fs.mkdirp('/tmp');
+    await fs.mkdirp('/tmp/maestro_xctestrunner_xcodebuild_output123');
+    await fs.mkdirp('/tmp/maestro_xctestrunner_xcodebuild_output456');
+    const loggerMock = {
+      info: jest.fn(),
+      error: jest.fn(),
+    };
+    const paths = await findArtifacts({
+      rootDir: '/Users/expo/build',
+      patternOrPath: '/tmp/maestro_xctestrunner_xcodebuild_output*',
+      logger: loggerMock as any,
+    });
+    expect(loggerMock.error).toHaveBeenCalledTimes(0);
+    expect(paths).toEqual([
+      '/tmp/maestro_xctestrunner_xcodebuild_output123',
+      '/tmp/maestro_xctestrunner_xcodebuild_output456',
+    ]);
+  });
+
  test('with missing file in empty directory', async () => {
    await fs.mkdirp('/dir1/dir2/dir3');
    let errMsg = '';
@@ -0,0 +1,273 @@
+import { Platform } from '@expo/eas-build-job';
+
+import { BuildContext } from '../../context';
+import * as expoUpdates from '../expoUpdates';
+import { uploadEmbeddedBundleAsync } from '../expoUpdatesEmbedded';
+import * as easCli from '../easCli';
+import * as artifacts from '../artifacts';
+
+jest.mock('../expoUpdates');
+jest.mock('../easCli');
+jest.mock('../artifacts');
+
+const mockZipEntries = jest.fn();
+const mockZipExtract = jest.fn();
+const mockZipClose = jest.fn();
+
+jest.mock('node-stream-zip', () => ({
+  __esModule: true,
+  default: {
+    async: jest.fn(() => ({
+      entries: mockZipEntries,
+      extract: mockZipExtract,
+      close: mockZipClose,
+    })),
+  },
+}));
+
+function zipEntryMap(entries: Record<string, true>): Record<string, { name: string }> {
+  return Object.fromEntries(Object.keys(entries).map(name => [name, { name }]));
+}
+
+function makeCtx(overrides: {
+  platform: Platform;
+  simulator?: boolean;
+  channel?: string;
+  env?: Record<string, string>;
+}): BuildContext<any> {
+  const job =
+    overrides.platform === Platform.IOS
+      ? {
+          platform: Platform.IOS,
+          simulator: overrides.simulator ?? false,
+          updates: overrides.channel ? { channel: overrides.channel } : undefined,
+        }
+      : {
+          platform: Platform.ANDROID,
+          updates: overrides.channel ? { channel: overrides.channel } : undefined,
+        };
+
+  return {
+    job,
+    env: overrides.env ?? {},
+    appConfig: Promise.resolve({
+      updates: { url: 'https://u.expo.dev/project-id' },
+    }),
+    logger: {
+      info: jest.fn(),
+      warn: jest.fn(),
+    },
+    markBuildPhaseSkipped: jest.fn(),
+    markBuildPhaseHasWarnings: jest.fn(),
+    getReactNativeProjectDirectory: () => '/project',
+  } as any;
+}
+
+describe('uploadEmbeddedBundleAsync', () => {
+  beforeEach(() => {
+    jest.mocked(expoUpdates.isEASUpdateConfigured).mockResolvedValue(true);
+    jest.mocked(easCli.runEasCliCommand).mockResolvedValue({} as any);
+    jest.mocked(artifacts.findArtifacts).mockResolvedValue([]);
+    mockZipEntries.mockResolvedValue({});
+    mockZipExtract.mockResolvedValue(undefined);
+    mockZipClose.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+    jest.restoreAllMocks();
+  });
+
+  it('skips when EAS Update is not configured', async () => {
+    jest.mocked(expoUpdates.isEASUpdateConfigured).mockResolvedValue(false);
+    const ctx = makeCtx({ platform: Platform.ANDROID, channel: 'production' });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(ctx.markBuildPhaseSkipped).toHaveBeenCalled();
+    expect(artifacts.findArtifacts).not.toHaveBeenCalled();
+  });
+
+  it('warns when no channel is configured and does not look for the archive', async () => {
+    const ctx = makeCtx({ platform: Platform.ANDROID });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(ctx.logger.warn).toHaveBeenCalledWith(
+      'Skipping embedded bundle upload: no channel configured for this build profile.'
+    );
+    expect(ctx.markBuildPhaseHasWarnings).toHaveBeenCalled();
+    expect(artifacts.findArtifacts).not.toHaveBeenCalled();
+  });
+
+  it('throws for an unsupported platform', async () => {
+    const ctx = makeCtx({ platform: Platform.ANDROID, channel: 'production' });
+    (ctx.job as { platform: string }).platform = 'web';
+
+    await expect(uploadEmbeddedBundleAsync(ctx)).rejects.toThrow(
+      'Uploading embedded updates is not supported for the web platform.'
+    );
+    expect(artifacts.findArtifacts).not.toHaveBeenCalled();
+  });
+
+  it('uploads from Android APK archives', async () => {
+    jest.mocked(artifacts.findArtifacts).mockResolvedValue(['/tmp/app-release.apk']);
+    mockZipEntries.mockResolvedValue(
+      zipEntryMap({
+        'assets/index.android.bundle': true,
+        'assets/app.manifest': true,
+      })
+    );
+    const ctx = makeCtx({
+      platform: Platform.ANDROID,
+      channel: 'production',
+      env: { EAS_BUILD_ID: 'build-123' },
+    });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(mockZipExtract).toHaveBeenCalledWith(
+      'assets/index.android.bundle',
+      expect.stringContaining('index.android.bundle')
+    );
+    expect(easCli.runEasCliCommand).toHaveBeenCalledWith(
+      expect.objectContaining({
+        args: expect.arrayContaining([
+          'update:embedded:upload',
+          '--platform',
+          Platform.ANDROID,
+          '--channel',
+          'production',
+          '--build-id',
+          'build-123',
+        ]),
+      })
+    );
+  });
+
+  it('uploads from Android AAB archives', async () => {
+    jest.mocked(artifacts.findArtifacts).mockResolvedValue(['/tmp/app-release.aab']);
+    mockZipEntries.mockResolvedValue(
+      zipEntryMap({
+        'base/assets/index.android.bundle': true,
+        'base/assets/app.manifest': true,
+      })
+    );
+    const ctx = makeCtx({ platform: Platform.ANDROID, channel: 'production' });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(mockZipExtract).toHaveBeenCalledWith(
+      'base/assets/index.android.bundle',
+      expect.stringContaining('index.android.bundle')
+    );
+    expect(easCli.runEasCliCommand).toHaveBeenCalled();
+  });
+
+  it('uploads from iOS IPA archives', async () => {
+    jest.mocked(artifacts.findArtifacts).mockResolvedValue(['/tmp/App.ipa']);
+    mockZipEntries.mockResolvedValue(
+      zipEntryMap({
+        'Payload/App.app/main.jsbundle': true,
+        'Payload/App.app/EXUpdates.bundle/app.manifest': true,
+      })
+    );
+    const ctx = makeCtx({ platform: Platform.IOS, channel: 'production' });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(easCli.runEasCliCommand).toHaveBeenCalledWith(
+      expect.objectContaining({
+        args: expect.arrayContaining(['--platform', Platform.IOS]),
+      })
+    );
+  });
+
+  it('skips simulator builds', async () => {
+    const ctx = makeCtx({ platform: Platform.IOS, simulator: true, channel: 'preview' });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(ctx.markBuildPhaseSkipped).toHaveBeenCalled();
+    expect(artifacts.findArtifacts).not.toHaveBeenCalled();
+  });
+
+  it('warns when bundle or manifest is missing from the archive', async () => {
+    jest.mocked(artifacts.findArtifacts).mockResolvedValue(['/tmp/app-release.apk']);
+    mockZipEntries.mockResolvedValue(
+      zipEntryMap({
+        'assets/app.manifest': true,
+      })
+    );
+    const ctx = makeCtx({ platform: Platform.ANDROID, channel: 'production' });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(ctx.logger.warn).toHaveBeenCalledWith(
+      'Skipping embedded bundle upload: bundle or manifest not found in archive.'
+    );
+    expect(easCli.runEasCliCommand).not.toHaveBeenCalled();
+  });
+
+  it('warns when build archive is not found', async () => {
+    jest.mocked(artifacts.findArtifacts).mockResolvedValue([]);
+    const ctx = makeCtx({ platform: Platform.ANDROID, channel: 'production' });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(ctx.logger.warn).toHaveBeenCalledWith(
+      'Skipping embedded bundle upload: build archive not found.'
+    );
+    expect(ctx.markBuildPhaseHasWarnings).toHaveBeenCalled();
+    expect(easCli.runEasCliCommand).not.toHaveBeenCalled();
+  });
+
+  it('treats findArtifacts errors as no archive found', async () => {
+    jest.mocked(artifacts.findArtifacts).mockRejectedValue(new Error('glob failed'));
+    const ctx = makeCtx({ platform: Platform.ANDROID, channel: 'production' });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(ctx.logger.warn).toHaveBeenCalledWith(
+      'Skipping embedded bundle upload: build archive not found.'
+    );
+    expect(ctx.markBuildPhaseHasWarnings).toHaveBeenCalled();
+    expect(easCli.runEasCliCommand).not.toHaveBeenCalled();
+  });
+
+  it('warns and continues when CLI upload throws', async () => {
+    jest.mocked(artifacts.findArtifacts).mockResolvedValue(['/tmp/app-release.apk']);
+    mockZipEntries.mockResolvedValue(
+      zipEntryMap({
+        'assets/index.android.bundle': true,
+        'assets/app.manifest': true,
+      })
+    );
+    jest.mocked(easCli.runEasCliCommand).mockRejectedValue(new Error('upload failed'));
+    const ctx = makeCtx({ platform: Platform.ANDROID, channel: 'production' });
+
+    await uploadEmbeddedBundleAsync(ctx);
+
+    expect(ctx.logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      'Failed to upload embedded bundle.'
+    );
+    expect(ctx.markBuildPhaseHasWarnings).toHaveBeenCalled();
+  });
+
+  it('swallows zip.close() failures so they do not mask the upload result', async () => {
+    jest.mocked(artifacts.findArtifacts).mockResolvedValue(['/tmp/app-release.apk']);
+    mockZipEntries.mockResolvedValue(
+      zipEntryMap({
+        'assets/index.android.bundle': true,
+        'assets/app.manifest': true,
+      })
+    );
+    mockZipClose.mockRejectedValue(new Error('close failed'));
+    const ctx = makeCtx({ platform: Platform.ANDROID, channel: 'production' });
+
+    await expect(uploadEmbeddedBundleAsync(ctx)).resolves.toBeUndefined();
+    expect(easCli.runEasCliCommand).toHaveBeenCalled();
+    expect(mockZipClose).toHaveBeenCalled();
+  });
+});
@@ -19,11 +19,12 @@ export async function findArtifacts({
  /** If provided, will log error suggesting possible files to upload. */
  logger: bunyan | null;
 }): Promise<string[]> {
-  const files = path.isAbsolute(patternOrPath)
-    ? (await fs.pathExists(patternOrPath))
-      ? [patternOrPath]
-      : []
-    : await fg(patternOrPath, { cwd: rootDir, onlyFiles: false });
+  const files =
+    path.isAbsolute(patternOrPath) && !fg.isDynamicPattern(patternOrPath)
+      ? (await fs.pathExists(patternOrPath))
+        ? [patternOrPath]
+        : []
+      : await fg(patternOrPath, { cwd: rootDir, onlyFiles: false });
  if (files.length === 0) {
    if (fg.isDynamicPattern(patternOrPath)) {
      throw new FindArtifactsError(`There are no files matching pattern "${patternOrPath}"`);
@@ -0,0 +1,118 @@
+import { Android, BuildJob, Ios, Platform } from '@expo/eas-build-job';
+import { PipeMode } from '@expo/logger';
+import { asyncResult } from '@expo/results';
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import StreamZip from 'node-stream-zip';
+
+import { findArtifacts } from './artifacts';
+import { runEasCliCommand } from './easCli';
+import { resolveArtifactPath } from '../ios/resolve';
+import { BuildContext } from '../context';
+import { isEASUpdateConfigured } from './expoUpdates';
+
+export async function uploadEmbeddedBundleAsync(ctx: BuildContext<BuildJob>): Promise<void> {
+  if (!(await isEASUpdateConfigured(ctx))) {
+    ctx.markBuildPhaseSkipped();
+    return;
+  }
+
+  const { platform } = ctx.job;
+  if (platform === Platform.IOS && (ctx.job as Ios.Job).simulator) {
+    ctx.markBuildPhaseSkipped();
+    return;
+  }
+
+  const channel = ctx.job.updates?.channel;
+  if (!channel) {
+    ctx.logger.warn(
+      'Skipping embedded bundle upload: no channel configured for this build profile.'
+    );
+    ctx.markBuildPhaseHasWarnings();
+    return;
+  }
+
+  const projectDir = ctx.getReactNativeProjectDirectory();
+
+  let archivePattern: string;
+  if (platform === Platform.IOS) {
+    archivePattern = resolveArtifactPath(ctx as BuildContext<Ios.Job>);
+  } else if (platform === Platform.ANDROID) {
+    archivePattern =
+      (ctx as BuildContext<Android.Job>).job.applicationArchivePath ??
+      'android/app/build/outputs/**/*.{apk,aab}';
+  } else {
+    throw new Error(`Uploading embedded updates is not supported for the ${platform} platform.`);
+  }
+
+  const [archivePath] = await findArtifacts({
+    rootDir: projectDir,
+    patternOrPath: archivePattern,
+    logger: null,
+  }).catch(() => [] as string[]);
+
+  if (!archivePath) {
+    ctx.logger.warn('Skipping embedded bundle upload: build archive not found.');
+    ctx.markBuildPhaseHasWarnings();
+    return;
+  }
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'eas-embedded-bundle-'));
+  const bundleName = platform === Platform.IOS ? 'main.jsbundle' : 'index.android.bundle';
+  const bundlePath = path.join(tmpDir, bundleName);
+  const manifestPath = path.join(tmpDir, 'app.manifest');
+  const zip = new StreamZip.async({ file: archivePath });
+  try {
+    const entries = Object.values(await zip.entries());
+    const bundleEntry = entries.find(e =>
+      platform === Platform.IOS
+        ? e.name.endsWith('/main.jsbundle')
+        : e.name.endsWith('assets/index.android.bundle')
+    );
+    const manifestEntry = entries.find(e =>
+      platform === Platform.IOS
+        ? e.name.includes('EXUpdates.bundle/app.manifest')
+        : e.name.endsWith('assets/app.manifest')
+    );
+
+    if (!bundleEntry || !manifestEntry) {
+      ctx.logger.warn('Skipping embedded bundle upload: bundle or manifest not found in archive.');
+      ctx.markBuildPhaseHasWarnings();
+      return;
+    }
+
+    await zip.extract(bundleEntry.name, bundlePath);
+    await zip.extract(manifestEntry.name, manifestPath);
+
+    const args = [
+      'update:embedded:upload',
+      '--platform',
+      platform,
+      '--bundle',
+      bundlePath,
+      '--manifest',
+      manifestPath,
+      '--channel',
+      channel,
+      '--non-interactive',
+    ];
+    if (ctx.env.EAS_BUILD_ID) {
+      args.push('--build-id', ctx.env.EAS_BUILD_ID);
+    }
+    await runEasCliCommand({
+      args,
+      options: {
+        cwd: projectDir,
+        env: ctx.env,
+        logger: ctx.logger,
+        mode: PipeMode.STDERR_ONLY_AS_STDOUT,
+      },
+    });
+  } catch (err: any) {
+    ctx.logger.warn({ err }, 'Failed to upload embedded bundle.');
+    ctx.markBuildPhaseHasWarnings();
+  } finally {
+    await asyncResult(zip.close());
+  }
+}
@@ -1,6 +1,6 @@
 {
  "name": "create-eas-build-function",
-  "version": "19.0.0",
+  "version": "20.1.0",
  "description": "Create functions for use in EAS Build custom builds.",
  "keywords": [
    "expo",
@@ -35,7 +35,7 @@
    "clean": "rimraf ./build/ \"*.tsbuildinfo\""
  },
  "dependencies": {
-    "@expo/steps": "19.0.0"
+    "@expo/steps": "20.1.0"
  },
  "devDependencies": {
    "@expo/package-manager": "1.9.10",
@@ -1,6 +1,6 @@
 {
  "name": "@expo/downloader",
-  "version": "19.0.0",
+  "version": "20.0.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
  "author": "Expo <[email protected]>",
@@ -1,6 +1,6 @@
 {
  "name": "eas-build-cache-provider",
-  "version": "19.0.0",
+  "version": "20.0.0",
  "description": "A build cache provider plugin for the Expo CLI",
  "homepage": "https://github.com/expo/eas-cli",
  "bugs": "https://github.com/expo/eas-cli/issues",
@@ -1,6 +1,6 @@
 {
  "name": "@expo/eas-build-job",
-  "version": "19.0.0",
+  "version": "20.1.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "MIT",
  "author": "Expo <[email protected]>",
@@ -25,9 +25,9 @@
    "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\""
  },
  "dependencies": {
-    "@expo/logger": "19.0.0",
+    "@expo/logger": "20.0.0",
    "@expo/results": "1.0.0",
-    "@expo/turtle-spawn": "19.0.0",
+    "@expo/turtle-spawn": "20.0.0",
    "joi": "^17.13.1",
    "semver": "^7.6.2",
    "zod": "^4.3.5"
@@ -534,4 +534,47 @@ describe('Ios.JobSchema', () => {
    expect(value).toMatchObject(job);
    expect(error).toBeFalsy();
  });
+
+  test('accepts optional refreshAdHocProvisioningProfile', () => {
+    const job = {
+      secrets: {
+        buildCredentials,
+      },
+      type: Workflow.GENERIC,
+      platform: Platform.IOS,
+      projectArchive: {
+        type: ArchiveSourceType.URL,
+        url: 'http://localhost:3000',
+      },
+      projectRootDirectory: '.',
+      initiatingUserId: randomUUID(),
+      appId: randomUUID(),
+      refreshAdHocProvisioningProfile: true,
+    };
+
+    const { value, error } = Ios.JobSchema.validate(job, joiOptions);
+    expect(value.refreshAdHocProvisioningProfile).toBe(true);
+    expect(error).toBeFalsy();
+  });
+
+  test('does not require refreshAdHocProvisioningProfile', () => {
+    const job = {
+      secrets: {
+        buildCredentials,
+      },
+      type: Workflow.GENERIC,
+      platform: Platform.IOS,
+      projectArchive: {
+        type: ArchiveSourceType.URL,
+        url: 'http://localhost:3000',
+      },
+      projectRootDirectory: '.',
+      initiatingUserId: randomUUID(),
+      appId: randomUUID(),
+    };
+
+    const { value, error } = Ios.JobSchema.validate(job, joiOptions);
+    expect(value.refreshAdHocProvisioningProfile).toBeUndefined();
+    expect(error).toBeFalsy();
+  });
 });
@@ -181,12 +181,6 @@ export const CacheSchema = Joi.object({
  paths: Joi.array().items(Joi.string()).default([]),
 });

-export interface BuildPhaseStats {
-  buildPhase: BuildPhase;
-  result: BuildPhaseResult;
-  durationMs: number;
-}
-
 const GitHubContextZ = z.object({
  triggering_actor: z.string().optional(),
  event_name: z.enum(['push', 'pull_request', 'workflow_dispatch', 'schedule']),
@@ -5,7 +5,6 @@ export {
  ArchiveSource,
  ArchiveSourceSchemaZ,
  BuildMode,
-  BuildPhaseStats,
  BuildTrigger,
  EasCliNpmTags,
  Env,
@@ -144,6 +144,8 @@ export interface Job {
  appId: string;

  environment?: string;
+
+  refreshAdHocProvisioningProfile?: boolean;
 }

 const SecretsSchema = Joi.object({
@@ -229,6 +231,8 @@ export const JobSchema = Joi.object({

  environment: Joi.string(),

+  refreshAdHocProvisioningProfile: Joi.boolean(),
+
  workflowInterpolationContext: Joi.object().custom(workflowInterpolationContext =>
    StaticWorkflowInterpolationContextZ.optional().parse(workflowInterpolationContext)
  ),
@@ -27,6 +27,7 @@ export enum BuildPhase {
   */
  UPLOAD_ARTIFACTS = 'UPLOAD_ARTIFACTS',
  UPLOAD_APPLICATION_ARCHIVE = 'UPLOAD_APPLICATION_ARCHIVE',
+  UPLOAD_EMBEDDED_BUNDLE = 'UPLOAD_EMBEDDED_BUNDLE',
  UPLOAD_BUILD_ARTIFACTS = 'UPLOAD_BUILD_ARTIFACTS',
  PREPARE_ARTIFACTS = 'PREPARE_ARTIFACTS',
  CLEAN_UP_CREDENTIALS = 'CLEAN_UP_CREDENTIALS',
@@ -91,6 +92,7 @@ export const buildPhaseDisplayName: Record<BuildPhase, string> = {
  [BuildPhase.CACHE_STATS]: 'Cache stats',
  [BuildPhase.UPLOAD_ARTIFACTS]: 'Upload artifacts',
  [BuildPhase.UPLOAD_APPLICATION_ARCHIVE]: 'Upload application archive',
+  [BuildPhase.UPLOAD_EMBEDDED_BUNDLE]: 'Upload embedded bundle',
  [BuildPhase.UPLOAD_BUILD_ARTIFACTS]: 'Upload build artifacts',
  [BuildPhase.PREPARE_ARTIFACTS]: 'Prepare artifacts',
  [BuildPhase.CLEAN_UP_CREDENTIALS]: 'Clean up credentials',
@@ -157,6 +159,7 @@ export const buildPhaseWebsiteId: Record<BuildPhase, string> = {
  [BuildPhase.CACHE_STATS]: 'cache-stats',
  [BuildPhase.UPLOAD_ARTIFACTS]: 'upload-artifacts',
  [BuildPhase.UPLOAD_APPLICATION_ARCHIVE]: 'upload-application-archive',
+  [BuildPhase.UPLOAD_EMBEDDED_BUNDLE]: 'upload-embedded-bundle',
  [BuildPhase.UPLOAD_BUILD_ARTIFACTS]: 'upload-build-artifacts',
  [BuildPhase.PREPARE_ARTIFACTS]: 'prepare-artifacts',
  [BuildPhase.CLEAN_UP_CREDENTIALS]: 'clean-up-credentials',
@@ -1,6 +1,6 @@
 {
  "name": "eas-cli",
-  "version": "19.0.7",
+  "version": "20.1.0",
  "description": "EAS command line tool",
  "keywords": [
    "cli",
@@ -47,11 +47,11 @@
    "@expo/code-signing-certificates": "0.0.5",
    "@expo/config": "55.0.10",
    "@expo/config-plugins": "55.0.7",
-    "@expo/eas-build-job": "19.0.0",
-    "@expo/eas-json": "19.0.0",
+    "@expo/eas-build-job": "20.1.0",
+    "@expo/eas-json": "20.1.0",
    "@expo/env": "^1.0.0",
    "@expo/json-file": "8.3.3",
-    "@expo/logger": "19.0.0",
+    "@expo/logger": "20.0.0",
    "@expo/multipart-body-parser": "2.0.0",
    "@expo/osascript": "2.1.4",
    "@expo/package-manager": "1.9.10",
@@ -63,7 +63,7 @@
    "@expo/results": "1.0.0",
    "@expo/rudder-sdk-node": "1.1.1",
    "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "19.0.0",
+    "@expo/steps": "20.1.0",
    "@expo/timeago.js": "1.0.0",
    "@oclif/core": "^4.8.3",
    "@oclif/plugin-autocomplete": "^3.2.40",
@@ -0,0 +1,197 @@
+import { getConfigFilePaths } from '@expo/config';
+
+import { getWorkflowRunUrl } from '../../build/utils/url';
+import Go 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 { getPrivateExpoConfigAsync } from '../../project/expoConfig';
+import { uploadAccountScopedFileAsync } from '../../project/uploadAccountScopedFileAsync';
+import { uploadAccountScopedProjectSourceAsync } from '../../project/uploadAccountScopedProjectSourceAsync';
+import { ensureActorHasPrimaryAccount } from '../../user/actions';
+import { detectProjectSdkVersionAsync } from '../../commands/go';
+import { mockTestCommand } from './utils';
+
+jest.mock('@expo/config', () => ({
+  ...jest.requireActual('@expo/config'),
+  getConfigFilePaths: jest.fn(),
+}));
+jest.mock('../../project/expoConfig');
+jest.mock('../../log', () => ({
+  __esModule: true,
+  default: {
+    log: jest.fn(),
+    withTick: jest.fn(),
+    newLine: jest.fn(),
+    succeed: jest.fn(),
+    debug: jest.fn(),
+    markFreshLine: jest.fn(),
+    error: jest.fn(),
+  },
+  learnMore: jest.fn().mockReturnValue(''),
+}));
+jest.mock('../../ora', () => ({
+  ora: jest.fn().mockReturnValue({
+    start: jest.fn().mockReturnThis(),
+    stop: jest.fn().mockReturnThis(),
+    fail: jest.fn().mockReturnThis(),
+    succeed: jest.fn().mockReturnThis(),
+  }),
+}));
+jest.mock('fs-extra', () => ({
+  ensureDir: jest.fn().mockResolvedValue(undefined),
+  writeFile: jest.fn().mockResolvedValue(undefined),
+  remove: jest.fn().mockResolvedValue(undefined),
+}));
+jest.mock('../../user/actions');
+jest.mock('../../graphql/queries/WorkflowRunQuery');
+jest.mock('../../graphql/mutations/WorkflowRunMutation');
+jest.mock('../../project/uploadAccountScopedFileAsync');
+jest.mock('../../project/uploadAccountScopedProjectSourceAsync');
+jest.mock('../../build/utils/url');
+jest.mock('../../prompts');
+
+const mockGetConfigFilePaths = jest.mocked(getConfigFilePaths);
+const mockGetPrivateExpoConfigAsync = jest.mocked(getPrivateExpoConfigAsync);
+
+describe('detectProjectSdkVersionAsync', () => {
+  it('returns undefined when no config file exists', async () => {
+    mockGetConfigFilePaths.mockReturnValue({ staticConfigPath: null, dynamicConfigPath: null });
+    await expect(detectProjectSdkVersionAsync('/project')).resolves.toBeUndefined();
+  });
+
+  it('returns the sdkVersion from the project config', async () => {
+    mockGetConfigFilePaths.mockReturnValue({
+      staticConfigPath: '/project/app.json',
+      dynamicConfigPath: null,
+    });
+    mockGetPrivateExpoConfigAsync.mockResolvedValue({ sdkVersion: '55.0.0' } as any);
+    await expect(detectProjectSdkVersionAsync('/project')).resolves.toBe('55.0.0');
+  });
+
+  it('returns undefined when reading the config throws', async () => {
+    mockGetConfigFilePaths.mockReturnValue({
+      staticConfigPath: '/project/app.json',
+      dynamicConfigPath: null,
+    });
+    mockGetPrivateExpoConfigAsync.mockRejectedValue(new Error('config error'));
+    await expect(detectProjectSdkVersionAsync('/project')).resolves.toBeUndefined();
+  });
+});
+
+const mockAccount = { id: 'account-id', name: 'testuser' };
+const mockActor = {
+  __typename: 'User' as const,
+  id: 'user-id',
+  username: 'testuser',
+  primaryAccount: mockAccount,
+};
+
+describe('Go command', () => {
+  beforeEach(() => {
+    jest.mocked(ensureActorHasPrimaryAccount).mockReturnValue(mockAccount as any);
+    jest.mocked(WorkflowRunQuery.expoGoRepackConfigurationAsync).mockResolvedValue({
+      files: [],
+      sdkVersion: '55.0.0',
+    } as any);
+    jest.mocked(WorkflowRunMutation.createExpoGoRepackWorkflowRunAsync).mockResolvedValue({
+      id: 'run-id',
+    } as any);
+    jest.mocked(uploadAccountScopedProjectSourceAsync).mockResolvedValue({
+      projectArchiveBucketKey: 'archive-key',
+    });
+    jest
+      .mocked(uploadAccountScopedFileAsync)
+      .mockResolvedValue({ fileBucketKey: 'file-key' } as any);
+    jest.mocked(getWorkflowRunUrl).mockReturnValue('https://expo.dev/run/123');
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  function makeCmd(argv: string[] = []) {
+    const ctx = {
+      loggedIn: { actor: mockActor as any, graphqlClient: {} as any },
+      analytics: {} as any,
+    };
+    const cmd = mockTestCommand(Go, ['--bundle-id', 'com.test.go', ...argv], ctx);
+    jest.spyOn(cmd as any, 'ensureEasProjectAsync').mockResolvedValue('project-id');
+    jest.spyOn(cmd as any, 'setupCredentialsAsync').mockResolvedValue({ id: 'asc-app-id' });
+    jest.spyOn(cmd as any, 'monitorWorkflowJobsAsync').mockResolvedValue(WorkflowRunStatus.Success);
+    return cmd;
+  }
+
+  it('logs auto-selected SDK message and reports resolved version after dispatch', async () => {
+    mockGetConfigFilePaths.mockReturnValue({
+      staticConfigPath: '/app.json',
+      dynamicConfigPath: null,
+    });
+    mockGetPrivateExpoConfigAsync.mockResolvedValue({ sdkVersion: '55.0.0' } as any);
+
+    await makeCmd().run();
+
+    expect(Log.log).toHaveBeenCalledWith(expect.stringContaining('SDK 55'));
+    expect(Log.withTick).toHaveBeenCalledWith(expect.stringContaining('Using Expo Go SDK'));
+  });
+
+  it('skips auto-select log when --sdk-version flag is provided', async () => {
+    mockGetConfigFilePaths.mockReturnValue({
+      staticConfigPath: '/app.json',
+      dynamicConfigPath: null,
+    });
+    mockGetPrivateExpoConfigAsync.mockResolvedValue({ sdkVersion: '55.0.0' } as any);
+
+    await makeCmd(['--sdk-version', '55.0.0']).run();
+
+    expect(Log.log).not.toHaveBeenCalledWith(expect.stringContaining('Auto-selected'));
+  });
+
+  it('prompts for SDK version when no project config is found', async () => {
+    mockGetConfigFilePaths.mockReturnValue({ staticConfigPath: null, dynamicConfigPath: null });
+    jest.mocked(WorkflowRunQuery.expoGoSupportedSdkVersionsAsync).mockResolvedValue([
+      { sdkVersion: '54.0.0', isLatest: false, isBeta: false, isDeprecated: false },
+      { sdkVersion: '55.0.0', isLatest: true, isBeta: false, isDeprecated: false },
+      { sdkVersion: '56.0.0', isLatest: false, isBeta: true, isDeprecated: false },
+    ]);
+    jest.mocked(selectAsync).mockResolvedValue('55.0.0');
+
+    await makeCmd().run();
+
+    expect(selectAsync).toHaveBeenCalledWith(
+      'Select an Expo SDK version',
+      expect.arrayContaining([
+        expect.objectContaining({ title: 'SDK 54', value: '54.0.0' }),
+        expect.objectContaining({ title: 'SDK 55 (latest)', value: '55.0.0' }),
+        expect.objectContaining({ title: 'SDK 56 (beta)', value: '56.0.0' }),
+      ]),
+      expect.objectContaining({ initial: '55.0.0' })
+    );
+  });
+
+  it('skips prompt when all versions are deprecated', async () => {
+    mockGetConfigFilePaths.mockReturnValue({ staticConfigPath: null, dynamicConfigPath: null });
+    jest
+      .mocked(WorkflowRunQuery.expoGoSupportedSdkVersionsAsync)
+      .mockResolvedValue([
+        { sdkVersion: '54.0.0', isLatest: false, isBeta: false, isDeprecated: true },
+      ]);
+
+    await makeCmd().run();
+
+    expect(selectAsync).not.toHaveBeenCalled();
+  });
+
+  it('falls back gracefully when supportedSdkVersions fetch fails', async () => {
+    mockGetConfigFilePaths.mockReturnValue({ staticConfigPath: null, dynamicConfigPath: null });
+    jest
+      .mocked(WorkflowRunQuery.expoGoSupportedSdkVersionsAsync)
+      .mockRejectedValue(new Error('network error'));
+
+    await makeCmd().run();
+
+    expect(selectAsync).not.toHaveBeenCalled();
+  });
+});
@@ -42,6 +42,7 @@ export async function createBuildContextAsync<T extends Platform>({
  customBuildConfigMetadata,
  buildLoggerLevel,
  freezeCredentials,
+  refreshAdHocProvisioningProfile: refreshAdHocProvisioningProfileFlag,
  isVerboseLoggingEnabled,
  whatToTest,
  env,
@@ -65,6 +66,7 @@ export async function createBuildContextAsync<T extends Platform>({
  customBuildConfigMetadata?: CustomBuildConfigMetadata;
  buildLoggerLevel?: LoggerLevel;
  freezeCredentials: boolean;
+  refreshAdHocProvisioningProfile?: boolean;
  isVerboseLoggingEnabled: boolean;
  whatToTest?: string;
  env: Record<string, string>;
@@ -90,6 +92,8 @@ export async function createBuildContextAsync<T extends Platform>({

  const requiredPackageManager = resolvePackageManager(projectDir);

+  const refreshAdHocProvisioningProfile = refreshAdHocProvisioningProfileFlag ?? false;
+
  const credentialsCtx = new CredentialsContext({
    projectInfo: { exp, projectId },
    nonInteractive,
@@ -101,6 +105,7 @@ export async function createBuildContextAsync<T extends Platform>({
    easJsonCliConfig,
    vcsClient,
    freezeCredentials,
+    refreshAdHocProvisioningProfile,
  });

  const devClientProperties = getDevClientEventProperties({
@@ -0,0 +1,40 @@
+import { Platform } from '@expo/eas-build-job';
+import { CredentialsSource } from '@expo/eas-json';
+
+import { BuildContext } from '../../context';
+import { ensureIosCredentialsAsync } from '../credentials';
+
+describe(ensureIosCredentialsAsync, () => {
+  it('errors when refresh is enabled with local credentials source', async () => {
+    const buildCtx = {
+      buildProfile: {
+        credentialsSource: CredentialsSource.LOCAL,
+        simulator: false,
+        withoutCredentials: false,
+      },
+      credentialsCtx: {
+        refreshAdHocProvisioningProfile: true,
+      },
+    } as BuildContext<Platform.IOS>;
+
+    await expect(ensureIosCredentialsAsync(buildCtx, [])).rejects.toThrow(
+      '--refresh-ad-hoc-provisioning-profile cannot be used with credentialsSource "local". Use remote credentials or omit the flag.'
+    );
+  });
+
+  it('does not reject refresh when credentials source is remote', async () => {
+    const buildCtx = {
+      buildProfile: {
+        credentialsSource: CredentialsSource.REMOTE,
+        simulator: true,
+        withoutCredentials: false,
+        distribution: 'internal',
+      },
+      credentialsCtx: {
+        refreshAdHocProvisioningProfile: true,
+      },
+    } as BuildContext<Platform.IOS>;
+
+    await expect(ensureIosCredentialsAsync(buildCtx, [])).resolves.toBeUndefined();
+  });
+});
@@ -17,6 +17,16 @@ export async function ensureIosCredentialsAsync(
    return;
  }

+  const { credentialsSource } = buildCtx.buildProfile;
+  if (
+    buildCtx.credentialsCtx.refreshAdHocProvisioningProfile &&
+    credentialsSource === 'local'
+  ) {
+    throw new Error(
+      '--refresh-ad-hoc-provisioning-profile cannot be used with credentialsSource "local". Use remote credentials or omit the flag.'
+    );
+  }
+
  const provider = new IosCredentialsProvider(buildCtx.credentialsCtx, {
    app: await getAppFromContextAsync(buildCtx.credentialsCtx),
    targets,
@@ -24,8 +34,6 @@ export async function ensureIosCredentialsAsync(
    enterpriseProvisioning: buildCtx.buildProfile.enterpriseProvisioning,
  });

-  const { credentialsSource } = buildCtx.buildProfile;
-
  logCredentialsSource(credentialsSource, Platform.IOS);
  return {
    credentials: await provider.getCredentialsAsync(credentialsSource),
@@ -112,6 +112,9 @@ export async function prepareJobAsync(
    // See: https://github.com/expo/eas-build/pull/454
    appId: ctx.projectId,
    initiatingUserId: ctx.user.id,
+    ...(ctx.credentialsCtx.refreshAdHocProvisioningProfile && {
+      refreshAdHocProvisioningProfile: true,
+    }),
  };
  return sanitizeBuildJob(job) as Ios.Job;
 }
@@ -103,6 +103,7 @@ export interface BuildFlags {
  message?: string;
  buildLoggerLevel?: LoggerLevel;
  freezeCredentials: boolean;
+  refreshAdHocProvisioningProfile?: boolean;
  isVerboseLoggingEnabled?: boolean;
  whatToTest?: string;
  simulator?: SimulatorRunTarget;
@@ -413,6 +414,7 @@ async function prepareAndStartBuildAsync({
    customBuildConfigMetadata,
    buildLoggerLevel: flags.buildLoggerLevel ?? (Log.isDebug ? LoggerLevel.DEBUG : undefined),
    freezeCredentials: flags.freezeCredentials,
+    refreshAdHocProvisioningProfile: flags.refreshAdHocProvisioningProfile,
    isVerboseLoggingEnabled: flags.isVerboseLoggingEnabled ?? false,
    whatToTest: flags.whatToTest,
    env,
@@ -35,4 +35,5 @@ export interface BuildFlags {
  message?: string;
  buildLoggerLevel?: LoggerLevel;
  freezeCredentials: boolean;
+  refreshAdHocProvisioningProfile?: boolean;
 }
@@ -40,6 +40,7 @@ interface RawBuildFlags {
  message?: string;
  'build-logger-level'?: LoggerLevel;
  'freeze-credentials': boolean;
+  'refresh-ad-hoc-provisioning-profile': boolean;
  'verbose-logs'?: boolean;
  'what-to-test'?: string;
 }
@@ -121,6 +122,11 @@ export default class Build extends EasCommand {
      default: false,
      description: 'Prevent the build from updating credentials in non-interactive mode',
    }),
+    'refresh-ad-hoc-provisioning-profile': Flags.boolean({
+      default: false,
+      description:
+        'Refresh managed ad-hoc provisioning profiles from App Store Connect before gathering build credentials',
+    }),
    'verbose-logs': Flags.boolean({
      default: false,
      description: 'Use verbose logs for the build process',
@@ -188,6 +194,20 @@ export default class Build extends EasCommand {
    flags: RawBuildFlags
  ): Omit<BuildFlags, 'requestedPlatform'> & { requestedPlatform?: RequestedPlatform } {
    const { json, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+    if (flags['refresh-ad-hoc-provisioning-profile']) {
+      if (!nonInteractive) {
+        Errors.error(
+          '--refresh-ad-hoc-provisioning-profile can only be used in non-interactive mode.',
+          { exit: 1 }
+        );
+      }
+      if (flags['freeze-credentials']) {
+        Errors.error(
+          'Cannot use --refresh-ad-hoc-provisioning-profile with --freeze-credentials.',
+          { exit: 1 }
+        );
+      }
+    }
    if (!flags.local && flags.output) {
      Errors.error('--output is allowed only for local builds', { exit: 1 });
    }
@@ -249,6 +269,7 @@ export default class Build extends EasCommand {
      message,
      buildLoggerLevel: flags['build-logger-level'],
      freezeCredentials: flags['freeze-credentials'],
+      refreshAdHocProvisioningProfile: flags['refresh-ad-hoc-provisioning-profile'],
      isVerboseLoggingEnabled: flags['verbose-logs'],
      whatToTest: flags['what-to-test'],
    };
@@ -40,6 +40,11 @@ export default class BuildInternal extends EasCommand {
      helpValue: 'PROFILE_NAME',
      exclusive: ['auto-submit'],
    }),
+    'refresh-ad-hoc-provisioning-profile': Flags.boolean({
+      default: false,
+      description:
+        'Refresh managed ad-hoc provisioning profiles from App Store Connect before gathering build credentials',
+    }),
  };

  static override contextDefinition = {
@@ -85,6 +90,7 @@ export default class BuildInternal extends EasCommand {
        profile: flags.profile,
        nonInteractive: true,
        freezeCredentials: false,
+        refreshAdHocProvisioningProfile: flags['refresh-ad-hoc-provisioning-profile'],
        wait: false,
        clearCache: false,
        json: true,
@@ -1,4 +1,4 @@
-import { ExpoConfig } from '@expo/config';
+import { ExpoConfig, getConfigFilePaths } from '@expo/config';
 import { App, User, UserRole } from '@expo/apple-utils';
 import { Flags } from '@oclif/core';
 import chalk from 'chalk';
@@ -26,8 +26,9 @@ import { AppMutation } from '../graphql/mutations/AppMutation';
 import { WorkflowRunMutation } from '../graphql/mutations/WorkflowRunMutation';
 import { WorkflowRunQuery } from '../graphql/queries/WorkflowRunQuery';
 import Log, { learnMore } from '../log';
-import { confirmAsync } from '../prompts';
+import { confirmAsync, selectAsync } from '../prompts';
 import { ora } from '../ora';
+import { getPrivateExpoConfigAsync } from '../project/expoConfig';
 import { findProjectIdByAccountNameAndSlugNullableAsync } from '../project/fetchOrCreateProjectIDForWriteToConfigWithConfirmationAsync';
 import { uploadAccountScopedFileAsync } from '../project/uploadAccountScopedFileAsync';
 import { uploadAccountScopedProjectSourceAsync } from '../project/uploadAccountScopedProjectSourceAsync';
@@ -45,6 +46,20 @@ 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;
+  }
+}
+
 const TESTFLIGHT_GROUP_NAME = 'Team (Expo)';

 async function setupTestFlightAsync(ascApp: App): Promise<void> {
@@ -189,7 +204,16 @@ export default class Go extends EasCommand {
    });
    Log.withTick(`Logged in as ${chalk.cyan(getActorDisplayName(actor))}`);

-    const sdkVersion = flags['sdk-version'];
+    const detectedSdkVersion = await detectProjectSdkVersionAsync(process.cwd());
+    if (detectedSdkVersion && !flags['sdk-version']) {
+      Log.log(
+        `Current project using SDK ${detectedSdkVersion.split('.')[0]}. Auto-selected same version. To use a different version, pass --sdk-version.`
+      );
+    }
+    let sdkVersion = flags['sdk-version'] ?? detectedSdkVersion;
+    if (!sdkVersion) {
+      ({ sdkVersion } = await this.selectSdkVersionAsync(graphqlClient));
+    }
    const bundleId = flags['bundle-id'] ?? this.generateBundleId(actor);
    if (!isBundleIdentifierValid(bundleId)) {
      throw new Error(
@@ -231,7 +255,11 @@ export default class Go extends EasCommand {
        }
      );

-      const { workflowUrl, workflowRunId } = await this.dispatchWorkflowAsync(
+      const {
+        workflowUrl,
+        workflowRunId,
+        sdkVersion: resolvedSdkVersion,
+      } = await this.dispatchWorkflowAsync(
        graphqlClient,
        projectId,
        actor,
@@ -242,6 +270,7 @@ export default class Go extends EasCommand {
        tmpDir,
        vcsClient
      );
+      Log.withTick(`Using Expo Go SDK ${chalk.cyan(resolvedSdkVersion.split('.')[0])}`);
      Log.withTick(`Build started: ${chalk.cyan(workflowUrl)}`);

      const status = await this.monitorWorkflowJobsAsync(graphqlClient, workflowRunId);
@@ -275,6 +304,37 @@ export default class Go extends EasCommand {
    }
  }

+  private async selectSdkVersionAsync(
+    graphqlClient: ExpoGraphqlClient
+  ): Promise<{ sdkVersion: string | undefined }> {
+    let versions;
+    try {
+      versions = await WorkflowRunQuery.expoGoSupportedSdkVersionsAsync(graphqlClient);
+    } catch {
+      return { sdkVersion: undefined };
+    }
+    const selectable = versions.filter(v => !v.isDeprecated);
+    if (selectable.length === 0) {
+      return { sdkVersion: undefined };
+    }
+    const defaultVersion = selectable.find(v => v.isLatest) ?? selectable.at(-1);
+    return {
+      sdkVersion: await selectAsync(
+        'Select an Expo SDK version',
+        selectable.map(v => {
+          const major = v.sdkVersion.split('.')[0];
+          const title = v.isLatest
+            ? `SDK ${major} (latest)`
+            : v.isBeta
+              ? `SDK ${major} (beta)`
+              : `SDK ${major}`;
+          return { title, value: v.sdkVersion };
+        }),
+        { initial: defaultVersion?.sdkVersion }
+      ),
+    };
+  }
+
  private generateBundleId(actor: Actor): string {
    const username = ensureActorHasPrimaryAccount(actor).name;
    const sanitizedUsername = username
@@ -401,7 +461,7 @@ export default class Go extends EasCommand {
    sdkVersion: string | undefined,
    tmpDir: string,
    vcsClient: Client
-  ): Promise<{ workflowUrl: string; workflowRunId: string }> {
+  ): Promise<{ workflowUrl: string; workflowRunId: string; sdkVersion: string }> {
    const account = ensureActorHasPrimaryAccount(actor);

    const repackConfig = await WorkflowRunQuery.expoGoRepackConfigurationAsync(graphqlClient, {
@@ -451,7 +511,7 @@ export default class Go extends EasCommand {

    const workflowUrl = getWorkflowRunUrl(account.name, deriveBundleIdSlug(bundleId), result.id);

-    return { workflowUrl, workflowRunId: result.id };
+    return { workflowUrl, workflowRunId: result.id, sdkVersion: repackConfig.sdkVersion };
  }

  private async monitorWorkflowJobsAsync(
@@ -1,31 +1,51 @@
 import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
 import { getMockOclifConfig } from '../../../__tests__/commands/utils';
+import { AppObservePlatform } from '../../../graphql/generated';
+import { ObserveQuery } from '../../../graphql/queries/ObserveQuery';
+import { fetchObserveCustomEventsAsync } from '../../../observe/fetchCustomEvents';
 import {
-  AppObserveEventsOrderByDirection,
-  AppObserveEventsOrderByField,
-  AppObservePlatform,
-} from '../../../graphql/generated';
-import { fetchObserveEventsAsync, resolveOrderBy } from '../../../observe/fetchEvents';
-import { buildObserveEventsJson } from '../../../observe/formatEvents';
+  buildObserveCustomEventNamesJson,
+  buildObserveCustomEventsEmptyWithSuggestionsJson,
+  buildObserveCustomEventsEmptyWithSuggestionsTable,
+  buildObserveCustomEventsJson,
+} from '../../../observe/formatCustomEvents';
 import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
 import ObserveEvents from '../events';

-jest.mock('../../../observe/fetchEvents', () => {
-  const actual = jest.requireActual('../../../observe/fetchEvents');
-  return {
-    ...actual,
-    fetchObserveEventsAsync: jest.fn(),
-  };
-});
-jest.mock('../../../observe/formatEvents', () => ({
-  buildObserveEventsTable: jest.fn().mockReturnValue('table'),
-  buildObserveEventsJson: jest.fn().mockReturnValue({}),
+jest.mock('../../../observe/fetchCustomEvents');
+jest.mock('../../../observe/formatCustomEvents', () => ({
+  buildObserveCustomEventsTable: jest.fn().mockReturnValue('table'),
+  buildObserveCustomEventsJson: jest.fn().mockReturnValue({}),
+  buildObserveCustomEventNamesTable: jest.fn().mockReturnValue('names-table'),
+  buildObserveCustomEventNamesJson: jest.fn().mockReturnValue({ names: [], isTruncated: false }),
+  buildObserveCustomEventsEmptyWithSuggestionsTable: jest
+    .fn()
+    .mockReturnValue('empty-with-suggestions-table'),
+  buildObserveCustomEventsEmptyWithSuggestionsJson: jest.fn().mockReturnValue({
+    filteredEventName: 'my_event',
+    events: [],
+    availableEventNames: [],
+    availableEventNamesIsTruncated: false,
+  }),
+}));
+jest.mock('../../../graphql/queries/ObserveQuery', () => ({
+  ObserveQuery: {
+    customEventNamesAsync: jest.fn(),
+  },
 }));
 jest.mock('../../../log');
 jest.mock('../../../utils/json');

-const mockFetchObserveEventsAsync = jest.mocked(fetchObserveEventsAsync);
-const mockBuildObserveEventsJson = jest.mocked(buildObserveEventsJson);
+const mockFetchObserveCustomEventsAsync = jest.mocked(fetchObserveCustomEventsAsync);
+const mockBuildObserveCustomEventsJson = jest.mocked(buildObserveCustomEventsJson);
+const mockBuildObserveCustomEventNamesJson = jest.mocked(buildObserveCustomEventNamesJson);
+const mockBuildObserveCustomEventsEmptyWithSuggestionsTable = jest.mocked(
+  buildObserveCustomEventsEmptyWithSuggestionsTable
+);
+const mockBuildObserveCustomEventsEmptyWithSuggestionsJson = jest.mocked(
+  buildObserveCustomEventsEmptyWithSuggestionsJson
+);
+const mockCustomEventNamesAsync = jest.mocked(ObserveQuery.customEventNamesAsync);
 const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
 const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);

@@ -36,10 +56,11 @@ describe(ObserveEvents, () => {

  beforeEach(() => {
    jest.clearAllMocks();
-    mockFetchObserveEventsAsync.mockResolvedValue({
+    mockFetchObserveCustomEventsAsync.mockResolvedValue({
      events: [],
      pageInfo: { hasNextPage: false, hasPreviousPage: false },
    });
+    mockCustomEventNamesAsync.mockResolvedValue({ names: [], isTruncated: false });
  });

  function createCommand(argv: string[]): ObserveEvents {
@@ -52,38 +73,80 @@ describe(ObserveEvents, () => {
    return command;
  }

-  it('uses --days to compute start/end time range', async () => {
+  it('passes eventName arg to fetchObserveCustomEventsAsync', async () => {
+    mockFetchObserveCustomEventsAsync.mockResolvedValue({
+      events: [{ id: 'evt-1' } as any],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
+    });
+    const command = createCommand(['my_event']);
+    await command.runAsync();
+
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
+    expect(options.eventName).toBe('my_event');
+    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
+  });
+
+  it('routes to customEventNamesAsync when no positional arg is provided', async () => {
+    const command = createCommand([]);
+    await command.runAsync();
+
+    expect(mockCustomEventNamesAsync).toHaveBeenCalledTimes(1);
+    expect(mockFetchObserveCustomEventsAsync).not.toHaveBeenCalled();
+  });
+
+  it('routes to fetchObserveCustomEventsAsync when --all-events is set with no positional arg', async () => {
+    const command = createCommand(['--all-events']);
+    await command.runAsync();
+
+    expect(mockFetchObserveCustomEventsAsync).toHaveBeenCalledTimes(1);
+    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
+    expect(options.eventName).toBeUndefined();
+  });
+
+  it('throws when both an event name argument and --all-events are provided', async () => {
+    const command = createCommand(['my_event', '--all-events']);
+    await expect(command.runAsync()).rejects.toThrow(
+      '--all-events cannot be combined with an event name argument'
+    );
+    expect(mockFetchObserveCustomEventsAsync).not.toHaveBeenCalled();
+    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
+  });
+
+  it('passes the resolved time range and platform to customEventNamesAsync', async () => {
    const now = new Date('2025-06-15T12:00:00.000Z');
    jest.useFakeTimers({ now });

-    const command = createCommand(['tti', '--days', '7']);
+    const command = createCommand(['--days', '7', '--platform', 'ios']);
    await command.runAsync();

-    expect(mockFetchObserveEventsAsync).toHaveBeenCalledTimes(1);
-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(mockCustomEventNamesAsync).toHaveBeenCalledWith(graphqlClient, {
+      appId: projectId,
+      startTime: '2025-06-08T12:00:00.000Z',
+      endTime: '2025-06-15T12:00:00.000Z',
+      platform: AppObservePlatform.Ios,
+    });
+
+    jest.useRealTimers();
+  });
+
+  it('uses --days to compute start/end time range when an event name is provided', async () => {
+    const now = new Date('2025-06-15T12:00:00.000Z');
+    jest.useFakeTimers({ now });
+
+    const command = createCommand(['my_event', '--days', '7']);
+    await command.runAsync();
+
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');
    expect(options.startTime).toBe('2025-06-08T12:00:00.000Z');

    jest.useRealTimers();
  });

-  it('uses DEFAULT_DAYS_BACK (60 days) when neither --days nor --start/--end are provided', async () => {
-    const now = new Date('2025-06-15T12:00:00.000Z');
-    jest.useFakeTimers({ now });
-
-    const command = createCommand(['tti']);
-    await command.runAsync();
-
-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
-    expect(options.startTime).toBe('2025-04-16T12:00:00.000Z');
-    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');
-
-    jest.useRealTimers();
-  });
-
  it('uses explicit --start and --end when provided', async () => {
    const command = createCommand([
-      'tti',
+      'my_event',
      '--start',
      '2025-01-01T00:00:00.000Z',
      '--end',
@@ -91,109 +154,86 @@ describe(ObserveEvents, () => {
    ]);
    await command.runAsync();

-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
    expect(options.startTime).toBe('2025-01-01T00:00:00.000Z');
    expect(options.endTime).toBe('2025-02-01T00:00:00.000Z');
  });

-  it('defaults endTime to now when only --start is provided', async () => {
-    const now = new Date('2025-06-15T12:00:00.000Z');
-    jest.useFakeTimers({ now });
-
-    const command = createCommand(['tti', '--start', '2025-01-01T00:00:00.000Z']);
-    await command.runAsync();
-
-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
-    expect(options.startTime).toBe('2025-01-01T00:00:00.000Z');
-    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');
-
-    jest.useRealTimers();
-  });
-
  it('rejects --days combined with --start', async () => {
-    const command = createCommand(['tti', '--days', '7', '--start', '2025-01-01T00:00:00.000Z']);
-
+    const command = createCommand([
+      'my_event',
+      '--days',
+      '7',
+      '--start',
+      '2025-01-01T00:00:00.000Z',
+    ]);
    await expect(command.runAsync()).rejects.toThrow();
  });

-  it('passes --limit to fetchObserveEventsAsync', async () => {
-    const command = createCommand(['tti', '--limit', '42']);
+  it('passes --limit to fetchObserveCustomEventsAsync', async () => {
+    const command = createCommand(['my_event', '--limit', '42']);
    await command.runAsync();

-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
    expect(options.limit).toBe(42);
  });

-  it('passes --after cursor to fetchObserveEventsAsync', async () => {
-    const command = createCommand(['tti', '--after', 'cursor-xyz']);
+  it('passes --after cursor', async () => {
+    const command = createCommand(['my_event', '--after', 'cursor-xyz']);
    await command.runAsync();

-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
    expect(options.after).toBe('cursor-xyz');
  });

-  it('does not pass after when --after flag is not provided', async () => {
-    const command = createCommand(['tti']);
+  it('passes --platform ios as AppObservePlatform.Ios', async () => {
+    const command = createCommand(['my_event', '--platform', 'ios']);
    await command.runAsync();

-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
-    expect(options).not.toHaveProperty('after');
-  });
-
-  it('rejects --days combined with --end', async () => {
-    const command = createCommand(['tti', '--days', '7', '--end', '2025-02-01T00:00:00.000Z']);
-
-    await expect(command.runAsync()).rejects.toThrow();
-  });
-
-  it('passes --platform ios to fetchObserveEventsAsync as AppObservePlatform.Ios', async () => {
-    const command = createCommand(['tti', '--platform', 'ios']);
-    await command.runAsync();
-
-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
    expect(options.platform).toBe(AppObservePlatform.Ios);
  });

-  it('passes --platform android to fetchObserveEventsAsync as AppObservePlatform.Android', async () => {
-    const command = createCommand(['tti', '--platform', 'android']);
+  it('passes --app-version', async () => {
+    const command = createCommand(['my_event', '--app-version', '2.1.0']);
    await command.runAsync();

-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
-    expect(options.platform).toBe(AppObservePlatform.Android);
-  });
-
-  it('passes --app-version to fetchObserveEventsAsync', async () => {
-    const command = createCommand(['tti', '--app-version', '2.1.0']);
-    await command.runAsync();
-
-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
    expect(options.appVersion).toBe('2.1.0');
  });

-  it('passes --update-id to fetchObserveEventsAsync', async () => {
-    const command = createCommand(['tti', '--update-id', 'update-xyz']);
+  it('passes --update-id', async () => {
+    const command = createCommand(['my_event', '--update-id', 'update-xyz']);
    await command.runAsync();

-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
    expect(options.updateId).toBe('update-xyz');
  });

-  it('does not pass platform, appVersion, or updateId when flags are not provided', async () => {
-    const command = createCommand(['tti']);
+  it('passes --session-id', async () => {
+    const command = createCommand(['my_event', '--session-id', 'session-xyz']);
    await command.runAsync();

-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
+    expect(options.sessionId).toBe('session-xyz');
+  });
+
+  it('does not pass platform, appVersion, updateId, or sessionId when flags are not provided', async () => {
+    const command = createCommand(['my_event']);
+    await command.runAsync();
+
+    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
    expect(options.platform).toBeUndefined();
    expect(options.appVersion).toBeUndefined();
    expect(options.updateId).toBeUndefined();
+    expect(options.sessionId).toBeUndefined();
  });

-  it('calls enableJsonOutput and printJsonOnlyOutput when --json is provided', async () => {
+  it('calls enableJsonOutput and printJsonOnlyOutput when --json is provided with an event name', async () => {
    const mockEvents = [
      {
        id: 'evt-1',
-        metricName: 'expo.app_startup.tti',
-        metricValue: 1.23,
+        eventName: 'my_event',
        timestamp: '2025-01-15T10:30:00.000Z',
        appVersion: '1.0.0',
        appBuildNumber: '42',
@@ -203,78 +243,139 @@ describe(ObserveEvents, () => {
        countryCode: 'US',
        sessionId: 'session-1',
        easClientId: 'client-1',
+        properties: [],
      },
    ];
-    mockFetchObserveEventsAsync.mockResolvedValue({
+    mockFetchObserveCustomEventsAsync.mockResolvedValue({
      events: mockEvents as any,
      pageInfo: { hasNextPage: false, hasPreviousPage: false },
    });

-    const command = createCommand(['tti', '--json', '--non-interactive']);
+    const command = createCommand(['my_event', '--json', '--non-interactive']);
    await command.runAsync();

    expect(mockEnableJsonOutput).toHaveBeenCalled();
-    expect(mockBuildObserveEventsJson).toHaveBeenCalledWith(
+    expect(mockBuildObserveCustomEventsJson).toHaveBeenCalledWith(
      mockEvents,
      expect.objectContaining({ hasNextPage: false })
    );
    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
  });

-  it('does not call enableJsonOutput when --json is not provided', async () => {
-    const command = createCommand(['tti']);
-    await command.runAsync();
-
-    expect(mockEnableJsonOutput).not.toHaveBeenCalled();
-    expect(mockPrintJsonOnlyOutput).not.toHaveBeenCalled();
-  });
-
-  it('passes --sort flag through to fetchObserveEventsAsync', async () => {
-    const command = createCommand(['tti', '--sort', 'slowest']);
-    await command.runAsync();
-
-    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
-    expect(options.orderBy).toEqual({
-      field: AppObserveEventsOrderByField.MetricValue,
-      direction: AppObserveEventsOrderByDirection.Desc,
+  it('falls back to fetching event names and renders the empty-with-suggestions table when filtered fetch returns 0 events', async () => {
+    mockFetchObserveCustomEventsAsync.mockResolvedValue({
+      events: [],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
+    });
+    const mockNames = [
+      { eventName: 'foo', count: 10 },
+      { eventName: 'bar', count: 5 },
+    ];
+    mockCustomEventNamesAsync.mockResolvedValue({
+      names: mockNames as any,
+      isTruncated: false,
    });
-  });

-  it('throws in non-interactive mode when no metric is provided', async () => {
-    const command = createCommand(['--non-interactive']);
+    const command = createCommand(['my_event']);
+    await command.runAsync();

-    await expect(command.runAsync()).rejects.toThrow(
-      'metric argument is required in non-interactive mode'
+    expect(mockFetchObserveCustomEventsAsync).toHaveBeenCalledTimes(1);
+    expect(mockCustomEventNamesAsync).toHaveBeenCalledTimes(1);
+    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsTable).toHaveBeenCalledWith(
+      'my_event',
+      mockNames,
+      expect.objectContaining({ isTruncated: false })
    );
  });
-});

-describe(resolveOrderBy, () => {
-  it('resolves lowercase "slowest" to MetricValue DESC', () => {
-    expect(resolveOrderBy('slowest')).toEqual({
-      field: AppObserveEventsOrderByField.MetricValue,
-      direction: AppObserveEventsOrderByDirection.Desc,
+  it('does not call customEventNamesAsync when filtered fetch returns at least one event', async () => {
+    mockFetchObserveCustomEventsAsync.mockResolvedValue({
+      events: [
+        {
+          id: 'evt-1',
+          eventName: 'my_event',
+          timestamp: '2025-01-15T10:30:00.000Z',
+          appVersion: '1.0.0',
+          appBuildNumber: '42',
+          deviceModel: 'iPhone 15',
+          deviceOs: 'iOS',
+          deviceOsVersion: '17.0',
+          easClientId: 'client-1',
+          properties: [],
+        } as any,
+      ],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
    });
+
+    const command = createCommand(['my_event']);
+    await command.runAsync();
+
+    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
+    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsTable).not.toHaveBeenCalled();
  });

-  it('resolves lowercase "fastest" to MetricValue ASC', () => {
-    expect(resolveOrderBy('fastest')).toEqual({
-      field: AppObserveEventsOrderByField.MetricValue,
-      direction: AppObserveEventsOrderByDirection.Asc,
+  it('emits empty-with-suggestions JSON when filtered fetch returns 0 events and --json is set', async () => {
+    mockFetchObserveCustomEventsAsync.mockResolvedValue({
+      events: [],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
    });
+    const mockNames = [{ eventName: 'foo', count: 10 }];
+    mockCustomEventNamesAsync.mockResolvedValue({
+      names: mockNames as any,
+      isTruncated: false,
+    });
+
+    const command = createCommand(['my_event', '--json', '--non-interactive']);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsJson).toHaveBeenCalledWith(
+      'my_event',
+      mockNames,
+      false
+    );
+    expect(mockBuildObserveCustomEventsJson).not.toHaveBeenCalled();
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
  });

-  it('resolves lowercase "newest" to Timestamp DESC', () => {
-    expect(resolveOrderBy('newest')).toEqual({
-      field: AppObserveEventsOrderByField.Timestamp,
-      direction: AppObserveEventsOrderByDirection.Desc,
-    });
+  it('does not run the empty-with-suggestions fallback when no event name is provided (event names mode)', async () => {
+    mockCustomEventNamesAsync.mockResolvedValue({ names: [], isTruncated: false });
+
+    const command = createCommand([]);
+    await command.runAsync();
+
+    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsTable).not.toHaveBeenCalled();
+    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsJson).not.toHaveBeenCalled();
  });

-  it('resolves lowercase "oldest" to Timestamp ASC', () => {
-    expect(resolveOrderBy('oldest')).toEqual({
-      field: AppObserveEventsOrderByField.Timestamp,
-      direction: AppObserveEventsOrderByDirection.Asc,
+  it('does not run the empty-with-suggestions fallback for --all-events with 0 results', async () => {
+    mockFetchObserveCustomEventsAsync.mockResolvedValue({
+      events: [],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
    });
+
+    const command = createCommand(['--all-events']);
+    await command.runAsync();
+
+    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
+    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsTable).not.toHaveBeenCalled();
+  });
+
+  it('emits JSON of event names + counts when --json is provided without an event name', async () => {
+    const mockNames = [
+      { eventName: 'foo', count: 10 },
+      { eventName: 'bar', count: 5 },
+    ];
+    mockCustomEventNamesAsync.mockResolvedValue({
+      names: mockNames as any,
+      isTruncated: false,
+    });
+
+    const command = createCommand(['--json', '--non-interactive']);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockBuildObserveCustomEventNamesJson).toHaveBeenCalledWith(mockNames, false);
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
  });
 });
@@ -1,381 +0,0 @@
-import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
-import { getMockOclifConfig } from '../../../__tests__/commands/utils';
-import { AppObservePlatform } from '../../../graphql/generated';
-import { ObserveQuery } from '../../../graphql/queries/ObserveQuery';
-import { fetchObserveCustomEventsAsync } from '../../../observe/fetchCustomEvents';
-import {
-  buildObserveCustomEventNamesJson,
-  buildObserveCustomEventsEmptyWithSuggestionsJson,
-  buildObserveCustomEventsEmptyWithSuggestionsTable,
-  buildObserveCustomEventsJson,
-} from '../../../observe/formatCustomEvents';
-import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
-import ObserveLogs from '../logs';
-
-jest.mock('../../../observe/fetchCustomEvents');
-jest.mock('../../../observe/formatCustomEvents', () => ({
-  buildObserveCustomEventsTable: jest.fn().mockReturnValue('table'),
-  buildObserveCustomEventsJson: jest.fn().mockReturnValue({}),
-  buildObserveCustomEventNamesTable: jest.fn().mockReturnValue('names-table'),
-  buildObserveCustomEventNamesJson: jest.fn().mockReturnValue({ names: [], isTruncated: false }),
-  buildObserveCustomEventsEmptyWithSuggestionsTable: jest
-    .fn()
-    .mockReturnValue('empty-with-suggestions-table'),
-  buildObserveCustomEventsEmptyWithSuggestionsJson: jest.fn().mockReturnValue({
-    filteredEventName: 'my_event',
-    events: [],
-    availableEventNames: [],
-    availableEventNamesIsTruncated: false,
-  }),
-}));
-jest.mock('../../../graphql/queries/ObserveQuery', () => ({
-  ObserveQuery: {
-    customEventNamesAsync: jest.fn(),
-  },
-}));
-jest.mock('../../../log');
-jest.mock('../../../utils/json');
-
-const mockFetchObserveCustomEventsAsync = jest.mocked(fetchObserveCustomEventsAsync);
-const mockBuildObserveCustomEventsJson = jest.mocked(buildObserveCustomEventsJson);
-const mockBuildObserveCustomEventNamesJson = jest.mocked(buildObserveCustomEventNamesJson);
-const mockBuildObserveCustomEventsEmptyWithSuggestionsTable = jest.mocked(
-  buildObserveCustomEventsEmptyWithSuggestionsTable
-);
-const mockBuildObserveCustomEventsEmptyWithSuggestionsJson = jest.mocked(
-  buildObserveCustomEventsEmptyWithSuggestionsJson
-);
-const mockCustomEventNamesAsync = jest.mocked(ObserveQuery.customEventNamesAsync);
-const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
-const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);
-
-describe(ObserveLogs, () => {
-  const graphqlClient = {} as any as ExpoGraphqlClient;
-  const mockConfig = getMockOclifConfig();
-  const projectId = 'test-project-id';
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    mockFetchObserveCustomEventsAsync.mockResolvedValue({
-      events: [],
-      pageInfo: { hasNextPage: false, hasPreviousPage: false },
-    });
-    mockCustomEventNamesAsync.mockResolvedValue({ names: [], isTruncated: false });
-  });
-
-  function createCommand(argv: string[]): ObserveLogs {
-    const command = new ObserveLogs(argv, mockConfig);
-    // @ts-expect-error
-    jest.spyOn(command, 'getContextAsync').mockReturnValue({
-      projectId,
-      loggedIn: { graphqlClient },
-    });
-    return command;
-  }
-
-  it('passes eventName arg to fetchObserveCustomEventsAsync', async () => {
-    mockFetchObserveCustomEventsAsync.mockResolvedValue({
-      events: [{ id: 'evt-1' } as any],
-      pageInfo: { hasNextPage: false, hasPreviousPage: false },
-    });
-    const command = createCommand(['my_event']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.eventName).toBe('my_event');
-    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
-  });
-
-  it('routes to customEventNamesAsync when no positional arg is provided', async () => {
-    const command = createCommand([]);
-    await command.runAsync();
-
-    expect(mockCustomEventNamesAsync).toHaveBeenCalledTimes(1);
-    expect(mockFetchObserveCustomEventsAsync).not.toHaveBeenCalled();
-  });
-
-  it('routes to fetchObserveCustomEventsAsync when --all-events is set with no positional arg', async () => {
-    const command = createCommand(['--all-events']);
-    await command.runAsync();
-
-    expect(mockFetchObserveCustomEventsAsync).toHaveBeenCalledTimes(1);
-    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.eventName).toBeUndefined();
-  });
-
-  it('throws when both an event name argument and --all-events are provided', async () => {
-    const command = createCommand(['my_event', '--all-events']);
-    await expect(command.runAsync()).rejects.toThrow(
-      '--all-events cannot be combined with an event name argument'
-    );
-    expect(mockFetchObserveCustomEventsAsync).not.toHaveBeenCalled();
-    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
-  });
-
-  it('passes the resolved time range and platform to customEventNamesAsync', async () => {
-    const now = new Date('2025-06-15T12:00:00.000Z');
-    jest.useFakeTimers({ now });
-
-    const command = createCommand(['--days', '7', '--platform', 'ios']);
-    await command.runAsync();
-
-    expect(mockCustomEventNamesAsync).toHaveBeenCalledWith(graphqlClient, {
-      appId: projectId,
-      startTime: '2025-06-08T12:00:00.000Z',
-      endTime: '2025-06-15T12:00:00.000Z',
-      platform: AppObservePlatform.Ios,
-    });
-
-    jest.useRealTimers();
-  });
-
-  it('uses --days to compute start/end time range when an event name is provided', async () => {
-    const now = new Date('2025-06-15T12:00:00.000Z');
-    jest.useFakeTimers({ now });
-
-    const command = createCommand(['my_event', '--days', '7']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');
-    expect(options.startTime).toBe('2025-06-08T12:00:00.000Z');
-
-    jest.useRealTimers();
-  });
-
-  it('uses explicit --start and --end when provided', async () => {
-    const command = createCommand([
-      'my_event',
-      '--start',
-      '2025-01-01T00:00:00.000Z',
-      '--end',
-      '2025-02-01T00:00:00.000Z',
-    ]);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.startTime).toBe('2025-01-01T00:00:00.000Z');
-    expect(options.endTime).toBe('2025-02-01T00:00:00.000Z');
-  });
-
-  it('rejects --days combined with --start', async () => {
-    const command = createCommand([
-      'my_event',
-      '--days',
-      '7',
-      '--start',
-      '2025-01-01T00:00:00.000Z',
-    ]);
-    await expect(command.runAsync()).rejects.toThrow();
-  });
-
-  it('passes --limit to fetchObserveCustomEventsAsync', async () => {
-    const command = createCommand(['my_event', '--limit', '42']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.limit).toBe(42);
-  });
-
-  it('passes --after cursor', async () => {
-    const command = createCommand(['my_event', '--after', 'cursor-xyz']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.after).toBe('cursor-xyz');
-  });
-
-  it('passes --platform ios as AppObservePlatform.Ios', async () => {
-    const command = createCommand(['my_event', '--platform', 'ios']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.platform).toBe(AppObservePlatform.Ios);
-  });
-
-  it('passes --app-version', async () => {
-    const command = createCommand(['my_event', '--app-version', '2.1.0']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.appVersion).toBe('2.1.0');
-  });
-
-  it('passes --update-id', async () => {
-    const command = createCommand(['my_event', '--update-id', 'update-xyz']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.updateId).toBe('update-xyz');
-  });
-
-  it('passes --session-id', async () => {
-    const command = createCommand(['my_event', '--session-id', 'session-xyz']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.sessionId).toBe('session-xyz');
-  });
-
-  it('does not pass platform, appVersion, updateId, or sessionId when flags are not provided', async () => {
-    const command = createCommand(['my_event']);
-    await command.runAsync();
-
-    const options = mockFetchObserveCustomEventsAsync.mock.calls[0][2];
-    expect(options.platform).toBeUndefined();
-    expect(options.appVersion).toBeUndefined();
-    expect(options.updateId).toBeUndefined();
-    expect(options.sessionId).toBeUndefined();
-  });
-
-  it('calls enableJsonOutput and printJsonOnlyOutput when --json is provided with an event name', async () => {
-    const mockEvents = [
-      {
-        id: 'evt-1',
-        eventName: 'my_event',
-        timestamp: '2025-01-15T10:30:00.000Z',
-        appVersion: '1.0.0',
-        appBuildNumber: '42',
-        deviceModel: 'iPhone 15',
-        deviceOs: 'iOS',
-        deviceOsVersion: '17.0',
-        countryCode: 'US',
-        sessionId: 'session-1',
-        easClientId: 'client-1',
-        properties: [],
-      },
-    ];
-    mockFetchObserveCustomEventsAsync.mockResolvedValue({
-      events: mockEvents as any,
-      pageInfo: { hasNextPage: false, hasPreviousPage: false },
-    });
-
-    const command = createCommand(['my_event', '--json', '--non-interactive']);
-    await command.runAsync();
-
-    expect(mockEnableJsonOutput).toHaveBeenCalled();
-    expect(mockBuildObserveCustomEventsJson).toHaveBeenCalledWith(
-      mockEvents,
-      expect.objectContaining({ hasNextPage: false })
-    );
-    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
-  });
-
-  it('falls back to fetching event names and renders the empty-with-suggestions table when filtered fetch returns 0 events', async () => {
-    mockFetchObserveCustomEventsAsync.mockResolvedValue({
-      events: [],
-      pageInfo: { hasNextPage: false, hasPreviousPage: false },
-    });
-    const mockNames = [
-      { eventName: 'foo', count: 10 },
-      { eventName: 'bar', count: 5 },
-    ];
-    mockCustomEventNamesAsync.mockResolvedValue({
-      names: mockNames as any,
-      isTruncated: false,
-    });
-
-    const command = createCommand(['my_event']);
-    await command.runAsync();
-
-    expect(mockFetchObserveCustomEventsAsync).toHaveBeenCalledTimes(1);
-    expect(mockCustomEventNamesAsync).toHaveBeenCalledTimes(1);
-    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsTable).toHaveBeenCalledWith(
-      'my_event',
-      mockNames,
-      expect.objectContaining({ isTruncated: false })
-    );
-  });
-
-  it('does not call customEventNamesAsync when filtered fetch returns at least one event', async () => {
-    mockFetchObserveCustomEventsAsync.mockResolvedValue({
-      events: [
-        {
-          id: 'evt-1',
-          eventName: 'my_event',
-          timestamp: '2025-01-15T10:30:00.000Z',
-          appVersion: '1.0.0',
-          appBuildNumber: '42',
-          deviceModel: 'iPhone 15',
-          deviceOs: 'iOS',
-          deviceOsVersion: '17.0',
-          easClientId: 'client-1',
-          properties: [],
-        } as any,
-      ],
-      pageInfo: { hasNextPage: false, hasPreviousPage: false },
-    });
-
-    const command = createCommand(['my_event']);
-    await command.runAsync();
-
-    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
-    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsTable).not.toHaveBeenCalled();
-  });
-
-  it('emits empty-with-suggestions JSON when filtered fetch returns 0 events and --json is set', async () => {
-    mockFetchObserveCustomEventsAsync.mockResolvedValue({
-      events: [],
-      pageInfo: { hasNextPage: false, hasPreviousPage: false },
-    });
-    const mockNames = [{ eventName: 'foo', count: 10 }];
-    mockCustomEventNamesAsync.mockResolvedValue({
-      names: mockNames as any,
-      isTruncated: false,
-    });
-
-    const command = createCommand(['my_event', '--json', '--non-interactive']);
-    await command.runAsync();
-
-    expect(mockEnableJsonOutput).toHaveBeenCalled();
-    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsJson).toHaveBeenCalledWith(
-      'my_event',
-      mockNames,
-      false
-    );
-    expect(mockBuildObserveCustomEventsJson).not.toHaveBeenCalled();
-    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
-  });
-
-  it('does not run the empty-with-suggestions fallback when no event name is provided (event names mode)', async () => {
-    mockCustomEventNamesAsync.mockResolvedValue({ names: [], isTruncated: false });
-
-    const command = createCommand([]);
-    await command.runAsync();
-
-    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsTable).not.toHaveBeenCalled();
-    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsJson).not.toHaveBeenCalled();
-  });
-
-  it('does not run the empty-with-suggestions fallback for --all-events with 0 results', async () => {
-    mockFetchObserveCustomEventsAsync.mockResolvedValue({
-      events: [],
-      pageInfo: { hasNextPage: false, hasPreviousPage: false },
-    });
-
-    const command = createCommand(['--all-events']);
-    await command.runAsync();
-
-    expect(mockCustomEventNamesAsync).not.toHaveBeenCalled();
-    expect(mockBuildObserveCustomEventsEmptyWithSuggestionsTable).not.toHaveBeenCalled();
-  });
-
-  it('emits JSON of event names + counts when --json is provided without an event name', async () => {
-    const mockNames = [
-      { eventName: 'foo', count: 10 },
-      { eventName: 'bar', count: 5 },
-    ];
-    mockCustomEventNamesAsync.mockResolvedValue({
-      names: mockNames as any,
-      isTruncated: false,
-    });
-
-    const command = createCommand(['--json', '--non-interactive']);
-    await command.runAsync();
-
-    expect(mockEnableJsonOutput).toHaveBeenCalled();
-    expect(mockBuildObserveCustomEventNamesJson).toHaveBeenCalledWith(mockNames, false);
-    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
-  });
-});
@@ -0,0 +1,228 @@
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { getMockOclifConfig } from '../../../__tests__/commands/utils';
+import { AppPlatform } from '../../../graphql/generated';
+import { fetchObserveMetricsAsync, validateDateFlag } from '../../../observe/fetchMetrics';
+import { buildObserveMetricsJson, buildObserveMetricsTable } from '../../../observe/formatMetrics';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+import ObserveMetricsSummary from '../metrics-summary';
+
+jest.mock('../../../observe/fetchMetrics', () => {
+  const actual = jest.requireActual('../../../observe/fetchMetrics');
+  return {
+    ...actual,
+    fetchObserveMetricsAsync: jest.fn(),
+  };
+});
+jest.mock('../../../observe/formatMetrics', () => ({
+  ...jest.requireActual('../../../observe/formatMetrics'),
+  buildObserveMetricsTable: jest.fn().mockReturnValue('table'),
+  buildObserveMetricsJson: jest.fn().mockReturnValue([]),
+}));
+jest.mock('../../../log');
+jest.mock('../../../utils/json');
+
+const mockFetchObserveMetricsSummaryAsync = jest.mocked(fetchObserveMetricsAsync);
+const mockBuildObserveMetricsSummaryTable = jest.mocked(buildObserveMetricsTable);
+const mockBuildObserveMetricsSummaryJson = jest.mocked(buildObserveMetricsJson);
+const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
+const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);
+
+describe(ObserveMetricsSummary, () => {
+  const graphqlClient = {} as any as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+  const projectId = 'test-project-id';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockFetchObserveMetricsSummaryAsync.mockResolvedValue({
+      metricsMap: new Map(),
+      buildNumbersMap: new Map(),
+      updateIdsMap: new Map(),
+      totalEventCounts: new Map(),
+    });
+  });
+
+  function createCommand(argv: string[]): ObserveMetricsSummary {
+    const command = new ObserveMetricsSummary(argv, mockConfig);
+    // @ts-expect-error getContextAsync is a protected method
+    jest.spyOn(command, 'getContextAsync').mockReturnValue({
+      projectId,
+      loggedIn: { graphqlClient },
+    });
+    return command;
+  }
+
+  it('fetches metrics with default parameters (both platforms)', async () => {
+    const now = new Date('2025-06-15T12:00:00.000Z');
+    jest.useFakeTimers({ now });
+
+    const command = createCommand([]);
+    await command.runAsync();
+
+    expect(mockFetchObserveMetricsSummaryAsync).toHaveBeenCalledTimes(1);
+    const platforms = mockFetchObserveMetricsSummaryAsync.mock.calls[0][3];
+    expect(platforms).toEqual([AppPlatform.Android, AppPlatform.Ios]);
+
+    jest.useRealTimers();
+  });
+
+  it('queries only Android when --platform android is passed', async () => {
+    const command = createCommand(['--platform', 'android']);
+    await command.runAsync();
+
+    const platforms = mockFetchObserveMetricsSummaryAsync.mock.calls[0][3];
+    expect(platforms).toEqual([AppPlatform.Android]);
+  });
+
+  it('queries only iOS when --platform ios is passed', async () => {
+    const command = createCommand(['--platform', 'ios']);
+    await command.runAsync();
+
+    const platforms = mockFetchObserveMetricsSummaryAsync.mock.calls[0][3];
+    expect(platforms).toEqual([AppPlatform.Ios]);
+  });
+
+  it('resolves --metric aliases before passing to fetchObserveMetricsAsync', async () => {
+    const command = createCommand(['--metric', 'tti', '--metric', 'cold_launch']);
+    await command.runAsync();
+
+    const metricNames = mockFetchObserveMetricsSummaryAsync.mock.calls[0][2];
+    expect(metricNames).toEqual(['expo.app_startup.tti', 'expo.app_startup.cold_launch_time']);
+  });
+
+  it('uses default time range (60 days back) when no --start/--end flags', async () => {
+    const now = new Date('2025-06-15T12:00:00.000Z');
+    jest.useFakeTimers({ now });
+
+    const command = createCommand([]);
+    await command.runAsync();
+
+    const startTime = mockFetchObserveMetricsSummaryAsync.mock.calls[0][4];
+    const endTime = mockFetchObserveMetricsSummaryAsync.mock.calls[0][5];
+    expect(endTime).toBe('2025-06-15T12:00:00.000Z');
+    expect(startTime).toBe('2025-04-16T12:00:00.000Z');
+
+    jest.useRealTimers();
+  });
+
+  it('uses explicit --start and --end when provided', async () => {
+    const command = createCommand([
+      '--start',
+      '2025-01-01T00:00:00.000Z',
+      '--end',
+      '2025-02-01T00:00:00.000Z',
+    ]);
+    await command.runAsync();
+
+    const startTime = mockFetchObserveMetricsSummaryAsync.mock.calls[0][4];
+    const endTime = mockFetchObserveMetricsSummaryAsync.mock.calls[0][5];
+    expect(startTime).toBe('2025-01-01T00:00:00.000Z');
+    expect(endTime).toBe('2025-02-01T00:00:00.000Z');
+  });
+
+  it('passes resolved --stat flags to buildObserveMetricsTable', async () => {
+    const command = createCommand(['--stat', 'p90', '--stat', 'eventCount']);
+    await command.runAsync();
+
+    expect(mockBuildObserveMetricsSummaryTable).toHaveBeenCalledWith(
+      expect.any(Map),
+      expect.any(Array),
+      ['p90', 'eventCount'],
+      expect.objectContaining({ daysBack: 60 })
+    );
+  });
+
+  it('deduplicates --stat flags that resolve to the same key', async () => {
+    const command = createCommand(['--stat', 'median', '--stat', 'median']);
+    await command.runAsync();
+
+    expect(mockBuildObserveMetricsSummaryTable).toHaveBeenCalledWith(
+      expect.any(Map),
+      expect.any(Array),
+      ['median'],
+      expect.objectContaining({ daysBack: 60 })
+    );
+  });
+
+  it('uses --days to compute start/end time range', async () => {
+    const now = new Date('2025-06-15T12:00:00.000Z');
+    jest.useFakeTimers({ now });
+
+    const command = createCommand(['--days', '7']);
+    await command.runAsync();
+
+    const startTime = mockFetchObserveMetricsSummaryAsync.mock.calls[0][4];
+    const endTime = mockFetchObserveMetricsSummaryAsync.mock.calls[0][5];
+    expect(endTime).toBe('2025-06-15T12:00:00.000Z');
+    expect(startTime).toBe('2025-06-08T12:00:00.000Z');
+
+    jest.useRealTimers();
+  });
+
+  it('rejects --days combined with --start', async () => {
+    const command = createCommand(['--days', '7', '--start', '2025-01-01T00:00:00.000Z']);
+
+    await expect(command.runAsync()).rejects.toThrow();
+  });
+
+  it('rejects --days combined with --end', async () => {
+    const command = createCommand(['--days', '7', '--end', '2025-02-01T00:00:00.000Z']);
+
+    await expect(command.runAsync()).rejects.toThrow();
+  });
+
+  it('uses default stats when --stat is not provided', async () => {
+    const command = createCommand([]);
+    await command.runAsync();
+
+    expect(mockBuildObserveMetricsSummaryTable).toHaveBeenCalledWith(
+      expect.any(Map),
+      expect.any(Array),
+      ['median', 'eventCount'],
+      expect.objectContaining({ daysBack: 60 })
+    );
+  });
+
+  it('passes resolved --stat flags to buildObserveMetricsJson when --json is used', async () => {
+    const command = createCommand([
+      '--json',
+      '--non-interactive',
+      '--stat',
+      'min',
+      '--stat',
+      'average',
+    ]);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockBuildObserveMetricsSummaryJson).toHaveBeenCalledWith(
+      expect.any(Map),
+      expect.any(Array),
+      ['min', 'average'],
+      expect.any(Map),
+      expect.any(Map),
+      expect.any(Map)
+    );
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
+  });
+});
+
+describe(validateDateFlag, () => {
+  it('throws on invalid --start date', () => {
+    expect(() => {
+      validateDateFlag('not-a-date', '--start');
+    }).toThrow('Invalid --start date: "not-a-date"');
+  });
+
+  it('throws on invalid --end date', () => {
+    expect(() => {
+      validateDateFlag('also-bad', '--end');
+    }).toThrow('Invalid --end date: "also-bad"');
+  });
+
+  it('accepts valid ISO date in --start', () => {
+    expect(() => {
+      validateDateFlag('2025-01-01', '--start');
+    }).not.toThrow();
+  });
+});
@@ -1,29 +1,31 @@
 import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
 import { getMockOclifConfig } from '../../../__tests__/commands/utils';
-import { AppPlatform } from '../../../graphql/generated';
-import { fetchObserveMetricsAsync, validateDateFlag } from '../../../observe/fetchMetrics';
-import { buildObserveMetricsJson, buildObserveMetricsTable } from '../../../observe/formatMetrics';
+import {
+  AppObserveEventsOrderByDirection,
+  AppObserveEventsOrderByField,
+  AppObservePlatform,
+} from '../../../graphql/generated';
+import { fetchObserveEventsAsync, resolveOrderBy } from '../../../observe/fetchEvents';
+import { buildObserveEventsJson } from '../../../observe/formatEvents';
 import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
 import ObserveMetrics from '../metrics';

-jest.mock('../../../observe/fetchMetrics', () => {
-  const actual = jest.requireActual('../../../observe/fetchMetrics');
+jest.mock('../../../observe/fetchEvents', () => {
+  const actual = jest.requireActual('../../../observe/fetchEvents');
  return {
    ...actual,
-    fetchObserveMetricsAsync: jest.fn(),
+    fetchObserveEventsAsync: jest.fn(),
  };
 });
-jest.mock('../../../observe/formatMetrics', () => ({
-  ...jest.requireActual('../../../observe/formatMetrics'),
-  buildObserveMetricsTable: jest.fn().mockReturnValue('table'),
-  buildObserveMetricsJson: jest.fn().mockReturnValue([]),
+jest.mock('../../../observe/formatEvents', () => ({
+  buildObserveEventsTable: jest.fn().mockReturnValue('table'),
+  buildObserveEventsJson: jest.fn().mockReturnValue({}),
 }));
 jest.mock('../../../log');
 jest.mock('../../../utils/json');

-const mockFetchObserveMetricsAsync = jest.mocked(fetchObserveMetricsAsync);
-const mockBuildObserveMetricsTable = jest.mocked(buildObserveMetricsTable);
-const mockBuildObserveMetricsJson = jest.mocked(buildObserveMetricsJson);
+const mockFetchObserveEventsAsync = jest.mocked(fetchObserveEventsAsync);
+const mockBuildObserveEventsJson = jest.mocked(buildObserveEventsJson);
 const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
 const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);

@@ -34,17 +36,15 @@ describe(ObserveMetrics, () => {

  beforeEach(() => {
    jest.clearAllMocks();
-    mockFetchObserveMetricsAsync.mockResolvedValue({
-      metricsMap: new Map(),
-      buildNumbersMap: new Map(),
-      updateIdsMap: new Map(),
-      totalEventCounts: new Map(),
+    mockFetchObserveEventsAsync.mockResolvedValue({
+      events: [],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
    });
  });

  function createCommand(argv: string[]): ObserveMetrics {
    const command = new ObserveMetrics(argv, mockConfig);
-    // @ts-expect-error getContextAsync is a protected method
+    // @ts-expect-error
    jest.spyOn(command, 'getContextAsync').mockReturnValue({
      projectId,
      loggedIn: { graphqlClient },
@@ -52,61 +52,38 @@ describe(ObserveMetrics, () => {
    return command;
  }

-  it('fetches metrics with default parameters (both platforms)', async () => {
+  it('uses --days to compute start/end time range', async () => {
    const now = new Date('2025-06-15T12:00:00.000Z');
    jest.useFakeTimers({ now });

-    const command = createCommand([]);
+    const command = createCommand(['tti', '--days', '7']);
    await command.runAsync();

-    expect(mockFetchObserveMetricsAsync).toHaveBeenCalledTimes(1);
-    const platforms = mockFetchObserveMetricsAsync.mock.calls[0][3];
-    expect(platforms).toEqual([AppPlatform.Android, AppPlatform.Ios]);
+    expect(mockFetchObserveEventsAsync).toHaveBeenCalledTimes(1);
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');
+    expect(options.startTime).toBe('2025-06-08T12:00:00.000Z');

    jest.useRealTimers();
  });

-  it('queries only Android when --platform android is passed', async () => {
-    const command = createCommand(['--platform', 'android']);
-    await command.runAsync();
-
-    const platforms = mockFetchObserveMetricsAsync.mock.calls[0][3];
-    expect(platforms).toEqual([AppPlatform.Android]);
-  });
-
-  it('queries only iOS when --platform ios is passed', async () => {
-    const command = createCommand(['--platform', 'ios']);
-    await command.runAsync();
-
-    const platforms = mockFetchObserveMetricsAsync.mock.calls[0][3];
-    expect(platforms).toEqual([AppPlatform.Ios]);
-  });
-
-  it('resolves --metric aliases before passing to fetchObserveMetricsAsync', async () => {
-    const command = createCommand(['--metric', 'tti', '--metric', 'cold_launch']);
-    await command.runAsync();
-
-    const metricNames = mockFetchObserveMetricsAsync.mock.calls[0][2];
-    expect(metricNames).toEqual(['expo.app_startup.tti', 'expo.app_startup.cold_launch_time']);
-  });
-
-  it('uses default time range (60 days back) when no --start/--end flags', async () => {
+  it('uses DEFAULT_DAYS_BACK (60 days) when neither --days nor --start/--end are provided', async () => {
    const now = new Date('2025-06-15T12:00:00.000Z');
    jest.useFakeTimers({ now });

-    const command = createCommand([]);
+    const command = createCommand(['tti']);
    await command.runAsync();

-    const startTime = mockFetchObserveMetricsAsync.mock.calls[0][4];
-    const endTime = mockFetchObserveMetricsAsync.mock.calls[0][5];
-    expect(endTime).toBe('2025-06-15T12:00:00.000Z');
-    expect(startTime).toBe('2025-04-16T12:00:00.000Z');
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.startTime).toBe('2025-04-16T12:00:00.000Z');
+    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');

    jest.useRealTimers();
  });

  it('uses explicit --start and --end when provided', async () => {
    const command = createCommand([
+      'tti',
      '--start',
      '2025-01-01T00:00:00.000Z',
      '--end',
@@ -114,111 +91,190 @@ describe(ObserveMetrics, () => {
    ]);
    await command.runAsync();

-    const startTime = mockFetchObserveMetricsAsync.mock.calls[0][4];
-    const endTime = mockFetchObserveMetricsAsync.mock.calls[0][5];
-    expect(startTime).toBe('2025-01-01T00:00:00.000Z');
-    expect(endTime).toBe('2025-02-01T00:00:00.000Z');
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.startTime).toBe('2025-01-01T00:00:00.000Z');
+    expect(options.endTime).toBe('2025-02-01T00:00:00.000Z');
  });

-  it('passes resolved --stat flags to buildObserveMetricsTable', async () => {
-    const command = createCommand(['--stat', 'p90', '--stat', 'eventCount']);
-    await command.runAsync();
-
-    expect(mockBuildObserveMetricsTable).toHaveBeenCalledWith(
-      expect.any(Map),
-      expect.any(Array),
-      ['p90', 'eventCount'],
-      expect.objectContaining({ daysBack: 60 })
-    );
-  });
-
-  it('deduplicates --stat flags that resolve to the same key', async () => {
-    const command = createCommand(['--stat', 'median', '--stat', 'median']);
-    await command.runAsync();
-
-    expect(mockBuildObserveMetricsTable).toHaveBeenCalledWith(
-      expect.any(Map),
-      expect.any(Array),
-      ['median'],
-      expect.objectContaining({ daysBack: 60 })
-    );
-  });
-
-  it('uses --days to compute start/end time range', async () => {
+  it('defaults endTime to now when only --start is provided', async () => {
    const now = new Date('2025-06-15T12:00:00.000Z');
    jest.useFakeTimers({ now });

-    const command = createCommand(['--days', '7']);
+    const command = createCommand(['tti', '--start', '2025-01-01T00:00:00.000Z']);
    await command.runAsync();

-    const startTime = mockFetchObserveMetricsAsync.mock.calls[0][4];
-    const endTime = mockFetchObserveMetricsAsync.mock.calls[0][5];
-    expect(endTime).toBe('2025-06-15T12:00:00.000Z');
-    expect(startTime).toBe('2025-06-08T12:00:00.000Z');
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.startTime).toBe('2025-01-01T00:00:00.000Z');
+    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');

    jest.useRealTimers();
  });

  it('rejects --days combined with --start', async () => {
-    const command = createCommand(['--days', '7', '--start', '2025-01-01T00:00:00.000Z']);
+    const command = createCommand(['tti', '--days', '7', '--start', '2025-01-01T00:00:00.000Z']);

    await expect(command.runAsync()).rejects.toThrow();
  });

+  it('passes --limit to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['tti', '--limit', '42']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.limit).toBe(42);
+  });
+
+  it('passes --after cursor to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['tti', '--after', 'cursor-xyz']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.after).toBe('cursor-xyz');
+  });
+
+  it('does not pass after when --after flag is not provided', async () => {
+    const command = createCommand(['tti']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options).not.toHaveProperty('after');
+  });
+
  it('rejects --days combined with --end', async () => {
-    const command = createCommand(['--days', '7', '--end', '2025-02-01T00:00:00.000Z']);
+    const command = createCommand(['tti', '--days', '7', '--end', '2025-02-01T00:00:00.000Z']);

    await expect(command.runAsync()).rejects.toThrow();
  });

-  it('uses default stats when --stat is not provided', async () => {
-    const command = createCommand([]);
+  it('passes --platform ios to fetchObserveEventsAsync as AppObservePlatform.Ios', async () => {
+    const command = createCommand(['tti', '--platform', 'ios']);
    await command.runAsync();

-    expect(mockBuildObserveMetricsTable).toHaveBeenCalledWith(
-      expect.any(Map),
-      expect.any(Array),
-      ['median', 'eventCount'],
-      expect.objectContaining({ daysBack: 60 })
-    );
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.platform).toBe(AppObservePlatform.Ios);
  });

-  it('passes resolved --stat flags to buildObserveMetricsJson when --json is used', async () => {
-    const command = createCommand([
-      '--json',
-      '--non-interactive',
-      '--stat',
-      'min',
-      '--stat',
-      'average',
-    ]);
+  it('passes --platform android to fetchObserveEventsAsync as AppObservePlatform.Android', async () => {
+    const command = createCommand(['tti', '--platform', 'android']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.platform).toBe(AppObservePlatform.Android);
+  });
+
+  it('passes --app-version to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['tti', '--app-version', '2.1.0']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.appVersion).toBe('2.1.0');
+  });
+
+  it('passes --update-id to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['tti', '--update-id', 'update-xyz']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.updateId).toBe('update-xyz');
+  });
+
+  it('does not pass platform, appVersion, or updateId when flags are not provided', async () => {
+    const command = createCommand(['tti']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.platform).toBeUndefined();
+    expect(options.appVersion).toBeUndefined();
+    expect(options.updateId).toBeUndefined();
+  });
+
+  it('calls enableJsonOutput and printJsonOnlyOutput when --json is provided', async () => {
+    const mockEvents = [
+      {
+        id: 'evt-1',
+        metricName: 'expo.app_startup.tti',
+        metricValue: 1.23,
+        timestamp: '2025-01-15T10:30:00.000Z',
+        appVersion: '1.0.0',
+        appBuildNumber: '42',
+        deviceModel: 'iPhone 15',
+        deviceOs: 'iOS',
+        deviceOsVersion: '17.0',
+        countryCode: 'US',
+        sessionId: 'session-1',
+        easClientId: 'client-1',
+      },
+    ];
+    mockFetchObserveEventsAsync.mockResolvedValue({
+      events: mockEvents as any,
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
+    });
+
+    const command = createCommand(['tti', '--json', '--non-interactive']);
    await command.runAsync();

    expect(mockEnableJsonOutput).toHaveBeenCalled();
-    expect(mockBuildObserveMetricsJson).toHaveBeenCalledWith(
-      expect.any(Map),
-      expect.any(Array),
-      ['min', 'average'],
-      expect.any(Map),
-      expect.any(Map),
-      expect.any(Map)
+    expect(mockBuildObserveEventsJson).toHaveBeenCalledWith(
+      mockEvents,
+      expect.objectContaining({ hasNextPage: false })
    );
    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
  });
-});

-describe(validateDateFlag, () => {
-  it('throws on invalid --start date', () => {
-    expect(() => validateDateFlag('not-a-date', '--start')).toThrow(
-      'Invalid --start date: "not-a-date"'
+  it('does not call enableJsonOutput when --json is not provided', async () => {
+    const command = createCommand(['tti']);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).not.toHaveBeenCalled();
+    expect(mockPrintJsonOnlyOutput).not.toHaveBeenCalled();
+  });
+
+  it('passes --sort flag through to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['tti', '--sort', 'slowest']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.orderBy).toEqual({
+      field: AppObserveEventsOrderByField.MetricValue,
+      direction: AppObserveEventsOrderByDirection.Desc,
+    });
+  });
+
+  it('throws in non-interactive mode when no metric is provided', async () => {
+    const command = createCommand(['--non-interactive']);
+
+    await expect(command.runAsync()).rejects.toThrow(
+      'metric argument is required in non-interactive mode'
    );
  });
+});

-  it('throws on invalid --end date', () => {
-    expect(() => validateDateFlag('also-bad', '--end')).toThrow('Invalid --end date: "also-bad"');
+describe(resolveOrderBy, () => {
+  it('resolves lowercase "slowest" to MetricValue DESC', () => {
+    expect(resolveOrderBy('slowest')).toEqual({
+      field: AppObserveEventsOrderByField.MetricValue,
+      direction: AppObserveEventsOrderByDirection.Desc,
+    });
  });

-  it('accepts valid ISO date in --start', () => {
-    expect(() => validateDateFlag('2025-01-01', '--start')).not.toThrow();
+  it('resolves lowercase "fastest" to MetricValue ASC', () => {
+    expect(resolveOrderBy('fastest')).toEqual({
+      field: AppObserveEventsOrderByField.MetricValue,
+      direction: AppObserveEventsOrderByDirection.Asc,
+    });
+  });
+
+  it('resolves lowercase "newest" to Timestamp DESC', () => {
+    expect(resolveOrderBy('newest')).toEqual({
+      field: AppObserveEventsOrderByField.Timestamp,
+      direction: AppObserveEventsOrderByDirection.Desc,
+    });
+  });
+
+  it('resolves lowercase "oldest" to Timestamp ASC', () => {
+    expect(resolveOrderBy('oldest')).toEqual({
+      field: AppObserveEventsOrderByField.Timestamp,
+      direction: AppObserveEventsOrderByDirection.Asc,
+    });
  });
 });
@@ -1,16 +1,11 @@
 import { Args, Flags } from '@oclif/core';

 import EasCommand from '../../commandUtils/EasCommand';
-import { EasCommandError } from '../../commandUtils/errors';
 import { EasNonInteractiveAndJsonFlags } from '../../commandUtils/flags';
 import { getLimitFlagWithCustomValues } from '../../commandUtils/pagination';
 import Log from '../../log';
-import {
-  EventsOrderPreset,
-  fetchObserveEventsAsync,
-  fetchTotalEventCountAsync,
-  resolveOrderBy,
-} from '../../observe/fetchEvents';
+import { ObserveQuery } from '../../graphql/queries/ObserveQuery';
+import { fetchObserveCustomEventsAsync } from '../../observe/fetchCustomEvents';
 import {
  ObserveAfterFlag,
  ObserveAppVersionFlag,
@@ -19,35 +14,33 @@ import {
  ObserveTimeRangeFlags,
  ObserveUpdateIdFlag,
 } from '../../observe/flags';
-import { METRIC_ALIASES, METRIC_SHORT_NAMES, resolveMetricName } from '../../observe/metricNames';
-import { buildObserveEventsJson, buildObserveEventsTable } from '../../observe/formatEvents';
-import { appObservePlatformFromFlag, appPlatformsFromFlag } from '../../observe/platforms';
+import {
+  buildObserveCustomEventNamesJson,
+  buildObserveCustomEventNamesTable,
+  buildObserveCustomEventsEmptyWithSuggestionsJson,
+  buildObserveCustomEventsEmptyWithSuggestionsTable,
+  buildObserveCustomEventsJson,
+  buildObserveCustomEventsTable,
+} from '../../observe/formatCustomEvents';
+import { appObservePlatformFromFlag } from '../../observe/platforms';
 import { resolveObserveCommandContextAsync } from '../../observe/resolveProjectContext';
 import { resolveTimeRange } from '../../observe/startAndEndTime';
-import { selectAsync } from '../../prompts';
 import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';

 const DEFAULT_EVENTS_LIMIT = 10;

 export default class ObserveEvents extends EasCommand {
-  static override hidden = true;
-  static override description = 'display individual app performance events ordered by metric value';
+  static override description =
+    'display individual events emitted by the app via `logEvent`, filtered by the event name in the argument. With no arguments, a list of the available event names and associated event counts is returned.';

  static override args = {
-    metric: Args.string({
-      description: 'Metric to query (e.g. tti, cold_launch)',
+    eventName: Args.string({
+      description: 'Event name to filter by',
      required: false,
-      options: Object.keys(METRIC_ALIASES),
    }),
  };

  static override flags = {
-    sort: Flags.option({
-      description: 'Sort order for events',
-      options: Object.values(EventsOrderPreset).map(s => s.toLowerCase()),
-      required: false,
-      default: EventsOrderPreset.Oldest.valueOf().toLowerCase(),
-    })(),
    ...ObservePlatformFlag,
    ...ObserveAfterFlag,
    limit: getLimitFlagWithCustomValues({
@@ -57,6 +50,14 @@ export default class ObserveEvents extends EasCommand {
    ...ObserveTimeRangeFlags,
    ...ObserveAppVersionFlag,
    ...ObserveUpdateIdFlag,
+    'session-id': Flags.string({
+      description: 'Filter by session ID',
+    }),
+    'all-events': Flags.boolean({
+      description:
+        'When no event name argument is provided, list all events across all event names instead of a summary of event names + counts.',
+      default: false,
+    }),
    ...ObserveProjectIdFlag,
    ...EasNonInteractiveAndJsonFlags,
  };
@@ -73,6 +74,12 @@ export default class ObserveEvents extends EasCommand {
  async runAsync(): Promise<void> {
    const { flags, args } = await this.parse(ObserveEvents);

+    if (args.eventName && flags['all-events']) {
+      throw new Error(
+        '--all-events cannot be combined with an event name argument. Pass an event name to filter by it, or pass --all-events to list all events across all event names.'
+      );
+    }
+
    const { projectId, graphqlClient } = await resolveObserveCommandContextAsync({
      command: this,
      commandClass: ObserveEvents,
@@ -83,65 +90,84 @@ export default class ObserveEvents extends EasCommand {

    if (flags.json) {
      enableJsonOutput();
-    } else {
-      Log.warn('EAS Observe is in preview and subject to breaking changes.');
    }

-    let metricName: string;
-    if (args.metric) {
-      metricName = resolveMetricName(args.metric);
-    } else if (flags['non-interactive']) {
-      throw new EasCommandError(
-        'A metric argument is required in non-interactive mode. Available metrics: ' +
-          Object.keys(METRIC_ALIASES).join(', ')
-      );
-    } else {
-      const choices = Object.entries(METRIC_SHORT_NAMES).map(([fullName, displayName]) => ({
-        title: `${displayName} (${fullName})`,
-        value: fullName,
-      }));
-      metricName = await selectAsync('Select a metric', choices);
-    }
-    const orderBy = resolveOrderBy(flags.sort);
-
    const { daysBack, startTime, endTime } = resolveTimeRange(flags);

    const platform = appObservePlatformFromFlag(flags.platform);
-    const platforms = appPlatformsFromFlag(flags.platform);

-    const [{ events, pageInfo }, totalEventCount] = await Promise.all([
-      fetchObserveEventsAsync(graphqlClient, projectId, {
-        metricName,
-        orderBy,
-        limit: flags.limit ?? DEFAULT_EVENTS_LIMIT,
-        ...(flags.after && { after: flags.after }),
+    if (!args.eventName && !flags['all-events']) {
+      const { names, isTruncated } = await ObserveQuery.customEventNamesAsync(graphqlClient, {
+        appId: projectId,
        startTime,
        endTime,
        platform,
-        appVersion: flags['app-version'],
-        updateId: flags['update-id'],
-      }),
-      fetchTotalEventCountAsync(
-        graphqlClient,
-        projectId,
-        metricName,
-        platforms,
+      });
+
+      if (flags.json) {
+        printJsonOnlyOutput(buildObserveCustomEventNamesJson(names, isTruncated));
+      } else {
+        Log.addNewLineIfNone();
+        Log.log(
+          buildObserveCustomEventNamesTable(names, {
+            daysBack,
+            startTime,
+            endTime,
+            isTruncated,
+          })
+        );
+      }
+      return;
+    }
+
+    const { events, pageInfo } = await fetchObserveCustomEventsAsync(graphqlClient, projectId, {
+      eventName: args.eventName,
+      limit: flags.limit ?? DEFAULT_EVENTS_LIMIT,
+      ...(flags.after && { after: flags.after }),
+      startTime,
+      endTime,
+      platform,
+      appVersion: flags['app-version'],
+      updateId: flags['update-id'],
+      sessionId: flags['session-id'],
+    });
+
+    if (args.eventName && events.length === 0) {
+      const { names, isTruncated } = await ObserveQuery.customEventNamesAsync(graphqlClient, {
+        appId: projectId,
        startTime,
-        endTime
-      ),
-    ]);
+        endTime,
+        platform,
+      });
+
+      if (flags.json) {
+        printJsonOnlyOutput(
+          buildObserveCustomEventsEmptyWithSuggestionsJson(args.eventName, names, isTruncated)
+        );
+      } else {
+        Log.addNewLineIfNone();
+        Log.log(
+          buildObserveCustomEventsEmptyWithSuggestionsTable(args.eventName, names, {
+            daysBack,
+            startTime,
+            endTime,
+            isTruncated,
+          })
+        );
+      }
+      return;
+    }

    if (flags.json) {
-      printJsonOnlyOutput(buildObserveEventsJson(events, pageInfo));
+      printJsonOnlyOutput(buildObserveCustomEventsJson(events, pageInfo));
    } else {
      Log.addNewLineIfNone();
      Log.log(
-        buildObserveEventsTable(events, pageInfo, {
-          metricName,
+        buildObserveCustomEventsTable(events, pageInfo, {
+          eventName: args.eventName,
          daysBack,
          startTime,
          endTime,
-          totalEventCount,
        })
      );
    }
@@ -1,178 +0,0 @@
-import { Args, Flags } from '@oclif/core';
-
-import EasCommand from '../../commandUtils/EasCommand';
-import { EasNonInteractiveAndJsonFlags } from '../../commandUtils/flags';
-import { getLimitFlagWithCustomValues } from '../../commandUtils/pagination';
-import Log from '../../log';
-import { ObserveQuery } from '../../graphql/queries/ObserveQuery';
-import { fetchObserveCustomEventsAsync } from '../../observe/fetchCustomEvents';
-import {
-  ObserveAfterFlag,
-  ObserveAppVersionFlag,
-  ObservePlatformFlag,
-  ObserveProjectIdFlag,
-  ObserveTimeRangeFlags,
-  ObserveUpdateIdFlag,
-} from '../../observe/flags';
-import {
-  buildObserveCustomEventNamesJson,
-  buildObserveCustomEventNamesTable,
-  buildObserveCustomEventsEmptyWithSuggestionsJson,
-  buildObserveCustomEventsEmptyWithSuggestionsTable,
-  buildObserveCustomEventsJson,
-  buildObserveCustomEventsTable,
-} from '../../observe/formatCustomEvents';
-import { appObservePlatformFromFlag } from '../../observe/platforms';
-import { resolveObserveCommandContextAsync } from '../../observe/resolveProjectContext';
-import { resolveTimeRange } from '../../observe/startAndEndTime';
-import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
-
-const DEFAULT_EVENTS_LIMIT = 10;
-
-export default class ObserveLogs extends EasCommand {
-  static override hidden = true;
-  static override description =
-    'display individual custom events (logs) emitted by the app, filtered by the event name in the argument. With no arguments, a list of the available event names and associated event counts is returned.';
-
-  static override args = {
-    eventName: Args.string({
-      description: 'Custom event name to filter by',
-      required: false,
-    }),
-  };
-
-  static override flags = {
-    ...ObservePlatformFlag,
-    ...ObserveAfterFlag,
-    limit: getLimitFlagWithCustomValues({
-      defaultTo: DEFAULT_EVENTS_LIMIT,
-      limit: 100,
-    }),
-    ...ObserveTimeRangeFlags,
-    ...ObserveAppVersionFlag,
-    ...ObserveUpdateIdFlag,
-    'session-id': Flags.string({
-      description: 'Filter by session ID',
-    }),
-    'all-events': Flags.boolean({
-      description:
-        'When no event name argument is provided, list all events across all event names instead of a summary of event names + counts.',
-      default: false,
-    }),
-    ...ObserveProjectIdFlag,
-    ...EasNonInteractiveAndJsonFlags,
-  };
-
-  static override contextDefinition = {
-    ...this.ContextOptions.ProjectId,
-    ...this.ContextOptions.LoggedIn,
-  };
-
-  private static loggedInOnlyContextDefinition = {
-    ...this.ContextOptions.LoggedIn,
-  };
-
-  async runAsync(): Promise<void> {
-    const { flags, args } = await this.parse(ObserveLogs);
-
-    if (args.eventName && flags['all-events']) {
-      throw new Error(
-        '--all-events cannot be combined with an event name argument. Pass an event name to filter by it, or pass --all-events to list all events across all event names.'
-      );
-    }
-
-    const { projectId, graphqlClient } = await resolveObserveCommandContextAsync({
-      command: this,
-      commandClass: ObserveLogs,
-      loggedInOnlyContextDefinition: ObserveLogs.loggedInOnlyContextDefinition,
-      projectIdOverride: flags['project-id'],
-      nonInteractive: flags['non-interactive'],
-    });
-
-    if (flags.json) {
-      enableJsonOutput();
-    } else {
-      Log.warn('EAS Observe is in preview and subject to breaking changes.');
-    }
-
-    const { daysBack, startTime, endTime } = resolveTimeRange(flags);
-
-    const platform = appObservePlatformFromFlag(flags.platform);
-
-    if (!args.eventName && !flags['all-events']) {
-      const { names, isTruncated } = await ObserveQuery.customEventNamesAsync(graphqlClient, {
-        appId: projectId,
-        startTime,
-        endTime,
-        platform,
-      });
-
-      if (flags.json) {
-        printJsonOnlyOutput(buildObserveCustomEventNamesJson(names, isTruncated));
-      } else {
-        Log.addNewLineIfNone();
-        Log.log(
-          buildObserveCustomEventNamesTable(names, {
-            daysBack,
-            startTime,
-            endTime,
-            isTruncated,
-          })
-        );
-      }
-      return;
-    }
-
-    const { events, pageInfo } = await fetchObserveCustomEventsAsync(graphqlClient, projectId, {
-      eventName: args.eventName,
-      limit: flags.limit ?? DEFAULT_EVENTS_LIMIT,
-      ...(flags.after && { after: flags.after }),
-      startTime,
-      endTime,
-      platform,
-      appVersion: flags['app-version'],
-      updateId: flags['update-id'],
-      sessionId: flags['session-id'],
-    });
-
-    if (args.eventName && events.length === 0) {
-      const { names, isTruncated } = await ObserveQuery.customEventNamesAsync(graphqlClient, {
-        appId: projectId,
-        startTime,
-        endTime,
-        platform,
-      });
-
-      if (flags.json) {
-        printJsonOnlyOutput(
-          buildObserveCustomEventsEmptyWithSuggestionsJson(args.eventName, names, isTruncated)
-        );
-      } else {
-        Log.addNewLineIfNone();
-        Log.log(
-          buildObserveCustomEventsEmptyWithSuggestionsTable(args.eventName, names, {
-            daysBack,
-            startTime,
-            endTime,
-            isTruncated,
-          })
-        );
-      }
-      return;
-    }
-
-    if (flags.json) {
-      printJsonOnlyOutput(buildObserveCustomEventsJson(events, pageInfo));
-    } else {
-      Log.addNewLineIfNone();
-      Log.log(
-        buildObserveCustomEventsTable(events, pageInfo, {
-          eventName: args.eventName,
-          daysBack,
-          startTime,
-          endTime,
-        })
-      );
-    }
-  }
-}
@@ -0,0 +1,135 @@
+import { Flags } from '@oclif/core';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import { EasNonInteractiveAndJsonFlags } from '../../commandUtils/flags';
+import Log from '../../log';
+import { fetchObserveMetricsAsync } from '../../observe/fetchMetrics';
+import {
+  ObservePlatformFlag,
+  ObserveProjectIdFlag,
+  ObserveTimeRangeFlags,
+} from '../../observe/flags';
+import {
+  StatisticKey,
+  buildObserveMetricsJson,
+  buildObserveMetricsTable,
+  resolveStatKey,
+} from '../../observe/formatMetrics';
+import { METRIC_ALIASES, resolveMetricName } from '../../observe/metricNames';
+import { appPlatformsFromFlag } from '../../observe/platforms';
+import { resolveObserveCommandContextAsync } from '../../observe/resolveProjectContext';
+import { resolveTimeRange } from '../../observe/startAndEndTime';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
+
+const DEFAULT_METRICS = [
+  'expo.app_startup.cold_launch_time',
+  'expo.app_startup.warm_launch_time',
+  'expo.app_startup.tti',
+  'expo.app_startup.ttr',
+  'expo.app_startup.bundle_load_time',
+];
+
+const DEFAULT_STATS_TABLE: StatisticKey[] = ['median', 'eventCount'];
+const DEFAULT_STATS_JSON: StatisticKey[] = [
+  'min',
+  'median',
+  'max',
+  'average',
+  'p80',
+  'p90',
+  'p99',
+  'eventCount',
+];
+
+export default class ObserveMetricsSummary extends EasCommand {
+  static override description =
+    'display aggregated performance metric statistics grouped by app version';
+
+  static override flags = {
+    ...ObservePlatformFlag,
+    metric: Flags.option({
+      description: 'Metric name to display (can be specified multiple times).',
+      multiple: true,
+      options: Object.keys(METRIC_ALIASES),
+    })(),
+    stat: Flags.option({
+      description: 'Statistic to display per metric (can be specified multiple times)',
+      multiple: true,
+      options: DEFAULT_STATS_JSON,
+    })(),
+    ...ObserveTimeRangeFlags,
+    ...ObserveProjectIdFlag,
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectId,
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  private static loggedInOnlyContextDefinition = {
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(ObserveMetricsSummary);
+
+    const { projectId, graphqlClient } = await resolveObserveCommandContextAsync({
+      command: this,
+      commandClass: ObserveMetricsSummary,
+      loggedInOnlyContextDefinition: ObserveMetricsSummary.loggedInOnlyContextDefinition,
+      projectIdOverride: flags['project-id'],
+      nonInteractive: flags['non-interactive'],
+    });
+
+    if (flags.json) {
+      enableJsonOutput();
+    }
+
+    const metricNames = flags.metric?.length
+      ? flags.metric.map(resolveMetricName)
+      : DEFAULT_METRICS;
+
+    const { daysBack, startTime, endTime } = resolveTimeRange(flags);
+
+    const platforms = appPlatformsFromFlag(flags.platform);
+
+    const { metricsMap, buildNumbersMap, updateIdsMap, totalEventCounts } =
+      await fetchObserveMetricsAsync(
+        graphqlClient,
+        projectId,
+        metricNames,
+        platforms,
+        startTime,
+        endTime
+      );
+
+    const argumentsStat = flags.stat?.length
+      ? Array.from(new Set(flags.stat.map(resolveStatKey)))
+      : undefined;
+
+    if (flags.json) {
+      const stats: StatisticKey[] = argumentsStat ?? DEFAULT_STATS_JSON;
+      printJsonOnlyOutput(
+        buildObserveMetricsJson(
+          metricsMap,
+          metricNames,
+          stats,
+          totalEventCounts,
+          buildNumbersMap,
+          updateIdsMap
+        )
+      );
+    } else {
+      const stats: StatisticKey[] = argumentsStat ?? DEFAULT_STATS_TABLE;
+      Log.addNewLineIfNone();
+      Log.log(
+        buildObserveMetricsTable(metricsMap, metricNames, stats, {
+          daysBack,
+          buildNumbersMap,
+          totalEventCounts,
+        })
+      );
+    }
+  }
+}
@@ -1,63 +1,61 @@
-import { Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';

 import EasCommand from '../../commandUtils/EasCommand';
+import { EasCommandError } from '../../commandUtils/errors';
 import { EasNonInteractiveAndJsonFlags } from '../../commandUtils/flags';
+import { getLimitFlagWithCustomValues } from '../../commandUtils/pagination';
 import Log from '../../log';
-import { fetchObserveMetricsAsync } from '../../observe/fetchMetrics';
 import {
+  EventsOrderPreset,
+  fetchObserveEventsAsync,
+  fetchTotalEventCountAsync,
+  resolveOrderBy,
+} from '../../observe/fetchEvents';
+import {
+  ObserveAfterFlag,
+  ObserveAppVersionFlag,
  ObservePlatformFlag,
  ObserveProjectIdFlag,
  ObserveTimeRangeFlags,
+  ObserveUpdateIdFlag,
 } from '../../observe/flags';
-import {
-  StatisticKey,
-  buildObserveMetricsJson,
-  buildObserveMetricsTable,
-  resolveStatKey,
-} from '../../observe/formatMetrics';
-import { METRIC_ALIASES, resolveMetricName } from '../../observe/metricNames';
-import { appPlatformsFromFlag } from '../../observe/platforms';
+import { METRIC_ALIASES, METRIC_SHORT_NAMES, resolveMetricName } from '../../observe/metricNames';
+import { buildObserveEventsJson, buildObserveEventsTable } from '../../observe/formatEvents';
+import { appObservePlatformFromFlag, appPlatformsFromFlag } from '../../observe/platforms';
 import { resolveObserveCommandContextAsync } from '../../observe/resolveProjectContext';
 import { resolveTimeRange } from '../../observe/startAndEndTime';
+import { selectAsync } from '../../prompts';
 import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';

-const DEFAULT_METRICS = [
-  'expo.app_startup.cold_launch_time',
-  'expo.app_startup.warm_launch_time',
-  'expo.app_startup.tti',
-  'expo.app_startup.ttr',
-  'expo.app_startup.bundle_load_time',
-];
-
-const DEFAULT_STATS_TABLE: StatisticKey[] = ['median', 'eventCount'];
-const DEFAULT_STATS_JSON: StatisticKey[] = [
-  'min',
-  'median',
-  'max',
-  'average',
-  'p80',
-  'p90',
-  'p99',
-  'eventCount',
-];
+const DEFAULT_EVENTS_LIMIT = 10;

 export default class ObserveMetrics extends EasCommand {
-  static override hidden = true;
-  static override description = 'display app performance metrics grouped by app version';
+  static override description = 'display individual performance metric samples ordered by value';
+
+  static override args = {
+    metric: Args.string({
+      description: 'Metric to query (e.g. tti, cold_launch)',
+      required: false,
+      options: Object.keys(METRIC_ALIASES),
+    }),
+  };

  static override flags = {
+    sort: Flags.option({
+      description: 'Sort order for events',
+      options: Object.values(EventsOrderPreset).map(s => s.toLowerCase()),
+      required: false,
+      default: EventsOrderPreset.Oldest.valueOf().toLowerCase(),
+    })(),
    ...ObservePlatformFlag,
-    metric: Flags.option({
-      description: 'Metric name to display (can be specified multiple times).',
-      multiple: true,
-      options: Object.keys(METRIC_ALIASES),
-    })(),
-    stat: Flags.option({
-      description: 'Statistic to display per metric (can be specified multiple times)',
-      multiple: true,
-      options: DEFAULT_STATS_JSON,
-    })(),
+    ...ObserveAfterFlag,
+    limit: getLimitFlagWithCustomValues({
+      defaultTo: DEFAULT_EVENTS_LIMIT,
+      limit: 100,
+    }),
    ...ObserveTimeRangeFlags,
+    ...ObserveAppVersionFlag,
+    ...ObserveUpdateIdFlag,
    ...ObserveProjectIdFlag,
    ...EasNonInteractiveAndJsonFlags,
  };
@@ -72,7 +70,7 @@ export default class ObserveMetrics extends EasCommand {
  };

  async runAsync(): Promise<void> {
-    const { flags } = await this.parse(ObserveMetrics);
+    const { flags, args } = await this.parse(ObserveMetrics);

    const { projectId, graphqlClient } = await resolveObserveCommandContextAsync({
      command: this,
@@ -84,52 +82,63 @@ export default class ObserveMetrics extends EasCommand {

    if (flags.json) {
      enableJsonOutput();
-    } else {
-      Log.warn('EAS Observe is in preview and subject to breaking changes.');
    }

-    const metricNames = flags.metric?.length
-      ? flags.metric.map(resolveMetricName)
-      : DEFAULT_METRICS;
+    let metricName: string;
+    if (args.metric) {
+      metricName = resolveMetricName(args.metric);
+    } else if (flags['non-interactive']) {
+      throw new EasCommandError(
+        'A metric argument is required in non-interactive mode. Available metrics: ' +
+          Object.keys(METRIC_ALIASES).join(', ')
+      );
+    } else {
+      const choices = Object.entries(METRIC_SHORT_NAMES).map(([fullName, displayName]) => ({
+        title: `${displayName} (${fullName})`,
+        value: fullName,
+      }));
+      metricName = await selectAsync('Select a metric', choices);
+    }
+    const orderBy = resolveOrderBy(flags.sort);

    const { daysBack, startTime, endTime } = resolveTimeRange(flags);

+    const platform = appObservePlatformFromFlag(flags.platform);
    const platforms = appPlatformsFromFlag(flags.platform);

-    const { metricsMap, buildNumbersMap, updateIdsMap, totalEventCounts } =
-      await fetchObserveMetricsAsync(
+    const [{ events, pageInfo }, totalEventCount] = await Promise.all([
+      fetchObserveEventsAsync(graphqlClient, projectId, {
+        metricName,
+        orderBy,
+        limit: flags.limit ?? DEFAULT_EVENTS_LIMIT,
+        ...(flags.after && { after: flags.after }),
+        startTime,
+        endTime,
+        platform,
+        appVersion: flags['app-version'],
+        updateId: flags['update-id'],
+      }),
+      fetchTotalEventCountAsync(
        graphqlClient,
        projectId,
-        metricNames,
+        metricName,
        platforms,
        startTime,
        endTime
-      );
-
-    const argumentsStat = flags.stat?.length
-      ? Array.from(new Set(flags.stat.map(resolveStatKey)))
-      : undefined;
+      ),
+    ]);

    if (flags.json) {
-      const stats: StatisticKey[] = argumentsStat ?? DEFAULT_STATS_JSON;
-      printJsonOnlyOutput(
-        buildObserveMetricsJson(
-          metricsMap,
-          metricNames,
-          stats,
-          totalEventCounts,
-          buildNumbersMap,
-          updateIdsMap
-        )
-      );
+      printJsonOnlyOutput(buildObserveEventsJson(events, pageInfo));
    } else {
-      const stats: StatisticKey[] = argumentsStat ?? DEFAULT_STATS_TABLE;
      Log.addNewLineIfNone();
      Log.log(
-        buildObserveMetricsTable(metricsMap, metricNames, stats, {
+        buildObserveEventsTable(events, pageInfo, {
+          metricName,
          daysBack,
-          buildNumbersMap,
-          totalEventCounts,
+          startTime,
+          endTime,
+          totalEventCount,
        })
      );
    }
@@ -34,7 +34,6 @@ const DEFAULT_STATS_TABLE: NavigationStatKey[] = ['median', 'count'];
 const DEFAULT_STATS_JSON: NavigationStatKey[] = ['median', 'p90', 'count'];

 export default class ObserveRoutes extends EasCommand {
-  static override hidden = true;
  static override description =
    'display app navigation route metrics (Cold TTR, Warm TTR, TTI) grouped by route name';

@@ -93,8 +92,6 @@ export default class ObserveRoutes extends EasCommand {

    if (flags.json) {
      enableJsonOutput();
-    } else {
-      Log.warn('EAS Observe is in preview and subject to breaking changes.');
    }

    const metricNames = flags.metric?.length
@@ -14,7 +14,6 @@ import { resolveTimeRange } from '../../observe/startAndEndTime';
 import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';

 export default class ObserveVersions extends EasCommand {
-  static override hidden = true;
  static override description = 'display app versions with build and update details';

  static override flags = {
@@ -46,8 +45,6 @@ export default class ObserveVersions extends EasCommand {

    if (flags.json) {
      enableJsonOutput();
-    } else {
-      Log.warn('EAS Observe is in preview and subject to breaking changes.');
    }

    const { startTime, endTime } = resolveTimeRange(flags);
@@ -0,0 +1,134 @@
+import { loadEnvFiles, loadProjectEnv } from '@expo/env';
+import spawnAsync from '@expo/spawn-async';
+import { Config } from '@oclif/core';
+
+import SimulatorExec from '../exec';
+
+jest.mock('@expo/env', () => ({
+  loadEnvFiles: jest.fn(),
+  loadProjectEnv: jest.fn(),
+}));
+jest.mock('@expo/spawn-async');
+
+function getMockOclifConfig(): Config {
+  const config = new Config({ root: __dirname });
+  config.runHook = async () => ({
+    failures: [],
+    successes: [],
+  });
+  return config;
+}
+
+describe(SimulatorExec, () => {
+  const mockConfig = getMockOclifConfig();
+  const projectDir = '/test/project';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.mocked(spawnAsync).mockResolvedValue({} as never);
+  });
+
+  function createCommand(argv: string[]): {
+    command: SimulatorExec;
+    getContextAsync: jest.SpyInstance;
+  } {
+    const command = new SimulatorExec(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    const getContextAsync = jest.spyOn(command, 'getContextAsync').mockResolvedValue({
+      projectDir,
+    });
+    return { command, getContextAsync };
+  }
+
+  it('loads local env files and spawns the supplied command with inherited stdio', async () => {
+    const { command, getContextAsync } = createCommand(['agent-device', 'touch', '@e2']);
+
+    await command.runAsync();
+
+    expect(getContextAsync).toHaveBeenCalledWith(SimulatorExec, {
+      nonInteractive: true,
+    });
+    expect(loadProjectEnv).toHaveBeenCalledWith(projectDir, { silent: true });
+    expect(loadEnvFiles).toHaveBeenCalledWith([`${projectDir}/.env.eas-simulator`], {
+      force: true,
+    });
+    expect(spawnAsync).toHaveBeenCalledWith('agent-device', ['touch', '@e2'], {
+      stdio: 'inherit',
+      env: process.env,
+    });
+  });
+
+  it('passes through command flags as args', async () => {
+    const { command } = createCommand([
+      'agent-device',
+      'screenshot',
+      '/test/path.png',
+      '--format',
+      'png',
+    ]);
+
+    await command.runAsync();
+
+    expect(spawnAsync).toHaveBeenCalledWith(
+      'agent-device',
+      ['screenshot', '/test/path.png', '--format', 'png'],
+      {
+        stdio: 'inherit',
+        env: process.env,
+      }
+    );
+  });
+
+  it('does not emit an oclif unparsed arguments warning', async () => {
+    const { command } = createCommand(['echo', '"test"']);
+    const emitWarningSpy = jest.spyOn(process, 'emitWarning').mockImplementation();
+    jest.spyOn(command, 'run').mockImplementation(async () => {
+      await command.runAsync();
+    });
+    jest.spyOn(command, 'finally').mockResolvedValue(undefined);
+
+    try {
+      // @ts-expect-error _run is internal to oclif, but it is where the unparsed warning is emitted.
+      await command._run();
+
+      const emittedUnparsedCommandWarning = emitWarningSpy.mock.calls.some(([warning, options]) => {
+        return (
+          typeof warning === 'string' &&
+          warning.includes('did not parse its arguments') &&
+          typeof options === 'object' &&
+          options !== null &&
+          'code' in options &&
+          options.code === 'UnparsedCommand'
+        );
+      });
+      expect(emittedUnparsedCommandWarning).toBe(false);
+    } finally {
+      emitWarningSpy.mockRestore();
+    }
+  });
+
+  it('throws a helpful error when no command is provided', async () => {
+    const { command, getContextAsync } = createCommand([]);
+
+    await expect(command.runAsync()).rejects.toThrow(
+      'No command provided. Run `eas simulator:exec <command> [args...]`.'
+    );
+    expect(getContextAsync).not.toHaveBeenCalled();
+    expect(loadProjectEnv).not.toHaveBeenCalled();
+    expect(loadEnvFiles).not.toHaveBeenCalled();
+    expect(spawnAsync).not.toHaveBeenCalled();
+  });
+
+  it('loads simulator-specific env after regular env files', async () => {
+    const { command } = createCommand(['agent-device', 'touch', '@e2']);
+    await command.runAsync();
+
+    expect(loadProjectEnv).toHaveBeenCalledWith(projectDir, { silent: true });
+    expect(loadEnvFiles).toHaveBeenCalledWith([`${projectDir}/.env.eas-simulator`], {
+      force: true,
+    });
+    expect(jest.mocked(loadProjectEnv).mock.invocationCallOrder[0]).toBeLessThan(
+      jest.mocked(loadEnvFiles).mock.invocationCallOrder[0]
+    );
+  });
+});
@@ -8,11 +8,20 @@ import {
  JobRunStatus,
 } from '../../../graphql/generated';
 import { DeviceRunSessionQuery } from '../../../graphql/queries/DeviceRunSessionQuery';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+} from '../../../simulator/env';
 import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
 import SimulatorGet from '../get';

 jest.mock('../../../graphql/queries/DeviceRunSessionQuery');
 jest.mock('../../../log');
+jest.mock('../../../simulator/env', () => ({
+  ...jest.requireActual('../../../simulator/env'),
+  loadSimulatorEnvAsync: jest.fn(),
+}));
 jest.mock('../../../ora', () => ({
  ora: jest.fn(() => {
    const spinner = {
@@ -30,6 +39,7 @@ type DeviceRunSessionById = DeviceRunSessionByIdQuery['deviceRunSessions']['byId

 const mockByIdAsync = jest.mocked(DeviceRunSessionQuery.byIdAsync);
 const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
+const mockLoadSimulatorEnvironmentVariablesAsync = jest.mocked(loadSimulatorEnvAsync);
 const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);

 function makeDeviceRunSession(overrides: Partial<DeviceRunSessionById> = {}): DeviceRunSessionById {
@@ -71,9 +81,11 @@ function getMockOclifConfig(): Config {
 describe(SimulatorGet, () => {
  const graphqlClient = {} as ExpoGraphqlClient;
  const mockConfig = getMockOclifConfig();
+  const projectDir = '/test/project';

  beforeEach(() => {
    jest.clearAllMocks();
+    mockLoadSimulatorEnvironmentVariablesAsync.mockResolvedValue();
  });

  function createCommand(argv: string[]): {
@@ -84,6 +96,7 @@ describe(SimulatorGet, () => {
    // @ts-expect-error getContextAsync is protected
    const getContextAsync = jest.spyOn(command, 'getContextAsync').mockResolvedValue({
      loggedIn: { graphqlClient },
+      projectDir,
    });
    return { command, getContextAsync };
  }
@@ -96,6 +109,7 @@ describe(SimulatorGet, () => {
    await command.runAsync();

    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockLoadSimulatorEnvironmentVariablesAsync).toHaveBeenCalledWith(projectDir);
    expect(getContextAsync).toHaveBeenCalledWith(SimulatorGet, {
      nonInteractive: true,
    });
@@ -108,4 +122,46 @@ describe(SimulatorGet, () => {
      remoteConfig: session.remoteConfig,
    });
  });
+
+  it(`uses ${EAS_SIMULATOR_SESSION_ID} from simulator env when --id is not passed`, async () => {
+    const previousDeviceRunSessionId = process.env[EAS_SIMULATOR_SESSION_ID];
+    const session = makeDeviceRunSession({ id: 'session-from-env' });
+    mockByIdAsync.mockResolvedValue(session);
+    process.env[EAS_SIMULATOR_SESSION_ID] = 'session-from-env';
+
+    try {
+      const { command } = createCommand([]);
+      await command.runAsync();
+
+      expect(mockLoadSimulatorEnvironmentVariablesAsync).toHaveBeenCalledWith(projectDir);
+      expect(mockByIdAsync).toHaveBeenCalledWith(graphqlClient, 'session-from-env');
+    } finally {
+      if (previousDeviceRunSessionId === undefined) {
+        delete process.env[EAS_SIMULATOR_SESSION_ID];
+      } else {
+        process.env[EAS_SIMULATOR_SESSION_ID] = previousDeviceRunSessionId;
+      }
+    }
+  });
+
+  it('throws a helpful error when no simulator session ID is available', async () => {
+    const previousDeviceRunSessionId = process.env[EAS_SIMULATOR_SESSION_ID];
+    delete process.env[EAS_SIMULATOR_SESSION_ID];
+
+    try {
+      const { command } = createCommand([]);
+
+      await expect(command.runAsync()).rejects.toThrow(
+        `No simulator session ID provided. Pass --id, or run \`eas simulator:start\` first to write ${SIMULATOR_DOTENV_FILE_NAME}.`
+      );
+      expect(mockLoadSimulatorEnvironmentVariablesAsync).toHaveBeenCalledWith(projectDir);
+      expect(mockByIdAsync).not.toHaveBeenCalled();
+    } finally {
+      if (previousDeviceRunSessionId === undefined) {
+        delete process.env[EAS_SIMULATOR_SESSION_ID];
+      } else {
+        process.env[EAS_SIMULATOR_SESSION_ID] = previousDeviceRunSessionId;
+      }
+    }
+  });
 });
@@ -0,0 +1,317 @@
+import { Config } from '@oclif/core';
+import * as fs from 'fs-extra';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import {
+  AppPlatform,
+  CreateDeviceRunSessionMutation,
+  DeviceRunSessionByIdQuery,
+  DeviceRunSessionStatus,
+  DeviceRunSessionType,
+  JobRunStatus,
+} from '../../../graphql/generated';
+import { DeviceRunSessionMutation } from '../../../graphql/mutations/DeviceRunSessionMutation';
+import { DeviceRunSessionQuery } from '../../../graphql/queries/DeviceRunSessionQuery';
+import Log from '../../../log';
+import { ora } from '../../../ora';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_HEADER,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+  resetSimulatorEnvAsync,
+} from '../../../simulator/env';
+import SimulatorStart from '../start';
+
+jest.mock('fs-extra');
+jest.mock('../../../graphql/mutations/DeviceRunSessionMutation');
+jest.mock('../../../graphql/queries/DeviceRunSessionQuery');
+jest.mock('../../../log', () => ({
+  __esModule: true,
+  default: {
+    debug: jest.fn(),
+    log: jest.fn(),
+    newLine: jest.fn(),
+    warn: jest.fn(),
+    withTick: jest.fn(),
+  },
+  link: jest.fn((url: string) => url),
+}));
+jest.mock('../../../simulator/env', () => ({
+  ...jest.requireActual('../../../simulator/env'),
+  loadSimulatorEnvAsync: jest.fn(),
+  resetSimulatorEnvAsync: jest.fn(),
+}));
+jest.mock('../../../ora', () => ({
+  ora: jest.fn(() => {
+    const spinner = {
+      fail: jest.fn(),
+      start: jest.fn(),
+      succeed: jest.fn(),
+    };
+    spinner.start.mockReturnValue(spinner);
+    return spinner;
+  }),
+}));
+
+type CreatedDeviceRunSession =
+  CreateDeviceRunSessionMutation['deviceRunSession']['createDeviceRunSession'];
+type DeviceRunSessionById = DeviceRunSessionByIdQuery['deviceRunSessions']['byId'];
+
+const graphqlClient = {} as ExpoGraphqlClient;
+const projectDir = '/test/project';
+const simulatorDotenvPath = `${projectDir}/.env.eas-simulator`;
+const jobRunUrl = 'https://expo.dev/accounts/testuser/projects/testapp/job-runs/job-123';
+
+const mockCreateDeviceRunSessionAsync = jest.mocked(
+  DeviceRunSessionMutation.createDeviceRunSessionAsync
+);
+const mockByIdAsync = jest.mocked(DeviceRunSessionQuery.byIdAsync);
+const mockLoadSimulatorEnvAsync = jest.mocked(loadSimulatorEnvAsync);
+const mockResetSimulatorEnvAsync = jest.mocked(resetSimulatorEnvAsync);
+const mockOra = jest.mocked(ora);
+
+function makeCreatedDeviceRunSession(
+  overrides: Partial<CreatedDeviceRunSession> = {}
+): CreatedDeviceRunSession {
+  return {
+    id: 'session-123',
+    status: DeviceRunSessionStatus.InProgress,
+    app: {
+      id: 'app-123',
+      slug: 'testapp',
+      ownerAccount: {
+        id: 'account-123',
+        name: 'testuser',
+      },
+    },
+    turtleJobRun: {
+      id: 'job-123',
+    },
+    ...overrides,
+  };
+}
+
+function makeDeviceRunSession(overrides: Partial<DeviceRunSessionById> = {}): DeviceRunSessionById {
+  return {
+    id: 'session-123',
+    status: DeviceRunSessionStatus.InProgress,
+    type: DeviceRunSessionType.AgentDevice,
+    app: {
+      id: 'app-123',
+      slug: 'testapp',
+      ownerAccount: {
+        id: 'account-123',
+        name: 'testuser',
+      },
+    },
+    remoteConfig: {
+      __typename: 'AgentDeviceRunSessionRemoteConfig',
+      agentDeviceRemoteSessionUrl: 'https://agent.example.com',
+      agentDeviceRemoteSessionToken: 'token-123',
+      webPreviewUrl: 'https://preview.example.com',
+    },
+    turtleJobRun: {
+      id: 'job-123',
+      status: JobRunStatus.InProgress,
+    },
+    ...overrides,
+  };
+}
+
+function getMockOclifConfig(): Config {
+  const config = new Config({ root: __dirname });
+  config.runHook = async () => ({
+    failures: [],
+    successes: [],
+  });
+  return config;
+}
+
+describe(SimulatorStart, () => {
+  const mockConfig = getMockOclifConfig();
+  const previousDeviceRunSessionId = process.env[EAS_SIMULATOR_SESSION_ID];
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    delete process.env[EAS_SIMULATOR_SESSION_ID];
+    mockCreateDeviceRunSessionAsync.mockResolvedValue(makeCreatedDeviceRunSession());
+    mockByIdAsync.mockResolvedValue(makeDeviceRunSession());
+    mockLoadSimulatorEnvAsync.mockResolvedValue();
+    mockResetSimulatorEnvAsync.mockResolvedValue();
+    jest.mocked(fs.writeFile).mockResolvedValue(undefined as never);
+  });
+
+  afterAll(() => {
+    if (previousDeviceRunSessionId === undefined) {
+      delete process.env[EAS_SIMULATOR_SESSION_ID];
+    } else {
+      process.env[EAS_SIMULATOR_SESSION_ID] = previousDeviceRunSessionId;
+    }
+  });
+
+  function createCommand(argv: string[]): {
+    command: SimulatorStart;
+    getContextAsync: jest.SpyInstance;
+  } {
+    const command = new SimulatorStart(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    const getContextAsync = jest.spyOn(command, 'getContextAsync').mockResolvedValue({
+      loggedIn: { graphqlClient },
+      projectDir,
+      projectId: 'project-123',
+    });
+    return { command, getContextAsync };
+  }
+
+  it('prints environment variables without saving when outputting env', async () => {
+    const { command, getContextAsync } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--out-config-type',
+      'env',
+    ]);
+    await command.runAsync();
+
+    expect(getContextAsync).toHaveBeenCalledWith(SimulatorStart, {
+      nonInteractive: true,
+    });
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(graphqlClient, {
+      appId: 'project-123',
+      packageVersion: undefined,
+      platform: AppPlatform.Ios,
+      type: DeviceRunSessionType.AgentDevice,
+    });
+    expect(fs.writeFile).not.toHaveBeenCalled();
+    expect(mockOra.mock.results[0]?.value.succeed).toHaveBeenCalledWith(
+      `Device run session created (id: session-123) ${jobRunUrl}`
+    );
+    expect(Log.log).toHaveBeenCalledWith(
+      expect.stringContaining("export AGENT_DEVICE_DAEMON_BASE_URL='https://agent.example.com'")
+    );
+  });
+
+  it('writes .env.eas-simulator with the environment variables by default', async () => {
+    const { command } = createCommand(['--platform', 'ios', '--non-interactive']);
+    await command.runAsync();
+
+    expect(mockLoadSimulatorEnvAsync).toHaveBeenCalledWith(projectDir);
+    expect(fs.writeFile).toHaveBeenNthCalledWith(
+      1,
+      simulatorDotenvPath,
+      SIMULATOR_DOTENV_FILE_HEADER + `${EAS_SIMULATOR_SESSION_ID}="session-123"\n`
+    );
+    expect(fs.writeFile).toHaveBeenNthCalledWith(
+      2,
+      simulatorDotenvPath,
+      SIMULATOR_DOTENV_FILE_HEADER +
+        'AGENT_DEVICE_DAEMON_BASE_URL="https://agent.example.com"\n' +
+        'AGENT_DEVICE_DAEMON_AUTH_TOKEN="token-123"\n' +
+        `${EAS_SIMULATOR_SESSION_ID}="session-123"\n`
+    );
+    expect(jest.mocked(fs.writeFile).mock.invocationCallOrder[0]).toBeLessThan(
+      mockByIdAsync.mock.invocationCallOrder[0]
+    );
+    expect(mockOra.mock.results[0]?.value.succeed).toHaveBeenCalledWith(
+      `Device run session created (id: session-123, saved to ${SIMULATOR_DOTENV_FILE_NAME}) ${jobRunUrl}`
+    );
+    expect(Log.withTick).not.toHaveBeenCalled();
+    expect(Log.log).toHaveBeenCalledWith(
+      [
+        '🔑 Run the following to use agent-device with the simulator:',
+        '',
+        'eas simulator:exec agent-device <command>',
+        '',
+        '🌐 Open the following URL in your browser to preview the simulator:',
+        '',
+        'https://preview.example.com',
+      ].join('\n')
+    );
+  });
+
+  it('overwrites .env.eas-simulator when outputting dotenv and the file exists', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--out-config-type',
+      'dotenv',
+    ]);
+    await command.runAsync();
+
+    expect(fs.writeFile).toHaveBeenNthCalledWith(
+      1,
+      simulatorDotenvPath,
+      SIMULATOR_DOTENV_FILE_HEADER + `${EAS_SIMULATOR_SESSION_ID}="session-123"\n`
+    );
+    expect(fs.writeFile).toHaveBeenNthCalledWith(
+      2,
+      simulatorDotenvPath,
+      SIMULATOR_DOTENV_FILE_HEADER +
+        'AGENT_DEVICE_DAEMON_BASE_URL="https://agent.example.com"\n' +
+        'AGENT_DEVICE_DAEMON_AUTH_TOKEN="token-123"\n' +
+        `${EAS_SIMULATOR_SESSION_ID}="session-123"\n`
+    );
+  });
+
+  it(`warns and creates a new session when ${EAS_SIMULATOR_SESSION_ID} is already present by default`, async () => {
+    process.env[EAS_SIMULATOR_SESSION_ID] = 'existing-session';
+
+    const { command } = createCommand(['--platform', 'ios', '--non-interactive']);
+    await command.runAsync();
+
+    expect(Log.warn).toHaveBeenCalledWith(
+      '  Overwriting previous simulator session (id: existing-session). ' +
+        'The previous remote session will continue running until stopped. ' +
+        'To stop it, run: eas simulator:stop --id existing-session'
+    );
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(graphqlClient, {
+      appId: 'project-123',
+      packageVersion: undefined,
+      platform: AppPlatform.Ios,
+      type: DeviceRunSessionType.AgentDevice,
+    });
+  });
+
+  it(`creates a new session when ${EAS_SIMULATOR_SESSION_ID} is present with --force`, async () => {
+    process.env[EAS_SIMULATOR_SESSION_ID] = 'existing-session';
+
+    const { command } = createCommand(['--platform', 'ios', '--non-interactive', '--force']);
+    await command.runAsync();
+
+    expect(Log.warn).toHaveBeenCalledWith(
+      '  Overwriting previous simulator session (id: existing-session). ' +
+        'The previous remote session will continue running until stopped. ' +
+        'To stop it, run: eas simulator:stop --id existing-session'
+    );
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(graphqlClient, {
+      appId: 'project-123',
+      packageVersion: undefined,
+      platform: AppPlatform.Ios,
+      type: DeviceRunSessionType.AgentDevice,
+    });
+  });
+
+  it(`throws when ${EAS_SIMULATOR_SESSION_ID} is already present with --no-force`, async () => {
+    process.env[EAS_SIMULATOR_SESSION_ID] = 'existing-session';
+
+    const { command } = createCommand(['--platform', 'ios', '--non-interactive', '--no-force']);
+    await expect(command.runAsync()).rejects.toThrow(
+      'Existing simulator session in environment. Use --force to create a new device session.'
+    );
+
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('resets .env.eas-simulator when the interactive wait observes the session end', async () => {
+    mockByIdAsync
+      .mockResolvedValueOnce(makeDeviceRunSession())
+      .mockResolvedValueOnce(makeDeviceRunSession({ status: DeviceRunSessionStatus.Stopped }));
+
+    const { command } = createCommand(['--platform', 'ios']);
+    await command.runAsync();
+
+    expect(mockResetSimulatorEnvAsync).toHaveBeenCalledWith(projectDir);
+  });
+});
@@ -0,0 +1,152 @@
+import { Config } from '@oclif/core';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import {
+  DeviceRunSessionStatus,
+  EnsureDeviceRunSessionStoppedMutation,
+} from '../../../graphql/generated';
+import { DeviceRunSessionMutation } from '../../../graphql/mutations/DeviceRunSessionMutation';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+} from '../../../simulator/env';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+import SimulatorStop from '../stop';
+
+jest.mock('../../../graphql/mutations/DeviceRunSessionMutation');
+jest.mock('../../../simulator/env', () => ({
+  ...jest.requireActual('../../../simulator/env'),
+  loadSimulatorEnvAsync: jest.fn(),
+}));
+jest.mock('../../../ora', () => ({
+  ora: jest.fn(() => {
+    const spinner = {
+      fail: jest.fn(),
+      start: jest.fn(),
+      succeed: jest.fn(),
+    };
+    spinner.start.mockReturnValue(spinner);
+    return spinner;
+  }),
+}));
+jest.mock('../../../utils/json');
+
+type StoppedDeviceRunSession =
+  EnsureDeviceRunSessionStoppedMutation['deviceRunSession']['ensureDeviceRunSessionStopped'];
+
+const mockEnsureDeviceRunSessionStoppedAsync = jest.mocked(
+  DeviceRunSessionMutation.ensureDeviceRunSessionStoppedAsync
+);
+const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
+const mockLoadSimulatorEnvironmentVariablesAsync = jest.mocked(loadSimulatorEnvAsync);
+const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);
+
+function makeStoppedDeviceRunSession(
+  overrides: Partial<StoppedDeviceRunSession> = {}
+): StoppedDeviceRunSession {
+  return {
+    id: 'session-123',
+    status: DeviceRunSessionStatus.Stopped,
+    ...overrides,
+  };
+}
+
+function getMockOclifConfig(): Config {
+  const config = new Config({ root: __dirname });
+  config.runHook = async () => ({
+    failures: [],
+    successes: [],
+  });
+  return config;
+}
+
+describe(SimulatorStop, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+  const projectDir = '/test/project';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockEnsureDeviceRunSessionStoppedAsync.mockResolvedValue(makeStoppedDeviceRunSession());
+    mockLoadSimulatorEnvironmentVariablesAsync.mockResolvedValue();
+  });
+
+  function createCommand(argv: string[]): {
+    command: SimulatorStop;
+    getContextAsync: jest.SpyInstance;
+  } {
+    const command = new SimulatorStop(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    const getContextAsync = jest.spyOn(command, 'getContextAsync').mockResolvedValue({
+      loggedIn: { graphqlClient },
+      projectDir,
+    });
+    return { command, getContextAsync };
+  }
+
+  it('emits JSON when --json is passed', async () => {
+    const { command, getContextAsync } = createCommand(['--id', 'session-123', '--json']);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockLoadSimulatorEnvironmentVariablesAsync).toHaveBeenCalledWith(projectDir);
+    expect(getContextAsync).toHaveBeenCalledWith(SimulatorStop, {
+      nonInteractive: true,
+    });
+    expect(mockEnsureDeviceRunSessionStoppedAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      'session-123'
+    );
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalledWith({
+      id: 'session-123',
+      status: DeviceRunSessionStatus.Stopped,
+    });
+  });
+
+  it(`uses ${EAS_SIMULATOR_SESSION_ID} from simulator env when --id is not passed`, async () => {
+    const previousDeviceRunSessionId = process.env[EAS_SIMULATOR_SESSION_ID];
+    process.env[EAS_SIMULATOR_SESSION_ID] = 'session-from-env';
+    mockEnsureDeviceRunSessionStoppedAsync.mockResolvedValue(
+      makeStoppedDeviceRunSession({ id: 'session-from-env' })
+    );
+
+    try {
+      const { command } = createCommand([]);
+      await command.runAsync();
+
+      expect(mockLoadSimulatorEnvironmentVariablesAsync).toHaveBeenCalledWith(projectDir);
+      expect(mockEnsureDeviceRunSessionStoppedAsync).toHaveBeenCalledWith(
+        graphqlClient,
+        'session-from-env'
+      );
+    } finally {
+      if (previousDeviceRunSessionId === undefined) {
+        delete process.env[EAS_SIMULATOR_SESSION_ID];
+      } else {
+        process.env[EAS_SIMULATOR_SESSION_ID] = previousDeviceRunSessionId;
+      }
+    }
+  });
+
+  it('throws a helpful error when no simulator session ID is available', async () => {
+    const previousDeviceRunSessionId = process.env[EAS_SIMULATOR_SESSION_ID];
+    delete process.env[EAS_SIMULATOR_SESSION_ID];
+
+    try {
+      const { command } = createCommand([]);
+
+      await expect(command.runAsync()).rejects.toThrow(
+        `No simulator session ID provided. Pass --id, or run \`eas simulator:start\` first to write ${SIMULATOR_DOTENV_FILE_NAME}.`
+      );
+      expect(mockLoadSimulatorEnvironmentVariablesAsync).toHaveBeenCalledWith(projectDir);
+      expect(mockEnsureDeviceRunSessionStoppedAsync).not.toHaveBeenCalled();
+    } finally {
+      if (previousDeviceRunSessionId === undefined) {
+        delete process.env[EAS_SIMULATOR_SESSION_ID];
+      } else {
+        process.env[EAS_SIMULATOR_SESSION_ID] = previousDeviceRunSessionId;
+      }
+    }
+  });
+});
@@ -0,0 +1,47 @@
+import spawnAsync from '@expo/spawn-async';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import { SIMULATOR_DOTENV_FILE_NAME, loadSimulatorEnvAsync } from '../../simulator/env';
+
+export default class SimulatorExec extends EasCommand {
+  static override hidden = true;
+  static override description = `[EXPERIMENTAL] execute a simulator command with ${SIMULATOR_DOTENV_FILE_NAME} environment loaded`;
+  static override strict = false;
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectDir,
+  };
+
+  private isRunningSubprocess = false;
+
+  async runAsync(): Promise<void> {
+    const rawArgv = [...this.argv];
+    // Required to avoid `Warning: Command exec did not parse its arguments. Did you forget to call 'this.parse'?`
+    await this.parse(SimulatorExec, []);
+
+    const [command, ...args] = rawArgv;
+    if (typeof command !== 'string' || command.length === 0) {
+      throw new Error('No command provided. Run `eas simulator:exec <command> [args...]`.');
+    }
+
+    const { projectDir } = await this.getContextAsync(SimulatorExec, {
+      nonInteractive: true,
+    });
+    await loadSimulatorEnvAsync(projectDir);
+
+    this.isRunningSubprocess = true;
+    await spawnAsync(command, args, {
+      stdio: 'inherit',
+      env: process.env,
+    });
+  }
+
+  protected override catch(err: Error): Promise<any> {
+    // Propagate wrapped command from spawnAsync rejection
+    if (this.isRunningSubprocess) {
+      process.exitCode = process.exitCode ?? (err as any).status ?? 1;
+      return Promise.resolve();
+    }
+    return super.catch(err);
+  }
+}
@@ -10,6 +10,11 @@ import { DeviceRunSessionStatus } from '../../graphql/generated';
 import { DeviceRunSessionQuery } from '../../graphql/queries/DeviceRunSessionQuery';
 import Log, { link } from '../../log';
 import { ora } from '../../ora';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+} from '../../simulator/env';
 import {
  deviceRunSessionTypeToFlagValue,
  formatRemoteSessionInstructions,
@@ -23,14 +28,14 @@ export default class SimulatorGet extends EasCommand {

  static override flags = {
    id: Flags.string({
-      description: 'Device run session ID',
-      required: true,
+      description: `Device run session ID. Defaults to ${SIMULATOR_DOTENV_FILE_NAME}.`,
    }),
    ...EasNonInteractiveAndJsonFlags,
  };

  static override contextDefinition = {
    ...this.ContextOptions.LoggedIn,
+    ...this.ContextOptions.ProjectDir,
  };

  async runAsync(): Promise<void> {
@@ -42,18 +47,27 @@ export default class SimulatorGet extends EasCommand {
    }

    const {
+      projectDir,
      loggedIn: { graphqlClient },
    } = await this.getContextAsync(SimulatorGet, {
      nonInteractive,
    });

-    const fetchSpinner = ora(`Fetching device run session ${flags.id}`).start();
+    await loadSimulatorEnvAsync(projectDir);
+    const flagId = flags.id || process.env[EAS_SIMULATOR_SESSION_ID];
+    if (!flagId) {
+      throw new Error(
+        `No simulator session ID provided. Pass --id, or run \`eas simulator:start\` first to write ${SIMULATOR_DOTENV_FILE_NAME}.`
+      );
+    }
+
+    const fetchSpinner = ora(`Fetching device run session ${flagId}`).start();
    let session;
    try {
-      session = await DeviceRunSessionQuery.byIdAsync(graphqlClient, flags.id);
+      session = await DeviceRunSessionQuery.byIdAsync(graphqlClient, flagId);
      fetchSpinner.succeed(`Fetched device run session ${session.id}`);
    } catch (err) {
-      fetchSpinner.fail(`Failed to fetch device run session ${flags.id}`);
+      fetchSpinner.fail(`Failed to fetch device run session ${flagId}`);
      throw err;
    }

@@ -81,7 +95,7 @@ export default class SimulatorGet extends EasCommand {
    if (session.status === DeviceRunSessionStatus.InProgress) {
      Log.newLine();
      if (session.remoteConfig) {
-        Log.log(formatRemoteSessionInstructions(session.remoteConfig));
+        Log.log(formatRemoteSessionInstructions(session.remoteConfig, 'env'));
      } else {
        Log.log(
          '⏳ Session is starting up — remote config is not available yet. Re-run this command in a moment.'
@@ -1,4 +1,5 @@
 import { Flags } from '@oclif/core';
+import nullthrows from 'nullthrows';

 import { getBareJobRunUrl } from '../../build/utils/url';
 import EasCommand from '../../commandUtils/EasCommand';
@@ -17,18 +18,29 @@ import { DeviceRunSessionMutation } from '../../graphql/mutations/DeviceRunSessi
 import { DeviceRunSessionQuery } from '../../graphql/queries/DeviceRunSessionQuery';
 import Log, { link } from '../../log';
 import { ora } from '../../ora';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+  resetSimulatorEnvAsync,
+  writeSimulatorEnvAsync,
+} from '../../simulator/env';
 import {
  DEVICE_RUN_SESSION_TYPE_BY_FLAG_VALUE,
  DEVICE_RUN_SESSION_TYPE_FLAG_VALUES,
  DeviceRunSessionRemoteConfig,
  formatRemoteSessionInstructions,
+  getRemoteSessionEnvironmentVariables,
 } from '../../simulator/utils';
 import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
 import { sleepAsync } from '../../utils/promise';
-import nullthrows from 'nullthrows';

 const POLL_INTERVAL_MS = 5_000; // 5 seconds
 const POLL_TIMEOUT_MS = 15 * 60 * 1_000; // 15 minutes
+const OUT_CONFIG_TYPE_VALUES = {
+  Env: 'env',
+  Dotenv: 'dotenv',
+} as const;

 export default class SimulatorStart extends EasCommand {
  static override hidden = true;
@@ -50,11 +62,23 @@ export default class SimulatorStart extends EasCommand {
      description:
        'Version of the package backing the device run session (e.g. "0.1.3-alpha.3"). Defaults to "latest" when omitted.',
    }),
+    force: Flags.boolean({
+      description:
+        '[default: true] Create a new device session even when an existing simulator session is present in the environment.',
+      default: true,
+      allowNo: true,
+    }),
+    'out-config-type': Flags.option({
+      description: `How to output simulator connection configuration. Use "env" to print shell exports, or "dotenv" to write ${SIMULATOR_DOTENV_FILE_NAME}.`,
+      options: Object.values(OUT_CONFIG_TYPE_VALUES),
+      default: OUT_CONFIG_TYPE_VALUES.Dotenv,
+    })(),
    ...EasNonInteractiveAndJsonFlags,
  };

  static override contextDefinition = {
    ...this.ContextOptions.ProjectId,
+    ...this.ContextOptions.ProjectDir,
    ...this.ContextOptions.LoggedIn,
  };

@@ -68,11 +92,28 @@ export default class SimulatorStart extends EasCommand {

    const {
      projectId,
+      projectDir,
      loggedIn: { graphqlClient },
    } = await this.getContextAsync(SimulatorStart, {
      nonInteractive,
    });

+    await loadSimulatorEnvAsync(projectDir);
+    const existingDeviceRunSessionId = process.env[EAS_SIMULATOR_SESSION_ID];
+    if (existingDeviceRunSessionId && !flags.force) {
+      throw new Error(
+        `Existing simulator session in environment. Use --force to create a new device session.`
+      );
+    }
+    if (existingDeviceRunSessionId) {
+      Log.warn(
+        `  Overwriting previous simulator session (id: ${existingDeviceRunSessionId}). ` +
+          `The previous remote session will continue running until stopped. ` +
+          `To stop it, run: eas simulator:stop --id ${existingDeviceRunSessionId}`
+      );
+      Log.newLine();
+    }
+
    const platform = flags.platform === 'android' ? AppPlatform.Android : AppPlatform.Ios;

    const createSpinner = ora('🚀 Creating device run session').start();
@@ -88,8 +129,16 @@ export default class SimulatorStart extends EasCommand {
      deviceRunSessionId = session.id;
      const jobRunId = nullthrows(session.turtleJobRun?.id, 'Expected device run session to start');
      jobRunUrl = getBareJobRunUrl(session.app.ownerAccount.name, session.app.slug, jobRunId);
+      const simulatorEnvWritten =
+        !jsonFlag && flags['out-config-type'] === OUT_CONFIG_TYPE_VALUES.Dotenv
+          ? await writeSimulatorEnvSafelyAsync(projectDir, {
+              [EAS_SIMULATOR_SESSION_ID]: deviceRunSessionId,
+            })
+          : false;
      createSpinner.succeed(
-        `Device run session created (id: ${deviceRunSessionId}) ${link(jobRunUrl)}`
+        `Device run session created (id: ${deviceRunSessionId}${
+          simulatorEnvWritten ? `, saved to ${SIMULATOR_DOTENV_FILE_NAME}` : ''
+        }) ${link(jobRunUrl)}`
      );
    } catch (err) {
      createSpinner.fail('Failed to create device run session');
@@ -146,6 +195,13 @@ export default class SimulatorStart extends EasCommand {
      );
    }

+    if (flags['out-config-type'] === OUT_CONFIG_TYPE_VALUES.Dotenv) {
+      await writeSimulatorEnvSafelyAsync(projectDir, {
+        ...getRemoteSessionEnvironmentVariables(remoteConfig),
+        [EAS_SIMULATOR_SESSION_ID]: deviceRunSessionId,
+      });
+    }
+
    if (jsonFlag) {
      printJsonOnlyOutput({
        id: deviceRunSessionId,
@@ -157,7 +213,7 @@ export default class SimulatorStart extends EasCommand {
    }

    Log.newLine();
-    Log.log(formatRemoteSessionInstructions(remoteConfig));
+    Log.log(formatRemoteSessionInstructions(remoteConfig, flags['out-config-type']));
    Log.newLine();

    if (nonInteractive) {
@@ -171,18 +227,38 @@ export default class SimulatorStart extends EasCommand {
      graphqlClient,
      deviceRunSessionId,
      jobRunUrl,
+      projectDir,
    });
  }
 }

+async function writeSimulatorEnvSafelyAsync(
+  projectDir: string,
+  environmentVariables: Record<string, string>
+): Promise<boolean> {
+  try {
+    await writeSimulatorEnvAsync(projectDir, environmentVariables);
+    return true;
+  } catch (err) {
+    Log.warn(
+      `Failed to write simulator environment variables to ${SIMULATOR_DOTENV_FILE_NAME}: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    );
+    return false;
+  }
+}
+
 async function waitForSessionEndOrInterruptAsync({
  graphqlClient,
  deviceRunSessionId,
  jobRunUrl,
+  projectDir,
 }: {
  graphqlClient: ExpoGraphqlClient;
  deviceRunSessionId: string;
  jobRunUrl: string;
+  projectDir: string;
 }): Promise<void> {
  const spinner = ora(
    `Device run session active — press Ctrl+C to stop, or run \`eas simulator:stop --id ${deviceRunSessionId}\` from another shell`
@@ -239,6 +315,7 @@ async function waitForSessionEndOrInterruptAsync({
        jobRunStatus === JobRunStatus.Finished
      ) {
        spinner.succeed(`Device run session ended. ${link(jobRunUrl)}`);
+        await resetSimulatorEnvVerboseAsync(projectDir);
        return;
      }

@@ -252,6 +329,7 @@ async function waitForSessionEndOrInterruptAsync({
    );
    if (stopped) {
      spinner.succeed('Device run session stopped');
+      await resetSimulatorEnvVerboseAsync(projectDir);
    } else {
      spinner.fail(
        `Could not confirm the device run session was stopped. Run \`eas simulator:stop --id ${deviceRunSessionId}\` to terminate it and avoid unexpected charges.`
@@ -262,6 +340,15 @@ async function waitForSessionEndOrInterruptAsync({
  }
 }

+async function resetSimulatorEnvVerboseAsync(projectDir: string): Promise<void> {
+  try {
+    await resetSimulatorEnvAsync(projectDir);
+  } catch (err) {
+    Log.error(`Failed to clean up ${SIMULATOR_DOTENV_FILE_NAME}`);
+    throw err;
+  }
+}
+
 async function ensureDeviceRunSessionStoppedSafelyAsync(
  graphqlClient: ExpoGraphqlClient,
  deviceRunSessionId: string
@@ -7,6 +7,11 @@ import {
 } from '../../commandUtils/flags';
 import { DeviceRunSessionMutation } from '../../graphql/mutations/DeviceRunSessionMutation';
 import { ora } from '../../ora';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+} from '../../simulator/env';
 import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';

 export default class SimulatorStop extends EasCommand {
@@ -16,14 +21,14 @@ export default class SimulatorStop extends EasCommand {

  static override flags = {
    id: Flags.string({
-      description: 'Device run session ID',
-      required: true,
+      description: `Device run session ID. Defaults to ${SIMULATOR_DOTENV_FILE_NAME}.`,
    }),
    ...EasNonInteractiveAndJsonFlags,
  };

  static override contextDefinition = {
    ...this.ContextOptions.LoggedIn,
+    ...this.ContextOptions.ProjectDir,
  };

  async runAsync(): Promise<void> {
@@ -35,25 +40,35 @@ export default class SimulatorStop extends EasCommand {
    }

    const {
+      projectDir,
      loggedIn: { graphqlClient },
    } = await this.getContextAsync(SimulatorStop, {
      nonInteractive,
    });

-    const stopSpinner = ora(`🛑 Stopping device run session ${flags.id}`).start();
+    await loadSimulatorEnvAsync(projectDir);
+    const flagId = flags.id || process.env[EAS_SIMULATOR_SESSION_ID];
+    if (!flagId) {
+      throw new Error(
+        `No simulator session ID provided. Pass --id, or run \`eas simulator:start\` first to write ${SIMULATOR_DOTENV_FILE_NAME}.`
+      );
+    }
+
+    const stopSpinner = ora(`🛑 Stopping device run session ${flagId}`).start();
+    let session;
    try {
-      const session = await DeviceRunSessionMutation.ensureDeviceRunSessionStoppedAsync(
+      session = await DeviceRunSessionMutation.ensureDeviceRunSessionStoppedAsync(
        graphqlClient,
-        flags.id
+        flagId
      );
      stopSpinner.succeed(`🎉 Device run session ${session.id} is ${session.status.toLowerCase()}`);
-
-      if (jsonFlag) {
-        printJsonOnlyOutput({ id: session.id, status: session.status });
-      }
    } catch (err) {
-      stopSpinner.fail(`Failed to stop device run session ${flags.id}`);
+      stopSpinner.fail(`Failed to stop device run session ${flagId}`);
      throw err;
    }
+
+    if (jsonFlag) {
+      printJsonOnlyOutput({ id: session.id, status: session.status });
+    }
  }
 }
@@ -0,0 +1,130 @@
+import { getMockOclifConfig } from '../../../../__tests__/commands/utils';
+import { ExpoGraphqlClient } from '../../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { EmbeddedUpdateMutation } from '../../../../graphql/mutations/EmbeddedUpdateMutation';
+import Log from '../../../../log';
+import * as prompts from '../../../../prompts';
+import * as json from '../../../../utils/json';
+import UpdateEmbeddedDelete from '../delete';
+
+jest.mock('../../../../graphql/mutations/EmbeddedUpdateMutation', () => ({
+  EmbeddedUpdateMutation: { deleteEmbeddedUpdateAsync: jest.fn() },
+}));
+jest.mock('../../../../log');
+jest.mock('../../../../utils/json');
+jest.mock('../../../../prompts');
+
+const mockDelete = jest.mocked(EmbeddedUpdateMutation.deleteEmbeddedUpdateAsync);
+const mockToggleConfirm = jest.mocked(prompts.toggleConfirmAsync);
+const mockLogLog = jest.mocked(Log.log);
+const mockLogWithTick = jest.mocked(Log.withTick);
+const mockLogError = jest.mocked(Log.error);
+const mockEnableJsonOutput = jest.mocked(json.enableJsonOutput);
+const mockPrintJson = jest.mocked(json.printJsonOnlyOutput);
+
+const VALID_UUID = 'a1b2c3d4-1234-4000-8000-000000000000';
+
+const MOCK_CONTEXT = {
+  loggedIn: { graphqlClient: {} as ExpoGraphqlClient },
+};
+
+describe(UpdateEmbeddedDelete, () => {
+  const mockConfig = getMockOclifConfig();
+  let processExitSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockDelete.mockResolvedValue({ id: VALID_UUID });
+    mockToggleConfirm.mockResolvedValue(true);
+    processExitSpy = jest.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('process.exit');
+    }) as never);
+  });
+
+  afterEach(() => {
+    processExitSpy.mockRestore();
+  });
+
+  function createCommand(argv: string[]): UpdateEmbeddedDelete {
+    const command = new UpdateEmbeddedDelete(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    jest.spyOn(command, 'getContextAsync').mockResolvedValue(MOCK_CONTEXT);
+    return command;
+  }
+
+  it('deletes when the user confirms', async () => {
+    await createCommand([VALID_UUID]).run();
+
+    expect(mockToggleConfirm).toHaveBeenCalledTimes(1);
+    expect(mockDelete).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      id: VALID_UUID,
+    });
+    expect(mockLogWithTick).toHaveBeenCalledWith(`Deleted embedded update ${VALID_UUID}`);
+  });
+
+  it('skips confirmation in non-interactive mode', async () => {
+    await createCommand([VALID_UUID, '--non-interactive']).run();
+
+    expect(mockToggleConfirm).not.toHaveBeenCalled();
+    expect(mockDelete).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      id: VALID_UUID,
+    });
+  });
+
+  it('aborts (process.exit) without calling the mutation when the user declines', async () => {
+    mockToggleConfirm.mockResolvedValue(false);
+    await expect(createCommand([VALID_UUID]).run()).rejects.toThrow('process.exit');
+
+    expect(mockDelete).not.toHaveBeenCalled();
+    expect(mockLogWithTick).not.toHaveBeenCalled();
+  });
+
+  it('--json prints { id } and skips the human-readable success line', async () => {
+    await createCommand([VALID_UUID, '--non-interactive', '--json']).run();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockPrintJson).toHaveBeenCalledWith({ id: VALID_UUID });
+    expect(mockLogWithTick).not.toHaveBeenCalled();
+  });
+
+  it('rethrows unexpected mutation errors', async () => {
+    const boom = new Error('boom');
+    mockDelete.mockRejectedValue(boom);
+    await expect(createCommand([VALID_UUID, '--non-interactive']).run()).rejects.toThrow('boom');
+  });
+
+  it('succeeds for an unknown id (server best-effort)', async () => {
+    // Server returns { id } even when nothing was deleted, so we should still tick.
+    await createCommand([VALID_UUID, '--non-interactive']).run();
+    expect(mockLogWithTick).toHaveBeenCalledWith(`Deleted embedded update ${VALID_UUID}`);
+  });
+
+  it('prints an explanatory message before prompting (interactive)', async () => {
+    await createCommand([VALID_UUID]).run();
+    const lines = mockLogLog.mock.calls.map(c => String(c[0])).join('\n');
+    expect(lines).toContain(`permanently delete embedded update: "${VALID_UUID}"`);
+    expect(lines).toContain('Diff patches already generated');
+    expect(lines).toContain('re-upload');
+  });
+
+  it('logs a cancel message when the user declines', async () => {
+    mockToggleConfirm.mockResolvedValue(false);
+    await expect(createCommand([VALID_UUID]).run()).rejects.toThrow('process.exit');
+    expect(mockLogError).toHaveBeenCalledWith(
+      `Canceled deletion of embedded update: "${VALID_UUID}".`
+    );
+  });
+
+  it('passes the id through to deleteEmbeddedUpdateAsync', async () => {
+    await createCommand([VALID_UUID, '--non-interactive']).run();
+    expect(mockDelete).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      id: VALID_UUID,
+    });
+  });
+
+  it('--json + --non-interactive: skips prompt, skips tick, prints { id }', async () => {
+    await createCommand([VALID_UUID, '--non-interactive', '--json']).run();
+    expect(mockToggleConfirm).not.toHaveBeenCalled();
+    expect(mockLogWithTick).not.toHaveBeenCalled();
+    expect(mockPrintJson).toHaveBeenCalledWith({ id: VALID_UUID });
+  });
+});
@@ -0,0 +1,280 @@
+import { getMockOclifConfig } from '../../../../__tests__/commands/utils';
+import { ExpoGraphqlClient } from '../../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { AppPlatform } from '../../../../graphql/generated';
+import { ChannelQuery } from '../../../../graphql/queries/ChannelQuery';
+import {
+  EmbeddedUpdateFragment,
+  EmbeddedUpdateQuery,
+} from '../../../../graphql/queries/EmbeddedUpdateQuery';
+import Log from '../../../../log';
+import { selectAsync } from '../../../../prompts';
+import * as json from '../../../../utils/json';
+import UpdateEmbeddedList from '../list';
+
+jest.mock('../../../../graphql/queries/EmbeddedUpdateQuery', () => ({
+  EmbeddedUpdateQuery: { viewPaginatedAsync: jest.fn() },
+}));
+jest.mock('../../../../graphql/queries/ChannelQuery', () => ({
+  ChannelQuery: { viewUpdateChannelsOnAppAsync: jest.fn() },
+}));
+jest.mock('../../../../prompts');
+jest.mock('../../../../log');
+jest.mock('../../../../utils/json');
+
+const mockPaginated = jest.mocked(EmbeddedUpdateQuery.viewPaginatedAsync);
+const mockViewChannels = jest.mocked(ChannelQuery.viewUpdateChannelsOnAppAsync);
+const mockSelectAsync = jest.mocked(selectAsync);
+const mockLogLog = jest.mocked(Log.log);
+const mockEnableJsonOutput = jest.mocked(json.enableJsonOutput);
+const mockPrintJson = jest.mocked(json.printJsonOnlyOutput);
+
+const MOCK_CONTEXT = {
+  projectId: 'project-123',
+  loggedIn: { graphqlClient: {} as ExpoGraphqlClient },
+};
+
+const ROW_A: EmbeddedUpdateFragment = {
+  id: 'aaaaaaaa-1111-4000-8000-000000000001',
+  platform: AppPlatform.Ios,
+  runtimeVersion: '1.0.0',
+  channel: 'production',
+  createdAt: '2026-05-29T00:00:00Z',
+  launchAsset: { id: 'asset-a', fileSize: 1024, finalFileSize: 768, fileSHA256: 'abc123' },
+};
+const ROW_B: EmbeddedUpdateFragment = {
+  id: 'bbbbbbbb-2222-4000-8000-000000000002',
+  platform: AppPlatform.Android,
+  runtimeVersion: '1.0.1',
+  channel: 'preview',
+  createdAt: '2026-05-30T00:00:00Z',
+  launchAsset: { id: 'asset-b', fileSize: 2048, finalFileSize: null, fileSHA256: 'def456' },
+};
+
+function emptyConnection(): {
+  edges: { cursor: string; node: EmbeddedUpdateFragment }[];
+  pageInfo: {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor: string | null;
+    endCursor: string | null;
+  };
+} {
+  return {
+    edges: [],
+    pageInfo: { hasNextPage: false, hasPreviousPage: false, startCursor: null, endCursor: null },
+  };
+}
+
+describe(UpdateEmbeddedList, () => {
+  const mockConfig = getMockOclifConfig();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Default: no channels on the project (skips the prompt).
+    mockViewChannels.mockResolvedValue([]);
+  });
+
+  function createCommand(argv: string[]): UpdateEmbeddedList {
+    const command = new UpdateEmbeddedList(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    jest.spyOn(command, 'getContextAsync').mockResolvedValue(MOCK_CONTEXT);
+    return command;
+  }
+
+  it('prints each row when results exist', async () => {
+    mockPaginated.mockResolvedValue({
+      edges: [
+        { cursor: 'c1', node: ROW_A },
+        { cursor: 'c2', node: ROW_B },
+      ],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false, startCursor: 'c1', endCursor: 'c2' },
+    });
+    await createCommand(['--non-interactive']).run();
+
+    expect(mockPaginated).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      appId: MOCK_CONTEXT.projectId,
+      filter: undefined,
+      first: 25,
+      after: undefined,
+    });
+    expect(mockLogLog.mock.calls.some(c => String(c[0]).includes(ROW_A.id))).toBe(true);
+    expect(mockLogLog.mock.calls.some(c => String(c[0]).includes(ROW_B.id))).toBe(true);
+  });
+
+  it('prints empty message when no results', async () => {
+    mockPaginated.mockResolvedValue(emptyConnection());
+    await createCommand(['--non-interactive']).run();
+    expect(mockLogLog).toHaveBeenCalledWith('No embedded updates found.');
+  });
+
+  it('--json prints connection payload and skips formatted output', async () => {
+    mockPaginated.mockResolvedValue({
+      edges: [{ cursor: 'c1', node: ROW_A }],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false, startCursor: 'c1', endCursor: 'c1' },
+    });
+    await createCommand(['--json', '--non-interactive']).run();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockPrintJson).toHaveBeenCalledWith({
+      embeddedUpdates: [ROW_A],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false, startCursor: 'c1', endCursor: 'c1' },
+    });
+    expect(mockLogLog.mock.calls.every(c => !String(c[0]).includes(ROW_A.id))).toBe(true);
+  });
+
+  it('passes filter when flags supplied', async () => {
+    mockPaginated.mockResolvedValue(emptyConnection());
+    await createCommand([
+      '--non-interactive',
+      '--platform',
+      'ios',
+      '--runtime-version',
+      '1.2.0',
+      '--channel',
+      'preview',
+    ]).run();
+
+    expect(mockPaginated).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      appId: MOCK_CONTEXT.projectId,
+      filter: { platform: AppPlatform.Ios, runtimeVersion: '1.2.0', channel: 'preview' },
+      first: 25,
+      after: undefined,
+    });
+  });
+
+  it('shows next-page hint when hasNextPage', async () => {
+    mockPaginated.mockResolvedValue({
+      edges: [{ cursor: 'c1', node: ROW_A }],
+      pageInfo: { hasNextPage: true, hasPreviousPage: false, startCursor: 'c1', endCursor: 'c1' },
+    });
+    await createCommand(['--non-interactive']).run();
+
+    expect(mockLogLog.mock.calls.some(c => String(c[0]).includes('--after-cursor c1'))).toBe(true);
+  });
+
+  it('prompts for channel in interactive mode and applies the selected channel', async () => {
+    mockViewChannels.mockResolvedValue([
+      { id: 'ch1', name: 'production' } as any,
+      { id: 'ch2', name: 'preview' } as any,
+    ]);
+    mockSelectAsync.mockResolvedValue('preview');
+    mockPaginated.mockResolvedValue(emptyConnection());
+
+    await createCommand([]).run();
+
+    expect(mockSelectAsync).toHaveBeenCalledTimes(1);
+    expect(mockPaginated).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      appId: MOCK_CONTEXT.projectId,
+      filter: { platform: undefined, runtimeVersion: undefined, channel: 'preview' },
+      first: 25,
+      after: undefined,
+    });
+  });
+
+  it('skips channel filter when "All channels" is selected', async () => {
+    mockViewChannels.mockResolvedValue([{ id: 'ch1', name: 'production' } as any]);
+    // The sentinel value returned by selectAsync for the "All channels" option.
+    mockSelectAsync.mockResolvedValue('__embedded_update_list__all_channels__');
+    mockPaginated.mockResolvedValue(emptyConnection());
+
+    await createCommand([]).run();
+
+    expect(mockPaginated).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      appId: MOCK_CONTEXT.projectId,
+      filter: undefined,
+      first: 25,
+      after: undefined,
+    });
+  });
+
+  it('skips the channel prompt when --channel is supplied', async () => {
+    mockPaginated.mockResolvedValue(emptyConnection());
+    await createCommand(['--channel', 'preview']).run();
+    expect(mockSelectAsync).not.toHaveBeenCalled();
+    expect(mockViewChannels).not.toHaveBeenCalled();
+  });
+
+  it('treats --channel all as no channel filter', async () => {
+    mockPaginated.mockResolvedValue(emptyConnection());
+    await createCommand(['--channel', 'all']).run();
+    expect(mockPaginated).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      appId: MOCK_CONTEXT.projectId,
+      filter: undefined,
+      first: 25,
+      after: undefined,
+    });
+  });
+
+  it('skips the channel prompt when the project has no channels', async () => {
+    mockViewChannels.mockResolvedValue([]);
+    mockPaginated.mockResolvedValue(emptyConnection());
+    await createCommand([]).run();
+    expect(mockSelectAsync).not.toHaveBeenCalled();
+  });
+
+  it('passes --after-cursor through to viewPaginatedAsync', async () => {
+    mockPaginated.mockResolvedValue(emptyConnection());
+    await createCommand(['--non-interactive', '--after-cursor', 'cursor-123']).run();
+    expect(mockPaginated).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      appId: MOCK_CONTEXT.projectId,
+      filter: undefined,
+      first: 25,
+      after: 'cursor-123',
+    });
+  });
+
+  it('honors --limit', async () => {
+    mockPaginated.mockResolvedValue(emptyConnection());
+    await createCommand(['--non-interactive', '--limit', '5']).run();
+    expect(mockPaginated).toHaveBeenCalledWith(
+      MOCK_CONTEXT.loggedIn.graphqlClient,
+      expect.objectContaining({ first: 5 })
+    );
+  });
+
+  it('prints the section header with row count', async () => {
+    mockPaginated.mockResolvedValue({
+      edges: [{ cursor: 'c1', node: ROW_A }],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false, startCursor: 'c1', endCursor: 'c1' },
+    });
+    await createCommand(['--non-interactive']).run();
+    expect(mockLogLog.mock.calls.some(c => String(c[0]).includes('Embedded updates (1)'))).toBe(
+      true
+    );
+  });
+
+  it('suffixes the section header count with "+" when hasNextPage', async () => {
+    mockPaginated.mockResolvedValue({
+      edges: [{ cursor: 'c1', node: ROW_A }],
+      pageInfo: { hasNextPage: true, hasPreviousPage: false, startCursor: 'c1', endCursor: 'c1' },
+    });
+    await createCommand(['--non-interactive']).run();
+    expect(mockLogLog.mock.calls.some(c => String(c[0]).includes('Embedded updates (1+)'))).toBe(
+      true
+    );
+  });
+
+  it('shows relative-time "ago" hints in formatted rows', async () => {
+    mockPaginated.mockResolvedValue({
+      edges: [{ cursor: 'c1', node: ROW_A }],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false, startCursor: 'c1', endCursor: 'c1' },
+    });
+    await createCommand(['--non-interactive']).run();
+    expect(mockLogLog.mock.calls.some(c => /ago/.test(String(c[0])))).toBe(true);
+  });
+
+  it('puts "All channels" first in the prompt, then channels in order', async () => {
+    mockViewChannels.mockResolvedValue([
+      { id: 'ch1', name: 'production' } as any,
+      { id: 'ch2', name: 'preview' } as any,
+    ]);
+    mockSelectAsync.mockResolvedValue('production');
+    mockPaginated.mockResolvedValue(emptyConnection());
+
+    await createCommand([]).run();
+
+    const [, choices] = mockSelectAsync.mock.calls[0];
+    const titles = (choices as any[]).map(c => c.title);
+    expect(titles).toEqual(['All channels', 'production', 'preview']);
+  });
+});
@@ -0,0 +1,337 @@
+import { Platform } from '@expo/eas-build-job';
+import { Updates } from '@expo/config-plugins';
+import { vol } from 'memfs';
+
+import { getMockOclifConfig } from '../../../../__tests__/commands/utils';
+import { ExpoGraphqlClient } from '../../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { EmbeddedUpdateAssetMutation } from '../../../../graphql/mutations/EmbeddedUpdateAssetMutation';
+import {
+  EmbeddedUpdateMutation,
+  isEmbeddedUpdateAlreadyExistsError,
+  isEmbeddedUpdateAssetNotAvailableError,
+} from '../../../../graphql/mutations/EmbeddedUpdateMutation';
+import { AppPlatform } from '../../../../graphql/generated';
+import Log from '../../../../log';
+import { ora } from '../../../../ora';
+import * as uploads from '../../../../uploads';
+import * as json from '../../../../utils/json';
+import * as promise from '../../../../utils/promise';
+import UpdateEmbeddedUpload from '../upload';
+
+jest.mock('fs', () => jest.requireActual('memfs').fs);
+jest.mock('../../../../ora');
+jest.mock('@expo/config-plugins', () => ({
+  Updates: { getRuntimeVersionNullableAsync: jest.fn() },
+}));
+jest.mock('../../../../graphql/mutations/EmbeddedUpdateAssetMutation', () => ({
+  EmbeddedUpdateAssetMutation: { getSignedUploadSpecAsync: jest.fn() },
+}));
+jest.mock('../../../../graphql/mutations/EmbeddedUpdateMutation', () => ({
+  EmbeddedUpdateMutation: { uploadEmbeddedUpdateAsync: jest.fn() },
+  isEmbeddedUpdateAssetNotAvailableError: jest.fn(),
+  isEmbeddedUpdateAlreadyExistsError: jest.fn(),
+}));
+jest.mock('../../../../uploads');
+jest.mock('../../../../log');
+jest.mock('../../../../utils/json');
+jest.mock('../../../../utils/promise', () => ({
+  sleepAsync: jest.fn().mockResolvedValue(undefined),
+}));
+
+const mockGetRuntimeVersion = jest.mocked(Updates.getRuntimeVersionNullableAsync);
+const mockGetSignedUploadSpec = jest.mocked(EmbeddedUpdateAssetMutation.getSignedUploadSpecAsync);
+const mockUpload = jest.mocked(uploads.uploadWithPresignedPostWithRetryAsync);
+const mockUploadEmbeddedUpdate = jest.mocked(EmbeddedUpdateMutation.uploadEmbeddedUpdateAsync);
+const mockOra = jest.mocked(ora);
+const mockUploadSpinnerSucceed = jest.fn();
+const mockUploadSpinnerFail = jest.fn();
+const mockRegisterSpinnerSucceed = jest.fn();
+const mockRegisterSpinnerFail = jest.fn();
+const mockSleepAsync = jest.mocked(promise.sleepAsync);
+const mockIsEmbeddedUpdateAssetNotAvailableError = jest.mocked(
+  isEmbeddedUpdateAssetNotAvailableError
+);
+const mockIsEmbeddedUpdateAlreadyExistsError = jest.mocked(isEmbeddedUpdateAlreadyExistsError);
+const mockLogLog = jest.mocked(Log.log);
+
+const BUNDLE_PATH = '/project/app.bundle';
+const MANIFEST_PATH = '/project/app.manifest';
+const VALID_UUID = 'a1b2c3d4-1234-4000-8000-000000000000';
+const VALID_MANIFEST = JSON.stringify({ id: VALID_UUID });
+
+const BASE_ARGV = [
+  '--platform',
+  Platform.IOS,
+  '--bundle',
+  BUNDLE_PATH,
+  '--manifest',
+  MANIFEST_PATH,
+  '--channel',
+  'production',
+];
+
+const MOCK_CONTEXT = {
+  loggedIn: { graphqlClient: {} as ExpoGraphqlClient },
+  privateProjectConfig: {
+    projectId: 'project-123',
+    exp: { name: 'test', slug: 'test' },
+    projectDir: '/project',
+  },
+};
+
+const MOCK_EMBEDDED_UPDATE = {
+  id: 'embedded-update-id-abc',
+  platform: AppPlatform.Ios,
+  runtimeVersion: '1.0.0',
+  channel: 'production',
+  createdAt: '2024-01-01T00:00:00Z',
+};
+
+describe(UpdateEmbeddedUpload, () => {
+  const mockConfig = getMockOclifConfig();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockOra.mockImplementation(
+      (text?: string | object) =>
+        ({
+          start: () =>
+            text === 'Uploading bundle...'
+              ? { succeed: mockUploadSpinnerSucceed, fail: mockUploadSpinnerFail }
+              : { succeed: mockRegisterSpinnerSucceed, fail: mockRegisterSpinnerFail },
+        }) as any
+    );
+    vol.reset();
+    vol.fromJSON({
+      [BUNDLE_PATH]: 'bundle-bytes',
+      [MANIFEST_PATH]: VALID_MANIFEST,
+    });
+    mockGetRuntimeVersion.mockResolvedValue('1.0.0');
+    mockGetSignedUploadSpec.mockResolvedValue({
+      storageKey: 'storage-key-abc',
+      presignedUrl: 'https://storage.googleapis.com/upload-bucket',
+      fields: { key: 'obj-key', policy: 'abc123' },
+    });
+    mockUpload.mockImplementation(async (_path, _spec, onProgress) => {
+      // Invoke the progress callback so the no-op arrow passed by the command is executed.
+      (onProgress as () => void)();
+      return undefined as any;
+    });
+    mockUploadEmbeddedUpdate.mockResolvedValue(MOCK_EMBEDDED_UPDATE);
+    mockIsEmbeddedUpdateAssetNotAvailableError.mockReturnValue(false);
+    mockIsEmbeddedUpdateAlreadyExistsError.mockReturnValue(false);
+  });
+
+  function createCommand(argv: string[]): UpdateEmbeddedUpload {
+    const command = new UpdateEmbeddedUpload(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    jest.spyOn(command, 'getContextAsync').mockResolvedValue(MOCK_CONTEXT);
+    return command;
+  }
+
+  describe('file existence checks', () => {
+    it('runs successfully when both files exist', async () => {
+      const command = createCommand(BASE_ARGV);
+      await command.runAsync();
+      expect(mockUploadSpinnerSucceed).toHaveBeenCalledWith('Uploaded bundle');
+      expect(mockRegisterSpinnerSucceed).toHaveBeenCalledWith(
+        expect.stringContaining('production')
+      );
+    });
+
+    it('errors with message when bundle file does not exist', async () => {
+      vol.reset();
+      vol.fromJSON({ [MANIFEST_PATH]: VALID_MANIFEST });
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow(/Bundle file not found/);
+    });
+
+    it('errors with message when manifest file does not exist', async () => {
+      vol.reset();
+      vol.fromJSON({ [BUNDLE_PATH]: 'bundle-bytes' });
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow(/Could not read or parse manifest/);
+    });
+
+    it('includes build-id in log when provided', async () => {
+      const command = createCommand([...BASE_ARGV, '--build-id', 'build-uuid-123']);
+      await command.runAsync();
+      expect(mockRegisterSpinnerSucceed).toHaveBeenCalledWith(
+        expect.stringContaining('production')
+      );
+    });
+
+    it('accepts android platform', async () => {
+      const argv = [...BASE_ARGV];
+      argv[1] = Platform.ANDROID;
+      const command = createCommand(argv);
+      await command.runAsync();
+      expect(mockRegisterSpinnerSucceed).toHaveBeenCalledWith(
+        expect.stringContaining(Platform.ANDROID)
+      );
+    });
+  });
+
+  describe('manifest parsing', () => {
+    it('reads embeddedUpdateId from manifest and passes platform directly to getRuntimeVersion', async () => {
+      const command = createCommand(BASE_ARGV);
+      await command.runAsync();
+      expect(mockGetRuntimeVersion).toHaveBeenCalledWith(
+        MOCK_CONTEXT.privateProjectConfig.projectDir,
+        MOCK_CONTEXT.privateProjectConfig.exp,
+        Platform.IOS
+      );
+    });
+
+    it('errors when manifest contains invalid JSON', async () => {
+      vol.fromJSON({ [MANIFEST_PATH]: 'not-json', [BUNDLE_PATH]: 'bytes' });
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow(/Could not read or parse manifest/);
+    });
+
+    it('errors when manifest id is missing', async () => {
+      vol.fromJSON({ [MANIFEST_PATH]: JSON.stringify({ noId: true }), [BUNDLE_PATH]: 'bytes' });
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow(/"id" field/);
+    });
+
+    it('errors when manifest id is not a valid UUID', async () => {
+      vol.fromJSON({
+        [MANIFEST_PATH]: JSON.stringify({ id: 'not-a-uuid' }),
+        [BUNDLE_PATH]: 'bytes',
+      });
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow(/is not a UUID/);
+    });
+
+    it('errors when runtimeVersion cannot be resolved', async () => {
+      mockGetRuntimeVersion.mockResolvedValue(null);
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow(/runtimeVersion/);
+    });
+  });
+
+  describe('bundle upload', () => {
+    it('requests a presigned URL with embeddedUpdateId and uploads the bundle', async () => {
+      const command = createCommand(BASE_ARGV);
+      await command.runAsync();
+      expect(mockGetSignedUploadSpec).toHaveBeenCalledWith(
+        MOCK_CONTEXT.loggedIn.graphqlClient,
+        expect.objectContaining({
+          appId: MOCK_CONTEXT.privateProjectConfig.projectId,
+          embeddedUpdateId: VALID_UUID,
+          contentType: 'application/javascript',
+        })
+      );
+      expect(mockUpload).toHaveBeenCalledWith(
+        BUNDLE_PATH,
+        {
+          url: 'https://storage.googleapis.com/upload-bucket',
+          fields: { key: 'obj-key', policy: 'abc123' },
+        },
+        expect.any(Function)
+      );
+    });
+
+    it('propagates upload errors', async () => {
+      mockUpload.mockRejectedValue(new Error('upload failed'));
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow('upload failed');
+    });
+  });
+
+  describe('mutation registration', () => {
+    it('calls uploadEmbeddedUpdateAsync with channel name and AppPlatform enum', async () => {
+      const command = createCommand(BASE_ARGV);
+      await command.runAsync();
+      expect(mockUploadEmbeddedUpdate).toHaveBeenCalledWith(
+        MOCK_CONTEXT.loggedIn.graphqlClient,
+        expect.objectContaining({
+          appId: MOCK_CONTEXT.privateProjectConfig.projectId,
+          platform: AppPlatform.Ios,
+          runtimeVersion: '1.0.0',
+          channel: 'production',
+          embeddedUpdateId: VALID_UUID,
+        })
+      );
+    });
+
+    it('logs the embedded update id on success', async () => {
+      const command = createCommand(BASE_ARGV);
+      await command.runAsync();
+      expect(mockUploadSpinnerSucceed).toHaveBeenCalledWith('Uploaded bundle');
+      expect(mockLogLog).toHaveBeenCalledWith(expect.stringContaining(MOCK_EMBEDDED_UPDATE.id));
+    });
+
+    it('passes build-id as turtleBuildId when provided', async () => {
+      const command = createCommand([...BASE_ARGV, '--build-id', 'turtle-build-xyz']);
+      await command.runAsync();
+      expect(mockUploadEmbeddedUpdate).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ turtleBuildId: 'turtle-build-xyz' })
+      );
+    });
+
+    it('retries on ASSET_NOT_AVAILABLE: succeeds on second attempt, sleeps once with first delay', async () => {
+      const assetNotAvailableError = new Error('asset not available');
+      mockIsEmbeddedUpdateAssetNotAvailableError.mockImplementation(
+        e => e === assetNotAvailableError
+      );
+      mockUploadEmbeddedUpdate
+        .mockRejectedValueOnce(assetNotAvailableError)
+        .mockResolvedValueOnce(MOCK_EMBEDDED_UPDATE);
+
+      const command = createCommand(BASE_ARGV);
+      await command.runAsync();
+
+      expect(mockUploadEmbeddedUpdate).toHaveBeenCalledTimes(2);
+      expect(mockSleepAsync).toHaveBeenCalledTimes(1);
+      expect(mockSleepAsync).toHaveBeenCalledWith(3_000);
+      expect(mockUploadSpinnerSucceed).toHaveBeenCalledWith('Uploaded bundle');
+      expect(mockLogLog).toHaveBeenCalledWith(expect.stringContaining(MOCK_EMBEDDED_UPDATE.id));
+    });
+
+    it('exhausts all 10 attempts on ASSET_NOT_AVAILABLE, sleeping 9 times then throwing', async () => {
+      const assetNotAvailableError = new Error('asset not available');
+      mockIsEmbeddedUpdateAssetNotAvailableError.mockImplementation(
+        e => e === assetNotAvailableError
+      );
+      mockUploadEmbeddedUpdate.mockRejectedValue(assetNotAvailableError);
+
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow();
+      expect(mockUploadEmbeddedUpdate).toHaveBeenCalledTimes(10);
+      expect(mockSleepAsync).toHaveBeenCalledTimes(9);
+    });
+
+    it('propagates unexpected mutation errors immediately without retrying', async () => {
+      const unexpectedError = new Error('network timeout');
+      mockUploadEmbeddedUpdate.mockRejectedValue(unexpectedError);
+
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow('network timeout');
+      expect(mockUploadEmbeddedUpdate).toHaveBeenCalledTimes(1);
+      expect(mockRegisterSpinnerFail).toHaveBeenCalledWith('Failed to register embedded update');
+    });
+
+    it('fails with a clean message when the update is already registered', async () => {
+      const alreadyExistsError = new Error('already exists');
+      mockIsEmbeddedUpdateAlreadyExistsError.mockImplementation(e => e === alreadyExistsError);
+      mockUploadEmbeddedUpdate.mockRejectedValue(alreadyExistsError);
+
+      const command = createCommand(BASE_ARGV);
+      await expect(command.runAsync()).rejects.toThrow(/already registered/);
+      expect(mockUploadEmbeddedUpdate).toHaveBeenCalledTimes(1);
+      expect(mockRegisterSpinnerFail).toHaveBeenCalledWith('Failed to register embedded update');
+    });
+  });
+
+  describe('--json flag', () => {
+    it('enables JSON output and prints the embedded update as JSON', async () => {
+      const command = createCommand([...BASE_ARGV, '--json', '--non-interactive']);
+      await command.runAsync();
+      expect(jest.mocked(json.enableJsonOutput)).toHaveBeenCalled();
+      expect(jest.mocked(json.printJsonOnlyOutput)).toHaveBeenCalledWith(MOCK_EMBEDDED_UPDATE);
+    });
+  });
+});
@@ -0,0 +1,144 @@
+import { CombinedError } from '@urql/core';
+
+import { getMockOclifConfig } from '../../../../__tests__/commands/utils';
+import { ExpoGraphqlClient } from '../../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { AppPlatform } from '../../../../graphql/generated';
+import {
+  EmbeddedUpdateFragment,
+  EmbeddedUpdateQuery,
+  isEmbeddedUpdateNotFoundError,
+} from '../../../../graphql/queries/EmbeddedUpdateQuery';
+import Log from '../../../../log';
+import * as json from '../../../../utils/json';
+import UpdateEmbeddedView from '../view';
+
+jest.mock('../../../../graphql/queries/EmbeddedUpdateQuery', () => ({
+  EmbeddedUpdateQuery: { viewByIdAsync: jest.fn() },
+  isEmbeddedUpdateNotFoundError: jest.fn(),
+}));
+jest.mock('../../../../log');
+jest.mock('../../../../utils/json');
+
+const mockView = jest.mocked(EmbeddedUpdateQuery.viewByIdAsync);
+const mockIsNotFound = jest.mocked(isEmbeddedUpdateNotFoundError);
+const mockLogLog = jest.mocked(Log.log);
+const mockEnableJsonOutput = jest.mocked(json.enableJsonOutput);
+const mockPrintJson = jest.mocked(json.printJsonOnlyOutput);
+
+const VALID_UUID = 'a1b2c3d4-1234-4000-8000-000000000000';
+
+const MOCK_CONTEXT = {
+  projectId: 'project-123',
+  loggedIn: { graphqlClient: {} as ExpoGraphqlClient },
+};
+
+const MOCK_EMBEDDED_UPDATE: EmbeddedUpdateFragment = {
+  id: VALID_UUID,
+  platform: AppPlatform.Ios,
+  runtimeVersion: '1.0.0',
+  channel: 'production',
+  createdAt: '2026-05-29T00:00:00Z',
+  launchAsset: {
+    id: 'asset-1',
+    fileSize: 1024,
+    finalFileSize: 768,
+    fileSHA256: 'abc123',
+  },
+};
+
+describe(UpdateEmbeddedView, () => {
+  const mockConfig = getMockOclifConfig();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockView.mockResolvedValue(MOCK_EMBEDDED_UPDATE);
+    mockIsNotFound.mockReturnValue(false);
+  });
+
+  function createCommand(argv: string[]): UpdateEmbeddedView {
+    const command = new UpdateEmbeddedView(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    jest.spyOn(command, 'getContextAsync').mockResolvedValue(MOCK_CONTEXT);
+    return command;
+  }
+
+  it('prints formatted details on success', async () => {
+    await createCommand([VALID_UUID]).run();
+
+    expect(mockView).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      embeddedUpdateId: VALID_UUID,
+      appId: MOCK_CONTEXT.projectId,
+    });
+    // Header line + body line
+    expect(mockLogLog).toHaveBeenCalledTimes(2);
+    expect(mockLogLog.mock.calls[0][0]).toContain('Embedded update');
+    expect(mockLogLog.mock.calls[1][0]).toContain(VALID_UUID);
+    expect(mockLogLog.mock.calls[1][0]).toContain('Bundle size');
+    expect(mockLogLog.mock.calls[1][0]).toContain('Bundle SHA-256');
+  });
+
+  it('--json prints the raw embedded update and skips formatted output', async () => {
+    await createCommand([VALID_UUID, '--json']).run();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockPrintJson).toHaveBeenCalledWith(MOCK_EMBEDDED_UPDATE);
+    expect(mockLogLog).not.toHaveBeenCalled();
+  });
+
+  it('exits with a friendly message when the server returns NOT_FOUND', async () => {
+    const notFound = new CombinedError({ graphQLErrors: [] });
+    mockView.mockRejectedValue(notFound);
+    mockIsNotFound.mockReturnValue(true);
+
+    await expect(createCommand([VALID_UUID]).run()).rejects.toThrow();
+    expect(mockIsNotFound).toHaveBeenCalledWith(notFound);
+  });
+
+  it('rethrows unexpected errors', async () => {
+    const boom = new Error('boom');
+    mockView.mockRejectedValue(boom);
+    mockIsNotFound.mockReturnValue(false);
+
+    await expect(createCommand([VALID_UUID]).run()).rejects.toThrow('boom');
+  });
+
+  it('renders bundle size from finalFileSize when present', async () => {
+    mockView.mockResolvedValue({
+      ...MOCK_EMBEDDED_UPDATE,
+      launchAsset: { id: 'asset-x', fileSize: 2048, finalFileSize: 768, fileSHA256: 'abc' },
+    });
+    await createCommand([VALID_UUID]).run();
+    // 768 B; not 2.0 KB (which would be fileSize).
+    expect(mockLogLog.mock.calls[1][0]).toContain('768 B');
+  });
+
+  it('falls back to fileSize when finalFileSize is null', async () => {
+    mockView.mockResolvedValue({
+      ...MOCK_EMBEDDED_UPDATE,
+      launchAsset: { id: 'asset-y', fileSize: 2048, finalFileSize: null, fileSHA256: 'abc' },
+    });
+    await createCommand([VALID_UUID]).run();
+    expect(mockLogLog.mock.calls[1][0]).toContain('2.0 KB');
+  });
+
+  it('shows runtime version, channel, and SHA-256 in the body', async () => {
+    await createCommand([VALID_UUID]).run();
+    const body = String(mockLogLog.mock.calls[1][0]);
+    expect(body).toContain('1.0.0');
+    expect(body).toContain('production');
+    expect(body).toContain('abc123');
+  });
+
+  it('shows a relative-time hint in the Created at row', async () => {
+    await createCommand([VALID_UUID]).run();
+    expect(mockLogLog.mock.calls[1][0]).toMatch(/\(.+ago\)/);
+  });
+
+  it('passes the project id and uuid through to viewByIdAsync', async () => {
+    await createCommand([VALID_UUID]).run();
+    expect(mockView).toHaveBeenCalledWith(MOCK_CONTEXT.loggedIn.graphqlClient, {
+      embeddedUpdateId: VALID_UUID,
+      appId: MOCK_CONTEXT.projectId,
+    });
+  });
+});
@@ -0,0 +1,72 @@
+import { Args } from '@oclif/core';
+
+import EasCommand from '../../../commandUtils/EasCommand';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../../commandUtils/flags';
+import { EmbeddedUpdateMutation } from '../../../graphql/mutations/EmbeddedUpdateMutation';
+import Log from '../../../log';
+import { toggleConfirmAsync } from '../../../prompts';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+
+export default class UpdateEmbeddedDelete extends EasCommand {
+  static override description = 'delete an embedded update registered with EAS Update';
+
+  static override args = {
+    id: Args.string({
+      required: true,
+      description: 'The ID of the embedded update (manifest UUID from app.manifest).',
+    }),
+  };
+
+  static override flags = {
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const {
+      args: { id: embeddedUpdateId },
+      flags,
+    } = await this.parse(UpdateEmbeddedDelete);
+    const { json: jsonFlag, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+
+    const {
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(UpdateEmbeddedDelete, { nonInteractive });
+
+    if (jsonFlag) {
+      enableJsonOutput();
+    }
+
+    if (!nonInteractive) {
+      Log.log(
+        `You are about to permanently delete embedded update: "${embeddedUpdateId}". ` +
+          `Diff patches already generated against this bundle keep serving, but new diffs ` +
+          `can't be generated until you re-upload it.`
+      );
+      Log.newLine();
+      const confirmed = await toggleConfirmAsync({ message: 'Are you sure you wish to proceed?' });
+      if (!confirmed) {
+        Log.error(`Canceled deletion of embedded update: "${embeddedUpdateId}".`);
+        process.exit(1);
+      }
+    }
+
+    // Best-effort delete on the server: deleting an unknown id succeeds (idempotent),
+    // so we don't need a not-found branch here.
+    await EmbeddedUpdateMutation.deleteEmbeddedUpdateAsync(graphqlClient, {
+      id: embeddedUpdateId,
+    });
+
+    if (jsonFlag) {
+      printJsonOnlyOutput({ id: embeddedUpdateId });
+      return;
+    }
+    Log.withTick(`Deleted embedded update ${embeddedUpdateId}`);
+  }
+}
@@ -0,0 +1,172 @@
+import { Platform } from '@expo/eas-build-job';
+import { Flags } from '@oclif/core';
+import chalk from 'chalk';
+
+import EasCommand from '../../../commandUtils/EasCommand';
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../../commandUtils/flags';
+import { getLimitFlagWithCustomValues } from '../../../commandUtils/pagination';
+import { AppPlatform } from '../../../graphql/generated';
+import { ChannelQuery } from '../../../graphql/queries/ChannelQuery';
+import {
+  EmbeddedUpdateFragment,
+  EmbeddedUpdateQuery,
+} from '../../../graphql/queries/EmbeddedUpdateQuery';
+import { toAppPlatform } from '../../../graphql/types/AppPlatform';
+import Log from '../../../log';
+import { selectAsync } from '../../../prompts';
+import { fromNow } from '../../../utils/date';
+import formatFields from '../../../utils/formatFields';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+
+const DEFAULT_LIMIT = 25;
+const MAX_LIMIT = 50;
+const CHANNELS_LIMIT = 50;
+
+export default class UpdateEmbeddedList extends EasCommand {
+  static override description = 'list embedded updates registered with EAS Update for this project';
+
+  static override flags = {
+    platform: Flags.option({
+      char: 'p',
+      description: 'Filter by platform',
+      options: [Platform.IOS, Platform.ANDROID] as const,
+    })(),
+    'runtime-version': Flags.string({
+      description: 'Filter by runtime version',
+    }),
+    channel: Flags.string({
+      description: 'Filter by channel name (pass "all" to skip the channel prompt)',
+    }),
+    limit: getLimitFlagWithCustomValues({ defaultTo: DEFAULT_LIMIT, limit: MAX_LIMIT }),
+    'after-cursor': Flags.string({
+      description: 'Return items after this cursor (for pagination)',
+    }),
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectId,
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(UpdateEmbeddedList);
+    const { json: jsonFlag, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+
+    const {
+      projectId,
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(UpdateEmbeddedList, { nonInteractive });
+
+    if (jsonFlag) {
+      enableJsonOutput();
+    }
+
+    const platform: AppPlatform | undefined = flags.platform
+      ? toAppPlatform(flags.platform)
+      : undefined;
+
+    // Resolve channel filter:
+    // - `--channel <name>`: use it
+    // - `--channel all` (or no flag in non-interactive / json): no channel filter
+    // - no flag in interactive: prompt with the project's channels + "All channels"
+    let channel: string | undefined;
+    if (flags.channel) {
+      channel = flags.channel.toLowerCase() === 'all' ? undefined : flags.channel;
+    } else if (!nonInteractive && !jsonFlag) {
+      channel = await promptForChannelAsync(graphqlClient, projectId);
+    }
+
+    const filter =
+      platform || flags['runtime-version'] || channel
+        ? {
+            platform,
+            runtimeVersion: flags['runtime-version'],
+            channel,
+          }
+        : undefined;
+
+    const limit = flags.limit ?? DEFAULT_LIMIT;
+    const connection = await EmbeddedUpdateQuery.viewPaginatedAsync(graphqlClient, {
+      appId: projectId,
+      filter,
+      first: limit,
+      after: flags['after-cursor'],
+    });
+
+    const embeddedUpdates = connection.edges.map(e => e.node);
+
+    if (jsonFlag) {
+      printJsonOnlyOutput({
+        embeddedUpdates,
+        pageInfo: connection.pageInfo,
+      });
+      return;
+    }
+
+    if (embeddedUpdates.length === 0) {
+      Log.log('No embedded updates found.');
+      return;
+    }
+
+    Log.addNewLineIfNone();
+    Log.log(
+      chalk.bold(
+        `Embedded updates (${embeddedUpdates.length}${connection.pageInfo.hasNextPage ? '+' : ''}):`
+      )
+    );
+    Log.newLine();
+    Log.log(embeddedUpdates.map(formatEmbeddedUpdateRow).join(`\n\n${chalk.dim('———')}\n\n`));
+
+    if (connection.pageInfo.hasNextPage && connection.pageInfo.endCursor) {
+      Log.newLine();
+      Log.log(
+        chalk.dim(
+          `Showing ${embeddedUpdates.length}. For the next page, run with --after-cursor ${connection.pageInfo.endCursor}`
+        )
+      );
+    }
+  }
+}
+
+// Sentinel for the "All channels" option. We can't use `undefined` here because
+// the underlying `prompts` library substitutes a choice's index when its value
+// is undefined, which then leaks into the GraphQL filter.
+const ALL_CHANNELS = '__embedded_update_list__all_channels__';
+
+async function promptForChannelAsync(
+  graphqlClient: ExpoGraphqlClient,
+  projectId: string
+): Promise<string | undefined> {
+  const channels = await ChannelQuery.viewUpdateChannelsOnAppAsync(graphqlClient, {
+    appId: projectId,
+    offset: 0,
+    limit: CHANNELS_LIMIT,
+  });
+
+  if (channels.length === 0) {
+    // Nothing to choose from — fall back to listing everything.
+    return undefined;
+  }
+
+  const selected = await selectAsync<string>('Filter embedded updates by which channel?', [
+    { title: 'All channels', value: ALL_CHANNELS },
+    ...channels.map(c => ({ title: c.name, value: c.name })),
+  ]);
+  return selected === ALL_CHANNELS ? undefined : selected;
+}
+
+function formatEmbeddedUpdateRow(embeddedUpdate: EmbeddedUpdateFragment): string {
+  const createdAt = new Date(embeddedUpdate.createdAt);
+  return formatFields([
+    { label: 'ID', value: embeddedUpdate.id },
+    { label: 'Platform', value: embeddedUpdate.platform.toLowerCase() },
+    { label: 'Runtime version', value: embeddedUpdate.runtimeVersion },
+    { label: 'Channel', value: embeddedUpdate.channel },
+    { label: 'Created', value: `${fromNow(createdAt)} ago` },
+  ]);
+}
@@ -0,0 +1,177 @@
+import { Platform } from '@expo/eas-build-job';
+import { Updates } from '@expo/config-plugins';
+import { Errors, Flags } from '@oclif/core';
+import fs from 'fs-extra';
+
+import EasCommand from '../../../commandUtils/EasCommand';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../../commandUtils/flags';
+import { EmbeddedUpdateAssetMutation } from '../../../graphql/mutations/EmbeddedUpdateAssetMutation';
+import {
+  EmbeddedUpdateMutation,
+  EmbeddedUpdateResult,
+  isEmbeddedUpdateAlreadyExistsError,
+  isEmbeddedUpdateAssetNotAvailableError,
+} from '../../../graphql/mutations/EmbeddedUpdateMutation';
+import { toAppPlatform } from '../../../graphql/types/AppPlatform';
+import Log from '../../../log';
+import { ora } from '../../../ora';
+import { readEmbeddedManifestAsync } from '../../../update/embeddedManifest';
+import { uploadWithPresignedPostWithRetryAsync } from '../../../uploads';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+import { sleepAsync } from '../../../utils/promise';
+
+const MAX_ATTEMPTS = 10;
+const RETRY_BASE_DELAY_MS = 3_000;
+const RETRY_MAX_DELAY_MS = 10_000;
+
+export default class UpdateEmbeddedUpload extends EasCommand {
+  static override description =
+    'upload the JS bundle embedded in a native build so EAS Update can generate bsdiff patches against it';
+
+  static override examples = [
+    '$ eas update:embedded:upload --platform ios --bundle ios/build/App.app/main.jsbundle --manifest ios/build/App.app/app.manifest --channel production',
+    '$ eas update:embedded:upload --platform android --bundle android/app/src/main/assets/index.android.bundle --manifest android/app/src/main/assets/app.manifest --channel production --build-id <BUILD-ID>',
+  ];
+
+  static override flags = {
+    platform: Flags.option({
+      char: 'p',
+      description: 'Platform of the embedded bundle',
+      options: [Platform.IOS, Platform.ANDROID] as const,
+      required: true,
+    })(),
+    bundle: Flags.string({
+      description: 'Path to the embedded JS bundle file',
+      required: true,
+    }),
+    manifest: Flags.string({
+      description: 'Path to the app.manifest file embedded in the build',
+      required: true,
+    }),
+    channel: Flags.string({
+      description: 'Channel name the embedded update should be associated with',
+      required: true,
+    }),
+    'build-id': Flags.string({
+      description: 'EAS Build ID that produced this binary (required when invoked from EAS Build)',
+      required: false,
+    }),
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectConfig,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(UpdateEmbeddedUpload);
+    const { json: jsonFlag, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+    const platform = flags.platform;
+    const bundlePath = flags.bundle;
+    const manifestPath = flags.manifest;
+    const channelName = flags.channel;
+    const buildId = flags['build-id'];
+
+    const {
+      loggedIn: { graphqlClient },
+      privateProjectConfig: { projectId, exp, projectDir },
+    } = await this.getContextAsync(UpdateEmbeddedUpload, {
+      nonInteractive,
+      withServerSideEnvironment: null,
+    });
+
+    if (jsonFlag) {
+      enableJsonOutput();
+    }
+
+    if (!(await fs.pathExists(bundlePath))) {
+      Errors.error(
+        `Bundle file not found at "${bundlePath}". Check that the path is correct and points to the JS bundle in your native build output.`,
+        { exit: 1 }
+      );
+    }
+
+    const { id: embeddedUpdateId } = await readEmbeddedManifestAsync(manifestPath);
+
+    const runtimeVersion = await Updates.getRuntimeVersionNullableAsync(projectDir, exp, platform);
+    if (runtimeVersion === null) {
+      Errors.error(
+        `Could not resolve runtimeVersion for platform "${platform}". ` +
+          `Ensure runtimeVersion is set in your app.json under the expo key.`,
+        { exit: 1 }
+      );
+    }
+
+    const appPlatform = toAppPlatform(platform);
+
+    const uploadSpinner = ora('Uploading bundle...').start();
+
+    const contentType = 'application/javascript';
+    const uploadSpec = await EmbeddedUpdateAssetMutation.getSignedUploadSpecAsync(graphqlClient, {
+      appId: projectId,
+      embeddedUpdateId,
+      contentType,
+    });
+    await uploadWithPresignedPostWithRetryAsync(
+      bundlePath,
+      { url: uploadSpec.presignedUrl, fields: uploadSpec.fields },
+      () => {}
+    );
+
+    uploadSpinner.succeed('Uploaded bundle');
+
+    const registerSpinner = ora('Registering embedded update...').start();
+
+    let embeddedUpdate: EmbeddedUpdateResult | undefined;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      try {
+        embeddedUpdate = await EmbeddedUpdateMutation.uploadEmbeddedUpdateAsync(graphqlClient, {
+          appId: projectId,
+          platform: appPlatform,
+          runtimeVersion,
+          channel: channelName,
+          embeddedUpdateId,
+          turtleBuildId: buildId,
+        });
+        break;
+      } catch (e: unknown) {
+        if (isEmbeddedUpdateAssetNotAvailableError(e)) {
+          if (attempt < MAX_ATTEMPTS) {
+            await sleepAsync(
+              Math.min(RETRY_BASE_DELAY_MS * 2 ** (attempt - 1), RETRY_MAX_DELAY_MS)
+            );
+          }
+          continue;
+        }
+
+        registerSpinner.fail('Failed to register embedded update');
+        if (isEmbeddedUpdateAlreadyExistsError(e)) {
+          Errors.error(
+            `An embedded update with id "${embeddedUpdateId}" is already registered for this app. Delete it before re-uploading.`,
+            { exit: 1 }
+          );
+        }
+        throw e;
+      }
+    }
+
+    if (embeddedUpdate === undefined) {
+      registerSpinner.fail('Failed to register embedded update');
+      throw new Error(
+        'Embedded bundle could not be processed in time. Try re-running the command in a moment.'
+      );
+    }
+
+    registerSpinner.succeed(
+      `Registered ${platform} embedded update (runtimeVersion: ${runtimeVersion}, channel: "${channelName}")`
+    );
+    Log.log(`Embedded update ID: ${embeddedUpdate.id}`);
+
+    if (jsonFlag) {
+      printJsonOnlyOutput(embeddedUpdate);
+    }
+  }
+}
@@ -0,0 +1,95 @@
+import { Args, Errors } from '@oclif/core';
+import chalk from 'chalk';
+
+import EasCommand from '../../../commandUtils/EasCommand';
+import { EasJsonOnlyFlag } from '../../../commandUtils/flags';
+import {
+  EmbeddedUpdateFragment,
+  EmbeddedUpdateQuery,
+  isEmbeddedUpdateNotFoundError,
+} from '../../../graphql/queries/EmbeddedUpdateQuery';
+import Log from '../../../log';
+import { fromNow } from '../../../utils/date';
+import { formatBytes } from '../../../utils/files';
+import formatFields from '../../../utils/formatFields';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+
+export default class UpdateEmbeddedView extends EasCommand {
+  static override description = 'view details of an embedded update registered with EAS Update';
+
+  static override args = {
+    id: Args.string({
+      required: true,
+      description: 'The ID of the embedded update (manifest UUID from app.manifest).',
+    }),
+  };
+
+  static override flags = {
+    ...EasJsonOnlyFlag,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectId,
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const {
+      args: { id: embeddedUpdateId },
+      flags: { json: jsonFlag },
+    } = await this.parse(UpdateEmbeddedView);
+
+    const {
+      projectId,
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(UpdateEmbeddedView, { nonInteractive: true });
+
+    if (jsonFlag) {
+      enableJsonOutput();
+    }
+
+    let embeddedUpdate;
+    try {
+      embeddedUpdate = await EmbeddedUpdateQuery.viewByIdAsync(graphqlClient, {
+        embeddedUpdateId,
+        appId: projectId,
+      });
+    } catch (e: unknown) {
+      if (isEmbeddedUpdateNotFoundError(e)) {
+        Errors.error(
+          `No embedded update found with id "${embeddedUpdateId}" for this project. ` +
+            `Run "eas update:embedded:list" to see the embedded updates registered for this app.`,
+          { exit: 1 }
+        );
+      }
+      throw e;
+    }
+
+    if (jsonFlag) {
+      printJsonOnlyOutput(embeddedUpdate);
+      return;
+    }
+
+    Log.addNewLineIfNone();
+    Log.log(chalk.bold('Embedded update:'));
+    Log.log(formatEmbeddedUpdate(embeddedUpdate));
+  }
+}
+
+export function formatEmbeddedUpdate(embeddedUpdate: EmbeddedUpdateFragment): string {
+  const createdAt = new Date(embeddedUpdate.createdAt);
+  const bundleSize =
+    embeddedUpdate.launchAsset.finalFileSize ?? embeddedUpdate.launchAsset.fileSize;
+  return formatFields([
+    { label: 'ID', value: embeddedUpdate.id },
+    { label: 'Platform', value: embeddedUpdate.platform.toLowerCase() },
+    { label: 'Runtime version', value: embeddedUpdate.runtimeVersion },
+    { label: 'Channel', value: embeddedUpdate.channel },
+    { label: 'Bundle size', value: formatBytes(bundleSize) },
+    { label: 'Bundle SHA-256', value: embeddedUpdate.launchAsset.fileSHA256 },
+    {
+      label: 'Created at',
+      value: `${createdAt.toLocaleString()} (${fromNow(createdAt)} ago)`,
+    },
+  ]);
+}
@@ -27,6 +27,7 @@ export class CredentialsContext {
  public readonly nonInteractive: boolean;
  public readonly autoAcceptCredentialReuse: boolean;
  public readonly freezeCredentials: boolean = false;
+  public readonly refreshAdHocProvisioningProfile: boolean = false;
  public readonly projectDir: string;
  public readonly user: Actor;
  public readonly graphqlClient: ExpoGraphqlClient;
@@ -52,6 +53,7 @@ export class CredentialsContext {
      vcsClient: Client;
      freezeCredentials?: boolean;
      autoAcceptCredentialReuse?: boolean;
+      refreshAdHocProvisioningProfile?: boolean;
      env?: Env;
    }
  ) {
@@ -65,6 +67,7 @@ export class CredentialsContext {
    this.autoAcceptCredentialReuse = options.autoAcceptCredentialReuse ?? false;
    this.projectInfo = options.projectInfo;
    this.freezeCredentials = options.freezeCredentials ?? false;
+    this.refreshAdHocProvisioningProfile = options.refreshAdHocProvisioningProfile ?? false;
    this.usesBroadcastPushNotifications =
      options.projectInfo?.exp.ios?.usesBroadcastPushNotifications ?? false;
  }
@@ -1,6 +1,37 @@
 import { promptAsync } from '../.././../prompts';
-import { AppleDevice, AppleDeviceFragment } from '../../../graphql/generated';
+import { AppleDevice, AppleDeviceClass, AppleDeviceFragment } from '../../../graphql/generated';
 import { APPLE_DEVICE_CLASS_LABELS } from '../../../graphql/types/credentials/AppleDevice';
+import { ApplePlatform } from '../appstore/constants';
+
+export function filterDevicesForApplePlatform(
+  devices: AppleDeviceFragment[],
+  applePlatform: ApplePlatform
+): AppleDeviceFragment[] {
+  if (applePlatform === ApplePlatform.TV_OS) {
+    throw new Error('Filtering for tvOS is not supported yet');
+  }
+
+  if (applePlatform === ApplePlatform.VISION_OS) {
+    throw new Error('Filtering for visionOS is not supported yet');
+  }
+
+  return devices.filter(device => isDeviceCompatibleWithApplePlatform(device, applePlatform));
+}
+
+function isDeviceCompatibleWithApplePlatform(
+  device: AppleDeviceFragment,
+  applePlatform: Exclude<ApplePlatform, ApplePlatform.TV_OS | ApplePlatform.VISION_OS>
+): boolean {
+  switch (applePlatform) {
+    case ApplePlatform.IOS:
+      return (
+        device.deviceClass === AppleDeviceClass.Iphone ||
+        device.deviceClass === AppleDeviceClass.Ipad
+      );
+    case ApplePlatform.MAC_OS:
+      return device.deviceClass === AppleDeviceClass.Mac;
+  }
+}

 export async function chooseDevicesAsync(
  allDevices: AppleDeviceFragment[],
@@ -6,7 +6,11 @@ import nullthrows from 'nullthrows';

 import { resolveAppleTeamIfAuthenticatedAsync } from './AppleTeamUtils';
 import { assignBuildCredentialsAsync, getBuildCredentialsAsync } from './BuildCredentialsUtils';
-import { chooseDevicesAsync, formatDeviceLabel } from './DeviceUtils';
+import {
+  chooseDevicesAsync,
+  filterDevicesForApplePlatform,
+  formatDeviceLabel,
+} from './DeviceUtils';
 import { SetUpDistributionCertificate } from './SetUpDistributionCertificate';
 import DeviceCreateAction, { RegistrationMethod } from '../../../devices/actions/create/action';
 import {
@@ -18,6 +22,8 @@ import {
  IosAppBuildCredentialsFragment,
  IosDistributionType,
 } from '../../../graphql/generated';
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { AppStoreConnectApiKeyQuery } from '../../../graphql/queries/AppStoreConnectApiKeyQuery';
 import Log from '../../../log';
 import { getApplePlatformFromTarget } from '../../../project/ios/target';
 import {
@@ -29,9 +35,13 @@ import {
 import differenceBy from '../../../utils/expodash/differenceBy';
 import { CredentialsContext } from '../../context';
 import { MissingCredentialsNonInteractiveError } from '../../errors';
+import { getAscApiKeyForAppSubmissionsAsync } from '../api/GraphqlClient';
 import { AppLookupParams } from '../api/graphql/types/AppLookupParams';
+import { AppleTeamType, AuthenticationMode } from '../appstore/authenticateTypes';
 import { ProvisioningProfile } from '../appstore/Credentials.types';
 import { ApplePlatform } from '../appstore/constants';
+import { hasAscEnvVars } from '../appstore/resolveCredentials';
+import { MinimalAscApiKey } from '../credentials';
 import { Target } from '../types';
 import { validateProvisioningProfileAsync } from '../validators/validateProvisioningProfile';

@@ -51,11 +61,23 @@ export class SetUpAdhocProvisioningProfile {

  async runAsync(ctx: CredentialsContext): Promise<IosAppBuildCredentialsFragment> {
    const { app } = this.options;
+
+    if (ctx.refreshAdHocProvisioningProfile && ctx.freezeCredentials) {
+      throw new Error(
+        'Cannot refresh ad-hoc provisioning profile when credentials are frozen. Remove --freeze-credentials or --refresh-ad-hoc-provisioning-profile.'
+      );
+    }
+
    const distCert = await new SetUpDistributionCertificate(
      app,
      IosDistributionType.AdHoc
    ).runAsync(ctx);

+    if (ctx.nonInteractive && ctx.refreshAdHocProvisioningProfile) {
+      await this.ensureAppStoreAuthenticatedForAdhocRefreshAsync(ctx, app);
+      return await this.runWithDistributionCertificateAsync(ctx, distCert);
+    }
+
    const areBuildCredentialsSetup = await this.areBuildCredentialsSetupAsync(ctx);

    if (ctx.nonInteractive) {
@@ -111,6 +133,11 @@ export class SetUpAdhocProvisioningProfile {
      appleTeam
    );
    if (registeredAppleDevices.length === 0) {
+      if (ctx.nonInteractive) {
+        throw new Error(
+          'No devices are registered for this Apple team. Register devices with eas device:create first.'
+        );
+      }
      const shouldRegisterDevices = await confirmAsync({
        message: `You don't have any registered devices yet. Would you like to register them now?`,
        initial: true,
@@ -127,13 +154,13 @@ export class SetUpAdhocProvisioningProfile {
    const provisionedDeviceIdentifiers = (
      currentBuildCredentials?.provisioningProfile?.appleDevices ?? []
    ).map(i => i.identifier);
-    const chosenDevices = await chooseDevicesAsync(
-      registeredAppleDevices,
-      provisionedDeviceIdentifiers
-    );
+    const applePlatform = getApplePlatformFromTarget(target);
+    const chosenDevices =
+      ctx.nonInteractive && ctx.refreshAdHocProvisioningProfile
+        ? filterDevicesForApplePlatform(registeredAppleDevices, applePlatform)
+        : await chooseDevicesAsync(registeredAppleDevices, provisionedDeviceIdentifiers);

    // 4. Reuse or create the profile on Apple Developer Portal
-    const applePlatform = getApplePlatformFromTarget(target);
    const profileType =
      applePlatform === ApplePlatform.TV_OS
        ? ProfileType.TVOS_APP_ADHOC
@@ -187,21 +214,25 @@ export class SetUpAdhocProvisioningProfile {
      Log.log(
        'Most commonly devices fail to to be provisioned while they are still being processed by Apple, which can take up to 24-72 hours. Check your Apple Developer Portal page at https://developer.apple.com/account/resources/devices/list, the devices in "Processing" status cannot be provisioned yet'
      );
-      const shouldContinue = await selectAsync(
-        'Do you want to continue without provisioning these devices?',
-        [
-          {
-            title: 'Yes',
-            value: true,
-          },
-          {
-            title: 'No (EAS CLI will exit)',
-            value: false,
-          },
-        ]
-      );
-      if (!shouldContinue) {
-        Errors.exit(1);
+      if (ctx.nonInteractive && ctx.refreshAdHocProvisioningProfile) {
+        // Continue without prompting in non-interactive refresh mode.
+      } else {
+        const shouldContinue = await selectAsync(
+          'Do you want to continue without provisioning these devices?',
+          [
+            {
+              title: 'Yes',
+              value: true,
+            },
+            {
+              title: 'No (EAS CLI will exit)',
+              value: false,
+            },
+          ]
+        );
+        if (!shouldContinue) {
+          Errors.exit(1);
+        }
      }
    }

@@ -371,6 +402,67 @@ export class SetUpAdhocProvisioningProfile {
      }
    }
  }
+
+  private async ensureAppStoreAuthenticatedForAdhocRefreshAsync(
+    ctx: CredentialsContext,
+    app: AppLookupParams
+  ): Promise<void> {
+    if (hasAscEnvVars()) {
+      await ctx.appStore.ensureAuthenticatedAsync({ mode: AuthenticationMode.API_KEY });
+      return;
+    }
+
+    const resolvedKey = await resolveAscApiKeyForAppCredentialsAsync({
+      graphqlClient: ctx.graphqlClient,
+      app,
+    });
+    if (!resolvedKey) {
+      throw new Error(
+        'No App Store Connect API Key found for ad-hoc provisioning profile refresh. In non-interactive mode, provide one via:\n' +
+          '  - Environment variables: EXPO_ASC_API_KEY_PATH, EXPO_ASC_KEY_ID, EXPO_ASC_ISSUER_ID\n' +
+          '  - EAS credentials service: configure an App Store Connect API Key for submissions on this app'
+      );
+    }
+
+    await ctx.appStore.ensureAuthenticatedAsync({
+      mode: AuthenticationMode.API_KEY,
+      ascApiKey: resolvedKey.ascApiKey,
+      teamId: resolvedKey.teamId,
+      teamName: resolvedKey.teamName,
+      // Provide a non-enterprise team type to avoid interactive team-type resolution.
+      // Ad-hoc profile handling below uses explicit ProfileType and does not branch on team.inHouse.
+      teamType: AppleTeamType.COMPANY_OR_ORGANIZATION,
+    });
+  }
+}
+
+async function resolveAscApiKeyForAppCredentialsAsync({
+  graphqlClient,
+  app,
+}: {
+  graphqlClient: ExpoGraphqlClient;
+  app: AppLookupParams;
+}): Promise<{
+  ascApiKey: MinimalAscApiKey;
+  teamId?: string;
+  teamName?: string;
+} | null> {
+  const ascKeyFragment = await getAscApiKeyForAppSubmissionsAsync(graphqlClient, app);
+  if (!ascKeyFragment) {
+    return null;
+  }
+
+  Log.log('Using App Store Connect API Key from EAS credentials service.');
+  const fullKey = await AppStoreConnectApiKeyQuery.getByIdAsync(graphqlClient, ascKeyFragment.id);
+  return {
+    ascApiKey: {
+      keyP8: fullKey.keyP8,
+      keyId: fullKey.keyIdentifier,
+      issuerId: fullKey.issuerIdentifier,
+    },
+    teamId: ascKeyFragment.appleTeam?.appleTeamIdentifier,
+    teamName: ascKeyFragment.appleTeam?.appleTeamName ?? undefined,
+  };
 }

 export function doUDIDsMatch(udidsA: string[], udidsB: string[]): boolean {
@@ -54,6 +54,18 @@ export class SetUpTargetBuildCredentials {
    ctx: CredentialsContext
  ): Promise<IosAppBuildCredentialsFragment> {
    const { app, distribution, enterpriseProvisioning, target } = this.options;
+    if (ctx.refreshAdHocProvisioningProfile) {
+      if (distribution !== 'internal') {
+        throw new Error(
+          '--refresh-ad-hoc-provisioning-profile is only supported for internal distribution builds.'
+        );
+      }
+      if (enterpriseProvisioning === 'universal') {
+        throw new Error(
+          '--refresh-ad-hoc-provisioning-profile is only supported for ad-hoc internal builds.'
+        );
+      }
+    }
    if (distribution === 'internal') {
      if (enterpriseProvisioning === 'adhoc') {
        return await new SetUpAdhocProvisioningProfile({ app, target }).runAsync(ctx);
@@ -1,7 +1,65 @@
 import { v4 as uuidv4 } from 'uuid';

 import { AppleDeviceClass, AppleDeviceFragment } from '../../../../graphql/generated';
-import { formatDeviceLabel } from '../DeviceUtils';
+import { ApplePlatform } from '../../appstore/constants';
+import { filterDevicesForApplePlatform, formatDeviceLabel } from '../DeviceUtils';
+
+function createDevice(
+  overrides: Partial<AppleDeviceFragment> & Pick<AppleDeviceFragment, 'identifier'>
+): AppleDeviceFragment {
+  return {
+    __typename: 'AppleDevice',
+    id: uuidv4(),
+    name: 'device',
+    model: null,
+    deviceClass: null,
+    createdAt: new Date().toISOString(),
+    ...overrides,
+  } as AppleDeviceFragment;
+}
+
+describe(filterDevicesForApplePlatform, () => {
+  const iphone = createDevice({
+    identifier: 'iphone',
+    deviceClass: AppleDeviceClass.Iphone,
+  });
+  const ipad = createDevice({
+    identifier: 'ipad',
+    deviceClass: AppleDeviceClass.Ipad,
+  });
+  const mac = createDevice({
+    identifier: 'mac',
+    deviceClass: AppleDeviceClass.Mac,
+  });
+  const appleTv = createDevice({
+    identifier: 'appletv',
+    model: 'AppleTV6,3',
+    deviceClass: AppleDeviceClass.Unknown,
+  });
+  const unknown = createDevice({
+    identifier: 'unknown',
+    deviceClass: AppleDeviceClass.Unknown,
+  });
+  const noClass = createDevice({
+    identifier: 'noclass',
+    deviceClass: null,
+  });
+
+  it('keeps only iPhone and iPad devices for iOS targets', () => {
+    expect(
+      filterDevicesForApplePlatform(
+        [iphone, ipad, mac, appleTv, unknown, noClass],
+        ApplePlatform.IOS
+      )
+    ).toEqual([iphone, ipad]);
+  });
+
+  it('throws for tvOS targets', () => {
+    expect(() =>
+      filterDevicesForApplePlatform([iphone, ipad, mac, appleTv], ApplePlatform.TV_OS)
+    ).toThrow('Filtering for tvOS is not supported yet');
+  });
+});

 describe(formatDeviceLabel, () => {
  it('returns createdAt clause', async () => {
@@ -23,17 +23,37 @@ import { ApplePlatform } from '../../appstore/constants';
 import { assignBuildCredentialsAsync, getBuildCredentialsAsync } from '../BuildCredentialsUtils';
 import { chooseDevicesAsync } from '../DeviceUtils';
 import { SetUpAdhocProvisioningProfile, doUDIDsMatch } from '../SetUpAdhocProvisioningProfile';
+import { getAscApiKeyForAppSubmissionsAsync } from '../../api/GraphqlClient';
+import { AuthenticationMode, AppleTeamType } from '../../appstore/authenticateTypes';
+import { hasAscEnvVars } from '../../appstore/resolveCredentials';
+import { AppStoreConnectApiKeyQuery } from '../../../../graphql/queries/AppStoreConnectApiKeyQuery';

 jest.mock('../BuildCredentialsUtils');
 jest.mock('../../../context');
-jest.mock('../../../ios/api/GraphqlClient');
+jest.mock('../../../ios/api/GraphqlClient', () => ({
+  ...jest.requireActual('../../../ios/api/GraphqlClient'),
+  getAscApiKeyForAppSubmissionsAsync: jest.fn(),
+}));
+jest.mock('../../appstore/resolveCredentials', () => ({
+  hasAscEnvVars: jest.fn(),
+}));
+jest.mock('../../../../graphql/queries/AppStoreConnectApiKeyQuery', () => ({
+  AppStoreConnectApiKeyQuery: {
+    getByIdAsync: jest.fn(),
+  },
+}));
 jest.mock('../DeviceUtils', () => {
  return {
    __esModule: true,
+    ...jest.requireActual('../DeviceUtils'),
    chooseDevicesAsync: jest.fn(),
    formatDeviceLabel: jest.requireActual('../DeviceUtils').formatDeviceLabel,
  };
 });
+jest.mock('../SetUpDistributionCertificate', () => ({
+  SetUpDistributionCertificate: jest.fn(),
+}));
+import { SetUpDistributionCertificate } from '../SetUpDistributionCertificate';
 jest.mock('../../../../project/ios/target');
 jest.mock('../../../../prompts');

@@ -148,6 +168,231 @@ describe('runWithDistributionCertificateAsync', () => {
  });
 });

+describe('runAsync', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.restoreAllMocks();
+    jest.mocked(SetUpDistributionCertificate).mockImplementation(
+      () =>
+        ({
+          runAsync: jest.fn().mockResolvedValue({} as AppleDistributionCertificateFragment),
+        }) as any
+    );
+  });
+
+  const setUpAdhocProvisioningProfile = new SetUpAdhocProvisioningProfile({
+    app: { account: {} as Account, projectName: 'projName', bundleIdentifier: 'bundleId' },
+    target: { targetName: 'targetName', bundleIdentifier: 'bundleId', entitlements: {} },
+  });
+
+  it('skips non-interactive reuse when refresh is enabled', async () => {
+    const { ctx } = setUpTest();
+    Object.defineProperty(ctx, 'nonInteractive', { value: true });
+    Object.defineProperty(ctx, 'refreshAdHocProvisioningProfile', { value: true });
+    const areBuildCredentialsSetupAsyncSpy = jest
+      .spyOn(SetUpAdhocProvisioningProfile.prototype as any, 'areBuildCredentialsSetupAsync')
+      .mockResolvedValue(true);
+    const ensureAppStoreAuthenticatedForAdhocRefreshAsyncSpy = jest
+      .spyOn(
+        SetUpAdhocProvisioningProfile.prototype as any,
+        'ensureAppStoreAuthenticatedForAdhocRefreshAsync'
+      )
+      .mockResolvedValue(undefined);
+    jest
+      .spyOn(SetUpAdhocProvisioningProfile.prototype, 'runWithDistributionCertificateAsync')
+      .mockResolvedValue({} as IosAppBuildCredentialsFragment);
+
+    await setUpAdhocProvisioningProfile.runAsync(ctx);
+
+    expect(areBuildCredentialsSetupAsyncSpy).not.toHaveBeenCalled();
+    expect(ensureAppStoreAuthenticatedForAdhocRefreshAsyncSpy).toHaveBeenCalledWith(ctx, {
+      account: {} as Account,
+      projectName: 'projName',
+      bundleIdentifier: 'bundleId',
+    });
+    expect(
+      SetUpAdhocProvisioningProfile.prototype.runWithDistributionCertificateAsync
+    ).toHaveBeenCalled();
+    expect(getBuildCredentialsAsync).not.toHaveBeenCalled();
+  });
+
+  it('fails when refresh is enabled and credentials are frozen', async () => {
+    const { ctx } = setUpTest();
+    Object.defineProperty(ctx, 'nonInteractive', { value: true });
+    Object.defineProperty(ctx, 'refreshAdHocProvisioningProfile', { value: true });
+    Object.defineProperty(ctx, 'freezeCredentials', { value: true });
+
+    await expect(setUpAdhocProvisioningProfile.runAsync(ctx)).rejects.toThrow(
+      'Cannot refresh ad-hoc provisioning profile when credentials are frozen'
+    );
+  });
+});
+
+describe('refresh ad-hoc provisioning profile', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.restoreAllMocks();
+    jest.mocked(getApplePlatformFromTarget).mockReturnValue(ApplePlatform.IOS);
+    jest.mocked(SetUpDistributionCertificate).mockImplementation(
+      () =>
+        ({
+          runAsync: jest.fn().mockResolvedValue({} as AppleDistributionCertificateFragment),
+        }) as any
+    );
+    jest.mocked(hasAscEnvVars).mockReturnValue(false);
+    jest.mocked(getAscApiKeyForAppSubmissionsAsync).mockResolvedValue(null);
+  });
+
+  const setUpAdhocProvisioningProfile = new SetUpAdhocProvisioningProfile({
+    app: { account: {} as Account, projectName: 'projName', bundleIdentifier: 'bundleId' },
+    target: { targetName: 'targetName', bundleIdentifier: 'bundleId', entitlements: {} },
+  });
+
+  it('provisions all registered devices without prompting in refresh mode', async () => {
+    const { ctx, distCert } = setUpRefreshTest();
+    Object.defineProperty(ctx, 'nonInteractive', { value: true });
+    Object.defineProperty(ctx, 'refreshAdHocProvisioningProfile', { value: true });
+
+    await setUpAdhocProvisioningProfile.runWithDistributionCertificateAsync(ctx, distCert);
+
+    expect(chooseDevicesAsync).not.toHaveBeenCalled();
+    expect(ctx.appStore.createOrReuseAdhocProvisioningProfileAsync).toHaveBeenCalledWith(
+      ['id1', 'id2', 'id3'],
+      'bundleId',
+      distCert.serialNumber,
+      expect.anything()
+    );
+  });
+
+  it('filters devices by target platform only in refresh mode', async () => {
+    const { ctx, distCert } = setUpRefreshTest();
+    Object.defineProperty(ctx, 'nonInteractive', { value: true });
+    Object.defineProperty(ctx, 'refreshAdHocProvisioningProfile', { value: true });
+    ctx.ios.getDevicesForAppleTeamAsync = jest.fn().mockResolvedValue([
+      { identifier: 'id1', model: 'iPhone17,1', deviceClass: AppleDeviceClass.Iphone },
+      { identifier: 'id2', model: 'AppleTV6,3', deviceClass: AppleDeviceClass.Unknown },
+      { identifier: 'id3', deviceClass: AppleDeviceClass.Mac },
+    ]);
+
+    await setUpAdhocProvisioningProfile.runWithDistributionCertificateAsync(ctx, distCert);
+
+    expect(ctx.appStore.createOrReuseAdhocProvisioningProfileAsync).toHaveBeenCalledWith(
+      ['id1'],
+      'bundleId',
+      distCert.serialNumber,
+      expect.anything()
+    );
+    expect(chooseDevicesAsync).not.toHaveBeenCalled();
+  });
+
+  it('continues without prompting when some devices are not provisioned in refresh mode', async () => {
+    const { ctx, distCert } = setUpRefreshTest();
+    Object.defineProperty(ctx, 'nonInteractive', { value: true });
+    Object.defineProperty(ctx, 'refreshAdHocProvisioningProfile', { value: true });
+    jest.mocked(getBuildCredentialsAsync).mockResolvedValue({
+      provisioningProfile: {
+        appleTeam: { appleTeamIdentifier: 'team' },
+        appleDevices: [{ identifier: 'id1' }],
+        developerPortalIdentifier: 'provisioningProfileId',
+      },
+    } as IosAppBuildCredentialsFragment);
+    ctx.ios.updateProvisioningProfileAsync = jest.fn().mockResolvedValue({
+      appleTeam: { appleTeamIdentifier: 'team' },
+      appleDevices: [{ identifier: 'id1' }],
+      developerPortalIdentifier: 'provisioningProfileId',
+    });
+
+    await setUpAdhocProvisioningProfile.runWithDistributionCertificateAsync(ctx, distCert);
+
+    expect(selectAsync).not.toHaveBeenCalled();
+    expect(assignBuildCredentialsAsync).toHaveBeenCalled();
+  });
+
+  it('errors when no devices are registered in non-interactive mode', async () => {
+    const { ctx, distCert } = setUpRefreshTest();
+    Object.defineProperty(ctx, 'nonInteractive', { value: true });
+    ctx.ios.getDevicesForAppleTeamAsync = jest.fn().mockResolvedValue([]);
+
+    await expect(
+      setUpAdhocProvisioningProfile.runWithDistributionCertificateAsync(ctx, distCert)
+    ).rejects.toThrow(
+      'No devices are registered for this Apple team. Register devices with eas device:create first.'
+    );
+  });
+
+  describe('ensureAppStoreAuthenticatedForAdhocRefreshAsync', () => {
+    it('authenticates with ASC environment variables when present', async () => {
+      const { ctx } = setUpRefreshTest();
+      jest.mocked(hasAscEnvVars).mockReturnValue(true);
+      jest
+        .spyOn(SetUpAdhocProvisioningProfile.prototype, 'runWithDistributionCertificateAsync')
+        .mockResolvedValue({} as IosAppBuildCredentialsFragment);
+
+      await setUpAdhocProvisioningProfile.runAsync(ctx);
+
+      expect(ctx.appStore.ensureAuthenticatedAsync).toHaveBeenCalledWith({
+        mode: AuthenticationMode.API_KEY,
+      });
+      expect(getAscApiKeyForAppSubmissionsAsync).not.toHaveBeenCalled();
+    });
+
+    it('authenticates with the stored submissions ASC API key when env vars are absent', async () => {
+      const { ctx } = setUpRefreshTest();
+      jest.mocked(hasAscEnvVars).mockReturnValue(false);
+      jest.mocked(getAscApiKeyForAppSubmissionsAsync).mockResolvedValue({
+        id: 'asc-key-id',
+        appleTeam: {
+          appleTeamIdentifier: 'TEAM123',
+          appleTeamName: 'Team Name',
+        },
+      } as any);
+      jest.mocked(AppStoreConnectApiKeyQuery.getByIdAsync).mockResolvedValue({
+        keyP8: 'key-p8',
+        keyIdentifier: 'key-id',
+        issuerIdentifier: 'issuer-id',
+      } as any);
+      jest
+        .spyOn(SetUpAdhocProvisioningProfile.prototype, 'runWithDistributionCertificateAsync')
+        .mockResolvedValue({} as IosAppBuildCredentialsFragment);
+
+      await setUpAdhocProvisioningProfile.runAsync(ctx);
+
+      expect(ctx.appStore.ensureAuthenticatedAsync).toHaveBeenCalledWith({
+        mode: AuthenticationMode.API_KEY,
+        ascApiKey: {
+          keyP8: 'key-p8',
+          keyId: 'key-id',
+          issuerId: 'issuer-id',
+        },
+        teamId: 'TEAM123',
+        teamName: 'Team Name',
+        teamType: AppleTeamType.COMPANY_OR_ORGANIZATION,
+      });
+    });
+  });
+});
+
+function setUpRefreshTest(): {
+  ctx: CredentialsContext;
+  distCert: AppleDistributionCertificateFragment;
+} {
+  const { ctx, distCert } = setUpTest();
+  Object.defineProperty(ctx, 'nonInteractive', { value: true });
+  Object.defineProperty(ctx, 'refreshAdHocProvisioningProfile', { value: true });
+  distCert.appleTeam = {
+    appleTeamIdentifier: 'team',
+  } as AppleDistributionCertificateFragment['appleTeam'];
+  distCert.serialNumber = 'serial-number';
+  ctx.appStore.ensureAuthenticatedAsync = jest.fn().mockResolvedValue({});
+  jest.mocked(getBuildCredentialsAsync).mockResolvedValue(null);
+  ctx.ios.getDevicesForAppleTeamAsync = jest.fn().mockResolvedValue([
+    { identifier: 'id1', deviceClass: AppleDeviceClass.Iphone },
+    { identifier: 'id2', deviceClass: AppleDeviceClass.Ipad },
+    { identifier: 'id3', deviceClass: AppleDeviceClass.Iphone },
+  ] as AppleDeviceFragment[]);
+  return { ctx, distCert };
+}
+
 function setUpTest(): { ctx: CredentialsContext; distCert: AppleDistributionCertificateFragment } {
  const ctx = jest.mocked(
    new CredentialsContext(
@@ -177,8 +422,7 @@ function setUpTest(): { ctx: CredentialsContext; distCert: AppleDistributionCert
    { identifier: 'id2', name: 'Device 2', deviceClass: AppleDeviceClass.Iphone },
    { identifier: 'id3', name: 'Device 3', deviceClass: AppleDeviceClass.Mac },
  ] as AppleDevice[]);
-  // @ts-expect-error
-  jest.mocked(getApplePlatformFromTarget).mockResolvedValue(ApplePlatform.IOS);
+  jest.mocked(getApplePlatformFromTarget).mockReturnValue(ApplePlatform.IOS);
  Object.defineProperty(ctx, 'appStore', { value: jest.mock('../../appstore/AppStoreApi') });
  ctx.appStore.createOrReuseAdhocProvisioningProfileAsync = jest.fn().mockResolvedValue({
    provisioningProfileId: 'provisioningProfileId',
@@ -186,6 +430,11 @@ function setUpTest(): { ctx: CredentialsContext; distCert: AppleDistributionCert
  ctx.ios.createOrGetExistingAppleAppIdentifierAsync = jest
    .fn()
    .mockResolvedValue({} as AppleAppIdentifierFragment);
+  ctx.ios.createProvisioningProfileAsync = jest.fn().mockResolvedValue({
+    appleTeam: { appleTeamIdentifier: 'team' },
+    appleDevices: [{ identifier: 'id1' }, { identifier: 'id2' }, { identifier: 'id3' }],
+    developerPortalIdentifier: 'provisioningProfileId',
+  });
  jest.mocked(assignBuildCredentialsAsync).mockResolvedValue({} as IosAppBuildCredentialsFragment);
  const distCert = {} as AppleDistributionCertificateFragment;
  return { ctx, distCert };
@@ -0,0 +1,110 @@
+import { Env } from '@expo/eas-build-job';
+import { EasJson } from '@expo/eas-json';
+
+import { Analytics } from '../../../../analytics/AnalyticsManager';
+import { ExpoGraphqlClient } from '../../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { Account, IosAppBuildCredentialsFragment } from '../../../../graphql/generated';
+import { Actor } from '../../../../user/User';
+import { Client } from '../../../../vcs/vcs';
+import { CredentialsContext, CredentialsContextProjectInfo } from '../../../context';
+import { SetUpAdhocProvisioningProfile } from '../SetUpAdhocProvisioningProfile';
+import { SetUpInternalProvisioningProfile } from '../SetUpInternalProvisioningProfile';
+import { SetUpTargetBuildCredentials } from '../SetUpTargetBuildCredentials';
+
+jest.mock('../SetUpAdhocProvisioningProfile', () => ({
+  SetUpAdhocProvisioningProfile: jest.fn(),
+}));
+jest.mock('../SetUpInternalProvisioningProfile', () => ({
+  SetUpInternalProvisioningProfile: jest.fn(),
+}));
+jest.mock('../../../context');
+
+describe(SetUpTargetBuildCredentials, () => {
+  const app = {
+    account: { name: 'account' } as Account,
+    projectName: 'projName',
+    bundleIdentifier: 'bundleId',
+  };
+  const target = { targetName: 'targetName', bundleIdentifier: 'bundleId', entitlements: {} };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.mocked(SetUpAdhocProvisioningProfile).mockImplementation(
+      () =>
+        ({
+          runAsync: jest.fn().mockResolvedValue({} as IosAppBuildCredentialsFragment),
+        }) as any
+    );
+    jest.mocked(SetUpInternalProvisioningProfile).mockImplementation(
+      () =>
+        ({
+          runAsync: jest.fn().mockResolvedValue({} as IosAppBuildCredentialsFragment),
+        }) as any
+    );
+  });
+
+  function createCtx(overrides: Partial<CredentialsContext> = {}): CredentialsContext {
+    const ctx = jest.mocked(
+      new CredentialsContext(
+        {} as {
+          projectInfo: CredentialsContextProjectInfo | null;
+          easJsonCliConfig?: EasJson['cli'];
+          nonInteractive: boolean;
+          projectDir: string;
+          user: Actor;
+          graphqlClient: ExpoGraphqlClient;
+          analytics: Analytics;
+          env?: Env;
+          vcsClient: Client;
+        }
+      )
+    );
+    Object.defineProperty(ctx, 'refreshAdHocProvisioningProfile', {
+      value: true,
+      writable: true,
+    });
+    return Object.assign(ctx, overrides);
+  }
+
+  it('errors when refresh is enabled for store distribution builds', async () => {
+    const action = new SetUpTargetBuildCredentials({
+      app,
+      distribution: 'store',
+      entitlements: {},
+      target,
+    });
+
+    await expect(action.setupBuildCredentialsAsync(createCtx())).rejects.toThrow(
+      '--refresh-ad-hoc-provisioning-profile is only supported for internal distribution builds.'
+    );
+  });
+
+  it('errors when refresh is enabled for universal enterprise internal builds', async () => {
+    const action = new SetUpTargetBuildCredentials({
+      app,
+      distribution: 'internal',
+      enterpriseProvisioning: 'universal',
+      entitlements: {},
+      target,
+    });
+
+    await expect(action.setupBuildCredentialsAsync(createCtx())).rejects.toThrow(
+      '--refresh-ad-hoc-provisioning-profile is only supported for ad-hoc internal builds.'
+    );
+  });
+
+  it('delegates to internal provisioning setup when refresh is enabled for internal ad-hoc builds', async () => {
+    const action = new SetUpTargetBuildCredentials({
+      app,
+      distribution: 'internal',
+      entitlements: {},
+      target,
+    });
+    const ctx = createCtx();
+
+    await action.setupBuildCredentialsAsync(ctx);
+
+    expect(SetUpInternalProvisioningProfile).toHaveBeenCalledWith({ app, target });
+    expect(SetUpAdhocProvisioningProfile).not.toHaveBeenCalled();
+  });
+});
@@ -1,16 +1,46 @@
 import { CombinedError } from '@urql/core';

+import Log from '../../log';
 import {
  EAS_CLI_UPGRADE_REQUIRED_ERROR_CODE,
+  withErrorHandlingAsync,
  withUpgradeRequiredErrorHandlingAsync,
 } from '../client';

+jest.mock('../../log');
+
 function makeError(message: string, extensions?: Record<string, unknown>): CombinedError {
  return new CombinedError({
    graphQLErrors: [{ message, extensions } as any],
  });
 }

+const mockLogError = jest.mocked(Log.error);
+
+describe(withErrorHandlingAsync, () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('logs the transient error message for generic transient errors', async () => {
+    const error = makeError('Transient failure', {
+      isTransient: true,
+      errorCode: 'SOME_TRANSIENT',
+    });
+    await expect(withErrorHandlingAsync(Promise.resolve({ error } as any))).rejects.toBe(error);
+    expect(mockLogError).toHaveBeenCalledWith(
+      expect.stringContaining("We've encountered a transient error")
+    );
+  });
+
+  it('suppresses the transient error message for EMBEDDED_UPDATE_ASSET_NOT_AVAILABLE', async () => {
+    const error = makeError('Asset not yet available', {
+      isTransient: true,
+      errorCode: 'EMBEDDED_UPDATE_ASSET_NOT_AVAILABLE',
+    });
+    await expect(withErrorHandlingAsync(Promise.resolve({ error } as any))).rejects.toBe(error);
+    expect(mockLogError).not.toHaveBeenCalled();
+  });
+});
+
 describe(withUpgradeRequiredErrorHandlingAsync, () => {
  it('returns data when the promise resolves successfully', async () => {
    const result = await withUpgradeRequiredErrorHandlingAsync(
@@ -16,6 +16,7 @@ export async function withErrorHandlingAsync<T>(promise: Promise<OperationResult
          ![
            'EAS_BUILD_FREE_TIER_LIMIT_EXCEEDED',
            'EAS_BUILD_FREE_TIER_IOS_LIMIT_EXCEEDED',
+            'EMBEDDED_UPDATE_ASSET_NOT_AVAILABLE',
          ].includes(e?.extensions?.errorCode as string)
      )
    ) {