v27.3.0

[eas-build-job] Add Observe workflow event context (#4787 )
[worker][build-tools] Stop warmup in the background for jobs that do not use a warm Simulator (#4721 )
2026-11-14 17:50:32 -10:00 · 2026-11-02 19:28:08 +00:00 · 2026-11-02 13:57:12 -05:00 · 2026-11-02 10:56:53 -07:00 · 2026-10-30 15:47:16 -07:00 · 2026-10-30 05:51:23 -07:00
160 changed files with 13370 additions and 1042 deletions
@@ -19,7 +19,9 @@
      "@expo/downloader",
      "@expo/turtle-spawn",
      "@expo/template-file",
-      "create-eas-build-function"
+      "create-eas-build-function",
+      "@expo/vm-tools",
+      "@expo/simulator-launcher"
    ]
  ],
  "linked": [],
@@ -2,6 +2,52 @@

 This is the log of notable changes to EAS CLI and related packages.

+## [27.3.0](https://github.com/expo/eas-cli/releases/tag/v27.3.0) - 2026-11-02
+
+### 🎉 New features
+
+- [eas-build-job] Add optional Observe error context to workflow jobs. ([#4787](https://github.com/expo/eas-cli/pull/4787) by [@AbbanMustafa](https://github.com/AbbanMustafa))
+
+### 🐛 Bug fixes
+
+- [eas-cli] Bump `@expo/apple-utils` to `2.3.0` to fix iOS capability sync when App Store Connect rejects enabling, disabling or changing a capability. ([#4790](https://github.com/expo/eas-cli/pull/4790) by [@douglowder](https://github.com/douglowder))
+- [eas-cli] Keep already linked App Groups, Merchant IDs and iCloud containers when capability sync links another identifier. ([#4584](https://github.com/expo/eas-cli/pull/4584) by [@ceydaakin](https://github.com/ceydaakin))
+- [worker] Mask secrets in every record the worker process writes to its stdout: the build log records and the worker's own records. ([#4782](https://github.com/expo/eas-cli/pull/4782) by [@hSATAC](https://github.com/hSATAC))
+- [worker][build-tools] Stop warmup in the background for jobs that do not use the warm Simulator, so job setup does not wait for it. Before build-tools boots or clones a Simulator, it waits until the launcher's state file records that cleanup finished, and fails if cleanup does not finish in time. ([#4721](https://github.com/expo/eas-cli/pull/4721) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Recover unhealthy device-session tunnels without changing their URLs and block further traffic when shutdown starts, even if ngrok cleanup times out. ([#4526](https://github.com/expo/eas-cli/pull/4526) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Stop sending the SSH host when registering an SSH session. ([#4784](https://github.com/expo/eas-cli/pull/4784) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+## [27.2.0](https://github.com/expo/eas-cli/releases/tag/v27.2.0) - 2026-10-29
+
+### 🎉 New features
+
+- [build-tools] Use single-device previews when the session already has a valid device ID. ([#4733](https://github.com/expo/eas-cli/pull/4733) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Add an experiment that suggests Expo Update to coding agents after a build when the Free plan account is within 5 builds of the platform limit. ([#4758](https://github.com/expo/eas-cli/pull/4758) by [@williamgrosset](https://github.com/williamgrosset))
+- [eas-cli] Add `eas observe:traces` to list request trace spans (or a summary of span names and counts), `eas observe:trace` to display one trace as a span tree, and span rows in the `eas observe:session` timeline. ([#4772](https://github.com/expo/eas-cli/pull/4772) by [@kadikraman](https://github.com/kadikraman))
+- [simulator-launcher] Accept a comma-separated list of warm Simulators in `EXPO_SIMULATOR_DEVICE`; the first is the default. One serve-sim serves every listed device on one port. After the default device is ready, warmup preinstalls the latest stable Expo Go from one download and tries to disable apsd on the other devices, until a job claims one. A claim can select any listed device and reports its preinstalled Expo Go. ([#4764](https://github.com/expo/eas-cli/pull/4764) by [@gwdp](https://github.com/gwdp))
+- [simulator-launcher] Add `@expo/simulator-launcher`, which warms an iOS Simulator at VM boot and hands it to one EAS job (`start`, `claim`, `prepare-tools`, `stop`). ([#4722](https://github.com/expo/eas-cli/pull/4722) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Show a one-time Expo Simulators hint after a successful build. ([#4768](https://github.com/expo/eas-cli/pull/4768) by [@FiberJW](https://github.com/FiberJW))
+- [vm-tools] Add a macOS startup script loader that runs `/usr/local/share/vm-tools/startup.sh` once per VM boot. ([#4725](https://github.com/expo/eas-cli/pull/4725) by [@gwdp](https://github.com/gwdp))
+
+### 🐛 Bug fixes
+
+- [build-tools] Explain missing background task identifiers reported by App Store Connect. ([#3465](https://github.com/expo/eas-cli/pull/3465) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Explain App Store Connect NOT_AUTHORIZED responses in the shared API client. ([#3462](https://github.com/expo/eas-cli/pull/3462) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Explain App Store Connect UNEXPECTED_ERROR responses in the shared API client. ([#3467](https://github.com/expo/eas-cli/pull/3467) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] Explain missing app icons reported by App Store Connect, including codes 90022 and 90023, while preserving Apple’s validation details. ([#3466](https://github.com/expo/eas-cli/pull/3466) by [@sjchmiela](https://github.com/sjchmiela))
+- [build-tools] List failed Google Play commit attempts in order, including network failures, when the outcome is uncertain. ([#4660](https://github.com/expo/eas-cli/pull/4660) by [@sjchmiela](https://github.com/sjchmiela))
+- [worker] Run package-manager version queries in parallel during worker preparation. ([#4710](https://github.com/expo/eas-cli/pull/4710) by [@gwdp](https://github.com/gwdp))
+- [worker] Start the Xcode version check in the background during worker tool preparation. Apply the Xcode 26.0 upload workaround when the query finishes, without delaying job startup. ([#4707](https://github.com/expo/eas-cli/pull/4707) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Fix a five-minute cleanup delay when a device session is canceled during startup and its screen recorder fails before connecting. ([#4761](https://github.com/expo/eas-cli/pull/4761) by [@gwdp](https://github.com/gwdp))
+- [eas-cli] Remove the Free plan build limit guidance experiment for coding agents from `eas build`. ([#4757](https://github.com/expo/eas-cli/pull/4757) by [@williamgrosset](https://github.com/williamgrosset))
+- [worker] Allow jobs to skip installing the CocoaPods cache proxy with EAS_BUILD_DISABLE_COCOAPODS_CACHE_PLUGIN=1. ([#4709](https://github.com/expo/eas-cli/pull/4709) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Handle TURN requests for a stopped device session without reporting a warning. ([#4762](https://github.com/expo/eas-cli/pull/4762) by [@gwdp](https://github.com/gwdp))
+- [build-tools] Preserve indented and incomplete Xcode compiler errors in formatted build logs, including the final diagnostic when logging stops. ([#4365](https://github.com/expo/eas-cli/pull/4365) by [@sjchmiela](https://github.com/sjchmiela))
+
+### 🧹 Chores
+
+- [simulator-launcher] Add the state, request command and service helpers for the warm Simulator launcher. The package stays private until #4722 adds its CLI entry point. ([#4766](https://github.com/expo/eas-cli/pull/4766) by [@gwdp](https://github.com/gwdp))
+
 ## [27.1.0](https://github.com/expo/eas-cli/releases/tag/v27.1.0) - 2026-10-28

 ### 🎉 New features
@@ -1,4 +1,4 @@
 {
-  "STAGING": "26.0.0",
-  "PRODUCTION": "26.0.0"
+  "STAGING": "27.2.0",
+  "PRODUCTION": "27.2.0"
 }
@@ -1,5 +1,5 @@
 {
  "npmClient": "yarn",
-  "version": "27.1.0",
+  "version": "27.3.0",
  "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
@@ -1,5 +1,30 @@
 # @expo/build-tools

+## 27.3.0
+
+### Patch Changes
+
+- Stop warmup in the background for jobs that do not use the warm Simulator, so job setup does not wait for it. Before build-tools boots or clones a Simulator, it waits until the launcher's state file records that cleanup finished, and fails if cleanup does not finish in time. ([#4721](https://github.com/expo/eas-cli/pull/4721) by [@gwdp](https://github.com/gwdp))
+- Recover unhealthy device-session tunnels without changing their URLs and block further traffic when shutdown starts, even if ngrok cleanup times out. ([#4526](https://github.com/expo/eas-cli/pull/4526) by [@gwdp](https://github.com/gwdp))
+- Stop sending the SSH host when registering an SSH session. ([#4784](https://github.com/expo/eas-cli/pull/4784) by [@AHGIJMKLKKZNPJKQR](https://github.com/AHGIJMKLKKZNPJKQR))
+
+## 27.2.0
+
+### Minor Changes
+
+- Use single-device previews when the session already has a valid device ID. ([#4733](https://github.com/expo/eas-cli/pull/4733) by [@gwdp](https://github.com/gwdp))
+
+### Patch Changes
+
+- Explain missing background task identifiers reported by App Store Connect. ([#3465](https://github.com/expo/eas-cli/pull/3465) by [@sjchmiela](https://github.com/sjchmiela))
+- Explain App Store Connect NOT_AUTHORIZED responses in the shared API client. ([#3462](https://github.com/expo/eas-cli/pull/3462) by [@sjchmiela](https://github.com/sjchmiela))
+- Explain App Store Connect UNEXPECTED_ERROR responses in the shared API client. ([#3467](https://github.com/expo/eas-cli/pull/3467) by [@sjchmiela](https://github.com/sjchmiela))
+- Explain missing app icons reported by App Store Connect, including codes 90022 and 90023, while preserving Apple’s validation details. ([#3466](https://github.com/expo/eas-cli/pull/3466) by [@sjchmiela](https://github.com/sjchmiela))
+- List failed Google Play commit attempts in order, including network failures, when the outcome is uncertain. ([#4660](https://github.com/expo/eas-cli/pull/4660) by [@sjchmiela](https://github.com/sjchmiela))
+- Fix a five-minute cleanup delay when a device session is canceled during startup and its screen recorder fails before connecting. ([#4761](https://github.com/expo/eas-cli/pull/4761) by [@gwdp](https://github.com/gwdp))
+- Handle TURN requests for a stopped device session without reporting a warning. ([#4762](https://github.com/expo/eas-cli/pull/4762) by [@gwdp](https://github.com/gwdp))
+- Preserve indented and incomplete Xcode compiler errors in formatted build logs, including the final diagnostic when logging stops. ([#4365](https://github.com/expo/eas-cli/pull/4365) by [@sjchmiela](https://github.com/sjchmiela))
+
 ## 27.1.0

 ### Patch Changes
@@ -1,6 +1,6 @@
 {
  "name": "@expo/build-tools",
-  "version": "27.1.0",
+  "version": "27.3.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
  "author": "Expo <[email protected]>",
@@ -42,18 +42,18 @@
  "dependencies": {
    "@expo/config": "55.0.10",
    "@expo/config-plugins": "55.0.7",
-    "@expo/downloader": "27.1.0",
-    "@expo/eas-build-job": "27.1.0",
+    "@expo/downloader": "27.3.0",
+    "@expo/eas-build-job": "27.3.0",
    "@expo/env": "^0.4.0",
-    "@expo/logger": "27.1.0",
+    "@expo/logger": "27.3.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": "27.1.0",
-    "@expo/template-file": "27.1.0",
-    "@expo/turtle-spawn": "27.1.0",
-    "@expo/xcpretty": "^4.3.1",
+    "@expo/steps": "27.3.0",
+    "@expo/template-file": "27.3.0",
+    "@expo/turtle-spawn": "27.3.0",
+    "@expo/xcpretty": "^4.4.7",
    "@ngrok/ngrok": "1.7.0",
    "@sentry/node": "7.77.0",
    "@urql/core": "^6.0.1",
@@ -3,6 +3,7 @@ import { EventEmitter } from 'events';
 import spawnAsync from '@expo/spawn-async';
 import { ExpoRunFormatter } from '@expo/xcpretty';
 import fg from 'fast-glob';
+import { vol } from 'memfs';

 import { createMockLogger } from '../../__tests__/utils/logger';
 import { Sentry } from '../../sentry';
@@ -59,6 +60,47 @@ describe(XcodeBuildLogger, () => {
    expect(Sentry.capture).not.toHaveBeenCalled();
  });

+  it('flushes the final incomplete compiler error when the log reader is interrupted', async () => {
+    const { ExpoRunFormatter: RealFormatter } =
+      jest.requireActual<typeof import('@expo/xcpretty')>('@expo/xcpretty');
+    jest.mocked(ExpoRunFormatter.create).mockImplementation(RealFormatter.create);
+
+    let rejectReader!: (error: Error) => void;
+    const spawnPromise = Object.assign(
+      new Promise<never>((_resolve, reject) => {
+        rejectReader = reject;
+      }),
+      {
+        child: {
+          stdout,
+          kill: () =>
+            rejectReader(Object.assign(new Error('tail interrupted'), { signal: 'SIGINT' })),
+        },
+      }
+    );
+    jest.mocked(spawnAsync).mockReturnValue(spawnPromise as any);
+    const diagnostics =
+      '/project/First.swift:12:3: error: first compiler error\n' +
+      '    /project/Last.swift:20:4: error: final compiler error\n';
+    vol.fromJSON({ '/logs/build.log': diagnostics });
+    const logger = createMockLogger();
+    const buildLogger = new XcodeBuildLogger(logger, '/project');
+    await buildLogger.watchLogFiles('/logs');
+    stdout.emit('data', diagnostics);
+
+    await buildLogger.flush();
+
+    const output = jest
+      .mocked(logger.info)
+      .mock.calls.map(([line]) => String(line))
+      .join('\n');
+    expect(output).toContain('first compiler error');
+    expect(output).toContain('final compiler error');
+    expect(output).toContain('Last.swift:20:4');
+    expect(output).toContain('2 error(s)');
+    expect(output.match(/final compiler error/g)).toHaveLength(1);
+  });
+
  it('falls back to raw logs when the formatter throws', async () => {
    const logger = createMockLogger();
    await startWatchingAsync(logger);
@@ -80,9 +80,12 @@ export class XcodeBuildLogger {
          this.logger.info(data.toString());
        }
      });
-      await this.logReaderPromise;
-
-      this.logger.info(formatter.getBuildSummary());
+      try {
+        await this.logReaderPromise;
+      } finally {
+        // flush() interrupts tail, but the formatter may still hold a final compiler diagnostic.
+        this.logger.info(formatter.getBuildSummary());
+      }
    } catch (err: any) {
      if (!this.flushing) {
        this.loggerError = err;
@@ -382,6 +382,29 @@ describe('createStartAppiumRemoteSessionBuildFunction session lifecycle', () =>
    );
  }

+  it('passes the existing Android selection to the preview host', async () => {
+    stopAppium.mockResolvedValue(undefined);
+    await runSessionAsync(logger);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ previewDeviceId: 'emulator-5554' })
+    );
+  });
+
+  it('passes the selected iOS preview target without enabling Simulator startup', async () => {
+    stopAppium.mockResolvedValue(undefined);
+    const udid = 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA';
+    jest
+      .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+      .mockResolvedValue([{ udid }, { udid: 'BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB' }] as Awaited<
+        ReturnType<typeof IosSimulatorUtils.getAvailableDevicesAsync>
+      >);
+    await runSessionAsync(logger, undefined, BuildRuntimePlatform.DARWIN);
+    const options = jest.mocked(startDeviceSessionHostAsync).mock.calls[0][1];
+    expect(options).toHaveProperty('previewDeviceId', udid);
+    expect(options.iosSimulatorUdid).toBeUndefined();
+  });
+
  it.each([false, true])(
    'preserves preview settings with Simulator startup %s',
    async bootSimulator => {
@@ -198,7 +198,10 @@ it('does not delete the edit or publish outputs when commit outcome is unknown',
      return [204];
    });
  const task = submission();
-  await expect(task.run()).rejects.toBeInstanceOf(SystemError);
+  const error = await task.run().catch(error => error);
+  expect(error).toBeInstanceOf(SystemError);
+  expect((error as Error).message).toContain('HTTP 404');
+  expect((error as Error).message).toContain('Could not confirm whether Google Play saved');
  expect(deleted).toBe(false);
  expect(task.setters.every(set => set.mock.calls.length === 0)).toBe(true);
 });
@@ -8,6 +8,8 @@ import {
  createUploadToAscBuildFunction,
  isClosedVersionTrainError,
  isInvalidBundleIdentifierError,
+  isMissingAppIconsError,
+  isMissingBackgroundTaskIdentifiersError,
  isMissingPurposeStringError,
  isRedundantBinaryUploadError,
  isSdkVersionIssueError,
@@ -95,6 +97,41 @@ describe(isSdkVersionIssueError, () => {
  });
 });

+describe(isMissingBackgroundTaskIdentifiersError, () => {
+  it('returns true when all errors are missing BG task identifiers codes', () => {
+    expect(isMissingBackgroundTaskIdentifiersError([{ code: '90771' }, { code: '90771' }])).toBe(
+      true
+    );
+  });
+
+  it('returns false when any other error code is present', () => {
+    expect(isMissingBackgroundTaskIdentifiersError([{ code: '90771' }, { code: '90062' }])).toBe(
+      false
+    );
+  });
+
+  it('returns false when there are no errors', () => {
+    expect(isMissingBackgroundTaskIdentifiersError([])).toBe(false);
+  });
+});
+
+describe(isMissingAppIconsError, () => {
+  it.each([['90391', '90713', '90713'], ['90713', '90022', '90023'], ['90022'], ['90023']])(
+    'recognizes missing-icon validation codes %j',
+    (...codes) => {
+      expect(isMissingAppIconsError(codes.map(code => ({ code })))).toBe(true);
+    }
+  );
+
+  it('returns false when any other error code is present', () => {
+    expect(isMissingAppIconsError([{ code: '90391' }, { code: '90771' }])).toBe(false);
+  });
+
+  it('returns false when there are no errors', () => {
+    expect(isMissingAppIconsError([])).toBe(false);
+  });
+});
+
 describe(parseMissingUsageDescriptionKeys, () => {
  it('extracts missing UsageDescription keys from ASC messages', () => {
    expect(
@@ -191,3 +228,117 @@ describe(createUploadToAscBuildFunction, () => {
    }
  });
 });
+
+describe(createUploadToAscBuildFunction, () => {
+  it('keeps Apple background-task details in the public error and the full state as its cause', async () => {
+    const state = {
+      state: 'FAILED',
+      errors: [
+        {
+          code: '90771',
+          description:
+            'Missing BGTaskSchedulerPermittedIdentifiers while UIBackgroundModes includes processing.',
+        },
+      ],
+      warnings: [{ code: 'WARNING', description: 'Apple warning.' }],
+      infos: [{ code: 'INFO', description: 'Apple information.' }],
+    };
+    await fs.writeFile('/app.ipa', 'ipa');
+    await fs.writeFile('/key.json', '{}');
+    jest.spyOn(AscApiUtils, 'loadApiKeyAsync').mockResolvedValue({} as never);
+    jest.spyOn(AscApiUtils, 'getAppInfoAsync').mockResolvedValue({
+      data: { attributes: { name: 'App', bundleId: 'com.example.app' } },
+    } as never);
+    jest.spyOn(AscApiUtils, 'createBuildUploadAsync').mockResolvedValue({
+      data: { id: 'upload-id' },
+    } as never);
+    jest.spyOn(AscApiUtils, 'commitBuildUploadFileAsync').mockResolvedValue(undefined as never);
+    jest.spyOn(AscApiClient.prototype, 'postAsync').mockResolvedValue({
+      data: { id: 'file-id', attributes: { uploadOperations: [] } },
+    } as never);
+    jest
+      .spyOn(AscApiClient.prototype, 'getAsync')
+      .mockResolvedValueOnce({
+        data: { attributes: { assetDeliveryState: { state: 'COMPLETE' } } },
+      } as never)
+      .mockResolvedValueOnce({ data: { attributes: { state } } } as never);
+    try {
+      const step = createUploadToAscBuildFunction().createBuildStepFromFunctionCall(
+        createGlobalContextMock({ staticContextContent: { job: {} } }),
+        {
+          callInputs: {
+            ipa_path: '/app.ipa',
+            asc_api_key_path: '/key.json',
+            apple_app_identifier: 'app-id',
+            bundle_version: '1',
+            bundle_short_version: '1.0',
+            wait_for_processing: true,
+          },
+        }
+      );
+      const error = await step.executeAsync().catch(error => error);
+      expect(error).toBeInstanceOf(UserError);
+      expect(error.errorCode).toBe('EAS_UPLOAD_TO_ASC_MISSING_BG_TASK_IDENTIFIERS');
+      expect(error.cause).toEqual(state);
+      expect(error.toExternalExpoError().message).toContain(
+        'Missing BGTaskSchedulerPermittedIdentifiers while UIBackgroundModes includes processing. (90771)'
+      );
+    } finally {
+      jest.restoreAllMocks();
+    }
+  });
+});
+
+describe(createUploadToAscBuildFunction, () => {
+  it('keeps Apple validation details in the public error and the full state as its cause', async () => {
+    const state = {
+      state: 'FAILED',
+      errors: [{ code: '90713', description: 'Missing CFBundleIconName in Watch.app.' }],
+      warnings: [{ code: 'WARNING', description: 'Apple warning.' }],
+      infos: [{ code: 'INFO', description: 'Apple information.' }],
+    };
+    await fs.writeFile('/app.ipa', 'ipa');
+    await fs.writeFile('/key.json', '{}');
+    jest.spyOn(AscApiUtils, 'loadApiKeyAsync').mockResolvedValue({} as never);
+    jest.spyOn(AscApiUtils, 'getAppInfoAsync').mockResolvedValue({
+      data: { attributes: { name: 'App', bundleId: 'com.example.app' } },
+    } as never);
+    jest.spyOn(AscApiUtils, 'createBuildUploadAsync').mockResolvedValue({
+      data: { id: 'upload-id' },
+    } as never);
+    jest.spyOn(AscApiUtils, 'commitBuildUploadFileAsync').mockResolvedValue(undefined as never);
+    jest.spyOn(AscApiClient.prototype, 'postAsync').mockResolvedValue({
+      data: { id: 'file-id', attributes: { uploadOperations: [] } },
+    } as never);
+    jest
+      .spyOn(AscApiClient.prototype, 'getAsync')
+      .mockResolvedValueOnce({
+        data: { attributes: { assetDeliveryState: { state: 'COMPLETE' } } },
+      } as never)
+      .mockResolvedValueOnce({ data: { attributes: { state } } } as never);
+    try {
+      const step = createUploadToAscBuildFunction().createBuildStepFromFunctionCall(
+        createGlobalContextMock({ staticContextContent: { job: {} } }),
+        {
+          callInputs: {
+            ipa_path: '/app.ipa',
+            asc_api_key_path: '/key.json',
+            apple_app_identifier: 'app-id',
+            bundle_version: '1',
+            bundle_short_version: '1.0',
+            wait_for_processing: true,
+          },
+        }
+      );
+      const error = await step.executeAsync().catch(error => error);
+      expect(error).toBeInstanceOf(UserError);
+      expect(error.errorCode).toBe('EAS_UPLOAD_TO_ASC_MISSING_APP_ICONS');
+      expect(error.cause).toEqual(state);
+      expect(error.toExternalExpoError().message).toContain(
+        'Missing CFBundleIconName in Watch.app. (90713)'
+      );
+    } finally {
+      jest.restoreAllMocks();
+    }
+  });
+});
@@ -167,6 +167,7 @@ export async function runAgentDeviceRemoteSessionAsync(
      subdomainPrefix: 'agent-device',
      baseDomain: ngrokTunnelDomain,
      authtoken: ngrokAuthtoken,
+      healthCheck: { path: '/health' },
      logger: taskLogger,
    });
    tasks.signal.throwIfAborted();
@@ -157,6 +157,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
      const startHost = () =>
        startDeviceSessionHostAsync(ctx, {
          ...iosStartup,
+          previewDeviceId: device.udid,
          separateLogPhase: true,
          runtimePlatform,
          env,
@@ -273,11 +274,11 @@ export function createStartAppiumRemoteSessionBuildFunction(
          subdomainPrefix: 'appium',
          baseDomain: ngrokTunnelDomain,
          authtoken: ngrokAuthtoken,
+          healthCheck: { path: '/status' },
          logger,
        });

-        // expo-device-hub has no serial-selection flag. Device run session workflows must expose
-        // a single booted Android emulator so the Hub and Appium resolve the same device.
+        // The preview host uses the same device selected for Appium.
        const launchDescription = describeServeSimLaunch(launch);
        if (launchDescription) {
          logger.info(launchDescription);
@@ -340,6 +340,7 @@ export function createStartArgentRemoteSessionBuildFunction(
          baseDomain: ngrokTunnelDomain,
          authtoken: ngrokAuthtoken,
          rewriteHostHeader: true,
+          healthCheck: { path: '/tools', statuses: [200, 401] },
          logger,
        });
        const publicToolsUrl = toolsTunnel.url;
@@ -275,6 +275,32 @@ export function createUploadToAscBuildFunction(): BuildFunction {
              }
            );
          }
+          if (isMissingBackgroundTaskIdentifiersError(errors)) {
+            throw new UserError(
+              'EAS_UPLOAD_TO_ASC_MISSING_BG_TASK_IDENTIFIERS',
+              'Build upload was rejected by App Store Connect because Info.plist is missing `BGTaskSchedulerPermittedIdentifiers` while `UIBackgroundModes` includes `processing`. ' +
+                'In an Expo project, add `BGTaskSchedulerPermittedIdentifiers` to `ios.infoPlist` in your app config and include every background task identifier the app schedules. ' +
+                'If you do not use Continuous Native Generation (CNG), add the same key to the native target Info.plist. Then rebuild and submit again.' +
+                `\n\nApp Store Connect errors:\n${itemizeMessages(errors)}`,
+              {
+                docsUrl: 'https://docs.expo.dev/versions/latest/config/app/#infoplist',
+                cause: state,
+              }
+            );
+          }
+          if (isMissingAppIconsError(errors)) {
+            throw new UserError(
+              'EAS_UPLOAD_TO_ASC_MISSING_APP_ICONS',
+              'Build upload was rejected by App Store Connect because required app icons are missing or misconfigured in one of the iOS bundles. ' +
+                'In an Expo project, check your icon config (`expo.icon`, `ios.icon`) and any custom native targets or plugins that create extra bundles, such as watch extensions. ' +
+                'Make sure the affected target has the required icon assets and Info.plist icon keys (for example `CFBundleIconName` / `CFBundleIconFiles`), then rebuild and submit again.' +
+                `\n\nApp Store Connect errors:\n${itemizeMessages(errors)}`,
+              {
+                docsUrl: 'https://docs.expo.dev/develop/user-interface/splash-screen-and-app-icon/',
+                cause: state,
+              }
+            );
+          }
          if (isInvalidBundleIdentifierError(errors)) {
            const ipaInfoResult = await asyncResult(readIpaInfoAsync(ipaPath));
            const ipaBundleIdentifier = ipaInfoResult.ok
@@ -361,6 +387,17 @@ export function isRedundantBinaryUploadError(messages: { code: string }[]): bool
  return messages.length > 0 && messages.every(message => message.code === '90189');
 }

+export function isMissingBackgroundTaskIdentifiersError(messages: { code: string }[]): boolean {
+  return messages.length > 0 && messages.every(message => message.code === '90771');
+}
+
+export function isMissingAppIconsError(messages: { code: string }[]): boolean {
+  return (
+    messages.length > 0 &&
+    messages.every(message => ['90022', '90023', '90391', '90713'].includes(message.code))
+  );
+}
+
 export function isInvalidBundleIdentifierError(messages: { code: string }[]): boolean {
  return (
    messages.length > 0 && messages.every(message => ['90054', '90055'].includes(message.code))
@@ -36,7 +36,7 @@ const SERVE_SIM_LEASE_FINALIZE_TIMEOUT_MS =
 const SERVE_SIM_FINISH_TIMEOUT_MS =
  SERVE_SIM_CONTROL_REQUEST_TIMEOUT_MS + SERVE_SIM_LEASE_FINALIZE_TIMEOUT_MS;
 const SERVE_SIM_FORCE_STOP_TIMEOUT_MS = 5_000;
-const SERVE_SIM_RECORDING_STARTED = 'serve-sim:recording-started';
+const SERVE_SIM_RECORDING_STARTED_LINE = /(?:^|\n)serve-sim:recording-started\r?\n/;
 // The serve-sim package the session host started; every recorder runs `record-video` from it.
 let serveSimPackageSpec: string | null = null;

@@ -507,14 +507,19 @@ function captureProcessOutput(recordingProcess: ChildProcess): {
 } {
  let output = '';
  let started = false;
-  const appendChunk = (chunk: Buffer | string): void => {
-    output = `${output}${chunk.toString()}`;
-    if (output.includes(SERVE_SIM_RECORDING_STARTED)) {
-      started = true;
-    }
-    output = output.slice(-16_384);
+  const captureStreamOutput = (stream: ChildProcess['stdout']): void => {
+    let streamOutput = '';
+    stream?.on('data', (chunk: Buffer | string) => {
+      const text = chunk.toString();
+      output = `${output}${text}`.slice(-16_384);
+      streamOutput = `${streamOutput}${text}`;
+      if (SERVE_SIM_RECORDING_STARTED_LINE.test(streamOutput)) {
+        started = true;
+      }
+      streamOutput = streamOutput.slice(-16_384);
+    });
  };
-  recordingProcess.stdout?.on('data', appendChunk);
-  recordingProcess.stderr?.on('data', appendChunk);
+  captureStreamOutput(recordingProcess.stdout);
+  captureStreamOutput(recordingProcess.stderr);
  return { getOutput: () => output, hasStarted: () => started };
 }
@@ -144,7 +144,10 @@ test('starts serve-sim record-video and returns only a finalized recording', asy
  const finishing = IosSimulatorRecordingUtils.finishAsync({ logger });
  await setTimeout(20);
  expect(child.kill).not.toHaveBeenCalled();
-  stderr.write('serve-sim:recording-started\n');
+  child.stdout?.emit('data', 'Downloading');
+  stderr.write('serve-sim:recording-');
+  child.stdout?.emit('data', ' package');
+  stderr.write('started\r\n');
  stderr.write('x'.repeat(17_000));
  const recordings = await finishing;

@@ -362,6 +365,32 @@ test('keeps a recorder active after its package-manager wrapper exits', async ()
  expect(recordings).toHaveLength(1);
 });

+test('does not mistake bundled source in an error for a recording start', async () => {
+  let currentTime = Date.now();
+  jest.spyOn(Date, 'now').mockImplementation(() => currentTime);
+  jest
+    .mocked(readServeSimServersAsync)
+    .mockResolvedValue([{ udid, url: 'http://127.0.0.1:43563', token: 'session-token' }]);
+  const recorder = mockRecorder();
+
+  await IosSimulatorRecordingUtils.startAsync({ env, logger });
+  await waitForRecorderSpawnAsync();
+  recorder.child.stderr?.emit(
+    'data',
+    'const marker = "serve-sim:recording-started";\nError: No running serve-sim session found.\n'
+  );
+  recorder.fail(new Error('recorder exited before connecting'));
+
+  const finishing = IosSimulatorRecordingUtils.finishAsync({ logger });
+  try {
+    expect(await Promise.race([finishing.then(() => true), setTimeout(250, false)])).toBe(true);
+  } finally {
+    currentTime += 311_000;
+    await finishing;
+  }
+  expect(recorder.child.kill).not.toHaveBeenCalled();
+});
+
 test('does not signal a recorder that exits before it reports its start', async () => {
  let currentTime = Date.now();
  jest.spyOn(Date, 'now').mockImplementation(() => currentTime);
@@ -7,6 +7,7 @@ import { setImmediate } from 'node:timers/promises';

 import { type CustomBuildContext } from '../../../customBuildContext';
 import RemoteLoggerStream from '../../../logging/RemoteLoggerStream';
+import { Sentry } from '../../../sentry';
 import { turtleFetch } from '../../../utils/turtleFetch';
 import { downloadBuildAsync } from '../../functions/downloadBuild';
 import { uploadDeviceRunSessionArtifactAsync } from '../deviceRunSessionArtifacts';
@@ -266,6 +267,48 @@ describe('with a device run session token', () => {
    expect(jest.mocked(turtleFetch)).toHaveBeenCalledTimes(1);
  });

+  it('handles a stopped-session TURN response without a warning or retry', async () => {
+    const ctx = createCtx({ withToken: true });
+    jest
+      .mocked(turtleFetch)
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { errors: [{ code: 'DEVICE_RUN_SESSION_ALREADY_STOPPED', message: 'Stopped.' }] },
+          400
+        )
+      );
+
+    await expect(fetchWebPreviewTurnArgsAsync(ctx, { logger })).resolves.toEqual([]);
+
+    expect(logger.info).toHaveBeenCalledWith(
+      'Device run session was stopped before TURN credentials were fetched.'
+    );
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(Sentry.capture).not.toHaveBeenCalled();
+    expect(turtleFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([undefined, 'VALIDATION_ERROR'])(
+    'still warns on a TURN failure with code %s',
+    async code => {
+      const ctx = createCtx({ withToken: true });
+      jest
+        .mocked(turtleFetch)
+        .mockResolvedValueOnce(
+          jsonResponse(
+            { errors: [{ code, message: 'Device run session has already stopped.' }] },
+            400
+          )
+        );
+
+      await expect(fetchWebPreviewTurnArgsAsync(ctx, { logger })).resolves.toEqual([]);
+
+      expect(logger.warn).toHaveBeenCalled();
+      expect(Sentry.capture).toHaveBeenCalled();
+      expect(turtleFetch).toHaveBeenCalledTimes(1);
+    }
+  );
+
  it('creates artifact upload sessions through the worker API', async () => {
    const ctx = createCtx({ withToken: true });
    jest.mocked(turtleFetch).mockResolvedValueOnce(
@@ -24,6 +24,7 @@ import {
  uploadDeviceRunSessionScreenRecordingsAsync,
 } from '../deviceRunSessionScreenRecordings';
 import {
+  captureDeviceRunSessionPreviewAsync,
  ensureMacosPreviewEncoderInstalledAsync,
  startDeviceRunSessionPreview,
 } from '../deviceRunSessionPreview';
@@ -68,6 +69,7 @@ jest.mock('../remoteDeviceRunSession', () => ({
 jest.mock('../deviceRunSessionPreview', () => ({
  ...jest.requireActual('../deviceRunSessionPreview'),
  ensureMacosPreviewEncoderInstalledAsync: jest.fn(),
+  captureDeviceRunSessionPreviewAsync: jest.fn(),
  startDeviceRunSessionPreview: jest.fn(),
 }));
 jest.mock('../deviceRunSessionScreenRecordings', () => ({
@@ -191,6 +193,91 @@ afterEach(async () => {
  );
 });

+it.each([undefined, '', 'invalid serial', 'all', 'booted'])(
+  'starts Hub without adding a device restriction for %j',
+  async previewDeviceId => {
+    const host = await startDeviceSessionHostAsync(ctx, {
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      env,
+      logger,
+      timeoutMs: 10_000,
+      previewDeviceId,
+    });
+    try {
+      expect(jest.mocked(spawnDetached).mock.calls[0][0].args).not.toContain('--single-device');
+    } finally {
+      await host.finishAsync();
+    }
+  }
+);
+
+it('uses the supplied Android serial for Hub and thumbnails without selecting another device', async () => {
+  jest.mocked(turtleFetch).mockResolvedValue({
+    ok: true,
+    json: async () => ({ status: 'ready', device: 'no-device-id' }),
+  } as Awaited<ReturnType<typeof turtleFetch>>);
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.LINUX,
+    env,
+    logger,
+    timeoutMs: 10_000,
+    previewDeviceId: 'emulator-5556',
+  });
+  try {
+    const args = jest.mocked(spawnDetached).mock.calls[0][0].args;
+    expect(
+      args.slice(args.indexOf('--single-device'), args.indexOf('--single-device') + 2)
+    ).toEqual(['--single-device', 'emulator-5556']);
+    await new Promise(resolve => setImmediate(resolve));
+    await jest
+      .mocked(startDeviceRunSessionPreview)
+      .mock.calls[0][0].captureAsync(new AbortController().signal);
+    expect(captureDeviceRunSessionPreviewAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ device: 'emulator-5556' })
+    );
+  } finally {
+    await host.finishAsync();
+  }
+});
+
+it('pins an already-booted iOS preview without taking over boot or setup', async () => {
+  const udid = 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA';
+  jest.mocked(turtleFetch).mockResolvedValue({
+    ok: true,
+    json: async () => ({ status: 'ready', device: udid }),
+  } as Awaited<ReturnType<typeof turtleFetch>>);
+  const host = await startDeviceSessionHostAsync(ctx, {
+    runtimePlatform: BuildRuntimePlatform.DARWIN,
+    env,
+    logger,
+    timeoutMs: 10_000,
+    previewDeviceId: udid,
+  });
+  try {
+    const args = jest.mocked(spawnDetached).mock.calls[0][0].args;
+    expect(
+      args.slice(args.indexOf('--single-device'), args.indexOf('--single-device') + 2)
+    ).toEqual(['--single-device', udid]);
+    expect(IosSimulatorUtils.disableApsdAsync).not.toHaveBeenCalled();
+    expect(runServeSimActionAsync).not.toHaveBeenCalled();
+  } finally {
+    await host.finishAsync();
+  }
+});
+
+it('rejects readiness on a different Simulator from the selected preview target', async () => {
+  await expect(
+    startDeviceSessionHostAsync(ctx, {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      env,
+      logger,
+      timeoutMs: 10_000,
+      previewDeviceId: 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA',
+    })
+  ).rejects.toThrow('but this session requested AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA');
+  expect(stopServer).toHaveBeenCalled();
+});
+
 it('targets the selected Simulator in the serve-sim invocation', () => {
  expect(createServeSimArgs({ port: 4321, iosSimulatorUdid: 'session-udid' }).slice(0, 4)).toEqual([
    '@expo/serve-sim@latest',
@@ -0,0 +1,873 @@
+import { type bunyan } from '@expo/logger';
+import * as ngrok from '@ngrok/ngrok';
+import { once } from 'node:events';
+import { createServer } from 'node:http';
+import WebSocket, { WebSocketServer } from 'ws';
+import { type AddressInfo, createConnection, createServer as createTcpServer } from 'node:net';
+
+import { turtleFetch } from '../../../utils/turtleFetch';
+import { startNgrokTunnelAsync } from '../ngrokTunnel';
+
+jest.mock('@ngrok/ngrok');
+jest.mock('node:timers', () => ({
+  setTimeout: (...args: Parameters<typeof setTimeout>) => setTimeout(...args),
+  clearTimeout: (...args: Parameters<typeof clearTimeout>) => clearTimeout(...args),
+}));
+jest.mock('../../../utils/turtleFetch');
+
+const { Response } = jest.requireActual<typeof import('node-fetch')>('node-fetch');
+const url = 'https://web-preview-fixed.example.test';
+const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
+const options = {
+  port: 4321,
+  subdomainPrefix: 'web-preview',
+  subdomainId: 'fixed',
+  baseDomain: 'example.test',
+  authtoken: 'token',
+  rewriteHostHeader: true,
+  healthCheck: { path: '/healthz' },
+  logger,
+};
+
+function listener(publicUrl = url) {
+  return { url: () => publicUrl, close: jest.fn().mockResolvedValue(undefined) };
+}
+
+let initial: ReturnType<typeof listener>;
+let replacement: ReturnType<typeof listener>;
+
+beforeEach(() => {
+  jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate'] });
+  jest.clearAllMocks();
+  initial = listener();
+  replacement = listener();
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockResolvedValue(replacement as never);
+  jest
+    .mocked(turtleFetch)
+    .mockReset()
+    .mockResolvedValue(new Response(undefined, { status: 200 }));
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+function failPublicProbes() {
+  jest.mocked(turtleFetch).mockImplementation(
+    async target =>
+      new Response(undefined, {
+        status: target.startsWith('https:') ? 503 : 200,
+      })
+  );
+}
+
+it('keeps tunnels without a health check unsupervised and closes them on stop', async () => {
+  const tunnel = await startNgrokTunnelAsync({ ...options, healthCheck: undefined });
+  await jest.advanceTimersByTimeAsync(90_000);
+  expect(turtleFetch).not.toHaveBeenCalled();
+  expect(ngrok.forward).toHaveBeenCalledTimes(1);
+  await tunnel.stopAsync();
+  expect(initial.close).toHaveBeenCalledTimes(1);
+});
+
+it('probes the public service and keeps a healthy listener open', async () => {
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(45_000);
+    expect(turtleFetch).toHaveBeenCalledTimes(3);
+    expect(turtleFetch).toHaveBeenCalledWith(
+      `${url}/healthz`,
+      'GET',
+      expect.objectContaining({
+        retries: 0,
+        redirect: 'manual',
+        headers: expect.objectContaining({ 'ngrok-skip-browser-warning': 'true' }),
+      })
+    );
+    expect(ngrok.forward).toHaveBeenCalledTimes(1);
+  } finally {
+    await tunnel.stopAsync();
+  }
+  expect(initial.close).toHaveBeenCalledTimes(1);
+  await jest.advanceTimersByTimeAsync(60_000);
+  expect(turtleFetch).toHaveBeenCalledTimes(3);
+});
+
+it('reopens after three failed public probes with a healthy local service, preserving the endpoint', async () => {
+  failPublicProbes();
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(30_000);
+    expect(initial.close).not.toHaveBeenCalled();
+    await jest.advanceTimersByTimeAsync(15_000);
+    expect(initial.close).toHaveBeenCalledTimes(1);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(ngrok.forward).mock.calls[1][0]).toEqual({
+      addr: expect.any(Number),
+      authtoken: 'token',
+      domain: 'web-preview-fixed.example.test',
+      request_header_add: ['Host:localhost:4321'],
+      force_new_session: true,
+    });
+    expect(tunnel.url).toBe(url);
+    jest.mocked(turtleFetch).mockResolvedValue(new Response(undefined, { status: 200 }));
+    await jest.advanceTimersByTimeAsync(15_000);
+    expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('healthy again'));
+  } finally {
+    await tunnel.stopAsync();
+  }
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+});
+
+it('does not reopen when the local service is unhealthy', async () => {
+  jest.mocked(turtleFetch).mockResolvedValue(new Response(undefined, { status: 503 }));
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(90_000);
+    expect(ngrok.forward).toHaveBeenCalledTimes(1);
+    expect(initial.close).not.toHaveBeenCalled();
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('resets consecutive failures after a successful public probe', async () => {
+  failPublicProbes();
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(30_000);
+    jest.mocked(turtleFetch).mockResolvedValueOnce(new Response(undefined, { status: 200 }));
+    await jest.advanceTimersByTimeAsync(15_000);
+    await jest.advanceTimersByTimeAsync(30_000);
+    expect(ngrok.forward).toHaveBeenCalledTimes(1);
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('retries a failed reopen with backoff', async () => {
+  failPublicProbes();
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockRejectedValueOnce(new Error('offline'))
+    .mockResolvedValue(replacement as never);
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(45_000);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+    await jest.advanceTimersByTimeAsync(1_999);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+    await jest.advanceTimersByTimeAsync(1);
+    expect(ngrok.forward).toHaveBeenCalledTimes(3);
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('closes a listener that finishes opening after shutdown, with idempotent cleanup', async () => {
+  failPublicProbes();
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(
+      new Promise(resolve => {
+        resolveOpening = resolve;
+      })
+    );
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  const stopping = tunnel.stopAsync();
+  expect(tunnel.stopAsync()).toBe(stopping);
+  const stopped = jest.fn();
+  void stopping.then(stopped);
+  await jest.advanceTimersByTimeAsync(0);
+  expect(stopped).not.toHaveBeenCalled();
+  resolveOpening(replacement as never);
+  await stopping;
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+  await jest.advanceTimersByTimeAsync(120_000);
+  expect(ngrok.forward).toHaveBeenCalledTimes(2);
+});
+
+it('waits for a replacement acquired during shutdown to finish closing', async () => {
+  failPublicProbes();
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  let resolveClose!: () => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
+  replacement.close.mockReturnValue(new Promise<void>(resolve => (resolveClose = resolve)));
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  let stopped = false;
+  const stopping = tunnel.stopAsync().then(() => {
+    stopped = true;
+  });
+  await jest.advanceTimersByTimeAsync(0);
+  resolveOpening(replacement as never);
+  await jest.advanceTimersByTimeAsync(0);
+  const stoppedBeforeClose = stopped;
+  resolveClose();
+  await jest.advanceTimersByTimeAsync(250);
+  await stopping;
+  expect(stoppedBeforeClose).toBe(false);
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+});
+
+it.each([0, 4, 5, 10])('retires a reopen cancelled after %s promise turns', async turns => {
+  failPublicProbes();
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  resolveOpening(replacement as never);
+  for (let turn = 0; turn < turns; turn++) {
+    await Promise.resolve();
+  }
+  await tunnel.stopAsync();
+  await jest.advanceTimersByTimeAsync(0);
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+});
+
+it('retries a rejected close when a reopen finishes after shutdown', async () => {
+  failPublicProbes();
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  const stopping = tunnel.stopAsync();
+  replacement.close.mockRejectedValueOnce(new Error('temporary unlisten failure'));
+  resolveOpening(replacement as never);
+  await jest.advanceTimersByTimeAsync(250);
+  await stopping;
+  expect(replacement.close).toHaveBeenCalledTimes(2);
+  const warnings = jest.mocked(logger.warn).mock.calls.length;
+  await jest.advanceTimersByTimeAsync(120_000);
+  expect(logger.warn).toHaveBeenCalledTimes(warnings);
+});
+
+it('fails stop if an in-flight reopen still has not settled by the stop deadline', async () => {
+  failPublicProbes();
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  const rejected = expect(tunnel.stopAsync()).rejects.toThrow(
+    'Ngrok tunnel web-preview-fixed.example.test stop timed out after 4000ms'
+  );
+  await jest.advanceTimersByTimeAsync(4_000);
+  await rejected;
+  expect(ngrok.forward).toHaveBeenCalledTimes(2);
+  resolveOpening(replacement as never);
+  await jest.advanceTimersByTimeAsync(0);
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+});
+
+it('retries an old listener while a reopen outlasts shutdown', async () => {
+  failPublicProbes();
+  initial.close.mockRejectedValueOnce(new Error('agent disconnected'));
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  expect(initial.close).toHaveBeenCalledTimes(1);
+  const rejected = expect(tunnel.stopAsync()).rejects.toThrow(
+    'Ngrok tunnel web-preview-fixed.example.test stop timed out after 4000ms'
+  );
+  await jest.advanceTimersByTimeAsync(4_000);
+  await rejected;
+  const oldCloseCalls = initial.close.mock.calls.length;
+  resolveOpening(replacement as never);
+  await jest.advanceTimersByTimeAsync(0);
+  expect(oldCloseCalls).toBe(2);
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+  expect(ngrok.forward).toHaveBeenCalledTimes(2);
+});
+
+it('fails stop if a pending reopen arrives but cannot be retired', async () => {
+  failPublicProbes();
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
+  replacement.close.mockRejectedValue(new Error('unlisten failed'));
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  const rejected = expect(tunnel.stopAsync()).rejects.toThrow(
+    'Ngrok tunnel web-preview-fixed.example.test stop timed out'
+  );
+  resolveOpening(replacement as never);
+  await jest.advanceTimersByTimeAsync(4_000);
+  await rejected;
+  expect(replacement.close.mock.calls.length).toBeGreaterThan(1);
+  expect(logger.warn).toHaveBeenCalledWith(
+    expect.objectContaining({ err: expect.any(Error) }),
+    'Could not retire late ngrok tunnel web-preview-fixed.example.test.'
+  );
+  const warnings = jest.mocked(logger.warn).mock.calls.length;
+  await jest.advanceTimersByTimeAsync(120_000);
+  expect(logger.warn).toHaveBeenCalledTimes(warnings);
+  expect(ngrok.forward).toHaveBeenCalledTimes(2);
+});
+
+it('rejects a changed public URL and closes the replacement', async () => {
+  failPublicProbes();
+  const changed = listener('https://different.example.test');
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockResolvedValue(changed as never);
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(45_000);
+    expect(changed.close).toHaveBeenCalledTimes(1);
+    expect(tunnel.url).toBe(url);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      expect.stringContaining('Could not reopen')
+    );
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('treats ngrok error responses as failures even if their status is accepted', async () => {
+  jest.mocked(turtleFetch).mockImplementation(
+    async target =>
+      new Response(undefined, {
+        status: 200,
+        headers: target.startsWith('https:') ? { 'ngrok-error-code': 'ERR_NGROK_3200' } : {},
+      })
+  );
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(45_000);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('reopens on a fresh agent session even if closing the old listener fails', async () => {
+  failPublicProbes();
+  initial.close.mockRejectedValueOnce(new Error('agent disconnected'));
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(45_000);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+    expect(ngrok.forward).toHaveBeenLastCalledWith(
+      expect.objectContaining({ force_new_session: true })
+    );
+    expect(ngrok.disconnect).not.toHaveBeenCalled();
+  } finally {
+    await tunnel.stopAsync();
+  }
+  expect(initial.close).toHaveBeenCalledTimes(2);
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+});
+
+it('retries a rejected close before reopening an endpoint that remains bound', async () => {
+  failPublicProbes();
+  let domainOccupied = true;
+  initial.close
+    .mockRejectedValueOnce(new Error('agent disconnected'))
+    .mockImplementation(async () => {
+      domainOccupied = false;
+    });
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockImplementation(async () => {
+      if (domainOccupied) {
+        throw new Error('endpoint is still bound');
+      }
+      return replacement as never;
+    });
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(45_000);
+    expect(initial.close).toHaveBeenCalledTimes(1);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+    await jest.advanceTimersByTimeAsync(2_000);
+    expect(initial.close).toHaveBeenCalledTimes(2);
+    expect(ngrok.forward).toHaveBeenCalledTimes(3);
+    expect(tunnel.url).toBe(url);
+  } finally {
+    await tunnel.stopAsync();
+  }
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+});
+
+it('retires an old listener even after its replacement is healthy', async () => {
+  failPublicProbes();
+  initial.close.mockRejectedValueOnce(new Error('agent disconnected'));
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(45_000);
+    expect(initial.close).toHaveBeenCalledTimes(1);
+    jest.mocked(turtleFetch).mockResolvedValue(new Response(undefined, { status: 200 }));
+    await jest.advanceTimersByTimeAsync(15_000);
+    expect(initial.close).toHaveBeenCalledTimes(2);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+  } finally {
+    await tunnel.stopAsync();
+  }
+});
+
+it('retries an old listener without repeating its close warning on every probe', async () => {
+  failPublicProbes();
+  initial.close.mockRejectedValue(new Error('old session disconnected'));
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  const warnings = jest.mocked(logger.warn).mock.calls.length;
+  expect(warnings).toBeGreaterThan(0);
+  jest.mocked(turtleFetch).mockResolvedValue(new Response(undefined, { status: 200 }));
+  await jest.advanceTimersByTimeAsync(120_000);
+  expect(initial.close.mock.calls.length).toBeGreaterThan(1);
+  expect(ngrok.forward).toHaveBeenCalledTimes(2);
+  expect(logger.warn).toHaveBeenCalledTimes(warnings);
+  const rejected = expect(tunnel.stopAsync()).rejects.toThrow(
+    'Ngrok tunnel web-preview-fixed.example.test stop timed out'
+  );
+  await jest.advanceTimersByTimeAsync(4_000);
+  await rejected;
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+});
+
+it('retries a rejected close during shutdown', async () => {
+  const failure = new Error('agent disconnected');
+  initial.close.mockRejectedValueOnce(failure);
+  const tunnel = await startNgrokTunnelAsync(options);
+  const stopping = tunnel.stopAsync();
+  await jest.advanceTimersByTimeAsync(250);
+  await stopping;
+  expect(initial.close).toHaveBeenCalledTimes(2);
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn).toHaveBeenCalledWith(
+    { err: failure },
+    'Could not stop ngrok tunnel web-preview-fixed.example.test.'
+  );
+});
+
+it('logs the first close rejection once while bounded shutdown retries it', async () => {
+  const failure = new Error('agent disconnected');
+  initial.close.mockRejectedValue(failure);
+  const tunnel = await startNgrokTunnelAsync(options);
+  const rejected = expect(tunnel.stopAsync()).rejects.toThrow('stop timed out');
+  await jest.advanceTimersByTimeAsync(4_000);
+  await rejected;
+  expect(initial.close.mock.calls.length).toBeGreaterThan(1);
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn).toHaveBeenCalledWith(
+    { err: failure },
+    'Could not stop ngrok tunnel web-preview-fixed.example.test.'
+  );
+});
+
+it('bounds shutdown during recovery without duplicating a pending native close', async () => {
+  failPublicProbes();
+  let finishClose!: () => void;
+  initial.close.mockReturnValueOnce(new Promise<void>(resolve => (finishClose = resolve)));
+  const tunnel = await startNgrokTunnelAsync(options);
+  await jest.advanceTimersByTimeAsync(45_000);
+  const stopping = tunnel.stopAsync();
+  expect(tunnel.stopAsync()).toBe(stopping);
+  const rejected = expect(stopping).rejects.toThrow(
+    'Ngrok tunnel web-preview-fixed.example.test stop timed out after 4000ms'
+  );
+  await jest.advanceTimersByTimeAsync(4_000);
+  await rejected;
+  expect(initial.close).toHaveBeenCalledTimes(1);
+  expect(ngrok.forward).toHaveBeenCalledTimes(1);
+  const warnings = jest.mocked(logger.warn).mock.calls.length;
+  finishClose();
+  await jest.advanceTimersByTimeAsync(120_000);
+  expect(logger.warn).toHaveBeenCalledTimes(warnings);
+  expect(initial.close).toHaveBeenCalledTimes(1);
+});
+
+it('bounds a stalled listener close before reopening', async () => {
+  failPublicProbes();
+  initial.close.mockImplementationOnce(async () => await new Promise(() => {}));
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(49_999);
+    expect(ngrok.forward).toHaveBeenCalledTimes(1);
+    await jest.advanceTimersByTimeAsync(1);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+  } finally {
+    const stopping = tunnel.stopAsync();
+    const rejected = expect(stopping).rejects.toThrow(
+      'Ngrok tunnel web-preview-fixed.example.test stop timed out'
+    );
+    await jest.advanceTimersByTimeAsync(4_000);
+    await rejected;
+  }
+});
+
+it('does not queue more native opens while a timed-out open is still pending', async () => {
+  failPublicProbes();
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(
+      new Promise(resolve => {
+        resolveOpening = resolve;
+      })
+    )
+    .mockResolvedValue(replacement as never);
+  const tunnel = await startNgrokTunnelAsync(options);
+  const late = listener();
+  try {
+    await jest.advanceTimersByTimeAsync(180_000);
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+    resolveOpening(late as never);
+    await jest.advanceTimersByTimeAsync(30_000);
+    expect(late.close).toHaveBeenCalledTimes(1);
+    expect(ngrok.forward).toHaveBeenCalledTimes(3);
+  } finally {
+    await tunnel.stopAsync();
+  }
+  expect(replacement.close).toHaveBeenCalledTimes(1);
+});
+
+it('bounds initial tunnel creation and retires a late listener', async () => {
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockReturnValueOnce(
+      new Promise(resolve => {
+        resolveOpening = resolve;
+      })
+    );
+  const opening = startNgrokTunnelAsync(options);
+  const rejected = expect(opening).rejects.toThrow('Ngrok tunnel open timed out');
+  await jest.advanceTimersByTimeAsync(15_000);
+  await rejected;
+  resolveOpening(initial as never);
+  await jest.advanceTimersByTimeAsync(0);
+  expect(initial.close).toHaveBeenCalledTimes(1);
+});
+
+it('retries a rejected close after initial tunnel creation timed out', async () => {
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)));
+  const opening = startNgrokTunnelAsync(options);
+  const rejected = expect(opening).rejects.toThrow('Ngrok tunnel open timed out');
+  await jest.advanceTimersByTimeAsync(15_000);
+  await rejected;
+  initial.close.mockRejectedValueOnce(new Error('temporary unlisten failure'));
+  resolveOpening(initial as never);
+  await jest.advanceTimersByTimeAsync(250);
+  expect(initial.close).toHaveBeenCalledTimes(2);
+});
+
+it('retires only the late listener without blaming it for an older stuck listener', async () => {
+  failPublicProbes();
+  initial.close.mockRejectedValue(new Error('old session disconnected'));
+  let resolveOpening!: (value: ngrok.Listener) => void;
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(initial as never)
+    .mockReturnValueOnce(new Promise(resolve => (resolveOpening = resolve)))
+    .mockResolvedValue(replacement as never);
+  const tunnel = await startNgrokTunnelAsync(options);
+  try {
+    await jest.advanceTimersByTimeAsync(60_000);
+    const late = listener();
+    resolveOpening(late as never);
+    jest.mocked(turtleFetch).mockResolvedValue(new Response(undefined, { status: 200 }));
+    await jest.advanceTimersByTimeAsync(4_000);
+    expect(late.close).toHaveBeenCalledTimes(1);
+    expect(
+      jest
+        .mocked(logger.warn)
+        .mock.calls.some(([, message]) => message?.includes('Could not retire late'))
+    ).toBe(false);
+  } finally {
+    initial.close.mockResolvedValue(undefined);
+    await tunnel.stopAsync();
+  }
+});
+
+it('recovers using actual HTTP health probes with a local ngrok adapter', async () => {
+  const actualFetch = jest.requireActual<typeof import('node-fetch')>('node-fetch').default;
+  const realSetTimeout = jest.requireActual<typeof import('node:timers')>('node:timers').setTimeout;
+  let broken = true;
+  const local = createServer((_req, res) => {
+    res.writeHead(200);
+    res.end('healthy');
+  });
+  const publicServer = createServer((_req, res) => {
+    res.writeHead(broken ? 503 : 200);
+    res.end('probe');
+  });
+  await Promise.all(
+    [local, publicServer].map(
+      server => new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+    )
+  );
+  const publicUrl = `http://127.0.0.1:${(publicServer.address() as AddressInfo).port}`;
+  let completedRequests = 0;
+  jest.mocked(turtleFetch).mockImplementation(async (target, method, requestOptions) => {
+    const response = await actualFetch(target, { ...requestOptions, method });
+    completedRequests++;
+    return response;
+  });
+  const first = listener(publicUrl);
+  const next = listener(publicUrl);
+  jest
+    .mocked(ngrok.forward)
+    .mockReset()
+    .mockResolvedValueOnce(first as never)
+    .mockImplementation(async () => {
+      broken = false;
+      return next as never;
+    });
+  const tunnel = await startNgrokTunnelAsync({
+    ...options,
+    port: (local.address() as AddressInfo).port,
+  });
+  try {
+    for (let count = 0; count < 3; count++) {
+      await jest.advanceTimersByTimeAsync(15_000);
+      for (let turns = 0; turns < 50 && completedRequests < (count + 1) * 2; turns++) {
+        await new Promise(resolve => realSetTimeout(resolve, 10));
+      }
+      expect(completedRequests).toBe((count + 1) * 2);
+    }
+    expect(ngrok.forward).toHaveBeenCalledTimes(2);
+    expect(first.close).toHaveBeenCalledTimes(1);
+    expect((await actualFetch(`${tunnel.url}/healthz`)).status).toBe(200);
+  } finally {
+    await tunnel.stopAsync();
+    await Promise.all(
+      [local, publicServer].map(
+        server =>
+          new Promise<void>((resolve, reject) =>
+            server.close(err => (err ? reject(err) : resolve()))
+          )
+      )
+    );
+  }
+  expect(next.close).toHaveBeenCalledTimes(1);
+});
+
+it('blocks HTTP and existing WebSockets on Stop even when ngrok cannot close', async () => {
+  jest.useRealTimers();
+  const actualFetch = jest.requireActual<typeof import('node-fetch')>('node-fetch').default;
+  let requests = 0;
+  let messages = 0;
+  const backend = createServer((_request, response) => {
+    requests++;
+    response.end('owned backend');
+  });
+  const websockets = new WebSocketServer({ server: backend });
+  websockets.on('connection', socket => {
+    socket.on('message', data => {
+      messages++;
+      socket.send(data);
+    });
+  });
+  backend.listen(0, '127.0.0.1');
+  await once(backend, 'listening');
+  const backendPort = (backend.address() as AddressInfo).port;
+  const tunnel = await startNgrokTunnelAsync({
+    ...options,
+    port: backendPort,
+    healthCheck: undefined,
+  });
+  const targetPort = (jest.mocked(ngrok.forward).mock.calls[0][0] as ngrok.Config).addr;
+  const targetUrl = `http://127.0.0.1:${targetPort}`;
+  const socket = new WebSocket(`ws://127.0.0.1:${targetPort}`);
+  const opened = once(socket, 'open');
+  try {
+    expect(await (await actualFetch(targetUrl)).text()).toBe('owned backend');
+    await opened;
+    const echoed = once(socket, 'message');
+    socket.send('before-stop');
+    expect((await echoed)[0].toString()).toBe('before-stop');
+    const closed = once(socket, 'close');
+    initial.close.mockRejectedValue(new Error('agent disconnected'));
+    const stopping = tunnel.stopAsync();
+    const rejected = expect(stopping).rejects.toThrow('stop timed out after 4000ms');
+    await expect(actualFetch(targetUrl, { timeout: 1_000 })).rejects.toThrow();
+    await closed;
+    expect(requests).toBe(1);
+    expect(messages).toBe(1);
+    expect(await (await actualFetch(`http://127.0.0.1:${backendPort}`)).text()).toBe(
+      'owned backend'
+    );
+    await rejected;
+    await expect(actualFetch(targetUrl, { timeout: 1_000 })).rejects.toThrow();
+    expect(requests).toBe(2);
+    expect(messages).toBe(1);
+    const competing = createTcpServer();
+    const conflict = once(competing, 'error');
+    competing.listen(targetPort as number, '127.0.0.1');
+    expect((await conflict)[0]).toMatchObject({ code: 'EADDRINUSE' });
+  } finally {
+    socket.terminate();
+    for (const client of websockets.clients) {
+      client.terminate();
+    }
+    websockets.close();
+    backend.closeAllConnections();
+    await new Promise<void>(resolve => backend.close(() => resolve()));
+    await tunnel.stopAsync().catch(() => {});
+  }
+});
+
+it('releases its local target when initial tunnel creation fails', async () => {
+  jest.useRealTimers();
+  jest.mocked(ngrok.forward).mockReset().mockRejectedValue(new Error('forward failed'));
+  await expect(startNgrokTunnelAsync(options)).rejects.toThrow('forward failed');
+  const targetPort = (jest.mocked(ngrok.forward).mock.calls[0][0] as ngrok.Config).addr;
+  const server = createServer();
+  server.listen(targetPort as number, '127.0.0.1');
+  await once(server, 'listening');
+  await new Promise<void>(resolve => server.close(() => resolve()));
+});
+
+it('preserves a full response for a half-closed slow reader', async () => {
+  jest.useRealTimers();
+  const payload = Buffer.alloc(4 * 1024 * 1024, 37);
+  const backend = createTcpServer({ allowHalfOpen: true }, socket => {
+    socket.resume();
+    socket.on('end', () => socket.end(payload));
+  });
+  backend.listen(0, '127.0.0.1');
+  await once(backend, 'listening');
+  const tunnel = await startNgrokTunnelAsync({
+    ...options,
+    port: (backend.address() as AddressInfo).port,
+    healthCheck: undefined,
+  });
+  const targetPort = (jest.mocked(ngrok.forward).mock.calls[0][0] as ngrok.Config).addr as number;
+  const socket = createConnection({ host: '127.0.0.1', port: targetPort, allowHalfOpen: true });
+  try {
+    const chunks: Buffer[] = [];
+    socket.on('data', chunk => chunks.push(chunk));
+    const ended = once(socket, 'end');
+    socket.pause();
+    socket.end('request');
+    await new Promise(resolve => setTimeout(resolve, 100));
+    socket.resume();
+    await ended;
+    expect(Buffer.concat(chunks).equals(payload)).toBe(true);
+  } finally {
+    socket.destroy();
+    await tunnel.stopAsync();
+    await new Promise<void>(resolve => backend.close(() => resolve()));
+  }
+});
+
+it.each(['resolve', 'reject'])(
+  'releases the target after timed-out startup later %s',
+  async outcome => {
+    let resolveOpening!: (value: ngrok.Listener) => void;
+    let rejectOpening!: (error: Error) => void;
+    jest
+      .mocked(ngrok.forward)
+      .mockReset()
+      .mockReturnValue(
+        new Promise((resolve, reject) => {
+          resolveOpening = resolve;
+          rejectOpening = reject;
+        })
+      );
+    const opening = startNgrokTunnelAsync(options);
+    const rejected = expect(opening).rejects.toThrow('open timed out');
+    await new Promise<void>(resolve => setImmediate(resolve));
+    await jest.advanceTimersByTimeAsync(15_000);
+    await rejected;
+    const targetPort = (jest.mocked(ngrok.forward).mock.calls[0][0] as ngrok.Config).addr as number;
+    if (outcome === 'resolve') {
+      resolveOpening(replacement as never);
+    } else {
+      rejectOpening(new Error('forward failed'));
+    }
+    await jest.advanceTimersByTimeAsync(0);
+    const server = createTcpServer();
+    server.listen(targetPort, '127.0.0.1');
+    await once(server, 'listening');
+    await new Promise<void>(resolve => server.close(() => resolve()));
+  }
+);
+
+it('drains a full upload when the backend ends its response early', async () => {
+  jest.useRealTimers();
+  const payload = Buffer.alloc(4 * 1024 * 1024, 51);
+  let received!: Buffer;
+  let receivedRequest!: () => void;
+  const completed = new Promise<void>(resolve => {
+    receivedRequest = resolve;
+  });
+  const backend = createTcpServer({ allowHalfOpen: true }, socket => {
+    const chunks: Buffer[] = [];
+    socket.on('data', chunk => chunks.push(chunk));
+    socket.on('end', () => {
+      received = Buffer.concat(chunks);
+      receivedRequest();
+    });
+    socket.pause();
+    socket.end('early response');
+    setTimeout(() => socket.resume(), 100);
+  });
+  backend.listen(0, '127.0.0.1');
+  await once(backend, 'listening');
+  const tunnel = await startNgrokTunnelAsync({
+    ...options,
+    port: (backend.address() as AddressInfo).port,
+    healthCheck: undefined,
+  });
+  const targetPort = (jest.mocked(ngrok.forward).mock.calls[0][0] as ngrok.Config).addr as number;
+  const socket = createConnection({ host: '127.0.0.1', port: targetPort, allowHalfOpen: true });
+  try {
+    socket.resume();
+    socket.end(payload);
+    await completed;
+    expect(received.equals(payload)).toBe(true);
+  } finally {
+    socket.destroy();
+    await tunnel.stopAsync();
+    await new Promise<void>(resolve => backend.close(() => resolve()));
+  }
+});
@@ -530,6 +530,22 @@ describe(describeServeSimLaunch, () => {
  });
 });

+it('only pins hosts when a valid device ID is supplied', () => {
+  const udid = 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA';
+  expect(createServeSimArgs({ port: 4321, iosSimulatorUdid: udid })).toEqual(
+    expect.arrayContaining(['--single-device', udid])
+  );
+  for (const iosSimulatorUdid of [undefined, '', 'booted', 'iPhone 17']) {
+    expect(createServeSimArgs({ port: 4321, iosSimulatorUdid })).not.toContain('--single-device');
+  }
+  expect(createExpoDeviceHubArgs({ port: 4321, device: 'emulator-5554' })).toEqual(
+    expect.arrayContaining(['--single-device', 'emulator-5554'])
+  );
+  for (const device of [undefined, '', 'all', 'booted', 'invalid serial']) {
+    expect(createExpoDeviceHubArgs({ port: 4321, device })).not.toContain('--single-device');
+  }
+});
+
 describe(createServeSimArgs, () => {
  it('uses the latest Expo package and applies the EAS streaming policy', () => {
    expect(
@@ -916,7 +932,7 @@ describe(waitForWebPreviewReadyAsync, () => {

 describe(startNgrokTunnelAsync, () => {
  it.each(['rejected', 'stalled'] as const)(
-    'retains a %s close failure on repeated stops',
+    'bounds %s listener retirement and reuses the stop promise',
    async mode => {
      jest.useFakeTimers();
      try {
@@ -938,14 +954,12 @@ describe(startNgrokTunnelAsync, () => {
          logger: createLoggerMock(),
        });
        const stopping = tunnel.stopAsync();
-        const assertion = expect(stopping).rejects.toThrow(
-          mode === 'rejected' ? 'close failed' : 'Ngrok tunnel stop timed out after 4000ms.'
-        );
+        const assertion = expect(stopping).rejects.toThrow(/stop timed out after 4000ms/);
        expect(tunnel.stopAsync()).toBe(stopping);
        await jest.advanceTimersByTimeAsync(4_000);
        await assertion;
        await expect(tunnel.stopAsync()).rejects.toThrow();
-        expect(close).toHaveBeenCalledTimes(1);
+        expect(close).toHaveBeenCalled();
      } finally {
        jest.useRealTimers();
      }
@@ -969,7 +983,7 @@ describe(startNgrokTunnelAsync, () => {

    expect(ngrok.forward).toHaveBeenCalledWith(
      expect.objectContaining({
-        addr: 4321,
+        addr: expect.any(Number),
        authtoken: 'token',
        domain: expect.stringMatching(/^web-preview-[a-f0-9]{32}\.eas-simulator\.ngrok\.dev$/),
      })
@@ -1286,7 +1300,10 @@ describe(startDeviceSessionHostAsync, () => {
        recordingDirectory,
      }),
    ]);
-    expect(ngrok.forward).toHaveBeenCalledWith(expect.objectContaining({ addr: port }));
+    expect(ngrok.forward).toHaveBeenCalledWith(
+      expect.objectContaining({ addr: expect.any(Number) })
+    );
+    expect(ngrok.forward).not.toHaveBeenCalledWith(expect.objectContaining({ addr: port }));
    expect(preview.apiUrl).toBe('https://android-preview.example.test');

    await host.finishAsync();
@@ -1422,7 +1439,10 @@ describe(startDeviceSessionHostAsync, () => {
        packageVersion,
      }),
    ]);
-    expect(ngrok.forward).toHaveBeenCalledWith(expect.objectContaining({ addr: port }));
+    expect(ngrok.forward).toHaveBeenCalledWith(
+      expect.objectContaining({ addr: expect.any(Number) })
+    );
+    expect(ngrok.forward).not.toHaveBeenCalledWith(expect.objectContaining({ addr: port }));
    expect(preview.apiUrl).toBe('https://ios-preview.example.test');

    await host.finishAsync();
@@ -144,6 +144,7 @@ export namespace GooglePlayUtils {
      signal?: AbortSignal;
    }
  ): Promise<void> {
+    const attempts: unknown[] = [];
    const sendCommitAsync = async ({
      changesNotSentForReview,
    }: {
@@ -161,6 +162,7 @@ export namespace GooglePlayUtils {
          throw new SystemError('Google did not confirm the committed edit.');
        }
      } catch (error) {
+        attempts.push(...(error instanceof AggregateError ? error.errors : [error]));
        if (error instanceof GooglePlayAuthRequestError) {
          throw error;
        }
@@ -168,8 +170,14 @@ export namespace GooglePlayUtils {
          !(error instanceof GooglePlayApiError) ||
          GooglePlayApiError.isRetryableStatus(error.status)
        ) {
+          const attemptMessages = attempts
+            .map(
+              (attempt, index) =>
+                `${index + 1}. ${attempt instanceof Error ? attempt.message : String(attempt)}`
+            )
+            .join('\n');
          throw new GooglePlayCommitOutcomeUnknownError(
-            `Could not confirm whether Google Play saved the release for ${packageName}. Check its release status at https://play.google.com/console/ before submitting again.`,
+            `Could not confirm whether Google Play saved the release for ${packageName}. Check its release status at https://play.google.com/console/ before submitting again.\n\nCommit attempts:\n${attemptMessages}`,
            { cause: error, metadata: GooglePlayApiError.getErrorMetadata(error) }
          );
        }
@@ -84,6 +84,41 @@ it.each([408, 429, 503])('retries a transient HTTP %s commit on the same edit',
  api().post(`${editPath}:commit`).query({}).reply(200, { id: 'edit' });
  await expect(commit()).resolves.toBeUndefined();
 });
+it('shows failed commit attempts in order across processing, HTTP, and network retries', async () => {
+  mockToken();
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .reply(400, { error: { message: pendingUploadMessage } });
+  api().post(`${editPath}:commit`).query({}).reply(503);
+  api()
+    .post(`${editPath}:commit`)
+    .query({})
+    .replyWithError(Object.assign(new Error('Lost commit response'), { code: 'ECONNRESET' }));
+  const message = 'You must let us know whether your app includes any health features.';
+  api().post(`${editPath}:commit`).query({}).reply(403, { error: { message } });
+  const error = await commit().catch(error => error);
+  const mapped = GooglePlayUtils.mapGooglePlayError(error, packageName);
+  expect(mapped).toBeInstanceOf(GooglePlayCommitOutcomeUnknownError);
+  expect((mapped as Error).message).toContain(`Google Play request failed (HTTP 403): ${message}`);
+  expect((mapped as Error).message).toContain('Could not confirm whether Google Play saved');
+  expect((mapped as Error).message).toContain('https://play.google.com/console/');
+  expect(mapped).toMatchObject({
+    metadata: { googlePlayErrorResponse: JSON.stringify({ error: { message } }) },
+    cause: expect.any(AggregateError),
+  });
+  const attempts = (mapped as Error).message.split('Commit attempts:\n')[1]?.split('\n');
+  expect(attempts).toEqual([
+    `1. Google Play request failed (HTTP 400): ${pendingUploadMessage}`,
+    '2. Google Play request failed (HTTP 503).',
+    '3. Google Play request failed before a response was received.',
+    `4. Google Play request failed (HTTP 403): ${message}`,
+  ]);
+  expect(((mapped as Error).cause as AggregateError).errors).toHaveLength(3);
+  expect(((mapped as Error).cause as AggregateError).errors[1]).toMatchObject({
+    cause: { code: 'ECONNRESET' },
+  });
+});
 it('preserves cancellation before commit is sent', async () => {
  const controller = new AbortController();
  const reason = new Error('cancelled before commit');
@@ -250,7 +285,9 @@ it('keeps the last Google Play error response when the commit outcome is unknown
    .query({})
    .times(6)
    .reply(503, { error: { message: 'Backend error' } });
-  await expect(commit()).rejects.toMatchObject({
+  const error = await commit().catch(error => error);
+  expect(error.message).toContain('Google Play request failed (HTTP 503): Backend error');
+  expect(error).toMatchObject({
    metadata: {
      googlePlayRequestPath: `${editPath}:commit`,
      googlePlayErrorResponse: JSON.stringify({ error: { message: 'Backend error' } }),
@@ -55,6 +55,8 @@ import { IosSimulatorUtils, type IosSimulatorUuid } from '../../utils/IosSimulat
 import { createStartupTasks } from './startupTasks';

 const WEB_PREVIEW_HOST = '127.0.0.1';
+const IOS_SIMULATOR_UDID = /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+const ANDROID_DEVICE_SERIAL = /^(?!all$|booted$)[A-Za-z0-9][A-Za-z0-9._:-]*$/;
 const SERVE_SIM_PACKAGE_NAME = '@expo/serve-sim';
 const SERVE_SIM_MAX_DIMENSION = '1600';
 const SERVE_SIM_MJPEG_QUALITY = '0.55';
@@ -157,6 +159,9 @@ export function createServeSimArgs({
  return [
    createServeSimPackageSpec(packageVersion),
    ...(iosSimulatorUdid ? [iosSimulatorUdid] : []),
+    ...(iosSimulatorUdid && IOS_SIMULATOR_UDID.test(iosSimulatorUdid)
+      ? ['--single-device', iosSimulatorUdid]
+      : []),
    '--port',
    String(port),
    '--host',
@@ -198,6 +203,7 @@ export function createServeSimArgs({

 export function createExpoDeviceHubArgs({
  port,
+  device,
  turnArgs = [],
  websiteArgs = [],
  frameAncestorArgs: frameArgs = [],
@@ -206,6 +212,7 @@ export function createExpoDeviceHubArgs({
  recordingDirectory,
 }: {
  port: number;
+  device?: string;
  turnArgs?: string[];
  websiteArgs?: string[];
  frameAncestorArgs?: string[];
@@ -215,6 +222,7 @@ export function createExpoDeviceHubArgs({
 }): string[] {
  return [
    createExpoDeviceHubPackageSpec(packageVersion),
+    ...(device && ANDROID_DEVICE_SERIAL.test(device) ? ['--single-device', device] : []),
    '--port',
    String(port),
    '--host',
@@ -387,6 +395,8 @@ type DeviceSessionHostOptions = {
  /** Origins whose pages may call the preview host's API, in addition to the website origins. */
  corsOrigins?: string[];
  iosSimulatorUdid?: string;
+  /** Selected preview target; does not enable Simulator boot or setup. */
+  previewDeviceId?: string;
  installAppPath?: string;
  bootEnv?: Record<string, string>;
  application?: Promise<ServeSimApplicationOptions | void>;
@@ -431,6 +441,7 @@ async function startDeviceSessionHostInternalAsync(
    signal,
    packageVersion,
    iosSimulatorUdid,
+    previewDeviceId,
    installAppPath,
    application,
    onStartupError,
@@ -479,6 +490,10 @@ async function startDeviceSessionHostInternalAsync(
  if (isAndroid) {
    await ensureFfmpegInstalledOnceAsync({ runtimePlatform, env, logger });
  }
+  const deviceIdPattern = isAndroid ? ANDROID_DEVICE_SERIAL : IOS_SIMULATOR_UDID;
+  const validPreviewDevice =
+    previewDeviceId && deviceIdPattern.test(previewDeviceId) ? previewDeviceId : undefined;
+  const previewDevice = isAndroid ? validPreviewDevice : (iosSimulatorUdid ?? validPreviewDevice);
  const recording: AndroidSessionRecording | null = isAndroid
    ? {
        deviceRunSessionId: getDeviceRunSessionIdOrThrow(env),
@@ -506,6 +521,7 @@ async function startDeviceSessionHostInternalAsync(
    isAndroid
      ? createExpoDeviceHubArgs({
          port,
+          device: previewDevice,
          turnArgs,
          packageVersion,
          recordingDirectory: recording?.directory,
@@ -517,7 +533,7 @@ async function startDeviceSessionHostInternalAsync(
          port,
          turnArgs,
          packageVersion,
-          iosSimulatorUdid,
+          iosSimulatorUdid: previewDevice,
          websiteArgs: websiteOriginArgs(env),
          frameAncestorArgs: frameAncestorArgs(frameAncestors),
          corsOriginArgs: corsOriginArgs(corsOrigins),
@@ -607,6 +623,7 @@ async function startDeviceSessionHostInternalAsync(
          subdomainId,
          baseDomain,
          authtoken,
+          healthCheck: { path: isAndroid ? '/readyz' : '/healthz' },
          logger,
        });
        if (finishTask) {
@@ -762,9 +779,9 @@ async function startDeviceSessionHostInternalAsync(
    }
    logger.info(`Waiting for ${serverName} to become ready.`);
    const device = (await readiness).enforceValue();
-    if (iosSimulatorUdid && device.toLowerCase() !== iosSimulatorUdid.toLowerCase()) {
+    if (!isAndroid && previewDevice && device.toLowerCase() !== previewDevice.toLowerCase()) {
      throw new SystemError(
-        `serve-sim became ready on ${device}, but this session requested ${iosSimulatorUdid}.`
+        `serve-sim became ready on ${device}, but this session requested ${previewDevice}.`
      );
    }
    hostReady = true;
@@ -807,7 +824,7 @@ async function startDeviceSessionHostInternalAsync(
          captureAsync: signal =>
            captureDeviceRunSessionPreviewAsync({
              runtimePlatform,
-              device,
+              device: previewDevice ?? device,
              env,
              signal,
            }),
@@ -1,4 +1,4 @@
-import { UserError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import * as jose from 'jose';
@@ -617,6 +617,24 @@ export class AscApiClient {
      );
      if (parsedAscErrorResponse.ok) {
        const errors = parsedAscErrorResponse.value.errors.map(ascError => {
+          if (response.status === 401 && ascError.code === 'NOT_AUTHORIZED') {
+            return new UserError(
+              'EAS_ASC_INVALID_AUTH',
+              'App Store Connect rejected the API authentication credentials. ' +
+                'Check that the API key is active and belongs to the correct App Store Connect account. ' +
+                'If the key is stored in EAS credentials, replace or reconfigure it. ' +
+                'For a local key, check `key_id` and `key`, and `issuer_id` for a team key. Then try again.',
+              { cause: ascError, docsUrl: 'https://docs.expo.dev/submit/ios/' }
+            );
+          }
+          if (response.status === 500 && ascError.code === 'UNEXPECTED_ERROR') {
+            return new SystemError(
+              'App Store Connect returned an unexpected server error. ' +
+                'Check Apple’s service status at https://developer.apple.com/system-status/ and verify whether the requested operation completed in App Store Connect before trying again. ' +
+                'If the error continues, try again later or contact Apple Developer Support.',
+              { cause: ascError, trackingCode: 'EAS_ASC_SERVER_ERROR' }
+            );
+          }
          if (ascError.code === 'FORBIDDEN.REQUIRED_AGREEMENTS_MISSING_OR_EXPIRED') {
            return new UserError(
              'EAS_ASC_REQUIRED_AGREEMENTS_MISSING_OR_EXPIRED',
@@ -1,4 +1,4 @@
-import { UserError } from '@expo/eas-build-job';
+import { SystemError, UserError } from '@expo/eas-build-job';
 import * as jose from 'jose';
 import nock from 'nock';

@@ -85,6 +85,57 @@ describe(AscApiClient, () => {
    }
  );

+  it.each([false, true])(
+    'explains NOT_AUTHORIZED without losing other errors (mixed: %s)',
+    async mixed => {
+      const known = { status: '401', code: 'NOT_AUTHORIZED' };
+      const other = { status: '401', code: 'OTHER_ERROR' };
+      const scope = nock('https://api.appstoreconnect.apple.com')
+        .get('/v1/apps/app')
+        .query(true)
+        .reply(401, { errors: mixed ? [known, other] : [known] });
+      const error = await client
+        .getAsync('/v1/apps/:id', { 'fields[apps]': ['bundleId', 'name'] }, { id: 'app' })
+        .catch(error => error);
+      const mapped = mixed ? error.errors[0] : error;
+      expect(mapped).toBeInstanceOf(UserError);
+      expect(mapped).toMatchObject({ errorCode: 'EAS_ASC_INVALID_AUTH', cause: known });
+      if (mixed) {
+        expect(error).toBeInstanceOf(AggregateError);
+        expect(error.errors[1]).toBeInstanceOf(AscApiRequestError);
+        expect(error.errors[1].code).toBe('OTHER_ERROR');
+      }
+      expect(scope.isDone()).toBe(true);
+    }
+  );
+
+  it.each([false, true])(
+    'explains UNEXPECTED_ERROR without losing other errors (mixed: %s)',
+    async mixed => {
+      const known = { status: '500', code: 'UNEXPECTED_ERROR' };
+      const other = { status: '500', code: 'OTHER_ERROR' };
+      const scope = nock('https://api.appstoreconnect.apple.com')
+        .get('/v1/apps/app')
+        .query(true)
+        .reply(500, { errors: mixed ? [known, other] : [known] });
+      const error = await client
+        .getAsync('/v1/apps/:id', { 'fields[apps]': ['bundleId', 'name'] }, { id: 'app' })
+        .catch(error => error);
+      const mapped = mixed ? error.errors[0] : error;
+      expect(mapped).toBeInstanceOf(SystemError);
+      expect(mapped).toMatchObject({
+        trackingCode: 'EAS_ASC_SERVER_ERROR',
+        cause: known,
+      });
+      if (mixed) {
+        expect(error).toBeInstanceOf(AggregateError);
+        expect(error.errors[1]).toBeInstanceOf(AscApiRequestError);
+        expect(error.errors[1].code).toBe('OTHER_ERROR');
+      }
+      expect(scope.isDone()).toBe(true);
+    }
+  );
+
  it('fetches app info', async () => {
    const appId = '1491144534';
    const responseFixture = require('./fixtures/apps/get-apps-200.json');
@@ -391,7 +391,9 @@ describe('commitBuildUploadFileAsync', () => {
      .reply(status, { errors: [{ code }] });
    await expect(
      AscApiUtils.commitBuildUploadFileAsync({ client, fileId: 'file', logger })
-    ).rejects.toMatchObject({ status, code });
+    ).rejects.toMatchObject(
+      code === 'NOT_AUTHORIZED' ? { errorCode: 'EAS_ASC_INVALID_AUTH' } : { status, code }
+    );
  });

  it('does not commit when the initial state read fails', async () => {
@@ -0,0 +1,368 @@
+import { SystemError } from '@expo/eas-build-job';
+import { type bunyan } from '@expo/logger';
+import * as ngrok from '@ngrok/ngrok';
+import { randomBytes } from 'node:crypto';
+import { once } from 'node:events';
+import { type AddressInfo, type Socket, createConnection, createServer } from 'node:net';
+import { clearTimeout, setTimeout } from 'node:timers';
+
+import { turtleFetch } from '../../utils/turtleFetch';
+import { withDeviceRunSessionTimeoutAsync } from './deviceRunSessionTimeout';
+
+const PROBE_INTERVAL_MS = 15_000;
+const FAILURE_THRESHOLD = 3;
+const STOP_TIMEOUT_MS = 4_000;
+
+export type NgrokTunnelHandle = {
+  url: string;
+  subdomainId: string;
+  stopAsync: () => Promise<void>;
+};
+
+export async function startNgrokTunnelAsync({
+  port,
+  subdomainPrefix,
+  subdomainId = randomBytes(16).toString('hex'),
+  baseDomain,
+  authtoken,
+  rewriteHostHeader,
+  healthCheck,
+  logger,
+}: {
+  port: number;
+  subdomainPrefix: string;
+  subdomainId?: string;
+  baseDomain: string;
+  authtoken: string;
+  rewriteHostHeader?: boolean;
+  healthCheck?: { path: string; statuses?: number[] };
+  logger: bunyan;
+}): Promise<NgrokTunnelHandle> {
+  const domain = `${subdomainPrefix}-${subdomainId}.${baseDomain}`;
+  const controller = new AbortController();
+  const { signal } = controller;
+  const sockets = new Set<Socket>();
+  const target = createServer({ allowHalfOpen: true }, client => {
+    if (signal.aborted) {
+      client.destroy();
+      return;
+    }
+    const upstream = createConnection({ host: '127.0.0.1', port, allowHalfOpen: true });
+    for (const socket of [client, upstream]) {
+      sockets.add(socket);
+      socket.on('error', () => {
+        client.destroy();
+        upstream.destroy();
+      });
+      socket.on('close', () => sockets.delete(socket));
+    }
+    client.pipe(upstream).pipe(client);
+  });
+  target.listen(0, '127.0.0.1');
+  await once(target, 'listening');
+  target.unref();
+  signal.addEventListener(
+    'abort',
+    () => {
+      for (const socket of sockets) {
+        socket.destroy();
+      }
+    },
+    { once: true }
+  );
+  const config: ngrok.Config = {
+    addr: (target.address() as AddressInfo).port,
+    authtoken,
+    domain,
+    ...(rewriteHostHeader ? { request_header_add: [`Host:localhost:${port}`] } : {}),
+  };
+
+  const ownedListeners = new Set<ngrok.Listener>();
+  const retiredListeners = new Set<ngrok.Listener>();
+  const closingListeners = new Map<ngrok.Listener, Promise<void>>();
+  let pendingOpen: Promise<ngrok.Listener> | undefined;
+  let currentListener: ngrok.Listener | undefined;
+  function releaseTarget(): void {
+    if (signal.aborted && !pendingOpen && ownedListeners.size === 0 && target.listening) {
+      target.close();
+    }
+  }
+
+  async function closeAsync(
+    listener: ngrok.Listener,
+    closeSignal: AbortSignal,
+    logFailure = true
+  ): Promise<void> {
+    retiredListeners.add(listener);
+    let closing = closingListeners.get(listener);
+    if (!closing) {
+      closing = Promise.resolve().then(async () => await listener.close());
+      closingListeners.set(listener, closing);
+      void closing.then(
+        () => {
+          closingListeners.delete(listener);
+          retiredListeners.delete(listener);
+          ownedListeners.delete(listener);
+          releaseTarget();
+        },
+        () => closingListeners.delete(listener)
+      );
+    }
+    try {
+      await withDeviceRunSessionTimeoutAsync(
+        { name: 'Ngrok tunnel close', timeoutMs: 5_000, signal: closeSignal },
+        async () => await closing
+      );
+    } catch (err) {
+      if (logFailure && !closeSignal.aborted) {
+        logger.warn({ err }, `Could not stop ngrok tunnel ${domain}.`);
+      }
+    }
+  }
+
+  async function retireListenersAsync(retirementSignal: AbortSignal): Promise<void> {
+    let logFailure = true;
+    while (retiredListeners.size > 0) {
+      retirementSignal.throwIfAborted();
+      await Promise.all(
+        [...retiredListeners].map(retired => closeAsync(retired, retirementSignal, logFailure))
+      );
+      logFailure = false;
+      if (retiredListeners.size > 0) {
+        await waitAsync(250, retirementSignal);
+      }
+    }
+  }
+
+  async function retireLateListenerAsync(listener: ngrok.Listener): Promise<void> {
+    retiredListeners.add(listener);
+    try {
+      await withDeviceRunSessionTimeoutAsync(
+        { name: 'Late ngrok tunnel retirement', timeoutMs: STOP_TIMEOUT_MS },
+        async retirementSignal => {
+          while (retiredListeners.has(listener)) {
+            retirementSignal.throwIfAborted();
+            await closeAsync(listener, retirementSignal, false);
+            if (retiredListeners.has(listener)) {
+              await waitAsync(250, retirementSignal);
+            }
+          }
+        }
+      );
+    } catch (err) {
+      logger.warn({ err }, `Could not retire late ngrok tunnel ${domain}.`);
+    }
+  }
+
+  async function openAsync(forceNewSession = false): Promise<ngrok.Listener> {
+    if (pendingOpen) {
+      throw new SystemError(`A previous ngrok tunnel open for ${domain} is still pending.`);
+    }
+    let acquired: ngrok.Listener | undefined;
+    let retirement: Promise<void> | undefined;
+    const retireAcquired = () => {
+      if (acquired) {
+        retirement ??= retireLateListenerAsync(acquired);
+      }
+    };
+    try {
+      return await withDeviceRunSessionTimeoutAsync(
+        { name: 'Ngrok tunnel open', timeoutMs: 15_000, signal },
+        async openSignal => {
+          openSignal.throwIfAborted();
+          const opening = ngrok
+            .forward({
+              ...config,
+              ...(forceNewSession ? { force_new_session: true } : {}),
+            })
+            .then(listener => {
+              acquired = listener;
+              ownedListeners.add(listener);
+              return listener;
+            })
+            .finally(() => {
+              pendingOpen = undefined;
+            });
+          pendingOpen = opening;
+          void opening
+            .then(() => {
+              if (openSignal.aborted) {
+                retireAcquired();
+              }
+            })
+            .catch(() => releaseTarget());
+          const listener = await opening;
+          openSignal.throwIfAborted();
+          return listener;
+        }
+      );
+    } catch (err) {
+      retireAcquired();
+      throw err;
+    }
+  }
+
+  logger.info(`Starting ngrok tunnel ${domain} -> http://localhost:${port}.`);
+  let publicUrl: string | null;
+  try {
+    currentListener = await openAsync();
+    publicUrl = currentListener.url();
+    if (!publicUrl) {
+      await closeAsync(currentListener, signal);
+      currentListener = undefined;
+      throw new SystemError(`ngrok tunnel for ${domain} did not return a public URL.`);
+    }
+  } catch (error) {
+    controller.abort();
+    releaseTarget();
+    throw error;
+  }
+
+  const url = publicUrl;
+
+  async function probeAsync(
+    baseUrl: string,
+    { path, statuses = [200] }: NonNullable<typeof healthCheck>
+  ): Promise<boolean> {
+    try {
+      return await withDeviceRunSessionTimeoutAsync(
+        { name: 'Ngrok tunnel health probe', timeoutMs: 5_000, signal },
+        async probeSignal => {
+          const requestController = new AbortController();
+          try {
+            const response = await turtleFetch(new URL(path, baseUrl).href, 'GET', {
+              retries: 0,
+              redirect: 'manual',
+              shouldThrowOnNotOk: false,
+              headers: { 'ngrok-skip-browser-warning': 'true', 'Cache-Control': 'no-cache' },
+              signal: AbortSignal.any([probeSignal, requestController.signal]),
+            });
+            return !response.headers.has('ngrok-error-code') && statuses.includes(response.status);
+          } finally {
+            requestController.abort();
+          }
+        }
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  async function superviseAsync(check: NonNullable<typeof healthCheck>): Promise<void> {
+    let failures = 0;
+    let attempts = 0;
+    let localUnhealthy = false;
+    while (
+      await waitAsync(
+        currentListener || localUnhealthy
+          ? PROBE_INTERVAL_MS
+          : Math.min(1_000 * 2 ** Math.min(attempts, 5), 30_000),
+        signal
+      )
+    ) {
+      await Promise.all([...retiredListeners].map(retired => closeAsync(retired, signal, false)));
+      if (signal.aborted) {
+        return;
+      }
+      if (currentListener && (await probeAsync(url, check))) {
+        if (failures > 0 || attempts > 0 || localUnhealthy) {
+          logger.info(`Ngrok tunnel ${domain} is healthy again.`);
+        }
+        failures = 0;
+        attempts = 0;
+        localUnhealthy = false;
+        continue;
+      }
+      if (signal.aborted) {
+        return;
+      }
+      if (!(await probeAsync(`http://127.0.0.1:${port}`, check))) {
+        if (!localUnhealthy && !signal.aborted) {
+          logger.warn(`Local service on port ${port} is unhealthy; waiting for it to recover.`);
+        }
+        localUnhealthy = true;
+        failures = 0;
+        continue;
+      }
+      localUnhealthy = false;
+      if (currentListener) {
+        failures++;
+        if (failures < FAILURE_THRESHOLD) {
+          continue;
+        }
+        logger.warn(`Ngrok tunnel ${domain} failed ${failures} health probes; reopening it.`);
+        await closeAsync(currentListener, signal);
+        currentListener = undefined;
+      }
+      if (signal.aborted) {
+        return;
+      }
+      attempts++;
+      try {
+        const reopened = await openAsync(/* forceNewSession */ true);
+        if (reopened.url() !== url) {
+          await closeAsync(reopened, signal);
+          throw new SystemError(
+            `Reopened ngrok tunnel for ${domain} returned a different public URL.`
+          );
+        }
+        currentListener = reopened;
+        failures = 0;
+      } catch (err) {
+        if (!signal.aborted && (attempts === 1 || attempts % 5 === 0)) {
+          logger.warn(
+            { err, attempt: attempts },
+            `Could not reopen ngrok tunnel ${domain}; will retry.`
+          );
+        }
+      }
+    }
+  }
+
+  const supervision = healthCheck
+    ? superviseAsync(healthCheck).catch(err => {
+        if (!signal.aborted) {
+          logger.warn({ err }, `Ngrok tunnel supervision stopped for ${domain}.`);
+        }
+      })
+    : Promise.resolve();
+  let stopTask: Promise<void> | undefined;
+  return {
+    url,
+    subdomainId,
+    stopAsync: () =>
+      (stopTask ??= (async () => {
+        controller.abort();
+        await withDeviceRunSessionTimeoutAsync(
+          { name: `Ngrok tunnel ${domain} stop`, timeoutMs: STOP_TIMEOUT_MS },
+          async stopSignal => {
+            await supervision;
+            if (currentListener) {
+              retiredListeners.add(currentListener);
+              currentListener = undefined;
+            }
+            await Promise.all([pendingOpen?.catch(() => {}), retireListenersAsync(stopSignal)]);
+            await retireListenersAsync(stopSignal);
+          }
+        );
+        releaseTarget();
+      })()),
+  };
+}
+
+function waitAsync(ms: number, signal: AbortSignal): Promise<boolean> {
+  if (signal.aborted) {
+    return Promise.resolve(false);
+  }
+  return new Promise(resolve => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve(false);
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve(true);
+    }, ms);
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
@@ -9,9 +9,7 @@ import {
  spawnAsync,
 } from '@expo/steps';
 import spawn from '@expo/turtle-spawn';
-import * as ngrok from '@ngrok/ngrok';
 import { z } from 'zod';
-import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import { createServer } from 'node:net';
 import path from 'node:path';
@@ -524,6 +522,14 @@ export async function fetchWebPreviewTurnArgsAsync(
    }
    return args;
  } catch (err) {
+    if (
+      err instanceof DeviceRunSessionWorkerApiError &&
+      err.code === 'DEVICE_RUN_SESSION_ALREADY_STOPPED'
+    ) {
+      logger.info('Device run session was stopped before TURN credentials were fetched.');
+      return [];
+    }
+
    const error = err instanceof Error ? err : new Error(String(err));
    Sentry.capture('Could not fetch Cloudflare TURN ICE servers', error, { level: 'warning' });
    logger.warn(
@@ -959,63 +965,7 @@ export async function findAvailablePortAsync(): Promise<number> {
  return address.port;
 }

-export type NgrokTunnelHandle = {
-  url: string;
-  subdomainId: string;
-  stopAsync: () => Promise<void>;
-};
-
-export async function startNgrokTunnelAsync({
-  port,
-  subdomainPrefix,
-  subdomainId: subdomainIdArg,
-  baseDomain,
-  authtoken,
-  rewriteHostHeader,
-  logger,
-}: {
-  port: number;
-  subdomainPrefix: string;
-  subdomainId?: string;
-  baseDomain: string;
-  authtoken: string;
-  rewriteHostHeader?: boolean;
-  logger: bunyan;
-}): Promise<NgrokTunnelHandle> {
-  const subdomainId = subdomainIdArg ?? randomBytes(16).toString('hex');
-  const domain = `${subdomainPrefix}-${subdomainId}.${baseDomain}`;
-  logger.info(`Starting ngrok tunnel ${domain} -> http://localhost:${port}.`);
-  // Run the ngrok agent in-process via the SDK; it keeps the session alive until
-  // the process exits, and the step blocks forever to hold it open.
-  const listener = await ngrok.forward({
-    addr: port,
-    authtoken,
-    domain,
-    ...(rewriteHostHeader ? { request_header_add: [`Host:localhost:${port}`] } : {}),
-  });
-  const url = listener.url();
-  if (!url) {
-    await listener.close();
-    throw new SystemError(`ngrok tunnel for ${domain} did not return a public URL.`);
-  }
-  let stopTask: Promise<void> | undefined;
-  return {
-    url,
-    subdomainId,
-    stopAsync: () =>
-      (stopTask ??= (async () => {
-        try {
-          await withDeviceRunSessionTimeoutAsync(
-            { name: 'Ngrok tunnel stop', timeoutMs: 4_000 },
-            async () => await listener.close()
-          );
-        } catch (error) {
-          logger.warn({ err: error }, `Could not stop ngrok tunnel ${domain}.`);
-          throw error;
-        }
-      })()),
-  };
-}
+export { type NgrokTunnelHandle, startNgrokTunnelAsync } from './ngrokTunnel';

 export async function waitForFileAsync<T>({
  filePath,
@@ -7,6 +7,7 @@ import { setTimeout } from 'node:timers/promises';
 import { z } from 'zod';

 import { retryAsync } from './retry';
+import { waitForWarmSimulatorCleanupAsync } from './warmSimulatorCleanup';

 export type IosSimulatorUuid = string & z.BRAND<'IosSimulatorUuid'>;
 export type IosSimulatorName = string & z.BRAND<'IosSimulatorName'>;
@@ -119,6 +120,7 @@ export namespace IosSimulatorUtils {
    destinationDeviceName: IosSimulatorName;
    env: NodeJS.ProcessEnv;
  }): Promise<void> {
+    await waitForWarmSimulatorCleanupAsync(env);
    await spawn('xcrun', ['simctl', 'clone', sourceDeviceIdentifier, destinationDeviceName], {
      env,
    });
@@ -131,6 +133,7 @@ export namespace IosSimulatorUtils {
    deviceIdentifier: IosSimulatorUuid | IosSimulatorName;
    env: NodeJS.ProcessEnv;
  }): Promise<void> {
+    await waitForWarmSimulatorCleanupAsync(env);
    try {
      const devices = await getAvailableDevicesAsync({ env, filter: 'available' });
      const device = devices.find(
@@ -231,6 +234,7 @@ export namespace IosSimulatorUtils {
    env: NodeJS.ProcessEnv;
    launchdEnvironment?: Record<string, string>;
  }): Promise<void> {
+    await waitForWarmSimulatorCleanupAsync(env);
    const bootEnv = { ...env };
    for (const [name, value] of Object.entries(launchdEnvironment)) {
      bootEnv[`SIMCTL_CHILD_${name}`] = value;
@@ -253,6 +257,7 @@ export namespace IosSimulatorUtils {
    deviceIdentifier: IosSimulatorUuid | IosSimulatorName;
    env: NodeJS.ProcessEnv;
  }): Promise<{ udid: IosSimulatorUuid }> {
+    await waitForWarmSimulatorCleanupAsync(env);
    const bootstatusResult = await spawn(
      'xcrun',
      ['simctl', 'bootstatus', deviceIdentifier, '-b'],
@@ -5,6 +5,7 @@ import path from 'node:path';

 import { IosSimulatorUtils } from '../IosSimulatorUtils';
 import { retryAsync } from '../retry';
+import { waitForWarmSimulatorCleanupAsync } from '../warmSimulatorCleanup';

 jest.mock('@expo/turtle-spawn', () => ({
  __esModule: true,
@@ -14,6 +15,7 @@ jest.mock('@expo/turtle-spawn', () => ({
 jest.mock('../retry', () => ({
  retryAsync: jest.fn(async fn => await fn(0)),
 }));
+jest.mock('../warmSimulatorCleanup');

 const mockedSpawn = jest.mocked(spawn);

@@ -21,6 +23,7 @@ describe('IosSimulatorUtils', () => {
  beforeEach(() => {
    mockedSpawn.mockReset();
    mockedSpawn.mockResolvedValue({ stdout: '', stderr: '' } as any);
+    jest.mocked(waitForWarmSimulatorCleanupAsync).mockReset().mockResolvedValue(undefined);
  });

  describe(IosSimulatorUtils.getAvailableRuntimesAsync, () => {
@@ -151,6 +154,30 @@ describe('IosSimulatorUtils', () => {
      }) as any);
    }

+    it('waits for warm cleanup before checking device state and writing accessibility prefs', async () => {
+      let finishCleanup: (() => void) | undefined;
+      jest.mocked(waitForWarmSimulatorCleanupAsync).mockImplementationOnce(
+        async () =>
+          await new Promise<void>(resolve => {
+            finishCleanup = resolve;
+          })
+      );
+      mockAvailableDevices([device()]);
+
+      const setup = IosSimulatorUtils.enableAccessibilitySettingsAsync({
+        deviceIdentifier: device().udid as any,
+        env: {},
+      });
+      expect(mockedSpawn).not.toHaveBeenCalled();
+      expect(finishCleanup).toBeDefined();
+      finishCleanup?.();
+      await setup;
+
+      expect(mockedSpawn).toHaveBeenCalledWith('plutil', expect.anything(), {
+        env: {},
+      });
+    });
+
    it('writes accessibility prefs for an exact shutdown simulator match', async () => {
      mockAvailableDevices([
        device({
@@ -76,11 +76,7 @@ describe(getSshRelayServerUrl, () => {
 });

 describe(startSshSessionAsync, () => {
-  const config1: SshConnectionConfig = {
-    type: 'upterm-v1',
-    host: 'relay.expo.dev',
-    secret: 'secret-1',
-  };
+  const config1: SshConnectionConfig = { type: 'upterm-v1', secret: 'secret-1' };
  const config2: SshConnectionConfig = { ...config1, secret: 'secret-2' };
  const target = { type: 'JOB_RUN', id: 'jr-1' } as const;

@@ -133,7 +129,7 @@ describe(startSshSessionAsync, () => {

    expect(mutation).toHaveBeenCalledWith(expect.anything(), {
      target: { type: 'JOB_RUN', id: 'jr-1' },
-      connectionConfig: { ...config1, reconnecting: false, type: 'UPTERM_V1' },
+      connectionConfig: { type: 'UPTERM_V1', secret: 'secret-1', reconnecting: false },
      sessionSettings: { idleTimeoutSeconds: 900 },
    });
    expect(idleTimeoutSeconds).toBe(900);
@@ -155,7 +151,7 @@ describe(startSshSessionAsync, () => {

    expect(mutation).toHaveBeenCalledWith(expect.anything(), {
      target: { type: 'BUILD', id: 'b-1' },
-      connectionConfig: { ...config1, reconnecting: false, type: 'UPTERM_V1' },
+      connectionConfig: { type: 'UPTERM_V1', secret: 'secret-1', reconnecting: false },
      sessionSettings: { idleTimeoutSeconds: 900 },
    });
  });
@@ -242,7 +238,7 @@ describe(startSshSessionAsync, () => {
    );
    expect(mutation).toHaveBeenLastCalledWith(expect.anything(), {
      target: { type: 'JOB_RUN', id: 'jr-1' },
-      connectionConfig: { ...config2, reconnecting: false, type: 'UPTERM_V1' },
+      connectionConfig: { type: 'UPTERM_V1', secret: 'secret-2', reconnecting: false },
      sessionSettings: { idleTimeoutSeconds: 300 },
    });
  });
@@ -298,7 +294,7 @@ describe(startSshSessionAsync, () => {
    expect(host.redialAsync).toHaveBeenCalledTimes(1);
    expect(mutation).toHaveBeenLastCalledWith(expect.anything(), {
      target: { type: 'JOB_RUN', id: 'jr-1' },
-      connectionConfig: { ...config2, reconnecting: false, type: 'UPTERM_V1' },
+      connectionConfig: { type: 'UPTERM_V1', secret: 'secret-2', reconnecting: false },
      sessionSettings: { idleTimeoutSeconds: 300 },
    });
  });
@@ -7,7 +7,6 @@ import { createMockLogger } from '../../__tests__/utils/logger';
 import { BuildContext } from '../../context';
 import { sleepAsync } from '../retry';
 import {
-  connectionConfigFromUptermSession,
  redactConnectionSecrets,
  redactSpawnErrorForLog,
  resolveUptermGcsObjectName,
@@ -42,49 +41,6 @@ describe(resolveUptermGcsObjectName, () => {
  });
 });

-describe(connectionConfigFromUptermSession, () => {
-  it('parses sessionId and host from session current fields', () => {
-    expect(
-      connectionConfigFromUptermSession({
-        sessionId: 'TOKENabc123',
-        host: 'ssh://relay.expo.dev:22',
-      })
-    ).toEqual({
-      type: 'upterm-v1',
-      host: 'relay.expo.dev',
-      secret: 'TOKENabc123',
-    });
-  });
-
-  it('accepts a bare hostname', () => {
-    expect(connectionConfigFromUptermSession({ sessionId: 'tok', host: 'relay.expo.dev' })).toEqual(
-      {
-        type: 'upterm-v1',
-        host: 'relay.expo.dev',
-        secret: 'tok',
-      }
-    );
-  });
-
-  it('keeps a non-default port so the CLI can pass it to ssh -p', () => {
-    expect(
-      connectionConfigFromUptermSession({
-        sessionId: 'tok',
-        host: 'ssh://relay.expo.dev:2222',
-      })
-    ).toEqual({
-      type: 'upterm-v1',
-      host: 'relay.expo.dev:2222',
-      secret: 'tok',
-    });
-  });
-
-  it('returns null when the host is not a parseable url', () => {
-    expect(connectionConfigFromUptermSession({ sessionId: 'tok', host: 'ssh://' })).toBeNull();
-    expect(connectionConfigFromUptermSession({ sessionId: 'tok', host: 'ssh://[' })).toBeNull();
-  });
-});
-
 describe(redactConnectionSecrets, () => {
  it('strips the userinfo secret from a connection string', () => {
    expect(
@@ -257,11 +213,7 @@ describe(startUptermHostAsync, () => {
      relayServerUrl: 'wss://relay.expo.dev',
    });

-    expect(host.connectionConfig).toEqual({
-      type: 'upterm-v1',
-      host: 'relay.expo.dev',
-      secret: 'TOKENx',
-    });
+    expect(host.connectionConfig).toEqual({ type: 'upterm-v1', secret: 'TOKENx' });
    expect(host.isAlive()).toBe(true);
    expect(mockedDownloadFile).not.toHaveBeenCalled();
    expect(mockedSpawn).toHaveBeenCalledWith('upterm', ['version'], {
@@ -369,6 +321,21 @@ describe(startUptermHostAsync, () => {
    );
  });

+  it('keeps polling until upterm reports a session id', async () => {
+    sessionStdout = JSON.stringify({ host: 'ssh://relay.expo.dev:22', clientCount: 0 });
+    mockedSleep.mockImplementationOnce(async () => {
+      sessionStdout = JSON.stringify({
+        sessionId: 'TOKENy',
+        host: 'ssh://relay.expo.dev:22',
+        clientCount: 0,
+      });
+    });
+
+    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
+
+    expect(host.connectionConfig).toEqual({ type: 'upterm-v1', secret: 'TOKENy' });
+  });
+
  it('tears down and rethrows when the host never registers with the relay', async () => {
    jest.useFakeTimers();
    jest.setSystemTime(0);
@@ -420,11 +387,7 @@ describe(startUptermHostAsync, () => {
    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
    const config = await host.redialAsync();

-    expect(config).toEqual({
-      type: 'upterm-v1',
-      host: 'relay.expo.dev',
-      secret: 'TOKENx',
-    });
+    expect(config).toEqual({ type: 'upterm-v1', secret: 'TOKENx' });
    expect(host.connectionConfig).toEqual(config);
  });

@@ -462,11 +425,7 @@ describe(startUptermHostAsync, () => {
    const host = await startUptermHostAsync(makeCtx(), { relayServerUrl: 'wss://r' });
    hostProcess.catch = () => new Promise<void>(() => {});

-    await expect(host.redialAsync()).resolves.toEqual({
-      type: 'upterm-v1',
-      host: 'relay.expo.dev',
-      secret: 'TOKENx',
-    });
+    await expect(host.redialAsync()).resolves.toEqual({ type: 'upterm-v1', secret: 'TOKENx' });
    expect(mockedSleep).toHaveBeenCalledWith(5_000);
  });

@@ -0,0 +1,125 @@
+import spawn from '@expo/turtle-spawn';
+import fs from 'node:fs/promises';
+
+import { waitForWarmSimulatorCleanupAsync } from '../warmSimulatorCleanup';
+
+const STATE_FILE = '/tmp/expo-simulator-startup.json';
+const STARTUP_SCRIPT = '/usr/local/share/vm-tools/startup.sh';
+const platform = Object.getOwnPropertyDescriptor(process, 'platform')!;
+jest.mock('@expo/turtle-spawn');
+
+async function writeStateAsync(state: object): Promise<void> {
+  await fs.mkdir('/tmp', { recursive: true });
+  await fs.writeFile(STATE_FILE, JSON.stringify({ bootUuid: 'current-boot', ...state }));
+}
+
+beforeEach(() => {
+  Object.defineProperty(process, 'platform', { value: 'darwin' });
+  jest.mocked(spawn).mockResolvedValue({ stdout: 'current-boot\n' } as never);
+});
+afterEach(() => {
+  Object.defineProperty(process, 'platform', platform);
+});
+
+it('continues at once on a VM without warmup', async () => {
+  await expect(waitForWarmSimulatorCleanupAsync({})).resolves.toBeUndefined();
+  expect(spawn).not.toHaveBeenCalled();
+});
+
+it('ignores a previous boot cleanup record and reads the current boot only once', async () => {
+  await writeStateAsync({ status: 'disabled', bootUuid: 'old-boot' });
+  let finished = false;
+  const waiting = waitForWarmSimulatorCleanupAsync({}, { pollMs: 5 }).then(() => {
+    finished = true;
+  });
+  await new Promise(resolve => setTimeout(resolve, 30));
+  expect(finished).toBe(false);
+  await writeStateAsync({ status: 'disabled' });
+  await waiting;
+  expect(spawn).toHaveBeenCalledTimes(1);
+});
+
+it('does not accept a cleanup record without a boot ID', async () => {
+  await writeStateAsync({ status: 'disabled', bootUuid: undefined });
+  await expect(waitForWarmSimulatorCleanupAsync({}, { timeoutMs: 20, pollMs: 5 })).rejects.toThrow(
+    'Warm Simulator cleanup did not finish'
+  );
+});
+
+it.each(['failed', 'empty'])('fails closed when the current boot ID is %s', async mode => {
+  await writeStateAsync({ status: 'disabled' });
+  if (mode === 'failed') {
+    jest.mocked(spawn).mockRejectedValueOnce(new Error('sysctl failed'));
+  } else {
+    jest.mocked(spawn).mockResolvedValueOnce({ stdout: '' } as never);
+  }
+  await expect(waitForWarmSimulatorCleanupAsync({})).rejects.toThrow();
+});
+
+it('waits for cleanup when warmup is installed but has not written state yet', async () => {
+  await fs.mkdir('/usr/local/share/vm-tools', { recursive: true });
+  await fs.writeFile(STARTUP_SCRIPT, '');
+  let finished = false;
+  const waiting = waitForWarmSimulatorCleanupAsync({}, { pollMs: 5 }).then(() => {
+    finished = true;
+  });
+  await new Promise(resolve => setTimeout(resolve, 30));
+  expect(finished).toBe(false);
+  await writeStateAsync({ status: 'starting' });
+  await new Promise(resolve => setTimeout(resolve, 30));
+  expect(finished).toBe(false);
+  await writeStateAsync({ status: 'disabled' });
+  await waiting;
+});
+
+it('times out when installed warmup never writes state', async () => {
+  await fs.mkdir('/usr/local/share/vm-tools', { recursive: true });
+  await fs.writeFile(STARTUP_SCRIPT, '');
+  await expect(waitForWarmSimulatorCleanupAsync({}, { timeoutMs: 20, pollMs: 5 })).rejects.toThrow(
+    'Warm Simulator cleanup did not finish; the Simulator cannot be used.'
+  );
+});
+
+it('waits until the launcher records that cleanup finished', async () => {
+  await writeStateAsync({ status: 'ready' });
+  let finished = false;
+  const waiting = waitForWarmSimulatorCleanupAsync({}, { pollMs: 5 }).then(() => {
+    finished = true;
+  });
+  await new Promise(resolve => setTimeout(resolve, 30));
+  expect(finished).toBe(false);
+  await writeStateAsync({ status: 'stopping' });
+  await new Promise(resolve => setTimeout(resolve, 30));
+  expect(finished).toBe(false);
+  await writeStateAsync({ status: 'disabled' });
+  await waiting;
+  expect(finished).toBe(true);
+});
+
+it('fails with the recorded error when cleanup does not finish in time', async () => {
+  await writeStateAsync({ status: 'stopping', error: 'serve-sim did not exit' });
+  await expect(waitForWarmSimulatorCleanupAsync({}, { timeoutMs: 20, pollMs: 5 })).rejects.toThrow(
+    'Warm Simulator cleanup did not finish (serve-sim did not exit); the Simulator cannot be used.'
+  );
+});
+
+it('stops waiting when the job is cancelled', async () => {
+  await writeStateAsync({ status: 'stopping' });
+  const controller = new AbortController();
+  const waiting = waitForWarmSimulatorCleanupAsync({}, { pollMs: 5, signal: controller.signal });
+  controller.abort(new Error('cancelled'));
+  await expect(waiting).rejects.toThrow('cancelled');
+});
+
+it('does not wait for a job that uses the warm Simulator', async () => {
+  await writeStateAsync({ status: 'claimed' });
+  await expect(
+    waitForWarmSimulatorCleanupAsync({ EAS_USE_WARM_SIMULATOR: '1' }, { timeoutMs: 0 })
+  ).resolves.toBeUndefined();
+});
+
+it('does nothing outside macOS', async () => {
+  Object.defineProperty(process, 'platform', { value: 'linux' });
+  await writeStateAsync({ status: 'ready' });
+  await expect(waitForWarmSimulatorCleanupAsync({}, { timeoutMs: 0 })).resolves.toBeUndefined();
+});
@@ -37,11 +37,9 @@ const CONNECTION_STARTUP_TIMEOUT_MS = 60_000;
 const PROCESS_EXIT_TIMEOUT_MS = 5_000;
 const CLIENT_COUNT_READ_ATTEMPTS = 4;
 const CLIENT_COUNT_READ_RETRY_MS = 500;
-const DEFAULT_SSH_PORT = '22';

 export type SshConnectionConfig = {
  type: 'upterm-v1';
-  host: string;
  secret: string;
 };

@@ -55,30 +53,10 @@ export type UptermHost = {

 const UptermSessionJsonZ = z.object({
  sessionId: z.string().min(1),
-  host: z.string().min(1),
  clientCount: z.number().optional(),
 });
 type UptermSessionJson = z.infer<typeof UptermSessionJsonZ>;

-export function connectionConfigFromUptermSession(
-  parsed: Pick<UptermSessionJson, 'sessionId' | 'host'>
-): SshConnectionConfig | null {
-  let host = parsed.host;
-  if (host.includes('://')) {
-    let url: URL;
-    try {
-      url = new URL(host);
-    } catch {
-      return null;
-    }
-    host = url.port && url.port !== DEFAULT_SSH_PORT ? `${url.hostname}:${url.port}` : url.hostname;
-  }
-  if (!host) {
-    return null;
-  }
-  return { type: 'upterm-v1', host, secret: parsed.sessionId };
-}
-
 /**
 * Strip upterm session secrets out of text before it reaches a log or an error message. upterm
 * prints the session id as the userinfo of the connect line it advertises
@@ -196,10 +174,7 @@ async function waitForConnectionConfigAsync(
    if (adminSocketPath) {
      const session = await readCurrentSessionJsonAsync(uptermPath, adminSocketPath);
      if (session) {
-        const connectionConfig = connectionConfigFromUptermSession(session);
-        if (connectionConfig) {
-          return connectionConfig;
-        }
+        return { type: 'upterm-v1', secret: session.sessionId };
      }
    }
    if (Date.now() >= deadline) {
@@ -0,0 +1,61 @@
+import { SystemError } from '@expo/eas-build-job';
+import spawn from '@expo/turtle-spawn';
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { setTimeout as sleepAsync } from 'node:timers/promises';
+
+const LAUNCHER_STATE_FILE = '/tmp/expo-simulator-startup.json';
+const STARTUP_SCRIPT = '/usr/local/share/vm-tools/startup.sh';
+
+/**
+ * The worker stops warmup in the background for a job that does not use the warm Simulator. Wait
+ * here, before the job changes a Simulator, until the launcher records that its cleanup finished.
+ */
+export async function waitForWarmSimulatorCleanupAsync(
+  env: NodeJS.ProcessEnv,
+  {
+    timeoutMs = 150_000,
+    pollMs = 250,
+    signal,
+  }: { timeoutMs?: number; pollMs?: number; signal?: AbortSignal } = {}
+): Promise<void> {
+  if (process.platform !== 'darwin' || env.EAS_USE_WARM_SIMULATOR === '1') {
+    return;
+  }
+  const deadline = Date.now() + timeoutMs;
+  let bootUuid: string | undefined;
+  for (;;) {
+    signal?.throwIfAborted();
+    let state: { status?: unknown; error?: unknown; bootUuid?: unknown };
+    try {
+      state = JSON.parse(await fs.readFile(LAUNCHER_STATE_FILE, 'utf8'));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT' && !existsSync(STARTUP_SCRIPT)) {
+        return;
+      }
+      // Warmup may still be loading; only disabled confirms cleanup on an enabled VM.
+      state = {};
+    }
+    if (state.status === 'disabled' && typeof state.bootUuid === 'string') {
+      bootUuid ??= (
+        await spawn('/usr/sbin/sysctl', ['-n', 'kern.bootsessionuuid'], {
+          signal,
+          timeout: Math.max(1, deadline - Date.now()),
+        })
+      ).stdout.trim();
+      if (!bootUuid) {
+        throw new SystemError('Could not read the current VM boot ID.');
+      }
+      if (state.bootUuid === bootUuid) {
+        return;
+      }
+    }
+    if (Date.now() >= deadline) {
+      throw new SystemError(
+        `Warm Simulator cleanup did not finish${typeof state.error === 'string' ? ` (${state.error})` : ''}; the Simulator cannot be used.`
+      );
+    }
+    // The signal is checked at each poll, so a cancelled job stops within one interval.
+    await sleepAsync(pollMs);
+  }
+}
@@ -1,5 +1,13 @@
 # create-eas-build-function

+## 27.3.0
+
+No changes in this release.
+
+## 27.2.0
+
+No changes in this release.
+
 ## 27.1.0

 No changes in this release.
@@ -1,6 +1,6 @@
 {
  "name": "create-eas-build-function",
-  "version": "27.1.0",
+  "version": "27.3.0",
  "description": "Create functions for use in EAS Build custom builds.",
  "keywords": [
    "expo",
@@ -35,7 +35,7 @@
    "clean": "rimraf ./build/ \"*.tsbuildinfo\""
  },
  "dependencies": {
-    "@expo/steps": "27.1.0"
+    "@expo/steps": "27.3.0"
  },
  "devDependencies": {
    "@expo/package-manager": "1.9.10",
@@ -1,5 +1,13 @@
 # @expo/downloader

+## 27.3.0
+
+No changes in this release.
+
+## 27.2.0
+
+No changes in this release.
+
 ## 27.1.0

 No changes in this release.
@@ -1,6 +1,6 @@
 {
  "name": "@expo/downloader",
-  "version": "27.1.0",
+  "version": "27.3.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
  "author": "Expo <[email protected]>",
@@ -1,5 +1,13 @@
 # eas-build-cache-provider

+## 27.3.0
+
+No changes in this release.
+
+## 27.2.0
+
+No changes in this release.
+
 ## 27.1.0

 No changes in this release.
@@ -1,6 +1,6 @@
 {
  "name": "eas-build-cache-provider",
-  "version": "27.1.0",
+  "version": "27.3.0",
  "description": "A build cache provider plugin for the Expo CLI",
  "homepage": "https://github.com/expo/eas-cli",
  "bugs": "https://github.com/expo/eas-cli/issues",
@@ -1,5 +1,15 @@
 # @expo/eas-build-job

+## 27.3.0
+
+### Minor Changes
+
+- Add optional Observe error context to workflow jobs. ([#4787](https://github.com/expo/eas-cli/pull/4787) by [@AbbanMustafa](https://github.com/AbbanMustafa))
+
+## 27.2.0
+
+No changes in this release.
+
 ## 27.1.0

 No changes in this release.
@@ -1,6 +1,6 @@
 {
  "name": "@expo/eas-build-job",
-  "version": "27.1.0",
+  "version": "27.3.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": "27.1.0",
+    "@expo/logger": "27.3.0",
    "@expo/results": "1.0.0",
-    "@expo/turtle-spawn": "27.1.0",
+    "@expo/turtle-spawn": "27.3.0",
    "joi": "^17.13.1",
    "semver": "^7.6.2",
    "zod": "^4.3.5"
@@ -0,0 +1,95 @@
+import { ArchiveSourceType, BuildTrigger, StaticWorkflowInterpolationContextZ } from '../common';
+import { Generic } from '../generic';
+
+function createContext() {
+  return {
+    after: {},
+    needs: {},
+    workflow: {
+      id: 'workflow-id',
+      name: 'Investigate error',
+      filename: 'observe.yml',
+      url: 'https://expo.dev/accounts/example/workflows/workflow-id',
+    },
+    app: { id: '123e4567-e89b-42d3-a456-426614174000', slug: 'example' },
+    account: { id: 'account-id', name: 'example' },
+    observe: {
+      event: {
+        id: '123e4567-e89b-42d3-a456-426614174001',
+        type: 'new_error' as const,
+        occurredAt: '2026-10-29T12:00:00.000Z',
+        appId: '123e4567-e89b-42d3-a456-426614174000',
+        fingerprint: { value: 'error-fingerprint', version: 'v1' },
+        severity: 'fatal' as const,
+        environment: 'production',
+        platform: 'ios' as const,
+        deviceOs: 'iOS',
+        exception: { type: 'Error', message: 'Example error' },
+      },
+    },
+  };
+}
+
+describe('Observe workflow context', () => {
+  it('preserves the event when validating a generic job', () => {
+    const context = createContext();
+    const job = {
+      projectArchive: { type: ArchiveSourceType.GIT, gitCommitHash: 'abc123', gitRef: null },
+      steps: [{ run: 'echo "${{ observe.event.exception.message }}"', shell: 'sh' }],
+      secrets: { robotAccessToken: 'token', environmentSecrets: [] },
+      expoDevUrl: context.workflow.url,
+      builderEnvironment: { image: 'ubuntu', env: {} },
+      triggeredBy: BuildTrigger.GIT_BASED_INTEGRATION,
+      appId: context.app.id,
+      initiatingUserId: '123e4567-e89b-42d3-a456-426614174002',
+      workflowInterpolationContext: context,
+    };
+
+    const parsed = Generic.JobZ.parse(job);
+
+    expect(parsed.workflowInterpolationContext).toEqual(context);
+  });
+
+  it('accepts nullable event metadata and an omitted device OS', () => {
+    const context = createContext();
+    const nullableContext = {
+      ...context,
+      observe: {
+        event: {
+          ...context.observe.event,
+          fingerprint: { value: 'error-fingerprint', version: null },
+          severity: 'error',
+          environment: null,
+          platform: null,
+          deviceOs: undefined,
+          exception: { type: null, message: null },
+        },
+      },
+    };
+
+    expect(StaticWorkflowInterpolationContextZ.parse(nullableContext)).toEqual(nullableContext);
+  });
+
+  it('preserves additional event fields from a newer producer', () => {
+    const context = createContext();
+    const extendedContext = {
+      ...context,
+      observe: {
+        ...context.observe,
+        event: {
+          ...context.observe.event,
+          additionalMetadata: 'future value',
+          exception: { ...context.observe.event.exception, stacktrace: 'future stack trace' },
+        },
+      },
+    };
+
+    expect(StaticWorkflowInterpolationContextZ.parse(extendedContext)).toEqual(extendedContext);
+  });
+
+  it('rejects an Observe context without an event', () => {
+    expect(
+      StaticWorkflowInterpolationContextZ.safeParse({ ...createContext(), observe: {} }).success
+    ).toBe(false);
+  });
+});
@@ -344,6 +344,24 @@ const SentryContextZ = z.looseObject({
  resolution_type: z.string().optional(),
 });

+const ObserveContextZ = z.looseObject({
+  event: z.looseObject({
+    id: z.uuid(),
+    type: z.literal('new_error'),
+    occurredAt: z.iso.datetime(),
+    appId: z.uuid(),
+    fingerprint: z.looseObject({
+      value: z.string().min(1),
+      version: z.string().min(1).nullable(),
+    }),
+    severity: z.enum(['fatal', 'error']),
+    environment: z.string().nullable(),
+    platform: z.enum(['ios', 'android']).nullable(),
+    deviceOs: z.string().optional(),
+    exception: z.looseObject({ type: z.string().nullable(), message: z.string().nullable() }),
+  }),
+});
+
 export const StaticWorkflowInterpolationContextZ = z.object({
  after: z.record(
    z.string(),
@@ -381,6 +399,7 @@ export const StaticWorkflowInterpolationContextZ = z.object({
  app_store_connect: AppStoreConnectContextZ.optional(),
  // We need to .optional() to support jobs that are not triggered by a Sentry event.
  sentry: SentryContextZ.optional(),
+  observe: ObserveContextZ.optional(),
 });

 export type StaticWorkflowInterpolationContext = z.infer<
@@ -1,5 +1,24 @@
 # eas-cli

+## 27.3.0
+
+### Patch Changes
+
+- Bump `@expo/apple-utils` to `2.3.0` to fix iOS capability sync when App Store Connect rejects enabling, disabling or changing a capability. ([#4790](https://github.com/expo/eas-cli/pull/4790) by [@douglowder](https://github.com/douglowder))
+- Keep already linked App Groups, Merchant IDs and iCloud containers when capability sync links another identifier. ([#4584](https://github.com/expo/eas-cli/pull/4584) by [@ceydaakin](https://github.com/ceydaakin))
+
+## 27.2.0
+
+### Minor Changes
+
+- Add an experiment that suggests Expo Update to coding agents after a build when the Free plan account is within 5 builds of the platform limit. ([#4758](https://github.com/expo/eas-cli/pull/4758) by [@williamgrosset](https://github.com/williamgrosset))
+- Add `eas observe:traces` to list request trace spans (or a summary of span names and counts), `eas observe:trace` to display one trace as a span tree, and span rows in the `eas observe:session` timeline. ([#4772](https://github.com/expo/eas-cli/pull/4772) by [@kadikraman](https://github.com/kadikraman))
+- Show a one-time Expo Simulators hint after a successful build. ([#4768](https://github.com/expo/eas-cli/pull/4768) by [@FiberJW](https://github.com/FiberJW))
+
+### Patch Changes
+
+- Remove the Free plan build limit guidance experiment for coding agents from `eas build`. ([#4757](https://github.com/expo/eas-cli/pull/4757) by [@williamgrosset](https://github.com/williamgrosset))
+
 ## 27.1.0

 ### Minor Changes
@@ -1,6 +1,6 @@
 {
  "name": "eas-cli",
-  "version": "27.1.0",
+  "version": "27.3.0",
  "description": "EAS command line tool",
  "keywords": [
    "cli",
@@ -44,16 +44,16 @@
    "copy-new-templates": "rimraf build/commandUtils/new/templates && mkdir -p build/commandUtils/new && cp -r src/commandUtils/new/templates build/commandUtils/new"
  },
  "dependencies": {
-    "@expo/apple-utils": "2.2.1",
+    "@expo/apple-utils": "2.3.0",
    "@expo/code-signing-certificates": "0.0.5",
    "@expo/config": "55.0.10",
    "@expo/config-plugins": "55.0.7",
-    "@expo/eas-build-job": "27.1.0",
-    "@expo/eas-json": "27.1.0",
+    "@expo/eas-build-job": "27.3.0",
+    "@expo/eas-json": "27.3.0",
    "@expo/env": "^1.0.0",
    "@expo/experimentation": "0.0.5",
    "@expo/json-file": "8.3.3",
-    "@expo/logger": "27.1.0",
+    "@expo/logger": "27.3.0",
    "@expo/multipart-body-parser": "2.0.0",
    "@expo/osascript": "2.1.4",
    "@expo/package-manager": "1.9.10",
@@ -65,7 +65,7 @@
    "@expo/results": "1.0.0",
    "@expo/rudder-sdk-node": "1.1.1",
    "@expo/spawn-async": "1.7.2",
-    "@expo/steps": "27.1.0",
+    "@expo/steps": "27.3.0",
    "@expo/timeago.js": "1.0.0",
    "@oclif/core": "^4.8.3",
    "@oclif/plugin-autocomplete": "^3.2.40",
@@ -70,6 +70,8 @@ export enum BuildEvent {
  BUILD_REQUEST_SUCCESS = 'build cli build request success',
  BUILD_REQUEST_FAIL = 'build cli build request fail',
  FREE_TIER_LIMIT_CHECKOUT_PROMPT = 'build cli free tier limit checkout prompt',
+  FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP = 'build cli free tier near limit agent updates tip',
+  SIMULATORS_LAUNCH_HINT_SHOWN = 'build cli simulators launch hint shown',

  BUILD_STATUS_COMMAND = 'build cli build status',

@@ -1,280 +0,0 @@
-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();
-  });
-});
@@ -0,0 +1,880 @@
+import type { ExperimentationDefinition } from '@expo/experimentation';
+import { ExpoConfig } from '@expo/config';
+
+import { getAgentTelemetryContext } from '../../analytics/agent';
+import { createGraphqlClient } from '../../commandUtils/context/contextUtils/createGraphqlClient';
+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 {
+  AppPlatform,
+  BuildFragment,
+  BuildStatus,
+  EasServiceMetric,
+  UsageMetricType,
+} from '../../graphql/generated';
+import { UserPreferenceMutation } from '../../graphql/mutations/UserPreferenceMutation';
+import { AccountQuery } from '../../graphql/queries/AccountQuery';
+import { UserPreferenceQuery } from '../../graphql/queries/UserPreferenceQuery';
+import Log from '../../log';
+import { isExpoUpdatesInstalled, isUsingEASUpdate } from '../../project/projectUtils';
+import { LoggedInAuthenticationInfo } from '../../user/SessionManager';
+import { Actor } from '../../user/User';
+import {
+  FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP_EXPERIMENT_NAMESPACE,
+  FreeTierNearLimitAgentUpdatesTipExperiment,
+  FreeTierNearLimitAgentUpdatesTipPlatformProject,
+  formatFreeTierNearLimitAgentUpdatesTip,
+  getFreeTierBuildUsageAsync,
+  getFreeTierNearLimitAgentUpdatesTipExperiment,
+  getFreeTierNearLimitAgentUpdatesTipPreferenceKey,
+  isEligibleForFreeTierNearLimitAgentUpdatesTip,
+  isPlatformEligibleForFreeTierNearLimitAgentUpdatesTip,
+  isWithinFreeTierNearLimitBand,
+  maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync,
+  resolveFreeTierNearLimitAgentUpdatesTipVariantAsync,
+} from '../freeTierNearLimitAgentUpdatesTip';
+
+jest.mock('../../analytics/agent');
+jest.mock('../../commandUtils/context/contextUtils/createGraphqlClient');
+jest.mock('../../graphql/queries/AccountQuery');
+jest.mock('../../graphql/queries/UserPreferenceQuery');
+jest.mock('../../graphql/mutations/UserPreferenceMutation');
+jest.mock('../../project/projectUtils', () => ({
+  ...jest.requireActual('../../project/projectUtils'),
+  isExpoUpdatesInstalled: jest.fn(),
+  isUsingEASUpdate: jest.fn(),
+}));
+
+const EXPERIMENT_NAME = 'cli-build-free-tier-near-limit-agent-updates-tip';
+const ANALYTICS_EVENT_PROPERTIES = { tracking_id: 'tracking-id' };
+const EXP = { name: 'app', slug: 'app' } as ExpoConfig;
+const IOS_EXP = { name: 'app', slug: 'app', ios: { bundleIdentifier: 'com.app' } } as ExpoConfig;
+const USER = { __typename: 'User', id: 'user-id' } as Actor;
+const SSO_USER = { __typename: 'SSOUser', id: 'sso-user-id' } as Actor;
+const ROBOT = { __typename: 'Robot', id: 'robot-id' } as Actor;
+const PARTNER = { __typename: 'PartnerActor', id: 'partner-id' } as Actor;
+const AUTHENTICATION_INFO: LoggedInAuthenticationInfo = {
+  accessToken: 'access-token',
+  sessionSecret: null,
+};
+const GRAPHQL_CLIENT = {} as FreeTierNearLimitAgentUpdatesTipExperiment['graphqlClient'];
+
+const ANDROID_KEY = 'free-tier-near-limit-agent-updates-tip-shown/account-id/android';
+const IOS_KEY = 'free-tier-near-limit-agent-updates-tip-shown/account-id/ios';
+
+const ANDROID_TIP_11_OF_15 = [
+  "Tip: this account has used 11 of 15 Android builds on the Free plan this period. This project isn't set up for Expo Update, so every change needs a new build.",
+  'With Expo Update, JavaScript, styling and image changes reach installed builds without a new build. Setup takes effect from the next build, so it saves the most builds if done now.',
+  'Next: eas update:configure --non-interactive, then build once more.',
+  'Tell the user: this adds expo-updates and changes app.json and eas.json.',
+  'Docs: https://docs.expo.dev/eas-update/getting-started/',
+].join('\n');
+
+function accountDefinition(enrolledSegments: number): ExperimentationDefinition {
+  return {
+    experiments: [
+      {
+        experimentName: EXPERIMENT_NAME,
+        paramDefinitions: {
+          variant: { type: 'uniform_choice', choices: ['control', 'treatment'] },
+        },
+        exposureLoggerType: 'rudderstack',
+      },
+    ],
+    namespaces: [
+      {
+        name: FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP_EXPERIMENT_NAMESPACE,
+        numSegments: 1000,
+        segmentExperimentSetupDefinitions: [
+          {
+            method: 'ADD',
+            name: `${EXPERIMENT_NAME} rollout`,
+            experimentName: EXPERIMENT_NAME,
+            numSegments: enrolledSegments,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/** Every account is in the experiment: 50% control, 50% treatment. */
+const ACCOUNT_DEFINITION = accountDefinition(1000);
+
+/** Like the production soft launch: 20% of accounts are in the experiment. */
+const PARTIAL_ROLLOUT_DEFINITION = accountDefinition(200);
+
+function createClient(definition: ExperimentationDefinition = ACCOUNT_DEFINITION): {
+  client: ExperimentationClient;
+  analytics: ReturnType<typeof createMockAnalytics>;
+} {
+  const analytics = createMockAnalytics();
+  const client = new ExperimentationClient(
+    {
+      user: EMPTY_EXPERIMENTATION_DEFINITION,
+      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. The
+ * probe uses a null default, so accounts outside the rollout can be told apart from control.
+ */
+function findAccountIdsByVariant(
+  definition: ExperimentationDefinition,
+  variants: (string | null)[]
+): Map<string | null, string> {
+  const { client } = createClient(definition);
+  return findUnitsByValue(
+    accountId =>
+      client.getAccountNamespace(FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP_EXPERIMENT_NAMESPACE, {
+        accountId,
+      }),
+    'variant',
+    null,
+    variants
+  );
+}
+
+function createOverriddenClient(variant: string): ExperimentationClient {
+  return ExperimentationClient.createDisabled(
+    new ExperimentOverrides(
+      new Map([
+        [FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP_EXPERIMENT_NAMESPACE, new Map([['variant', variant]])],
+      ])
+    )
+  );
+}
+
+function project(
+  overrides: Partial<FreeTierNearLimitAgentUpdatesTipPlatformProject> = {}
+): FreeTierNearLimitAgentUpdatesTipPlatformProject {
+  return {
+    developmentClient: false,
+    projectDir: '/app',
+    projectId: 'project-id',
+    exp: EXP,
+    manifestHostOverride: null,
+    ...overrides,
+  };
+}
+
+function createExperiment(
+  accountId: string,
+  {
+    client = createClient().client,
+    runFromCI = false,
+    json = false,
+    isUser = true,
+    analytics = createMockAnalytics(),
+    projectByPlatform = { [AppPlatform.Android]: project(), [AppPlatform.Ios]: project() },
+  }: {
+    client?: ExperimentationClient;
+    runFromCI?: boolean;
+    json?: boolean;
+    isUser?: boolean;
+    analytics?: ReturnType<typeof createMockAnalytics>;
+    projectByPlatform?: FreeTierNearLimitAgentUpdatesTipExperiment['projectByPlatform'];
+  } = {}
+): FreeTierNearLimitAgentUpdatesTipExperiment {
+  return {
+    experimentation: LazyExperimentationClient.fromClient(client),
+    graphqlClient: GRAPHQL_CLIENT,
+    analytics,
+    analyticsEventProperties: ANALYTICS_EVENT_PROPERTIES,
+    accountId,
+    isUser,
+    runFromCI,
+    json,
+    projectByPlatform,
+  };
+}
+
+function build(platform: AppPlatform, status: BuildStatus = BuildStatus.Finished): BuildFragment {
+  return { id: `${platform}-build`, platform, status } as BuildFragment;
+}
+
+type PlatformUsage = { value: number; limit: number };
+
+function usageResponse({
+  subscriptionName = 'Free' as string | null,
+  android = { value: 11, limit: 15 } as PlatformUsage,
+  ios = { value: 3, limit: 15 } as PlatformUsage,
+  billingPeriodId = 'period-1',
+  platformBreakdown = true,
+} = {}): Awaited<ReturnType<typeof AccountQuery.getFreeTierBuildUsageAsync>> {
+  return {
+    id: 'account-id',
+    subscription: subscriptionName === null ? null : { id: 'subscription-id', name: subscriptionName },
+    billingPeriod: {
+      id: billingPeriodId,
+      start: '2026-10-01T00:00:00.000Z',
+      end: '2026-11-01T00:00:00.000Z',
+    },
+    usageMetrics: {
+      EAS_BUILD: {
+        id: 'eas-build',
+        planMetrics: [
+          {
+            id: 'builds',
+            serviceMetric: EasServiceMetric.Builds,
+            metricType: UsageMetricType.Build,
+            value: android.value + ios.value,
+            limit: android.limit + ios.limit,
+            platformBreakdown: platformBreakdown ? { android, ios } : null,
+          },
+        ],
+      },
+    },
+  };
+}
+
+const accountIdsByVariant = findAccountIdsByVariant(ACCOUNT_DEFINITION, ['control', 'treatment']);
+const treatmentAccountId = accountIdsByVariant.get('treatment')!;
+const controlAccountId = accountIdsByVariant.get('control')!;
+/** An account outside the partial rollout. */
+const notEnrolledAccountId = findAccountIdsByVariant(PARTIAL_ROLLOUT_DEFINITION, [null]).get(null)!;
+
+/** In-memory stand-in for the server-side user preference store, keyed by preference key. */
+let shownTips: Record<string, unknown>;
+let logSpy: jest.SpyInstance;
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  shownTips = {};
+  jest
+    .mocked(UserPreferenceQuery.getValueAsync)
+    .mockImplementation(async (_graphqlClient, key) => shownTips[key] ?? null);
+  jest
+    .mocked(UserPreferenceMutation.setAsync)
+    .mockImplementation(async (_graphqlClient, key, value) => {
+      shownTips[key] = value;
+    });
+  jest.mocked(getAgentTelemetryContext).mockReturnValue({ id: 'claude-code', sessionId: 's-1' });
+  jest.mocked(createGraphqlClient).mockReturnValue(GRAPHQL_CLIENT);
+  jest.mocked(isExpoUpdatesInstalled).mockReturnValue(false);
+  jest.mocked(isUsingEASUpdate).mockReturnValue(false);
+  jest.mocked(AccountQuery.getFreeTierBuildUsageAsync).mockResolvedValue(usageResponse());
+  logSpy = jest.spyOn(Log, 'log').mockImplementation(() => {});
+});
+
+describe(getFreeTierNearLimitAgentUpdatesTipExperiment, () => {
+  const ctx = {
+    authenticationInfo: AUTHENTICATION_INFO,
+    analytics: createMockAnalytics(),
+    analyticsEventProperties: ANALYTICS_EVENT_PROPERTIES,
+    accountId: 'account-id',
+    user: USER,
+    developmentClient: false,
+    projectDir: '/app',
+    projectId: 'project-id',
+    exp: EXP,
+    easJsonCliConfig: { updateManifestHostOverride: 'https://u.example.com' },
+    runFromCI: false,
+  };
+
+  it('returns the handle when the command has an experimentation client', () => {
+    const experimentation = new LazyExperimentationClient(async () => createClient().client);
+
+    expect(
+      getFreeTierNearLimitAgentUpdatesTipExperiment(
+        { [AppPlatform.Android]: { ...ctx, experimentation } },
+        { json: true }
+      )
+    ).toEqual({
+      experimentation,
+      graphqlClient: GRAPHQL_CLIENT,
+      analytics: ctx.analytics,
+      analyticsEventProperties: ANALYTICS_EVENT_PROPERTIES,
+      accountId: 'account-id',
+      isUser: true,
+      runFromCI: false,
+      json: true,
+      projectByPlatform: {
+        [AppPlatform.Android]: {
+          developmentClient: false,
+          projectDir: '/app',
+          projectId: 'project-id',
+          exp: EXP,
+          manifestHostOverride: 'https://u.example.com',
+        },
+      },
+    });
+  });
+
+  it('keeps the project state of each platform', () => {
+    const experimentation = new LazyExperimentationClient(async () => createClient().client);
+
+    expect(
+      getFreeTierNearLimitAgentUpdatesTipExperiment(
+        {
+          [AppPlatform.Android]: { ...ctx, experimentation },
+          [AppPlatform.Ios]: {
+            ...ctx,
+            experimentation,
+            exp: IOS_EXP,
+            developmentClient: true,
+            easJsonCliConfig: undefined,
+          },
+        },
+        { json: false }
+      )?.projectByPlatform
+    ).toEqual({
+      [AppPlatform.Android]: project({ manifestHostOverride: 'https://u.example.com' }),
+      [AppPlatform.Ios]: project({ exp: IOS_EXP, developmentClient: true }),
+    });
+  });
+
+  it('creates one GraphQL client with a request timeout', () => {
+    const experimentation = new LazyExperimentationClient(async () => createClient().client);
+
+    getFreeTierNearLimitAgentUpdatesTipExperiment(
+      {
+        [AppPlatform.Android]: { ...ctx, experimentation },
+        [AppPlatform.Ios]: { ...ctx, experimentation },
+      },
+      { json: false }
+    );
+
+    expect(createGraphqlClient).toHaveBeenCalledTimes(1);
+    expect(createGraphqlClient).toHaveBeenCalledWith(AUTHENTICATION_INFO, {
+      requestTimeoutMs: 3000,
+    });
+  });
+
+  it.each([
+    ['a regular user', USER, true],
+    ['an SSO user', SSO_USER, true],
+    ['a robot', ROBOT, false],
+    ['a partner actor', PARTNER, false],
+  ])('marks %s with isUser %p', (_label, user, isUser) => {
+    const experimentation = new LazyExperimentationClient(async () => createClient().client);
+
+    expect(
+      getFreeTierNearLimitAgentUpdatesTipExperiment(
+        { [AppPlatform.Android]: { ...ctx, user, experimentation } },
+        { json: false }
+      )?.isUser
+    ).toBe(isUser);
+  });
+
+  it('returns undefined when the command has no experimentation client', () => {
+    expect(
+      getFreeTierNearLimitAgentUpdatesTipExperiment({ [AppPlatform.Android]: ctx }, { json: false })
+    ).toBeUndefined();
+  });
+
+  it('returns undefined when the command has no authentication info', () => {
+    const experimentation = new LazyExperimentationClient(async () => createClient().client);
+
+    expect(
+      getFreeTierNearLimitAgentUpdatesTipExperiment(
+        { [AppPlatform.Android]: { ...ctx, authenticationInfo: undefined, experimentation } },
+        { json: false }
+      )
+    ).toBeUndefined();
+    expect(createGraphqlClient).not.toHaveBeenCalled();
+  });
+
+  it('returns undefined without build contexts', () => {
+    expect(getFreeTierNearLimitAgentUpdatesTipExperiment({}, { json: false })).toBeUndefined();
+  });
+});
+
+describe(isEligibleForFreeTierNearLimitAgentUpdatesTip, () => {
+  it('accepts agent runs', () => {
+    expect(isEligibleForFreeTierNearLimitAgentUpdatesTip(createExperiment('account-id'))).toBe(true);
+  });
+
+  it('rejects runs without a coding agent', () => {
+    jest.mocked(getAgentTelemetryContext).mockReturnValue(null);
+
+    expect(isEligibleForFreeTierNearLimitAgentUpdatesTip(createExperiment('account-id'))).toBe(false);
+  });
+
+  it('rejects runs from CI', () => {
+    expect(
+      isEligibleForFreeTierNearLimitAgentUpdatesTip(createExperiment('account-id', { runFromCI: true }))
+    ).toBe(false);
+  });
+
+  it('rejects robot and partner actors, which cannot store user preferences', () => {
+    expect(
+      isEligibleForFreeTierNearLimitAgentUpdatesTip(createExperiment('account-id', { isUser: false }))
+    ).toBe(false);
+  });
+
+  it('rejects --json runs', () => {
+    expect(
+      isEligibleForFreeTierNearLimitAgentUpdatesTip(createExperiment('account-id', { json: true }))
+    ).toBe(false);
+  });
+});
+
+describe(isPlatformEligibleForFreeTierNearLimitAgentUpdatesTip, () => {
+  it('accepts a project without Expo Update', () => {
+    expect(isPlatformEligibleForFreeTierNearLimitAgentUpdatesTip(project())).toBe(true);
+  });
+
+  it('accepts a project with expo-updates installed but no Expo Update URL', () => {
+    jest.mocked(isExpoUpdatesInstalled).mockReturnValue(true);
+
+    expect(isPlatformEligibleForFreeTierNearLimitAgentUpdatesTip(project())).toBe(true);
+  });
+
+  it('rejects a project that is already set up for Expo Update', () => {
+    jest.mocked(isExpoUpdatesInstalled).mockReturnValue(true);
+    jest.mocked(isUsingEASUpdate).mockReturnValue(true);
+
+    expect(isPlatformEligibleForFreeTierNearLimitAgentUpdatesTip(project())).toBe(false);
+    expect(isUsingEASUpdate).toHaveBeenCalledWith(EXP, 'project-id', null);
+  });
+
+  it('rejects development builds, which load JavaScript from the dev server', () => {
+    expect(
+      isPlatformEligibleForFreeTierNearLimitAgentUpdatesTip(project({ developmentClient: true }))
+    ).toBe(false);
+  });
+});
+
+describe(isWithinFreeTierNearLimitBand, () => {
+  it.each([
+    [9, false],
+    [10, true],
+    [11, true],
+    [14, true],
+    [15, false],
+    [16, false],
+  ])('used %s of 15 → %s', (used, expected) => {
+    expect(isWithinFreeTierNearLimitBand({ used, limit: 15 })).toBe(expected);
+  });
+
+  it('is false without a limit', () => {
+    expect(isWithinFreeTierNearLimitBand({ used: 0, limit: 0 })).toBe(false);
+  });
+});
+
+describe(getFreeTierBuildUsageAsync, () => {
+  it('returns the per-platform usage for a Free account', async () => {
+    expect(await getFreeTierBuildUsageAsync(createExperiment('account-id'))).toEqual({
+      billingPeriodId: 'period-1',
+      byPlatform: {
+        [AppPlatform.Android]: { used: 11, limit: 15 },
+        [AppPlatform.Ios]: { used: 3, limit: 15 },
+      },
+    });
+    expect(AccountQuery.getFreeTierBuildUsageAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      'account-id',
+      expect.any(Date)
+    );
+  });
+
+  it('treats an account without a subscription as Free', async () => {
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockResolvedValue(usageResponse({ subscriptionName: null }));
+
+    expect(await getFreeTierBuildUsageAsync(createExperiment('account-id'))).not.toBeNull();
+  });
+
+  it('returns null for a paid plan', async () => {
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockResolvedValue(usageResponse({ subscriptionName: 'Starter' }));
+
+    expect(await getFreeTierBuildUsageAsync(createExperiment('account-id'))).toBeNull();
+  });
+
+  it('returns null without a platform breakdown', async () => {
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockResolvedValue(usageResponse({ platformBreakdown: false }));
+
+    expect(await getFreeTierBuildUsageAsync(createExperiment('account-id'))).toBeNull();
+  });
+});
+
+describe(resolveFreeTierNearLimitAgentUpdatesTipVariantAsync, () => {
+  it('returns the account variant and logs the exposure once', async () => {
+    const { client, analytics } = createClient();
+    const experiment = createExperiment(treatmentAccountId, { client });
+
+    expect(await resolveFreeTierNearLimitAgentUpdatesTipVariantAsync(experiment)).toBe('treatment');
+    expect(await resolveFreeTierNearLimitAgentUpdatesTipVariantAsync(experiment)).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 resolveFreeTierNearLimitAgentUpdatesTipVariantAsync(
+        createExperiment(controlAccountId, { client })
+      )
+    ).toBe('control');
+    expect(analytics.logEvent).toHaveBeenCalledWith('Experiment Viewed', {
+      experimentName: EXPERIMENT_NAME,
+      variationName: 'control',
+      unit: controlAccountId,
+    });
+  });
+
+  it('returns control and logs no exposure for an account outside the rollout', async () => {
+    const { client, analytics } = createClient(PARTIAL_ROLLOUT_DEFINITION);
+
+    expect(
+      await resolveFreeTierNearLimitAgentUpdatesTipVariantAsync(
+        createExperiment(notEnrolledAccountId, { client })
+      )
+    ).toBe('control');
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+  });
+
+  it('returns control and logs no exposure when the namespace is missing from the config', async () => {
+    const { client, analytics } = createClient(EMPTY_EXPERIMENTATION_DEFINITION);
+
+    expect(
+      await resolveFreeTierNearLimitAgentUpdatesTipVariantAsync(
+        createExperiment(treatmentAccountId, { client })
+      )
+    ).toBe('control');
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+  });
+});
+
+describe(getFreeTierNearLimitAgentUpdatesTipPreferenceKey, () => {
+  it('scopes the key to the account and the lowercase platform', () => {
+    expect(getFreeTierNearLimitAgentUpdatesTipPreferenceKey('account-id', AppPlatform.Android)).toBe(
+      ANDROID_KEY
+    );
+    expect(getFreeTierNearLimitAgentUpdatesTipPreferenceKey('account-id', AppPlatform.Ios)).toBe(
+      IOS_KEY
+    );
+  });
+});
+
+describe(formatFreeTierNearLimitAgentUpdatesTip, () => {
+  it('formats the Android tip', () => {
+    expect(
+      formatFreeTierNearLimitAgentUpdatesTip({ platform: AppPlatform.Android, used: 11, limit: 15 })
+    ).toBe(ANDROID_TIP_11_OF_15);
+  });
+
+  it('formats the iOS tip', () => {
+    expect(
+      formatFreeTierNearLimitAgentUpdatesTip({ platform: AppPlatform.Ios, used: 14, limit: 15 })
+    ).toContain('Tip: this account has used 14 of 15 iOS builds on the Free plan this period.');
+  });
+});
+
+describe(maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync, () => {
+  function treatmentExperiment(
+    options: Parameters<typeof createExperiment>[1] = {}
+  ): FreeTierNearLimitAgentUpdatesTipExperiment {
+    return createExperiment('account-id', {
+      client: createOverriddenClient('treatment'),
+      ...options,
+    });
+  }
+
+  it('does nothing when the command has no experiment handle', async () => {
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync([build(AppPlatform.Android)], undefined);
+
+    expect(AccountQuery.getFreeTierBuildUsageAsync).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
+  it('requests no usage for ineligible runs', async () => {
+    jest.mocked(getAgentTelemetryContext).mockReturnValue(null);
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android)],
+      treatmentExperiment()
+    );
+
+    expect(AccountQuery.getFreeTierBuildUsageAsync).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
+  it('requests no usage when no build finished', async () => {
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android, BuildStatus.Errored), null],
+      treatmentExperiment()
+    );
+
+    expect(AccountQuery.getFreeTierBuildUsageAsync).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
+  it('requests no usage when no finished platform is eligible', async () => {
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android)],
+      treatmentExperiment({
+        projectByPlatform: { [AppPlatform.Android]: project({ developmentClient: true }) },
+      })
+    );
+
+    expect(AccountQuery.getFreeTierBuildUsageAsync).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
+  it('checks each platform against its own build context', async () => {
+    // Only the iOS build evaluated a config with the Expo Update URL.
+    jest.mocked(isExpoUpdatesInstalled).mockReturnValue(true);
+    jest.mocked(isUsingEASUpdate).mockImplementation(exp => exp === IOS_EXP);
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockResolvedValue(usageResponse({ ios: { value: 14, limit: 15 } }));
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android), build(AppPlatform.Ios)],
+      treatmentExperiment({
+        projectByPlatform: {
+          [AppPlatform.Android]: project(),
+          [AppPlatform.Ios]: project({ exp: IOS_EXP }),
+        },
+      })
+    );
+
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy).toHaveBeenCalledWith(ANDROID_TIP_11_OF_15);
+    expect(shownTips).toEqual({ [ANDROID_KEY]: { billingPeriodId: 'period-1' } });
+  });
+
+  it('prints the tip in the treatment arm and remembers it for the billing period', async () => {
+    const experiment = treatmentExperiment();
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync([build(AppPlatform.Android)], experiment);
+
+    expect(logSpy).toHaveBeenCalledWith(ANDROID_TIP_11_OF_15);
+    expect(shownTips).toEqual({ [ANDROID_KEY]: { billingPeriodId: 'period-1' } });
+    expect(UserPreferenceMutation.setAsync).toHaveBeenCalledWith(GRAPHQL_CLIENT, ANDROID_KEY, {
+      billingPeriodId: 'period-1',
+    });
+    expect(experiment.analytics.logEvent).toHaveBeenCalledWith(
+      'build cli free tier near limit agent updates tip',
+      {
+        ...ANALYTICS_EVENT_PROPERTIES,
+        platform: AppPlatform.Android,
+        builds_used: 11,
+        builds_limit: 15,
+      }
+    );
+  });
+
+  it('prints nothing and writes no marker in the control arm, but records the exposure', async () => {
+    const { client, analytics } = createClient();
+    const experiment = createExperiment(controlAccountId, { client, analytics });
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync([build(AppPlatform.Android)], experiment);
+
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(shownTips).toEqual({});
+    expect(UserPreferenceMutation.setAsync).not.toHaveBeenCalled();
+    expect(analytics.logEvent).toHaveBeenCalledWith('Experiment Viewed', {
+      experimentName: EXPERIMENT_NAME,
+      variationName: 'control',
+      unit: controlAccountId,
+    });
+    expect(analytics.logEvent).not.toHaveBeenCalledWith(
+      'build cli free tier near limit agent updates tip',
+      expect.anything()
+    );
+  });
+
+  it('does nothing for an account outside the experiment', async () => {
+    const { client, analytics } = createClient(PARTIAL_ROLLOUT_DEFINITION);
+    const experiment = createExperiment(notEnrolledAccountId, { client, analytics });
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync([build(AppPlatform.Android)], experiment);
+
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+    expect(shownTips).toEqual({});
+    expect(UserPreferenceMutation.setAsync).not.toHaveBeenCalled();
+  });
+
+  it('logs the exposure only after the usage checks pass', async () => {
+    const { client, analytics } = createClient();
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockResolvedValue(usageResponse({ android: { value: 9, limit: 15 } }));
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android)],
+      createExperiment(treatmentAccountId, { client, analytics })
+    );
+
+    expect(analytics.logEvent).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(UserPreferenceQuery.getValueAsync).not.toHaveBeenCalled();
+    expect(UserPreferenceMutation.setAsync).not.toHaveBeenCalled();
+  });
+
+  it('does nothing for paid plans', async () => {
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockResolvedValue(usageResponse({ subscriptionName: 'Production' }));
+    const experiment = treatmentExperiment();
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync([build(AppPlatform.Android)], experiment);
+
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(experiment.analytics.logEvent).not.toHaveBeenCalled();
+  });
+
+  it('does not repeat the tip within the same billing period for this user', async () => {
+    shownTips = { [ANDROID_KEY]: { billingPeriodId: 'period-1' } };
+    const experiment = treatmentExperiment();
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync([build(AppPlatform.Android)], experiment);
+
+    expect(UserPreferenceQuery.getValueAsync).toHaveBeenCalledWith(GRAPHQL_CLIENT, ANDROID_KEY);
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(experiment.analytics.logEvent).not.toHaveBeenCalled();
+    expect(UserPreferenceMutation.setAsync).not.toHaveBeenCalled();
+  });
+
+  it('shows the tip again in a new billing period', async () => {
+    const otherAccountIosKey = 'free-tier-near-limit-agent-updates-tip-shown/other-account/ios';
+    shownTips = {
+      [ANDROID_KEY]: { billingPeriodId: 'period-0' },
+      [otherAccountIosKey]: { billingPeriodId: 'period-1' },
+    };
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android)],
+      treatmentExperiment()
+    );
+
+    expect(logSpy).toHaveBeenCalledWith(ANDROID_TIP_11_OF_15);
+    expect(shownTips).toEqual({
+      [ANDROID_KEY]: { billingPeriodId: 'period-1' },
+      [otherAccountIosKey]: { billingPeriodId: 'period-1' },
+    });
+  });
+
+  it('treats a malformed stored preference as not shown', async () => {
+    shownTips = { [ANDROID_KEY]: 'period-1' };
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android)],
+      treatmentExperiment()
+    );
+
+    expect(logSpy).toHaveBeenCalledWith(ANDROID_TIP_11_OF_15);
+    expect(shownTips).toEqual({ [ANDROID_KEY]: { billingPeriodId: 'period-1' } });
+  });
+
+  it('checks each finished platform with one usage request', async () => {
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockResolvedValue(usageResponse({ ios: { value: 14, limit: 15 } }));
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android), build(AppPlatform.Ios)],
+      treatmentExperiment()
+    );
+
+    expect(AccountQuery.getFreeTierBuildUsageAsync).toHaveBeenCalledTimes(1);
+    expect(logSpy).toHaveBeenCalledTimes(2);
+    expect(logSpy).toHaveBeenCalledWith(ANDROID_TIP_11_OF_15);
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining('used 14 of 15 iOS builds on the Free plan')
+    );
+    expect(shownTips).toEqual({
+      [ANDROID_KEY]: { billingPeriodId: 'period-1' },
+      [IOS_KEY]: { billingPeriodId: 'period-1' },
+    });
+  });
+
+  it('skips platforms outside the band', async () => {
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android), build(AppPlatform.Ios)],
+      treatmentExperiment()
+    );
+
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy).toHaveBeenCalledWith(ANDROID_TIP_11_OF_15);
+    expect(shownTips).toEqual({ [ANDROID_KEY]: { billingPeriodId: 'period-1' } });
+  });
+
+  it('still shows the tip and logs the events when the marker write fails', async () => {
+    jest.mocked(UserPreferenceMutation.setAsync).mockRejectedValue(new Error('forbidden'));
+    const { client, analytics } = createClient();
+    const experiment = createExperiment(treatmentAccountId, { client, analytics });
+
+    await expect(
+      maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync([build(AppPlatform.Android)], experiment)
+    ).resolves.toBeUndefined();
+
+    expect(logSpy).toHaveBeenCalledWith(ANDROID_TIP_11_OF_15);
+    expect(analytics.logEvent).toHaveBeenCalledWith('Experiment Viewed', {
+      experimentName: EXPERIMENT_NAME,
+      variationName: 'treatment',
+      unit: treatmentAccountId,
+    });
+    expect(analytics.logEvent).toHaveBeenCalledWith(
+      'build cli free tier near limit agent updates tip',
+      expect.objectContaining({ platform: AppPlatform.Android })
+    );
+    expect(shownTips).toEqual({});
+  });
+
+  it('still checks the next platform when a marker write fails', async () => {
+    jest
+      .mocked(UserPreferenceMutation.setAsync)
+      .mockRejectedValueOnce(new Error('forbidden'))
+      .mockImplementation(async (_graphqlClient, key, value) => {
+        shownTips[key] = value;
+      });
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockResolvedValue(usageResponse({ ios: { value: 14, limit: 15 } }));
+
+    await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+      [build(AppPlatform.Android), build(AppPlatform.Ios)],
+      treatmentExperiment()
+    );
+
+    expect(logSpy).toHaveBeenCalledTimes(2);
+    expect(logSpy).toHaveBeenCalledWith(ANDROID_TIP_11_OF_15);
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining('used 14 of 15 iOS builds on the Free plan')
+    );
+    expect(shownTips).toEqual({ [IOS_KEY]: { billingPeriodId: 'period-1' } });
+  });
+
+  it('fails open when the usage request fails', async () => {
+    jest
+      .mocked(AccountQuery.getFreeTierBuildUsageAsync)
+      .mockRejectedValue(new Error('network down'));
+    const experiment = treatmentExperiment();
+
+    await expect(
+      maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync([build(AppPlatform.Android)], experiment)
+    ).resolves.toBeUndefined();
+
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(experiment.analytics.logEvent).not.toHaveBeenCalled();
+  });
+});
@@ -5,12 +5,8 @@ import { GraphQLError } from 'graphql/error';
 import { v4 as uuidv4 } from 'uuid';

 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 { handleBuildRequestErrorAsync } from '../build';
 import {
@@ -30,12 +26,7 @@ import {
  FreeTierLimitCheckoutExperiment,
  maybeOfferFreeTierLimitCheckoutAsync,
 } from '../freeTierLimitCheckout';
-import {
-  FREE_TIER_LIMIT_AGENT_GUIDANCE_EXPERIMENT_NAMESPACE,
-  FreeTierLimitAgentGuidanceExperiment,
-} from '../freeTierLimitGuidance';

-jest.mock('../../analytics/agent');
 jest.mock('../freeTierLimitCheckout', () => ({
  ...jest.requireActual('../freeTierLimitCheckout'),
  maybeOfferFreeTierLimitCheckoutAsync: jest.fn(),
@@ -45,26 +36,9 @@ const CHECKOUT_EXPERIMENT = { accountId: 'account-id' } as FreeTierLimitCheckout

 beforeEach(() => {
  jest.resetAllMocks();
-  jest.mocked(getAgentTelemetryContext).mockReturnValue(null);
  jest.mocked(maybeOfferFreeTierLimitCheckoutAsync).mockResolvedValue(false);
 });

-/** 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",
@@ -357,115 +331,6 @@ 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 free tier limit errors in the checkout experiment', () => {
        it('offers the checkout with the limit message and marks the message as printed', async () => {
          jest.mocked(maybeOfferFreeTierLimitCheckoutAsync).mockResolvedValue(true);
@@ -482,7 +347,6 @@ describe(Build.name, () => {
                error,
                platform,
                accountName,
-                undefined,
                CHECKOUT_EXPERIMENT
              );
            }
@@ -515,7 +379,6 @@ describe(Build.name, () => {
                error,
                platform,
                accountName,
-                undefined,
                CHECKOUT_EXPERIMENT
              );
            });
@@ -544,7 +407,6 @@ describe(Build.name, () => {
                error,
                platform,
                accountName,
-                undefined,
                CHECKOUT_EXPERIMENT
              );
            }
@@ -559,35 +421,6 @@ describe(Build.name, () => {
          );
        });

-        it('passes the agent guidance along when both experiments are present', async () => {
-          jest
-            .mocked(getAgentTelemetryContext)
-            .mockReturnValue({ id: 'claude-code', sessionId: 'session-1' });
-          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] });
-
-          await getErrorAsync(async () => {
-            await handleBuildRequestErrorAsync(
-              error,
-              platform,
-              accountName,
-              createExperiment('treatment'),
-              CHECKOUT_EXPERIMENT
-            );
-          });
-
-          expect(maybeOfferFreeTierLimitCheckoutAsync).toHaveBeenCalledWith(
-            [
-              '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'),
-            CHECKOUT_EXPERIMENT
-          );
-        });
-
        it('does not offer the checkout for other server-side errors', async () => {
          const platform = Platform.ANDROID;
          const graphQLError = getGraphQLError('Error 1', 'EAS_BUILD_FREE_TIER_DISABLED');
@@ -599,7 +432,6 @@ describe(Build.name, () => {
                error,
                platform,
                undefined,
-                undefined,
                CHECKOUT_EXPERIMENT
              );
            }
@@ -34,11 +34,6 @@ import {
  getFreeTierLimitCheckoutExperiment,
  maybeOfferFreeTierLimitCheckoutAsync,
 } from './freeTierLimitCheckout';
-import {
-  FreeTierLimitAgentGuidanceExperiment,
-  getFreeTierLimitAgentGuidanceExperiment,
-  maybeAppendFreeTierLimitAgentGuidanceAsync,
-} from './freeTierLimitGuidance';
 import { transformMetadata } from './graphql';
 import { LocalBuildMode, runLocalBuildAsync } from './local';
 import {
@@ -236,7 +231,6 @@ export async function prepareBuildRequestForPlatformAsync<
          error,
          job.platform,
          ctx.accountName,
-          getFreeTierLimitAgentGuidanceExperiment(ctx),
          getFreeTierLimitCheckoutExperiment(ctx)
        );
      }
@@ -263,7 +257,6 @@ export async function handleBuildRequestErrorAsync(
  error: any,
  platform: Platform,
  accountName?: string,
-  freeTierLimitAgentGuidanceExperiment?: FreeTierLimitAgentGuidanceExperiment,
  freeTierLimitCheckoutExperiment?: FreeTierLimitCheckoutExperiment
 ): Promise<never> {
  logBuildRequestErrorDebugInfo(error);
@@ -283,11 +276,7 @@ export async function handleBuildRequestErrorAsync(
    if (!isFreeTierLimitError) {
      throw new ErrorClass(message);
    }
-    const limitMessage = await maybeAppendFreeTierLimitAgentGuidanceAsync(
-      `${message}\nRun ${formatStarterSubscribeCommand(accountName)} to upgrade to the Starter plan.`,
-      platform,
-      freeTierLimitAgentGuidanceExperiment
-    );
+    const limitMessage = `${message}\nRun ${formatStarterSubscribeCommand(accountName)} to upgrade to the Starter plan.`;
    const messageAlreadyPrinted = await maybeOfferFreeTierLimitCheckoutAsync(
      limitMessage,
      freeTierLimitCheckoutExperiment
@@ -1,60 +0,0 @@
-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)}`;
-}
@@ -0,0 +1,344 @@
+import { ExpoConfig } from '@expo/config';
+
+import { getAgentTelemetryContext } from '../analytics/agent';
+import { Analytics, AnalyticsEventProperties, BuildEvent } from '../analytics/AnalyticsManager';
+import {
+  ExpoGraphqlClient,
+  createGraphqlClient,
+} from '../commandUtils/context/contextUtils/createGraphqlClient';
+import { LazyExperimentationClient } from '../experimentation/LazyExperimentationClient';
+import {
+  AppPlatform,
+  BuildFragment,
+  BuildStatus,
+  EasServiceMetric,
+  UsageMetricType,
+} from '../graphql/generated';
+import { UserPreferenceMutation } from '../graphql/mutations/UserPreferenceMutation';
+import { AccountQuery } from '../graphql/queries/AccountQuery';
+import { UserPreferenceQuery } from '../graphql/queries/UserPreferenceQuery';
+import Log from '../log';
+import { appPlatformDisplayNames } from '../platform';
+import { isExpoUpdatesInstalled, isUsingEASUpdate } from '../project/projectUtils';
+import { LoggedInAuthenticationInfo } from '../user/SessionManager';
+import { Actor } from '../user/User';
+
+export const FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP_EXPERIMENT_NAMESPACE =
+  'cli-build-free-tier-near-limit-agent-updates-tip';
+
+/** The tip shows when this many builds or fewer are left on the platform. */
+export const FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP_BUILDS_LEFT = 5;
+
+export const EAS_UPDATE_GETTING_STARTED_URL = 'https://docs.expo.dev/eas-update/getting-started/';
+
+/** Server-side user preference key prefix. The full key is `<prefix>/<accountId>/<platform>`. */
+const USER_PREFERENCE_KEY_PREFIX = 'free-tier-near-limit-agent-updates-tip-shown';
+
+/** The tip's requests run after the build, so a stalled request must not delay the exit. */
+const REQUEST_TIMEOUT_MS = 3000;
+
+export type FreeTierNearLimitAgentUpdatesTipVariant = 'control' | 'treatment';
+
+/** The project state of one platform's build. Each build profile evaluates its own config. */
+export type FreeTierNearLimitAgentUpdatesTipPlatformProject = {
+  developmentClient: boolean;
+  projectDir: string;
+  projectId: string;
+  exp: ExpoConfig;
+  manifestHostOverride: string | null;
+};
+
+export type FreeTierNearLimitAgentUpdatesTipExperiment = {
+  experimentation: LazyExperimentationClient;
+  graphqlClient: ExpoGraphqlClient;
+  analytics: Analytics;
+  analyticsEventProperties: AnalyticsEventProperties;
+  accountId: string;
+  /** Only regular and SSO users can store user preferences. */
+  isUser: boolean;
+  runFromCI: boolean;
+  json: boolean;
+  projectByPlatform: Partial<Record<AppPlatform, FreeTierNearLimitAgentUpdatesTipPlatformProject>>;
+};
+
+export type FreeTierNearLimitAgentUpdatesTipBuildContext = {
+  experimentation?: LazyExperimentationClient;
+  authenticationInfo?: LoggedInAuthenticationInfo;
+  analytics: Analytics;
+  analyticsEventProperties: AnalyticsEventProperties;
+  accountId: string;
+  user: Actor;
+  developmentClient: boolean;
+  projectDir: string;
+  projectId: string;
+  exp: ExpoConfig;
+  easJsonCliConfig: { updateManifestHostOverride?: string } | undefined;
+  runFromCI: boolean;
+};
+
+export type FreeTierPlatformBuildUsage = {
+  used: number;
+  limit: number;
+};
+
+export type FreeTierBuildUsage = {
+  billingPeriodId: string;
+  byPlatform: Record<AppPlatform, FreeTierPlatformBuildUsage>;
+};
+
+/** All build contexts belong to one command run, so the account and the actor are shared. */
+export function getFreeTierNearLimitAgentUpdatesTipExperiment(
+  buildCtxByPlatform: Partial<Record<AppPlatform, FreeTierNearLimitAgentUpdatesTipBuildContext>>,
+  { json }: { json: boolean }
+): FreeTierNearLimitAgentUpdatesTipExperiment | undefined {
+  const ctx = Object.values(buildCtxByPlatform)[0];
+  if (!ctx?.experimentation || !ctx.authenticationInfo) {
+    return undefined;
+  }
+  const projectByPlatform: FreeTierNearLimitAgentUpdatesTipExperiment['projectByPlatform'] = {};
+  for (const [platform, platformCtx] of Object.entries(buildCtxByPlatform)) {
+    projectByPlatform[platform as AppPlatform] = {
+      developmentClient: platformCtx.developmentClient,
+      projectDir: platformCtx.projectDir,
+      projectId: platformCtx.projectId,
+      exp: platformCtx.exp,
+      manifestHostOverride: platformCtx.easJsonCliConfig?.updateManifestHostOverride ?? null,
+    };
+  }
+  return {
+    experimentation: ctx.experimentation,
+    graphqlClient: createGraphqlClient(ctx.authenticationInfo, {
+      requestTimeoutMs: REQUEST_TIMEOUT_MS,
+    }),
+    analytics: ctx.analytics,
+    analyticsEventProperties: ctx.analyticsEventProperties,
+    accountId: ctx.accountId,
+    isUser: ctx.user.__typename === 'User' || ctx.user.__typename === 'SSOUser',
+    runFromCI: ctx.runFromCI,
+    json,
+    projectByPlatform,
+  };
+}
+
+export function isProjectConfiguredForEASUpdate({
+  projectDir,
+  exp,
+  projectId,
+  manifestHostOverride,
+}: Pick<
+  FreeTierNearLimitAgentUpdatesTipPlatformProject,
+  'projectDir' | 'exp' | 'projectId' | 'manifestHostOverride'
+>): boolean {
+  return (
+    isExpoUpdatesInstalled(projectDir) && isUsingEASUpdate(exp, projectId, manifestHostOverride)
+  );
+}
+
+/**
+ * Only runs driven by a coding agent logged in as a user, outside CI and without --json are
+ * eligible. Everything else gets no tip and no usage request.
+ */
+export function isEligibleForFreeTierNearLimitAgentUpdatesTip(
+  experiment: FreeTierNearLimitAgentUpdatesTipExperiment
+): boolean {
+  return !(
+    experiment.runFromCI ||
+    experiment.json ||
+    !experiment.isUser ||
+    !getAgentTelemetryContext()
+  );
+}
+
+/**
+ * A platform is eligible when its project is not set up for Expo Update. Development builds load
+ * JavaScript from the dev server, so the tip does not apply to them.
+ */
+export function isPlatformEligibleForFreeTierNearLimitAgentUpdatesTip(
+  project: FreeTierNearLimitAgentUpdatesTipPlatformProject
+): boolean {
+  return !project.developmentClient && !isProjectConfiguredForEASUpdate(project);
+}
+
+/** True when the platform still has builds left, but no more than the tip's threshold. */
+export function isWithinFreeTierNearLimitBand({ used, limit }: FreeTierPlatformBuildUsage): boolean {
+  return limit > 0 && used < limit && limit - used <= FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP_BUILDS_LEFT;
+}
+
+/** Returns the Free plan build usage per platform, or null when the account is not on the Free plan. */
+export async function getFreeTierBuildUsageAsync({
+  graphqlClient,
+  accountId,
+}: Pick<FreeTierNearLimitAgentUpdatesTipExperiment, 'graphqlClient' | 'accountId'>): Promise<FreeTierBuildUsage | null> {
+  const account = await AccountQuery.getFreeTierBuildUsageAsync(graphqlClient, accountId, new Date());
+  if ((account.subscription?.name ?? 'Free') !== 'Free') {
+    return null;
+  }
+  const buildMetric = account.usageMetrics.EAS_BUILD.planMetrics.find(
+    metric =>
+      metric.serviceMetric === EasServiceMetric.Builds &&
+      metric.metricType === UsageMetricType.Build
+  );
+  const breakdown = buildMetric?.platformBreakdown;
+  if (!breakdown) {
+    return null;
+  }
+  return {
+    billingPeriodId: account.billingPeriod.id,
+    byPlatform: {
+      [AppPlatform.Android]: { used: breakdown.android.value, limit: breakdown.android.limit },
+      [AppPlatform.Ios]: { used: breakdown.ios.value, limit: breakdown.ios.limit },
+    },
+  };
+}
+
+/**
+ * The first call logs the exposure, so call it only when the tip would show. Accounts outside the
+ * rollout get the control default and no exposure.
+ */
+export async function resolveFreeTierNearLimitAgentUpdatesTipVariantAsync({
+  experimentation,
+  accountId,
+}: Pick<FreeTierNearLimitAgentUpdatesTipExperiment, 'experimentation' | 'accountId'>): Promise<FreeTierNearLimitAgentUpdatesTipVariant> {
+  const client = await experimentation.getClientAsync();
+  return client
+    .getAccountNamespace(FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP_EXPERIMENT_NAMESPACE, { accountId })
+    .getParam<FreeTierNearLimitAgentUpdatesTipVariant>('variant', 'control');
+}
+
+export function formatFreeTierNearLimitAgentUpdatesTip({
+  platform,
+  used,
+  limit,
+}: FreeTierPlatformBuildUsage & { platform: AppPlatform }): string {
+  const platformName = appPlatformDisplayNames[platform];
+  return [
+    `Tip: this account has used ${used} of ${limit} ${platformName} builds on the Free plan this period. This project isn't set up for Expo Update, so every change needs a new build.`,
+    'With Expo Update, JavaScript, styling and image changes reach installed builds without a new build. Setup takes effect from the next build, so it saves the most builds if done now.',
+    'Next: eas update:configure --non-interactive, then build once more.',
+    'Tell the user: this adds expo-updates and changes app.json and eas.json.',
+    `Docs: ${EAS_UPDATE_GETTING_STARTED_URL}`,
+  ].join('\n');
+}
+
+export function getFreeTierNearLimitAgentUpdatesTipPreferenceKey(
+  accountId: string,
+  platform: AppPlatform
+): string {
+  return `${USER_PREFERENCE_KEY_PREFIX}/${accountId}/${platform.toLowerCase()}`;
+}
+
+type ShownTipPreference = { billingPeriodId: string };
+
+function isShownTipPreference(value: unknown): value is ShownTipPreference {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as ShownTipPreference).billingPeriodId === 'string'
+  );
+}
+
+/**
+ * The tip shows at most once per user, account, platform and billing period. The marker is a
+ * user preference on the server, so it follows the user across machines and fresh agent
+ * sandboxes.
+ */
+export async function wasFreeTierNearLimitAgentUpdatesTipShownAsync(
+  graphqlClient: ExpoGraphqlClient,
+  accountId: string,
+  platform: AppPlatform,
+  billingPeriodId: string
+): Promise<boolean> {
+  const value = await UserPreferenceQuery.getValueAsync(
+    graphqlClient,
+    getFreeTierNearLimitAgentUpdatesTipPreferenceKey(accountId, platform)
+  );
+  return isShownTipPreference(value) && value.billingPeriodId === billingPeriodId;
+}
+
+export async function markFreeTierNearLimitAgentUpdatesTipShownAsync(
+  graphqlClient: ExpoGraphqlClient,
+  accountId: string,
+  platform: AppPlatform,
+  billingPeriodId: string
+): Promise<void> {
+  const value: ShownTipPreference = { billingPeriodId };
+  await UserPreferenceMutation.setAsync(
+    graphqlClient,
+    getFreeTierNearLimitAgentUpdatesTipPreferenceKey(accountId, platform),
+    value
+  );
+}
+
+/**
+ * After finished builds, suggests Expo Update to coding agents whose Free plan account is close to
+ * the platform build limit. The exposure logs only when every eligibility check passed, so both
+ * arms see the same population. The treatment arm prints the tip, logs the tip event, then
+ * writes the marker, so a failed write means at most a repeated tip. Fails open on any error.
+ */
+export async function maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+  builds: (BuildFragment | null)[],
+  experiment: FreeTierNearLimitAgentUpdatesTipExperiment | undefined
+): Promise<void> {
+  if (!experiment || !isEligibleForFreeTierNearLimitAgentUpdatesTip(experiment)) {
+    return;
+  }
+  const eligiblePlatforms = new Set(
+    builds
+      .filter((build): build is BuildFragment => build?.status === BuildStatus.Finished)
+      .map(build => build.platform)
+      .filter(platform => {
+        const project = experiment.projectByPlatform[platform];
+        return project && isPlatformEligibleForFreeTierNearLimitAgentUpdatesTip(project);
+      })
+  );
+  if (eligiblePlatforms.size === 0) {
+    return;
+  }
+
+  try {
+    const usage = await getFreeTierBuildUsageAsync(experiment);
+    if (!usage) {
+      return;
+    }
+    for (const platform of eligiblePlatforms) {
+      const platformUsage = usage.byPlatform[platform];
+      if (
+        !isWithinFreeTierNearLimitBand(platformUsage) ||
+        (await wasFreeTierNearLimitAgentUpdatesTipShownAsync(
+          experiment.graphqlClient,
+          experiment.accountId,
+          platform,
+          usage.billingPeriodId
+        ))
+      ) {
+        continue;
+      }
+
+      const variant = await resolveFreeTierNearLimitAgentUpdatesTipVariantAsync(experiment);
+      if (variant !== 'treatment') {
+        continue;
+      }
+      Log.newLine();
+      Log.log(formatFreeTierNearLimitAgentUpdatesTip({ platform, ...platformUsage }));
+      experiment.analytics.logEvent(BuildEvent.FREE_TIER_NEAR_LIMIT_AGENT_UPDATES_TIP, {
+        ...experiment.analyticsEventProperties,
+        platform,
+        builds_used: platformUsage.used,
+        builds_limit: platformUsage.limit,
+      });
+      try {
+        await markFreeTierNearLimitAgentUpdatesTipShownAsync(
+          experiment.graphqlClient,
+          experiment.accountId,
+          platform,
+          usage.billingPeriodId
+        );
+      } catch (error: any) {
+        // The tip was shown. A missing marker means at most a repeated tip, so keep going.
+        Log.debug('Failed to mark the Expo Update tip as shown:', error?.message ?? error);
+      }
+    }
+  } catch (error: any) {
+    Log.debug('Failed to run the Expo Update tip check:', error?.message ?? error);
+  }
+}
@@ -24,6 +24,10 @@ import { prepareIosBuildAsync } from './ios/build';
 import { LocalBuildMode, LocalBuildOptions } from './local';
 import { ensureLockfileExistsAsync } from './validateLockfile';
 import { ensureExpoDevClientInstalledForDevClientBuildsAsync } from './utils/devClient';
+import {
+  getFreeTierNearLimitAgentUpdatesTipExperiment,
+  maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync,
+} from './freeTierNearLimitAgentUpdatesTip';
 import { printBuildResults, printLogsUrls } from './utils/printBuildInfo';
 import { ensureRepoIsCleanAsync } from './utils/repository';
 import { Analytics } from '../analytics/AnalyticsManager';
@@ -139,6 +143,7 @@ export async function runBuildAndSubmitAsync({
 }): Promise<{
  buildIds: string[];
  buildProfiles?: ProfileData<'build'>[];
+  builds?: MaybeBuildFragment[];
 }> {
  await vcsClient.ensureRepoExistsAsync();
  await ensureRepoIsCleanAsync(vcsClient, flags.nonInteractive);
@@ -339,6 +344,10 @@ export async function runBuildAndSubmitAsync({
  if (!flags.json) {
    printBuildResults(builds);
  }
+  await maybeSuggestEASUpdateToAgentNearFreeTierLimitAsync(
+    builds,
+    getFreeTierNearLimitAgentUpdatesTipExperiment(buildCtxByPlatform, { json: flags.json })
+  );

  const haveAllBuildsFailedOrCanceled = builds.every(
    build =>
@@ -372,6 +381,7 @@ export async function runBuildAndSubmitAsync({
  return {
    buildIds: startedBuilds.map(({ build }) => build.id),
    buildProfiles,
+    builds,
  };
 }

@@ -0,0 +1,52 @@
+import { boolish } from 'getenv';
+
+import { Analytics, BuildEvent } from '../analytics/AnalyticsManager';
+import { createGraphqlClient } from '../commandUtils/context/contextUtils/createGraphqlClient';
+import { UserPreferenceMutation } from '../graphql/mutations/UserPreferenceMutation';
+import { UserPreferenceQuery } from '../graphql/queries/UserPreferenceQuery';
+import Log, { link } from '../log';
+import { LoggedInAuthenticationInfo } from '../user/SessionManager';
+import { Actor } from '../user/User';
+
+const SIMULATORS_LAUNCH_AT = new Date('2026-11-05T18:00:00Z');
+const SIMULATORS_LAUNCH_HINT_PREFERENCE_KEY = 'simulators-launch-cli-hint-seen';
+const REQUEST_TIMEOUT_MS = 3000;
+const SIMULATORS_QUICKSTART_URL =
+  'https://docs.expo.dev/preview/simulators/get-started/?utm_source=eas-cli&utm_medium=cli&utm_campaign=simulators-launch';
+
+export async function maybeShowSimulatorsLaunchHintAsync(
+  authenticationInfo: LoggedInAuthenticationInfo,
+  analytics: Analytics,
+  { actor, nonInteractive }: { actor: Actor; nonInteractive: boolean }
+): Promise<void> {
+  if (
+    nonInteractive ||
+    boolish('CI', false) ||
+    Date.now() < SIMULATORS_LAUNCH_AT.getTime() ||
+    (actor.__typename !== 'User' && actor.__typename !== 'SSOUser')
+  ) {
+    return;
+  }
+  try {
+    const graphqlClient = createGraphqlClient(authenticationInfo, {
+      requestTimeoutMs: REQUEST_TIMEOUT_MS,
+    });
+    const value = await UserPreferenceQuery.getValueAsync(
+      graphqlClient,
+      SIMULATORS_LAUNCH_HINT_PREFERENCE_KEY
+    );
+    if (value && typeof value === 'object' && 'isDismissed' in value && value.isDismissed) {
+      return;
+    }
+    Log.newLine();
+    Log.log(
+      `✨ New: run your build in Expo Simulators, cloud Android and iOS simulators for you and your agents. ${link(SIMULATORS_QUICKSTART_URL)}`
+    );
+    analytics.logEvent(BuildEvent.SIMULATORS_LAUNCH_HINT_SHOWN, {});
+    await UserPreferenceMutation.setAsync(graphqlClient, SIMULATORS_LAUNCH_HINT_PREFERENCE_KEY, {
+      isDismissed: true,
+    });
+  } catch (error) {
+    Log.debug('Failed to show the Expo Simulators hint', error);
+  }
+}
@@ -9,12 +9,13 @@ import path from 'path';

 import { LocalBuildMode } from '../../build/local';
 import { BuildFlags, runBuildAndSubmitAsync } from '../../build/runBuildAndSubmit';
+import { maybeShowSimulatorsLaunchHintAsync } from '../../build/simulatorsLaunchHint';
 import EasCommand from '../../commandUtils/EasCommand';
 import {
  EasNonInteractiveAndJsonFlags,
  resolveNonInteractiveAndJsonFlags,
 } from '../../commandUtils/flags';
-import { StatuspageServiceName } from '../../graphql/generated';
+import { BuildStatus, StatuspageServiceName } from '../../graphql/generated';
 import Log, { link } from '../../log';
 import { RequestedPlatform, selectRequestedPlatformAsync } from '../../platform';
 import { selectAsync } from '../../prompts';
@@ -176,7 +177,7 @@ export default class Build extends EasCommand {

    const flagsWithPlatform = await this.ensurePlatformSelectedAsync(flags);

-    const { buildProfiles } = await runBuildAndSubmitAsync({
+    const { buildProfiles, builds } = await runBuildAndSubmitAsync({
      graphqlClient,
      analytics,
      vcsClient,
@@ -192,6 +193,13 @@ export default class Build extends EasCommand {
      buildProfiles,
      nonInteractive: flags.nonInteractive,
    });
+
+    if (builds?.some(build => build?.status === BuildStatus.Finished)) {
+      await maybeShowSimulatorsLaunchHintAsync(authenticationInfo, analytics, {
+        actor,
+        nonInteractive: flags.nonInteractive,
+      });
+    }
  }

  private sanitizeFlags(
@@ -112,6 +112,7 @@ describe(ObserveSession, () => {
      metadata: null,
      hasMoreMetricEvents: false,
      hasMoreLogEvents: false,
+      hasMoreSpans: false,
    });
    mockFetchSessionMetricCandidatesAsync.mockResolvedValue([]);
    mockFetchSessionLogCandidatesAsync.mockResolvedValue([]);
@@ -0,0 +1,113 @@
+import { CombinedError } from '@urql/core';
+import { GraphQLError } from 'graphql';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { getMockOclifConfig } from '../../../__tests__/commands/utils';
+import { ObserveQuery } from '../../../graphql/queries/ObserveQuery';
+import { buildObserveTraceJson, buildObserveTraceTable } from '../../../observe/formatSpans';
+import { EAS_OBSERVE_PLAN_UPGRADE_REQUIRED_ERROR_CODE } from '../../../observe/planGating';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+import ObserveTrace from '../trace';
+
+jest.mock('../../../observe/formatSpans', () => ({
+  buildObserveTraceTable: jest.fn().mockReturnValue('trace-table'),
+  buildObserveTraceJson: jest.fn().mockReturnValue({ id: 'trace-json' }),
+}));
+jest.mock('../../../graphql/queries/ObserveQuery', () => ({
+  ObserveQuery: {
+    traceByIdAsync: jest.fn(),
+  },
+}));
+jest.mock('../../../log');
+jest.mock('../../../utils/json');
+
+const mockTraceByIdAsync = jest.mocked(ObserveQuery.traceByIdAsync);
+const mockBuildObserveTraceTable = jest.mocked(buildObserveTraceTable);
+const mockBuildObserveTraceJson = jest.mocked(buildObserveTraceJson);
+const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
+const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);
+
+const TRACE_ID = '0123456789abcdef0123456789abcdef';
+const trace = { id: TRACE_ID, isTruncated: false, spans: [] } as any;
+
+describe(ObserveTrace, () => {
+  const graphqlClient = {} as any as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+  const projectId = 'test-project-id';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockTraceByIdAsync.mockResolvedValue(trace);
+  });
+
+  function createCommand(argv: string[]): ObserveTrace {
+    const command = new ObserveTrace(argv, mockConfig);
+    // @ts-expect-error
+    jest.spyOn(command, 'getContextAsync').mockReturnValue({
+      projectId,
+      loggedIn: { graphqlClient },
+    });
+    return command;
+  }
+
+  it('requires a trace ID argument', async () => {
+    await expect(createCommand([]).runAsync()).rejects.toThrow();
+    expect(mockTraceByIdAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects a malformed trace ID before querying', async () => {
+    await expect(createCommand(['not-a-trace-id']).runAsync()).rejects.toThrow(
+      /not a valid trace ID/
+    );
+    expect(mockTraceByIdAsync).not.toHaveBeenCalled();
+  });
+
+  it('accepts an uppercase trace ID', async () => {
+    await createCommand([TRACE_ID.toUpperCase()]).runAsync();
+    expect(mockTraceByIdAsync).toHaveBeenCalledWith(graphqlClient, {
+      appId: projectId,
+      id: TRACE_ID.toUpperCase(),
+    });
+  });
+
+  it('renders the trace table by default', async () => {
+    await createCommand([TRACE_ID]).runAsync();
+
+    expect(mockTraceByIdAsync).toHaveBeenCalledWith(graphqlClient, {
+      appId: projectId,
+      id: TRACE_ID,
+    });
+    expect(mockBuildObserveTraceTable).toHaveBeenCalledWith(trace);
+    expect(mockBuildObserveTraceJson).not.toHaveBeenCalled();
+  });
+
+  it('emits JSON with --json', async () => {
+    await createCommand([TRACE_ID, '--json', '--non-interactive']).runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockBuildObserveTraceJson).toHaveBeenCalledWith(trace);
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalledWith({ id: 'trace-json' });
+    expect(mockBuildObserveTraceTable).not.toHaveBeenCalled();
+  });
+
+  it('fails with a not-found message when the trace is unknown', async () => {
+    mockTraceByIdAsync.mockResolvedValue(null);
+    await expect(createCommand([TRACE_ID]).runAsync()).rejects.toThrow(/No trace found with ID/);
+  });
+
+  it('surfaces the plan-gate message', async () => {
+    const serverMessage =
+      'Access to this feature is not included in your current plan. ' +
+      'Upgrade your plan: https://expo.dev/accounts/acme/settings/billing';
+    mockTraceByIdAsync.mockRejectedValueOnce(
+      new CombinedError({
+        graphQLErrors: [
+          new GraphQLError(serverMessage, null, null, null, null, null, {
+            errorCode: EAS_OBSERVE_PLAN_UPGRADE_REQUIRED_ERROR_CODE,
+          }),
+        ],
+      })
+    );
+    await expect(createCommand([TRACE_ID]).runAsync()).rejects.toThrow(serverMessage);
+  });
+});
@@ -0,0 +1,260 @@
+import { CombinedError } from '@urql/core';
+import { GraphQLError } from 'graphql';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { getMockOclifConfig } from '../../../__tests__/commands/utils';
+import {
+  AppObservePlatform,
+  AppObserveSpanKind,
+  AppObserveSpanStatusCode,
+} from '../../../graphql/generated';
+import { ObserveQuery } from '../../../graphql/queries/ObserveQuery';
+import { fetchObserveSpansAsync } from '../../../observe/fetchSpans';
+import {
+  buildObserveSpanNamesJson,
+  buildObserveSpanNamesTable,
+  buildObserveSpansJson,
+  buildObserveSpansTable,
+} from '../../../observe/formatSpans';
+import { EAS_OBSERVE_PLAN_UPGRADE_REQUIRED_ERROR_CODE } from '../../../observe/planGating';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+import ObserveTraces from '../traces';
+
+jest.mock('../../../observe/fetchSpans');
+jest.mock('../../../observe/formatSpans', () => ({
+  buildObserveSpansTable: jest.fn().mockReturnValue('spans-table'),
+  buildObserveSpansJson: jest.fn().mockReturnValue({ spans: [] }),
+  buildObserveSpanNamesTable: jest.fn().mockReturnValue('names-table'),
+  buildObserveSpanNamesJson: jest.fn().mockReturnValue({ names: [], isTruncated: false }),
+}));
+jest.mock('../../../graphql/queries/ObserveQuery', () => ({
+  ObserveQuery: {
+    spanNamesAsync: jest.fn(),
+  },
+}));
+jest.mock('../../../log');
+jest.mock('../../../utils/json');
+
+const mockFetchObserveSpansAsync = jest.mocked(fetchObserveSpansAsync);
+const mockSpanNamesAsync = jest.mocked(ObserveQuery.spanNamesAsync);
+const mockBuildObserveSpansTable = jest.mocked(buildObserveSpansTable);
+const mockBuildObserveSpansJson = jest.mocked(buildObserveSpansJson);
+const mockBuildObserveSpanNamesTable = jest.mocked(buildObserveSpanNamesTable);
+const mockBuildObserveSpanNamesJson = jest.mocked(buildObserveSpanNamesJson);
+const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
+const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);
+
+describe(ObserveTraces, () => {
+  const graphqlClient = {} as any as ExpoGraphqlClient;
+  const mockConfig = getMockOclifConfig();
+  const projectId = 'test-project-id';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockFetchObserveSpansAsync.mockResolvedValue({
+      spans: [],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
+    });
+    mockSpanNamesAsync.mockResolvedValue({ names: [], isTruncated: false });
+  });
+
+  function createCommand(argv: string[]): ObserveTraces {
+    const command = new ObserveTraces(argv, mockConfig);
+    // @ts-expect-error
+    jest.spyOn(command, 'getContextAsync').mockReturnValue({
+      projectId,
+      loggedIn: { graphqlClient },
+    });
+    return command;
+  }
+
+  function planGateError(): CombinedError {
+    const serverMessage =
+      'Access to this feature is not included in your current plan. ' +
+      'Upgrade your plan: https://expo.dev/accounts/acme/settings/billing';
+    return new CombinedError({
+      graphQLErrors: [
+        new GraphQLError(serverMessage, null, null, null, null, null, {
+          errorCode: EAS_OBSERVE_PLAN_UPGRADE_REQUIRED_ERROR_CODE,
+        }),
+      ],
+    });
+  }
+
+  it('shows the span names summary when no span filter is given', async () => {
+    const command = createCommand(['--days', '7', '--platform', 'ios', '--environment', 'prod']);
+    await command.runAsync();
+
+    expect(mockSpanNamesAsync).toHaveBeenCalledTimes(1);
+    const variables = mockSpanNamesAsync.mock.calls[0][1];
+    expect(variables.appId).toBe(projectId);
+    expect(variables.input.platforms).toEqual([AppObservePlatform.Ios]);
+    expect(variables.input.environment).toBe('prod');
+    expect(variables.input.startTime).toBeDefined();
+    expect(variables.input.endTime).toBeDefined();
+    expect(mockFetchObserveSpansAsync).not.toHaveBeenCalled();
+    expect(mockBuildObserveSpanNamesTable).toHaveBeenCalled();
+    expect(mockBuildObserveSpansTable).not.toHaveBeenCalled();
+  });
+
+  it('passes release filters to the summary', async () => {
+    const command = createCommand([
+      '--app-version',
+      '1.2.0',
+      '--build-number',
+      '42',
+      '--update-id',
+      'update-1',
+    ]);
+    await command.runAsync();
+
+    const { input } = mockSpanNamesAsync.mock.calls[0][1];
+    expect(input.appVersion).toBe('1.2.0');
+    expect(input.appBuildNumber).toBe('42');
+    expect(input.appUpdateId).toBe('update-1');
+  });
+
+  it('emits the summary as JSON with --json', async () => {
+    const command = createCommand(['--json', '--non-interactive']);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockBuildObserveSpanNamesJson).toHaveBeenCalled();
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
+    expect(mockBuildObserveSpanNamesTable).not.toHaveBeenCalled();
+  });
+
+  it('lists spans with --all-spans', async () => {
+    const command = createCommand(['--all-spans']);
+    await command.runAsync();
+
+    expect(mockSpanNamesAsync).not.toHaveBeenCalled();
+    expect(mockFetchObserveSpansAsync).toHaveBeenCalledTimes(1);
+    expect(mockBuildObserveSpansTable).toHaveBeenCalled();
+  });
+
+  it('lists spans when paging with --after', async () => {
+    const command = createCommand(['--after', 'cursor-1']);
+    await command.runAsync();
+
+    expect(mockSpanNamesAsync).not.toHaveBeenCalled();
+    expect(mockFetchObserveSpansAsync.mock.calls[0][2].after).toBe('cursor-1');
+  });
+
+  it.each([
+    ['--name', 'GET'],
+    ['--kind', 'client'],
+    ['--status', 'error'],
+    ['--host', 'api.example.com'],
+    ['--http-status', '500'],
+    ['--min-duration', '100'],
+    ['--session-id', 'session-1'],
+  ])('lists spans when %s is given', async (flag, value) => {
+    const command = createCommand([flag, value]);
+    await command.runAsync();
+
+    expect(mockSpanNamesAsync).not.toHaveBeenCalled();
+    expect(mockFetchObserveSpansAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('lists spans with --root-only', async () => {
+    const command = createCommand(['--root-only']);
+    await command.runAsync();
+
+    expect(mockSpanNamesAsync).not.toHaveBeenCalled();
+    expect(mockFetchObserveSpansAsync.mock.calls[0][2].rootOnly).toBe(true);
+  });
+
+  it('maps every span filter flag to the fetch options', async () => {
+    const command = createCommand([
+      '--name',
+      'GET',
+      '--name',
+      'POST',
+      '--kind',
+      'client',
+      '--status',
+      'error',
+      '--status',
+      'unset',
+      '--host',
+      'api.example.com',
+      '--http-status',
+      '500',
+      '--http-status',
+      '502',
+      '--min-duration',
+      '250',
+      '--root-only',
+      '--session-id',
+      'session-1',
+      '--platform',
+      'android',
+      '--app-version',
+      '1.2.0',
+      '--build-number',
+      '42',
+      '--update-id',
+      'update-1',
+      '--environment',
+      'prod',
+      '--limit',
+      '50',
+    ]);
+    await command.runAsync();
+
+    const options = mockFetchObserveSpansAsync.mock.calls[0][2];
+    expect(options).toEqual(
+      expect.objectContaining({
+        limit: 50,
+        names: ['GET', 'POST'],
+        kinds: [AppObserveSpanKind.Client],
+        statusCodes: [AppObserveSpanStatusCode.Error, AppObserveSpanStatusCode.Unset],
+        hosts: ['api.example.com'],
+        httpStatusCodes: [500, 502],
+        minDurationMs: 250,
+        rootOnly: true,
+        sessionId: 'session-1',
+        platforms: [AppObservePlatform.Android],
+        appVersion: '1.2.0',
+        buildNumber: '42',
+        updateId: 'update-1',
+        environment: 'prod',
+      })
+    );
+  });
+
+  it('defaults the span list limit to 20 and caps it at 100', async () => {
+    await createCommand(['--all-spans']).runAsync();
+    expect(mockFetchObserveSpansAsync.mock.calls[0][2].limit).toBe(20);
+
+    await expect(createCommand(['--all-spans', '--limit', '101']).runAsync()).rejects.toThrow();
+  });
+
+  it('rejects an unknown --kind or --status value', async () => {
+    await expect(createCommand(['--kind', 'bogus']).runAsync()).rejects.toThrow();
+    await expect(createCommand(['--status', 'bogus']).runAsync()).rejects.toThrow();
+  });
+
+  it('emits the span list as JSON with --json', async () => {
+    const command = createCommand(['--all-spans', '--json', '--non-interactive']);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockBuildObserveSpansJson).toHaveBeenCalled();
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
+    expect(mockBuildObserveSpansTable).not.toHaveBeenCalled();
+  });
+
+  it('surfaces the plan-gate message when a session filter is not available on the plan', async () => {
+    mockFetchObserveSpansAsync.mockRejectedValueOnce(planGateError());
+    const command = createCommand(['--session-id', 'session-1']);
+    await expect(command.runAsync()).rejects.toThrow(/not included in your current plan/);
+  });
+
+  it('surfaces the plan-gate message from the summary query', async () => {
+    mockSpanNamesAsync.mockRejectedValueOnce(planGateError());
+    const command = createCommand([]);
+    await expect(command.runAsync()).rejects.toThrow(/not included in your current plan/);
+  });
+});
@@ -45,7 +45,7 @@ const PICKER_CANDIDATE_LIMIT = 25;

 export default class ObserveSession extends EasCommand {
  static override description =
-    'display the timeline of metric and log events for a specific session';
+    'display the timeline of metric, log, and request trace span events for a specific session';

  static override args = {
    sessionId: Args.string({
@@ -129,7 +129,7 @@ export default class ObserveSession extends EasCommand {
      });
    }

-    const { entries, metadata, hasMoreMetricEvents, hasMoreLogEvents } =
+    const { entries, metadata, hasMoreMetricEvents, hasMoreLogEvents, hasMoreSpans } =
      await withObservePlanGateHandlingAsync(() =>
        fetchObserveSessionEventsAsync(graphqlClient, projectId, {
          sessionId,
@@ -144,7 +144,8 @@ export default class ObserveSession extends EasCommand {
          sessionId,
          metadata,
          hasMoreMetricEvents,
-          hasMoreLogEvents
+          hasMoreLogEvents,
+          hasMoreSpans
        )
      );
    } else {
@@ -154,6 +155,7 @@ export default class ObserveSession extends EasCommand {
          metadata,
          hasMoreMetricEvents,
          hasMoreLogEvents,
+          hasMoreSpans,
        })
      );
    }
@@ -0,0 +1,80 @@
+import { Args } from '@oclif/core';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import { EasCommandError } from '../../commandUtils/errors';
+import {
+  EasNonInteractiveAndJsonFlags,
+  EasProjectIdFlag,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../commandUtils/flags';
+import { ObserveQuery } from '../../graphql/queries/ObserveQuery';
+import Log from '../../log';
+import { buildObserveTraceJson, buildObserveTraceTable } from '../../observe/formatSpans';
+import { withObservePlanGateHandlingAsync } from '../../observe/planGating';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
+
+// A trace ID is the 32-character hex string of the OTLP JSON encoding.
+const TRACE_ID_REGEX = /^[0-9a-f]{32}$/i;
+
+export default class ObserveTrace extends EasCommand {
+  static override description =
+    'display every span of a single request trace by its trace ID, oldest first, with child spans indented under their parent. Trace IDs are shown by `eas observe:traces`. In `--json` output a span with no `parentSpanId` is a root span, and a span with no `http` object is not an HTTP request';
+
+  static override args = {
+    traceId: Args.string({
+      description: 'ID of the trace to display',
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...EasProjectIdFlag,
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectId,
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags, args } = await this.parse(ObserveTrace);
+    const { json, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+
+    const traceId = args.traceId;
+    if (!TRACE_ID_REGEX.test(traceId)) {
+      throw new EasCommandError(
+        `"${traceId}" is not a valid trace ID. A trace ID is 32 hexadecimal characters; copy it from the Trace ID column of \`eas observe:traces\`.`
+      );
+    }
+
+    const {
+      projectId,
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(ObserveTrace, {
+      nonInteractive,
+      projectIdOverride: flags['project-id'],
+    });
+
+    if (json) {
+      enableJsonOutput();
+    }
+
+    const trace = await withObservePlanGateHandlingAsync(() =>
+      ObserveQuery.traceByIdAsync(graphqlClient, { appId: projectId, id: traceId })
+    );
+
+    if (!trace) {
+      throw new EasCommandError(
+        `No trace found with ID "${traceId}". Trace IDs come from \`eas observe:traces\`, and traces age out of retention.`
+      );
+    }
+
+    if (json) {
+      printJsonOnlyOutput(buildObserveTraceJson(trace));
+    } else {
+      Log.addNewLineIfNone();
+      Log.log(buildObserveTraceTable(trace));
+    }
+  }
+}
@@ -0,0 +1,203 @@
+import { Flags } from '@oclif/core';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import {
+  EasNonInteractiveAndJsonFlags,
+  EasProjectIdFlag,
+  resolveNonInteractiveAndJsonFlags,
+} from '../../commandUtils/flags';
+import { getLimitFlagWithCustomValues } from '../../commandUtils/pagination';
+import { ObserveQuery } from '../../graphql/queries/ObserveQuery';
+import Log from '../../log';
+import { fetchObserveSpansAsync } from '../../observe/fetchSpans';
+import {
+  ObserveAfterFlag,
+  ObserveAppVersionFlag,
+  ObserveBuildNumberFlag,
+  ObserveEnvironmentFlag,
+  ObservePlatformFlag,
+  ObserveTimeRangeFlags,
+  ObserveUpdateIdFlag,
+} from '../../observe/flags';
+import {
+  buildObserveSpanNamesJson,
+  buildObserveSpanNamesTable,
+  buildObserveSpansJson,
+  buildObserveSpansTable,
+} from '../../observe/formatSpans';
+import { withObservePlanGateHandlingAsync } from '../../observe/planGating';
+import { observePlatformsFromFlag } from '../../observe/platforms';
+import {
+  allowedSpanKindFlagValues,
+  allowedSpanStatusFlagValues,
+  spanKindsFromFlag,
+  spanStatusCodesFromFlag,
+} from '../../observe/spanFilters';
+import { resolveTimeRange } from '../../observe/startAndEndTime';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
+
+const DEFAULT_SPANS_LIMIT = 20;
+
+export default class ObserveTraces extends EasCommand {
+  static override description =
+    'display request trace spans recorded by the app, newest first. With no span filters, a summary of span names and kinds with counts is returned. Pass --all-spans or a span filter (--name, --kind, --status, --host, --http-status, --min-duration, --root-only, --session-id) to list individual spans';
+
+  static override flags = {
+    ...ObservePlatformFlag,
+    ...ObserveAfterFlag,
+    limit: getLimitFlagWithCustomValues({
+      defaultTo: DEFAULT_SPANS_LIMIT,
+      limit: 100,
+    }),
+    ...ObserveTimeRangeFlags,
+    ...ObserveAppVersionFlag,
+    ...ObserveBuildNumberFlag,
+    ...ObserveUpdateIdFlag,
+    ...ObserveEnvironmentFlag,
+    'session-id': Flags.string({
+      description: 'Filter by session ID',
+    }),
+    name: Flags.string({
+      description: 'Filter by span name, such as GET or POST (can be specified multiple times)',
+      multiple: true,
+    }),
+    kind: Flags.option({
+      description: 'Filter by span kind (can be specified multiple times)',
+      multiple: true,
+      options: allowedSpanKindFlagValues,
+    })(),
+    status: Flags.option({
+      description: 'Filter by span status (can be specified multiple times)',
+      multiple: true,
+      options: allowedSpanStatusFlagValues,
+    })(),
+    host: Flags.string({
+      description: 'Filter by request host (can be specified multiple times)',
+      multiple: true,
+    }),
+    'http-status': Flags.integer({
+      description: 'Filter by HTTP response status code (can be specified multiple times)',
+      multiple: true,
+    }),
+    'min-duration': Flags.integer({
+      description: 'Only spans that took at least this many milliseconds',
+      min: 0,
+    }),
+    'root-only': Flags.boolean({
+      description: 'Only root spans (spans with no parent)',
+      default: false,
+    }),
+    'all-spans': Flags.boolean({
+      description:
+        'List individual spans instead of the summary of span names + counts, even with no span filter',
+      default: false,
+    }),
+    ...EasProjectIdFlag,
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectId,
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(ObserveTraces);
+    const { json, nonInteractive } = resolveNonInteractiveAndJsonFlags(flags);
+
+    const {
+      projectId,
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(ObserveTraces, {
+      nonInteractive,
+      projectIdOverride: flags['project-id'],
+    });
+
+    if (json) {
+      enableJsonOutput();
+    }
+
+    const { daysBack, startTime, endTime } = resolveTimeRange(flags);
+    const platforms = observePlatformsFromFlag(flags.platform);
+
+    const hasSpanFilter =
+      flags['session-id'] !== undefined ||
+      (flags.name?.length ?? 0) > 0 ||
+      (flags.kind?.length ?? 0) > 0 ||
+      (flags.status?.length ?? 0) > 0 ||
+      (flags.host?.length ?? 0) > 0 ||
+      (flags['http-status']?.length ?? 0) > 0 ||
+      flags['min-duration'] !== undefined ||
+      flags['root-only'];
+
+    // The names summary has no span-level filters and no pagination, so any of
+    // those (or --all-spans) means the caller wants the span list.
+    if (!hasSpanFilter && !flags['all-spans'] && !flags.after) {
+      const { names, isTruncated } = await withObservePlanGateHandlingAsync(() =>
+        ObserveQuery.spanNamesAsync(graphqlClient, {
+          appId: projectId,
+          input: {
+            startTime,
+            endTime,
+            ...(platforms?.length && { platforms }),
+            ...(flags.environment && { environment: flags.environment }),
+            ...(flags['app-version'] && { appVersion: flags['app-version'] }),
+            ...(flags['build-number'] && { appBuildNumber: flags['build-number'] }),
+            ...(flags['update-id'] && { appUpdateId: flags['update-id'] }),
+          },
+        })
+      );
+
+      if (json) {
+        printJsonOnlyOutput(buildObserveSpanNamesJson(names, isTruncated));
+      } else {
+        Log.addNewLineIfNone();
+        Log.log(
+          buildObserveSpanNamesTable(names, {
+            daysBack,
+            startTime,
+            endTime,
+            isTruncated,
+          })
+        );
+      }
+      return;
+    }
+
+    const { spans, pageInfo } = await withObservePlanGateHandlingAsync(() =>
+      fetchObserveSpansAsync(graphqlClient, projectId, {
+        limit: flags.limit ?? DEFAULT_SPANS_LIMIT,
+        ...(flags.after && { after: flags.after }),
+        startTime,
+        endTime,
+        platforms,
+        appVersion: flags['app-version'],
+        buildNumber: flags['build-number'],
+        updateId: flags['update-id'],
+        environment: flags.environment,
+        sessionId: flags['session-id'],
+        names: flags.name,
+        kinds: spanKindsFromFlag(flags.kind),
+        statusCodes: spanStatusCodesFromFlag(flags.status),
+        hosts: flags.host,
+        httpStatusCodes: flags['http-status'],
+        minDurationMs: flags['min-duration'],
+        rootOnly: flags['root-only'],
+      })
+    );
+
+    if (json) {
+      printJsonOnlyOutput(buildObserveSpansJson(spans, pageInfo));
+    } else {
+      Log.addNewLineIfNone();
+      Log.log(
+        buildObserveSpansTable(spans, pageInfo, {
+          daysBack,
+          startTime,
+          endTime,
+          sessionId: flags['session-id'],
+        })
+      );
+    }
+  }
+}
@@ -187,6 +187,69 @@ describe(syncCapabilityIdentifiersForEntitlementsAsync, () => {
    expect(bundleId.updateBundleIdCapabilityAsync).toHaveBeenCalledTimes(1);
  });

+  it(`keeps already linked capability identifiers when linking another one`, async () => {
+    const Apple = require('@expo/apple-utils');
+    mockCapabilities(Apple);
+    const bundleId = {
+      context: {},
+      updateBundleIdCapabilityAsync: jest.fn(),
+      id: 'XXX',
+    } as any;
+
+    const result = await syncCapabilityIdentifiersForEntitlementsAsync(bundleId, {
+      'com.apple.security.application-groups': ['group.expo', 'group.bacon'],
+    });
+
+    expect(result).toStrictEqual({
+      created: ['group.bacon'],
+      linked: ['group.bacon'],
+    });
+    expect(bundleId.updateBundleIdCapabilityAsync).toHaveBeenCalledTimes(1);
+    expect(bundleId.updateBundleIdCapabilityAsync).toHaveBeenLastCalledWith([
+      {
+        capabilityType: 'APP_GROUPS',
+        option: 'ON',
+        relationships: {
+          appGroups: ['XXX-group-1', 'XXX-group-2'],
+        },
+      },
+    ]);
+  });
+
+  it(`keeps already linked capability identifiers when linking an existing unlinked one`, async () => {
+    const Apple = require('@expo/apple-utils');
+    mockCapabilities(Apple);
+    Apple.AppGroup.getAsync.mockResolvedValue([
+      mockItems.appGroup.expo,
+      { id: 'XXX-group-2', attributes: { identifier: 'group.bacon' } },
+    ]);
+    const bundleId = {
+      context: {},
+      updateBundleIdCapabilityAsync: jest.fn(),
+      id: 'XXX',
+    } as any;
+
+    const result = await syncCapabilityIdentifiersForEntitlementsAsync(bundleId, {
+      'com.apple.security.application-groups': ['group.expo', 'group.bacon'],
+    });
+
+    expect(result).toStrictEqual({
+      created: [],
+      linked: ['group.bacon'],
+    });
+    expect(Apple.AppGroup.createAsync).not.toHaveBeenCalled();
+    expect(bundleId.updateBundleIdCapabilityAsync).toHaveBeenCalledTimes(1);
+    expect(bundleId.updateBundleIdCapabilityAsync).toHaveBeenLastCalledWith([
+      {
+        capabilityType: 'APP_GROUPS',
+        option: 'ON',
+        relationships: {
+          appGroups: ['XXX-group-1', 'XXX-group-2'],
+        },
+      },
+    ]);
+  });
+
  it(`doesn't perform duplicate CapabilityModel.getAsync calls`, async () => {
    const Apple = require('@expo/apple-utils');
    mockCapabilities(Apple);
@@ -94,7 +94,8 @@ export async function syncCapabilityIdentifiersForEntitlementsAsync(
      (remoteLinkedIds?.[CapabilityModel.type] ?? []).map(model => model.id)
    );

-    // A list of server IDs for linking.
+    // A list of server IDs for linking. The update replaces the linked identifiers,
+    // so this includes the ones that are already linked.
    const capabilityIdOpaqueIds: string[] = [];

    // Iterate through all the local IDs and see if they exist on the server.
@@ -106,8 +107,8 @@ export async function syncCapabilityIdentifiersForEntitlementsAsync(
        if (!alreadyLinkedOpaqueIds.has(remoteIdModel.id)) {
          // Link the existing identifier to this bundle.
          linkedIds.push(remoteIdModel.attributes.identifier);
-          capabilityIdOpaqueIds.push(remoteIdModel.id);
        }
+        capabilityIdOpaqueIds.push(remoteIdModel.id);
        continue;
      }

@@ -133,7 +134,9 @@ export async function syncCapabilityIdentifiersForEntitlementsAsync(
      capabilityIdOpaqueIds.push(remoteIdModel.id);
    }

-    if (capabilityIdOpaqueIds.length) {
+    // The update replaces the linked identifiers, so it is sent only when one of them is not
+    // linked yet. An identifier removed from the entitlements therefore stays linked.
+    if (capabilityIdOpaqueIds.some(id => !alreadyLinkedOpaqueIds.has(id))) {
      updateRequest.push({
        capabilityType: classifier.capability,
        option: CapabilityTypeOption.ON,
@@ -15896,6 +15896,14 @@ export type CreateAppScopedUploadSessionMutationVariables = Exact<{

 export type CreateAppScopedUploadSessionMutation = { __typename?: 'RootMutation', uploadSession: { __typename?: 'UploadSession', createAppScopedUploadSession: any } };

+export type SetUserPreferenceMutationVariables = Exact<{
+  key: Scalars['String']['input'];
+  value: Scalars['JSON']['input'];
+}>;
+
+
+export type SetUserPreferenceMutation = { __typename?: 'RootMutation', userPreference: { __typename?: 'UserPreferenceMutation', set: { __typename?: 'UserPreference', id: string, key: string, value: any } } };
+
 export type CreateWebhookMutationVariables = Exact<{
  appId: Scalars['String']['input'];
  webhookInput: WebhookInput;
@@ -15989,6 +15997,14 @@ export type AccountFullUsageQueryVariables = Exact<{

 export type AccountFullUsageQuery = { __typename?: 'RootQuery', account: { __typename?: 'AccountQuery', byId: { __typename?: 'Account', id: string, name: string, subscription?: { __typename?: 'SubscriptionDetails', id: string, name?: string | null, status?: string | null, nextInvoice?: any | null, nextInvoiceAmountDueCents?: number | null, recurringCents?: number | null, price: number, concurrencies?: { __typename?: 'Concurrencies', total: number, android: number, ios: number } | null, addons: Array<{ __typename?: 'AddonDetails', id: string, name: string, quantity?: number | null }>, upcomingInvoice?: { __typename?: 'Invoice', id: string, total: number, lineItems: Array<{ __typename?: 'InvoiceLineItem', id: string, description: string, amount: number, period: { __typename?: 'InvoicePeriod', start: any, end: any } }> } | null } | null, billingPeriod: { __typename?: 'BillingPeriod', id: string, start: any, end: any, anchor: any }, usageMetrics: { __typename?: 'AccountUsageMetrics', MEDIUM_ANDROID_BUILDS: Array<{ __typename?: 'AccountUsageMetric', id: string, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number }>, LARGE_ANDROID_BUILDS: Array<{ __typename?: 'AccountUsageMetric', id: string, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number }>, MEDIUM_IOS_BUILDS: Array<{ __typename?: 'AccountUsageMetric', id: string, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number }>, LARGE_IOS_BUILDS: Array<{ __typename?: 'AccountUsageMetric', id: string, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number }>, EAS_BUILD: { __typename?: 'UsageMetricTotal', id: string, totalCost: number, billingPeriod: { __typename?: 'BillingPeriod', id: string, start: any, end: any, anchor: any }, planMetrics: Array<{ __typename?: 'EstimatedUsage', id: string, service: EasService, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number, limit: number, platformBreakdown?: { __typename?: 'EstimatedUsagePlatformBreakdown', ios: { __typename?: 'EstimatedUsagePlatformDetail', value: number, limit: number }, android: { __typename?: 'EstimatedUsagePlatformDetail', value: number, limit: number } } | null, jobTypeBreakdown?: { __typename?: 'EstimatedUsageJobTypeBreakdown', workflows: number, simulator: number, other: number } | null }>, overageMetrics: Array<{ __typename?: 'EstimatedOverageAndCost', id: string, service: EasService, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number, limit: number, totalCost: number, metadata?: { __typename?: 'AccountUsageEASBuildMetadata', billingResourceClass?: EasBuildBillingResourceClass | null, platform?: AppPlatform | null } | null }> }, EAS_UPDATE: { __typename?: 'UsageMetricTotal', id: string, totalCost: number, billingPeriod: { __typename?: 'BillingPeriod', id: string, start: any, end: any, anchor: any }, planMetrics: Array<{ __typename?: 'EstimatedUsage', id: string, service: EasService, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number, limit: number, platformBreakdown?: { __typename?: 'EstimatedUsagePlatformBreakdown', ios: { __typename?: 'EstimatedUsagePlatformDetail', value: number, limit: number }, android: { __typename?: 'EstimatedUsagePlatformDetail', value: number, limit: number } } | null, jobTypeBreakdown?: { __typename?: 'EstimatedUsageJobTypeBreakdown', workflows: number, simulator: number, other: number } | null }>, overageMetrics: Array<{ __typename?: 'EstimatedOverageAndCost', id: string, service: EasService, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number, limit: number, totalCost: number, metadata?: { __typename?: 'AccountUsageEASBuildMetadata', billingResourceClass?: EasBuildBillingResourceClass | null, platform?: AppPlatform | null } | null }> }, EAS_SIMULATOR: { __typename?: 'UsageMetricTotal', id: string, totalCost: number, unavailableServiceUsageMetrics: Array<{ __typename?: 'UnavailableServiceUsageMetric', service: EasService }>, billingPeriod: { __typename?: 'BillingPeriod', id: string, start: any, end: any, anchor: any }, planMetrics: Array<{ __typename?: 'EstimatedUsage', id: string, service: EasService, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number, limit: number, platformBreakdown?: { __typename?: 'EstimatedUsagePlatformBreakdown', ios: { __typename?: 'EstimatedUsagePlatformDetail', value: number, limit: number }, android: { __typename?: 'EstimatedUsagePlatformDetail', value: number, limit: number } } | null, jobTypeBreakdown?: { __typename?: 'EstimatedUsageJobTypeBreakdown', workflows: number, simulator: number, other: number } | null }>, overageMetrics: Array<{ __typename?: 'EstimatedOverageAndCost', id: string, service: EasService, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number, limit: number, totalCost: number, metadata?: { __typename?: 'AccountUsageEASBuildMetadata', billingResourceClass?: EasBuildBillingResourceClass | nulLine truncated

+export type AccountFreeTierBuildUsageQueryVariables = Exact<{
+  accountId: Scalars['String']['input'];
+  currentDate: Scalars['DateTime']['input'];
+}>;
+
+
+export type AccountFreeTierBuildUsageQuery = { __typename?: 'RootQuery', account: { __typename?: 'AccountQuery', byId: { __typename?: 'Account', id: string, subscription?: { __typename?: 'SubscriptionDetails', id: string, name?: string | null } | null, billingPeriod: { __typename?: 'BillingPeriod', id: string, start: any, end: any }, usageMetrics: { __typename?: 'AccountUsageMetrics', EAS_BUILD: { __typename?: 'UsageMetricTotal', id: string, planMetrics: Array<{ __typename?: 'EstimatedUsage', id: string, serviceMetric: EasServiceMetric, metricType: UsageMetricType, value: number, limit: number, platformBreakdown?: { __typename?: 'EstimatedUsagePlatformBreakdown', ios: { __typename?: 'EstimatedUsagePlatformDetail', value: number, limit: number }, android: { __typename?: 'EstimatedUsagePlatformDetail', value: number, limit: number } } | null }> } } } } };
+
 export type AccountUsageForOverageWarningQueryVariables = Exact<{
  accountId: Scalars['String']['input'];
  currentDate: Scalars['DateTime']['input'];
@@ -16529,13 +16545,41 @@ export type AppObserveSessionEventsQueryVariables = Exact<{
  first?: InputMaybe<Scalars['Int']['input']>;
  metricsOrderBy?: InputMaybe<AppObserveMetricsListOrderBy>;
  logsOrderBy?: InputMaybe<AppObserveLogsOrderBy>;
+  spansOrderBy?: InputMaybe<AppObserveSpanListOrderBy>;
 }>;


 export type AppObserveSessionEventsQuery = { __typename?: 'RootQuery', app: { __typename?: 'AppQuery', byId: { __typename?: 'App', id: string, observe: { __typename?: 'AppObserve', session: { __typename?: 'AppObserveSession', id: string, metrics: { __typename?: 'AppObserveMetricConnection', pageInfo: { __typename?: 'PageInfo', hasNextPage: boolean, hasPreviousPage: boolean, endCursor?: string | null }, edges: Array<{ __typename?: 'AppObserveMetricEdge', node: { __typename?: 'AppObserveMetric', id: string, name: string, value: number, timestamp: any, appVersion: string, appBuildNumber: string, appUpdateId?: string | null, deviceModel: string, deviceOs: string, deviceOsVersion: string, countryCode?: string | null, sessionId?: string | null, easClientId: string, customParams?: any | null, routeName?: string | null } }> }, logs: { __typename?: 'AppObserveLogConnection', pageInfo: { __typename?: 'PageInfo', hasNextPage: boolean, hasPreviousPage: boolean, endCursor?: string | null }, edges: Array<{ __typename?: 'AppObserveLogEdge', node:
                | { __typename: 'AppObserveError', id: string, timestamp: any, sessionId?: string | null, severityNumber?: number | null, severityText?: string | null, type?: string | null, message?: string | null, source?: string | null, fingerprint?: string | null, isFatal?: boolean | null, appVersion: string, appBuildNumber: string, appUpdateId?: string | null, appEasBuildId?: string | null, deviceOs: string, deviceOsVersion: string, deviceModel: string, environment?: string | null, easClientId: string, countryCode?: string | null, properties: Array<{ __typename?: 'AppObserveEventProperty', key: string, value: string, type: AppObservePropertyType }> }
                | { __typename: 'AppObserveUserEvent', id: string, name: string, timestamp: any, sessionId?: string | null, severityNumber?: number | null, severityText?: string | null, appVersion: string, appBuildNumber: string, appUpdateId?: string | null, appEasBuildId?: string | null, deviceOs: string, deviceOsVersion: string, deviceModel: string, environment?: string | null, easClientId: string, countryCode?: string | null, properties: Array<{ __typename?: 'AppObserveEventProperty', key: string, value: string, type: AppObservePropertyType }> }
-               }> } } } } } };
+               }> }, spans: { __typename?: 'AppObserveSpanConnection', pageInfo: { __typename?: 'PageInfo', hasNextPage: boolean, hasPreviousPage: boolean, endCursor?: string | null }, edges: Array<{ __typename?: 'AppObserveSpanEdge', node: { __typename?: 'AppObserveSpan', id: string, traceId: string, spanId: string, parentSpanId?: string | null, name: string, kind: AppObserveSpanKind, startTimestamp: any, endTimestamp: any, durationMs: number, statusCode: AppObserveSpanStatusCode, statusMessage?: string | null, sessionId?: string | null, droppedAttributesCount: number, droppedEventsCount: number, droppedLinksCount: number, ingestedAt?: any | null, appVersion: string, appBuildNumber: string, appUpdateId?: string | null, appEasBuildId?: string | null, expoSdkVersion?: string | null, reactNativeVersion?: string | null, deviceOs: string, deviceOsVersion: string, deviceModel: string, environment?: string | null, easClientId: string, countryCode?: string | null, http?: { __typename?: 'AppObserveSpanHttp', method?: string | null, statusCode?: number | null, urlHost?: string | null, urlFull?: string | null, protocolVersion?: string | null, requestSize?: number | null, responseSize?: number | null, errorType?: string | null } | null, attributes: Array<{ __typename?: 'AppObserveEventProperty', key: string, value: string, type: AppObservePropertyType }>, events: Array<{ __typename?: 'AppObserveSpanEvent', name: string, timestamp: any, attributes: any }> } }> } } } } } };
+
+export type AppObserveSpanListQueryVariables = Exact<{
+  appId: Scalars['String']['input'];
+  filter: AppObserveSpanListFilter;
+  first?: InputMaybe<Scalars['Int']['input']>;
+  after?: InputMaybe<Scalars['String']['input']>;
+  orderBy?: InputMaybe<AppObserveSpanListOrderBy>;
+}>;
+
+
+export type AppObserveSpanListQuery = { __typename?: 'RootQuery', app: { __typename?: 'AppQuery', byId: { __typename?: 'App', id: string, observe: { __typename?: 'AppObserve', traces: { __typename?: 'AppObserveTraces', spans: { __typename?: 'AppObserveSpanConnection', pageInfo: { __typename?: 'PageInfo', hasNextPage: boolean, hasPreviousPage: boolean, endCursor?: string | null }, edges: Array<{ __typename?: 'AppObserveSpanEdge', cursor: string, node: { __typename?: 'AppObserveSpan', id: string, traceId: string, spanId: string, parentSpanId?: string | null, name: string, kind: AppObserveSpanKind, startTimestamp: any, endTimestamp: any, durationMs: number, statusCode: AppObserveSpanStatusCode, statusMessage?: string | null, sessionId?: string | null, droppedAttributesCount: number, droppedEventsCount: number, droppedLinksCount: number, ingestedAt?: any | null, appVersion: string, appBuildNumber: string, appUpdateId?: string | null, appEasBuildId?: string | null, expoSdkVersion?: string | null, reactNativeVersion?: string | null, deviceOs: string, deviceOsVersion: string, deviceModel: string, environment?: string | null, easClientId: string, countryCode?: string | null, http?: { __typename?: 'AppObserveSpanHttp', method?: string | null, statusCode?: number | null, urlHost?: string | null, urlFull?: string | null, protocolVersion?: string | null, requestSize?: number | null, responseSize?: number | null, errorType?: string | null } | null, attributes: Array<{ __typename?: 'AppObserveEventProperty', key: string, value: string, type: AppObservePropertyType }>, events: Array<{ __typename?: 'AppObserveSpanEvent', name: string, timestamp: any, attributes: any }> } }> } } } } } };
+
+export type AppObserveSpanNamesQueryVariables = Exact<{
+  appId: Scalars['String']['input'];
+  input: AppObserveSpanNamesInput;
+}>;
+
+
+export type AppObserveSpanNamesQuery = { __typename?: 'RootQuery', app: { __typename?: 'AppQuery', byId: { __typename?: 'App', id: string, observe: { __typename?: 'AppObserve', traces: { __typename?: 'AppObserveTraces', names: { __typename?: 'AppObserveSpanNames', isTruncated: boolean, names: Array<{ __typename?: 'AppObserveSpanName', name: string, kind: AppObserveSpanKind, count: number }> } } } } } };
+
+export type AppObserveTraceByIdQueryVariables = Exact<{
+  appId: Scalars['String']['input'];
+  id: Scalars['ID']['input'];
+}>;
+
+
+export type AppObserveTraceByIdQuery = { __typename?: 'RootQuery', app: { __typename?: 'AppQuery', byId: { __typename?: 'App', id: string, observe: { __typename?: 'AppObserve', traces: { __typename?: 'AppObserveTraces', trace?: { __typename?: 'AppObserveTrace', id: string, isTruncated: boolean, spans: Array<{ __typename?: 'AppObserveSpan', id: string, traceId: string, spanId: string, parentSpanId?: string | null, name: string, kind: AppObserveSpanKind, startTimestamp: any, endTimestamp: any, durationMs: number, statusCode: AppObserveSpanStatusCode, statusMessage?: string | null, sessionId?: string | null, droppedAttributesCount: number, droppedEventsCount: number, droppedLinksCount: number, ingestedAt?: any | null, appVersion: string, appBuildNumber: string, appUpdateId?: string | null, appEasBuildId?: string | null, expoSdkVersion?: string | null, reactNativeVersion?: string | null, deviceOs: string, deviceOsVersion: string, deviceModel: string, environment?: string | null, easClientId: string, countryCode?: string | null, http?: { __typename?: 'AppObserveSpanHttp', method?: string | null, statusCode?: number | null, urlHost?: string | null, urlFull?: string | null, protocolVersion?: string | null, requestSize?: number | null, responseSize?: number | null, errorType?: string | null } | null, attributes: Array<{ __typename?: 'AppObserveEventProperty', key: string, value: string, type: AppObservePropertyType }>, events: Array<{ __typename?: 'AppObserveSpanEvent', name: string, timestamp: any, attributes: any }> }> } | null } } } } };

 export type AppObserveMetricByIdQueryVariables = Exact<{
  appId: Scalars['String']['input'];
@@ -16769,6 +16813,13 @@ export type UpdateByIdQuery = { __typename?: 'RootQuery', updates: { __typename?
        | { __typename: 'User', username: string, id: string }
       | null, branch: { __typename?: 'UpdateBranch', id: string, name: string }, codeSigningInfo?: { __typename?: 'CodeSigningInfo', keyid: string, sig: string, alg: string } | null, rolloutControlUpdate?: { __typename?: 'Update', id: string, group: string } | null, fingerprint?: { __typename?: 'Fingerprint', id: string, hash: string, debugInfoUrl?: string | null, source?: { __typename?: 'FingerprintSource', type: FingerprintSourceType, bucketKey: string, isDebugFingerprint?: boolean | null } | null } | null } } };

+export type UserPreferenceByKeyQueryVariables = Exact<{
+  key: Scalars['String']['input'];
+}>;
+
+
+export type UserPreferenceByKeyQuery = { __typename?: 'RootQuery', userPreference: { __typename?: 'UserPreferenceQuery', get?: { __typename?: 'UserPreference', id: string, key: string, value: any } | null } };
+
 export type CurrentUserQueryVariables = Exact<{ [key: string]: never; }>;


@@ -17059,6 +17110,8 @@ export type AppObserveErrorGroupFragment = { __typename?: 'AppObserveErrorGroup'

 export type AppObserveAppVersionFragment = { __typename?: 'AppObserveAppVersion', appVersion: string, firstSeenAt: any, eventCount: number, uniqueUserCount: number, buildNumbers: Array<{ __typename?: 'AppObserveAppBuildNumber', appBuildNumber: string, firstSeenAt: any, eventCount: number, uniqueUserCount: number, easBuilds: Array<{ __typename?: 'AppObserveAppEasBuild', easBuildId: string, firstSeenAt: any, eventCount: number, uniqueUserCount: number }> }>, updates: Array<{ __typename?: 'AppObserveAppUpdate', appUpdateId: string, firstSeenAt: any, eventCount: number, uniqueUserCount: number, easBuilds: Array<{ __typename?: 'AppObserveAppEasBuild', easBuildId: string, firstSeenAt: any, eventCount: number, uniqueUserCount: number }> }>, metrics: Array<{ __typename?: 'AppObserveAppVersionMetric', metricName: string, eventCount: number, statistics: { __typename?: 'AppObserveVersionMarkerStatistics', min?: number | null, max?: number | null, median?: number | null, average?: number | null, p80?: number | null, p90?: number | null, p99?: number | null } }> };

+export type AppObserveSpanFragment = { __typename?: 'AppObserveSpan', id: string, traceId: string, spanId: string, parentSpanId?: string | null, name: string, kind: AppObserveSpanKind, startTimestamp: any, endTimestamp: any, durationMs: number, statusCode: AppObserveSpanStatusCode, statusMessage?: string | null, sessionId?: string | null, droppedAttributesCount: number, droppedEventsCount: number, droppedLinksCount: number, ingestedAt?: any | null, appVersion: string, appBuildNumber: string, appUpdateId?: string | null, appEasBuildId?: string | null, expoSdkVersion?: string | null, reactNativeVersion?: string | null, deviceOs: string, deviceOsVersion: string, deviceModel: string, environment?: string | null, easClientId: string, countryCode?: string | null, http?: { __typename?: 'AppObserveSpanHttp', method?: string | null, statusCode?: number | null, urlHost?: string | null, urlFull?: string | null, protocolVersion?: string | null, requestSize?: number | null, responseSize?: number | null, errorType?: string | null } | null, attributes: Array<{ __typename?: 'AppObserveEventProperty', key: string, value: string, type: AppObservePropertyType }>, events: Array<{ __typename?: 'AppObserveSpanEvent', name: string, timestamp: any, attributes: any }> };
+
 export type PostHogOrganizationConnectionFragment = { __typename?: 'PostHogOrganizationConnection', id: string, posthogOrganizationIdentifier: string, posthogOrganizationName: string, posthogRegion: PostHogRegion, createdAt: any, updatedAt: any };

 export type PostHogProjectFragment = { __typename?: 'PostHogProject', id: string, posthogProjectIdentifier: string, posthogProjectName: string, posthogProjectToken: string, posthogHost: string, createdAt: any, updatedAt: any, posthogOrganizationConnection: { __typename?: 'PostHogOrganizationConnection', id: string, posthogOrganizationIdentifier: string, posthogOrganizationName: string, posthogRegion: PostHogRegion, createdAt: any, updatedAt: any } };
@@ -0,0 +1,30 @@
+import gql from 'graphql-tag';
+
+import { ExpoGraphqlClient } from '../../commandUtils/context/contextUtils/createGraphqlClient';
+import { withErrorHandlingAsync } from '../client';
+import { SetUserPreferenceMutation, SetUserPreferenceMutationVariables } from '../generated';
+
+export const UserPreferenceMutation = {
+  /** Stores the JSON value under the key for the current user. Rejects for robot viewers. */
+  async setAsync(graphqlClient: ExpoGraphqlClient, key: string, value: unknown): Promise<void> {
+    await withErrorHandlingAsync(
+      graphqlClient
+        .mutation<SetUserPreferenceMutation, SetUserPreferenceMutationVariables>(
+          gql`
+            mutation SetUserPreference($key: String!, $value: JSON!) {
+              userPreference {
+                set(key: $key, value: $value) {
+                  id
+                  key
+                  value
+                }
+              }
+            }
+          `,
+          { key, value },
+          { additionalTypenames: ['UserPreference'], noRetry: true }
+        )
+        .toPromise()
+    );
+  },
+};
@@ -0,0 +1,45 @@
+import { CombinedError } from '@urql/core';
+import { print } from 'graphql';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { UserPreferenceMutation } from '../UserPreferenceMutation';
+
+function makeGraphqlClient(result: { data?: unknown; error?: CombinedError }): ExpoGraphqlClient & {
+  mutation: jest.Mock;
+} {
+  return {
+    mutation: jest.fn().mockReturnValue({ toPromise: jest.fn().mockResolvedValue(result) }),
+  } as unknown as ExpoGraphqlClient & { mutation: jest.Mock };
+}
+
+describe('UserPreferenceMutation.setAsync', () => {
+  it('sets the preference by key', async () => {
+    const graphqlClient = makeGraphqlClient({
+      data: {
+        userPreference: {
+          set: { id: 'preference-id', key: 'some-key', value: { billingPeriodId: 'period-1' } },
+        },
+      },
+    });
+
+    await expect(
+      UserPreferenceMutation.setAsync(graphqlClient, 'some-key', { billingPeriodId: 'period-1' })
+    ).resolves.toBeUndefined();
+
+    const [document, variables, context] = graphqlClient.mutation.mock.calls[0];
+    const printed = print(document);
+    expect(printed).toContain('mutation SetUserPreference');
+    expect(printed).toContain('set(key: $key, value: $value)');
+    expect(variables).toEqual({ key: 'some-key', value: { billingPeriodId: 'period-1' } });
+    expect(context).toEqual({ additionalTypenames: ['UserPreference'], noRetry: true });
+  });
+
+  it('rejects on a GraphQL error', async () => {
+    const error = new CombinedError({ networkError: new Error('forbidden') });
+    const graphqlClient = makeGraphqlClient({ error });
+
+    await expect(
+      UserPreferenceMutation.setAsync(graphqlClient, 'some-key', { billingPeriodId: 'period-1' })
+    ).rejects.toBe(error);
+  });
+});
@@ -6,6 +6,8 @@ import { withErrorHandlingAsync } from '../client';
 import {
  AccountByNameQuery as AccountByNameQueryType,
  AccountByNameQueryVariables,
+  AccountFreeTierBuildUsageQuery,
+  AccountFreeTierBuildUsageQueryVariables,
  AccountFullUsageQuery as AccountFullUsageQueryType,
  AccountFullUsageQueryVariables,
  AccountSubscriptionQuery as AccountSubscriptionQueryType,
@@ -21,6 +23,9 @@ import {
 } from '../types/Account';

 export type AccountFullUsageData = NonNullable<AccountFullUsageQueryType['account']['byId']>;
+export type AccountFreeTierBuildUsageData = NonNullable<
+  AccountFreeTierBuildUsageQuery['account']['byId']
+>;
 export type AccountSubscriptionInfo = NonNullable<
  NonNullable<AccountSubscriptionQueryType['account']['byId']>['subscription']
 >;
@@ -208,6 +213,72 @@ export const AccountQuery = {
    return data.account.byId;
  },

+  async getFreeTierBuildUsageAsync(
+    graphqlClient: ExpoGraphqlClient,
+    accountId: string,
+    currentDate: Date
+  ): Promise<AccountFreeTierBuildUsageData> {
+    const data = await withErrorHandlingAsync(
+      graphqlClient
+        .query<AccountFreeTierBuildUsageQuery, AccountFreeTierBuildUsageQueryVariables>(
+          gql`
+            query AccountFreeTierBuildUsage($accountId: String!, $currentDate: DateTime!) {
+              account {
+                byId(accountId: $accountId) {
+                  id
+                  subscription {
+                    id
+                    name
+                  }
+                  billingPeriod(date: $currentDate) {
+                    id
+                    start
+                    end
+                  }
+                  usageMetrics {
+                    EAS_BUILD: byBillingPeriod(date: $currentDate, service: BUILDS) {
+                      id
+                      planMetrics {
+                        id
+                        serviceMetric
+                        metricType
+                        value
+                        limit
+                        platformBreakdown {
+                          ios {
+                            value
+                            limit
+                          }
+                          android {
+                            value
+                            limit
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          `,
+          { accountId, currentDate: currentDate.toISOString() },
+          {
+            additionalTypenames: [
+              'Account',
+              'AccountUsageMetrics',
+              'UsageMetricTotal',
+              'BillingPeriod',
+              'EstimatedUsage',
+            ],
+            noRetry: true,
+          }
+        )
+        .toPromise()
+    );
+
+    return data.account.byId;
+  },
+
  async getUsageForOverageWarningAsync(
    graphqlClient: ExpoGraphqlClient,
    accountId: string,
@@ -18,6 +18,12 @@ import {
  AppObserveNavigationRoute,
  AppObservePlatform,
  AppObserveReleasesInput,
+  AppObserveSpan,
+  AppObserveSpanListFilter,
+  AppObserveSpanListOrderBy,
+  AppObserveSpanName,
+  AppObserveSpanNamesInput,
+  AppObserveTrace,
  AppObserveUserEvent,
  AppObserveUserEventListFilter,
  AppObserveUserEventListOrderBy,
@@ -31,6 +37,7 @@ import {
  AppObserveErrorGroupFragmentNode,
  AppObserveErrorOccurrenceFragmentNode,
  AppObserveMetricFragmentNode,
+  AppObserveSpanFragmentNode,
  AppObserveUserEventFragmentNode,
 } from '../types/Observe';

@@ -222,6 +229,10 @@ type AppObserveSessionEventsQuery = {
            pageInfo: PageInfo;
            edges: Array<{ node: AppObserveSessionLog }>;
          };
+          spans: {
+            pageInfo: PageInfo;
+            edges: Array<{ node: AppObserveSpan }>;
+          };
        };
      };
    };
@@ -234,6 +245,68 @@ type AppObserveSessionEventsQueryVariables = {
  first?: number;
  metricsOrderBy?: AppObserveMetricsListOrderBy;
  logsOrderBy?: AppObserveLogsOrderBy;
+  spansOrderBy?: AppObserveSpanListOrderBy;
+};
+
+type AppObserveSpanListQuery = {
+  app: {
+    byId: {
+      id: string;
+      observe: {
+        traces: {
+          spans: {
+            pageInfo: PageInfo;
+            edges: Array<{
+              cursor: string;
+              node: AppObserveSpan;
+            }>;
+          };
+        };
+      };
+    };
+  };
+};
+
+type AppObserveSpanListQueryVariables = {
+  appId: string;
+  filter: AppObserveSpanListFilter;
+  first?: number;
+  after?: string;
+  orderBy?: AppObserveSpanListOrderBy;
+};
+
+type AppObserveSpanNamesQuery = {
+  app: {
+    byId: {
+      id: string;
+      observe: {
+        traces: {
+          names: {
+            isTruncated: boolean;
+            names: AppObserveSpanName[];
+          };
+        };
+      };
+    };
+  };
+};
+
+type AppObserveSpanNamesQueryVariables = {
+  appId: string;
+  input: AppObserveSpanNamesInput;
+};
+
+type AppObserveTraceByIdQuery = {
+  app: {
+    byId: {
+      id: string;
+      observe: {
+        traces: {
+          trace: AppObserveTrace | null;
+        };
+      };
+    };
+  };
 };

 type AppObserveMetricByIdQuery = {
@@ -645,8 +718,10 @@ export const ObserveQuery = {
  ): Promise<{
    metrics: AppObserveMetric[];
    logs: AppObserveSessionLog[];
+    spans: AppObserveSpan[];
    metricsPageInfo: PageInfo;
    logsPageInfo: PageInfo;
+    spansPageInfo: PageInfo;
  }> {
    const data = await withErrorHandlingAsync(
      graphqlClient
@@ -658,6 +733,7 @@ export const ObserveQuery = {
              $first: Int
              $metricsOrderBy: AppObserveMetricsListOrderBy
              $logsOrderBy: AppObserveLogsOrderBy
+              $spansOrderBy: AppObserveSpanListOrderBy
            ) {
              app {
                byId(appId: $appId) {
@@ -697,6 +773,19 @@ export const ObserveQuery = {
                          }
                        }
                      }
+                      spans(first: $first, orderBy: $spansOrderBy) {
+                        pageInfo {
+                          hasNextPage
+                          hasPreviousPage
+                          endCursor
+                        }
+                        edges {
+                          node {
+                            id
+                            ...AppObserveSpanFragment
+                          }
+                        }
+                      }
                    }
                  }
                }
@@ -705,21 +794,150 @@ export const ObserveQuery = {
            ${print(AppObserveMetricFragmentNode)}
            ${print(AppObserveUserEventFragmentNode)}
            ${print(AppObserveErrorFragmentNode)}
+            ${print(AppObserveSpanFragmentNode)}
          `,
          variables
        )
        .toPromise()
    );

-    const { metrics, logs } = data.app.byId.observe.session;
+    const { metrics, logs, spans } = data.app.byId.observe.session;
    return {
      metrics: metrics.edges.map(edge => edge.node),
      logs: logs.edges.map(edge => edge.node),
+      spans: spans.edges.map(edge => edge.node),
      metricsPageInfo: metrics.pageInfo,
      logsPageInfo: logs.pageInfo,
+      spansPageInfo: spans.pageInfo,
    };
  },

+  async spanListAsync(
+    graphqlClient: ExpoGraphqlClient,
+    variables: AppObserveSpanListQueryVariables
+  ): Promise<{ spans: AppObserveSpan[]; pageInfo: PageInfo }> {
+    const data = await withErrorHandlingAsync(
+      graphqlClient
+        .query<AppObserveSpanListQuery, AppObserveSpanListQueryVariables>(
+          gql`
+            query AppObserveSpanList(
+              $appId: String!
+              $filter: AppObserveSpanListFilter!
+              $first: Int
+              $after: String
+              $orderBy: AppObserveSpanListOrderBy
+            ) {
+              app {
+                byId(appId: $appId) {
+                  id
+                  observe {
+                    traces {
+                      spans(filter: $filter, first: $first, after: $after, orderBy: $orderBy) {
+                        pageInfo {
+                          hasNextPage
+                          hasPreviousPage
+                          endCursor
+                        }
+                        edges {
+                          cursor
+                          node {
+                            id
+                            ...AppObserveSpanFragment
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            ${print(AppObserveSpanFragmentNode)}
+          `,
+          variables
+        )
+        .toPromise()
+    );
+
+    const { edges, pageInfo } = data.app.byId.observe.traces.spans;
+    return {
+      spans: edges.map(edge => edge.node),
+      pageInfo,
+    };
+  },
+
+  async spanNamesAsync(
+    graphqlClient: ExpoGraphqlClient,
+    variables: AppObserveSpanNamesQueryVariables
+  ): Promise<{ names: AppObserveSpanName[]; isTruncated: boolean }> {
+    const data = await withErrorHandlingAsync(
+      graphqlClient
+        .query<AppObserveSpanNamesQuery, AppObserveSpanNamesQueryVariables>(
+          gql`
+            query AppObserveSpanNames($appId: String!, $input: AppObserveSpanNamesInput!) {
+              app {
+                byId(appId: $appId) {
+                  id
+                  observe {
+                    traces {
+                      names(input: $input) {
+                        isTruncated
+                        names {
+                          name
+                          kind
+                          count
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          `,
+          variables
+        )
+        .toPromise()
+    );
+
+    return data.app.byId.observe.traces.names;
+  },
+
+  async traceByIdAsync(
+    graphqlClient: ExpoGraphqlClient,
+    { appId, id }: AppObserveByIdQueryVariables
+  ): Promise<AppObserveTrace | null> {
+    const data = await withErrorHandlingAsync(
+      graphqlClient
+        .query<AppObserveTraceByIdQuery, AppObserveByIdQueryVariables>(
+          gql`
+            query AppObserveTraceById($appId: String!, $id: ID!) {
+              app {
+                byId(appId: $appId) {
+                  id
+                  observe {
+                    traces {
+                      trace(id: $id) {
+                        id
+                        isTruncated
+                        spans {
+                          id
+                          ...AppObserveSpanFragment
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            ${print(AppObserveSpanFragmentNode)}
+          `,
+          { appId, id }
+        )
+        .toPromise()
+    );
+
+    return data.app.byId.observe.traces.trace ?? null;
+  },
+
  async metricByIdAsync(
    graphqlClient: ExpoGraphqlClient,
    { appId, id }: AppObserveByIdQueryVariables
@@ -0,0 +1,34 @@
+import gql from 'graphql-tag';
+
+import { ExpoGraphqlClient } from '../../commandUtils/context/contextUtils/createGraphqlClient';
+import { withErrorHandlingAsync } from '../client';
+import { UserPreferenceByKeyQuery, UserPreferenceByKeyQueryVariables } from '../generated';
+
+export const UserPreferenceQuery = {
+  /**
+   * Returns the JSON value stored under the key for the current user, or null when the key is not
+   * set or the viewer is not a user (for example a robot).
+   */
+  async getValueAsync(graphqlClient: ExpoGraphqlClient, key: string): Promise<unknown> {
+    const data = await withErrorHandlingAsync(
+      graphqlClient
+        .query<UserPreferenceByKeyQuery, UserPreferenceByKeyQueryVariables>(
+          gql`
+            query UserPreferenceByKey($key: String!) {
+              userPreference {
+                get(key: $key) {
+                  id
+                  key
+                  value
+                }
+              }
+            }
+          `,
+          { key },
+          { additionalTypenames: ['UserPreference'], noRetry: true }
+        )
+        .toPromise()
+    );
+    return data.userPreference.get?.value ?? null;
+  },
+};
@@ -0,0 +1,91 @@
+import { CombinedError } from '@urql/core';
+import { print } from 'graphql';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { EasServiceMetric, UsageMetricType } from '../../generated';
+import { AccountQuery } from '../AccountQuery';
+
+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('AccountQuery.getFreeTierBuildUsageAsync', () => {
+  const currentDate = new Date('2026-10-26T12:00:00.000Z');
+  const account = {
+    id: 'account-id',
+    subscription: { id: 'subscription-id', name: 'Free' },
+    billingPeriod: {
+      id: 'period-1',
+      start: '2026-10-01T00:00:00.000Z',
+      end: '2026-11-01T00:00:00.000Z',
+    },
+    usageMetrics: {
+      EAS_BUILD: {
+        id: 'eas-build',
+        planMetrics: [
+          {
+            id: 'builds',
+            serviceMetric: EasServiceMetric.Builds,
+            metricType: UsageMetricType.Build,
+            value: 14,
+            limit: 30,
+            platformBreakdown: {
+              android: { value: 11, limit: 15 },
+              ios: { value: 3, limit: 15 },
+            },
+          },
+        ],
+      },
+    },
+  };
+
+  it('returns the account usage', async () => {
+    const graphqlClient = makeGraphqlClient({ data: { account: { byId: account } } });
+
+    await expect(
+      AccountQuery.getFreeTierBuildUsageAsync(graphqlClient, 'account-id', currentDate)
+    ).resolves.toEqual(account);
+  });
+
+  it('selects the plan name, billing period, and per-platform build usage for the date', async () => {
+    const graphqlClient = makeGraphqlClient({ data: { account: { byId: account } } });
+
+    await AccountQuery.getFreeTierBuildUsageAsync(graphqlClient, 'account-id', currentDate);
+
+    const [document, variables, context] = graphqlClient.query.mock.calls[0];
+    const printed = print(document);
+    expect(printed).toContain('query AccountFreeTierBuildUsage');
+    expect(printed).toContain('byId(accountId: $accountId)');
+    expect(printed).toContain('billingPeriod(date: $currentDate)');
+    expect(printed).toContain('EAS_BUILD: byBillingPeriod(date: $currentDate, service: BUILDS)');
+    expect(printed).toContain('platformBreakdown');
+    expect(printed).not.toContain('overageMetrics');
+    expect(variables).toEqual({
+      accountId: 'account-id',
+      currentDate: '2026-10-26T12:00:00.000Z',
+    });
+    expect(context).toEqual({
+      additionalTypenames: [
+        'Account',
+        'AccountUsageMetrics',
+        'UsageMetricTotal',
+        'BillingPeriod',
+        'EstimatedUsage',
+      ],
+      noRetry: true,
+    });
+  });
+
+  it('rejects on a GraphQL error', async () => {
+    const error = new CombinedError({ networkError: new Error('offline') });
+    const graphqlClient = makeGraphqlClient({ error });
+
+    await expect(
+      AccountQuery.getFreeTierBuildUsageAsync(graphqlClient, 'account-id', currentDate)
+    ).rejects.toBe(error);
+  });
+});
@@ -0,0 +1,55 @@
+import { CombinedError } from '@urql/core';
+import { print } from 'graphql';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { UserPreferenceQuery } from '../UserPreferenceQuery';
+
+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('UserPreferenceQuery.getValueAsync', () => {
+  it('returns the stored value', async () => {
+    const graphqlClient = makeGraphqlClient({
+      data: {
+        userPreference: {
+          get: { id: 'preference-id', key: 'some-key', value: { billingPeriodId: 'period-1' } },
+        },
+      },
+    });
+
+    await expect(UserPreferenceQuery.getValueAsync(graphqlClient, 'some-key')).resolves.toEqual({
+      billingPeriodId: 'period-1',
+    });
+  });
+
+  it('returns null when the key is not set', async () => {
+    const graphqlClient = makeGraphqlClient({ data: { userPreference: { get: null } } });
+
+    await expect(UserPreferenceQuery.getValueAsync(graphqlClient, 'some-key')).resolves.toBeNull();
+  });
+
+  it('queries the preference by key', async () => {
+    const graphqlClient = makeGraphqlClient({ data: { userPreference: { get: null } } });
+
+    await UserPreferenceQuery.getValueAsync(graphqlClient, 'some-key');
+
+    const [document, variables, context] = graphqlClient.query.mock.calls[0];
+    const printed = print(document);
+    expect(printed).toContain('query UserPreferenceByKey');
+    expect(printed).toContain('get(key: $key)');
+    expect(variables).toEqual({ key: 'some-key' });
+    expect(context).toEqual({ additionalTypenames: ['UserPreference'], noRetry: true });
+  });
+
+  it('rejects on a GraphQL error', async () => {
+    const error = new CombinedError({ networkError: new Error('offline') });
+    const graphqlClient = makeGraphqlClient({ error });
+
+    await expect(UserPreferenceQuery.getValueAsync(graphqlClient, 'some-key')).rejects.toBe(error);
+  });
+});
@@ -170,3 +170,56 @@ export const AppObserveAppVersionFragmentNode = gql`
    }
  }
 `;
+
+export const AppObserveSpanFragmentNode = gql`
+  fragment AppObserveSpanFragment on AppObserveSpan {
+    id
+    traceId
+    spanId
+    parentSpanId
+    name
+    kind
+    startTimestamp
+    endTimestamp
+    durationMs
+    statusCode
+    statusMessage
+    sessionId
+    http {
+      method
+      statusCode
+      urlHost
+      urlFull
+      protocolVersion
+      requestSize
+      responseSize
+      errorType
+    }
+    attributes {
+      key
+      value
+      type
+    }
+    events {
+      name
+      timestamp
+      attributes
+    }
+    droppedAttributesCount
+    droppedEventsCount
+    droppedLinksCount
+    ingestedAt
+    appVersion
+    appBuildNumber
+    appUpdateId
+    appEasBuildId
+    expoSdkVersion
+    reactNativeVersion
+    deviceOs
+    deviceOsVersion
+    deviceModel
+    environment
+    easClientId
+    countryCode
+  }
+`;
@@ -4,6 +4,10 @@ import {
  AppObserveMetric,
  AppObserveMetricsListOrderByField,
  AppObserveOrderDirection,
+  AppObserveSpan,
+  AppObserveSpanKind,
+  AppObserveSpanListOrderByField,
+  AppObserveSpanStatusCode,
  AppObserveUserEvent,
  AppObserveUserEventListOrderByField,
 } from '../../graphql/generated';
@@ -106,6 +110,54 @@ function makeErrorLog(overrides: Partial<AppObserveError> = {}): AppObserveSessi
  } as AppObserveSessionLog;
 }

+function makeSpan(overrides: Partial<AppObserveSpan> = {}): AppObserveSpan {
+  return {
+    __typename: 'AppObserveSpan' as const,
+    id: 'span-1',
+    traceId: 'a'.repeat(32),
+    spanId: '1'.repeat(16),
+    parentSpanId: null,
+    name: 'GET',
+    kind: AppObserveSpanKind.Client,
+    startTimestamp: '2025-01-15T10:00:01.000Z',
+    endTimestamp: '2025-01-15T10:00:01.123Z',
+    durationMs: 123.4,
+    statusCode: AppObserveSpanStatusCode.Ok,
+    statusMessage: null,
+    sessionId: 'session-1',
+    http: {
+      __typename: 'AppObserveSpanHttp' as const,
+      method: 'GET',
+      statusCode: 200,
+      urlHost: 'api.example.com',
+      urlFull: 'https://api.example.com/users?page=1',
+      protocolVersion: '1.1',
+      requestSize: 100,
+      responseSize: 2000,
+      errorType: null,
+    },
+    attributes: [],
+    events: [],
+    droppedAttributesCount: 0,
+    droppedEventsCount: 0,
+    droppedLinksCount: 0,
+    ingestedAt: null,
+    appVersion: '1.0.0',
+    appBuildNumber: '42',
+    appUpdateId: null,
+    appEasBuildId: null,
+    expoSdkVersion: '54.0.0',
+    reactNativeVersion: '0.81.0',
+    deviceModel: 'iPhone 15',
+    deviceOs: 'iOS',
+    deviceOsVersion: '17.0',
+    environment: 'production',
+    easClientId: 'client-1',
+    countryCode: 'US',
+    ...overrides,
+  } as AppObserveSpan;
+}
+
 const baseOptions = {
  limit: 100,
 };
@@ -118,6 +170,8 @@ describe('fetchObserveSessionEventsAsync', () => {
      logs: [],
      metricsPageInfo: noNextPage,
      logsPageInfo: noNextPage,
+      spans: [],
+      spansPageInfo: noNextPage,
    });
  });

@@ -154,6 +208,8 @@ describe('fetchObserveSessionEventsAsync', () => {
      ],
      metricsPageInfo: noNextPage,
      logsPageInfo: noNextPage,
+      spans: [],
+      spansPageInfo: noNextPage,
    });

    const result = await fetchObserveSessionEventsAsync({} as any, 'project-1', {
@@ -180,6 +236,8 @@ describe('fetchObserveSessionEventsAsync', () => {
      ],
      metricsPageInfo: noNextPage,
      logsPageInfo: noNextPage,
+      spans: [],
+      spansPageInfo: noNextPage,
    });

    const result = await fetchObserveSessionEventsAsync({} as any, 'project-1', {
@@ -202,6 +260,8 @@ describe('fetchObserveSessionEventsAsync', () => {
      logs: [makeUserLog({ timestamp: '2025-01-15T10:05:00.000Z', appUpdateId: 'update-xyz' })],
      metricsPageInfo: noNextPage,
      logsPageInfo: noNextPage,
+      spans: [],
+      spansPageInfo: noNextPage,
    });

    const result = await fetchObserveSessionEventsAsync({} as any, 'project-1', {
@@ -236,6 +296,8 @@ describe('fetchObserveSessionEventsAsync', () => {
      logs: [],
      metricsPageInfo: { hasNextPage: true, hasPreviousPage: false, endCursor: 'cm' },
      logsPageInfo: noNextPage,
+      spans: [],
+      spansPageInfo: noNextPage,
    });

    const result = await fetchObserveSessionEventsAsync({} as any, 'project-1', {
@@ -245,6 +307,52 @@ describe('fetchObserveSessionEventsAsync', () => {

    expect(result.hasMoreMetricEvents).toBe(true);
    expect(result.hasMoreLogEvents).toBe(false);
+    expect(result.hasMoreSpans).toBe(false);
+  });
+
+  it('queries the session spans oldest-first and merges them into the timeline', async () => {
+    mockSessionEventsAsync.mockResolvedValue({
+      metrics: [makeMetricEvent({ timestamp: '2025-01-15T10:00:00.000Z' })],
+      logs: [makeUserLog({ timestamp: '2025-01-15T10:00:02.000Z' })],
+      spans: [makeSpan({ startTimestamp: '2025-01-15T10:00:01.000Z' })],
+      metricsPageInfo: noNextPage,
+      logsPageInfo: noNextPage,
+      spansPageInfo: { hasNextPage: true, hasPreviousPage: false, endCursor: 'cs' },
+    });
+
+    const result = await fetchObserveSessionEventsAsync({} as any, 'project-1', {
+      ...baseOptions,
+      sessionId: 'session-1',
+    });
+
+    expect(mockSessionEventsAsync).toHaveBeenCalledWith(
+      {},
+      expect.objectContaining({
+        spansOrderBy: {
+          field: AppObserveSpanListOrderByField.StartTimestamp,
+          direction: AppObserveOrderDirection.Asc,
+        },
+      })
+    );
+    expect(result.entries.map(e => e.source)).toEqual(['metric', 'span', 'log']);
+    const spanEntry = result.entries[1];
+    expect(spanEntry).toEqual(
+      expect.objectContaining({
+        id: 'span-1',
+        name: 'GET',
+        timestamp: '2025-01-15T10:00:01.000Z',
+        traceId: 'a'.repeat(32),
+        spanId: '1'.repeat(16),
+        parentSpanId: null,
+        durationMs: 123.4,
+        statusCode: AppObserveSpanStatusCode.Ok,
+        httpMethod: 'GET',
+        httpStatusCode: 200,
+        urlHost: 'api.example.com',
+        urlFull: 'https://api.example.com/users?page=1',
+      })
+    );
+    expect(result.hasMoreSpans).toBe(true);
  });
 });

@@ -0,0 +1,130 @@
+import {
+  AppObserveOrderDirection,
+  AppObservePlatform,
+  AppObserveSpanKind,
+  AppObserveSpanListOrderByField,
+  AppObserveSpanStatusCode,
+} from '../../graphql/generated';
+import { ObserveQuery } from '../../graphql/queries/ObserveQuery';
+import { fetchObserveSpansAsync } from '../fetchSpans';
+
+jest.mock('../../graphql/queries/ObserveQuery');
+
+describe(fetchObserveSpansAsync, () => {
+  const mockSpanListAsync = jest.mocked(ObserveQuery.spanListAsync);
+  const mockGraphqlClient = {} as any;
+
+  beforeEach(() => {
+    mockSpanListAsync.mockClear();
+    mockSpanListAsync.mockResolvedValue({
+      spans: [],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
+    });
+  });
+
+  it('passes appId, time range, and limit to spanListAsync', async () => {
+    await fetchObserveSpansAsync(mockGraphqlClient, 'project-123', {
+      limit: 25,
+      startTime: '2025-01-01T00:00:00.000Z',
+      endTime: '2025-03-01T00:00:00.000Z',
+    });
+
+    expect(mockSpanListAsync).toHaveBeenCalledTimes(1);
+    const callArgs = mockSpanListAsync.mock.calls[0][1];
+    expect(callArgs.appId).toBe('project-123');
+    expect(callArgs.first).toBe(25);
+    expect(callArgs.after).toBeUndefined();
+    expect(callArgs.filter).toEqual({
+      startTime: '2025-01-01T00:00:00.000Z',
+      endTime: '2025-03-01T00:00:00.000Z',
+    });
+  });
+
+  it('always asks for spans newest first', async () => {
+    await fetchObserveSpansAsync(mockGraphqlClient, 'project-123', {
+      limit: 25,
+      startTime: '2025-01-01T00:00:00.000Z',
+      endTime: '2025-03-01T00:00:00.000Z',
+    });
+
+    expect(mockSpanListAsync.mock.calls[0][1].orderBy).toEqual({
+      field: AppObserveSpanListOrderByField.StartTimestamp,
+      direction: AppObserveOrderDirection.Desc,
+    });
+  });
+
+  it('maps every option to its filter key', async () => {
+    await fetchObserveSpansAsync(mockGraphqlClient, 'project-123', {
+      limit: 10,
+      after: 'cursor-1',
+      startTime: '2025-01-01T00:00:00.000Z',
+      endTime: '2025-03-01T00:00:00.000Z',
+      platforms: [AppObservePlatform.Ios],
+      appVersion: '1.2.0',
+      buildNumber: '42',
+      updateId: 'update-1',
+      environment: 'production',
+      sessionId: 'session-1',
+      names: ['GET', 'POST'],
+      kinds: [AppObserveSpanKind.Client],
+      statusCodes: [AppObserveSpanStatusCode.Error],
+      hosts: ['api.example.com'],
+      httpStatusCodes: [500, 502],
+      minDurationMs: 250,
+      rootOnly: true,
+    });
+
+    const callArgs = mockSpanListAsync.mock.calls[0][1];
+    expect(callArgs.after).toBe('cursor-1');
+    expect(callArgs.filter).toEqual({
+      startTime: '2025-01-01T00:00:00.000Z',
+      endTime: '2025-03-01T00:00:00.000Z',
+      platforms: [AppObservePlatform.Ios],
+      appVersion: '1.2.0',
+      appBuildNumber: '42',
+      appUpdateId: 'update-1',
+      environment: 'production',
+      sessionId: 'session-1',
+      names: ['GET', 'POST'],
+      kinds: [AppObserveSpanKind.Client],
+      statusCodes: [AppObserveSpanStatusCode.Error],
+      hosts: ['api.example.com'],
+      httpStatusCodes: [500, 502],
+      minDurationMs: 250,
+      rootOnly: true,
+    });
+  });
+
+  it('sends a zero minimum duration and omits rootOnly when false', async () => {
+    await fetchObserveSpansAsync(mockGraphqlClient, 'project-123', {
+      limit: 10,
+      startTime: '2025-01-01T00:00:00.000Z',
+      endTime: '2025-03-01T00:00:00.000Z',
+      minDurationMs: 0,
+      rootOnly: false,
+      names: [],
+    });
+
+    const filter = mockSpanListAsync.mock.calls[0][1].filter;
+    expect(filter.minDurationMs).toBe(0);
+    expect(filter).not.toHaveProperty('rootOnly');
+    expect(filter).not.toHaveProperty('names');
+  });
+
+  it('returns the spans and pageInfo from the query', async () => {
+    const span = { id: 'span-1' } as any;
+    mockSpanListAsync.mockResolvedValue({
+      spans: [span],
+      pageInfo: { hasNextPage: true, hasPreviousPage: false, endCursor: 'c' },
+    });
+
+    const result = await fetchObserveSpansAsync(mockGraphqlClient, 'project-123', {
+      limit: 10,
+      startTime: '2025-01-01T00:00:00.000Z',
+      endTime: '2025-03-01T00:00:00.000Z',
+    });
+
+    expect(result.spans).toEqual([span]);
+    expect(result.pageInfo.endCursor).toBe('c');
+  });
+});
@@ -52,7 +52,71 @@ function makeLogEntry(overrides: Partial<SessionEventEntry> = {}): SessionEventE
  };
 }

+function makeSpanEntry(overrides: Partial<SessionEventEntry> = {}): SessionEventEntry {
+  return {
+    source: 'span',
+    id: 'span-1',
+    timestamp: '2025-01-15T10:00:01.000Z',
+    sessionId: 'session-1',
+    appVersion: '1.0.0',
+    appBuildNumber: '42',
+    appUpdateId: null,
+    deviceModel: 'iPhone 15',
+    deviceOs: 'iOS',
+    deviceOsVersion: '17.0',
+    countryCode: 'US',
+    easClientId: 'client-1',
+    name: 'GET',
+    environment: 'production',
+    traceId: 'a'.repeat(32),
+    spanId: '1'.repeat(16),
+    parentSpanId: null,
+    durationMs: 123.4,
+    statusCode: 'OK',
+    httpMethod: 'GET',
+    httpStatusCode: 200,
+    httpErrorType: null,
+    urlHost: 'api.example.com',
+    urlFull: 'https://api.example.com/users?page=1',
+    ...overrides,
+  };
+}
+
 describe(buildObserveSessionEventsTable, () => {
+  it('renders a span row with its method, host and path, duration, and status', () => {
+    const output = buildObserveSessionEventsTable([makeMetricEntry(), makeSpanEntry()]);
+    const spanLine = output.split('\n').find(line => line.includes('span'));
+    expect(spanLine).toContain('1.00s');
+    expect(spanLine).toContain('GET api.example.com/users?page=1');
+    expect(spanLine).toContain('123ms');
+    expect(spanLine).toContain('status=OK http=200');
+  });
+
+  it('shows the client error type for a span whose request got no response', () => {
+    const output = buildObserveSessionEventsTable([
+      makeSpanEntry({
+        statusCode: 'ERROR',
+        httpStatusCode: null,
+        httpErrorType: 'NSURLErrorTimedOut',
+      }),
+    ]);
+    expect(output).toContain('status=ERROR error=NSURLErrorTimedOut');
+  });
+
+  it('strips control characters from a span row name', () => {
+    const output = buildObserveSessionEventsTable([
+      makeSpanEntry({ name: 'GET\u001b[2J', urlHost: 'api.example.com\u0007', urlFull: null }),
+    ]);
+    expect(output).not.toContain('\u001b[2J');
+    expect(output).not.toContain('\u0007');
+    expect(output).toContain('GET[2J api.example.com');
+  });
+
+  it('names spans in the "more available" note', () => {
+    const output = buildObserveSessionEventsTable([makeSpanEntry()], { hasMoreSpans: true });
+    expect(output).toContain('More spans are available for this session');
+  });
+
  it('renders a chronological table with display name for metric rows and event name for log rows', () => {
    const entries: SessionEventEntry[] = [
      makeMetricEntry(),
@@ -234,19 +298,20 @@ describe(buildObserveSessionEventsJson, () => {
      firstSeenAt: '2025-01-15T10:00:00.000Z',
      lastSeenAt: '2025-01-15T10:05:00.000Z',
    };
-    const result = buildObserveSessionEventsJson(entries, 'session-1', metadata, false, true);
+    const result = buildObserveSessionEventsJson(entries, 'session-1', metadata, false, true, true);
    expect(result).toEqual({
      sessionId: 'session-1',
      metadata,
      entries,
      hasMoreMetricEvents: false,
      hasMoreLogEvents: true,
+      hasMoreSpans: true,
    });
    expect(result.entries[0].id).toBe('evt-m-1');
  });

  it('returns null metadata when there were no entries', () => {
-    const result = buildObserveSessionEventsJson([], 'session-1', null, false, false);
+    const result = buildObserveSessionEventsJson([], 'session-1', null, false, false, false);
    expect(result.metadata).toBeNull();
  });
 });
@@ -0,0 +1,377 @@
+import {
+  AppObserveSpan,
+  AppObserveSpanKind,
+  AppObserveSpanName,
+  AppObserveSpanStatusCode,
+  AppObserveTrace,
+  PageInfo,
+} from '../../graphql/generated';
+import {
+  buildObserveSpanJson,
+  buildObserveSpanNamesJson,
+  buildObserveSpanNamesTable,
+  buildObserveSpansJson,
+  buildObserveSpansTable,
+  buildObserveTraceJson,
+  buildObserveTraceTable,
+  formatSpanDuration,
+  formatSpanHttpStatus,
+  formatSpanTitle,
+  formatSpanUrlPath,
+  orderTraceSpans,
+} from '../formatSpans';
+
+const TRACE_ID = 'a'.repeat(32);
+
+function makeSpan(overrides: Partial<AppObserveSpan> = {}): AppObserveSpan {
+  return {
+    __typename: 'AppObserveSpan' as const,
+    id: 'span-1',
+    traceId: TRACE_ID,
+    spanId: '1'.repeat(16),
+    parentSpanId: null,
+    name: 'GET',
+    kind: AppObserveSpanKind.Client,
+    startTimestamp: '2025-01-15T10:00:00.000Z',
+    endTimestamp: '2025-01-15T10:00:00.123Z',
+    durationMs: 123.4,
+    statusCode: AppObserveSpanStatusCode.Ok,
+    statusMessage: null,
+    sessionId: 'session-1',
+    http: {
+      __typename: 'AppObserveSpanHttp' as const,
+      method: 'GET',
+      statusCode: 200,
+      urlHost: 'api.example.com',
+      urlFull: 'https://api.example.com/users?page=1',
+      protocolVersion: '1.1',
+      requestSize: 100,
+      responseSize: 2000,
+      errorType: null,
+    },
+    attributes: [{ key: 'expo.http.resource.fetch_type', value: 'network', type: 'STRING' }],
+    events: [{ name: 'exception', timestamp: '2025-01-15T10:00:00.100Z', attributes: { a: 1 } }],
+    droppedAttributesCount: 0,
+    droppedEventsCount: 0,
+    droppedLinksCount: 1,
+    ingestedAt: '2025-01-15T10:00:05.000Z',
+    appVersion: '1.0.0',
+    appBuildNumber: '42',
+    appUpdateId: null,
+    appEasBuildId: null,
+    expoSdkVersion: '54.0.0',
+    reactNativeVersion: '0.81.0',
+    deviceModel: 'iPhone 15',
+    deviceOs: 'iOS',
+    deviceOsVersion: '17.0',
+    environment: 'production',
+    easClientId: 'client-1',
+    countryCode: 'US',
+    ...overrides,
+  } as AppObserveSpan;
+}
+
+function makeSpanName(name: string, kind: AppObserveSpanKind, count: number): AppObserveSpanName {
+  return { __typename: 'AppObserveSpanName' as const, name, kind, count };
+}
+
+const noNextPage: PageInfo = { hasNextPage: false, hasPreviousPage: false };
+const withNextPage: PageInfo = {
+  hasNextPage: true,
+  hasPreviousPage: false,
+  endCursor: 'cursor-abc',
+};
+
+describe(formatSpanDuration, () => {
+  it('shows milliseconds under a second and seconds above', () => {
+    expect(formatSpanDuration(0.4)).toBe('0ms');
+    expect(formatSpanDuration(123.4)).toBe('123ms');
+    expect(formatSpanDuration(999.6)).toBe('1.00s');
+    expect(formatSpanDuration(1234)).toBe('1.23s');
+  });
+});
+
+describe(formatSpanHttpStatus, () => {
+  it('prefers the status code, then the error type, then a dash', () => {
+    expect(formatSpanHttpStatus(makeSpan())).toBe('200');
+    expect(
+      formatSpanHttpStatus(
+        makeSpan({ http: { statusCode: null, errorType: 'NSURLErrorTimedOut' } as any })
+      )
+    ).toBe('NSURLErrorTimedOut');
+    expect(formatSpanHttpStatus(makeSpan({ http: null }))).toBe('-');
+  });
+});
+
+describe(formatSpanUrlPath, () => {
+  it('keeps the path and query of a URL and returns unparsable input as is', () => {
+    expect(formatSpanUrlPath('https://api.example.com/users?page=1')).toBe('/users?page=1');
+    expect(formatSpanUrlPath('not a url')).toBe('not a url');
+  });
+});
+
+describe(formatSpanTitle, () => {
+  it('joins the span name, host, and path for a request span', () => {
+    expect(formatSpanTitle(makeSpan())).toBe('GET api.example.com/users?page=1');
+  });
+
+  it('falls back to the span name for a non-HTTP span', () => {
+    expect(formatSpanTitle(makeSpan({ name: 'render', http: null }))).toBe('render');
+  });
+});
+
+describe(buildObserveSpanNamesTable, () => {
+  it('lists names with kind and count and a hint to list spans', () => {
+    const output = buildObserveSpanNamesTable(
+      [
+        makeSpanName('GET', AppObserveSpanKind.Client, 1234),
+        makeSpanName('POST', AppObserveSpanKind.Client, 5),
+      ],
+      { daysBack: 7 }
+    );
+    expect(output).toContain('Span names for the last 7 days');
+    expect(output).toContain('GET');
+    expect(output).toContain('CLIENT');
+    expect(output).toContain((1234).toLocaleString());
+    expect(output).toContain('--all-spans');
+    expect(output).not.toContain('truncated');
+  });
+
+  it('strips control characters from span names', () => {
+    const output = buildObserveSpanNamesTable([
+      makeSpanName('GET\u001b[2J', AppObserveSpanKind.Client, 1),
+    ]);
+    expect(output).not.toContain('\u001b[2J');
+    expect(output).toContain('GET');
+  });
+
+  it('notes truncation', () => {
+    const output = buildObserveSpanNamesTable([makeSpanName('GET', AppObserveSpanKind.Client, 1)], {
+      isTruncated: true,
+    });
+    expect(output).toContain('truncated');
+  });
+
+  it('reports no spans', () => {
+    expect(buildObserveSpanNamesTable([])).toContain('No spans found.');
+  });
+});
+
+describe(buildObserveSpanNamesJson, () => {
+  it('maps names and the truncation flag', () => {
+    expect(
+      buildObserveSpanNamesJson([makeSpanName('GET', AppObserveSpanKind.Client, 3)], true)
+    ).toEqual({ names: [{ name: 'GET', kind: 'CLIENT', count: 3 }], isTruncated: true });
+  });
+});
+
+describe(buildObserveSpansTable, () => {
+  it('renders one row per span with duration, status, HTTP status, host, and trace id', () => {
+    const output = buildObserveSpansTable([makeSpan()], noNextPage, { daysBack: 7 });
+    expect(output).toContain('Spans for the last 7 days');
+    const row = output.split('\n').find(line => line.includes(TRACE_ID));
+    expect(row).toContain('GET');
+    expect(row).toContain('123ms');
+    expect(row).toContain('OK');
+    expect(row).toContain('200');
+    expect(row).toContain('api.example.com');
+    expect(row).toContain('1.0.0 (42)');
+    expect(row).toContain('iOS 17.0');
+    expect(output).toContain('eas observe:trace <Trace ID>');
+    expect(output).not.toContain('Next page');
+  });
+
+  it('strips control characters from span names and hosts', () => {
+    const span = makeSpan({
+      name: 'GET\u001b[2J',
+      http: { ...makeSpan().http!, urlHost: 'api.example.com\u0007' },
+    });
+    const output = buildObserveSpansTable([span], noNextPage);
+    expect(output).not.toContain('\u001b[2J');
+    expect(output).not.toContain('\u0007');
+    expect(output).toContain('GET');
+    expect(output).toContain('api.example.com');
+  });
+
+  it('titles the table by session when a session filter is set', () => {
+    const output = buildObserveSpansTable([makeSpan()], noNextPage, {
+      daysBack: 7,
+      sessionId: 'session-1',
+    });
+    expect(output).toContain('Spans in session session-1');
+    expect(output).not.toContain('for the last');
+  });
+
+  it('appends the next page hint when hasNextPage is true', () => {
+    const output = buildObserveSpansTable([makeSpan()], withNextPage);
+    expect(output).toContain('Next page: --after cursor-abc');
+  });
+
+  it('reports no spans', () => {
+    expect(buildObserveSpansTable([], noNextPage)).toContain('No spans found.');
+  });
+});
+
+describe(buildObserveSpanJson, () => {
+  it('maps every field and nulls missing optionals', () => {
+    const json = buildObserveSpanJson(makeSpan());
+    expect(json).toEqual({
+      id: 'span-1',
+      traceId: TRACE_ID,
+      spanId: '1'.repeat(16),
+      parentSpanId: null,
+      name: 'GET',
+      kind: 'CLIENT',
+      startTimestamp: '2025-01-15T10:00:00.000Z',
+      endTimestamp: '2025-01-15T10:00:00.123Z',
+      durationMs: 123.4,
+      statusCode: 'OK',
+      statusMessage: null,
+      sessionId: 'session-1',
+      http: {
+        method: 'GET',
+        statusCode: 200,
+        urlHost: 'api.example.com',
+        urlFull: 'https://api.example.com/users?page=1',
+        protocolVersion: '1.1',
+        requestSize: 100,
+        responseSize: 2000,
+        errorType: null,
+      },
+      attributes: [{ key: 'expo.http.resource.fetch_type', value: 'network', type: 'STRING' }],
+      events: [{ name: 'exception', timestamp: '2025-01-15T10:00:00.100Z', attributes: { a: 1 } }],
+      droppedAttributesCount: 0,
+      droppedEventsCount: 0,
+      droppedLinksCount: 1,
+      ingestedAt: '2025-01-15T10:00:05.000Z',
+      appVersion: '1.0.0',
+      appBuildNumber: '42',
+      appUpdateId: null,
+      appEasBuildId: null,
+      expoSdkVersion: '54.0.0',
+      reactNativeVersion: '0.81.0',
+      deviceModel: 'iPhone 15',
+      deviceOs: 'iOS',
+      deviceOsVersion: '17.0',
+      environment: 'production',
+      easClientId: 'client-1',
+      countryCode: 'US',
+    });
+    expect(buildObserveSpanJson(makeSpan({ http: null })).http).toBeNull();
+  });
+});
+
+describe(buildObserveSpansJson, () => {
+  it('wraps spans with pageInfo', () => {
+    const json = buildObserveSpansJson([makeSpan()], withNextPage);
+    expect(json.spans).toHaveLength(1);
+    expect(json.pageInfo).toEqual({ hasNextPage: true, endCursor: 'cursor-abc' });
+  });
+});
+
+function makeTrace(spans: AppObserveSpan[], isTruncated = false): AppObserveTrace {
+  return { __typename: 'AppObserveTrace' as const, id: TRACE_ID, spans, isTruncated };
+}
+
+const root = makeSpan({
+  id: 'root',
+  spanId: 'r'.repeat(16),
+  startTimestamp: '2025-01-15T10:00:00.000Z',
+});
+const childLater = makeSpan({
+  id: 'child-later',
+  spanId: 'b'.repeat(16),
+  parentSpanId: 'r'.repeat(16),
+  name: 'POST',
+  startTimestamp: '2025-01-15T10:00:00.500Z',
+  durationMs: 50,
+});
+const childEarlier = makeSpan({
+  id: 'child-earlier',
+  spanId: 'c'.repeat(16),
+  parentSpanId: 'r'.repeat(16),
+  startTimestamp: '2025-01-15T10:00:00.200Z',
+  durationMs: 2500,
+});
+const grandchild = makeSpan({
+  id: 'grandchild',
+  spanId: 'd'.repeat(16),
+  parentSpanId: 'c'.repeat(16),
+  startTimestamp: '2025-01-15T10:00:00.300Z',
+});
+const orphan = makeSpan({
+  id: 'orphan',
+  spanId: 'e'.repeat(16),
+  parentSpanId: 'f'.repeat(16),
+  startTimestamp: '2025-01-15T10:00:00.100Z',
+});
+
+describe(orderTraceSpans, () => {
+  it('walks children under their parent, siblings oldest first, orphans as roots', () => {
+    const rows = orderTraceSpans([childLater, grandchild, orphan, childEarlier, root]);
+    expect(rows.map(r => [r.span.id, r.depth])).toEqual([
+      ['root', 0],
+      ['child-earlier', 1],
+      ['grandchild', 2],
+      ['child-later', 1],
+      ['orphan', 0],
+    ]);
+  });
+});
+
+describe(buildObserveTraceTable, () => {
+  it('renders a header, indented rows with offsets, and a session hint', () => {
+    const output = buildObserveTraceTable(makeTrace([childLater, childEarlier, root]));
+    expect(output).toContain(`Trace ${TRACE_ID}`);
+    expect(output).toContain('Spans:       3');
+    expect(output).toContain('Session:     session-1');
+    expect(output).toContain('eas observe:session session-1');
+
+    const lines = output.split('\n');
+    const rootLine = lines.find(
+      line => line.includes('https://api.example.com') && line.includes('0ms')
+    );
+    expect(rootLine).toBeDefined();
+    const indentedLines = lines.filter(
+      line => /\s{2}GET|\s{2}POST/.test(line) && line.includes('ms')
+    );
+    expect(indentedLines.length).toBeGreaterThanOrEqual(1);
+    expect(output).toContain('200ms');
+    expect(output).toContain('500ms');
+    expect(output).toContain('2.50s');
+    expect(output).not.toContain('more spans');
+  });
+
+  it('strips control characters from the device, span names, and URLs', () => {
+    const span = makeSpan({
+      name: 'GET\u001b[2J',
+      deviceModel: 'iPhone\u0007 15',
+      http: { ...makeSpan().http!, urlFull: 'https://api.example.com/\u001b[Husers' },
+    });
+    const output = buildObserveTraceTable(makeTrace([span]));
+    expect(output).not.toContain('\u001b[2J');
+    expect(output).not.toContain('\u001b[H');
+    expect(output).not.toContain('\u0007');
+    expect(output).toContain('Device:      iPhone 15');
+    expect(output).toContain('https://api.example.com/[Husers');
+  });
+
+  it('notes truncation', () => {
+    const output = buildObserveTraceTable(makeTrace([root], true));
+    expect(output).toContain('Spans:       1 (truncated)');
+    expect(output).toContain('more spans');
+  });
+
+  it('handles a trace without spans', () => {
+    expect(buildObserveTraceTable(makeTrace([]))).toContain('No spans found for this trace.');
+  });
+});
+
+describe(buildObserveTraceJson, () => {
+  it('keeps the tree order and the truncation flag', () => {
+    const json = buildObserveTraceJson(makeTrace([childLater, childEarlier, root], true));
+    expect(json.id).toBe(TRACE_ID);
+    expect(json.isTruncated).toBe(true);
+    expect(json.spans.map(s => s.id)).toEqual(['root', 'child-earlier', 'child-later']);
+  });
+});
@@ -0,0 +1,42 @@
+import { AppObserveSpanKind, AppObserveSpanStatusCode } from '../../graphql/generated';
+import {
+  allowedSpanKindFlagValues,
+  allowedSpanStatusFlagValues,
+  spanKindsFromFlag,
+  spanStatusCodesFromFlag,
+} from '../spanFilters';
+
+describe('span filter flags', () => {
+  it('offers the lowercase enum values as flag options', () => {
+    expect(allowedSpanKindFlagValues).toEqual(
+      expect.arrayContaining([
+        'client',
+        'server',
+        'internal',
+        'producer',
+        'consumer',
+        'unspecified',
+      ])
+    );
+    expect(allowedSpanStatusFlagValues).toEqual(['error', 'ok', 'unset']);
+  });
+
+  it('maps flag values back to the enums', () => {
+    expect(spanKindsFromFlag(['client', 'server'])).toEqual([
+      AppObserveSpanKind.Client,
+      AppObserveSpanKind.Server,
+    ]);
+    expect(spanStatusCodesFromFlag(['error'])).toEqual([AppObserveSpanStatusCode.Error]);
+  });
+
+  it('returns undefined for no values', () => {
+    expect(spanKindsFromFlag(undefined)).toBeUndefined();
+    expect(spanKindsFromFlag([])).toBeUndefined();
+    expect(spanStatusCodesFromFlag(undefined)).toBeUndefined();
+  });
+
+  it('rejects unknown values', () => {
+    expect(() => spanKindsFromFlag(['bogus'])).toThrow(/Unknown span kind/);
+    expect(() => spanStatusCodesFromFlag(['bogus'])).toThrow(/Unknown span status/);
+  });
+});
@@ -5,6 +5,8 @@ import {
  AppObserveMetric,
  AppObserveMetricsListOrderByField,
  AppObserveOrderDirection,
+  AppObserveSpan,
+  AppObserveSpanListOrderByField,
  AppObserveUserEvent,
  AppObserveUserEventListOrderByField,
 } from '../graphql/generated';
@@ -13,7 +15,7 @@ import { fetchObserveCustomEventsAsync } from './fetchCustomEvents';
 import { fetchObserveEventsAsync, resolveOrderBy } from './fetchEvents';

 export interface SessionEventEntry {
-  source: 'metric' | 'log';
+  source: 'metric' | 'log' | 'span';
  id: string;
  timestamp: string;
  sessionId: string;
@@ -36,6 +38,17 @@ export interface SessionEventEntry {
  severityNumber?: number | null;
  properties?: Array<{ key: string; value: string; type: string }>;
  environment?: string | null;
+  // span-only fields
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string | null;
+  durationMs?: number;
+  statusCode?: string;
+  httpMethod?: string | null;
+  httpStatusCode?: number | null;
+  httpErrorType?: string | null;
+  urlHost?: string | null;
+  urlFull?: string | null;
 }

 function metricEventToEntry(event: AppObserveMetric): SessionEventEntry {
@@ -107,6 +120,35 @@ function errorToEntry(event: AppObserveError): SessionEventEntry {
  };
 }

+function spanToEntry(span: AppObserveSpan): SessionEventEntry {
+  return {
+    source: 'span',
+    id: span.id,
+    timestamp: span.startTimestamp,
+    sessionId: span.sessionId ?? '',
+    name: span.name,
+    appVersion: span.appVersion,
+    appBuildNumber: span.appBuildNumber,
+    appUpdateId: span.appUpdateId ?? null,
+    deviceModel: span.deviceModel,
+    deviceOs: span.deviceOs,
+    deviceOsVersion: span.deviceOsVersion,
+    countryCode: span.countryCode ?? null,
+    easClientId: span.easClientId,
+    environment: span.environment ?? null,
+    traceId: span.traceId,
+    spanId: span.spanId,
+    parentSpanId: span.parentSpanId ?? null,
+    durationMs: span.durationMs,
+    statusCode: span.statusCode,
+    httpMethod: span.http?.method ?? null,
+    httpStatusCode: span.http?.statusCode ?? null,
+    httpErrorType: span.http?.errorType ?? null,
+    urlHost: span.http?.urlHost ?? null,
+    urlFull: span.http?.urlFull ?? null,
+  };
+}
+
 function sessionLogToEntry(log: AppObserveSessionLog): SessionEventEntry {
  return log.__typename === 'AppObserveError' ? errorToEntry(log) : userEventToEntry(log);
 }
@@ -133,6 +175,7 @@ export interface FetchSessionEventsResult {
  metadata: SessionMetadata | null;
  hasMoreMetricEvents: boolean;
  hasMoreLogEvents: boolean;
+  hasMoreSpans: boolean;
 }

 // A syntactically valid UUID that matches no real session, used only to trip
@@ -160,9 +203,8 @@ export async function fetchObserveSessionEventsAsync(
  appId: string,
  options: FetchSessionEventsOptions
 ): Promise<FetchSessionEventsResult> {
-  const { metrics, logs, metricsPageInfo, logsPageInfo } = await ObserveQuery.sessionEventsAsync(
-    graphqlClient,
-    {
+  const { metrics, logs, spans, metricsPageInfo, logsPageInfo, spansPageInfo } =
+    await ObserveQuery.sessionEventsAsync(graphqlClient, {
      appId,
      id: options.sessionId,
      first: options.limit,
@@ -174,12 +216,17 @@ export async function fetchObserveSessionEventsAsync(
        field: AppObserveLogsOrderByField.Timestamp,
        direction: AppObserveOrderDirection.Asc,
      },
-    }
-  );
+      spansOrderBy: {
+        field: AppObserveSpanListOrderByField.StartTimestamp,
+        direction: AppObserveOrderDirection.Asc,
+      },
+    });

-  const entries = [...metrics.map(metricEventToEntry), ...logs.map(sessionLogToEntry)].sort(
-    (a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0)
-  );
+  const entries = [
+    ...metrics.map(metricEventToEntry),
+    ...logs.map(sessionLogToEntry),
+    ...spans.map(spanToEntry),
+  ].sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0));

  let metadata: SessionMetadata | null = null;
  if (entries.length > 0) {
@@ -202,6 +249,7 @@ export async function fetchObserveSessionEventsAsync(
    metadata,
    hasMoreMetricEvents: metricsPageInfo.hasNextPage,
    hasMoreLogEvents: logsPageInfo.hasNextPage,
+    hasMoreSpans: spansPageInfo.hasNextPage,
  };
 }

@@ -0,0 +1,75 @@
+import { ExpoGraphqlClient } from '../commandUtils/context/contextUtils/createGraphqlClient';
+import {
+  AppObserveOrderDirection,
+  AppObservePlatform,
+  AppObserveSpan,
+  AppObserveSpanKind,
+  AppObserveSpanListFilter,
+  AppObserveSpanListOrderBy,
+  AppObserveSpanListOrderByField,
+  AppObserveSpanStatusCode,
+  PageInfo,
+} from '../graphql/generated';
+import { ObserveQuery } from '../graphql/queries/ObserveQuery';
+
+export interface FetchSpansOptions {
+  limit: number;
+  after?: string;
+  startTime: string;
+  endTime: string;
+  platforms?: AppObservePlatform[];
+  appVersion?: string;
+  buildNumber?: string;
+  updateId?: string;
+  environment?: string;
+  sessionId?: string;
+  names?: string[];
+  kinds?: AppObserveSpanKind[];
+  statusCodes?: AppObserveSpanStatusCode[];
+  hosts?: string[];
+  httpStatusCodes?: number[];
+  minDurationMs?: number;
+  rootOnly?: boolean;
+}
+
+export const NEWEST_SPANS_FIRST: AppObserveSpanListOrderBy = {
+  field: AppObserveSpanListOrderByField.StartTimestamp,
+  direction: AppObserveOrderDirection.Desc,
+};
+
+export interface FetchSpansResult {
+  spans: AppObserveSpan[];
+  pageInfo: PageInfo;
+}
+
+export async function fetchObserveSpansAsync(
+  graphqlClient: ExpoGraphqlClient,
+  appId: string,
+  options: FetchSpansOptions
+): Promise<FetchSpansResult> {
+  const filter: AppObserveSpanListFilter = {
+    startTime: options.startTime,
+    endTime: options.endTime,
+    ...(options.platforms?.length && { platforms: options.platforms }),
+    ...(options.appVersion && { appVersion: options.appVersion }),
+    ...(options.buildNumber && { appBuildNumber: options.buildNumber }),
+    ...(options.updateId && { appUpdateId: options.updateId }),
+    ...(options.environment && { environment: options.environment }),
+    ...(options.sessionId && { sessionId: options.sessionId }),
+    ...(options.names?.length && { names: options.names }),
+    ...(options.kinds?.length && { kinds: options.kinds }),
+    ...(options.statusCodes?.length && { statusCodes: options.statusCodes }),
+    ...(options.hosts?.length && { hosts: options.hosts }),
+    ...(options.httpStatusCodes?.length && { httpStatusCodes: options.httpStatusCodes }),
+    ...(options.minDurationMs != null && { minDurationMs: options.minDurationMs }),
+    ...(options.rootOnly && { rootOnly: true }),
+  };
+
+  return await ObserveQuery.spanListAsync(graphqlClient, {
+    appId,
+    filter,
+    first: options.limit,
+    orderBy: NEWEST_SPANS_FIRST,
+    ...(options.after && { after: options.after }),
+  });
+}
@@ -2,14 +2,17 @@ import chalk from 'chalk';

 import { AppObserveMetric, AppObserveUserEvent } from '../graphql/generated';
 import { SessionEventEntry, SessionMetadata } from './fetchSessions';
+import { formatSpanDuration, formatSpanUrlPath } from './formatSpans';
 import { formatLogTimestamp } from './formatUtils';
 import { getMetricDisplayName } from './metricNames';
 import renderTextTable from '../utils/renderTextTable';
+import { sanitizeTerminalText } from '../utils/terminalText';

 export interface BuildSessionEventsOptions {
  metadata?: SessionMetadata | null;
  hasMoreMetricEvents?: boolean;
  hasMoreLogEvents?: boolean;
+  hasMoreSpans?: boolean;
 }

 function formatEntryName(entry: SessionEventEntry): string {
@@ -17,9 +20,30 @@ function formatEntryName(entry: SessionEventEntry): string {
    const name = getMetricDisplayName(entry.name);
    return entry.routeName ? `${name} · ${entry.routeName}` : name;
  }
+  if (entry.source === 'span') {
+    if (!entry.urlHost) {
+      return sanitizeTerminalText(entry.name);
+    }
+    const path = entry.urlFull ? formatSpanUrlPath(entry.urlFull) : '';
+    return sanitizeTerminalText(`${entry.name} ${entry.urlHost}${path}`);
+  }
  return entry.name;
 }

+function formatSpanEntryValue(entry: SessionEventEntry): string {
+  return typeof entry.durationMs === 'number' ? formatSpanDuration(entry.durationMs) : '-';
+}
+
+function formatSpanEntryProperties(entry: SessionEventEntry): string {
+  const parts = [`status=${entry.statusCode ?? '-'}`];
+  if (entry.httpStatusCode != null) {
+    parts.push(`http=${entry.httpStatusCode}`);
+  } else if (entry.httpErrorType) {
+    parts.push(`error=${entry.httpErrorType}`);
+  }
+  return parts.join(' ');
+}
+
 function formatMetricEntryValue(entry: SessionEventEntry): string {
  if (typeof entry.value === 'number') {
    return `${entry.value.toFixed(2)}s`;
@@ -81,13 +105,24 @@ export function buildObserveSessionEventsTable(
  const rows: string[][] = [];
  for (const entry of entries) {
    const offset = formatOffsetSeconds(startIso, entry.timestamp);
-    const type = entry.source === 'metric' ? 'metric' : 'log';
+    const type = entry.source;
    const name = formatEntryName(entry);
    const severity = formatEntrySeverity(entry);
    if (entry.source === 'metric') {
      rows.push([offset, type, name, formatMetricEntryValue(entry), '-', severity]);
      continue;
    }
+    if (entry.source === 'span') {
+      rows.push([
+        offset,
+        type,
+        name,
+        formatSpanEntryValue(entry),
+        formatSpanEntryProperties(entry),
+        severity,
+      ]);
+      continue;
+    }
    const propLines = primitivePropertyLines(entry);
    if (propLines.length === 0) {
      rows.push([offset, type, name, '-', '-', severity]);
@@ -101,7 +136,7 @@ export function buildObserveSessionEventsTable(

  lines.push(renderTextTable(headers, rows));

-  if (options?.hasMoreMetricEvents || options?.hasMoreLogEvents) {
+  if (options?.hasMoreMetricEvents || options?.hasMoreLogEvents || options?.hasMoreSpans) {
    const sources: string[] = [];
    if (options.hasMoreMetricEvents) {
      sources.push('metric events');
@@ -109,6 +144,9 @@ export function buildObserveSessionEventsTable(
    if (options.hasMoreLogEvents) {
      sources.push('log events');
    }
+    if (options.hasMoreSpans) {
+      sources.push('spans');
+    }
    lines.push(
      '',
      chalk.yellow(
@@ -126,6 +164,7 @@ export interface ObserveSessionEventsJson {
  entries: SessionEventEntry[];
  hasMoreMetricEvents: boolean;
  hasMoreLogEvents: boolean;
+  hasMoreSpans: boolean;
 }

 export function buildObserveSessionEventsJson(
@@ -133,7 +172,8 @@ export function buildObserveSessionEventsJson(
  sessionId: string,
  metadata: SessionMetadata | null,
  hasMoreMetricEvents: boolean,
-  hasMoreLogEvents: boolean
+  hasMoreLogEvents: boolean,
+  hasMoreSpans: boolean
 ): ObserveSessionEventsJson {
  return {
    sessionId,
@@ -141,6 +181,7 @@ export function buildObserveSessionEventsJson(
    entries,
    hasMoreMetricEvents,
    hasMoreLogEvents,
+    hasMoreSpans,
  };
 }

@@ -0,0 +1,373 @@
+import chalk from 'chalk';
+
+import {
+  AppObserveSpan,
+  AppObserveSpanName,
+  AppObserveTrace,
+  PageInfo,
+} from '../graphql/generated';
+import renderTextTable from '../utils/renderTextTable';
+import { sanitizeTerminalText } from '../utils/terminalText';
+import { buildTimeRangeDescription, formatLogTimestamp } from './formatUtils';
+
+export function formatSpanDuration(durationMs: number): string {
+  const wholeMs = Math.round(durationMs);
+  if (wholeMs >= 1000) {
+    return `${(durationMs / 1000).toFixed(2)}s`;
+  }
+  return `${wholeMs}ms`;
+}
+
+/**
+ * The HTTP response status code, or the client-side error type when the
+ * request got no response, or "-" for a span that is not an HTTP request.
+ */
+export function formatSpanHttpStatus(span: AppObserveSpan): string {
+  if (span.http?.statusCode != null) {
+    return String(span.http.statusCode);
+  }
+  return span.http?.errorType ?? '-';
+}
+
+/** The path and query of a full URL; the URL itself when it does not parse. */
+export function formatSpanUrlPath(urlFull: string): string {
+  try {
+    const url = new URL(urlFull);
+    return `${url.pathname}${url.search}`;
+  } catch {
+    return urlFull;
+  }
+}
+
+/**
+ * One-line title for a span: the HTTP method, host, and path for a request
+ * span (`GET api.example.com/users`), else the span name.
+ */
+export function formatSpanTitle(span: AppObserveSpan): string {
+  const host = span.http?.urlHost;
+  if (!host) {
+    return span.name;
+  }
+  const path = span.http?.urlFull ? formatSpanUrlPath(span.http.urlFull) : '';
+  return `${span.name} ${host}${path}`;
+}
+
+export interface ObserveSpanHttpJson {
+  method: string | null;
+  statusCode: number | null;
+  urlHost: string | null;
+  urlFull: string | null;
+  protocolVersion: string | null;
+  requestSize: number | null;
+  responseSize: number | null;
+  errorType: string | null;
+}
+
+export interface ObserveSpanJson {
+  id: string;
+  traceId: string;
+  spanId: string;
+  parentSpanId: string | null;
+  name: string;
+  kind: string;
+  startTimestamp: string;
+  endTimestamp: string;
+  durationMs: number;
+  statusCode: string;
+  statusMessage: string | null;
+  sessionId: string | null;
+  http: ObserveSpanHttpJson | null;
+  attributes: Array<{ key: string; value: string; type: string }>;
+  events: Array<{ name: string; timestamp: string; attributes: unknown }>;
+  droppedAttributesCount: number;
+  droppedEventsCount: number;
+  droppedLinksCount: number;
+  ingestedAt: string | null;
+  appVersion: string;
+  appBuildNumber: string;
+  appUpdateId: string | null;
+  appEasBuildId: string | null;
+  expoSdkVersion: string | null;
+  reactNativeVersion: string | null;
+  deviceModel: string;
+  deviceOs: string;
+  deviceOsVersion: string;
+  environment: string | null;
+  easClientId: string;
+  countryCode: string | null;
+}
+
+export function buildObserveSpanJson(span: AppObserveSpan): ObserveSpanJson {
+  return {
+    id: span.id,
+    traceId: span.traceId,
+    spanId: span.spanId,
+    parentSpanId: span.parentSpanId ?? null,
+    name: span.name,
+    kind: span.kind,
+    startTimestamp: span.startTimestamp,
+    endTimestamp: span.endTimestamp,
+    durationMs: span.durationMs,
+    statusCode: span.statusCode,
+    statusMessage: span.statusMessage ?? null,
+    sessionId: span.sessionId ?? null,
+    http: span.http
+      ? {
+          method: span.http.method ?? null,
+          statusCode: span.http.statusCode ?? null,
+          urlHost: span.http.urlHost ?? null,
+          urlFull: span.http.urlFull ?? null,
+          protocolVersion: span.http.protocolVersion ?? null,
+          requestSize: span.http.requestSize ?? null,
+          responseSize: span.http.responseSize ?? null,
+          errorType: span.http.errorType ?? null,
+        }
+      : null,
+    attributes: span.attributes.map(a => ({ key: a.key, value: a.value, type: a.type })),
+    events: span.events.map(e => ({
+      name: e.name,
+      timestamp: e.timestamp,
+      attributes: e.attributes,
+    })),
+    droppedAttributesCount: span.droppedAttributesCount,
+    droppedEventsCount: span.droppedEventsCount,
+    droppedLinksCount: span.droppedLinksCount,
+    ingestedAt: span.ingestedAt ?? null,
+    appVersion: span.appVersion,
+    appBuildNumber: span.appBuildNumber,
+    appUpdateId: span.appUpdateId ?? null,
+    appEasBuildId: span.appEasBuildId ?? null,
+    expoSdkVersion: span.expoSdkVersion ?? null,
+    reactNativeVersion: span.reactNativeVersion ?? null,
+    deviceModel: span.deviceModel,
+    deviceOs: span.deviceOs,
+    deviceOsVersion: span.deviceOsVersion,
+    environment: span.environment ?? null,
+    easClientId: span.easClientId,
+    countryCode: span.countryCode ?? null,
+  };
+}
+
+export interface BuildSpanNamesTableOptions {
+  daysBack?: number;
+  startTime?: string;
+  endTime?: string;
+  isTruncated?: boolean;
+}
+
+export function buildObserveSpanNamesTable(
+  names: AppObserveSpanName[],
+  options?: BuildSpanNamesTableOptions
+): string {
+  if (names.length === 0) {
+    return chalk.yellow('No spans found.');
+  }
+
+  const headers = ['Span Name', 'Kind', 'Count'];
+  const rows: string[][] = names.map(n => [
+    sanitizeTerminalText(n.name),
+    n.kind,
+    n.count.toLocaleString(),
+  ]);
+
+  const lines: string[] = [];
+
+  if (options) {
+    const timeDesc = buildTimeRangeDescription(options);
+    lines.push(chalk.bold(`Span names ${timeDesc}`.trim()), '');
+  }
+
+  lines.push(renderTextTable(headers, rows));
+
+  if (options?.isTruncated) {
+    lines.push('', chalk.yellow('Result is truncated; not all span names are shown.'));
+  }
+
+  lines.push(
+    '',
+    'Pass --all-spans or a span filter such as --name, --host, or --status to list individual spans.'
+  );
+
+  return lines.join('\n');
+}
+
+export function buildObserveSpanNamesJson(
+  names: AppObserveSpanName[],
+  isTruncated: boolean
+): { names: Array<{ name: string; kind: string; count: number }>; isTruncated: boolean } {
+  return {
+    names: names.map(n => ({ name: n.name, kind: n.kind, count: n.count })),
+    isTruncated,
+  };
+}
+
+export interface BuildSpansTableOptions {
+  daysBack?: number;
+  startTime?: string;
+  endTime?: string;
+  sessionId?: string;
+}
+
+export function buildObserveSpansTable(
+  spans: AppObserveSpan[],
+  pageInfo: PageInfo,
+  options?: BuildSpansTableOptions
+): string {
+  if (spans.length === 0) {
+    return chalk.yellow('No spans found.');
+  }
+
+  const headers = [
+    'Timestamp',
+    'Name',
+    'Duration',
+    'Status',
+    'HTTP',
+    'Host',
+    'App Version',
+    'Platform',
+    'Trace ID',
+  ];
+
+  const rows: string[][] = spans.map(span => [
+    formatLogTimestamp(span.startTimestamp),
+    sanitizeTerminalText(span.name),
+    formatSpanDuration(span.durationMs),
+    span.statusCode,
+    formatSpanHttpStatus(span),
+    sanitizeTerminalText(span.http?.urlHost ?? '-'),
+    `${span.appVersion} (${span.appBuildNumber})`,
+    `${span.deviceOs} ${span.deviceOsVersion}`,
+    span.traceId,
+  ]);
+
+  const lines: string[] = [];
+
+  if (options) {
+    const subject = options.sessionId ? `Spans in session ${options.sessionId}` : 'Spans';
+    const timeDesc = options.sessionId ? '' : buildTimeRangeDescription(options);
+    lines.push(chalk.bold(`${subject} ${timeDesc}`.trim()), '');
+  }
+
+  lines.push(renderTextTable(headers, rows));
+
+  lines.push('', 'Show a whole trace: eas observe:trace <Trace ID>');
+
+  if (pageInfo.hasNextPage && pageInfo.endCursor) {
+    lines.push('', `Next page: --after ${pageInfo.endCursor}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function buildObserveSpansJson(
+  spans: AppObserveSpan[],
+  pageInfo: PageInfo
+): {
+  spans: ObserveSpanJson[];
+  pageInfo: { hasNextPage: boolean; endCursor: string | null };
+} {
+  return {
+    spans: spans.map(buildObserveSpanJson),
+    pageInfo: {
+      hasNextPage: pageInfo.hasNextPage,
+      endCursor: pageInfo.endCursor ?? null,
+    },
+  };
+}
+
+export interface TraceTreeRow {
+  span: AppObserveSpan;
+  depth: number;
+}
+
+function compareByStart(a: AppObserveSpan, b: AppObserveSpan): number {
+  if (a.startTimestamp !== b.startTimestamp) {
+    return a.startTimestamp < b.startTimestamp ? -1 : 1;
+  }
+  return a.spanId < b.spanId ? -1 : a.spanId > b.spanId ? 1 : 0;
+}
+
+/**
+ * Orders a trace's spans depth-first, children under their parent, siblings
+ * oldest first. A span whose parent is not in the trace is shown as a root.
+ */
+export function orderTraceSpans(spans: AppObserveSpan[]): TraceTreeRow[] {
+  const spanIds = new Set(spans.map(span => span.spanId));
+  const childrenByParent = new Map<string | null, AppObserveSpan[]>();
+  for (const span of spans) {
+    const parentKey =
+      span.parentSpanId && spanIds.has(span.parentSpanId) ? span.parentSpanId : null;
+    const siblings = childrenByParent.get(parentKey) ?? [];
+    siblings.push(span);
+    childrenByParent.set(parentKey, siblings);
+  }
+
+  const rows: TraceTreeRow[] = [];
+  const visit = (parentKey: string | null, depth: number): void => {
+    const children = childrenByParent.get(parentKey) ?? [];
+    for (const span of [...children].sort(compareByStart)) {
+      rows.push({ span, depth });
+      visit(span.spanId, depth + 1);
+    }
+  };
+  visit(null, 0);
+  return rows;
+}
+
+export function buildObserveTraceTable(trace: AppObserveTrace): string {
+  const rows = orderTraceSpans(trace.spans);
+  const lines: string[] = [chalk.bold(`Trace ${trace.id}`), ''];
+
+  if (rows.length === 0) {
+    lines.push(chalk.yellow('No spans found for this trace.'));
+    return lines.join('\n');
+  }
+
+  const sessionId = trace.spans.find(span => span.sessionId)?.sessionId;
+  const first = rows[0].span;
+  lines.push(
+    `Started:     ${formatLogTimestamp(first.startTimestamp)}`,
+    `Spans:       ${rows.length}${trace.isTruncated ? ' (truncated)' : ''}`,
+    `App version: ${first.appVersion} (${first.appBuildNumber})`,
+    `Device:      ${sanitizeTerminalText(first.deviceModel)} · ${first.deviceOs} ${first.deviceOsVersion}`,
+    `Session:     ${sessionId ?? '-'}`,
+    ''
+  );
+
+  const traceStartMs = Math.min(
+    ...trace.spans.map(span => new Date(span.startTimestamp).getTime())
+  );
+  const headers = ['Offset', 'Duration', 'Name', 'Status', 'HTTP', 'URL'];
+  const tableRows: string[][] = rows.map(({ span, depth }) => [
+    formatSpanDuration(new Date(span.startTimestamp).getTime() - traceStartMs),
+    formatSpanDuration(span.durationMs),
+    `${'  '.repeat(depth)}${sanitizeTerminalText(span.name)}`,
+    span.statusCode,
+    formatSpanHttpStatus(span),
+    sanitizeTerminalText(span.http?.urlFull ?? '-'),
+  ]);
+  lines.push(renderTextTable(headers, tableRows));
+
+  if (trace.isTruncated) {
+    lines.push('', chalk.yellow('This trace has more spans than are shown.'));
+  }
+
+  if (sessionId) {
+    lines.push('', `Show the session timeline: eas observe:session ${sessionId}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function buildObserveTraceJson(trace: AppObserveTrace): {
+  id: string;
+  isTruncated: boolean;
+  spans: ObserveSpanJson[];
+} {
+  return {
+    id: trace.id,
+    isTruncated: trace.isTruncated,
+    spans: orderTraceSpans(trace.spans).map(({ span }) => buildObserveSpanJson(span)),
+  };
+}
@@ -0,0 +1,37 @@
+import { AppObserveSpanKind, AppObserveSpanStatusCode } from '../graphql/generated';
+
+export const allowedSpanKindFlagValues = Object.values(AppObserveSpanKind).map(kind =>
+  kind.toLowerCase()
+);
+
+export const allowedSpanStatusFlagValues = Object.values(AppObserveSpanStatusCode).map(code =>
+  code.toLowerCase()
+);
+
+export function spanKindsFromFlag(values: string[] | undefined): AppObserveSpanKind[] | undefined {
+  if (!values?.length) {
+    return undefined;
+  }
+  return values.map(value => {
+    const kind = Object.values(AppObserveSpanKind).find(k => k.toLowerCase() === value);
+    if (!kind) {
+      throw new Error(`Unknown span kind flag value: "${value}"`);
+    }
+    return kind;
+  });
+}
+
+export function spanStatusCodesFromFlag(
+  values: string[] | undefined
+): AppObserveSpanStatusCode[] | undefined {
+  if (!values?.length) {
+    return undefined;
+  }
+  return values.map(value => {
+    const code = Object.values(AppObserveSpanStatusCode).find(c => c.toLowerCase() === value);
+    if (!code) {
+      throw new Error(`Unknown span status flag value: "${value}"`);
+    }
+    return code;
+  });
+}
@@ -1,5 +1,13 @@
 # @expo/eas-json

+## 27.3.0
+
+No changes in this release.
+
+## 27.2.0
+
+No changes in this release.
+
 ## 27.1.0

 No changes in this release.
@@ -1,6 +1,6 @@
 {
  "name": "@expo/eas-json",
-  "version": "27.1.0",
+  "version": "27.3.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": "27.1.0",
+    "@expo/eas-build-job": "27.3.0",
    "chalk": "4.1.2",
    "env-string": "1.0.1",
    "fs-extra": "11.2.0",
@@ -1,5 +1,13 @@
 # eas-cli-local-build-plugin

+## 27.3.0
+
+No changes in this release.
+
+## 27.2.0
+
+No changes in this release.
+
 ## 27.1.0

 No changes in this release.
@@ -1,6 +1,6 @@
 {
  "name": "eas-cli-local-build-plugin",
-  "version": "27.1.0",
+  "version": "27.3.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": "27.1.0",
+    "@expo/build-tools": "27.3.0",
    "@expo/bunyan": "^4.0.1",
-    "@expo/eas-build-job": "27.1.0",
-    "@expo/logger": "27.1.0",
+    "@expo/eas-build-job": "27.3.0",
+    "@expo/logger": "27.3.0",
    "@expo/spawn-async": "^1.7.2",
-    "@expo/turtle-spawn": "27.1.0",
+    "@expo/turtle-spawn": "27.3.0",
    "chalk": "4.1.2",
    "env-paths": "^2.2.1",
    "fs-extra": "^11.2.0",
@@ -1,5 +1,13 @@
 # @expo/logger

+## 27.3.0
+
+No changes in this release.
+
+## 27.2.0
+
+No changes in this release.
+
 ## 27.1.0

 No changes in this release.
@@ -1,6 +1,6 @@
 {
  "name": "@expo/logger",
-  "version": "27.1.0",
+  "version": "27.3.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
  "author": "Expo <[email protected]>",
@@ -0,0 +1,12 @@
+# @expo/simulator-launcher
+
+## 27.3.0
+
+No changes in this release.
+
+## 27.2.0
+
+### Minor Changes
+
+- Accept a comma-separated list of warm Simulators in `EXPO_SIMULATOR_DEVICE`; the first is the default. One serve-sim serves every listed device on one port. After the default device is ready, warmup preinstalls the latest stable Expo Go from one download and tries to disable apsd on the other devices, until a job claims one. A claim can select any listed device and reports its preinstalled Expo Go. ([#4764](https://github.com/expo/eas-cli/pull/4764) by [@gwdp](https://github.com/gwdp))
+- Add `@expo/simulator-launcher`, which warms an iOS Simulator at VM boot and hands it to one EAS job (`start`, `claim`, `prepare-tools`, `stop`). ([#4722](https://github.com/expo/eas-cli/pull/4722) by [@gwdp](https://github.com/gwdp))
@@ -0,0 +1,80 @@
+# @expo/simulator-launcher
+
+Warm iOS Simulators before an EAS job arrives. Requires macOS.
+The image installs vm-tools and writes its startup script at
+`/usr/local/share/vm-tools/startup.sh`:
+
+```sh
+export EXPO_SIMULATOR_STARTUP=1
+export EXPO_SIMULATOR_DEVICE="iPhone Duo,iPhone 18"
+exec bunx @expo/simulator-launcher@latest start
+```
+
+## Commands
+
+- `start`: run one orphan serve-sim for the configured devices. Its default device becomes ready
+  first; additional devices warm in the background. Argent and agent-device prestart on the default.
+- `claim ENGINE [DEVICE]`: reserve one job and return its selected device plus the existing server's
+  identity, port and credentials. Engines: `serve-sim`, `agent-device`, `argent`.
+  No DEVICE means the first configured device. Claim does not boot the selected device or wait for
+  its tool. Build-tools privately adopts that device on the existing serve-sim port.
+- `prepare-tools`: continue the consumed claim after adoption. Keep global Argent, reuse the default
+  agent-device runner or prepare a runner for the selected device.
+- `stop`: permanently end warmup for this boot and wait for all owned resources to be cleaned up.
+
+```sh
+# Build-tools reads LAUNCHER_VERSION from the version recorded by start.
+bun x --no-install "@expo/simulator-launcher@$LAUNCHER_VERSION" claim serve-sim
+# After private serve-sim adoption confirms the selected device and native ACK:
+bun x --no-install "@expo/simulator-launcher@$LAUNCHER_VERSION" prepare-tools
+bun x --no-install "@expo/simulator-launcher@$LAUNCHER_VERSION" stop
+```
+
+There is no copied launcher bundle. Build-tools uses the recorded package version for claim/stop;
+Warmup primes Bun’s exact-version cache before ready, with two attempts of up to 30 seconds. Its claim/stop calls use `--no-install`, retrying
+once with the registry only when Bun cannot find that cached binary. Priming failures warn.
+Before start has run,
+stop uses the normal package-manager path and still disables later warmup for this boot.
+
+This flow requires the serve-sim release supporting port-based device adoption.
+
+One durable state file, `/tmp/expo-simulator-startup.json`, holds the lifecycle, launcher version,
+selected device, server credentials, claim and native identity. It is independent of HOME/TMPDIR. A short boot-scoped lock
+serializes updates; an abandoned lock fails closed. This private format requires a fresh VM.
+
+## Environment
+
+- `EXPO_SIMULATOR_STARTUP=1` enables warmup.
+- `EXPO_SIMULATOR_PREINSTALL_EXPO_GO=0` turns off the Expo Go preinstall.
+- `EXPO_SIMULATOR_DEVICE` is a comma-separated list of exact device names or UDIDs. Entries are
+  trimmed and must each identify one available device. The first is the default. Unset keeps
+  the shortest available iPhone name, as does an empty or blank value. Empty list entries, missing,
+  ambiguous or duplicate devices fail clearly.
+- `SERVE_SIM_VERSION`, `AGENT_DEVICE_VERSION`, `ARGENT_VERSION`: each defaults to `latest`.
+- `AGENT_DEVICE_STATE_DIR`, `ARGENT_EVENT_LOG`: tool state/output locations.
+- Agent-device idle timers default to off. Override with `AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS`
+  and `AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS` (milliseconds).
+
+## Boundaries
+
+- Ready means the default device booted and serve-sim answers. The apsd step and the Expo Go
+  preinstall run in the background on every listed device. A claim does not wait for them; stop
+  joins them.
+  The second device may not have started yet. Its startup failure leaves the default available.
+  Claim reserves a device; it does not report that device ready. Private adoption must confirm
+  the same server PID/port, selected-device readiness and native video/capture before tool setup
+  and app actions. Job-time version and authentication checks remain authoritative.
+- Agent-device prestarts on the default device only. A secondary claim prepares its runner after
+  adoption and old-runner cleanup finish. One device-independent Argent server is reused for the claimed device.
+- Warmup downloads/extracts the latest stable Expo Go once and reuses it for the second device.
+  Each initial device gets a preinstall attempt; ordinary failures warn. Claim prevents new
+  preinstalls. `prepare-tools` waits for an install still running on the claimed device and
+  reports its version, because the job installs its app next. Installs on other devices continue;
+  adoption may shut such a device down, and its install then fails with a warning. Terminal stop
+  drains them and the download cleanup. Job app installs remain
+  authoritative. Replacements do not preinstall again. The VM image provides ffmpeg.
+- One start attempt and one accepted claim per boot. Failed cleanup never permits another session.
+  Stop's caller timeout is not a global cleanup deadline or proof that teardown completed.
+  A build-tools claim timeout uses normal startup only after confirmed terminal cleanup.
+
+Claim and tool JSON include credentials; capture them rather than streaming them to job logs.
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index').runCliAsync();
@@ -0,0 +1,13 @@
+import type { Config } from '@jest/types';
+
+import baseConfig from '../../jest/jest.shared.config';
+
+const config: Config.InitialOptions = {
+  ...baseConfig,
+  rootDir: 'src',
+  testMatch: ['**/__tests__/*.test.ts'],
+  setupFiles: ['<rootDir>/__tests__/fixturePids.ts'],
+  clearMocks: true,
+};
+
+export default config;
@@ -0,0 +1,37 @@
+{
+  "name": "@expo/simulator-launcher",
+  "version": "27.3.0",
+  "description": "Launch and claim Simulator sessions on EAS workers",
+  "bugs": "https://github.com/expo/eas-cli/issues",
+  "license": "BUSL-1.1",
+  "author": "Expo <[email protected]>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/expo/eas-cli.git",
+    "directory": "packages/simulator-launcher"
+  },
+  "bin": "bin/simulator-launcher",
+  "files": [
+    "bin",
+    "dist/index.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest --config jest.config.ts",
+    "build": "ncc build src/main.ts -o dist --no-cache --no-source-map-register",
+    "typecheck": "tsc --noEmit",
+    "prepack": "yarn build",
+    "rebuild": "yarn build"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "22.20.5",
+    "@vercel/ncc": "^0.38.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.12",
+    "typescript": "^6.0.3",
+    "zod": "^4.3.5"
+  }
+}
@@ -0,0 +1,190 @@
+import { type ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs/promises';
+
+import { createArgentTool } from '../utils/argent';
+import {
+  commands,
+  isProcessOwnedByServiceAsync,
+  stopProcessAndDescendantsAsync,
+} from '../utils/processes';
+import { type WarmTool } from '../utils/tools';
+import { deferred, until } from './helpers';
+
+jest.mock('node:fs/promises');
+jest.mock('../utils/processes');
+let child: ChildProcess;
+let result: ReturnType<typeof deferred<string>>;
+let controller: AbortController;
+let onFailure: jest.Mock;
+let tool: WarmTool;
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  child = Object.assign(new EventEmitter(), {
+    pid: 90001,
+    exitCode: null,
+    signalCode: null,
+  }) as ChildProcess;
+  result = deferred<string>();
+  void result.promise.catch(() => {});
+  controller = new AbortController();
+  onFailure = jest.fn();
+  // The old factory ignores this callback; its start also resolves without readiness.
+  const createTool: (onFailure: (error: unknown) => void) => WarmTool = createArgentTool;
+  tool = createTool(onFailure);
+  jest.mocked(commands.start).mockReturnValue({ child, resultPromise: result.promise });
+  jest.mocked(isProcessOwnedByServiceAsync).mockResolvedValue(true);
+  jest.mocked(fs.readdir).mockResolvedValue(['tool-server.json'] as never);
+  jest
+    .mocked(fs.readFile)
+    .mockResolvedValue(JSON.stringify({ pid: 90001, port: 3201, token: 'fixture-token' }));
+  jest.spyOn(global, 'fetch').mockResolvedValue(new Response(JSON.stringify({ tools: [] })));
+  jest.mocked(stopProcessAndDescendantsAsync).mockResolvedValue();
+});
+afterEach(() => {
+  controller.abort();
+  jest.restoreAllMocks();
+});
+
+it('does not report ready until its owned server answers the authenticated tools request', async () => {
+  const response = deferred<Response>();
+  jest.mocked(fetch).mockReturnValue(response.promise);
+  let ready = false;
+  const started = tool.startAsync('PHONE', controller.signal).then(() => {
+    ready = true;
+  });
+  await until(() => jest.mocked(fetch).mock.calls.length > 0 || ready);
+  expect(ready).toBe(false);
+  response.resolve(new Response(JSON.stringify({ tools: [] })));
+  await started;
+  expect(commands.start).toHaveBeenCalledWith('bunx', expect.arrayContaining(['server', 'start']), {
+    detached: true,
+  });
+  expect(fetch).toHaveBeenCalledWith('http://127.0.0.1:3201/tools', {
+    headers: { Authorization: 'Bearer fixture-token' },
+    signal: expect.any(AbortSignal),
+  });
+});
+
+it('rejects an exit during the readiness request, even before the wrapper finishes closing', async () => {
+  const response = deferred<Response>();
+  jest.mocked(fetch).mockReturnValue(response.promise);
+  const started = tool.startAsync('PHONE', controller.signal);
+  await until(() => jest.mocked(fetch).mock.calls.length > 0);
+  Object.assign(child, { exitCode: 1 });
+  child.emit('exit', 1, null);
+  response.resolve(new Response(JSON.stringify({ tools: [] })));
+  await expect(started).rejects.toThrow('Argent exited before its server became ready');
+  expect(onFailure).not.toHaveBeenCalled();
+});
+
+it('observes an unexpected exit after readiness exactly once', async () => {
+  await tool.startAsync('PHONE', controller.signal);
+  child.emit('exit', 1, null);
+  result.reject(new Error('wrapper failed'));
+  await Promise.resolve();
+  expect(onFailure).toHaveBeenCalledTimes(1);
+  expect(onFailure.mock.calls[0][0].message).toContain('Argent server exited unexpectedly');
+});
+
+it('ignores a foreign state file without sending its token to the local port', async () => {
+  jest.mocked(isProcessOwnedByServiceAsync).mockResolvedValue(false);
+  const started = tool.startAsync('PHONE', controller.signal).catch(error => error);
+  await until(() => jest.mocked(isProcessOwnedByServiceAsync).mock.calls.length > 0);
+  expect(fetch).not.toHaveBeenCalled();
+  controller.abort(new Error('cancelled'));
+  expect((await started).code).toBe('ABORT_ERR');
+});
+
+it('retries an invalid tools response and does not notify for intentional stop', async () => {
+  jest
+    .mocked(fetch)
+    .mockResolvedValueOnce(new Response('{}'))
+    .mockImplementation(async () => new Response(JSON.stringify({ tools: [] })));
+  await tool.startAsync('PHONE', controller.signal);
+  expect(fetch).toHaveBeenCalledTimes(2);
+  jest.mocked(stopProcessAndDescendantsAsync).mockImplementation(async () => {
+    child.emit('exit', 0, null);
+  });
+  await tool.stopAsync();
+  expect(onFailure).not.toHaveBeenCalled();
+});
+
+it('does not notify for cancelled tool teardown', async () => {
+  await tool.startAsync('PHONE', controller.signal);
+  controller.abort();
+  child.emit('exit', 0, null);
+  expect(onFailure).not.toHaveBeenCalled();
+});
+
+it('never publishes ready when cancellation arrives during the tools request', async () => {
+  const response = deferred<Response>();
+  jest.mocked(fetch).mockReturnValue(response.promise);
+  const started = tool.startAsync('PHONE', controller.signal);
+  await until(() => jest.mocked(fetch).mock.calls.length > 0);
+  controller.abort(new Error('cancelled'));
+  response.resolve(new Response(JSON.stringify({ tools: [] })));
+  await expect(started).rejects.toThrow('cancelled');
+  expect(onFailure).not.toHaveBeenCalled();
+});
+
+it('bounds readiness when the server never becomes available', async () => {
+  const now = Date.now();
+  jest
+    .spyOn(Date, 'now')
+    .mockReturnValueOnce(now)
+    .mockReturnValue(now + 120_000);
+  await expect(tool.startAsync('PHONE', controller.signal)).rejects.toThrow(
+    'Timed out waiting for the Argent server'
+  );
+  expect(fetch).not.toHaveBeenCalled();
+});
+
+it('retries missing or incomplete state and transient HTTP failures before becoming ready', async () => {
+  jest
+    .mocked(fs.readdir)
+    .mockRejectedValueOnce(
+      Object.assign(new Error('state directory not written yet'), { code: 'ENOENT' })
+    )
+    .mockResolvedValue(['events.jsonl', 'tool-server-old.json', 'tool-server.json'] as never);
+  jest
+    .mocked(fs.readFile)
+    .mockRejectedValueOnce(new Error('state disappeared during startup'))
+    .mockResolvedValue(JSON.stringify({ pid: 90001, port: 3201, token: 'fixture-token' }));
+  jest
+    .mocked(fetch)
+    .mockRejectedValueOnce(new Error('connection refused'))
+    .mockResolvedValueOnce(new Response('unauthorized', { status: 401 }))
+    .mockImplementation(async () => new Response(JSON.stringify({ tools: [] })));
+  await tool.startAsync('PHONE', controller.signal);
+  expect(fs.readdir).toHaveBeenCalledTimes(3);
+  expect(fetch).toHaveBeenCalledTimes(3);
+  expect(onFailure).not.toHaveBeenCalled();
+});
+
+it('rejects a successful wrapper exit while no state directory is available', async () => {
+  jest.mocked(fs.readdir).mockImplementation(async () => {
+    result.resolve('');
+    throw new Error('state directory unavailable');
+  });
+  await expect(tool.startAsync('PHONE', controller.signal)).rejects.toThrow(
+    'Argent exited before its server became ready'
+  );
+  expect(fetch).not.toHaveBeenCalled();
+  expect(onFailure).not.toHaveBeenCalled();
+});
+
+it('rejects an exit during the final ownership check before publishing readiness', async () => {
+  const owned = deferred<boolean>();
+  jest
+    .mocked(isProcessOwnedByServiceAsync)
+    .mockResolvedValueOnce(true)
+    .mockReturnValue(owned.promise);
+  const started = tool.startAsync('PHONE', controller.signal);
+  await until(() => jest.mocked(isProcessOwnedByServiceAsync).mock.calls.length === 2);
+  child.emit('error', new Error('server failed during validation'));
+  owned.resolve(true);
+  await expect(started).rejects.toThrow('Argent exited before its server became ready');
+  expect(onFailure).not.toHaveBeenCalled();
+});
@@ -0,0 +1,87 @@
+import { commands } from '../utils/processes';
+import { startOwnedWrapperAsync } from './fixtures/ownedWrapper';
+
+it('an early claim survives unused-tool wrapper exit while the selected server and Simulator stay owned', async () => {
+  const fixture = await startOwnedWrapperAsync();
+  const environment = { ...process.env };
+  let session:
+    | ReturnType<typeof import('../commands/start').createWarmSimulatorSession>
+    | undefined;
+  try {
+    const { createWarmSimulatorSession } = await import('../commands/start');
+    const simulator = await import('../utils/simulator');
+    const serveSim = await import('../utils/serveSim');
+    const processes = await import('../utils/processes');
+    const agentDevice = await import('../utils/agentDevice');
+    const argent = await import('../utils/argent');
+    const expoGo = await import('../utils/expoGo');
+    const controller = new AbortController();
+    const running = commands.runAsync.bind(commands);
+    process.env.EXPO_SIMULATOR_DEVICE = 'DUO';
+    process.env.AGENT_DEVICE_STATE_DIR = '/owned-wrapper-fixture/agent';
+    process.env.ARGENT_EVENT_LOG = '/owned-wrapper-fixture/argent-events';
+    jest
+      .spyOn(commands, 'runAsync')
+      .mockImplementation((file, args, signal) =>
+        file === 'bun' || (file === 'ps' && args[1] === String(process.pid))
+          ? Promise.resolve('controller-start')
+          : running(file, args, signal)
+      );
+    jest
+      .spyOn(simulator, 'listAvailableSimulatorsAsync')
+      .mockResolvedValue([{ udid: 'DUO', name: 'iPhone Duo' }]);
+    jest.spyOn(simulator, 'waitForSimulatorBootAsync').mockResolvedValue();
+    jest.spyOn(simulator, 'disableApsdAsync').mockResolvedValue();
+    const shutdown = jest.spyOn(simulator, 'shutdownSimulatorAsync').mockResolvedValue();
+    const stopServer = jest.spyOn(processes, 'stopProcessAndDescendantsAsync').mockResolvedValue();
+    jest.spyOn(agentDevice, 'createAgentDeviceTool').mockReturnValue({
+      name: 'agent-device',
+      startAsync: async () => {},
+      stopAsync: fixture.stopAsync,
+    });
+    jest
+      .spyOn(argent, 'createArgentTool')
+      .mockReturnValue({ name: 'argent', startAsync: async () => {}, stopAsync: async () => {} });
+    jest.spyOn(expoGo, 'startExpoGoPreinstall').mockReturnValue({
+      preinstallOnDeviceAsync: async () => {},
+      claimAsync: async () => undefined,
+      stopAsync: async () => {},
+    });
+    jest.spyOn(serveSim, 'startServeSim').mockReturnValue({
+      child: { pid: 90001 } as import('node:child_process').ChildProcess,
+      resultPromise: new Promise(() => {}),
+    });
+    jest.spyOn(serveSim, 'waitForServeSimReadyAsync').mockResolvedValue({
+      startupDevice: 'DUO',
+      pid: 90001,
+      nativeStartTime: 'fixture-start',
+      port: 3200,
+      url: 'http://127.0.0.1:3200',
+      token: 'fixture-token',
+    });
+    const onFailure = jest.fn(error => controller.abort(error));
+    session = createWarmSimulatorSession({
+      signal: controller.signal,
+      throwIfStoppingAsync: async () => controller.signal.throwIfAborted(),
+      onPreparationFailure: onFailure,
+    });
+    await session.prepareAsync();
+    expect(await session.claimAsync({ engine: 'serve-sim' })).toMatchObject({
+      device: { udid: 'DUO' },
+    });
+    await session.prepareToolsAsync();
+    await fixture.stopAsync();
+    expect(fixture.job.child.exitCode).toBe(23);
+    expect(onFailure).not.toHaveBeenCalled();
+    expect(controller.signal.aborted).toBe(false);
+    expect(stopServer).not.toHaveBeenCalled();
+    expect(shutdown).not.toHaveBeenCalled();
+    await session.stopAsync();
+    expect(shutdown).toHaveBeenCalledWith('DUO');
+  } finally {
+    await session?.stopAsync().catch(() => {});
+    jest.restoreAllMocks();
+    process.env = environment;
+    await fixture.cleanupAsync();
+  }
+}, 10_000);
@@ -0,0 +1,636 @@
+import fs from 'node:fs/promises';
+import { gzipSync } from 'node:zlib';
+import os from 'node:os';
+import path from 'node:path';
+
+import { startExpoGoPreinstall } from '../utils/expoGo';
+import { commands } from '../utils/processes';
+import { deferred, until } from './helpers';
+
+const runCommandAsync = commands.runAsync.bind(commands);
+function createArchive(entries: { name: string; contents: Buffer }[]): Buffer {
+  const blocks: Buffer[] = [];
+  for (const { name, contents } of entries) {
+    const header = Buffer.alloc(512);
+    header.write(name);
+    header.write('0000644\0', 100);
+    header.write(contents.length.toString(8).padStart(11, '0') + '\0', 124);
+    header.fill(32, 148, 156);
+    header.write('0', 156);
+    const checksum = header.reduce((sum, byte) => sum + byte, 0);
+    header.write(checksum.toString(8).padStart(6, '0') + '\0 ', 148);
+    blocks.push(header, contents, Buffer.alloc((512 - (contents.length % 512)) % 512));
+  }
+  return gzipSync(Buffer.concat([...blocks, Buffer.alloc(1024)]));
+}
+function installCalls() {
+  return jest.mocked(commands.runAsync).mock.calls.filter(([file]) => file === 'xcrun');
+}
+
+let directory: string;
+let archive: Buffer;
+let controller: AbortController;
+let warmup: ReturnType<typeof startOn> | undefined;
+const stableUrl = 'https://example.test/Expo-Go-stable.tar.gz';
+const sdkVersions = {
+  '57.0.0': {
+    releaseNoteUrl: 'https://example.test/57',
+    iosClientUrl: 'https://example.test/old.tar.gz',
+  },
+  '58.0.0': { releaseNoteUrl: 'https://example.test/58', iosClientUrl: stableUrl },
+  '59.0.0': {
+    isBeta: true,
+    releaseNoteUrl: 'https://example.test/beta',
+    iosClientUrl: 'https://example.test/beta.tar.gz',
+  },
+  '60.0.0': { iosClientUrl: 'https://example.test/canary.tar.gz' },
+  '61.1.0': {
+    releaseNoteUrl: 'https://example.test/not-published',
+    iosClientUrl: 'https://example.test/not-published.tar.gz',
+  },
+};
+
+/** Starts the shared download and preinstalls on one device, as warmup does for each device. */
+function startOn(udid: string, boot: Promise<unknown>) {
+  const preinstall = startExpoGoPreinstall(controller.signal);
+  return {
+    ...preinstall,
+    resultPromise: preinstall.preinstallOnDeviceAsync(udid, boot, controller.signal),
+  };
+}
+
+beforeEach(async () => {
+  directory = await fs.mkdtemp(path.join(os.tmpdir(), 'expo-go-unit-'));
+  archive = createArchive([
+    { name: 'Info.plist', contents: Buffer.from('<plist>fixture</plist>') },
+  ]);
+  jest.spyOn(os, 'tmpdir').mockReturnValue(directory);
+  jest
+    .spyOn(global, 'fetch')
+    .mockImplementation(async url =>
+      url === 'https://api.expo.dev/v2/versions'
+        ? Response.json({ iosUrl: 'https://example.test/legacy.tar.gz', sdkVersions })
+        : new Response(Uint8Array.from(archive))
+    );
+  jest
+    .spyOn(commands, 'runAsync')
+    .mockImplementation(async (file, args, signal) =>
+      file === '/usr/bin/tar' ? await runCommandAsync(file, args, signal) : ''
+    );
+  jest.spyOn(commands, 'throwIfCommandCloseTimedOut').mockImplementation(() => {});
+  jest.spyOn(process.stderr, 'write').mockReturnValue(true);
+  controller = new AbortController();
+  warmup = undefined;
+});
+afterEach(async () => {
+  controller.abort();
+  await warmup?.stopAsync('UDID').catch(() => {});
+  jest.restoreAllMocks();
+  await fs.rm(directory, { recursive: true, force: true });
+});
+
+it('uses the website stable release policy, extracts flat contents as .app and installs only after boot', async () => {
+  const boot = deferred();
+  warmup = startOn('UDID', boot.promise);
+  try {
+    await until(() => jest.mocked(fetch).mock.calls.length === 2);
+    expect(fetch).toHaveBeenLastCalledWith(
+      stableUrl,
+      expect.objectContaining({
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': 'expo-simulator-launcher',
+        },
+      })
+    );
+    expect(installCalls()).toHaveLength(0);
+    boot.resolve();
+    await warmup.resultPromise;
+    expect(installCalls()).toHaveLength(1);
+    const [file, args, signal] = installCalls()[0];
+    expect(file).toBe('xcrun');
+    expect(args.slice(0, 3)).toEqual(['simctl', 'install', 'UDID']);
+    expect(path.basename(args[3])).toBe('ExpoGo.app');
+    expect(signal).toBeUndefined(); // Never cancel an in-flight installd transaction through simctl.
+    // The shared download stays until a claim or stop releases it; stop waits for the removal.
+    expect((await fs.stat(path.dirname(args[3]))).isDirectory()).toBe(true);
+    await warmup.stopAsync('UDID');
+    await expect(fs.stat(path.dirname(args[3]))).rejects.toMatchObject({ code: 'ENOENT' });
+  } finally {
+    boot.resolve();
+  }
+});
+
+it('claim aborts a pending download without waiting for it, and a late fetch cannot install', async () => {
+  const pending = deferred<Response>();
+  jest.mocked(fetch).mockReturnValueOnce(pending.promise);
+  warmup = startOn('UDID', Promise.resolve());
+  try {
+    await until(() => jest.mocked(fetch).mock.calls.length > 0);
+    await warmup.claimAsync('UDID');
+    expect(jest.mocked(fetch).mock.calls[0][1]?.signal?.aborted).toBe(true);
+    pending.resolve(Response.json({ sdkVersions })); // Even an uncooperative late fetch cannot install.
+    await warmup.stopAsync('UDID');
+    expect(installCalls()).toHaveLength(0);
+    expect(
+      (await fs.readdir(directory)).filter(name => name.startsWith('simulator-expo-go-'))
+    ).toEqual([]);
+  } finally {
+    pending.resolve(Response.json({ sdkVersions }));
+  }
+});
+
+it('claim only waits for the native install; terminal stop also drains temporary-file cleanup', async () => {
+  const installation = deferred<string>();
+  const cleanup = deferred();
+  const remove = fs.rm.bind(fs);
+  let cleanupStarted = false;
+  jest.spyOn(fs, 'rm').mockImplementation(async (file, options) => {
+    cleanupStarted = true;
+    await cleanup.promise;
+    return await remove(file, options);
+  });
+  jest
+    .mocked(commands.runAsync)
+    .mockImplementation(async (file, args) =>
+      file === '/usr/bin/tar' ? await runCommandAsync(file, args) : await installation.promise
+    );
+  warmup = startOn('UDID', Promise.resolve());
+  try {
+    await until(() => installCalls().length > 0);
+    let claimed = false;
+    const claiming = warmup.claimAsync('UDID').then(() => {
+      claimed = true;
+    });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(claimed).toBe(false);
+    installation.resolve('');
+    await claiming;
+    expect(claimed).toBe(true);
+    await until(() => cleanupStarted);
+    let stopped = false;
+    const stopping = warmup.stopAsync('UDID').then(() => {
+      stopped = true;
+    });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(stopped).toBe(false);
+    cleanup.resolve();
+    await stopping;
+  } finally {
+    installation.resolve('');
+    cleanup.resolve();
+  }
+});
+
+it('claim during extraction returns without waiting but cannot begin an install afterward', async () => {
+  const extraction = deferred();
+  let extracting = false;
+  jest.mocked(commands.runAsync).mockImplementation(async (file, args) => {
+    expect(file).toBe('/usr/bin/tar');
+    extracting = true;
+    await extraction.promise;
+    return await runCommandAsync(file, args);
+  });
+  warmup = startOn('UDID', Promise.resolve());
+  try {
+    await until(() => extracting);
+    await warmup.claimAsync('UDID');
+    expect(installCalls()).toHaveLength(0);
+    let stopped = false;
+    const stopping = warmup.stopAsync('UDID').then(() => {
+      stopped = true;
+    });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(stopped).toBe(false);
+    extraction.resolve();
+    await stopping;
+    expect(installCalls()).toHaveLength(0);
+  } finally {
+    extraction.resolve();
+  }
+});
+
+it.each(['metadata', 'archive', 'install'])(
+  'warns on an ordinary %s failure without failing warmup',
+  async phase => {
+    if (phase === 'metadata') {
+      jest.mocked(fetch).mockResolvedValueOnce(new Response('', { status: 403 }));
+    }
+    if (phase === 'archive') {
+      jest
+        .mocked(fetch)
+        .mockResolvedValueOnce(Response.json({ sdkVersions }))
+        .mockResolvedValueOnce(new Response('', { status: 503 }));
+    }
+    if (phase === 'install') {
+      jest.mocked(commands.runAsync).mockImplementation(async (file, args) => {
+        if (file === '/usr/bin/tar') {
+          return await runCommandAsync(file, args);
+        }
+        throw Object.assign(new Error('install failed'), { code: 1 });
+      });
+    }
+    warmup = startOn('UDID', Promise.resolve());
+    await warmup.resultPromise;
+    await warmup.claimAsync('UDID');
+    await warmup.stopAsync('UDID');
+    expect(process.stderr.write).toHaveBeenCalledWith(
+      expect.stringContaining('Could not preinstall Expo Go')
+    );
+  }
+);
+
+it.each(['signal', 'close timeout', 'temp removal'])(
+  'fails closed on %s instead of treating it as optional installation failure',
+  async kind => {
+    const error = Object.assign(new Error(`uncertain ${kind}`), {
+      code: kind === 'signal' ? null : 1,
+    });
+    if (kind === 'temp removal') {
+      jest.spyOn(fs, 'rm').mockRejectedValueOnce(error);
+    } else {
+      jest.mocked(commands.runAsync).mockImplementation(async (file, args) => {
+        if (file === '/usr/bin/tar') {
+          return await runCommandAsync(file, args);
+        }
+        if (kind === 'close timeout') {
+          jest.mocked(commands.throwIfCommandCloseTimedOut).mockImplementation(() => {
+            throw error;
+          });
+        }
+        throw error;
+      });
+    }
+    warmup = startOn('UDID', Promise.resolve());
+    await warmup.resultPromise.catch(() => {});
+    // The claim does not wait for the removal; stop does, and never confirms a failed one.
+    await warmup.claimAsync('UDID').catch(() => {});
+    await expect(warmup.stopAsync('UDID')).rejects.toBe(error);
+  }
+);
+
+it.each(['valid', 'traversal', 'malformed'] as const)(
+  'drains the real owned extractor for a %s archive before removing temp files or settling stop',
+  async kind => {
+    const contents = Buffer.alloc(4 * 1024 * 1024, 97);
+    archive =
+      kind === 'malformed'
+        ? Buffer.from('not a gzip or tar archive')
+        : createArchive([
+            ...(kind === 'traversal'
+              ? [{ name: '../escaped', contents: Buffer.from('unsafe') }]
+              : []),
+            { name: 'Info.plist', contents: Buffer.from('<plist>fixture</plist>') },
+            { name: 'ordinary-file', contents },
+          ]);
+    const start = commands.start.bind(commands);
+    let extractor: ReturnType<typeof commands.start> | undefined;
+    let extractorClosed = false;
+    const remove = fs.rm.bind(fs);
+    const removing = jest.spyOn(fs, 'rm').mockImplementation(async (file, options) => {
+      expect(extractorClosed).toBe(true);
+      if (kind === 'traversal') {
+        await expect(fs.access(path.join(String(file), 'escaped'))).rejects.toMatchObject({
+          code: 'ENOENT',
+        });
+      }
+      if (kind !== 'malformed') {
+        expect(
+          (await fs.readFile(path.join(String(file), 'ExpoGo.app', 'ordinary-file'))).equals(
+            contents
+          )
+        ).toBe(true);
+      }
+      return await remove(file, options);
+    });
+    jest.spyOn(commands, 'start').mockImplementation((file, args, options) => {
+      expect(file).toBe('/usr/bin/tar');
+      expect(args).toEqual([
+        '-xzf',
+        expect.stringMatching(/\/expo-go.tar.gz$/),
+        '-C',
+        expect.stringMatching(/\/ExpoGo.app$/),
+      ]);
+      expect(options?.signal).toBeUndefined();
+      extractor = start(file, args, options);
+      extractor.child.once('close', () => {
+        extractorClosed = true;
+      });
+      expect(extractor.child.kill('SIGSTOP')).toBe(true);
+      return extractor;
+    });
+    warmup = startOn('UDID', Promise.resolve());
+    try {
+      await until(() => extractor !== undefined);
+      await warmup.claimAsync('UDID'); // Only forbids new install; extraction remains owned and pending.
+      expect(extractorClosed).toBe(false);
+      let stopped = false;
+      const stopping = warmup.stopAsync('UDID').then(() => {
+        stopped = true;
+      });
+      await new Promise(resolve => setImmediate(resolve));
+      expect(stopped).toBe(false);
+      expect(removing).not.toHaveBeenCalled();
+      extractor!.child.kill('SIGCONT');
+      await stopping;
+      expect(extractorClosed).toBe(true);
+      expect(removing).toHaveBeenCalledTimes(1);
+      expect(installCalls()).toHaveLength(0);
+      expect(await fs.readdir(directory)).toEqual([]);
+      if (kind !== 'valid') {
+        const extractionError = await extractor!.resultPromise.catch(error => error);
+        expect(extractionError.code).toBeGreaterThan(0);
+      }
+    } finally {
+      // Reap only this test's owned child, including an assertion failure while it is stopped.
+      if (extractor?.child.exitCode == null && extractor?.child.signalCode == null) {
+        extractor?.child.kill('SIGCONT');
+        extractor?.child.kill('SIGKILL');
+      }
+      await extractor?.resultPromise.catch(() => {});
+      removing.mockRestore();
+    }
+  }
+);
+
+it('keeps owned temp files and rejects terminal stop when extractor close is uncertain', async () => {
+  const failure = new Error('extractor close not proved');
+  const remove = jest.spyOn(fs, 'rm');
+  jest.mocked(commands.runAsync).mockImplementationOnce(async file => {
+    expect(file).toBe('/usr/bin/tar');
+    jest.mocked(commands.throwIfCommandCloseTimedOut).mockImplementation(() => {
+      throw failure;
+    });
+    throw failure;
+  });
+  warmup = startOn('UDID', Promise.resolve());
+  await expect(warmup.resultPromise).rejects.toBe(failure);
+  await expect(warmup.stopAsync('UDID')).rejects.toBe(failure);
+  await expect(warmup.claimAsync('UDID')).rejects.toBe(failure);
+  expect(remove).not.toHaveBeenCalled();
+  expect((await fs.readdir(directory)).some(name => name.startsWith('simulator-expo-go-'))).toBe(
+    true
+  );
+  expect(installCalls()).toHaveLength(0);
+});
+
+it.each(['traversal', 'malformed'] as const)(
+  'never installs after a real %s archive failure without a claim',
+  async kind => {
+    archive =
+      kind === 'malformed'
+        ? Buffer.from('not an archive')
+        : createArchive([
+            { name: '../escaped', contents: Buffer.from('unsafe') },
+            { name: 'Info.plist', contents: Buffer.from('<plist>fixture</plist>') },
+          ]);
+    warmup = startOn('UDID', Promise.resolve());
+    await warmup.resultPromise;
+    expect(installCalls()).toHaveLength(0);
+    expect(process.stderr.write).toHaveBeenCalledWith(
+      expect.stringContaining('Could not preinstall Expo Go')
+    );
+    await warmup.stopAsync('UDID');
+    expect(await fs.readdir(directory)).toEqual([]);
+  }
+);
+
+it('claim returns the identity read from the Expo Go it installed', async () => {
+  const plist: Record<string, string> = {
+    CFBundleIdentifier: 'host.exp.Exponent',
+    CFBundleShortVersionString: '58.0.7',
+    CFBundleVersion: '58.0.7',
+  };
+  jest
+    .mocked(commands.runAsync)
+    .mockImplementation(async (file, args, signal) =>
+      file === '/usr/bin/tar'
+        ? await runCommandAsync(file, args, signal)
+        : file === 'plutil'
+          ? `${plist[args[1]]}\n`
+          : ''
+    );
+  warmup = startOn('UDID', Promise.resolve());
+  await warmup.resultPromise;
+  expect(await warmup.claimAsync('UDID')).toEqual({
+    udid: 'UDID',
+    bundleIdentifier: 'host.exp.Exponent',
+    shortVersion: '58.0.7',
+    version: '58.0.7',
+  });
+  const plistPath = jest
+    .mocked(commands.runAsync)
+    .mock.calls.find(([file]) => file === 'plutil')![1];
+  expect(path.basename(path.dirname(plistPath[5]))).toBe('ExpoGo.app');
+});
+
+it('claim returns no identity when the preinstall fails', async () => {
+  jest
+    .mocked(commands.runAsync)
+    .mockImplementation(async (file, args, signal) =>
+      file === '/usr/bin/tar'
+        ? await runCommandAsync(file, args, signal)
+        : file === 'xcrun'
+          ? Promise.reject(Object.assign(new Error('install failed'), { code: 1 }))
+          : ''
+    );
+  warmup = startOn('UDID', Promise.resolve());
+  await warmup.resultPromise;
+  expect(await warmup.claimAsync('UDID')).toBeUndefined();
+  expect(jest.mocked(commands.runAsync).mock.calls.some(([file]) => file === 'plutil')).toBe(false);
+});
+
+it('downloads and extracts once for two devices, then removes the shared app on stop', async () => {
+  warmup = startOn('FIRST', Promise.resolve());
+  await warmup.resultPromise;
+  const app = installCalls()[0][1][3];
+  expect((await fs.stat(app)).isDirectory()).toBe(true);
+  await warmup.preinstallOnDeviceAsync('SECOND', Promise.resolve(), controller.signal);
+  expect(fetch).toHaveBeenCalledTimes(2);
+  expect(
+    jest.mocked(commands.runAsync).mock.calls.filter(([file]) => file === '/usr/bin/tar')
+  ).toHaveLength(1);
+  expect(installCalls().map(([, args]) => args.slice(2))).toEqual([
+    ['FIRST', app],
+    ['SECOND', app],
+  ]);
+  const claimed = await warmup.claimAsync('SECOND');
+  await warmup.stopAsync('SECOND');
+  await expect(fs.stat(app)).rejects.toMatchObject({ code: 'ENOENT' });
+  expect(claimed?.udid).toBe('SECOND');
+});
+it('a claim prevents secondary preinstall from starting and releases the retained archive', async () => {
+  warmup = startOn('FIRST', Promise.resolve());
+  await warmup.resultPromise;
+  await warmup.claimAsync('FIRST');
+  await warmup.preinstallOnDeviceAsync('SECOND', Promise.resolve(), controller.signal);
+  await warmup.stopAsync('FIRST');
+  expect(installCalls()).toHaveLength(1);
+  expect(await fs.readdir(directory)).toEqual([]);
+});
+it('claim and stop drain a secondary native install without cancelling its transaction', async () => {
+  const install = deferred<string>();
+  const original = jest.mocked(commands.runAsync).getMockImplementation()!;
+  warmup = startOn('FIRST', Promise.resolve());
+  await warmup.resultPromise;
+  jest
+    .mocked(commands.runAsync)
+    .mockImplementation((file, args, signal) =>
+      file === 'xcrun' && args.includes('SECOND') ? install.promise : original(file, args, signal)
+    );
+  const secondary = warmup.preinstallOnDeviceAsync('SECOND', Promise.resolve(), controller.signal);
+  let claimed = false;
+  try {
+    await until(() => installCalls().length === 2);
+    const claiming = warmup.claimAsync('SECOND').then(() => {
+      claimed = true;
+    });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(claimed).toBe(false);
+    expect(installCalls()[1][2]).toBeUndefined();
+    install.resolve('');
+    await claiming;
+    await secondary;
+    await warmup.stopAsync('FIRST');
+    expect(await fs.readdir(directory)).toEqual([]);
+  } finally {
+    install.resolve('');
+    await secondary;
+  }
+});
+
+it.each(['signal', 'close timeout'])(
+  'isolates a secondary %s failure from the already-installed default',
+  async kind => {
+    warmup = startOn('FIRST', Promise.resolve());
+    await warmup.resultPromise;
+    const failure = Object.assign(new Error('secondary install failed'), { code: null });
+    const original = jest.mocked(commands.runAsync).getMockImplementation()!;
+    jest.mocked(commands.runAsync).mockImplementation((file, args, signal) => {
+      if (file === 'xcrun' && args.includes('SECOND')) {
+        if (kind === 'close timeout') {
+          jest.mocked(commands.throwIfCommandCloseTimedOut).mockImplementation(() => {
+            throw failure;
+          });
+        }
+        return Promise.reject(failure);
+      }
+      return original(file, args, signal);
+    });
+    await expect(
+      warmup.preinstallOnDeviceAsync('SECOND', Promise.resolve(), controller.signal)
+    ).rejects.toBe(failure);
+    expect((await warmup.claimAsync('FIRST'))?.udid).toBe('FIRST');
+    await expect(warmup.claimAsync('SECOND')).rejects.toBe(failure);
+    if (kind === 'close timeout') {
+      await expect(warmup.stopAsync('FIRST')).rejects.toBe(failure);
+    } else {
+      await expect(warmup.stopAsync('FIRST')).resolves.toBeUndefined();
+    }
+    await expect(warmup.stopAsync('SECOND')).rejects.toBe(failure);
+  }
+);
+it('a concurrent stop cannot miss a secondary install failure while shared cleanup drains', async () => {
+  warmup = startOn('FIRST', Promise.resolve());
+  await warmup.resultPromise;
+  const installation = deferred<string>();
+  const original = jest.mocked(commands.runAsync).getMockImplementation()!;
+  jest
+    .mocked(commands.runAsync)
+    .mockImplementation((file, args, signal) =>
+      file === 'xcrun' && args.includes('SECOND')
+        ? installation.promise
+        : original(file, args, signal)
+    );
+  const secondary = warmup.preinstallOnDeviceAsync('SECOND', Promise.resolve(), controller.signal);
+  void secondary.catch(() => {});
+  try {
+    await until(() => installCalls().length === 2);
+    const stopping = warmup.stopAsync('SECOND');
+    void stopping.catch(() => {});
+    const failure = Object.assign(new Error('secondary killed'), { code: null });
+    installation.reject(failure);
+    await expect(stopping).rejects.toBe(failure);
+    await expect(secondary).rejects.toBe(failure);
+  } finally {
+    installation.resolve('');
+    await secondary.catch(() => {});
+  }
+});
+
+it('preinstalls all three configured devices from one shared archive through the session owner', async () => {
+  const { createWarmSimulatorSession } = await import('../commands/start');
+  const simulator = await import('../utils/simulator');
+  const serveSim = await import('../utils/serveSim');
+  const processes = await import('../utils/processes');
+  const agentDevice = await import('../utils/agentDevice');
+  const argent = await import('../utils/argent');
+  const devices = ['FIRST', 'SECOND', 'THIRD'].map(udid => ({ udid, name: `iPhone ${udid}` }));
+  const environment = { ...process.env };
+  process.env.EXPO_SIMULATOR_DEVICE = devices.map(device => device.udid).join(',');
+  process.env.AGENT_DEVICE_STATE_DIR = path.join(directory, 'agent');
+  process.env.ARGENT_EVENT_LOG = path.join(directory, 'argent-events');
+  jest.spyOn(simulator, 'listAvailableSimulatorsAsync').mockResolvedValue(devices);
+  jest.spyOn(simulator, 'waitForSimulatorBootAsync').mockResolvedValue();
+  jest.spyOn(simulator, 'disableApsdAsync').mockResolvedValue();
+  jest.spyOn(simulator, 'shutdownSimulatorAsync').mockResolvedValue();
+  jest.spyOn(processes, 'stopProcessAndDescendantsAsync').mockResolvedValue();
+  jest.spyOn(agentDevice, 'createAgentDeviceTool').mockReturnValue({
+    name: 'agent-device',
+    startAsync: async () => {},
+    stopAsync: async () => {},
+  });
+  jest
+    .spyOn(argent, 'createArgentTool')
+    .mockReturnValue({ name: 'argent', startAsync: async () => {}, stopAsync: async () => {} });
+  jest.spyOn(serveSim, 'startServeSim').mockReturnValue({
+    child: { pid: 90001 } as import('node:child_process').ChildProcess,
+    resultPromise: new Promise(() => {}),
+  });
+  jest.spyOn(serveSim, 'waitForServeSimReadyAsync').mockResolvedValue({
+    startupDevice: 'FIRST',
+    pid: 90001,
+    port: 3200,
+    nativeStartTime: 'start-time',
+    url: 'http://127.0.0.1:3200',
+    token: 'fixture-token',
+  });
+  const original = jest.mocked(commands.runAsync).getMockImplementation()!;
+  jest.mocked(commands.runAsync).mockImplementation(async (file, args, signal) => {
+    if (file === 'ps') {
+      return 'controller-start';
+    }
+    if (file === 'plutil') {
+      return args.includes('CFBundleIdentifier') ? 'host.exp.Exponent' : '58.0.7';
+    }
+    return original(file, args, signal);
+  });
+  const onFailure = jest.fn();
+  const session = createWarmSimulatorSession({
+    signal: controller.signal,
+    throwIfStoppingAsync: async () => controller.signal.throwIfAborted(),
+    onPreparationFailure: onFailure,
+  });
+  try {
+    await session.prepareAsync();
+    await until(() => installCalls().length === 3);
+    await session.claimAsync({ engine: 'serve-sim', requestedDevice: 'THIRD' });
+    const prepared = await session.prepareToolsAsync();
+    expect(prepared.preinstalledExpoGo).toEqual({
+      udid: 'THIRD',
+      bundleIdentifier: 'host.exp.Exponent',
+      shortVersion: '58.0.7',
+      version: '58.0.7',
+    });
+    expect(installCalls().map(([, args]) => args[2])).toEqual(['FIRST', 'SECOND', 'THIRD']);
+    expect(new Set(installCalls().map(([, args]) => args[3])).size).toBe(1);
+    expect(fetch).toHaveBeenCalledTimes(2);
+    expect(
+      jest.mocked(commands.runAsync).mock.calls.filter(([file]) => file === '/usr/bin/tar')
+    ).toHaveLength(1);
+    expect(onFailure).not.toHaveBeenCalled();
+  } finally {
+    await session.stopAsync();
+    process.env = environment;
+  }
+});