diff --git a/packages/device-selection/src/__tests__/device-selection-resolver.test.ts b/packages/device-selection/src/__tests__/device-selection-resolver.test.ts index e9bc72686e..1e1cb0d9de 100644 --- a/packages/device-selection/src/__tests__/device-selection-resolver.test.ts +++ b/packages/device-selection/src/__tests__/device-selection-resolver.test.ts @@ -74,6 +74,37 @@ test('the booted simulator with the app installed carries its own selected-by re assert.equal(selection.source, 'local'); }); +test('a cross-platform tie fails undispatched, naming only the tied devices and their ids', async () => { + const error = await resolveInventoryDeviceSelection({ + devices: [ + ANDROID_EMULATOR, + IOS_SIMULATOR, + { ...IOS_SIMULATOR, id: 'sim-stopped-1', name: 'iPhone 17', booted: false }, + { ...IOS_SIMULATOR, id: 'sim-stopped-2', name: 'iPhone Air', booted: false }, + ], + selector: {}, + source: 'local', + }).catch((error: unknown) => error); + + assert.ok(error instanceof AppError); + assert.equal(error.code, 'AMBIGUOUS_MATCH'); + assert.equal(error.details?.dispatched, 'no'); + assert.deepEqual(error.details?.devices, [ + { id: ANDROID_EMULATOR.id, name: ANDROID_EMULATOR.name }, + { id: IOS_SIMULATOR.id, name: IOS_SIMULATOR.name }, + ]); + assert.deepEqual(error.details?.retrySelectors, [ + { flag: '--serial', value: ANDROID_EMULATOR.id }, + { flag: '--device', value: ANDROID_EMULATOR.name }, + { flag: '--udid', value: IOS_SIMULATOR.id }, + { flag: '--device', value: IOS_SIMULATOR.name }, + ]); + assert.equal( + error.details?.hint, + `Retry with the id of the intended device: --serial ${ANDROID_EMULATOR.id} or --udid ${IOS_SIMULATOR.id}.`, + ); +}); + test('successful local virtual preparation records the boot event without changing provider evidence', () => { const localSelection = markSelectionBootOccurred({ device: STOPPED_ANDROID_EMULATOR, diff --git a/packages/device-selection/src/__tests__/dispatch-resolve.test.ts b/packages/device-selection/src/__tests__/dispatch-resolve.test.ts index 0939d25d3d..4bc4b24355 100644 --- a/packages/device-selection/src/__tests__/dispatch-resolve.test.ts +++ b/packages/device-selection/src/__tests__/dispatch-resolve.test.ts @@ -472,6 +472,7 @@ test('resolveTargetDevice refuses ambiguous booted simulator app matches', async assert.equal(error.code, 'AMBIGUOUS_MATCH'); assert.match(error.message, /Multiple booted iOS simulators have com\.example\.demo installed/); assert.equal(error.details?.hint, 'Pass --udid to select the intended simulator explicitly.'); + assert.equal(error.details?.dispatched, 'no'); assert.deepEqual(error.details?.devices, [ { id: bootedSimulator.id, name: bootedSimulator.name }, { id: secondBootedSimulator.id, name: secondBootedSimulator.name }, diff --git a/packages/device-selection/src/device-selection-resolver.ts b/packages/device-selection/src/device-selection-resolver.ts index 37a06d1b54..9e9896ad46 100644 --- a/packages/device-selection/src/device-selection-resolver.ts +++ b/packages/device-selection/src/device-selection-resolver.ts @@ -12,6 +12,7 @@ import { matchesDeviceSelector, matchesDeviceNameSelector, platformSelectorsConflict, + preferredDeviceCandidates, type PlatformSelector, pickNewestBootableDevice, resolveDevice, @@ -171,6 +172,7 @@ async function resolveSingleProviderDevice( throw new AppError('AMBIGUOUS_MATCH', 'Multiple provider devices match this request.', { ...deviceCandidateDetails(candidates), matches: candidates.length, + dispatched: 'no', hint: 'Select the leased provider device explicitly with --device, --udid, or --serial.', retrySelectors: retrySelectorsFor(candidates), }); @@ -235,6 +237,7 @@ async function resolveAppInstalledSimulatorSelection( { appTarget, ...deviceCandidateDetails(matches), + dispatched: 'no', hint: 'Pass --udid to select the intended simulator explicitly.', retrySelectors: retrySelectorsFor(matches), }, @@ -247,13 +250,16 @@ function withDeviceRetrySelectors( extraHint?: string, ): unknown { if (!(error instanceof AppError) || error.code !== 'AMBIGUOUS_MATCH') return error; + // The kernel refuses only its equally preferred devices; a lower-ranked or shut-down match is + // no answer to the tie, so only the tied devices become retry selectors. + const tied = preferredDeviceCandidates([...candidates]); return new AppError( error.code, error.message, { ...(error.details ?? {}), - ...deviceCandidateDetails(candidates), - retrySelectors: retrySelectorsFor(candidates), + ...deviceCandidateDetails(tied), + retrySelectors: retrySelectorsFor(tied), ...(extraHint ? { hint: [error.details?.hint, extraHint].filter(Boolean).join(' ') } : {}), }, error, diff --git a/packages/kernel/src/device.ts b/packages/kernel/src/device.ts index 8a741892ce..d223799c0b 100644 --- a/packages/kernel/src/device.ts +++ b/packages/kernel/src/device.ts @@ -780,21 +780,18 @@ function throwAmbiguousDeviceSelection(candidates: DeviceInfo[]): never { // and MCP renderers print these candidates without a new shape to learn. devices: listed.map((device) => ({ id: device.id, name: device.name })), matches: candidates.length, + // Selection precedes every device operation, so a refused tie never reached a device. + dispatched: 'no', hint: buildAmbiguousDeviceHint(listed), }, ); } function buildAmbiguousDeviceHint(candidates: DeviceInfo[]): string { - const first = candidates[0]; - const identitySelector = first - ? `--${deviceIdentityFlag(first.platform) ?? 'udid'} ${first.id}` - : `--udid `; - return ( - `Select the intended device explicitly, for example ${identitySelector} ` + - `or --device ${JSON.stringify(first?.name ?? '')}. ` + - `Run agent-device devices to list them.` + const selectors = candidates.map( + (device) => `--${deviceIdentityFlag(device.platform) ?? 'udid'} ${device.id}`, ); + return `Retry with the id of the intended device: ${selectors.join(' or ')}.`; } /** @@ -803,7 +800,7 @@ function buildAmbiguousDeviceHint(candidates: DeviceInfo[]): string { * comparator's remaining tie-breaks are name order and discovery order, which encode nothing about * intent. */ -function preferredDeviceCandidates(candidates: DeviceInfo[]): DeviceInfo[] { +export function preferredDeviceCandidates(candidates: DeviceInfo[]): DeviceInfo[] { const ranked = isAppleDeviceCandidateSet(candidates) ? candidatesWithBestAppleRank(candidates) : preferVirtualCandidates(candidates);