@autifyhq/aximo-cli 0.11.0 → 0.11.1

package/README.md

@@ -546,7 +546,7 @@ Run `aximo mobile doctor --platform ios` to see what was discovered (identity, t
 
 > **On-device steps you can't skip** (Apple requires them once per phone): enable **Developer Mode** (Settings → Privacy & Security → Developer Mode; the phone restarts), tap **Trust This Computer**, and — after the first install of an app signed by your team — **trust the developer certificate** (Settings → General → VPN & Device Management → your "Apple Development" profile → Trust; the phone needs internet). On **free/personal teams** profiles expire every ~7 days; the CLI re-mints them automatically, but a re-mint **resets the certificate trust**, so expect that trust tap to recur weekly. Free teams are also capped at 10 App IDs per week.
 >
-> On **iOS 17+**, `aximo mobile connect` also starts a small **device tunnel that needs admin rights** — it prompts once for your macOS password / Touch ID (reused on later runs, so at most once per boot). The tunnel deliberately keeps running after `connect` exits; stop it anytime with `sudo pkill -f tunnel-creation`. Devices below iOS 17 skip the tunnel entirely, and Android never uses it. If anything mentions "iOS X is not installed", run `xcodebuild -downloadPlatform iOS` (only the classic build flow needs it).
+> On **iOS 17+**, `aximo mobile connect` also starts a small **device tunnel that needs admin rights** — it prompts once for your macOS password / Touch ID (reused on later runs; it only re-prompts when the running tunnel has no tunnel for your device — e.g. it was started before the phone was attached — and must be restarted). The tunnel deliberately keeps running after `connect` exits; stop it anytime with `sudo pkill -f tunnel-creation`. Devices below iOS 17 skip the tunnel entirely, and Android never uses it. If anything mentions "iOS X is not installed", run `xcodebuild -downloadPlatform iOS` (only the classic build flow needs it).
 
 ### Enable USB debugging on the phone
 

package/dist/commands/mobile/connect-core.js

@@ -125,7 +125,7 @@ export async function connectWithConfig(config, options) {
             console.error(`iOS ${iosMajor} device — skipping the RemoteXPC tunnel (not needed).`);
         }
         else {
-            const tunnel = await ensureIosTunnel();
+            const tunnel = await ensureIosTunnel({ udid: config.target });
             tunnelRunning = tunnel.started || tunnel.reused;
             if (tunnel.reused)
                 console.error("Reusing the running iOS device tunnel.");

package/dist/commands/mobile/doctor.d.ts

@@ -23,11 +23,18 @@ export interface MobileDoctorReport {
  * APKs have wedged instrumentation. Only called when adb itself is available.
  */
 export declare function checkAndroidDevice(exec?: ExecFn): Promise<Check[]>;
-export declare function checkIosTunnel(isHealthy?: (port: number) => Promise<boolean>): Promise<Check>;
+export interface IosTunnelTarget {
+    name: string;
+    /** Device udid the registry must have a tunnel for. */
+    target: string;
+}
+export declare function checkIosTunnel(listUdids?: (port: number) => Promise<string[] | null>, targets?: IosTunnelTarget[]): Promise<Check>;
 export interface RunMobileDoctorOptions {
     platform?: "ios" | "android" | undefined;
-    /** Injectable tunnel probe for tests. */
-    isTunnelHealthy?: (port: number) => Promise<boolean>;
+    /** Injectable tunnel-registry probe for tests. */
+    listTunnelUdids?: (port: number) => Promise<string[] | null>;
+    /** Registered iOS devices the tunnel registry should serve (defaults to on-disk configs). */
+    iosTunnelTargets?: IosTunnelTarget[];
     /** Injectable adb runner for tests (device-state checks). */
     exec?: ExecFn;
 }

package/dist/commands/mobile/doctor.js

@@ -10,7 +10,8 @@ import { getAppiumHome, resolveAndroidSdk } from "../../mobile-control/appium-se
 import { listAndroidDevices } from "../../mobile-control/devices.js";
 import { execBinary } from "../../mobile-control/exec.js";
 import { resolveIosSigningAuto } from "../../mobile-control/ios-signing.js";
-import { DEFAULT_TUNNEL_REGISTRY_PORT, isTunnelHealthy } from "../../mobile-control/ios-tunnel.js";
+import { DEFAULT_TUNNEL_REGISTRY_PORT, listTunnelUdids } from "../../mobile-control/ios-tunnel.js";
+import { listMobileDeviceConfigs } from "./paths.js";
 function which(cmd) {
     const probe = platform() === "win32" ? "where" : "which";
     const result = spawnSync(probe, [cmd], { encoding: "utf-8" });
@@ -283,21 +284,35 @@ async function probeInstrumentation(serial, exec) {
 }
 // The RemoteXPC tunnel is host-level (a registry port), so doctor can probe it
 // without a connected device. `connect` starts it automatically, so a missing
-// tunnel is informational, not a failure.
-export async function checkIosTunnel(isHealthy = isTunnelHealthy) {
-    const running = await isHealthy(DEFAULT_TUNNEL_REGISTRY_PORT);
-    return running
-        ? {
-            name: "ios tunnel",
-            status: "pass",
-            message: `RemoteXPC tunnel running (registry port ${DEFAULT_TUNNEL_REGISTRY_PORT})`,
-        }
-        : {
+// tunnel is informational, not a failure. A running tunnel that lacks a
+// registered device IS a failure mode though: XCUITest 12+ trusts the registry
+// over usbmuxd/devicectl, so such sessions die with "Unknown device or
+// simulator UDID" no matter how visible the phone is.
+export async function checkIosTunnel(listUdids = listTunnelUdids, targets = []) {
+    const udids = await listUdids(DEFAULT_TUNNEL_REGISTRY_PORT);
+    if (udids === null) {
+        return {
             name: "ios tunnel",
             status: "info",
             message: "RemoteXPC tunnel not running",
             hint: "iOS 17+ needs it to reach WebDriverAgent; `aximo mobile connect` starts it automatically (prompts for admin).",
         };
+    }
+    const missing = targets.filter((t) => !udids.includes(t.target));
+    if (missing.length > 0) {
+        const list = missing.map((m) => `${m.name} (${m.target})`).join(", ");
+        return {
+            name: "ios tunnel",
+            status: "warn",
+            message: `RemoteXPC tunnel running but its registry has no tunnel for ${list} — sessions fail with 'Unknown device or simulator UDID'`,
+            hint: "Plug the phone in if it isn't connected. If it is, the daemon was likely started before it was attached — `aximo mobile connect` restarts it automatically; manual: sudo pkill -f tunnel-creation, then reconnect.",
+        };
+    }
+    return {
+        name: "ios tunnel",
+        status: "pass",
+        message: `RemoteXPC tunnel running (registry port ${DEFAULT_TUNNEL_REGISTRY_PORT})`,
+    };
 }
 export async function runMobileDoctor(options = {}) {
     const checks = [await checkAppium()];
@@ -312,7 +327,11 @@ export async function runMobileDoctor(options = {}) {
     if (options.platform !== "android") {
         checks.push(...(await checkIos()));
         if (platform() === "darwin") {
-            checks.push(await checkIosTunnel(options.isTunnelHealthy));
+            const targets = options.iosTunnelTargets ??
+                listMobileDeviceConfigs()
+                    .filter((c) => c.platform === "ios")
+                    .map((c) => ({ name: c.name, target: c.target }));
+            checks.push(await checkIosTunnel(options.listTunnelUdids, targets));
         }
     }
     const summary = { pass: 0, warn: 0, fail: 0, info: 0 };

package/dist/commands/mobile/doctor.test.js

@@ -67,12 +67,23 @@ describe("checkAndroidDevice", () => {
 });
 describe("checkIosTunnel", () => {
     it("passes when the RemoteXPC tunnel is reachable", async () => {
-        const check = await checkIosTunnel(async () => true);
+        const check = await checkIosTunnel(async () => []);
         expect(check.status).toBe("pass");
         expect(check.name).toBe("ios tunnel");
     });
+    it("passes when the registry serves all registered devices", async () => {
+        const check = await checkIosTunnel(async () => ["00008030-AAAA"], [{ name: "My iPhone", target: "00008030-AAAA" }]);
+        expect(check.status).toBe("pass");
+    });
+    it("warns when the registry has no tunnel for a registered device", async () => {
+        const check = await checkIosTunnel(async () => [], [{ name: "My iPhone", target: "00008030-AAAA" }]);
+        expect(check.status).toBe("warn");
+        expect(check.message).toContain("My iPhone (00008030-AAAA)");
+        expect(check.message).toContain("Unknown device or simulator UDID");
+        expect(check.hint).toContain("pkill -f tunnel-creation");
+    });
     it("is informational (not a failure) when the tunnel is down", async () => {
-        const check = await checkIosTunnel(async () => false);
+        const check = await checkIosTunnel(async () => null, [{ name: "My iPhone", target: "00008030-AAAA" }]);
         expect(check.status).toBe("info");
         expect(check.hint).toContain("aximo mobile connect");
     });

package/dist/mobile-control/ios-tunnel.d.ts

@@ -9,16 +9,25 @@ export declare const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;
 /** How to stop the elevated tunnel daemon — surfaced whenever we start or leave it running. */
 export declare const TUNNEL_STOP_COMMAND = "sudo pkill -f tunnel-creation";
 /**
- * True when the tunnel registry server answers its HTTP API on `port`. A raw
- * TCP connect is not enough — an unrelated listener on the port would be
- * mistaken for the tunnel and surface much later as an opaque XCUITest error.
+ * Fetch the tunnel registry on `port` and return the device udids it has
+ * tunnels for, or null when no valid registry answers. The response must parse
+ * as a registry (`{"tunnels": {...}}`) — a raw TCP connect is not enough, as an
+ * unrelated listener on the port would be mistaken for the tunnel and surface
+ * much later as an opaque XCUITest error.
+ *
+ * The udid list matters because the XCUITest driver (12+) validates the
+ * session's udid against this registry whenever it answers, ignoring what
+ * devicectl/usbmuxd can see — a running registry without the target device
+ * guarantees "Unknown device or simulator UDID".
  */
-export declare function isTunnelHealthy(port?: number, host?: string, timeoutMs?: number): Promise<boolean>;
+export declare function listTunnelUdids(port?: number, host?: string, timeoutMs?: number): Promise<string[] | null>;
 export interface TunnelScriptOptions {
     appiumHome: string;
     nodePath: string;
     appiumBin: string;
     logFile: string;
+    /** Kill any running tunnel-creation daemon first (its registry lacks the target device). */
+    restart?: boolean;
 }
 /**
  * A self-contained shell script that launches the driver's `tunnel-creation` as a
@@ -36,8 +45,15 @@ export interface EnsureIosTunnelOptions {
     appiumBin?: string;
     /** Directory for the generated tunnel script + log (defaults to $AXIMO_HOME/ios-tunnel). */
     dir?: string;
+    /**
+     * Device udid the registry must have a tunnel for. A running daemon without
+     * it (started before the phone was attached, or its creation failed) is
+     * restarted — reusing it would guarantee an "Unknown device or simulator
+     * UDID" session failure from XCUITest 12+.
+     */
+    udid?: string;
     elevate?: Elevator;
-    isHealthy?: (port: number) => Promise<boolean>;
+    listUdids?: (port: number) => Promise<string[] | null>;
     writeScript?: (path: string, content: string, dir: string) => void;
     readyTimeoutMs?: number;
     log?: (message: string) => void;
@@ -46,12 +62,16 @@ export interface EnsureIosTunnelOptions {
 export interface EnsureIosTunnelResult {
     reused: boolean;
     started: boolean;
+    /** True when a running daemon was replaced because it had no tunnel for `udid`. */
+    restarted: boolean;
     skipped: boolean;
     port: number;
 }
 /**
- * Ensure the RemoteXPC tunnel is running so XCUITest can reach WebDriverAgent.
- * Reuses an already-running tunnel (no prompt); otherwise elevates once via the
- * macOS auth dialog to start it. No-op when AXIMO_IOS_SKIP_TUNNEL is set.
+ * Ensure the RemoteXPC tunnel is running — with a tunnel for `udid` when given —
+ * so XCUITest can find the device and reach WebDriverAgent. Reuses a running
+ * daemon whose registry serves the device (no prompt); restarts one that
+ * doesn't; otherwise elevates once via the macOS auth dialog to start it.
+ * No-op when AXIMO_IOS_SKIP_TUNNEL is set.
  */
 export declare function ensureIosTunnel(options?: EnsureIosTunnelOptions): Promise<EnsureIosTunnelResult>;

package/dist/mobile-control/ios-tunnel.js

@@ -16,22 +16,32 @@ export const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;
 /** How to stop the elevated tunnel daemon — surfaced whenever we start or leave it running. */
 export const TUNNEL_STOP_COMMAND = "sudo pkill -f tunnel-creation";
 /**
- * True when the tunnel registry server answers its HTTP API on `port`. A raw
- * TCP connect is not enough — an unrelated listener on the port would be
- * mistaken for the tunnel and surface much later as an opaque XCUITest error.
+ * Fetch the tunnel registry on `port` and return the device udids it has
+ * tunnels for, or null when no valid registry answers. The response must parse
+ * as a registry (`{"tunnels": {...}}`) — a raw TCP connect is not enough, as an
+ * unrelated listener on the port would be mistaken for the tunnel and surface
+ * much later as an opaque XCUITest error.
+ *
+ * The udid list matters because the XCUITest driver (12+) validates the
+ * session's udid against this registry whenever it answers, ignoring what
+ * devicectl/usbmuxd can see — a running registry without the target device
+ * guarantees "Unknown device or simulator UDID".
  */
-export async function isTunnelHealthy(port = DEFAULT_TUNNEL_REGISTRY_PORT, host = "127.0.0.1", timeoutMs = 1500) {
+export async function listTunnelUdids(port = DEFAULT_TUNNEL_REGISTRY_PORT, host = "127.0.0.1", timeoutMs = 1500) {
     try {
         const res = await fetch(`http://${host}:${port}/remotexpc/tunnels`, {
             signal: AbortSignal.timeout(timeoutMs),
         });
         if (!res.ok)
-            return false;
-        await res.json();
-        return true;
+            return null;
+        const body = (await res.json());
+        if (!body || typeof body !== "object" || !body.tunnels || typeof body.tunnels !== "object") {
+            return null;
+        }
+        return Object.keys(body.tunnels);
     }
     catch {
-        return false;
+        return null;
     }
 }
 /** Single-quote a value for safe embedding in a POSIX shell script. */
@@ -65,6 +75,9 @@ export function buildTunnelScript(opts) {
         "#!/bin/sh",
         `export APPIUM_HOME=${shQuote(opts.appiumHome)}`,
         'export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"',
+        // The old daemon must die before the new one binds the registry port. The
+        // pattern can't match this script (its cmdline is `/bin/sh <path>`).
+        ...(opts.restart ? ["pkill -f tunnel-creation 2>/dev/null; sleep 1"] : []),
         `exec perl -e ${shQuote(DAEMONIZE_PERL)} ${shQuote(opts.logFile)} ${shQuote(opts.nodePath)} ${shQuote(opts.appiumBin)} driver run xcuitest tunnel-creation`,
         "",
     ].join("\n");
@@ -91,35 +104,47 @@ const defaultWriteScript = (path, content, dir) => {
     mkdirSync(dir, { recursive: true });
     writeFileSync(path, content, { mode: 0o700 });
 };
-async function pollHealthy(isHealthy, port, timeoutMs, logFile) {
+async function pollReady(listUdids, port, udid, timeoutMs, logFile) {
     const deadline = Date.now() + timeoutMs;
+    let last = null;
     while (Date.now() < deadline) {
-        if (await isHealthy(port))
+        last = await listUdids(port);
+        if (last !== null && (!udid || last.includes(udid)))
             return;
         await new Promise((resolve) => setTimeout(resolve, 500));
     }
+    if (last !== null && udid) {
+        throw new Error(`The iOS device tunnel is running but did not create a tunnel for device ${udid} ` +
+            `within ${timeoutMs}ms. Make sure the phone is connected over USB, unlocked, and ` +
+            `trusts this Mac, then retry. Check ${logFile} for the daemon's output; stop it ` +
+            `with: ${TUNNEL_STOP_COMMAND}`);
+    }
     throw new Error(`iOS device tunnel did not become ready within ${timeoutMs}ms. ` +
         `Check ${logFile} for the daemon's output. A partially-started daemon may still ` +
         `be running; stop it before retrying: ${TUNNEL_STOP_COMMAND}`);
 }
 /**
- * Ensure the RemoteXPC tunnel is running so XCUITest can reach WebDriverAgent.
- * Reuses an already-running tunnel (no prompt); otherwise elevates once via the
- * macOS auth dialog to start it. No-op when AXIMO_IOS_SKIP_TUNNEL is set.
+ * Ensure the RemoteXPC tunnel is running — with a tunnel for `udid` when given —
+ * so XCUITest can find the device and reach WebDriverAgent. Reuses a running
+ * daemon whose registry serves the device (no prompt); restarts one that
+ * doesn't; otherwise elevates once via the macOS auth dialog to start it.
+ * No-op when AXIMO_IOS_SKIP_TUNNEL is set.
  */
 export async function ensureIosTunnel(options = {}) {
     const env = options.env ?? process.env;
     const port = options.port ?? DEFAULT_TUNNEL_REGISTRY_PORT;
-    const isHealthy = options.isHealthy ?? ((p) => isTunnelHealthy(p));
+    const listUdids = options.listUdids ?? ((p) => listTunnelUdids(p));
     const log = options.log ?? ((m) => console.error(m));
     if (envFlag(env, "AXIMO_IOS_SKIP_TUNNEL")) {
-        return { reused: false, started: false, skipped: true, port };
+        return { reused: false, started: false, restarted: false, skipped: true, port };
     }
-    // A healthy tunnel is reused as-is — this is what makes the prompt appear at
-    // most once per boot rather than once per `connect`.
-    if (await isHealthy(port)) {
-        return { reused: true, started: false, skipped: false, port };
+    // A tunnel serving the device is reused as-is — this is what makes the prompt
+    // appear at most once per boot rather than once per `connect`.
+    const existing = await listUdids(port);
+    if (existing !== null && (!options.udid || existing.includes(options.udid))) {
+        return { reused: true, started: false, restarted: false, skipped: false, port };
     }
+    const restarting = existing !== null;
     const appiumHome = options.appiumHome ?? getAppiumHome();
     const nodePath = options.nodePath ?? process.execPath;
     const appiumBin = options.appiumBin ?? resolveAppiumBin();
@@ -127,8 +152,12 @@ export async function ensureIosTunnel(options = {}) {
     const scriptPath = join(dir, "tunnel.sh");
     const logFile = join(dir, "tunnel.log");
     const writeScript = options.writeScript ?? defaultWriteScript;
-    writeScript(scriptPath, buildTunnelScript({ appiumHome, nodePath, appiumBin, logFile }), dir);
-    log("Starting the iOS device tunnel (needs admin). Approve the macOS password / Touch ID prompt…");
+    writeScript(scriptPath, buildTunnelScript({ appiumHome, nodePath, appiumBin, logFile, restart: restarting }), dir);
+    log(restarting
+        ? `The running iOS device tunnel has no tunnel for this device (${options.udid}) — ` +
+            "sessions would fail with 'Unknown device or simulator UDID'. Restarting it " +
+            "(needs admin). Approve the macOS password / Touch ID prompt…"
+        : "Starting the iOS device tunnel (needs admin). Approve the macOS password / Touch ID prompt…");
     const elevate = options.elevate ?? osascriptElevate;
     try {
         await elevate(scriptPath);
@@ -136,15 +165,22 @@ export async function ensureIosTunnel(options = {}) {
     catch (err) {
         const detail = err instanceof Error ? err.message : String(err);
         const declined = /User canceled|-128/i.test(detail);
+        const verb = restarting ? "restarted" : "started";
         const lead = declined
-            ? "Admin approval was declined, so the iOS device tunnel wasn't started."
-            : `Could not start the iOS device tunnel: ${detail}.`;
+            ? `Admin approval was declined, so the iOS device tunnel wasn't ${verb}.`
+            : `Could not ${restarting ? "restart" : "start"} the iOS device tunnel: ${detail}.`;
+        // In the restart path the stale daemon still holds the registry port, so the
+        // manual command must include the stop step or it fails to bind.
+        const manual = restarting ? `stop the stale daemon first (${TUNNEL_STOP_COMMAND}), then ` : "";
         throw new Error(`${lead} It is required for iOS 17+ to reach WebDriverAgent. Approve the macOS prompt and ` +
-            `retry, or start it yourself: sudo APPIUM_HOME=${shQuote(appiumHome)} ${shQuote(nodePath)} ` +
-            `${shQuote(appiumBin)} driver run xcuitest tunnel-creation`);
+            `retry, or ${manual}start it yourself: sudo APPIUM_HOME=${shQuote(appiumHome)} ` +
+            `${shQuote(nodePath)} ${shQuote(appiumBin)} driver run xcuitest tunnel-creation`);
     }
-    await pollHealthy(isHealthy, port, options.readyTimeoutMs ?? 45_000, logFile);
+    // Per-device tunnel creation (lockdown, CoreDeviceProxy, RSD catalog discovery)
+    // takes 30-60s on top of daemon boot, so the device wait gets a longer default.
+    const readyTimeoutMs = options.readyTimeoutMs ?? (options.udid ? 90_000 : 45_000);
+    await pollReady(listUdids, port, options.udid, readyTimeoutMs, logFile);
     log(`iOS device tunnel is up (registry on port ${port}). It keeps running in the background ` +
         `so later connects don't prompt again; stop it anytime with: ${TUNNEL_STOP_COMMAND}`);
-    return { reused: false, started: true, skipped: false, port };
+    return { reused: false, started: true, restarted: restarting, skipped: false, port };
 }

package/dist/mobile-control/ios-tunnel.test.js

@@ -1,5 +1,6 @@
-import { describe, expect, it, vi } from "vitest";
-import { buildTunnelScript, DEFAULT_TUNNEL_REGISTRY_PORT, ensureIosTunnel } from "./ios-tunnel.js";
+import { createServer } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildTunnelScript, DEFAULT_TUNNEL_REGISTRY_PORT, ensureIosTunnel, listTunnelUdids, } from "./ios-tunnel.js";
 describe("buildTunnelScript", () => {
     it("launches tunnel-creation as a setsid-detached daemon with APPIUM_HOME set", () => {
         const script = buildTunnelScript({
@@ -26,6 +27,63 @@ describe("buildTunnelScript", () => {
         });
         expect(script).toContain("export APPIUM_HOME='/home/o'\\''brien/.aximo'");
     });
+    it("kills the old daemon before starting when restart is set", () => {
+        const opts = {
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            logFile: "/l.log",
+        };
+        const restart = buildTunnelScript({ ...opts, restart: true });
+        expect(restart).toContain("pkill -f tunnel-creation");
+        // pkill must come before the daemon launch, not after.
+        expect(restart.indexOf("pkill")).toBeLessThan(restart.indexOf("exec perl"));
+        expect(buildTunnelScript(opts)).not.toContain("pkill");
+    });
+});
+describe("listTunnelUdids", () => {
+    let server;
+    afterEach(async () => {
+        const open = server;
+        server = undefined;
+        if (open)
+            await new Promise((resolve) => open.close(() => resolve()));
+    });
+    const listen = (handler) => new Promise((resolve) => {
+        server = createServer(handler).listen(0, "127.0.0.1", () => {
+            const address = server?.address();
+            resolve(typeof address === "object" && address ? address.port : 0);
+        });
+    });
+    it("returns the udids the registry has tunnels for", async () => {
+        const port = await listen((req, res) => {
+            expect(req.url).toBe("/remotexpc/tunnels");
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify({ tunnels: { "00008030-AAAA": {}, "00008130-BBBB": {} } }));
+        });
+        await expect(listTunnelUdids(port)).resolves.toEqual(["00008030-AAAA", "00008130-BBBB"]);
+    });
+    it("returns null when nothing listens on the port", async () => {
+        const port = await listen((_req, res) => res.end());
+        const closed = new Promise((resolve) => server?.close(() => resolve()));
+        await closed;
+        server = undefined;
+        await expect(listTunnelUdids(port)).resolves.toBeNull();
+    });
+    it("returns null when the listener is not a tunnel registry", async () => {
+        const port = await listen((_req, res) => {
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify({ hello: "world" }));
+        });
+        await expect(listTunnelUdids(port)).resolves.toBeNull();
+    });
+    it("returns null on a non-JSON or error response", async () => {
+        const port = await listen((_req, res) => {
+            res.statusCode = 500;
+            res.end("boom");
+        });
+        await expect(listTunnelUdids(port)).resolves.toBeNull();
+    });
 });
 describe("ensureIosTunnel", () => {
     const stubs = () => ({
@@ -36,35 +94,73 @@ describe("ensureIosTunnel", () => {
     it("reuses a healthy tunnel without prompting", async () => {
         const s = stubs();
         const result = await ensureIosTunnel({
-            isHealthy: async () => true,
+            listUdids: async () => [],
             ...s,
             env: {},
         });
         expect(result).toEqual({
             reused: true,
             started: false,
+            restarted: false,
             skipped: false,
             port: DEFAULT_TUNNEL_REGISTRY_PORT,
         });
         expect(s.elevate).not.toHaveBeenCalled();
         expect(s.writeScript).not.toHaveBeenCalled();
     });
+    it("reuses a tunnel that serves the requested device", async () => {
+        const s = stubs();
+        const result = await ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids: async () => ["00008030-AAAA"],
+            ...s,
+            env: {},
+        });
+        expect(result.reused).toBe(true);
+        expect(s.elevate).not.toHaveBeenCalled();
+    });
+    it("restarts a running tunnel whose registry lacks the device", async () => {
+        const s = stubs();
+        const listUdids = vi
+            .fn()
+            .mockResolvedValueOnce([]) // pre-check: registry up, no tunnel for the phone
+            .mockResolvedValue(["00008030-AAAA"]); // poll after restart
+        const result = await ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            readyTimeoutMs: 2000,
+            ...s,
+            env: {},
+        });
+        expect(result.restarted).toBe(true);
+        expect(result.started).toBe(true);
+        expect(result.reused).toBe(false);
+        expect(s.elevate).toHaveBeenCalledWith("/tun/tunnel.sh");
+        // The elevated script must replace the old daemon, not race it for the port.
+        const script = s.writeScript.mock.calls[0]?.[1];
+        expect(script).toContain("pkill -f tunnel-creation");
+        expect(s.log).toHaveBeenCalledWith(expect.stringContaining("no tunnel for this device"));
+    });
     it("is a no-op when AXIMO_IOS_SKIP_TUNNEL is set", async () => {
         const s = stubs();
-        const isHealthy = vi.fn(async () => false);
+        const listUdids = vi.fn(async () => null);
         const result = await ensureIosTunnel({
-            isHealthy,
+            listUdids,
             ...s,
             env: { AXIMO_IOS_SKIP_TUNNEL: "1" },
         });
         expect(result.skipped).toBe(true);
-        expect(isHealthy).not.toHaveBeenCalled();
+        expect(listUdids).not.toHaveBeenCalled();
         expect(s.elevate).not.toHaveBeenCalled();
     });
     it('does not skip for AXIMO_IOS_SKIP_TUNNEL="0"', async () => {
         const s = stubs();
         const result = await ensureIosTunnel({
-            isHealthy: async () => true,
+            listUdids: async () => [],
             ...s,
             env: { AXIMO_IOS_SKIP_TUNNEL: "0" },
         });
@@ -74,7 +170,7 @@ describe("ensureIosTunnel", () => {
     it("points at the tunnel log when the daemon never becomes healthy", async () => {
         const s = stubs();
         await expect(ensureIosTunnel({
-            isHealthy: async () => false,
+            listUdids: async () => null,
             appiumHome: "/ah",
             nodePath: "/node",
             appiumBin: "/appium",
@@ -84,14 +180,40 @@ describe("ensureIosTunnel", () => {
             env: {},
         })).rejects.toThrow(/tunnel\.log.*pkill -f tunnel-creation/s);
     });
+    it("explains when the registry never creates a tunnel for the device", async () => {
+        const s = stubs();
+        await expect(ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids: async () => null,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            readyTimeoutMs: 700,
+            ...s,
+            env: {},
+        })).rejects.toThrow(/did not become ready/);
+        const s2 = stubs();
+        await expect(ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids: async () => ["00008130-OTHER"],
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            readyTimeoutMs: 700,
+            ...s2,
+            env: {},
+        })).rejects.toThrow(/did not create a tunnel for device 00008030-AAAA.*connected over USB/s);
+    });
     it("elevates and starts the tunnel when none is running", async () => {
         const s = stubs();
-        const isHealthy = vi
+        const listUdids = vi
             .fn()
-            .mockResolvedValueOnce(false) // pre-check
-            .mockResolvedValue(true); // poll after elevate
+            .mockResolvedValueOnce(null) // pre-check
+            .mockResolvedValue([]); // poll after elevate
         const result = await ensureIosTunnel({
-            isHealthy,
+            listUdids,
             appiumHome: "/ah",
             nodePath: "/node",
             appiumBin: "/appium",
@@ -101,20 +223,37 @@ describe("ensureIosTunnel", () => {
             env: {},
         });
         expect(result.started).toBe(true);
+        expect(result.restarted).toBe(false);
         expect(s.writeScript).toHaveBeenCalledOnce();
         expect(s.elevate).toHaveBeenCalledWith("/tun/tunnel.sh");
+        const script = s.writeScript.mock.calls[0]?.[1];
+        expect(script).not.toContain("pkill");
     });
     it("throws actionable guidance when the admin prompt is declined", async () => {
         const s = stubs();
         s.elevate.mockRejectedValueOnce(new Error("User canceled."));
         await expect(ensureIosTunnel({
-            isHealthy: async () => false,
+            listUdids: async () => null,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            ...s,
+            env: {},
+        })).rejects.toThrow(/Admin approval was declined.*wasn't started.*driver run xcuitest tunnel-creation/s);
+    });
+    it("tells the user to stop the stale daemon when a declined restart leaves it running", async () => {
+        const s = stubs();
+        s.elevate.mockRejectedValueOnce(new Error("User canceled."));
+        await expect(ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids: async () => [],
             appiumHome: "/ah",
             nodePath: "/node",
             appiumBin: "/appium",
             dir: "/tun",
             ...s,
             env: {},
-        })).rejects.toThrow(/Admin approval was declined.*driver run xcuitest tunnel-creation/s);
+        })).rejects.toThrow(/wasn't restarted.*stop the stale daemon first \(sudo pkill -f tunnel-creation\), then start it yourself/s);
     });
 });

package/dist/mobile-control/mobile-errors.js

@@ -41,6 +41,12 @@ const IOS_RULES = [
         test: /Connection refused to port \d+|Tunnel registry port not found|RemoteXPC|tunnel is not available/i,
         hint: "The iOS device tunnel isn't reachable. `aximo mobile connect` starts it (needs admin); confirm with `aximo mobile doctor`. Set AXIMO_IOS_SKIP_TUNNEL only if you manage it yourself.",
     },
+    {
+        // XCUITest 12+ trusts the tunnel registry over usbmuxd/devicectl when it
+        // answers, so a registry without this device fails even a visible phone.
+        test: /Unknown device or simulator UDID/i,
+        hint: "Appium's device list did not include this phone. If it shows in `xcrun devicectl list devices`, the running tunnel daemon has no tunnel for it — re-run `aximo mobile connect` (it restarts the daemon), or stop it first: sudo pkill -f tunnel-creation. Otherwise reconnect USB (data cable, no hub), unlock the phone, and re-trust this Mac.",
+    },
     {
         // "is locked" (not "is unlocked") plus XCUITest's "could not be, unlocked" phrasing.
         test: /(device|screen).{0,30}\bis locked|could not be,? unlocked|passcode/i,

package/dist/mobile-control/mobile-errors.test.js

@@ -19,6 +19,9 @@ describe("mobileErrorHint (iOS)", () => {
     it("matches a refused connection on a dynamic wdaLocalPort", () => {
         expect(mobileErrorHint("Connection refused to port 51234", "ios")).toContain("device tunnel");
     });
+    it("explains the stale tunnel registry behind 'Unknown device or simulator UDID'", () => {
+        expect(mobileErrorHint("Unknown device or simulator UDID: '00008030-001D78CC2653402E'", "ios")).toContain("tunnel daemon has no tunnel for it");
+    });
     it("matches the driver's RemoteXPC tunnel errors", () => {
         expect(mobileErrorHint("RemoteXPC tunnel is not available for this session", "ios")).toContain("device tunnel");
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autifyhq/aximo-cli",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Autify Aximo Command Line Interface (CLI)",
   "keywords": [
     "autify",