[eas-cli] Add simulator:simctl to set appearance and restart SpringBoard on remote iOS sessions

* [eas-cli] Add experimentation client

* [eas-cli] Document experimentation context order and override semantics

* [eas-cli] Take the account unit from the command instead of the app config

* [eas-cli] Skip experiments in CI

* [eas-cli] Make the GraphQL request timeout take effect

* [eas-cli] Document which experiment units are shared across surfaces

* [eas-cli] Test that non-timeout fetch errors pass through the timeout wrapper

* [eas-cli] Fetch the experimentation config lazily on first variant read

* [eas-cli] Cap the actor lookup in the experimentation context field

.changeset/experimentation-client.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': minor
+---
+
+Add experimentation client.

.changeset/free-tier-limit-agent-guidance-experiment.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': minor
+---
+
+Add a Free plan build limit guidance experiment for coding agents to `eas build`.

.changeset/serve-sim-pr-4544.md

@@ -0,0 +1,5 @@
+---
+'@expo/build-tools': minor
+---
+
+Let serve-sim boot, install and launch agent-device iOS sessions with the local-egress guard.

.changeset/simulator-simctl.md

@@ -0,0 +1,5 @@
+---
+'eas-cli': minor
+---
+
+Add `eas simulator:simctl` to set the appearance of a remote iOS simulator session and restart its SpringBoard.

.github/workflows/test-graphql.yml

@@ -22,4 +22,3 @@ jobs:
         uses: ./.github/actions/setup-mise
       - run: yarn install --immutable
       - run: yarn verify-graphql-code
-        working-directory: packages/eas-cli

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 This is the log of notable changes to EAS CLI and related packages.
 
+## [25.1.1](https://github.com/expo/eas-cli/releases/tag/v25.1.1) - 2026-10-16
+
+### 🐛 Bug fixes
+
+- [build-tools] Call www only through the device run session worker API in device run session jobs, and remove their GraphQL fallbacks. ([#4638](https://github.com/expo/eas-cli/pull/4638) by [@szdziedzic](https://github.com/szdziedzic))
+
+## [25.1.0](https://github.com/expo/eas-cli/releases/tag/v25.1.0) - 2026-10-16
+
+### 🎉 New features
+
+- [eas-cli] Show EAS Simulator minutes in `eas account:usage`. ([#4583](https://github.com/expo/eas-cli/pull/4583) by [@LipLoody](https://github.com/LipLoody))
+- [build-tools] Pass the `cors_origins` session input to serve-sim and expo-device-hub as `--cors-origin` origins, so a third party page can call the preview host API, for example with `@expo/hub-client`. ([#4657](https://github.com/expo/eas-cli/pull/4657) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- [build-tools] Pass the `frame_ancestors` session input to serve-sim and expo-device-hub as `--frame-ancestor` origins, so a third party can embed the preview host. ([#4655](https://github.com/expo/eas-cli/pull/4655) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- [eas-cli] Add `--cors-origin` to `eas simulator:start`, so a third party page can call the simulator preview API, for example with `@expo/hub-client`. ([#4658](https://github.com/expo/eas-cli/pull/4658) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- [eas-cli] Add `--frame-ancestor` to `eas simulator:start`, so a third party site can embed the simulator preview, and print the embeddable preview URL. ([#4656](https://github.com/expo/eas-cli/pull/4656) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+
+### 🐛 Bug fixes
+
+- [build-tools] Allocate 4 GiB of guest RAM to Android emulators in EAS Simulator sessions. ([#4640](https://github.com/expo/eas-cli/pull/4640) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Retry transient Google Play API failures with exponential backoff while keeping uncertain commit results explicit. ([#4629](https://github.com/expo/eas-cli/pull/4629) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Retry Google Play edit commits when an uploaded Android App Bundle is still processing, with bounded retries and progress warnings. ([#4651](https://github.com/expo/eas-cli/pull/4651) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Report Google Play error responses to Sentry so unexplained submission failures can be classified. ([#4652](https://github.com/expo/eas-cli/pull/4652) by [@sjchmiela](https://github.com/sjchmiela))
+
 ## [25.0.0](https://github.com/expo/eas-cli/releases/tag/v25.0.0) - 2026-10-15
 
 ### 🛠 Breaking changes

cli-versions.json

@@ -1,4 +1,4 @@
 {
-  "STAGING": "24.14.0",
-  "PRODUCTION": "24.14.0"
+  "STAGING": "25.1.1",
+  "PRODUCTION": "25.1.1"
 }

lerna.json

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

package.json

@@ -7,6 +7,7 @@
   "scripts": {
     "build": "lerna run build",
     "typecheck": "lerna run typecheck",
+    "verify-graphql-code": "lerna run verify-graphql-code --concurrency 1",
     "start": "lerna run watch --stream --parallel",
     "start-allow-unused": "lerna run watch-allow-unused --stream --parallel",
     "watch": "yarn start",

packages/build-tools/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @expo/build-tools
 
+## 25.1.1
+
+### Patch Changes
+
+- Call www only through the device run session worker API in device run session jobs, and remove their GraphQL fallbacks. ([#4638](https://github.com/expo/eas-cli/pull/4638) by [@szdziedzic](https://github.com/szdziedzic))
+
+## 25.1.0
+
+### Minor Changes
+
+- Pass the `cors_origins` session input to serve-sim and expo-device-hub as `--cors-origin` origins, so a third party page can call the preview host API, for example with `@expo/hub-client`. ([#4657](https://github.com/expo/eas-cli/pull/4657) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- Pass the `frame_ancestors` session input to serve-sim and expo-device-hub as `--frame-ancestor` origins, so a third party can embed the preview host. ([#4655](https://github.com/expo/eas-cli/pull/4655) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+
+### Patch Changes
+
+- Allocate 4 GiB of guest RAM to Android emulators in EAS Simulator sessions. ([#4640](https://github.com/expo/eas-cli/pull/4640) by [@gwdp](https://github.com/gwdp))
+- Retry transient Google Play API failures with exponential backoff while keeping uncertain commit results explicit. ([#4629](https://github.com/expo/eas-cli/pull/4629) by [@sjchmiela](https://github.com/sjchmiela))
+- Retry Google Play edit commits when an uploaded Android App Bundle is still processing, with bounded retries and progress warnings. ([#4651](https://github.com/expo/eas-cli/pull/4651) by [@sjchmiela](https://github.com/sjchmiela))
+- Report Google Play error responses to Sentry so unexplained submission failures can be classified. ([#4652](https://github.com/expo/eas-cli/pull/4652) by [@sjchmiela](https://github.com/sjchmiela))
+
 ## 25.0.0
 
 ### Minor Changes

packages/build-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/build-tools",
-  "version": "25.0.0",
+  "version": "25.1.1",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",
@@ -36,22 +36,23 @@
     "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\"",
     "gql": "gql.tada generate-schema ${API_SERVER_URL:-https://api.expo.dev}/graphql --output ./schema.graphql && gql.tada generate-output",
     "gql:local": "API_SERVER_URL=http://api.expo.test yarn gql",
+    "verify-graphql-code": "./scripts/verify-graphql.sh",
     "test": "yarn jest-unit"
   },
   "dependencies": {
     "@expo/config": "55.0.10",
     "@expo/config-plugins": "55.0.7",
-    "@expo/downloader": "25.0.0",
-    "@expo/eas-build-job": "25.0.0",
+    "@expo/downloader": "25.1.1",
+    "@expo/eas-build-job": "25.1.1",
     "@expo/env": "^0.4.0",
-    "@expo/logger": "25.0.0",
+    "@expo/logger": "25.1.1",
     "@expo/package-manager": "1.9.10",
     "@expo/plist": "^0.3.5",
     "@expo/results": "^1.0.0",
     "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "25.0.0",
-    "@expo/template-file": "25.0.0",
-    "@expo/turtle-spawn": "25.0.0",
+    "@expo/steps": "25.1.1",
+    "@expo/template-file": "25.1.1",
+    "@expo/turtle-spawn": "25.1.1",
     "@expo/xcpretty": "^4.3.1",
     "@ngrok/ngrok": "1.7.0",
     "@sentry/node": "7.77.0",

packages/build-tools/scripts/verify-graphql.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -eox pipefail
+
+# Generated GraphQL files are untracked, so always regenerate and check compatibility.
+yarn gql
+yarn run -T lerna run build --scope @expo/build-tools --include-dependencies

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

@@ -108,7 +108,11 @@ describe.each([
   ['Appium', createStartAppiumRemoteSessionBuildFunction],
   ['Agent Device', createStartAgentDeviceSessionBuildFunction],
 ] as const)('%s host ownership', (name, createFunction) => {
-  async function runAsync(publicPreview?: boolean) {
+  async function runAsync(
+    publicPreview?: boolean,
+    frameAncestors?: string[],
+    corsOrigins?: string[]
+  ) {
     const fn = createFunction({} as CustomBuildContext);
     await fn.fn!(
       {
@@ -118,7 +122,11 @@ describe.each([
       {
         // Inputs a step does not get default to undefined, like in a real step call.
         inputs: new Proxy(
-          { public_preview: { value: publicPreview } } as Record<string, { value: unknown }>,
+          {
+            public_preview: { value: publicPreview },
+            frame_ancestors: { value: frameAncestors },
+            cors_origins: { value: corsOrigins },
+          } as Record<string, { value: unknown }>,
           {
             get: (target, id: string) => target[id] ?? { value: undefined },
           }
@@ -179,6 +187,34 @@ describe.each([
     );
   });
 
+  it('maps frame_ancestors to the host and defaults to none', async () => {
+    await runAsync(undefined, ['https://embed.example.test']);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ frameAncestors: ['https://embed.example.test'] })
+    );
+    jest.mocked(startDeviceSessionHostAsync).mockClear();
+    await runAsync();
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ frameAncestors: [] })
+    );
+  });
+
+  it('maps cors_origins to the host and defaults to none', async () => {
+    await runAsync(undefined, undefined, ['https://app.example.test']);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+    jest.mocked(startDeviceSessionHostAsync).mockClear();
+    await runAsync();
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ corsOrigins: [] })
+    );
+  });
+
   it('stops automation while recording finalization or upload is pending', async () => {
     let release!: () => void;
     let stopped!: () => void;

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

@@ -14,6 +14,12 @@ import {
   registerLocalEgressResources,
   stopLocalEgressResourcesAsync,
 } from '../../utils/localEgress';
+import {
+  reportLocalEgressGuardCoverageAsync,
+  resolveLocalEgressServeSimBootEnvironmentAsync,
+  startLocalEgressGuardRelayAsync,
+  verifyLocalEgressGuardAsync,
+} from '../../utils/localEgressGuard';
 import {
   uploadRemoteSessionConfigAsync,
   waitForDeviceRunSessionStoppedAsync,
@@ -51,6 +57,13 @@ jest.mock('../../utils/localEgress', () => ({
   readLocalEgressHandoffAsync: jest.fn(),
   monitorLocalEgressAsync: jest.fn(),
 }));
+jest.mock('../../utils/localEgressGuard', () => ({
+  ...jest.requireActual('../../utils/localEgressGuard'),
+  resolveLocalEgressServeSimBootEnvironmentAsync: jest.fn(),
+  startLocalEgressGuardRelayAsync: jest.fn(),
+  reportLocalEgressGuardCoverageAsync: jest.fn(),
+  verifyLocalEgressGuardAsync: jest.fn(),
+}));
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
   getDeviceRunSessionIdOrThrow: () => 'session-id',
@@ -126,9 +139,20 @@ describe.each(controllers)('%s local egress', (_name, createFunction, controller
     jest.mocked(isProcessDescendantOfAsync).mockResolvedValue(true);
     jest
       .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
-      .mockResolvedValue([{ udid: 'sim' }] as never);
+      .mockResolvedValue([{ udid: 'sim', name: 'iPhone 17' }] as never);
+    jest.mocked(IosSimulatorUtils.resolveUdidAsync).mockResolvedValue('sim' as never);
     jest.mocked(turtleFetch).mockResolvedValue({ ok: true } as never);
     jest.mocked(readLocalEgressHandoffAsync).mockResolvedValue(handoff);
+    jest
+      .mocked(resolveLocalEgressServeSimBootEnvironmentAsync)
+      .mockImplementation(async () =>
+        (await readLocalEgressHandoffAsync())
+          ? { SERVE_SIM_ADDITIONAL_DYLIBS: '/test/egress-guard.dylib' }
+          : null
+      );
+    jest.mocked(startLocalEgressGuardRelayAsync).mockResolvedValue(undefined);
+    jest.mocked(reportLocalEgressGuardCoverageAsync).mockResolvedValue(null);
+    jest.mocked(verifyLocalEgressGuardAsync).mockResolvedValue(undefined);
     jest.mocked(monitorLocalEgressAsync).mockResolvedValue(undefined);
     openPreview.mockResolvedValue({
       previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',

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

@@ -70,7 +70,7 @@ const mockEventCollectionStopAsync = jest.fn();
 type CaptureInputs = Parameters<typeof runAgentDeviceRemoteSessionAsync>[1]['capture'];
 const NO_CAPTURE: CaptureInputs = { networkCapture: false, networkCaptureFields: [] };
 
-/** Runs the session for a device that is already booted, with the app (if any) launched. */
+/** Runs an Android session that is ready, or an iOS session with no application preparation. */
 async function runAsync(
   logger: { info: jest.Mock; warn: jest.Mock; child: jest.Mock },
   runtimePlatform: BuildRuntimePlatform,
@@ -94,7 +94,10 @@ async function runAsync(
     disableShare,
     privatePreviewUrl,
     tasks: createStartupTasks(logger as never),
-    device: { booted: Promise.resolve(), ready: Promise.resolve() },
+    device:
+      runtimePlatform === BuildRuntimePlatform.DARWIN
+        ? { iosSimulatorUdid: 'selected-udid', application: Promise.resolve() }
+        : { booted: Promise.resolve(), ready: Promise.resolve() },
   });
 }
 
@@ -124,13 +127,23 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
       subdomainId: 'agent-device-abc',
       stopAsync: mockTunnelStopAsync,
     });
-    jest.mocked(startDeviceSessionHostAsync).mockResolvedValue({
+    const host = {
       openPreviewAsync: jest.fn().mockResolvedValue({
         previewPageUrl: 'https://expo.dev/simulator-preview/preview-id',
         apiUrl: 'https://web-preview.tunnel.example.com',
         closeAsync: jest.fn(),
       }),
       finishAsync: mockPreviewStopAsync,
+    };
+    jest.mocked(startDeviceSessionHostAsync).mockImplementation(async (_ctx, options) => {
+      try {
+        await options.application;
+        options.signal?.throwIfAborted();
+      } catch (error) {
+        await mockPreviewStopAsync();
+        throw error;
+      }
+      return host;
     });
     jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
@@ -150,7 +163,7 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
 
     expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
       ctx,
-      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX })
+      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX, timeoutMs: 60_000 })
     );
     expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -289,14 +302,14 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
   });
 
   describe('runAgentDeviceRemoteSessionAsync with a device that is still starting', () => {
-    function deferred(): {
-      promise: Promise<void>;
-      resolve: () => void;
+    function deferred<T = void>(): {
+      promise: Promise<T>;
+      resolve: (value: T) => void;
       reject: (e: Error) => void;
     } {
-      let resolve!: () => void;
+      let resolve!: (value: T) => void;
       let reject!: (e: Error) => void;
-      const promise = new Promise<void>((res, rej) => {
+      const promise = new Promise<T>((res, rej) => {
         resolve = res;
         reject = rej;
       });
@@ -304,18 +317,26 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
       return { promise, resolve, reject };
     }
 
-    type Device = { booted: Promise<unknown>; ready: Promise<unknown> };
-    function startSession(device: Device | ((tasks: StartupTasks) => Device)) {
+    type Device = Parameters<typeof runAgentDeviceRemoteSessionAsync>[1]['device'];
+    function startSession(
+      device: Device | ((tasks: StartupTasks) => Device),
+      signal?: AbortSignal
+    ) {
       const logger = {
         info: jest.fn(),
         warn: jest.fn(),
         child: jest.fn().mockReturnThis(),
       } as never;
-      const tasks = createStartupTasks(logger);
+      const tasks = createStartupTasks(logger, signal);
+      const sessionDevice = typeof device === 'function' ? device(tasks) : device;
       return runAgentDeviceRemoteSessionAsync(ctx, {
         env: {},
         logger,
-        runtimePlatform: BuildRuntimePlatform.DARWIN,
+        signal,
+        runtimePlatform:
+          'iosSimulatorUdid' in sessionDevice
+            ? BuildRuntimePlatform.DARWIN
+            : BuildRuntimePlatform.LINUX,
         sessionEnv: {
           deviceRunSessionId: 'device-run-session-id',
           ngrokTunnelDomain: 'tunnel.example.com',
@@ -326,7 +347,7 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
         maxDurationSeconds: undefined,
         capture: NO_CAPTURE,
         tasks,
-        device: typeof device === 'function' ? device(tasks) : device,
+        device: sessionDevice,
       });
     }
 
@@ -336,7 +357,31 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
       }
     }
 
-    it('starts the daemon during the boot and the session host after it', async () => {
+    it('aborts parallel startup before host failure cleanup finishes', async () => {
+      const failure = new Error('guard refused startup');
+      const cleanup = deferred();
+      const notified = deferred();
+      let startupTasks!: StartupTasks;
+      jest.mocked(startDeviceSessionHostAsync).mockImplementation(async (_ctx, options) => {
+        options.onStartupError?.(failure);
+        notified.resolve();
+        await cleanup.promise;
+        throw failure;
+      });
+      const session = startSession(tasks => {
+        startupTasks = tasks;
+        return { iosSimulatorUdid: 'selected-udid' };
+      });
+      const rejected = expect(session).rejects.toBe(failure);
+      await notified.promise;
+      expect(startupTasks.signal.aborted).toBe(true);
+      expect(startupTasks.signal.reason).toBe(failure);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+      cleanup.resolve();
+      await rejected;
+    });
+
+    it('starts the daemon during the Android boot and the session host after it', async () => {
       const booted = deferred();
       const session = startSession({ booted: booted.promise, ready: booted.promise });
       await flushAsync();
@@ -348,10 +393,237 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
       booted.resolve();
       await session;
       expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+        ctx,
+        expect.objectContaining({
+          runtimePlatform: BuildRuntimePlatform.LINUX,
+          timeoutMs: 60_000,
+          iosSimulatorUdid: undefined,
+        })
+      );
       expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledTimes(1);
     });
 
-    it('reports the session as ready only after the app is launched', async () => {
+    it('preserves a failed download when aborting daemon installation rejects first', async () => {
+      const failure = new Error('download failed: build not found');
+      const installStarted = deferred();
+      jest.mocked(spawn).mockImplementation((async (_command, _args, options) => {
+        return await new Promise((_resolve, reject) => {
+          options!.signal!.addEventListener(
+            'abort',
+            () => {
+              const error = new Error('The operation was aborted');
+              error.name = 'AbortError';
+              reject(error);
+            },
+            { once: true }
+          );
+          installStarted.resolve();
+        });
+      }) as typeof spawn);
+      jest.mocked(startDeviceSessionHostAsync).mockImplementation(async (_ctx, { signal }) => {
+        return await new Promise((_resolve, reject) => {
+          signal!.addEventListener(
+            'abort',
+            () => {
+              setTimeout(() => reject(signal!.reason), 20);
+            },
+            { once: true }
+          );
+        });
+      });
+      const applicationReady = Promise.resolve();
+      const session = startSession(tasks => {
+        void tasks.run('build download', async () => {
+          await installStarted.promise;
+          throw failure;
+        });
+        return { iosSimulatorUdid: 'selected-udid', application: applicationReady };
+      });
+      await expect(session).rejects.toBe(failure);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('boots the host during download and releases startup only after preparation', async () => {
+      const hostReady = deferred();
+      const application = deferred<{
+        installAppPath: string;
+        launchAppIdentifier: string;
+        launchArgs: string[];
+        openUrl: string;
+      }>();
+      const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+        ctx,
+        {} as never
+      );
+      const release = jest.fn();
+      jest
+        .mocked(startDeviceSessionHostAsync)
+        .mockClear()
+        .mockImplementation(async (_ctx, options) => {
+          release(await options.application);
+          await hostReady.promise;
+          return host;
+        });
+      const applicationReady = application.promise;
+      const session = startSession({
+        iosSimulatorUdid: 'selected-udid',
+        application: applicationReady,
+      });
+      await flushAsync();
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+      expect(release).not.toHaveBeenCalled();
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+      const startup = {
+        installAppPath: '/tmp/App.app',
+        launchAppIdentifier: 'dev.example.app',
+        launchArgs: ['--flag'],
+        openUrl: 'example://screen',
+      };
+      application.resolve(startup);
+      await flushAsync();
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+        ctx,
+        expect.objectContaining({
+          application: applicationReady,
+          iosSimulatorUdid: 'selected-udid',
+          timeoutMs: 60_000,
+          signal: expect.any(AbortSignal),
+        })
+      );
+      expect(release).toHaveBeenCalledWith(startup);
+      expect(host.openPreviewAsync).not.toHaveBeenCalled();
+      hostReady.resolve();
+      await session;
+      expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledTimes(1);
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+    });
+
+    it('passes the guard boot environment with the startup installation and launch', async () => {
+      const startup = {
+        installAppPath: '/tmp/App.app',
+        launchAppIdentifier: 'dev.example.app',
+        launchArgs: ['--flag'],
+        openUrl: 'example://screen',
+      };
+      const bootEnv = {
+        SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+        SIMCTL_CHILD_EAS_EGRESS_GUARD_MODE: 'block',
+        SIMCTL_CHILD_EAS_EGRESS_GUARD_LOG: '/tmp/egress-guard.log',
+        SIMCTL_CHILD_HTTP_PROXY: 'http://127.0.0.1:8899',
+      };
+      await startSession({
+        iosSimulatorUdid: 'guarded-udid',
+        bootEnv,
+        application: Promise.resolve(startup),
+      });
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+        ctx,
+        expect.objectContaining({
+          application: expect.any(Promise),
+          bootEnv,
+          iosSimulatorUdid: 'guarded-udid',
+        })
+      );
+      const hostOptions = jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1];
+      expect(hostOptions.bootEnv).toBe(bootEnv);
+      expect(hostOptions.bootEnv).not.toHaveProperty('DYLD_INSERT_LIBRARIES');
+      expect(hostOptions.bootEnv).not.toHaveProperty('SIMCTL_CHILD_DYLD_INSERT_LIBRARIES');
+    });
+
+    it('cleans up a host returned after cancellation without configuring the device', async () => {
+      const hostReady = deferred();
+      const controller = new AbortController();
+      const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+        ctx,
+        {} as never
+      );
+      jest.mocked(startDeviceSessionHostAsync).mockImplementation(async () => {
+        await hostReady.promise;
+        return host;
+      });
+      const applicationReady = Promise.resolve();
+      const session = startSession(
+        { iosSimulatorUdid: 'selected-udid', application: applicationReady },
+        controller.signal
+      );
+      const failure = expect(session).rejects.toThrow('cancelled');
+      await flushAsync();
+      controller.abort(new Error('cancelled'));
+      hostReady.resolve();
+
+      await failure;
+      expect(host.openPreviewAsync).not.toHaveBeenCalled();
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
+      expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('drains in-flight application preparation and stops the waiting host after cancellation', async () => {
+      const controller = new AbortController();
+      const appReady = deferred();
+      const session = startSession(
+        { iosSimulatorUdid: 'selected-udid', application: appReady.promise },
+        controller.signal
+      );
+      const failure = expect(session).rejects.toThrow('cancelled');
+      await flushAsync();
+      controller.abort(new Error('cancelled'));
+      await flushAsync();
+      expect(mockPreviewStopAsync).not.toHaveBeenCalled();
+
+      appReady.resolve();
+      await failure;
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('does not report readiness when cancellation arrives during preview startup', async () => {
+      const controller = new AbortController();
+      const previewReady = deferred();
+      const host = await jest.mocked(startDeviceSessionHostAsync).getMockImplementation()!(
+        ctx,
+        {} as never
+      );
+      const preview = await host.openPreviewAsync({
+        baseDomain: 'tunnel.example.com',
+        authtoken: 'ngrok-token',
+      });
+      jest.mocked(host.openPreviewAsync).mockImplementation(async () => {
+        await previewReady.promise;
+        return preview;
+      });
+      const session = startSession(
+        { iosSimulatorUdid: 'selected-udid', application: Promise.resolve() },
+        controller.signal
+      );
+      const failure = expect(session).rejects.toThrow('cancelled');
+      await flushAsync();
+      controller.abort(new Error('cancelled'));
+      previewReady.resolve();
+
+      await failure;
+      expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
+      expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    });
+
+    it('does not start resources for an already cancelled session', async () => {
+      const controller = new AbortController();
+      controller.abort(new Error('cancelled'));
+      const applicationReady = Promise.resolve();
+
+      await expect(
+        startSession(
+          { iosSimulatorUdid: 'selected-udid', application: applicationReady },
+          controller.signal
+        )
+      ).rejects.toThrow('cancelled');
+      expect(spawn).not.toHaveBeenCalled();
+      expect(startDeviceSessionHostAsync).not.toHaveBeenCalled();
+    });
+
+    it('starts the Android host before application readiness and waits before reporting ready', async () => {
       const ready = deferred();
       const session = startSession({ booted: Promise.resolve(), ready: ready.promise });
       await flushAsync();
@@ -361,10 +633,11 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
 
       ready.resolve();
       await session;
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
       expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledTimes(1);
     });
 
-    it('stops waiting for the boot when the daemon fails', async () => {
+    it('stops waiting for the Android boot when the daemon fails', async () => {
       jest.mocked(waitForFileAsync).mockRejectedValue(new Error('no daemon credentials'));
       const neverBooted = new Promise<void>(() => {});
 
@@ -378,7 +651,7 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
       expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
     });
 
-    it('stops the session host when the app fails while the daemon install hangs', async () => {
+    it('cancels daemon installation and stops the Android host when the download fails', async () => {
       jest.mocked(spawn).mockImplementation(((
         command: string,
         args: string[],
@@ -394,21 +667,22 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
       await flushAsync();
       expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
 
-      ready.reject(new Error('simctl install failed'));
+      ready.reject(new Error('download failed'));
 
-      await expect(session).rejects.toThrow('simctl install failed');
+      await expect(session).rejects.toThrow('download failed');
       expect(mockPreviewStopAsync).toHaveBeenCalledTimes(1);
       expect(spawnDetached).not.toHaveBeenCalled();
       expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
     });
 
-    it('stops everything it started when the app install fails', async () => {
+    it('stops the Android host, daemon and tunnel when the download fails', async () => {
       const ready = deferred();
       const session = startSession({ booted: Promise.resolve(), ready: ready.promise });
       await flushAsync();
-      ready.reject(new Error('simctl install failed'));
+      expect(startDeviceSessionHostAsync).toHaveBeenCalledTimes(1);
+      ready.reject(new Error('download failed'));
 
-      await expect(session).rejects.toThrow('simctl install failed');
+      await expect(session).rejects.toThrow('download failed');
       expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
       expect(mockDaemonStopAsync).toHaveBeenCalledTimes(1);
       expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);

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

@@ -1,11 +1,20 @@
 import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
+import { UserError } from '@expo/eas-build-job';
+import spawn from '@expo/turtle-spawn';
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
 import { DeviceRunSessionWorkerApi } from '../../utils/deviceRunSessionWorkerApi';
+import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import { stopLocalEgressResourcesAsync } from '../../utils/localEgress';
+import {
+  resolveLocalEgressServeSimBootEnvironmentAsync,
+  startLocalEgressGuardRelayAsync,
+} from '../../utils/localEgressGuard';
 import { selectXcodeDeveloperDirectoryAsync } from '../../utils/remoteDeviceRunSession';
 import { downloadBuildAsync } from '../downloadBuild';
 import { installBuildAsync } from '../installBuild';
+import { readIosApplicationIdentifierAsync } from '../../utils/iosAppArtifact';
 import { launchApplicationAsync } from '../launchApplication';
 import {
   getAgentDeviceRemoteSessionEnvOrThrow,
@@ -15,17 +24,30 @@ import { createStartAgentDeviceSessionBuildFunction } from '../startAgentDeviceS
 import { startAndroidEmulatorAsync } from '../startAndroidEmulator';
 import { bootIosSimulatorAsync } from '../startIosSimulator';
 
-jest.mock('../../utils/localEgressSession', () => ({
-  withLocalEgressSession: (fn: unknown) => fn,
+jest.mock('../../utils/localEgress', () => ({
+  stopLocalEgressResourcesAsync: jest.fn().mockResolvedValue(undefined),
 }));
+jest.mock('../../utils/localEgressGuard', () => ({
+  resolveLocalEgressServeSimBootEnvironmentAsync: jest.fn(),
+  startLocalEgressGuardRelayAsync: jest.fn(),
+}));
+jest.mock('@expo/turtle-spawn');
+jest.mock('../../../utils/IosSimulatorUtils');
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
   selectXcodeDeveloperDirectoryAsync: jest.fn(),
 }));
-jest.mock('../startIosSimulator', () => ({ bootIosSimulatorAsync: jest.fn() }));
+jest.mock('../startIosSimulator', () => ({
+  ...jest.requireActual('../startIosSimulator'),
+  bootIosSimulatorAsync: jest.fn(),
+}));
 jest.mock('../startAndroidEmulator', () => ({ startAndroidEmulatorAsync: jest.fn() }));
 jest.mock('../downloadBuild', () => ({ downloadBuildAsync: jest.fn() }));
 jest.mock('../installBuild', () => ({ installBuildAsync: jest.fn() }));
+jest.mock('../../utils/iosAppArtifact', () => ({
+  ...jest.requireActual('../../utils/iosAppArtifact'),
+  readIosApplicationIdentifierAsync: jest.fn(),
+}));
 jest.mock('../launchApplication', () => ({
   ...jest.requireActual('../launchApplication'),
   launchApplicationAsync: jest.fn(),
@@ -43,7 +65,17 @@ const sessionEnv = {
   ngrokAuthtoken: 'ngrok-token',
 };
 
-type Device = { booted: Promise<unknown>; ready: Promise<unknown> };
+type Device = Parameters<typeof runAgentDeviceRemoteSessionAsync>[1]['device'];
+let deviceLaunch: unknown;
+
+function runDevicePreparationAsync(device: Device): Promise<unknown> {
+  return (
+    'iosSimulatorUdid' in device ? (device.application ?? Promise.resolve()) : device.ready
+  ).then(async launch => {
+    deviceLaunch = launch;
+    return launch;
+  });
+}
 
 function deferred<T = void>(): {
   promise: Promise<T>;
@@ -69,6 +101,7 @@ async function flushAsync(): Promise<void> {
 function runStep(
   runtimePlatform: BuildRuntimePlatform,
   inputValues: Record<string, unknown> = {},
+  signal?: AbortSignal,
   stepCtx: CustomBuildContext = ctx
 ): Promise<void> {
   const buildFunction = createStartAgentDeviceSessionBuildFunction(stepCtx);
@@ -88,6 +121,8 @@ function runStep(
       'network_capture_fields',
       'public_preview',
       'private_preview_url',
+      'frame_ancestors',
+      'cors_origins',
       'package_version',
       'max_idle_time_minutes',
       'max_duration_seconds',
@@ -101,22 +136,32 @@ function runStep(
         staticContext: { job: { secrets: { robotAccessToken: 'robot-token' } } },
       },
     } as unknown as BuildStepContext,
-    { inputs, outputs: {}, env: {}, signal: undefined } as never
+    { inputs, outputs: {}, env: {}, signal } as never
   ) as Promise<void>;
 }
 
-/** The `device` promises handed to the shared agent-device session code. */
 function sessionDevice(): Device {
   return jest.mocked(runAgentDeviceRemoteSessionAsync).mock.calls[0][1].device;
 }
 
 describe(createStartAgentDeviceSessionBuildFunction, () => {
   beforeEach(() => {
+    deviceLaunch = undefined;
     jest.clearAllMocks();
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue(null);
+    jest.mocked(startLocalEgressGuardRelayAsync).mockResolvedValue(undefined);
+    jest.mocked(IosSimulatorUtils.getDeviceAsync).mockResolvedValue({ state: 'Shutdown' } as never);
+    jest.mocked(spawn).mockResolvedValue({ stdout: '' } as never);
+    jest.mocked(IosSimulatorUtils.resolveUdidAsync).mockResolvedValue('selected-udid' as never);
+    jest
+      .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+      .mockResolvedValue([{ name: 'iPhone 17', udid: 'SELECTED-UDID' }] as never);
     jest.mocked(getAgentDeviceRemoteSessionEnvOrThrow).mockReturnValue(sessionEnv);
-    jest.mocked(runAgentDeviceRemoteSessionAsync).mockImplementation(async (_ctx, { device }) => {
-      await device.ready;
-    });
+    jest
+      .mocked(runAgentDeviceRemoteSessionAsync)
+      .mockImplementation(async (_ctx, { device, tasks }) => {
+        await tasks.untilAborted(runDevicePreparationAsync(device));
+      });
     jest.mocked(bootIosSimulatorAsync).mockResolvedValue({
       deviceIdentifier: 'iPhone 17' as never,
       udid: 'udid' as never,
@@ -132,22 +177,31 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
       .mocked(installBuildAsync)
       .mockResolvedValue({ applicationIdentifier: 'dev.example.app', activityName: '.Main' });
     jest.mocked(launchApplicationAsync).mockResolvedValue(undefined);
+    jest.mocked(readIosApplicationIdentifierAsync).mockResolvedValue('dev.example.app');
   });
 
-  it('downloads the build and starts the session while the iOS Simulator boots', async () => {
-    const boot = deferred<Awaited<ReturnType<typeof bootIosSimulatorAsync>>>();
-    jest.mocked(bootIosSimulatorAsync).mockReturnValue(boot.promise);
-
-    const step = runStep(BuildRuntimePlatform.DARWIN, {
+  it('hands guarded iOS boot to serve-sim and starts reporting before host startup', async () => {
+    const bootEnv = {
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+      SIMCTL_CHILD_EAS_EGRESS_GUARD_MODE: 'block',
+      SIMCTL_CHILD_http_proxy: 'http://127.0.0.1:8899',
+    };
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue(bootEnv);
+    await runStep(BuildRuntimePlatform.DARWIN, {
       build_id: 'build-id',
       launch_args: ['-flag'],
       open_url: 'exp://example.test',
     });
-    await flushAsync();
-
     expect(
       jest.mocked(selectXcodeDeveloperDirectoryAsync).mock.invocationCallOrder[0]
-    ).toBeLessThan(jest.mocked(bootIosSimulatorAsync).mock.invocationCallOrder[0]);
+    ).toBeLessThan(
+      jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mock.invocationCallOrder[0]
+    );
+    expect(startLocalEgressGuardRelayAsync).toHaveBeenCalledTimes(1);
+    expect(jest.mocked(startLocalEgressGuardRelayAsync).mock.invocationCallOrder[0]).toBeLessThan(
+      jest.mocked(runAgentDeviceRemoteSessionAsync).mock.invocationCallOrder[0]
+    );
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
     expect(downloadBuildAsync).toHaveBeenCalledWith(
       expect.objectContaining({
         buildId: 'build-id',
@@ -157,28 +211,45 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
       })
     );
     expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledTimes(1);
-    // The install needs the booted Simulator.
-    expect(installBuildAsync).not.toHaveBeenCalled();
-
-    boot.resolve({
-      deviceIdentifier: 'iPhone 17' as never,
-      udid: 'udid' as never,
-      displayName: '',
+    const device = sessionDevice();
+    expect(device).toEqual({
+      iosSimulatorUdid: 'SELECTED-UDID',
+      bootEnv,
+      application: expect.any(Promise),
     });
-    await step;
+    expect(spawn).not.toHaveBeenCalled();
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledWith({
+      artifactPath: '/tmp/App.app',
+      env: {},
+    });
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(deviceLaunch).toEqual({
+      installAppPath: '/tmp/App.app',
+      launchAppIdentifier: 'dev.example.app',
+      launchArgs: ['-flag'],
+      openUrl: 'exp://example.test',
+    });
+  });
 
-    expect(installBuildAsync).toHaveBeenCalledWith(
-      expect.objectContaining({ artifactPath: '/tmp/App.app' })
-    );
-    expect(launchApplicationAsync).toHaveBeenCalledWith(
-      expect.objectContaining({
-        applicationIdentifier: 'dev.example.app',
-        launchArgs: ['-flag'],
-        openUrl: 'exp://example.test',
-      })
-    );
-    expect(jest.mocked(installBuildAsync).mock.invocationCallOrder[0]).toBeLessThan(
-      jest.mocked(launchApplicationAsync).mock.invocationCallOrder[0]
+  it('shuts down only the selected guarded Booted device before host startup', async () => {
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue({
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+    });
+    jest.mocked(IosSimulatorUtils.getDeviceAsync).mockResolvedValue({ state: 'Booted' } as never);
+    await runStep(BuildRuntimePlatform.DARWIN);
+    expect(IosSimulatorUtils.getDeviceAsync).toHaveBeenCalledWith({
+      udid: 'SELECTED-UDID',
+      env: {},
+    });
+    expect(spawn).toHaveBeenCalledTimes(1);
+    expect(spawn).toHaveBeenCalledWith('xcrun', ['simctl', 'shutdown', 'SELECTED-UDID'], {
+      env: {},
+      logger: expect.any(Object),
+      signal: expect.any(AbortSignal),
+    });
+    expect(jest.mocked(spawn).mock.invocationCallOrder[0]).toBeLessThan(
+      jest.mocked(runAgentDeviceRemoteSessionAsync).mock.invocationCallOrder[0]
     );
   });
 
@@ -189,7 +260,7 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
       expoApiV2BaseUrl: 'https://api.expo.test/v2/',
     } as unknown as CustomBuildContext;
 
-    await runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id' }, sessionCtx);
+    await runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id' }, undefined, sessionCtx);
 
     expect(downloadBuildAsync).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -213,6 +284,7 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     await runStep(
       BuildRuntimePlatform.LINUX,
       { application_archive_url: 'https://example.test/app.tar.gz' },
+      undefined,
       sessionCtx
     );
     expect(downloadBuildAsync).toHaveBeenLastCalledWith(
@@ -223,7 +295,96 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     );
   });
 
-  it('waits for the download when the Simulator boots first', async () => {
+  it('fails before download or host startup when guarded device shutdown fails', async () => {
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue({
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+    });
+    jest.mocked(IosSimulatorUtils.getDeviceAsync).mockResolvedValue({ state: 'Booted' } as never);
+    jest.mocked(spawn).mockRejectedValue(new Error('shutdown failed'));
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'shutdown failed'
+    );
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+    expect(stopLocalEgressResourcesAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('provides Simulator preparation and downloaded startup options to the remote session', async () => {
+    const hostReady = deferred();
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue({
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+    });
+    jest.mocked(runAgentDeviceRemoteSessionAsync).mockImplementation(async (_ctx, { device }) => {
+      expect('iosSimulatorUdid' in device).toBe(true);
+      if (!('iosSimulatorUdid' in device)) {
+        return;
+      }
+      await hostReady.promise;
+      deviceLaunch = await device.application;
+    });
+    const step = runStep(BuildRuntimePlatform.DARWIN, {
+      device_identifier: 'iPhone 17',
+      build_id: 'build-id',
+      launch_args: ['-flag'],
+      open_url: 'exp://example.test',
+    });
+    await flushAsync();
+    expect(IosSimulatorUtils.resolveUdidAsync).toHaveBeenCalledWith({
+      deviceIdentifier: 'iPhone 17',
+      env: {},
+    });
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).toHaveBeenCalledTimes(1);
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledWith({
+      artifactPath: '/tmp/App.app',
+      env: {},
+    });
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(deviceLaunch).toBeUndefined();
+    hostReady.resolve();
+    await step;
+    expect(deviceLaunch).toEqual({
+      installAppPath: '/tmp/App.app',
+      launchAppIdentifier: 'dev.example.app',
+      launchArgs: ['-flag'],
+      openUrl: 'exp://example.test',
+    });
+  });
+
+  it('fails a guarded session before download or host startup if its boot files are missing', async () => {
+    jest
+      .mocked(resolveLocalEgressServeSimBootEnvironmentAsync)
+      .mockRejectedValue(new Error('missing bin/egress-guard-check'));
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'missing bin/egress-guard-check'
+    );
+    expect(startLocalEgressGuardRelayAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(IosSimulatorUtils.getDeviceAsync).not.toHaveBeenCalled();
+    expect(spawn).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+    expect(stopLocalEgressResourcesAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('releases guard reporting and egress resources when host startup fails', async () => {
+    jest.mocked(resolveLocalEgressServeSimBootEnvironmentAsync).mockResolvedValue({
+      SERVE_SIM_ADDITIONAL_DYLIBS: '/w/bin/egress-guard.dylib',
+    });
+    jest
+      .mocked(runAgentDeviceRemoteSessionAsync)
+      .mockRejectedValueOnce(new Error('guard check failed'));
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'guard check failed'
+    );
+    expect(startLocalEgressGuardRelayAsync).toHaveBeenCalledTimes(1);
+    expect(stopLocalEgressResourcesAsync).toHaveBeenCalledTimes(1);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+    expect(launchApplicationAsync).not.toHaveBeenCalled();
+  });
+
+  it('waits for the download before handing the app to the host', async () => {
     const download = deferred<{ artifactPath: string }>();
     jest.mocked(downloadBuildAsync).mockReturnValue(download.promise);
 
@@ -235,16 +396,21 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
 
     download.resolve({ artifactPath: '/tmp/App.app' });
     await step;
-    expect(installBuildAsync).toHaveBeenCalledTimes(1);
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledTimes(1);
+    expect(installBuildAsync).not.toHaveBeenCalled();
   });
 
-  it('makes the session ready when the device boots if there is no app', async () => {
+  it('passes the selected Simulator to the host even when there is no app', async () => {
     await runStep(BuildRuntimePlatform.DARWIN);
 
     expect(downloadBuildAsync).not.toHaveBeenCalled();
     expect(installBuildAsync).not.toHaveBeenCalled();
     expect(launchApplicationAsync).not.toHaveBeenCalled();
-    await expect(sessionDevice().ready).resolves.toBeUndefined();
+    expect(sessionDevice()).toEqual({
+      iosSimulatorUdid: 'SELECTED-UDID',
+      bootEnv: undefined,
+      application: undefined,
+    });
   });
 
   it('boots the Android Emulator with the device inputs', async () => {
@@ -276,23 +442,10 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
   });
 
   it('fails the session when the download fails, without an unhandled rejection', async () => {
-    const boot = deferred<Awaited<ReturnType<typeof bootIosSimulatorAsync>>>();
-    jest.mocked(bootIosSimulatorAsync).mockReturnValue(boot.promise);
     jest.mocked(downloadBuildAsync).mockRejectedValue(new Error('download failed'));
-
-    const stepFailure = expect(
-      runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })
-    ).rejects.toThrow('download failed');
-    // The download fails while the boot still runs. Nothing inside the step may leave
-    // that rejection unhandled; Jest fails the test if it does.
-    await flushAsync();
-    boot.resolve({
-      deviceIdentifier: 'iPhone 17' as never,
-      udid: 'udid' as never,
-      displayName: '',
-    });
-
-    await stepFailure;
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'download failed'
+    );
     expect(installBuildAsync).not.toHaveBeenCalled();
   });
 
@@ -321,23 +474,24 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     jest
       .mocked(runAgentDeviceRemoteSessionAsync)
       .mockImplementation(async (_ctx, { tasks, device }) => {
+        const ready = runDevicePreparationAsync(device);
         await beforeFailure?.();
         const daemon = tasks.run('agent-device daemon', async () => {
           throw new Error('daemon failed');
         });
         try {
-          await Promise.all([daemon, device.ready]);
+          await Promise.all([daemon, ready]);
         } finally {
-          await Promise.allSettled([daemon, device.ready]);
+          await Promise.allSettled([daemon, ready]);
         }
       });
   }
 
-  it('stops the download and waits for it when the boot fails', async () => {
+  it('stops the download and waits for it when Android boot fails', async () => {
     const download = mockStalledDownload();
-    jest.mocked(bootIosSimulatorAsync).mockRejectedValue(new Error('boot failed'));
+    jest.mocked(startAndroidEmulatorAsync).mockRejectedValue(new Error('boot failed'));
 
-    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+    await expect(runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id' })).rejects.toThrow(
       'boot failed'
     );
 
@@ -361,25 +515,79 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     expect(launchApplicationAsync).not.toHaveBeenCalled();
   });
 
-  it('does not launch the app when startup fails during the install', async () => {
-    const install = deferred<Awaited<ReturnType<typeof installBuildAsync>>>();
-    const installStarted = deferred();
-    jest.mocked(installBuildAsync).mockImplementation(() => {
-      installStarted.resolve();
-      return install.promise;
+  it('drains the download when host startup fails before app preparation', async () => {
+    const download = mockStalledDownload();
+    jest.mocked(runAgentDeviceRemoteSessionAsync).mockRejectedValue(new Error('host failed'));
+
+    await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
+      'host failed'
+    );
+    expect(download.aborted()).toBe(true);
+    expect(download.settled()).toBe(true);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+  });
+
+  it('does not start work for an already cancelled step', async () => {
+    const controller = new AbortController();
+    controller.abort(new Error('cancelled'));
+
+    await expect(
+      runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' }, controller.signal)
+    ).rejects.toThrow('cancelled');
+    expect(selectXcodeDeveloperDirectoryAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('cancels and drains a pending download through the external signal', async () => {
+    const controller = new AbortController();
+    const download = mockStalledDownload();
+    const step = runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' }, controller.signal);
+    const failure = expect(step).rejects.toThrow('cancelled');
+    await flushAsync();
+    controller.abort(new Error('cancelled'));
+
+    await failure;
+    expect(download.aborted()).toBe(true);
+    expect(download.settled()).toBe(true);
+    expect(installBuildAsync).not.toHaveBeenCalled();
+  });
+
+  it('does not start device or download work after cancellation during Xcode selection', async () => {
+    const controller = new AbortController();
+    const selected = deferred();
+    jest.mocked(selectXcodeDeveloperDirectoryAsync).mockReturnValue(selected.promise);
+    const step = runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' }, controller.signal);
+    const failure = expect(step).rejects.toThrow('cancelled');
+    await flushAsync();
+    controller.abort(new Error('cancelled'));
+    selected.resolve();
+
+    await failure;
+    expect(IosSimulatorUtils.resolveUdidAsync).not.toHaveBeenCalled();
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('drains app preparation when the daemon fails', async () => {
+    const metadata = deferred<string>();
+    const metadataStarted = deferred();
+    jest.mocked(readIosApplicationIdentifierAsync).mockImplementation(() => {
+      metadataStarted.resolve();
+      return metadata.promise;
     });
     mockSessionWithFailingDaemon(async () => {
-      await installStarted.promise;
-      // The install finishes only after the daemon failed.
-      setImmediate(() => install.resolve({ applicationIdentifier: 'dev.example.app' }));
+      await metadataStarted.promise;
+      setImmediate(() => metadata.resolve('dev.example.app'));
     });
-
     await expect(runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id' })).rejects.toThrow(
       'daemon failed'
     );
-
-    expect(installBuildAsync).toHaveBeenCalledTimes(1);
+    expect(readIosApplicationIdentifierAsync).toHaveBeenCalledTimes(1);
+    expect(installBuildAsync).not.toHaveBeenCalled();
     expect(launchApplicationAsync).not.toHaveBeenCalled();
+    expect(deviceLaunch).toBeUndefined();
   });
 
   it('rejects conflicting application inputs before it boots anything', async () => {
@@ -417,6 +625,8 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
       'network_capture_fields',
       'public_preview',
       'private_preview_url',
+      'frame_ancestors',
+      'cors_origins',
       'package_version',
       'max_idle_time_minutes',
       'max_duration_seconds',
@@ -440,6 +650,51 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     }
   );
 
+  it('passes frame_ancestors to the session host', async () => {
+    await runStep(BuildRuntimePlatform.DARWIN, {
+      frame_ancestors: ['https://embed.example.test'],
+    });
+    expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ frameAncestors: ['https://embed.example.test'] })
+    );
+  });
+
+  it('passes cors_origins to the session host', async () => {
+    await runStep(BuildRuntimePlatform.DARWIN, {
+      cors_origins: ['https://app.example.test'],
+    });
+    expect(runAgentDeviceRemoteSessionAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+  });
+
+  it.each([
+    ['argument count', { launch_args: Array(257).fill('a') }],
+    ['argument length', { launch_args: ['a'.repeat(9000)] }],
+    ['NUL argument', { launch_args: ['a\u0000b'] }],
+    ['total UTF-8 bytes', { launch_args: Array(8).fill('😃'.repeat(4096)) }],
+    ['NUL URL', { open_url: 'example:\u0000screen' }],
+    ['URL length', { open_url: `example://${'a'.repeat(8192)}` }],
+  ])('rejects iOS launch %s before startup work', async (_name, inputs) => {
+    const step = runStep(BuildRuntimePlatform.DARWIN, { build_id: 'build-id', ...inputs });
+    await expect(step).rejects.toBeInstanceOf(UserError);
+    expect(selectXcodeDeveloperDirectoryAsync).not.toHaveBeenCalled();
+    expect(IosSimulatorUtils.resolveUdidAsync).not.toHaveBeenCalled();
+    expect(bootIosSimulatorAsync).not.toHaveBeenCalled();
+    expect(downloadBuildAsync).not.toHaveBeenCalled();
+    expect(runAgentDeviceRemoteSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('keeps Android launch inputs on its existing direct path', async () => {
+    const launchArgs = ['a'.repeat(9000)];
+    await runStep(BuildRuntimePlatform.LINUX, { build_id: 'build-id', launch_args: launchArgs });
+    expect(launchApplicationAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ runtimePlatform: BuildRuntimePlatform.LINUX, launchArgs })
+    );
+  });
+
   it('passes network capture to the session', async () => {
     await runStep(BuildRuntimePlatform.DARWIN, {
       network_capture: true,

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

@@ -422,6 +422,54 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     );
   });
 
+  it('passes frame_ancestors to the session host', async () => {
+    const ctx = {} as CustomBuildContext;
+    const buildFunction = createStartArgentRemoteSessionBuildFunction(ctx);
+    await buildFunction.fn!(
+      {
+        logger: { info: jest.fn(), warn: jest.fn() },
+        global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+      } as unknown as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: undefined },
+          frame_ancestors: { value: ['https://embed.example.test'] },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ frameAncestors: ['https://embed.example.test'] })
+    );
+  });
+
+  it('passes cors_origins to the session host', async () => {
+    const ctx = {} as CustomBuildContext;
+    const buildFunction = createStartArgentRemoteSessionBuildFunction(ctx);
+    await buildFunction.fn!(
+      {
+        logger: { info: jest.fn(), warn: jest.fn() },
+        global: { runtimePlatform: BuildRuntimePlatform.LINUX },
+      } as unknown as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: undefined },
+          cors_origins: { value: ['https://app.example.test'] },
+        },
+        outputs: {},
+        env: {},
+      } as never
+    );
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+  });
+
   it('continues the session when disabling the video watermark fails', async () => {
     const error = new Error('bun x failed');
     jest

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

@@ -210,6 +210,8 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
         : {}),
       packageVersion: '1.2.3',
       disableShare: false,
+      frameAncestors: [],
+      corsOrigins: [],
       launchAppIdentifier: undefined,
       launchArgs: [],
       openUrl: undefined,
@@ -258,6 +260,8 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
       'network_capture_fields',
       'public_preview',
       'private_preview_url',
+      'frame_ancestors',
+      'cors_origins',
       'package_version',
       'max_duration_seconds',
     ]);
@@ -322,6 +326,26 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     }
   );
 
+  it('hands frame_ancestors to the session host', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      frame_ancestors: { value: ['https://embed.example.test'] },
+    });
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ frameAncestors: ['https://embed.example.test'] })
+    );
+  });
+
+  it('hands cors_origins to the session host', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      cors_origins: { value: ['https://app.example.test'] },
+    });
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+  });
+
   it('hands network capture to the session host', async () => {
     await runAsync(BuildRuntimePlatform.DARWIN, {
       network_capture: { value: true },

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

@@ -15,6 +15,11 @@ import {
 import { createSubmitToGooglePlayBuildFunction } from '../submitToGooglePlay';
 
 jest.unmock('node-fetch');
+jest.mock('promise-retry', () => {
+  const actual = jest.requireActual('promise-retry');
+  return (fn: Parameters<typeof actual>[0], options: object) =>
+    actual(fn, { ...options, minTimeout: 1, maxTimeout: 1, randomize: false });
+});
 jest.unmock('fs');
 jest.unmock('node:fs');
 jest.unmock('fs/promises');
@@ -174,7 +179,7 @@ it('preserves the original failure when cleanup fails', async () => {
   api()
     .put(`${editPath}/tracks/internal`)
     .reply(400, { error: { message: 'unknown track' } });
-  api().delete(editPath).reply(500);
+  api().delete(editPath).times(6).reply(500);
   await expect(submission().run()).rejects.toMatchObject({
     cause: expect.objectContaining({ apiMessage: 'unknown track' }),
   });
@@ -183,6 +188,7 @@ it('does not delete the edit or publish outputs when commit outcome is unknown',
   upload();
   api().put(`${editPath}/tracks/internal`).reply(200, { track: 'internal' });
   api().post(`${editPath}:commit`).query(true).reply(503);
+  api().post(`${editPath}:commit`).query(true).reply(404);
   let deleted = false;
   api()
     .delete(editPath)

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

@@ -1,6 +1,6 @@
 import { SystemError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
-import { type BuildRuntimePlatform, type BuildStepEnv } from '@expo/steps';
+import { BuildRuntimePlatform, type BuildStepEnv } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -19,6 +19,7 @@ import {
 import { pollAgentDeviceArtifactsForUploadAsync } from '../utils/agentDeviceArtifacts';
 import { type parseNetworkCaptureInputs } from '../utils/networkCaptureFields';
 import { startAgentDeviceEventCollectionAsync } from '../utils/agentDeviceEvents';
+import { type ServeSimApplicationOptions } from '../utils/remoteDeviceRunSession';
 import { type StartupTasks } from '../utils/startupTasks';
 import {
   type DetachedProcessHandle,
@@ -76,13 +77,9 @@ export function getAgentDeviceRemoteSessionEnvOrThrow(
  * Starts the agent-device daemon, its tunnel, the session host and the web preview,
  * reports the session as ready, and keeps it alive until it stops.
  *
- * The daemon does not need the device, so it starts at once. The session host starts
- * when `device.booted` resolves. The session is reported as ready only when both are
- * up and `device.ready` (the app is installed and launched) resolved too.
- *
- * The first failure aborts `tasks.signal`: each part stops before its next stage, and
- * the teardown then stops whatever was started. `device.ready` must settle soon after
- * an abort, because the teardown waits for it.
+ * Serve-sim boots while the iOS download runs. After device preparation verifies
+ * any egress guard, its control API installs and launches the app.
+ * Startup failures abort the other tasks; teardown drains them before stopping acquired resources.
  */
 export async function runAgentDeviceRemoteSessionAsync(
   ctx: CustomBuildContext,
@@ -98,6 +95,8 @@ export async function runAgentDeviceRemoteSessionAsync(
     capture,
     disableShare = false,
     privatePreviewUrl,
+    frameAncestors,
+    corsOrigins,
     tasks,
     device,
   }: {
@@ -112,10 +111,24 @@ export async function runAgentDeviceRemoteSessionAsync(
     capture: ReturnType<typeof parseNetworkCaptureInputs>;
     disableShare?: boolean;
     privatePreviewUrl?: string;
+    frameAncestors?: string[];
+    corsOrigins?: string[];
     tasks: StartupTasks;
-    device: { booted: Promise<unknown>; ready: Promise<unknown> };
+    device:
+      | {
+          booted: Promise<unknown>;
+          ready: Promise<unknown>;
+        }
+      | {
+          iosSimulatorUdid: string;
+          bootEnv?: Record<string, string>;
+          application?: Promise<ServeSimApplicationOptions | void>;
+        };
   }
 ): Promise<void> {
+  signal?.throwIfAborted();
+  tasks.signal.throwIfAborted();
+
   logger.info(
     `Starting agent-device remote session (version: ${packageVersion ?? 'latest'}, runtime: ${runtimePlatform}).`
   );
@@ -126,6 +139,8 @@ export async function runAgentDeviceRemoteSessionAsync(
   let eventCollection: Awaited<ReturnType<typeof startAgentDeviceEventCollectionAsync>> | undefined;
   let sessionFailed = false;
   const daemonSecrets = [ngrokAuthtoken];
+  const hostBootedDevice = 'iosSimulatorUdid' in device ? device : undefined;
+  const externallyBootedDevice = 'booted' in device ? device : undefined;
 
   // Each task stores what it started, so the teardown below can stop it even when
   // another task failed first.
@@ -154,12 +169,14 @@ export async function runAgentDeviceRemoteSessionAsync(
       authtoken: ngrokAuthtoken,
       logger: taskLogger,
     });
+    tasks.signal.throwIfAborted();
     taskLogger.info(`Tunnel is ready at ${agentDeviceTunnel.url}.`);
     return { ...daemonInfo, remoteSessionUrl: agentDeviceTunnel.url };
   });
   const sessionHostStartup = tasks.run('session host', async taskLogger => {
-    // A boot cannot be cancelled, so stop waiting for it when startup is aborted.
-    await tasks.untilAborted(device.booted);
+    if (externallyBootedDevice) {
+      await tasks.untilAborted(externallyBootedDevice.booted);
+    }
     tasks.signal.throwIfAborted();
     sessionHost = await startDeviceSessionHostAsync(ctx, {
       separateLogPhase: true,
@@ -169,14 +186,22 @@ export async function runAgentDeviceRemoteSessionAsync(
       timeoutMs: STARTUP_TIMEOUT_MS,
       disableShare,
       privatePreviewUrl,
+      frameAncestors,
+      corsOrigins,
+      signal: tasks.signal,
+      onStartupError: tasks.abort,
       networkCapture: capture.networkCapture,
       networkCaptureFields: capture.networkCaptureFields,
+      iosSimulatorUdid: hostBootedDevice?.iosSimulatorUdid,
+      bootEnv: hostBootedDevice?.bootEnv,
+      application: hostBootedDevice?.application,
     });
     tasks.signal.throwIfAborted();
     const webPreview = await sessionHost.openPreviewAsync({
       baseDomain: ngrokTunnelDomain,
       authtoken: ngrokAuthtoken,
     });
+    tasks.signal.throwIfAborted();
     taskLogger.info(
       webPreview.sharePageUrl
         ? `Web preview URL: ${webPreview.sharePageUrl} (server: ${webPreview.apiUrl}).`
@@ -184,18 +209,20 @@ export async function runAgentDeviceRemoteSessionAsync(
     );
     return webPreview;
   });
+  const deviceReady = externallyBootedDevice?.ready;
 
   try {
     const [
       { port: daemonPort, token: daemonToken, remoteSessionUrl: agentDeviceRemoteSessionUrl },
       webPreview,
-    ] = await Promise.all([agentDeviceStartup, sessionHostStartup, device.ready]).catch(
+    ] = await Promise.all([agentDeviceStartup, sessionHostStartup, deviceReady]).catch(
       (err: unknown) => {
         // Also aborts for a `device.ready` that does not come from `tasks.run`.
         tasks.abort(err);
-        throw err;
+        throw tasks.signal.reason;
       }
     );
+    tasks.signal.throwIfAborted();
     logger.info(tasks.summary());
 
     await uploadRemoteSessionConfigWithLocalEgressAsync({
@@ -212,6 +239,7 @@ export async function runAgentDeviceRemoteSessionAsync(
       },
       logger,
     });
+    tasks.signal.throwIfAborted();
     void pollAgentDeviceArtifactsForUploadAsync(ctx, {
       deviceRunSessionId,
       daemonUrl: `http://127.0.0.1:${daemonPort}`,
@@ -247,7 +275,7 @@ export async function runAgentDeviceRemoteSessionAsync(
     // Promise.all rejects on the first failure while other tasks can still be starting.
     // They stop at their next abort check. Wait for all of them, so the teardown sees
     // everything that was started.
-    await Promise.allSettled([agentDeviceStartup, sessionHostStartup, device.ready]);
+    await Promise.allSettled([agentDeviceStartup, sessionHostStartup, deviceReady]);
     const startedDaemon = daemonProcess;
     await finishRemoteSessionAsync({
       logger,
@@ -291,6 +319,7 @@ export async function startAgentDeviceDaemonAsync({
   signal?: AbortSignal;
   secrets?: string[];
 }): Promise<DetachedProcessHandle> {
+  signal?.throwIfAborted();
   const packageSpec = createAgentDevicePackageSpec(packageVersion);
   const packageManager = resolveConfiguredPackageManager(env, PackageManager.BUN);
   const installDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'eas-agent-device-'));
@@ -300,6 +329,7 @@ export async function startAgentDeviceDaemonAsync({
   );
 
   try {
+    signal?.throwIfAborted();
     const add = resolvePackageAdd(packageManager, packageSpec);
     logger.info(`Installing ${packageSpec} with ${add.command}.`);
     await spawn(add.command, add.args, { cwd: installDir, env, logger, signal });

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

@@ -15,13 +15,16 @@ import {
   AndroidEmulatorUtils,
   AndroidVirtualDeviceName,
 } from '../../utils/AndroidEmulatorUtils';
-import { IosSimulatorName, IosSimulatorUuid } from '../../utils/IosSimulatorUtils';
 import { getDeviceRunSessionWorkerApi } from '../utils/deviceRunSessionWorkerApi';
 import { withLocalEgressSession } from '../utils/localEgressSession';
 import {
+  createCorsOriginsInputProvider,
+  createFrameAncestorsInputProvider,
   createPrivatePreviewUrlInputProvider,
   createPublicPreviewInputProvider,
   omitNgrokAuthtoken,
+  parseCorsOriginsInput,
+  parseFrameAncestorsInput,
   selectXcodeDeveloperDirectoryAsync,
 } from '../utils/remoteDeviceRunSession';
 import {
@@ -29,6 +32,10 @@ import {
   parseNetworkCaptureInputs,
 } from '../utils/networkCaptureFields';
 import { createStartupTasks } from '../utils/startupTasks';
+import {
+  type ServeSimApplicationOptions,
+  validateServeSimLaunchOptions,
+} from '../utils/remoteDeviceRunSession';
 
 import { downloadBuildAsync } from './downloadBuild';
 import { installBuildAsync } from './installBuild';
@@ -42,26 +49,15 @@ import {
   runAgentDeviceRemoteSessionAsync,
 } from './startAgentDeviceRemoteSession';
 import { startAndroidEmulatorAsync } from './startAndroidEmulator';
-import { bootIosSimulatorAsync } from './startIosSimulator';
+import { resolveIosSessionStartupAsync } from '../utils/iosSimulatorSession';
+import { readIosApplicationIdentifierAsync } from '../utils/iosAppArtifact';
 
 const ANDROID_DEVICE_NAME = 'EasAndroidDevice01' as AndroidVirtualDeviceName;
 
 /**
- * One step for a whole agent-device session: boot the device, download, install and
- * launch the app, and start the agent-device daemon and the web preview.
- *
- * It does the work of eas/start_ios_simulator or eas/start_android_emulator,
- * eas/download_build, eas/install_build and eas/launch_application, plus the agent-device
- * session, so the parts that do not depend on each other can run at the same time:
- *
- *   boot ─────────────┬─► install ─► launch ─┐
- *   download ─────────┘                      │
- *   boot ─► session host ─► web preview ─────┼─► ready
- *   agent-device daemon ─► tunnel ───────────┘
- *
- * The first failure aborts the rest: the download stops, and nothing installs, launches
- * or starts after it. A boot cannot be cancelled, so it can still run when a failed
- * step returns.
+ * Starts a device session, downloading the app alongside daemon startup.
+ * On iOS, serve-sim boots the selected Simulator, then installs and launches
+ * the downloaded app. Build-tools verifies any egress guard before install and launch.
  */
 export function createStartAgentDeviceSessionBuildFunction(ctx: CustomBuildContext): BuildFunction {
   return new BuildFunction({
@@ -122,6 +118,8 @@ export function createStartAgentDeviceSessionBuildFunction(ctx: CustomBuildConte
       ...createNetworkCaptureInputProviders(),
       createPublicPreviewInputProvider(),
       createPrivatePreviewUrlInputProvider(),
+      createFrameAncestorsInputProvider(),
+      createCorsOriginsInputProvider(),
       BuildStepInput.createProvider({
         id: 'package_version',
         required: false,
@@ -164,6 +162,9 @@ export function createStartAgentDeviceSessionBuildFunction(ctx: CustomBuildConte
           'launch_args and open_url need an application: pass build_id or application_archive_url.'
         );
       }
+      if (isIos) {
+        validateServeSimLaunchOptions({ launchArgs, openUrl });
+      }
       const deviceIdentifier = inputs.device_identifier.value as string | undefined;
       const capture = parseNetworkCaptureInputs(
         {
@@ -173,107 +174,137 @@ export function createStartAgentDeviceSessionBuildFunction(ctx: CustomBuildConte
         { runtimePlatform }
       );
 
-      if (isIos) {
-        // Before the boot, so every Xcode tool below uses the same developer directory.
-        await selectXcodeDeveloperDirectoryAsync({ env, logger });
-      }
+      const tasks = createStartupTasks(logger, signal);
+      let downloaded: Promise<string> | undefined;
+      let applicationReady: Promise<ServeSimApplicationOptions | void> | undefined;
 
-      const tasks = createStartupTasks(logger);
-
-      const booted = tasks.run(
-        isIos ? 'iOS Simulator boot' : 'Android Emulator boot',
-        async taskLogger => {
-          if (isIos) {
-            await bootIosSimulatorAsync({
-              deviceIdentifier: deviceIdentifier as IosSimulatorUuid | IosSimulatorName | undefined,
-              env,
-              logger: taskLogger,
-            });
-            return;
-          }
-          await startAndroidEmulatorAsync({
-            deviceName: ANDROID_DEVICE_NAME,
-            systemImagePackage: `${inputs.system_image_package.value}`,
-            deviceIdentifier: deviceIdentifier as AndroidDeviceName | undefined,
-            lcdWidth: inputs.lcd_width.value as number | undefined,
-            lcdHeight: inputs.lcd_height.value as number | undefined,
-            lcdDensity: inputs.lcd_density.value as number | undefined,
-            logcatDirectory: await fs.promises.mkdtemp(
-              path.join(os.tmpdir(), 'eas-android-emulator-logcat-')
-            ),
-            env,
-            logger: taskLogger,
-          });
+      try {
+        if (isIos) {
+          // Select Xcode before serve-sim boots the device or any Simulator tools run.
+          await selectXcodeDeveloperDirectoryAsync({ env, logger });
         }
-      );
-
-      const downloaded = hasApplication
-        ? tasks.run('build download', async taskLogger => {
-            const { artifactPath } = await downloadBuildAsync({
-              logger: taskLogger,
-              ...(buildId ? { buildId } : { applicationArchiveUrl: applicationArchiveUrl! }),
-              graphqlClient: ctx.graphqlClient,
-              deviceRunSessionWorkerApi: buildId ? getDeviceRunSessionWorkerApi(ctx) : null,
-              robotAccessToken: global.staticContext.job.secrets?.robotAccessToken ?? null,
-              extensions: isIos ? ['app'] : ['apk'],
+        tasks.signal.throwIfAborted();
+        const { iosStartup } = isIos
+          ? await resolveIosSessionStartupAsync({
+              runtimePlatform,
+              bootSimulator: true,
+              deviceIdentifier,
+              env,
+              logger,
               signal: tasks.signal,
-            });
-            return artifactPath;
-          })
-        : undefined;
+            })
+          : {};
+        const iosSimulatorUdid = iosStartup?.iosSimulatorUdid;
+        if (iosSimulatorUdid) {
+          logger.info(`Selected iOS Simulator: ${iosSimulatorUdid}.`);
+        }
 
-      // `ready` settles only after everything it started has settled, so the session
-      // teardown, which waits for it, never leaves a download running. It must also settle
-      // soon after an abort: it stops waiting for the boot then, and the download stops.
-      const ready = downloaded
-        ? tasks.run('app install and launch', async taskLogger => {
-            const [download, boot] = await Promise.allSettled([
-              downloaded,
-              tasks.untilAborted(booted),
-            ]);
-            // After a failure elsewhere, report that failure, not the abort it caused here.
-            tasks.signal.throwIfAborted();
-            if (download.status === 'rejected') {
-              throw download.reason;
-            }
-            if (boot.status === 'rejected') {
-              throw boot.reason;
-            }
-            const { applicationIdentifier, activityName } = await installBuildAsync({
-              artifactPath: download.value,
-              runtimePlatform,
-              env,
-              logger: taskLogger,
+        const booted = iosSimulatorUdid
+          ? undefined
+          : tasks.run('Android Emulator boot', async taskLogger => {
+              const logcatDirectory = await fs.promises.mkdtemp(
+                path.join(os.tmpdir(), 'eas-android-emulator-logcat-')
+              );
+              tasks.signal.throwIfAborted();
+              await startAndroidEmulatorAsync({
+                deviceName: ANDROID_DEVICE_NAME,
+                systemImagePackage: `${inputs.system_image_package.value}`,
+                deviceIdentifier: deviceIdentifier as AndroidDeviceName | undefined,
+                lcdWidth: inputs.lcd_width.value as number | undefined,
+                lcdHeight: inputs.lcd_height.value as number | undefined,
+                lcdDensity: inputs.lcd_density.value as number | undefined,
+                logcatDirectory,
+                env,
+                logger: taskLogger,
+              });
             });
-            tasks.signal.throwIfAborted();
-            await launchApplicationAsync({
-              applicationIdentifier,
-              activityName,
-              launchArgs,
-              openUrl,
-              runtimePlatform,
-              env,
-              logger: taskLogger,
-            });
-          })
-        : tasks.untilAborted(booted);
 
-      await runAgentDeviceRemoteSessionAsync(ctx, {
-        env,
-        logger,
-        signal,
-        runtimePlatform,
-        sessionEnv,
-        packageVersion: inputs.package_version.value as string | undefined,
-        // A missing or non-positive value disables the idle timeout (opt-in feature).
-        maxIdleTimeMinutes: inputs.max_idle_time_minutes.value as number | undefined,
-        maxDurationSeconds: inputs.max_duration_seconds.value as number | undefined,
-        capture,
-        disableShare: inputs.public_preview?.value === false,
-        privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
-        tasks,
-        device: { booted, ready },
-      });
+        downloaded = hasApplication
+          ? tasks.run('build download', async taskLogger => {
+              const { artifactPath } = await downloadBuildAsync({
+                logger: taskLogger,
+                ...(buildId ? { buildId } : { applicationArchiveUrl: applicationArchiveUrl! }),
+                graphqlClient: ctx.graphqlClient,
+                deviceRunSessionWorkerApi: buildId ? getDeviceRunSessionWorkerApi(ctx) : null,
+                robotAccessToken: global.staticContext.job.secrets?.robotAccessToken ?? null,
+                extensions: isIos ? ['app'] : ['apk'],
+                signal: tasks.signal,
+              });
+              return artifactPath;
+            })
+          : undefined;
+
+        const download = downloaded;
+        applicationReady = download
+          ? tasks.run(isIos ? 'app preparation' : 'app install and launch', async taskLogger => {
+              if (booted) {
+                await tasks.untilAborted(booted);
+              }
+              const artifactPath = await download;
+              tasks.signal.throwIfAborted();
+              if (isIos) {
+                const applicationIdentifier = await readIosApplicationIdentifierAsync({
+                  artifactPath,
+                  env,
+                });
+                tasks.signal.throwIfAborted();
+                return {
+                  installAppPath: artifactPath,
+                  launchAppIdentifier: applicationIdentifier,
+                  launchArgs,
+                  openUrl,
+                };
+              }
+              const { applicationIdentifier, activityName } = await installBuildAsync({
+                artifactPath,
+                runtimePlatform,
+                env,
+                logger: taskLogger,
+              });
+              tasks.signal.throwIfAborted();
+              await launchApplicationAsync({
+                applicationIdentifier,
+                activityName,
+                launchArgs,
+                openUrl,
+                runtimePlatform,
+                env,
+                logger: taskLogger,
+              });
+            })
+          : undefined;
+
+        await runAgentDeviceRemoteSessionAsync(ctx, {
+          env,
+          logger,
+          signal,
+          runtimePlatform,
+          sessionEnv,
+          packageVersion: inputs.package_version.value as string | undefined,
+          // A missing or non-positive value disables the idle timeout (opt-in feature).
+          maxIdleTimeMinutes: inputs.max_idle_time_minutes.value as number | undefined,
+          maxDurationSeconds: inputs.max_duration_seconds.value as number | undefined,
+          capture,
+          disableShare: inputs.public_preview?.value === false,
+          privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
+          frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
+          corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
+          tasks,
+          device: iosSimulatorUdid
+            ? {
+                ...iosStartup,
+                iosSimulatorUdid,
+                application: applicationReady,
+              }
+            : {
+                booted: booted!,
+                ready: applicationReady ?? tasks.untilAborted(booted!),
+              },
+        });
+      } finally {
+        tasks.abort(new Error('Agent-device session ended.'));
+        await Promise.allSettled([downloaded, applicationReady]);
+      }
     }),
   });
 }

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

@@ -37,6 +37,8 @@ import { turtleFetch } from '../../utils/turtleFetch';
 import { startAppiumEventCollectionAsync } from '../utils/appiumEvents';
 import { preparePreinstalledWdaAsync } from '../utils/preinstalledWda';
 import {
+  createCorsOriginsInputProvider,
+  createFrameAncestorsInputProvider,
   createPrivatePreviewUrlInputProvider,
   createPublicPreviewInputProvider,
   createServeSimLaunchInputProviders,
@@ -47,6 +49,8 @@ import {
   getNgrokAuthtokenOrThrow,
   getNgrokTunnelDomainOrThrow,
   omitNgrokAuthtoken,
+  parseCorsOriginsInput,
+  parseFrameAncestorsInput,
   parseServeSimLaunchInputs,
   selectXcodeDeveloperDirectoryAsync,
   spawnDetached,
@@ -77,6 +81,8 @@ export function createStartAppiumRemoteSessionBuildFunction(
       ...createNetworkCaptureInputProviders(),
       createPublicPreviewInputProvider(),
       createPrivatePreviewUrlInputProvider(),
+      createFrameAncestorsInputProvider(),
+      createCorsOriginsInputProvider(),
       BuildStepInput.createProvider({
         id: 'package_version',
         required: false,
@@ -192,6 +198,8 @@ export function createStartAppiumRemoteSessionBuildFunction(
           timeoutMs: APPIUM_STARTUP_TIMEOUT_MS,
           disableShare: inputs.public_preview?.value === false,
           privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
+          frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
+          corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
           launchAppIdentifier: launch.launchAppIdentifier,
           launchArgs: launch.launchArgs,
           openUrl: launch.openUrl,

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

@@ -34,6 +34,8 @@ import { sleepAsync } from '../../utils/retry';
 import { pollArgentArtifactsForUploadAsync } from '../utils/argentArtifacts';
 import { ARGENT_EVENT_LOG_FILENAME, startArgentEventCollectionAsync } from '../utils/argentEvents';
 import {
+  createCorsOriginsInputProvider,
+  createFrameAncestorsInputProvider,
   createPrivatePreviewUrlInputProvider,
   createPublicPreviewInputProvider,
   createServeSimLaunchInputProviders,
@@ -44,6 +46,8 @@ import {
   getNgrokAuthtokenOrThrow,
   getNgrokTunnelDomainOrThrow,
   omitNgrokAuthtoken,
+  parseCorsOriginsInput,
+  parseFrameAncestorsInput,
   parseServeSimLaunchInputs,
   selectXcodeDeveloperDirectoryAsync,
   spawnDetached,
@@ -89,6 +93,8 @@ export function createStartArgentRemoteSessionBuildFunction(
       ...createNetworkCaptureInputProviders(),
       createPublicPreviewInputProvider(),
       createPrivatePreviewUrlInputProvider(),
+      createFrameAncestorsInputProvider(),
+      createCorsOriginsInputProvider(),
       BuildStepInput.createProvider({
         id: 'package_version',
         required: false,
@@ -289,6 +295,8 @@ export function createStartArgentRemoteSessionBuildFunction(
           timeoutMs: STARTUP_TIMEOUT_MS,
           disableShare: inputs.public_preview?.value === false,
           privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
+          frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
+          corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
           launchAppIdentifier: launch.launchAppIdentifier,
           launchArgs: launch.launchArgs,
           openUrl: launch.openUrl,

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

@@ -17,6 +17,8 @@ import {
   withLocalEgressSession,
 } from '../utils/localEgressSession';
 import {
+  createCorsOriginsInputProvider,
+  createFrameAncestorsInputProvider,
   createIosSessionStartupInputProviders,
   createPrivatePreviewUrlInputProvider,
   createPublicPreviewInputProvider,
@@ -26,6 +28,8 @@ import {
   getNgrokAuthtokenOrThrow,
   getNgrokTunnelDomainOrThrow,
   omitNgrokAuthtoken,
+  parseCorsOriginsInput,
+  parseFrameAncestorsInput,
   selectXcodeDeveloperDirectoryAsync,
   waitForDeviceRunSessionStoppedAsync,
 } from '../utils/remoteDeviceRunSession';
@@ -46,6 +50,8 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
       ...createNetworkCaptureInputProviders(),
       createPublicPreviewInputProvider(),
       createPrivatePreviewUrlInputProvider(),
+      createFrameAncestorsInputProvider(),
+      createCorsOriginsInputProvider(),
       BuildStepInput.createProvider({
         id: 'package_version',
         required: false,
@@ -104,6 +110,8 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
         packageVersion,
         disableShare: inputs.public_preview?.value === false,
         privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
+        frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
+        corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
         launchAppIdentifier: launch.launchAppIdentifier,
         launchArgs: launch.launchArgs,
         openUrl: launch.openUrl,

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

@@ -131,7 +131,7 @@ export function createSubmitToGooglePlayBuildFunction(): BuildFunction {
         keyPath: path.resolve(ctx.workingDirectory, submission.service_account_key_path),
       });
       const artifactPath = path.resolve(ctx.workingDirectory, submission.artifact_path);
-      const client = new GooglePlayClient(credentials);
+      const client = new GooglePlayClient(credentials, ctx.logger);
       const versionCode = await submitToGooglePlayAsync({
         artifactType: submission.artifact_type,
         client,

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

@@ -7,7 +7,12 @@ import { type CustomBuildContext } from '../../../customBuildContext';
 import HttpLogStream from '../../../logging/HttpLogStream';
 import RemoteLoggerStream from '../../../logging/RemoteLoggerStream';
 import { Sentry } from '../../../sentry';
+import { turtleFetch } from '../../../utils/turtleFetch';
 import { startAgentDeviceEventCollectionAsync } from '../agentDeviceEvents';
+import {
+  DEVICE_RUN_SESSION_TOKEN_HEADER,
+  DeviceRunSessionWorkerApiError,
+} from '../deviceRunSessionWorkerApi';
 
 const mockEventLogStream = {
   init: jest.fn(async () => undefined),
@@ -28,10 +33,18 @@ jest.mock('../../../logging/RemoteLoggerStream', () => ({
   default: jest.fn(() => mockEventLogStream),
 }));
 jest.mock('../../../sentry');
+jest.mock('../../../utils/turtleFetch');
+
+const { Response } = jest.requireActual('node-fetch') as typeof import('node-fetch');
+
+const DEVICE_RUN_SESSION_TOKEN = 'device-run-session-token-value';
+const EVENT_LOG_UPLOAD_SESSION_URL =
+  'https://api.expo.test/v2/device-run-session-worker/event-log-upload-session';
 
 describe(startAgentDeviceEventCollectionAsync, () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    jest.mocked(turtleFetch).mockImplementation(async () => eventLogUploadSessionResponse());
   });
 
   it('uploads normalized events to the session event artifact once', async () => {
@@ -88,9 +101,13 @@ describe(startAgentDeviceEventCollectionAsync, () => {
       await fs.promises.rm(stateDir, { recursive: true, force: true });
     }
 
-    expect(ctx.graphqlClient.mutation).toHaveBeenCalledWith(expect.anything(), {
-      deviceRunSessionId: 'session-id',
-    });
+    expect(turtleFetch).toHaveBeenCalledWith(
+      EVENT_LOG_UPLOAD_SESSION_URL,
+      'POST',
+      expect.objectContaining({
+        headers: { [DEVICE_RUN_SESSION_TOKEN_HEADER]: DEVICE_RUN_SESSION_TOKEN },
+      })
+    );
     expect(RemoteLoggerStream).toHaveBeenCalledWith({
       logger,
       uploadMethod: {
@@ -535,11 +552,13 @@ describe(startAgentDeviceEventCollectionAsync, () => {
   });
 
   it('does not fail the session when event log setup fails', async () => {
-    const error = new Error('WWW unavailable');
     const ctx = createContext({ realtimeLogs: true });
-    jest.mocked(ctx.graphqlClient.mutation).mockReturnValueOnce({
-      toPromise: async () => ({ error }),
-    } as unknown as ReturnType<CustomBuildContext['graphqlClient']['mutation']>);
+    jest.mocked(turtleFetch).mockResolvedValueOnce(
+      new Response(JSON.stringify({ errors: [{ message: 'WWW unavailable' }] }), {
+        status: 503,
+        headers: { 'content-type': 'application/json' },
+      })
+    );
     const logger = createLogger();
 
     const collection = await startAgentDeviceEventCollectionAsync({
@@ -554,8 +573,11 @@ describe(startAgentDeviceEventCollectionAsync, () => {
     expect(logger.warn).toHaveBeenCalledWith(
       {
         err: expect.objectContaining({
-          message: 'Failed to create device run session event log upload session: WWW unavailable',
-          cause: error,
+          message:
+            'Failed to create device run session event log upload session: ' +
+            'POST /v2/device-run-session-worker/event-log-upload-session failed with status 503: ' +
+            'WWW unavailable',
+          cause: expect.any(DeviceRunSessionWorkerApiError),
         }),
       },
       'Could not persist device run session events to the artifact.'
@@ -563,8 +585,11 @@ describe(startAgentDeviceEventCollectionAsync, () => {
     expect(Sentry.capture).toHaveBeenCalledWith(
       'Could not persist device run session events',
       expect.objectContaining({
-        message: 'Failed to create device run session event log upload session: WWW unavailable',
-        cause: error,
+        message:
+          'Failed to create device run session event log upload session: ' +
+          'POST /v2/device-run-session-worker/event-log-upload-session failed with status 503: ' +
+          'WWW unavailable',
+        cause: expect.any(DeviceRunSessionWorkerApiError),
       }),
       {
         level: 'warning',
@@ -669,32 +694,35 @@ describe(startAgentDeviceEventCollectionAsync, () => {
 function createContext({
   realtimeLogs = false,
 }: { realtimeLogs?: boolean } = {}): CustomBuildContext {
-  const mutation = jest.fn().mockReturnValue({
-    toPromise: async () => ({
-      data: {
-        deviceRunSession: {
-          createEventLogUploadSession: {
-            uploadSession: {
-              url: 'https://uploads.expo.test/events',
-              headers: {
-                'content-disposition': 'attachment; filename="events.ndjson"',
-                'x-goog-content-length-range': '0,104857600',
-              },
-            },
-          },
-        },
-      },
-    }),
-  });
   return {
-    graphqlClient: { mutation },
-    env: realtimeLogs ? { EXPO_STAGING: '1', EAS_BUILD_ID: 'job-run-id' } : {},
+    env: {
+      EAS_DEVICE_RUN_SESSION_TOKEN: DEVICE_RUN_SESSION_TOKEN,
+      ...(realtimeLogs ? { EXPO_STAGING: '1', EAS_BUILD_ID: 'job-run-id' } : {}),
+    },
+    expoApiV2BaseUrl: 'https://api.expo.test/v2/',
     job: {
       secrets: realtimeLogs ? { robotAccessToken: 'robot-access-token' } : {},
     },
   } as unknown as CustomBuildContext;
 }
 
+function eventLogUploadSessionResponse(): InstanceType<typeof Response> {
+  return new Response(
+    JSON.stringify({
+      data: {
+        uploadSession: {
+          url: 'https://uploads.expo.test/events',
+          headers: {
+            'content-disposition': 'attachment; filename="events.ndjson"',
+            'x-goog-content-length-range': '0,104857600',
+          },
+        },
+      },
+    }),
+    { headers: { 'content-type': 'application/json' } }
+  );
+}
+
 function createLogger(): bunyan {
   return { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
 }

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

@@ -7,7 +7,9 @@ import { type CustomBuildContext } from '../../../customBuildContext';
 import HttpLogStream from '../../../logging/HttpLogStream';
 import RemoteLoggerStream from '../../../logging/RemoteLoggerStream';
 import { Sentry } from '../../../sentry';
+import { turtleFetch } from '../../../utils/turtleFetch';
 import { startArgentEventCollectionAsync } from '../argentEvents';
+import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 
 const mockEventLogStream = {
   init: jest.fn(async () => undefined),
@@ -28,12 +30,20 @@ jest.mock('../../../logging/RemoteLoggerStream', () => ({
   default: jest.fn(() => mockEventLogStream),
 }));
 jest.mock('../../../sentry');
+jest.mock('../../../utils/turtleFetch');
+
+const { Response } = jest.requireActual('node-fetch') as typeof import('node-fetch');
+
+const DEVICE_RUN_SESSION_TOKEN = 'device-run-session-token-value';
+const EVENT_LOG_UPLOAD_SESSION_URL =
+  'https://api.expo.test/v2/device-run-session-worker/event-log-upload-session';
 
 const EVENT_LOG_FILENAME = 'tool-server-events.jsonl';
 
 describe(startArgentEventCollectionAsync, () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    jest.mocked(turtleFetch).mockImplementation(async () => eventLogUploadSessionResponse());
   });
 
   it('maps tool lifecycle records onto the shared operation vocabulary', async () => {
@@ -84,9 +94,13 @@ describe(startArgentEventCollectionAsync, () => {
       await fs.promises.rm(stateDir, { recursive: true, force: true });
     }
 
-    expect(ctx.graphqlClient.mutation).toHaveBeenCalledWith(expect.anything(), {
-      deviceRunSessionId: 'session-id',
-    });
+    expect(turtleFetch).toHaveBeenCalledWith(
+      EVENT_LOG_UPLOAD_SESSION_URL,
+      'POST',
+      expect.objectContaining({
+        headers: { [DEVICE_RUN_SESSION_TOKEN_HEADER]: DEVICE_RUN_SESSION_TOKEN },
+      })
+    );
     expect(RemoteLoggerStream).toHaveBeenCalledWith({
       logger,
       uploadMethod: {
@@ -318,29 +332,32 @@ function bunyanRecord(fields: Record<string, unknown>): Record<string, unknown>
 function createContext({
   realtimeLogs = false,
 }: { realtimeLogs?: boolean } = {}): CustomBuildContext {
-  const mutation = jest.fn().mockReturnValue({
-    toPromise: async () => ({
-      data: {
-        deviceRunSession: {
-          createEventLogUploadSession: {
-            uploadSession: {
-              url: 'https://uploads.expo.test/events',
-              headers: { 'content-disposition': 'attachment; filename="events.ndjson"' },
-            },
-          },
-        },
-      },
-    }),
-  });
   return {
-    graphqlClient: { mutation },
-    env: realtimeLogs ? { EXPO_STAGING: '1', EAS_BUILD_ID: 'job-run-id' } : {},
+    env: {
+      EAS_DEVICE_RUN_SESSION_TOKEN: DEVICE_RUN_SESSION_TOKEN,
+      ...(realtimeLogs ? { EXPO_STAGING: '1', EAS_BUILD_ID: 'job-run-id' } : {}),
+    },
+    expoApiV2BaseUrl: 'https://api.expo.test/v2/',
     job: {
       secrets: realtimeLogs ? { robotAccessToken: 'robot-access-token' } : {},
     },
   } as unknown as CustomBuildContext;
 }
 
+function eventLogUploadSessionResponse(): InstanceType<typeof Response> {
+  return new Response(
+    JSON.stringify({
+      data: {
+        uploadSession: {
+          url: 'https://uploads.expo.test/events',
+          headers: { 'content-disposition': 'attachment; filename="events.ndjson"' },
+        },
+      },
+    }),
+    { headers: { 'content-type': 'application/json' } }
+  );
+}
+
 function createLogger(): bunyan {
   return { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
 }

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

@@ -2,46 +2,56 @@ import fetch from 'node-fetch';
 import { Readable } from 'node:stream';
 
 import { CustomBuildContext } from '../../../customBuildContext';
+import { turtleFetch } from '../../../utils/turtleFetch';
 import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
+import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 
 jest.mock('node-fetch');
+jest.mock('../../../utils/turtleFetch');
 
 const { Response } = jest.requireActual('node-fetch') as typeof import('node-fetch');
 
+const TOKEN = 'device-run-session-token-value';
+
+function jsonResponse(body: unknown): InstanceType<typeof Response> {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+function createCtx(): CustomBuildContext {
+  return {
+    env: { EAS_DEVICE_RUN_SESSION_TOKEN: TOKEN },
+    expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+  } as unknown as CustomBuildContext;
+}
+
 describe(uploadDeviceRunSessionArtifactAsync, () => {
   beforeEach(() => {
     jest.mocked(fetch).mockReset();
+    jest.mocked(turtleFetch).mockReset();
   });
 
   it('streams an artifact through a signed upload URL', async () => {
     const stream = Readable.from(Buffer.from('artifact-data'));
     const reportedSize = 1024;
-    const mutation = jest.fn().mockReturnValue({
-      toPromise: async () => ({
+    jest.mocked(turtleFetch).mockResolvedValueOnce(
+      jsonResponse({
         data: {
-          deviceRunSession: {
-            createArtifactUploadSession: {
-              uploadSession: {
-                url: 'https://uploads.expo.test/artifact',
-                headers: {
-                  'Content-Length': String(reportedSize),
-                  'Content-Type': 'application/octet-stream',
-                },
-              },
+          uploadSession: {
+            url: 'https://uploads.expo.test/artifact',
+            headers: {
+              'Content-Length': String(reportedSize),
+              'Content-Type': 'application/octet-stream',
             },
           },
         },
-      }),
-    });
-    const ctx = {
-      graphqlClient: {
-        mutation,
-      },
-    } as unknown as CustomBuildContext;
-
+      })
+    );
     jest.mocked(fetch).mockResolvedValueOnce(new Response('', { status: 200 }));
 
-    await uploadDeviceRunSessionArtifactAsync(ctx, {
+    await uploadDeviceRunSessionArtifactAsync(createCtx(), {
       deviceRunSessionId: 'drs-id',
       artifactId: 'artifact-id',
       name: 'Artifact report.json (artifact-id)',
@@ -52,19 +62,20 @@ describe(uploadDeviceRunSessionArtifactAsync, () => {
       openStream: () => stream,
     });
 
-    expect(mutation).toHaveBeenCalledWith(
-      expect.anything(),
+    expect(jest.mocked(turtleFetch)).toHaveBeenCalledWith(
+      'https://api.expo.test/v2/device-run-session-worker/artifact-upload-sessions',
+      'POST',
       expect.objectContaining({
-        deviceRunSessionId: 'drs-id',
-        input: {
+        headers: { [DEVICE_RUN_SESSION_TOKEN_HEADER]: TOKEN },
+        json: {
           name: 'Artifact report.json (artifact-id)',
           filename: 'report.json',
           kind: 'agent-device-test-report',
           metadata: { firstFrameRecordAt: 'test-time' },
           size: reportedSize,
         },
-      }),
-      { fetch: expect.any(Function) }
+        signal: expect.any(AbortSignal),
+      })
     );
     expect(jest.mocked(fetch)).toHaveBeenCalledWith(
       'https://uploads.expo.test/artifact',
@@ -77,26 +88,19 @@ describe(uploadDeviceRunSessionArtifactAsync, () => {
 
   it('forwards cancellation through upload allocation and skips PUT when allocation aborts', async () => {
     const controller = new AbortController();
-    const mutation = jest.fn().mockReturnValue({
-      toPromise: async () => {
-        controller.abort();
-        return {
-          data: {
-            deviceRunSession: {
-              createArtifactUploadSession: {
-                uploadSession: {
-                  url: 'https://uploads.expo.test/artifact',
-                  headers: {},
-                },
-              },
-            },
+    jest.mocked(turtleFetch).mockImplementationOnce(async () => {
+      controller.abort();
+      return jsonResponse({
+        data: {
+          uploadSession: {
+            url: 'https://uploads.expo.test/artifact',
+            headers: {},
           },
-        };
-      },
+        },
+      });
     });
-    const ctx = { graphqlClient: { mutation } } as unknown as CustomBuildContext;
     await expect(
-      uploadDeviceRunSessionArtifactAsync(ctx, {
+      uploadDeviceRunSessionArtifactAsync(createCtx(), {
         deviceRunSessionId: 'session',
         artifactId: 'id',
         name: 'Logs',
@@ -108,18 +112,8 @@ describe(uploadDeviceRunSessionArtifactAsync, () => {
       })
     ).rejects.toThrow();
     expect(fetch).not.toHaveBeenCalled();
-    const allocationFetch = mutation.mock.calls[0][2].fetch;
-    const mockFetch = jest.spyOn(globalThis, 'fetch').mockRejectedValueOnce(new Error('aborted'));
-    try {
-      await expect(allocationFetch('https://api.expo.test/graphql', {})).rejects.toThrow('aborted');
-      expect(mockFetch).toHaveBeenCalledWith(
-        'https://api.expo.test/graphql',
-        expect.objectContaining({
-          signal: expect.objectContaining({ aborted: true }),
-        })
-      );
-    } finally {
-      mockFetch.mockRestore();
-    }
+    const allocationSignal = jest.mocked(turtleFetch).mock.calls[0][2].signal;
+    expect(allocationSignal).toBeInstanceOf(AbortSignal);
+    expect(allocationSignal?.aborted).toBe(true);
   });
 });

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

@@ -1,7 +1,7 @@
 import { type bunyan } from '@expo/logger';
 import { BuildRuntimePlatform } from '@expo/steps';
+import { SystemError } from '@expo/eas-build-job';
 import spawn from '@expo/turtle-spawn';
-import { Client, fetchExchange } from '@urql/core';
 import { getEventListeners } from 'node:events';
 import { readFile, readdir, writeFile } from 'node:fs/promises';
 import { Readable } from 'node:stream';
@@ -10,20 +10,43 @@ import fetch from 'node-fetch';
 
 import { type CustomBuildContext } from '../../../customBuildContext';
 import * as processes from '../../../utils/processes';
+import { turtleFetch } from '../../../utils/turtleFetch';
 import {
   captureDeviceRunSessionPreviewAsync,
   ensureMacosPreviewEncoderInstalledAsync,
   startDeviceRunSessionPreview,
 } from '../deviceRunSessionPreview';
+import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 
 jest.mock('node-fetch');
 jest.mock('@expo/turtle-spawn');
+jest.mock('../../../utils/turtleFetch');
 const { Response } = jest.requireActual('node-fetch') as typeof import('node-fetch');
 
+const DEVICE_RUN_SESSION_TOKEN = 'device-run-session-token-value';
+const PREVIEW_UPLOAD_SESSION_URL =
+  'https://api.expo.test/v2/device-run-session-worker/preview-upload-session';
+const uploadSession = {
+  url: 'https://uploads.expo.test/preview',
+  headers: { 'content-type': 'image/webp' },
+};
+
+function createCtx(): CustomBuildContext {
+  return {
+    env: { EAS_DEVICE_RUN_SESSION_TOKEN: DEVICE_RUN_SESSION_TOKEN },
+    expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+  } as unknown as CustomBuildContext;
+}
+
+function uploadSessionResponse(): InstanceType<typeof Response> {
+  return new Response(JSON.stringify({ data: { uploadSession } }), {
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
 describe(startDeviceRunSessionPreview, () => {
   const image = Buffer.from('webp-image');
   let captureAsync: jest.Mock<Promise<Buffer>, [AbortSignal]>;
-  let mutation: jest.Mock;
   let logger: bunyan;
   let ctx: CustomBuildContext;
   let preview: ReturnType<typeof startDeviceRunSessionPreview> | undefined;
@@ -31,21 +54,11 @@ describe(startDeviceRunSessionPreview, () => {
   beforeEach(() => {
     jest.useFakeTimers();
     captureAsync = jest.fn().mockResolvedValue(image);
-    mutation = jest.fn().mockReturnValue({
-      toPromise: async () => ({
-        data: {
-          deviceRunSession: {
-            createPreviewUploadSession: {
-              uploadSession: {
-                url: 'https://uploads.expo.test/preview',
-                headers: { 'content-type': 'image/webp' },
-              },
-            },
-          },
-        },
-      }),
-    });
-    ctx = { graphqlClient: { mutation } } as unknown as CustomBuildContext;
+    jest
+      .mocked(turtleFetch)
+      .mockReset()
+      .mockImplementation(async () => uploadSessionResponse());
+    ctx = createCtx();
     logger = { warn: jest.fn() } as unknown as bunyan;
     jest
       .mocked(fetch)
@@ -82,7 +95,7 @@ describe(startDeviceRunSessionPreview, () => {
     expect(captureAsync).toHaveBeenCalledTimes(1);
     await jest.advanceTimersByTimeAsync(1);
     expect(captureAsync).toHaveBeenCalledTimes(2);
-    expect(mutation).toHaveBeenCalledTimes(1);
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
     await preview!.stopAsync();
     await jest.advanceTimersByTimeAsync(120_000);
     expect(captureAsync).toHaveBeenCalledTimes(2);
@@ -92,7 +105,7 @@ describe(startDeviceRunSessionPreview, () => {
     captureAsync.mockRejectedValueOnce(new Error('device not ready'));
     start();
     await jest.advanceTimersByTimeAsync(0);
-    expect(mutation).not.toHaveBeenCalled();
+    expect(turtleFetch).not.toHaveBeenCalled();
     expect(logger.warn).toHaveBeenCalled();
     await jest.advanceTimersByTimeAsync(60_000);
     expect(fetch).toHaveBeenCalledTimes(1);
@@ -102,7 +115,7 @@ describe(startDeviceRunSessionPreview, () => {
     jest.mocked(fetch).mockResolvedValueOnce(new Response('', { status: 403 }));
     start();
     await jest.advanceTimersByTimeAsync(60_000);
-    expect(mutation).toHaveBeenCalledTimes(1);
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
     expect(fetch).toHaveBeenCalledTimes(2);
   });
 
@@ -126,7 +139,7 @@ describe(startDeviceRunSessionPreview, () => {
   it('reuses the upload URL for the full session', async () => {
     start();
     await jest.advanceTimersByTimeAsync(119 * 60_000);
-    expect(mutation).toHaveBeenCalledTimes(1);
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
   });
 
   it('does not overlap captures and aborts pending work when stopped', async () => {
@@ -156,29 +169,20 @@ describe(startDeviceRunSessionPreview, () => {
     const stopping = handle.stopAsync();
     finish(image);
     await stopping;
-    expect(mutation).not.toHaveBeenCalled();
+    expect(turtleFetch).not.toHaveBeenCalled();
   });
 });
 
-describe('session preview with the real GraphQL client', () => {
-  const uploadSession = {
-    url: 'https://uploads.expo.test/preview',
-    headers: { 'content-type': 'image/webp' },
-  };
-  let graphqlFetch: jest.SpyInstance;
+describe('session preview upload session from the worker API', () => {
   let preview: ReturnType<typeof startDeviceRunSessionPreview> | undefined;
   let logger: bunyan;
 
   beforeEach(() => {
     jest.useFakeTimers();
-    graphqlFetch = jest.spyOn(globalThis, 'fetch').mockResolvedValue(
-      new globalThis.Response(
-        JSON.stringify({
-          data: { deviceRunSession: { createPreviewUploadSession: { uploadSession } } },
-        }),
-        { headers: { 'content-type': 'application/json' } }
-      )
-    );
+    jest
+      .mocked(turtleFetch)
+      .mockReset()
+      .mockImplementation(async () => uploadSessionResponse());
     logger = { warn: jest.fn() } as unknown as bunyan;
     jest
       .mocked(fetch)
@@ -193,14 +197,9 @@ describe('session preview with the real GraphQL client', () => {
     jest.useRealTimers();
   });
 
-  const start = () => {
-    const graphqlClient = new Client({
-      url: 'https://api.expo.test/graphql',
-      exchanges: [fetchExchange],
-      fetchOptions: { headers: { Authorization: 'Bearer worker-token' } },
-    });
+  const start = (ctx: CustomBuildContext = createCtx()) => {
     preview = startDeviceRunSessionPreview({
-      ctx: { graphqlClient } as CustomBuildContext,
+      ctx,
       deviceRunSessionId: 'session-id',
       captureAsync: async () => Buffer.from('webp-image'),
       logger,
@@ -208,25 +207,49 @@ describe('session preview with the real GraphQL client', () => {
     return preview;
   };
 
-  it('preserves the worker authentication when creating the upload session', async () => {
+  it('sends the device run session token when creating the upload session', async () => {
     start();
     await jest.advanceTimersByTimeAsync(0);
-    const [, options] = graphqlFetch.mock.calls[0];
-    expect(new Headers(options.headers).get('authorization')).toBe('Bearer worker-token');
+    expect(turtleFetch).toHaveBeenCalledWith(
+      PREVIEW_UPLOAD_SESSION_URL,
+      'POST',
+      expect.objectContaining({
+        headers: { [DEVICE_RUN_SESSION_TOKEN_HEADER]: DEVICE_RUN_SESSION_TOKEN },
+        signal: expect.any(AbortSignal),
+      })
+    );
     expect(fetch).toHaveBeenCalledTimes(1);
   });
 
-  it.each(['shutdown', 'timeout'])('aborts a stalled GraphQL request on %s', async reason => {
+  it('logs a failure and uploads nothing when the job has no device run session token', async () => {
+    start({
+      env: {},
+      expoApiV2BaseUrl: 'https://api.expo.test/v2/',
+    } as unknown as CustomBuildContext);
+    await jest.advanceTimersByTimeAsync(0);
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: expect.any(SystemError) },
+      'Could not refresh the session preview; retrying in 60 seconds.'
+    );
+    const [{ err }] = jest.mocked(logger.warn).mock.calls[0] as unknown as [{ err: Error }];
+    expect(err.message).toMatch(
+      /^This device run session job has no EAS_DEVICE_RUN_SESSION_TOKEN secret\./
+    );
+    expect(turtleFetch).not.toHaveBeenCalled();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it.each(['shutdown', 'timeout'])('aborts a stalled worker API request on %s', async reason => {
     const timeout = new AbortController();
     jest.spyOn(AbortSignal, 'timeout').mockReturnValue(timeout.signal);
     let requestSignal: AbortSignal | undefined;
     let rejectRequest!: (error: Error) => void;
-    graphqlFetch.mockImplementation(
-      (_url, options) =>
+    jest.mocked(turtleFetch).mockImplementation(
+      (_url, _method, options) =>
         new Promise((_, reject) => {
           rejectRequest = reject;
-          requestSignal = options.signal;
-          requestSignal!.addEventListener('abort', () => reject(requestSignal!.reason), {
+          requestSignal = options.signal as AbortSignal;
+          requestSignal.addEventListener('abort', () => reject(requestSignal!.reason), {
             once: true,
           });
         })
@@ -255,14 +278,7 @@ describe('session preview with the real GraphQL client', () => {
       await stopping;
     } else {
       expect(logger.warn).toHaveBeenCalled();
-      graphqlFetch.mockResolvedValue(
-        new globalThis.Response(
-          JSON.stringify({
-            data: { deviceRunSession: { createPreviewUploadSession: { uploadSession } } },
-          }),
-          { headers: { 'content-type': 'application/json' } }
-        )
-      );
+      jest.mocked(turtleFetch).mockImplementation(async () => uploadSessionResponse());
       jest.spyOn(AbortSignal, 'timeout').mockReturnValue(new AbortController().signal);
       await jest.advanceTimersByTimeAsync(60_000);
       expect(fetch).toHaveBeenCalledTimes(1);

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

@@ -1,6 +1,5 @@
 import type { bunyan } from '@expo/logger';
 import type { BuildStepEnv } from '@expo/steps';
-import { Client, fetchExchange } from '@urql/core';
 import { execFileSync } from 'node:child_process';
 import { copyFile, mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
 import { type IncomingMessage, type ServerResponse, createServer } from 'node:http';
@@ -25,28 +24,23 @@ let ctx: CustomBuildContext;
 let url: string;
 let directory: string;
 let creationBodies: string[];
+let creationTokens: (string | undefined)[];
 
 beforeEach(async () => {
   creationBodies = [];
+  creationTokens = [];
   directory = await mkdtemp(path.join(tmpdir(), 'recording-recovery-'));
   server = createServer((request, response) => {
-    if (request.url === '/graphql') {
+    if (request.url === '/v2/device-run-session-worker/artifact-upload-sessions') {
       request.setEncoding('utf8');
       let body = '';
       request.on('data', chunk => (body += chunk));
       request.on('end', () => {
         creationBodies.push(body);
+        creationTokens.push(request.headers['expo-device-run-session-token'] as string | undefined);
         response.setHeader('Content-Type', 'application/json');
         response.end(
-          JSON.stringify({
-            data: {
-              deviceRunSession: {
-                createArtifactUploadSession: {
-                  uploadSession: { url: `${url}/artifact`, headers: {} },
-                },
-              },
-            },
-          })
+          JSON.stringify({ data: { uploadSession: { url: `${url}/artifact`, headers: {} } } })
         );
       });
     } else {
@@ -60,12 +54,9 @@ beforeEach(async () => {
   }
   url = `http://127.0.0.1:${address.port}`;
   ctx = {
-    graphqlClient: new Client({
-      url: `${url}/graphql`,
-      exchanges: [fetchExchange],
-      fetchOptions: { headers: { Authorization: 'Bearer test-auth' } },
-    }),
-  } as CustomBuildContext;
+    env: { EAS_DEVICE_RUN_SESSION_TOKEN: 'session-token' },
+    expoApiV2BaseUrl: `${url}/v2/`,
+  } as unknown as CustomBuildContext;
 });
 
 afterEach(async () => {
@@ -181,8 +172,9 @@ it('recovers unlisted recordings from a killed host and flags the unfinished one
     })
   ).resolves.toBe(true);
   expect(putBytes).toBe(3 * (await stat(path.join(cut, 'recording.mp4.partial'))).size);
+  expect(creationTokens).toEqual(['session-token', 'session-token', 'session-token']);
   const inputs = creationBodies
-    .map(body => JSON.parse(body).variables.input)
+    .map(body => JSON.parse(body))
     .sort((a, b) => a.filename.localeCompare(b.filename));
   expect(inputs.map(input => input.filename)).toEqual(['cut.mp4', 'done.mp4', 'failed.mp4']);
   expect(inputs.map(input => input.name.includes(', partial)'))).toEqual([true, false, true]);

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

@@ -1,5 +1,5 @@
 import type { bunyan } from '@expo/logger';
-import { Client, fetchExchange } from '@urql/core';
+import { BuildRuntimePlatform } from '@expo/steps';
 import { mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
 import { type IncomingMessage, type ServerResponse, createServer } from 'node:http';
 import { tmpdir } from 'node:os';
@@ -10,6 +10,7 @@ import {
   screenshotArtifactDetails,
 } from '../deviceRunSessionScreenshotNames';
 import { uploadDeviceRunSessionScreenshotsAsync } from '../deviceRunSessionScreenshots';
+import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 jest.unmock('node-fetch');
 jest.mock('../../../sentry');
 function deferred<T>() {
@@ -26,7 +27,7 @@ let ctx: CustomBuildContext;
 let url: string;
 let directory: string;
 let creates: number;
-let authorization: string | undefined;
+let deviceRunSessionToken: string | string[] | undefined;
 let stallCreation: boolean;
 let creationStarted: ReturnType<typeof deferred<IncomingMessage>>;
 let creationBodies: string[];
@@ -40,42 +41,32 @@ beforeEach(async () => {
   sessionLookups = 0;
   sessionLookupFails = false;
   uploadQuery = '';
-  authorization = undefined;
+  deviceRunSessionToken = undefined;
   stallCreation = false;
   creationBodies = [];
   creationStarted = deferred();
   directory = await mkdtemp(path.join(tmpdir(), 'recording-upload-http-'));
   server = createServer((request, response) => {
-    if (request.url?.startsWith('/graphql')) {
-      authorization = request.headers.authorization;
+    if (request.url?.startsWith('/v2/device-run-session-worker/')) {
+      deviceRunSessionToken = request.headers[DEVICE_RUN_SESSION_TOKEN_HEADER];
       request.setEncoding('utf8');
       let body = '';
-      if (request.method === 'GET') {
-        const requestUrl = new URL(request.url, 'http://localhost');
-        body = JSON.stringify({ query: requestUrl.searchParams.get('query') });
-      }
       request.on('data', chunk => (body += chunk));
       request.on('end', () => {
-        const operation = JSON.parse(body);
-        if (operation.query.includes('query ScreenshotSession')) {
+        if (request.url === '/v2/device-run-session-worker/application') {
           sessionLookups++;
           response.setHeader('Content-Type', 'application/json');
           if (sessionLookupFails) {
+            response.statusCode = 503;
             response.end(JSON.stringify({ errors: [{ message: 'Lookup unavailable' }] }));
           } else {
             response.end(
               JSON.stringify({
                 data: {
-                  deviceRunSessions: {
-                    byId: {
-                      platform: 'IOS',
-                      app: { slug: 'session-project' },
-                      build: {
-                        id: 'installed-build',
-                        gitCommitHash: installedCommit,
-                        app: { slug: 'my-app' },
-                      },
-                    },
+                  build: {
+                    id: 'installed-build',
+                    gitCommitHash: installedCommit,
+                    applicationArchiveUrl: null,
                   },
                 },
               })
@@ -92,13 +83,7 @@ beforeEach(async () => {
         response.setHeader('Content-Type', 'application/json');
         response.end(
           JSON.stringify({
-            data: {
-              deviceRunSession: {
-                createArtifactUploadSession: {
-                  uploadSession: { url: `${url}/artifact${uploadQuery}`, headers: {} },
-                },
-              },
-            },
+            data: { uploadSession: { url: `${url}/artifact${uploadQuery}`, headers: {} } },
           })
         );
       });
@@ -113,12 +98,10 @@ beforeEach(async () => {
   }
   url = `http://127.0.0.1:${address.port}`;
   ctx = {
-    graphqlClient: new Client({
-      url: `${url}/graphql`,
-      exchanges: [fetchExchange],
-      fetchOptions: { headers: { Authorization: 'Bearer test-auth' } },
-    }),
-  } as CustomBuildContext;
+    env: { EAS_DEVICE_RUN_SESSION_TOKEN: 'test-device-run-session-token' },
+    expoApiV2BaseUrl: `${url}/v2/`,
+    runtimePlatform: BuildRuntimePlatform.DARWIN,
+  } as unknown as CustomBuildContext;
 });
 
 afterEach(async () => {
@@ -127,7 +110,7 @@ afterEach(async () => {
   await rm(directory, { recursive: true, force: true });
 });
 
-it('publishes a manual preview PNG through the artifact GraphQL and HTTP upload path', async () => {
+it('publishes a manual preview PNG through the worker API and HTTP upload path', async () => {
   const payload = Buffer.from(
     'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aF9sAAAAASUVORK5CYII=',
     'base64'
@@ -157,25 +140,20 @@ it('publishes a manual preview PNG through the artifact GraphQL and HTTP upload
   expect(bodies).toEqual([payload]);
   expect(creates).toBe(1);
   expect(sessionLookups).toBe(1);
-  expect(authorization).toBe('Bearer test-auth');
-  expect(JSON.parse(creationBodies[0]).variables).toEqual(
-    expect.objectContaining({
-      deviceRunSessionId: 'drs-id',
-      input: expect.objectContaining({
-        name: 'Screenshot 2026-09-24 08:45:59 UTC',
-        filename: 'my-app-ios-a1b2c3d-2026-09-24T08-45-59-123Z.png',
-        kind: 'screenshot',
-        size: payload.length,
-        metadata: {
-          __eas_type: 'screenshot',
-          appSlug: 'my-app',
-          platform: 'ios',
-          buildId: 'installed-build',
-          gitCommitHash: installedCommit,
-        },
-      }),
-    })
-  );
+  expect(deviceRunSessionToken).toBe('test-device-run-session-token');
+  // The worker API does not return the app slug, so the filename starts with the platform.
+  expect(JSON.parse(creationBodies[0])).toEqual({
+    name: 'Screenshot 2026-09-24 08:45:59 UTC',
+    filename: 'ios-a1b2c3d-2026-09-24T08-45-59-123Z.png',
+    kind: 'screenshot',
+    size: payload.length,
+    metadata: {
+      __eas_type: 'screenshot',
+      platform: 'ios',
+      buildId: 'installed-build',
+      gitCommitHash: installedCommit,
+    },
+  });
   await expect(stat(path.join(directory, filename))).rejects.toMatchObject({ code: 'ENOENT' });
 });
 
@@ -206,7 +184,7 @@ it('rereads the PNG when the artifact PUT is retried', async () => {
   await expect(stat(path.join(directory, filename))).rejects.toMatchObject({ code: 'ENOENT' });
 });
 
-it('aborts a stalled GraphQL upload request and keeps the PNG', async () => {
+it('aborts a stalled worker API upload session request and keeps the PNG', async () => {
   stallCreation = true;
   const filename = 'screenshot-2026-09-24T08-45-59-123Z-a1b2c3d4e5f6.png';
   await writeFile(path.join(directory, filename), 'png');

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

@@ -1,6 +1,5 @@
 import type { bunyan } from '@expo/logger';
 import type { BuildStepEnv } from '@expo/steps';
-import { Client, fetchExchange } from '@urql/core';
 import { createReadStream } from 'node:fs';
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { type IncomingMessage, type ServerResponse, createServer } from 'node:http';
@@ -13,6 +12,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 import type { CustomBuildContext } from '../../../customBuildContext';
 import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
 import { findUnlistedDeviceScreenRecordingsAsync } from '../deviceRunSessionScreenRecordings';
+import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 
 jest.unmock('node-fetch');
 jest.unmock('node:fs');
@@ -40,20 +40,20 @@ let ctx: CustomBuildContext;
 let url: string;
 let directory: string;
 let creates: number;
-let authorization: string | undefined;
+let deviceRunSessionToken: string | string[] | undefined;
 let stallCreation: boolean;
 let creationStarted: ReturnType<typeof deferred<IncomingMessage>>;
 
 beforeEach(async () => {
   creates = 0;
-  authorization = undefined;
+  deviceRunSessionToken = undefined;
   stallCreation = false;
   creationStarted = deferred();
   directory = await mkdtemp(path.join(tmpdir(), 'recording-upload-http-'));
   server = createServer((request, response) => {
-    if (request.url === '/graphql') {
+    if (request.url === '/v2/device-run-session-worker/artifact-upload-sessions') {
       creates++;
-      authorization = request.headers.authorization;
+      deviceRunSessionToken = request.headers[DEVICE_RUN_SESSION_TOKEN_HEADER];
       creationStarted.resolve(request);
       request.resume();
       request.on('end', () => {
@@ -63,13 +63,7 @@ beforeEach(async () => {
         response.setHeader('Content-Type', 'application/json');
         response.end(
           JSON.stringify({
-            data: {
-              deviceRunSession: {
-                createArtifactUploadSession: {
-                  uploadSession: { url: `${url}/artifact`, headers: {} },
-                },
-              },
-            },
+            data: { uploadSession: { url: `${url}/artifact`, headers: {} } },
           })
         );
       });
@@ -84,12 +78,9 @@ beforeEach(async () => {
   }
   url = `http://127.0.0.1:${address.port}`;
   ctx = {
-    graphqlClient: new Client({
-      url: `${url}/graphql`,
-      exchanges: [fetchExchange],
-      fetchOptions: { headers: { Authorization: 'Bearer test-auth' } },
-    }),
-  } as CustomBuildContext;
+    env: { EAS_DEVICE_RUN_SESSION_TOKEN: 'test-device-run-session-token' },
+    expoApiV2BaseUrl: `${url}/v2/`,
+  } as unknown as CustomBuildContext;
 });
 
 afterEach(async () => {
@@ -126,7 +117,7 @@ it('replays the full file after a transient PUT failure without recreating the u
     attempts: 3,
   });
   expect(creates).toBe(1);
-  expect(authorization).toBe('Bearer test-auth');
+  expect(deviceRunSessionToken).toBe('test-device-run-session-token');
   expect(bodies).toEqual([payload, payload]);
   expect(streams).toHaveLength(2);
   expect(streams.every(stream => stream.destroyed)).toBe(true);
@@ -281,7 +272,7 @@ it.each([200, 400, 503])(
   }
 );
 
-it('cancels urql session creation with auth intact and never starts a PUT', async () => {
+it('cancels worker API session creation with the token intact and never starts a PUT', async () => {
   stallCreation = true;
   const puts = jest.fn();
   handle = puts;
@@ -298,7 +289,7 @@ it('cancels urql session creation with auth intact and never starts a PUT', asyn
   controller.abort(new Error('test cancellation'));
   await rejected;
   await closed;
-  expect(authorization).toBe('Bearer test-auth');
+  expect(deviceRunSessionToken).toBe('test-device-run-session-token');
   expect(creates).toBe(1);
   expect(puts).not.toHaveBeenCalled();
   expect(openStream).not.toHaveBeenCalled();

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

@@ -7,6 +7,7 @@ import {
   DeviceRunSessionWorkerApi,
   DeviceRunSessionWorkerApiError,
   getDeviceRunSessionWorkerApi,
+  requireDeviceRunSessionWorkerApi,
 } from '../deviceRunSessionWorkerApi';
 
 jest.mock('../../../utils/turtleFetch');
@@ -88,6 +89,36 @@ describe(getDeviceRunSessionWorkerApi, () => {
   });
 });
 
+describe(requireDeviceRunSessionWorkerApi, () => {
+  it('returns the client when the job has a device run session token', () => {
+    expect(
+      requireDeviceRunSessionWorkerApi({
+        env: { EAS_DEVICE_RUN_SESSION_TOKEN: TOKEN },
+        expoApiV2BaseUrl: BASE_URL,
+      } as unknown as CustomBuildContext)
+    ).toBeInstanceOf(DeviceRunSessionWorkerApi);
+  });
+
+  it('throws a system error when the job has no device run session token', () => {
+    const error = (() => {
+      try {
+        requireDeviceRunSessionWorkerApi({
+          env: { __API_SERVER_URL: 'https://api.expo.test' },
+          expoApiV2BaseUrl: BASE_URL,
+        } as unknown as CustomBuildContext);
+      } catch (err) {
+        return err;
+      }
+      return undefined;
+    })();
+
+    expect(error).toBeInstanceOf(SystemError);
+    expect((error as Error).message).toMatch(
+      /^This device run session job has no EAS_DEVICE_RUN_SESSION_TOKEN secret\./
+    );
+  });
+});
+
 describe(DeviceRunSessionWorkerApi, () => {
   beforeEach(() => {
     jest.mocked(turtleFetch).mockReset();
@@ -101,7 +132,7 @@ describe(DeviceRunSessionWorkerApi, () => {
       route: 'session',
       json: undefined,
       data: { id: 'drs-id', status: 'in-progress' },
-      expected: { id: 'drs-id', status: 'IN_PROGRESS' },
+      expected: { id: 'drs-id', status: 'in-progress' },
     },
     {
       name: 'startAsync',
@@ -111,7 +142,7 @@ describe(DeviceRunSessionWorkerApi, () => {
       route: 'start',
       json: { remoteConfig: { type: 'agent-device', url: 'https://x.test' } },
       data: { id: 'drs-id', status: 'in-progress' },
-      expected: { id: 'drs-id', status: 'IN_PROGRESS' },
+      expected: { id: 'drs-id', status: 'in-progress' },
     },
     {
       name: 'stopAsync',
@@ -120,7 +151,7 @@ describe(DeviceRunSessionWorkerApi, () => {
       route: 'stop',
       json: undefined,
       data: { id: 'drs-id', status: 'stopped' },
-      expected: { id: 'drs-id', status: 'STOPPED' },
+      expected: { id: 'drs-id', status: 'stopped' },
     },
     {
       name: 'createArtifactUploadSessionAsync',
@@ -217,20 +248,16 @@ describe(DeviceRunSessionWorkerApi, () => {
     }
   );
 
-  it.each([
-    ['new', 'NEW'],
-    ['queued', 'QUEUED'],
-    ['starting', 'STARTING'],
-    ['in-progress', 'IN_PROGRESS'],
-    ['stopped', 'STOPPED'],
-    ['errored', 'ERRORED'],
-  ])('maps the www status %s to the GraphQL status %s', async (wwwStatus, status) => {
-    jest
-      .mocked(turtleFetch)
-      .mockResolvedValueOnce(jsonResponse({ data: { id: 'drs-id', status: wwwStatus } }));
+  it.each(['new', 'queued', 'starting', 'in-progress', 'stopped', 'errored'])(
+    'returns the www status %s unchanged',
+    async status => {
+      jest
+        .mocked(turtleFetch)
+        .mockResolvedValueOnce(jsonResponse({ data: { id: 'drs-id', status } }));
 
-    await expect(createApi().getSessionAsync()).resolves.toEqual({ id: 'drs-id', status });
-  });
+      await expect(createApi().getSessionAsync()).resolves.toEqual({ id: 'drs-id', status });
+    }
+  );
 
   it('rejects an application response without the build field', async () => {
     jest.mocked(turtleFetch).mockResolvedValueOnce(jsonResponse({ data: { platform: 'ios' } }));

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

@@ -1,6 +1,6 @@
 import { SystemError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
-import { BuildRuntimePlatform, type BuildStepEnv } from '@expo/steps';
+import { BuildRuntimePlatform } from '@expo/steps';
 import fetch from 'node-fetch';
 import { Readable } from 'node:stream';
 import { setImmediate } from 'node:timers/promises';
@@ -105,8 +105,6 @@ async function waitForCallAsync(mock: jest.Mock): Promise<void> {
   }
 }
 
-const env = { DEVICE_RUN_SESSION_ID: 'drs-id' } as unknown as BuildStepEnv;
-
 const eventSource = {
   producer: 'test-producer',
   findEventFilesAsync: async () => [],
@@ -203,7 +201,7 @@ describe('with a device run session token', () => {
       })
     );
 
-    const args = await fetchWebPreviewTurnArgsAsync(ctx, { env, logger });
+    const args = await fetchWebPreviewTurnArgsAsync(ctx, { logger });
 
     expect(args).toEqual([
       '--stun-url',
@@ -426,29 +424,38 @@ describe('with a device run session token', () => {
 });
 
 describe('without a device run session token', () => {
-  it('polls the session status with GraphQL', async () => {
+  const MISSING_TOKEN_MESSAGE =
+    /^This device run session job has no EAS_DEVICE_RUN_SESSION_TOKEN secret\./;
+
+  function expectMissingTokenError(error: unknown): void {
+    expect(error).toBeInstanceOf(SystemError);
+    expect((error as Error).message).toMatch(MISSING_TOKEN_MESSAGE);
+  }
+
+  function expectMissingTokenWarning(message: string): void {
+    const warning = (jest.mocked(logger.warn).mock.calls as unknown[][]).find(
+      ([, warningMessage]) => warningMessage === message
+    );
+    expect(warning).toBeDefined();
+    expectMissingTokenError((warning![0] as { err: unknown }).err);
+  }
+
+  it('fails the status poll with a system error', async () => {
     const ctx = createCtx({ withToken: false });
-    jest
-      .mocked(ctx.graphqlClient.query)
-      .mockReturnValueOnce(
-        graphqlResult({ deviceRunSessions: { byId: { id: 'drs-id', status: 'STOPPED' } } }) as never
-      );
 
-    await waitForDeviceRunSessionStoppedAsync({ ctx, deviceRunSessionId: 'drs-id', logger });
-
-    expect(ctx.graphqlClient.query).toHaveBeenCalledWith(expect.anything(), {
+    const error = await waitForDeviceRunSessionStoppedAsync({
+      ctx,
       deviceRunSessionId: 'drs-id',
-    });
+      logger,
+    }).catch(err => err);
+
+    expectMissingTokenError(error);
     expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+    expect(ctx.graphqlClient.query).not.toHaveBeenCalled();
   });
 
-  it('stops an idle session with GraphQL', async () => {
+  it('logs the failed idle stop and ends the wait', async () => {
     const ctx = createCtx({ withToken: false });
-    jest.mocked(ctx.graphqlClient.mutation).mockReturnValueOnce(
-      graphqlResult({
-        deviceRunSession: { ensureDeviceRunSessionStopped: { id: 'drs-id', status: 'STOPPED' } },
-      }) as never
-    );
 
     await waitForDeviceRunSessionStoppedAsync({
       ctx,
@@ -457,65 +464,43 @@ describe('without a device run session token', () => {
       idleTimeout: { maxIdleTimeMinutes: 0, getLastEventObservedAt: () => undefined },
     });
 
-    expect(ctx.graphqlClient.mutation).toHaveBeenCalledWith(expect.anything(), {
-      deviceRunSessionId: 'drs-id',
-    });
+    expectMissingTokenWarning(
+      'Could not mark device run session drs-id as stopped. The session job ends anyway.'
+    );
     expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+    expect(ctx.graphqlClient.mutation).not.toHaveBeenCalled();
   });
 
-  it('starts the session with GraphQL', async () => {
+  it('fails the start with a system error', async () => {
     const ctx = createCtx({ withToken: false });
-    jest.mocked(ctx.graphqlClient.mutation).mockReturnValueOnce(
-      graphqlResult({
-        deviceRunSession: { startDeviceRunSession: { id: 'drs-id', status: 'IN_PROGRESS' } },
-      }) as never
-    );
 
-    await uploadRemoteSessionConfigAsync({
+    const error = await uploadRemoteSessionConfigAsync({
       ctx,
       deviceRunSessionId: 'drs-id',
       remoteConfig: { type: 'agent-device' },
       logger,
-    });
+    }).catch(err => err);
 
-    expect(ctx.graphqlClient.mutation).toHaveBeenCalledWith(expect.anything(), {
-      deviceRunSessionId: 'drs-id',
-      remoteConfig: { type: 'agent-device' },
-    });
+    expectMissingTokenError(error);
+    expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+    expect(ctx.graphqlClient.mutation).not.toHaveBeenCalled();
+  });
+
+  it('falls back to no TURN ICE servers', async () => {
+    const ctx = createCtx({ withToken: false });
+
+    await expect(fetchWebPreviewTurnArgsAsync(ctx, { logger })).resolves.toEqual([]);
+
+    expectMissingTokenWarning(
+      'Could not fetch Cloudflare TURN ICE servers; the web preview will fall back to P2P/STUN.'
+    );
     expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
   });
 
-  it('fetches TURN ICE servers from the device run sessions route with the robot token', async () => {
+  it('fails the artifact upload with a system error before any PUT', async () => {
     const ctx = createCtx({ withToken: false });
-    jest.mocked(turtleFetch).mockResolvedValueOnce(jsonResponse({ data: { iceServers: [] } }));
 
-    await fetchWebPreviewTurnArgsAsync(ctx, { env, logger });
-
-    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_ACCESS_TOKEN}` },
-        timeout: 5000,
-        retries: 1,
-      })
-    );
-  });
-
-  it('creates artifact upload sessions with GraphQL', async () => {
-    const ctx = createCtx({ withToken: false });
-    jest.mocked(ctx.graphqlClient.mutation).mockReturnValueOnce(
-      graphqlResult({
-        deviceRunSession: {
-          createArtifactUploadSession: {
-            uploadSession: { url: 'https://uploads.expo.test/artifact', headers: {} },
-          },
-        },
-      }) as never
-    );
-    jest.mocked(fetch).mockResolvedValueOnce(new Response('', { status: 200 }));
-
-    await uploadDeviceRunSessionArtifactAsync(ctx, {
+    const error = await uploadDeviceRunSessionArtifactAsync(ctx, {
       deviceRunSessionId: 'drs-id',
       artifactId: 'artifact-id',
       name: 'Report',
@@ -523,23 +508,16 @@ describe('without a device run session token', () => {
       kind: undefined,
       size: 4,
       openStream: () => Readable.from(Buffer.from('data')),
-    });
+    }).catch(err => err);
 
-    expect(ctx.graphqlClient.mutation).toHaveBeenCalled();
+    expectMissingTokenError(error);
     expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+    expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+    expect(ctx.graphqlClient.mutation).not.toHaveBeenCalled();
   });
 
-  it('creates the event log upload session with GraphQL', async () => {
+  it('runs the session without persisting events', async () => {
     const ctx = createCtx({ withToken: false });
-    jest.mocked(ctx.graphqlClient.mutation).mockReturnValueOnce(
-      graphqlResult({
-        deviceRunSession: {
-          createEventLogUploadSession: {
-            uploadSession: { url: 'https://uploads.expo.test/events', headers: {} },
-          },
-        },
-      }) as never
-    );
 
     const collection = await startDeviceRunSessionEventCollectionAsync({
       ctx,
@@ -549,24 +527,14 @@ describe('without a device run session token', () => {
     });
     await collection.stopAsync();
 
-    expect(ctx.graphqlClient.mutation).toHaveBeenCalledWith(expect.anything(), {
-      deviceRunSessionId: 'drs-id',
-    });
+    expectMissingTokenWarning('Could not persist device run session events to the artifact.');
+    expect(jest.mocked(RemoteLoggerStream)).not.toHaveBeenCalled();
     expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+    expect(ctx.graphqlClient.mutation).not.toHaveBeenCalled();
   });
 
-  it('creates the preview upload session with GraphQL', async () => {
+  it('logs the failed preview upload session and uploads no preview', async () => {
     const ctx = createCtx({ withToken: false });
-    jest.mocked(ctx.graphqlClient.mutation).mockReturnValueOnce(
-      graphqlResult({
-        deviceRunSession: {
-          createPreviewUploadSession: {
-            uploadSession: { url: 'https://uploads.expo.test/preview', headers: {} },
-          },
-        },
-      }) as never
-    );
-    jest.mocked(fetch).mockResolvedValue(new Response('', { status: 200 }));
 
     const preview = startDeviceRunSessionPreview({
       ctx,
@@ -574,29 +542,25 @@ describe('without a device run session token', () => {
       captureAsync: async () => Buffer.from('webp'),
       logger,
     });
-    await waitForCallAsync(jest.mocked(fetch));
+    await waitForCallAsync(jest.mocked(logger.warn));
     await preview.stopAsync();
 
-    expect(ctx.graphqlClient.mutation).toHaveBeenCalled();
+    expectMissingTokenWarning('Could not refresh the session preview; retrying in 60 seconds.');
     expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+    expect(jest.mocked(fetch)).not.toHaveBeenCalled();
+    expect(ctx.graphqlClient.mutation).not.toHaveBeenCalled();
   });
 
-  it('loads the screenshot naming details with GraphQL', async () => {
+  it('names screenshots with capture timestamps', async () => {
     const ctx = createCtx({ withToken: false });
-    jest.mocked(ctx.graphqlClient.query).mockReturnValueOnce(
-      graphqlResult({
-        deviceRunSessions: {
-          byId: { platform: 'ANDROID', app: { slug: 'app' }, build: null },
-        },
-      }) as never
-    );
 
-    await expect(loadScreenshotSessionAsync(ctx, 'drs-id', logger)).resolves.toEqual({
-      platform: 'ANDROID',
-      app: { slug: 'app' },
-      build: null,
-    });
+    await expect(loadScreenshotSessionAsync(ctx, 'drs-id', logger)).resolves.toBeNull();
+
+    expectMissingTokenWarning(
+      'Could not load screenshot session details; using capture timestamps.'
+    );
     expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+    expect(ctx.graphqlClient.query).not.toHaveBeenCalled();
   });
 
   it('looks up the build archive URL with GraphQL', async () => {

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

@@ -874,6 +874,23 @@ it.each([
   await host.finishAsync();
 });
 
+it('lets the session add frame ancestors and CORS origins after the website origins', async () => {
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.LINUX,
+    env,
+    logger,
+    separateLogPhase: true,
+    timeoutMs: 10_000,
+    frameAncestors: ['https://embed.example.test', 'https://*.example.test'],
+    corsOrigins: ['https://app.example.test'],
+  });
+  const { args } = jest.mocked(spawnDetached).mock.calls[0][0];
+  expect(args.join(' ')).toContain(
+    '--frame-ancestor https://expo.dev --frame-ancestor https://embed.example.test --frame-ancestor https://*.example.test --cors-origin https://app.example.test'
+  );
+  await host.finishAsync();
+});
+
 it('stops when expo-device-hub records no session token', async () => {
   jest.mocked(spawnDetached).mockImplementationOnce(options => {
     const flag = options.args.indexOf('--android-recording-directory');

packages/build-tools/src/steps/utils/__tests__/remoteDeviceRunSession.test.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 { BuildRuntimePlatform, BuildStepEnv, BuildStepInputValueTypeName } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
@@ -26,7 +26,10 @@ import * as remoteDeviceRunSession from '../remoteDeviceRunSession';
 import { readServeSimServersAsync } from '../serveSimMetricsRecorder';
 import { sleepAsync } from '../../../utils/retry';
 import { uploadDeviceRunSessionScreenRecordingsAsync } from '../deviceRunSessionScreenRecordings';
+import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 import {
+  createCorsOriginsInputProvider,
+  createFrameAncestorsInputProvider,
   createIosSessionStartupInputProviders,
   createPrivatePreviewUrlInputProvider,
   createPublicPreviewInputProvider,
@@ -34,6 +37,8 @@ import {
   describeServeSimLaunch,
   ensureFfmpegInstalledOnceAsync,
   fetchWebPreviewTurnArgsAsync,
+  parseCorsOriginsInput,
+  parseFrameAncestorsInput,
   parseServeSimLaunchInputs,
   spawnDetached,
   startNgrokTunnelAsync,
@@ -44,8 +49,10 @@ import {
 
 import {
   EXPO_DEVICE_HUB_STATE_DIR,
+  corsOriginArgs,
   createExpoDeviceHubArgs,
   createServeSimArgs,
+  frameAncestorArgs,
   simulatorPreviewPageUrl,
   startDeviceSessionHostAsync,
   waitForWebPreviewReadyAsync,
@@ -148,73 +155,70 @@ describe(spawnDetached, () => {
   );
 });
 
-function createCtxMock(): CustomBuildContext {
+const DEVICE_RUN_SESSION_TOKEN = 'device-run-session-token';
+const DEVICE_RUN_SESSION_WORKER_URL = 'https://api.expo.test/v2/device-run-session-worker/';
+
+function createCtxMock({ withToken = true }: { withToken?: boolean } = {}): CustomBuildContext {
   return {
     env: {
       __API_SERVER_URL: 'https://api.expo.test',
+      ...(withToken ? { EAS_DEVICE_RUN_SESSION_TOKEN: DEVICE_RUN_SESSION_TOKEN } : {}),
     },
+    expoApiV2BaseUrl: 'https://api.expo.test/v2/',
     job: {
       secrets: { robotAccessToken: 'robot-token' },
     },
   } as unknown as CustomBuildContext;
 }
 
+/** A successful device run session worker API response with the `{ data }` body. */
+function workerApiResponse(data: unknown): Awaited<ReturnType<typeof turtleFetch>> {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => ({ data }),
+  } as unknown as Awaited<ReturnType<typeof turtleFetch>>;
+}
+
+/** The number of device run session worker API requests to the route. */
+function workerApiCallCount(route: string): number {
+  return jest
+    .mocked(turtleFetch)
+    .mock.calls.filter(([url]) => url === `${DEVICE_RUN_SESSION_WORKER_URL}${route}`).length;
+}
+
+/**
+ * Serves session status polls from `results` in order, and idle stops, through the device run
+ * session worker API.
+ */
 function createStatusCtxMock(
   results: (
-    | { status: 'NEW' | 'IN_PROGRESS' | 'STOPPED' | 'ERRORED' }
+    | { status: 'new' | 'in-progress' | 'stopped' | 'errored' }
     | { error: Error }
     | { data: unknown }
   )[],
-  { ensureStoppedError }: { ensureStoppedError?: Error } = {}
+  { stopError }: { stopError?: Error } = {}
 ): CustomBuildContext {
-  const query = jest.fn(() => {
+  jest.mocked(turtleFetch).mockImplementation(async url => {
+    if (url === `${DEVICE_RUN_SESSION_WORKER_URL}stop`) {
+      if (stopError) {
+        throw stopError;
+      }
+      return workerApiResponse({ id: 'drs-id', status: 'stopped' });
+    }
     const result = results.shift();
     if (!result) {
       throw new Error('No mocked status result available');
     }
-    return {
-      toPromise: async () => {
-        if ('error' in result) {
-          throw result.error;
-        }
-        if ('data' in result) {
-          return { data: result.data };
-        }
-        return {
-          data: {
-            deviceRunSessions: {
-              byId: {
-                id: 'drs-id',
-                status: result.status,
-              },
-            },
-          },
-        };
-      },
-    };
+    if ('error' in result) {
+      throw result.error;
+    }
+    if ('data' in result) {
+      return workerApiResponse(result.data);
+    }
+    return workerApiResponse({ id: 'drs-id', status: result.status });
   });
-
-  const mutation = jest.fn(() => ({
-    toPromise: async () => {
-      if (ensureStoppedError) {
-        return { error: ensureStoppedError };
-      }
-      return {
-        data: {
-          deviceRunSession: {
-            ensureDeviceRunSessionStopped: { id: 'drs-id', status: 'STOPPED' },
-          },
-        },
-      };
-    },
-  }));
-
-  return {
-    graphqlClient: {
-      query,
-      mutation,
-    },
-  } as unknown as CustomBuildContext;
+  return createCtxMock();
 }
 
 function createEnvMock(): BuildStepEnv {
@@ -321,6 +325,88 @@ describe(createPrivatePreviewUrlInputProvider, () => {
   });
 });
 
+describe(createFrameAncestorsInputProvider, () => {
+  it('accepts an optional JSON list of origins from the session job', () => {
+    const input = createFrameAncestorsInputProvider()(createGlobalContextMock(), 'step-id');
+    expect(input).toMatchObject({
+      id: 'frame_ancestors',
+      required: false,
+      allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+    });
+  });
+});
+
+describe(parseFrameAncestorsInput, () => {
+  it('defaults to no extra origins when the step declares nothing', () => {
+    expect(parseFrameAncestorsInput(undefined)).toEqual([]);
+  });
+
+  it('returns the origins as given', () => {
+    expect(
+      parseFrameAncestorsInput(['https://embed.example.test', 'https://*.example.test'])
+    ).toEqual(['https://embed.example.test', 'https://*.example.test']);
+  });
+
+  it.each([['https://embed.example.test'], [['https://embed.example.test', '']], [[1]]])(
+    'rejects %j',
+    value => {
+      expect(() => parseFrameAncestorsInput(value)).toThrow(
+        'Input "frame_ancestors" must be an array of non-empty strings, one origin each.'
+      );
+    }
+  );
+});
+
+describe(createCorsOriginsInputProvider, () => {
+  it('accepts an optional JSON list of origins from the session job', () => {
+    const input = createCorsOriginsInputProvider()(createGlobalContextMock(), 'step-id');
+    expect(input).toMatchObject({
+      id: 'cors_origins',
+      required: false,
+      allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+    });
+  });
+});
+
+describe(parseCorsOriginsInput, () => {
+  it('defaults to no extra origins and returns the origins as given', () => {
+    expect(parseCorsOriginsInput(undefined)).toEqual([]);
+    expect(parseCorsOriginsInput(['https://app.example.test'])).toEqual([
+      'https://app.example.test',
+    ]);
+  });
+
+  it('rejects anything but a list of non-empty strings', () => {
+    expect(() => parseCorsOriginsInput(['https://app.example.test', ''])).toThrow(
+      'Input "cors_origins" must be an array of non-empty strings, one origin each.'
+    );
+  });
+});
+
+describe(corsOriginArgs, () => {
+  it('repeats the flag once per origin', () => {
+    expect(corsOriginArgs(['https://a.example.test', 'https://b.example.test'])).toEqual([
+      '--cors-origin',
+      'https://a.example.test',
+      '--cors-origin',
+      'https://b.example.test',
+    ]);
+    expect(corsOriginArgs([])).toEqual([]);
+  });
+});
+
+describe(frameAncestorArgs, () => {
+  it('repeats the flag once per origin', () => {
+    expect(frameAncestorArgs(['https://a.example.test', 'https://b.example.test'])).toEqual([
+      '--frame-ancestor',
+      'https://a.example.test',
+      '--frame-ancestor',
+      'https://b.example.test',
+    ]);
+    expect(frameAncestorArgs([])).toEqual([]);
+  });
+});
+
 describe(parseServeSimLaunchInputs, () => {
   const darwin = { runtimePlatform: BuildRuntimePlatform.DARWIN };
 
@@ -488,6 +574,26 @@ describe(createServeSimArgs, () => {
     ]);
   });
 
+  it('appends the session frame ancestors after the website args', () => {
+    const args = createServeSimArgs({
+      port: 4321,
+      websiteArgs: ['--frame-ancestor', 'https://expo.dev'],
+      frameAncestorArgs: ['--frame-ancestor', 'https://embed.example.test'],
+      corsOriginArgs: ['--cors-origin', 'https://app.example.test'],
+      shareUrl: 'https://expo.dev/simulator-preview/preview-id',
+    });
+    expect(args.slice(-8)).toEqual([
+      '--frame-ancestor',
+      'https://expo.dev',
+      '--frame-ancestor',
+      'https://embed.example.test',
+      '--cors-origin',
+      'https://app.example.test',
+      '--share-url',
+      'https://expo.dev/simulator-preview/preview-id',
+    ]);
+  });
+
   it('pins the requested package version', () => {
     expect(createServeSimArgs({ port: 4321, packageVersion: '0.1.38' })[0]).toBe(
       '@expo/[email protected]'
@@ -685,6 +791,23 @@ describe(createExpoDeviceHubArgs, () => {
     ]);
   });
 
+  it('appends the session frame ancestors after the website args', () => {
+    const args = createExpoDeviceHubArgs({
+      port: 4321,
+      websiteArgs: ['--frame-ancestor', 'https://expo.dev'],
+      frameAncestorArgs: ['--frame-ancestor', 'https://embed.example.test'],
+      corsOriginArgs: ['--cors-origin', 'https://app.example.test'],
+    });
+    expect(args.slice(-6)).toEqual([
+      '--frame-ancestor',
+      'https://expo.dev',
+      '--frame-ancestor',
+      'https://embed.example.test',
+      '--cors-origin',
+      'https://app.example.test',
+    ]);
+  });
+
   it('pins the requested package version', () => {
     expect(createExpoDeviceHubArgs({ port: 4321, packageVersion: '0.7.0' })[0]).toBe(
       '[email protected]'
@@ -973,6 +1096,8 @@ describe(startDeviceSessionHostAsync, () => {
     jest.mocked(turtleFetch).mockImplementation(async url => {
       if (url.endsWith('/turn-ice-servers')) {
         return {
+          ok: true,
+          status: 200,
           json: async () => ({
             data: {
               iceServers: [
@@ -1470,24 +1595,21 @@ describe(fetchWebPreviewTurnArgsAsync, () => {
     jest.mocked(turtleFetch).mockReset();
   });
 
-  it('requests TURN ICE servers from the device run session endpoint and returns web preview 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>>);
+  it('requests TURN ICE servers from the device run session worker API and returns web preview args', async () => {
+    jest.mocked(turtleFetch).mockResolvedValue(
+      workerApiResponse({
+        iceServers: [
+          { urls: ['stun:stun.cloudflare.com:3478'] },
+          {
+            urls: ['turns:turn.cloudflare.com:443?transport=tcp'],
+            username: 'u',
+            credential: 'c',
+          },
+        ],
+      })
+    );
 
     const args = await fetchWebPreviewTurnArgsAsync(createCtxMock(), {
-      env: createEnvMock(),
       logger: createLoggerMock(),
     });
 
@@ -1502,10 +1624,10 @@ describe(fetchWebPreviewTurnArgsAsync, () => {
       'c',
     ]);
     expect(jest.mocked(turtleFetch)).toHaveBeenCalledWith(
-      'https://api.expo.test/v2/device-run-sessions/drs-id/turn-ice-servers',
+      `${DEVICE_RUN_SESSION_WORKER_URL}turn-ice-servers`,
       'POST',
       expect.objectContaining({
-        headers: { Authorization: 'Bearer robot-token' },
+        headers: { [DEVICE_RUN_SESSION_TOKEN_HEADER]: DEVICE_RUN_SESSION_TOKEN },
       })
     );
   });
@@ -1514,15 +1636,33 @@ describe(fetchWebPreviewTurnArgsAsync, () => {
     jest.mocked(turtleFetch).mockRejectedValue(new Error('boom'));
     const logger = createLoggerMock();
 
-    const args = await fetchWebPreviewTurnArgsAsync(createCtxMock(), {
-      env: createEnvMock(),
-      logger,
-    });
+    const args = await fetchWebPreviewTurnArgsAsync(createCtxMock(), { logger });
 
     expect(args).toEqual([]);
     expect(logger.warn).toHaveBeenCalled();
     expect(jest.mocked(Sentry).capture).toHaveBeenCalled();
   });
+
+  it('returns [] and warns when the job has no device run session token', async () => {
+    const logger = createLoggerMock();
+
+    const args = await fetchWebPreviewTurnArgsAsync(createCtxMock({ withToken: false }), {
+      logger,
+    });
+
+    expect(args).toEqual([]);
+    expect(logger.warn).toHaveBeenCalledWith(
+      {
+        err: expect.objectContaining({
+          message: expect.stringMatching(
+            /^This device run session job has no EAS_DEVICE_RUN_SESSION_TOKEN secret\./
+          ),
+        }),
+      },
+      'Could not fetch Cloudflare TURN ICE servers; the web preview will fall back to P2P/STUN.'
+    );
+    expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+  });
 });
 
 describe(waitForDeviceRunSessionStoppedAsync, () => {
@@ -1538,7 +1678,7 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
   });
 
   it('continues polling until the device run session is stopped', async () => {
-    const ctx = createStatusCtxMock([{ status: 'IN_PROGRESS' }, { status: 'STOPPED' }]);
+    const ctx = createStatusCtxMock([{ status: 'in-progress' }, { status: 'stopped' }]);
     const logger = createLoggerMock();
 
     await waitForDeviceRunSessionStoppedAsync({
@@ -1547,13 +1687,59 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
       logger,
     });
 
-    expect(ctx.graphqlClient.query).toHaveBeenCalledTimes(2);
+    expect(workerApiCallCount('session')).toBe(2);
     expect(logger.info).toHaveBeenCalledWith('Device run session drs-id was stopped.');
     expect(setTimeoutCallback).not.toHaveBeenCalled();
   });
 
+  it('polls the session status through the worker API with the abort signal', async () => {
+    const ctx = createStatusCtxMock([{ status: 'stopped' }]);
+
+    await waitForDeviceRunSessionStoppedAsync({
+      ctx,
+      deviceRunSessionId: 'drs-id',
+      logger: createLoggerMock(),
+    });
+
+    expect(jest.mocked(turtleFetch)).toHaveBeenCalledWith(
+      `${DEVICE_RUN_SESSION_WORKER_URL}session`,
+      'GET',
+      expect.objectContaining({
+        headers: { [DEVICE_RUN_SESSION_TOKEN_HEADER]: DEVICE_RUN_SESSION_TOKEN },
+        signal: expect.any(AbortSignal),
+        timeout: 30_000,
+      })
+    );
+  });
+
+  it('keeps polling while the session status is new', async () => {
+    const ctx = createStatusCtxMock([{ status: 'new' }, { status: 'stopped' }]);
+
+    await waitForDeviceRunSessionStoppedAsync({
+      ctx,
+      deviceRunSessionId: 'drs-id',
+      logger: createLoggerMock(),
+    });
+
+    expect(workerApiCallCount('session')).toBe(2);
+  });
+
+  it('fails with a system error when the job has no device run session token', async () => {
+    const error = await waitForDeviceRunSessionStoppedAsync({
+      ctx: createCtxMock({ withToken: false }),
+      deviceRunSessionId: 'drs-id',
+      logger: createLoggerMock(),
+    }).catch(err => err);
+
+    expect(error).toBeInstanceOf(SystemError);
+    expect(error.message).toMatch(
+      /^This device run session job has no EAS_DEVICE_RUN_SESSION_TOKEN secret\./
+    );
+    expect(jest.mocked(turtleFetch)).not.toHaveBeenCalled();
+  });
+
   it('returns normally when the maximum duration elapses', async () => {
-    const ctx = createStatusCtxMock([{ status: 'IN_PROGRESS' }]);
+    const ctx = createStatusCtxMock([{ status: 'in-progress' }]);
     const logger = createLoggerMock();
     const waitPromise = waitForDeviceRunSessionStoppedAsync({
       ctx,
@@ -1567,7 +1753,7 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
     durationTimeoutCallback();
     await waitPromise;
 
-    expect(ctx.graphqlClient.query).toHaveBeenCalledTimes(1);
+    expect(workerApiCallCount('session')).toBe(1);
     expect(logger.info).toHaveBeenCalledWith(
       'Device run session drs-id reached its maximum duration.'
     );
@@ -1576,7 +1762,7 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
 
   it('clears the duration timeout when the session stops first', async () => {
     await waitForDeviceRunSessionStoppedAsync({
-      ctx: createStatusCtxMock([{ status: 'STOPPED' }]),
+      ctx: createStatusCtxMock([{ status: 'stopped' }]),
       deviceRunSessionId: 'drs-id',
       logger: createLoggerMock(),
       maxDurationSeconds: 30,
@@ -1598,12 +1784,12 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
       signal: abortController.signal,
     });
 
-    expect(ctx.graphqlClient.query).not.toHaveBeenCalled();
+    expect(workerApiCallCount('session')).toBe(0);
     expect(setTimeoutCallback).not.toHaveBeenCalled();
   });
 
   it('throws when the device run session errors', async () => {
-    const ctx = createStatusCtxMock([{ status: 'ERRORED' }]);
+    const ctx = createStatusCtxMock([{ status: 'errored' }]);
 
     await expect(
       waitForDeviceRunSessionStoppedAsync({
@@ -1617,7 +1803,7 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
   });
 
   it('clears the duration timeout when the build step is aborted', async () => {
-    const ctx = createStatusCtxMock([{ status: 'IN_PROGRESS' }]);
+    const ctx = createStatusCtxMock([{ status: 'in-progress' }]);
     const abortController = new AbortController();
     const waitPromise = waitForDeviceRunSessionStoppedAsync({
       ctx,
@@ -1630,12 +1816,12 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
     abortController.abort();
     await waitPromise;
 
-    expect(ctx.graphqlClient.query).toHaveBeenCalledTimes(1);
+    expect(workerApiCallCount('session')).toBe(1);
     expect(clearTimeoutCallback).toHaveBeenCalledWith(durationTimeout);
   });
 
   it('logs and retries transient polling errors', async () => {
-    const ctx = createStatusCtxMock([{ error: new Error('network down') }, { status: 'STOPPED' }]);
+    const ctx = createStatusCtxMock([{ error: new Error('network down') }, { status: 'stopped' }]);
     const logger = createLoggerMock();
 
     await waitForDeviceRunSessionStoppedAsync({
@@ -1644,7 +1830,7 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
       logger,
     });
 
-    expect(ctx.graphqlClient.query).toHaveBeenCalledTimes(2);
+    expect(workerApiCallCount('session')).toBe(2);
     expect(logger.warn).toHaveBeenCalledWith(
       expect.objectContaining({ failedStatusPollCount: 1 }),
       'Could not poll device run session status; will retry.'
@@ -1656,11 +1842,8 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
     );
   });
 
-  it('logs and retries when the status response is missing', async () => {
-    const ctx = createStatusCtxMock([
-      { data: { deviceRunSessions: { byId: null } } },
-      { status: 'STOPPED' },
-    ]);
+  it('logs and retries when the status response does not match the route contract', async () => {
+    const ctx = createStatusCtxMock([{ data: { id: 'drs-id' } }, { status: 'stopped' }]);
     const logger = createLoggerMock();
 
     await waitForDeviceRunSessionStoppedAsync({
@@ -1669,7 +1852,7 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
       logger,
     });
 
-    expect(ctx.graphqlClient.query).toHaveBeenCalledTimes(2);
+    expect(workerApiCallCount('session')).toBe(2);
     expect(logger.warn).toHaveBeenCalledWith(
       expect.objectContaining({ failedStatusPollCount: 1 }),
       'Could not poll device run session status; will retry.'
@@ -1677,7 +1860,9 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
     expect(jest.mocked(Sentry).capture).toHaveBeenCalledWith(
       'Could not poll device run session status',
       expect.objectContaining({
-        message: 'Device run session drs-id status response was missing.',
+        message: expect.stringContaining(
+          'GET /v2/device-run-session-worker/session returned an unexpected response'
+        ),
       }),
       { level: 'warning' }
     );
@@ -1698,8 +1883,8 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
       jest.useRealTimers();
     });
 
-    function manyInProgressStatuses(): { status: 'IN_PROGRESS' }[] {
-      return Array.from({ length: 20 }, () => ({ status: 'IN_PROGRESS' as const }));
+    function manyInProgressStatuses(): { status: 'in-progress' }[] {
+      return Array.from({ length: 20 }, () => ({ status: 'in-progress' as const }));
     }
 
     it('stops the session when no activity is observed within the max idle time', async () => {
@@ -1717,15 +1902,15 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
       });
 
       // One minute at the 5-second poll interval is 12 status polls.
-      expect(ctx.graphqlClient.query).toHaveBeenCalledTimes(12);
-      expect(ctx.graphqlClient.mutation).toHaveBeenCalledTimes(1);
+      expect(workerApiCallCount('session')).toBe(12);
+      expect(workerApiCallCount('stop')).toBe(1);
       expect(logger.info).toHaveBeenCalledWith(
         'Device run session drs-id had no activity for 1 minute(s) (max idle time). Stopping the session.'
       );
     });
 
     it('keeps the session alive while events keep arriving', async () => {
-      const ctx = createStatusCtxMock([...manyInProgressStatuses(), { status: 'STOPPED' }]);
+      const ctx = createStatusCtxMock([...manyInProgressStatuses(), { status: 'stopped' }]);
       const logger = createLoggerMock();
 
       await waitForDeviceRunSessionStoppedAsync({
@@ -1740,14 +1925,14 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
         },
       });
 
-      expect(ctx.graphqlClient.query).toHaveBeenCalledTimes(21);
-      expect(ctx.graphqlClient.mutation).not.toHaveBeenCalled();
+      expect(workerApiCallCount('session')).toBe(21);
+      expect(workerApiCallCount('stop')).toBe(0);
       expect(logger.info).toHaveBeenCalledWith('Device run session drs-id was stopped.');
     });
 
     it('still returns when the session cannot be marked stopped', async () => {
       const ctx = createStatusCtxMock(manyInProgressStatuses(), {
-        ensureStoppedError: new Error('forbidden'),
+        stopError: new Error('forbidden'),
       });
       const logger = createLoggerMock();
 
@@ -1761,7 +1946,7 @@ describe(waitForDeviceRunSessionStoppedAsync, () => {
         },
       });
 
-      expect(ctx.graphqlClient.mutation).toHaveBeenCalledTimes(1);
+      expect(workerApiCallCount('stop')).toBe(1);
       expect(logger.warn).toHaveBeenCalledWith(
         { err: expect.any(Error) },
         'Could not mark device run session drs-id as stopped. The session job ends anyway.'

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

@@ -6,11 +6,13 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { type CustomBuildContext } from '../../../customBuildContext';
+import { DEVICE_RUN_SESSION_TOKEN_HEADER } from '../deviceRunSessionWorkerApi';
 import { uploadServeSimLogsFileAsync } from '../serveSimLogsArtifacts';
 import { streamServeSimLogsToFileAsync } from '../serveSimLogsRecorder';
 
 // This test exercises actual sockets, UTF-8 decoding, files, and PUT uploads.
-// Only WWW's allocation response is substituted; it does not verify cloud storage.
+// WWW's device run session worker API is served by the local server; it does not verify cloud
+// storage.
 jest.mock('../../../sentry');
 jest.unmock('fs');
 jest.unmock('node:fs');
@@ -55,7 +57,29 @@ it('streams selected-device logs into NDJSON and uploads the exact bytes as a se
   let streamRequest: { url?: string; authorization?: string } | undefined;
   let uploaded: Buffer | undefined;
   let uploadedLength: string | undefined;
+  let uploadSessionRequest: { token?: string | string[]; body: unknown } | undefined;
   server.on('request', (request, response) => {
+    if (request.url === '/v2/device-run-session-worker/artifact-upload-sessions') {
+      const chunks: Buffer[] = [];
+      request.on('data', chunk => chunks.push(Buffer.from(chunk)));
+      request.on('end', () => {
+        uploadSessionRequest = {
+          token: request.headers[DEVICE_RUN_SESSION_TOKEN_HEADER],
+          body: JSON.parse(Buffer.concat(chunks).toString('utf8')),
+        };
+        response.writeHead(200, { 'Content-Type': 'application/json' }).end(
+          JSON.stringify({
+            data: {
+              uploadSession: {
+                url: `${baseUrl}/upload`,
+                headers: { 'Content-Length': String(expected.length) },
+              },
+            },
+          })
+        );
+      });
+      return;
+    }
     if (request.method === 'GET') {
       streamRequest = { url: request.url, authorization: request.headers.authorization };
       response.writeHead(200, {
@@ -95,27 +119,16 @@ it('streams selected-device logs into NDJSON and uploads the exact bytes as a se
   });
   expect(await readFile(filePath)).toEqual(expected);
 
-  const mutation = jest.fn().mockReturnValue({
-    toPromise: async () => ({
-      data: {
-        deviceRunSession: {
-          createArtifactUploadSession: {
-            uploadSession: {
-              url: `${baseUrl}/upload`,
-              headers: { 'Content-Length': String(expected.length) },
-            },
-          },
-        },
-      },
-    }),
-  });
   await uploadServeSimLogsFileAsync(
-    { graphqlClient: { mutation } } as unknown as CustomBuildContext,
+    {
+      env: { EAS_DEVICE_RUN_SESSION_TOKEN: 'device-run-session-token' },
+      expoApiV2BaseUrl: `${baseUrl}/v2/`,
+    } as unknown as CustomBuildContext,
     { deviceRunSessionId: 'session-test', udid: 'device-B', filePath, logger }
   );
-  expect(mutation.mock.calls[0][1]).toEqual({
-    deviceRunSessionId: 'session-test',
-    input: {
+  expect(uploadSessionRequest).toEqual({
+    token: 'device-run-session-token',
+    body: {
       name: 'App logs (device-B)',
       filename: 'app-logs.ndjson',
       kind: 'simulator-log',

packages/build-tools/src/steps/utils/android/GooglePlayApiError.ts

@@ -0,0 +1,70 @@
+import { ErrorMetadata } from '@expo/eas-build-job';
+import { Response } from 'node-fetch';
+import { z } from 'zod';
+
+const MAX_RESPONSE_BODY_LENGTH = 8_000;
+
+export class GooglePlayApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly apiMessage: string,
+    readonly reasons: string[],
+    // Kept for Sentry only, so build logs stay short.
+    readonly diagnostics: { requestPath?: string; responseBody?: string } = {}
+  ) {
+    super(`Google Play request failed (HTTP ${status})${apiMessage ? `: ${apiMessage}` : '.'}`);
+  }
+
+  static isRetryableStatus(status: number): boolean {
+    return status === 408 || status === 429 || (status >= 500 && status < 600);
+  }
+
+  // Error metadata for the first Google Play API error in the cause chain. Retries and
+  // uncertain commits wrap the API error, e.g. in an AggregateError.
+  static getErrorMetadata(error: unknown): ErrorMetadata | undefined {
+    let cause = error;
+    for (let depth = 0; cause instanceof Error && depth < 5; depth++) {
+      if (cause instanceof GooglePlayApiError) {
+        return {
+          googlePlayRequestPath: cause.diagnostics.requestPath,
+          // A string, so Sentry does not cut off nested error details.
+          googlePlayErrorResponse: cause.diagnostics.responseBody,
+        };
+      }
+      cause = cause.cause;
+    }
+    return undefined;
+  }
+
+  static async fromResponseAsync(
+    response: Response,
+    signal?: AbortSignal
+  ): Promise<GooglePlayApiError> {
+    let data: unknown;
+    try {
+      data = await response.json();
+    } catch {
+      signal?.throwIfAborted();
+      // Raw text or HTML can contain the request URL, including an upload secret.
+    }
+    const parsed = z
+      .object({
+        error: z.object({
+          message: z.string().optional(),
+          errors: z.array(z.object({ reason: z.string().optional() })).optional(),
+        }),
+      })
+      .safeParse(data);
+    return new GooglePlayApiError(
+      response.status,
+      parsed.data?.error.message ?? '',
+      parsed.data?.error.errors?.flatMap(error => (error.reason ? [error.reason] : [])) ?? [],
+      {
+        // Path only: the upload session query contains a secret.
+        requestPath: response.url ? new URL(response.url).pathname : undefined,
+        responseBody:
+          data === undefined ? undefined : JSON.stringify(data).slice(0, MAX_RESPONSE_BODY_LENGTH),
+      }
+    );
+  }
+}

packages/build-tools/src/steps/utils/android/GooglePlayAuthClient.ts

@@ -5,6 +5,7 @@ import { z } from 'zod';
 
 import { promiseRetryWithCondition } from '../../../utils/promiseRetryWithCondition';
 
+import { GooglePlayApiError } from './GooglePlayApiError';
 const PostApi = {
   '/token': {
     request: z.object({
@@ -61,7 +62,7 @@ export class GooglePlayAuthClient {
       error =>
         !signal?.aborted &&
         error instanceof GooglePlayAuthRequestError &&
-        (error.status === 429 || error.status >= 500),
+        GooglePlayApiError.isRetryableStatus(error.status),
       { retries: 3, factor: 2, minTimeout: 1000, maxTimeout: 4000 }
     )();
   }

packages/build-tools/src/steps/utils/android/GooglePlayClient.ts

@@ -1,45 +1,13 @@
 import { SystemError } from '@expo/eas-build-job';
 import fetch, { RequestInit, Response } from 'node-fetch';
+import { bunyan } from '@expo/logger';
+import { promiseRetryWithCondition } from '../../../utils/promiseRetryWithCondition';
 import { z } from 'zod';
 
+import { isConnectFailure, isConnectionInterruptedError } from '../../../utils/networkErrors';
+import { GooglePlayApiError } from './GooglePlayApiError';
 import { GooglePlayAuthUtils, GoogleServiceAccount } from './GooglePlayAuthUtils';
 
-export class GooglePlayApiError extends Error {
-  constructor(
-    readonly status: number,
-    readonly apiMessage: string,
-    readonly reasons: string[]
-  ) {
-    super(`Google Play request failed (HTTP ${status})${apiMessage ? `: ${apiMessage}` : '.'}`);
-  }
-
-  static async fromResponseAsync(
-    response: Response,
-    signal?: AbortSignal
-  ): Promise<GooglePlayApiError> {
-    let data: unknown;
-    try {
-      data = await response.json();
-    } catch {
-      signal?.throwIfAborted();
-      // Raw text or HTML can contain the request URL, including an upload secret.
-    }
-    const parsed = z
-      .object({
-        error: z.object({
-          message: z.string().optional(),
-          errors: z.array(z.object({ reason: z.string().optional() })).optional(),
-        }),
-      })
-      .safeParse(data);
-    return new GooglePlayApiError(
-      response.status,
-      parsed.data?.error.message ?? '',
-      parsed.data?.error.errors?.flatMap(error => (error.reason ? [error.reason] : [])) ?? []
-    );
-  }
-}
-
 export const ReleaseStatusZ = z.enum(['draft', 'inProgress', 'halted', 'completed']);
 export type ReleaseStatus = z.output<typeof ReleaseStatusZ>;
 
@@ -88,7 +56,9 @@ const PostApi = {
   '/androidpublisher/v3/applications/:packageName/edits/:editId:commit': {
     path: z.object({ packageName: z.string().min(1), editId: z.string().min(1) }),
     request: z.object({}),
-    query: z.object({ changesNotSentForReview: z.boolean().optional() }),
+    query: z.object({
+      changesNotSentForReview: z.boolean().optional(),
+    }),
     response: z.object({ id: z.string().min(1), expiryTimeSeconds: z.string().optional() }),
   },
   '/androidpublisher/v3/applications/:packageName/edits/:editId:validate': {
@@ -128,7 +98,10 @@ export class GooglePlayClient {
   private readonly baseUrl = 'https://androidpublisher.googleapis.com';
   private cachedToken?: Promise<{ value: string; expiresAt: number }>;
 
-  constructor(private readonly serviceAccount: GoogleServiceAccount) {}
+  constructor(
+    private readonly serviceAccount: GoogleServiceAccount,
+    private readonly logger?: bunyan
+  ) {}
 
   private async getTokenAsync(signal?: AbortSignal): Promise<string> {
     signal?.throwIfAborted();
@@ -204,7 +177,21 @@ export class GooglePlayClient {
     for (const [key, value] of Object.entries(DeleteApi[path].path.parse(params))) {
       url = url.replace(`:${key}`, encodeURIComponent(value));
     }
-    await this.requestAsync('DELETE', url, undefined, signal);
+    try {
+      await this.requestWithRetriesAsync(
+        () => this.requestAsync('DELETE', url, undefined, signal),
+        signal
+      );
+    } catch (error) {
+      if (
+        error instanceof AggregateError &&
+        error.cause instanceof GooglePlayApiError &&
+        error.cause.status === 404
+      ) {
+        return;
+      }
+      throw error;
+    }
   }
 
   private async sendJsonRequestAsync(
@@ -236,12 +223,16 @@ export class GooglePlayClient {
       }
     }
 
-    const response = await this.requestAsync(
-      method,
-      search.size ? `${path}?${search}` : path,
-      method === 'GET' ? undefined : JSON.stringify(parsedBody),
-      signal,
-      { 'Content-Type': 'application/json' }
+    const response = await this.requestWithRetriesAsync(
+      () =>
+        this.requestAsync(
+          method,
+          search.size ? `${path}?${search}` : path,
+          method === 'GET' ? undefined : JSON.stringify(parsedBody),
+          signal,
+          { 'Content-Type': 'application/json' }
+        ),
+      signal
     );
 
     let data: unknown;
@@ -264,6 +255,47 @@ export class GooglePlayClient {
     return parsed.data;
   }
 
+  private async requestWithRetriesAsync<T>(
+    request: () => Promise<T>,
+    signal?: AbortSignal
+  ): Promise<T> {
+    const errors: unknown[] = [];
+    try {
+      return await promiseRetryWithCondition(
+        async () => {
+          try {
+            signal?.throwIfAborted();
+            return await request();
+          } catch (error) {
+            errors.push(error);
+            throw error;
+          }
+        },
+        error =>
+          !signal?.aborted &&
+          (error instanceof GooglePlayApiError
+            ? GooglePlayApiError.isRetryableStatus(error.status)
+            : isConnectFailure(error) || isConnectionInterruptedError(error)),
+        { retries: 5, factor: 2, minTimeout: 1000, maxTimeout: 32_000, randomize: true },
+        ({ attemptNumber, maxAttemptsCount, error }) => {
+          const reason =
+            error instanceof GooglePlayApiError ? `HTTP ${error.status}` : 'network error';
+          this.logger?.warn(
+            `Retrying Google Play request (${reason}, attempt ${attemptNumber}/${maxAttemptsCount})...`
+          );
+        }
+      )();
+    } catch (error) {
+      // Keep earlier failures: a later rejection does not prove that every attempt failed.
+      if (errors.length > 1) {
+        throw new AggregateError(errors, 'Google Play request failed after retries.', {
+          cause: error,
+        });
+      }
+      throw error;
+    }
+  }
+
   async requestAsync(
     method: 'GET' | 'POST' | 'PUT' | 'DELETE',
     path: string,

packages/build-tools/src/steps/utils/android/GooglePlayResumableUpload.ts

@@ -1,10 +1,12 @@
 import { SystemError } from '@expo/eas-build-job';
-import fetch, { FetchError, Response } from 'node-fetch';
+import fetch, { Response } from 'node-fetch';
 import promiseRetry from 'promise-retry';
 import { FileHandle } from 'node:fs/promises';
 import { z } from 'zod';
 
-import { GooglePlayApiError, GooglePlayClient } from './GooglePlayClient';
+import { isConnectFailure, isConnectionInterruptedError } from '../../../utils/networkErrors';
+import { GooglePlayApiError } from './GooglePlayApiError';
+import { GooglePlayClient } from './GooglePlayClient';
 import { AndroidArtifactType } from './appArtifact';
 
 const UploadResponseZ = z.object({
@@ -53,8 +55,10 @@ export namespace GooglePlayResumableUpload {
           signal?.throwIfAborted();
           if (
             timeout.aborted ||
-            isNetworkRetryable(error) ||
-            (error instanceof GooglePlayApiError && (error.status === 429 || error.status >= 500))
+            isConnectFailure(error) ||
+            isConnectionInterruptedError(error) ||
+            (error instanceof GooglePlayApiError &&
+              GooglePlayApiError.isRetryableStatus(error.status))
           ) {
             retry(
               timeout.aborted
@@ -187,7 +191,7 @@ export namespace GooglePlayResumableUpload {
             const failure = new SystemError(
               'Google Play upload failed before a response was received.'
             );
-            if (timeout.aborted || isNetworkRetryable(error)) {
+            if (timeout.aborted || isConnectFailure(error) || isConnectionInterruptedError(error)) {
               checkServerOffset = true;
               retry(failure);
             }
@@ -200,7 +204,7 @@ export namespace GooglePlayResumableUpload {
               checkServerOffset = true;
               return retry(new SystemError('Google Play upload response timed out.'));
             }
-            if (response.status === 429 || response.status >= 500) {
+            if (GooglePlayApiError.isRetryableStatus(response.status)) {
               checkServerOffset = true;
               retry(error);
             }
@@ -276,15 +280,3 @@ function getContentTypeFromArtifactType(artifactType: AndroidArtifactType): stri
     ? 'application/vnd.android.package-archive'
     : 'application/octet-stream';
 }
-
-function isNetworkRetryable(error: unknown): boolean {
-  const visited = new Set<Error>();
-  while (error instanceof Error && !visited.has(error)) {
-    if (error instanceof FetchError && error.type === 'system') {
-      return true;
-    }
-    visited.add(error);
-    error = error.cause;
-  }
-  return false;
-}

packages/build-tools/src/steps/utils/android/GooglePlayUtils.ts

@@ -3,8 +3,11 @@ import { bunyan } from '@expo/logger';
 import fs from 'node:fs/promises';
 import promiseRetry from 'promise-retry';
 
+import { promiseRetryWithCondition } from '../../../utils/promiseRetryWithCondition';
+
+import { GooglePlayApiError } from './GooglePlayApiError';
 import { GooglePlayAuthRequestError } from './GooglePlayAuthClient';
-import { GooglePlayApiError, GooglePlayClient, ReleaseStatus } from './GooglePlayClient';
+import { GooglePlayClient, ReleaseStatus } from './GooglePlayClient';
 import { GooglePlayResumableUpload } from './GooglePlayResumableUpload';
 import { AndroidArtifactType } from './appArtifact';
 
@@ -141,7 +144,7 @@ export namespace GooglePlayUtils {
       signal?: AbortSignal;
     }
   ): Promise<void> {
-    const commitOnceAsync = async ({
+    const sendCommitAsync = async ({
       changesNotSentForReview,
     }: {
       changesNotSentForReview?: boolean;
@@ -163,13 +166,11 @@ export namespace GooglePlayUtils {
         }
         if (
           !(error instanceof GooglePlayApiError) ||
-          error.status >= 500 ||
-          error.status === 408 ||
-          error.status === 429
+          GooglePlayApiError.isRetryableStatus(error.status)
         ) {
           throw new GooglePlayCommitOutcomeUnknownError(
-            `Could not confirm whether Google Play saved the release for ${packageName}. Check its release status at https://play.google.com/console/ before submitting again. The request was not retried because it may have succeeded.`,
-            { cause: error }
+            `Could not confirm whether Google Play saved the release for ${packageName}. Check its release status at https://play.google.com/console/ before submitting again.`,
+            { cause: error, metadata: GooglePlayApiError.getErrorMetadata(error) }
           );
         }
         throw error;
@@ -180,10 +181,42 @@ export namespace GooglePlayUtils {
           : 'Google Play saved the release using its normal review process. Check its review and publishing status at https://play.google.com/console/.'
       );
     };
+    // Google can accept the bundle upload before the edit is ready to commit.
+    // Retry only this explicit rejection, not other HTTP 400 preconditions.
+    const isUploadStillProcessing = (error: unknown): boolean =>
+      error instanceof GooglePlayApiError &&
+      error.status === 400 &&
+      error.apiMessage === 'Some of the Android App Bundle uploads are not completed yet.';
+
+    const commitAsync = async (options: { changesNotSentForReview?: boolean }): Promise<void> => {
+      try {
+        await promiseRetryWithCondition(
+          sendCommitAsync,
+          error => {
+            signal?.throwIfAborted();
+            return isUploadStillProcessing(error);
+          },
+          { retries: 5, factor: 2, minTimeout: 2000, maxTimeout: 32_000 },
+          ({ attemptNumber, maxAttemptsCount }) => {
+            logger.warn(
+              `Google Play is still processing the uploaded bundle. Retrying the same edit commit (attempt ${attemptNumber}/${maxAttemptsCount}).`
+            );
+          }
+        )(options);
+      } catch (error) {
+        if (isUploadStillProcessing(error)) {
+          throw new SystemError(
+            `Google Play did not finish processing the uploaded bundle for ${packageName} after six commit attempts. Wait a few minutes, then check the release at https://play.google.com/console/ before submitting again.`,
+            { cause: error, metadata: GooglePlayApiError.getErrorMetadata(error) }
+          );
+        }
+        throw error;
+      }
+    };
     try {
       // Omit the optional parameter for normal review submission. Some app states
       // reject its presence, even when false. True saves changes for review in Console.
-      await commitOnceAsync({ changesNotSentForReview: changesNotSentForReview || undefined });
+      await commitAsync({ changesNotSentForReview: changesNotSentForReview || undefined });
     } catch (error) {
       if (!(error instanceof GooglePlayApiError) || error.status !== 400) {
         throw error;
@@ -196,7 +229,7 @@ export namespace GooglePlayUtils {
         logger.warn(
           'Google does not allow changesNotSentForReview for this app right now. Retrying commit once without it. The changes will be sent for review.'
         );
-        await commitOnceAsync({});
+        await commitAsync({});
       } else if (
         !changesNotSentForReview &&
         error.apiMessage.includes('Please set the query parameter changesNotSentForReview to true')
@@ -204,7 +237,7 @@ export namespace GooglePlayUtils {
         logger.warn(
           'Google requires changesNotSentForReview=true. Retrying commit once. Send the saved changes for review from Play Console.'
         );
-        await commitOnceAsync({ changesNotSentForReview: true });
+        await commitAsync({ changesNotSentForReview: true });
       } else {
         throw error;
       }
@@ -212,21 +245,23 @@ export namespace GooglePlayUtils {
   }
 
   export function mapGooglePlayError(error: unknown, packageName: string): unknown {
+    if (error instanceof AggregateError) {
+      return mapGooglePlayError(error.cause, packageName);
+    }
     if (
       (error instanceof GooglePlayApiError || error instanceof GooglePlayAuthRequestError) &&
-      (error.status === 408 || error.status === 429 || error.status >= 500)
+      GooglePlayApiError.isRetryableStatus(error.status)
     ) {
       return new SystemError(
         `Google Play is temporarily unavailable or rate limited (HTTP ${error.status}). Try again later.`,
-        { cause: error }
+        { cause: error, metadata: GooglePlayApiError.getErrorMetadata(error) }
       );
     }
     if (
       error instanceof GooglePlayAuthRequestError &&
       error.status >= 400 &&
       error.status < 500 &&
-      error.status !== 408 &&
-      error.status !== 429
+      !GooglePlayApiError.isRetryableStatus(error.status)
     ) {
       return new UserError(
         'EAS_GOOGLE_PLAY_INVALID_CREDENTIALS',
@@ -282,9 +317,7 @@ export namespace GooglePlayUtils {
     return new UserError(
       code,
       `${detail}\n\nApp: ${packageName}\nGoogle Play Console: https://play.google.com/console/`,
-      {
-        cause: error,
-      }
+      { cause: error, metadata: GooglePlayApiError.getErrorMetadata(error) }
     );
   }
 }

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

@@ -1,9 +1,9 @@
 import nock from 'nock';
 import { generateKeyPairSync } from 'node:crypto';
-import { SystemError } from '@expo/eas-build-job';
 import { ZodError } from 'zod';
 
 import { GooglePlayClient } from '../GooglePlayClient';
+import { createMockLogger } from '../../../../__tests__/utils/logger';
 
 const packageName = 'dev.expo.submitfixture';
 const editPath = `/androidpublisher/v3/applications/${packageName}/edits/edit`;
@@ -13,6 +13,11 @@ const api = (): nock.Scope =>
   });
 
 jest.unmock('node-fetch');
+jest.mock('promise-retry', () => {
+  const actual = jest.requireActual('promise-retry');
+  return (fn: Parameters<typeof actual>[0], options: object) =>
+    actual(fn, { ...options, minTimeout: 1, maxTimeout: 1, randomize: false });
+});
 
 const serviceAccount = {
   client_email: '[email protected]',
@@ -75,11 +80,12 @@ it('rejects invalid rollout requests before sending them', async () => {
   ).rejects.toBeInstanceOf(ZodError);
 });
 
-it('does not retry an ambiguous edit commit', async () => {
+it('keeps the outcome unknown when a lost commit response is followed by an invalid edit', async () => {
   api()
     .post(`${editPath}:commit`, {})
     .query({ changesNotSentForReview: false })
-    .replyWithError('Lost response');
+    .replyWithError(Object.assign(new Error('Lost response'), { code: 'ECONNRESET' }));
+  api().post(`${editPath}:commit`, {}).query({ changesNotSentForReview: false }).reply(404);
   await expect(
     client.postAsync(
       '/androidpublisher/v3/applications/:packageName/edits/:editId:commit',
@@ -87,7 +93,62 @@ it('does not retry an ambiguous edit commit', async () => {
       { packageName, editId: 'edit' },
       { query: { changesNotSentForReview: false } }
     )
-  ).rejects.toBeInstanceOf(SystemError);
+  ).rejects.toMatchObject({
+    errors: [expect.any(Error), expect.objectContaining({ status: 404 })],
+  });
+});
+
+it.each([408, 429, 500, 503])('stops after five retries for HTTP %s', async status => {
+  api().get(editPath).times(6).reply(status);
+  await expect(
+    client.getAsync('/androidpublisher/v3/applications/:packageName/edits/:editId', {
+      packageName,
+      editId: 'edit',
+    })
+  ).rejects.toMatchObject({
+    cause: expect.objectContaining({ status }),
+    errors: expect.arrayContaining([expect.objectContaining({ status })]),
+  });
+});
+
+it('retries the same track update body after a temporary error', async () => {
+  const body = {
+    track: 'internal',
+    releases: [{ versionCodes: ['123'], status: 'draft' as const }],
+  };
+  api().put(`${editPath}/tracks/internal`, body).reply(503);
+  api().put(`${editPath}/tracks/internal`, body).reply(200, { track: 'internal' });
+  await expect(
+    client.putAsync(
+      '/androidpublisher/v3/applications/:packageName/edits/:editId/tracks/:track',
+      body,
+      { packageName, editId: 'edit', track: 'internal' }
+    )
+  ).resolves.toEqual({ track: 'internal' });
+});
+
+it('does not add retries to upload-session requests', async () => {
+  api().post('/upload/session').reply(503);
+  await expect(client.requestAsync('POST', '/upload/session')).rejects.toMatchObject({
+    status: 503,
+  });
+});
+
+it('stops retrying when cancelled after a transient response', async () => {
+  const controller = new AbortController();
+  api()
+    .get(editPath)
+    .reply(() => {
+      controller.abort();
+      return [503];
+    });
+  await expect(
+    client.getAsync(
+      '/androidpublisher/v3/applications/:packageName/edits/:editId',
+      { packageName, editId: 'edit' },
+      controller.signal
+    )
+  ).rejects.toBeDefined();
 });
 
 it('deletes an edit with an empty response', async () => {
@@ -100,6 +161,44 @@ it('deletes an edit with an empty response', async () => {
   ).resolves.toBeUndefined();
 });
 
+it('reports a retry even when the next request succeeds', async () => {
+  const logger = createMockLogger();
+  client = new GooglePlayClient(serviceAccount, logger);
+  api().get(editPath).reply(503);
+  api().get(editPath).reply(200, { id: 'edit' });
+  await client.getAsync('/androidpublisher/v3/applications/:packageName/edits/:editId', {
+    packageName,
+    editId: 'edit',
+  });
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn).toHaveBeenCalledWith(
+    'Retrying Google Play request (HTTP 503, attempt 2/6)...'
+  );
+});
+
+it('accepts a missing edit after a lost delete response', async () => {
+  api()
+    .delete(editPath)
+    .replyWithError(Object.assign(new Error('Lost response'), { code: 'ECONNRESET' }));
+  api().delete(editPath).reply(404);
+  await expect(
+    client.deleteAsync('/androidpublisher/v3/applications/:packageName/edits/:editId', {
+      packageName,
+      editId: 'edit',
+    })
+  ).resolves.toBeUndefined();
+});
+
+it('retains an initial delete rejection', async () => {
+  api().delete(editPath).reply(404);
+  await expect(
+    client.deleteAsync('/androidpublisher/v3/applications/:packageName/edits/:editId', {
+      packageName,
+      editId: 'edit',
+    })
+  ).rejects.toMatchObject({ status: 404 });
+});
+
 it('rejects malformed success responses without exposing their contents', async () => {
   api()
     .get(editPath)
@@ -124,6 +223,42 @@ it('retains structured API errors', async () => {
   ).rejects.toMatchObject({ status: 403, apiMessage: 'Denied', reasons: ['forbidden'] });
 });
 
+it.each(['CERT_HAS_EXPIRED', 'EPROTO', 'EACCES', undefined])(
+  'does not retry a system error with code %s',
+  async code => {
+    const logger = createMockLogger();
+    client = new GooglePlayClient(serviceAccount, logger);
+    api()
+      .get(editPath)
+      .replyWithError(Object.assign(new Error('Request failed'), { code }));
+    await expect(
+      client.getAsync('/androidpublisher/v3/applications/:packageName/edits/:editId', {
+        packageName,
+        editId: 'edit',
+      })
+    ).rejects.toMatchObject({
+      cause: expect.objectContaining({ type: 'system' }),
+    });
+    expect(logger.warn).not.toHaveBeenCalled();
+  }
+);
+
+it.each(['EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'UND_ERR_SOCKET'])(
+  'retries a recognised network error %s',
+  async code => {
+    api()
+      .get(editPath)
+      .replyWithError(Object.assign(new Error('Request failed'), { code }));
+    api().get(editPath).reply(200, { id: 'edit' });
+    await expect(
+      client.getAsync('/androidpublisher/v3/applications/:packageName/edits/:editId', {
+        packageName,
+        editId: 'edit',
+      })
+    ).resolves.toEqual({ id: 'edit' });
+  }
+);
+
 it.each(['body', 'query'])('accepts extra fields in an empty %s object', async field => {
   api()
     .post(`/androidpublisher/v3/applications/${packageName}/edits`, {})

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

@@ -1,13 +1,20 @@
 import { SystemError, UserError } from '@expo/eas-build-job';
 import nock from 'nock';
+import { Response } from 'node-fetch';
 
 import { api, editPath, mockToken, packageName, serviceAccount } from './googlePlayTestUtils';
 import { createMockLogger } from '../../../../__tests__/utils/logger';
 import { GooglePlayAuthRequestError } from '../GooglePlayAuthClient';
-import { GooglePlayApiError, GooglePlayClient } from '../GooglePlayClient';
-import { GooglePlayUtils } from '../GooglePlayUtils';
+import { GooglePlayApiError } from '../GooglePlayApiError';
+import { GooglePlayClient } from '../GooglePlayClient';
+import { GooglePlayCommitOutcomeUnknownError, GooglePlayUtils } from '../GooglePlayUtils';
 
 jest.unmock('node-fetch');
+jest.mock('promise-retry', () => {
+  const actual = jest.requireActual('promise-retry');
+  return (fn: Parameters<typeof actual>[0], options: object) =>
+    actual(fn, { ...options, minTimeout: 1, maxTimeout: 1, randomize: false });
+});
 beforeEach(() => nock.disableNetConnect());
 afterEach(() => {
   const pending = nock.pendingMocks();
@@ -71,10 +78,11 @@ it.each([
     );
   }
 );
-it.each([408, 429, 503])('does not retry an uncertain HTTP %s commit', async status => {
+it.each([408, 429, 503])('retries a transient HTTP %s commit on the same edit', async status => {
   mockToken();
   api().post(`${editPath}:commit`).query(true).reply(status);
-  await expect(commit()).rejects.toMatchObject({ cause: expect.objectContaining({ status }) });
+  api().post(`${editPath}:commit`).query({}).reply(200, { id: 'edit' });
+  await expect(commit()).resolves.toBeUndefined();
 });
 it('preserves cancellation before commit is sent', async () => {
   const controller = new AbortController();
@@ -82,6 +90,74 @@ it('preserves cancellation before commit is sent', async () => {
   controller.abort(reason);
   await expect(commit({ signal: controller.signal })).rejects.toBe(reason);
 });
+const pendingUploadMessage = 'Some of the Android App Bundle uploads are not completed yet.';
+
+it.each([false, true])(
+  'waits for bundle processing without changing review settings (%s)',
+  async changesNotSentForReview => {
+    const logger = createMockLogger();
+    const query = changesNotSentForReview ? { changesNotSentForReview: 'true' } : {};
+    mockToken();
+    api()
+      .post(`${editPath}:commit`, {})
+      .query(query)
+      .reply(400, { error: { message: pendingUploadMessage } });
+    api().post(`${editPath}:commit`, {}).query(query).reply(200, { id: 'edit' });
+    await expect(commit({ changesNotSentForReview, logger })).resolves.toBeUndefined();
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Google Play is still processing')
+    );
+  }
+);
+
+it('stops waiting for bundle processing after six attempts', async () => {
+  mockToken();
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .times(6)
+    .reply(400, { error: { message: pendingUploadMessage } });
+  const error = await commit().catch(error => error);
+  expect(GooglePlayUtils.mapGooglePlayError(error, packageName)).toMatchObject({
+    message: expect.stringContaining('Google Play did not finish processing'),
+    metadata: {
+      googlePlayRequestPath: `${editPath}:commit`,
+      googlePlayErrorResponse: JSON.stringify({ error: { message: pendingUploadMessage } }),
+    },
+  });
+});
+
+it('does not retry an unrelated commit precondition', async () => {
+  mockToken();
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .reply(400, { error: { message: 'Precondition check failed.' } });
+  await expect(commit()).rejects.toBeInstanceOf(GooglePlayApiError);
+});
+
+it('checks cancellation before sending a processing retry', async () => {
+  const controller = new AbortController();
+  const reason = new Error('cancelled while waiting');
+  const logger = createMockLogger();
+  jest.spyOn(logger, 'warn').mockImplementation(() => controller.abort(reason));
+  mockToken();
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .reply(400, { error: { message: pendingUploadMessage } });
+  await expect(commit({ signal: controller.signal, logger })).rejects.toBe(reason);
+});
+
+it('does not report success if a processing retry has no valid commit receipt', async () => {
+  mockToken();
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .reply(400, { error: { message: pendingUploadMessage } });
+  api().post(`${editPath}:commit`).query({}).reply(200, { id: 'different-edit' });
+  await expect(commit()).rejects.toBeInstanceOf(GooglePlayCommitOutcomeUnknownError);
+});
 it('preserves OAuth rejection before commit is sent', async () => {
   nock('https://oauth2.googleapis.com').post('/token').reply(400, { error: 'invalid_grant' });
   await expect(commit()).rejects.toBeInstanceOf(GooglePlayAuthRequestError);
@@ -140,3 +216,56 @@ it('keeps non-Google errors unchanged', () => {
   const error = new SystemError('file failure');
   expect(GooglePlayUtils.mapGooglePlayError(error, packageName)).toBe(error);
 });
+it('keeps the Google Play error response in metadata, not in the message', async () => {
+  const response = {
+    error: {
+      code: 400,
+      message: 'Precondition check failed.',
+      status: 'FAILED_PRECONDITION',
+      details: [
+        {
+          '@type': 'type.googleapis.com/google.rpc.PreconditionFailure',
+          violations: [{ type: 'APP_SETUP', description: 'Complete the app setup.' }],
+        },
+      ],
+    },
+  };
+  mockToken();
+  api().post(`${editPath}:commit`).query({}).reply(400, response);
+  const error = await commit().catch(error => error);
+  const mapped = GooglePlayUtils.mapGooglePlayError(error, packageName);
+  expect(mapped).toMatchObject({
+    errorCode: 'EAS_GOOGLE_PLAY_INVALID_RELEASE',
+    metadata: {
+      googlePlayRequestPath: `${editPath}:commit`,
+      googlePlayErrorResponse: JSON.stringify(response),
+    },
+  });
+  expect((mapped as Error).message).not.toContain('APP_SETUP');
+});
+it('keeps the last Google Play error response when the commit outcome is unknown', async () => {
+  mockToken();
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .times(6)
+    .reply(503, { error: { message: 'Backend error' } });
+  await expect(commit()).rejects.toMatchObject({
+    metadata: {
+      googlePlayRequestPath: `${editPath}:commit`,
+      googlePlayErrorResponse: JSON.stringify({ error: { message: 'Backend error' } }),
+    },
+  });
+});
+it('does not keep the upload session query or a non-JSON response', async () => {
+  const error = await GooglePlayApiError.fromResponseAsync(
+    new Response('<html>upload_id=SECRET</html>', {
+      status: 400,
+      url: 'https://androidpublisher.googleapis.com/upload/session?upload_id=SECRET',
+    })
+  );
+  expect(GooglePlayApiError.getErrorMetadata(error)).toEqual({
+    googlePlayRequestPath: '/upload/session',
+    googlePlayErrorResponse: undefined,
+  });
+});

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

@@ -89,14 +89,16 @@ it('uploads aligned chunks and reports server-confirmed progress', async () => {
   ]);
 });
 
-it.each(['network', 429, 503])(
+it.each(['network', 408, 429, 503])(
   'recovers the accepted offset after a %s interruption',
   async failure => {
     mockToken();
     mockStart();
     const interrupted = uploadApi().put(session).matchHeader('content-range', 'bytes 0-11/12');
     if (failure === 'network') {
-      interrupted.replyWithError('connection reset');
+      interrupted.replyWithError(
+        Object.assign(new Error('connection reset'), { code: 'ECONNRESET' })
+      );
     } else {
       interrupted.reply(failure as number, { error: { message: 'retry' } });
     }
@@ -121,7 +123,7 @@ it('recovers a completed upload when the final upload response is lost', async (
   uploadApi()
     .put(session)
     .matchHeader('content-length', '12')
-    .replyWithError('lost final response');
+    .replyWithError(Object.assign(new Error('lost final response'), { code: 'ECONNRESET' }));
   status().reply(200, { versionCode: 42 });
   await expect(upload()).resolves.toBe(42);
 });
@@ -286,7 +288,7 @@ it('retries a network failure during session creation', async () => {
   api()
     .post(`/upload${editPath}/apks`)
     .query({ uploadType: 'resumable' })
-    .replyWithError('connection reset');
+    .replyWithError(Object.assign(new Error('connection reset'), { code: 'ECONNRESET' }));
   mockStart();
   uploadApi().put(session).reply(200, { versionCode: 42 });
   await expect(upload()).resolves.toBe(42);
@@ -347,7 +349,9 @@ it.each([
     mockStart();
     const finalChunk = uploadApi().put(session).matchHeader('content-length', '12');
     if (finalResponse === 'lost') {
-      finalChunk.replyWithError('lost final response');
+      finalChunk.replyWithError(
+        Object.assign(new Error('lost final response'), { code: 'ECONNRESET' })
+      );
     } else {
       finalChunk.reply(308, '', { Range: 'bytes=0-11' });
     }

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

@@ -1,8 +1,6 @@
 import { SystemError } from '@expo/eas-build-job';
-import { graphql } from 'gql.tada';
 
 import { CustomBuildContext } from '../../customBuildContext';
-import { graphqlAbortContext } from '../../utils/graphqlAbort';
 import {
   ArtifactPutError,
   ArtifactPutNetworkError,
@@ -11,23 +9,7 @@ import {
   putArtifactWithRetriesAsync,
 } from './artifactPut';
 import { withDeviceRunSessionTimeoutAsync } from './deviceRunSessionTimeout';
-import { getDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
-
-const CREATE_DEVICE_RUN_SESSION_ARTIFACT_UPLOAD_SESSION_MUTATION = graphql(`
-  mutation CreateDeviceRunSessionArtifactUploadSession(
-    $deviceRunSessionId: ID!
-    $input: CreateDeviceRunSessionArtifactUploadSessionInput!
-  ) {
-    deviceRunSession {
-      createArtifactUploadSession(deviceRunSessionId: $deviceRunSessionId, input: $input) {
-        uploadSession {
-          url
-          headers
-        }
-      }
-    }
-  }
-`);
+import { requireDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
 
 type ArtifactMetadata = {
   deviceRunSessionId: string;
@@ -72,54 +54,28 @@ async function createDeviceRunSessionArtifactUploadSessionAsync(
   { deviceRunSessionId, artifactId, name, filename, kind, metadata, size }: ArtifactMetadata,
   signal: AbortSignal
 ): Promise<ArtifactUploadSession> {
-  const workerApi = getDeviceRunSessionWorkerApi(ctx);
-  if (workerApi) {
-    let uploadSession: ArtifactUploadSession;
-    try {
-      uploadSession = await workerApi.createArtifactUploadSessionAsync(
-        {
-          name,
-          filename,
-          ...(kind !== undefined ? { kind } : {}),
-          ...(metadata !== undefined ? { metadata } : {}),
-          size,
-        },
-        { signal }
-      );
-    } catch (err) {
-      signal.throwIfAborted();
-      throw new SystemError(
-        `Failed to create upload session for device run session artifact ${artifactId}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-        { cause: err }
-      );
-    }
-    signal.throwIfAborted();
-    return uploadSession;
-  }
-  const result = await ctx.graphqlClient
-    .mutation(
-      CREATE_DEVICE_RUN_SESSION_ARTIFACT_UPLOAD_SESSION_MUTATION,
+  const workerApi = requireDeviceRunSessionWorkerApi(ctx);
+  let uploadSession: ArtifactUploadSession;
+  try {
+    uploadSession = await workerApi.createArtifactUploadSessionAsync(
       {
-        deviceRunSessionId,
-        input: {
-          name,
-          filename,
-          ...(kind !== undefined ? { kind } : {}),
-          ...(metadata !== undefined ? { metadata } : {}),
-          size,
-        },
+        name,
+        filename,
+        ...(kind !== undefined ? { kind } : {}),
+        ...(metadata !== undefined ? { metadata } : {}),
+        size,
       },
-      graphqlAbortContext(signal)
-    )
-    .toPromise();
-  signal.throwIfAborted();
-  if (result.error) {
+      { signal }
+    );
+  } catch (err) {
+    signal.throwIfAborted();
     throw new SystemError(
-      `Failed to create upload session for device run session artifact ${artifactId}: ${result.error.message}`,
-      { cause: result.error }
+      `Failed to create upload session for device run session artifact ${artifactId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      { cause: err }
     );
   }
-  return result.data!.deviceRunSession.createArtifactUploadSession.uploadSession;
+  signal.throwIfAborted();
+  return uploadSession;
 }

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

@@ -1,6 +1,5 @@
 import { SystemError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
-import { graphql } from 'gql.tada';
 import fs from 'node:fs';
 import { StringDecoder } from 'node:string_decoder';
 import { setTimeout as setTimeoutAsync } from 'node:timers/promises';
@@ -10,26 +9,13 @@ import HttpLogStream from '../../logging/HttpLogStream';
 import RemoteLoggerStream from '../../logging/RemoteLoggerStream';
 import { Sentry } from '../../sentry';
 import { type SignedUrl } from '../../storage/uploadWithSignedUrl';
-import { getDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
+import { requireDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
 
 const POLL_INTERVAL_MS = 1_000;
 const UPLOAD_INTERVAL_MS = 5_000;
 const EAS_LOGS_THREAD = 'session-events';
 const EAS_LOGS_BUFFER_RETENTION_MS = 30_000;
 
-const CREATE_DEVICE_RUN_SESSION_EVENT_LOG_UPLOAD_SESSION_MUTATION = graphql(`
-  mutation CreateDeviceRunSessionEventLogUploadSession($deviceRunSessionId: ID!) {
-    deviceRunSession {
-      createEventLogUploadSession(deviceRunSessionId: $deviceRunSessionId) {
-        uploadSession {
-          url
-          headers
-        }
-      }
-    }
-  }
-`);
-
 /**
  * The normalized, producer-agnostic event shape uploaded to the API server.
  * Every remote-session producer (agent-device, argent, ...) tails its own
@@ -350,35 +336,17 @@ async function createEventLogUploadSessionAsync(
   ctx: CustomBuildContext,
   deviceRunSessionId: string
 ): Promise<SignedUrl> {
-  const workerApi = getDeviceRunSessionWorkerApi(ctx);
-  if (workerApi) {
-    try {
-      return await workerApi.createEventLogUploadSessionAsync();
-    } catch (err) {
-      throw new SystemError(
-        `Failed to create device run session event log upload session: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-        { cause: err }
-      );
-    }
-  }
-  const result = await ctx.graphqlClient
-    .mutation(CREATE_DEVICE_RUN_SESSION_EVENT_LOG_UPLOAD_SESSION_MUTATION, {
-      deviceRunSessionId,
-    })
-    .toPromise();
-  if (result.error) {
+  const workerApi = requireDeviceRunSessionWorkerApi(ctx);
+  try {
+    return await workerApi.createEventLogUploadSessionAsync();
+  } catch (err) {
     throw new SystemError(
-      `Failed to create device run session event log upload session: ${result.error.message}`,
-      { cause: result.error }
+      `Failed to create device run session event log upload session: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      { cause: err }
     );
   }
-  const uploadSession = result.data!.deviceRunSession.createEventLogUploadSession.uploadSession;
-  return {
-    url: uploadSession.url,
-    headers: uploadSession.headers as Record<string, string>,
-  };
 }
 
 async function collectEventFileAsync({

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

@@ -2,7 +2,6 @@ import { type bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import { BuildRuntimePlatform, type BuildStepEnv } from '@expo/steps';
 import spawn, { type SpawnOptions } from '@expo/turtle-spawn';
-import { graphql } from 'gql.tada';
 import fetch from 'node-fetch';
 import { createWriteStream } from 'node:fs';
 import { pipeline } from 'node:stream/promises';
@@ -12,25 +11,12 @@ import path from 'node:path';
 
 import { type CustomBuildContext } from '../../customBuildContext';
 import { killProcessGroup } from '../../utils/processes';
-import { getDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
+import { requireDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
 
 const PREVIEW_INTERVAL_MS = 60_000;
 const PREVIEW_MAX_DIMENSION = 320;
 const PREVIEW_QUALITY = 70;
 const MAX_PREVIEW_SIZE_BYTES = 5 * 1024 * 1024;
-const CREATE_PREVIEW_UPLOAD_SESSION_MUTATION = graphql(`
-  mutation CreateDeviceRunSessionPreviewUploadSession($deviceRunSessionId: ID!) {
-    deviceRunSession {
-      createPreviewUploadSession(deviceRunSessionId: $deviceRunSessionId) {
-        uploadSession {
-          url
-          headers
-        }
-      }
-    }
-  }
-`);
-
 /**
  * node-fetch includes the request URL in its error messages, and this URL is a signed upload URL
  * that is valid for the whole session. Replace such errors with one that names only the failure.
@@ -122,35 +108,7 @@ async function createPreviewUploadSessionAsync(
   deviceRunSessionId: string,
   signal: AbortSignal
 ): Promise<{ url: string; headers: Record<string, string> }> {
-  const workerApi = getDeviceRunSessionWorkerApi(ctx);
-  if (workerApi) {
-    return await workerApi.createPreviewUploadSessionAsync({ signal });
-  }
-  const result = await ctx.graphqlClient
-    .mutation(
-      CREATE_PREVIEW_UPLOAD_SESSION_MUTATION,
-      { deviceRunSessionId },
-      {
-        // Keep the client's auth headers and combine cancellation after URQL sets its signal.
-        fetch: (url, options) =>
-          globalThis.fetch(url, {
-            ...options,
-            signal: AbortSignal.any([signal, ...(options?.signal ? [options.signal] : [])]),
-          }),
-      }
-    )
-    .toPromise();
-  if (result.error) {
-    throw result.error;
-  }
-  const session = result.data?.deviceRunSession.createPreviewUploadSession.uploadSession;
-  if (!session) {
-    throw new Error('No session preview upload URL was returned.');
-  }
-  return {
-    url: session.url,
-    headers: session.headers as Record<string, string>,
-  };
+  return await requireDeviceRunSessionWorkerApi(ctx).createPreviewUploadSessionAsync({ signal });
 }
 
 /**

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

@@ -1,11 +1,8 @@
 import type { bunyan } from '@expo/logger';
 import { BuildRuntimePlatform } from '@expo/steps';
-import { graphql } from 'gql.tada';
-import { z } from 'zod';
 
 import type { CustomBuildContext } from '../../customBuildContext';
-import { graphqlAbortContext } from '../../utils/graphqlAbort';
-import { getDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
+import { requireDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
 
 const SHORT_COMMIT_HASH_LENGTH = 7;
 const MAX_APP_SLUG_LENGTH = 80;
@@ -17,38 +14,9 @@ const LEADING_OR_TRAILING_DOTS_AND_HYPHENS = /^[.-]+|[.-]+$/g;
 // A full git commit hash: 40 hex characters for SHA-1 or 64 for SHA-256.
 const FULL_GIT_COMMIT_HASH = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i;
 
-const SCREENSHOT_SESSION_QUERY = graphql(`
-  query ScreenshotSession($deviceRunSessionId: ID!) {
-    deviceRunSessions {
-      byId(deviceRunSessionId: $deviceRunSessionId) {
-        platform
-        app { slug }
-        build {
-          id
-          gitCommitHash
-          app { slug }
-        }
-      }
-    }
-  }
-`);
-
-const AppSchema = z.object({ slug: z.string() });
-const ScreenshotSessionSchema = z.object({
-  platform: z.enum(['IOS', 'ANDROID']),
-  app: AppSchema,
-  build: z
-    .object({
-      id: z.string(),
-      gitCommitHash: z.string().nullable(),
-      app: AppSchema,
-    })
-    .nullable(),
-});
-
 /**
- * Session details used to name screenshots. `app` is null when the source does not report an app
- * slug: the device run session worker API does not return one.
+ * Session details used to name screenshots. `app` is always null: the device run session worker
+ * API does not return the app slug.
  */
 export type ScreenshotSession = {
   platform: 'IOS' | 'ANDROID';
@@ -63,30 +31,22 @@ export async function loadScreenshotSessionAsync(
 ): Promise<ScreenshotSession | null> {
   try {
     const signal = AbortSignal.timeout(SESSION_LOOKUP_TIMEOUT_MS);
-    const workerApi = getDeviceRunSessionWorkerApi(ctx);
-    if (workerApi) {
-      const application = await workerApi.getApplicationAsync({ signal });
-      return {
-        // www runs iOS sessions only on macOS workers and Android sessions only on Linux workers,
-        // so the worker API does not return the platform.
-        platform: ctx.runtimePlatform === BuildRuntimePlatform.DARWIN ? 'IOS' : 'ANDROID',
-        app: null,
-        build: application.build
-          ? {
-              id: application.build.id,
-              gitCommitHash: application.build.gitCommitHash,
-              app: null,
-            }
-          : null,
-      };
-    }
-    const result = await ctx.graphqlClient
-      .query(SCREENSHOT_SESSION_QUERY, { deviceRunSessionId }, graphqlAbortContext(signal))
-      .toPromise();
-    if (result.error) {
-      throw result.error;
-    }
-    return ScreenshotSessionSchema.parse(result.data?.deviceRunSessions.byId);
+    const application = await requireDeviceRunSessionWorkerApi(ctx).getApplicationAsync({
+      signal,
+    });
+    return {
+      // www runs iOS sessions only on macOS workers and Android sessions only on Linux workers,
+      // so the worker API does not return the platform.
+      platform: ctx.runtimePlatform === BuildRuntimePlatform.DARWIN ? 'IOS' : 'ANDROID',
+      app: null,
+      build: application.build
+        ? {
+            id: application.build.id,
+            gitCommitHash: application.build.gitCommitHash,
+            app: null,
+          }
+        : null,
+    };
   } catch (err) {
     logger.warn(
       { err, deviceRunSessionId },

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

@@ -20,24 +20,10 @@ export const DEVICE_RUN_SESSION_TOKEN_HEADER = 'expo-device-run-session-token';
 
 const DEVICE_RUN_SESSION_WORKER_PATH = 'device-run-session-worker/';
 
-/**
- * www returns the entity value of the status. The client maps it to the GraphQL enum value, so
- * callers compare statuses the same way on both paths.
- */
-const DEVICE_RUN_SESSION_STATUS_FROM_ENTITY_VALUE = {
-  new: 'NEW',
-  queued: 'QUEUED',
-  starting: 'STARTING',
-  'in-progress': 'IN_PROGRESS',
-  stopped: 'STOPPED',
-  errored: 'ERRORED',
-} as const;
-
 const DeviceRunSessionStatusSchema = z.object({
   id: z.string(),
-  status: z
-    .enum(['new', 'queued', 'starting', 'in-progress', 'stopped', 'errored'])
-    .transform(status => DEVICE_RUN_SESSION_STATUS_FROM_ENTITY_VALUE[status]),
+  // The status entity values that www returns.
+  status: z.enum(['new', 'queued', 'starting', 'in-progress', 'stopped', 'errored']),
 });
 
 const UploadSessionSchema = z.object({
@@ -307,6 +293,24 @@ export function getDeviceRunSessionWorkerApi(
   return new DeviceRunSessionWorkerApi(getExpoApiV2BaseUrl(ctx), token);
 }
 
+/**
+ * Returns the client for the device run session worker API, which every device run session job
+ * uses to call www about its session.
+ */
+export function requireDeviceRunSessionWorkerApi(
+  ctx: Pick<CustomBuildContext, 'env' | 'expoApiV2BaseUrl'>
+): DeviceRunSessionWorkerApi {
+  const workerApi = getDeviceRunSessionWorkerApi(ctx);
+  if (!workerApi) {
+    throw new SystemError(
+      `This device run session job has no ${DEVICE_RUN_SESSION_TOKEN_ENV} secret. ` +
+        'www gives one to every device run session job, and the worker needs it to call the ' +
+        'device run session API. Start a new session, and contact support if it happens again.'
+    );
+  }
+  return workerApi;
+}
+
 function getExpoApiV2BaseUrl(ctx: Pick<CustomBuildContext, 'env' | 'expoApiV2BaseUrl'>): string {
   if (ctx.expoApiV2BaseUrl) {
     return ctx.expoApiV2BaseUrl;

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

@@ -102,6 +102,16 @@ export function websiteOriginArgs(env: BuildStepEnv): string[] {
   return [...origins].flatMap(origin => ['--cors-origin', origin, '--frame-ancestor', origin]);
 }
 
+// Both hosts take the same flag; it only applies under --require-token, which both run with.
+export function frameAncestorArgs(frameAncestors: readonly string[]): string[] {
+  return frameAncestors.flatMap(origin => ['--frame-ancestor', origin]);
+}
+
+// Both hosts take the same flag and match the same origin shapes.
+export function corsOriginArgs(corsOrigins: readonly string[]): string[] {
+  return corsOrigins.flatMap(origin => ['--cors-origin', origin]);
+}
+
 function createServeSimPackageSpec(packageVersion: string | undefined): string {
   return `${SERVE_SIM_PACKAGE_NAME}@${packageVersion ?? 'latest'}`;
 }
@@ -114,6 +124,8 @@ export function createServeSimArgs({
   port,
   turnArgs = [],
   websiteArgs = [],
+  frameAncestorArgs: frameArgs = [],
+  corsOriginArgs: corsArgs = [],
   shareUrl,
   disableShare = false,
   packageVersion,
@@ -128,6 +140,8 @@ export function createServeSimArgs({
   port: number;
   turnArgs?: string[];
   websiteArgs?: string[];
+  frameAncestorArgs?: string[];
+  corsOriginArgs?: string[];
   shareUrl?: string;
   disableShare?: boolean;
   packageVersion?: string;
@@ -158,6 +172,8 @@ export function createServeSimArgs({
     SERVE_SIM_VIDEO_FPS,
     ...turnArgs,
     ...websiteArgs,
+    ...frameArgs,
+    ...corsArgs,
     ...(shareUrl ? ['--share-url', shareUrl] : []),
     ...(disableShare ? ['--disable-share'] : []),
     ...(launchAppIdentifier ? ['--launch-app-identifier', launchAppIdentifier] : []),
@@ -179,12 +195,16 @@ export function createExpoDeviceHubArgs({
   port,
   turnArgs = [],
   websiteArgs = [],
+  frameAncestorArgs: frameArgs = [],
+  corsOriginArgs: corsArgs = [],
   packageVersion,
   recordingDirectory,
 }: {
   port: number;
   turnArgs?: string[];
   websiteArgs?: string[];
+  frameAncestorArgs?: string[];
+  corsOriginArgs?: string[];
   packageVersion?: string;
   recordingDirectory?: string;
 }): string[] {
@@ -214,6 +234,8 @@ export function createExpoDeviceHubArgs({
     ...(recordingDirectory ? ['--android-recording-directory', recordingDirectory] : []),
     ...turnArgs,
     ...websiteArgs,
+    ...frameArgs,
+    ...corsArgs,
   ];
 }
 
@@ -353,6 +375,10 @@ type DeviceSessionHostOptions = {
   packageVersion?: string;
   disableShare?: boolean;
   privatePreviewUrl?: string;
+  /** Origins allowed to embed the preview host, in addition to the website origins. */
+  frameAncestors?: string[];
+  /** Origins whose pages may call the preview host's API, in addition to the website origins. */
+  corsOrigins?: string[];
   iosSimulatorUdid?: string;
   installAppPath?: string;
   bootEnv?: Record<string, string>;
@@ -403,6 +429,8 @@ async function startDeviceSessionHostInternalAsync(
     onStartupError,
     disableShare = false,
     privatePreviewUrl,
+    frameAncestors = [],
+    corsOrigins = [],
     launchAppIdentifier,
     launchArgs,
     openUrl,
@@ -464,7 +492,7 @@ async function startDeviceSessionHostInternalAsync(
   const packageSpec = isAndroid
     ? createExpoDeviceHubPackageSpec(packageVersion)
     : createServeSimPackageSpec(packageVersion);
-  const turnArgs = await fetchWebPreviewTurnArgsAsync(ctx, { env, logger });
+  const turnArgs = await fetchWebPreviewTurnArgsAsync(ctx, { logger });
   const previewExec = resolvePackageExec(
     resolveConfiguredPackageManager(env, PackageManager.NPM),
     isAndroid
@@ -474,6 +502,8 @@ async function startDeviceSessionHostInternalAsync(
           packageVersion,
           recordingDirectory: recording?.directory,
           websiteArgs: websiteOriginArgs(env),
+          frameAncestorArgs: frameAncestorArgs(frameAncestors),
+          corsOriginArgs: corsOriginArgs(corsOrigins),
         })
       : createServeSimArgs({
           port,
@@ -481,6 +511,8 @@ async function startDeviceSessionHostInternalAsync(
           packageVersion,
           iosSimulatorUdid,
           websiteArgs: websiteOriginArgs(env),
+          frameAncestorArgs: frameAncestorArgs(frameAncestors),
+          corsOriginArgs: corsOriginArgs(corsOrigins),
           // serve-sim adds its bearer token to --share-url; private links are for worker logs only.
           shareUrl: disableShare ? undefined : previewPageUrl,
           disableShare,

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

@@ -10,8 +10,6 @@ import {
 } 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';
@@ -29,49 +27,15 @@ import {
 import { Sentry } from '../../sentry';
 import { isProcessGroupRunning } from '../../utils/processes';
 import { sleepAsync } from '../../utils/retry';
-import { turtleFetch } from '../../utils/turtleFetch';
 import { createProcessOutput } from './processOutput';
 import { withDeviceRunSessionTimeoutAsync } from './deviceRunSessionTimeout';
-import { getDeviceRunSessionWorkerApi } from './deviceRunSessionWorkerApi';
+import {
+  type DeviceRunSessionStatus,
+  requireDeviceRunSessionWorkerApi,
+} from './deviceRunSessionWorkerApi';
 
 const XCODE_DEVELOPER_DIR = '/Applications/Xcode.app/Contents/Developer';
 
-const START_DEVICE_RUN_SESSION_MUTATION = graphql(`
-  mutation StartDeviceRunSession($deviceRunSessionId: ID!, $remoteConfig: JSONObject!) {
-    deviceRunSession {
-      startDeviceRunSession(
-        deviceRunSessionId: $deviceRunSessionId
-        remoteConfig: $remoteConfig
-      ) {
-        id
-        status
-      }
-    }
-  }
-`);
-
-const DEVICE_RUN_SESSION_STATUS_QUERY = graphql(`
-  query DeviceRunSessionStatus($deviceRunSessionId: ID!) {
-    deviceRunSessions {
-      byId(deviceRunSessionId: $deviceRunSessionId) {
-        id
-        status
-      }
-    }
-  }
-`);
-
-const ENSURE_DEVICE_RUN_SESSION_STOPPED_MUTATION = graphql(`
-  mutation EnsureDeviceRunSessionStopped($deviceRunSessionId: ID!) {
-    deviceRunSession {
-      ensureDeviceRunSessionStopped(deviceRunSessionId: $deviceRunSessionId) {
-        id
-        status
-      }
-    }
-  }
-`);
-
 const DEVICE_RUN_SESSION_STATUS_POLL_INTERVAL_MS = 5_000;
 // A request to the device run session worker API that hangs counts as a failed poll or stop.
 const DEVICE_RUN_SESSION_WORKER_REQUEST_TIMEOUT_MS = 30_000;
@@ -230,15 +194,12 @@ export async function waitForDeviceRunSessionStoppedAsync({
       }
       try {
         const status = await fetchDeviceRunSessionStatusAsync(ctx, deviceRunSessionId, signal);
-        if (!status) {
-          throw new Error(`Device run session ${deviceRunSessionId} status response was missing.`);
-        }
         pollErrorCount = 0;
-        if (status === 'STOPPED') {
+        if (status === 'stopped') {
           logger.info(`Device run session ${deviceRunSessionId} was stopped.`);
           return;
         }
-        if (status === 'ERRORED') {
+        if (status === 'errored') {
           throw new SystemError(`Device run session ${deviceRunSessionId} errored.`);
         }
       } catch (err) {
@@ -269,24 +230,14 @@ async function fetchDeviceRunSessionStatusAsync(
   ctx: CustomBuildContext,
   deviceRunSessionId: string,
   signal: AbortSignal
-): Promise<string | undefined> {
-  const workerApi = getDeviceRunSessionWorkerApi(ctx);
-  if (workerApi) {
-    // One request per poll; the polling loop retries on its own schedule.
-    return (
-      await workerApi.getSessionAsync({
-        signal,
-        timeoutMs: DEVICE_RUN_SESSION_WORKER_REQUEST_TIMEOUT_MS,
-      })
-    ).status;
-  }
-  const result = await ctx.graphqlClient
-    .query(DEVICE_RUN_SESSION_STATUS_QUERY, { deviceRunSessionId })
-    .toPromise();
-  if (result.error) {
-    throw result.error;
-  }
-  return result.data?.deviceRunSessions?.byId?.status;
+): Promise<DeviceRunSessionStatus['status']> {
+  // One request per poll; the polling loop retries on its own schedule.
+  return (
+    await requireDeviceRunSessionWorkerApi(ctx).getSessionAsync({
+      signal,
+      timeoutMs: DEVICE_RUN_SESSION_WORKER_REQUEST_TIMEOUT_MS,
+    })
+  ).status;
 }
 
 // Best effort: when this fails, the caller still tears the session down and the
@@ -301,17 +252,9 @@ async function ensureDeviceRunSessionStoppedSafelyAsync({
   logger: bunyan;
 }): Promise<void> {
   try {
-    const workerApi = getDeviceRunSessionWorkerApi(ctx);
-    if (workerApi) {
-      await workerApi.stopAsync({ timeoutMs: DEVICE_RUN_SESSION_WORKER_REQUEST_TIMEOUT_MS });
-    } else {
-      const result = await ctx.graphqlClient
-        .mutation(ENSURE_DEVICE_RUN_SESSION_STOPPED_MUTATION, { deviceRunSessionId })
-        .toPromise();
-      if (result.error) {
-        throw result.error;
-      }
-    }
+    await requireDeviceRunSessionWorkerApi(ctx).stopAsync({
+      timeoutMs: DEVICE_RUN_SESSION_WORKER_REQUEST_TIMEOUT_MS,
+    });
   } catch (err) {
     const error = err instanceof Error ? err : new Error(String(err));
     Sentry.capture('Could not mark idle device run session as stopped', error, {
@@ -476,12 +419,6 @@ export async function ensureFfmpegInstalledOnceAsync({
   }
 }
 
-const TurnIceServersResponseSchema = z.object({
-  data: z.object({
-    iceServers: TurnIceServersSchema,
-  }),
-});
-
 /**
  * Translate Cloudflare ICE servers into web preview CLI flags: `--stun-url` (the
  * credential-less entries) and `--turn-url`/`--turn-username`/`--turn-credential`
@@ -523,10 +460,10 @@ export function turnIceServersToWebPreviewArgs(iceServers: TurnIceServers): stri
  */
 export async function fetchWebPreviewTurnArgsAsync(
   ctx: CustomBuildContext,
-  { env, logger }: { env: BuildStepEnv; logger: bunyan }
+  { logger }: { logger: bunyan }
 ): Promise<string[]> {
   try {
-    const iceServers = await fetchTurnIceServersAsync(ctx, { env, logger });
+    const iceServers = await fetchTurnIceServersAsync(ctx, { logger });
     const args = turnIceServersToWebPreviewArgs(iceServers);
     if (args.length > 0) {
       logger.info('Configured the web preview with Cloudflare TURN ICE servers.');
@@ -545,38 +482,13 @@ export async function fetchWebPreviewTurnArgsAsync(
 
 async function fetchTurnIceServersAsync(
   ctx: CustomBuildContext,
-  { env, logger }: { env: BuildStepEnv; logger: bunyan }
+  { logger }: { logger: bunyan }
 ): Promise<TurnIceServers> {
-  const workerApi = getDeviceRunSessionWorkerApi(ctx);
-  if (workerApi) {
-    return await workerApi.fetchTurnIceServersAsync({ timeoutMs: 5000, retries: 1, logger });
-  }
-
-  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());
-  return data.iceServers;
+  return await requireDeviceRunSessionWorkerApi(ctx).fetchTurnIceServersAsync({
+    timeoutMs: 5000,
+    retries: 1,
+    logger,
+  });
 }
 
 export async function uploadRemoteSessionConfigAsync({
@@ -593,26 +505,15 @@ export async function uploadRemoteSessionConfigAsync({
   logger.info(
     `Reporting remote config to the API server (device run session: ${deviceRunSessionId}).`
   );
-  const workerApi = getDeviceRunSessionWorkerApi(ctx);
-  if (workerApi) {
-    try {
-      await workerApi.startAsync({ remoteConfig });
-    } catch (err) {
-      throw new SystemError(
-        `Failed to start device run session ${deviceRunSessionId}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-        { cause: err }
-      );
-    }
-    return;
-  }
-  const result = await ctx.graphqlClient
-    .mutation(START_DEVICE_RUN_SESSION_MUTATION, { deviceRunSessionId, remoteConfig })
-    .toPromise();
-  if (result.error) {
+  const workerApi = requireDeviceRunSessionWorkerApi(ctx);
+  try {
+    await workerApi.startAsync({ remoteConfig });
+  } catch (err) {
     throw new SystemError(
-      `Failed to start device run session ${deviceRunSessionId}: ${result.error.message}`
+      `Failed to start device run session ${deviceRunSessionId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      { cause: err }
     );
   }
 }
@@ -880,6 +781,58 @@ export function createPrivatePreviewUrlInputProvider(): ReturnType<
   });
 }
 
+/**
+ * Origins that may embed the preview host in a frame, next to the website origins. The host
+ * drops values that are not an origin or a subdomain wildcard, so this parser only guards
+ * the input shape.
+ */
+export function createFrameAncestorsInputProvider(): ReturnType<
+  typeof BuildStepInput.createProvider
+> {
+  return BuildStepInput.createProvider({
+    id: 'frame_ancestors',
+    required: false,
+    allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+  });
+}
+
+export function parseFrameAncestorsInput(value: unknown): string[] {
+  return parseOriginListInput(value, 'frame_ancestors', 'EAS_FRAME_ANCESTORS_INVALID_INPUT');
+}
+
+/**
+ * Origins whose pages may call the preview host's API cross-origin, such as a page that renders
+ * the device with @expo/hub-client. Framing alone does not need it. The host refuses values that
+ * are not an origin or a subdomain wildcard, so this parser only guards the input shape.
+ */
+export function createCorsOriginsInputProvider(): ReturnType<typeof BuildStepInput.createProvider> {
+  return BuildStepInput.createProvider({
+    id: 'cors_origins',
+    required: false,
+    allowedValueTypeName: BuildStepInputValueTypeName.JSON,
+  });
+}
+
+export function parseCorsOriginsInput(value: unknown): string[] {
+  return parseOriginListInput(value, 'cors_origins', 'EAS_CORS_ORIGINS_INVALID_INPUT');
+}
+
+function parseOriginListInput(value: unknown, inputId: string, errorCode: string): string[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (
+    !Array.isArray(value) ||
+    !value.every(origin => typeof origin === 'string' && origin.trim().length > 0)
+  ) {
+    throw new UserError(
+      errorCode,
+      `Input "${inputId}" must be an array of non-empty strings, one origin each.`
+    );
+  }
+  return value;
+}
+
 export function parseServeSimLaunchInputs(
   {
     launchAppIdentifier: rawLaunchAppIdentifier,

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

@@ -154,8 +154,10 @@ export namespace AndroidEmulatorUtils {
     try {
       let configIniFileContent = await fs.promises.readFile(configIniFile, 'utf-8');
 
-      logger.info('Setting hw.ramSize to 2048.');
-      configIniFileContent = `${configIniFileContent}\nhw.ramSize=2048\n`;
+      // Give interactive sessions more headroom for guest VSOCK packet allocations.
+      const ramSize = env.DEVICE_RUN_SESSION_ID ? 4096 : 2048;
+      logger.info(`Setting hw.ramSize to ${ramSize}.`);
+      configIniFileContent = `${configIniFileContent}\nhw.ramSize=${ramSize}\n`;
 
       const shouldResizeScreen =
         env.ANDROID_EMULATOR_ADJUST_SCREEN === 'true' || env.ANDROID_EMULATOR_ADJUST_SCREEN === '1';

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

@@ -136,7 +136,10 @@ describe('AndroidEmulatorUtils', () => {
       );
     });
 
-    it('does not apply an LCD configuration when it is omitted', async () => {
+    it.each([
+      [undefined, 2048],
+      ['device-run-session-id', 4096],
+    ])('configures memory for session %s without an LCD override', async (sessionId, ramSize) => {
       const deviceName = 'generic-emulator' as AndroidVirtualDeviceName;
       const avdDirectory = `/home/expo/.android/avd/${deviceName}.avd`;
       const initialConfig = ['skin.path=pixel_9', 'showDeviceFrame=yes'].join('\n');
@@ -156,12 +159,14 @@ describe('AndroidEmulatorUtils', () => {
         env: {
           HOME: '/home/expo',
           ANDROID_EMULATOR_ADJUST_HEAP_SIZE: '0',
+          DEVICE_RUN_SESSION_ID: sessionId,
         },
         logger: createMockLogger(),
       });
 
       const config = await fs.promises.readFile(`${avdDirectory}/config.ini`, 'utf8');
       expect(config).toContain(initialConfig);
+      expect(config).toContain(`hw.ramSize=${ramSize}\n`);
       expect(config).not.toContain('hw.lcd.');
     });
   });

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

@@ -3,7 +3,13 @@ import promiseRetry from 'promise-retry';
 export function promiseRetryWithCondition<TFn extends (...args: any[]) => Promise<any>>(
   fn: TFn,
   retryConditionFn: (error: any) => boolean,
-  options: { retries: number; factor?: number; minTimeout?: number; maxTimeout?: number } = {
+  options: {
+    retries: number;
+    factor?: number;
+    minTimeout?: number;
+    maxTimeout?: number;
+    randomize?: boolean;
+  } = {
     retries: 3,
     factor: 2,
   },

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

@@ -1,5 +1,13 @@
 # create-eas-build-function
 
+## 25.1.1
+
+No changes in this release.
+
+## 25.1.0
+
+No changes in this release.
+
 ## 25.0.0
 
 No changes in this release.

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

@@ -1,6 +1,6 @@
 {
   "name": "create-eas-build-function",
-  "version": "25.0.0",
+  "version": "25.1.1",
   "description": "Create functions for use in EAS Build custom builds.",
   "keywords": [
     "expo",
@@ -35,7 +35,7 @@
     "clean": "rimraf ./build/ \"*.tsbuildinfo\""
   },
   "dependencies": {
-    "@expo/steps": "25.0.0"
+    "@expo/steps": "25.1.1"
   },
   "devDependencies": {
     "@expo/package-manager": "1.9.10",

packages/downloader/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @expo/downloader
 
+## 25.1.1
+
+No changes in this release.
+
+## 25.1.0
+
+No changes in this release.
+
 ## 25.0.0
 
 No changes in this release.

packages/downloader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/downloader",
-  "version": "25.0.0",
+  "version": "25.1.1",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",

packages/eas-build-cache-provider/CHANGELOG.md

@@ -1,5 +1,13 @@
 # eas-build-cache-provider
 
+## 25.1.1
+
+No changes in this release.
+
+## 25.1.0
+
+No changes in this release.
+
 ## 25.0.0
 
 No changes in this release.

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

@@ -1,6 +1,6 @@
 {
   "name": "eas-build-cache-provider",
-  "version": "25.0.0",
+  "version": "25.1.1",
   "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/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @expo/eas-build-job
 
+## 25.1.1
+
+No changes in this release.
+
+## 25.1.0
+
+No changes in this release.
+
 ## 25.0.0
 
 No changes in this release.

packages/eas-build-job/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/eas-build-job",
-  "version": "25.0.0",
+  "version": "25.1.1",
   "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": "25.0.0",
+    "@expo/logger": "25.1.1",
     "@expo/results": "1.0.0",
-    "@expo/turtle-spawn": "25.0.0",
+    "@expo/turtle-spawn": "25.1.1",
     "joi": "^17.13.1",
     "semver": "^7.6.2",
     "zod": "^4.3.5"

packages/eas-cli/CHANGELOG.md

@@ -1,5 +1,17 @@
 # eas-cli
 
+## 25.1.1
+
+No changes in this release.
+
+## 25.1.0
+
+### Minor Changes
+
+- Show EAS Simulator minutes in `eas account:usage`. ([#4583](https://github.com/expo/eas-cli/pull/4583) by [@LipLoody](https://github.com/LipLoody))
+- Add `--cors-origin` to `eas simulator:start`, so a third party page can call the simulator preview API, for example with `@expo/hub-client`. ([#4658](https://github.com/expo/eas-cli/pull/4658) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+- Add `--frame-ancestor` to `eas simulator:start`, so a third party site can embed the simulator preview, and print the embeddable preview URL. ([#4656](https://github.com/expo/eas-cli/pull/4656) by [@krystofwoldrich](https://github.com/krystofwoldrich))
+
 ## 25.0.0
 
 ### Major Changes

packages/eas-cli/graphql.schema.json

@@ -45707,6 +45707,26 @@
             "isDeprecated": false,
             "deprecationReason": null
           },
+          {
+            "name": "corsOrigins",
+            "description": "Origins of pages that may call the session's preview host API cross-origin, for example to\nrender the device with @expo/hub-client. Framing the preview does not need this. Same value\nrules as frameAncestors. At most 10. The page still needs the preview token from remoteConfig.\nIf omitted, only expo.dev may call the preview API cross-origin.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "SCALAR",
+                  "name": "String",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
           {
             "name": "egress",
             "description": "Where the virtual device's proxied network traffic exits to the internet. If\nomitted, all traffic exits from EAS infrastructure.",
@@ -45731,6 +45751,26 @@
             "isDeprecated": false,
             "deprecationReason": null
           },
+          {
+            "name": "frameAncestors",
+            "description": "Origins of pages that may embed the session's preview host in a frame, next to expo.dev.\nEach value is an https origin such as https://app.example.com or a subdomain wildcard such\nas https://*.example.com; plain http is accepted for localhost only. At most 10. The\nembedding page still needs the preview token from remoteConfig, and whoever embeds the\npreview can also control the device. If omitted, only expo.dev may embed the preview.",
+            "type": {
+              "kind": "LIST",
+              "name": null,
+              "ofType": {
+                "kind": "NON_NULL",
+                "name": null,
+                "ofType": {
+                  "kind": "SCALAR",
+                  "name": "String",
+                  "ofType": null
+                }
+              }
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
           {
             "name": "ios",
             "description": "iOS Simulator options. Only supported when platform is IOS.",

packages/eas-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eas-cli",
-  "version": "25.0.0",
+  "version": "25.1.1",
   "description": "EAS command line tool",
   "keywords": [
     "cli",
@@ -48,11 +48,12 @@
     "@expo/code-signing-certificates": "0.0.5",
     "@expo/config": "55.0.10",
     "@expo/config-plugins": "55.0.7",
-    "@expo/eas-build-job": "25.0.0",
-    "@expo/eas-json": "25.0.0",
+    "@expo/eas-build-job": "25.1.1",
+    "@expo/eas-json": "25.1.1",
     "@expo/env": "^1.0.0",
+    "@expo/experimentation": "0.0.5",
     "@expo/json-file": "8.3.3",
-    "@expo/logger": "25.0.0",
+    "@expo/logger": "25.1.1",
     "@expo/multipart-body-parser": "2.0.0",
     "@expo/osascript": "2.1.4",
     "@expo/package-manager": "1.9.10",
@@ -64,7 +65,7 @@
     "@expo/results": "1.0.0",
     "@expo/rudder-sdk-node": "1.1.1",
     "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "25.0.0",
+    "@expo/steps": "25.1.1",
     "@expo/timeago.js": "1.0.0",
     "@oclif/core": "^4.8.3",
     "@oclif/plugin-autocomplete": "^3.2.40",

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

@@ -0,0 +1,25 @@
+import EasCommand from '../../commandUtils/EasCommand';
+import { mockCommandContext } from './utils';
+
+jest.mock('fs');
+
+class TestCommand extends EasCommand {
+  static override contextDefinition = {
+    ...this.ContextOptions.LoggedIn,
+    ...this.ContextOptions.Experimentation,
+  };
+
+  async runAsync(): Promise<void> {}
+}
+
+describe(mockCommandContext, () => {
+  it('provides a disabled experimentation client that returns defaults', async () => {
+    const ctx = mockCommandContext(TestCommand, {});
+    const client = await ctx.experimentation.getClientAsync();
+    expect(client.getUserNamespace('any').getParam('variant', 'control')).toBe('control');
+    expect(client.getAccountNamespace('any', { accountId: 'a' }).getParam('enabled', true)).toBe(
+      true
+    );
+    expect(client.getDeviceNamespace('any').getParam('count', 3)).toBe(3);
+  });
+});

packages/eas-cli/src/__tests__/commands/utils.ts

@@ -7,6 +7,9 @@ import { v4 as uuidv4 } from 'uuid';
 
 import { ContextInput, ContextOutput } from '../../commandUtils/EasCommand';
 import { DynamicConfigContextFn } from '../../commandUtils/context/DynamicProjectConfigContextField';
+import { ExperimentOverrides } from '../../experimentation/ExperimentOverrides';
+import { ExperimentationClient } from '../../experimentation/ExperimentationClient';
+import { LazyExperimentationClient } from '../../experimentation/LazyExperimentationClient';
 import {
   AppFragment,
   Role,
@@ -96,6 +99,11 @@ export function mockCommandContext<
     if (contextKey === 'sessionManager') {
       result.sessionManager = {};
     }
+    if (contextKey === 'experimentation') {
+      result.experimentation = LazyExperimentationClient.fromClient(
+        ExperimentationClient.createDisabled(ExperimentOverrides.empty())
+      );
+    }
     if (contextKey === 'projectConfig') {
       result.projectConfig = {
         exp: overrides.exp ?? getMockExpoConfig(),

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

@@ -21,12 +21,17 @@ export type AnalyticsEvent =
   | SubmissionEvent
   | MetadataEvent
   | BillingEvent
-  | SimulatorEvent;
+  | SimulatorEvent
+  | ExperimentationEvent;
 
 export enum CommandEvent {
   ACTION = 'action', // generic event type which is used to determine the 'daily active user' stat, include an `action: eas ${subcommand}` property inside of the event properties object
 }
 
+export enum ExperimentationEvent {
+  EXPERIMENT_VIEWED = 'Experiment Viewed',
+}
+
 export enum BillingEvent {
   SUBSCRIBE_COMMAND = 'billing cli subscribe command',
 }
@@ -105,6 +110,8 @@ export interface Analytics {
 export interface AnalyticsWithOrchestration extends Analytics {
   setActor(actor: Actor): void;
   flushAsync(): Promise<void>;
+  /** The persisted RudderStack anonymous ID, or null when analytics is disabled. */
+  getDeviceId(): string | null;
 }
 
 const USER_SETTINGS_KEY_AMPLITUDE_ENABLED = 'amplitudeEnabled';
@@ -183,6 +190,9 @@ class NoOpAnalytics implements AnalyticsWithOrchestration {
   logEvent(): void {}
   setActor(): void {}
   async flushAsync(): Promise<void> {}
+  getDeviceId(): null {
+    return null;
+  }
 }
 
 const RudderstackAnalyticsConfig =
@@ -234,6 +244,10 @@ class RudderstackAnalytics implements AnalyticsWithOrchestration {
     this.identifiedActor = actor;
   }
 
+  public getDeviceId(): string {
+    return this.persistentDeviceId;
+  }
+
   public logEvent(name: AnalyticsEvent, properties: AnalyticsEventProperties): void {
     const userId = this.identifiedActor?.id;
     const deviceId = this.persistentDeviceId;

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

@@ -140,3 +140,55 @@ describe(isAnalyticsOptedOutAsync, () => {
     await expect(isAnalyticsOptedOutAsync()).resolves.toBe(true);
   });
 });
+
+describe('getDeviceId', () => {
+  // Backs UserSettings with an in-memory store so a value written by createAnalyticsAsync is read back.
+  function useInMemoryUserSettings(initial: Record<string, unknown>): void {
+    const stored: Record<string, unknown> = { ...initial };
+    (userSettingsMock.setAsync as jest.Mock).mockImplementation(
+      async (key: string, value: unknown) => {
+        stored[key] = value;
+        return {};
+      }
+    );
+    (userSettingsMock.getAsync as jest.Mock).mockImplementation(
+      async (key: string, defaultValue: unknown) => (key in stored ? stored[key] : defaultValue)
+    );
+  }
+
+  it('returns the persisted analytics device ID', async () => {
+    const analytics = await createAnalyticsAsync();
+    expect(analytics.getDeviceId()).toBe('persistent-device-id');
+  });
+
+  it('creates and persists a device ID when none is stored', async () => {
+    userSettingsMock.getAsync.mockImplementation(async (key, defaultValue) =>
+      key === 'analyticsDeviceId' ? null : defaultValue
+    );
+    const analytics = await createAnalyticsAsync();
+    const deviceId = analytics.getDeviceId();
+    expect(deviceId).toMatch(/^[0-9a-f-]{36}$/);
+    expect(userSettingsMock.setAsync).toHaveBeenCalledWith('analyticsDeviceId', deviceId);
+  });
+
+  it('is null when DISABLE_EAS_ANALYTICS is set', async () => {
+    useInMemoryUserSettings({ analyticsDeviceId: 'persistent-device-id' });
+    process.env.DISABLE_EAS_ANALYTICS = '1';
+    const analytics = await createAnalyticsAsync();
+    expect(analytics.getDeviceId()).toBeNull();
+  });
+
+  it('is null when running behind https_proxy', async () => {
+    process.env.https_proxy = 'http://proxy.local:8080';
+    const analytics = await createAnalyticsAsync();
+    expect(analytics.getDeviceId()).toBeNull();
+  });
+
+  it('is null when analytics were turned off with eas analytics off', async () => {
+    userSettingsMock.getAsync.mockImplementation(async (key, defaultValue) =>
+      key === 'analyticsEnabled' ? false : defaultValue
+    );
+    const analytics = await createAnalyticsAsync();
+    expect(analytics.getDeviceId()).toBeNull();
+  });
+});

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

@@ -0,0 +1,280 @@
+import type { ExperimentationDefinition } from '@expo/experimentation';
+import { Platform } from '@expo/eas-build-job';
+
+import { getAgentTelemetryContext } from '../../analytics/agent';
+import { ExperimentOverrides } from '../../experimentation/ExperimentOverrides';
+import {
+  EMPTY_EXPERIMENTATION_DEFINITION,
+  ExperimentationClient,
+  createLoggerConfig,
+} from '../../experimentation/ExperimentationClient';
+import { LazyExperimentationClient } from '../../experimentation/LazyExperimentationClient';
+import { createMockAnalytics, findUnitsByValue } from '../../experimentation/__tests__/fixtures';
+import {
+  FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE,
+  getFreeTierLimitAgentGuidanceExperiment,
+  maybeAppendFreeTierLimitAgentGuidanceAsync,
+  resolveFreeTierLimitAgentGuidanceVariantAsync,
+} from '../freeTierLimitGuidance';
+
+jest.mock('../../analytics/agent');
+
+const EXPERIMENT_NAME = 'cli-build-free-tier-limit-agent-guidance';
+
+/** Every account is in the experiment: 50% control, 50% treatment. */
+const ACCOUNT_DEFINITION: ExperimentationDefinition = {
+  experiments: [
+    {
+      experimentName: EXPERIMENT_NAME,
+      paramDefinitions: {
+        variant: { type: 'uniform_choice', choices: ['control', 'treatment'] },
+      },
+      exposureLoggerType: 'rudderstack',
+    },
+  ],
+  namespaces: [
+    {
+      name: FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE,
+      numSegments: 1000,
+      segmentExperimentSetupDefinitions: [
+        {
+          method: 'ADD',
+          name: `${EXPERIMENT_NAME} full`,
+          experimentName: EXPERIMENT_NAME,
+          numSegments: 1000,
+        },
+      ],
+    },
+  ],
+};
+
+function createClient(): {
+  client: ExperimentationClient;
+  analytics: ReturnType<typeof createMockAnalytics>;
+} {
+  const analytics = createMockAnalytics();
+  const client = new ExperimentationClient(
+    {
+      user: EMPTY_EXPERIMENTATION_DEFINITION,
+      account: ACCOUNT_DEFINITION,
+      device: EMPTY_EXPERIMENTATION_DEFINITION,
+    },
+    { user: null, device: null },
+    ExperimentOverrides.empty(),
+    createLoggerConfig(analytics)
+  );
+  return { client, analytics };
+}
+
+/** Probes a throwaway client, so the exposures it logs do not affect the client under test. */
+function findAccountIdsByVariant(): Map<string, string> {
+  const { client } = createClient();
+  return findUnitsByValue(
+    accountId =>
+      client.getAccountNamespace(FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE, {
+        accountId,
+      }),
+    'variant',
+    'control',
+    ['control', 'treatment']
+  );
+}
+
+describe(getFreeTierLimitAgentGuidanceExperiment, () => {
+  it('returns the handle when the command has an experimentation client', () => {
+    const experimentation = new LazyExperimentationClient(async () => createClient().client);
+
+    expect(
+      getFreeTierLimitAgentGuidanceExperiment({ experimentation, accountId: 'account-id' })
+    ).toEqual({ experimentation, accountId: 'account-id' });
+  });
+
+  it('returns undefined when the command has no experimentation client', () => {
+    expect(getFreeTierLimitAgentGuidanceExperiment({ accountId: 'account-id' })).toBeUndefined();
+  });
+});
+
+describe(resolveFreeTierLimitAgentGuidanceVariantAsync, () => {
+  const accountIdsByVariant = findAccountIdsByVariant();
+  const treatmentAccountId = accountIdsByVariant.get('treatment')!;
+  const controlAccountId = accountIdsByVariant.get('control')!;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest
+      .mocked(getAgentTelemetryContext)
+      .mockReturnValue({ id: 'claude-code', sessionId: 'session-1' });
+  });
+
+  it('does not load the client when no coding agent runs the CLI', async () => {
+    jest.mocked(getAgentTelemetryContext).mockReturnValue(null);
+    const loadAsync = jest.fn(async () => createClient().client);
+
+    expect(
+      await resolveFreeTierLimitAgentGuidanceVariantAsync({
+        experimentation: new LazyExperimentationClient(loadAsync),
+        accountId: treatmentAccountId,
+      })
+    ).toBe('control');
+    expect(loadAsync).not.toHaveBeenCalled();
+  });
+
+  it('loads the client once across repeated reads', async () => {
+    const { client, analytics } = createClient();
+    const loadAsync = jest.fn(async () => client);
+    const experiment = {
+      experimentation: new LazyExperimentationClient(loadAsync),
+      accountId: treatmentAccountId,
+    };
+
+    await resolveFreeTierLimitAgentGuidanceVariantAsync(experiment);
+    await resolveFreeTierLimitAgentGuidanceVariantAsync(experiment);
+
+    expect(loadAsync).toHaveBeenCalledTimes(1);
+    expect(analytics.logEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns control and logs no exposure when no coding agent runs the CLI', async () => {
+    jest.mocked(getAgentTelemetryContext).mockReturnValue(null);
+    const { client, analytics } = createClient();
+
+    expect(
+      await resolveFreeTierLimitAgentGuidanceVariantAsync({
+        experimentation: LazyExperimentationClient.fromClient(client),
+        accountId: treatmentAccountId,
+      })
+    ).toBe('control');
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+  });
+
+  it('returns the account variant and logs the exposure once when a coding agent runs the CLI', async () => {
+    const { client, analytics } = createClient();
+
+    expect(
+      await resolveFreeTierLimitAgentGuidanceVariantAsync({
+        experimentation: LazyExperimentationClient.fromClient(client),
+        accountId: treatmentAccountId,
+      })
+    ).toBe('treatment');
+    expect(
+      await resolveFreeTierLimitAgentGuidanceVariantAsync({
+        experimentation: LazyExperimentationClient.fromClient(client),
+        accountId: treatmentAccountId,
+      })
+    ).toBe('treatment');
+
+    expect(analytics.logEvent).toHaveBeenCalledTimes(1);
+    expect(analytics.logEvent).toHaveBeenCalledWith('Experiment Viewed', {
+      experimentName: EXPERIMENT_NAME,
+      variationName: 'treatment',
+      unit: treatmentAccountId,
+    });
+  });
+
+  it('logs the exposure for control accounts too', async () => {
+    const { client, analytics } = createClient();
+
+    expect(
+      await resolveFreeTierLimitAgentGuidanceVariantAsync({
+        experimentation: LazyExperimentationClient.fromClient(client),
+        accountId: controlAccountId,
+      })
+    ).toBe('control');
+    expect(analytics.logEvent).toHaveBeenCalledWith('Experiment Viewed', {
+      experimentName: EXPERIMENT_NAME,
+      variationName: 'control',
+      unit: controlAccountId,
+    });
+  });
+
+  it('returns control and logs no exposure when the namespace is missing from the config', async () => {
+    const analytics = createMockAnalytics();
+    const client = new ExperimentationClient(
+      {
+        user: EMPTY_EXPERIMENTATION_DEFINITION,
+        account: EMPTY_EXPERIMENTATION_DEFINITION,
+        device: EMPTY_EXPERIMENTATION_DEFINITION,
+      },
+      { user: null, device: null },
+      ExperimentOverrides.empty(),
+      createLoggerConfig(analytics)
+    );
+
+    expect(
+      await resolveFreeTierLimitAgentGuidanceVariantAsync({
+        experimentation: LazyExperimentationClient.fromClient(client),
+        accountId: treatmentAccountId,
+      })
+    ).toBe('control');
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+  });
+});
+
+describe(maybeAppendFreeTierLimitAgentGuidanceAsync, () => {
+  const treatmentAccountId = findAccountIdsByVariant().get('treatment')!;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest
+      .mocked(getAgentTelemetryContext)
+      .mockReturnValue({ id: 'claude-code', sessionId: 'session-1' });
+  });
+
+  it('returns the message unchanged and logs no exposure when the command has no experimentation client', async () => {
+    expect(await maybeAppendFreeTierLimitAgentGuidanceAsync('Error 1', Platform.ANDROID, undefined)).toBe(
+      'Error 1'
+    );
+  });
+
+  it('logs the exposure and appends the guidance in the treatment arm', async () => {
+    const { client, analytics } = createClient();
+
+    expect(
+      await maybeAppendFreeTierLimitAgentGuidanceAsync('Error 1', Platform.IOS, {
+        experimentation: LazyExperimentationClient.fromClient(client),
+        accountId: treatmentAccountId,
+      })
+    ).toBe(
+      [
+        'Error 1',
+        'Fix: Human required: iOS builds for this account are blocked until the Free plan resets. Upgrading costs money, so an account owner or admin decides.',
+      ].join('\n')
+    );
+    expect(analytics.logEvent).toHaveBeenCalledTimes(1);
+    expect(analytics.logEvent).toHaveBeenCalledWith('Experiment Viewed', {
+      experimentName: EXPERIMENT_NAME,
+      variationName: 'treatment',
+      unit: treatmentAccountId,
+    });
+  });
+
+  it('returns the message unchanged in the control arm', async () => {
+    const client = ExperimentationClient.createDisabled(
+      new ExperimentOverrides(
+        new Map([
+          [FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE, new Map([['variant', 'control']])],
+        ])
+      )
+    );
+
+    expect(
+      await maybeAppendFreeTierLimitAgentGuidanceAsync('Error 1', Platform.ANDROID, {
+        experimentation: LazyExperimentationClient.fromClient(client),
+        accountId: treatmentAccountId,
+      })
+    ).toBe('Error 1');
+  });
+
+  it('returns the message unchanged and logs no exposure when no coding agent runs the CLI', async () => {
+    jest.mocked(getAgentTelemetryContext).mockReturnValue(null);
+    const { client, analytics } = createClient();
+
+    expect(
+      await maybeAppendFreeTierLimitAgentGuidanceAsync('Error 1', Platform.ANDROID, {
+        experimentation: LazyExperimentationClient.fromClient(client),
+        accountId: treatmentAccountId,
+      })
+    ).toBe('Error 1');
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+  });
+});

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

@@ -3,11 +3,15 @@ import { CombinedError } from '@urql/core';
 import { GraphQLError } from 'graphql/error';
 import { v4 as uuidv4 } from 'uuid';
 
-import { getError } from '../../__tests__/commands/utils';
+import { getErrorAsync } from '../../__tests__/commands/utils';
+import { getAgentTelemetryContext } from '../../analytics/agent';
 import { EasCommandError } from '../../commandUtils/errors';
 import Build from '../../commands/build';
+import { ExperimentOverrides } from '../../experimentation/ExperimentOverrides';
+import { ExperimentationClient } from '../../experimentation/ExperimentationClient';
+import { LazyExperimentationClient } from '../../experimentation/LazyExperimentationClient';
 import Log, { link } from '../../log';
-import { handleBuildRequestError } from '../build';
+import { handleBuildRequestErrorAsync } from '../build';
 import {
   EasBuildDownForMaintenanceError,
   EasBuildFreeTierDisabledAndroidError,
@@ -20,11 +24,34 @@ import {
   RequestValidationError,
   TurtleDeprecatedJobFormatError,
 } from '../errors';
+import {
+  FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE,
+  FreeTierLimitAgentGuidanceExperiment,
+} from '../freeTierLimitGuidance';
+
+jest.mock('../../analytics/agent');
 
 beforeEach(() => {
   jest.resetAllMocks();
+  jest.mocked(getAgentTelemetryContext).mockReturnValue(null);
 });
 
+/** An experiment handle whose client is forced to the given variant through an override. */
+function createExperiment(variant: string): FreeTierLimitAgentGuidanceExperiment {
+  return {
+    accountId: 'account-id',
+    experimentation: LazyExperimentationClient.fromClient(
+      ExperimentationClient.createDisabled(
+        new ExperimentOverrides(
+          new Map([
+            [FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE, new Map([['variant', variant]])],
+          ])
+        )
+      )
+    ),
+  };
+}
+
 const EXPECTED_STRINGIFIED_GRAPHQL_ERROR_JSON = `Build request error details:
 {
   "message": "[GraphQL] Error 1\\n[GraphQL] Error 2\\n[GraphQL] Error 3",
@@ -84,7 +111,7 @@ describe(Build.name, () => {
         const error = new CombinedError({ graphQLErrors });
 
         try {
-          handleBuildRequestError(error, platform);
+          await handleBuildRequestErrorAsync(error, platform);
         } catch {}
 
         expect(logDebugSpy).toBeCalledWith(EXPECTED_STRINGIFIED_GRAPHQL_ERROR_JSON);
@@ -97,7 +124,7 @@ describe(Build.name, () => {
         const error = new CombinedError({ graphQLErrors });
 
         try {
-          handleBuildRequestError(error, platform);
+          await handleBuildRequestErrorAsync(error, platform);
         } catch {}
 
         expect(logDebugSpy).toBeCalledWith(EXPECTED_STRINGIFIED_GRAPHQL_ERROR_JSON);
@@ -111,7 +138,7 @@ describe(Build.name, () => {
         const error = new Error('Generic error');
 
         try {
-          handleBuildRequestError(error, platform);
+          await handleBuildRequestErrorAsync(error, platform);
         } catch {}
 
         expect(logDebugSpy).not.toHaveBeenCalled();
@@ -123,7 +150,7 @@ describe(Build.name, () => {
         const error = new Error('Generic error');
 
         try {
-          handleBuildRequestError(error, platform);
+          await handleBuildRequestErrorAsync(error, platform);
         } catch {}
 
         expect(logDebugSpy).not.toHaveBeenCalled();
@@ -139,9 +166,9 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<TurtleDeprecatedJobFormatError>(
-              () => {
-                handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<TurtleDeprecatedJobFormatError>(
+              async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               }
             );
 
@@ -162,8 +189,8 @@ describe(Build.name, () => {
             const error = new CombinedError({ graphQLErrors });
 
             const handleBuildRequestErrorThrownError =
-              getError<EasBuildResourceClassNotAvailableInFreeTierError>(() => {
-                handleBuildRequestError(error, platform);
+              await getErrorAsync<EasBuildResourceClassNotAvailableInFreeTierError>(async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               });
 
             assertReThrownError(
@@ -180,9 +207,9 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<TurtleDeprecatedJobFormatError>(
-              () => {
-                handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<TurtleDeprecatedJobFormatError>(
+              async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               }
             );
 
@@ -203,8 +230,8 @@ describe(Build.name, () => {
             const error = new CombinedError({ graphQLErrors });
 
             const handleBuildRequestErrorThrownError =
-              getError<EasBuildResourceClassNotAvailableInFreeTierError>(() => {
-                handleBuildRequestError(error, platform);
+              await getErrorAsync<EasBuildResourceClassNotAvailableInFreeTierError>(async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               });
 
             assertReThrownError(
@@ -224,9 +251,9 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<EasBuildFreeTierDisabledError>(
-              () => {
-                handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildFreeTierDisabledError>(
+              async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               }
             );
 
@@ -244,9 +271,9 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<EasBuildFreeTierDisabledError>(
-              () => {
-                handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildFreeTierDisabledError>(
+              async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               }
             );
 
@@ -266,7 +293,7 @@ describe(Build.name, () => {
           const error = new CombinedError({ graphQLErrors });
 
           try {
-            handleBuildRequestError(error, platform);
+            await handleBuildRequestErrorAsync(error, platform);
           } catch (caughtError) {
             assertReThrownError(caughtError as Error, EasBuildFreeTierDisabledIOSError, 'Error 1');
           }
@@ -279,9 +306,9 @@ describe(Build.name, () => {
           const graphQLErrors = [graphQLError];
           const error = new CombinedError({ graphQLErrors });
 
-          const handleBuildRequestErrorThrownError = getError<EasBuildFreeTierDisabledAndroidError>(
-            () => {
-              handleBuildRequestError(error, platform);
+          const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildFreeTierDisabledAndroidError>(
+            async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             }
           );
 
@@ -300,9 +327,9 @@ describe(Build.name, () => {
           const graphQLErrors = [graphQLError];
           const error = new CombinedError({ graphQLErrors });
 
-          const handleBuildRequestErrorThrownError = getError<EasBuildFreeTierLimitExceededError>(
-            () => {
-              handleBuildRequestError(error, platform, accountName);
+          const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildFreeTierLimitExceededError>(
+            async () => {
+              await handleBuildRequestErrorAsync(error, platform, accountName);
             }
           );
 
@@ -313,6 +340,115 @@ describe(Build.name, () => {
           );
         });
       });
+      describe('for free tier limit errors in the agent guidance experiment', () => {
+        beforeEach(() => {
+          jest
+            .mocked(getAgentTelemetryContext)
+            .mockReturnValue({ id: 'claude-code', sessionId: 'session-1' });
+        });
+
+        it('appends the human required block for Android in the treatment arm', async () => {
+          const platform = Platform.ANDROID;
+          const accountName = 'test-account';
+          const graphQLError = getGraphQLError('Error 1', 'EAS_BUILD_FREE_TIER_LIMIT_EXCEEDED');
+          const error = new CombinedError({ graphQLErrors: [graphQLError] });
+
+          const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildFreeTierLimitExceededError>(
+            async () => {
+              await handleBuildRequestErrorAsync(error, platform, accountName, createExperiment('treatment'));
+            }
+          );
+
+          assertReThrownError(
+            handleBuildRequestErrorThrownError,
+            EasBuildFreeTierLimitExceededError,
+            [
+              'Error 1',
+              'Run eas billing:subscribe starter --account test-account to upgrade to the Starter plan.',
+              'Fix: Human required: Android builds for this account are blocked until the Free plan resets. Upgrading costs money, so an account owner or admin decides.',
+            ].join('\n')
+          );
+        });
+
+        it('appends the human required block for iOS in the treatment arm', async () => {
+          const platform = Platform.IOS;
+          const accountName = 'test-account';
+          const graphQLError = getGraphQLError('Error 1', 'EAS_BUILD_FREE_TIER_IOS_LIMIT_EXCEEDED');
+          const error = new CombinedError({ graphQLErrors: [graphQLError] });
+
+          const handleBuildRequestErrorThrownError =
+            await getErrorAsync<EasBuildFreeTierIosLimitExceededError>(async () => {
+              await handleBuildRequestErrorAsync(error, platform, accountName, createExperiment('treatment'));
+            });
+
+          assertReThrownError(
+            handleBuildRequestErrorThrownError,
+            EasBuildFreeTierIosLimitExceededError,
+            [
+              'Error 1',
+              'Run eas billing:subscribe starter --account test-account to upgrade to the Starter plan.',
+              'Fix: Human required: iOS builds for this account are blocked until the Free plan resets. Upgrading costs money, so an account owner or admin decides.',
+            ].join('\n')
+          );
+        });
+
+        it('does not append the block in the control arm', async () => {
+          const platform = Platform.ANDROID;
+          const accountName = 'test-account';
+          const graphQLError = getGraphQLError('Error 1', 'EAS_BUILD_FREE_TIER_LIMIT_EXCEEDED');
+          const error = new CombinedError({ graphQLErrors: [graphQLError] });
+
+          const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildFreeTierLimitExceededError>(
+            async () => {
+              await handleBuildRequestErrorAsync(error, platform, accountName, createExperiment('control'));
+            }
+          );
+
+          assertReThrownError(
+            handleBuildRequestErrorThrownError,
+            EasBuildFreeTierLimitExceededError,
+            'Error 1\nRun eas billing:subscribe starter --account test-account to upgrade to the Starter plan.'
+          );
+        });
+
+        it('does not append the block when no coding agent runs the CLI', async () => {
+          jest.mocked(getAgentTelemetryContext).mockReturnValue(null);
+          const platform = Platform.ANDROID;
+          const accountName = 'test-account';
+          const graphQLError = getGraphQLError('Error 1', 'EAS_BUILD_FREE_TIER_LIMIT_EXCEEDED');
+          const error = new CombinedError({ graphQLErrors: [graphQLError] });
+
+          const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildFreeTierLimitExceededError>(
+            async () => {
+              await handleBuildRequestErrorAsync(error, platform, accountName, createExperiment('treatment'));
+            }
+          );
+
+          assertReThrownError(
+            handleBuildRequestErrorThrownError,
+            EasBuildFreeTierLimitExceededError,
+            'Error 1\nRun eas billing:subscribe starter --account test-account to upgrade to the Starter plan.'
+          );
+        });
+
+        it('does not append the block to other server-side errors', async () => {
+          const platform = Platform.ANDROID;
+          const graphQLError = getGraphQLError('Error 1', 'EAS_BUILD_FREE_TIER_DISABLED');
+          const error = new CombinedError({ graphQLErrors: [graphQLError] });
+
+          const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildFreeTierDisabledError>(
+            async () => {
+              await handleBuildRequestErrorAsync(error, platform, undefined, createExperiment('treatment'));
+            }
+          );
+
+          assertReThrownError(
+            handleBuildRequestErrorThrownError,
+            EasBuildFreeTierDisabledError,
+            'Error 1'
+          );
+        });
+      });
       describe('for EAS_BUILD_FREE_TIER_IOS_LIMIT_EXCEEDED', () => {
         it('throws correct EasCommandError subclass', async () => {
           const platform = Platform.ANDROID;
@@ -322,8 +458,8 @@ describe(Build.name, () => {
           const error = new CombinedError({ graphQLErrors });
 
           const handleBuildRequestErrorThrownError =
-            getError<EasBuildFreeTierIosLimitExceededError>(() => {
-              handleBuildRequestError(error, platform, accountName);
+            await getErrorAsync<EasBuildFreeTierIosLimitExceededError>(async () => {
+              await handleBuildRequestErrorAsync(error, platform, accountName);
             });
 
           assertReThrownError(
@@ -342,8 +478,8 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<RequestValidationError>(() => {
-              handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<RequestValidationError>(async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             });
 
             assertReThrownError(
@@ -360,8 +496,8 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<RequestValidationError>(() => {
-              handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<RequestValidationError>(async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             });
 
             assertReThrownError(
@@ -383,9 +519,9 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<EasBuildDownForMaintenanceError>(
-              () => {
-                handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildDownForMaintenanceError>(
+              async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               }
             );
 
@@ -403,9 +539,9 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<EasBuildDownForMaintenanceError>(
-              () => {
-                handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildDownForMaintenanceError>(
+              async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               }
             );
 
@@ -426,9 +562,9 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<EasBuildTooManyPendingBuildsError>(
-              () => {
-                handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildTooManyPendingBuildsError>(
+              async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               }
             );
 
@@ -446,9 +582,9 @@ describe(Build.name, () => {
             const graphQLErrors = [graphQLError];
             const error = new CombinedError({ graphQLErrors });
 
-            const handleBuildRequestErrorThrownError = getError<EasBuildTooManyPendingBuildsError>(
-              () => {
-                handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<EasBuildTooManyPendingBuildsError>(
+              async () => {
+                await handleBuildRequestErrorAsync(error, platform);
               }
             );
 
@@ -471,8 +607,8 @@ describe(Build.name, () => {
           const error = new CombinedError({ graphQLErrors });
           const expectedMessage = `${EXPECTED_GENERIC_MESSAGE}\nRequest ID: ${mockRequestId}\nError message: Error 1`;
 
-          const handleBuildRequestErrorThrownError = getError<Error>(() => {
-            handleBuildRequestError(error, platform);
+          const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+            await handleBuildRequestErrorAsync(error, platform);
           });
 
           assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -494,8 +630,8 @@ describe(Build.name, () => {
             `Request ID: ${mockRequestId}\n` +
             'Error message: Error 3';
 
-          const handleBuildRequestErrorThrownError = getError<Error>(() => {
-            handleBuildRequestError(error, platform);
+          const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+            await handleBuildRequestErrorAsync(error, platform);
           });
 
           assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -509,8 +645,8 @@ describe(Build.name, () => {
             const error = new CombinedError({ graphQLErrors });
             const expectedMessage = `${EXPECTED_GENERIC_MESSAGE}\nError message: Error 1`;
 
-            const handleBuildRequestErrorThrownError = getError<Error>(() => {
-              handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             });
 
             assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -537,8 +673,8 @@ describe(Build.name, () => {
               'Response status: 400 Bad Request\n' +
               `Request ID: ${mockRequestId}`;
 
-            const handleBuildRequestErrorThrownError = getError<Error>(() => {
-              handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             });
 
             assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -561,7 +697,7 @@ describe(Build.name, () => {
             });
 
             try {
-              handleBuildRequestError(error, platform);
+              await handleBuildRequestErrorAsync(error, platform);
             } catch {}
 
             expect(logDebugSpy).toBeCalledWith(expect.stringContaining('"graphQLErrors": []'));
@@ -597,8 +733,8 @@ describe(Build.name, () => {
               'Response status: 400 Bad Request\n' +
               `Request ID: ${mockRequestId}`;
 
-            const handleBuildRequestErrorThrownError = getError<Error>(() => {
-              handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             });
 
             assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -625,8 +761,8 @@ describe(Build.name, () => {
               'Error message: Error 1\n' +
               'Response status: 400 Bad Request';
 
-            const handleBuildRequestErrorThrownError = getError<Error>(() => {
-              handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             });
 
             assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -638,8 +774,8 @@ describe(Build.name, () => {
             const error = { graphQLErrors: [], message: 'Something went wrong' };
             const expectedMessage = `${EXPECTED_GENERIC_MESSAGE}\nError message: Something went wrong`;
 
-            const handleBuildRequestErrorThrownError = getError<Error>(() => {
-              handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             });
 
             assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -654,8 +790,8 @@ describe(Build.name, () => {
           const error = new CombinedError({ graphQLErrors });
           const expectedMessage = `${EXPECTED_GENERIC_MESSAGE}\nRequest ID: ${mockRequestId}\nError message: Error 1`;
 
-          const handleBuildRequestErrorThrownError = getError<Error>(() => {
-            handleBuildRequestError(error, platform);
+          const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+            await handleBuildRequestErrorAsync(error, platform);
           });
 
           assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -677,8 +813,8 @@ describe(Build.name, () => {
             `Request ID: ${mockRequestId}\n` +
             'Error message: Error 3';
 
-          const handleBuildRequestErrorThrownError = getError<Error>(() => {
-            handleBuildRequestError(error, platform);
+          const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+            await handleBuildRequestErrorAsync(error, platform);
           });
 
           assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -692,8 +828,8 @@ describe(Build.name, () => {
             const error = new CombinedError({ graphQLErrors });
             const expectedMessage = `${EXPECTED_GENERIC_MESSAGE}\nError message: Error 1`;
 
-            const handleBuildRequestErrorThrownError = getError<Error>(() => {
-              handleBuildRequestError(error, platform);
+            const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+              await handleBuildRequestErrorAsync(error, platform);
             });
 
             assertReThrownError(handleBuildRequestErrorThrownError, Error, expectedMessage);
@@ -708,8 +844,8 @@ describe(Build.name, () => {
           const platform = Platform.ANDROID;
           const error = new Error('Non-graphQL-related error');
 
-          const handleBuildRequestErrorThrownError = getError<Error>(() => {
-            handleBuildRequestError(error, platform);
+          const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+            await handleBuildRequestErrorAsync(error, platform);
           });
 
           expect(handleBuildRequestErrorThrownError).toStrictEqual(error);
@@ -720,8 +856,8 @@ describe(Build.name, () => {
           const platform = Platform.IOS;
           const error = new Error('Non-graphQL-related error');
 
-          const handleBuildRequestErrorThrownError = getError<Error>(() => {
-            handleBuildRequestError(error, platform);
+          const handleBuildRequestErrorThrownError = await getErrorAsync<Error>(async () => {
+            await handleBuildRequestErrorAsync(error, platform);
           });
 
           expect(handleBuildRequestErrorThrownError).toStrictEqual(error);

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

@@ -28,6 +28,11 @@ import {
   RequestValidationError,
   TurtleDeprecatedJobFormatError,
 } from './errors';
+import {
+  FreeTierLimitAgentGuidanceExperiment,
+  getFreeTierLimitAgentGuidanceExperiment,
+  maybeAppendFreeTierLimitAgentGuidanceAsync,
+} from './freeTierLimitGuidance';
 import { transformMetadata } from './graphql';
 import { LocalBuildMode, runLocalBuildAsync } from './local';
 import {
@@ -219,7 +224,12 @@ export async function prepareBuildRequestForPlatformAsync<
         });
         return await sendBuildRequestAsync(builder, job, graphqlMetadata, buildParams);
       } catch (error: any) {
-        handleBuildRequestError(error, job.platform, ctx.accountName);
+        return await handleBuildRequestErrorAsync(
+          error,
+          job.platform,
+          ctx.accountName,
+          getFreeTierLimitAgentGuidanceExperiment(ctx)
+        );
       }
     } else {
       throw new Error('Unknown localBuildMode.');
@@ -240,11 +250,12 @@ const SERVER_SIDE_DEFINED_ERRORS: Record<string, typeof EasCommandError> = {
   VALIDATION_ERROR: RequestValidationError,
 };
 
-export function handleBuildRequestError(
+export async function handleBuildRequestErrorAsync(
   error: any,
   platform: Platform,
-  accountName?: string
-): never {
+  accountName?: string,
+  freeTierLimitAgentGuidanceExperiment?: FreeTierLimitAgentGuidanceExperiment
+): Promise<never> {
   logBuildRequestErrorDebugInfo(error);
 
   const graphQLErrors: GraphQLError[] = Array.isArray(error?.graphQLErrors)
@@ -261,7 +272,11 @@ export function handleBuildRequestError(
       graphQLErrorCode === 'EAS_BUILD_FREE_TIER_IOS_LIMIT_EXCEEDED';
     throw new ErrorClass(
       isFreeTierLimitError
-        ? `${message}\nRun ${formatStarterSubscribeCommand(accountName)} to upgrade to the Starter plan.`
+        ? await maybeAppendFreeTierLimitAgentGuidanceAsync(
+            `${message}\nRun ${formatStarterSubscribeCommand(accountName)} to upgrade to the Starter plan.`,
+            platform,
+            freeTierLimitAgentGuidanceExperiment
+          )
         : message
     );
   } else if (graphQLErrorCode === 'EAS_BUILD_DOWN_FOR_MAINTENANCE') {

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

@@ -8,6 +8,7 @@ import { LocalBuildOptions } from './local';
 import { Analytics, AnalyticsEventProperties } from '../analytics/AnalyticsManager';
 import { ExpoGraphqlClient } from '../commandUtils/context/contextUtils/createGraphqlClient';
 import { CredentialsContext } from '../credentials/context';
+import { LazyExperimentationClient } from '../experimentation/LazyExperimentationClient';
 import { Target } from '../credentials/ios/types';
 import { BuildResourceClass } from '../graphql/generated';
 import { GradleBuildContext } from '../project/android/gradle';
@@ -66,4 +67,5 @@ export interface BuildContext<T extends Platform> {
   isVerboseLoggingEnabled: boolean;
   whatToTest?: string;
   env: Env;
+  experimentation?: LazyExperimentationClient;
 }

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

@@ -16,6 +16,7 @@ import { Analytics, AnalyticsEventProperties, BuildEvent } from '../analytics/An
 import { DynamicConfigContextFn } from '../commandUtils/context/DynamicProjectConfigContextField';
 import { ExpoGraphqlClient } from '../commandUtils/context/contextUtils/createGraphqlClient';
 import { CredentialsContext } from '../credentials/context';
+import { LazyExperimentationClient } from '../experimentation/LazyExperimentationClient';
 import { CustomBuildConfigMetadata } from '../project/customBuildConfig';
 import { getOwnerAccountForProjectIdAsync } from '../project/projectUtils';
 import { resolveWorkflowAsync } from '../project/workflow';
@@ -46,6 +47,7 @@ export async function createBuildContextAsync<T extends Platform>({
   isVerboseLoggingEnabled,
   whatToTest,
   env,
+  experimentation,
 }: {
   buildProfileName: string;
   buildProfile: BuildProfile<T>;
@@ -70,6 +72,7 @@ export async function createBuildContextAsync<T extends Platform>({
   isVerboseLoggingEnabled: boolean;
   whatToTest?: string;
   env: Env;
+  experimentation?: LazyExperimentationClient;
 }): Promise<BuildContext<T>> {
   const { exp, projectId } = await getDynamicPrivateProjectConfigAsync({
     env,
@@ -159,6 +162,7 @@ export async function createBuildContextAsync<T extends Platform>({
     isVerboseLoggingEnabled,
     env,
     whatToTest,
+    experimentation,
   };
   if (platform === Platform.ANDROID) {
     const common = commonContext as CommonContext<Platform.ANDROID>;

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

@@ -0,0 +1,60 @@
+import { Platform } from '@expo/eas-build-job';
+
+import { getAgentTelemetryContext } from '../analytics/agent';
+import { LazyExperimentationClient } from '../experimentation/LazyExperimentationClient';
+import { requestedPlatformDisplayNames } from '../platform';
+
+export const FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE =
+  'cli-build-free-tier-limit-agent-guidance';
+
+export type FreeTierLimitAgentGuidanceVariant = 'control' | 'treatment';
+
+export type FreeTierLimitAgentGuidanceExperiment = {
+  experimentation: LazyExperimentationClient;
+  accountId: string;
+};
+
+export function getFreeTierLimitAgentGuidanceExperiment(ctx: {
+  experimentation?: LazyExperimentationClient;
+  accountId: string;
+}): FreeTierLimitAgentGuidanceExperiment | undefined {
+  return ctx.experimentation
+    ? { experimentation: ctx.experimentation, accountId: ctx.accountId }
+    : undefined;
+}
+
+/**
+ * Resolves the account's variant. Only runs driven by a coding agent are eligible. Other runs get
+ * control before the client loads, so they make no config request and log no exposure.
+ */
+export async function resolveFreeTierLimitAgentGuidanceVariantAsync({
+  experimentation,
+  accountId,
+}: FreeTierLimitAgentGuidanceExperiment): Promise<FreeTierLimitAgentGuidanceVariant> {
+  if (!getAgentTelemetryContext()) {
+    return 'control';
+  }
+  const client = await experimentation.getClientAsync();
+  return client
+    .getAccountNamespace(FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE, { accountId })
+    .getParam<FreeTierLimitAgentGuidanceVariant>('variant', 'control');
+}
+
+export function formatFreeTierLimitAgentGuidance(platform: Platform): string {
+  const platformName = requestedPlatformDisplayNames[platform];
+  return `Fix: Human required: ${platformName} builds for this account are blocked until the Free plan resets. Upgrading costs money, so an account owner or admin decides.`;
+}
+
+export async function maybeAppendFreeTierLimitAgentGuidanceAsync(
+  message: string,
+  platform: Platform,
+  experiment: FreeTierLimitAgentGuidanceExperiment | undefined
+): Promise<string> {
+  if (
+    !experiment ||
+    (await resolveFreeTierLimitAgentGuidanceVariantAsync(experiment)) !== 'treatment'
+  ) {
+    return message;
+  }
+  return `${message}\n${formatFreeTierLimitAgentGuidance(platform)}`;
+}

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

@@ -30,6 +30,7 @@ import { Analytics } from '../analytics/AnalyticsManager';
 import { createAndLinkChannelAsync, doesChannelExistAsync } from '../channel/queries';
 import { DynamicConfigContextFn } from '../commandUtils/context/DynamicProjectConfigContextField';
 import { ExpoGraphqlClient } from '../commandUtils/context/contextUtils/createGraphqlClient';
+import { LazyExperimentationClient } from '../experimentation/LazyExperimentationClient';
 import {
   AppPlatform,
   BuildFragment,
@@ -118,6 +119,7 @@ export async function runBuildAndSubmitAsync({
   getDynamicPrivateProjectConfigAsync,
   downloadSimBuildAutoConfirm,
   envOverride,
+  experimentation,
 }: {
   graphqlClient: ExpoGraphqlClient;
   analytics: Analytics;
@@ -128,6 +130,8 @@ export async function runBuildAndSubmitAsync({
   getDynamicPrivateProjectConfigAsync: DynamicConfigContextFn;
   downloadSimBuildAutoConfirm?: boolean;
   envOverride?: Env;
+  /** Enables the Free plan limit guidance experiment for builds driven by a coding agent. */
+  experimentation?: LazyExperimentationClient;
 }): Promise<{
   buildIds: string[];
   buildProfiles?: ProfileData<'build'>[];
@@ -240,6 +244,7 @@ export async function runBuildAndSubmitAsync({
       customBuildConfigMetadata: customBuildConfigMetadataByPlatform[platform],
       env,
       easJsonAccessor,
+      experimentation,
     });
     if (maybeBuild) {
       startedBuilds.push({ build: maybeBuild, buildProfile });
@@ -378,6 +383,7 @@ async function prepareAndStartBuildAsync({
   customBuildConfigMetadata,
   env,
   easJsonAccessor,
+  experimentation,
 }: {
   projectDir: string;
   flags: BuildFlags;
@@ -392,6 +398,7 @@ async function prepareAndStartBuildAsync({
   customBuildConfigMetadata?: CustomBuildConfigMetadata;
   easJsonAccessor: EasJsonAccessor;
   env: Env;
+  experimentation?: LazyExperimentationClient;
 }): Promise<{ build: BuildFragment | undefined; buildCtx: BuildContext<Platform> }> {
   const buildCtx = await createBuildContextAsync({
     buildProfileName: buildProfile.profileName,
@@ -417,6 +424,7 @@ async function prepareAndStartBuildAsync({
     isVerboseLoggingEnabled: flags.isVerboseLoggingEnabled ?? false,
     whatToTest: flags.whatToTest,
     env,
+    experimentation,
   });
 
   if (!lockfileChecked && !flags.localBuildOptions.localBuildMode) {

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

@@ -7,6 +7,7 @@ import nullthrows from 'nullthrows';
 import AnalyticsContextField from './context/AnalyticsContextField';
 import ContextField from './context/ContextField';
 import DynamicLoggedInContextField from './context/DynamicLoggedInContextField';
+import ExperimentationContextField from './context/ExperimentationContextField';
 import {
   DynamicPrivateProjectConfigContextField,
   DynamicPublicProjectConfigContextField,
@@ -148,6 +149,14 @@ export default abstract class EasCommand extends Command {
     ProjectId: {
       projectId: new ProjectIdContextField(),
     },
+    /**
+     * Experimentation client for user, account, and device experiments.
+     * Declare a login field first so user experiments see the actor.
+     * Account experiments take the account ID from the command.
+     */
+    Experimentation: {
+      experimentation: new ExperimentationContextField(),
+    },
   };
 
   /**

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

@@ -48,6 +48,7 @@ const analytics: AnalyticsWithOrchestration = {
   logEvent: jest.fn((): void => {}),
   setActor: jest.fn((): void => {}),
   flushAsync: jest.fn(async (): Promise<void> => {}),
+  getDeviceId: jest.fn((): string | null => null),
 };
 
 beforeEach(() => {

packages/eas-cli/src/commandUtils/__tests__/usageUtils.test.ts

@@ -22,6 +22,15 @@ function createMockFullUsageData(
     bandwidthLimit: number;
     buildOverageCost: number;
     updateOverageCost: number;
+    simulator: {
+      planValue: number;
+      limit: number;
+      iosMinutes: number;
+      androidMinutes: number;
+      overageMinutes: number;
+      overageCost: number;
+      jobTypeBreakdown?: { workflows: number; simulator: number; other: number };
+    };
   }> = {}
 ): AccountFullUsageData {
   const {
@@ -35,6 +44,7 @@ function createMockFullUsageData(
     bandwidthLimit = 10,
     buildOverageCost = 0,
     updateOverageCost = 0,
+    simulator,
   } = overrides;
 
   const now = new Date();
@@ -167,6 +177,72 @@ function createMockFullUsageData(
             : [],
         totalCost: updateOverageCost,
       },
+      EAS_SIMULATOR: {
+        unavailableServiceUsageMetrics: [],
+        __typename: 'UsageMetricTotal',
+        id: 'simulator-metric-id',
+        billingPeriod: {
+          __typename: 'BillingPeriod',
+          id: 'billing-period-id',
+          start: startOfMonth.toISOString(),
+          end: endOfMonth.toISOString(),
+          anchor: startOfMonth.toISOString(),
+        },
+        planMetrics: simulator
+          ? [
+              {
+                __typename: 'EstimatedUsage',
+                id: 'simulator-plan-metric-id',
+                service: EasService.Simulator,
+                serviceMetric: EasServiceMetric.SimulatorUsage,
+                metricType: UsageMetricType.Minute,
+                value: simulator.planValue,
+                limit: simulator.limit,
+                jobTypeBreakdown: simulator.jobTypeBreakdown
+                  ? { __typename: 'EstimatedUsageJobTypeBreakdown', ...simulator.jobTypeBreakdown }
+                  : null,
+              },
+            ]
+          : [],
+        overageMetrics:
+          simulator && simulator.overageMinutes > 0
+            ? [
+                {
+                  __typename: 'EstimatedOverageAndCost',
+                  id: 'simulator-overage-id',
+                  service: EasService.Simulator,
+                  serviceMetric: EasServiceMetric.SimulatorUsage,
+                  metricType: UsageMetricType.Minute,
+                  value: simulator.overageMinutes,
+                  limit: simulator.limit,
+                  totalCost: simulator.overageCost,
+                },
+              ]
+            : [],
+        totalCost: simulator?.overageCost ?? 0,
+      },
+      IOS_SIMULATOR_MINUTES: simulator
+        ? [
+            {
+              __typename: 'AccountUsageMetric',
+              id: 'ios-simulator-minutes-id',
+              serviceMetric: EasServiceMetric.SimulatorUsage,
+              metricType: UsageMetricType.Minute,
+              value: simulator.iosMinutes,
+            },
+          ]
+        : [],
+      ANDROID_SIMULATOR_MINUTES: simulator
+        ? [
+            {
+              __typename: 'AccountUsageMetric',
+              id: 'android-simulator-minutes-id',
+              serviceMetric: EasServiceMetric.SimulatorUsage,
+              metricType: UsageMetricType.Minute,
+              value: simulator.androidMinutes,
+            },
+          ]
+        : [],
     },
   };
 }
@@ -240,6 +316,14 @@ describe('calculateBillingPeriodDays', () => {
 });
 
 describe('extractUsageData', () => {
+  it('does not estimate a bill when Simulator usage is unavailable', () => {
+    const data = createMockFullUsageData();
+    data.usageMetrics.EAS_SIMULATOR.unavailableServiceUsageMetrics = [
+      { service: EasService.Simulator },
+    ];
+    expect(() => extractUsageData(data)).toThrow('Simulator usage is temporarily unavailable');
+  });
+
   it('correctly extracts usage data from API response', () => {
     const mockData = createMockFullUsageData({
       buildValue: 25,
@@ -271,6 +355,71 @@ describe('extractUsageData', () => {
     expect(result.totalOverageCostCents).toBe(2000);
   });
 
+  it('omits simulator usage when the account has no simulator metric', () => {
+    const result = extractUsageData(createMockFullUsageData());
+
+    expect(result.simulator).toBeUndefined();
+  });
+
+  it('extracts simulator minutes and adds the overage to the total cost', () => {
+    const mockData = createMockFullUsageData({
+      buildValue: 60,
+      buildLimit: 50,
+      buildOverageCost: 2000,
+      simulator: {
+        planValue: 60,
+        limit: 60,
+        iosMinutes: 50.5,
+        androidMinutes: 14,
+        overageMinutes: 4.5,
+        overageCost: 68,
+      },
+    });
+
+    const result = extractUsageData(mockData);
+
+    expect(result.simulator).toEqual({
+      minutes: {
+        name: 'Simulator minutes',
+        planValue: 60,
+        limit: 60,
+        percentUsed: 100,
+        overageValue: 4.5,
+        overageCost: 68,
+        unit: 'minutes',
+        maxDecimals: 1,
+      },
+      iosMinutes: 50.5,
+      androidMinutes: 14,
+      jobTypeBreakdown: undefined,
+      overageCostCents: 68,
+    });
+    expect(result.totalOverageCostCents).toBe(2068);
+    expect(result.estimatedBillCents).toBe(1900 + 2068);
+  });
+
+  it('labels the Free plan minute pool and keeps the job type breakdown', () => {
+    const mockData = createMockFullUsageData({
+      subscriptionName: 'Free',
+      simulator: {
+        planValue: 45,
+        limit: 60,
+        iosMinutes: 5,
+        androidMinutes: 0,
+        overageMinutes: 0,
+        overageCost: 0,
+        jobTypeBreakdown: { workflows: 40, simulator: 5, other: 0 },
+      },
+    });
+
+    const result = extractUsageData(mockData);
+
+    expect(result.simulator?.minutes.name).toBe('CI/CD and Simulator minutes');
+    expect(result.simulator?.minutes.percentUsed).toBe(75);
+    expect(result.simulator?.jobTypeBreakdown).toEqual({ workflows: 40, simulator: 5, other: 0 });
+    expect(result.totalOverageCostCents).toBe(0);
+  });
+
   it('handles Free plan', () => {
     const mockData = createMockFullUsageData({
       subscriptionName: 'Free',

packages/eas-cli/src/commandUtils/context/ExperimentationContextField.ts

@@ -0,0 +1,111 @@
+import ContextField, { ContextOptions } from './ContextField';
+import { createGraphqlClient } from './contextUtils/createGraphqlClient';
+import { AnalyticsWithOrchestration } from '../../analytics/AnalyticsManager';
+import { ExperimentOverrides } from '../../experimentation/ExperimentOverrides';
+import {
+  ExperimentationClient,
+  createLoggerConfig,
+} from '../../experimentation/ExperimentationClient';
+import { LazyExperimentationClient } from '../../experimentation/LazyExperimentationClient';
+import { ExperimentationConfigQuery } from '../../graphql/queries/ExperimentationConfigQuery';
+import Log from '../../log';
+
+/** Caps how long the config fetch and the actor lookup can delay a command. */
+const REQUEST_TIMEOUT_MS = 3000;
+
+const CI_ENVIRONMENT_FLAGS = ['EAS_BUILD', 'CI'];
+
+function isRunningInCi(): boolean {
+  return CI_ENVIRONMENT_FLAGS.some(flag => !!process.env[flag]);
+}
+
+/**
+ * Never prompts, throws, writes files, or reads the app config. A failed config fetch disables
+ * all scopes. CI runs skip the fetch and get defaults.
+ * The config fetch runs on the first `getClientAsync` call, so commands that never read a variant
+ * make no request.
+ */
+export default class ExperimentationContextField extends ContextField<LazyExperimentationClient> {
+  // One handle per command run, so repeated getContextAsync calls cannot log duplicate exposures.
+  private readonly clientByAnalytics = new WeakMap<
+    AnalyticsWithOrchestration,
+    LazyExperimentationClient
+  >();
+
+  async getValueAsync(options: ContextOptions): Promise<LazyExperimentationClient> {
+    let client = this.clientByAnalytics.get(options.analytics);
+    if (!client) {
+      client = new LazyExperimentationClient(() => this.buildClientAsync(options));
+      this.clientByAnalytics.set(options.analytics, client);
+    }
+    return client;
+  }
+
+  private async buildClientAsync({
+    sessionManager,
+    analytics,
+  }: ContextOptions): Promise<ExperimentationClient> {
+    const overrides = ExperimentOverrides.fromEnv();
+
+    if (isRunningInCi()) {
+      Log.debug('[experimentation] Running in CI. Experiments return defaults.');
+      return ExperimentationClient.createDisabled(overrides);
+    }
+
+    const deviceId = analytics.getDeviceId();
+    if (deviceId === null) {
+      Log.debug('[experimentation] Analytics is disabled. Experiments return defaults.');
+      return ExperimentationClient.createDisabled(overrides);
+    }
+
+    try {
+      const graphqlClient = createGraphqlClient(
+        {
+          accessToken: sessionManager.getAccessToken(),
+          sessionSecret: sessionManager.getSessionSecret(),
+        },
+        { requestTimeoutMs: REQUEST_TIMEOUT_MS }
+      );
+
+      // The session manager skips the request once an actor is cached. Without a cached actor
+      // (for example, a stale session) it makes its own request, so it needs the same cap.
+      const [actorResult, configsResult] = await Promise.allSettled([
+        sessionManager.getUserAsync({ requestTimeoutMs: REQUEST_TIMEOUT_MS }),
+        ExperimentationConfigQuery.getConfigsAsync(graphqlClient),
+      ]);
+
+      if (configsResult.status === 'rejected') {
+        Log.debug(
+          '[experimentation] Failed to fetch the experiment config. Experiments return defaults.',
+          errorMessage(configsResult.reason)
+        );
+        return ExperimentationClient.createDisabled(overrides);
+      }
+
+      const configs = configsResult.value;
+      return new ExperimentationClient(
+        {
+          user: configs.userConfig,
+          account: configs.accountConfig,
+          device: configs.deviceConfig,
+        },
+        {
+          user: actorResult.status === 'fulfilled' ? (actorResult.value?.id ?? null) : null,
+          device: deviceId,
+        },
+        overrides,
+        createLoggerConfig(analytics)
+      );
+    } catch (error) {
+      Log.debug(
+        '[experimentation] Failed to initialize experiments. Experiments return defaults.',
+        errorMessage(error)
+      );
+      return ExperimentationClient.createDisabled(overrides);
+    }
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

packages/eas-cli/src/commandUtils/context/__tests__/ExperimentationContextField-test.ts

@@ -0,0 +1,289 @@
+import { anything, deepEqual, instance, mock, verify, when } from 'ts-mockito';
+
+import { AnalyticsWithOrchestration } from '../../../analytics/AnalyticsManager';
+import { TEST_DEFINITION } from '../../../experimentation/__tests__/fixtures';
+import { ExperimentationConfigQuery } from '../../../graphql/queries/ExperimentationConfigQuery';
+import Log from '../../../log';
+import SessionManager from '../../../user/SessionManager';
+import { Actor } from '../../../user/User';
+import { ContextOptions } from '../ContextField';
+import { ExperimentationClient } from '../../../experimentation/ExperimentationClient';
+import ExperimentationContextField from '../ExperimentationContextField';
+import { createGraphqlClient } from '../contextUtils/createGraphqlClient';
+
+jest.mock('../../../env', () => ({
+  __esModule: true,
+  default: { experimentOverride: undefined as string | undefined },
+}));
+jest.mock('../../../graphql/queries/ExperimentationConfigQuery');
+jest.mock('../../../log');
+jest.mock('../contextUtils/createGraphqlClient');
+
+const mockEnv = jest.requireMock('../../../env').default as { experimentOverride?: string };
+const getConfigsAsyncMock = jest.mocked(ExperimentationConfigQuery.getConfigsAsync);
+const fakeGraphqlClient = { fake: true } as any;
+
+const actor = { __typename: 'User', id: 'user-1' } as unknown as Actor;
+const emptyDefinition = { experiments: [], namespaces: [] };
+const allConfigs = {
+  userConfig: TEST_DEFINITION,
+  accountConfig: TEST_DEFINITION,
+  deviceConfig: TEST_DEFINITION,
+};
+
+function createAnalytics(deviceId: string | null = 'device-1'): AnalyticsWithOrchestration & {
+  logEvent: jest.Mock;
+} {
+  return {
+    logEvent: jest.fn(),
+    setActor: jest.fn(),
+    flushAsync: jest.fn(),
+    getDeviceId: jest.fn(() => deviceId),
+  };
+}
+
+function createSessionManager({ loggedOut = false }: { loggedOut?: boolean } = {}): {
+  sessionManager: SessionManager;
+  mocked: SessionManager;
+} {
+  const mocked = mock<SessionManager>();
+  when(mocked.getAccessToken()).thenReturn(null);
+  when(mocked.getSessionSecret()).thenReturn(loggedOut ? null : 'secret');
+  when(mocked.getUserAsync(anything())).thenResolve(loggedOut ? undefined : actor);
+  return { sessionManager: instance(mocked), mocked };
+}
+
+function options(overrides: Partial<ContextOptions> = {}): ContextOptions {
+  return {
+    nonInteractive: false,
+    sessionManager: createSessionManager().sessionManager,
+    analytics: createAnalytics(),
+    ...overrides,
+  } as ContextOptions;
+}
+
+/** Resolves the context and then loads the client, as a command does on its first variant read. */
+async function loadClientAsync(
+  contextOptions: ContextOptions = options()
+): Promise<ExperimentationClient> {
+  const lazyClient = await new ExperimentationContextField().getValueAsync(contextOptions);
+  return await lazyClient.getClientAsync();
+}
+
+async function flushPromisesAsync(): Promise<void> {
+  await new Promise(resolve => setImmediate(resolve));
+}
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+const ORIGINAL_ENV = process.env;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = { ...ORIGINAL_ENV };
+  delete process.env.CI;
+  delete process.env.EAS_BUILD;
+  mockEnv.experimentOverride = undefined;
+  jest.mocked(createGraphqlClient).mockReturnValue(fakeGraphqlClient);
+  getConfigsAsyncMock.mockResolvedValue(allConfigs);
+});
+
+describe(ExperimentationContextField, () => {
+  it('returns a disabled client and fetches nothing when analytics is disabled', async () => {
+    const { sessionManager, mocked } = createSessionManager();
+    const client = await loadClientAsync(
+      options({ analytics: createAnalytics(null), sessionManager })
+    );
+
+    expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+    expect(client.getDeviceNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+    expect(getConfigsAsyncMock).not.toHaveBeenCalled();
+    expect(createGraphqlClient).not.toHaveBeenCalled();
+    verify(mocked.getUserAsync(anything())).never();
+  });
+
+  it.each(['CI', 'EAS_BUILD'])(
+    'returns a disabled client and fetches nothing when %s is set',
+    async flag => {
+      process.env[flag] = '1';
+      const { sessionManager, mocked } = createSessionManager();
+      const client = await loadClientAsync(options({ sessionManager }));
+
+      expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+      expect(client.getDeviceNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+      expect(getConfigsAsyncMock).not.toHaveBeenCalled();
+      expect(createGraphqlClient).not.toHaveBeenCalled();
+      verify(mocked.getUserAsync(anything())).never();
+    }
+  );
+
+  it('still honors EAS_EXPERIMENT_OVERRIDE in CI', async () => {
+    process.env.CI = 'true';
+    mockEnv.experimentOverride = 'cli-full:variant=treatment';
+    const client = await loadClientAsync(options());
+    expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('treatment');
+    expect(getConfigsAsyncMock).not.toHaveBeenCalled();
+  });
+
+  it('still honors EAS_EXPERIMENT_OVERRIDE when analytics is disabled', async () => {
+    mockEnv.experimentOverride = 'cli-full:variant=treatment';
+    const client = await loadClientAsync(options({ analytics: createAnalytics(null) }));
+    expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('treatment');
+  });
+
+  it('buckets each scope on its own unit and logs exposures through analytics', async () => {
+    const analytics = createAnalytics('device-1');
+    const client = await loadClientAsync(options({ analytics }));
+
+    client.getUserNamespace('cli-full').getParam('variant', 'control');
+    client
+      .getAccountNamespace('cli-full', { accountId: 'account-1' })
+      .getParam('variant', 'control');
+    client.getDeviceNamespace('cli-full').getParam('variant', 'control');
+
+    const units = analytics.logEvent.mock.calls.map(([, properties]) => properties.unit);
+    expect(units).toEqual(['user-1', 'account-1', 'device-1']);
+    expect(createGraphqlClient).toHaveBeenCalledWith(
+      { accessToken: null, sessionSecret: 'secret' },
+      { requestTimeoutMs: 3000 }
+    );
+  });
+
+  it('gives logged-out users defaults for user experiments but still runs device experiments', async () => {
+    const analytics = createAnalytics('device-1');
+    const { sessionManager } = createSessionManager({ loggedOut: true });
+    const client = await loadClientAsync(options({ analytics, sessionManager }));
+
+    expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+    expect(['control', 'treatment']).toContain(
+      client.getDeviceNamespace('cli-full').getParam('variant', 'x')
+    );
+    expect(analytics.logEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it('fails open to defaults when the config fetch rejects', async () => {
+    getConfigsAsyncMock.mockRejectedValue(new Error('offline'));
+    const analytics = createAnalytics();
+    const client = await loadClientAsync(options({ analytics }));
+
+    expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+    expect(client.getDeviceNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+    expect(Log.debug).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to fetch'),
+      expect.anything()
+    );
+    expect(Log.error).not.toHaveBeenCalled();
+    expect(Log.warn).not.toHaveBeenCalled();
+  });
+
+  it('returns defaults and logs nothing for empty configs, as the server sends for robots', async () => {
+    getConfigsAsyncMock.mockResolvedValue({
+      userConfig: emptyDefinition,
+      accountConfig: emptyDefinition,
+      deviceConfig: emptyDefinition,
+    });
+    const analytics = createAnalytics();
+    const client = await loadClientAsync(options({ analytics }));
+
+    expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+  });
+
+  it('fails open to defaults when the server config is invalid', async () => {
+    getConfigsAsyncMock.mockResolvedValue({
+      ...allConfigs,
+      userConfig: {
+        experiments: TEST_DEFINITION.experiments,
+        namespaces: [
+          {
+            name: 'too-many',
+            numSegments: 10,
+            segmentExperimentSetupDefinitions: [
+              { method: 'ADD', name: 'all', experimentName: 'cli-test', numSegments: 20 },
+            ],
+          },
+        ],
+      },
+    });
+    const client = await loadClientAsync(options());
+
+    expect(client.getDeviceNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+    expect(Log.debug).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to initialize'),
+      expect.anything()
+    );
+  });
+
+  it('logs account exposures on the account ID the command passes', async () => {
+    const analytics = createAnalytics();
+    const client = await loadClientAsync(options({ analytics }));
+    client
+      .getAccountNamespace('cli-full', { accountId: 'picked-account' })
+      .getParam('variant', 'x');
+    expect(analytics.logEvent).toHaveBeenCalledWith(
+      'Experiment Viewed',
+      expect.objectContaining({ unit: 'picked-account' })
+    );
+  });
+
+  it('caps the actor lookup with the same timeout as the config fetch', async () => {
+    const { sessionManager, mocked } = createSessionManager();
+    await loadClientAsync(options({ sessionManager }));
+
+    verify(mocked.getUserAsync(deepEqual({ requestTimeoutMs: 3000 }))).once();
+    expect(createGraphqlClient).toHaveBeenCalledWith(expect.anything(), { requestTimeoutMs: 3000 });
+  });
+
+  it('runs the actor lookup and the config fetch in parallel', async () => {
+    let resolveConfigs!: (value: typeof allConfigs) => void;
+    let resolveActor!: (value: Actor) => void;
+    getConfigsAsyncMock.mockReturnValue(new Promise(resolve => (resolveConfigs = resolve)));
+    const mocked = mock<SessionManager>();
+    when(mocked.getAccessToken()).thenReturn(null);
+    when(mocked.getSessionSecret()).thenReturn('secret');
+    when(mocked.getUserAsync(anything())).thenReturn(
+      new Promise(resolve => (resolveActor = resolve))
+    );
+
+    const pending = loadClientAsync(options({ sessionManager: instance(mocked) }));
+    await flushPromisesAsync();
+
+    expect(getConfigsAsyncMock).toHaveBeenCalledTimes(1);
+    verify(mocked.getUserAsync(anything())).once();
+
+    resolveConfigs(allConfigs);
+    resolveActor(actor);
+    await expect(pending).resolves.toBeDefined();
+  });
+
+  it('fetches nothing until a command asks for the client', async () => {
+    const { sessionManager, mocked } = createSessionManager();
+    const lazyClient = await new ExperimentationContextField().getValueAsync(
+      options({ sessionManager })
+    );
+
+    expect(getConfigsAsyncMock).not.toHaveBeenCalled();
+    expect(createGraphqlClient).not.toHaveBeenCalled();
+    verify(mocked.getUserAsync(anything())).never();
+
+    await lazyClient.getClientAsync();
+    expect(getConfigsAsyncMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('caches one client per analytics instance so repeated context calls do not log duplicate exposures', async () => {
+    const field = new ExperimentationContextField();
+    const analytics = createAnalytics();
+    const first = await field.getValueAsync(options({ analytics }));
+    const second = await field.getValueAsync(options({ analytics }));
+    const other = await field.getValueAsync(options({ analytics: createAnalytics() }));
+
+    expect(second).toBe(first);
+    expect(other).not.toBe(first);
+    expect(await second.getClientAsync()).toBe(await first.getClientAsync());
+    expect(await other.getClientAsync()).not.toBe(await first.getClientAsync());
+    expect(getConfigsAsyncMock).toHaveBeenCalledTimes(2);
+  });
+});

packages/eas-cli/src/commandUtils/context/contextUtils/__tests__/createGraphqlClient-test.ts

@@ -0,0 +1,124 @@
+import { createRequest } from '@urql/core';
+import http from 'http';
+import { AddressInfo } from 'net';
+
+import { createGraphqlClient } from '../createGraphqlClient';
+
+jest.mock('../../../../api', () => ({
+  getExpoApiBaseUrl: () => process.env.CREATE_GRAPHQL_CLIENT_TEST_URL,
+}));
+
+// A plain string keeps this document out of GraphQL codegen, which scans gql tags in src/**.
+const TEST_QUERY = 'query CreateGraphqlClientTest { __typename }';
+
+function fetchOptionsOf(client: ReturnType<typeof createGraphqlClient>): RequestInit {
+  const operation = client.createRequestOperation('query', createRequest(TEST_QUERY, {}));
+  const { fetchOptions } = operation.context;
+  return typeof fetchOptions === 'function' ? fetchOptions() : (fetchOptions ?? {});
+}
+
+/** Serves one GraphQL response after `delayMs`. Returns the base URL. */
+async function startSlowServerAsync(server: http.Server, delayMs: number): Promise<string> {
+  server.on('request', (_req, res) => {
+    setTimeout(() => {
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ data: { __typename: 'RootQuery' } }));
+    }, delayMs);
+  });
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address() as AddressInfo;
+  return `http://127.0.0.1:${port}`;
+}
+
+describe(createGraphqlClient, () => {
+  it('sends the access token as a bearer header', () => {
+    const init = fetchOptionsOf(createGraphqlClient({ accessToken: 'token', sessionSecret: null }));
+    expect(init.headers).toEqual({ authorization: 'Bearer token' });
+  });
+
+  it('sends the session secret when there is no access token', () => {
+    const init = fetchOptionsOf(
+      createGraphqlClient({ accessToken: null, sessionSecret: 'secret' })
+    );
+    expect(init.headers).toEqual({ 'expo-session': 'secret' });
+  });
+
+  it('keeps the auth headers when a request timeout is set', () => {
+    const init = fetchOptionsOf(
+      createGraphqlClient({ accessToken: 'token', sessionSecret: null }, { requestTimeoutMs: 50 })
+    );
+    expect(init.headers).toEqual({ authorization: 'Bearer token' });
+  });
+
+  describe('against a slow server', () => {
+    const server = http.createServer();
+    const serverDelayMs = 2000;
+
+    beforeAll(async () => {
+      process.env.CREATE_GRAPHQL_CLIENT_TEST_URL = await startSlowServerAsync(
+        server,
+        serverDelayMs
+      );
+    });
+
+    afterAll(async () => {
+      delete process.env.CREATE_GRAPHQL_CLIENT_TEST_URL;
+      server.closeAllConnections();
+      await new Promise<void>(resolve => {
+        server.close(() => {
+          resolve();
+        });
+      });
+    });
+
+    it('aborts the request when the timeout elapses', async () => {
+      // Only a real request proves the timeout works.
+      const client = createGraphqlClient(
+        { accessToken: 'token', sessionSecret: null },
+        { requestTimeoutMs: 100 }
+      );
+      const start = Date.now();
+      const result = await client.query(TEST_QUERY, {}, { noRetry: true }).toPromise();
+      expect(Date.now() - start).toBeLessThan(serverDelayMs);
+      expect(result.data).toBeUndefined();
+      expect(result.error?.networkError?.name).toBe('TimeoutError');
+      expect(result.error?.networkError?.message).toBe('Request timed out after 100 ms');
+    });
+
+    it('waits for the response when no timeout is set', async () => {
+      const client = createGraphqlClient({ accessToken: 'token', sessionSecret: null });
+      const result = await client.query(TEST_QUERY, {}, { noRetry: true }).toPromise();
+      expect(result.error).toBeUndefined();
+      expect(result.data).toEqual({ __typename: 'RootQuery' });
+    });
+  });
+
+  describe('against a closed port', () => {
+    beforeAll(async () => {
+      // Listen once to reserve a free port, then close so the port refuses connections.
+      const server = http.createServer();
+      process.env.CREATE_GRAPHQL_CLIENT_TEST_URL = await startSlowServerAsync(server, 0);
+      await new Promise<void>(resolve => {
+        server.close(() => {
+          resolve();
+        });
+      });
+    });
+
+    afterAll(() => {
+      delete process.env.CREATE_GRAPHQL_CLIENT_TEST_URL;
+    });
+
+    it('passes through fetch errors that are not timeouts', async () => {
+      const client = createGraphqlClient(
+        { accessToken: 'token', sessionSecret: null },
+        { requestTimeoutMs: 5000 }
+      );
+      const result = await client.query(TEST_QUERY, {}, { noRetry: true }).toPromise();
+      expect(result.data).toBeUndefined();
+      expect(result.error?.networkError).toBeDefined();
+      expect(result.error?.networkError?.name).not.toBe('TimeoutError');
+      expect(result.error?.networkError?.message).toContain('ECONNREFUSED');
+    });
+  });
+});

packages/eas-cli/src/commandUtils/context/contextUtils/createGraphqlClient.ts

@@ -1,6 +1,10 @@
 import { Client, cacheExchange, createClient as createUrqlClient, fetchExchange } from '@urql/core';
 import { retryExchange } from '@urql/exchange-retry';
-import fetch from 'node-fetch';
+import fetch, {
+  RequestInfo as NodeFetchRequestInfo,
+  RequestInit as NodeFetchRequestInit,
+  Response as NodeFetchResponse,
+} from 'node-fetch';
 
 import { getExpoApiBaseUrl } from '../../../api';
 import { httpsProxyAgent } from '../../../fetch';
@@ -8,10 +12,46 @@ import { httpsProxyAgent } from '../../../fetch';
 // Extend the urql Client to allow for future customizations or type additions ahead of upstream type support.
 export interface ExpoGraphqlClient extends Client {}
 
-export function createGraphqlClient(authInfo: {
-  accessToken: string | null;
-  sessionSecret: string | null;
-}): ExpoGraphqlClient {
+export function createGraphqlClient(
+  authInfo: {
+    accessToken: string | null;
+    sessionSecret: string | null;
+  },
+  options: {
+    /** Request timeout. Kept at the client level: a per-operation `fetchOptions` in urql would replace the auth headers. */
+    requestTimeoutMs?: number;
+  } = {}
+): ExpoGraphqlClient {
+  const { requestTimeoutMs } = options;
+  // urql overwrites `fetchOptions.signal`, so the timeout must be added inside fetch.
+  const fetchWithTimeoutAsync = async (
+    url: NodeFetchRequestInfo,
+    init?: NodeFetchRequestInit
+  ): Promise<NodeFetchResponse> => {
+    if (!requestTimeoutMs) {
+      return await fetch(url, init);
+    }
+    const timeoutSignal = AbortSignal.timeout(requestTimeoutMs);
+    try {
+      return await fetch(url, {
+        ...init,
+        signal: AbortSignal.any([
+          ...(init?.signal ? [init.signal as AbortSignal] : []),
+          timeoutSignal,
+        ]),
+      });
+    } catch (error) {
+      if (timeoutSignal.aborted) {
+        const timeoutError = new Error(`Request timed out after ${requestTimeoutMs} ms`, {
+          cause: error,
+        });
+        timeoutError.name = 'TimeoutError';
+        throw timeoutError;
+      }
+      throw error;
+    }
+  };
+
   return createUrqlClient({
     url: getExpoApiBaseUrl() + '/graphql',
     exchanges: [
@@ -29,7 +69,7 @@ export function createGraphqlClient(authInfo: {
       fetchExchange,
     ],
     // @ts-expect-error Type 'typeof fetch' is not assignable to type '(input: RequestInfo, init?: RequestInit | undefined) => Promise<Response>'.
-    fetch,
+    fetch: fetchWithTimeoutAsync,
     fetchOptions: (): RequestInit => {
       const headers: Record<string, string> = {};
       if (authInfo.accessToken) {

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

@@ -1,6 +1,7 @@
 import {
   AppPlatform,
   EasBuildBillingResourceClass,
+  EasService,
   EasServiceMetric,
   UsageMetricType,
 } from '../graphql/generated';
@@ -15,6 +16,21 @@ export interface UsageMetricDisplay {
   overageValue: number;
   overageCost: number;
   unit?: string;
+  maxDecimals?: number;
+}
+
+export interface SimulatorJobTypeBreakdown {
+  workflows: number;
+  simulator: number;
+  other: number;
+}
+
+export interface SimulatorUsageDisplay {
+  minutes: UsageMetricDisplay;
+  iosMinutes: number;
+  androidMinutes: number;
+  jobTypeBreakdown?: SimulatorJobTypeBreakdown;
+  overageCostCents: number;
 }
 
 export interface BuildOverageByWorkerSize {
@@ -50,6 +66,7 @@ export interface UsageDisplayData {
     bandwidth: UsageMetricDisplay;
     overageCostCents: number;
   };
+  simulator?: SimulatorUsageDisplay;
   totalOverageCostCents: number;
   estimatedBillCents: number;
   recurringCents: number | null;
@@ -108,6 +125,9 @@ export function extractUsageData(data: AccountFullUsageData): UsageDisplayData {
     LARGE_ANDROID_BUILDS,
     MEDIUM_IOS_BUILDS,
     LARGE_IOS_BUILDS,
+    EAS_SIMULATOR,
+    IOS_SIMULATOR_MINUTES,
+    ANDROID_SIMULATOR_MINUTES,
   } = usageMetrics;
 
   // Find build metrics
@@ -201,9 +221,17 @@ export function extractUsageData(data: AccountFullUsageData): UsageDisplayData {
   const bandwidthOverageValue = bandwidthOverage?.value ?? 0;
   const bandwidthLimit = bandwidthMetric?.limit ?? 0;
 
+  const simulator = extractSimulatorUsage(
+    EAS_SIMULATOR,
+    IOS_SIMULATOR_MINUTES?.[0]?.value ?? 0,
+    ANDROID_SIMULATOR_MINUTES?.[0]?.value ?? 0
+  );
+
   const buildOverageCostCents = EAS_BUILD.totalCost;
   const updateOverageCostCents = EAS_UPDATE.totalCost;
-  const totalOverageCostCents = buildOverageCostCents + updateOverageCostCents;
+  const simulatorOverageCostCents = simulator?.overageCostCents ?? 0;
+  const totalOverageCostCents =
+    buildOverageCostCents + updateOverageCostCents + simulatorOverageCostCents;
 
   // Calculate total overage count for display
   const totalOverageBuilds = overagesByWorkerSize.reduce((sum, o) => sum + o.count, 0);
@@ -272,12 +300,64 @@ export function extractUsageData(data: AccountFullUsageData): UsageDisplayData {
       },
       overageCostCents: updateOverageCostCents,
     },
+    simulator,
     totalOverageCostCents,
     estimatedBillCents: (subscription?.recurringCents ?? 0) + totalOverageCostCents,
     recurringCents: subscription?.recurringCents ?? null,
   };
 }
 
+// Accounts without EAS Simulator get no SIMULATOR_USAGE plan metric, so the section is hidden.
+// On the Free plan the metric is the minute pool shared with Workflows, split by jobTypeBreakdown.
+function extractSimulatorUsage(
+  simulatorTotal: AccountFullUsageData['usageMetrics']['EAS_SIMULATOR'],
+  iosMinutes: number,
+  androidMinutes: number
+): SimulatorUsageDisplay | undefined {
+  if (
+    simulatorTotal.unavailableServiceUsageMetrics.some(
+      metric => metric.service === EasService.Simulator
+    )
+  ) {
+    throw new Error(
+      'Simulator usage is temporarily unavailable, so the bill cannot be estimated. Try again in a few minutes.'
+    );
+  }
+  const planMetric = simulatorTotal.planMetrics.find(
+    m => m.serviceMetric === EasServiceMetric.SimulatorUsage
+  );
+  if (!planMetric) {
+    return undefined;
+  }
+  const overage = simulatorTotal.overageMetrics.find(
+    m => m.serviceMetric === EasServiceMetric.SimulatorUsage
+  );
+  const jobTypeBreakdown = planMetric.jobTypeBreakdown
+    ? {
+        workflows: planMetric.jobTypeBreakdown.workflows,
+        simulator: planMetric.jobTypeBreakdown.simulator,
+        other: planMetric.jobTypeBreakdown.other,
+      }
+    : undefined;
+
+  return {
+    minutes: {
+      name: jobTypeBreakdown ? 'CI/CD and Simulator minutes' : 'Simulator minutes',
+      planValue: planMetric.value,
+      limit: planMetric.limit,
+      percentUsed: calculatePercentUsed(planMetric.value, planMetric.limit),
+      overageValue: overage?.value ?? 0,
+      overageCost: overage?.totalCost ?? 0,
+      unit: 'minutes',
+      maxDecimals: 1,
+    },
+    iosMinutes,
+    androidMinutes,
+    jobTypeBreakdown,
+    overageCostCents: simulatorTotal.totalCost,
+  };
+}
+
 export function calculateBillingPeriodInfo(data: UsageDisplayData): {
   daysRemaining: number;
   daysElapsed: number;

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

@@ -28,6 +28,7 @@ const sessionManager = new SessionManager({
   logEvent: jest.fn(),
   setActor: jest.fn(),
   flushAsync: jest.fn(),
+  getDeviceId: jest.fn(),
 });
 const originalIsTTY = process.stdin.isTTY;
 const originalCI = process.env.CI;

packages/eas-cli/src/commands/account/__tests__/usage.test.ts

@@ -34,6 +34,15 @@ function createMockFullUsageData(
     bandwidthLimit: number;
     buildOverageCost: number;
     updateOverageCost: number;
+    simulator: {
+      planValue: number;
+      limit: number;
+      iosMinutes: number;
+      androidMinutes: number;
+      overageMinutes?: number;
+      overageCost?: number;
+      jobTypeBreakdown?: { workflows: number; simulator: number; other: number };
+    };
   }> = {}
 ): AccountFullUsageQueryType['account']['byId'] {
   const {
@@ -47,6 +56,7 @@ function createMockFullUsageData(
     bandwidthLimit = 10,
     buildOverageCost = 0,
     updateOverageCost = 0,
+    simulator,
   } = overrides;
 
   const now = new Date();
@@ -179,10 +189,88 @@ function createMockFullUsageData(
             : [],
         totalCost: updateOverageCost,
       },
+      // Accounts without EAS Simulator get empty metrics from the server
+      EAS_SIMULATOR: {
+        unavailableServiceUsageMetrics: [],
+        __typename: 'UsageMetricTotal',
+        id: 'simulator-metric-id',
+        billingPeriod: {
+          __typename: 'BillingPeriod',
+          id: 'billing-period-id',
+          start: startOfMonth.toISOString(),
+          end: endOfMonth.toISOString(),
+          anchor: startOfMonth.toISOString(),
+        },
+        planMetrics: simulator
+          ? [
+              {
+                __typename: 'EstimatedUsage',
+                id: 'simulator-plan-metric-id',
+                service: EasService.Simulator,
+                serviceMetric: EasServiceMetric.SimulatorUsage,
+                metricType: UsageMetricType.Minute,
+                value: simulator.planValue,
+                limit: simulator.limit,
+                jobTypeBreakdown: simulator.jobTypeBreakdown
+                  ? { __typename: 'EstimatedUsageJobTypeBreakdown', ...simulator.jobTypeBreakdown }
+                  : null,
+              },
+            ]
+          : [],
+        overageMetrics:
+          simulator && (simulator.overageMinutes ?? 0) > 0
+            ? [
+                {
+                  __typename: 'EstimatedOverageAndCost',
+                  id: 'simulator-overage-id',
+                  service: EasService.Simulator,
+                  serviceMetric: EasServiceMetric.SimulatorUsage,
+                  metricType: UsageMetricType.Minute,
+                  value: simulator.overageMinutes ?? 0,
+                  limit: simulator.limit,
+                  totalCost: simulator.overageCost ?? 0,
+                },
+              ]
+            : [],
+        totalCost: simulator?.overageCost ?? 0,
+      },
+      IOS_SIMULATOR_MINUTES: simulator
+        ? [
+            {
+              __typename: 'AccountUsageMetric',
+              id: 'ios-simulator-minutes-id',
+              serviceMetric: EasServiceMetric.SimulatorUsage,
+              metricType: UsageMetricType.Minute,
+              value: simulator.iosMinutes,
+            },
+          ]
+        : [],
+      ANDROID_SIMULATOR_MINUTES: simulator
+        ? [
+            {
+              __typename: 'AccountUsageMetric',
+              id: 'android-simulator-minutes-id',
+              serviceMetric: EasServiceMetric.SimulatorUsage,
+              metricType: UsageMetricType.Minute,
+              value: simulator.androidMinutes,
+            },
+          ]
+        : [],
     },
   };
 }
 
+function renderUsage(usageData: ReturnType<typeof createMockFullUsageData>): string {
+  const mockLog = jest.mocked(Log.log);
+  mockLog.mockClear();
+  displayUsage(extractUsageData(usageData), usageData);
+  // eslint-disable-next-line no-control-regex
+  return mockLog.mock.calls
+    .flat()
+    .join('\n')
+    .replace(/\u001b\[\d+m/g, '');
+}
+
 describe('AccountQuery', () => {
   const mockGraphqlClient = {} as ExpoGraphqlClient;
   const mockGetFullUsageAsync = jest.mocked(AccountQuery.getFullUsageAsync);
@@ -219,12 +307,6 @@ describe('AccountQuery', () => {
 });
 
 describe('displayUsage', () => {
-  const mockLog = jest.mocked(Log.log);
-
-  beforeEach(() => {
-    mockLog.mockClear();
-  });
-
   it('labels usage beyond included credits as "additional usage"', () => {
     const usageData = createMockFullUsageData({
       buildValue: 55,
@@ -234,21 +316,71 @@ describe('displayUsage', () => {
       buildOverageCost: 1500,
       updateOverageCost: 250,
     });
-    const displayData = extractUsageData(usageData);
+    const output = renderUsage(usageData);
 
-    displayUsage(displayData, usageData);
-
-    // eslint-disable-next-line no-control-regex
-    const output = mockLog.mock.calls
-      .flat()
-      .join('\n')
-      .replace(/\u001b\[\d+m/g, '');
     expect(output).toContain('Unique Updaters (additional usage): 500 users ($2.50)');
     expect(output).toContain('Additional usage: $17.50');
     expect(output).toContain('Builds: $15.00');
     expect(output).toContain('Updates: $2.50');
     expect(output.toLowerCase()).not.toContain('overage');
   });
+
+  it('hides the EAS Simulator section when the account has no simulator metric', () => {
+    const usageData = createMockFullUsageData();
+
+    const output = renderUsage(usageData);
+
+    expect(output).not.toContain('EAS Simulator');
+    expect(extractUsageData(usageData).simulator).toBeUndefined();
+  });
+
+  it('shows simulator minutes with the platform breakdown and additional usage', () => {
+    const usageData = createMockFullUsageData({
+      simulator: {
+        planValue: 60,
+        limit: 60,
+        iosMinutes: 50.25,
+        androidMinutes: 13.5,
+        overageMinutes: 3.75,
+        overageCost: 52,
+      },
+    });
+
+    const output = renderUsage(usageData);
+
+    expect(output).toContain('EAS Simulator');
+    expect(output).toContain('Simulator minutes (plan): 60/60 minutes');
+    expect(output).toContain('Simulator minutes (additional usage): 3.8 minutes ($0.52)');
+    expect(output).toContain('Simulator minutes by platform:');
+    expect(output).toContain('iOS: 50.3 minutes');
+    expect(output).toContain('Android: 13.5 minutes');
+    expect(output).not.toContain('Breakdown by job type');
+    expect(output).toContain('Simulator: $0.52');
+    expect(output).toContain('Additional usage: $0.52');
+    expect(output).toContain('Estimated bill: $19.52');
+  });
+
+  it('shows the shared minute pool by job type on the Free plan', () => {
+    const usageData = createMockFullUsageData({
+      subscriptionName: 'Free',
+      simulator: {
+        planValue: 50,
+        limit: 60,
+        iosMinutes: 10,
+        androidMinutes: 0,
+        jobTypeBreakdown: { workflows: 40, simulator: 10, other: 0 },
+      },
+    });
+
+    const output = renderUsage(usageData);
+
+    expect(output).toContain('CI/CD and Simulator minutes (plan): 50/60 minutes');
+    expect(output).toContain('Breakdown by job type:');
+    expect(output).toContain('Workflows: 40 minutes');
+    expect(output).toContain('Simulator: 10 minutes');
+    expect(output).not.toContain('Other jobs');
+    expect(output).toContain('iOS: 10 minutes');
+  });
 });
 
 describe('calculatePercentUsed', () => {

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

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import EasCommand from '../../commandUtils/EasCommand';
 import { EASNonInteractiveFlag, EasJsonOnlyFlag } from '../../commandUtils/flags';
 import {
+  SimulatorUsageDisplay,
   UsageDisplayData,
   UsageMetricDisplay,
   calculateBillingPeriodInfo,
@@ -65,12 +66,22 @@ function displayBandwidthMetric(metric: UsageMetricDisplay, indent: string = '
   }
 }
 
+function formatMetricValue(value: number, maxDecimals: number): string {
+  return value.toLocaleString(undefined, { maximumFractionDigits: maxDecimals });
+}
+
+function formatMinutes(minutes: number): string {
+  return `${formatMetricValue(minutes, 1)} minutes`;
+}
+
 function displayMetric(metric: UsageMetricDisplay, indent: string = '  '): void {
   const progressBar = createProgressBar(metric.percentUsed, 20);
   const percentStr = `${metric.percentUsed}%`;
-  const planUsageStr = `${formatNumber(metric.planValue)}/${formatNumber(metric.limit)} ${
-    metric.unit ?? ''
-  }`;
+  const maxDecimals = metric.maxDecimals ?? 0;
+  const planUsageStr = `${formatMetricValue(metric.planValue, maxDecimals)}/${formatMetricValue(
+    metric.limit,
+    maxDecimals
+  )} ${metric.unit ?? ''}`;
 
   let color = chalk.green;
   if (metric.percentUsed >= 100) {
@@ -85,12 +96,34 @@ function displayMetric(metric: UsageMetricDisplay, indent: string = '  '): void
   if (metric.overageValue > 0) {
     Log.log(
       `${indent}${metric.name} (additional usage): ${chalk.red(
-        `${formatNumber(metric.overageValue)} ${metric.unit ?? ''}`
+        `${formatMetricValue(metric.overageValue, maxDecimals)} ${metric.unit ?? ''}`
       )} (${formatCurrency(metric.overageCost)})`
     );
   }
 }
 
+function displaySimulatorUsage(simulator: SimulatorUsageDisplay): void {
+  Log.newLine();
+  Log.log(chalk.bold.underline('EAS Simulator'));
+  displayMetric(simulator.minutes);
+
+  if (simulator.jobTypeBreakdown) {
+    const { workflows, simulator: simulatorMinutes, other } = simulator.jobTypeBreakdown;
+    Log.log('  Breakdown by job type:');
+    Log.log(`    Workflows: ${formatMinutes(workflows)}`);
+    Log.log(`    Simulator: ${formatMinutes(simulatorMinutes)}`);
+    if (other > 0) {
+      Log.log(`    Other jobs: ${formatMinutes(other)}`);
+    }
+  }
+
+  if (simulator.iosMinutes > 0 || simulator.androidMinutes > 0) {
+    Log.log('  Simulator minutes by platform:');
+    Log.log(`    iOS: ${formatMinutes(simulator.iosMinutes)}`);
+    Log.log(`    Android: ${formatMinutes(simulator.androidMinutes)}`);
+  }
+}
+
 function billingUrl(accountName: string): string {
   return `https://expo.dev/accounts/${accountName}/settings/billing`;
 }
@@ -141,6 +174,10 @@ export function displayUsage(data: UsageDisplayData, usageData: AccountFullUsage
   displayMetric(data.updates.mau);
   displayBandwidthMetric(data.updates.bandwidth);
 
+  if (data.simulator) {
+    displaySimulatorUsage(data.simulator);
+  }
+
   Log.newLine();
   Log.log(chalk.bold.underline('Billing'));
 
@@ -190,6 +227,9 @@ export function displayUsage(data: UsageDisplayData, usageData: AccountFullUsage
       if (data.updates.overageCostCents > 0) {
         Log.log(`    Updates: ${formatCurrency(data.updates.overageCostCents)}`);
       }
+      if (data.simulator && data.simulator.overageCostCents > 0) {
+        Log.log(`    Simulator: ${formatCurrency(data.simulator.overageCostCents)}`);
+      }
     }
 
     Log.log(`  Estimated bill: ${chalk.bold(formatCurrency(data.estimatedBillCents))}`);
@@ -387,6 +427,27 @@ export default class AccountUsage extends EasCommand {
             },
             overageCostCents: displayData.updates.overageCostCents,
           },
+          simulator: displayData.simulator
+            ? {
+                minutes: {
+                  plan: {
+                    used: displayData.simulator.minutes.planValue,
+                    limit: displayData.simulator.minutes.limit,
+                    percentUsed: displayData.simulator.minutes.percentUsed,
+                  },
+                  overage: {
+                    count: displayData.simulator.minutes.overageValue,
+                    costCents: displayData.simulator.minutes.overageCost,
+                  },
+                },
+                byPlatform: {
+                  ios: displayData.simulator.iosMinutes,
+                  android: displayData.simulator.androidMinutes,
+                },
+                byJobType: displayData.simulator.jobTypeBreakdown ?? null,
+                overageCostCents: displayData.simulator.overageCostCents,
+              }
+            : null,
           billing: {
             addons: subscription?.addons ?? [],
             upcomingInvoice: subscription?.upcomingInvoice ?? null,

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

@@ -4,7 +4,8 @@ import EasCommand from '../commandUtils/EasCommand';
 import Log from '../log';
 
 export default class AnalyticsView extends EasCommand {
-  static override description = 'display or change analytics settings';
+  static override description =
+    'display or change analytics settings (disabling analytics also disables experiments)';
 
   static override args = {
     STATUS: Args.string({

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

@@ -140,6 +140,7 @@ export default class Build extends EasCommand {
     ...this.ContextOptions.ProjectDir,
     ...this.ContextOptions.Analytics,
     ...this.ContextOptions.Vcs,
+    ...this.ContextOptions.Experimentation,
   };
 
   async runAsync(): Promise<void> {
@@ -156,6 +157,7 @@ export default class Build extends EasCommand {
       projectDir,
       analytics,
       vcsClient,
+      experimentation,
     } = await this.getContextAsync(Build, {
       nonInteractive: flags.nonInteractive,
       withServerSideEnvironment: null,
@@ -182,6 +184,7 @@ export default class Build extends EasCommand {
       flags: flagsWithPlatform,
       actor,
       getDynamicPrivateProjectConfigAsync,
+      experimentation,
     });
 
     this.maybeSuggestUsingEasBuildDev({

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

@@ -1967,6 +1967,146 @@ describe(Simulator, () => {
     );
   });
 
+  it('sends frame ancestors and prints the embed URL', async () => {
+    const remoteConfig = {
+      __typename: 'AgentDeviceRunSessionRemoteConfig' as const,
+      agentDeviceRemoteSessionUrl: 'https://agent-device.example.test',
+      agentDeviceRemoteSessionToken: 'daemon-token',
+      webPreviewUrl: 'https://expo.dev/simulator-preview/preview-123',
+      webPreviewToken: 'preview-secret',
+      previewApiUrl: 'https://preview-api.example.test',
+    };
+    mockByIdAsync.mockResolvedValue(
+      makeDeviceRunSession({ type: DeviceRunSessionType.AgentDevice, remoteConfig })
+    );
+    const frameAncestorFlags = [
+      '--frame-ancestor',
+      'https://Embed.example.test/',
+      '--frame-ancestor',
+      'https://*.example.test',
+    ];
+
+    const { command: jsonCommand } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--json',
+      ...frameAncestorFlags,
+    ]);
+    await jsonCommand.runAsync();
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      expect.objectContaining({
+        publicPreview: false,
+        frameAncestors: ['https://embed.example.test', 'https://*.example.test'],
+      })
+    );
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteConfig: expect.objectContaining({
+          webPreviewUrl: deviceRunSessionPreviewUrl,
+          previewApiUrl: 'https://preview-api.example.test/?token=preview-secret',
+        }),
+      })
+    );
+
+    jest.clearAllMocks();
+    mockByIdAsync.mockResolvedValue(
+      makeDeviceRunSession({ type: DeviceRunSessionType.AgentDevice, remoteConfig })
+    );
+    const { command: humanCommand } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      ...frameAncestorFlags,
+    ]);
+    await humanCommand.runAsync();
+    expect(Log.log).toHaveBeenCalledWith(
+      expect.stringContaining('https://preview-api.example.test/?token=preview-secret')
+    );
+  });
+
+  it('sends CORS origins and prints the preview API URL', async () => {
+    const remoteConfig = {
+      __typename: 'AgentDeviceRunSessionRemoteConfig' as const,
+      agentDeviceRemoteSessionUrl: 'https://agent-device.example.test',
+      agentDeviceRemoteSessionToken: 'daemon-token',
+      webPreviewUrl: 'https://expo.dev/simulator-preview/preview-123',
+      webPreviewToken: 'preview-secret',
+      previewApiUrl: 'https://preview-api.example.test',
+    };
+    mockByIdAsync.mockResolvedValue(
+      makeDeviceRunSession({ type: DeviceRunSessionType.AgentDevice, remoteConfig })
+    );
+
+    const { command: jsonCommand } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--json',
+      '--cors-origin',
+      'https://App.example.test/',
+    ]);
+    await jsonCommand.runAsync();
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      expect.objectContaining({ corsOrigins: ['https://app.example.test'] })
+    );
+    expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+      graphqlClient,
+      expect.not.objectContaining({ frameAncestors: expect.anything() })
+    );
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteConfig: expect.objectContaining({
+          previewApiUrl: 'https://preview-api.example.test/?token=preview-secret',
+        }),
+      })
+    );
+
+    jest.clearAllMocks();
+    mockByIdAsync.mockResolvedValue(
+      makeDeviceRunSession({ type: DeviceRunSessionType.AgentDevice, remoteConfig })
+    );
+    const { command: humanCommand } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--cors-origin',
+      'https://app.example.test',
+    ]);
+    await humanCommand.runAsync();
+    expect(Log.log).toHaveBeenCalledWith(
+      expect.stringContaining('https://preview-api.example.test/?token=preview-secret')
+    );
+  });
+
+  it('rejects a CORS origin with a path before creating a session', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--cors-origin',
+      'https://app.example.test/app',
+    ]);
+    await expect(command.runAsync()).rejects.toThrow(
+      '--cors-origin https://app.example.test/app must be an origin only'
+    );
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects a frame ancestor that is not an origin before creating a session', async () => {
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--non-interactive',
+      '--frame-ancestor',
+      'https://embed.example.test/embed',
+    ]);
+    await expect(command.runAsync()).rejects.toThrow('must be an origin only');
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
   it.each([false, true])(
     'uses the %s public-link choice in start JSON and human output',
     async publicLink => {

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

@@ -0,0 +1,154 @@
+import { Config } from '@oclif/core';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import {
+  AppPlatform,
+  DeviceRunSessionByIdQuery,
+  DeviceRunSessionStatus,
+  DeviceRunSessionType,
+} from '../../../graphql/generated';
+import { DeviceRunSessionQuery } from '../../../graphql/queries/DeviceRunSessionQuery';
+import { EAS_SIMULATOR_SESSION_ID, loadSimulatorEnvAsync } from '../../../simulator/env';
+import {
+  getServeSimDeviceUdidAsync,
+  runServeSimHostActionAsync,
+} from '../../../simulator/serveSimHost';
+import SimulatorSimctl, { parseSimctlArgv } from '../simctl';
+
+jest.mock('../../../graphql/queries/DeviceRunSessionQuery');
+jest.mock('../../../log');
+jest.mock('../../../simulator/env', () => ({
+  ...jest.requireActual('../../../simulator/env'),
+  loadSimulatorEnvAsync: jest.fn(),
+}));
+jest.mock('../../../simulator/serveSimHost', () => ({
+  ...jest.requireActual('../../../simulator/serveSimHost'),
+  getServeSimDeviceUdidAsync: jest.fn(),
+  runServeSimHostActionAsync: jest.fn(),
+}));
+
+type DeviceRunSessionById = DeviceRunSessionByIdQuery['deviceRunSessions']['byId'];
+
+const UDID = '5B3A2F1E-0C4D-4E8F-9A7B-1C2D3E4F5A6B';
+const SPRINGBOARD_RESTART = [
+  'spawn',
+  'launchctl',
+  'kickstart',
+  '-k',
+  'system/com.apple.SpringBoard',
+];
+
+const mockByIdAsync = jest.mocked(DeviceRunSessionQuery.byIdAsync);
+const mockGetServeSimDeviceUdidAsync = jest.mocked(getServeSimDeviceUdidAsync);
+const mockRunServeSimHostActionAsync = jest.mocked(runServeSimHostActionAsync);
+
+function makeSession(overrides: Partial<DeviceRunSessionById> = {}): DeviceRunSessionById {
+  return {
+    id: 'session-123',
+    status: DeviceRunSessionStatus.InProgress,
+    type: DeviceRunSessionType.Argent,
+    platform: AppPlatform.Ios,
+    remoteConfig: {
+      __typename: 'ArgentRunSessionRemoteConfig',
+      toolsUrl: 'https://argent.example.com',
+      previewApiUrl: 'https://preview.example.com',
+      webPreviewToken: 'preview-token',
+    },
+    ...overrides,
+  } as DeviceRunSessionById;
+}
+
+function getMockOclifConfig(): Config {
+  const config = new Config({ root: __dirname });
+  config.runHook = async () => ({ failures: [], successes: [] });
+  return config;
+}
+
+describe(parseSimctlArgv, () => {
+  it('reads --id before the simctl arguments', () => {
+    expect(parseSimctlArgv(['--id', 'session-1', 'ui', 'appearance', 'dark'])).toEqual({
+      id: 'session-1',
+      args: ['ui', 'appearance', 'dark'],
+    });
+    expect(parseSimctlArgv(['--id=session-1', ...SPRINGBOARD_RESTART])).toEqual({
+      id: 'session-1',
+      args: SPRINGBOARD_RESTART,
+    });
+  });
+
+  it('passes simctl flags through untouched', () => {
+    expect(parseSimctlArgv(SPRINGBOARD_RESTART)).toEqual({ args: SPRINGBOARD_RESTART });
+    expect(parseSimctlArgv(['--', '--id', 'x'])).toEqual({ args: ['--id', 'x'] });
+  });
+});
+
+describe(SimulatorSimctl, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    delete process.env[EAS_SIMULATOR_SESSION_ID];
+    jest.mocked(loadSimulatorEnvAsync).mockResolvedValue();
+    mockByIdAsync.mockResolvedValue(makeSession());
+    mockGetServeSimDeviceUdidAsync.mockResolvedValue(UDID);
+    mockRunServeSimHostActionAsync.mockResolvedValue({ stdout: '', stderr: '' });
+  });
+
+  function createCommand(argv: string[]): SimulatorSimctl {
+    const command = new SimulatorSimctl(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    jest.spyOn(command, 'getContextAsync').mockResolvedValue({
+      loggedIn: { graphqlClient },
+      projectDir: '/test/project',
+    });
+    return command;
+  }
+
+  it('restarts SpringBoard on the session simulator', async () => {
+    await createCommand(['--id', 'session-123', ...SPRINGBOARD_RESTART]).runAsync();
+
+    expect(mockByIdAsync).toHaveBeenCalledWith(graphqlClient, 'session-123');
+    expect(mockRunServeSimHostActionAsync).toHaveBeenCalledWith(
+      { apiUrl: 'https://preview.example.com', token: 'preview-token' },
+      'springboard.restart',
+      { udid: UDID }
+    );
+  });
+
+  it('sets the appearance on the session from the env file', async () => {
+    process.env[EAS_SIMULATOR_SESSION_ID] = 'session-123';
+
+    await createCommand(['ui', 'appearance', 'dark']).runAsync();
+
+    expect(mockRunServeSimHostActionAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      'appearance.set',
+      { value: 'dark', udid: UDID }
+    );
+  });
+
+  it('rejects an unsupported command before fetching the session', async () => {
+    await expect(
+      createCommand(['--id', 'session-123', 'spawn', 'sh', '-c', 'id']).runAsync()
+    ).rejects.toThrow('Unsupported simctl command: spawn sh -c id');
+    expect(mockByIdAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects an Android session', async () => {
+    mockByIdAsync.mockResolvedValue(makeSession({ platform: AppPlatform.Android }));
+
+    await expect(
+      createCommand(['--id', 'session-123', 'ui', 'appearance', 'dark']).runAsync()
+    ).rejects.toThrow('only supports iOS');
+    expect(mockRunServeSimHostActionAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects a session that is not running', async () => {
+    mockByIdAsync.mockResolvedValue(makeSession({ status: DeviceRunSessionStatus.Stopped }));
+
+    await expect(
+      createCommand(['--id', 'session-123', 'ui', 'appearance', 'dark']).runAsync()
+    ).rejects.toThrow('is stopped, not running');
+  });
+});

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

@@ -31,6 +31,7 @@ import Log, { link } from '../../log';
 import { Ora, ora } from '../../ora';
 import { promptAsync } from '../../prompts';
 import { parseEgressAllowList, runLocalEgressAsync } from '../../simulator/egress';
+import { parseCorsOriginList, parseFrameAncestorList } from '../../simulator/frameAncestors';
 import { parseNetworkCaptureFields } from '../../simulator/networkCapture';
 import {
   EAS_SIMULATOR_SESSION_ID,
@@ -177,6 +178,16 @@ export default class Simulator extends EasCommand {
       multiple: true,
       dependsOn: ['egress'],
     }),
+    'cors-origin': Flags.string({
+      description:
+        'Origin of a page that may call the simulator preview API cross-origin, for example to render the device with @expo/hub-client, such as https://app.example.com or https://*.example.com. Repeat for multiple origins. Embedding the preview in a frame does not need this; use --frame-ancestor for that. The page still needs the printed preview URL and its token.',
+      multiple: true,
+    }),
+    'frame-ancestor': Flags.string({
+      description:
+        'Origin of a page that may embed the simulator preview in a frame, such as https://app.example.com or https://*.example.com. Repeat for multiple origins. The embedding page loads the printed preview URL, which carries the session token, so anyone who can read that page can also control the simulator.',
+      multiple: true,
+    }),
     force: Flags.boolean({
       description:
         '[default: true] Create a new simulator session even when an existing simulator session is present in the environment.',
@@ -286,6 +297,18 @@ export default class Simulator extends EasCommand {
     } catch (err) {
       throw new EasCommandError(err instanceof Error ? err.message : String(err));
     }
+    let frameAncestors: string[] = [];
+    try {
+      frameAncestors = parseFrameAncestorList(flags['frame-ancestor'] ?? []);
+    } catch (err) {
+      throw new EasCommandError(err instanceof Error ? err.message : String(err));
+    }
+    let corsOrigins: string[] = [];
+    try {
+      corsOrigins = parseCorsOriginList(flags['cors-origin'] ?? []);
+    } catch (err) {
+      throw new EasCommandError(err instanceof Error ? err.message : String(err));
+    }
     if (flags['network-capture'] && platform !== AppPlatform.Ios) {
       throw new EasCommandError(
         'Network capture is only supported on iOS simulator sessions. Re-run without --network-capture, or pass --platform ios.'
@@ -358,6 +381,8 @@ export default class Simulator extends EasCommand {
             ...(openUrl ? { openUrl } : {}),
             ...(resourceClass ? { resourceClass } : {}),
             ...(egress ? { egress } : {}),
+            ...(frameAncestors.length ? { frameAncestors } : {}),
+            ...(corsOrigins.length ? { corsOrigins } : {}),
             requestOrigin: DeviceRunSessionRequestOrigin.EasCli,
             ...agentIdentity,
             maxRunTimeMinutes: flags['max-duration-minutes'],
@@ -510,7 +535,8 @@ export default class Simulator extends EasCommand {
         remoteConfig: sanitizeRemoteConfigForJson(
           remoteConfig,
           deviceRunSessionPreviewUrl,
-          flags['public-link']
+          flags['public-link'],
+          { frameAncestors, corsOrigins }
         ),
       });
       return;
@@ -524,6 +550,8 @@ export default class Simulator extends EasCommand {
         sessionUrl: deviceRunSessionUrl,
         privatePreviewUrl: deviceRunSessionPreviewUrl,
         publicLink: flags['public-link'],
+        frameAncestors,
+        corsOrigins,
         platform,
       })
     );

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

@@ -0,0 +1,108 @@
+import EasCommand from '../../commandUtils/EasCommand';
+import { AppPlatform, DeviceRunSessionStatus } from '../../graphql/generated';
+import { DeviceRunSessionQuery } from '../../graphql/queries/DeviceRunSessionQuery';
+import Log from '../../log';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+} from '../../simulator/env';
+import {
+  getServeSimDeviceUdidAsync,
+  getServeSimHost,
+  runServeSimHostActionAsync,
+} from '../../simulator/serveSimHost';
+import { SUPPORTED_SIMCTL_COMMANDS, resolveSimctlHostAction } from '../../simulator/simctl';
+
+export function parseSimctlArgv(rawArgv: string[]): { id?: string; args: string[] } {
+  let id: string | undefined;
+  let index = 0;
+  while (index < rawArgv.length) {
+    const arg = rawArgv[index];
+    if (arg === '--') {
+      index += 1;
+      break;
+    }
+    if (arg === '--id') {
+      id = rawArgv[index + 1];
+      if (!id) {
+        throw new Error('--id needs a simulator session ID.');
+      }
+      index += 2;
+    } else if (arg.startsWith('--id=')) {
+      id = arg.slice('--id='.length);
+      index += 1;
+    } else {
+      break;
+    }
+  }
+  return { id, args: rawArgv.slice(index) };
+}
+
+export default class SimulatorSimctl extends EasCommand {
+  static override aliases = ['sim:simctl'];
+  static override description = `[EXPERIMENTAL] run a supported simctl command on a remote iOS simulator session, without the device argument. Supported: ${SUPPORTED_SIMCTL_COMMANDS.map(
+    command => `\`${command}\``
+  ).join(', ')}`;
+  static override strict = false;
+  static override usage = ['simulator:simctl [--id <value>] <simctl arguments...>'];
+
+  static override contextDefinition = {
+    ...this.ContextOptions.LoggedIn,
+    ...this.ContextOptions.ProjectDir,
+  };
+
+  async runAsync(): Promise<void> {
+    const rawArgv = [...this.argv];
+    await this.parse(SimulatorSimctl, []);
+    const { id: flagId, args } = parseSimctlArgv(rawArgv);
+
+    const hostAction = resolveSimctlHostAction(args);
+    if (!hostAction) {
+      throw new Error(
+        `Unsupported simctl command${args.length > 0 ? `: ${args.join(' ')}` : ''}. Supported commands, without the device argument:\n${SUPPORTED_SIMCTL_COMMANDS.map(
+          command => `  ${command}`
+        ).join('\n')}`
+      );
+    }
+
+    const {
+      projectDir,
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(SimulatorSimctl, { nonInteractive: true });
+
+    await loadSimulatorEnvAsync(projectDir);
+    const sessionId = flagId || process.env[EAS_SIMULATOR_SESSION_ID];
+    if (!sessionId) {
+      throw new Error(
+        `No simulator session ID provided. Pass --id, or run \`eas simulator:start\` first to write ${SIMULATOR_DOTENV_FILE_NAME}.`
+      );
+    }
+
+    const session = await DeviceRunSessionQuery.byIdAsync(graphqlClient, sessionId);
+    if (session.platform !== AppPlatform.Ios) {
+      throw new Error(`simulator:simctl only supports iOS simulator sessions.`);
+    }
+    if (session.status !== DeviceRunSessionStatus.InProgress) {
+      throw new Error(
+        `Simulator session ${session.id} is ${session.status.toLowerCase()}, not running.`
+      );
+    }
+    const host = session.remoteConfig ? getServeSimHost(session.remoteConfig) : null;
+    if (!host) {
+      throw new Error(`Simulator session ${session.id} has no simulator host to run simctl on.`);
+    }
+
+    const udid = await getServeSimDeviceUdidAsync(host);
+    const { stdout, stderr } = await runServeSimHostActionAsync(host, hostAction.action, {
+      ...hostAction.params,
+      udid,
+    });
+    if (stdout) {
+      Log.log(stdout.trimEnd());
+    }
+    if (stderr) {
+      Log.warn(stderr.trimEnd());
+    }
+  }
+}

packages/eas-cli/src/env.ts

@@ -21,4 +21,10 @@ export default {
    * Comma separated list of feature gate keys of feature gates to evaluate override to false.
    */
   featureGateDisable: process.env.EAS_FG_DISABLE,
+  /**
+   * Comma separated list of experiment overrides in the form `namespace:param=value`.
+   * Overrides apply in every scope, even when analytics is disabled. A namespace with any override
+   * returns defaults for its other params and logs no exposure.
+   */
+  experimentOverride: process.env.EAS_EXPERIMENT_OVERRIDE,
 };

packages/eas-cli/src/experimentation/AnalyticsExposureLogger.ts

@@ -0,0 +1,18 @@
+import type { ExposureData, ExposureLogger } from '@expo/experimentation';
+
+import { Analytics, ExperimentationEvent } from '../analytics/AnalyticsManager';
+
+export class AnalyticsExposureLogger implements ExposureLogger<Record<string, any>> {
+  constructor(private readonly analytics: Analytics) {}
+
+  public logExposure(data: ExposureData<Record<string, any>>): void {
+    const { variant } = data.params;
+    this.analytics.logEvent(ExperimentationEvent.EXPERIMENT_VIEWED, {
+      experimentName: data.name,
+      // Analytics properties cannot be undefined. Fall back to all params when there is no variant.
+      variationName: variant !== undefined ? String(variant) : JSON.stringify(data.params),
+      // The unit is always a single value (actor ID, account ID, or device ID).
+      unit: String(data.unit[0]),
+    });
+  }
+}

packages/eas-cli/src/experimentation/ExperimentNamespace.ts

@@ -0,0 +1,79 @@
+import type { Namespace } from '@expo/experimentation';
+
+import { ExperimentOverrides } from './ExperimentOverrides';
+import Log from '../log';
+
+export type ExperimentNamespace = {
+  getParam<T>(paramName: string, defaultValue: T): T;
+  isOverridden: boolean;
+};
+
+export const FALLBACK_NAMESPACE: ExperimentNamespace = {
+  getParam(_paramName, defaultValue) {
+    return defaultValue;
+  },
+  isOverridden: false,
+};
+
+/** Serves overrides without consulting the real namespace, so no exposure is logged. */
+export class OverrideFallbackNamespace implements ExperimentNamespace {
+  public readonly isOverridden = true;
+
+  constructor(
+    private readonly namespaceName: string,
+    private readonly overrides: ExperimentOverrides
+  ) {}
+
+  public getParam<T>(paramName: string, defaultValue: T): T {
+    if (this.overrides.hasOverride(this.namespaceName, paramName)) {
+      return coerceOverrideValue(
+        this.overrides.getOverride(this.namespaceName, paramName),
+        defaultValue
+      );
+    }
+    return defaultValue;
+  }
+}
+
+/** Returns the default instead of throwing when the library rejects a param on first read. */
+export class SafeNamespace implements ExperimentNamespace {
+  public readonly isOverridden = false;
+
+  constructor(
+    private readonly namespace: Namespace,
+    private readonly namespaceName: string
+  ) {}
+
+  public getParam<T>(paramName: string, defaultValue: T): T {
+    try {
+      return this.namespace.getParam(paramName, defaultValue);
+    } catch (error) {
+      Log.debug(
+        `[experimentation] Failed to read param "${paramName}" from namespace "${this.namespaceName}". Returning the default.`,
+        error
+      );
+      return defaultValue;
+    }
+  }
+}
+
+export function coerceOverrideValue<T>(overrideValue: string | undefined, defaultValue: T): T {
+  if (overrideValue === undefined || overrideValue.trim() === '') {
+    return defaultValue;
+  }
+  if (typeof defaultValue === 'boolean') {
+    const normalized = overrideValue.toLowerCase();
+    if (normalized === 'true') {
+      return true as T;
+    }
+    if (normalized === 'false') {
+      return false as T;
+    }
+    return defaultValue;
+  }
+  if (typeof defaultValue === 'number') {
+    const parsed = Number(overrideValue);
+    return (Number.isFinite(parsed) ? parsed : defaultValue) as T;
+  }
+  return overrideValue as T;
+}

packages/eas-cli/src/experimentation/ExperimentOverrides.ts

@@ -0,0 +1,73 @@
+import env from '../env';
+
+export type ExperimentOverrideMap = ReadonlyMap<string, ReadonlyMap<string, string>>;
+
+/**
+ * Parses `EAS_EXPERIMENT_OVERRIDE`: comma-separated `namespace:param=value` entries. Values may
+ * contain `:` and `=` but not `,`. Overrides are keyed by namespace name and apply in every scope.
+ *
+ * @example EAS_EXPERIMENT_OVERRIDE="onboarding:variant=treatment,cli-hints:enabled=true"
+ */
+export function parseExperimentOverrides(rawValue: string | undefined): ExperimentOverrideMap {
+  const overrideMap = new Map<string, Map<string, string>>();
+  if (!rawValue) {
+    return overrideMap;
+  }
+
+  for (const entry of rawValue.split(',')) {
+    const override = entry.trim();
+    if (!override) {
+      continue;
+    }
+
+    const firstEqualsIndex = override.indexOf('=');
+    if (firstEqualsIndex === -1) {
+      continue;
+    }
+    const namespaceAndParam = override.slice(0, firstEqualsIndex);
+    const value = override.slice(firstEqualsIndex + 1).trim();
+
+    const firstColonIndex = namespaceAndParam.indexOf(':');
+    if (firstColonIndex === -1) {
+      continue;
+    }
+    const namespace = namespaceAndParam.slice(0, firstColonIndex).trim();
+    const param = namespaceAndParam.slice(firstColonIndex + 1).trim();
+    if (!namespace || !param) {
+      continue;
+    }
+
+    let params = overrideMap.get(namespace);
+    if (!params) {
+      params = new Map();
+      overrideMap.set(namespace, params);
+    }
+    params.set(param, value);
+  }
+
+  return overrideMap;
+}
+
+export class ExperimentOverrides {
+  constructor(private readonly overrideMap: ExperimentOverrideMap) {}
+
+  public static fromEnv(): ExperimentOverrides {
+    return new ExperimentOverrides(parseExperimentOverrides(env.experimentOverride));
+  }
+
+  public static empty(): ExperimentOverrides {
+    return new ExperimentOverrides(new Map());
+  }
+
+  public hasNamespaceOverride(namespace: string): boolean {
+    return this.overrideMap.has(namespace);
+  }
+
+  public hasOverride(namespace: string, param: string): boolean {
+    return this.overrideMap.get(namespace)?.has(param) ?? false;
+  }
+
+  public getOverride(namespace: string, param: string): string | undefined {
+    return this.overrideMap.get(namespace)?.get(param);
+  }
+}

packages/eas-cli/src/experimentation/ExperimentationClient.ts

@@ -0,0 +1,175 @@
+import {
+  type ExperimentUnit,
+  type ExperimentationDefinition,
+  type LoggerConfig,
+  type Namespace,
+  NoOpExposureLogger,
+  parseExperimentationConfig,
+} from '@expo/experimentation';
+import { createHash } from 'node:crypto';
+
+import { AnalyticsExposureLogger } from './AnalyticsExposureLogger';
+import {
+  type ExperimentNamespace,
+  FALLBACK_NAMESPACE,
+  OverrideFallbackNamespace,
+  SafeNamespace,
+} from './ExperimentNamespace';
+import { ExperimentOverrides } from './ExperimentOverrides';
+import { Analytics } from '../analytics/AnalyticsManager';
+import Log from '../log';
+
+export type ExperimentationScope = 'user' | 'account' | 'device';
+
+export type ExperimentationConfigs = Record<ExperimentationScope, ExperimentationDefinition>;
+
+/** Commands pass the account unit on each `getAccountNamespace` call. */
+export type ExperimentationUnits = Record<Exclude<ExperimentationScope, 'account'>, string | null>;
+
+export const EMPTY_EXPERIMENTATION_DEFINITION: ExperimentationDefinition = {
+  experiments: [],
+  namespaces: [],
+};
+
+const EMPTY_CONFIGS: ExperimentationConfigs = {
+  user: EMPTY_EXPERIMENTATION_DEFINITION,
+  account: EMPTY_EXPERIMENTATION_DEFINITION,
+  device: EMPTY_EXPERIMENTATION_DEFINITION,
+};
+
+const NULL_UNITS: ExperimentationUnits = { user: null, device: null };
+
+function sha1(input: string): string {
+  return createHash('sha1').update(input).digest('hex');
+}
+
+export function createLoggerConfig(analytics: Analytics): LoggerConfig {
+  return {
+    flavorMap: new Map([
+      ['no-op', new NoOpExposureLogger()],
+      ['rudderstack', new AnalyticsExposureLogger(analytics)],
+    ]),
+    fallbackLoggerType: 'no-op',
+  };
+}
+
+const NO_OP_LOGGER_CONFIG: LoggerConfig = {
+  flavorMap: new Map([['no-op', new NoOpExposureLogger()]]),
+  fallbackLoggerType: 'no-op',
+};
+
+/** Cached per (unit, name): the library deduplicates exposures per Namespace instance. */
+class ScopedNamespaces {
+  private readonly factories: ReadonlyMap<string, (unit: ExperimentUnit) => Namespace>;
+  private readonly instances = new Map<string, Map<string, Namespace>>();
+
+  constructor(
+    definition: ExperimentationDefinition,
+    loggerConfig: LoggerConfig,
+    defaultUnit: string | null
+  ) {
+    this.factories = parseExperimentationConfig(definition, { sha1Fn: sha1 }, loggerConfig);
+    // Build every namespace now so an invalid server config throws here, in the fail-open path.
+    if (defaultUnit) {
+      for (const name of this.factories.keys()) {
+        this.getNamespace(name, defaultUnit);
+      }
+    }
+  }
+
+  public getNamespace(name: string, unit: string): Namespace | null {
+    const factory = this.factories.get(name);
+    if (!factory) {
+      return null;
+    }
+    let byName = this.instances.get(unit);
+    if (!byName) {
+      byName = new Map();
+      this.instances.set(unit, byName);
+    }
+    let namespace = byName.get(name);
+    if (!namespace) {
+      namespace = factory([unit]);
+      byName.set(name, namespace);
+    }
+    return namespace;
+  }
+}
+
+/**
+ * Resolves experiment params for the current CLI run. Units: user is the actor ID, account is the
+ * ID the command passes to `getAccountNamespace`, device is the analytics device ID.
+ * User and account units are shared across surfaces. The device unit is specific to the CLI, so a
+ * device namespace must not be shared with another surface.
+ * The first `getParam` on a namespace logs an exposure, so call it only where the variant is used.
+ */
+export class ExperimentationClient {
+  private readonly scopes: Record<ExperimentationScope, ScopedNamespaces>;
+
+  constructor(
+    configs: ExperimentationConfigs,
+    private readonly units: ExperimentationUnits,
+    private readonly overrides: ExperimentOverrides,
+    loggerConfig: LoggerConfig
+  ) {
+    this.scopes = {
+      user: new ScopedNamespaces(configs.user, loggerConfig, units.user),
+      account: new ScopedNamespaces(configs.account, loggerConfig, null),
+      device: new ScopedNamespaces(configs.device, loggerConfig, units.device),
+    };
+  }
+
+  /** Env overrides still apply, so QA can force a variant even with analytics disabled. */
+  public static createDisabled(
+    overrides: ExperimentOverrides = ExperimentOverrides.fromEnv()
+  ): ExperimentationClient {
+    return new ExperimentationClient(EMPTY_CONFIGS, NULL_UNITS, overrides, NO_OP_LOGGER_CONFIG);
+  }
+
+  public getUserNamespace(name: string): ExperimentNamespace {
+    return this.resolve('user', name, this.units.user);
+  }
+
+  /** Takes the account the command already resolved, so no extra lookup or config read happens here. */
+  public getAccountNamespace(
+    name: string,
+    { accountId }: { accountId: string }
+  ): ExperimentNamespace {
+    return this.resolve('account', name, accountId);
+  }
+
+  public getDeviceNamespace(name: string): ExperimentNamespace {
+    return this.resolve('device', name, this.units.device);
+  }
+
+  private resolve(
+    scope: ExperimentationScope,
+    name: string,
+    unit: string | null
+  ): ExperimentNamespace {
+    if (this.overrides.hasNamespaceOverride(name)) {
+      return new OverrideFallbackNamespace(name, this.overrides);
+    }
+    if (!unit) {
+      return FALLBACK_NAMESPACE;
+    }
+
+    let namespace: Namespace | null;
+    try {
+      namespace = this.scopes[scope].getNamespace(name, unit);
+    } catch (error) {
+      Log.debug(
+        `[experimentation] Failed to build namespace "${name}" in the ${scope} config. Returning defaults.`,
+        error
+      );
+      return FALLBACK_NAMESPACE;
+    }
+    if (!namespace) {
+      Log.debug(
+        `[experimentation] Namespace "${name}" not found in the ${scope} config. Returning defaults.`
+      );
+      return FALLBACK_NAMESPACE;
+    }
+    return new SafeNamespace(namespace, name);
+  }
+}