fix(mobile): boot a shut-down device when none is booted and no device is named
An iOS target with no device, on a Mac where no simulator is booted, fails e2e run in prepare:
ENGINE_FAILURE (launch) boot failed: 43 devices match this request equally; select one explicitly
The e2e init iOS preset writes mobile({ platform: 'ios' }), so the first run of a fresh project hits this on most Macs.
Issue
Refs ENG-1037
Cause
With nothing booted, the pool binds one empty slot, and both warm and the worker's init call devices.boot({ platform: 'ios' }). agent-device ranks every shut-down iPhone simulator equally and throws AMBIGUOUS_MATCH.
Fix
- agent-device 0.21.35 added an opt-in tie-break for exactly this (callstack/agent-device#4042, which replaced the e2e-side pick in #1433). e2e already pins 0.21.36, but never opted in.
bootRequest(packages/mobile/src/pool.ts) addspick: 'newest'when the selection names no device. Both boot calls go through it. A named device, UDID, or serial is sent unchanged.- agent-device's
newestprefers a phone or tablet over a TV, then the newest OS, then name order (not device age:iPhone 16esorts beforeiPhone 17). Several booted matches still fail. Shut-down Android AVDs report no OS version, so on Android the name decides. - Docs (
mobile.mdx, thedeviceoption JSDoc and its reference copy, the skill's setup reference) say how the device is picked.
export function bootRequest(selection: DeviceSelection): DeviceSelection & Pick<DeviceBootOptions, 'pick'> {
const named = selection.device ?? selection.udid ?? selection.serial;
return named === undefined ? { ...selection, pick: 'newest' } : selection;
}
Known gaps, all in agent-device
A Vision Pro simulator can win the pick. agent-device reports visionOS simulators as target: 'mobile' and ranks them level with iPhones under --platform ios, and no selector field excludes them. On equal OS versions the name decides, so Apple Vision Pro beats iPhone 17. Checked with agent-device's own resolveInventoryDeviceSelection on 0.21.36 and on 0.21.37-nightly.20261110.154: shut-down Apple Vision Pro, iPhone 17 Pro, iPhone 17, and iPad Pro, all on 26.1, give Apple Vision Pro; without the Vision Pro, iPhone 17. So on a Mac with the visionOS runtime installed, the run goes from a clear AMBIGUOUS_MATCH to booting the Vision Pro and failing later. Macs without that runtime get the fix. Naming a device avoids both. The real fix is ranking visionOS below iOS in agent-device's pick, not a second picker in e2e (the approach #1433 dropped).
The pick ignores session claims. agent-device's tie-break never reads claimedBy, so two runs starting at once on a cold Mac can both pick the device the first is still booting. Before this PR both failed with AMBIGUOUS_MATCH. Left open for the maintainer in the review thread.
A paired iPhone that isn't connected counts as booted.
Verifying this on a Mac with a paired iPhone turned up callstack/agent-device#4209 (reported from #1528): agent-device lists a paired iPhone that CoreDevice cannot reach as booted: true. With nothing booted, e2e then drives that phone instead of reaching the no-booted path, and the run fails at app launch. The fix, callstack/agent-device#4210, merged on 2026-11-04, after 0.21.36, so it is only in nightlies. No e2e change is needed for it: the pool already reads booted. Once agent-device 0.21.37 ships, a bump picks it up, and ENG-1037 can be closed after a live run on a Mac with a paired phone.
Verified
Ran it locally: no - the live simulator run was blocked by callstack/agent-device#4209 (above); unit tests only.
- Unit:
tests/unit/engine.test.tsandprovider.test.tsnow expect{ platform: 'ios', pick: 'newest' }for an unscoped boot, and the existing UDID tests still expect nopick. RevertingbootRequestfails all four. - Live: MacBook, no simulator booted, a scratch project matching the
e2e initiOS preset (Settings app, nodevice), built packages, main and this branch. On both, agent-device listed the unavailable paired iPhone as booted (callstack/agent-device#4209 above), so e2e logged1 booted ios device(s); driving 1: <the paired iPhone>and never reached the changed code. No simulator was booted. - Upstream: callstack/agent-device#4042 checked the same scenario live on agent-device (plain
bootrefuses,--pick newestboots iPhone 17, two booted devices still refuse).
Made with Claude Opus 5.5 (claude-opus-5-5) in Claude Code, running inside T3 Code.