gwdp · Oct 23, 2026 · Oct 24, 2026 · Oct 24, 2026
diff --git a/.changeset/prepared-simulator-adoption-helpers.md b/.changeset/prepared-simulator-adoption-helpers.md
@@ -0,0 +1,13 @@
+---
+'@expo/build-tools': patch
+---
+
+Add internal helpers for claiming warm iOS Simulator services and validating the device returned by the controller. Start job video recording during adoption before app actions, and collect the server-owned recording without a separate recorder process.
+
+Overlap tunnel opening with adoption, and keep the video-start acknowledgement before app actions. A warm Simulator arrives with apsd already disabled, so the job skips Simulator setup.
+
+Finish pending agent-device artifact uploads and check for final artifacts when a warm session stops.
+
+Open the web preview tunnel while every session host starts, so `openPreviewAsync()` returns the startup tunnel.
+
+Skip installing Expo Go on a warm Simulator when the same Expo Go version is already installed.
diff --git a/packages/build-tools/src/steps/functions/__tests__/deviceSessionHost-orchestration.test.ts b/packages/build-tools/src/steps/functions/__tests__/deviceSessionHost-orchestration.test.ts
@@ -145,7 +145,11 @@ describe.each([
 
   it('holds the host until session completion', async () => {
     await runAsync();
-    expect(openPreview).toHaveBeenCalledWith({ baseDomain: 'example.test', authtoken: 'token' });
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ preview: { baseDomain: 'example.test', authtoken: 'token' } })
+    );
+    expect(openPreview).toHaveBeenCalledWith();
     expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
       expect.objectContaining({
         remoteConfig: expect.objectContaining({

diff --git a/...d-tools/src/steps/functions/__tests__/startAgentDeviceRemoteSession-orchestration.test.ts b/...d-tools/src/steps/functions/__tests__/startAgentDeviceRemoteSession-orchestration.test.ts
@@ -603,10 +603,7 @@ describe('runAgentDeviceRemoteSessionAsync orchestration', () => {
         ctx,
         {} as never
       );
-      const preview = await host.openPreviewAsync({
-        baseDomain: 'tunnel.example.com',
-        authtoken: 'ngrok-token',
-      });
+      const preview = await host.openPreviewAsync();
       jest.mocked(host.openPreviewAsync).mockImplementation(async () => {
         await previewReady.promise;
         return preview;

diff --git a/packages/build-tools/src/steps/functions/__tests__/startArgentRemoteSession.test.ts b/packages/build-tools/src/steps/functions/__tests__/startArgentRemoteSession.test.ts
@@ -1,84 +1,16 @@
-import { SystemError } from '@expo/eas-build-job';
 import { type bunyan } from '@expo/logger';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
 import { Sentry } from '../../../sentry';
 import {
-  MIN_ARGENT_REMOTE_SESSION_VERSION,
   stopArgentEventCollectionSafelyAsync,
   waitForArgentToolServerStateAsync,
-  warnIfArgentPackageVersionCannotBeVerified,
 } from '../startArgentRemoteSession';
 
 jest.mock('../../../sentry');
 
-describe(warnIfArgentPackageVersionCannotBeVerified, () => {
-  const warn = jest.fn();
-  const logger = { warn } as unknown as bunyan;
-  const supportedVersion = '999.0.0';
-  const oldVersion = '0.0.0';
-
-  beforeEach(() => {
-    warn.mockClear();
-  });
-
-  it('allows the default latest package version', () => {
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: undefined, logger })
-    ).not.toThrow();
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: 'latest', logger })
-    ).not.toThrow();
-    expect(warn).not.toHaveBeenCalled();
-  });
-
-  it('allows exact supported semver versions', () => {
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({
-        packageVersion: MIN_ARGENT_REMOTE_SESSION_VERSION,
-        logger,
-      })
-    ).not.toThrow();
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: supportedVersion, logger })
-    ).not.toThrow();
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({
-        packageVersion: `v${supportedVersion}`,
-        logger,
-      })
-    ).not.toThrow();
-    expect(warn).not.toHaveBeenCalled();
-  });
-
-  it('rejects exact semver versions that are too old', () => {
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: oldVersion, logger })
-    ).toThrow(SystemError);
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: oldVersion, logger })
-    ).toThrow(`Use "latest" or pass an exact version >= ${MIN_ARGENT_REMOTE_SESSION_VERSION}`);
-  });
-
-  it('warns for package tags or ranges that cannot be verified', () => {
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({ packageVersion: 'next', logger })
-    ).not.toThrow();
-    expect(() =>
-      warnIfArgentPackageVersionCannotBeVerified({
-        packageVersion: `^${MIN_ARGENT_REMOTE_SESSION_VERSION}`,
-        logger,
-      })
-    ).not.toThrow();
-    expect(warn).toHaveBeenCalledTimes(2);
-    expect(warn).toHaveBeenCalledWith(
-      expect.stringContaining('Continuing and letting the package manager resolve it.')
-    );
-  });
-});
-
 describe(waitForArgentToolServerStateAsync, () => {
   let stateDir: string;
 

diff --git a/packages/build-tools/src/steps/functions/__tests__/startWebPreviewRemoteSession.test.ts b/packages/build-tools/src/steps/functions/__tests__/startWebPreviewRemoteSession.test.ts
@@ -205,6 +205,7 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
       env: childEnv,
       logger,
       timeoutMs: 60_000,
+      preview: { baseDomain: 'tunnel.example.com', authtoken: 'ngrok-token' },
       signal: undefined,
       ...(selectsXcode
         ? {
@@ -224,10 +225,7 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
       networkCaptureFields: [],
     });
     const host = await jest.mocked(startDeviceSessionHostAsync).mock.results[0].value;
-    expect(host.openPreviewAsync).toHaveBeenCalledWith({
-      baseDomain: 'tunnel.example.com',
-      authtoken: 'ngrok-token',
-    });
+    expect(host.openPreviewAsync).toHaveBeenCalledWith();
     expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith({
       ctx,
       deviceRunSessionId: 'device-run-session-id',

diff --git a/packages/build-tools/src/steps/functions/startAgentDeviceRemoteSession.ts b/packages/build-tools/src/steps/functions/startAgentDeviceRemoteSession.ts
@@ -184,6 +184,7 @@ export async function runAgentDeviceRemoteSessionAsync(
       env,
       logger: taskLogger,
       timeoutMs: STARTUP_TIMEOUT_MS,
+      preview: { baseDomain: ngrokTunnelDomain, authtoken: ngrokAuthtoken },
       disableShare,
       privatePreviewUrl,
       frameAncestors,
@@ -197,10 +198,7 @@ export async function runAgentDeviceRemoteSessionAsync(
       application: hostBootedDevice?.application,
     });
     tasks.signal.throwIfAborted();
-    const webPreview = await sessionHost.openPreviewAsync({
-      baseDomain: ngrokTunnelDomain,
-      authtoken: ngrokAuthtoken,
-    });
+    const webPreview = await sessionHost.openPreviewAsync();
     tasks.signal.throwIfAborted();
     taskLogger.info(
       webPreview.sharePageUrl

diff --git a/packages/build-tools/src/steps/functions/startAppiumRemoteSession.ts b/packages/build-tools/src/steps/functions/startAppiumRemoteSession.ts
@@ -161,6 +161,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
           env,
           logger,
           timeoutMs: APPIUM_STARTUP_TIMEOUT_MS,
+          preview: { baseDomain: ngrokTunnelDomain, authtoken: ngrokAuthtoken },
           disableShare: inputs.public_preview?.value === false,
           privatePreviewUrl: inputs.private_preview_url?.value as string | undefined,
           frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
@@ -273,10 +274,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
           logger.info(launchDescription);
         }
         sessionHost ??= (await (hostStartup ??= asyncResult(startHost()))).enforceValue();
-        const webPreview = await sessionHost.openPreviewAsync({
-          baseDomain: ngrokTunnelDomain,
-          authtoken: ngrokAuthtoken,
-        });
+        const webPreview = await sessionHost.openPreviewAsync();
 
         await uploadRemoteSessionConfigWithLocalEgressAsync({
           env,

diff --git a/packages/build-tools/src/steps/functions/startArgentRemoteSession.ts b/packages/build-tools/src/steps/functions/startArgentRemoteSession.ts
@@ -12,7 +12,6 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { setTimeout as setTimeoutAsync } from 'node:timers/promises';
-import semver from 'semver';
 import { z } from 'zod';
 
 import { CustomBuildContext } from '../../customBuildContext';
@@ -21,6 +20,7 @@ import {
   withLocalEgressSession,
 } from '../utils/localEgressSession';
 import { type DeviceSessionHost, startDeviceSessionHostAsync } from '../utils/deviceSessionHost';
+import { validateControllerVersion } from '../utils/controllerVersion';
 import { resolveIosSessionStartupAsync } from '../utils/iosSimulatorSession';
 import {
   createNetworkCaptureInputProviders,
@@ -129,7 +129,12 @@ export function createStartArgentRemoteSessionBuildFunction(
       // A missing or non-positive value disables the idle timeout (opt-in feature).
       const maxIdleTimeMinutes = inputs.max_idle_time_minutes.value as number | undefined;
       const maxDurationSeconds = inputs.max_duration_seconds?.value as number | undefined;
-      warnIfArgentPackageVersionCannotBeVerified({ packageVersion, logger });
+      validateControllerVersion({
+        packageName: ARGENT_PACKAGE_NAME,
+        minimumVersion: MIN_ARGENT_REMOTE_SESSION_VERSION,
+        packageVersion,
+        logger,
+      });
       const versionSpec = packageVersion ?? 'latest';
       const { runtimePlatform } = global;
       if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
@@ -194,6 +199,7 @@ export function createStartArgentRemoteSessionBuildFunction(
           frameAncestors: parseFrameAncestorsInput(inputs.frame_ancestors?.value),
           corsOrigins: parseCorsOriginsInput(inputs.cors_origins?.value),
           timeoutMs: STARTUP_TIMEOUT_MS,
+          preview: { baseDomain: ngrokTunnelDomain, authtoken: ngrokAuthtoken },
           signal: startupSignal,
           onStartupError: iosStartup ? error => startupAbortController.abort(error) : undefined,
           ...launch,
@@ -350,10 +356,7 @@ export function createStartArgentRemoteSessionBuildFunction(
           logger.info(launchDescription);
         }
         sessionHost ??= (await (hostStartup ??= asyncResult(startHost()))).enforceValue();
-        const webPreview = await sessionHost.openPreviewAsync({
-          baseDomain: ngrokTunnelDomain,
-          authtoken: ngrokAuthtoken,
-        });
+        const webPreview = await sessionHost.openPreviewAsync();
         logger.info(
           webPreview.sharePageUrl
             ? `Web preview URL: ${webPreview.sharePageUrl} (server: ${webPreview.apiUrl}).`
@@ -460,36 +463,6 @@ export async function stopArgentEventCollectionSafelyAsync({
   }
 }
 
-export function warnIfArgentPackageVersionCannotBeVerified({
-  packageVersion,
-  logger,
-}: {
-  packageVersion: string | undefined;
-  logger: bunyan;
-}): void {
-  if (!packageVersion || packageVersion === 'latest') {
-    return;
-  }
-
-  const validVersion = semver.valid(packageVersion);
-  if (!validVersion) {
-    logger.warn(
-      `Argent remote simulator sessions require ${ARGENT_PACKAGE_NAME}@${MIN_ARGENT_REMOTE_SESSION_VERSION} or newer, ` +
-        `but package_version "${packageVersion}" is not an exact semver version that EAS can verify. ` +
-        `Continuing and letting the package manager resolve it.`
-    );
-    return;
-  }
-
-  if (semver.lt(validVersion, MIN_ARGENT_REMOTE_SESSION_VERSION)) {
-    throw new SystemError(
-      `Argent remote simulator sessions require ${ARGENT_PACKAGE_NAME}@${MIN_ARGENT_REMOTE_SESSION_VERSION} or newer. ` +
-        `The requested package_version "${packageVersion}" is too old for the EAS remote-session API. ` +
-        `Use "latest" or pass an exact version >= ${MIN_ARGENT_REMOTE_SESSION_VERSION}.`
-    );
-  }
-}
-
 async function runArgentSetupCommandAsync(
   command: string,
   args: string[],

diff --git a/packages/build-tools/src/steps/functions/startWebPreviewRemoteSession.ts b/packages/build-tools/src/steps/functions/startWebPreviewRemoteSession.ts
@@ -106,6 +106,7 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
         env,
         logger,
         timeoutMs: STARTUP_TIMEOUT_MS,
+        preview: { baseDomain: ngrokTunnelDomain, authtoken: ngrokAuthtoken },
         signal,
         packageVersion,
         disableShare: inputs.public_preview?.value === false,
@@ -120,10 +121,7 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
       });
 
       try {
-        const webPreview = await sessionHost.openPreviewAsync({
-          baseDomain: ngrokTunnelDomain,
-          authtoken: ngrokAuthtoken,
-        });
+        const webPreview = await sessionHost.openPreviewAsync();
         logger.info(
           webPreview.sharePageUrl
             ? `Preview URL: ${webPreview.sharePageUrl} (server: ${webPreview.apiUrl}).`