fix(mobile): boot a shut-down device when none is booted and no device is named

Merged
KR
6d ago
+44-20

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) adds pick: '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 newest prefers a phone or tablet over a TV, then the newest OS, then name order (not device age: iPhone 16e sorts before iPhone 17). Several booted matches still fail. Shut-down Android AVDs report no OS version, so on Android the name decides.
  • Docs (mobile.mdx, the device option 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.ts and provider.test.ts now expect { platform: 'ios', pick: 'newest' } for an unscoped boot, and the existing UDID tests still expect no pick. Reverting bootRequest fails all four.
  • Live: MacBook, no simulator booted, a scratch project matching the e2e init iOS preset (Settings app, no device), built packages, main and this branch. On both, agent-device listed the unavailable paired iPhone as booted (callstack/agent-device#4209 above), so e2e logged 1 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 boot refuses, --pick newest boots iPhone 17, two booted devices still refuse).

Made with Claude Opus 5.5 (claude-opus-5-5) in Claude Code, running inside T3 Code.