v25.2.0

* [eas-cli] Add simulator:action command

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Fold simulator actions into one table

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Give the simulator API lookup its own timeout

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Drop event-log from simulator:action

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Rename to simulator:control and add sidebar actions

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Drive simulator:control from the serve-sim action catalog

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Fix value order, upload cleanup and output handling in simulator:control

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Check output paths and local files before simulator:control runs

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Upload only when the catalog condition matches

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Send upload IDs and JSON lists from simulator:control

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* [eas-cli] Complete the simulator control session fixture

Co-authored-by: Codex <[email protected]>

* [eas-cli] Close simulator control after discovery failure

Co-authored-by: Codex <[email protected]>

* [eas-cli] Keep simulator action descriptions on one line

Co-authored-by: Codex <[email protected]>

* [eas-cli] List simulator actions by default

Co-authored-by: Codex <[email protected]>

* [eas-cli] Reject empty simulator control session IDs

Document the separator for values beginning with --.

Co-authored-by: Codex <[email protected]>

* [eas-cli] Clarify local screenshot output usage

Co-authored-by: Codex <[email protected]>

* [eas-cli] Compact simulator action discovery and add action help

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
Co-authored-by: Codex <[email protected]>

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 This is the log of notable changes to EAS CLI and related packages.
 
+## [25.2.0](https://github.com/expo/eas-cli/releases/tag/v25.2.0) - 2026-10-17
+
+### 🎉 New features
+
+- [eas-cli] Add experimentation client. ([#4558](https://github.com/expo/eas-cli/pull/4558) by [@williamgrosset](https://github.com/williamgrosset))
+- [eas-cli] Add a Free plan build limit guidance experiment for coding agents to `eas build`. ([#4631](https://github.com/expo/eas-cli/pull/4631) by [@williamgrosset](https://github.com/williamgrosset))
+- [build-tools] Let serve-sim boot, install and launch agent-device iOS sessions with the local-egress guard. ([#4544](https://github.com/expo/eas-cli/pull/4544) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add `eas simulator:control` to run serve-sim actions, with file upload and download, on a remote iOS simulator session. ([#4641](https://github.com/expo/eas-cli/pull/4641) by [@gwdp](https://github.com/gwdp))
+
+### 🧹 Chores
+
+- [eas-cli] Prepare authenticated simulator action transport and file transfers. ([#4642](https://github.com/expo/eas-cli/pull/4642) by [@gwdp](https://github.com/gwdp))
+
 ## [25.1.1](https://github.com/expo/eas-cli/releases/tag/v25.1.1) - 2026-10-16
 
 ### 🐛 Bug fixes

cli-versions.json

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

lerna.json

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

packages/build-tools/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @expo/build-tools
 
+## 25.2.0
+
+### Minor Changes
+
+- Let serve-sim boot, install and launch agent-device iOS sessions with the local-egress guard. ([#4544](https://github.com/expo/eas-cli/pull/4544) by [@gwdp](https://github.com/gwdp))
+
 ## 25.1.1
 
 ### Patch Changes

packages/build-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/build-tools",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",
@@ -42,17 +42,17 @@
   "dependencies": {
     "@expo/config": "55.0.10",
     "@expo/config-plugins": "55.0.7",
-    "@expo/downloader": "25.1.1",
-    "@expo/eas-build-job": "25.1.1",
+    "@expo/downloader": "25.2.0",
+    "@expo/eas-build-job": "25.2.0",
     "@expo/env": "^0.4.0",
-    "@expo/logger": "25.1.1",
+    "@expo/logger": "25.2.0",
     "@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.1.1",
-    "@expo/template-file": "25.1.1",
-    "@expo/turtle-spawn": "25.1.1",
+    "@expo/steps": "25.2.0",
+    "@expo/template-file": "25.2.0",
+    "@expo/turtle-spawn": "25.2.0",
     "@expo/xcpretty": "^4.3.1",
     "@ngrok/ngrok": "1.7.0",
     "@sentry/node": "7.77.0",

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);
@@ -103,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,
@@ -134,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',
@@ -159,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]
     );
   });
 
@@ -191,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({
@@ -215,6 +284,7 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     await runStep(
       BuildRuntimePlatform.LINUX,
       { application_archive_url: 'https://example.test/app.tar.gz' },
+      undefined,
       sessionCtx
     );
     expect(downloadBuildAsync).toHaveBeenLastCalledWith(
@@ -225,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);
 
@@ -237,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 () => {
@@ -278,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();
   });
 
@@ -323,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'
     );
 
@@ -363,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 () => {
@@ -464,6 +670,31 @@ describe(createStartAgentDeviceSessionBuildFunction, () => {
     );
   });
 
+  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/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,
@@ -117,9 +114,21 @@ export async function runAgentDeviceRemoteSessionAsync(
     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}).`
   );
@@ -130,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.
@@ -158,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,
@@ -175,14 +188,20 @@ export async function runAgentDeviceRemoteSessionAsync(
       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}).`
@@ -190,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({
@@ -218,6 +239,7 @@ export async function runAgentDeviceRemoteSessionAsync(
       },
       logger,
     });
+    tasks.signal.throwIfAborted();
     void pollAgentDeviceArtifactsForUploadAsync(ctx, {
       deviceRunSessionId,
       daemonUrl: `http://127.0.0.1:${daemonPort}`,
@@ -253,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,
@@ -297,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-'));
@@ -306,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,7 +15,6 @@ import {
   AndroidEmulatorUtils,
   AndroidVirtualDeviceName,
 } from '../../utils/AndroidEmulatorUtils';
-import { IosSimulatorName, IosSimulatorUuid } from '../../utils/IosSimulatorUtils';
 import { getDeviceRunSessionWorkerApi } from '../utils/deviceRunSessionWorkerApi';
 import { withLocalEgressSession } from '../utils/localEgressSession';
 import {
@@ -33,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';
@@ -46,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({
@@ -170,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(
         {
@@ -179,109 +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,
-        frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
-        corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
-        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/create-eas-build-function/CHANGELOG.md

@@ -1,5 +1,9 @@
 # create-eas-build-function
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

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

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

packages/downloader/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @expo/downloader
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/downloader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/downloader",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "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,9 @@
 # eas-build-cache-provider
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

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

@@ -1,6 +1,6 @@
 {
   "name": "eas-build-cache-provider",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "description": "A build cache provider plugin for the Expo CLI",
   "homepage": "https://github.com/expo/eas-cli",
   "bugs": "https://github.com/expo/eas-cli/issues",

packages/eas-build-job/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @expo/eas-build-job
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/eas-build-job/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/eas-build-job",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "MIT",
   "author": "Expo <[email protected]>",
@@ -25,9 +25,9 @@
     "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\""
   },
   "dependencies": {
-    "@expo/logger": "25.1.1",
+    "@expo/logger": "25.2.0",
     "@expo/results": "1.0.0",
-    "@expo/turtle-spawn": "25.1.1",
+    "@expo/turtle-spawn": "25.2.0",
     "joi": "^17.13.1",
     "semver": "^7.6.2",
     "zod": "^4.3.5"

packages/eas-cli/CHANGELOG.md

@@ -1,5 +1,13 @@
 # eas-cli
 
+## 25.2.0
+
+### Minor Changes
+
+- Add experimentation client. ([#4558](https://github.com/expo/eas-cli/pull/4558) by [@williamgrosset](https://github.com/williamgrosset))
+- Add a Free plan build limit guidance experiment for coding agents to `eas build`. ([#4631](https://github.com/expo/eas-cli/pull/4631) by [@williamgrosset](https://github.com/williamgrosset))
+- Add `eas simulator:control` to run serve-sim actions, with file upload and download, on a remote iOS simulator session. ([#4641](https://github.com/expo/eas-cli/pull/4641) by [@gwdp](https://github.com/gwdp))
+
 ## 25.1.1
 
 No changes in this release.

packages/eas-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eas-cli",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "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.1.1",
-    "@expo/eas-json": "25.1.1",
+    "@expo/eas-build-job": "25.2.0",
+    "@expo/eas-json": "25.2.0",
     "@expo/env": "^1.0.0",
+    "@expo/experimentation": "0.0.5",
     "@expo/json-file": "8.3.3",
-    "@expo/logger": "25.1.1",
+    "@expo/logger": "25.2.0",
     "@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.1.1",
+    "@expo/steps": "25.2.0",
     "@expo/timeago.js": "1.0.0",
     "@oclif/core": "^4.8.3",
     "@oclif/plugin-autocomplete": "^3.2.40",
@@ -184,6 +185,7 @@
     ],
     "bin": "eas",
     "commands": "./build/commands",
+    "helpClass": "./build/help",
     "plugins": [
       "@oclif/plugin-autocomplete",
       "@expo/plugin-help",

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/__tests__/help.test.ts

@@ -0,0 +1,38 @@
+import { Config, Help } from '@oclif/core';
+
+import SimulatorControl from '../commands/simulator/control';
+import EasHelp from '../help';
+
+describe(EasHelp, () => {
+  const config = new Config({ root: __dirname });
+  let run: jest.SpyInstance;
+  let showHelp: jest.SpyInstance;
+
+  beforeEach(() => {
+    run = jest.spyOn(SimulatorControl, 'run').mockResolvedValue(Promise.resolve());
+    showHelp = jest.spyOn(Help.prototype, 'showHelp').mockResolvedValue();
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it.each([
+    ['simulator:control', 'rotate', '--help'],
+    ['sim:control', 'screenshot.capture', '-h', '--id', 'session-123'],
+    ['simulator:control', '--id', 'session-123', '--help', 'rotate'],
+  ])('routes action help through the command: %j', async (...argv) => {
+    await new EasHelp(config).showHelp(argv);
+    expect(run).toHaveBeenCalledWith(argv.slice(1), config);
+    expect(showHelp).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['simulator:control', '--help'],
+    ['sim:control', '-h'],
+    ['build', '--help'],
+    ['simulator:control', 'clipboard.write', '--', '--help'],
+  ])('preserves regular help and literal values: %j', async (...argv) => {
+    await new EasHelp(config).showHelp(argv);
+    expect(showHelp).toHaveBeenCalledWith(argv);
+    expect(run).not.toHaveBeenCalled();
+  });
+});

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/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/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/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__/control.test.ts

@@ -0,0 +1,499 @@
+import { Config } from '@oclif/core';
+import * as fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import {
+  AppPlatform,
+  DeviceRunSessionByIdQuery,
+  DeviceRunSessionStatus,
+  DeviceRunSessionType,
+  JobRunStatus,
+} from '../../../graphql/generated';
+import { DeviceRunSessionQuery } from '../../../graphql/queries/DeviceRunSessionQuery';
+import Log from '../../../log';
+import { loadSimulatorEnvAsync } from '../../../simulator/env';
+import {
+  HostActionCatalog,
+  HostActionResult,
+  connectHostActionsAsync,
+} from '../../../simulator/hostActions';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+import SimulatorControl from '../control';
+
+jest.mock('../../../graphql/queries/DeviceRunSessionQuery');
+jest.mock('../../../log');
+jest.mock('../../../simulator/env', () => ({
+  ...jest.requireActual('../../../simulator/env'),
+  loadSimulatorEnvAsync: jest.fn(),
+}));
+jest.mock('../../../simulator/hostActions', () => ({
+  ...jest.requireActual('../../../simulator/hostActions'),
+  connectHostActionsAsync: jest.fn(),
+}));
+jest.mock('../../../ora', () => ({
+  ora: jest.fn(() => {
+    const spinner = {
+      fail: jest.fn(),
+      start: jest.fn(),
+      succeed: jest.fn(),
+    };
+    spinner.start.mockReturnValue(spinner);
+    return spinner;
+  }),
+}));
+jest.mock('../../../utils/json');
+
+type DeviceRunSessionById = DeviceRunSessionByIdQuery['deviceRunSessions']['byId'];
+
+const catalog: HostActionCatalog = require('../../../simulator/__tests__/fixtures/hostActionCatalog.json');
+
+const mockByIdAsync = jest.mocked(DeviceRunSessionQuery.byIdAsync);
+const mockConnectHostActionsAsync = jest.mocked(connectHostActionsAsync);
+const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
+const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);
+
+function makeDeviceRunSession(
+  overrides: Partial<DeviceRunSessionById> = {}
+): DeviceRunSessionById & { publicPreview: boolean } {
+  return {
+    id: 'session-123',
+    name: null,
+    tags: [],
+    publicPreview: false,
+    status: DeviceRunSessionStatus.InProgress,
+    type: DeviceRunSessionType.WebPreviewOnly,
+    platform: AppPlatform.Ios,
+    createdAt: '2025-01-01T00:00:00.000Z',
+    startedAt: '2025-01-01T00:00:05.000Z',
+    finishedAt: null,
+    updatedAt: '2025-01-01T00:01:00.000Z',
+    app: {
+      id: 'app-123',
+      slug: 'testapp',
+      ownerAccount: { id: 'account-123', name: 'testuser' },
+    },
+    artifacts: [],
+    remoteConfig: {
+      __typename: 'WebPreviewOnlyRunSessionRemoteConfig',
+      previewUrl: 'https://expo.dev/preview',
+      previewToken: 'preview-token',
+      previewApiUrl: 'https://sim.example.test',
+    },
+    turtleJobRun: { id: 'job-123', status: JobRunStatus.InProgress },
+    ...overrides,
+  };
+}
+
+function getMockOclifConfig(): Config {
+  const config = new Config({ root: __dirname });
+  config.runHook = async () => ({
+    failures: [],
+    successes: [],
+  });
+  return config;
+}
+
+describe(SimulatorControl, () => {
+  const graphqlClient = {} as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+  const projectDir = '/test/project';
+  const ok = (stdout: string): HostActionResult => ({ stdout, stderr: '', exitCode: 0 });
+  let actionResult: HostActionResult;
+  let served: HostActionCatalog;
+  let tmpDir: string;
+  const requestAsync = jest.fn(
+    async (action: string, params: Record<string, unknown> = {}): Promise<HostActionResult> => {
+      switch (action) {
+        case 'actions.describe':
+          return ok(JSON.stringify(served));
+        case 'upload.append':
+          return ok(`/tmp/serve-sim-uploads/${params.uploadId}\n`);
+        case 'upload.remove':
+          return ok('');
+        case 'file.readBase64':
+          return ok(Buffer.from('png bytes').toString('base64'));
+        default:
+          return actionResult;
+      }
+    }
+  );
+  const close = jest.fn();
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    jest.mocked(loadSimulatorEnvAsync).mockResolvedValue();
+    mockByIdAsync.mockResolvedValue(makeDeviceRunSession());
+    mockConnectHostActionsAsync.mockResolvedValue({ requestAsync, close });
+    actionResult = ok('off\n');
+    served = catalog;
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'simulator-control-'));
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  function createCommand(argv: string[]): SimulatorControl {
+    const command = new SimulatorControl(argv, mockConfig);
+    // @ts-expect-error getContextAsync is protected
+    jest.spyOn(command, 'getContextAsync').mockResolvedValue({
+      loggedIn: { graphqlClient },
+      projectDir,
+    });
+    return command;
+  }
+
+  function actionRequests(): Parameters<typeof requestAsync>[] {
+    return requestAsync.mock.calls.filter(([action]) => action !== 'actions.describe');
+  }
+
+  it.each([['--id='], ['--id', '']])('refuses an empty session ID in %j', async (...flags) => {
+    const env = jest.replaceProperty(process, 'env', {
+      ...process.env,
+      EAS_SIMULATOR_SESSION_ID: 'env-session',
+    });
+    try {
+      await expect(
+        createCommand(['hardwareKeyboard.set', 'off', ...flags]).runAsync()
+      ).rejects.toThrow('--id needs a simulator session ID.');
+      expect(loadSimulatorEnvAsync).not.toHaveBeenCalled();
+      expect(mockByIdAsync).not.toHaveBeenCalled();
+      expect(mockConnectHostActionsAsync).not.toHaveBeenCalled();
+    } finally {
+      env.restore();
+    }
+  });
+
+  it('uses the environment session when --id is absent', async () => {
+    const env = jest.replaceProperty(process, 'env', {
+      ...process.env,
+      EAS_SIMULATOR_SESSION_ID: 'env-session',
+    });
+    try {
+      await createCommand(['hardwareKeyboard.set', 'off']).runAsync();
+      expect(mockByIdAsync).toHaveBeenCalledWith(graphqlClient, 'env-session');
+    } finally {
+      env.restore();
+    }
+  });
+
+  it('runs an action from the catalog with its values and prints the output', async () => {
+    await createCommand(['hardwareKeyboard.set', 'off', '--id', 'session-123']).runAsync();
+
+    expect(mockByIdAsync).toHaveBeenCalledWith(graphqlClient, 'session-123');
+    expect(mockConnectHostActionsAsync).toHaveBeenCalledWith({
+      apiUrl: 'https://sim.example.test',
+      token: 'preview-token',
+    });
+    expect(actionRequests()).toEqual([['hardwareKeyboard.set', { value: 'off' }]]);
+    expect(jest.mocked(Log.log)).toHaveBeenCalledWith('off');
+    expect(close).toHaveBeenCalled();
+  });
+
+  it.each([false, true])('lists the actions of the session with --list=%s', async list => {
+    await createCommand([...(list ? ['--list'] : []), '--id', 'session-123']).runAsync();
+
+    const lines = jest.mocked(Log.log).mock.calls.map(([line]) => String(line));
+    expect(lines.pop()).toBe('For action usage: eas simulator:control <action> --help');
+    expect(lines.flatMap(line => line.trim().split(/\s+/)).sort()).toEqual(
+      Object.keys(catalog).sort()
+    );
+    expect(actionRequests()).toEqual([]);
+  });
+
+  it.each(['--help', '-h'])('shows action help with %s without running the action', async help => {
+    await createCommand(['permissions.set', help, '--id', 'session-123']).runAsync();
+
+    expect(jest.mocked(Log.log)).toHaveBeenCalledWith(
+      '  Grant, revoke or reset one permission for an app.'
+    );
+    expect(jest.mocked(Log.log)).toHaveBeenCalledWith(
+      '    eas simulator:control permissions.set <action> <service> <bundleId>'
+    );
+    expect(actionRequests()).toEqual([]);
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows local file guidance without validating output or uploading files', async () => {
+    await createCommand([
+      'screenshot.capture',
+      '--help',
+      '--output',
+      '/missing/folder/screen.png',
+      '--id',
+      'session-123',
+    ]).runAsync();
+
+    expect(jest.mocked(Log.log)).toHaveBeenCalledWith(
+      '    eas simulator:control screenshot.capture [fileName]'
+    );
+    expect(jest.mocked(Log.log)).toHaveBeenCalledWith(
+      '    --output <path>    Local filename or existing directory.'
+    );
+    expect(actionRequests()).toEqual([]);
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it('prints the host action schema as JSON for help', async () => {
+    await createCommand(['app.install', '--help', '--json', '--id', 'session-123']).runAsync();
+
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalledWith({
+      action: 'app.install',
+      ...catalog['app.install'],
+    });
+    expect(actionRequests()).toEqual([]);
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects unknown actions in help and closes the connection', async () => {
+    await expect(
+      createCommand(['unknown.action', '--help', '--id', 'session-123']).runAsync()
+    ).rejects.toThrow('Unknown simulator action "unknown.action"');
+    expect(actionRequests()).toEqual([]);
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it('prints parsed JSON output', async () => {
+    actionResult = ok('{"voiceover":"off"}\n');
+
+    await createCommand(['permissions.list', '--id', 'session-123', '--json']).runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalledWith({
+      id: 'session-123',
+      action: 'permissions.list',
+      output: { voiceover: 'off' },
+      file: null,
+    });
+  });
+
+  it('uploads a local file for an action that takes one and removes it after', async () => {
+    const localFile = path.join(tmpDir, 'MyApp.ipa');
+    await fs.writeFile(localFile, 'app bytes');
+    actionResult = ok('');
+
+    await createCommand(['app.install', localFile, '--id', 'session-123']).runAsync();
+
+    const requests = actionRequests();
+    const uploadId = requests[0][1]?.uploadId;
+    expect(requests).toEqual([
+      [
+        'upload.append',
+        { uploadId, data: Buffer.from('app bytes').toString('base64'), first: true },
+      ],
+      ['app.install', { path: `/tmp/serve-sim-uploads/${uploadId}` }],
+      ['upload.remove', { uploadId }],
+    ]);
+  });
+
+  it('sends the upload ID to an action that asks for it', async () => {
+    const localFile = path.join(tmpDir, 'session.json');
+    await fs.writeFile(localFile, '{}');
+    actionResult = ok('');
+    served = {
+      ...catalog,
+      'app.file.upload': {
+        type: 'object',
+        properties: {
+          udid: { type: 'string' },
+          bundleId: { type: 'string' },
+          relativePath: { type: 'string' },
+          uploadId: { type: 'string' },
+        },
+        upload: 'uploadId',
+        uploadAs: 'id',
+      },
+    };
+
+    await createCommand([
+      'app.file.upload',
+      'com.example.app',
+      'Documents/session.json',
+      localFile,
+      '--id',
+      'session-123',
+    ]).runAsync();
+
+    const requests = actionRequests();
+    const uploadId = requests[0][1]?.uploadId;
+    expect(requests).toEqual([
+      ['upload.append', { uploadId, data: Buffer.from('{}').toString('base64'), first: true }],
+      [
+        'app.file.upload',
+        { bundleId: 'com.example.app', relativePath: 'Documents/session.json', uploadId },
+      ],
+      ['upload.remove', { uploadId }],
+    ]);
+  });
+
+  it('keeps an upload that the action goes on reading', async () => {
+    const localFile = path.join(tmpDir, 'feed.mp4');
+    await fs.writeFile(localFile, 'video bytes');
+    actionResult = ok('');
+
+    await createCommand(['camera.switch', 'file', localFile, '--id', 'session-123']).runAsync();
+
+    const requests = actionRequests();
+    expect(requests.map(([action]) => action)).toEqual(['upload.append', 'camera.switch']);
+    expect(requests[1][1]).toEqual({
+      source: 'file',
+      target: `/tmp/serve-sim-uploads/${requests[0][1]?.uploadId}`,
+    });
+  });
+
+  it('removes a kept upload when the action fails', async () => {
+    const localFile = path.join(tmpDir, 'feed.mp4');
+    await fs.writeFile(localFile, 'video bytes');
+    actionResult = { stdout: '', stderr: 'No such app.\n', exitCode: 1 };
+
+    await expect(
+      createCommand(['camera.switch', 'file', localFile, '--id', 'session-123']).runAsync()
+    ).rejects.toThrow('The simulator could not run camera.switch: No such app.');
+    expect(actionRequests().map(([action]) => action)).toEqual([
+      'upload.append',
+      'camera.switch',
+      'upload.remove',
+    ]);
+  });
+
+  it('passes a webcam name through without looking for a local file', async () => {
+    actionResult = ok('');
+
+    await createCommand([
+      'camera.switch',
+      'webcam',
+      'FaceTime HD Camera',
+      '--id',
+      'session-123',
+    ]).runAsync();
+
+    expect(actionRequests()).toEqual([
+      ['camera.switch', { source: 'webcam', target: 'FaceTime HD Camera' }],
+    ]);
+  });
+
+  it('refuses a relative file that does not exist on this computer', async () => {
+    await expect(
+      createCommand(['app.install', './MyAp.ipa', '--id', 'session-123']).runAsync()
+    ).rejects.toThrow('./MyAp.ipa does not exist on this computer.');
+    expect(actionRequests()).toEqual([]);
+  });
+
+  it('refuses --output for an action that returns no file before it runs', async () => {
+    await expect(
+      createCommand([
+        'hardwareKeyboard.set',
+        'off',
+        '--output',
+        './out',
+        '--id',
+        'session-123',
+      ]).runAsync()
+    ).rejects.toThrow('hardwareKeyboard.set does not return a file, so --output does not apply.');
+    expect(actionRequests()).toEqual([]);
+  });
+
+  it('passes a path that is not a local file through unchanged', async () => {
+    actionResult = ok('');
+
+    await createCommand([
+      'app.install',
+      '/Users/runner/MyApp.ipa',
+      '--id',
+      'session-123',
+    ]).runAsync();
+
+    expect(actionRequests()).toEqual([['app.install', { path: '/Users/runner/MyApp.ipa' }]]);
+  });
+
+  it('downloads the file an action returns', async () => {
+    const outputPath = path.join(tmpDir, 'shot.png');
+    actionResult = ok('/tmp/serve-sim-screenshots/serve-sim-screenshot-1.png\n');
+
+    await createCommand([
+      'screenshot.capture',
+      '--output',
+      outputPath,
+      '--id',
+      'session-123',
+    ]).runAsync();
+
+    expect(await fs.readFile(outputPath, 'utf8')).toBe('png bytes');
+    expect(jest.mocked(Log.log)).toHaveBeenCalledWith(`Saved ${outputPath}`);
+  });
+
+  it('refuses an action that the session does not list', async () => {
+    await expect(createCommand(['server.kill', '--id', 'session-123']).runAsync()).rejects.toThrow(
+      'Unknown simulator action "server.kill". Run `eas simulator:control` to see the actions.'
+    );
+    expect(actionRequests()).toEqual([]);
+    expect(close).toHaveBeenCalled();
+  });
+
+  it('closes an established connection when catalog setup fails', async () => {
+    requestAsync.mockImplementationOnce(async () => ok('not a catalog'));
+    await expect(createCommand(['--list', '--id', 'session-123']).runAsync()).rejects.toThrow(
+      'did not return its list of actions'
+    );
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it('lists the actions as JSON when no action is provided', async () => {
+    await createCommand(['--id', 'session-123', '--json']).runAsync();
+
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalledWith(catalog);
+    expect(actionRequests()).toEqual([]);
+  });
+
+  it('refuses a session that is not running', async () => {
+    mockByIdAsync.mockResolvedValue(
+      makeDeviceRunSession({ status: DeviceRunSessionStatus.Stopped })
+    );
+
+    await expect(
+      createCommand(['memoryWarning', '--id', 'session-123']).runAsync()
+    ).rejects.toThrow('Simulator session session-123 is stopped');
+    expect(mockConnectHostActionsAsync).not.toHaveBeenCalled();
+  });
+
+  it('refuses an Android session', async () => {
+    mockByIdAsync.mockResolvedValue(makeDeviceRunSession({ platform: AppPlatform.Android }));
+
+    await expect(
+      createCommand(['memoryWarning', '--id', 'session-123']).runAsync()
+    ).rejects.toThrow('available only for iOS sessions');
+    expect(mockConnectHostActionsAsync).not.toHaveBeenCalled();
+  });
+
+  it('refuses a session without a preview server API', async () => {
+    mockByIdAsync.mockResolvedValue(
+      makeDeviceRunSession({
+        remoteConfig: {
+          __typename: 'ServeSimRunSessionRemoteConfig',
+          previewUrl: 'https://sim.example.test',
+          previewToken: 'preview-token',
+        },
+      })
+    );
+
+    await expect(
+      createCommand(['memoryWarning', '--id', 'session-123']).runAsync()
+    ).rejects.toThrow('does not expose a preview server');
+  });
+
+  it('reports the simulator error when the action fails', async () => {
+    actionResult = {
+      stdout: '',
+      stderr: 'Simulator could not change the hinge angle.\n',
+      exitCode: 1,
+    };
+
+    await expect(
+      createCommand(['hinge.set', 'half', '--id', 'session-123']).runAsync()
+    ).rejects.toThrow(
+      'The simulator could not run hinge.set: Simulator could not change the hinge angle.'
+    );
+  });
+});

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

@@ -0,0 +1,322 @@
+import { Args, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import * as fs from 'fs-extra';
+import path from 'path';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import {
+  EasNonInteractiveAndJsonFlags,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../commandUtils/flags';
+import { AppPlatform, DeviceRunSessionStatus } from '../../graphql/generated';
+import { DeviceRunSessionQuery } from '../../graphql/queries/DeviceRunSessionQuery';
+import Log from '../../log';
+import { ora } from '../../ora';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+} from '../../simulator/env';
+import {
+  HostActionCatalog,
+  HostActionCatalogEntry,
+  HostActionConnection,
+  assertHostActionOutputAsync,
+  buildHostActionParams,
+  connectHostActionsAsync,
+  fetchHostActionCatalogAsync,
+  formatHostActionUsage,
+  saveHostActionOutputAsync,
+  uploadFileAsync,
+} from '../../simulator/hostActions';
+import { PreviewApiAccess, getPreviewApiAccess } from '../../simulator/utils';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
+
+export default class SimulatorControl extends EasCommand {
+  static override aliases = ['sim:control'];
+  static override description =
+    '[EXPERIMENTAL] run a serve-sim action on a remote iOS simulator session on EAS. Run without an action to list the actions the session supports. To save a screenshot locally, run `eas simulator:control screenshot.capture --output ./screenshot.png`.';
+  static override strict = false;
+
+  static override examples = [
+    '$ eas simulator:control',
+    '$ eas simulator:control --id <session-id>',
+    '$ eas simulator:control screenshot.capture --help',
+    '$ eas simulator:control clipboard.write -- --some-text',
+    '$ eas simulator:control hardwareKeyboard.set off',
+    '$ eas simulator:control permissions.set grant camera com.example.app',
+    '$ eas simulator:control app.install ./MyApp.ipa',
+    '$ eas simulator:control screenshot.capture --output ./screenshot.png',
+    '$ eas simulator:control screenshot.capture --output ./screenshot.png --id <session-id>',
+  ];
+
+  static override args = {
+    action: Args.string({
+      description:
+        'Action to run, followed by its values in order or as name=value. Omit to list the actions. Put -- before values that start with --.',
+    }),
+  };
+
+  static override flags = {
+    help: Flags.boolean({
+      char: 'h',
+      description: 'Show command help, or usage for the selected action from the session.',
+    }),
+    id: Flags.string({
+      description: `Simulator session ID. Defaults to ${SIMULATOR_DOTENV_FILE_NAME}.`,
+    }),
+    list: Flags.boolean({
+      description: 'List the actions the session supports.',
+    }),
+    output: Flags.string({
+      description:
+        'Local path to save a returned file. For screenshots, --output ./screenshot.png sets the local filename; omit it to save with a generated filename in the current directory.',
+    }),
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.LoggedIn,
+    ...this.ContextOptions.ProjectDir,
+  };
+
+  async runAsync(): Promise<void> {
+    const { args, argv, flags } = await this.parse(SimulatorControl);
+    const { json: jsonFlag, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+
+    if (jsonFlag) {
+      enableJsonOutput();
+    }
+    if (flags.id === '') {
+      throw new Error('--id needs a simulator session ID.');
+    }
+    const action = flags.list && !flags.help ? undefined : args.action;
+
+    const {
+      projectDir,
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(SimulatorControl, {
+      nonInteractive,
+    });
+
+    await loadSimulatorEnvAsync(projectDir);
+    const sessionId = flags.id ?? 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 spinner = ora(`Connecting to simulator session ${sessionId}`).start();
+    let connection: HostActionConnection | undefined;
+    try {
+      let catalog: HostActionCatalog;
+      try {
+        const session = await DeviceRunSessionQuery.byIdAsync(graphqlClient, sessionId);
+        connection = await connectHostActionsAsync(assertControllableSession(session));
+        catalog = await fetchHostActionCatalogAsync(connection);
+        spinner.succeed(`Connected to simulator session ${sessionId}`);
+      } catch (err) {
+        spinner.fail(`Failed to connect to simulator session ${sessionId}`);
+        throw err;
+      }
+      if (!action) {
+        this.printCatalog(catalog, jsonFlag);
+        return;
+      }
+      const entry = Object.hasOwn(catalog, action) ? catalog[action] : undefined;
+      if (!entry) {
+        throw new Error(
+          `Unknown simulator action "${action}". Run \`eas simulator:control\` to see the actions.`
+        );
+      }
+      if (flags.help) {
+        this.printActionHelp(action, entry, jsonFlag);
+        return;
+      }
+      await this.runActionAsync(connection, entry, {
+        sessionId,
+        action,
+        values: argv.slice(1).map(String),
+        outputPath: flags.output,
+        jsonFlag,
+      });
+    } finally {
+      connection?.close();
+    }
+  }
+
+  private printCatalog(catalog: HostActionCatalog, jsonFlag: boolean): void {
+    if (jsonFlag) {
+      printJsonOnlyOutput(catalog);
+      return;
+    }
+    const names = Object.keys(catalog).sort();
+    const width = Math.max(0, ...names.map(name => name.length)) + 3;
+    const columns = Math.max(1, Math.min(3, Math.floor((process.stdout.columns || 80) / width)));
+    const rows = Math.ceil(names.length / columns);
+    for (let row = 0; row < rows; row++) {
+      const cells = Array.from({ length: columns }, (_, column) =>
+        (names[row + column * rows] ?? '').padEnd(width)
+      );
+      Log.log(cells.join('').trimEnd());
+    }
+    Log.newLine();
+    Log.log('For action usage: eas simulator:control <action> --help');
+  }
+
+  private printActionHelp(action: string, entry: HostActionCatalogEntry, jsonFlag: boolean): void {
+    if (jsonFlag) {
+      printJsonOnlyOutput({ ...entry, action });
+      return;
+    }
+    Log.newLine();
+    Log.log(`  ${chalk.bold(action)}`);
+    if (entry.description) {
+      Log.log(`  ${entry.description}`);
+    }
+    Log.newLine();
+    Log.log(`  ${chalk.bold('USAGE')}`);
+    Log.log(`    eas simulator:control ${formatHostActionUsage(action, entry)}`);
+    const outputFlag = entry.output === 'base64' ? '--output <path>' : '[--output <path>]';
+    Log.log(`      ${entry.output ? `${outputFlag} ` : ''}[--id <session-id>] [--json]`);
+    Log.newLine();
+    Log.log(`  ${chalk.bold('OPTIONS')}`);
+    Log.log(`    --id <session-id>  Defaults to ${SIMULATOR_DOTENV_FILE_NAME}.`);
+    Log.log('    --json             Print the action schema as JSON. Implies --non-interactive.');
+    if (entry.output) {
+      Log.log(
+        entry.output === 'base64'
+          ? '    --output <path>    Required local filename for the returned file.'
+          : '    --output <path>    Local filename or existing directory.'
+      );
+      if (entry.output === 'path') {
+        Log.log('                       Omit to save with the generated filename.');
+      }
+      Log.newLine();
+      Log.log(
+        '  Action arguments refer to the simulator host. Use --output for the local filename.'
+      );
+    }
+    Log.newLine();
+  }
+
+  private async runActionAsync(
+    connection: HostActionConnection,
+    entry: HostActionCatalogEntry,
+    {
+      sessionId,
+      action,
+      values,
+      outputPath,
+      jsonFlag,
+    }: {
+      sessionId: string;
+      action: string;
+      values: string[];
+      outputPath: string | undefined;
+      jsonFlag: boolean;
+    }
+  ): Promise<void> {
+    const params = buildHostActionParams(action, entry, values);
+    await assertHostActionOutputAsync(action, entry, outputPath);
+    const localFile = await findLocalUploadAsync(entry, params);
+
+    const spinner = ora(`Running ${action} on simulator session ${sessionId}`).start();
+    let uploadId: string | undefined;
+    let succeeded = false;
+    let output: string;
+    let savedFile: string | null;
+    try {
+      if (localFile) {
+        spinner.text = `Uploading ${localFile.path}`;
+        const upload = await uploadFileAsync(connection, localFile.path);
+        uploadId = upload.uploadId;
+        params[localFile.param] = entry.uploadAs === 'id' ? upload.uploadId : upload.path;
+        spinner.text = `Running ${action} on simulator session ${sessionId}`;
+      }
+      const result = await connection.requestAsync(action, params);
+      if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout).trim() || `exit code ${result.exitCode}`;
+        throw new Error(`The simulator could not run ${action}: ${detail}`);
+      }
+      succeeded = true;
+      savedFile = await saveHostActionOutputAsync(connection, entry, result.stdout, outputPath);
+      output = savedFile ? '' : result.stdout.trim();
+      spinner.succeed(`Ran ${action} on simulator session ${sessionId}`);
+    } catch (err) {
+      spinner.fail(`Failed to run ${action} on simulator session ${sessionId}`);
+      throw err;
+    } finally {
+      if (uploadId && (!entry.keepUpload || !succeeded)) {
+        await connection.requestAsync('upload.remove', { uploadId }).catch(() => {});
+      }
+    }
+
+    if (jsonFlag) {
+      printJsonOnlyOutput({
+        id: sessionId,
+        action,
+        output: parseJsonOutput(output),
+        file: savedFile,
+      });
+      return;
+    }
+    if (savedFile) {
+      Log.log(`Saved ${savedFile}`);
+    } else if (output) {
+      Log.log(output);
+    }
+  }
+}
+
+async function findLocalUploadAsync(
+  { upload: param, uploadWhen = {} }: HostActionCatalogEntry,
+  params: Record<string, unknown>
+): Promise<{ param: string; path: string } | null> {
+  const value = param ? params[param] : undefined;
+  const applies = Object.entries(uploadWhen).every(([name, expected]) => params[name] === expected);
+  if (!param || typeof value !== 'string' || !applies) {
+    return null;
+  }
+  const stat = await fs.stat(value).catch(() => null);
+  if (stat?.isDirectory()) {
+    throw new Error(`${value} is a folder. Pass the path of a file.`);
+  }
+  if (!stat && !path.isAbsolute(value)) {
+    throw new Error(
+      `${value} does not exist on this computer. Pass the path of a local file, or an absolute path on the simulator host.`
+    );
+  }
+  return stat ? { param, path: value } : null;
+}
+
+function assertControllableSession(
+  session: Awaited<ReturnType<typeof DeviceRunSessionQuery.byIdAsync>>
+): PreviewApiAccess {
+  if (session.status !== DeviceRunSessionStatus.InProgress) {
+    throw new Error(
+      `Simulator session ${session.id} is ${session.status.toLowerCase()}. Simulator actions need a running session. Start one with \`eas simulator:start\`.`
+    );
+  }
+  if (session.platform !== AppPlatform.Ios) {
+    throw new Error(
+      `Simulator session ${session.id} runs on ${session.platform.toLowerCase()}. Simulator actions are available only for iOS sessions.`
+    );
+  }
+  const access = session.remoteConfig ? getPreviewApiAccess(session.remoteConfig) : null;
+  if (!access) {
+    throw new Error(
+      `Simulator session ${session.id} does not expose a preview server with a token. Simulator actions use that server. Start a new session with \`eas simulator:start\`.`
+    );
+  }
+  return access;
+}
+
+function parseJsonOutput(output: string): unknown {
+  try {
+    return JSON.parse(output);
+  } catch {
+    return output;
+  }
+}

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

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

@@ -0,0 +1,20 @@
+import { ExperimentationClient } from './ExperimentationClient';
+
+/**
+ * Defers building the experimentation client, and the config fetch behind it, until a command
+ * first needs a variant.
+ */
+export class LazyExperimentationClient {
+  private pending: Promise<ExperimentationClient> | null = null;
+
+  constructor(private readonly loadAsync: () => Promise<ExperimentationClient>) {}
+
+  public static fromClient(client: ExperimentationClient): LazyExperimentationClient {
+    return new LazyExperimentationClient(async () => client);
+  }
+
+  public async getClientAsync(): Promise<ExperimentationClient> {
+    this.pending ??= this.loadAsync();
+    return await this.pending;
+  }
+}

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

@@ -0,0 +1,124 @@
+import RudderAnalytics from '@expo/rudder-sdk-node';
+
+import UserSettings from '../../user/UserSettings';
+import { createAnalyticsAsync } from '../../analytics/AnalyticsManager';
+import { AnalyticsExposureLogger } from '../AnalyticsExposureLogger';
+import { createMockAnalytics } from './fixtures';
+
+const mockIdentify = jest.fn();
+const mockTrack = jest.fn();
+const mockFlush = jest.fn();
+
+jest.mock('@expo/rudder-sdk-node', () =>
+  jest.fn().mockImplementation(() => ({
+    identify: mockIdentify,
+    track: mockTrack,
+    flush: mockFlush,
+  }))
+);
+jest.mock('../../user/UserSettings', () => ({
+  __esModule: true,
+  default: {
+    deleteKeyAsync: jest.fn(),
+    getAsync: jest.fn(),
+    setAsync: jest.fn(),
+  },
+}));
+jest.mock('../../analytics/agent', () => ({ getAgentTelemetryContext: jest.fn() }));
+jest.mock('../../analytics/sandbox', () => ({ getSandboxTelemetryContext: jest.fn() }));
+
+const originalDisableEasAnalytics = process.env.DISABLE_EAS_ANALYTICS;
+const originalHttpsProxy = process.env.https_proxy;
+
+afterAll(() => {
+  if (originalDisableEasAnalytics === undefined) {
+    delete process.env.DISABLE_EAS_ANALYTICS;
+  } else {
+    process.env.DISABLE_EAS_ANALYTICS = originalDisableEasAnalytics;
+  }
+  if (originalHttpsProxy === undefined) {
+    delete process.env.https_proxy;
+  } else {
+    process.env.https_proxy = originalHttpsProxy;
+  }
+});
+
+const exposure = {
+  name: 'cli-test',
+  time: 1700000000,
+  salt: 'cli-full.cli-test.cli-test',
+};
+
+describe(AnalyticsExposureLogger, () => {
+  it('logs Experiment Viewed with experimentName, variationName, and unit', () => {
+    const analytics = createMockAnalytics();
+    new AnalyticsExposureLogger(analytics).logExposure({
+      ...exposure,
+      unit: ['account-1'],
+      params: { variant: 'treatment' },
+    });
+    expect(analytics.logEvent).toHaveBeenCalledWith('Experiment Viewed', {
+      experimentName: 'cli-test',
+      variationName: 'treatment',
+      unit: 'account-1',
+    });
+  });
+
+  it('never sends an undefined variationName', () => {
+    const analytics = createMockAnalytics();
+    new AnalyticsExposureLogger(analytics).logExposure({
+      ...exposure,
+      unit: ['account-1'],
+      params: { enabled: true, count: 2 },
+    });
+    expect(analytics.logEvent).toHaveBeenCalledWith(
+      'Experiment Viewed',
+      expect.objectContaining({ variationName: JSON.stringify({ enabled: true, count: 2 }) })
+    );
+  });
+
+  it('sends numeric units and variants as strings', () => {
+    const analytics = createMockAnalytics();
+    new AnalyticsExposureLogger(analytics).logExposure({
+      ...exposure,
+      unit: [42],
+      params: { variant: 3 },
+    });
+    expect(analytics.logEvent).toHaveBeenCalledWith(
+      'Experiment Viewed',
+      expect.objectContaining({ unit: '42', variationName: '3' })
+    );
+  });
+
+  it('reaches RudderStack with the CLI source and anonymous ID', async () => {
+    jest.mocked(RudderAnalytics).mockClear();
+    mockTrack.mockClear();
+    jest
+      .mocked(UserSettings.getAsync)
+      .mockImplementation(async (key, defaultValue) =>
+        key === 'analyticsDeviceId' ? 'persistent-device-id' : defaultValue
+      );
+    delete process.env.DISABLE_EAS_ANALYTICS;
+    delete process.env.https_proxy;
+
+    const analytics = await createAnalyticsAsync();
+    new AnalyticsExposureLogger(analytics).logExposure({
+      ...exposure,
+      unit: ['account-1'],
+      params: { variant: 'treatment' },
+    });
+
+    expect(mockTrack).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'Experiment Viewed',
+        anonymousId: 'persistent-device-id',
+        properties: expect.objectContaining({
+          experimentName: 'cli-test',
+          variationName: 'treatment',
+          unit: 'account-1',
+          source: 'eas cli',
+        }),
+      })
+    );
+  });
+});

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

@@ -0,0 +1,74 @@
+import type { Namespace } from '@expo/experimentation';
+
+import Log from '../../log';
+import {
+  FALLBACK_NAMESPACE,
+  OverrideFallbackNamespace,
+  SafeNamespace,
+  coerceOverrideValue,
+} from '../ExperimentNamespace';
+import { ExperimentOverrides, parseExperimentOverrides } from '../ExperimentOverrides';
+
+jest.mock('../../log');
+
+describe(coerceOverrideValue, () => {
+  it('coerces booleans only from "true" and "false"', () => {
+    expect(coerceOverrideValue('false', true)).toBe(false);
+    expect(coerceOverrideValue('TRUE', false)).toBe(true);
+    expect(coerceOverrideValue('1', false)).toBe(false);
+    expect(coerceOverrideValue('yes', true)).toBe(true);
+  });
+
+  it('coerces finite numbers and falls back otherwise', () => {
+    expect(coerceOverrideValue('2', 1)).toBe(2);
+    expect(coerceOverrideValue('2.5', 1)).toBe(2.5);
+    expect(coerceOverrideValue('x', 1)).toBe(1);
+    expect(coerceOverrideValue('Infinity', 1)).toBe(1);
+  });
+
+  it('passes strings through and returns the default for empty input', () => {
+    expect(coerceOverrideValue('b', 'a')).toBe('b');
+    expect(coerceOverrideValue('', 'a')).toBe('a');
+    expect(coerceOverrideValue('   ', 'a')).toBe('a');
+    expect(coerceOverrideValue(undefined, 'a')).toBe('a');
+  });
+});
+
+describe('FALLBACK_NAMESPACE', () => {
+  it('returns the default for every param', () => {
+    expect(FALLBACK_NAMESPACE.getParam('variant', 'control')).toBe('control');
+    expect(FALLBACK_NAMESPACE.isOverridden).toBe(false);
+  });
+});
+
+describe(OverrideFallbackNamespace, () => {
+  const overrides = new ExperimentOverrides(parseExperimentOverrides('ns:variant=treatment'));
+  const namespace = new OverrideFallbackNamespace('ns', overrides);
+
+  it('returns the coerced override for overridden params', () => {
+    expect(namespace.getParam('variant', 'control')).toBe('treatment');
+    expect(namespace.isOverridden).toBe(true);
+  });
+
+  it('returns the default for params without an override', () => {
+    expect(namespace.getParam('enabled', false)).toBe(false);
+  });
+});
+
+describe(SafeNamespace, () => {
+  it('delegates to the wrapped namespace', () => {
+    const inner = { getParam: jest.fn().mockReturnValue('treatment') } as unknown as Namespace;
+    expect(new SafeNamespace(inner, 'ns').getParam('variant', 'control')).toBe('treatment');
+    expect(inner.getParam).toHaveBeenCalledWith('variant', 'control');
+  });
+
+  it('returns the default and logs at debug level when the wrapped namespace throws', () => {
+    const inner = {
+      getParam: jest.fn(() => {
+        throw new Error('bad operator');
+      }),
+    } as unknown as Namespace;
+    expect(new SafeNamespace(inner, 'ns').getParam('variant', 'control')).toBe('control');
+    expect(Log.debug).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,72 @@
+import { ExperimentOverrides, parseExperimentOverrides } from '../ExperimentOverrides';
+
+jest.mock('../../env', () => ({
+  __esModule: true,
+  default: { experimentOverride: 'from-env:variant=treatment' },
+}));
+
+describe(parseExperimentOverrides, () => {
+  it('parses a single override', () => {
+    const map = parseExperimentOverrides('pricing:variant=treatment');
+    expect(map.get('pricing')?.get('variant')).toBe('treatment');
+  });
+
+  it('parses multiple overrides and multiple params per namespace', () => {
+    const map = parseExperimentOverrides('a:variant=x,b:limit=3,a:enabled=true');
+    expect(map.get('a')?.get('variant')).toBe('x');
+    expect(map.get('a')?.get('enabled')).toBe('true');
+    expect(map.get('b')?.get('limit')).toBe('3');
+  });
+
+  it('returns an empty map for undefined or empty input', () => {
+    expect(parseExperimentOverrides(undefined).size).toBe(0);
+    expect(parseExperimentOverrides('').size).toBe(0);
+    expect(parseExperimentOverrides('  ,  ').size).toBe(0);
+  });
+
+  it('skips entries without "=" or ":" and entries with an empty namespace or param', () => {
+    const map = parseExperimentOverrides(
+      'bogus,ns:x,variant=1,:variant=1,ns:=1,ok:variant=control'
+    );
+    expect([...map.keys()]).toEqual(['ok']);
+  });
+
+  it('keeps "=" and ":" inside values', () => {
+    const map = parseExperimentOverrides('ns:url=https://expo.dev/a=b');
+    expect(map.get('ns')?.get('url')).toBe('https://expo.dev/a=b');
+  });
+
+  it('trims whitespace and tolerates a trailing comma', () => {
+    const map = parseExperimentOverrides(' ns : variant = treatment , ');
+    expect(map.get('ns')?.get('variant')).toBe('treatment');
+    expect(map.size).toBe(1);
+  });
+
+  it('lets later duplicates win', () => {
+    const map = parseExperimentOverrides('ns:variant=a,ns:variant=b');
+    expect(map.get('ns')?.get('variant')).toBe('b');
+  });
+});
+
+describe(ExperimentOverrides, () => {
+  it('exposes namespace and param lookups', () => {
+    const overrides = new ExperimentOverrides(parseExperimentOverrides('ns:variant=treatment'));
+    expect(overrides.hasNamespaceOverride('ns')).toBe(true);
+    expect(overrides.hasNamespaceOverride('other')).toBe(false);
+    expect(overrides.hasOverride('ns', 'variant')).toBe(true);
+    expect(overrides.hasOverride('ns', 'enabled')).toBe(false);
+    expect(overrides.hasOverride('other', 'variant')).toBe(false);
+    expect(overrides.getOverride('ns', 'variant')).toBe('treatment');
+    expect(overrides.getOverride('ns', 'enabled')).toBeUndefined();
+    expect(overrides.getOverride('other', 'variant')).toBeUndefined();
+  });
+
+  it('reads EAS_EXPERIMENT_OVERRIDE through env', () => {
+    const overrides = ExperimentOverrides.fromEnv();
+    expect(overrides.getOverride('from-env', 'variant')).toBe('treatment');
+  });
+
+  it('empty() has no overrides', () => {
+    expect(ExperimentOverrides.empty().hasNamespaceOverride('from-env')).toBe(false);
+  });
+});

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

@@ -0,0 +1,376 @@
+import type { ExperimentationDefinition } from '@expo/experimentation';
+
+import Log from '../../log';
+import {
+  EMPTY_EXPERIMENTATION_DEFINITION,
+  ExperimentationClient,
+  ExperimentationConfigs,
+  ExperimentationUnits,
+  createLoggerConfig,
+} from '../ExperimentationClient';
+import { ExperimentOverrides, parseExperimentOverrides } from '../ExperimentOverrides';
+import { TEST_DEFINITION, createMockAnalytics, findUnitsByValue } from './fixtures';
+import { FALLBACK_NAMESPACE } from '../ExperimentNamespace';
+
+jest.mock('../../log');
+jest.mock('../../env', () => ({
+  __esModule: true,
+  default: { experimentOverride: 'cli-full:variant=from-env' },
+}));
+
+function createClient({
+  configs = {},
+  units = {},
+  overrides = ExperimentOverrides.empty(),
+  analytics = createMockAnalytics(),
+}: {
+  configs?: Partial<ExperimentationConfigs>;
+  units?: Partial<ExperimentationUnits>;
+  overrides?: ExperimentOverrides;
+  analytics?: ReturnType<typeof createMockAnalytics>;
+} = {}): { client: ExperimentationClient; analytics: ReturnType<typeof createMockAnalytics> } {
+  const client = new ExperimentationClient(
+    {
+      user: configs.user ?? EMPTY_EXPERIMENTATION_DEFINITION,
+      account: configs.account ?? EMPTY_EXPERIMENTATION_DEFINITION,
+      device: configs.device ?? EMPTY_EXPERIMENTATION_DEFINITION,
+    },
+    { user: units.user ?? null, device: units.device ?? null },
+    overrides,
+    createLoggerConfig(analytics)
+  );
+  return { client, analytics };
+}
+
+function userClientForUnit(unit: string): ExperimentationClient {
+  return createClient({ configs: { user: TEST_DEFINITION }, units: { user: unit } }).client;
+}
+
+const unitsByVariant = findUnitsByValue(
+  unit => userClientForUnit(unit).getUserNamespace('cli-full'),
+  'variant',
+  'control',
+  ['control', 'treatment']
+);
+const controlUnit = unitsByVariant.get('control')!;
+const treatmentUnit = unitsByVariant.get('treatment')!;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe(findUnitsByValue, () => {
+  it('throws when no unit produces an expected value', () => {
+    expect(() => findUnitsByValue(() => FALLBACK_NAMESPACE, 'variant', 'x', ['never'])).toThrow(
+      'Could not find units for all of: never'
+    );
+  });
+});
+
+describe(ExperimentationClient, () => {
+  describe('assignment', () => {
+    it('gives the same unit the same variant across clients', () => {
+      const first = userClientForUnit(treatmentUnit).getUserNamespace('cli-full');
+      const second = userClientForUnit(treatmentUnit).getUserNamespace('cli-full');
+      expect(first.getParam('variant', 'control')).toBe('treatment');
+      expect(second.getParam('variant', 'control')).toBe('treatment');
+      expect(
+        userClientForUnit(controlUnit).getUserNamespace('cli-full').getParam('variant', 'x')
+      ).toBe('control');
+    });
+
+    it('returns the default and logs at debug level for an unknown namespace', () => {
+      const { client, analytics } = createClient({
+        configs: { user: TEST_DEFINITION },
+        units: { user: treatmentUnit },
+      });
+      expect(client.getUserNamespace('missing').getParam('variant', 'control')).toBe('control');
+      expect(Log.debug).toHaveBeenCalledWith(expect.stringContaining('"missing"'));
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+    });
+
+    it('returns the default and logs no exposure when the scope has no unit', () => {
+      const { client, analytics } = createClient({ configs: { user: TEST_DEFINITION } });
+      expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+      expect(Log.debug).not.toHaveBeenCalled();
+    });
+
+    it('treats an empty string unit like a missing unit', () => {
+      const { client, analytics } = createClient({ configs: { account: TEST_DEFINITION } });
+      expect(
+        client.getAccountNamespace('cli-full', { accountId: '' }).getParam('variant', 'control')
+      ).toBe('control');
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+    });
+
+    it('buckets account experiments on the account ID the command passes', () => {
+      const { client, analytics } = createClient({ configs: { account: TEST_DEFINITION } });
+      expect(
+        client.getAccountNamespace('cli-full', { accountId: controlUnit }).getParam('variant', 'x')
+      ).toBe('control');
+      expect(
+        client
+          .getAccountNamespace('cli-full', { accountId: treatmentUnit })
+          .getParam('variant', 'x')
+      ).toBe('treatment');
+      expect(analytics.logEvent).toHaveBeenCalledTimes(2);
+    });
+
+    it('resolves the same namespace name independently per scope', () => {
+      const scoped = (choice: string): ExperimentationDefinition => ({
+        experiments: [
+          {
+            experimentName: 'shared',
+            paramDefinitions: { variant: { type: 'uniform_choice', choices: [choice] } },
+            exposureLoggerType: 'no-op',
+          },
+        ],
+        namespaces: [
+          {
+            name: 'shared',
+            numSegments: 10,
+            segmentExperimentSetupDefinitions: [
+              { method: 'ADD', name: 'all', experimentName: 'shared', numSegments: 10 },
+            ],
+          },
+        ],
+      });
+      const { client } = createClient({
+        configs: {
+          user: scoped('from-user'),
+          account: scoped('from-account'),
+          device: scoped('from-device'),
+        },
+        units: { user: 'u', device: 'd' },
+      });
+      expect(client.getUserNamespace('shared').getParam('variant', 'x')).toBe('from-user');
+      expect(
+        client.getAccountNamespace('shared', { accountId: 'a' }).getParam('variant', 'x')
+      ).toBe('from-account');
+      expect(client.getDeviceNamespace('shared').getParam('variant', 'x')).toBe('from-device');
+    });
+
+    it('returns the default and logs no exposure for a unit outside the allocated segments', () => {
+      const unallocated = findUnitsByValue(
+        unit => userClientForUnit(unit).getUserNamespace('cli-half'),
+        'variant',
+        'not-allocated',
+        ['not-allocated']
+      ).get('not-allocated')!;
+      const { client, analytics } = createClient({
+        configs: { user: TEST_DEFINITION },
+        units: { user: unallocated },
+      });
+      expect(client.getUserNamespace('cli-half').getParam('variant', 'control')).toBe('control');
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('exposure logging', () => {
+    it('logs one exposure per namespace per client', () => {
+      const { client, analytics } = createClient({
+        configs: { user: TEST_DEFINITION },
+        units: { user: treatmentUnit },
+      });
+      const namespace = client.getUserNamespace('cli-full');
+      namespace.getParam('variant', 'control');
+      namespace.getParam('enabled', false);
+      client.getUserNamespace('cli-full').getParam('variant', 'control');
+
+      expect(analytics.logEvent).toHaveBeenCalledTimes(1);
+      expect(analytics.logEvent).toHaveBeenCalledWith('Experiment Viewed', {
+        experimentName: 'cli-test',
+        variationName: 'treatment',
+        unit: treatmentUnit,
+      });
+    });
+
+    it('logs again for a second client with the same unit, so clients must be cached per command', () => {
+      const analytics = createMockAnalytics();
+      createClient({
+        configs: { user: TEST_DEFINITION },
+        units: { user: treatmentUnit },
+        analytics,
+      })
+        .client.getUserNamespace('cli-full')
+        .getParam('variant', 'control');
+      createClient({
+        configs: { user: TEST_DEFINITION },
+        units: { user: treatmentUnit },
+        analytics,
+      })
+        .client.getUserNamespace('cli-full')
+        .getParam('variant', 'control');
+      expect(analytics.logEvent).toHaveBeenCalledTimes(2);
+    });
+
+    it('logs nothing for experiments that use the no-op logger', () => {
+      const { client, analytics } = createClient({
+        configs: { user: TEST_DEFINITION },
+        units: { user: 'unit-1' },
+      });
+      expect(['a', 'b']).toContain(
+        client.getUserNamespace('cli-quiet-ns').getParam('variant', 'x')
+      );
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+    });
+
+    it('falls back to the no-op logger for an unknown exposureLoggerType', () => {
+      const definition: ExperimentationDefinition = {
+        experiments: [
+          {
+            experimentName: 'odd',
+            paramDefinitions: { variant: { type: 'uniform_choice', choices: ['only'] } },
+            exposureLoggerType: 'something-else',
+          },
+        ],
+        namespaces: [
+          {
+            name: 'odd',
+            numSegments: 10,
+            segmentExperimentSetupDefinitions: [
+              { method: 'ADD', name: 'all', experimentName: 'odd', numSegments: 10 },
+            ],
+          },
+        ],
+      };
+      const { client, analytics } = createClient({
+        configs: { user: definition },
+        units: { user: 'u' },
+      });
+      expect(client.getUserNamespace('odd').getParam('variant', 'x')).toBe('only');
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('overrides', () => {
+    it('returns the override instead of the assigned variant and logs no exposure', () => {
+      const { client, analytics } = createClient({
+        configs: { user: TEST_DEFINITION },
+        units: { user: controlUnit },
+        overrides: new ExperimentOverrides(parseExperimentOverrides('cli-full:variant=treatment')),
+      });
+      const namespace = client.getUserNamespace('cli-full');
+      expect(namespace.isOverridden).toBe(true);
+      expect(namespace.getParam('variant', 'control')).toBe('treatment');
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+    });
+
+    it('returns the default for other params of an overridden namespace without logging an exposure', () => {
+      const { client, analytics } = createClient({
+        configs: { user: TEST_DEFINITION },
+        units: { user: controlUnit },
+        overrides: new ExperimentOverrides(parseExperimentOverrides('cli-full:variant=treatment')),
+      });
+      expect(client.getUserNamespace('cli-full').getParam('enabled', false)).toBe(false);
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+    });
+
+    it('applies overrides to namespaces that are not in the server config', () => {
+      const { client } = createClient({
+        overrides: new ExperimentOverrides(
+          parseExperimentOverrides('not-deployed:variant=treatment')
+        ),
+      });
+      expect(client.getUserNamespace('not-deployed').getParam('variant', 'control')).toBe(
+        'treatment'
+      );
+    });
+
+    it('applies the same override in every scope', () => {
+      const { client } = createClient({
+        overrides: new ExperimentOverrides(parseExperimentOverrides('ns:enabled=true')),
+      });
+      expect(client.getUserNamespace('ns').getParam('enabled', false)).toBe(true);
+      expect(client.getAccountNamespace('ns', { accountId: 'a' }).getParam('enabled', false)).toBe(
+        true
+      );
+      expect(client.getDeviceNamespace('ns').getParam('enabled', false)).toBe(true);
+    });
+  });
+
+  describe('invalid server config', () => {
+    it('returns the default without throwing when a param uses an unknown operator', () => {
+      const definition = {
+        experiments: [
+          {
+            experimentName: 'broken',
+            paramDefinitions: { variant: { type: 'not-an-operator' } },
+            exposureLoggerType: 'rudderstack',
+          },
+        ],
+        namespaces: [
+          {
+            name: 'broken',
+            numSegments: 10,
+            segmentExperimentSetupDefinitions: [
+              { method: 'ADD', name: 'all', experimentName: 'broken', numSegments: 10 },
+            ],
+          },
+        ],
+      } as unknown as ExperimentationDefinition;
+      const { client } = createClient({ configs: { user: definition }, units: { user: 'u' } });
+      expect(client.getUserNamespace('broken').getParam('variant', 'control')).toBe('control');
+      expect(Log.debug).toHaveBeenCalled();
+    });
+
+    const overAllocated: ExperimentationDefinition = {
+      experiments: TEST_DEFINITION.experiments,
+      namespaces: [
+        {
+          name: 'too-many',
+          numSegments: 10,
+          segmentExperimentSetupDefinitions: [
+            { method: 'ADD', name: 'all', experimentName: 'cli-test', numSegments: 20 },
+          ],
+        },
+      ],
+    };
+
+    it('throws during construction when a namespace over-allocates segments', () => {
+      expect(() =>
+        createClient({ configs: { user: overAllocated }, units: { user: 'u' } })
+      ).toThrow(/requested 20 segments/);
+    });
+
+    it('returns the default when a namespace fails to build for an account ID', () => {
+      // Account namespaces have no default unit, so the failure surfaces on lookup, not construction.
+      const { client, analytics } = createClient({ configs: { account: overAllocated } });
+      expect(
+        client.getAccountNamespace('too-many', { accountId: 'a' }).getParam('variant', 'control')
+      ).toBe('control');
+      expect(Log.debug).toHaveBeenCalledWith(
+        expect.stringContaining('Failed to build namespace'),
+        expect.anything()
+      );
+      expect(analytics.logEvent).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('createDisabled', () => {
+    it('returns defaults for every scope and logs no exposure', () => {
+      const client = ExperimentationClient.createDisabled(ExperimentOverrides.empty());
+      expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+      expect(client.getDeviceNamespace('cli-full').getParam('variant', 'control')).toBe('control');
+      expect(Log.debug).not.toHaveBeenCalled();
+      // The account scope always has a unit, so the empty config reports the namespace as missing.
+      expect(
+        client.getAccountNamespace('cli-full', { accountId: 'a' }).getParam('variant', 'control')
+      ).toBe('control');
+      expect(Log.debug).toHaveBeenCalledWith(expect.stringContaining('not found'));
+    });
+
+    it('reads overrides from the environment by default', () => {
+      const client = ExperimentationClient.createDisabled();
+      expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('from-env');
+    });
+
+    it('still honors overrides', () => {
+      const client = ExperimentationClient.createDisabled(
+        new ExperimentOverrides(parseExperimentOverrides('cli-full:variant=treatment'))
+      );
+      expect(client.getUserNamespace('cli-full').getParam('variant', 'control')).toBe('treatment');
+    });
+  });
+});

packages/eas-cli/src/experimentation/__tests__/fixtures.ts

@@ -0,0 +1,79 @@
+import type { ExperimentationDefinition } from '@expo/experimentation';
+
+import { Analytics } from '../../analytics/AnalyticsManager';
+import { ExperimentNamespace } from '../ExperimentNamespace';
+
+/**
+ * - `cli-full`: every unit is in the `cli-test` experiment (50% control, 50% treatment).
+ * - `cli-half`: half of the units are in `cli-test`, the rest get defaults.
+ * - `cli-quiet-ns`: experiment with the `no-op` exposure logger.
+ */
+export const TEST_DEFINITION: ExperimentationDefinition = {
+  experiments: [
+    {
+      experimentName: 'cli-test',
+      paramDefinitions: {
+        variant: { type: 'uniform_choice', choices: ['control', 'treatment'] },
+        enabled: { type: 'bernoulli', p: 0.5 },
+      },
+      exposureLoggerType: 'rudderstack',
+    },
+    {
+      experimentName: 'cli-quiet',
+      paramDefinitions: {
+        variant: { type: 'uniform_choice', choices: ['a', 'b'] },
+      },
+      exposureLoggerType: 'no-op',
+    },
+  ],
+  namespaces: [
+    {
+      name: 'cli-full',
+      numSegments: 1000,
+      segmentExperimentSetupDefinitions: [
+        { method: 'ADD', name: 'cli-test full', experimentName: 'cli-test', numSegments: 1000 },
+      ],
+    },
+    {
+      name: 'cli-half',
+      numSegments: 1000,
+      segmentExperimentSetupDefinitions: [
+        { method: 'ADD', name: 'cli-test half', experimentName: 'cli-test', numSegments: 500 },
+      ],
+    },
+    {
+      name: 'cli-quiet-ns',
+      numSegments: 1000,
+      segmentExperimentSetupDefinitions: [
+        { method: 'ADD', name: 'cli-quiet full', experimentName: 'cli-quiet', numSegments: 1000 },
+      ],
+    },
+  ],
+};
+
+export function createMockAnalytics(): Analytics & { logEvent: jest.Mock } {
+  return { logEvent: jest.fn() };
+}
+
+/**
+ * Finds one unit per expected value by probing the real library, instead of hard-coding hashes.
+ */
+export function findUnitsByValue<T>(
+  getNamespaceForUnit: (unit: string) => ExperimentNamespace,
+  paramName: string,
+  defaultValue: T,
+  expectedValues: T[]
+): Map<T, string> {
+  const found = new Map<T, string>();
+  for (let i = 0; i < 1000 && found.size < expectedValues.length; i++) {
+    const unit = `unit-${i}`;
+    const value = getNamespaceForUnit(unit).getParam(paramName, defaultValue);
+    if (expectedValues.includes(value) && !found.has(value)) {
+      found.set(value, unit);
+    }
+  }
+  if (found.size !== expectedValues.length) {
+    throw new Error(`Could not find units for all of: ${expectedValues.join(', ')}`);
+  }
+  return found;
+}

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

@@ -16113,6 +16113,11 @@ export type EnvironmentVariablesSharedWithSensitiveQueryVariables = Exact<{
 
 export type EnvironmentVariablesSharedWithSensitiveQuery = { __typename?: 'RootQuery', app: { __typename?: 'AppQuery', byId: { __typename?: 'App', id: string, ownerAccount: { __typename?: 'Account', id: string, environmentVariablesIncludingSensitive: Array<{ __typename?: 'EnvironmentVariableWithSecret', id: string, name: string, value?: string | null, environments?: Array<any> | null, createdAt: any, updatedAt: any, scope: EnvironmentVariableScope, visibility: EnvironmentVariableVisibility, type: EnvironmentSecretType, valueWithFileContent?: string | null }> } } } };
 
+export type ExperimentationConfigsQueryVariables = Exact<{ [key: string]: never; }>;
+
+
+export type ExperimentationConfigsQuery = { __typename?: 'RootQuery', experimentation: { __typename?: 'ExperimentationQuery', userConfig: any, accountConfig: any, deviceConfig: any } };
+
 export type FingerprintsByAppIdQueryVariables = Exact<{
   appId: Scalars['String']['input'];
   after?: InputMaybe<Scalars['String']['input']>;

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

@@ -0,0 +1,66 @@
+import type { ExperimentationDefinition } from '@expo/experimentation';
+import { OperationResult } from '@urql/core';
+import gql from 'graphql-tag';
+
+import { ExpoGraphqlClient } from '../../commandUtils/context/contextUtils/createGraphqlClient';
+import { EMPTY_EXPERIMENTATION_DEFINITION } from '../../experimentation/ExperimentationClient';
+import { ExperimentationConfigsQuery, ExperimentationConfigsQueryVariables } from '../generated';
+
+export type ExperimentationConfigsResult = {
+  userConfig: ExperimentationDefinition;
+  accountConfig: ExperimentationDefinition;
+  deviceConfig: ExperimentationDefinition;
+};
+
+/** Like `withErrorHandlingAsync`, but never logs. Callers fail open. */
+async function quietQueryAsync<T>(promise: Promise<OperationResult<T>>): Promise<T> {
+  const { data, error } = await promise;
+  if (error) {
+    throw error;
+  }
+  if (!data) {
+    throw new Error('Returned query result data is null!');
+  }
+  return data;
+}
+
+/** The server sends an untyped JSONObject. Anything but the expected shape means no experiments. */
+function toExperimentationDefinition(value: unknown): ExperimentationDefinition {
+  if (
+    value &&
+    typeof value === 'object' &&
+    Array.isArray((value as { experiments?: unknown }).experiments) &&
+    Array.isArray((value as { namespaces?: unknown }).namespaces)
+  ) {
+    return value as ExperimentationDefinition;
+  }
+  return EMPTY_EXPERIMENTATION_DEFINITION;
+}
+
+export const ExperimentationConfigQuery = {
+  async getConfigsAsync(graphqlClient: ExpoGraphqlClient): Promise<ExperimentationConfigsResult> {
+    const data = await quietQueryAsync(
+      graphqlClient
+        .query<ExperimentationConfigsQuery, ExperimentationConfigsQueryVariables>(
+          gql`
+            query ExperimentationConfigs {
+              experimentation {
+                userConfig
+                accountConfig
+                deviceConfig
+              }
+            }
+          `,
+          {},
+          // A failing network must not delay the command.
+          { additionalTypenames: ['ExperimentationQuery'], noRetry: true }
+        )
+        .toPromise()
+    );
+    return {
+      userConfig: toExperimentationDefinition(data.experimentation.userConfig),
+      accountConfig: toExperimentationDefinition(data.experimentation.accountConfig),
+      deviceConfig: toExperimentationDefinition(data.experimentation.deviceConfig),
+    };
+  },
+};

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

@@ -12,7 +12,10 @@ import { AccountFragmentNode } from '../types/Account';
 import { MeActorFragmentNode } from '../types/Actor';
 
 export const UserQuery = {
-  async currentUserAsync(graphqlClient: ExpoGraphqlClient): Promise<CurrentUserQuery['meActor']> {
+  async currentUserAsync(
+    graphqlClient: ExpoGraphqlClient,
+    { noRetry = false }: { noRetry?: boolean } = {}
+  ): Promise<CurrentUserQuery['meActor']> {
     const data = await withErrorHandlingAsync(
       graphqlClient
         .query<CurrentUserQuery>(
@@ -29,6 +32,7 @@ export const UserQuery = {
           {},
           {
             additionalTypenames: ['User', 'SSOUser'],
+            noRetry,
           }
         )
         .toPromise()

packages/eas-cli/src/graphql/queries/__tests__/ExperimentationConfigQuery-test.ts

@@ -0,0 +1,89 @@
+import { CombinedError } from '@urql/core';
+import { print } from 'graphql';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import Log from '../../../log';
+import { ExperimentationConfigQuery } from '../ExperimentationConfigQuery';
+
+jest.mock('../../../log');
+
+const definition = {
+  experiments: [{ experimentName: 'x', paramDefinitions: {}, exposureLoggerType: 'rudderstack' }],
+  namespaces: [],
+};
+
+function makeGraphqlClient(result: { data?: unknown; error?: CombinedError }): ExpoGraphqlClient & {
+  query: jest.Mock;
+} {
+  return {
+    query: jest.fn().mockReturnValue({ toPromise: jest.fn().mockResolvedValue(result) }),
+  } as unknown as ExpoGraphqlClient & { query: jest.Mock };
+}
+
+describe('ExperimentationConfigQuery.getConfigsAsync', () => {
+  it('returns the three configs', async () => {
+    const graphqlClient = makeGraphqlClient({
+      data: {
+        experimentation: {
+          userConfig: definition,
+          accountConfig: definition,
+          deviceConfig: definition,
+        },
+      },
+    });
+    await expect(ExperimentationConfigQuery.getConfigsAsync(graphqlClient)).resolves.toEqual({
+      userConfig: definition,
+      accountConfig: definition,
+      deviceConfig: definition,
+    });
+  });
+
+  it('replaces malformed configs with an empty definition', async () => {
+    const graphqlClient = makeGraphqlClient({
+      data: {
+        experimentation: {
+          userConfig: { experiments: 'nope', namespaces: [] },
+          accountConfig: null,
+          deviceConfig: definition,
+        },
+      },
+    });
+    await expect(ExperimentationConfigQuery.getConfigsAsync(graphqlClient)).resolves.toEqual({
+      userConfig: { experiments: [], namespaces: [] },
+      accountConfig: { experiments: [], namespaces: [] },
+      deviceConfig: definition,
+    });
+  });
+
+  it('disables retries and selects only the config fields', async () => {
+    const graphqlClient = makeGraphqlClient({
+      data: { experimentation: { userConfig: {}, accountConfig: {}, deviceConfig: {} } },
+    });
+    await ExperimentationConfigQuery.getConfigsAsync(graphqlClient);
+
+    const [document, variables, context] = graphqlClient.query.mock.calls[0];
+    const printed = print(document);
+    expect(printed).toContain('experimentation');
+    expect(printed).toContain('userConfig');
+    expect(printed).toContain('accountConfig');
+    expect(printed).toContain('deviceConfig');
+    expect(printed).not.toContain('deviceExperimentationUnit');
+    expect(variables).toEqual({});
+    expect(context).toEqual({ additionalTypenames: ['ExperimentationQuery'], noRetry: true });
+  });
+
+  it('rejects on a GraphQL error without logging', async () => {
+    const error = new CombinedError({ networkError: new Error('offline') });
+    const graphqlClient = makeGraphqlClient({ error });
+    await expect(ExperimentationConfigQuery.getConfigsAsync(graphqlClient)).rejects.toBe(error);
+    expect(Log.error).not.toHaveBeenCalled();
+    expect(Log.warn).not.toHaveBeenCalled();
+  });
+
+  it('rejects when the result has no data', async () => {
+    const graphqlClient = makeGraphqlClient({ data: null });
+    await expect(ExperimentationConfigQuery.getConfigsAsync(graphqlClient)).rejects.toThrow(
+      'Returned query result data is null!'
+    );
+  });
+});

packages/eas-cli/src/graphql/queries/__tests__/UserQuery-test.ts

@@ -0,0 +1,74 @@
+import http from 'http';
+import { AddressInfo } from 'net';
+
+import { createGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { UserQuery } from '../UserQuery';
+
+jest.mock('../../../api', () => ({
+  getExpoApiBaseUrl: () => process.env.USER_QUERY_TEST_URL,
+}));
+
+describe(UserQuery.currentUserAsync, () => {
+  describe('against a slow server', () => {
+    const server = http.createServer();
+    const serverDelayMs = 2000;
+    const requestTimeoutMs = 100;
+    let requestCount = 0;
+    // Aborted requests leave their response timers pending; clear them so the worker can exit.
+    const responseTimers: NodeJS.Timeout[] = [];
+
+    beforeAll(async () => {
+      server.on('request', (_req, res) => {
+        requestCount += 1;
+        responseTimers.push(
+          setTimeout(() => {
+            res.setHeader('content-type', 'application/json');
+            res.end(JSON.stringify({ data: { meActor: null } }));
+          }, serverDelayMs)
+        );
+      });
+      await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+      const { port } = server.address() as AddressInfo;
+      process.env.USER_QUERY_TEST_URL = `http://127.0.0.1:${port}`;
+    });
+
+    beforeEach(() => {
+      requestCount = 0;
+    });
+
+    afterAll(async () => {
+      delete process.env.USER_QUERY_TEST_URL;
+      for (const timer of responseTimers) {
+        clearTimeout(timer);
+      }
+      server.closeAllConnections();
+      await new Promise<void>(resolve => {
+        server.close(() => {
+          resolve();
+        });
+      });
+    });
+
+    it('fails after one timed-out request when retries are disabled', async () => {
+      const client = createGraphqlClient(
+        { accessToken: 'token', sessionSecret: null },
+        { requestTimeoutMs }
+      );
+      await expect(UserQuery.currentUserAsync(client, { noRetry: true })).rejects.toThrow(
+        `Request timed out after ${requestTimeoutMs} ms`
+      );
+      expect(requestCount).toBe(1);
+    });
+
+    it('retries a timed-out request by default', async () => {
+      const client = createGraphqlClient(
+        { accessToken: 'token', sessionSecret: null },
+        { requestTimeoutMs }
+      );
+      await expect(UserQuery.currentUserAsync(client)).rejects.toThrow(
+        `Request timed out after ${requestTimeoutMs} ms`
+      );
+      expect(requestCount).toBe(2);
+    }, 15000);
+  });
+});

packages/eas-cli/src/help.ts

@@ -0,0 +1,21 @@
+import { Help, Parser } from '@oclif/core';
+
+export default class EasHelp extends Help {
+  // eslint-disable-next-line async-protect/async-suffix -- oclif defines the method name.
+  override async showHelp(argv: string[]): Promise<void> {
+    const [command, ...args] = argv;
+    if (command === 'simulator:control' || command === 'sim:control') {
+      const { default: SimulatorControl } = await import('./commands/simulator/control');
+      const parsed = await Parser.parse(args, {
+        args: SimulatorControl.args,
+        flags: SimulatorControl.flags,
+        strict: false,
+      });
+      if (parsed.args.action && parsed.flags.help) {
+        await SimulatorControl.run(args, this.config);
+        return;
+      }
+    }
+    await super.showHelp(argv);
+  }
+}

packages/eas-cli/src/simulator/__tests__/fixtures/hostActionCatalog.json

@@ -0,0 +1,518 @@
+{
+  "hardwareKeyboard.set": {
+    "type": "object",
+    "properties": {
+      "udid": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+      },
+      "value": {
+        "type": "string",
+        "enum": [
+          "on",
+          "off"
+        ]
+      }
+    },
+    "required": [
+      "udid",
+      "value"
+    ],
+    "description": "Connect or disconnect the hardware keyboard."
+  },
+  "caDebug.set": {
+    "type": "object",
+    "properties": {
+      "udid": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+      },
+      "option": {
+        "type": "string",
+        "enum": [
+          "blended",
+          "copies",
+          "misaligned",
+          "offscreen",
+          "slow-animations"
+        ]
+      },
+      "value": {
+        "type": "string",
+        "enum": [
+          "on",
+          "off"
+        ]
+      }
+    },
+    "required": [
+      "udid",
+      "option",
+      "value"
+    ],
+    "description": "Turn a Core Animation debug option on or off."
+  },
+  "hinge.set": {
+    "type": "object",
+    "properties": {
+      "udid": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+      },
+      "value": {
+        "anyOf": [
+          {
+            "type": "string",
+            "enum": [
+              "fold",
+              "half",
+              "unfold"
+            ]
+          },
+          {
+            "type": "number"
+          }
+        ]
+      }
+    },
+    "required": [
+      "udid",
+      "value"
+    ],
+    "description": "Fold or unfold a foldable simulator."
+  },
+  "location.set": {
+    "type": "object",
+    "properties": {
+      "udid": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+      },
+      "lat": {
+        "type": "number"
+      },
+      "lng": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "udid",
+      "lat",
+      "lng"
+    ],
+    "description": "Set the simulated location."
+  },
+  "permissions.list": {
+    "type": "object",
+    "properties": {
+      "udid": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+      },
+      "bundleId": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+      }
+    },
+    "required": [
+      "udid"
+    ],
+    "description": "List permissions for one app or for every app."
+  },
+  "permissions.set": {
+    "type": "object",
+    "properties": {
+      "udid": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+      },
+      "action": {
+        "type": "string",
+        "enum": [
+          "grant",
+          "revoke",
+          "reset"
+        ]
+      },
+      "service": {
+        "type": "string",
+        "maxLength": 64,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+      },
+      "bundleId": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+      }
+    },
+    "required": [
+      "udid",
+      "action",
+      "service",
+      "bundleId"
+    ],
+    "description": "Grant, revoke or reset one permission for an app."
+  },
+  "app.install": {
+    "description": "Install an app from an .ipa file.",
+    "args": [
+      "path"
+    ],
+    "upload": "path",
+    "anyOf": [
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "uploadId": {
+            "type": "string",
+            "pattern": "^(?!\\.)[A-Za-z0-9._-]{1,128}$"
+          }
+        },
+        "required": [
+          "udid",
+          "uploadId"
+        ]
+      },
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096,
+            "pattern": "^[^\\p{C}]+$"
+          }
+        },
+        "required": [
+          "udid",
+          "path"
+        ]
+      }
+    ]
+  },
+  "media.add": {
+    "description": "Add a photo or video to the Photos library.",
+    "args": [
+      "path"
+    ],
+    "upload": "path",
+    "anyOf": [
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "uploadId": {
+            "type": "string",
+            "pattern": "^(?!\\.)[A-Za-z0-9._-]{1,128}$"
+          }
+        },
+        "required": [
+          "udid",
+          "uploadId"
+        ]
+      },
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096,
+            "pattern": "^[^\\p{C}]+$"
+          }
+        },
+        "required": [
+          "udid",
+          "path"
+        ]
+      }
+    ]
+  },
+  "camera.switch": {
+    "oneOf": [
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "source": {
+            "type": "string",
+            "const": "file"
+          },
+          "target": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096,
+            "pattern": "^[^\\p{C}]+$"
+          }
+        },
+        "required": [
+          "udid",
+          "source",
+          "target"
+        ]
+      },
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "source": {
+            "type": "string",
+            "const": "webcam"
+          },
+          "target": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096,
+            "pattern": "^[^\\p{C}]+$"
+          }
+        },
+        "required": [
+          "udid",
+          "source"
+        ]
+      },
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "source": {
+            "type": "string",
+            "const": "placeholder"
+          }
+        },
+        "required": [
+          "udid",
+          "source"
+        ]
+      }
+    ],
+    "description": "Change the camera feed of an app with a simulated camera.",
+    "args": [
+      "source",
+      "target"
+    ],
+    "upload": "target",
+    "uploadWhen": {
+      "source": "file"
+    },
+    "keepUpload": true
+  },
+  "camera.inject": {
+    "oneOf": [
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "bundleId": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+          },
+          "mirror": {
+            "type": "string",
+            "enum": [
+              "on",
+              "off"
+            ]
+          },
+          "source": {
+            "type": "string",
+            "const": "file"
+          },
+          "target": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096,
+            "pattern": "^[^\\p{C}]+$"
+          }
+        },
+        "required": [
+          "udid",
+          "bundleId",
+          "mirror",
+          "source",
+          "target"
+        ]
+      },
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "bundleId": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+          },
+          "mirror": {
+            "type": "string",
+            "enum": [
+              "on",
+              "off"
+            ]
+          },
+          "source": {
+            "type": "string",
+            "const": "webcam"
+          },
+          "target": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096,
+            "pattern": "^[^\\p{C}]+$"
+          }
+        },
+        "required": [
+          "udid",
+          "bundleId",
+          "mirror",
+          "source"
+        ]
+      },
+      {
+        "type": "object",
+        "properties": {
+          "udid": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+          },
+          "bundleId": {
+            "type": "string",
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+          },
+          "mirror": {
+            "type": "string",
+            "enum": [
+              "on",
+              "off"
+            ]
+          },
+          "source": {
+            "type": "string",
+            "const": "placeholder"
+          }
+        },
+        "required": [
+          "udid",
+          "bundleId",
+          "mirror",
+          "source"
+        ]
+      }
+    ],
+    "description": "Relaunch an app with a simulated camera feed.",
+    "args": [
+      "bundleId",
+      "mirror",
+      "source",
+      "target"
+    ],
+    "upload": "target",
+    "uploadWhen": {
+      "source": "file"
+    },
+    "keepUpload": true
+  },
+  "screenshot.capture": {
+    "type": "object",
+    "properties": {
+      "udid": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+      },
+      "fileName": {
+        "type": "string",
+        "pattern": "^serve-sim-screenshot-[A-Za-z0-9._-]{1,100}\\.png$"
+      }
+    },
+    "required": [
+      "udid"
+    ],
+    "description": "Take a screenshot.",
+    "output": "path"
+  },
+  "file.readBase64": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 4096,
+        "pattern": "^[^\\p{C}]+$"
+      }
+    },
+    "required": [
+      "path"
+    ],
+    "description": "Download a file from the simulator host.",
+    "output": "base64"
+  },
+  "app.container": {
+    "type": "object",
+    "properties": {
+      "udid": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._()-]*$"
+      },
+      "bundleId": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+      }
+    },
+    "required": [
+      "udid",
+      "bundleId"
+    ],
+    "description": "Print the path of an installed app bundle."
+  }
+}

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

@@ -0,0 +1,633 @@
+import * as fs from 'fs-extra';
+import { once } from 'node:events';
+import http from 'node:http';
+import { AddressInfo } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { Duplex } from 'node:stream';
+import { WebSocketServer } from 'ws';
+
+import * as fetchModule from '../../fetch';
+import {
+  HostActionCatalog,
+  HostActionConnection,
+  assertHostActionOutputAsync,
+  buildHostActionParams,
+  connectHostActionsAsync,
+  fetchHostActionCatalogAsync,
+  formatHostActionUsage,
+  saveHostActionOutputAsync,
+  uploadFileAsync,
+} from '../hostActions';
+
+const UDID = '90858C9D-BC34-4A0A-93D4-E4939A681A72';
+const TOKEN = 'preview-token_123';
+const catalog: HostActionCatalog = require('./fixtures/hostActionCatalog.json');
+
+function entry(name: string): HostActionCatalog[string] {
+  return catalog[name];
+}
+
+describe(buildHostActionParams, () => {
+  it('fills parameters in schema order', () => {
+    expect(
+      buildHostActionParams('permissions.set', entry('permissions.set'), [
+        'grant',
+        'camera',
+        'com.example.app',
+      ])
+    ).toEqual({ action: 'grant', service: 'camera', bundleId: 'com.example.app' });
+  });
+
+  it('converts values to the types the schema accepts', () => {
+    expect(
+      buildHostActionParams('location.set', entry('location.set'), ['37.3349', '-122.009'])
+    ).toEqual({ lat: 37.3349, lng: -122.009 });
+    expect(buildHostActionParams('hinge.set', entry('hinge.set'), ['90'])).toEqual({ value: 90 });
+    expect(buildHostActionParams('hinge.set', entry('hinge.set'), ['half'])).toEqual({
+      value: 'half',
+    });
+    expect(
+      buildHostActionParams('hardwareKeyboard.set', entry('hardwareKeyboard.set'), ['1'])
+    ).toEqual({ value: '1' });
+    expect(buildHostActionParams('location.set', entry('location.set'), ['1e1', '.5'])).toEqual({
+      lat: 10,
+      lng: 0.5,
+    });
+  });
+
+  it('reads JSON for a parameter that takes a list', () => {
+    const launch = {
+      type: 'object',
+      properties: {
+        udid: { type: 'string' },
+        bundleId: { type: 'string' },
+        launchArgs: { type: 'array', items: { type: 'string' } },
+      },
+    };
+
+    expect(
+      buildHostActionParams('app.launch', launch, ['com.example.app', '["-FIRDebugEnabled"]'])
+    ).toEqual({ bundleId: 'com.example.app', launchArgs: ['-FIRDebugEnabled'] });
+    expect(buildHostActionParams('app.launch', launch, ['com.example.app', '[oops'])).toEqual({
+      bundleId: 'com.example.app',
+      launchArgs: '[oops',
+    });
+  });
+
+  it('fills the values in order around the named ones', () => {
+    expect(buildHostActionParams('location.set', entry('location.set'), ['lat=1', '2'])).toEqual({
+      lat: 1,
+      lng: 2,
+    });
+    expect(
+      buildHostActionParams('permissions.set', entry('permissions.set'), [
+        'action=grant',
+        'camera',
+        'com.example.app',
+      ])
+    ).toEqual({ action: 'grant', service: 'camera', bundleId: 'com.example.app' });
+  });
+
+  it('accepts named values in any order', () => {
+    expect(
+      buildHostActionParams('permissions.list', entry('permissions.list'), [
+        'bundleId=com.example.app',
+      ])
+    ).toEqual({ bundleId: 'com.example.app' });
+    expect(
+      buildHostActionParams('camera.switch', entry('camera.switch'), [
+        'target=./photo.jpg',
+        'source=file',
+      ])
+    ).toEqual({ source: 'file', target: './photo.jpg' });
+  });
+
+  it('follows the value order the catalog gives for actions with several shapes', () => {
+    expect(buildHostActionParams('app.install', entry('app.install'), ['./MyApp.ipa'])).toEqual({
+      path: './MyApp.ipa',
+    });
+    expect(
+      buildHostActionParams('camera.switch', entry('camera.switch'), ['file', './photo.jpg'])
+    ).toEqual({ source: 'file', target: './photo.jpg' });
+    expect(
+      buildHostActionParams('camera.inject', entry('camera.inject'), [
+        'com.example.app',
+        'off',
+        'placeholder',
+      ])
+    ).toEqual({ bundleId: 'com.example.app', mirror: 'off', source: 'placeholder' });
+  });
+
+  it('refuses extra values and a value given twice', () => {
+    expect(() =>
+      buildHostActionParams('hardwareKeyboard.set', entry('hardwareKeyboard.set'), ['on', 'off'])
+    ).toThrow(
+      'Too many values for hardwareKeyboard.set. Usage: eas simulator:control hardwareKeyboard.set <value>.'
+    );
+    expect(() =>
+      buildHostActionParams('camera.switch', entry('camera.switch'), ['file', './a.jpg', './b.jpg'])
+    ).toThrow('Too many values for camera.switch.');
+    expect(() =>
+      buildHostActionParams('hardwareKeyboard.set', entry('hardwareKeyboard.set'), [
+        'value=on',
+        'value=off',
+      ])
+    ).toThrow('value is given twice for hardwareKeyboard.set.');
+  });
+});
+
+describe(formatHostActionUsage, () => {
+  it.each(['anyOf', 'oneOf'])('shows a %s input group only once', composition => {
+    expect(
+      formatHostActionUsage('app.install', {
+        type: 'object',
+        properties: {
+          bundleId: { type: 'string' },
+          path: { type: 'string' },
+          uploadId: { type: 'string' },
+        },
+        required: ['bundleId'],
+        args: ['bundleId', 'path', 'uploadId'],
+        [composition]: [{ required: ['path'] }, { required: ['uploadId'] }],
+      })
+    ).toBe('app.install <bundleId> <path|uploadId=...>');
+  });
+
+  it('shows the required alternative file sources for an upload action', () => {
+    expect(formatHostActionUsage('app.install', entry('app.install'))).toBe(
+      'app.install <uploadId=...|path>'
+    );
+  });
+
+  it('marks required and optional parameters', () => {
+    expect(formatHostActionUsage('permissions.set', entry('permissions.set'))).toBe(
+      'permissions.set <action> <service> <bundleId>'
+    );
+    expect(formatHostActionUsage('screenshot.capture', entry('screenshot.capture'))).toBe(
+      'screenshot.capture [fileName]'
+    );
+    expect(formatHostActionUsage('camera.switch', entry('camera.switch'))).toBe(
+      'camera.switch <source> [target]'
+    );
+  });
+});
+
+describe('host action transport policy', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it.each([
+    'http://sim.example.test',
+    'http://127.0.0.1.example.test',
+    'http://localhost.example.test',
+    'http://[::ffff:192.0.2.1]',
+    'ftp://127.0.0.1',
+    'ws://127.0.0.1',
+  ])('rejects %s before sending the session token', async apiUrl => {
+    const fetch = jest
+      .spyOn(fetchModule, 'default')
+      .mockRejectedValue(new Error('Unexpected fetch'));
+
+    await expect(connectHostActionsAsync({ apiUrl, token: TOKEN })).rejects.toThrow(
+      'Simulator actions require HTTPS'
+    );
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['https://sim.example.test', 'https://sim.example.test/api'],
+    ['http://localhost:44370', 'http://localhost:44370/api'],
+    ['http://127.0.0.1:44370', 'http://127.0.0.1:44370/api'],
+    ['http://127.255.255.254:44370', 'http://127.255.255.254:44370/api'],
+    ['http://2130706433:44370', 'http://127.0.0.1:44370/api'],
+    ['http://[::1]:44370', 'http://[::1]:44370/api'],
+  ])('accepts %s without following authenticated redirects', async (apiUrl, endpoint) => {
+    const stopped = new Error('Fetch reached');
+    const fetch = jest.spyOn(fetchModule, 'default').mockRejectedValue(stopped);
+
+    await expect(connectHostActionsAsync({ apiUrl, token: TOKEN })).rejects.toBe(stopped);
+    expect(fetch).toHaveBeenCalledWith(
+      endpoint,
+      expect.objectContaining({
+        headers: { Authorization: `Bearer ${TOKEN}` },
+        redirect: 'error',
+      })
+    );
+  });
+});
+
+describe('host action connection', () => {
+  let server: http.Server;
+  let wss: WebSocketServer;
+  let apiUrl: string;
+  let received: { id: number; action: string; params: Record<string, unknown> }[];
+  let requests: (string | undefined)[];
+  let apiBody: string;
+  let uploads: Map<string, Buffer>;
+  let reply: (message: {
+    id: number;
+    action: string;
+    params: Record<string, unknown>;
+  }) => Record<string, unknown> | null;
+  let tmpDir: string;
+  let connection: HostActionConnection | undefined;
+  let closeBeforeReady: boolean;
+
+  function serveSim(message: {
+    id: number;
+    action: string;
+    params: Record<string, unknown>;
+  }): Record<string, unknown> {
+    const ok = (stdout: string): Record<string, unknown> => ({
+      id: message.id,
+      stdout,
+      stderr: '',
+      exitCode: 0,
+    });
+    switch (message.action) {
+      case 'actions.describe':
+        return ok(JSON.stringify(catalog));
+      case 'upload.append': {
+        const uploadId = String(message.params.uploadId);
+        const chunk = Buffer.from(String(message.params.data), 'base64');
+        const earlier = message.params.first ? [] : [uploads.get(uploadId) ?? Buffer.alloc(0)];
+        uploads.set(uploadId, Buffer.concat([...earlier, chunk]));
+        return ok(`/tmp/serve-sim-uploads/${uploadId}\n`);
+      }
+      case 'file.readBase64':
+        return ok(Buffer.from('png bytes').toString('base64'));
+      default:
+        return ok('on\n');
+    }
+  }
+
+  beforeEach(async () => {
+    received = [];
+    requests = [];
+    uploads = new Map();
+    apiBody = JSON.stringify({ device: UDID });
+    reply = serveSim;
+    closeBeforeReady = false;
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'host-actions-'));
+    server = http.createServer((req, res) => {
+      requests.push(req.url);
+      if (req.url === '/api' && req.headers.authorization === `Bearer ${TOKEN}`) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(apiBody);
+        return;
+      }
+      res.writeHead(401);
+      res.end();
+    });
+    wss = new WebSocketServer({
+      server,
+      path: '/exec-ws',
+      handleProtocols: offered =>
+        offered.has(`serve-sim.token.${TOKEN}`) ? `serve-sim.token.${TOKEN}` : false,
+    });
+    wss.on('connection', ws => {
+      if (closeBeforeReady) {
+        ws.close();
+        return;
+      }
+      ws.send(JSON.stringify({ ready: true }));
+      ws.on('message', data => {
+        const message = JSON.parse(data.toString());
+        received.push(message);
+        const response = reply(message);
+        if (response) {
+          ws.send(JSON.stringify(response));
+        }
+      });
+    });
+    server.listen(0, '127.0.0.1');
+    await once(server, 'listening');
+    apiUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  });
+
+  afterEach(async () => {
+    connection?.close();
+    connection = undefined;
+    for (const client of wss.clients) {
+      client.terminate();
+    }
+    wss.close();
+    server.close();
+    await once(server, 'close');
+    await fs.remove(tmpDir);
+  });
+
+  async function connectAsync(timeoutMs?: number): Promise<HostActionConnection> {
+    connection = await connectHostActionsAsync({ apiUrl, token: TOKEN }, { timeoutMs });
+    return connection;
+  }
+
+  it('sends several requests over one connection with the simulator udid', async () => {
+    const hostActions = await connectAsync();
+
+    const results = await Promise.all([
+      hostActions.requestAsync('hardwareKeyboard.get'),
+      hostActions.requestAsync('hardwareKeyboard.set', { value: 'off' }),
+    ]);
+
+    expect(received).toEqual([
+      { id: 1, action: 'hardwareKeyboard.get', params: { udid: UDID } },
+      { id: 2, action: 'hardwareKeyboard.set', params: { value: 'off', udid: UDID } },
+    ]);
+    expect(results).toEqual([
+      { stdout: 'on\n', stderr: '', exitCode: 0 },
+      { stdout: 'on\n', stderr: '', exitCode: 0 },
+    ]);
+  });
+
+  it('reads the catalog of actions', async () => {
+    const hostActions = await connectAsync();
+
+    await expect(fetchHostActionCatalogAsync(hostActions)).resolves.toEqual(catalog);
+  });
+
+  it('explains that an old serve-sim does not have the catalog', async () => {
+    reply = message => ({ id: message.id, error: 'unknown action actions.describe' });
+    const hostActions = await connectAsync();
+
+    await expect(fetchHostActionCatalogAsync(hostActions)).rejects.toThrow(
+      'does not support this action'
+    );
+  });
+
+  it('passes a validation error from the simulator through', async () => {
+    reply = message => ({
+      id: message.id,
+      error: 'hardwareKeyboard.set: value must be one of on, off',
+    });
+    const hostActions = await connectAsync();
+
+    await expect(
+      hostActions.requestAsync('hardwareKeyboard.set', { value: 'maybe' })
+    ).rejects.toThrow(
+      'The simulator refused the request: hardwareKeyboard.set: value must be one of on, off'
+    );
+  });
+
+  it('fails a request at once on a reply it cannot read', async () => {
+    reply = message => ({ id: message.id, output: 'on' });
+    const hostActions = await connectAsync();
+
+    await expect(hostActions.requestAsync('memoryWarning')).rejects.toThrow(
+      'sent a reply that this version of eas-cli cannot read'
+    );
+  });
+
+  it('gives up on a request the simulator does not answer', async () => {
+    reply = () => null;
+    const hostActions = await connectAsync(100);
+
+    await expect(hostActions.requestAsync('memoryWarning')).rejects.toThrow(
+      'The simulator did not answer within'
+    );
+  });
+
+  it('keeps a path on the API URL and drops its query', async () => {
+    await expect(
+      connectHostActionsAsync({ apiUrl: `${apiUrl}/preview?token=${TOKEN}`, token: TOKEN })
+    ).rejects.toThrow('refused the session token (HTTP 401)');
+    expect(requests).toEqual(['/preview/api']);
+  });
+
+  it('refuses a wrong token before it opens the socket', async () => {
+    await expect(connectHostActionsAsync({ apiUrl, token: 'wrong' })).rejects.toThrow(
+      'refused the session token (HTTP 401)'
+    );
+    expect(wss.clients.size).toBe(0);
+  });
+
+  it('does not send the session token to an API redirect target', async () => {
+    server.removeAllListeners('request');
+    server.on('request', (req, res) => {
+      requests.push(req.url);
+      if (req.url === '/api') {
+        res.writeHead(302, { Location: '/redirected-api' });
+        res.end();
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(apiBody);
+      }
+    });
+
+    await expect(connectAsync()).rejects.toThrow(/redirect/i);
+    expect(requests).toEqual(['/api']);
+    expect(wss.clients.size).toBe(0);
+  });
+
+  it('explains a connection that closes during setup', async () => {
+    closeBeforeReady = true;
+
+    await expect(connectHostActionsAsync({ apiUrl, token: TOKEN })).rejects.toThrow(
+      /closed the connection during setup.*token.*eas simulator:get/
+    );
+  });
+
+  it.each([401, 403])(
+    'closes a refused HTTP %i upgrade without waiting for its body',
+    async status => {
+      let rejectedSocket: Duplex | undefined;
+      let timer: NodeJS.Timeout | undefined;
+      const closed = new Promise<void>(resolve => {
+        server.removeAllListeners('upgrade');
+        server.once('upgrade', (_req, socket) => {
+          rejectedSocket = socket;
+          socket.once('close', resolve);
+          socket.on('end', () => socket.end());
+          socket.write(
+            `HTTP/1.1 ${status} Refused\r\nConnection: keep-alive\r\nContent-Length: 1000000\r\n\r\nrefused`
+          );
+        });
+      });
+
+      try {
+        await expect(connectHostActionsAsync({ apiUrl, token: TOKEN })).rejects.toThrow(
+          `refused the connection (HTTP ${status})`
+        );
+        await Promise.race([
+          closed,
+          new Promise<never>((_resolve, reject) => {
+            timer = setTimeout(() => {
+              reject(new Error('Refused upgrade socket stayed open'));
+            }, 1000);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+        rejectedSocket?.destroy();
+      }
+    }
+  );
+
+  it('explains a preview server that does not report its simulator', async () => {
+    apiBody = '<html>starting</html>';
+
+    await expect(connectHostActionsAsync({ apiUrl, token: TOKEN })).rejects.toThrow(
+      'did not report which simulator it streams'
+    );
+  });
+
+  it('uploads a file in order and returns where the simulator host stored it', async () => {
+    const localFile = path.join(tmpDir, 'MyApp.ipa');
+    await fs.writeFile(localFile, 'hello simulator');
+    const hostActions = await connectAsync();
+
+    const upload = await uploadFileAsync(hostActions, localFile, { chunkBytes: 4 });
+
+    expect(upload.uploadId).toMatch(/^eas-cli-[0-9a-f-]{36}\.ipa$/);
+    expect(upload.path).toBe(`/tmp/serve-sim-uploads/${upload.uploadId}`);
+    expect(uploads.get(upload.uploadId)?.toString()).toBe('hello simulator');
+    expect(received.map(message => message.params.first)).toEqual([true, false, false, false]);
+  });
+
+  it('removes a partial upload when a chunk fails', async () => {
+    const localFile = path.join(tmpDir, 'MyApp.ipa');
+    await fs.writeFile(localFile, 'hello simulator');
+    reply = message =>
+      message.action === 'upload.append' && !message.params.first
+        ? { id: message.id, stdout: '', stderr: 'The upload staging area is full.', exitCode: 1 }
+        : serveSim(message);
+    const hostActions = await connectAsync();
+
+    await expect(uploadFileAsync(hostActions, localFile, { chunkBytes: 4 })).rejects.toThrow(
+      `Could not upload ${localFile}: The upload staging area is full.`
+    );
+    expect(received.at(-1)).toMatchObject({
+      action: 'upload.remove',
+      params: { uploadId: received[0].params.uploadId },
+    });
+  });
+
+  it('refuses to upload an empty file', async () => {
+    const localFile = path.join(tmpDir, 'empty.png');
+    await fs.writeFile(localFile, '');
+    const hostActions = await connectAsync();
+
+    await expect(uploadFileAsync(hostActions, localFile)).rejects.toThrow(`${localFile} is empty.`);
+  });
+
+  it('downloads a file the action left on the simulator host', async () => {
+    const hostActions = await connectAsync();
+    const outputPath = path.join(tmpDir, 'shot.png');
+
+    const saved = await saveHostActionOutputAsync(
+      hostActions,
+      entry('screenshot.capture'),
+      '/tmp/serve-sim-screenshots/serve-sim-screenshot-1.png\n',
+      outputPath
+    );
+
+    expect(saved).toBe(outputPath);
+    expect(received.at(-1)).toMatchObject({
+      action: 'file.readBase64',
+      params: { path: '/tmp/serve-sim-screenshots/serve-sim-screenshot-1.png' },
+    });
+    expect(await fs.readFile(outputPath, 'utf8')).toBe('png bytes');
+  });
+
+  it('saves into a folder under the name the host gave the file', async () => {
+    const hostActions = await connectAsync();
+
+    const saved = await saveHostActionOutputAsync(
+      hostActions,
+      entry('screenshot.capture'),
+      '/tmp/serve-sim-screenshots/serve-sim-screenshot-1.png\n',
+      tmpDir
+    );
+
+    expect(saved).toBe(path.join(tmpDir, 'serve-sim-screenshot-1.png'));
+    expect(await fs.readFile(path.join(tmpDir, 'serve-sim-screenshot-1.png'), 'utf8')).toBe(
+      'png bytes'
+    );
+  });
+
+  it('does not replace a file it named itself', async () => {
+    const existing = path.join(tmpDir, 'serve-sim-screenshot-1.png');
+    await fs.writeFile(existing, 'mine');
+    const hostActions = await connectAsync();
+
+    await expect(
+      saveHostActionOutputAsync(
+        hostActions,
+        entry('screenshot.capture'),
+        '/tmp/serve-sim-screenshots/serve-sim-screenshot-1.png\n',
+        tmpDir
+      )
+    ).rejects.toThrow(`${existing} already exists.`);
+    expect(await fs.readFile(existing, 'utf8')).toBe('mine');
+  });
+
+  it('saves file contents the action returned', async () => {
+    const hostActions = await connectAsync();
+    const outputPath = path.join(tmpDir, 'Info.plist');
+
+    await saveHostActionOutputAsync(
+      hostActions,
+      entry('file.readBase64'),
+      Buffer.from('plist').toString('base64'),
+      outputPath
+    );
+
+    expect(await fs.readFile(outputPath, 'utf8')).toBe('plist');
+  });
+
+  it('saves nothing for an action that returns no file', async () => {
+    const hostActions = await connectAsync();
+
+    await expect(
+      saveHostActionOutputAsync(hostActions, entry('hardwareKeyboard.set'), 'on', undefined)
+    ).resolves.toBeNull();
+  });
+});
+
+describe(assertHostActionOutputAsync, () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'host-action-output-'));
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it('allows --output only for actions that return a file', async () => {
+    await expect(
+      assertHostActionOutputAsync('app.container', entry('app.container'), './out')
+    ).rejects.toThrow('app.container does not return a file, so --output does not apply.');
+    await expect(
+      assertHostActionOutputAsync('screenshot.capture', entry('screenshot.capture'), undefined)
+    ).resolves.toBeUndefined();
+    await expect(
+      assertHostActionOutputAsync('screenshot.capture', entry('screenshot.capture'), tmpDir)
+    ).resolves.toBeUndefined();
+  });
+
+  it('needs a file path for an action that returns file contents', async () => {
+    await expect(
+      assertHostActionOutputAsync('file.readBase64', entry('file.readBase64'), undefined)
+    ).rejects.toThrow('file.readBase64 returns a file. Pass --output with the path to save it to.');
+    await expect(
+      assertHostActionOutputAsync('file.readBase64', entry('file.readBase64'), tmpDir)
+    ).rejects.toThrow(`${tmpDir} is a folder. Pass --output with a file path for file.readBase64.`);
+  });
+
+  it('refuses a path in a folder that does not exist', async () => {
+    const missing = path.join(tmpDir, 'missing', 'shot.png');
+
+    await expect(
+      assertHostActionOutputAsync('screenshot.capture', entry('screenshot.capture'), missing)
+    ).rejects.toThrow(`The folder for ${missing} does not exist.`);
+    await expect(
+      assertHostActionOutputAsync(
+        'screenshot.capture',
+        entry('screenshot.capture'),
+        path.join(tmpDir, 'missing') + path.sep
+      )
+    ).rejects.toThrow('does not exist');
+  });
+});

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

@@ -19,6 +19,7 @@ import {
   formatSimulatorUnavailableMessage,
   getLocalEgressConfig,
   getLoopbackForwardPlan,
+  getPreviewApiAccess,
   getRemoteSessionEnvironmentVariables,
   sanitizeRemoteConfigForJson,
 } from '../utils';
@@ -837,6 +838,45 @@ describe.each(controllerConfigs)('$__typename local egress', remoteConfig => {
   });
 });
 
