@houwert/conductor 0.30.0 → 0.31.0

package/dist/commands/install-app.js

@@ -8,6 +8,7 @@ const sdk_js_1 = require("../android/sdk.js");
 const session_js_1 = require("../session.js");
 const output_js_1 = require("../output.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
+const devicectl_js_1 = require("../drivers/devicectl.js");
 const cli_js_1 = require("../drivers/vega/cli.js");
 async function resolveDeviceId(sessionName) {
     if (sessionName !== 'default')
@@ -46,10 +47,21 @@ async function installApp(appPath, opts = {}, sessionName = 'default') {
         }
     }
     else if (platform === 'ios' || platform === 'tvos') {
-        const result = await (0, runner_js_1.spawnCommand)('xcrun', ['simctl', 'install', deviceId, appPath]);
-        if (!result.success) {
-            (0, output_js_1.printError)(`install-app failed: ${result.stderr}`, opts);
-            return 1;
+        if ((await (0, bootstrap_js_1.detectDeviceKind)(deviceId)) === 'physical') {
+            try {
+                await (0, devicectl_js_1.installApp)(deviceId, appPath);
+            }
+            catch (e) {
+                (0, output_js_1.printError)(`install-app failed: ${e instanceof Error ? e.message : String(e)}`, opts);
+                return 1;
+            }
+        }
+        else {
+            const result = await (0, runner_js_1.spawnCommand)('xcrun', ['simctl', 'install', deviceId, appPath]);
+            if (!result.success) {
+                (0, output_js_1.printError)(`install-app failed: ${result.stderr}`, opts);
+                return 1;
+            }
         }
     }
     else {

package/dist/commands/list-apps.js

@@ -8,6 +8,7 @@ const sdk_js_1 = require("../android/sdk.js");
 const session_js_1 = require("../session.js");
 const output_js_1 = require("../output.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
+const devicectl_js_1 = require("../drivers/devicectl.js");
 const cli_js_1 = require("../drivers/vega/cli.js");
 async function resolveDeviceId(sessionName) {
     if (sessionName !== 'default')
@@ -38,6 +39,16 @@ async function listApps(opts = {}, sessionName = 'default') {
         // Vega is driven through Amazon's CLI, not adb; strip the `vega:` id prefix.
         appIds = (await new cli_js_1.VegaCli(deviceId.replace(/^vega:/, '')).listInstalledApps()).sort();
     }
+    else if ((platform === 'ios' || platform === 'tvos') &&
+        (await (0, bootstrap_js_1.detectDeviceKind)(deviceId)) === 'physical') {
+        try {
+            appIds = (await (0, devicectl_js_1.listApps)(deviceId)).map((a) => a.id).sort();
+        }
+        catch (e) {
+            (0, output_js_1.printError)(`list-apps failed: ${e instanceof Error ? e.message : String(e)}`, opts);
+            return 1;
+        }
+    }
     else if (platform === 'ios' || platform === 'tvos') {
         const result = await (0, runner_js_1.spawnCommand)('bash', [
             '-c',

package/dist/commands/list-devices.js

@@ -18,6 +18,7 @@ const protocol_js_1 = require("../daemon/protocol.js");
 const cli_js_1 = require("../drivers/vega/cli.js");
 const discovery_js_1 = require("../drivers/roku/discovery.js");
 const cdp_discovery_js_1 = require("../drivers/cdp-discovery.js");
+const devicectl_js_1 = require("../drivers/devicectl.js");
 // Captured during discoverAvailableDevices so listDevices() can report it.
 // Module-scoped because the discover function returns Device[]; bolting an
 // extra return field onto the public type would ripple beyond this fix.
@@ -110,6 +111,18 @@ async function discoverBootedDevices() {
             }
         }
     }
+    // Physical iOS/tvOS devices: paired and reachable is the closest analogue to
+    // a booted simulator — that's when conductor can actually drive them.
+    for (const d of await (0, devicectl_js_1.listPhysicalDevices)()) {
+        if (!d.available)
+            continue;
+        devices.push({
+            id: d.identifier,
+            name: d.name,
+            platform: d.platform,
+            status: d.developerModeEnabled ? 'connected' : 'developer mode off',
+        });
+    }
     // Vega (Amazon Fire TV): booted devices reported by the vega CLI. Best-effort —
     // the CLI is absent unless the Vega SDK is installed.
     try {
@@ -166,6 +179,18 @@ async function discoverAvailableDevices() {
             // ignore parse errors
         }
     }
+    // Physical devices that aren't currently reachable — listed so users can see
+    // why a device they expect is missing.
+    for (const d of await (0, devicectl_js_1.listPhysicalDevices)()) {
+        if (d.available)
+            continue;
+        devices.push({
+            id: d.identifier,
+            name: d.name,
+            platform: d.platform,
+            status: 'unavailable',
+        });
+    }
     // Android: list available AVDs
     const emu = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('emulator'), ['-list-avds'], {
         env: (0, sdk_js_1.androidSpawnEnv)(),

package/dist/commands/press-key.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ANDROID_KEYCODE = exports.VALID_KEYS = exports.HELP = void 0;
+exports.ANDROID_KEYCODE = exports.TVOS_REMOTE_BUTTONS = exports.VALID_KEYS = exports.HELP = void 0;
 exports.dispatchKey = dispatchKey;
 exports.pressKey = pressKey;
 exports.HELP = `  press-key <key>                     Press a key (Enter, Backspace, Home, ...)
@@ -59,6 +59,12 @@ exports.VALID_KEYS = [
     'Remote Info',
     'Remote Instant Replay',
     'Remote Search',
+    'Remote Page Up',
+    'Remote Page Down',
+    'Remote Guide',
+    'Remote TV Provider',
+    'Remote One Two Three',
+    'Remote Four Colors',
 ];
 // iOS XCTest pressKey accepts these values (maps to XCUIKeyboardKey)
 const IOS_KEY_MAP = {
@@ -74,7 +80,9 @@ const IOS_BUTTON_MAP = {
     Power: 'lock',
 };
 // tvOS remote: map key names to pressButton values
-const TVOS_REMOTE_BUTTONS = {
+// Page Up/Down and Guide need tvOS 14.3; the last three need tvOS 18.1. The
+// driver reports a precondition error when the device's OS is older.
+exports.TVOS_REMOTE_BUTTONS = {
     'Remote Dpad Up': 'up',
     'Remote Dpad Down': 'down',
     'Remote Dpad Left': 'left',
@@ -82,6 +90,12 @@ const TVOS_REMOTE_BUTTONS = {
     'Remote Dpad Center': 'select',
     'Remote Menu': 'menu',
     'Remote Media Play Pause': 'playPause',
+    'Remote Page Up': 'pageUp',
+    'Remote Page Down': 'pageDown',
+    'Remote Guide': 'guide',
+    'Remote TV Provider': 'tvProvider',
+    'Remote One Two Three': 'oneTwoThree',
+    'Remote Four Colors': 'fourColors',
 };
 // vega (Amazon Fire TV) remote: map key names to VegaDriver button values.
 const VEGA_REMOTE_BUTTONS = {
@@ -139,6 +153,10 @@ exports.ANDROID_KEYCODE = {
     'Remote Info': 165,
     'Remote Instant Replay': 273, // KEYCODE_MEDIA_SKIP_BACKWARD
     'Remote Search': 84,
+    // Paging keys — the fast way through a long list. Whether a given app honours
+    // them varies, the same as on tvOS.
+    'Remote Page Up': 92,
+    'Remote Page Down': 93,
 };
 /**
  * Send `key` on an already-connected driver. Split out of `pressKey` so
@@ -148,7 +166,7 @@ exports.ANDROID_KEYCODE = {
 async function dispatchKey(driver, matched, holdSeconds) {
     if (driver instanceof ios_js_1.IOSDriver) {
         if (driver.platform === 'tvos') {
-            const tvosButton = TVOS_REMOTE_BUTTONS[matched];
+            const tvosButton = exports.TVOS_REMOTE_BUTTONS[matched];
             const iosButton = IOS_BUTTON_MAP[matched];
             if (tvosButton) {
                 await driver.pressButton(tvosButton, holdSeconds);

package/dist/commands/stop-device.js

@@ -10,6 +10,7 @@ const sdk_js_1 = require("../android/sdk.js");
 const output_js_1 = require("../output.js");
 const client_js_1 = require("../daemon/client.js");
 const list_devices_js_1 = require("./list-devices.js");
+const bootstrap_js_1 = require("../drivers/bootstrap.js");
 // ── iOS / tvOS ───────────────────────────────────────────────────────────────
 async function shutdownSimulator(udid) {
     const result = await (0, runner_js_1.spawnCommand)('xcrun', ['simctl', 'shutdown', udid]);
@@ -55,7 +56,12 @@ async function stopDevice(nameOrId, opts, flags) {
             if (d.platform === 'roku' && !includeRoku)
                 continue;
             try {
-                if (d.platform === 'ios' || d.platform === 'tvos') {
+                if ((d.platform === 'ios' || d.platform === 'tvos') &&
+                    (await (0, bootstrap_js_1.detectDeviceKind)(d.id)) === 'physical') {
+                    // Real hardware can't be shut down from here — just release our driver.
+                    await (0, client_js_1.stopDaemon)(d.id);
+                }
+                else if (d.platform === 'ios' || d.platform === 'tvos') {
                     await shutdownSimulator(d.id);
                 }
                 else if (d.platform === 'android') {
@@ -101,7 +107,12 @@ async function stopDevice(nameOrId, opts, flags) {
         return 1;
     }
     try {
-        if (match.platform === 'ios' || match.platform === 'tvos') {
+        if ((match.platform === 'ios' || match.platform === 'tvos') &&
+            (await (0, bootstrap_js_1.detectDeviceKind)(match.id)) === 'physical') {
+            // Real hardware can't be shut down from here — just release our driver.
+            await (0, client_js_1.stopDaemon)(match.id);
+        }
+        else if (match.platform === 'ios' || match.platform === 'tvos') {
             await shutdownSimulator(match.id);
         }
         else if (match.platform === 'android') {

package/dist/commands/swipe.js

@@ -26,8 +26,10 @@ async function swipe(direction, opts = {}, sessionName = 'default', flags = {})
     }
     const result = await (0, runner_js_1.runDirect)(async (driver) => {
         if (driver instanceof ios_js_1.IOSDriver && driver.platform === 'tvos') {
-            throw new Error('swipe is not supported on tvOS — Apple TV uses focus-based navigation.\n' +
-                'Use press-key to navigate (e.g. conductor press-key left).');
+            throw new Error('swipe is not supported on tvOS — XCTest has no Siri Remote touch-surface\n' +
+                'gesture ("Swipe events are only implemented for iOS, visionOS, and watchOS").\n' +
+                'Navigate with press-key "Remote Dpad Left"/"Right"/"Up"/"Down", or cover\n' +
+                'long lists faster with press-key "Remote Page Up"/"Remote Page Down".');
         }
         let startX, startY, endX, endY;
         if (driver instanceof ios_js_1.IOSDriver) {

package/dist/daemon/input-backends.js

@@ -34,6 +34,15 @@ const IOS_BUTTON = {
     ArrowDown: 'down',
     ArrowLeft: 'left',
     ArrowRight: 'right',
+    // Newer remote buttons; the driver rejects these on older tvOS.
+    pageUp: 'pageUp',
+    PageUp: 'pageUp',
+    pageDown: 'pageDown',
+    PageDown: 'pageDown',
+    guide: 'guide',
+    tvProvider: 'tvProvider',
+    oneTwoThree: 'oneTwoThree',
+    fourColors: 'fourColors',
 };
 function iosBackend(driver) {
     let size = null;
@@ -52,7 +61,23 @@ function iosBackend(driver) {
                 touch: true,
                 drag: true,
                 multitouch: true,
-                buttons: ['home', 'lock'],
+                // Advertise what this platform actually accepts so clients can hide
+                // controls rather than discover failures at press time.
+                buttons: tvos
+                    ? [
+                        'home',
+                        'menu',
+                        'select',
+                        'up',
+                        'down',
+                        'left',
+                        'right',
+                        'playPause',
+                        'pageUp',
+                        'pageDown',
+                        'guide',
+                    ]
+                    : ['home', 'lock'],
                 keyboard: true,
                 text: true,
                 tvRemote: tvos,

package/dist/daemon/log-collector.js

@@ -35,6 +35,7 @@ const android_js_1 = require("../drivers/log-sources/android.js");
 const vega_js_1 = require("../drivers/log-sources/vega.js");
 const metro_js_1 = require("../drivers/log-sources/metro.js");
 const metro_discovery_js_1 = require("../drivers/log-sources/metro-discovery.js");
+const bootstrap_js_1 = require("../drivers/bootstrap.js");
 const MAX_BUFFER = 5000;
 const RESTART_DELAY_MS = 2000;
 const WEB_POLL_INTERVAL_MS = 500;
@@ -145,6 +146,11 @@ class LogCollector {
             return;
         try {
             if (this.platform === 'ios' || this.platform === 'tvos') {
+                // `simctl spawn ... log stream` has no devicectl equivalent, so OS logs
+                // are simulator-only. Metro still streams over the network below, which
+                // is the useful source for React Native apps anyway.
+                if ((await (0, bootstrap_js_1.detectDeviceKind)(this.deviceId)) === 'physical')
+                    return;
                 this.source = new ios_js_1.IOSLogSource(this.deviceId, this.appId);
             }
             else if (this.platform === 'android') {

package/dist/daemon/server.js

@@ -84,6 +84,20 @@ function dlog(msg) {
 // ── Driver lifecycle ──────────────────────────────────────────────────────────
 let driverPort = 1075;
 let driverPlatform = 'ios';
+/**
+ * Host the driver is reachable on. Simulators and every non-Apple platform use
+ * the host's loopback; a physical device runs the driver on its own, so we talk
+ * to it over the network. Memoised — resolution goes through mDNS.
+ */
+let _driverHost = null;
+async function driverHost() {
+    if (_driverHost)
+        return _driverHost;
+    if (driverPlatform !== 'ios' && driverPlatform !== 'tvos')
+        return '127.0.0.1';
+    _driverHost = await (0, bootstrap_js_1.resolveDriverHost)(sessionName).catch(() => '127.0.0.1');
+    return _driverHost;
+}
 let logCollector = null;
 let inputServer = null;
 let inputPort = null;
@@ -109,7 +123,7 @@ async function startInputServerForPlatform() {
         makeBackend = () => (0, input_backends_js_1.androidBackend)(driver);
     }
     else {
-        const driver = new ios_js_1.IOSDriver(driverPort, '127.0.0.1', sessionName, driverPlatform);
+        const driver = new ios_js_1.IOSDriver(driverPort, await driverHost(), sessionName, driverPlatform, (await (0, bootstrap_js_1.detectDeviceKind)(sessionName)) === 'physical');
         makeBackend = () => (0, input_backends_js_1.iosBackend)(driver);
         // Opt-in native held-touch backend for live drags (iOS only; single-touch).
         if (driverPlatform === 'ios' && process.env.CONDUCTOR_IOS_HID === '1') {
@@ -154,6 +168,12 @@ async function startVideoServerForPlatform() {
         return;
     if (driverPlatform !== 'ios' && driverPlatform !== 'tvos')
         return;
+    // Capture attaches to the Simulator's framebuffer via SimulatorKit, which has
+    // no counterpart on real hardware.
+    if ((await (0, bootstrap_js_1.detectDeviceKind)(sessionName)) === 'physical') {
+        dlog('video capture is simulator-only — stream server disabled for this device');
+        return;
+    }
     const binary = await (0, bootstrap_js_1.getCaptureBinaryPath)();
     if (!binary) {
         dlog('video capture binary not present — stream server disabled for this device');
@@ -189,11 +209,13 @@ async function ensureDriverRunning() {
         probe.close();
     }
     else {
-        // 'ios', 'tvos', and 'web' all use an HTTP server — port open = alive
-        alive = await (0, bootstrap_js_1.isPortOpen)(driverPort);
+        // 'ios', 'tvos', and 'web' all use an HTTP server — port open = alive.
+        // Physical devices answer on the LAN rather than the host's loopback.
+        alive = await (0, bootstrap_js_1.isPortOpen)(driverPort, await driverHost());
     }
     if (!alive) {
         if ((driverPlatform === 'ios' || driverPlatform === 'tvos') &&
+            (await (0, bootstrap_js_1.detectDeviceKind)(sessionName)) === 'simulator' &&
             !(await (0, bootstrap_js_1.isSimulatorBooted)(sessionName))) {
             dlog(`Simulator ${sessionName} is not booted — skipping driver restart`);
             return;
@@ -201,7 +223,11 @@ async function ensureDriverRunning() {
         _restartInProgress = true;
         dlog(`Driver on port ${driverPort} not responding — restarting`);
         try {
-            if (driverPlatform === 'ios') {
+            if ((driverPlatform === 'ios' || driverPlatform === 'tvos') &&
+                (await (0, bootstrap_js_1.detectDeviceKind)(sessionName)) === 'physical') {
+                await (0, bootstrap_js_1.startDeviceDriver)(sessionName, driverPlatform, driverPort);
+            }
+            else if (driverPlatform === 'ios') {
                 await (0, bootstrap_js_1.startIOSDriver)(sessionName, driverPort);
             }
             else if (driverPlatform === 'tvos') {
@@ -333,7 +359,10 @@ async function main() {
             else {
                 dlog(`Stopping driver on port ${driverPort}`);
                 try {
-                    if (driverPlatform === 'ios') {
+                    if (driverPlatform === 'ios' && (await (0, bootstrap_js_1.detectDeviceKind)(sessionName)) === 'physical') {
+                        await (0, bootstrap_js_1.stopDeviceDriver)(sessionName, 'ios');
+                    }
+                    else if (driverPlatform === 'ios') {
                         await (0, bootstrap_js_1.stopIOSDriver)(sessionName);
                     }
                     else {
@@ -510,7 +539,7 @@ async function startDriverForPlatform(platform) {
     }
     else {
         // 'ios', 'tvos', and 'web' all use an HTTP server — port open = alive
-        driverAlive = await (0, bootstrap_js_1.isPortOpen)(driverPort);
+        driverAlive = await (0, bootstrap_js_1.isPortOpen)(driverPort, await driverHost());
     }
     if (driverAlive) {
         _driverStarted = true;
@@ -533,7 +562,11 @@ async function startDriverForPlatform(platform) {
     }
     dlog(`Starting ${platform} driver on port ${driverPort}`);
     try {
-        if (platform === 'ios') {
+        if ((platform === 'ios' || platform === 'tvos') &&
+            (await (0, bootstrap_js_1.detectDeviceKind)(sessionName)) === 'physical') {
+            await (0, bootstrap_js_1.startDeviceDriver)(sessionName, platform, driverPort);
+        }
+        else if (platform === 'ios') {
             await (0, bootstrap_js_1.startIOSDriver)(sessionName, driverPort);
         }
         else if (platform === 'tvos') {

package/dist/drivers/bootstrap.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectPlatform = detectPlatform;
+exports.detectDeviceKind = detectDeviceKind;
+exports.resolveDriverHost = resolveDriverHost;
 exports.getDriverPort = getDriverPort;
 exports.getInputPort = getInputPort;
 exports.getStreamPort = getStreamPort;
@@ -18,6 +20,9 @@ exports.stopIOSDriver = stopIOSDriver;
 exports.setupTvOSDriverCache = setupTvOSDriverCache;
 exports.startTvOSDriver = startTvOSDriver;
 exports.stopTvOSDriver = stopTvOSDriver;
+exports.resolveTeamId = resolveTeamId;
+exports.startDeviceDriver = startDeviceDriver;
+exports.stopDeviceDriver = stopDeviceDriver;
 exports.startAndroidDriver = startAndroidDriver;
 exports.stopAndroidDriver = stopAndroidDriver;
 exports.webBrowserName = webBrowserName;
@@ -48,6 +53,7 @@ const path_1 = __importDefault(require("path"));
 const verbose_js_1 = require("../verbose.js");
 const utils_js_1 = require("../utils.js");
 const sdk_js_1 = require("../android/sdk.js");
+const devicectl_js_1 = require("./devicectl.js");
 /** Cache: deviceId → platform */
 const _platformCache = new Map();
 async function detectPlatform(deviceId) {
@@ -68,9 +74,11 @@ async function detectPlatform(deviceId) {
         _platformCache.set(deviceId, 'roku');
         return 'roku';
     }
-    // Check if it looks like an iOS/tvOS simulator UUID (8-4-4-4-12 hex chars)
-    const iosUuidRe = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
-    if (iosUuidRe.test(deviceId)) {
+    // Simulator UDIDs and CoreDevice identifiers share the 8-4-4-4-12 UUID shape;
+    // physical devices additionally answer to their 40-hex hardware UDID.
+    const appleUuidRe = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
+    const appleUdidRe = /^[0-9a-f]{40}$/i;
+    if (appleUuidRe.test(deviceId) || appleUdidRe.test(deviceId)) {
         // Query simctl to determine whether this UUID belongs to a tvOS runtime
         try {
             const out = await spawnCapture('xcrun', ['simctl', 'list', 'devices', '--json']);
@@ -79,12 +87,20 @@ async function detectPlatform(deviceId) {
                 if (sims.some((s) => s.udid === deviceId)) {
                     const platform = runtime.includes('tvOS') ? 'tvos' : 'ios';
                     _platformCache.set(deviceId, platform);
+                    _kindCache.set(deviceId, 'simulator');
                     return platform;
                 }
             }
         }
         catch {
-            /* fall through to ios default */
+            /* fall through to devicectl */
+        }
+        // Not a simulator — ask CoreDevice whether it's a paired physical device.
+        const physical = await (0, devicectl_js_1.findPhysicalDevice)(deviceId);
+        if (physical) {
+            _platformCache.set(deviceId, physical.platform);
+            _kindCache.set(deviceId, 'physical');
+            return physical.platform;
         }
         _platformCache.set(deviceId, 'ios');
         return 'ios';
@@ -93,6 +109,40 @@ async function detectPlatform(deviceId) {
     _platformCache.set(deviceId, 'android');
     return 'android';
 }
+/** Cache: deviceId → simulator vs physical. Populated as a side effect of detectPlatform. */
+const _kindCache = new Map();
+/**
+ * Whether the device is a real one rather than a simulator. Only meaningful for
+ * iOS/tvOS; everything else reports 'simulator' since the distinction is either
+ * absent (web) or already encoded in the driver (Android adb, Vega).
+ */
+async function detectDeviceKind(deviceId) {
+    if (_kindCache.has(deviceId))
+        return _kindCache.get(deviceId);
+    const platform = await detectPlatform(deviceId);
+    if (platform !== 'ios' && platform !== 'tvos') {
+        _kindCache.set(deviceId, 'simulator');
+        return 'simulator';
+    }
+    // detectPlatform records the kind for Apple devices it recognised; anything
+    // still unset never matched simctl or devicectl, so treat it as a simulator.
+    const kind = _kindCache.get(deviceId) ?? 'simulator';
+    _kindCache.set(deviceId, kind);
+    return kind;
+}
+/**
+ * Host the XCTest driver for this device is reachable on. Simulators share the
+ * host's loopback; physical devices run the driver on their own loopback, so we
+ * reach them over the LAN instead.
+ */
+async function resolveDriverHost(deviceId) {
+    if ((await detectDeviceKind(deviceId)) !== 'physical')
+        return '127.0.0.1';
+    const device = await (0, devicectl_js_1.findPhysicalDevice)(deviceId);
+    if (!device)
+        throw new Error(`Physical device ${deviceId} is no longer paired`);
+    return (0, devicectl_js_1.resolveDeviceHost)(device);
+}
 // ── Port management ───────────────────────────────────────────────────────────
 const IOS_BASE_PORT = 1075;
 const TVOS_BASE_PORT = 2075;
@@ -723,6 +773,179 @@ async function startTvOSDriver(deviceId, port = TVOS_BASE_PORT, restoreFocusAfte
 async function stopTvOSDriver(deviceId) {
     await spawnAndWait('xcrun', ['simctl', 'terminate', deviceId, TVOS_RUNNER_BUNDLE_ID]);
 }
+// ── Physical device bootstrap ─────────────────────────────────────────────────
+const DEVICE_STARTUP_TIMEOUT_MS = 300000;
+const DEVICE_STARTUP_POLL_MS = 1000;
+/**
+ * Resolve the Apple Developer team to sign the driver with.
+ *
+ * Unlike simulators, a real device only runs code signed for a team it's
+ * provisioned against, and we can't ship a signed driver — it has to be built
+ * on the user's machine with their credentials.
+ */
+async function resolveTeamId() {
+    const fromEnv = process.env.CONDUCTOR_TEAM_ID?.trim();
+    if (fromEnv)
+        return fromEnv;
+    // Fall back to the keychain when there's exactly one development team, which
+    // is the common single-account setup.
+    let identities;
+    try {
+        identities = await spawnCapture('security', ['find-identity', '-v', '-p', 'codesigning']);
+    }
+    catch {
+        identities = '';
+    }
+    const teams = new Set([...identities.matchAll(/"Apple Development:[^"]*\(([A-Z0-9]{10})\)"/g)].map((m) => m[1]));
+    if (teams.size === 1)
+        return [...teams][0];
+    throw new Error(teams.size === 0
+        ? 'No "Apple Development" signing identity found. Running on a physical device needs one — ' +
+            'sign in to Xcode ▸ Settings ▸ Accounts, then set CONDUCTOR_TEAM_ID=<team> if you have several teams.'
+        : `Multiple development teams found (${[...teams].join(', ')}). ` +
+            'Set CONDUCTOR_TEAM_ID=<team> to pick one.');
+}
+/** Where the signed device driver for a given platform + team is cached. */
+function deviceDriverCache(platform, teamId) {
+    return path_1.default.join(os_1.default.homedir(), '.conductor', `${platform}-driver-device`, teamId);
+}
+/**
+ * Build and sign the XCTest driver for a physical device.
+ *
+ * The bundled simulator builds are unsigned and the wrong slice, so the driver
+ * is compiled from the sources shipped alongside them. Building against the
+ * device (rather than a generic destination) lets Xcode register it with the
+ * team's provisioning profile on first run.
+ */
+async function setupDeviceDriver(deviceId, platform, teamId) {
+    const driversDir = await getDriversDir();
+    const projectDir = path_1.default.join(driversDir, 'ios-driver-src');
+    const project = path_1.default.join(projectDir, 'conductor-driver-ios.xcodeproj');
+    if (!fs_1.default.existsSync(project)) {
+        throw new Error(`Conductor driver sources not found at ${projectDir}.\n` +
+            `Physical devices need a locally signed driver build. Run 'make package-drivers-tarball' ` +
+            `from the repo root, or reinstall conductor to fetch a driver bundle that includes sources.`);
+    }
+    const cache = deviceDriverCache(platform, teamId);
+    const scheme = platform === 'tvos' ? 'conductor-driver-tvos' : 'conductor-driver-ios';
+    // Rebuild when the sources or the signing team change; the xctestrun naming
+    // is derived from the SDK so glob for it rather than hardcoding a version.
+    const stamp = path_1.default.join(cache, '.version');
+    const sourceMtime = String(fs_1.default.statSync(path_1.default.join(project, 'project.pbxproj')).mtimeMs);
+    let cached = '';
+    try {
+        cached = fs_1.default.readFileSync(stamp, 'utf-8').trim();
+    }
+    catch {
+        /* first run */
+    }
+    if (cached === sourceMtime && findDeviceXctestrun(cache))
+        return findDeviceXctestrun(cache);
+    (0, verbose_js_1.log)(`Building signed ${platform} driver for team ${teamId} (first run takes a few minutes)...`);
+    const args = [
+        'build-for-testing',
+        '-project',
+        project,
+        '-scheme',
+        scheme,
+        '-destination',
+        `id=${deviceId}`,
+        '-derivedDataPath',
+        cache,
+        '-allowProvisioningUpdates',
+        `DEVELOPMENT_TEAM=${teamId}`,
+    ];
+    // The first build for a team creates provisioning profiles as a side effect,
+    // and Xcode regularly references one before it lands on disk ("Build input
+    // file cannot be found: ….mobileprovision"). The profile exists by the retry.
+    try {
+        await spawnCaptureAll('xcodebuild', args);
+    }
+    catch (first) {
+        (0, verbose_js_1.log)(`Driver build failed, retrying once: ${first instanceof Error ? first.message : first}`);
+        try {
+            await spawnCaptureAll('xcodebuild', args);
+        }
+        catch (retry) {
+            throw new Error(`Could not build the ${platform} driver for team ${teamId}.\n` +
+                `${retry instanceof Error ? retry.message : String(retry)}\n` +
+                `Check that the device is registered to the team and that Xcode has an account for it.`);
+        }
+    }
+    const xctestrun = findDeviceXctestrun(cache);
+    if (!xctestrun) {
+        throw new Error(`Driver build for ${platform} produced no xctestrun under ${cache}`);
+    }
+    fs_1.default.writeFileSync(stamp, sourceMtime);
+    (0, verbose_js_1.log)(`${platform} device driver ready`);
+    return xctestrun;
+}
+/** Locate the xctestrun a device build produced — its name embeds the SDK version. */
+function findDeviceXctestrun(cache) {
+    const products = path_1.default.join(cache, 'Build', 'Products');
+    try {
+        const match = fs_1.default.readdirSync(products).find((f) => f.endsWith('.xctestrun'));
+        return match ? path_1.default.join(products, match) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Start the XCTest driver on a physical iOS/tvOS device.
+ *
+ * Mirrors startIOSDriver, with two differences forced by real hardware: the
+ * driver is built and signed locally, and it binds every interface because the
+ * device's loopback isn't shared with the host.
+ */
+async function startDeviceDriver(deviceId, platform, port) {
+    const host = await resolveDriverHost(deviceId);
+    if (await isPortOpen(port, host)) {
+        (0, verbose_js_1.log)(`${platform} device driver already running on ${host}:${port}`);
+        return;
+    }
+    const device = await (0, devicectl_js_1.findPhysicalDevice)(deviceId);
+    if (device && !device.developerModeEnabled) {
+        throw new Error(`Developer Mode is disabled on "${device.name}". ` +
+            `Enable it in Settings ▸ Privacy & Security ▸ Developer Mode and re-pair the device.`);
+    }
+    const teamId = await resolveTeamId();
+    const xctestrun = await setupDeviceDriver(deviceId, platform, teamId);
+    const testTarget = platform === 'tvos' ? 'conductor-driver-tvosUITests' : 'conductor-driver-iosUITests';
+    await spawnAndWait('plutil', [
+        '-replace',
+        `${testTarget}.EnvironmentVariables.PORT`,
+        '-string',
+        String(port),
+        xctestrun,
+    ]);
+    // The host reaches the driver over the network, so it can't bind loopback-only.
+    await spawnAndWait('plutil', [
+        '-replace',
+        `${testTarget}.EnvironmentVariables.BIND_ALL`,
+        '-string',
+        '1',
+        xctestrun,
+    ]);
+    (0, verbose_js_1.log)(`Starting ${platform} driver on ${device?.name ?? deviceId} (${host}:${port})`);
+    const proc = (0, child_process_1.spawn)('xcodebuild', ['test-without-building', '-xctestrun', xctestrun, '-destination', `id=${deviceId}`], { detached: true, stdio: ['ignore', 'ignore', 'ignore'] });
+    proc.unref();
+    const deadline = Date.now() + DEVICE_STARTUP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await (0, utils_js_1.sleep)(DEVICE_STARTUP_POLL_MS);
+        if (await isPortOpen(port, host)) {
+            (0, verbose_js_1.log)(`${platform} device driver ready on ${host}:${port}`);
+            return;
+        }
+    }
+    throw new Error(`${platform} XCTest driver did not start within ${DEVICE_STARTUP_TIMEOUT_MS / 1000}s ` +
+        `on ${host}:${port}. Check that the device is awake and on the same network.`);
+}
+/** Stop the driver on a physical device by killing the runner process. */
+async function stopDeviceDriver(deviceId, platform) {
+    const bundleId = platform === 'tvos' ? TVOS_RUNNER_BUNDLE_ID : IOS_RUNNER_BUNDLE_ID;
+    await (0, devicectl_js_1.terminateApp)(deviceId, bundleId).catch(() => { });
+}
 // ── Android bootstrap ─────────────────────────────────────────────────────────
 const ANDROID_STARTUP_TIMEOUT_MS = 30000;
 const ANDROID_STARTUP_POLL_MS = 500;
@@ -994,6 +1217,32 @@ function spawnAndWait(cmd, args) {
         proc.on('error', reject);
     });
 }
+/**
+ * Run a command, and on failure reject with the tail of its output. Used for
+ * xcodebuild, where the exit code alone tells the user nothing actionable.
+ */
+function spawnCaptureAll(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        const append = (chunk) => {
+            out += chunk.toString();
+        };
+        proc.stdout?.on('data', append);
+        proc.stderr?.on('data', append);
+        proc.on('close', (code) => {
+            if (code === 0)
+                return resolve(out);
+            const errors = out
+                .split('\n')
+                .filter((l) => l.includes('error:'))
+                .slice(0, 5)
+                .join('\n');
+            reject(new Error(`${cmd} exited ${code}${errors ? `:\n${errors}` : ''}`));
+        });
+        proc.on('error', reject);
+    });
+}
 function spawnCapture(cmd, args) {
     return new Promise((resolve, reject) => {
         const proc = (0, child_process_1.spawn)(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] });

package/dist/drivers/devicectl.js

@@ -0,0 +1,243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDevicectlDevices = parseDevicectlDevices;
+exports.listPhysicalDevices = listPhysicalDevices;
+exports.findPhysicalDevice = findPhysicalDevice;
+exports.bonjourHostname = bonjourHostname;
+exports.deviceHostCandidates = deviceHostCandidates;
+exports.resolveDeviceHost = resolveDeviceHost;
+exports.installApp = installApp;
+exports.uninstallApp = uninstallApp;
+exports.launchApp = launchApp;
+exports.terminateApp = terminateApp;
+exports.listApps = listApps;
+/**
+ * `xcrun devicectl` wrapper — the physical-device counterpart to `simctl`.
+ *
+ * Simulators and real devices share the XCTest driver (same HTTP protocol), but
+ * everything around it differs: discovery, app install/launch, and reachability.
+ * This module owns the devicectl half so the rest of the CLI can stay generic.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("dns/promises"));
+const verbose_js_1 = require("../verbose.js");
+function devicectl(args, timeoutMs = 30000) {
+    return new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)('xcrun', ['devicectl', ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        const timer = setTimeout(() => {
+            proc.kill('SIGKILL');
+            reject(new Error(`devicectl ${args[0]} ${args[1] ?? ''} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        proc.stdout?.on('data', (c) => {
+            out += c.toString();
+        });
+        proc.stderr?.on('data', (c) => {
+            err += c.toString();
+        });
+        proc.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 0) {
+                resolve(out);
+            }
+            else {
+                reject(new Error(`devicectl ${args.join(' ')} failed: ${err.trim() || out.trim()}`));
+            }
+        });
+        proc.on('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+/**
+ * Run a devicectl subcommand that reports its result as JSON. devicectl only
+ * writes structured output to a file, never stdout, so every call round-trips
+ * through a temp file.
+ */
+async function devicectlJson(args, timeoutMs = 30000) {
+    const file = path_1.default.join(os_1.default.tmpdir(), `conductor-devicectl-${process.pid}-${Math.random().toString(36).slice(2)}.json`);
+    try {
+        await devicectl([...args, '--json-output', file], timeoutMs);
+        return JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    finally {
+        fs_1.default.rmSync(file, { force: true });
+    }
+}
+function toPlatform(raw) {
+    if (!raw)
+        return null;
+    const v = raw.toLowerCase();
+    if (v === 'ios' || v === 'ipados')
+        return 'ios';
+    if (v === 'tvos')
+        return 'tvos';
+    return null;
+}
+/** Map devicectl's device list onto PhysicalDevice, dropping anything we can't drive. */
+function parseDevicectlDevices(parsed) {
+    const devices = [];
+    for (const d of parsed.result?.devices ?? []) {
+        const platform = toPlatform(d.hardwareProperties?.platform);
+        // Skip simulators (reality: "simulator") — simctl already covers those.
+        if (!platform || d.hardwareProperties?.reality !== 'physical')
+            continue;
+        devices.push({
+            identifier: d.identifier,
+            udid: d.hardwareProperties?.udid ?? d.identifier,
+            name: d.deviceProperties?.name ?? d.identifier,
+            platform,
+            // Paired isn't enough: a device that's off or on another network stays
+            // paired but reports no transport, and tunnelState goes 'unavailable'.
+            available: d.connectionProperties?.pairingState === 'paired' &&
+                d.connectionProperties?.tunnelState !== 'unavailable' &&
+                !!d.connectionProperties?.transportType,
+            potentialHostnames: d.connectionProperties?.potentialHostnames ?? [],
+            osVersion: d.deviceProperties?.osVersionNumber ?? '',
+            marketingName: d.hardwareProperties?.marketingName ?? '',
+            developerModeEnabled: d.deviceProperties?.developerModeStatus === 'enabled',
+        });
+    }
+    return devices;
+}
+/** List every paired physical iOS/tvOS device known to CoreDevice. */
+async function listPhysicalDevices() {
+    try {
+        return parseDevicectlDevices(await devicectlJson(['list', 'devices']));
+    }
+    catch (e) {
+        (0, verbose_js_1.log)(`devicectl list devices failed: ${e instanceof Error ? e.message : String(e)}`);
+        return [];
+    }
+}
+/** Cache: deviceId (identifier or udid) → device, or null when it isn't physical. */
+const _deviceCache = new Map();
+/** Look up a physical device by either its CoreDevice identifier or hardware UDID. */
+async function findPhysicalDevice(deviceId) {
+    if (_deviceCache.has(deviceId))
+        return _deviceCache.get(deviceId);
+    const key = deviceId.toLowerCase();
+    const match = (await listPhysicalDevices()).find((d) => d.identifier.toLowerCase() === key || d.udid.toLowerCase() === key) ?? null;
+    _deviceCache.set(deviceId, match);
+    return match;
+}
+/**
+ * Resolve the address the host can reach the device's driver on.
+ *
+ * devicectl's `*.coredevice.local` hostnames only resolve inside Apple's
+ * CoreDevice tunnel, so they're useless for a plain TCP connect. The device's
+ * Bonjour name (`<name>.local`) is what actually resolves on the LAN, so we
+ * derive that from the device name and resolve it to an IP once, since mDNS
+ * lookups are slow enough to matter on every driver poll.
+ */
+const _hostCache = new Map();
+/**
+ * The mDNS name a device advertises itself under, derived from its display name
+ * the same way the device does: apostrophes are dropped outright (so "Douwe's
+ * iPhone" is "Douwes-iPhone", not "Douwe-s-iPhone") and every other run of
+ * non-alphanumerics collapses to a single dash.
+ */
+function bonjourHostname(deviceName) {
+    return (deviceName
+        .replace(/['’]/g, '')
+        .replace(/[^A-Za-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '') + '.local');
+}
+/**
+ * Candidate LAN addresses, best first. devicectl's `potentialHostnames` already
+ * contain Apple's own sanitization of the device name, so re-pointing those at
+ * `.local` is more reliable than our derivation — we keep both because the
+ * hostname list is occasionally absent.
+ */
+function deviceHostCandidates(device) {
+    const fromDevicectl = device.potentialHostnames
+        .filter((h) => h.endsWith('.coredevice.local'))
+        .map((h) => h.replace(/\.coredevice\.local$/, '.local'));
+    return [
+        ...new Set([bonjourHostname(device.name), ...fromDevicectl, ...device.potentialHostnames]),
+    ];
+}
+async function resolveDeviceHost(device) {
+    const cached = _hostCache.get(device.identifier);
+    if (cached)
+        return cached;
+    const candidates = deviceHostCandidates(device);
+    for (const host of candidates) {
+        try {
+            const { address } = await promises_1.default.lookup(host, { family: 4 });
+            (0, verbose_js_1.log)(`Resolved ${device.name} → ${host} (${address})`);
+            _hostCache.set(device.identifier, address);
+            return address;
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    throw new Error(`Could not resolve a network address for "${device.name}".\n` +
+        `Tried: ${candidates.join(', ')}\n` +
+        `The device must be on the same network as this Mac for conductor to reach its driver.`);
+}
+// ── App lifecycle ─────────────────────────────────────────────────────────────
+async function installApp(deviceId, appPath) {
+    await devicectl(['device', 'install', 'app', '--device', deviceId, appPath], 300000);
+}
+async function uninstallApp(deviceId, bundleId) {
+    await devicectl(['device', 'uninstall', 'app', '--device', deviceId, bundleId], 60000);
+}
+/**
+ * Launch an app. `env` is passed as devicectl's JSON environment dictionary,
+ * which is the device-side equivalent of simctl's SIMCTL_CHILD_ vars.
+ */
+async function launchApp(deviceId, bundleId, args = [], env) {
+    const flags = ['device', 'process', 'launch', '--device', deviceId, '--terminate-existing'];
+    if (env && Object.keys(env).length > 0) {
+        flags.push('--environment-variables', JSON.stringify(env));
+    }
+    await devicectl([...flags, bundleId, ...args], 120000);
+}
+/** Terminate an app by bundle id. devicectl only kills by PID, so resolve one first. */
+async function terminateApp(deviceId, bundleId) {
+    const listed = await devicectlJson([
+        'device',
+        'info',
+        'processes',
+        '--device',
+        deviceId,
+    ]);
+    const match = (listed.result?.runningProcesses ?? []).find((p) => p.executable?.includes(`${bundleId}`));
+    if (!match)
+        return;
+    await devicectl([
+        'device',
+        'process',
+        'signal',
+        '--device',
+        deviceId,
+        '--signal',
+        'SIGKILL',
+        '--pid',
+        String(match.processIdentifier),
+    ]);
+}
+async function listApps(deviceId) {
+    const listed = await devicectlJson([
+        'device',
+        'info',
+        'apps',
+        '--device',
+        deviceId,
+    ]);
+    return (listed.result?.apps ?? []).map((a) => ({
+        id: a.bundleIdentifier,
+        name: a.name ?? a.bundleIdentifier,
+    }));
+}

package/dist/drivers/flow-runner.js

@@ -137,7 +137,16 @@ function parseFlowString(content, extraEnv) {
         else if (doc && typeof doc === 'object') {
             // Single-document flow: either a header-only or treat as single command
             const keys = Object.keys(doc);
-            const headerKeys = new Set(['appId', 'url', 'env', 'tags', 'onFlowStart', 'onFlowComplete']);
+            const headerKeys = new Set([
+                'appId',
+                'url',
+                'name',
+                'env',
+                'tags',
+                'properties',
+                'onFlowStart',
+                'onFlowComplete',
+            ]);
             if (keys.every((k) => headerKeys.has(k))) {
                 header = doc;
                 rawCommands = [];

package/dist/drivers/ios.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -16,6 +49,7 @@ const promises_1 = __importDefault(require("fs/promises"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const devicectl = __importStar(require("./devicectl.js"));
 /**
  * How long a captured view hierarchy may be reused. Bounds the staleness of a
  * cached snapshot when the screen changes without a driver-issued command
@@ -24,11 +58,18 @@ const child_process_1 = require("child_process");
  */
 const HIERARCHY_CACHE_TTL_MS = 750;
 class IOSDriver {
-    constructor(port = 1075, host = '127.0.0.1', deviceId, platform = 'ios') {
+    constructor(port = 1075, host = '127.0.0.1', deviceId, platform = 'ios', 
+    /**
+     * Physical devices route app lifecycle through devicectl instead of simctl,
+     * and can't offer the simulator-only conveniences (clipboard, location,
+     * TCC pre-approval, video capture).
+     */
+    isPhysical = false) {
         this.port = port;
         this.host = host;
         this.deviceId = deviceId;
         this.platform = platform;
+        this.isPhysical = isPhysical;
         this._recordingProcess = null;
         /**
          * Short-lived cache of the most recent view hierarchy, keyed by request
@@ -38,6 +79,12 @@ class IOSDriver {
          */
         this.hierarchyCache = null;
     }
+    /** Reject a simulator-only operation with a message that names the alternative. */
+    unsupportedOnDevice(operation, alternative) {
+        throw new Error(`${operation} is not supported on physical ${this.platform === 'tvos' ? 'tvOS' : 'iOS'} devices` +
+            (alternative ? ` — ${alternative}` : '') +
+            '.');
+    }
     request(method, path, body) {
         return new Promise((resolve, reject) => {
             const bodyBuf = body !== undefined ? Buffer.from(JSON.stringify(body), 'utf-8') : undefined;
@@ -193,7 +240,18 @@ class IOSDriver {
         for (const [key, value] of Object.entries(args ?? {})) {
             argPairs.push(`-${key}`, value);
         }
-        if (inject) {
+        if (this.isPhysical && (inject || argPairs.length > 0)) {
+            // devicectl is the device-side equivalent of `simctl launch`: it takes
+            // both launch arguments and an environment dictionary.
+            const deviceId = this.requireDeviceId();
+            await devicectl.launchApp(deviceId, bundleId, argPairs, inject
+                ? {
+                    DYLD_INSERT_LIBRARIES: inject.dylibPath,
+                    CONDUCTOR_INPROC_PORT: String(inject.inprocPort),
+                }
+                : undefined);
+        }
+        else if (inject) {
             // Injection requires simctl launch with SIMCTL_CHILD_ env — the XCTest
             // /launchApp path only activates and can't set environment.
             const deviceId = this.requireDeviceId();
@@ -220,6 +278,13 @@ class IOSDriver {
     }
     async clearAppState(bundleId) {
         const deviceId = this.requireDeviceId();
+        if (this.isPhysical) {
+            // No get_app_container on device, so there's no bundle to reinstall from;
+            // the caller has to supply the .app again via install-app.
+            await devicectl.uninstallApp(deviceId, bundleId);
+            this.invalidateHierarchyCache();
+            return;
+        }
         // Terminate first to prevent app from saving state after clear
         await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
         // Capture the .app bundle path before uninstalling — uninstall deletes the UUID directory
@@ -240,26 +305,40 @@ class IOSDriver {
     }
     async uninstallApp(bundleId) {
         const deviceId = this.requireDeviceId();
-        await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
-        await this.simctl(['uninstall', deviceId, bundleId]);
+        if (this.isPhysical) {
+            await devicectl.uninstallApp(deviceId, bundleId);
+        }
+        else {
+            await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
+            await this.simctl(['uninstall', deviceId, bundleId]);
+        }
         this.invalidateHierarchyCache();
     }
     async clearKeychain() {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('clear-keychain');
         const deviceId = this.requireDeviceId();
         await this.simctl(['keychain', deviceId, 'reset']);
     }
     async openLink(url) {
+        if (this.isPhysical) {
+            this.unsupportedOnDevice('open-link', 'devicectl has no openurl equivalent');
+        }
         const deviceId = this.requireDeviceId();
         await this.simctl(['openurl', deviceId, url]);
         this.invalidateHierarchyCache();
     }
     /** Read the simulator's clipboard. Uses `xcrun simctl pbpaste <udid>`. */
     async clipboardRead() {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('Reading the clipboard');
         const deviceId = this.requireDeviceId();
         return this.simctlCapture(['pbpaste', deviceId]);
     }
     /** Write to the simulator's clipboard. Uses `xcrun simctl pbcopy <udid>` over stdin. */
     async clipboardWrite(text) {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('Writing the clipboard');
         const deviceId = this.requireDeviceId();
         await new Promise((resolve, reject) => {
             const proc = (0, child_process_1.spawn)('xcrun', ['simctl', 'pbcopy', deviceId], {
@@ -275,6 +354,8 @@ class IOSDriver {
         });
     }
     async setLocation(latitude, longitude) {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('set-location');
         const deviceId = this.requireDeviceId();
         await this.simctl(['location', deviceId, 'set', `${latitude},${longitude}`]);
     }
@@ -339,6 +420,12 @@ class IOSDriver {
             mediaLibrary: 'media-library',
             siri: 'siri',
         };
+        // On device there's no TCC pre-approval path, so the runner's interruption
+        // monitor is the only thing that can answer permission dialogs.
+        if (this.isPhysical) {
+            await this.post('setPermissions', { permissions: expanded });
+            return;
+        }
         const deviceId = this.requireDeviceId();
         if (allValue !== undefined) {
             // Best-effort bulk grant/revoke. 'all' covers TCC-managed permissions but
@@ -370,6 +457,8 @@ class IOSDriver {
         await this.post('setPermissions', { permissions: expanded });
     }
     async addMedia(filePath) {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('add-media');
         const deviceId = this.requireDeviceId();
         await this.simctl(['addmedia', deviceId, filePath]);
     }
@@ -380,6 +469,9 @@ class IOSDriver {
         throw new Error('getAirplaneMode is not supported on iOS simulators');
     }
     async startRecording(outputPath) {
+        if (this.isPhysical) {
+            this.unsupportedOnDevice('Screen recording', 'capture stills with `conductor screenshot`');
+        }
         const deviceId = this.requireDeviceId();
         if (this._recordingProcess)
             await this.stopRecording();

package/dist/runner.js

@@ -151,12 +151,16 @@ async function getDriver(sessionName = 'default') {
     (0, verbose_js_1.log)(`getDriver: platform=${platform} deviceId=${deviceId} port=${port || '(deferred)'}`);
     let driver;
     if (platform === 'ios') {
-        if (!(await (0, bootstrap_js_1.isPortOpen)(port))) {
+        // Physical devices serve the driver from their own loopback, so the CLI
+        // has to reach them over the network instead of the host's.
+        const host = await (0, bootstrap_js_1.resolveDriverHost)(deviceId);
+        if (!(await (0, bootstrap_js_1.isPortOpen)(port, host))) {
             (0, verbose_js_1.log)(`Driver not running — starting daemon for ${deviceId}...`);
             await (0, client_js_1.startDaemon)(deviceId);
-            await waitForPort(port);
+            await waitForPort(port, undefined, undefined, host);
         }
-        const iosDriver = new ios_js_1.IOSDriver(port, '127.0.0.1', deviceId, 'ios');
+        const isPhysical = (await (0, bootstrap_js_1.detectDeviceKind)(deviceId)) === 'physical';
+        const iosDriver = new ios_js_1.IOSDriver(port, host, deviceId, 'ios', isPhysical);
         if (!(await iosDriver.isAlive())) {
             throw new Error(`iOS XCTest driver on port ${port} is not responding.\n` +
                 `Run: conductor daemon-start --device ${deviceId}`);
@@ -164,12 +168,16 @@ async function getDriver(sessionName = 'default') {
         driver = iosDriver;
     }
     else if (platform === 'tvos') {
-        if (!(await (0, bootstrap_js_1.isPortOpen)(port))) {
+        // Physical devices serve the driver from their own loopback, so the CLI
+        // has to reach them over the network instead of the host's.
+        const host = await (0, bootstrap_js_1.resolveDriverHost)(deviceId);
+        if (!(await (0, bootstrap_js_1.isPortOpen)(port, host))) {
             (0, verbose_js_1.log)(`tvOS driver not running — starting daemon for ${deviceId}...`);
             await (0, client_js_1.startDaemon)(deviceId);
-            await waitForPort(port);
+            await waitForPort(port, undefined, undefined, host);
         }
-        const tvosDriver = new ios_js_1.IOSDriver(port, '127.0.0.1', deviceId, 'tvos');
+        const isPhysical = (await (0, bootstrap_js_1.detectDeviceKind)(deviceId)) === 'physical';
+        const tvosDriver = new ios_js_1.IOSDriver(port, host, deviceId, 'tvos', isPhysical);
         if (!(await tvosDriver.isAlive())) {
             throw new Error(`tvOS XCTest driver on port ${port} is not responding.\n` +
                 `Run: conductor daemon-start --device ${deviceId}`);
@@ -403,10 +411,10 @@ async function spawnCommand(cmd, args, options) {
     });
 }
 /** Poll until a TCP port is open, or throw after timeout. */
-async function waitForPort(port, timeoutMs = 180000, pollMs = 500) {
+async function waitForPort(port, timeoutMs = 180000, pollMs = 500, host = '127.0.0.1') {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (await (0, bootstrap_js_1.isPortOpen)(port))
+        if (await (0, bootstrap_js_1.isPortOpen)(port, host))
             return;
         await new Promise((r) => setTimeout(r, pollMs));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

package/skills/conductor-device-interact/SKILL.md

@@ -41,7 +41,7 @@ conductor assert-visible "Dashboard"
 | `conductor copy-text-from <element>` | Print an element's text (and copy to the iOS clipboard) |
 | `conductor input-text <text>` | Type into the focused field |
 | `conductor erase-text [n]` | Erase n characters (default 50) |
-| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega / roku. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
+| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`, `Remote Page Up/Down` on tvOS and Android TV, and `Remote Guide` on tvOS) for tvOS / Android TV / vega / roku. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
 | `conductor hide-keyboard` | Dismiss the on-screen keyboard |
 | `conductor back` | Press back |
 | `conductor scroll [--direction down\|up\|left\|right]` | Scroll |
@@ -127,6 +127,16 @@ relaunch without the flag. (See `conductor-device-setup`.)
 
 - `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web|vega|roku>` scopes by platform.
 - Vega (Amazon Fire TV) is D-pad driven: navigate with `press-key "Remote Dpad …"`; coordinate `tap-on` also works. `open-link`, `set-location`, gestures, and clipboard are unsupported. See `conductor-device-setup`.
+- Apple TV (tvOS) is focus-driven and has **no touch surface automation**: XCTest
+  refuses remote swipe gestures ("Swipe events are only implemented for iOS,
+  visionOS, and watchOS"), so `swipe`/`scroll` are unavailable. Navigate with
+  `press-key "Remote Dpad Up/Down/Left/Right"` and `"Remote Dpad Center"`; for
+  long lists use `press-key "Remote Page Up"` / `"Remote Page Down"` (tvOS 14.3+;
+  also mapped on Android TV), which move a screenful at a time when the app
+  honours them. `"Remote Guide"` (14.3+) and
+  `"Remote TV Provider"` / `"Remote One Two Three"` / `"Remote Four Colors"`
+  (18.1+) are also available. `--duration <seconds>` holds a button for
+  accelerated scrolling.
 - Roku is D-pad only — there is no touch. `tap-on <selector>` resolves the element but presses `Select`, which activates whatever currently holds **focus**, so navigate focus onto the target with `press-key "Remote Dpad …"` first and use `tap-on` to confirm. `scroll`/`swipe` become repeated D-pad presses in the direction the content moves. `open-link` needs an app id (it becomes a channel launch parameter). Only sideloaded dev-mode channels are inspectable. See `conductor-device-setup`.
 - Add `--json` for machine-readable output; failed assertions exit non-zero.
 - Run a per-session daemon for many commands (see `conductor-device-setup`).

package/skills/conductor-device-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-setup
-description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, Vega (Amazon Fire TV) virtual devices, Roku devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD or a Roku device, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
+description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, physical iOS/tvOS devices, Vega (Amazon Fire TV) virtual devices, Roku devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD or a Roku device, driving a physical iPhone/iPad/Apple TV, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
 ---
 
 # Conductor — device & app setup
@@ -102,6 +102,33 @@ Unsupported on Roku: `install-app`/`uninstall-app` (sideload via the device's de
 web server at `http://<device-ip>`), `list-apps`, `clear-state`, gestures,
 screen recording, clipboard, `set-location`, memory/CPU profiling, and device logs.
 
+### Physical iOS / tvOS devices
+
+Real iPhones, iPads, and Apple TVs work alongside simulators. They're discovered
+through `devicectl`, show up in `list-devices` with status `connected`, and are
+addressed by their CoreDevice identifier (`--device <uuid>`).
+
+Requirements:
+
+- The device is **paired** with this Mac and on the **same network** — conductor
+  reaches the driver over the LAN, not the host's loopback.
+- **Developer Mode** is enabled on the device.
+- A signing team: conductor builds and signs the XCTest driver locally on first
+  use (a few minutes; cached per team in `~/.conductor/<platform>-driver-device/`).
+  Set `CONDUCTOR_TEAM_ID=<team>` when the Mac has more than one development team
+  — conductor refuses to guess rather than sign with the wrong one.
+
+Everything driven through the XCTest driver behaves the same as on a simulator:
+`inspect`, `capture-ui`, `tap-on`, `press-key`, `swipe`, `launch-app`,
+`terminate-app`, `install-app`, `uninstall-app`, flows.
+
+Simulator-only — these fail with an explicit message on a physical device:
+`set-location`, `open-link`, clipboard read/write, `clear-keychain`, `add-media`,
+screen recording and the live video stream, and OS log collection (`conductor
+logs` still gets **Metro** logs, which is the useful source for React Native).
+`clear-state` uninstalls on device without reinstalling — reinstall with
+`install-app` afterwards.
+
 ## App lifecycle
 
 | Command                                               | Purpose                                                                |