v20.3.0

Fixes Argent remote simulator sessions getting stuck immediately after starting the Argent tool-server.

The latest Argent support change switched the startup path to `bunx @swmansion/argent server start ...` and awaited that process. When the server process stays in the foreground, the build step never advances to read the tool-server state file, start the ngrok tunnel, or report remote config back to the API.

This restores detached process launching for the Argent tool-server while keeping the new server/auth flow. If the state file is not created in time, the error now includes captured Argent process output to aid diagnosis.

Failing job run referenced while debugging: https://expo.dev/accounts/sjchmiela/projects/test-production/job-runs/019eda48-6467-789d-8c5e-a7ed5f4ec89d

.vscode/settings.json

@@ -5,5 +5,6 @@
     "**/*.code-search": true,
     "**/src/**/build/**": false,
     "**/src/build/**": false,
-  }
+  },
+  "js/ts.tsdk.path": "node_modules/typescript/lib"
 }

CHANGELOG.md

@@ -8,10 +8,87 @@ This is the log of notable changes to EAS CLI and related packages.
 
 ### 🎉 New features
 
+- [eas-cli] Add `eas account:audit [ACCOUNT_NAME]` command to view an account's audit logs. ([#3863](https://github.com/expo/eas-cli/pull/3863) by [@keith-kurak](https://github.com/keith-kurak))
+- [eas-cli] `eas update:view [GROUP_ID]` now also accepts a platform-specific update ID, resolving it to and displaying its update group. ([#3864](https://github.com/expo/eas-cli/pull/3864) by [@keith-kurak](https://github.com/keith-kurak))
+- [eas-cli] Add `eas integrations:posthog:connect` command. ([#3836](https://github.com/expo/eas-cli/pull/3836) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add `eas integrations:posthog:dashboard` command. ([#3837](https://github.com/expo/eas-cli/pull/3837) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add `eas integrations:posthog:disconnect` command. ([#3838](https://github.com/expo/eas-cli/pull/3838) by [@gwdp](https://github.com/gwdp))
+
 ### 🐛 Bug fixes
 
+- [eas-cli] `eas integrations:posthog:connect` no longer aborts when `npx expo install` reports an error (for example, on a dynamic app config); it finishes writing the environment variables and prints any remaining manual steps. ([#3877](https://github.com/expo/eas-cli/pull/3877) by [@gwdp](https://github.com/gwdp))
+
 ### 🧹 Chores
 
+- [eas-cli] Simplify 2FA now that SMS is no longer supported. ([#3859](https://github.com/expo/eas-cli/pull/3859) by [@wschurman](https://github.com/wschurman))
+
+## [20.2.0](https://github.com/expo/eas-cli/releases/tag/v20.2.0) - 2026-06-15
+
+### 🎉 New features
+
+- [eas-cli] Non-interactive iOS App Store and Enterprise builds can now use the App Store Connect API key stored in EAS credentials as a submission key to validate and repair provisioning profiles on Apple servers, without requiring `EXPO_ASC_*` environment variables or an interactive Apple login. ([#3805](https://github.com/expo/eas-cli/pull/3805) by [@sswrk](https://github.com/sswrk))
+- [eas-cli] Add support for non-interactive `eas update:rollback [GROUP_ID]`. The given update group must be the latest for its branch and runtime version; the previous update group is republished, or a roll back to the embedded update is published if there is none. ([#3825](https://github.com/expo/eas-cli/pull/3825) by [@quinlanj](https://github.com/quinlanj))
+
+### 🐛 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))
+- [eas-cli] Fix `update:embedded` topic showing the `update:embedded:delete` subcommand description in the command listing. ([#3866](https://github.com/expo/eas-cli/pull/3866) by [@jc-expo](https://github.com/jc-expo))
+
+## [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
+
+- [build-tools] Update the minimum Expo version required for iOS precompiled modules to 55.0.26. ([#3771](https://github.com/expo/eas-cli/pull/3771) by [@chrfalch](https://github.com/chrfalch))
+
+## [19.0.5](https://github.com/expo/eas-cli/releases/tag/v19.0.5) - 2026-05-20
+
+### 🐛 Bug fixes
+
+- [eas-cli] Improve Sentry diagnostics for managed iOS entitlements config fallback. ([#3763](https://github.com/expo/eas-cli/pull/3763) by [@sjchmiela](https://github.com/sjchmiela))
+
+## [19.0.4](https://github.com/expo/eas-cli/releases/tag/v19.0.4) - 2026-05-20
+
 ## [19.0.1](https://github.com/expo/eas-cli/releases/tag/v19.0.1) - 2026-05-19
 
 ### 🐛 Bug fixes

lerna.json

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

mise.toml

@@ -3,4 +3,6 @@ _.path = "./tools/bin"
 MISE_NODE_COREPACK = "true"
 
 [tools]
+gcloud = "570.0.0"
+jq = "1.8.1"
 node = "20.19.4"

packages/build-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/build-tools",
-  "version": "19.0.0",
+  "version": "20.3.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",

packages/build-tools/src/__tests__/datadog.test.ts

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

packages/build-tools/src/__tests__/runtimeSettings.test.ts

@@ -0,0 +1,329 @@
+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 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();
+    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' });
+    jest.mocked(fetch).mockReset();
+  });
+
+  it('fetches runtime settings from the staging and production buckets', async () => {
+    jest.mocked(fetch).mockResolvedValue(response({}));
+
+    await RuntimeSettings.loadAsync({ environment: 'staging' });
+    await RuntimeSettings.loadAsync({ environment: 'production' });
+    await RuntimeSettings.loadAsync({ environment: 'test' });
+
+    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' });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+    expect(RuntimeSettings.isUsingIosPrecompiledModulesEnabled()).toBe(false);
+    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' });
+    await RuntimeSettings.loadAsync({ environment: 'staging' });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBe('https://npm.example');
+    expect(RuntimeSettings.isUsingIosPrecompiledModulesEnabled()).toBe(false);
+    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' });
+
+    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' });
+
+    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 job environment flags to enable cache URLs from worker environment variables', async () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+
+    await RuntimeSettings.loadAsync({
+      environment: 'test',
+      env: {
+        EAS_USE_NPM_CACHE: '1',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBe('https://npm.example');
+  });
+
+  it('returns null when job env enables cache but worker env var is empty', async () => {
+    process.env.EAS_NPM_CACHE_URL = '';
+
+    await RuntimeSettings.loadAsync({
+      environment: 'test',
+      env: {
+        EAS_USE_NPM_CACHE: '1',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+  });
+
+  it('does not use cache URLs from the job environment', async () => {
+    await RuntimeSettings.loadAsync({
+      environment: 'test',
+      env: {
+        EAS_USE_NPM_CACHE: '1',
+        EAS_NPM_CACHE_URL: 'https://job-npm.example',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+  });
+
+  it('does not enable cache when runtime settings explicitly disable it, even with job env flag', async () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+    jest.mocked(fetch).mockResolvedValue(response({ caches: { linux: { npm: false } } }));
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      env: {
+        EAS_USE_NPM_CACHE: '1',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+  });
+
+  it('disables cache when EAS_BUILD_DISABLE_NPM_CACHE is set', async () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+    jest.mocked(fetch).mockResolvedValue(response({ caches: { linux: { npm: true } } }));
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      env: {
+        EAS_BUILD_DISABLE_NPM_CACHE: '1',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getNpmCacheUrl()).toBeNull();
+  });
+
+  it('disables cache when EAS_BUILD_DISABLE_MAVEN_CACHE is set', async () => {
+    process.env.EAS_MAVEN_CACHE_URL = 'https://maven.example';
+    jest.mocked(fetch).mockResolvedValue(response({ caches: { linux: { maven: true } } }));
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      env: {
+        EAS_BUILD_DISABLE_MAVEN_CACHE: '1',
+      },
+    });
+
+    mockProcessPlatform('linux');
+    expect(RuntimeSettings.getMavenCacheUrl()).toBeNull();
+  });
+
+  it('disables cache when EAS_BUILD_DISABLE_COCOAPODS_CACHE is set', async () => {
+    process.env.EAS_COCOAPODS_CACHE_URL = 'https://pods.example';
+    jest.mocked(fetch).mockResolvedValue(response({ caches: { darwin: { cocoapods: true } } }));
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      env: {
+        EAS_BUILD_DISABLE_COCOAPODS_CACHE: '1',
+      },
+    });
+
+    mockProcessPlatform('darwin');
+    expect(RuntimeSettings.getCocoapodsCacheUrl()).toBeNull();
+  });
+
+  it('allows job environment flags to disable remotely enabled cache URLs', async () => {
+    process.env.EAS_NPM_CACHE_URL = 'https://npm.example';
+    jest.mocked(fetch).mockResolvedValue(response({ caches: { linux: { npm: true } } }));
+
+    await RuntimeSettings.loadAsync({
+      environment: 'staging',
+      env: {
+        EAS_USE_NPM_CACHE: '0',
+      },
+    });
+
+    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' });
+
+    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,
+  };
+}

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

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

packages/build-tools/src/builders/__tests__/custom.test.ts

@@ -7,6 +7,7 @@ import { createMockLogger } from '../../__tests__/utils/logger';
 import { prepareProjectSourcesAsync } from '../../common/projectSources';
 import { BuildContext } from '../../context';
 import { CustomBuildContext } from '../../customBuildContext';
+import { Datadog } from '../../datadog';
 import { findAndUploadXcodeBuildLogsAsync } from '../../ios/xcodeBuildLogs';
 import { runCustomBuildAsync } from '../custom';
 
@@ -17,6 +18,7 @@ const findAndUploadXcodeBuildLogsAsyncMock = jest.mocked(findAndUploadXcodeBuild
 
 describe(runCustomBuildAsync, () => {
   let ctx: BuildContext<BuildJob>;
+  const datadogLogSpy = jest.spyOn(Datadog, 'log');
 
   beforeEach(() => {
     const job = createTestIosJob();
@@ -27,10 +29,24 @@ describe(runCustomBuildAsync, () => {
       vol.fromJSON(
         {
           'test.yaml': `
+          functions:
+            test_function:
+              name: Test function
+              path: ./custom-function
+              shell: /bin/zsh
+              supported_platforms:
+                - darwin
+                - linux
+              inputs:
+                - name
+                - profile
+              outputs:
+                - artifact_path
           build:
             steps:
               - eas/checkout
           `,
+          'custom-function/package.json': '{}',
         },
         '/workingdir/temporary-custom-build'
       );
@@ -77,6 +93,21 @@ describe(runCustomBuildAsync, () => {
     expect(prepareProjectSourcesAsync).toHaveBeenCalledTimes(2);
   });
 
+  it('reports user-provided custom functions when parsing the custom build config', async () => {
+    await runCustomBuildAsync(ctx);
+
+    expect(datadogLogSpy).toHaveBeenCalledWith('Custom build saw user-provided function', {
+      event: 'custom_build_user_provided_function',
+      custom_function_id: 'test_function',
+      custom_function_input_count: '2',
+      custom_function_module_path: '/workingdir/temporary-custom-build/custom-function',
+      custom_function_name: 'Test function',
+      custom_function_output_count: '1',
+      custom_function_shell: '/bin/zsh',
+      custom_function_supported_runtime_platforms: 'darwin,linux',
+    });
+  });
+
   it('awaits drainPendingMetricUploads after workflow execution', async () => {
     let resolveDrain!: () => void;
     const drainSpy = jest

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

@@ -10,6 +10,8 @@ import {
   resolveGradleCommand,
   runGradleCommand,
 } from '../android/gradle';
+import { parseGradleProfile, formatGradleProfileReport } from '../android/gradleProfile';
+import { Sentry } from '../sentry';
 import { eagerBundleAsync, shouldUseEagerBundle } from '../common/eagerBundle';
 import { prebuildAsync } from '../common/prebuild';
 import { setupAsync } from '../common/setup';
@@ -30,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';
 
@@ -180,6 +183,20 @@ async function buildAsync(ctx: BuildContext<Android.Job>): Promise<void> {
     });
   });
 
+  await ctx.runBuildPhase(BuildPhase.GRADLE_BUILD_PROFILE, async () => {
+    try {
+      const androidDir = path.join(ctx.getReactNativeProjectDirectory(), 'android');
+      const profileTasks = await parseGradleProfile(androidDir);
+      if (profileTasks.length > 0) {
+        const report = formatGradleProfileReport(profileTasks);
+        ctx.logger.info(report);
+      }
+    } catch (err: any) {
+      Sentry.capture('Failed to parse Gradle build profile', err);
+      ctx.markBuildPhaseSkipped();
+    }
+  });
+
   await ctx.runBuildPhase(BuildPhase.PRE_UPLOAD_ARTIFACTS_HOOK, async () => {
     await runHookIfPresent(ctx, Hook.PRE_UPLOAD_ARTIFACTS);
   });
@@ -192,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.');

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

@@ -1,5 +1,11 @@
 import { BuildJob, BuildPhase, BuildTrigger, Ios, Platform } from '@expo/eas-build-job';
-import { BuildConfigParser, BuildStepGlobalContext, StepsConfigParser, errors } from '@expo/steps';
+import {
+  BuildConfigParser,
+  BuildStepGlobalContext,
+  BuildWorkflow,
+  StepsConfigParser,
+  errors,
+} from '@expo/steps';
 import assert from 'assert';
 import fs from 'fs/promises';
 import nullthrows from 'nullthrows';
@@ -9,6 +15,7 @@ import { resolveEnvFromBuildProfileAsync } from '../common/easBuildInternal';
 import { prepareProjectSourcesAsync } from '../common/projectSources';
 import { Artifacts, BuildContext } from '../context';
 import { CustomBuildContext } from '../customBuildContext';
+import { Datadog } from '../datadog';
 import { findAndUploadXcodeBuildLogsAsync } from '../ios/xcodeBuildLogs';
 import { getEasFunctionGroups } from '../steps/easFunctionGroups';
 import { getEasFunctions } from '../steps/easFunctions';
@@ -81,6 +88,7 @@ export async function runCustomBuildAsync(ctx: BuildContext<BuildJob>): Promise<
       throw parseError;
     }
   });
+  logUserProvidedCustomFunctions(workflow);
   try {
     try {
       await workflow.executeAsync();
@@ -103,3 +111,26 @@ export async function runCustomBuildAsync(ctx: BuildContext<BuildJob>): Promise<
 
   return ctx.artifacts;
 }
+
+function logUserProvidedCustomFunctions(workflow: BuildWorkflow): void {
+  for (const buildFunction of Object.values(workflow.buildFunctions)) {
+    if (!buildFunction.customFunctionModulePath) {
+      continue;
+    }
+    Datadog.log('Custom build saw user-provided function', {
+      event: 'custom_build_user_provided_function',
+      custom_function_id: buildFunction.getFullId(),
+      custom_function_module_path: buildFunction.customFunctionModulePath,
+      custom_function_input_count: String(buildFunction.inputProviders?.length ?? 0),
+      custom_function_output_count: String(buildFunction.outputProviders?.length ?? 0),
+      ...(buildFunction.name ? { custom_function_name: buildFunction.name } : {}),
+      ...(buildFunction.shell ? { custom_function_shell: buildFunction.shell } : {}),
+      ...(buildFunction.supportedRuntimePlatforms
+        ? {
+            custom_function_supported_runtime_platforms:
+              buildFunction.supportedRuntimePlatforms.join(','),
+          }
+        : {}),
+    });
+  }
+}

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

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

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

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

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

@@ -0,0 +1,222 @@
+import spawn, { SpawnPromise, SpawnResult } from '@expo/turtle-spawn';
+
+import { createMockLogger } from '../../__tests__/utils/logger';
+import { Sentry } from '../../sentry';
+import { PackageManager } from '../../utils/packageManager';
+import { installDependenciesWithNpmCacheFallbackAsync } from '../installDependencies';
+
+jest.mock('@expo/turtle-spawn', () => jest.fn());
+jest.mock('../../sentry', () => ({
+  Sentry: {
+    capture: jest.fn(),
+  },
+}));
+
+describe(installDependenciesWithNpmCacheFallbackAsync, () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('retries without NPM_CONFIG_REGISTRY when npm cache install fails', async () => {
+    const logger = createMockLogger();
+    const npmCacheUrl = 'http://npm.staging.caches.eas-build.internal';
+    const error = Object.assign(
+      new Error('npm install --include=dev exited with non-zero code: 1'),
+      {
+        status: 1,
+        signal: null,
+        stdout: '',
+        stderr: `npm error request to ${npmCacheUrl}/left-pad failed, reason: getaddrinfo ENOTFOUND npm.staging.caches.eas-build.internal`,
+      }
+    );
+
+    jest
+      .mocked(spawn)
+      .mockReturnValueOnce(createSpawnPromise(Promise.reject(error)))
+      .mockReturnValueOnce(createSpawnPromise(Promise.resolve(createSpawnResult())));
+
+    await installDependenciesWithNpmCacheFallbackAsync({
+      packageManager: PackageManager.NPM,
+      env: {
+        EAS_VERBOSE: '1',
+        EAS_USE_NPM_CACHE: '1',
+        NPM_CONFIG_REGISTRY: npmCacheUrl,
+      },
+      logger,
+      cwd: '/tmp/build',
+      useFrozenLockfile: false,
+    });
+
+    expect(spawn).toHaveBeenCalledTimes(2);
+    expect(spawn).toHaveBeenNthCalledWith(1, 'npm', ['install', '--include=dev', '--verbose'], {
+      cwd: '/tmp/build',
+      logger,
+      infoCallbackFn: undefined,
+      lineTransformer: expect.any(Function),
+      env: {
+        EAS_VERBOSE: '1',
+        EAS_USE_NPM_CACHE: '1',
+        NPM_CONFIG_REGISTRY: npmCacheUrl,
+      },
+    });
+    expect(spawn).toHaveBeenNthCalledWith(2, 'npm', ['install', '--include=dev', '--verbose'], {
+      cwd: '/tmp/build',
+      logger,
+      infoCallbackFn: undefined,
+      env: {
+        EAS_VERBOSE: '1',
+        EAS_USE_NPM_CACHE: '1',
+      },
+    });
+    expect(logger.warn).toHaveBeenCalledWith(
+      `Failed to install dependencies using the npm cache registry (${npmCacheUrl}). Retrying without the npm cache registry.`
+    );
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'Failed to install dependencies using npm cache registry',
+        name: 'NpmCacheRegistryInstallError',
+      }),
+      {
+        level: 'warning',
+        tags: {
+          packageManager: 'npm',
+        },
+        extras: {
+          cwd: '/tmp/build',
+          npmCacheUrl,
+          useFrozenLockfile: false,
+          originalErrorMessage: 'npm install --include=dev exited with non-zero code: 1',
+          status: 1,
+          signal: null,
+        },
+      }
+    );
+  });
+
+  it('reports non-fatal npm cache registry errors from successful installs', async () => {
+    const logger = createMockLogger();
+    const npmCacheUrl = 'http://npm.staging.caches.eas-build.internal';
+    const auditErrorLine = `npm verbose audit error FetchError: request to ${npmCacheUrl}/-/npm/v1/security/advisories/bulk failed, reason: getaddrinfo ENOTFOUND npm.staging.caches.eas-build.internal`;
+
+    jest.mocked(spawn).mockImplementationOnce((_command, _args, options: any) => {
+      options.lineTransformer(auditErrorLine);
+      options.lineTransformer(
+        `npm http cache left-pad@${npmCacheUrl}/left-pad/-/left-pad-1.3.0.tgz 0ms (cache hit)`
+      );
+      return createSpawnPromise(Promise.resolve(createSpawnResult()));
+    });
+
+    await installDependenciesWithNpmCacheFallbackAsync({
+      packageManager: PackageManager.NPM,
+      env: {
+        EAS_USE_NPM_CACHE: '1',
+        NPM_CONFIG_REGISTRY: npmCacheUrl,
+      },
+      logger,
+      cwd: '/tmp/build',
+      useFrozenLockfile: false,
+    });
+
+    expect(spawn).toHaveBeenCalledTimes(1);
+    expect(Sentry.capture).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'Non-fatal npm cache registry error during dependency install',
+        name: 'NpmCacheRegistryNonFatalError',
+      }),
+      {
+        level: 'warning',
+        tags: {
+          packageManager: 'npm',
+        },
+        extras: {
+          cwd: '/tmp/build',
+          npmCacheUrl,
+          useFrozenLockfile: false,
+          firstErrorLine: auditErrorLine,
+          errorLineCount: 1,
+        },
+      }
+    );
+  });
+
+  it('does not retry when install failure does not reference npm cache registry', async () => {
+    const logger = createMockLogger();
+    const error = Object.assign(
+      new Error('npm install --include=dev exited with non-zero code: 1'),
+      {
+        status: 1,
+        signal: null,
+        stdout: '',
+        stderr: 'npm error command sh -c node postinstall.js',
+      }
+    );
+
+    jest.mocked(spawn).mockReturnValueOnce(createSpawnPromise(Promise.reject(error)));
+
+    await expect(
+      installDependenciesWithNpmCacheFallbackAsync({
+        packageManager: PackageManager.NPM,
+        env: {
+          EAS_USE_NPM_CACHE: '1',
+          NPM_CONFIG_REGISTRY: 'http://npm.staging.caches.eas-build.internal',
+        },
+        logger,
+        cwd: '/tmp/build',
+        useFrozenLockfile: false,
+      })
+    ).rejects.toThrow(error);
+
+    expect(spawn).toHaveBeenCalledTimes(1);
+    expect(Sentry.capture).not.toHaveBeenCalled();
+  });
+
+  it('does not retry when EAS_USE_NPM_CACHE is not enabled', async () => {
+    const logger = createMockLogger();
+    const npmCacheUrl = 'http://npm.staging.caches.eas-build.internal';
+    const error = Object.assign(
+      new Error('npm install --include=dev exited with non-zero code: 1'),
+      {
+        status: 1,
+        signal: null,
+        stdout: '',
+        stderr: `npm error request to ${npmCacheUrl}/left-pad failed, reason: getaddrinfo ENOTFOUND npm.staging.caches.eas-build.internal`,
+      }
+    );
+
+    jest.mocked(spawn).mockReturnValueOnce(createSpawnPromise(Promise.reject(error)));
+
+    await expect(
+      installDependenciesWithNpmCacheFallbackAsync({
+        packageManager: PackageManager.NPM,
+        env: {
+          NPM_CONFIG_REGISTRY: npmCacheUrl,
+        },
+        logger,
+        cwd: '/tmp/build',
+        useFrozenLockfile: false,
+      })
+    ).rejects.toThrow(error);
+
+    expect(spawn).toHaveBeenCalledTimes(1);
+    expect(Sentry.capture).not.toHaveBeenCalled();
+  });
+});
+
+function createSpawnPromise(result: Promise<SpawnResult>): SpawnPromise<SpawnResult> {
+  return Object.assign(result, {
+    child: {
+      pid: 123,
+    },
+  }) as SpawnPromise<SpawnResult>;
+}
+
+function createSpawnResult(): SpawnResult {
+  return {
+    pid: 123,
+    output: ['', ''],
+    stdout: '',
+    stderr: '',
+    status: 0,
+    signal: null,
+  };
+}

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

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

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

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

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

@@ -1,8 +1,9 @@
-import { Job } from '@expo/eas-build-job';
+import { Job, SystemError } from '@expo/eas-build-job';
 import spawn, { SpawnOptions, SpawnPromise, SpawnResult } from '@expo/turtle-spawn';
 import path from 'path';
 
 import { BuildContext } from '../context';
+import { Sentry } from '../sentry';
 import { PackageManager, findPackagerRootDir } from '../utils/packageManager';
 import { isUsingModernYarnVersion } from '../utils/project';
 
@@ -11,6 +12,7 @@ export async function installDependenciesAsync({
   env,
   logger,
   infoCallbackFn,
+  lineTransformer,
   cwd,
   useFrozenLockfile,
 }: {
@@ -19,6 +21,7 @@ export async function installDependenciesAsync({
   cwd: string;
   logger: Exclude<SpawnOptions['logger'], undefined>;
   infoCallbackFn?: SpawnOptions['infoCallbackFn'];
+  lineTransformer?: SpawnOptions['lineTransformer'];
   useFrozenLockfile: boolean;
 }): Promise<{ spawnPromise: SpawnPromise<SpawnResult> }> {
   let args: string[];
@@ -69,11 +72,92 @@ export async function installDependenciesAsync({
       cwd,
       logger,
       infoCallbackFn,
+      lineTransformer,
       env,
     }),
   };
 }
 
+export async function installDependenciesWithNpmCacheFallbackAsync({
+  packageManager,
+  env,
+  logger,
+  infoCallbackFn,
+  cwd,
+  useFrozenLockfile,
+}: {
+  packageManager: PackageManager;
+  env: Record<string, string | undefined>;
+  cwd: string;
+  logger: Exclude<SpawnOptions['logger'], undefined>;
+  infoCallbackFn?: SpawnOptions['infoCallbackFn'];
+  useFrozenLockfile: boolean;
+}): Promise<void> {
+  const npmCacheUrl = env.NPM_CONFIG_REGISTRY;
+  let firstErrorLine: string | undefined;
+  let errorLineCount = 0;
+
+  try {
+    await (
+      await installDependenciesAsync({
+        packageManager,
+        env,
+        logger,
+        infoCallbackFn,
+        lineTransformer: (line: string) => {
+          if (isNpmCacheRegistryErrorLine(line, { env, npmCacheUrl })) {
+            firstErrorLine ??= line;
+            errorLineCount += 1;
+          }
+          return line;
+        },
+        cwd,
+        useFrozenLockfile,
+      })
+    ).spawnPromise;
+
+    if (firstErrorLine) {
+      Sentry.capture(new NpmCacheRegistryNonFatalError(), {
+        level: 'warning',
+        tags: { packageManager },
+        extras: { cwd, npmCacheUrl, useFrozenLockfile, firstErrorLine, errorLineCount },
+      });
+    }
+  } catch (err: unknown) {
+    if (!isNpmCacheInstallFailure(err, { env, npmCacheUrl })) {
+      throw err;
+    }
+
+    logger.warn(
+      `Failed to install dependencies using the npm cache registry (${npmCacheUrl}). Retrying without the npm cache registry.`
+    );
+    Sentry.capture(new NpmCacheRegistryInstallError(err), {
+      level: 'warning',
+      tags: { packageManager },
+      extras: {
+        cwd,
+        npmCacheUrl,
+        useFrozenLockfile,
+        originalErrorMessage: err instanceof Error ? err.message : String(err),
+        status: err instanceof Error ? (err as any).status : undefined,
+        signal: err instanceof Error ? (err as any).signal : undefined,
+      },
+    });
+
+    const { NPM_CONFIG_REGISTRY: _NPM_CONFIG_REGISTRY, ...fallbackEnv } = env;
+    await (
+      await installDependenciesAsync({
+        packageManager,
+        env: fallbackEnv,
+        logger,
+        infoCallbackFn,
+        cwd,
+        useFrozenLockfile,
+      })
+    ).spawnPromise;
+  }
+}
+
 export function resolvePackagerDir(ctx: BuildContext<Job>): string {
   const packagerRunDir = findPackagerRootDir(ctx.getReactNativeProjectDirectory());
   if (packagerRunDir !== ctx.getReactNativeProjectDirectory()) {
@@ -87,3 +171,54 @@ export function resolvePackagerDir(ctx: BuildContext<Job>): string {
   }
   return packagerRunDir;
 }
+
+function isNpmCacheInstallFailure(
+  err: unknown,
+  { env, npmCacheUrl }: { env: Record<string, string | undefined>; npmCacheUrl: string | undefined }
+): boolean {
+  if (!isNpmCacheRegistryEnabled(env, npmCacheUrl)) {
+    return false;
+  }
+  const errorOutput = getErrorOutput(err);
+  return errorOutput.includes(npmCacheUrl);
+}
+
+function isNpmCacheRegistryErrorLine(
+  line: string,
+  { env, npmCacheUrl }: { env: Record<string, string | undefined>; npmCacheUrl: string | undefined }
+): boolean {
+  return (
+    isNpmCacheRegistryEnabled(env, npmCacheUrl) &&
+    line.includes(npmCacheUrl) &&
+    /(?:error|failed|ENOTFOUND|ECONN|ETIMEDOUT|EAI_AGAIN|FetchError)/i.test(line)
+  );
+}
+
+function isNpmCacheRegistryEnabled(
+  env: Record<string, string | undefined>,
+  npmCacheUrl: string | undefined
+): npmCacheUrl is string {
+  return env.EAS_USE_NPM_CACHE === '1' && !!npmCacheUrl;
+}
+
+function getErrorOutput(err: unknown): string {
+  if (!(err instanceof Error)) {
+    return '';
+  }
+  const { stdout, stderr } = err as Error & { stdout?: string; stderr?: string };
+  return [stdout, stderr].filter(Boolean).join('\n');
+}
+
+class NpmCacheRegistryNonFatalError extends SystemError {
+  override name = 'NpmCacheRegistryNonFatalError';
+  constructor() {
+    super('Non-fatal npm cache registry error during dependency install');
+  }
+}
+
+class NpmCacheRegistryInstallError extends SystemError {
+  override name = 'NpmCacheRegistryInstallError';
+  constructor(cause: unknown) {
+    super('Failed to install dependencies using npm cache registry', { cause });
+  }
+}

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

@@ -2,7 +2,10 @@ import { BuildJob } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { SpawnOptions } from '@expo/turtle-spawn';
 
-import { installDependenciesAsync, resolvePackagerDir } from './installDependencies';
+import {
+  installDependenciesWithNpmCacheFallbackAsync,
+  resolvePackagerDir,
+} from './installDependencies';
 import { BuildContext } from '../context';
 import { runExpoCliCommand } from '../utils/project';
 
@@ -30,17 +33,14 @@ export async function prebuildAsync<TJob extends BuildJob>(
     options: spawnOptions,
     packageManager: ctx.packageManager,
   });
-  const installDependenciesSpawnPromise = (
-    await installDependenciesAsync({
-      packageManager: ctx.packageManager,
-      env: ctx.env,
-      logger,
-      cwd: resolvePackagerDir(ctx),
-      // prebuild sometimes modifies package.json, so we don't want to use frozen lockfile
-      useFrozenLockfile: false,
-    })
-  ).spawnPromise;
-  await installDependenciesSpawnPromise;
+  await installDependenciesWithNpmCacheFallbackAsync({
+    packageManager: ctx.packageManager,
+    env: ctx.env,
+    logger,
+    cwd: resolvePackagerDir(ctx),
+    // prebuild sometimes modifies package.json, so we don't want to use frozen lockfile
+    useFrozenLockfile: false,
+  });
 }
 
 function getPrebuildCommandArgs<TJob extends BuildJob>(ctx: BuildContext<TJob>): string[] {

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

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

packages/build-tools/src/context.ts

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

packages/build-tools/src/datadog.ts

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

packages/build-tools/src/index.ts

@@ -27,3 +27,4 @@ export * from './generic';
 
 export { Datadog } from './datadog';
 export { Sentry } from './sentry';
+export * from './runtimeSettings';

packages/build-tools/src/ios/__tests__/__snapshots__/fastfile.test.ts.snap

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

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

@@ -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(),
@@ -126,14 +131,14 @@ describe(installPods, () => {
   });
 
   it('does not add precompiled modules env vars below the minimum Expo version', async () => {
-    const ctx = makeIosBuildContext({ expoVersion: '55.0.17' });
+    const ctx = makeIosBuildContext({ expoVersion: '55.0.25' });
 
     await installPods(ctx, {});
 
     expect((spawn as jest.Mock).mock.calls[0][2].env.EXPO_USE_PRECOMPILED_MODULES).toBeUndefined();
     expect(ctx.logger.info).toHaveBeenCalledWith(
       expect.stringMatching(
-        /^Detected expo=55\.0\.17; not enabling precompiled modules use because precompiled modules require expo>=/
+        /^Detected expo=55\.0\.25; not enabling precompiled modules use because precompiled modules require expo>=55\.0\.26\./
       )
     );
   });
@@ -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();
+  });
 });

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

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

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

@@ -5,7 +5,7 @@ import semver from 'semver';
 
 import { BuildContext } from '../context';
 
-const MIN_PRECOMPILED_MODULES_EXPO_VERSION = '55.0.21';
+const MIN_PRECOMPILED_MODULES_EXPO_VERSION = '55.0.26';
 const PRECOMPILED_MODULES_BASE_URL =
   'https://storage.googleapis.com/eas-build-precompiled-modules/';
 
@@ -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 {};
   }
 

packages/build-tools/src/runtimeSettings.ts

@@ -0,0 +1,138 @@
+import { Env } from '@expo/eas-build-job';
+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();
+
+let runtimeSettings: z.infer<typeof RuntimeSettingsSchema> = {};
+let runtimeEnvironment: Env = {};
+
+export namespace RuntimeSettings {
+  export async function loadAsync({
+    environment,
+    env: nextRuntimeEnvironment = {},
+  }: {
+    environment: string;
+    env?: Env;
+  }): Promise<void> {
+    runtimeEnvironment = nextRuntimeEnvironment;
+    const url = ENVIRONMENT_TO_RUNTIME_SETTINGS_URL[environment];
+    if (!url) {
+      return;
+    }
+
+    try {
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(1000),
+      });
+
+      if (!response.ok) {
+        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',
+          }
+        );
+      }
+    } catch (err) {
+      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 {
+    if (runtimeEnvironment['EAS_BUILD_DISABLE_NPM_CACHE'] === '1') {
+      return null;
+    }
+    const runtimeEnabled = runtimeSettings.caches?.[process.platform]?.npm;
+    if (runtimeEnabled === false) {
+      return null;
+    }
+    const envOverride = runtimeEnvironment['EAS_USE_NPM_CACHE'];
+    const enabled = envOverride === '1' || (envOverride !== '0' && runtimeEnabled);
+    return enabled ? process.env.EAS_NPM_CACHE_URL || null : null;
+  }
+
+  export function getNodeJsCacheUrl(): string | null {
+    const runtimeEnabled = runtimeSettings.caches?.[process.platform]?.nodejs;
+    if (runtimeEnabled === false) {
+      return null;
+    }
+    const envOverride = runtimeEnvironment['EAS_USE_NODEJS_CACHE'];
+    const enabled = envOverride === '1' || (envOverride !== '0' && runtimeEnabled);
+    return enabled ? process.env.EAS_NODEJS_CACHE_URL || null : null;
+  }
+
+  export function getMavenCacheUrl(): string | null {
+    if (runtimeEnvironment['EAS_BUILD_DISABLE_MAVEN_CACHE'] === '1') {
+      return null;
+    }
+    const runtimeEnabled = runtimeSettings.caches?.[process.platform]?.maven;
+    if (runtimeEnabled === false) {
+      return null;
+    }
+    const envOverride = runtimeEnvironment['EAS_USE_MAVEN_CACHE'];
+    const enabled = envOverride === '1' || (envOverride !== '0' && runtimeEnabled);
+    return enabled ? process.env.EAS_MAVEN_CACHE_URL || null : null;
+  }
+
+  export function getCocoapodsCacheUrl(): string | null {
+    if (runtimeEnvironment['EAS_BUILD_DISABLE_COCOAPODS_CACHE'] === '1') {
+      return null;
+    }
+    const runtimeEnabled = runtimeSettings.caches?.[process.platform]?.cocoapods;
+    if (runtimeEnabled === false) {
+      return null;
+    }
+    const envOverride = runtimeEnvironment['EAS_USE_COCOAPODS_CACHE'];
+    const enabled = envOverride === '1' || (envOverride !== '0' && runtimeEnabled);
+    return enabled ? process.env.EAS_COCOAPODS_CACHE_URL || null : null;
+  }
+}

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

@@ -41,6 +41,7 @@ import { createSaveCacheFunction } from './functions/saveCache';
 import { createSendSlackMessageFunction } from './functions/sendSlackMessage';
 import { createStartAgentDeviceRemoteSessionBuildFunction } from './functions/startAgentDeviceRemoteSession';
 import { createStartAndroidEmulatorBuildFunction } from './functions/startAndroidEmulator';
+import { createStartArgentRemoteSessionBuildFunction } from './functions/startArgentRemoteSession';
 import { createStartCuttlefishDeviceBuildFunction } from './functions/startCuttlefishDevice';
 import { createStartIosSimulatorBuildFunction } from './functions/startIosSimulator';
 import { createStartServeSimRemoteSessionBuildFunction } from './functions/startServeSimRemoteSession';
@@ -60,7 +61,7 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
     createInstallNodeModulesBuildFunction(),
     createPrebuildBuildFunction(),
     createReadIpaInfoBuildFunction(),
-    createDownloadBuildFunction(),
+    createDownloadBuildFunction(ctx),
     createEasExportBuildFunction(),
     createEasDeployBuildFunction(),
     createRepackBuildFunction(),
@@ -81,6 +82,7 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
     runFastlaneFunction(),
     parseXcactivitylogFunction(),
     createStartAgentDeviceRemoteSessionBuildFunction(ctx),
+    createStartArgentRemoteSessionBuildFunction(ctx),
     createStartAndroidEmulatorBuildFunction(),
     createStartCuttlefishDeviceBuildFunction(),
     createStartIosSimulatorBuildFunction(),

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

@@ -1,4 +1,6 @@
+import { SystemError, UserError } from '@expo/eas-build-job';
 import { createLogger } from '@expo/logger';
+import { Client, CombinedError } from '@urql/core';
 import fetch, { Response } from 'node-fetch';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
@@ -17,22 +19,63 @@ const APP_TAR_GZ_BUFFER = Buffer.from(
   'base64'
 );
 
+const APPLICATION_ARCHIVE_URL = `https://expo.dev/artifacts/eas/${randomUUID()}.tar.gz`;
+
+function createMockGraphqlClient({
+  applicationArchiveUrl,
+  error,
+}: {
+  applicationArchiveUrl?: string | null;
+  error?: Error;
+}): Client {
+  const toPromise = jest.fn().mockResolvedValue(
+    error
+      ? { error, data: undefined }
+      : {
+          data: {
+            builds: {
+              byId: {
+                id: randomUUID(),
+                platform: 'IOS',
+                artifacts: {
+                  applicationArchiveUrl: applicationArchiveUrl ?? null,
+                },
+              },
+            },
+          },
+        }
+  );
+
+  return {
+    query: jest.fn().mockReturnValue({ toPromise }),
+  } as unknown as Client;
+}
+
 describe('downloadBuild', () => {
-  it('should handle an archive', async () => {
+  it('downloads from applicationArchiveUrl returned by GraphQL', async () => {
+    const buildId = randomUUID();
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+
     jest.mocked(fetch).mockResolvedValue({
       ok: true,
       body: Readable.from(APP_TAR_GZ_BUFFER),
-      url: `https://storage.googleapis.com/eas-workflows-production/artifacts/${randomUUID()}/${randomUUID()}/application-${randomUUID()}.tar.gz?X-Goog-Algorithm=GOOG4-RSA-SHA256`,
+      url: APPLICATION_ARCHIVE_URL,
     } as unknown as Response);
 
     const { artifactPath } = await downloadBuildAsync({
       logger: createLogger({ name: 'test' }),
-      buildId: randomUUID(),
-      expoApiServerURL: 'http://api.expo.test',
+      buildId,
+      graphqlClient,
       robotAccessToken: null,
       extensions: ['app'],
     });
 
+    expect(jest.mocked(fetch)).toHaveBeenCalledWith(
+      APPLICATION_ARCHIVE_URL,
+      expect.objectContaining({ headers: undefined })
+    );
     expect(artifactPath).toBeDefined();
     expect(await fs.promises.readFile(path.join(artifactPath, 'TestApp'), 'utf8')).toBe(
       'i am executable\n'
@@ -40,16 +83,21 @@ describe('downloadBuild', () => {
   });
 
   it('should handle a straight-up file', async () => {
+    const applicationArchiveUrl = `https://expo.dev/artifacts/eas/${randomUUID()}.apk`;
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl,
+    });
+
     jest.mocked(fetch).mockResolvedValue({
       ok: true,
       body: Readable.from(Buffer.from('hello')),
-      url: `https://storage.googleapis.com/eas-workflows-production/artifacts/${randomUUID()}/${randomUUID()}/application-${randomUUID()}.txt?X-Goog-Algorithm=GOOG4-RSA-SHA256`,
+      url: applicationArchiveUrl,
     } as unknown as Response);
 
     const { artifactPath } = await downloadBuildAsync({
       logger: createLogger({ name: 'test' }),
       buildId: randomUUID(),
-      expoApiServerURL: 'http://api.expo.test',
+      graphqlClient,
       robotAccessToken: null,
       extensions: ['app'],
     });
@@ -58,18 +106,114 @@ describe('downloadBuild', () => {
     expect(await fs.promises.readFile(artifactPath, 'utf-8')).toBe('hello');
   });
 
+  it('throws UserError when the build has no application archive url', async () => {
+    const graphqlClient = createMockGraphqlClient({ applicationArchiveUrl: null });
+
+    await expect(
+      downloadBuildAsync({
+        logger: createLogger({ name: 'test' }),
+        buildId: randomUUID(),
+        graphqlClient,
+        robotAccessToken: null,
+        extensions: ['app'],
+      })
+    ).rejects.toMatchObject({
+      errorCode: 'EAS_DOWNLOAD_BUILD_NO_APPLICATION_ARCHIVE',
+      message: 'Build does not have an application archive url',
+    });
+
+    expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+  });
+
+  it('throws SystemError when GraphQL request fails with a network error', async () => {
+    const buildId = randomUUID();
+    const graphqlClient = createMockGraphqlClient({
+      error: new CombinedError({
+        networkError: new Error('Network request failed'),
+      }),
+    });
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      buildId,
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['app'],
+    });
+
+    await expect(promise).rejects.toBeInstanceOf(SystemError);
+    await expect(promise).rejects.toMatchObject({
+      message: `Could not fetch build ${buildId}: [Network] Network request failed`,
+    });
+
+    expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+  });
+
+  it('throws SystemError when GraphQL request returns 5xx', async () => {
+    const buildId = randomUUID();
+    const graphqlClient = createMockGraphqlClient({
+      error: Object.assign(new Error('Internal Server Error'), {
+        response: { status: 500 },
+      }),
+    });
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      buildId,
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['app'],
+    });
+
+    await expect(promise).rejects.toBeInstanceOf(SystemError);
+    await expect(promise).rejects.toMatchObject({
+      message: `Could not fetch build ${buildId}: Internal Server Error`,
+    });
+
+    expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+  });
+
+  it('throws UserError when GraphQL returns a client error', async () => {
+    const buildId = randomUUID();
+    const graphqlClient = createMockGraphqlClient({
+      error: new CombinedError({
+        graphQLErrors: [{ message: 'Build not found' }],
+      }),
+    });
+
+    const promise = downloadBuildAsync({
+      logger: createLogger({ name: 'test' }),
+      buildId,
+      graphqlClient,
+      robotAccessToken: null,
+      extensions: ['app'],
+    });
+
+    await expect(promise).rejects.toBeInstanceOf(UserError);
+    await expect(promise).rejects.toMatchObject({
+      errorCode: 'EAS_DOWNLOAD_BUILD_FETCH_FAILED',
+      message: `Could not fetch build ${buildId}: [GraphQL] Build not found`,
+    });
+
+    expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+  });
+
   it('should throw an error if no matching files are found', async () => {
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+
     jest.mocked(fetch).mockResolvedValue({
       ok: true,
       body: Readable.from(APP_TAR_GZ_BUFFER),
-      url: `https://storage.googleapis.com/eas-workflows-production/artifacts/${randomUUID()}/${randomUUID()}/application-${randomUUID()}.tar.gz?X-Goog-Algorithm=GOOG4-RSA-SHA256`,
+      url: APPLICATION_ARCHIVE_URL,
     } as unknown as Response);
 
     await expect(
       downloadBuildAsync({
         logger: createLogger({ name: 'test' }),
         buildId: randomUUID(),
-        expoApiServerURL: 'http://api.expo.test',
+        graphqlClient,
         robotAccessToken: null,
         extensions: ['apk'],
       })
@@ -79,7 +223,11 @@ describe('downloadBuild', () => {
 
 describe('createDownloadBuildFunction', () => {
   it('should download a build', async () => {
-    const downloadBuild = createDownloadBuildFunction();
+    const buildId = randomUUID();
+    const graphqlClient = createMockGraphqlClient({
+      applicationArchiveUrl: APPLICATION_ARCHIVE_URL,
+    });
+    const downloadBuild = createDownloadBuildFunction({ graphqlClient } as any);
     const logger = createMockLogger();
 
     const buildStep = downloadBuild.createBuildStepFromFunctionCall(
@@ -92,7 +240,7 @@ describe('createDownloadBuildFunction', () => {
       }),
       {
         callInputs: {
-          build_id: randomUUID(),
+          build_id: buildId,
           extensions: ['app'],
         },
       }
@@ -105,5 +253,9 @@ describe('createDownloadBuildFunction', () => {
     } as unknown as Response);
 
     await expect(buildStep.executeAsync()).rejects.toThrow('Internal Server Error');
+    expect(jest.mocked(fetch)).toHaveBeenCalledWith(
+      APPLICATION_ARCHIVE_URL,
+      expect.objectContaining({ headers: undefined })
+    );
   });
 });

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

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

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

@@ -4,10 +4,14 @@ import { vol } from 'memfs';
 
 import {
   copyLatestAttemptXml,
+  isFileAttrRun,
+  junitFileHasFileAttrs,
   mergeJUnitReports,
+  parseFailedFlowsFromFileAttrs,
   parseFailedFlowsFromJUnit,
   parseJUnitTestCases,
   parseMaestroResults,
+  parseMaestroResultsFromFileAttrs,
 } from '../maestroResultParser';
 
 describe(parseMaestroResults, () => {
@@ -298,7 +302,169 @@ describe(parseMaestroResults, () => {
   });
 });
 
+describe(parseMaestroResultsFromFileAttrs, () => {
+  it('uses file= as the path', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="login" file=".maestro/login.yaml" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    const results = await parseMaestroResultsFromFileAttrs('/junit');
+    expect(results[0]).toEqual(
+      expect.objectContaining({ name: 'login', path: '.maestro/login.yaml' })
+    );
+  });
+
+  it('keeps two same-named flows separate by their file= path', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="login" file="a/login.yaml" status="SUCCESS" time="1.0"/>',
+        '  <testcase name="login" file="b/login.yaml" status="ERROR" time="1.0"><failure>x</failure></testcase>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    const results = await parseMaestroResultsFromFileAttrs('/junit');
+    expect(results.map(r => r.path).sort()).toEqual(['a/login.yaml', 'b/login.yaml']);
+  });
+
+  it('returns per-attempt results keyed by file= across attempt files', async () => {
+    vol.fromJSON({
+      '/junit/android-maestro-junit-attempt-0.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="login" file="flows/login.yaml" time="1.0"><failure>x</failure></testcase>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+      '/junit/android-maestro-junit-attempt-1.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="login" file="flows/login.yaml" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    const results = await parseMaestroResultsFromFileAttrs('/junit');
+    expect(results).toEqual([
+      expect.objectContaining({ path: 'flows/login.yaml', status: 'failed', retryCount: 0 }),
+      expect.objectContaining({ path: 'flows/login.yaml', status: 'passed', retryCount: 1 }),
+    ]);
+  });
+
+  it('returns empty array when the directory does not exist', async () => {
+    const results = await parseMaestroResultsFromFileAttrs('/nope');
+    expect(results).toEqual([]);
+  });
+
+  it('skips testcases without file= instead of emitting an undefined path (contract guard)', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="a" file="a.yaml" status="SUCCESS" time="1.0"/>',
+        '  <testcase name="b" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    const results = await parseMaestroResultsFromFileAttrs('/junit');
+    expect(results).toEqual([expect.objectContaining({ name: 'a', path: 'a.yaml' })]);
+  });
+});
+
+describe('junitFileHasFileAttrs', () => {
+  it('returns true when every testcase has a non-empty file= attribute', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="a" file="a.yaml" status="SUCCESS" time="1.0"/>',
+        '  <testcase name="b" file="b.yaml" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    expect(await junitFileHasFileAttrs('/junit/report.xml')).toBe(true);
+  });
+
+  it('returns false when any testcase lacks file= (mixed report)', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="a" file="a.yaml" status="SUCCESS" time="1.0"/>',
+        '  <testcase name="b" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    expect(await junitFileHasFileAttrs('/junit/report.xml')).toBe(false);
+  });
+
+  it('returns false when file= is an empty string', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="a" file="" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    expect(await junitFileHasFileAttrs('/junit/report.xml')).toBe(false);
+  });
+
+  it('returns false for a legacy report with no file= attributes', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="a" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    expect(await junitFileHasFileAttrs('/junit/report.xml')).toBe(false);
+  });
+
+  it('returns false when the file cannot be read', async () => {
+    expect(await junitFileHasFileAttrs('/missing.xml')).toBe(false);
+  });
+});
+
+describe('isFileAttrRun', () => {
+  it('returns false for an empty list (an empty report is not a file-attr run)', () => {
+    expect(isFileAttrRun([])).toBe(false);
+  });
+});
+
 describe(parseJUnitTestCases, () => {
+  it('extracts the file= attribute when present', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="login" file=".maestro/login.yaml" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    const results = await parseJUnitTestCases('/junit');
+    expect(results[0].file).toBe('.maestro/login.yaml');
+  });
+
+  it('treats a missing or empty file= attribute as undefined', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="a" status="SUCCESS" time="1.0"/>',
+        '  <testcase name="b" file="" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    const results = await parseJUnitTestCases('/junit');
+    expect(results.find(r => r.name === 'a')!.file).toBeUndefined();
+    expect(results.find(r => r.name === 'b')!.file).toBeUndefined();
+  });
+
   it('parses a single testcase with SUCCESS status', async () => {
     vol.fromJSON({
       '/junit/report.xml': [
@@ -582,6 +748,100 @@ describe(parseJUnitTestCases, () => {
   });
 });
 
+describe(parseFailedFlowsFromFileAttrs, () => {
+  it('returns the failing flows by file= (duplicate names retry correctly)', async () => {
+    vol.fromJSON({
+      '/tmp/jr/attempt-0.xml': `<?xml version="1.0"?>
+<testsuites><testsuite>
+  <testcase name="login" file="a/login.yaml" status="SUCCESS" time="1.0"/>
+  <testcase name="login" file="b/login.yaml" time="1.0"><failure>x</failure></testcase>
+</testsuite></testsuites>`,
+      '/proj/b/login.yaml': '',
+    });
+    const result = await parseFailedFlowsFromFileAttrs({
+      junitFile: '/tmp/jr/attempt-0.xml',
+      workingDirectory: '/proj',
+    });
+    expect(result).toEqual(['b/login.yaml']);
+  });
+
+  it('returns null when a file= path does not exist on disk (dumb retry, never legacy)', async () => {
+    vol.fromJSON({
+      '/tmp/jr/attempt-0.xml': `<?xml version="1.0"?>
+<testsuites><testsuite>
+  <testcase name="gone" file="missing/flow.yaml" time="1.0"><failure>x</failure></testcase>
+</testsuite></testsuites>`,
+    });
+    const result = await parseFailedFlowsFromFileAttrs({
+      junitFile: '/tmp/jr/attempt-0.xml',
+      workingDirectory: '/proj',
+    });
+    expect(result).toBeNull();
+  });
+
+  it('returns null when the report lacks file= attributes (callers must pre-check)', async () => {
+    vol.fromJSON({
+      '/tmp/jr/attempt-0.xml': `<?xml version="1.0"?>
+<testsuites><testsuite>
+  <testcase name="A" file="a.yaml" time="1.0"><failure>x</failure></testcase>
+  <testcase name="B" time="1.0"><failure>y</failure></testcase>
+</testsuite></testsuites>`,
+      '/proj/a.yaml': '',
+    });
+    const result = await parseFailedFlowsFromFileAttrs({
+      junitFile: '/tmp/jr/attempt-0.xml',
+      workingDirectory: '/proj',
+    });
+    expect(result).toBeNull();
+  });
+
+  it('dedupes repeated failing file= paths (same flow failed twice in one attempt)', async () => {
+    vol.fromJSON({
+      '/tmp/jr/attempt-0.xml': `<?xml version="1.0"?>
+<testsuites><testsuite>
+  <testcase name="login" file="flows/login.yaml" time="1.0"><failure>x</failure></testcase>
+  <testcase name="login" file="flows/login.yaml" time="1.0"><failure>y</failure></testcase>
+</testsuite></testsuites>`,
+      '/proj/flows/login.yaml': '',
+    });
+    const result = await parseFailedFlowsFromFileAttrs({
+      junitFile: '/tmp/jr/attempt-0.xml',
+      workingDirectory: '/proj',
+    });
+    expect(result).toEqual(['flows/login.yaml']);
+  });
+
+  it('resolves and existence-checks an absolute file= path', async () => {
+    vol.fromJSON({
+      '/tmp/jr/attempt-0.xml': `<?xml version="1.0"?>
+<testsuites><testsuite>
+  <testcase name="ext" file="/outside/flow.yaml" time="1.0"><failure>x</failure></testcase>
+</testsuite></testsuites>`,
+      '/outside/flow.yaml': '',
+    });
+    const result = await parseFailedFlowsFromFileAttrs({
+      junitFile: '/tmp/jr/attempt-0.xml',
+      workingDirectory: '/proj',
+    });
+    expect(result).toEqual(['/outside/flow.yaml']);
+  });
+
+  it('returns null when junit XML is truncated mid-tag (partial parse risk)', async () => {
+    vol.fromJSON({
+      '/tmp/jr/attempt-0.xml': `<?xml version="1.0"?>
+<testsuites><testsuite>
+  <testcase name="A" file="a.yaml" time="1.0"><failure>x</failure></testcase>
+  <testcase name="B" file="b.yaml"`, // intentionally truncated mid-tag
+      '/proj/a.yaml': '',
+    });
+    const result = await parseFailedFlowsFromFileAttrs({
+      junitFile: '/tmp/jr/attempt-0.xml',
+      workingDirectory: '/proj',
+    });
+    expect(result).toBeNull();
+  });
+});
+
 describe('parseFailedFlowsFromJUnit', () => {
   it('returns the subset of input flow paths whose testcases failed', async () => {
     vol.fromJSON({
@@ -765,6 +1025,28 @@ describe('mergeJUnitReports', () => {
     expect(b.failure).toBeUndefined();
   });
 
+  it('keeps a same-named flow from an earlier attempt when keyed by file=', async () => {
+    vol.fromJSON({
+      '/tmp/r/android-maestro-junit-attempt-0.xml': `<?xml version="1.0"?>
+<testsuites><testsuite>
+  <testcase name="login" file="a/login.yaml" status="SUCCESS" time="1.0"/>
+  <testcase name="login" file="b/login.yaml" time="1.0"><failure>x</failure></testcase>
+</testsuite></testsuites>`,
+      '/tmp/r/android-maestro-junit-attempt-1.xml': `<?xml version="1.0"?>
+<testsuites><testsuite>
+  <testcase name="login" file="b/login.yaml" status="SUCCESS" time="1.0"/>
+</testsuite></testsuites>`,
+    });
+
+    await mergeJUnitReports({ sourceDir: '/tmp/r', outputPath: '/tmp/final.xml' });
+
+    const out = await fs.readFile('/tmp/final.xml', 'utf-8');
+    const parsed = new XMLParser({ ignoreAttributes: false }).parse(out);
+    const testcases = parsed.testsuites.testsuite.testcase;
+    const files = testcases.map((t: any) => t['@_file']).sort();
+    expect(files).toEqual(['a/login.yaml', 'b/login.yaml']);
+  });
+
   it('throws when source directory contains no *.xml files', async () => {
     // No per-attempt JUnit files were ever written (maestro crashed before
     // producing output). Phase 3 in runMaestroTests treats this as a SystemError

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

@@ -273,6 +273,33 @@ describe('createMaestroTestsBuildFunction', () => {
     );
   });
 
+  it('uses the file= path on reports that carry it, without scanning flow files', async () => {
+    mockedSpawn.mockRejectedValueOnce(rejectExit1()).mockResolvedValueOnce(SPAWN_SUCCESS);
+    jest.spyOn(parser, 'junitFileHasFileAttrs').mockResolvedValue(true);
+    const discoverySpy = jest.spyOn(discovery, 'buildFlowNameToPathMap');
+    const legacyParseSpy = jest.spyOn(parser, 'parseFailedFlowsFromJUnit');
+    const newParseSpy = jest
+      .spyOn(parser, 'parseFailedFlowsFromFileAttrs')
+      .mockResolvedValue(['flows/b.yaml']);
+
+    const step = createStep({
+      flow_path: ['flows/a.yaml', 'flows/b.yaml'],
+      retries: 1,
+      output_format: 'junit',
+      retry_failed_only: true,
+      platform: 'android',
+    });
+    await step.executeAsync();
+
+    expect(newParseSpy).toHaveBeenCalledTimes(1);
+    // The new branch needs no name→path map: no scan, no legacy parser.
+    expect(discoverySpy).not.toHaveBeenCalled();
+    expect(legacyParseSpy).not.toHaveBeenCalled();
+    const a1 = mockedSpawn.mock.calls[1][1]!;
+    expect(a1).toContain('flows/b.yaml');
+    expect(a1).not.toContain('flows/a.yaml');
+  });
+
   it('falls back to all-flows retry when nameToPath is null (duplicate flow names)', async () => {
     mockedSpawn.mockRejectedValueOnce(rejectExit1()).mockResolvedValueOnce(SPAWN_SUCCESS);
     jest.spyOn(discovery, 'buildFlowNameToPathMap').mockResolvedValue(null);
@@ -293,6 +320,44 @@ describe('createMaestroTestsBuildFunction', () => {
     );
   });
 
+  it('never scans flow files when all attempts succeed', async () => {
+    mockedSpawn.mockResolvedValue(SPAWN_SUCCESS);
+    const discoverySpy = jest.spyOn(discovery, 'buildFlowNameToPathMap');
+
+    const step = createStep({ flow_path: ['flows/a.yaml'], platform: 'android' });
+    await step.executeAsync();
+
+    expect(discoverySpy).not.toHaveBeenCalled();
+  });
+
+  it('memoizes the flow scan across retries (legacy reports)', async () => {
+    // Routing note: the step lands in the legacy arm because the real
+    // junitFileHasFileAttrs returns false — the attempt XML does not exist on
+    // the mock fs. Creating that file with file= attrs would flip the branch.
+    mockedSpawn
+      .mockRejectedValueOnce(rejectExit1())
+      .mockRejectedValueOnce(rejectExit1())
+      .mockResolvedValueOnce(SPAWN_SUCCESS);
+    const discoverySpy = jest
+      .spyOn(discovery, 'buildFlowNameToPathMap')
+      .mockResolvedValue(new Map([['a', 'flows/a.yaml']]));
+    const parseSpy = jest
+      .spyOn(parser, 'parseFailedFlowsFromJUnit')
+      .mockResolvedValue(['flows/a.yaml']);
+
+    const step = createStep({
+      flow_path: ['flows/a.yaml'],
+      retries: 2,
+      output_format: 'junit',
+      platform: 'android',
+    });
+    await step.executeAsync();
+
+    // Two failed attempts hit the legacy branch twice; the scan runs once.
+    expect(parseSpy).toHaveBeenCalledTimes(2);
+    expect(discoverySpy).toHaveBeenCalledTimes(1);
+  });
+
   it('defaults retry_failed_only to true when omitted from inputs', async () => {
     mockedSpawn.mockRejectedValueOnce(rejectExit1()).mockResolvedValueOnce(SPAWN_SUCCESS);
     jest.spyOn(parser, 'parseFailedFlowsFromJUnit').mockResolvedValue(['flows/b.yaml']);

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

@@ -3,6 +3,7 @@ import { vol } from 'memfs';
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { createMockLogger } from '../../../__tests__/utils/logger';
+import * as discovery from '../maestroFlowDiscovery';
 import { createReportMaestroTestResultsFunction } from '../reportMaestroTestResults';
 
 const JUNIT_PASS = [
@@ -43,15 +44,24 @@ describe(createReportMaestroTestResultsFunction, () => {
     } as unknown as Client;
   });
 
+  // Returns a mock logger whose child() is itself, so step-level log calls can
+  // be asserted on the returned object.
+  function createSelfChildedLogger(): ReturnType<typeof createMockLogger> {
+    const logger = createMockLogger();
+    (logger.child as jest.Mock).mockReturnValue(logger);
+    return logger;
+  }
+
   function createStep(overrides?: {
     callInputs?: Record<string, unknown>;
     staticContextContent?: Record<string, unknown>;
     env?: Record<string, string>;
+    logger?: ReturnType<typeof createMockLogger>;
   }) {
     const ctx = { graphqlClient: mockGraphqlClient };
     const fn = createReportMaestroTestResultsFunction(ctx as any);
     const globalCtx = createGlobalContextMock({
-      logger: createMockLogger(),
+      logger: overrides?.logger ?? createMockLogger(),
       projectTargetDirectory: '/root/project',
       staticContextContent: {
         expoApiServerURL: 'https://api.expo.test',
@@ -105,6 +115,54 @@ describe(createReportMaestroTestResultsFunction, () => {
     ]);
   });
 
+  it('reports both flows when two share a name but have distinct file= paths', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="login" file="a/login.yaml" status="SUCCESS" time="1.0"/>',
+        '  <testcase name="login" file="b/login.yaml" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    mockMutationFn.mockResolvedValue({
+      data: {
+        workflowDeviceTestCaseResult: {
+          createWorkflowDeviceTestCaseResults: [{ id: '1' }, { id: '2' }],
+        },
+      },
+    });
+    await createStep().executeAsync();
+    expect(mockGraphqlClient.mutation).toHaveBeenCalledTimes(1);
+    const [, variables] = (mockGraphqlClient.mutation as jest.Mock).mock.calls[0];
+    expect(variables.input.testCaseResults.map((r: any) => r.path).sort()).toEqual([
+      'a/login.yaml',
+      'b/login.yaml',
+    ]);
+  });
+
+  it('never scans flow files for a file= report, even when flow_path is provided', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="login" file="flows/login.yaml" status="SUCCESS" time="1.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+    const discoverySpy = jest.spyOn(discovery, 'buildFlowNameToPathMap');
+    mockMutationFn.mockResolvedValue({
+      data: {
+        workflowDeviceTestCaseResult: { createWorkflowDeviceTestCaseResults: [{ id: '1' }] },
+      },
+    });
+
+    await createStep({ callInputs: { flow_path: ['flows/login.yaml'] } }).executeAsync();
+
+    expect(mockGraphqlClient.mutation).toHaveBeenCalledTimes(1);
+    expect(discoverySpy).not.toHaveBeenCalled();
+  });
+
   it('sends tags and properties from JUnit XML', async () => {
     vol.fromJSON({
       '/junit/report.xml': [
@@ -221,7 +279,7 @@ describe(createReportMaestroTestResultsFunction, () => {
     await createStep().executeAsync();
   });
 
-  it('skips report when duplicate testcase names found', async () => {
+  it('skips report when duplicate testcase names found (legacy), advising unique names', async () => {
     vol.fromJSON({
       '/junit/report.xml': [
         '<?xml version="1.0"?>',
@@ -238,8 +296,27 @@ describe(createReportMaestroTestResultsFunction, () => {
       }),
     });
 
-    await createStep().executeAsync();
+    const logger = createSelfChildedLogger();
+    await createStep({ logger }).executeAsync();
     expect(mockGraphqlClient.mutation).not.toHaveBeenCalled();
+    expect(logger.error).toHaveBeenCalledWith(expect.stringContaining('unique name'));
+  });
+
+  it('skips report when the same flow file appears twice in one attempt, advising flow_path check', async () => {
+    vol.fromJSON({
+      '/junit/report.xml': [
+        '<?xml version="1.0"?>',
+        '<testsuites><testsuite>',
+        '  <testcase name="login" file="flows/login.yaml" status="SUCCESS" time="1.0"/>',
+        '  <testcase name="login" file="flows/login.yaml" status="SUCCESS" time="2.0"/>',
+        '</testsuite></testsuites>',
+      ].join('\n'),
+    });
+
+    const logger = createSelfChildedLogger();
+    await createStep({ logger }).executeAsync();
+    expect(mockGraphqlClient.mutation).not.toHaveBeenCalled();
+    expect(logger.error).toHaveBeenCalledWith(expect.stringContaining('flow_path entries'));
   });
 
   it('sends per-attempt results with same name but different retryCount', async () => {

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

@@ -0,0 +1,58 @@
+import { SystemError } from '@expo/eas-build-job';
+import { type bunyan } from '@expo/logger';
+
+import { warnIfArgentPackageVersionCannotBeVerified } from '../startArgentRemoteSession';
+
+describe(warnIfArgentPackageVersionCannotBeVerified, () => {
+  const warn = jest.fn();
+  const logger = { warn } as unknown as bunyan;
+
+  beforeEach(() => {
+    warn.mockClear();
+  });
+
+  it('allows the default latest package version', () => {
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: undefined, logger })
+    ).not.toThrow();
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: 'latest', logger })
+    ).not.toThrow();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('allows exact supported semver versions', () => {
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: '0.11.0', logger })
+    ).not.toThrow();
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: '0.11.1', logger })
+    ).not.toThrow();
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: 'v0.11.1', logger })
+    ).not.toThrow();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('rejects exact semver versions that are too old', () => {
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: '0.10.9', logger })
+    ).toThrow(SystemError);
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: '0.10.9', logger })
+    ).toThrow(/Use "latest" or pass an exact version >= 0\.11\.0/);
+  });
+
+  it('warns for package tags or ranges that cannot be verified', () => {
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: 'next', logger })
+    ).not.toThrow();
+    expect(() =>
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: '^0.11.0', logger })
+    ).not.toThrow();
+    expect(warn).toHaveBeenCalledTimes(2);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('Continuing and letting bunx resolve it.')
+    );
+  });
+});

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

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

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

@@ -1,4 +1,4 @@
-import { UserError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import {
@@ -7,7 +7,9 @@ import {
   BuildStepInputValueTypeName,
   BuildStepOutput,
 } from '@expo/steps';
+import { Client } from '@urql/core';
 import { glob } from 'fast-glob';
+import { graphql } from 'gql.tada';
 import fetch from 'node-fetch';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -16,6 +18,7 @@ import stream from 'stream';
 import { promisify } from 'util';
 import { z } from 'zod';
 
+import { CustomBuildContext } from '../../customBuildContext';
 import { formatBytes } from '../../utils/artifacts';
 import { decompressTarAsync, isFileTarGzAsync } from '../../utils/files';
 import { retryOnDNSFailure } from '../../utils/retryOnDNSFailure';
@@ -23,7 +26,21 @@ import { pluralize } from '../../utils/strings';
 
 const streamPipeline = promisify(stream.pipeline);
 
-export function createDownloadBuildFunction(): BuildFunction {
+const BUILD_BY_ID_QUERY = graphql(`
+  query DownloadBuildByIdQuery($buildId: ID!) {
+    builds {
+      byId(buildId: $buildId) {
+        id
+        platform
+        artifacts {
+          applicationArchiveUrl
+        }
+      }
+    }
+  }
+`);
+
+export function createDownloadBuildFunction(ctx: CustomBuildContext): BuildFunction {
   return new BuildFunction({
     namespace: 'eas',
     id: 'download_build',
@@ -59,7 +76,7 @@ export function createDownloadBuildFunction(): BuildFunction {
       const { artifactPath } = await downloadBuildAsync({
         logger,
         buildId,
-        expoApiServerURL: stepsCtx.global.staticContext.expoApiServerURL,
+        graphqlClient: ctx.graphqlClient,
         robotAccessToken: stepsCtx.global.staticContext.job.secrets?.robotAccessToken ?? null,
         extensions,
       });
@@ -69,16 +86,45 @@ export function createDownloadBuildFunction(): BuildFunction {
   });
 }
 
+async function fetchApplicationArchiveUrlAsync({
+  buildId,
+  graphqlClient,
+}: {
+  buildId: string;
+  graphqlClient: Client;
+}): Promise<string> {
+  const result = await graphqlClient.query(BUILD_BY_ID_QUERY, { buildId }).toPromise();
+
+  if (result.error) {
+    const { error } = result;
+    const message = `Could not fetch build ${buildId}: ${error.message}`;
+
+    throw error.networkError || result.error.response?.status >= 500
+      ? new SystemError(message, { cause: error })
+      : new UserError('EAS_DOWNLOAD_BUILD_FETCH_FAILED', message, { cause: error });
+  }
+
+  const applicationArchiveUrl = result.data?.builds.byId?.artifacts?.applicationArchiveUrl;
+  if (!applicationArchiveUrl) {
+    throw new UserError(
+      'EAS_DOWNLOAD_BUILD_NO_APPLICATION_ARCHIVE',
+      'Build does not have an application archive url'
+    );
+  }
+
+  return applicationArchiveUrl;
+}
+
 export async function downloadBuildAsync({
   logger,
   buildId,
-  expoApiServerURL,
+  graphqlClient,
   robotAccessToken,
   extensions,
 }: {
   logger: bunyan;
   buildId: string;
-  expoApiServerURL: string;
+  graphqlClient: Client;
   robotAccessToken: string | null;
   extensions: string[];
 }): Promise<{ artifactPath: string }> {
@@ -86,12 +132,11 @@ export async function downloadBuildAsync({
     path.join(os.tmpdir(), 'download_build-downloaded-')
   );
 
-  const response = await retryOnDNSFailure(fetch)(
-    new URL(`/v2/artifacts/eas/${buildId}`, expoApiServerURL),
-    {
-      headers: robotAccessToken ? { Authorization: `Bearer ${robotAccessToken}` } : undefined,
-    }
-  );
+  const downloadUrl = await fetchApplicationArchiveUrlAsync({ buildId, graphqlClient });
+
+  const response = await retryOnDNSFailure(fetch)(downloadUrl, {
+    headers: robotAccessToken ? { Authorization: `Bearer ${robotAccessToken}` } : undefined,
+  });
 
   if (!response.ok) {
     const textResult = await asyncResult(response.text());

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

@@ -26,14 +26,14 @@ export function createFindAndUploadBuildArtifactsBuildFunction(
       try {
         await uploadApplicationArchivesAsync({ ctx, stepCtx });
       } catch (err: unknown) {
-        stepCtx.logger.error(`Failed to upload application archives.`, err);
+        stepCtx.logger.error({ err }, `Failed to upload application archives.`);
         firstError ||= err;
       }
 
       try {
         await uploadBuildArtifacts({ ctx, stepCtx });
       } catch (err: unknown) {
-        stepCtx.logger.error(`Failed to upload build artifacts.`, err);
+        stepCtx.logger.error({ err }, `Failed to upload build artifacts.`);
         firstError ||= err;
       }
 

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

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

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

@@ -1,3 +1,4 @@
+import { asyncResult } from '@expo/results';
 import { XMLBuilder, XMLParser, XMLValidator } from 'fast-xml-parser';
 import fs from 'fs/promises';
 import path from 'path';
@@ -18,6 +19,7 @@ const ATTEMPT_PATTERN = /attempt-(\d+)/;
 
 export interface JUnitTestCaseResult {
   name: string;
+  file: string | undefined;
   status: 'passed' | 'failed';
   duration: number; // milliseconds
   errorMessage: string | null;
@@ -32,6 +34,12 @@ const xmlParser = new XMLParser({
   isArray: name => ['testsuite', 'testcase', 'property'].includes(name),
 });
 
+// A `file=` attribute counts as present only when it is a non-empty string.
+function fileAttrOf(tc: any): string | undefined {
+  const f = tc?.['@_file'];
+  return typeof f === 'string' && f.length > 0 ? f : undefined;
+}
+
 function parseJUnitContent(content: string): JUnitTestCaseResult[] {
   const results: JUnitTestCaseResult[] = [];
   try {
@@ -54,6 +62,8 @@ function parseJUnitContent(content: string): JUnitTestCaseResult[] {
           continue;
         }
 
+        const file = fileAttrOf(tc);
+
         const timeStr = tc['@_time'];
         const timeSeconds = timeStr ? parseFloat(timeStr) : 0;
         const duration = Number.isFinite(timeSeconds) ? Math.round(timeSeconds * 1000) : 0;
@@ -94,7 +104,7 @@ function parseJUnitContent(content: string): JUnitTestCaseResult[] {
           : [];
         delete properties['tags'];
 
-        results.push({ name, status, duration, errorMessage, tags, properties });
+        results.push({ name, file, status, duration, errorMessage, tags, properties });
       }
     }
   } catch {
@@ -131,6 +141,142 @@ export async function parseJUnitTestCases(junitDirectory: string): Promise<JUnit
   return perFile.flat();
 }
 
+// ---------------------------------------------------------------------------
+// Maestro >= 2.6.0 code path: every <testcase> carries a `file=` attribute with
+// its flow's own path (all-or-none per run). Callers check the report first
+// (isFileAttrRun / junitFileHasFileAttrs) and route here; the legacy name→path
+// scan is then never consulted.
+// ---------------------------------------------------------------------------
+
+export function isFileAttrRun(
+  testcases: JUnitTestCaseResult[]
+): testcases is (JUnitTestCaseResult & { file: string })[] {
+  return testcases.length > 0 && testcases.every(tc => tc.file !== undefined);
+}
+
+// Unreadable or attribute-less reports ⇒ false: the caller then takes the
+// legacy path, whose own guards degrade safely.
+export async function junitFileHasFileAttrs(junitFile: string): Promise<boolean> {
+  return isFileAttrRun(await parseJUnitFile(junitFile));
+}
+
+async function fileExists(absPath: string): Promise<boolean> {
+  return (await asyncResult(fs.stat(absPath))).ok;
+}
+
+// Group by `file=` so two same-named flows in different files stay separate.
+export async function parseMaestroResultsFromFileAttrs(
+  junitDirectory: string
+): Promise<MaestroFlowResult[]> {
+  interface JUnitEntry {
+    result: JUnitTestCaseResult;
+    sourceFile: string;
+  }
+
+  let junitEntries: string[];
+  try {
+    junitEntries = await fs.readdir(junitDirectory);
+  } catch {
+    return [];
+  }
+  const xmlFiles = junitEntries.filter(f => f.endsWith('.xml')).sort();
+
+  const entries: JUnitEntry[] = [];
+  for (const xmlFile of xmlFiles) {
+    const fileResults = await parseJUnitFile(path.join(junitDirectory, xmlFile));
+    for (const result of fileResults) {
+      entries.push({ result, sourceFile: xmlFile });
+    }
+  }
+
+  const byPath = new Map<string, JUnitEntry[]>();
+  for (const entry of entries) {
+    // Callers verify the report with isFileAttrRun/junitFileHasFileAttrs first;
+    // skip (rather than emit an undefined path) if that contract is violated.
+    const flowPath = entry.result.file;
+    if (flowPath === undefined) {
+      continue;
+    }
+    const group = byPath.get(flowPath) ?? [];
+    group.push(entry);
+    byPath.set(flowPath, group);
+  }
+
+  const results: MaestroFlowResult[] = [];
+  for (const [flowPath, group] of byPath) {
+    // retryCount is derived from each entry's source filename (`attempt-N`);
+    // a single entry from `report.xml` (no marker) collapses to attempt 0.
+    const sorted = group
+      .map(entry => {
+        const match = entry.sourceFile.match(ATTEMPT_PATTERN);
+        const attemptIndex = match ? parseInt(match[1], 10) : 0;
+        return { ...entry, attemptIndex };
+      })
+      .sort((a, b) => a.attemptIndex - b.attemptIndex);
+
+    for (const { result, attemptIndex } of sorted) {
+      results.push({
+        name: result.name,
+        path: flowPath,
+        status: result.status,
+        errorMessage: result.errorMessage,
+        duration: result.duration,
+        retryCount: attemptIndex,
+        tags: result.tags,
+        properties: result.properties,
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Returns the `file=` paths of the failing testcases in the given attempt's
+ * JUnit file, or `null` when the result cannot be trusted (caller then falls
+ * back to dumb retry — re-run everything; never the legacy scan).
+ *
+ * Callers verify the report carries `file=` attributes first
+ * (junitFileHasFileAttrs).
+ */
+export async function parseFailedFlowsFromFileAttrs(args: {
+  junitFile: string;
+  workingDirectory: string;
+}): Promise<string[] | null> {
+  // Same hardening as the legacy parser: fast-xml-parser is lenient — a
+  // truncated XML could drop testcases, and trusting that partial failing set
+  // would skip retries for cut-off flows.
+  let content: string;
+  try {
+    content = await fs.readFile(args.junitFile, 'utf-8');
+  } catch {
+    return null;
+  }
+  if (XMLValidator.validate(content) !== true) {
+    return null;
+  }
+
+  const testcases = parseJUnitContent(content);
+  if (!isFileAttrRun(testcases)) {
+    return null;
+  }
+
+  const failing = testcases.filter(tc => tc.status === 'failed');
+  if (failing.length === 0) {
+    return [];
+  }
+
+  // Each failing testcase is self-identifying via `file=`, so duplicate flow
+  // names retry correctly. path.resolve (not join): `file=` may be absolute
+  // when the flow lives outside the working directory.
+  const paths = [...new Set(failing.map(tc => tc.file))];
+  for (const p of paths) {
+    if (!(await fileExists(path.resolve(args.workingDirectory, p)))) {
+      return null;
+    }
+  }
+  return paths;
+}
+
 export async function parseMaestroResults(
   junitDirectory: string,
   nameToPath: Map<string, string> | null
@@ -313,6 +459,13 @@ export async function mergeJUnitReports(args: {
     }
     const match = filename.match(ATTEMPT_PATTERN);
     const attemptIndex = match ? parseInt(match[1], 10) : 0;
+    // Maestro >= 2.6.0 reports: key by `file=` so two same-named flows in
+    // different files merge separately. Legacy reports keep name keying.
+    const allCases = testsuites.flatMap((suite: any) =>
+      Array.isArray(suite?.testcase) ? suite.testcase : []
+    );
+    const useFileKeys =
+      allCases.length > 0 && allCases.every((tc: any) => fileAttrOf(tc) !== undefined);
     const testcasesByName = new Map<string, unknown[]>();
     for (const suite of testsuites) {
       const cases = suite?.testcase;
@@ -324,9 +477,10 @@ export async function mergeJUnitReports(args: {
         if (typeof name !== 'string') {
           continue;
         }
-        const group = testcasesByName.get(name) ?? [];
+        const key = useFileKeys ? fileAttrOf(tc)! : name;
+        const group = testcasesByName.get(key) ?? [];
         group.push(tc);
-        testcasesByName.set(name, group);
+        testcasesByName.set(key, group);
       }
     }
     if (testcasesByName.size === 0) {

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

@@ -14,7 +14,9 @@ import { z } from 'zod';
 import { buildFlowNameToPathMap } from './maestroFlowDiscovery';
 import {
   copyLatestAttemptXml,
+  junitFileHasFileAttrs,
   mergeJUnitReports,
+  parseFailedFlowsFromFileAttrs,
   parseFailedFlowsFromJUnit,
 } from './maestroResultParser';
 import { sleepAsync } from '../../utils/retry';
@@ -200,13 +202,10 @@ export function createMaestroTestsBuildFunction(): BuildFunction {
         throw new SystemError('Failed to create JUnit report directory', { cause: err });
       }
 
-      // null → duplicate flow names; retry-failed-only disabled, fall through to
-      // dumb retry (re-run everything) on failure.
-      const nameToPath = await buildFlowNameToPathMap({
-        inputFlowPaths: flowPaths,
-        projectRoot: stepCtx.workingDirectory,
-        logger,
-      });
+      // Legacy-only (Maestro < 2.6.0 reports carry no `file=` attribute): the
+      // flow scan is built lazily in the retry branch below and memoized so
+      // retries share one scan. Never runs when the report has `file=`.
+      let nameToPathPromise: Promise<Map<string, string> | null> | undefined;
 
       // Retry loop. spawn-async error shapes:
       //   ENOENT/EACCES → infra (binary missing/not executable) → SystemError.
@@ -214,7 +213,7 @@ export function createMaestroTestsBuildFunction(): BuildFunction {
       //   else (signal-only, OOM kill, unknown) → infra → SystemError, never
       //     downgraded to "tests failed".
       // Retry-failed-only (junit mode): after a failed attempt, subset to the failing
-      // flows. parseFailedFlowsFromJUnit returns null when the JUnit cannot be
+      // flows. The failed-flow parsers return null when the JUnit cannot be
       // trusted; we then fall through to dumb retry (re-run everything).
       let flowsToRun: string[] = flowPaths;
       let lastAttemptExitCode: number | null = null;
@@ -263,11 +262,26 @@ export function createMaestroTestsBuildFunction(): BuildFunction {
           break;
         }
 
-        if (retryFailedOnly && outputFormat === 'junit' && outputPath && nameToPath) {
-          const failed = await parseFailedFlowsFromJUnit({
-            junitFile: outputPath,
-            nameToPath,
-          });
+        if (retryFailedOnly && outputFormat === 'junit' && outputPath) {
+          let failed: string[] | null;
+          if (await junitFileHasFileAttrs(outputPath)) {
+            failed = await parseFailedFlowsFromFileAttrs({
+              junitFile: outputPath,
+              workingDirectory: stepCtx.workingDirectory,
+            });
+          } else {
+            // Legacy (Maestro < 2.6.0): map failed testcase names back to flow
+            // paths via the flow-file scan. DELETE this arm once the fleet is
+            // on >= 2.6.0.
+            const nameToPath = await (nameToPathPromise ??= buildFlowNameToPathMap({
+              inputFlowPaths: flowPaths,
+              projectRoot: stepCtx.workingDirectory,
+              logger,
+            }));
+            failed = nameToPath
+              ? await parseFailedFlowsFromJUnit({ junitFile: outputPath, nameToPath })
+              : null;
+          }
           if (failed !== null && failed.length > 0) {
             flowsToRun = failed;
             logger.info(

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

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

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

@@ -3,7 +3,13 @@ import { graphql } from 'gql.tada';
 import { z } from 'zod';
 
 import { buildFlowNameToPathMap } from './maestroFlowDiscovery';
-import { MaestroFlowResult, parseMaestroResults } from './maestroResultParser';
+import {
+  MaestroFlowResult,
+  isFileAttrRun,
+  parseJUnitTestCases,
+  parseMaestroResults,
+  parseMaestroResultsFromFileAttrs,
+} from './maestroResultParser';
 import { CustomBuildContext } from '../../customBuildContext';
 
 const FlowPathSchema = z.array(z.string().min(1)).min(1);
@@ -61,47 +67,64 @@ export function createReportMaestroTestResultsFunction(ctx: CustomBuildContext):
         return;
       }
 
-      const flowPathRaw = inputs.flow_path.value;
-      let nameToPath: Map<string, string> | null = null;
-      if (flowPathRaw !== undefined) {
-        const parsed = FlowPathSchema.safeParse(flowPathRaw);
-        if (parsed.success) {
-          nameToPath = await buildFlowNameToPathMap({
-            inputFlowPaths: parsed.data,
-            projectRoot: stepsCtx.workingDirectory,
-            logger,
-          });
-        } else {
-          logger.warn(
-            'Ignoring malformed flow_path input (expected a non-empty array of non-empty strings).'
-          );
-        }
-      }
-
       try {
-        const flowResults = await parseMaestroResults(junitDirectory, nameToPath);
+        // Maestro >= 2.6.0 stamps every <testcase> with its flow's path in a
+        // `file=` attribute; older reports need the legacy flow-file scan to
+        // map testcase names back to paths.
+        const usedFileAttrs = isFileAttrRun(await parseJUnitTestCases(junitDirectory));
+
+        let flowResults: MaestroFlowResult[];
+        if (usedFileAttrs) {
+          flowResults = await parseMaestroResultsFromFileAttrs(junitDirectory);
+        } else {
+          // Legacy (Maestro < 2.6.0) — DELETE this arm once the fleet is on >= 2.6.0.
+          const flowPathRaw = inputs.flow_path.value;
+          let nameToPath: Map<string, string> | null = null;
+          if (flowPathRaw !== undefined) {
+            const parsed = FlowPathSchema.safeParse(flowPathRaw);
+            if (parsed.success) {
+              nameToPath = await buildFlowNameToPathMap({
+                inputFlowPaths: parsed.data,
+                projectRoot: stepsCtx.workingDirectory,
+                logger,
+              });
+            } else {
+              logger.warn(
+                'Ignoring malformed flow_path input (expected a non-empty array of non-empty strings).'
+              );
+            }
+          }
+          flowResults = await parseMaestroResults(junitDirectory, nameToPath);
+        }
+
         if (flowResults.length === 0) {
           logger.info('No maestro test results found, skipping report');
           return;
         }
 
-        // Detect truly conflicting results: same (name, retryCount) pair means different flow files
-        // share the same name (Maestro config override), which we can't disambiguate.
-        // Same name with different retryCount is expected (per-attempt results from retries).
+        // Detect truly conflicting results: the same (path, retryCount) twice means two
+        // flow files resolved to the same path, which we can't disambiguate and the API
+        // rejects as a duplicate. Same path with different retryCount is expected
+        // (per-attempt results from retries).
         const seen = new Set<string>();
         const conflicting = new Set<string>();
         for (const r of flowResults) {
-          const key = `${r.name}:${r.retryCount}`;
+          const key = `${r.path}:${r.retryCount}`;
           if (seen.has(key)) {
-            conflicting.add(r.name);
+            conflicting.add(r.path);
           }
           seen.add(key);
         }
         if (conflicting.size > 0) {
+          const conflictList = [...conflicting].join(', ');
           logger.error(
-            `Duplicate test case names found in JUnit output: ${[...conflicting].join(
-              ', '
-            )}. Skipping report. Ensure each Maestro flow has a unique name.`
+            usedFileAttrs
+              ? `The same flow file was reported more than once in a single attempt: ` +
+                  `${conflictList}. Skipping report. Check for duplicate flow_path entries ` +
+                  `or leftover XML files in the JUnit report directory.`
+              : `Duplicate Maestro flow names found: ${conflictList}. Skipping report. ` +
+                  `Give each flow a unique name, or upgrade Maestro to >= 2.6.0 (flows are ` +
+                  `then identified by file path, so duplicate names are fine).`
           );
           return;
         }

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

@@ -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';
 
@@ -205,16 +206,16 @@ export async function restoreGradleCacheAsync({
   }
 
   try {
-    const gradlePropertiesPath = path.join(workingDirectory, 'android', 'gradle.properties');
-    const gradlePropertiesContent = await fs.promises.readFile(gradlePropertiesPath, 'utf-8');
-    await fs.promises.writeFile(
-      gradlePropertiesPath,
-      `${gradlePropertiesContent}\n\norg.gradle.caching=true\n`
-    );
+    // Enable build cache via user-level gradle.properties.
+    // This avoids mutating android/gradle.properties which affects fingerprinting.
+    const gradleUserHome = path.join(os.homedir(), '.gradle');
+    await fs.promises.mkdir(gradleUserHome, { recursive: true });
+    const userGradlePropertiesPath = path.join(gradleUserHome, 'gradle.properties');
+    await fs.promises.appendFile(userGradlePropertiesPath, '\norg.gradle.caching=true\n');
 
-    // Configure cache cleanup via init script (works with both Gradle 8 and 9,
-    // org.gradle.cache.cleanup property was removed in Gradle 9)
-    const initScriptDir = path.join(os.homedir(), '.gradle', 'init.d');
+    // Configure cache cleanup via init script.
+    // Works with both Gradle 8 and 9 (org.gradle.cache.cleanup property was removed in Gradle 9).
+    const initScriptDir = path.join(gradleUserHome, 'init.d');
     await fs.promises.mkdir(initScriptDir, { recursive: true });
     await fs.promises.writeFile(
       path.join(initScriptDir, 'eas-cache-cleanup.gradle'),
@@ -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');

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

@@ -1,9 +1,9 @@
 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';
@@ -12,22 +12,25 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import { CustomBuildContext } from '../../customBuildContext';
-import { sleepAsync } from '../../utils/retry';
+import { type CustomBuildContext } from '../../customBuildContext';
+import { Sentry } from '../../sentry';
 import {
-  DetachedProcessHandle,
-  ensureBrewPackageInstalledAsync,
+  type DetachedProcessHandle,
   getDeviceRunSessionIdOrThrow,
+  getNgrokAuthtokenOrThrow,
+  getNgrokTunnelDomainOrThrow,
   spawnDetached,
+  startNgrokTunnelAsync,
   startServeSimWithTunnelAsync,
   uploadRemoteSessionConfigAsync,
+  waitForFileAsync,
 } 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');
 const XCODE_DEVELOPER_DIR = '/Applications/Xcode.app/Contents/Developer';
-const CLOUDFLARED_LINUX_INSTALL_PATH = '/usr/local/bin/cloudflared';
 const STARTUP_TIMEOUT_MS = 60_000;
 
 export function createStartAgentDeviceRemoteSessionBuildFunction(
@@ -46,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;
@@ -62,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}.`);
-      await waitForFileAsync({
-        filePath: DAEMON_JSON_PATH,
-        timeoutMs: STARTUP_TIMEOUT_MS,
-        description: 'agent-device daemon',
+      const { port: daemonPort, token: daemonToken } = await waitForDaemonInfoAsync({
+        daemonProcess,
       });
-      const { port: daemonPort, token: daemonToken } = readDaemonInfo(DAEMON_JSON_PATH);
       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}.`);
 
@@ -120,7 +90,8 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
       // on Darwin. Android sessions go without a preview URL.
       let webPreviewUrl: string | undefined;
       if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
-        const { previewUrl } = await startServeSimWithTunnelAsync({
+        const { previewUrl } = await startServeSimWithTunnelAsync(ctx, {
+          baseDomain: ngrokTunnelDomain,
           env,
           logger,
           timeoutMs: STARTUP_TIMEOUT_MS,
@@ -148,60 +119,91 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
   });
 }
 
-async function ensureCloudflaredInstalledAsync({
-  runtimePlatform,
+async function startAgentDeviceDaemonAsync({
+  packageVersion,
   env,
   logger,
 }: {
-  runtimePlatform: BuildRuntimePlatform;
+  packageVersion: string | undefined;
   env: BuildStepEnv;
   logger: bunyan;
-}): Promise<string> {
-  if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
-    await ensureBrewPackageInstalledAsync({ name: 'cloudflared', env, logger });
-    return 'cloudflared';
+}): 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 });
   }
-  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], {
+}
+
+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,
   });
-  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;
-}
 
-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;
-  }
+  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({
@@ -220,54 +222,64 @@ async function cloneAgentDeviceAsync({
   });
 }
 
-async function waitForMatchInOutputAsync({
-  process,
-  pattern,
-  timeoutMs,
-  description,
+async function waitForDaemonInfoAsync({
+  daemonProcess,
 }: {
-  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);
+  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}` : ''}`
+    );
   }
-  throw new SystemError(
-    `Timed out waiting for ${description} to start. Last output:\n${process.getOutput() || '<empty>'}`
+}
+
+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'
   );
 }
 
-async function waitForFileAsync({
-  filePath,
-  timeoutMs,
-  description,
-}: {
-  filePath: string;
-  timeoutMs: number;
-  description: string;
-}): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    try {
-      await fs.promises.access(filePath);
-      return;
-    } catch {
-      // not yet; keep polling
-    }
-    await sleepAsync(1_000);
-  }
-  throw new SystemError(`Timed out waiting for ${description} to write ${filePath}.`);
+function getBunInstallDirectory(env: BuildStepEnv): string {
+  const bunInstall = env.BUN_INSTALL?.trim();
+  return bunInstall ? bunInstall : path.join(os.homedir(), '.bun');
 }
 
-function readDaemonInfo(filePath: string): { port: number; token: string } {
-  const raw = fs.readFileSync(filePath, 'utf8');
+function parseDaemonInfo(raw: string): { port: number; token: string } {
   const parsed = JSON.parse(raw) as unknown;
   if (
     !parsed ||
@@ -276,7 +288,7 @@ function readDaemonInfo(filePath: string): { port: number; token: string } {
     typeof (parsed as { token: unknown }).token !== 'string'
   ) {
     throw new SystemError(
-      `Expected ${filePath} to contain { "httpPort": <number>, "token": "..." }.`
+      'Expected daemon credentials to contain { "httpPort": <number>, "token": "..." }.'
     );
   }
   const { httpPort, token } = parsed as { httpPort: number; token: string };

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

@@ -0,0 +1,197 @@
+import { SystemError } from '@expo/eas-build-job';
+import { type bunyan } from '@expo/logger';
+import {
+  BuildFunction,
+  BuildRuntimePlatform,
+  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 semver from 'semver';
+import { z } from 'zod';
+
+import { CustomBuildContext } from '../../customBuildContext';
+import {
+  getDeviceRunSessionIdOrThrow,
+  getNgrokAuthtokenOrThrow,
+  getNgrokTunnelDomainOrThrow,
+  spawnDetached,
+  startNgrokTunnelAsync,
+  startServeSimWithTunnelAsync,
+  uploadRemoteSessionConfigAsync,
+  waitForFileAsync,
+} from '../utils/remoteDeviceRunSession';
+
+const ARGENT_PACKAGE_NAME = '@swmansion/argent';
+const MIN_ARGENT_REMOTE_SESSION_VERSION = '0.11.0';
+const ARGENT_STATE_FILE = path.join(os.homedir(), '.argent', 'tool-server.json');
+const XCODE_DEVELOPER_DIR = '/Applications/Xcode.app/Contents/Developer';
+const STARTUP_TIMEOUT_MS = 60_000;
+
+const ArgentToolServerStateSchema = z.object({
+  port: z.number(),
+  token: z.string().optional(),
+});
+
+export function createStartArgentRemoteSessionBuildFunction(
+  ctx: CustomBuildContext
+): BuildFunction {
+  return new BuildFunction({
+    namespace: 'eas',
+    id: 'start_argent_remote_session',
+    name: 'Start argent remote session',
+    __metricsId: 'eas/start_argent_remote_session',
+    inputProviders: [
+      BuildStepInput.createProvider({
+        id: 'package_version',
+        required: false,
+        allowedValueTypeName: BuildStepInputValueTypeName.STRING,
+      }),
+    ],
+    fn: async ({ logger, global }, { inputs, env }) => {
+      // 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;
+      warnIfArgentPackageVersionCannotBeVerified({ packageVersion, logger });
+      const versionSpec = packageVersion ?? 'latest';
+      const { runtimePlatform } = global;
+      logger.info(
+        `Starting argent remote session (version: ${versionSpec}, runtime: ${runtimePlatform}).`
+      );
+
+      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
+        logger.info(`Selecting Xcode developer directory: ${XCODE_DEVELOPER_DIR}.`);
+        await spawn('sudo', ['xcode-select', '-s', XCODE_DEVELOPER_DIR], { env, logger });
+      }
+
+      // Stale state from a previous run would mask the new server's port.
+      await fs.promises.rm(ARGENT_STATE_FILE, { force: true });
+
+      logger.info(`Launching ${ARGENT_PACKAGE_NAME}@${versionSpec} tool-server via bunx.`);
+      const argentServer = spawnDetached({
+        command: 'bunx',
+        args: [
+          `${ARGENT_PACKAGE_NAME}@${versionSpec}`,
+          'server',
+          'start',
+          '--port',
+          '0',
+          '--idle-timeout',
+          '0',
+          '--detach',
+        ],
+        env,
+      });
+
+      logger.info(`Waiting for argent tool-server state at ${ARGENT_STATE_FILE}.`);
+      let toolServerPort: number;
+      let toolServerToken: string | undefined;
+      try {
+        const toolServerState = await waitForFileAsync({
+          filePath: ARGENT_STATE_FILE,
+          timeoutMs: STARTUP_TIMEOUT_MS,
+          description: 'argent tool-server state',
+          parse: parseArgentToolServerState,
+        });
+        toolServerPort = toolServerState.port;
+        toolServerToken = toolServerState.token;
+      } catch (err) {
+        const output = argentServer.getOutput();
+        throw new SystemError(
+          `${
+            err instanceof Error ? err.message : `Timed out waiting for argent tool-server state.`
+          }${output ? `\nArgent tool-server output:\n${output}` : ''}`
+        );
+      }
+      logger.info(`Argent tool-server is listening on port ${toolServerPort}.`);
+
+      const publicToolsUrl = await startNgrokTunnelAsync({
+        port: toolServerPort,
+        subdomainPrefix: 'argent',
+        baseDomain: ngrokTunnelDomain,
+        authtoken: ngrokAuthtoken,
+        rewriteHostHeader: true,
+        logger,
+      });
+      logger.info(`Tunnel is ready at ${publicToolsUrl}.`);
+
+      // serve-sim is iOS-only — Android sessions go without a preview URL.
+      let webPreviewUrl: string | undefined;
+      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
+        const serveSim = await startServeSimWithTunnelAsync(ctx, {
+          baseDomain: ngrokTunnelDomain,
+          env,
+          logger,
+          timeoutMs: STARTUP_TIMEOUT_MS,
+        });
+        webPreviewUrl = serveSim.previewUrl;
+        logger.info(`Web preview URL: ${webPreviewUrl}`);
+      }
+
+      await uploadRemoteSessionConfigAsync({
+        ctx,
+        deviceRunSessionId,
+        remoteConfig: {
+          toolsUrl: publicToolsUrl,
+          ...(toolServerToken ? { toolsAuthToken: toolServerToken } : {}),
+          ...(webPreviewUrl ? { webPreviewUrl } : {}),
+        },
+        logger,
+      });
+
+      logger.info('Remote session is live. Keeping the job alive until the session is stopped.');
+      // Keep the turtle job alive so the tool-server and tunnel stay reachable
+      // until stopDeviceRunSession cancels the run.
+      await new Promise<never>(() => {});
+    },
+  });
+}
+
+export function warnIfArgentPackageVersionCannotBeVerified({
+  packageVersion,
+  logger,
+}: {
+  packageVersion: string | undefined;
+  logger: bunyan;
+}): void {
+  if (!packageVersion || packageVersion === 'latest') {
+    return;
+  }
+
+  const validVersion = semver.valid(packageVersion);
+  if (!validVersion) {
+    logger.warn(
+      `Argent remote simulator sessions require ${ARGENT_PACKAGE_NAME}@${MIN_ARGENT_REMOTE_SESSION_VERSION} or newer, ` +
+        `but package_version "${packageVersion}" is not an exact semver version that EAS can verify. ` +
+        `Continuing and letting bunx resolve it.`
+    );
+    return;
+  }
+
+  if (semver.lt(validVersion, MIN_ARGENT_REMOTE_SESSION_VERSION)) {
+    throw new SystemError(
+      `Argent remote simulator sessions require ${ARGENT_PACKAGE_NAME}@${MIN_ARGENT_REMOTE_SESSION_VERSION} or newer. ` +
+        `The requested package_version "${packageVersion}" is too old for the EAS remote-session API. ` +
+        `Use "latest" or pass an exact version >= ${MIN_ARGENT_REMOTE_SESSION_VERSION}.`
+    );
+  }
+}
+
+function parseArgentToolServerState(raw: string): { port: number; token?: string } {
+  const result = ArgentToolServerStateSchema.safeParse(JSON.parse(raw));
+  if (!result.success) {
+    throw new SystemError(
+      `Expected tool-server state to contain { "port": <number>, ... }: ${result.error.message}`
+    );
+  }
+  return result.data;
+}

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

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

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

@@ -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({
+      const { previewUrl, streamUrl } = await startServeSimWithTunnelAsync(ctx, {
+        baseDomain: ngrokTunnelDomain,
         env,
         logger,
         timeoutMs: STARTUP_TIMEOUT_MS,

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

@@ -128,7 +128,7 @@ export function createUploadArtifactBuildFunction(ctx: CustomBuildContext): Buil
         }
       } catch (error) {
         if (inputs.ignore_error.value) {
-          logger.error(`Failed to upload ${artifact.type}. Ignoring error.`, error);
+          logger.error({ err: error }, `Failed to upload ${artifact.type}. Ignoring error.`);
           // Ignoring error.
           return;
         }

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

@@ -0,0 +1,154 @@
+import { bunyan } from '@expo/logger';
+import { BuildStepEnv } from '@expo/steps';
+
+import { CustomBuildContext } from '../../../customBuildContext';
+import { Sentry } from '../../../sentry';
+import { turtleFetch } from '../../../utils/turtleFetch';
+import {
+  fetchServeSimTurnArgsAsync,
+  turnIceServersToServeSimArgs,
+} from '../remoteDeviceRunSession';
+
+jest.mock('../../../utils/turtleFetch');
+jest.mock('../../../sentry');
+
+function createLoggerMock(): bunyan {
+  return {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    debug: jest.fn(),
+  } as unknown as bunyan;
+}
+
+function createCtxMock(): CustomBuildContext {
+  return {
+    env: {
+      __API_SERVER_URL: 'https://api.expo.test',
+    },
+    job: {
+      secrets: { robotAccessToken: 'robot-token' },
+    },
+  } as unknown as CustomBuildContext;
+}
+
+function createEnvMock(): BuildStepEnv {
+  return { DEVICE_RUN_SESSION_ID: 'drs-id' } as unknown as BuildStepEnv;
+}
+
+describe(turnIceServersToServeSimArgs, () => {
+  it('returns no args for an empty ICE server list', () => {
+    expect(turnIceServersToServeSimArgs([])).toEqual([]);
+  });
+
+  it('builds --stun-url and --turn-url flags from Cloudflare ICE servers', () => {
+    expect(
+      turnIceServersToServeSimArgs([
+        { urls: ['stun:stun.cloudflare.com:3478', 'stun:stun.cloudflare.com:53'] },
+        {
+          urls: [
+            'turn:turn.cloudflare.com:3478?transport=udp',
+            'turns:turn.cloudflare.com:443?transport=tcp',
+          ],
+          username: 'user-123',
+          credential: 'cred-456',
+        },
+      ])
+    ).toEqual([
+      '--stun-url',
+      'stun:stun.cloudflare.com:3478,stun:stun.cloudflare.com:53',
+      '--turn-url',
+      'turn:turn.cloudflare.com:3478?transport=udp,turns:turn.cloudflare.com:443?transport=tcp',
+      '--turn-username',
+      'user-123',
+      '--turn-credential',
+      'cred-456',
+    ]);
+  });
+
+  it('emits only --turn-url flags when no credential-less (STUN) entry is present', () => {
+    expect(
+      turnIceServersToServeSimArgs([
+        {
+          urls: ['turns:turn.cloudflare.com:443?transport=tcp'],
+          username: 'u',
+          credential: 'c',
+        },
+      ])
+    ).toEqual([
+      '--turn-url',
+      'turns:turn.cloudflare.com:443?transport=tcp',
+      '--turn-username',
+      'u',
+      '--turn-credential',
+      'c',
+    ]);
+  });
+
+  it('emits only --stun-url when there is no credentialed TURN entry', () => {
+    expect(turnIceServersToServeSimArgs([{ urls: ['stun:stun.cloudflare.com:3478'] }])).toEqual([
+      '--stun-url',
+      'stun:stun.cloudflare.com:3478',
+    ]);
+  });
+});
+
+describe(fetchServeSimTurnArgsAsync, () => {
+  beforeEach(() => {
+    jest.mocked(turtleFetch).mockReset();
+  });
+
+  it('requests TURN ICE servers from the device run session endpoint and returns serve-sim args', async () => {
+    jest.mocked(turtleFetch).mockResolvedValue({
+      json: async () => ({
+        data: {
+          iceServers: [
+            { urls: ['stun:stun.cloudflare.com:3478'] },
+            {
+              urls: ['turns:turn.cloudflare.com:443?transport=tcp'],
+              username: 'u',
+              credential: 'c',
+            },
+          ],
+        },
+      }),
+    } as unknown as Awaited<ReturnType<typeof turtleFetch>>);
+
+    const args = await fetchServeSimTurnArgsAsync(createCtxMock(), {
+      env: createEnvMock(),
+      logger: createLoggerMock(),
+    });
+
+    expect(args).toEqual([
+      '--stun-url',
+      'stun:stun.cloudflare.com:3478',
+      '--turn-url',
+      'turns:turn.cloudflare.com:443?transport=tcp',
+      '--turn-username',
+      'u',
+      '--turn-credential',
+      'c',
+    ]);
+    expect(jest.mocked(turtleFetch)).toHaveBeenCalledWith(
+      'https://api.expo.test/v2/device-run-sessions/drs-id/turn-ice-servers',
+      'POST',
+      expect.objectContaining({
+        headers: { Authorization: 'Bearer robot-token' },
+      })
+    );
+  });
+
+  it('returns [] and warns when the request fails so serve-sim falls back to P2P/STUN', async () => {
+    jest.mocked(turtleFetch).mockRejectedValue(new Error('boom'));
+    const logger = createLoggerMock();
+
+    const args = await fetchServeSimTurnArgsAsync(createCtxMock(), {
+      env: createEnvMock(),
+      logger,
+    });
+
+    expect(args).toEqual([]);
+    expect(logger.warn).toHaveBeenCalled();
+    expect(jest.mocked(Sentry).capture).toHaveBeenCalled();
+  });
+});

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

@@ -7,9 +7,9 @@ import { createMockLogger } from '../../../../__tests__/utils/logger';
 import { Sentry } from '../../../../sentry';
 import {
   buildTargetMetrics,
-  isCompileStep,
   collectTopLevelCompileSteps,
   formatReport,
+  isCompileStep,
   parseAndReportXcactivitylog,
 } from '../xcactivitylog';
 
@@ -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,
@@ -267,6 +276,9 @@ describe('parseAndReportXcactivitylog', () => {
         '/tmp/workspace',
         '--reporter',
         'json',
+        '--omit_warnings',
+        '--omit_notes',
+        '--trunc_large_issues',
         '--output',
         reportPath,
       ],
@@ -375,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' } })
     );
   });
 
@@ -406,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' } })
     );
   });
 
@@ -434,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')
     );
   });
 
@@ -460,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' } })
     );
   });
 
@@ -489,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();
@@ -524,6 +676,9 @@ describe('parseAndReportXcactivitylog', () => {
           '/tmp/workspace',
           '--reporter',
           'json',
+          '--omit_warnings',
+          '--omit_notes',
+          '--trunc_large_issues',
           '--output',
           reportPath,
         ],

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

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

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

@@ -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 }));
@@ -203,6 +241,9 @@ async function runXclogparser({
       workspacePath,
       '--reporter',
       'json',
+      '--omit_warnings',
+      '--omit_notes',
+      '--trunc_large_issues',
       '--output',
       outputPath,
     ],

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

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

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

@@ -2,12 +2,17 @@ import { SystemError } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { BuildStepEnv } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
+import * as ngrok from '@ngrok/ngrok';
 import { graphql } from 'gql.tada';
+import nullthrows from 'nullthrows';
+import { z } from 'zod';
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
 
 import { CustomBuildContext } from '../../customBuildContext';
+import { Sentry } from '../../sentry';
 import { sleepAsync } from '../../utils/retry';
-
-const TRYCLOUDFLARE_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+import { turtleFetch } from '../../utils/turtleFetch';
 
 const START_DEVICE_RUN_SESSION_MUTATION = graphql(`
   mutation StartDeviceRunSession($deviceRunSessionId: ID!, $remoteConfig: JSONObject!) {
@@ -28,13 +33,136 @@ 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;
+}
+
+const TurnIceServersSchema = z.array(
+  z.object({
+    urls: z.array(z.string()),
+    username: z.string().optional(),
+    credential: z.string().optional(),
+  })
+);
+
+export type TurnIceServers = z.infer<typeof TurnIceServersSchema>;
+
+const TurnIceServersResponseSchema = z.object({
+  data: z.object({
+    iceServers: TurnIceServersSchema,
+  }),
+});
+
+/**
+ * Translate Cloudflare ICE servers into serve-sim CLI flags: `--stun-url` (the
+ * credential-less entries) and `--turn-url`/`--turn-username`/`--turn-credential`
+ * (the entry carrying the short-lived credentials).
+ */
+export function turnIceServersToServeSimArgs(iceServers: TurnIceServers): string[] {
+  const stunUrls = iceServers
+    .filter(server => !server.username && !server.credential)
+    .flatMap(server => server.urls);
+  const turnServer = iceServers.find(server => server.username && server.credential);
+
+  const args: string[] = [];
+  if (stunUrls.length > 0) {
+    args.push('--stun-url', stunUrls.join(','));
+  }
+  if (turnServer?.username && turnServer.credential && turnServer.urls.length > 0) {
+    args.push(
+      '--turn-url',
+      turnServer.urls.join(','),
+      '--turn-username',
+      turnServer.username,
+      '--turn-credential',
+      turnServer.credential
+    );
+  }
+  return args;
+}
+
+/**
+ * Fetch short-lived Cloudflare TURN ICE servers for this job run from www
+ * (minted on demand, mirroring how the worker fetches project clone URLs) and
+ * translate them into serve-sim CLI flags.
+ *
+ * Best-effort: on any failure we log and return [] so serve-sim falls back to
+ * its built-in P2P/STUN behavior. The credential is passed to serve-sim as a
+ * process arg and deliberately not logged (turtle-spawn never logs argv and the
+ * worker is single-tenant).
+ */
+export async function fetchServeSimTurnArgsAsync(
+  ctx: CustomBuildContext,
+  { env, logger }: { env: BuildStepEnv; logger: bunyan }
+): Promise<string[]> {
+  try {
+    const deviceRunSessionId = getDeviceRunSessionIdOrThrow(env);
+    const expoApiServerUrl = nullthrows(ctx.env.__API_SERVER_URL, '__API_SERVER_URL is not set');
+    const robotAccessToken = nullthrows(
+      ctx.job.secrets?.robotAccessToken,
+      'robot access token is not set'
+    );
+
+    const response = await turtleFetch(
+      new URL(
+        `/v2/device-run-sessions/${deviceRunSessionId}/turn-ice-servers`,
+        expoApiServerUrl
+      ).toString(),
+      'POST',
+      {
+        headers: {
+          Authorization: `Bearer ${robotAccessToken}`,
+        },
+        timeout: 5000,
+        retries: 1,
+        logger,
+      }
+    );
+
+    const { data } = TurnIceServersResponseSchema.parse(await response.json());
+    const args = turnIceServersToServeSimArgs(data.iceServers);
+    if (args.length > 0) {
+      logger.info('Configured serve-sim with Cloudflare TURN ICE servers.');
+    }
+    return args;
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    Sentry.capture('Could not fetch Cloudflare TURN ICE servers', error, { level: 'warning' });
+    logger.warn(
+      { err: error },
+      'Could not fetch Cloudflare TURN ICE servers; serve-sim will fall back to P2P/STUN.'
+    );
+    return [];
+  }
+}
+
 export async function uploadRemoteSessionConfigAsync({
   ctx,
   deviceRunSessionId,
@@ -59,22 +187,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;
 };
@@ -111,27 +223,38 @@ export function spawnDetached({
   return { getOutput: () => output };
 }
 
-export async function startServeSimWithTunnelAsync({
-  env,
-  logger,
-  timeoutMs,
-}: {
-  env: BuildStepEnv;
-  logger: bunyan;
-  timeoutMs: number;
-}): Promise<{ previewUrl: string; streamUrl: string }> {
+export async function startServeSimWithTunnelAsync(
+  ctx: CustomBuildContext,
+  {
+    baseDomain,
+    env,
+    logger,
+    timeoutMs,
+  }: {
+    baseDomain: string;
+    env: BuildStepEnv;
+    logger: bunyan;
+    timeoutMs: number;
+  }
+): Promise<{ previewUrl: string; streamUrl: string }> {
   logger.info('Launching serve-sim with tunnel.');
+  const turnArgs = await fetchServeSimTurnArgsAsync(ctx, { env, logger });
   const serveSim = spawnDetached({
     command: 'npx',
     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',
+      ...turnArgs,
     ],
     env,
   });
@@ -140,8 +263,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 };
     }
@@ -152,8 +275,83 @@ 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 startNgrokTunnelAsync({
+  port,
+  subdomainPrefix,
+  baseDomain,
+  authtoken,
+  rewriteHostHeader,
+  logger,
+}: {
+  port: number;
+  subdomainPrefix: string;
+  baseDomain: string;
+  authtoken: string;
+  rewriteHostHeader?: boolean;
+  logger: bunyan;
+}): Promise<string> {
+  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,
+    ...(rewriteHostHeader ? { request_header_add: [`Host:localhost:${port}`] } : {}),
+  });
+  const url = listener.url();
+  if (!url) {
+    throw new SystemError(`ngrok tunnel for ${domain} did not return a public URL.`);
+  }
+  return url;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export async function waitForFileAsync<T>({
+  filePath,
+  timeoutMs,
+  description,
+  parse,
+}: {
+  filePath: string;
+  timeoutMs: number;
+  description: string;
+  parse: (raw: string) => T;
+}): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  let lastError: unknown;
+  while (Date.now() < deadline) {
+    try {
+      const raw = await fs.promises.readFile(filePath, 'utf8');
+      return parse(raw);
+    } catch (err) {
+      lastError = err;
+    }
+    await sleepAsync(1_000);
+  }
+  throw new SystemError(
+    `Timed out waiting for ${description} to be ready at ${filePath}${
+      lastError instanceof Error ? `: ${lastError.message}` : ''
+    }.`
+  );
+}

packages/build-tools/src/templates/FastfileResign.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

packages/downloader/package.json

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

packages/eas-build-cache-provider/package.json

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

packages/eas-build-job/package.json

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

packages/eas-build-job/src/__tests__/ios.test.ts

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

packages/eas-build-job/src/common.ts

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

packages/eas-build-job/src/index.ts

@@ -5,7 +5,6 @@ export {
   ArchiveSource,
   ArchiveSourceSchemaZ,
   BuildMode,
-  BuildPhaseStats,
   BuildTrigger,
   EasCliNpmTags,
   Env,

packages/eas-build-job/src/ios.ts

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

packages/eas-build-job/src/logs.ts

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

packages/eas-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eas-cli",
-  "version": "19.0.1",
+  "version": "20.3.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",
@@ -224,6 +224,9 @@
       "update": {
         "description": "manage individual updates"
       },
+      "update:embedded": {
+        "description": "manage embedded updates registered with EAS Update"
+      },
       "webhook": {
         "description": "manage webhooks"
       },

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

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

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

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

packages/eas-cli/src/build/ios/__tests__/credentials-test.ts

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

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

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

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

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

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

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

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

@@ -35,4 +35,5 @@ export interface BuildFlags {
   message?: string;
   buildLoggerLevel?: LoggerLevel;
   freezeCredentials: boolean;
+  refreshAdHocProvisioningProfile?: boolean;
 }

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

@@ -0,0 +1,22 @@
+import chalk from 'chalk';
+
+import { PostHogProjectData } from '../graphql/types/PostHogConnection';
+import Log, { link } from '../log';
+
+export function getPostHogProjectDashboardUrl(project: PostHogProjectData): string {
+  const host = project.posthogHost.replace(/\/$/, '');
+  return `${host}/project/${encodeURIComponent(project.posthogProjectIdentifier)}`;
+}
+
+export function formatPostHogProject(project: PostHogProjectData): string {
+  return [
+    `${chalk.bold('Name')}: ${project.posthogProjectName}`,
+    `${chalk.bold('Host')}: ${project.posthogHost}`,
+    `${chalk.bold('Region')}: ${project.posthogOrganizationConnection.posthogRegion}`,
+    `${chalk.bold('Dashboard')}: ${link(getPostHogProjectDashboardUrl(project), { dim: false })}`,
+  ].join('\n');
+}
+
+export function logNoPostHogProject(projectName: string): void {
+  Log.warn(`No PostHog project is linked to Expo app ${chalk.bold(projectName)} on EAS.`);
+}

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

@@ -0,0 +1,149 @@
+import { Args, Flags } from '@oclif/core';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import { EASNonInteractiveFlag, EasJsonOnlyFlag } from '../../commandUtils/flags';
+import { getLimitFlagWithCustomValues } from '../../commandUtils/pagination';
+import { AuditLogFragment } from '../../graphql/generated';
+import { AuditLogQuery } from '../../graphql/queries/AuditLogQuery';
+import Log from '../../log';
+import { ora } from '../../ora';
+import { confirmAsync, selectAsync } from '../../prompts';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
+import renderTextTable from '../../utils/renderTextTable';
+
+const AUDIT_LOGS_LIMIT = 50;
+
+export default class AccountAudit extends EasCommand {
+  static override description = 'view the audit logs for an account';
+
+  static override args = {
+    ACCOUNT_NAME: Args.string({
+      description:
+        'Account name to view audit logs for. If not provided, the account will be selected interactively (or defaults to the only account if there is just one)',
+    }),
+  };
+
+  static override flags = {
+    limit: getLimitFlagWithCustomValues({ defaultTo: AUDIT_LOGS_LIMIT, limit: 100 }),
+    after: Flags.string({
+      description:
+        'Cursor for pagination. Use the endCursor from a previous query to fetch the next page.',
+    }),
+    ...EasJsonOnlyFlag,
+    ...EASNonInteractiveFlag,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const {
+      args: { ACCOUNT_NAME: accountName },
+      flags: { limit, after, json: jsonFlag, 'non-interactive': nonInteractive },
+    } = await this.parse(AccountAudit);
+
+    const json = jsonFlag || nonInteractive;
+    if (json) {
+      enableJsonOutput();
+    }
+
+    const {
+      loggedIn: { graphqlClient, actor },
+    } = await this.getContextAsync(AccountAudit, { nonInteractive });
+
+    const pageSize = limit ?? AUDIT_LOGS_LIMIT;
+
+    let targetAccount: { id: string; name: string };
+    const availableAccounts = actor.accounts.map(a => a.name).join(', ');
+    if (accountName) {
+      const found = actor.accounts.find(a => a.name === accountName);
+      if (!found) {
+        throw new Error(
+          `Account "${accountName}" not found or you don't have access. Available accounts: ${availableAccounts}`
+        );
+      }
+      targetAccount = found;
+    } else if (nonInteractive) {
+      throw new Error(
+        'ACCOUNT_NAME argument must be provided when running in `--non-interactive` mode.'
+      );
+    } else if (actor.accounts.length === 1) {
+      targetAccount = actor.accounts[0];
+    } else {
+      targetAccount = await selectAsync(
+        'Select account to view audit logs for:',
+        actor.accounts.map(account => ({
+          title: account.name,
+          value: account,
+        }))
+      );
+    }
+
+    if (json) {
+      const spinner = ora(`Fetching audit logs for account ${targetAccount.name}`).start();
+      try {
+        const connection = await AuditLogQuery.getAllForAccountAsync(
+          graphqlClient,
+          targetAccount.id,
+          {
+            first: pageSize,
+            after,
+          }
+        );
+        spinner.stop();
+        printJsonOnlyOutput({
+          auditLogs: connection.edges.map(edge => edge.node),
+          pageInfo: connection.pageInfo,
+        });
+      } catch (error) {
+        spinner.fail(`Failed to fetch audit logs for account ${targetAccount.name}`);
+        throw error;
+      }
+      return;
+    }
+
+    let cursor = after;
+    do {
+      const spinner = ora(`Fetching audit logs for account ${targetAccount.name}`).start();
+      const connection = await AuditLogQuery.getAllForAccountAsync(
+        graphqlClient,
+        targetAccount.id,
+        {
+          first: pageSize,
+          after: cursor,
+        }
+      );
+      spinner.stop();
+
+      const logs = connection.edges.map(edge => edge.node);
+      renderPageOfAuditLogs(logs);
+
+      if (!connection.pageInfo.hasNextPage) {
+        break;
+      }
+      cursor = connection.pageInfo.endCursor ?? undefined;
+    } while (cursor && (await confirmAsync({ message: 'Load more audit logs?' })));
+  }
+}
+
+function renderPageOfAuditLogs(logs: AuditLogFragment[]): void {
+  if (logs.length === 0) {
+    Log.log('No audit logs found.');
+    return;
+  }
+
+  Log.log(
+    renderTextTable(
+      ['Date', 'Actor', 'Action', 'Entity', 'Message'],
+      logs.map(log => [
+        new Date(log.createdAt).toLocaleString(),
+        log.actor?.displayName ?? 'Unknown',
+        log.targetEntityMutationType,
+        log.targetEntityTypePublicName,
+        log.websiteMessage,
+      ])
+    )
+  );
+  Log.addNewLineIfNone();
+}

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

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

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

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

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

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

packages/eas-cli/src/commands/integrations/posthog/__tests__/connect.test.ts

@@ -0,0 +1,658 @@
+import spawnAsync from '@expo/spawn-async';
+import * as fs from 'fs-extra';
+
+import { getMockOclifConfig } from '../../../../__tests__/commands/utils';
+import { ExpoGraphqlClient } from '../../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { testProjectId } from '../../../../credentials/__tests__/fixtures-constants';
+import {
+  EnvironmentVariableScope,
+  EnvironmentVariableVisibility,
+  PostHogRegion,
+  Role,
+} from '../../../../graphql/generated';
+import { EnvironmentVariableMutation } from '../../../../graphql/mutations/EnvironmentVariableMutation';
+import { PostHogMutation } from '../../../../graphql/mutations/PostHogMutation';
+import { EnvironmentVariablesQuery } from '../../../../graphql/queries/EnvironmentVariablesQuery';
+import { PostHogQuery } from '../../../../graphql/queries/PostHogQuery';
+import {
+  PostHogOrganizationConnectionData,
+  PostHogProjectData,
+} from '../../../../graphql/types/PostHogConnection';
+import Log from '../../../../log';
+import { createOrModifyExpoConfigAsync } from '../../../../project/expoConfig';
+import { getOwnerAccountForProjectIdAsync } from '../../../../project/projectUtils';
+import { confirmAsync, promptAsync, selectAsync } from '../../../../prompts';
+import { Actor } from '../../../../user/User';
+import { printJsonOnlyOutput } from '../../../../utils/json';
+import IntegrationsPostHogConnect from '../connect';
+
+jest.mock('@expo/spawn-async');
+jest.mock('fs-extra');
+jest.mock('../../../../project/expoConfig');
+jest.mock('../../../../graphql/queries/PostHogQuery');
+jest.mock('../../../../graphql/queries/EnvironmentVariablesQuery');
+jest.mock('../../../../graphql/mutations/PostHogMutation');
+jest.mock('../../../../graphql/mutations/EnvironmentVariableMutation');
+jest.mock('../../../../project/projectUtils');
+jest.mock('../../../../prompts');
+jest.mock('../../../../log');
+jest.mock('../../../../utils/json');
+jest.mock('../../../../ora', () => ({
+  ora: () => ({
+    start: jest.fn().mockReturnThis(),
+    succeed: jest.fn().mockReturnThis(),
+    fail: jest.fn().mockReturnThis(),
+  }),
+}));
+
+describe(IntegrationsPostHogConnect, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+  const testAccountId = 'test-account-id';
+  const testAccountName = 'testuser';
+
+  const mockActor: Actor = {
+    __typename: 'User',
+    id: 'test-user-id',
+    username: testAccountName,
+    email: '[email protected]',
+    featureGates: {},
+    isExpoAdmin: false,
+    primaryAccount: { id: testAccountId, name: testAccountName, ownerUserActor: null, users: [] },
+    preferences: { onboarding: null },
+    accounts: [],
+  };
+
+  const mockAccount = {
+    id: testAccountId,
+    name: testAccountName,
+    ownerUserActor: { id: 'test-user-id', username: testAccountName },
+    users: [{ role: Role.Owner, actor: { id: 'test-user-id' } }],
+  };
+
+  const mockConnection: PostHogOrganizationConnectionData = {
+    id: 'connection-1',
+    posthogOrganizationIdentifier: 'org-123',
+    posthogOrganizationName: 'Test Org',
+    posthogRegion: PostHogRegion.Us,
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+  };
+
+  const mockProject: PostHogProjectData = {
+    id: 'project-1',
+    posthogProjectIdentifier: '467657',
+    posthogProjectName: 'testapp',
+    posthogProjectToken: 'phc_public_key',
+    posthogHost: 'https://us.posthog.com',
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+    posthogOrganizationConnection: mockConnection,
+  };
+
+  function createCommand(argv: string[], actor: Actor = mockActor): IntegrationsPostHogConnect {
+    const command = new IntegrationsPostHogConnect(argv, mockConfig);
+    jest.spyOn(command as any, 'getContextAsync').mockReturnValue({
+      privateProjectConfig: {
+        projectId: testProjectId,
+        exp: { name: 'testapp', slug: 'testapp', plugins: [] },
+        projectDir: '/test/project',
+      },
+      loggedIn: { graphqlClient, actor },
+    } as never);
+    return command;
+  }
+
+  // Helper: which features the interactive multiselect returns.
+  function mockFeatureSelection(features: string[]): void {
+    jest.mocked(promptAsync).mockImplementation((async (opts: any) => {
+      if (opts.name === 'features') {
+        return { features };
+      }
+      if (opts.name === 'apiKey') {
+        return { apiKey: 'phx_personal_key' };
+      }
+      return {};
+    }) as any);
+  }
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.spyOn(Log, 'log').mockImplementation(() => {});
+    jest.spyOn(Log, 'warn').mockImplementation(() => {});
+    jest.spyOn(Log, 'error').mockImplementation(() => {});
+    jest.spyOn(Log, 'withTick').mockImplementation(() => {});
+    jest.spyOn(Log, 'addNewLineIfNone').mockImplementation(() => {});
+    jest.spyOn(Log, 'newLine').mockImplementation(() => {});
+
+    jest.mocked(getOwnerAccountForProjectIdAsync).mockResolvedValue(mockAccount as any);
+    jest.mocked(selectAsync).mockResolvedValue(PostHogRegion.Us);
+    jest.mocked(confirmAsync).mockResolvedValue(true);
+    jest.mocked(spawnAsync).mockResolvedValue({} as any);
+    jest.mocked(fs.pathExists).mockResolvedValue(false as never);
+    jest.mocked(fs.writeFile).mockResolvedValue(undefined as never);
+    jest.mocked(createOrModifyExpoConfigAsync).mockResolvedValue({ type: 'success' } as any);
+    // Default: reuse an existing connection + project.
+    jest
+      .mocked(PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync)
+      .mockResolvedValue(mockConnection);
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(mockProject);
+    jest.mocked(PostHogMutation.createPostHogAccountRequestAsync).mockResolvedValue(mockConnection);
+    jest.mocked(PostHogMutation.setupPostHogProjectAsync).mockResolvedValue(mockProject);
+    jest.mocked(EnvironmentVariablesQuery.byAppIdAsync).mockResolvedValue([]);
+    jest.mocked(EnvironmentVariableMutation.createForAppAsync).mockResolvedValue({
+      id: 'env-var-1',
+      scope: EnvironmentVariableScope.Project,
+    } as any);
+    mockFeatureSelection(['analytics', 'session-replay', 'error-tracking']);
+  });
+
+  it('sets up all features: installs SDK + replay pkg, adds plugin, writes EXPO_PUBLIC_ + POSTHOG_CLI_ vars', async () => {
+    await createCommand([]).runAsync();
+
+    const installArgs = jest.mocked(spawnAsync).mock.calls[0][1];
+    expect(installArgs).toContain('posthog-react-native');
+    expect(installArgs).toContain('posthog-react-native-session-replay');
+    expect(createOrModifyExpoConfigAsync).toHaveBeenCalled();
+    expect(fs.writeFile).toHaveBeenCalled();
+
+    const createdNames = jest
+      .mocked(EnvironmentVariableMutation.createForAppAsync)
+      .mock.calls.map(call => call[1].name);
+    expect(createdNames).toEqual(
+      expect.arrayContaining([
+        'EXPO_PUBLIC_POSTHOG_API_KEY',
+        'EXPO_PUBLIC_POSTHOG_HOST',
+        'POSTHOG_CLI_API_KEY',
+        'POSTHOG_CLI_PROJECT_ID',
+        'POSTHOG_CLI_HOST',
+      ])
+    );
+    const cliKeyVar = jest
+      .mocked(EnvironmentVariableMutation.createForAppAsync)
+      .mock.calls.find(call => call[1].name === 'POSTHOG_CLI_API_KEY');
+    expect(cliKeyVar?.[1].visibility).toBe(EnvironmentVariableVisibility.Sensitive);
+    // The pasted personal key flows through verbatim — to EAS and to .env.local.
+    expect(cliKeyVar?.[1].value).toBe('phx_personal_key');
+    const written = jest.mocked(fs.writeFile).mock.calls[0][1] as string;
+    expect(written).toContain('POSTHOG_CLI_API_KEY=phx_personal_key');
+  });
+
+  it('asks for features only after provisioning (fast-forward ordering)', async () => {
+    jest
+      .mocked(PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync)
+      .mockResolvedValue(null);
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+    let provisionedBeforePrompt = false;
+    jest.mocked(promptAsync).mockImplementation((async (opts: any) => {
+      if (opts.name === 'features') {
+        provisionedBeforePrompt =
+          jest.mocked(PostHogMutation.createPostHogAccountRequestAsync).mock.calls.length > 0 &&
+          jest.mocked(PostHogMutation.setupPostHogProjectAsync).mock.calls.length > 0;
+        return { features: ['analytics'] };
+      }
+      return {};
+    }) as any);
+
+    await createCommand(['--region', 'US']).runAsync();
+
+    expect(provisionedBeforePrompt).toBe(true);
+  });
+
+  it('analytics only: no replay pkg, no CLI vars, no key prompt', async () => {
+    mockFeatureSelection(['analytics']);
+
+    await createCommand([]).runAsync();
+
+    expect(jest.mocked(spawnAsync).mock.calls[0][1]).not.toContain(
+      'posthog-react-native-session-replay'
+    );
+    const createdNames = jest
+      .mocked(EnvironmentVariableMutation.createForAppAsync)
+      .mock.calls.map(call => call[1].name);
+    expect(createdNames).toEqual(['EXPO_PUBLIC_POSTHOG_API_KEY', 'EXPO_PUBLIC_POSTHOG_HOST']);
+    expect(promptAsync).not.toHaveBeenCalledWith(expect.objectContaining({ name: 'apiKey' }));
+  });
+
+  it('adds the config plugin and public env vars for session-replay-only (analytics deselected)', async () => {
+    mockFeatureSelection(['session-replay']);
+
+    await createCommand([]).runAsync();
+
+    // The plugin wires native modules replay needs, so it must be added even without analytics.
+    expect(createOrModifyExpoConfigAsync).toHaveBeenCalled();
+    expect(jest.mocked(spawnAsync).mock.calls[0][1]).toContain(
+      'posthog-react-native-session-replay'
+    );
+    // The public key + host initialize the SDK for any feature, so they're still written.
+    const createdNames = jest
+      .mocked(EnvironmentVariableMutation.createForAppAsync)
+      .mock.calls.map(call => call[1].name);
+    expect(createdNames).toEqual(['EXPO_PUBLIC_POSTHOG_API_KEY', 'EXPO_PUBLIC_POSTHOG_HOST']);
+  });
+
+  it('captures the install child output so --json stdout stays clean', async () => {
+    await createCommand(['--json', '--posthog-cli-api-key', 'phx_x']).runAsync();
+
+    expect(jest.mocked(spawnAsync).mock.calls[0][2]).not.toHaveProperty('stdio');
+  });
+
+  it('non-interactive defaults: analytics + replay, error tracking auto-skipped', async () => {
+    await createCommand(['--non-interactive']).runAsync();
+
+    expect(promptAsync).not.toHaveBeenCalled();
+    const createdNames = jest
+      .mocked(EnvironmentVariableMutation.createForAppAsync)
+      .mock.calls.map(call => call[1].name);
+    expect(createdNames).not.toContain('POSTHOG_CLI_API_KEY');
+    expect(Log.warn).toHaveBeenCalledWith(expect.stringContaining('Skipping error tracking'));
+    // Session replay defaults on, so its package is still installed.
+    expect(jest.mocked(spawnAsync).mock.calls[0][1]).toContain(
+      'posthog-react-native-session-replay'
+    );
+  });
+
+  it('non-interactive --error-tracking without a key fails before any provisioning', async () => {
+    jest
+      .mocked(PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync)
+      .mockResolvedValue(null);
+
+    await expect(
+      createCommand(['--non-interactive', '--error-tracking']).runAsync()
+    ).rejects.toThrow(/personal API key in non-interactive/);
+
+    expect(PostHogMutation.createPostHogAccountRequestAsync).not.toHaveBeenCalled();
+  });
+
+  it('non-interactive --error-tracking with --posthog-cli-api-key sets up CLI vars without prompting', async () => {
+    await createCommand([
+      '--non-interactive',
+      '--error-tracking',
+      '--posthog-cli-api-key',
+      'phx_from_flag',
+    ]).runAsync();
+
+    expect(promptAsync).not.toHaveBeenCalled();
+    const cliKeyVar = jest
+      .mocked(EnvironmentVariableMutation.createForAppAsync)
+      .mock.calls.find(call => call[1].name === 'POSTHOG_CLI_API_KEY');
+    expect(cliKeyVar?.[1].value).toBe('phx_from_flag');
+  });
+
+  it('treats a whitespace-only --posthog-cli-api-key as absent (fails like no key)', async () => {
+    await expect(
+      createCommand([
+        '--non-interactive',
+        '--error-tracking',
+        '--posthog-cli-api-key',
+        '   ',
+      ]).runAsync()
+    ).rejects.toThrow(/personal API key in non-interactive/);
+  });
+
+  it('surfaces a manual plugin step and still writes env vars when the app config is dynamic', async () => {
+    mockFeatureSelection(['analytics']);
+    jest.mocked(createOrModifyExpoConfigAsync).mockResolvedValue({
+      type: 'warn',
+      message: 'Cannot automatically write to dynamic config',
+    } as any);
+
+    await createCommand([]).runAsync();
+
+    expect(Log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Add "posthog-react-native/expo" to the "plugins"')
+    );
+    expect(EnvironmentVariableMutation.createForAppAsync).toHaveBeenCalled();
+    expect(fs.writeFile).toHaveBeenCalled();
+  });
+
+  it('surfaces the plugin manual step (without a cause) when the config write fails', async () => {
+    mockFeatureSelection(['analytics']);
+    jest.mocked(createOrModifyExpoConfigAsync).mockResolvedValue({ type: 'fail' } as any);
+
+    await createCommand([]).runAsync();
+
+    expect(Log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Add "posthog-react-native/expo" to the "plugins"')
+    );
+    expect(EnvironmentVariableMutation.createForAppAsync).toHaveBeenCalled();
+  });
+
+  it('reuses an existing connection + project without provisioning', async () => {
+    await createCommand([]).runAsync();
+
+    expect(PostHogMutation.createPostHogAccountRequestAsync).not.toHaveBeenCalled();
+    expect(PostHogMutation.setupPostHogProjectAsync).not.toHaveBeenCalled();
+  });
+
+  it('surfaces the existing-account dead-end without provisioning a project', async () => {
+    jest
+      .mocked(PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync)
+      .mockResolvedValue(null);
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+    jest.mocked(PostHogMutation.createPostHogAccountRequestAsync).mockRejectedValue(
+      Object.assign(new Error('You already have a PostHog account.'), {
+        graphQLErrors: [{ extensions: { errorCode: 'POSTHOG_EXISTING_USER_NOT_SUPPORTED_ERROR' } }],
+      })
+    );
+
+    await expect(createCommand(['--region', 'US']).runAsync()).rejects.toThrow(
+      'You already have a PostHog account.'
+    );
+
+    // Fails (non-zero exit) without provisioning a project or writing any config.
+    expect(PostHogMutation.setupPostHogProjectAsync).not.toHaveBeenCalled();
+    expect(EnvironmentVariableMutation.createForAppAsync).not.toHaveBeenCalled();
+    expect(fs.writeFile).not.toHaveBeenCalled();
+  });
+
+  it('emits JSON output with --json', async () => {
+    await createCommand(['--json', '--posthog-cli-api-key', 'phx_x']).runAsync();
+
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith(
+      expect.objectContaining({
+        project: expect.objectContaining({ apiKey: 'phc_public_key' }),
+        // --json supplies the key, so error tracking is on and its vars are reported.
+        features: expect.objectContaining({ analytics: true, errorTracking: true }),
+        dashboardUrl: expect.any(String),
+        environmentVariables: expect.arrayContaining([
+          'EXPO_PUBLIC_POSTHOG_API_KEY',
+          'POSTHOG_CLI_API_KEY',
+          'POSTHOG_CLI_PROJECT_ID',
+          'POSTHOG_CLI_HOST',
+        ]),
+      })
+    );
+  });
+
+  it('requires --region in non-interactive mode when provisioning', async () => {
+    jest
+      .mocked(PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync)
+      .mockResolvedValue(null);
+
+    await expect(createCommand(['--non-interactive']).runAsync()).rejects.toThrow(
+      /region is required in non-interactive/
+    );
+  });
+
+  it('warns when --region differs from the already-connected region', async () => {
+    await createCommand(['--region', 'EU']).runAsync();
+
+    expect(Log.warn).toHaveBeenCalledWith(expect.stringContaining('already connected to PostHog'));
+  });
+
+  it('provisions a new connection and project when none exist', async () => {
+    jest
+      .mocked(PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync)
+      .mockResolvedValue(null);
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+    mockFeatureSelection(['analytics']);
+
+    await createCommand(['--region', 'US']).runAsync();
+
+    expect(PostHogMutation.createPostHogAccountRequestAsync).toHaveBeenCalledWith(graphqlClient, {
+      accountId: testAccountId,
+      region: PostHogRegion.Us,
+    });
+    expect(PostHogMutation.setupPostHogProjectAsync).toHaveBeenCalledWith(graphqlClient, {
+      appId: testProjectId,
+      posthogOrganizationConnectionId: mockConnection.id,
+    });
+  });
+
+  it('rethrows a non-dead-end provisioning failure', async () => {
+    jest
+      .mocked(PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync)
+      .mockResolvedValue(null);
+    jest
+      .mocked(PostHogMutation.createPostHogAccountRequestAsync)
+      .mockRejectedValue(new Error('network down'));
+
+    await expect(createCommand(['--region', 'US']).runAsync()).rejects.toThrow('network down');
+  });
+
+  it('rethrows when project setup fails', async () => {
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+    jest
+      .mocked(PostHogMutation.setupPostHogProjectAsync)
+      .mockRejectedValue(new Error('setup failed'));
+
+    await expect(createCommand([]).runAsync()).rejects.toThrow('setup failed');
+  });
+
+  it('honors explicit --no-session-replay without showing the feature multiselect', async () => {
+    await createCommand(['--no-session-replay']).runAsync();
+
+    expect(promptAsync).not.toHaveBeenCalledWith(expect.objectContaining({ name: 'features' }));
+    expect(jest.mocked(spawnAsync).mock.calls[0][1]).not.toContain(
+      'posthog-react-native-session-replay'
+    );
+  });
+
+  it('prompts for a personal API key and validates it', async () => {
+    await createCommand([]).runAsync();
+
+    const apiKeyPrompt = jest
+      .mocked(promptAsync)
+      .mock.calls.map(call => call[0])
+      .find((opts: any) => opts.name === 'apiKey') as any;
+    expect(apiKeyPrompt).toBeDefined();
+    expect(apiKeyPrompt.validate('')).toBe('Personal API key cannot be empty');
+    expect(apiKeyPrompt.validate('phx_real')).toBe(true);
+  });
+
+  it('continues (does not abort) and still writes env vars when SDK installation fails', async () => {
+    mockFeatureSelection(['analytics']);
+    jest.mocked(spawnAsync).mockRejectedValue(new Error('npm exploded'));
+
+    await createCommand([]).runAsync();
+
+    // Install failure is non-fatal: provisioning + env vars still happen, with a manual follow-up.
+    expect(EnvironmentVariableMutation.createForAppAsync).toHaveBeenCalled();
+    expect(fs.writeFile).toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(expect.stringContaining('npx expo install'));
+  });
+
+  it('on a dynamic config, surfaces only the plugin step (not a reinstall step) when expo install reports the dynamic-config error', async () => {
+    mockFeatureSelection(['analytics']);
+    jest.mocked(spawnAsync).mockRejectedValue(
+      Object.assign(new Error('Process exited with non-zero code: 1'), {
+        stdout: 'Cannot automatically write to dynamic config at: app.config.js\n',
+        stderr: '',
+      })
+    );
+    jest.mocked(createOrModifyExpoConfigAsync).mockResolvedValue({
+      type: 'warn',
+      message: 'Cannot automatically write to dynamic config at: app.config.js',
+    } as any);
+
+    await createCommand([]).runAsync();
+
+    expect(EnvironmentVariableMutation.createForAppAsync).toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Add "posthog-react-native/expo" to the "plugins"')
+    );
+    expect(Log.warn).not.toHaveBeenCalledWith(expect.stringContaining("didn't install"));
+  });
+
+  it('skips the config plugin when it is already configured', async () => {
+    mockFeatureSelection(['analytics']);
+    const command = createCommand([]);
+    jest.spyOn(command as any, 'getContextAsync').mockReturnValue({
+      privateProjectConfig: {
+        projectId: testProjectId,
+        exp: { name: 'testapp', slug: 'testapp', plugins: ['posthog-react-native/expo'] },
+        projectDir: '/test/project',
+      },
+      loggedIn: { graphqlClient, actor: mockActor },
+    } as never);
+
+    await command.runAsync();
+
+    expect(createOrModifyExpoConfigAsync).not.toHaveBeenCalled();
+  });
+
+  it('does nothing local when no features are selected (no install, no writes)', async () => {
+    mockFeatureSelection([]);
+
+    await createCommand([]).runAsync();
+
+    expect(spawnAsync).not.toHaveBeenCalled();
+    expect(createOrModifyExpoConfigAsync).not.toHaveBeenCalled();
+    expect(fs.writeFile).not.toHaveBeenCalled();
+    expect(EnvironmentVariableMutation.createForAppAsync).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(expect.stringContaining('No PostHog features selected'));
+    // Doesn't falsely claim the SDK is wired up when nothing was configured.
+    expect(Log.log).not.toHaveBeenCalledWith(expect.stringContaining('PostHog is connected!'));
+    expect(Log.warn).toHaveBeenCalledWith(expect.stringContaining('Re-run to add'));
+  });
+
+  it('merges into an existing .env.local, replacing matching keys and appending new ones', async () => {
+    mockFeatureSelection(['analytics']);
+    jest.mocked(fs.pathExists).mockResolvedValue(true as never);
+    jest
+      .mocked(fs.readFile)
+      .mockResolvedValue('EXPO_PUBLIC_POSTHOG_API_KEY=old_value\nOTHER=keep' as never);
+
+    await createCommand([]).runAsync();
+
+    const written = jest.mocked(fs.writeFile).mock.calls[0][1] as string;
+    expect(written).toContain('EXPO_PUBLIC_POSTHOG_API_KEY=phc_public_key');
+    expect(written).toContain('OTHER=keep');
+    expect(written).toContain('EXPO_PUBLIC_POSTHOG_HOST=https://us.posthog.com');
+  });
+
+  it('prompts for a region interactively when provisioning without --region', async () => {
+    jest
+      .mocked(PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync)
+      .mockResolvedValue(null);
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+    mockFeatureSelection(['analytics']);
+
+    await createCommand([]).runAsync();
+
+    expect(selectAsync).toHaveBeenCalledWith('Select a PostHog region', expect.any(Array));
+    expect(PostHogMutation.createPostHogAccountRequestAsync).toHaveBeenCalledWith(graphqlClient, {
+      accountId: testAccountId,
+      region: PostHogRegion.Us,
+    });
+  });
+
+  it('skips .env.local when the user declines to overwrite a conflict', async () => {
+    mockFeatureSelection(['analytics']);
+    jest.mocked(fs.pathExists).mockResolvedValue(true as never);
+    jest.mocked(fs.readFile).mockResolvedValue('EXPO_PUBLIC_POSTHOG_API_KEY=old_value\n' as never);
+    jest.mocked(confirmAsync).mockResolvedValue(false);
+
+    await createCommand([]).runAsync();
+
+    expect(fs.writeFile).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(expect.stringContaining('Skipped updating'));
+  });
+
+  it('--overwrite writes .env.local without prompting on a conflict', async () => {
+    mockFeatureSelection(['analytics']);
+    jest.mocked(fs.pathExists).mockResolvedValue(true as never);
+    jest.mocked(fs.readFile).mockResolvedValue('EXPO_PUBLIC_POSTHOG_API_KEY=old_value\n' as never);
+
+    await createCommand(['--overwrite']).runAsync();
+
+    expect(confirmAsync).not.toHaveBeenCalled();
+    const written = jest.mocked(fs.writeFile).mock.calls[0][1] as string;
+    expect(written).toContain('EXPO_PUBLIC_POSTHOG_API_KEY=phc_public_key');
+  });
+
+  it('non-interactively skips an existing .env.local key without --overwrite', async () => {
+    jest.mocked(fs.pathExists).mockResolvedValue(true as never);
+    jest.mocked(fs.readFile).mockResolvedValue('EXPO_PUBLIC_POSTHOG_API_KEY=old_value\n' as never);
+
+    await createCommand(['--non-interactive']).runAsync();
+
+    expect(confirmAsync).not.toHaveBeenCalled();
+    expect(fs.writeFile).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(expect.stringContaining('pass --overwrite to replace'));
+  });
+
+  it('non-interactively overwrites an existing .env.local key with --overwrite', async () => {
+    jest.mocked(fs.pathExists).mockResolvedValue(true as never);
+    jest.mocked(fs.readFile).mockResolvedValue('EXPO_PUBLIC_POSTHOG_API_KEY=old_value\n' as never);
+
+    await createCommand(['--non-interactive', '--overwrite']).runAsync();
+
+    expect(confirmAsync).not.toHaveBeenCalled();
+    const written = jest.mocked(fs.writeFile).mock.calls[0][1] as string;
+    expect(written).toContain('EXPO_PUBLIC_POSTHOG_API_KEY=phc_public_key');
+  });
+
+  it('writes a personal API key containing $ verbatim (no replacement-pattern expansion)', async () => {
+    const command = createCommand([]);
+    const merged = (command as any).mergeEnvContent('POSTHOG_CLI_API_KEY=old\n', {
+      POSTHOG_CLI_API_KEY: 'phx_a$2b$&c',
+    });
+    expect(merged).toContain('POSTHOG_CLI_API_KEY=phx_a$2b$&c');
+  });
+
+  it('updates an existing EAS environment variable with --overwrite', async () => {
+    mockFeatureSelection(['analytics']);
+    jest
+      .mocked(EnvironmentVariablesQuery.byAppIdAsync)
+      .mockResolvedValue([{ id: 'existing-1', scope: EnvironmentVariableScope.Project }] as any);
+    jest
+      .mocked(EnvironmentVariableMutation.updateAsync)
+      .mockResolvedValue({ id: 'existing-1' } as any);
+
+    await createCommand(['--overwrite']).runAsync();
+
+    expect(EnvironmentVariableMutation.updateAsync).toHaveBeenCalled();
+    expect(EnvironmentVariableMutation.createForAppAsync).not.toHaveBeenCalled();
+  });
+
+  it('honors explicit --error-tracking interactively and detects an array-form plugin', async () => {
+    const command = createCommand(['--error-tracking', '--posthog-cli-api-key', 'phx_flag']);
+    jest.spyOn(command as any, 'getContextAsync').mockReturnValue({
+      privateProjectConfig: {
+        projectId: testProjectId,
+        exp: { name: 'testapp', slug: 'testapp', plugins: [['expo-router', {}]] },
+        projectDir: '/test/project',
+      },
+      loggedIn: { graphqlClient, actor: mockActor },
+    } as never);
+
+    await command.runAsync();
+
+    expect(promptAsync).not.toHaveBeenCalledWith(expect.objectContaining({ name: 'features' }));
+    const cliKeyVar = jest
+      .mocked(EnvironmentVariableMutation.createForAppAsync)
+      .mock.calls.find(call => call[1].name === 'POSTHOG_CLI_API_KEY');
+    expect(cliKeyVar?.[1].value).toBe('phx_flag');
+    expect(createOrModifyExpoConfigAsync).toHaveBeenCalled();
+  });
+
+  it('skips an existing EAS environment variable non-interactively without --overwrite', async () => {
+    jest
+      .mocked(EnvironmentVariablesQuery.byAppIdAsync)
+      .mockResolvedValue([{ id: 'existing-1', scope: EnvironmentVariableScope.Project }] as any);
+
+    await createCommand(['--non-interactive', '--region', 'US']).runAsync();
+
+    expect(EnvironmentVariableMutation.updateAsync).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('pass --overwrite to replace it')
+    );
+  });
+
+  it('skips an existing EAS environment variable when overwrite is declined', async () => {
+    mockFeatureSelection(['analytics']);
+    jest
+      .mocked(EnvironmentVariablesQuery.byAppIdAsync)
+      .mockResolvedValue([{ id: 'existing-1', scope: EnvironmentVariableScope.Project }] as any);
+    jest.mocked(confirmAsync).mockResolvedValue(false);
+
+    await createCommand([]).runAsync();
+
+    expect(EnvironmentVariableMutation.updateAsync).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Skipped updating EAS environment variable')
+    );
+  });
+});

packages/eas-cli/src/commands/integrations/posthog/__tests__/dashboard.test.ts

@@ -0,0 +1,160 @@
+import openBrowserAsync from 'better-opn';
+
+import { getMockOclifConfig } from '../../../../__tests__/commands/utils';
+import { ExpoGraphqlClient } from '../../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { testProjectId } from '../../../../credentials/__tests__/fixtures-constants';
+import { PostHogRegion } from '../../../../graphql/generated';
+import { PostHogQuery } from '../../../../graphql/queries/PostHogQuery';
+import {
+  PostHogOrganizationConnectionData,
+  PostHogProjectData,
+} from '../../../../graphql/types/PostHogConnection';
+import Log from '../../../../log';
+import { ora } from '../../../../ora';
+import { printJsonOnlyOutput } from '../../../../utils/json';
+import IntegrationsPostHogDashboard from '../dashboard';
+
+jest.mock('better-opn');
+jest.mock('../../../../graphql/queries/PostHogQuery');
+jest.mock('../../../../log');
+jest.mock('../../../../utils/json');
+jest.mock('../../../../ora', () => ({
+  ora: jest.fn(() => ({
+    start: jest.fn().mockReturnThis(),
+    succeed: jest.fn().mockReturnThis(),
+    fail: jest.fn().mockReturnThis(),
+  })),
+}));
+
+describe(IntegrationsPostHogDashboard, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+
+  const mockConnection: PostHogOrganizationConnectionData = {
+    id: 'connection-1',
+    posthogOrganizationIdentifier: 'org-123',
+    posthogOrganizationName: 'Test Org',
+    posthogRegion: PostHogRegion.Us,
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+  };
+
+  const mockProject: PostHogProjectData = {
+    id: 'project-1',
+    posthogProjectIdentifier: 'res-123',
+    posthogProjectName: 'Test Project',
+    posthogProjectToken: 'phc_public_key',
+    posthogHost: 'https://us.posthog.com',
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+    posthogOrganizationConnection: mockConnection,
+  };
+
+  function createCommand(argv: string[] = []): IntegrationsPostHogDashboard {
+    const command = new IntegrationsPostHogDashboard(argv, mockConfig);
+    jest.spyOn(command as any, 'getContextAsync').mockReturnValue({
+      privateProjectConfig: {
+        projectId: testProjectId,
+        exp: { slug: 'testapp' },
+      },
+      loggedIn: { graphqlClient },
+    } as never);
+    return command;
+  }
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.spyOn(Log, 'warn').mockImplementation(() => {});
+    jest.spyOn(Log, 'log').mockImplementation(() => {});
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(mockProject);
+    jest.mocked(openBrowserAsync).mockResolvedValue({} as never);
+    jest.mocked(ora).mockReturnValue({
+      start: jest.fn().mockReturnThis(),
+      succeed: jest.fn().mockReturnThis(),
+      fail: jest.fn().mockReturnThis(),
+    } as any);
+  });
+
+  it('opens the linked PostHog project dashboard', async () => {
+    await createCommand().runAsync();
+
+    expect(openBrowserAsync).toHaveBeenCalledWith('https://us.posthog.com/project/res-123');
+  });
+
+  it('normalizes a trailing-slash host and percent-encodes the project identifier', async () => {
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue({
+      ...mockProject,
+      posthogHost: 'https://us.posthog.com/',
+      posthogProjectIdentifier: 'team a/b',
+    });
+
+    await createCommand().runAsync();
+
+    expect(openBrowserAsync).toHaveBeenCalledWith('https://us.posthog.com/project/team%20a%2Fb');
+  });
+
+  it('logs an empty state when no project link exists', async () => {
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+
+    await createCommand().runAsync();
+
+    expect(openBrowserAsync).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('No PostHog project is linked to Expo app')
+    );
+  });
+
+  it('fails the spinner when the browser cannot be opened', async () => {
+    jest.mocked(openBrowserAsync).mockResolvedValue(false);
+    const spinner = {
+      start: jest.fn().mockReturnThis(),
+      succeed: jest.fn().mockReturnThis(),
+      fail: jest.fn().mockReturnThis(),
+    };
+    jest.mocked(ora).mockReturnValue(spinner as any);
+
+    await createCommand().runAsync();
+
+    expect(spinner.fail).toHaveBeenCalledWith(
+      expect.stringContaining('Unable to open a web browser')
+    );
+  });
+
+  it('prints the dashboard URL in non-interactive mode without opening a browser', async () => {
+    await createCommand(['--non-interactive']).runAsync();
+
+    expect(openBrowserAsync).not.toHaveBeenCalled();
+    expect(Log.log).toHaveBeenCalledWith('https://us.posthog.com/project/res-123');
+  });
+
+  it('emits the dashboard URL as JSON with --json', async () => {
+    await createCommand(['--json']).runAsync();
+
+    expect(openBrowserAsync).not.toHaveBeenCalled();
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith({
+      dashboardUrl: 'https://us.posthog.com/project/res-123',
+    });
+  });
+
+  it('emits a null dashboardUrl as JSON when no project is linked', async () => {
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+
+    await createCommand(['--json']).runAsync();
+
+    expect(openBrowserAsync).not.toHaveBeenCalled();
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith({ dashboardUrl: null });
+  });
+
+  it('fails the spinner and rethrows when opening the browser throws', async () => {
+    jest.mocked(openBrowserAsync).mockRejectedValue(new Error('no browser'));
+    const spinner = {
+      start: jest.fn().mockReturnThis(),
+      succeed: jest.fn().mockReturnThis(),
+      fail: jest.fn().mockReturnThis(),
+    };
+    jest.mocked(ora).mockReturnValue(spinner as any);
+
+    await expect(createCommand().runAsync()).rejects.toThrow('no browser');
+    expect(spinner.fail).toHaveBeenCalled();
+  });
+});

packages/eas-cli/src/commands/integrations/posthog/__tests__/disconnect.test.ts

@@ -0,0 +1,158 @@
+import { getMockOclifConfig } from '../../../../__tests__/commands/utils';
+import { ExpoGraphqlClient } from '../../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { testProjectId } from '../../../../credentials/__tests__/fixtures-constants';
+import { PostHogRegion } from '../../../../graphql/generated';
+import { PostHogMutation } from '../../../../graphql/mutations/PostHogMutation';
+import { PostHogQuery } from '../../../../graphql/queries/PostHogQuery';
+import {
+  PostHogOrganizationConnectionData,
+  PostHogProjectData,
+} from '../../../../graphql/types/PostHogConnection';
+import Log from '../../../../log';
+import { confirmAsync } from '../../../../prompts';
+import { printJsonOnlyOutput } from '../../../../utils/json';
+import IntegrationsPostHogDisconnect from '../disconnect';
+
+jest.mock('../../../../graphql/queries/PostHogQuery');
+jest.mock('../../../../graphql/mutations/PostHogMutation');
+jest.mock('../../../../prompts');
+jest.mock('../../../../log');
+jest.mock('../../../../utils/json');
+jest.mock('../../../../ora', () => ({
+  ora: () => ({
+    start: jest.fn().mockReturnThis(),
+    succeed: jest.fn().mockReturnThis(),
+    fail: jest.fn().mockReturnThis(),
+  }),
+}));
+
+describe(IntegrationsPostHogDisconnect, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+
+  const mockConnection: PostHogOrganizationConnectionData = {
+    id: 'connection-1',
+    posthogOrganizationIdentifier: 'org-123',
+    posthogOrganizationName: 'Test Org',
+    posthogRegion: PostHogRegion.Us,
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+  };
+
+  const mockProject: PostHogProjectData = {
+    id: 'project-1',
+    posthogProjectIdentifier: 'res-123',
+    posthogProjectName: 'Test Project',
+    posthogProjectToken: 'phc_public_key',
+    posthogHost: 'https://us.posthog.com',
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+    posthogOrganizationConnection: mockConnection,
+  };
+
+  function createCommand(argv: string[]): IntegrationsPostHogDisconnect {
+    const command = new IntegrationsPostHogDisconnect(argv, mockConfig);
+    jest.spyOn(command as any, 'getContextAsync').mockReturnValue({
+      privateProjectConfig: {
+        projectId: testProjectId,
+        exp: { slug: 'testapp' },
+      },
+      loggedIn: { graphqlClient },
+    } as never);
+    return command;
+  }
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.spyOn(Log, 'log').mockImplementation(() => {});
+    jest.spyOn(Log, 'warn').mockImplementation(() => {});
+    jest.spyOn(Log, 'error').mockImplementation(() => {});
+    jest.spyOn(Log, 'addNewLineIfNone').mockImplementation(() => {});
+    jest.spyOn(Log, 'newLine').mockImplementation(() => {});
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(mockProject);
+    jest.mocked(PostHogMutation.deletePostHogProjectAsync).mockResolvedValue(mockProject.id);
+    jest.mocked(confirmAsync).mockResolvedValue(true);
+  });
+
+  it('removes the project link after confirmation', async () => {
+    await createCommand([]).runAsync();
+
+    expect(PostHogMutation.deletePostHogProjectAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      mockProject.id
+    );
+  });
+
+  it('skips the prompt with --yes', async () => {
+    await createCommand(['--yes']).runAsync();
+
+    expect(confirmAsync).not.toHaveBeenCalled();
+    expect(PostHogMutation.deletePostHogProjectAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      mockProject.id
+    );
+  });
+
+  it('does nothing when the user declines confirmation', async () => {
+    jest.mocked(confirmAsync).mockResolvedValue(false);
+
+    await createCommand([]).runAsync();
+
+    expect(PostHogMutation.deletePostHogProjectAsync).not.toHaveBeenCalled();
+  });
+
+  it('deletes after a warning in non-interactive mode, noting PostHog data is preserved', async () => {
+    await createCommand(['--non-interactive']).runAsync();
+
+    expect(confirmAsync).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('does not delete the project on PostHog')
+    );
+    expect(PostHogMutation.deletePostHogProjectAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      mockProject.id
+    );
+  });
+
+  it('logs an empty state when no project link exists', async () => {
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+
+    await createCommand([]).runAsync();
+
+    expect(PostHogMutation.deletePostHogProjectAsync).not.toHaveBeenCalled();
+    expect(Log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('No PostHog project is linked to Expo app')
+    );
+  });
+
+  it('emits JSON output with --json and skips the prompt', async () => {
+    await createCommand(['--json']).runAsync();
+
+    expect(confirmAsync).not.toHaveBeenCalled();
+    expect(PostHogMutation.deletePostHogProjectAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      mockProject.id
+    );
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith({
+      id: mockProject.id,
+      name: mockProject.posthogProjectName,
+    });
+  });
+
+  it('emits a null id as JSON when no project is linked', async () => {
+    jest.mocked(PostHogQuery.getPostHogProjectByAppIdAsync).mockResolvedValue(null);
+
+    await createCommand(['--json']).runAsync();
+
+    expect(PostHogMutation.deletePostHogProjectAsync).not.toHaveBeenCalled();
+    expect(printJsonOnlyOutput).toHaveBeenCalledWith({ id: null });
+  });
+
+  it('rethrows when the delete mutation fails', async () => {
+    jest
+      .mocked(PostHogMutation.deletePostHogProjectAsync)
+      .mockRejectedValue(new Error('delete boom'));
+
+    await expect(createCommand(['--yes']).runAsync()).rejects.toThrow('delete boom');
+  });
+});

packages/eas-cli/src/commands/integrations/posthog/connect.ts

@@ -0,0 +1,568 @@
+import { ExpoConfig } from '@expo/config';
+import spawnAsync from '@expo/spawn-async';
+import { Flags } from '@oclif/core';
+import chalk from 'chalk';
+import dotenv from 'dotenv';
+import * as fs from 'fs-extra';
+import path from 'path';
+
+import { DefaultEnvironment } from '../../../build/utils/environment';
+import EasCommand from '../../../commandUtils/EasCommand';
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../../commandUtils/flags';
+import { getPostHogProjectDashboardUrl } from '../../../commandUtils/posthog';
+import {
+  EnvironmentSecretType,
+  EnvironmentVariableScope,
+  EnvironmentVariableVisibility,
+  PostHogRegion,
+} from '../../../graphql/generated';
+import { EnvironmentVariableMutation } from '../../../graphql/mutations/EnvironmentVariableMutation';
+import { PostHogMutation } from '../../../graphql/mutations/PostHogMutation';
+import { EnvironmentVariablesQuery } from '../../../graphql/queries/EnvironmentVariablesQuery';
+import { PostHogQuery } from '../../../graphql/queries/PostHogQuery';
+import { PostHogProjectData } from '../../../graphql/types/PostHogConnection';
+import Log, { link } from '../../../log';
+import { ora } from '../../../ora';
+import { createOrModifyExpoConfigAsync } from '../../../project/expoConfig';
+import { getOwnerAccountForProjectIdAsync } from '../../../project/projectUtils';
+import { Choice, confirmAsync, promptAsync, selectAsync } from '../../../prompts';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+
+const POSTHOG_REGIONS = [
+  { title: 'United States (US)', value: PostHogRegion.Us },
+  { title: 'European Union (EU)', value: PostHogRegion.Eu },
+];
+
+const EAS_POSTHOG_ENVIRONMENTS = [
+  DefaultEnvironment.Production,
+  DefaultEnvironment.Preview,
+  DefaultEnvironment.Development,
+];
+
+const SDK_PACKAGES = [
+  'posthog-react-native',
+  'expo-file-system',
+  'expo-application',
+  'expo-device',
+  'expo-localization',
+];
+const SESSION_REPLAY_PACKAGE = 'posthog-react-native-session-replay';
+const CONFIG_PLUGIN = 'posthog-react-native/expo';
+
+const EAS_POSTHOG_API_KEY_ENV_VAR_NAME = 'EXPO_PUBLIC_POSTHOG_API_KEY';
+const EAS_POSTHOG_HOST_ENV_VAR_NAME = 'EXPO_PUBLIC_POSTHOG_HOST';
+const POSTHOG_CLI_API_KEY_ENV_VAR_NAME = 'POSTHOG_CLI_API_KEY';
+const POSTHOG_CLI_PROJECT_ID_ENV_VAR_NAME = 'POSTHOG_CLI_PROJECT_ID';
+const POSTHOG_CLI_HOST_ENV_VAR_NAME = 'POSTHOG_CLI_HOST';
+
+const PERSONAL_API_KEY_SETTINGS_PATH = '/settings/user-api-keys';
+const ERROR_TRACKING_NEEDS_KEY_MESSAGE = `Error tracking needs a PostHog personal API key in non-interactive mode. Pass --posthog-cli-api-key (create one in PostHog under Settings → Personal API keys (${PERSONAL_API_KEY_SETTINGS_PATH}) with the "Source map upload" preset), or drop --error-tracking.`;
+
+type Features = { analytics: boolean; sessionReplay: boolean; errorTracking: boolean };
+type EnvVar = { name: string; value: string; visibility: EnvironmentVariableVisibility };
+
+function getSpawnErrorOutput(error: unknown): string {
+  const { stdout, stderr } = (error ?? {}) as { stdout?: string; stderr?: string };
+  return `${stdout ?? ''}${stderr ?? ''}`;
+}
+
+export default class IntegrationsPostHogConnect extends EasCommand {
+  static override description = 'connect PostHog to your Expo project';
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectConfig,
+  };
+
+  static override flags = {
+    ...EasNonInteractiveAndJsonFlags,
+    region: Flags.string({
+      description: 'PostHog region',
+      options: POSTHOG_REGIONS.map(r => r.value),
+    }),
+    'session-replay': Flags.boolean({
+      allowNo: true,
+      description: 'Set up PostHog session replay (default: yes)',
+    }),
+    'error-tracking': Flags.boolean({
+      allowNo: true,
+      description: 'Set up PostHog error tracking / source maps (requires a personal API key)',
+    }),
+    'posthog-cli-api-key': Flags.string({
+      description:
+        'PostHog personal API key for error-tracking source-map uploads (enables error tracking non-interactively)',
+    }),
+    overwrite: Flags.boolean({
+      description: 'Overwrite existing PostHog environment variables without prompting',
+      default: false,
+    }),
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(IntegrationsPostHogConnect);
+    const { region: regionFlag, overwrite } = flags;
+    const cliApiKeyFlag =
+      (flags['posthog-cli-api-key'] ?? process.env[POSTHOG_CLI_API_KEY_ENV_VAR_NAME])?.trim() ||
+      undefined;
+    const { json: jsonFlag, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+    if (jsonFlag) {
+      enableJsonOutput();
+    }
+
+    if (nonInteractive && flags['error-tracking'] === true && !cliApiKeyFlag) {
+      throw new Error(ERROR_TRACKING_NEEDS_KEY_MESSAGE);
+    }
+
+    const {
+      privateProjectConfig: { projectId, exp, projectDir },
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(IntegrationsPostHogConnect, {
+      nonInteractive,
+      withServerSideEnvironment: null,
+    });
+
+    const account = await getOwnerAccountForProjectIdAsync(graphqlClient, projectId);
+
+    let connection = await PostHogQuery.getPostHogOrganizationConnectionByAccountIdAsync(
+      graphqlClient,
+      account.id
+    );
+    if (connection) {
+      if (regionFlag && regionFlag !== connection.posthogRegion) {
+        Log.warn(
+          `This account is already connected to PostHog in the ${connection.posthogRegion} region; --region ${regionFlag} is ignored. An account has a single PostHog organization and its region can't be changed.`
+        );
+      }
+      Log.withTick(
+        `Using existing PostHog organization ${chalk.bold(connection.posthogOrganizationName)} (${connection.posthogRegion})`
+      );
+    } else {
+      const region = await this.resolveRegionAsync(regionFlag, nonInteractive);
+      const spinner = ora('Creating PostHog organization').start();
+      try {
+        connection = await PostHogMutation.createPostHogAccountRequestAsync(graphqlClient, {
+          accountId: account.id,
+          region,
+        });
+        spinner.succeed(
+          `Created PostHog organization ${chalk.bold(connection.posthogOrganizationName)}`
+        );
+      } catch (error) {
+        spinner.fail('Failed to create PostHog organization');
+        throw error;
+      }
+    }
+
+    let project = await PostHogQuery.getPostHogProjectByAppIdAsync(graphqlClient, projectId);
+    if (project) {
+      Log.withTick(`Using existing PostHog project ${chalk.bold(project.posthogProjectName)}`);
+    } else {
+      const spinner = ora('Setting up PostHog project').start();
+      try {
+        project = await PostHogMutation.setupPostHogProjectAsync(graphqlClient, {
+          appId: projectId,
+          posthogOrganizationConnectionId: connection.id,
+        });
+        spinner.succeed(`Created PostHog project ${chalk.bold(project.posthogProjectName)}`);
+      } catch (error) {
+        spinner.fail('Failed to set up PostHog project');
+        throw error;
+      }
+    }
+
+    const features = await this.resolveFeaturesAsync(flags, cliApiKeyFlag, nonInteractive);
+    const anyFeatureSelected =
+      features.analytics || features.sessionReplay || features.errorTracking;
+
+    const envVars: EnvVar[] = [];
+    if (anyFeatureSelected) {
+      envVars.push(
+        {
+          name: EAS_POSTHOG_API_KEY_ENV_VAR_NAME,
+          value: project.posthogProjectToken,
+          visibility: EnvironmentVariableVisibility.Public,
+        },
+        {
+          name: EAS_POSTHOG_HOST_ENV_VAR_NAME,
+          value: project.posthogHost,
+          visibility: EnvironmentVariableVisibility.Public,
+        }
+      );
+    }
+    if (features.errorTracking) {
+      const cliApiKey = await this.resolveCliApiKeyAsync(cliApiKeyFlag, project.posthogHost);
+      envVars.push(
+        {
+          name: POSTHOG_CLI_API_KEY_ENV_VAR_NAME,
+          value: cliApiKey,
+          visibility: EnvironmentVariableVisibility.Sensitive,
+        },
+        {
+          name: POSTHOG_CLI_PROJECT_ID_ENV_VAR_NAME,
+          value: project.posthogProjectIdentifier,
+          visibility: EnvironmentVariableVisibility.Public,
+        },
+        {
+          name: POSTHOG_CLI_HOST_ENV_VAR_NAME,
+          value: project.posthogHost,
+          visibility: EnvironmentVariableVisibility.Public,
+        }
+      );
+    }
+
+    const manualSteps: string[] = [];
+    if (anyFeatureSelected) {
+      const packages = [...SDK_PACKAGES];
+      if (features.sessionReplay) {
+        packages.push(SESSION_REPLAY_PACKAGE);
+      }
+      const installResult = await this.installSdkPackagesAsync(projectDir, packages, jsonFlag);
+      if (installResult === 'failed') {
+        manualSteps.push(
+          `The PostHog SDK packages didn't install. Run npx expo install ${packages.join(' ')} from your project directory.`
+        );
+      }
+      const pluginManualStep = await this.addConfigPluginAsync(projectDir, exp);
+      if (pluginManualStep) {
+        manualSteps.push(pluginManualStep);
+      }
+    }
+
+    await this.writeEnvLocalAsync(projectDir, envVars, nonInteractive, overwrite);
+    await Promise.all(
+      envVars.map(envVar =>
+        this.upsertEasEnvVarAsync(graphqlClient, projectId, envVar, nonInteractive, overwrite)
+      )
+    );
+
+    if (jsonFlag) {
+      printJsonOnlyOutput({
+        organizationConnection: {
+          id: connection.id,
+          name: connection.posthogOrganizationName,
+          region: connection.posthogRegion,
+        },
+        project: {
+          id: project.id,
+          name: project.posthogProjectName,
+          apiKey: project.posthogProjectToken,
+          host: project.posthogHost,
+        },
+        features,
+        dashboardUrl: getPostHogProjectDashboardUrl(project),
+        environmentVariables: envVars.map(v => v.name),
+        manualSteps,
+      });
+      return;
+    }
+
+    if (!anyFeatureSelected) {
+      Log.addNewLineIfNone();
+      Log.log(chalk.green('PostHog project created.'));
+      Log.newLine();
+      Log.log(
+        `${chalk.bold('Dashboard')}: ${link(getPostHogProjectDashboardUrl(project), { dim: false })}`
+      );
+      Log.newLine();
+      Log.warn(
+        'No PostHog features selected, so no SDK, config plugin, or environment variables were set up. Re-run to add analytics, session replay, or error tracking.'
+      );
+      return;
+    }
+
+    this.printNextSteps(project, features, manualSteps);
+  }
+
+  private async resolveFeaturesAsync(
+    flags: { 'session-replay'?: boolean; 'error-tracking'?: boolean },
+    cliApiKey: string | undefined,
+    nonInteractive: boolean
+  ): Promise<Features> {
+    const sessionReplayFlag = flags['session-replay'];
+    const errorTrackingFlag = flags['error-tracking'];
+    const hasCliApiKey = !!cliApiKey;
+
+    if (nonInteractive) {
+      const errorTracking = errorTrackingFlag ?? hasCliApiKey;
+      if (errorTrackingFlag === undefined && !hasCliApiKey) {
+        Log.warn(
+          'Skipping error tracking (source maps) — it needs a personal API key. Re-run interactively, or pass --posthog-cli-api-key to enable it non-interactively.'
+        );
+      }
+      return { analytics: true, sessionReplay: sessionReplayFlag ?? true, errorTracking };
+    }
+
+    if (sessionReplayFlag !== undefined || errorTrackingFlag !== undefined) {
+      return {
+        analytics: true,
+        sessionReplay: sessionReplayFlag ?? true,
+        errorTracking: errorTrackingFlag ?? true,
+      };
+    }
+
+    const { features } = await promptAsync({
+      type: 'multiselect',
+      name: 'features',
+      message: 'PostHog features to set up',
+      choices: [
+        { title: 'Analytics', value: 'analytics', selected: true },
+        { title: 'Session replay', value: 'session-replay', selected: true },
+        {
+          title: 'Error tracking (source maps) — requires a personal API key',
+          value: 'error-tracking',
+          selected: true,
+        },
+      ] satisfies Choice[],
+      instructions: false,
+      min: 0,
+    });
+    const selected = new Set<string>(features as string[]);
+    return {
+      analytics: selected.has('analytics'),
+      sessionReplay: selected.has('session-replay'),
+      errorTracking: selected.has('error-tracking'),
+    };
+  }
+
+  private async resolveCliApiKeyAsync(
+    cliApiKey: string | undefined,
+    host: string
+  ): Promise<string> {
+    if (cliApiKey) {
+      return cliApiKey;
+    }
+    const settingsUrl = `${host.replace(/\/$/, '')}${PERSONAL_API_KEY_SETTINGS_PATH}`;
+    const { apiKey } = await promptAsync({
+      type: 'password',
+      name: 'apiKey',
+      message: `Paste a PostHog personal API key for source-map uploads.\nCreate one at ${settingsUrl} using the "Source map upload" preset.`,
+      validate: (value: string) => (value.trim() ? true : 'Personal API key cannot be empty'),
+    });
+    return apiKey.trim();
+  }
+
+  private async resolveRegionAsync(
+    flagValue: string | undefined,
+    nonInteractive: boolean
+  ): Promise<PostHogRegion> {
+    const flagRegion = POSTHOG_REGIONS.find(r => r.value === flagValue);
+    if (flagRegion) {
+      return flagRegion.value;
+    }
+    if (nonInteractive) {
+      throw new Error(
+        'A PostHog region is required in non-interactive mode. Pass --region US or --region EU. The region sets data residency and cannot be changed after connecting.'
+      );
+    }
+    return await selectAsync('Select a PostHog region', POSTHOG_REGIONS);
+  }
+
+  private async installSdkPackagesAsync(
+    projectDir: string,
+    packages: string[],
+    jsonFlag: boolean
+  ): Promise<'installed' | 'failed'> {
+    const spinner = jsonFlag ? null : ora('Installing the PostHog SDK packages').start();
+    try {
+      await spawnAsync('npx', ['expo', 'install', ...packages], { cwd: projectDir });
+      spinner?.succeed('Installed the PostHog SDK packages');
+      return 'installed';
+    } catch (error) {
+      const output = getSpawnErrorOutput(error);
+      Log.debug(output || error);
+      if (output.includes('Cannot automatically write to dynamic config')) {
+        spinner?.succeed('Installed the PostHog SDK packages');
+        return 'installed';
+      }
+      spinner?.fail('Failed to install the PostHog SDK packages');
+      return 'failed';
+    }
+  }
+
+  private async addConfigPluginAsync(projectDir: string, exp: ExpoConfig): Promise<string | null> {
+    const plugins = exp.plugins ?? [];
+    const alreadyAdded = plugins.some(p => (Array.isArray(p) ? p[0] : p) === CONFIG_PLUGIN);
+    if (alreadyAdded) {
+      Log.withTick(`Config plugin ${chalk.bold(CONFIG_PLUGIN)} is already configured`);
+      return null;
+    }
+
+    const modification = await createOrModifyExpoConfigAsync(
+      projectDir,
+      { plugins: [...plugins, CONFIG_PLUGIN] },
+      { skipSDKVersionRequirement: true }
+    );
+    if (modification.type === 'success') {
+      Log.withTick(`Added the ${chalk.bold(CONFIG_PLUGIN)} config plugin`);
+      return null;
+    }
+    if (modification.type === 'warn') {
+      return `${modification.message} Add ${JSON.stringify(CONFIG_PLUGIN)} to the "plugins" array in your app config.`;
+    }
+    return `Add ${JSON.stringify(CONFIG_PLUGIN)} to the "plugins" array in your app config.`;
+  }
+
+  private async writeEnvLocalAsync(
+    projectDir: string,
+    envVars: EnvVar[],
+    nonInteractive: boolean,
+    overwrite: boolean
+  ): Promise<void> {
+    if (envVars.length === 0) {
+      return;
+    }
+    const envPath = path.join(projectDir, '.env.local');
+    let rawContent = '';
+    if (await fs.pathExists(envPath)) {
+      rawContent = await fs.readFile(envPath, 'utf8');
+      const existing = dotenv.parse(rawContent);
+      const conflicts = envVars.filter(v => existing[v.name] !== undefined);
+      if (conflicts.length > 0 && !overwrite) {
+        if (nonInteractive) {
+          Log.warn(
+            `.env.local already defines ${conflicts
+              .map(v => v.name)
+              .join(', ')}; skipped (pass --overwrite to replace).`
+          );
+          return;
+        }
+        const confirmed = await confirmAsync({
+          message: `.env.local already defines ${conflicts
+            .map(v => v.name)
+            .join(', ')}. Overwrite with the PostHog values?`,
+        });
+        if (!confirmed) {
+          Log.warn(`Skipped updating ${chalk.bold('.env.local')}.`);
+          return;
+        }
+      }
+    }
+
+    const updatedContent = this.mergeEnvContent(
+      rawContent,
+      Object.fromEntries(envVars.map(v => [v.name, v.value]))
+    );
+    await fs.writeFile(envPath, updatedContent);
+    Log.withTick(`Wrote PostHog config to ${chalk.bold('.env.local')}`);
+  }
+
+  private mergeEnvContent(rawContent: string, newVars: Record<string, string>): string {
+    let content = rawContent;
+    const keysToAdd: Record<string, string> = { ...newVars };
+    for (const [key, value] of Object.entries(newVars)) {
+      const regex = new RegExp(`^${key}=.*$`, 'm');
+      if (regex.test(content)) {
+        content = content.replace(regex, () => `${key}=${value}`);
+        delete keysToAdd[key];
+      }
+    }
+    const remaining = Object.entries(keysToAdd);
+    if (remaining.length > 0) {
+      if (content.length > 0 && !content.endsWith('\n')) {
+        content += '\n';
+      }
+      for (const [key, value] of remaining) {
+        content += `${key}=${value}\n`;
+      }
+    }
+    return content;
+  }
+
+  private async upsertEasEnvVarAsync(
+    graphqlClient: ExpoGraphqlClient,
+    projectId: string,
+    envVar: EnvVar,
+    nonInteractive: boolean,
+    overwrite: boolean
+  ): Promise<void> {
+    const existingVariables = await EnvironmentVariablesQuery.byAppIdAsync(graphqlClient, {
+      appId: projectId,
+      filterNames: [envVar.name],
+    });
+    const existingProjectVariable = existingVariables.find(
+      variable => variable.scope === EnvironmentVariableScope.Project
+    );
+
+    if (existingProjectVariable) {
+      const shouldOverwrite =
+        overwrite ||
+        (!nonInteractive &&
+          (await confirmAsync({
+            message: `EAS already has an ${envVar.name} environment variable for this project. Overwrite it?`,
+          })));
+      if (!shouldOverwrite) {
+        Log.warn(
+          `Skipped updating EAS environment variable ${chalk.bold(envVar.name)}${
+            nonInteractive ? ' (pass --overwrite to replace it)' : ''
+          }.`
+        );
+        return;
+      }
+      await EnvironmentVariableMutation.updateAsync(graphqlClient, {
+        id: existingProjectVariable.id,
+        name: envVar.name,
+        value: envVar.value,
+        environments: EAS_POSTHOG_ENVIRONMENTS,
+        visibility: envVar.visibility,
+        type: EnvironmentSecretType.String,
+      });
+      Log.withTick(`Updated EAS environment variable ${chalk.bold(envVar.name)} for builds`);
+      return;
+    }
+
+    await EnvironmentVariableMutation.createForAppAsync(
+      graphqlClient,
+      {
+        name: envVar.name,
+        value: envVar.value,
+        environments: EAS_POSTHOG_ENVIRONMENTS,
+        visibility: envVar.visibility,
+        type: EnvironmentSecretType.String,
+      },
+      projectId
+    );
+    Log.withTick(`Created EAS environment variable ${chalk.bold(envVar.name)} for builds`);
+  }
+
+  private printNextSteps(
+    project: PostHogProjectData,
+    features: Features,
+    manualSteps: string[]
+  ): void {
+    Log.addNewLineIfNone();
+    Log.log(chalk.green('PostHog is connected!'));
+    Log.newLine();
+    Log.log(
+      `${chalk.bold('Dashboard')}: ${link(getPostHogProjectDashboardUrl(project), { dim: false })}`
+    );
+    Log.newLine();
+    Log.log('Next steps:');
+    const steps: string[] = [
+      `Wrap your app in ${chalk.cyan('<PostHogProvider>')} following our guide (${chalk.cyan('https://docs.expo.dev/guides/using-posthog')}).`,
+    ];
+    if (features.sessionReplay) {
+      steps.push(
+        `Enable session replay in the provider options (the ${chalk.bold(SESSION_REPLAY_PACKAGE)} package is installed).`
+      );
+    }
+    if (features.errorTracking) {
+      steps.push(
+        `Error-tracking source maps: your ${chalk.bold('POSTHOG_CLI_*')} env vars are set. Wrap ${chalk.bold('metro.config.js')} with ${chalk.cyan('getPostHogExpoConfig')} (see ${chalk.cyan('https://docs.expo.dev/guides/using-posthog#source-maps')}); uploads then run automatically on EAS Build, and via ${chalk.cyan('posthog-cli hermes upload')} for EAS Update.`
+      );
+    }
+    steps.forEach((step, index) => {
+      Log.log(`  ${index + 1}. ${step}`);
+    });
+
+    if (manualSteps.length > 0) {
+      Log.newLine();
+      Log.warn('Finish setup manually:');
+      manualSteps.forEach(step => {
+        Log.warn(`  • ${step}`);
+      });
+    }
+  }
+}

packages/eas-cli/src/commands/integrations/posthog/dashboard.ts

@@ -0,0 +1,80 @@
+import openBrowserAsync from 'better-opn';
+
+import EasCommand from '../../../commandUtils/EasCommand';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../../commandUtils/flags';
+import { getPostHogProjectDashboardUrl, logNoPostHogProject } from '../../../commandUtils/posthog';
+import { PostHogQuery } from '../../../graphql/queries/PostHogQuery';
+import Log from '../../../log';
+import { ora } from '../../../ora';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+
+export default class IntegrationsPostHogDashboard extends EasCommand {
+  static override description = 'open the PostHog dashboard for the linked PostHog project';
+
+  static override flags = {
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectConfig,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(IntegrationsPostHogDashboard);
+    const { json: jsonFlag, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+    if (jsonFlag) {
+      enableJsonOutput();
+    }
+
+    const {
+      privateProjectConfig: { projectId, exp },
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(IntegrationsPostHogDashboard, {
+      nonInteractive,
+      withServerSideEnvironment: null,
+    });
+
+    const posthogProject = await PostHogQuery.getPostHogProjectByAppIdAsync(
+      graphqlClient,
+      projectId
+    );
+
+    if (!posthogProject) {
+      if (jsonFlag) {
+        printJsonOnlyOutput({ dashboardUrl: null });
+      } else {
+        logNoPostHogProject(exp.slug);
+      }
+      return;
+    }
+
+    const dashboardUrl = getPostHogProjectDashboardUrl(posthogProject);
+
+    if (jsonFlag) {
+      printJsonOnlyOutput({ dashboardUrl });
+      return;
+    }
+
+    if (nonInteractive) {
+      Log.log(dashboardUrl);
+      return;
+    }
+
+    const failedMessage = `Unable to open a web browser. PostHog dashboard is available at: ${dashboardUrl}`;
+    const spinner = ora(`Opening ${dashboardUrl}`).start();
+    try {
+      const opened = await openBrowserAsync(dashboardUrl);
+      if (opened) {
+        spinner.succeed(`Opened ${dashboardUrl}`);
+      } else {
+        spinner.fail(failedMessage);
+      }
+    } catch (error) {
+      spinner.fail(failedMessage);
+      throw error;
+    }
+  }
+}

packages/eas-cli/src/commands/integrations/posthog/disconnect.ts

@@ -0,0 +1,100 @@
+import { Flags } from '@oclif/core';
+import chalk from 'chalk';
+
+import EasCommand from '../../../commandUtils/EasCommand';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../../commandUtils/flags';
+import { formatPostHogProject, logNoPostHogProject } from '../../../commandUtils/posthog';
+import { PostHogMutation } from '../../../graphql/mutations/PostHogMutation';
+import { PostHogQuery } from '../../../graphql/queries/PostHogQuery';
+import Log from '../../../log';
+import { ora } from '../../../ora';
+import { confirmAsync } from '../../../prompts';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+
+export default class IntegrationsPostHogDisconnect extends EasCommand {
+  static override description =
+    'remove the PostHog project link for the current Expo app from EAS servers';
+
+  static override flags = {
+    ...EasNonInteractiveAndJsonFlags,
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip confirmation prompt',
+      default: false,
+    }),
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectConfig,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(IntegrationsPostHogDisconnect);
+    const { yes } = flags;
+    const { json: jsonFlag, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+    if (jsonFlag) {
+      enableJsonOutput();
+    }
+
+    const {
+      privateProjectConfig: { projectId, exp },
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(IntegrationsPostHogDisconnect, {
+      nonInteractive,
+      withServerSideEnvironment: null,
+    });
+
+    const posthogProject = await PostHogQuery.getPostHogProjectByAppIdAsync(
+      graphqlClient,
+      projectId
+    );
+
+    if (!posthogProject) {
+      if (jsonFlag) {
+        printJsonOnlyOutput({ id: null });
+      } else {
+        logNoPostHogProject(exp.slug);
+      }
+      return;
+    }
+
+    if (!jsonFlag) {
+      Log.addNewLineIfNone();
+      Log.log(formatPostHogProject(posthogProject));
+      Log.newLine();
+    }
+
+    if (!nonInteractive && !yes) {
+      const confirmed = await confirmAsync({
+        message:
+          'Remove this PostHog project link from EAS servers? This does not delete the project on PostHog.',
+      });
+      if (!confirmed) {
+        Log.warn('Canceled removal of the PostHog project link.');
+        return;
+      }
+    } else if (!jsonFlag) {
+      Log.warn(
+        'Removing the PostHog project link from EAS servers. This does not delete the project on PostHog.'
+      );
+    }
+
+    const spinner = jsonFlag ? null : ora('Removing PostHog project link').start();
+    try {
+      await PostHogMutation.deletePostHogProjectAsync(graphqlClient, posthogProject.id);
+      spinner?.succeed(
+        `Removed PostHog project ${chalk.bold(posthogProject.posthogProjectName)} from EAS servers`
+      );
+    } catch (error) {
+      spinner?.fail('Failed to remove PostHog project link');
+      throw error;
+    }
+
+    if (jsonFlag) {
+      printJsonOnlyOutput({ id: posthogProject.id, name: posthogProject.posthogProjectName });
+    }
+  }
+}

packages/eas-cli/src/commands/observe/__tests__/events.test.ts

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

packages/eas-cli/src/commands/observe/__tests__/logs.test.ts

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

packages/eas-cli/src/commands/observe/__tests__/metrics-summary.test.ts

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

packages/eas-cli/src/commands/observe/__tests__/metrics.test.ts

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

packages/eas-cli/src/commands/observe/__tests__/versions.test.ts

@@ -171,6 +171,7 @@ describe(ObserveVersions, () => {
             firstSeenAt: '2025-06-01T00:00:00.000Z',
             eventCount: 100,
             uniqueUserCount: 50,
+            lastSeenUserCount: 12,
             buildNumbers: [],
             updates: [],
             metrics: [],

packages/eas-cli/src/commands/observe/events.ts

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

packages/eas-cli/src/commands/observe/logs.ts

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

packages/eas-cli/src/commands/observe/metrics-summary.ts

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

packages/eas-cli/src/commands/observe/metrics.ts

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