+describe(getPreviewApiAccess, () => {
+  it('reads the preview token for each remote config type', () => {
+    expect(
+      getPreviewApiAccess({
+        __typename: 'WebPreviewOnlyRunSessionRemoteConfig',
+        previewUrl: 'https://expo.dev/preview',
+        previewToken: 'preview-token',
+        previewApiUrl: 'https://sim.example.test',
+      })
+    ).toEqual({ apiUrl: 'https://sim.example.test', token: 'preview-token' });
+    expect(
+      getPreviewApiAccess({
+        __typename: 'AgentDeviceRunSessionRemoteConfig',
+        agentDeviceRemoteSessionUrl: 'https://agent.example.test',
+        agentDeviceRemoteSessionToken: 'agent-token',
+        webPreviewToken: 'preview-token',
+        previewApiUrl: 'https://sim.example.test',
+      })
+    ).toEqual({ apiUrl: 'https://sim.example.test', token: 'preview-token' });
+  });
+
+  it('returns null without an API URL or a token', () => {
+    expect(
+      getPreviewApiAccess({
+        __typename: 'ServeSimRunSessionRemoteConfig',
+        previewUrl: 'https://sim.example.test',
+        previewToken: 'preview-token',
+      })
+    ).toBeNull();
+    expect(
+      getPreviewApiAccess({
+        __typename: 'ServeSimRunSessionRemoteConfig',
+        previewUrl: 'https://sim.example.test',
+        previewApiUrl: 'https://sim.example.test',
+      })
+    ).toBeNull();
+  });
+});
+
 describe(formatEmbedPreviewUrl, () => {
   it('is null until the worker reports the preview host', () => {
     expect(formatEmbedPreviewUrl(agentDeviceConfig)).toBeNull();

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

@@ -0,0 +1,520 @@
+import { randomUUID } from 'crypto';
+import * as fs from 'fs-extra';
+import path from 'path';
+import WebSocket from 'ws';
+import { z } from 'zod';
+
+import { PreviewApiAccess } from './utils';
+import fetch, { RequestError, httpsProxyAgent } from '../fetch';
+
+export type HostActionResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export type HostActionConnection = {
+  requestAsync(action: string, params?: Record<string, unknown>): Promise<HostActionResult>;
+  close(): void;
+};
+
+const SchemaNode = z.looseObject({
+  type: z.union([z.string(), z.array(z.string())]).optional(),
+  properties: z.record(z.string(), z.unknown()).optional(),
+  required: z.array(z.string()).optional(),
+  allOf: z.array(z.unknown()).optional(),
+  anyOf: z.array(z.unknown()).optional(),
+  oneOf: z.array(z.unknown()).optional(),
+});
+
+const CatalogEntry = SchemaNode.extend({
+  description: z.string().optional(),
+  args: z.array(z.string()).optional(),
+  upload: z.string().optional(),
+  uploadAs: z.enum(['path', 'id']).optional(),
+  uploadWhen: z.record(z.string(), z.unknown()).optional(),
+  keepUpload: z.boolean().optional(),
+  output: z.enum(['path', 'base64']).optional(),
+});
+
+const Catalog = z.record(z.string(), CatalogEntry);
+
+export type HostActionCatalog = z.infer<typeof Catalog>;
+export type HostActionCatalogEntry = z.infer<typeof CatalogEntry>;
+
+const PreviewConfig = z.object({ device: z.string().min(1) });
+
+const ReplyId = z.object({ id: z.number() });
+
+const SocketMessage = z.union([
+  z.object({ ready: z.literal(true) }),
+  z.object({ id: z.number(), error: z.string() }),
+  z.object({
+    id: z.number(),
+    stdout: z.string(),
+    stderr: z.string(),
+    exitCode: z.number(),
+  }),
+]);
+
+const HOST_ACTION_TIMEOUT_MS = 130_000;
+const PREVIEW_API_TIMEOUT_MS = 30_000;
+const UPLOAD_CHUNK_BYTES = 2 * 1024 * 1024;
+const NAMED_VALUE = /^([A-Za-z][A-Za-z0-9]*)=(.*)$/s;
+const NUMBER = /^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i;
+
+function previewEndpoint(apiUrl: string, endpoint: string): URL {
+  const base = new URL(apiUrl);
+  const loopback =
+    base.hostname === 'localhost' ||
+    base.hostname === '[::1]' ||
+    /^127(?:\.\d{1,3}){3}$/.test(base.hostname);
+  if (base.protocol !== 'https:' && (base.protocol !== 'http:' || !loopback)) {
+    throw new Error(
+      'Simulator actions require HTTPS for remote preview servers. HTTP is supported only on localhost or a loopback address. Start a new session with `eas simulator:start`.'
+    );
+  }
+  base.search = '';
+  base.hash = '';
+  if (!base.pathname.endsWith('/')) {
+    base.pathname += '/';
+  }
+  return new URL(endpoint, base);
+}
+
+async function fetchSimulatorUdidAsync({ apiUrl, token }: PreviewApiAccess): Promise<string> {
+  let text: string;
+  try {
+    const response = await fetch(previewEndpoint(apiUrl, 'api').toString(), {
+      headers: { Authorization: `Bearer ${token}` },
+      redirect: 'error',
+      signal: AbortSignal.timeout(PREVIEW_API_TIMEOUT_MS),
+    });
+    text = await response.text();
+  } catch (error) {
+    if (error instanceof RequestError && [401, 403].includes(error.response.status)) {
+      throw new Error(
+        `The simulator preview server refused the session token (HTTP ${error.response.status}). Run \`eas simulator:get\` to check that the session still runs, then try again.`
+      );
+    }
+    if (error instanceof Error && error.name === 'AbortError') {
+      throw new Error(
+        `The simulator preview server did not answer within ${PREVIEW_API_TIMEOUT_MS / 1000} seconds. Run \`eas simulator:get\` to check that the session still runs, then try again.`
+      );
+    }
+    throw error;
+  }
+  let body: unknown = null;
+  try {
+    body = JSON.parse(text);
+  } catch {}
+  const config = PreviewConfig.safeParse(body);
+  if (!config.success) {
+    throw new Error(
+      'The simulator preview server did not report which simulator it streams. The session may still be starting. Wait a few seconds and run the command again.'
+    );
+  }
+  return config.data.device;
+}
+
+function refusedError(error: string): Error {
+  return error.startsWith('unknown action')
+    ? new Error(
+        'This simulator session runs a serve-sim version that does not support this action. Start a new session with `eas simulator:start` to get a newer version.'
+      )
+    : new Error(`The simulator refused the request: ${error}`);
+}
+
+export async function connectHostActionsAsync(
+  access: PreviewApiAccess,
+  { timeoutMs = HOST_ACTION_TIMEOUT_MS }: { timeoutMs?: number } = {}
+): Promise<HostActionConnection> {
+  const udid = await fetchSimulatorUdidAsync(access);
+  const socketUrl = previewEndpoint(access.apiUrl, 'exec-ws');
+  socketUrl.protocol = socketUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+  const ws = new WebSocket(
+    socketUrl.toString(),
+    [`serve-sim.token.${access.token}`],
+    httpsProxyAgent ? { agent: httpsProxyAgent } : {}
+  );
+
+  type Pending = {
+    resolve: (result: HostActionResult) => void;
+    reject: (error: Error) => void;
+    timer: NodeJS.Timeout;
+  };
+  const pending = new Map<number, Pending>();
+  let nextId = 1;
+  let lost: Error | null = null;
+  let ready = false;
+
+  function settle(id: number): Pending | undefined {
+    const request = pending.get(id);
+    if (request) {
+      pending.delete(id);
+      clearTimeout(request.timer);
+    }
+    return request;
+  }
+
+  function loseConnection(error: Error): void {
+    lost ??= error;
+    for (const id of [...pending.keys()]) {
+      settle(id)?.reject(error);
+    }
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `The simulator preview server did not accept the connection within ${PREVIEW_API_TIMEOUT_MS / 1000} seconds. Check that the session still runs with \`eas simulator:get\`, then try again.`
+        )
+      );
+      ws.terminate();
+    }, PREVIEW_API_TIMEOUT_MS);
+    const fail = (error: Error): void => {
+      clearTimeout(timer);
+      reject(error);
+      loseConnection(error);
+      if (!ready) {
+        ws.terminate();
+      }
+    };
+
+    ws.on('message', data => {
+      let message: unknown;
+      try {
+        message = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      const parsed = SocketMessage.safeParse(message);
+      if (!parsed.success) {
+        const id = ReplyId.safeParse(message);
+        if (id.success) {
+          settle(id.data.id)?.reject(
+            new Error(
+              'The simulator preview server sent a reply that this version of eas-cli cannot read. Update eas-cli and try again.'
+            )
+          );
+        }
+        return;
+      }
+      const reply = parsed.data;
+      if ('ready' in reply) {
+        ready = true;
+        clearTimeout(timer);
+        resolve();
+      } else if ('error' in reply) {
+        settle(reply.id)?.reject(refusedError(reply.error));
+      } else {
+        settle(reply.id)?.resolve({
+          stdout: reply.stdout,
+          stderr: reply.stderr,
+          exitCode: reply.exitCode,
+        });
+      }
+    });
+    ws.on('unexpected-response', (_req, res) => {
+      res.destroy();
+      fail(
+        new Error(
+          `The simulator preview server refused the connection (HTTP ${res.statusCode}). The session token may be out of date. Run \`eas simulator:get\` to check the session, then try again.`
+        )
+      );
+    });
+    ws.on('error', error => {
+      fail(
+        new Error(
+          `Could not connect to the simulator preview server: ${error.message}. Check your network connection and that the session still runs.`
+        )
+      );
+    });
+    ws.on('close', () => {
+      fail(
+        new Error(
+          ready
+            ? 'The simulator preview server closed the connection before it answered. The action may still have run. Check the current state before you try again.'
+            : 'The simulator preview server closed the connection during setup. The session token may be invalid or expired, or the session may run an older serve-sim version. Check the session with `eas simulator:get` before starting a new session.'
+        )
+      );
+    });
+  });
+
+  return {
+    async requestAsync(action, params = {}) {
+      if (lost) {
+        throw lost;
+      }
+      const id = nextId++;
+      return await new Promise<HostActionResult>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          settle(id)?.reject(
+            new Error(
+              `The simulator did not answer within ${Math.round(timeoutMs / 1000)} seconds. The action may still have run. Check the session with \`eas simulator:get\` and the current state before you try again.`
+            )
+          );
+        }, timeoutMs);
+        pending.set(id, { resolve, reject, timer });
+        ws.send(JSON.stringify({ id, action, params: { ...params, udid } }));
+      });
+    },
+    close() {
+      ws.close();
+    },
+  };
+}
+
+export async function fetchHostActionCatalogAsync(
+  connection: HostActionConnection
+): Promise<HostActionCatalog> {
+  const result = await connection.requestAsync('actions.describe');
+  let body: unknown = null;
+  try {
+    body = JSON.parse(result.stdout);
+  } catch {}
+  const catalog = Catalog.safeParse(body);
+  if (result.exitCode !== 0 || !catalog.success) {
+    throw new Error(
+      'The simulator did not return its list of actions. Start a new session with `eas simulator:start` to get a newer serve-sim version.'
+    );
+  }
+  return catalog.data;
+}
+
+function collectProperties(node: unknown, into: Map<string, unknown[]>): void {
+  const parsed = SchemaNode.safeParse(node);
+  if (!parsed.success) {
+    return;
+  }
+  for (const [name, schema] of Object.entries(parsed.data.properties ?? {})) {
+    into.set(name, [...(into.get(name) ?? []), schema]);
+  }
+  const { allOf = [], anyOf = [], oneOf = [] } = parsed.data;
+  for (const child of [...allOf, ...anyOf, ...oneOf]) {
+    collectProperties(child, into);
+  }
+}
+
+function hostActionProperties(entry: HostActionCatalogEntry): Map<string, unknown[]> {
+  const properties = new Map<string, unknown[]>();
+  collectProperties(entry, properties);
+  properties.delete('udid');
+  return properties;
+}
+
+function positionalNames(entry: HostActionCatalogEntry): string[] {
+  return entry.args ?? Object.keys(entry.properties ?? {}).filter(name => name !== 'udid');
+}
+
+function requiredProperties(node: unknown): Set<string> {
+  const parsed = SchemaNode.safeParse(node);
+  if (!parsed.success) {
+    return new Set();
+  }
+  const required = new Set(parsed.data.required ?? []);
+  for (const child of parsed.data.allOf ?? []) {
+    requiredProperties(child).forEach(name => required.add(name));
+  }
+  const branches = [...(parsed.data.anyOf ?? []), ...(parsed.data.oneOf ?? [])].map(
+    requiredProperties
+  );
+  for (const name of branches[0] ?? []) {
+    if (branches.every(branch => branch.has(name))) {
+      required.add(name);
+    }
+  }
+  return required;
+}
+
+function acceptsType(schema: unknown, types: string[]): boolean {
+  const node = SchemaNode.safeParse(schema);
+  if (!node.success) {
+    return false;
+  }
+  const own = [node.data.type ?? []].flat();
+  return (
+    own.some(type => types.includes(type)) ||
+    [...(node.data.anyOf ?? []), ...(node.data.oneOf ?? [])].some(child =>
+      acceptsType(child, types)
+    )
+  );
+}
+
+function coerce(value: string, schemas: unknown[]): unknown {
+  if (/^[[{]/.test(value) && schemas.some(schema => acceptsType(schema, ['array', 'object']))) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+  if (NUMBER.test(value) && schemas.some(schema => acceptsType(schema, ['number', 'integer']))) {
+    return Number(value);
+  }
+  if (
+    (value === 'true' || value === 'false') &&
+    schemas.some(schema => acceptsType(schema, ['boolean']))
+  ) {
+    return value === 'true';
+  }
+  return value;
+}
+
+export function formatHostActionUsage(name: string, entry: HostActionCatalogEntry): string {
+  const required = requiredProperties(entry);
+  const alternatives = (entry.anyOf ?? entry.oneOf ?? []).map(branch =>
+    [...requiredProperties(branch)].filter(
+      property => property !== 'udid' && !required.has(property)
+    )
+  );
+  const requiredAlternatives =
+    alternatives.length > 0 && alternatives.every(properties => properties.length === 1)
+      ? alternatives.map(([property]) => property)
+      : [];
+  let describedAlternatives = false;
+  const names = positionalNames(entry).flatMap(property => {
+    if (requiredAlternatives.includes(property)) {
+      if (describedAlternatives) {
+        return [];
+      }
+      describedAlternatives = true;
+      return [
+        `<${requiredAlternatives.map(name => (name === property ? name : `${name}=...`)).join('|')}>`,
+      ];
+    }
+    return [required.has(property) ? `<${property}>` : `[${property}]`];
+  });
+  return [name, ...names].join(' ');
+}
+
+export function buildHostActionParams(
+  name: string,
+  entry: HostActionCatalogEntry,
+  values: string[]
+): Record<string, unknown> {
+  const properties = hostActionProperties(entry);
+  const params: Record<string, unknown> = {};
+  const positional: string[] = [];
+  for (const value of values) {
+    const named = NAMED_VALUE.exec(value);
+    if (!named || !properties.has(named[1])) {
+      positional.push(value);
+    } else if (Object.hasOwn(params, named[1])) {
+      throw new Error(`${named[1]} is given twice for ${name}.`);
+    } else {
+      params[named[1]] = coerce(named[2], properties.get(named[1]) ?? []);
+    }
+  }
+  const open = positionalNames(entry).filter(property => !Object.hasOwn(params, property));
+  if (positional.length > open.length) {
+    throw new Error(
+      `Too many values for ${name}. Usage: eas simulator:control ${formatHostActionUsage(name, entry)}. Name a value with name=value.`
+    );
+  }
+  positional.forEach((value, index) => {
+    params[open[index]] = coerce(value, properties.get(open[index]) ?? []);
+  });
+  return params;
+}
+
+export async function assertHostActionOutputAsync(
+  name: string,
+  entry: HostActionCatalogEntry,
+  outputPath: string | undefined
+): Promise<void> {
+  if (!outputPath) {
+    if (entry.output === 'base64') {
+      throw new Error(`${name} returns a file. Pass --output with the path to save it to.`);
+    }
+    return;
+  }
+  if (!entry.output) {
+    throw new Error(`${name} does not return a file, so --output does not apply.`);
+  }
+  if ((await fs.stat(outputPath).catch(() => null))?.isDirectory()) {
+    if (entry.output === 'base64') {
+      throw new Error(`${outputPath} is a folder. Pass --output with a file path for ${name}.`);
+    }
+    return;
+  }
+  const folder = await fs.stat(path.dirname(outputPath)).catch(() => null);
+  if (outputPath.endsWith('/') || outputPath.endsWith(path.sep) || !folder?.isDirectory()) {
+    throw new Error(
+      `The folder for ${outputPath} does not exist. Create it, or pass --output with a path in a folder that exists.`
+    );
+  }
+}
+
+export async function uploadFileAsync(
+  connection: HostActionConnection,
+  localPath: string,
+  { chunkBytes = UPLOAD_CHUNK_BYTES }: { chunkBytes?: number } = {}
+): Promise<{ uploadId: string; path: string }> {
+  const uploadId = `eas-cli-${randomUUID()}${path.extname(localPath).replace(/[^A-Za-z0-9.]/g, '')}`;
+  let remotePath = '';
+  let first = true;
+  try {
+    for await (const chunk of fs.createReadStream(localPath, { highWaterMark: chunkBytes })) {
+      const result = await connection.requestAsync('upload.append', {
+        uploadId,
+        data: Buffer.from(chunk).toString('base64'),
+        first,
+      });
+      if (result.exitCode !== 0) {
+        throw new Error(`Could not upload ${localPath}: ${result.stderr.trim()}`);
+      }
+      remotePath = result.stdout.trim();
+      first = false;
+    }
+  } catch (error) {
+    await connection.requestAsync('upload.remove', { uploadId }).catch(() => {});
+    throw error;
+  }
+  if (first) {
+    throw new Error(`${localPath} is empty. Pass a file with content.`);
+  }
+  return { uploadId, path: remotePath };
+}
+
+export async function saveHostActionOutputAsync(
+  connection: HostActionConnection,
+  entry: HostActionCatalogEntry,
+  stdout: string,
+  outputPath: string | undefined
+): Promise<string | null> {
+  if (!entry.output) {
+    return null;
+  }
+  let base64 = stdout;
+  let defaultName: string | undefined;
+  if (entry.output === 'path') {
+    const remotePath = stdout.trim();
+    const file = await connection.requestAsync('file.readBase64', { path: remotePath });
+    if (file.exitCode !== 0) {
+      throw new Error(`Could not download ${remotePath}: ${file.stderr.trim()}`);
+    }
+    base64 = file.stdout;
+    defaultName = path.basename(remotePath);
+  }
+  const outputIsFolder = outputPath
+    ? (await fs.stat(outputPath).catch(() => null))?.isDirectory()
+    : false;
+  const generatedName = outputIsFolder || !outputPath ? defaultName : undefined;
+  const target = generatedName ? path.join(outputPath ?? '.', generatedName) : outputPath;
+  if (!target) {
+    throw new Error('Pass --output with a file path to save the file.');
+  }
+  try {
+    await fs.writeFile(target, Buffer.from(base64, 'base64'), {
+      flag: target === outputPath ? 'w' : 'wx',
+    });
+  } catch (error) {
+    if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST') {
+      throw new Error(`${target} already exists. Pass --output with a new path to save the file.`);
+    }
+    throw error;
+  }
+  return path.resolve(target);
+}

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

@@ -142,6 +142,25 @@ export function getLocalEgressConfig(
   };
 }
 
