fix: select app-bearing simulator for replay (#1387)

* fix(replay): bind app-aware simulator before replay

* fix(replay): preserve deep-link target resolution

* fix(replay): infer iOS app selection without platform

* fix(replay): preserve authored Android selection

* fix(replay): ignore deep links during device binding

* test(replay): cover authored Android platform

* fix(replay): defer binding after deep links

* fix(replay): retain platform before deep links

* fix(open): preserve platformless device resolution

Author: thymikee

src/core/__tests__/dispatch-resolve.test.ts

@@ -185,7 +185,20 @@ test('resolveTargetDevice selects the unique booted simulator with the requested
   );
 });
 
-test('resolveTargetDevice reuses an app-aware selection for later request resolution', async () => {
+test('resolveTargetDevice leaves platform-less static app selection to normal cross-platform resolution', async () => {
+  const result = await withDeviceInventoryProvider(
+    async (request) => {
+      assert.equal(request.platform, undefined);
+      return [androidEmulator, bootedSimulator, secondBootedSimulator];
+    },
+    async () => await resolveTargetDevice({}, { appleSimulatorAppTarget: 'com.example.demo' }),
+  );
+
+  assert.equal(result.id, androidEmulator.id);
+  assert.equal(mockFindIosSimulatorInstalledApp.mock.calls.length, 0);
+});
+
+test('resolveTargetDevice reuses an app-aware iOS selection for later iOS resolution', async () => {
   mockListAppleDevices.mockResolvedValue([bootedSimulator, secondBootedSimulator]);
   mockFindIosSimulatorInstalledApp.mockImplementation(async (device) =>
     device.id === secondBootedSimulator.id ? 'com.example.demo' : undefined,
@@ -233,11 +246,11 @@ test('resolveTargetDevice refuses ambiguous booted simulator app matches', async
   assert.equal(error.details?.hint, 'Pass --udid to select the intended simulator explicitly.');
 });
 
-test('resolveTargetDevice does not probe when an Apple device is explicitly selected', async () => {
+test('resolveTargetDevice preserves an explicit device selector when platform is omitted', async () => {
   mockListAppleDevices.mockResolvedValue([bootedSimulator, secondBootedSimulator]);
 
   const result = await resolveTargetDevice(
-    { platform: 'ios', udid: bootedSimulator.id },
+    { udid: bootedSimulator.id },
     { appleSimulatorAppTarget: 'com.example.demo' },
   );
 

src/core/dispatch-resolve.ts

@@ -211,7 +211,7 @@ export async function resolveTargetDevice(
       }
       const injectedDevices = await readInjectedDeviceInventory(inventoryRequest);
       if (injectedDevices) {
-        if (isAppleResolutionSelector(selector)) {
+        if (shouldUseAppleResolution(selector)) {
           return cacheResolvedTargetDevice(
             cacheKey,
             await resolveAppleDevice(injectedDevices, selector as AppleDeviceSelector, {
@@ -229,7 +229,7 @@ export async function resolveTargetDevice(
 
       const devices = await listLocalDeviceInventory(inventoryRequest);
 
-      if (isAppleResolutionSelector(selector)) {
+      if (shouldUseAppleResolution(selector)) {
         return cacheResolvedTargetDevice(
           cacheKey,
           await resolveAppleDevice(devices, selector as AppleDeviceSelector, {
@@ -325,6 +325,13 @@ function isAppleResolutionSelector(selector: {
   return isApplePlatform(selector.platform);
 }
 
+function shouldUseAppleResolution(selector: {
+  platform?: PlatformSelector;
+  target?: DeviceTarget;
+}): boolean {
+  return isAppleResolutionSelector(selector);
+}
+
 function readResolveTargetDeviceCache(cacheKey: string): DeviceInfo | undefined {
   const cache = resolveTargetDeviceCacheScope.getStore();
   const cached = cache?.get(cacheKey);

src/daemon/__tests__/replay-device-selection.test.ts

@@ -0,0 +1,56 @@
+import { test, expect } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseReplayInput } from '../../compat/replay-input.ts';
+import {
+  buildReplayScriptPlatformFlags,
+  buildReplayTargetDeviceResolution,
+} from '../replay-device-selection.ts';
+
+test('replay leaves deep-link opens to normal device resolution', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-device-selection-'));
+  const replayPath = path.join(root, 'deep-link.ad');
+  fs.writeFileSync(replayPath, 'open demo://checkout\n');
+
+  expect(
+    buildReplayTargetDeviceResolution({
+      token: 'test-token',
+      session: 'default',
+      command: 'replay',
+      positionals: [replayPath],
+      meta: { cwd: root },
+    }),
+  ).toBeUndefined();
+});
+
+test('native replay applies its authored platform before a first deep link', () => {
+  expect(
+    buildReplayScriptPlatformFlags(
+      undefined,
+      parseReplayInput(
+        'runtime set --platform ios --metro-port 8081\nopen demo://checkout\nopen com.example.demo\n',
+        undefined,
+      ).actions,
+    ),
+  ).toEqual({ platform: 'ios' });
+});
+
+test('native replay uses its authored Android runtime setting without an iOS app probe', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-device-selection-'));
+  const replayPath = path.join(root, 'android.ad');
+  fs.writeFileSync(
+    replayPath,
+    'runtime set --platform android --metro-port 8081\nopen com.example.demo\n',
+  );
+
+  expect(
+    buildReplayTargetDeviceResolution({
+      token: 'test-token',
+      session: 'default',
+      command: 'replay',
+      positionals: [replayPath],
+      meta: { cwd: root },
+    }),
+  ).toEqual({ flags: { platform: 'android' }, options: undefined });
+});

src/daemon/__tests__/request-router-open.test.ts

@@ -8,6 +8,7 @@ vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {})
 
 import { dispatchCommand } from '../../core/dispatch.ts';
 import { createRequestHandler } from '../request-router.ts';
+import { resolveRequestExecutionLockKeys } from '../request-binding.ts';
 import { LeaseRegistry } from '../lease-registry.ts';
 import { ensureDeviceReady } from '../device-ready.ts';
 import type { DeviceInfo } from '../../kernel/device.ts';
@@ -29,6 +30,17 @@ function makeIosDevice(id: string): DeviceInfo {
   };
 }
 
+function makeAndroidDevice(id: string): DeviceInfo {
+  return {
+    platform: 'android',
+    id,
+    name: `Android ${id}`,
+    kind: 'emulator',
+    target: 'mobile',
+    booted: true,
+  };
+}
+
 function createOpenHandler(
   sessionStore: ReturnType<typeof makeSessionStore>,
   leaseRegistry = new LeaseRegistry(),
@@ -122,6 +134,94 @@ test('fresh open uses app-aware device selection for advisory locking and dispat
   expect(sessionStore.get('session-app-aware')?.device.id).toBe(appDevice.id);
 });
 
+test('fresh replay reserves its authored app simulator before any replay step', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-app-lock-'));
+  const replayPath = path.join(root, 'flow.ad');
+  fs.writeFileSync(
+    replayPath,
+    'runtime set --platform ios --metro-port 8081\nopen com.example.demo\n',
+  );
+  const sessionStore = makeSessionStore('agent-device-router-replay-lock-');
+  const genericDevice = makeIosDevice('SIM-GENERIC');
+  const appDevice = makeIosDevice('SIM-WITH-APP');
+  mockResolveTargetDevice.mockImplementation(async (_flags, options) =>
+    options?.appleSimulatorAppTarget === 'com.example.demo' ? appDevice : genericDevice,
+  );
+
+  const keys = await resolveRequestExecutionLockKeys({
+    req: {
+      token: 'test-token',
+      session: 'fresh-replay',
+      command: 'replay',
+      positionals: [replayPath],
+      flags: {},
+      meta: { cwd: root },
+    },
+    sessionName: 'fresh-replay',
+    sessionStore,
+  });
+
+  expect(keys).toEqual(['session:fresh-replay', 'device:SIM-WITH-APP']);
+  expect(mockResolveTargetDevice).toHaveBeenCalledWith(
+    { platform: 'ios' },
+    { appleSimulatorAppTarget: 'com.example.demo' },
+  );
+});
+
+test('fresh replay leaves a first deep-link open unbound when a later app target exists', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-deep-link-lock-'));
+  const replayPath = path.join(root, 'flow.ad');
+  fs.writeFileSync(
+    replayPath,
+    'runtime set --platform ios --metro-port 8081\nopen demo://checkout\nopen com.example.demo\n',
+  );
+  const sessionStore = makeSessionStore('agent-device-router-replay-deep-link-lock-');
+
+  const keys = await resolveRequestExecutionLockKeys({
+    req: {
+      token: 'test-token',
+      session: 'fresh-replay-deep-link',
+      command: 'replay',
+      positionals: [replayPath],
+      flags: {},
+      meta: { cwd: root },
+    },
+    sessionName: 'fresh-replay-deep-link',
+    sessionStore,
+  });
+
+  expect(keys).toEqual(['session:fresh-replay-deep-link']);
+  expect(mockResolveTargetDevice).not.toHaveBeenCalled();
+});
+
+test('fresh replay preserves an authored Android platform before advisory locking', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-android-lock-'));
+  const replayPath = path.join(root, 'flow.ad');
+  fs.writeFileSync(
+    replayPath,
+    'runtime set --platform android --metro-port 8081\nopen com.example.demo\n',
+  );
+  const sessionStore = makeSessionStore('agent-device-router-replay-android-lock-');
+  const androidDevice = makeAndroidDevice('ANDROID-EMULATOR');
+  mockResolveTargetDevice.mockResolvedValue(androidDevice);
+
+  const keys = await resolveRequestExecutionLockKeys({
+    req: {
+      token: 'test-token',
+      session: 'fresh-replay-android',
+      command: 'replay',
+      positionals: [replayPath],
+      flags: {},
+      meta: { cwd: root },
+    },
+    sessionName: 'fresh-replay-android',
+    sessionStore,
+  });
+
+  expect(keys).toEqual(['session:fresh-replay-android', 'device:ANDROID-EMULATOR']);
+  expect(mockResolveTargetDevice).toHaveBeenCalledWith({ platform: 'android' }, undefined);
+});
+
 test('open --debug writes bounded open timing diagnostics to requestLogPath', async () => {
   const sessionStore = makeSessionStore('agent-device-router-open-');
   const device = makeIosDevice('SIM-DEBUG');

src/daemon/handlers/__tests__/session-command-replay.test.ts

@@ -111,7 +111,7 @@ test('replay parses inline open runtime flags and replays open with runtime payl
   expect(response?.ok).toBe(true);
   expect(invoked[0]?.command).toBe('open');
   expect(invoked[0]?.positionals).toEqual(['Demo']);
-  expect(invoked[0]?.flags).toEqual({ relaunch: true });
+  expect(invoked[0]?.flags).toEqual({ relaunch: true, platform: 'android' });
   expect(invoked[0]?.runtime).toEqual({
     platform: 'android',
     metroHost: '10.0.0.10',

src/daemon/handlers/__tests__/session-replay-runtime-plan.test.ts

@@ -11,7 +11,10 @@ import path from 'node:path';
 import { runReplayScriptFile } from '../session-replay-runtime.ts';
 import { SessionStore } from '../../session-store.ts';
 import { dispatchCommand, resolveTargetDevice } from '../../../core/dispatch.ts';
-import { makeIosSession } from '../../../__tests__/test-utils/session-factories.ts';
+import {
+  makeAndroidSession,
+  makeIosSession,
+} from '../../../__tests__/test-utils/session-factories.ts';
 import {
   baseReplayRequest as baseReq,
   writeReplayFile,
@@ -395,6 +398,102 @@ test('typed Maestro rejects selectors that conflict with an active session', asy
   expect(invoke).not.toHaveBeenCalled();
 });
 
+test('fresh typed Maestro replay resolves its configured app before runtime defaults', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-maestro-app-selection-'));
+  const sessionStore = new SessionStore(path.join(root, 'sessions'));
+  const flowPath = path.join(root, 'flow.yaml');
+  fs.writeFileSync(flowPath, 'appId: com.example.demo\n---\n- launchApp\n');
+  const genericDevice = { ...makeIosSession('generic').device, id: 'SIM-GENERIC' };
+  const appDevice = { ...makeIosSession('app').device, id: 'SIM-WITH-APP' };
+  mockResolveTargetDevice.mockImplementation(async (_flags, options) =>
+    options?.appleSimulatorAppTarget === 'com.example.demo' ? appDevice : genericDevice,
+  );
+  const invoke = vi.fn(async () => ({ ok: true as const, data: {} }));
+
+  const response = await runReplayScriptFile({
+    req: baseReq({
+      positionals: [flowPath],
+      flags: { replayBackend: 'maestro', platform: 'ios' },
+      runtime: { metroPort: 8081 },
+    }),
+    sessionName: 'default',
+    logPath: path.join(root, 'daemon.log'),
+    sessionStore,
+    invoke,
+  });
+
+  expect(response.ok).toBe(true);
+  expect(mockResolveTargetDevice).toHaveBeenCalledWith(
+    { replayBackend: 'maestro', platform: 'ios' },
+    { appleSimulatorAppTarget: 'com.example.demo' },
+  );
+  expect(invoke).toHaveBeenCalledWith(
+    expect.objectContaining({
+      command: 'open',
+      flags: expect.objectContaining({ udid: 'SIM-WITH-APP' }),
+    }),
+  );
+});
+
+test('native replay applies an authored Android platform to its static app open', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-native-android-selection-'));
+  const sessionStore = new SessionStore(path.join(root, 'sessions'));
+  const replayPath = path.join(root, 'flow.ad');
+  fs.writeFileSync(
+    replayPath,
+    'runtime set --platform android --metro-port 8081\nopen com.example.demo\n',
+  );
+  const invoke = vi.fn(async () => ({ ok: true as const, data: {} }));
+
+  const response = await runReplayScriptFile({
+    req: baseReq({ positionals: [replayPath] }),
+    sessionName: 'default',
+    logPath: path.join(root, 'daemon.log'),
+    sessionStore,
+    invoke,
+  });
+
+  expect(response.ok).toBe(true);
+  expect(invoke).toHaveBeenCalledWith(
+    expect.objectContaining({
+      command: 'open',
+      positionals: ['com.example.demo'],
+      flags: expect.objectContaining({ platform: 'android' }),
+    }),
+  );
+});
+
+test('platform-less typed Maestro replay preserves a resolved Android device', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-maestro-android-selection-'));
+  const sessionStore = new SessionStore(path.join(root, 'sessions'));
+  const flowPath = path.join(root, 'flow.yaml');
+  fs.writeFileSync(flowPath, 'appId: com.example.demo\n---\n- launchApp\n');
+  const androidDevice = { ...makeAndroidSession('android').device, id: 'ANDROID-EMULATOR' };
+  mockResolveTargetDevice.mockResolvedValue(androidDevice);
+  const invoke = vi.fn(async () => ({ ok: true as const, data: {} }));
+
+  const response = await runReplayScriptFile({
+    req: baseReq({
+      positionals: [flowPath],
+      flags: { replayBackend: 'maestro' },
+      runtime: { metroPort: 8081 },
+    }),
+    sessionName: 'default',
+    logPath: path.join(root, 'daemon.log'),
+    sessionStore,
+    invoke,
+  });
+
+  expect(response.ok).toBe(true);
+  expect(mockResolveTargetDevice).toHaveBeenCalledWith({ replayBackend: 'maestro' }, {});
+  expect(invoke).toHaveBeenCalledWith(
+    expect.objectContaining({
+      command: 'open',
+      flags: expect.objectContaining({ platform: 'android', serial: 'ANDROID-EMULATOR' }),
+    }),
+  );
+});
+
 test('typed Maestro resume digest binds effective stored runtime hints', async () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-maestro-session-runtime-'));
   const sessionStore = new SessionStore(path.join(root, 'sessions'));