refactor: simplify ios physical device transport

Author: thymikee

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

@@ -285,13 +285,13 @@ test('resolveTargetDevice uses injected device inventory without local discovery
   assert.equal(mockListAppleDevices.mock.calls.length, 0);
 });
 
-test('resolveTargetDevice preserves backend evidence from injected inventory', async () => {
+test('resolveTargetDevice preserves physical-device backend evidence from injected inventory', async () => {
   const result = await withDeviceInventoryProvider(
-    async () => [{ ...physical, backend: 'xctest' }],
+    async () => [{ ...physical, iosPhysicalDeviceBackend: 'xctest' }],
     async () => await resolveTargetDevice({ platform: 'ios', udid: physical.id }),
   );
 
-  assert.equal(result.backend, 'xctest');
+  assert.equal(result.iosPhysicalDeviceBackend, 'xctest');
   assert.equal(mockListAppleDevices.mock.calls.length, 0);
 });
 

src/daemon/handlers/__tests__/session-inventory-appleos.test.ts

@@ -93,10 +93,12 @@ test('devices omits appleOs for non-Apple devices', async () => {
   expect(ios?.appleOs).toBe('ios');
 });
 
-test('devices omits internal backend evidence', async () => {
-  const devices = await listPublicDevices([{ ...IOS_SIMULATOR, backend: 'xctest' }]);
+test('devices omits internal physical-device backend evidence', async () => {
+  const devices = await listPublicDevices([
+    { ...IOS_SIMULATOR, iosPhysicalDeviceBackend: 'xctest' },
+  ]);
 
-  expect(devices[0]).not.toHaveProperty('backend');
+  expect(devices[0]).not.toHaveProperty('iosPhysicalDeviceBackend');
 });
 
 test('devices drops a stray appleOs on a non-Apple device (gated to Apple platforms)', async () => {

src/daemon/handlers/session-inventory.ts

@@ -179,7 +179,7 @@ export async function handleSessionInventoryCommands(params: {
 
 function publicDeviceInfo({
   simulatorSetPath: _simulatorSetPath,
-  backend: _backend,
+  iosPhysicalDeviceBackend: _iosPhysicalDeviceBackend,
   appleOs,
   ...device
 }: DeviceInfo): Record<string, unknown> {

src/kernel/device.ts

@@ -38,9 +38,9 @@ export type DeviceInfo = {
   appleOs?: AppleOS;
   booted?: boolean;
   simulatorSetPath?: string;
-  // Internal execution-backend evidence attached by discovery/provider inventory.
+  // Internal physical-iOS execution backend selected during discovery.
   // Public device projections strip this field.
-  backend?: string;
+  iosPhysicalDeviceBackend?: 'coredevice' | 'xctest';
 };
 
 export type DeviceSelector = {

src/platforms/apple/core/__tests__/devices.test.ts

@@ -183,7 +183,7 @@ test('parseXctracePhysicalAppleDevices parses only physical devices from the Dev
       kind: 'device',
       target: 'mobile',
       appleOs: 'ios',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
     {
@@ -193,7 +193,7 @@ test('parseXctracePhysicalAppleDevices parses only physical devices from the Dev
       kind: 'device',
       target: 'tv',
       appleOs: 'tvos',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
   ]);
@@ -211,7 +211,7 @@ test('parseXctracePhysicalAppleDevices tags physical iPads as iPadOS', () => {
       kind: 'device',
       target: 'mobile',
       appleOs: 'ipados',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
   ]);
@@ -229,7 +229,7 @@ test('parseXctracePhysicalAppleDevices tags Apple Vision devices as visionOS', (
       kind: 'device',
       target: 'mobile',
       appleOs: 'visionos',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
   ]);
@@ -253,7 +253,7 @@ test('parseXctracePhysicalAppleDevices parses the parenthesized physical device
       kind: 'device',
       target: 'mobile',
       appleOs: 'ios',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
     {
@@ -263,7 +263,7 @@ test('parseXctracePhysicalAppleDevices parses the parenthesized physical device
       kind: 'device',
       target: 'mobile',
       appleOs: 'ipados',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
     {
@@ -273,7 +273,7 @@ test('parseXctracePhysicalAppleDevices parses the parenthesized physical device
       kind: 'device',
       target: 'tv',
       appleOs: 'tvos',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
   ]);
@@ -292,7 +292,7 @@ test('parseXctracePhysicalAppleDevices preserves parentheses in bracket-format n
       kind: 'device',
       target: 'mobile',
       appleOs: 'ios',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
     {
@@ -302,7 +302,7 @@ test('parseXctracePhysicalAppleDevices preserves parentheses in bracket-format n
       kind: 'device',
       target: 'mobile',
       appleOs: 'ios',
-      backend: 'xctest',
+      iosPhysicalDeviceBackend: 'xctest',
       booted: true,
     },
   ]);
@@ -611,7 +611,7 @@ test('listAppleDevices falls back to xctrace parenthesized devices when devicect
   assert.equal(physicalDevices.length, 1);
   assert.equal(physicalDevices[0]?.id, '00008020-001C2D2234567890');
   assert.equal(physicalDevices[0]?.name, 'iPhone 8 Plus');
-  assert.equal(physicalDevices[0]?.backend, 'xctest');
+  assert.equal(physicalDevices[0]?.iosPhysicalDeviceBackend, 'xctest');
 });
 
 test('listAppleDevices keeps physical discovery disabled for simulator-set scoped runs', async () => {

src/platforms/apple/core/__tests__/physical-device-control.test.ts

@@ -21,7 +21,7 @@ const IOS_DEVICE: DeviceInfo = {
 
 const XCTEST_IOS_DEVICE: DeviceInfo = {
   ...IOS_DEVICE,
-  backend: 'xctest',
+  iosPhysicalDeviceBackend: 'xctest',
 };
 
 test('physical-device backend defaults to CoreDevice and honors discovery evidence', () => {

src/platforms/apple/core/__tests__/runner-transport.test.ts

@@ -51,7 +51,7 @@ const iosDevice: DeviceInfo = {
 
 const xctestIosDevice: DeviceInfo = {
   ...iosDevice,
-  backend: 'xctest',
+  iosPhysicalDeviceBackend: 'xctest',
 };
 
 beforeEach(() => {

src/platforms/apple/core/devices.ts

@@ -249,7 +249,7 @@ function mapDevicectlAppleDevices(payload: DevicectlListDevicesPayload): DeviceI
         resolveDevicectlAppleProductType(device),
         ...resolveDevicectlAppleLabels(device),
       ]),
-      backend: 'coredevice',
+      iosPhysicalDeviceBackend: 'coredevice',
       booted: true,
     });
   }
@@ -285,7 +285,7 @@ function buildXctracePhysicalDevice(
     kind: 'device',
     target,
     appleOs: resolveAppleOs(target, osVersion ? [name, osVersion] : [name]),
-    backend: 'xctest',
+    iosPhysicalDeviceBackend: 'xctest',
     // xctrace lists currently connected devices in the "Devices" section.
     // The "Devices Offline" section is excluded above, so treating these as
     // booted preserves the existing physical-device selection semantics.

src/platforms/apple/core/physical-device-control.ts

@@ -72,7 +72,7 @@ const CONTROLS: Record<IosPhysicalDeviceBackend, IosPhysicalDeviceControl> = {
 };
 
 export function resolveIosPhysicalDeviceControl(device: DeviceInfo): IosPhysicalDeviceControl {
-  return CONTROLS[device.backend === 'xctest' ? 'xctest' : 'coredevice'];
+  return CONTROLS[device.iosPhysicalDeviceBackend === 'xctest' ? 'xctest' : 'coredevice'];
 }
 
 async function ensureXctestDeviceReady(device: DeviceInfo): Promise<void> {

src/platforms/apple/core/runner/runner-command-route.ts

@@ -34,8 +34,9 @@ export function createRunnerCommandRouteResolver(device: DeviceInfo, port: numbe
       }
       const control = resolveIosPhysicalDeviceControl(device);
       if (control.backend === 'xctest') {
+        const transport = await control.resolveRunnerTransport(device, timeoutBudgetMs);
         return {
-          kind: 'usbmux',
+          kind: transport.kind,
           endpoints: [`usbmux://${device.id}:${port}/command`],
           cachedTunnelIp: false,
         };
@@ -48,7 +49,14 @@ export function createRunnerCommandRouteResolver(device: DeviceInfo, port: numbe
         }
       }
       const transport = await control.resolveRunnerTransport(device, timeoutBudgetMs);
-      const tunnelIp = transport.kind === 'network' ? transport.tunnelIp : null;
+      if (transport.kind === 'usbmux') {
+        return {
+          kind: 'usbmux',
+          endpoints: [`usbmux://${device.id}:${port}/command`],
+          cachedTunnelIp: false,
+        };
+      }
+      const tunnelIp = transport.tunnelIp;
       requestTunnelIp = tunnelIp;
       if (tunnelIp) writeDeviceTunnelIpCache(device.id, tunnelIp);
       return buildNetworkRoute(device, port, tunnelIp, false);