+export type PreviewApiAccess = {
+  apiUrl: string;
+  token: string;
+};
+
+export function getPreviewApiAccess(
+  remoteConfig: DeviceRunSessionRemoteConfig
+): PreviewApiAccess | null {
+  const token =
+    remoteConfig.__typename === 'ServeSimRunSessionRemoteConfig' ||
+    remoteConfig.__typename === 'WebPreviewOnlyRunSessionRemoteConfig'
+      ? remoteConfig.previewToken
+      : remoteConfig.webPreviewToken;
+  if (!remoteConfig.previewApiUrl || !token) {
+    return null;
+  }
+  return { apiUrl: remoteConfig.previewApiUrl, token };
+}
+
 /** The worker relay that the Android emulator's proxy points at; see build-tools androidLocalEgress.ts. */
 export const ANDROID_EMULATOR_EGRESS_RELAY_PORT = 8898;
 

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

@@ -87,13 +87,23 @@ export default class SessionManager {
     await this.setSessionAsync(undefined);
   }
 
-  public async getUserAsync(): Promise<Actor | undefined> {
+  /**
+   * @param requestTimeoutMs caps the actor lookup when no actor is cached yet. Callers that must
+   * not delay a command past a deadline pass it; the default has no timeout. A capped lookup
+   * also skips the retry exchange, since a retry would double the wait.
+   */
+  public async getUserAsync({ requestTimeoutMs }: { requestTimeoutMs?: number } = {}): Promise<
+    Actor | undefined
+  > {
     if (!this.currentActor && (this.getAccessToken() || this.getSessionSecret())) {
       const authenticationInfo = {
         accessToken: this.getAccessToken(),
         sessionSecret: this.getSessionSecret(),
       };
-      const actor = await UserQuery.currentUserAsync(createGraphqlClient(authenticationInfo));
+      const actor = await UserQuery.currentUserAsync(
+        createGraphqlClient(authenticationInfo, { requestTimeoutMs }),
+        { noRetry: requestTimeoutMs !== undefined }
+      );
       this.currentActor = actor ?? undefined;
       if (actor) {
         this.analytics.setActor(actor);

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

@@ -5,6 +5,8 @@ import path from 'path';
 import { ApiV2Error } from '../../ApiV2Error';
 import { AnalyticsWithOrchestration } from '../../analytics/AnalyticsManager';
 import { ApiV2Client } from '../../api';
+import { createGraphqlClient } from '../../commandUtils/context/contextUtils/createGraphqlClient';
+import { UserQuery } from '../../graphql/queries/UserQuery';
 import Log from '../../log';
 import { promptAsync } from '../../prompts';
 import { getStateJsonPath } from '../../utils/paths';
@@ -17,16 +19,17 @@ jest.mock('../../log');
 jest.mock('fs');
 jest.mock('../../graphql/queries/UserQuery', () => ({
   UserQuery: {
-    currentUserAsync: async () => ({
+    currentUserAsync: jest.fn(async () => ({
       __typename: 'User',
       username: 'USERNAME',
       id: 'USER_ID',
-    }),
+    })),
   },
 }));
 jest.mock('../fetchSessionSecretAndUser');
 jest.mock('../fetchSessionSecretAndUserFromBrowserAuthFlow');
 jest.mock('../../api');
+jest.mock('../../commandUtils/context/contextUtils/createGraphqlClient');
 
 const authStub: any = {
   sessionSecret: 'SESSION_SECRET',
@@ -41,6 +44,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(() => {
@@ -131,6 +135,36 @@ describe(SessionManager, () => {
       });
       expect(await sessionManager.getUserAsync()).toMatchObject({ __typename: 'User' });
     });
+
+    it('creates the GraphQL client without a timeout and keeps retries by default', async () => {
+      process.env.EXPO_TOKEN = 'accesstoken';
+      const sessionManager = new SessionManager(analytics);
+      await sessionManager.getUserAsync();
+      expect(createGraphqlClient).toHaveBeenCalledWith(
+        { accessToken: 'accesstoken', sessionSecret: null },
+        { requestTimeoutMs: undefined }
+      );
+      expect(jest.mocked(UserQuery.currentUserAsync).mock.calls[0][1]).toEqual({ noRetry: false });
+    });
+
+    it('forwards the request timeout to the GraphQL client and disables retries', async () => {
+      process.env.EXPO_TOKEN = 'accesstoken';
+      const sessionManager = new SessionManager(analytics);
+      await sessionManager.getUserAsync({ requestTimeoutMs: 1234 });
+      expect(createGraphqlClient).toHaveBeenCalledWith(
+        { accessToken: 'accesstoken', sessionSecret: null },
+        { requestTimeoutMs: 1234 }
+      );
+      expect(jest.mocked(UserQuery.currentUserAsync).mock.calls[0][1]).toEqual({ noRetry: true });
+    });
+
+    it('skips the request once an actor is cached', async () => {
+      process.env.EXPO_TOKEN = 'accesstoken';
+      const sessionManager = new SessionManager(analytics);
+      await sessionManager.getUserAsync();
+      await sessionManager.getUserAsync({ requestTimeoutMs: 1234 });
+      expect(createGraphqlClient).toHaveBeenCalledTimes(1);
+    });
   });
 
   describe('loginAsync', () => {

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

@@ -18,7 +18,12 @@ const now = Date.parse('2026-09-29T12:00:00Z');
 let directory: string;
 
 function manager(): SessionManager {
-  return new SessionManager({ logEvent: jest.fn(), setActor: jest.fn(), flushAsync: jest.fn() });
+  return new SessionManager({
+    logEvent: jest.fn(),
+    setActor: jest.fn(),
+    flushAsync: jest.fn(),
+    getDeviceId: jest.fn(),
+  });
 }
 
 async function startAsync(): Promise<string> {

packages/eas-json/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @expo/eas-json
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/eas-json/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/eas-json",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "description": "A library for interacting with eas.json",
   "homepage": "https://github.com/expo/eas-cli",
   "bugs": "https://github.com/expo/eas-cli/issues",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@babel/code-frame": "7.23.5",
-    "@expo/eas-build-job": "25.1.1",
+    "@expo/eas-build-job": "25.2.0",
     "chalk": "4.1.2",
     "env-string": "1.0.1",
     "fs-extra": "11.2.0",

packages/local-build-plugin/CHANGELOG.md

@@ -1,5 +1,9 @@
 # eas-cli-local-build-plugin
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/local-build-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eas-cli-local-build-plugin",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "description": "Tool for running EAS compatible builds on a local machine.",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
@@ -26,12 +26,12 @@
     "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\""
   },
   "dependencies": {
-    "@expo/build-tools": "25.1.1",
+    "@expo/build-tools": "25.2.0",
     "@expo/bunyan": "^4.0.1",
-    "@expo/eas-build-job": "25.1.1",
-    "@expo/logger": "25.1.1",
+    "@expo/eas-build-job": "25.2.0",
+    "@expo/logger": "25.2.0",
     "@expo/spawn-async": "^1.7.2",
-    "@expo/turtle-spawn": "25.1.1",
+    "@expo/turtle-spawn": "25.2.0",
     "chalk": "4.1.2",
     "env-paths": "^2.2.1",
     "fs-extra": "^11.2.0",

packages/logger/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @expo/logger
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/logger/package.json

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

packages/steps/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @expo/steps
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/steps/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/steps",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",
@@ -27,8 +27,8 @@
     "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\""
   },
   "dependencies": {
-    "@expo/eas-build-job": "25.1.1",
-    "@expo/logger": "25.1.1",
+    "@expo/eas-build-job": "25.2.0",
+    "@expo/logger": "25.2.0",
     "@expo/spawn-async": "^1.7.2",
     "arg": "^5.0.2",
     "fast-glob": "^3.3.2",

packages/template-file/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @expo/template-file
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/template-file/package.json

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

packages/turtle-spawn/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @expo/turtle-spawn
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/turtle-spawn/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/turtle-spawn",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "bugs": "https://github.com/expo/eas-cli/issues",
   "license": "BUSL-1.1",
   "author": "Expo <[email protected]>",
@@ -25,7 +25,7 @@
     "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\""
   },
   "dependencies": {
-    "@expo/logger": "25.1.1",
+    "@expo/logger": "25.2.0",
     "@expo/spawn-async": "^1.7.2"
   },
   "devDependencies": {

packages/worker/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @expo/worker
 
+## 25.2.0
+
+No changes in this release.
+
 ## 25.1.1
 
 No changes in this release.

packages/worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/worker",
-  "version": "25.1.1",
+  "version": "25.2.0",
   "private": true,
   "scripts": {
     "start": "yarn watch",
@@ -19,17 +19,17 @@
   },
   "dependencies": {
     "@babel/core": "7.24.7",
-    "@expo/build-tools": "25.1.1",
+    "@expo/build-tools": "25.2.0",
     "@expo/config-plugins": "55.0.7",
     "@expo/config-types": "55.0.5",
-    "@expo/eas-build-job": "25.1.1",
-    "@expo/logger": "25.1.1",
+    "@expo/eas-build-job": "25.2.0",
+    "@expo/logger": "25.2.0",
     "@expo/results": "1.0.0",
     "@expo/rudder-sdk-node": "1.1.1",
     "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "25.1.1",
-    "@expo/template-file": "25.1.1",
-    "@expo/turtle-spawn": "25.1.1",
+    "@expo/steps": "25.2.0",
+    "@expo/template-file": "25.2.0",
+    "@expo/turtle-spawn": "25.2.0",
     "@hapi/boom": "10.0.1",
     "check-disk-space": "3.4.0",
     "fast-glob": "3.3.2",

yarn.lock

@@ -2515,24 +2515,24 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@expo/build-tools@npm:25.1.1, @expo/build-tools@workspace:packages/build-tools":
+"@expo/build-tools@npm:25.2.0, @expo/build-tools@workspace:packages/build-tools":
   version: 0.0.0-use.local
   resolution: "@expo/build-tools@workspace:packages/build-tools"
   dependencies:
     "@expo/config": "npm:55.0.10"
     "@expo/config-plugins": "npm:55.0.7"
-    "@expo/downloader": "npm:25.1.1"
-    "@expo/eas-build-job": "npm:25.1.1"
+    "@expo/downloader": "npm:25.2.0"
+    "@expo/eas-build-job": "npm:25.2.0"
     "@expo/env": "npm:^0.4.0"
-    "@expo/logger": "npm:25.1.1"
+    "@expo/logger": "npm:25.2.0"
     "@expo/package-manager": "npm:1.9.10"
     "@expo/plist": "npm:^0.3.5"
     "@expo/repack-app": "npm:~0.9.0"
     "@expo/results": "npm:^1.0.0"
     "@expo/spawn-async": "npm:1.7.2"
-    "@expo/steps": "npm:25.1.1"
-    "@expo/template-file": "npm:25.1.1"
-    "@expo/turtle-spawn": "npm:25.1.1"
+    "@expo/steps": "npm:25.2.0"
+    "@expo/template-file": "npm:25.2.0"
+    "@expo/turtle-spawn": "npm:25.2.0"
     "@expo/xcpretty": "npm:^4.3.1"
     "@ngrok/ngrok": "npm:1.7.0"
     "@sentry/node": "npm:7.77.0"
@@ -2768,7 +2768,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@expo/downloader@npm:25.1.1, @expo/downloader@workspace:packages/downloader":
+"@expo/downloader@npm:25.2.0, @expo/downloader@workspace:packages/downloader":
   version: 0.0.0-use.local
   resolution: "@expo/downloader@workspace:packages/downloader"
   dependencies:
@@ -2784,13 +2784,13 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@expo/eas-build-job@npm:25.1.1, @expo/eas-build-job@workspace:packages/eas-build-job":
+"@expo/eas-build-job@npm:25.2.0, @expo/eas-build-job@workspace:packages/eas-build-job":
   version: 0.0.0-use.local
   resolution: "@expo/eas-build-job@workspace:packages/eas-build-job"
   dependencies:
-    "@expo/logger": "npm:25.1.1"
+    "@expo/logger": "npm:25.2.0"
     "@expo/results": "npm:1.0.0"
-    "@expo/turtle-spawn": "npm:25.1.1"
+    "@expo/turtle-spawn": "npm:25.2.0"
     "@types/jest": "npm:^29.5.12"
     "@types/node": "npm:22.20.5"
     jest: "npm:^29.7.0"
@@ -2803,12 +2803,12 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@expo/eas-json@npm:25.1.1, @expo/eas-json@workspace:packages/eas-json":
+"@expo/eas-json@npm:25.2.0, @expo/eas-json@workspace:packages/eas-json":
   version: 0.0.0-use.local
   resolution: "@expo/eas-json@workspace:packages/eas-json"
   dependencies:
     "@babel/code-frame": "npm:7.23.5"
-    "@expo/eas-build-job": "npm:25.1.1"
+    "@expo/eas-build-job": "npm:25.2.0"
     "@tsconfig/node22": "npm:22.0.6"
     "@types/babel__code-frame": "npm:7.0.3"
     "@types/fs-extra": "npm:11.0.4"
@@ -2854,6 +2854,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@expo/experimentation@npm:0.0.5":
+  version: 0.0.5
+  resolution: "@expo/experimentation@npm:0.0.5"
+  dependencies:
+    nullthrows: "npm:^1.1.1"
+  checksum: 10c0/bc054e1bcc0583f2a09e8b56d2f95bb62cf2f4eaf78edac4eb709c73cfd1fdb93626b948f4184f6dc8096a44b6c12c97109a84622bb56620484b4e61856007fd
+  languageName: node
+  linkType: hard
+
 "@expo/image-utils@npm:^0.7.6":
   version: 0.7.6
   resolution: "@expo/image-utils@npm:0.7.6"
@@ -2922,7 +2931,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@expo/logger@npm:25.1.1, @expo/logger@workspace:packages/logger":
+"@expo/logger@npm:25.2.0, @expo/logger@workspace:packages/logger":
   version: 0.0.0-use.local
   resolution: "@expo/logger@workspace:packages/logger"
   dependencies:
@@ -3122,12 +3131,12 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@expo/steps@npm:25.1.1, @expo/steps@workspace:packages/steps":
+"@expo/steps@npm:25.2.0, @expo/steps@workspace:packages/steps":
   version: 0.0.0-use.local
   resolution: "@expo/steps@workspace:packages/steps"
   dependencies:
-    "@expo/eas-build-job": "npm:25.1.1"
-    "@expo/logger": "npm:25.1.1"
+    "@expo/eas-build-job": "npm:25.2.0"
+    "@expo/logger": "npm:25.2.0"
     "@expo/spawn-async": "npm:^1.7.2"
     "@jest/globals": "npm:^29.7.0"
     "@types/jest": "npm:^29.5.12"
@@ -3153,7 +3162,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@expo/template-file@npm:25.1.1, @expo/template-file@workspace:packages/template-file":
+"@expo/template-file@npm:25.2.0, @expo/template-file@workspace:packages/template-file":
   version: 0.0.0-use.local
   resolution: "@expo/template-file@workspace:packages/template-file"
   dependencies:
@@ -3176,11 +3185,11 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@expo/turtle-spawn@npm:25.1.1, @expo/turtle-spawn@workspace:packages/turtle-spawn":
+"@expo/turtle-spawn@npm:25.2.0, @expo/turtle-spawn@workspace:packages/turtle-spawn":
   version: 0.0.0-use.local
   resolution: "@expo/turtle-spawn@workspace:packages/turtle-spawn"
   dependencies:
-    "@expo/logger": "npm:25.1.1"
+    "@expo/logger": "npm:25.2.0"
     "@expo/spawn-async": "npm:^1.7.2"
     "@types/jest": "npm:^29.5.12"
     "@types/node": "npm:22.20.5"
@@ -3196,17 +3205,17 @@ __metadata:
   resolution: "@expo/worker@workspace:packages/worker"
   dependencies:
     "@babel/core": "npm:7.24.7"
-    "@expo/build-tools": "npm:25.1.1"
+    "@expo/build-tools": "npm:25.2.0"
     "@expo/config-plugins": "npm:55.0.7"
     "@expo/config-types": "npm:55.0.5"
-    "@expo/eas-build-job": "npm:25.1.1"
-    "@expo/logger": "npm:25.1.1"
+    "@expo/eas-build-job": "npm:25.2.0"
+    "@expo/logger": "npm:25.2.0"
     "@expo/results": "npm:1.0.0"
     "@expo/rudder-sdk-node": "npm:1.1.1"
     "@expo/spawn-async": "npm:1.7.2"
-    "@expo/steps": "npm:25.1.1"
-    "@expo/template-file": "npm:25.1.1"
-    "@expo/turtle-spawn": "npm:25.1.1"
+    "@expo/steps": "npm:25.2.0"
+    "@expo/template-file": "npm:25.2.0"
+    "@expo/turtle-spawn": "npm:25.2.0"
     "@hapi/boom": "npm:10.0.1"
     "@types/babel__core": "npm:7.20.5"
     "@types/fs-extra": "npm:11.0.4"
@@ -10090,7 +10099,7 @@ __metadata:
   resolution: "create-eas-build-function@workspace:packages/create-eas-build-function"
   dependencies:
     "@expo/package-manager": "npm:1.9.10"
-    "@expo/steps": "npm:25.1.1"
+    "@expo/steps": "npm:25.2.0"
     "@jest/globals": "npm:^29.7.0"
     "@types/jest": "npm:^29.5.12"
     "@types/node": "npm:22.20.5"
@@ -10674,12 +10683,12 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "eas-cli-local-build-plugin@workspace:packages/local-build-plugin"
   dependencies:
-    "@expo/build-tools": "npm:25.1.1"
+    "@expo/build-tools": "npm:25.2.0"
     "@expo/bunyan": "npm:^4.0.1"
-    "@expo/eas-build-job": "npm:25.1.1"
-    "@expo/logger": "npm:25.1.1"
+    "@expo/eas-build-job": "npm:25.2.0"
+    "@expo/logger": "npm:25.2.0"
     "@expo/spawn-async": "npm:^1.7.2"
-    "@expo/turtle-spawn": "npm:25.1.1"
+    "@expo/turtle-spawn": "npm:25.2.0"
     "@types/fs-extra": "npm:^11.0.4"
     "@types/hapi__joi": "npm:^17.1.14"
     "@types/lodash": "npm:^4.17.4"
@@ -10733,11 +10742,12 @@ __metadata:
     "@expo/code-signing-certificates": "npm:0.0.5"
     "@expo/config": "npm:55.0.10"
     "@expo/config-plugins": "npm:55.0.7"
-    "@expo/eas-build-job": "npm:25.1.1"
-    "@expo/eas-json": "npm:25.1.1"
+    "@expo/eas-build-job": "npm:25.2.0"
+    "@expo/eas-json": "npm:25.2.0"
     "@expo/env": "npm:^1.0.0"
+    "@expo/experimentation": "npm:0.0.5"
     "@expo/json-file": "npm:8.3.3"
-    "@expo/logger": "npm:25.1.1"
+    "@expo/logger": "npm:25.2.0"
     "@expo/multipart-body-parser": "npm:2.0.0"
     "@expo/osascript": "npm:2.1.4"
     "@expo/package-manager": "npm:1.9.10"
@@ -10749,7 +10759,7 @@ __metadata:
     "@expo/results": "npm:1.0.0"
     "@expo/rudder-sdk-node": "npm:1.1.1"
     "@expo/spawn-async": "npm:1.7.2"
-    "@expo/steps": "npm:25.1.1"
+    "@expo/steps": "npm:25.2.0"
     "@expo/timeago.js": "npm:1.0.0"
     "@graphql-codegen/cli": "npm:6.3.1"
     "@graphql-codegen/introspection": "npm:5.0.2"