fix: route xctest runner through usbmux

Author: thymikee

CONTEXT.md

@@ -35,8 +35,8 @@ task touches:
   not the remote client ownership boundary.
 - iOS physical-device control: Apple-local module selected from discovery evidence. CoreDevice
   devices retain the `devicectl` controller; devices found only by `xctrace` use the XCTest
-  controller for readiness, app activation/termination, and runner transport without claiming
-  unsupported app inventory or installation capabilities.
+  controller for readiness, app activation/termination, and cable-bound usbmux runner transport
+  without claiming unsupported app inventory or installation capabilities.
 - Host process primitive: low-level host PID helpers in `src/utils/host-process.ts` for liveness,
   start-time/command reads, process listing, process-tree expansion, PID de-duplication, and
   best-effort signaling. It must not own domain cleanup policy such as browser ownership markers,

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -1363,6 +1363,14 @@ extension RunnerTests {
     case .uptime:
       return executeUptime()
     case .activate:
+      guard
+        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !bundleId.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "activate requires appBundleId"))
+      }
+      // prepareActiveCommandContext already activated this bundle. Keep this case as the
+      // explicit acknowledgement after that preflight, not as a second activation.
       return Response(ok: true, data: DataPayload(message: "app activated"))
     case .terminate:
       guard

src/cli/parser/__tests__/cli-help-topics.test.ts

@@ -472,6 +472,7 @@ test('usageForCommand resolves physical-device help topic', async () => {
   assert.match(help, /AGENT_DEVICE_IOS_BUNDLE_ID=com\.yourname\.agentdevice\.runner/);
   assert.match(help, /profile name\/specifier, not a file path/);
   assert.match(help, /Older devices visible only to xctrace use the XCTest backend automatically/);
+  assert.match(help, /runner commands travel through macOS usbmuxd/);
   assert.match(help, /app inventory, install\/reinstall, deep links, and launch arguments/);
 });
 

src/cli/parser/cli-help.ts

@@ -807,6 +807,7 @@ iOS physical-device prerequisites:
   The device must be paired/trusted, connected, unlocked when needed, and have Developer Mode enabled.
   Modern devices visible to devicectl use CoreDevice. Older devices visible only to xctrace use the XCTest backend automatically.
   XCTest-backed devices must already have the target app installed and should be opened by bundle ID; app inventory, install/reinstall, deep links, and launch arguments require CoreDevice.
+  XCTest-backed runner commands travel through macOS usbmuxd; keep the trusted device connected by cable.
   The AgentDeviceRunner XCTest host must be signed before commands can run on a physical device.
   Start with Automatic Signing and only these env vars:
     AGENT_DEVICE_IOS_TEAM_ID=ABCDE12345

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

@@ -285,6 +285,16 @@ 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 () => {
+  const result = await withDeviceInventoryProvider(
+    async () => [{ ...physical, backend: 'xctest' }],
+    async () => await resolveTargetDevice({ platform: 'ios', udid: physical.id }),
+  );
+
+  assert.equal(result.backend, 'xctest');
+  assert.equal(mockListAppleDevices.mock.calls.length, 0);
+});
+
 test('resolveTargetDevice preserves Apple simulator preference with injected inventory', async () => {
   mockFindBootableIosSimulator.mockResolvedValue(simulator);
 

src/core/capabilities.ts

@@ -114,10 +114,6 @@ export function unsupportedHintForDevice(command: string, device: DeviceInfo): s
   return tryGetPlugin(device.platform)?.capability.unsupportedHintByDefault?.[command]?.(device);
 }
 
-export function deviceBackendForDevice(device: DeviceInfo): string | undefined {
-  return tryGetPlugin(device.platform)?.capability.deviceBackend?.(device);
-}
-
 export function listCapabilityCommands(): string[] {
   return Object.keys(COMMAND_CAPABILITY_MATRIX).sort();
 }

src/core/platform-plugin/plugin.ts

@@ -76,8 +76,6 @@ export type PlatformPlugin = {
     readonly unsupportedHintByDefault?: Readonly<
       Record<string, (device: DeviceInfo) => string | undefined>
     >;
-    /** Device-local execution backend selected from discovery/runtime capability evidence. */
-    readonly deviceBackend?: (device: DeviceInfo) => string | undefined;
   };
   /**
    * The daemon app-log facet (issue #974). `resolveBackend` wraps the platform

src/daemon/__tests__/device-ready.test.ts

@@ -1,5 +1,4 @@
 import { afterEach, beforeEach, expect, test, vi } from 'vitest';
-import assert from 'node:assert/strict';
 import { promises as fs } from 'node:fs';
 import type { DeviceInfo } from '../../kernel/device.ts';
 
@@ -19,12 +18,7 @@ import { runCmd } from '../../utils/exec.ts';
 import { waitForAndroidBoot } from '../../platforms/android/devices.ts';
 import { ensureBootedSimulator } from '../../platforms/apple/core/simulator.ts';
 import { ANDROID_EMULATOR, IOS_DEVICE, IOS_SIMULATOR } from '../../__tests__/test-utils/index.ts';
-import {
-  DEVICE_READY_CACHE_TTL_MS,
-  ensureDeviceReady,
-  parseIosReadyPayload,
-  resolveIosReadyHint,
-} from '../device-ready.ts';
+import { DEVICE_READY_CACHE_TTL_MS, ensureDeviceReady } from '../device-ready.ts';
 
 const mockRunCmd = vi.mocked(runCmd);
 const mockEnsureBootedSimulator = vi.mocked(ensureBootedSimulator);
@@ -130,52 +124,3 @@ test('ensureDeviceReady does not cache failed readiness checks', async () => {
 
   expect(mockEnsureBootedSimulator).toHaveBeenCalledTimes(2);
 });
-
-test('parseIosReadyPayload reads tunnelState from direct connectionProperties', () => {
-  const parsed = parseIosReadyPayload({
-    result: {
-      connectionProperties: {
-        tunnelState: 'connected',
-      },
-    },
-  });
-  assert.equal(parsed.tunnelState, 'connected');
-});
-
-test('parseIosReadyPayload reads tunnelState from nested device connectionProperties', () => {
-  const parsed = parseIosReadyPayload({
-    result: {
-      device: {
-        connectionProperties: {
-          tunnelState: 'connecting',
-        },
-      },
-    },
-  });
-  assert.equal(parsed.tunnelState, 'connecting');
-});
-
-test('parseIosReadyPayload returns empty payload for malformed input', () => {
-  assert.deepEqual(parseIosReadyPayload(null), {});
-  assert.deepEqual(parseIosReadyPayload({}), {});
-  assert.deepEqual(
-    parseIosReadyPayload({
-      result: { connectionProperties: { tunnelState: 123 } },
-    }),
-    {},
-  );
-});
-
-test('resolveIosReadyHint maps known connection errors', () => {
-  const connecting = resolveIosReadyHint('', 'Device is busy (Connecting to iPhone)');
-  assert.match(connecting, /still connecting/i);
-
-  const coreDeviceTimeout = resolveIosReadyHint('CoreDeviceService timed out', '');
-  assert.match(coreDeviceTimeout, /coredevice service/i);
-});
-
-test('resolveIosReadyHint falls back to generic guidance', () => {
-  const hint = resolveIosReadyHint('unexpected failure', '');
-  assert.match(hint, /unlocked/i);
-  assert.match(hint, /xcode/i);
-});

src/daemon/device-ready.ts

@@ -1,18 +1,8 @@
 import { isIosFamily, type DeviceInfo } from '../kernel/device.ts';
-import {
-  parseIosDeviceDetailsPayload,
-  resolveIosPhysicalDeviceControl,
-  resolveIosReadyHint,
-} from '../platforms/apple/core/physical-device-control.ts';
+import { resolveIosPhysicalDeviceControl } from '../platforms/apple/core/physical-device-control.ts';
 import { isActiveProviderDevice } from '../provider-device-runtime.ts';
 import { createTtlMemo } from '../utils/ttl-memo.ts';
 
-export { resolveIosReadyHint };
-export function parseIosReadyPayload(payload: unknown): { tunnelState?: string } {
-  const { tunnelState } = parseIosDeviceDetailsPayload(payload);
-  return tunnelState ? { tunnelState } : {};
-}
-
 // Exported so unit tests can assert TTL behavior without duplicating the value.
 export const DEVICE_READY_CACHE_TTL_MS = 5_000;
 

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

@@ -93,6 +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' }]);
+
+  expect(devices[0]).not.toHaveProperty('backend');
+});
+
 test('devices drops a stray appleOs on a non-Apple device (gated to Apple platforms)', async () => {
   // Regression: appleOs is Apple-only. A malformed/legacy NON-Apple record carrying a
   // valid Apple OS value must NOT surface it — the projection gates on the platform,