@autifyhq/aximo-cli 0.10.1 → 0.11.1

package/dist/desktop-server/setup.js

@@ -1,12 +1,15 @@
 import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
-import { arch as osArch, platform } from "node:os";
 import { join } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { DEFAULT_BASE_URL, getBaseUrl } from "../client.js";
 import { getAgentCaBundlePath, getAximoDir, getCacheDir, getDepsMarkerPath, getEmbeddedPythonBinary, getPythonDir, getPythonMarkerPath, getRemoteLogPath, } from "../commands/device/paths.js";
 import { ensureAgent } from "./agent-sync.js";
+import { warnIfCliOutdated } from "./cli-version.js";
+import { findOfflinePythonArchive, findOfflineWheelsDir } from "./offline.js";
+import { downloadServerPython, ensureServerWheels, platformKey, resolveServerPython, } from "./bundle-sync.js";
 export const PYTHON_RELEASE = "20260414";
 export const PYTHON_VERSION = "3.12.13";
 const BUILDS = {
@@ -36,16 +39,19 @@ const BUILDS = {
     },
 };
 function selectBuild() {
-    const key = `${platform()}-${osArch()}`;
+    const key = platformKey();
     const build = BUILDS[key];
     if (!build) {
         throw new Error(`Unsupported platform/arch: ${key}`);
     }
     return build;
 }
+/** Filename python-build-standalone publishes for this build, also used on disk. */
+export function pythonArchiveName(build = selectBuild()) {
+    return `cpython-${PYTHON_VERSION}+${PYTHON_RELEASE}-${build.target}-install_only.tar.gz`;
+}
 function buildDownloadUrl(build) {
-    const filename = `cpython-${PYTHON_VERSION}+${PYTHON_RELEASE}-${build.target}-install_only.tar.gz`;
-    return `https://github.com/astral-sh/python-build-standalone/releases/download/${PYTHON_RELEASE}/${filename}`;
+    return `https://github.com/astral-sh/python-build-standalone/releases/download/${PYTHON_RELEASE}/${pythonArchiveName(build)}`;
 }
 export function installedPythonTag() {
     return `${PYTHON_RELEASE}-${PYTHON_VERSION}`;
@@ -92,23 +98,93 @@ function extractTarball(tarball, destDir) {
         throw new Error(`tar extraction failed (exit ${result.status})`);
     }
 }
-async function installEmbeddedPython() {
+/**
+ * Resolve a verified Python archive from the nearest available source.
+ *
+ * Order is staged on disk, then the Aximo server, then GitHub. Every branch
+ * checks the same compiled-in SHA256, so nothing gets a weaker guarantee for
+ * being local — and because that constant ships with the CLI, a mismatched
+ * archive from any source is caught.
+ */
+async function acquirePythonTarball(build, manifest, deps) {
+    const archiveName = pythonArchiveName(build);
+    const staged = findOfflinePythonArchive(archiveName);
+    if (staged) {
+        console.log(`Using staged embedded Python ${PYTHON_VERSION} (${build.target})...`);
+        // Never delete a staged archive — it belongs to the user, not the cache.
+        verifyArchive(staged, build.sha256, { removeOnMismatch: false });
+        return { path: staged, ephemeral: false };
+    }
+    const served = manifest && resolveServerPython(manifest, archiveName);
+    if (served) {
+        const path = await downloadServerPython(served, deps ?? {});
+        verifyArchive(path, build.sha256, { removeOnMismatch: true });
+        // Kept in the cache: re-running setup on the same machine then costs nothing,
+        // which matters most on the slow internal links these servers often sit on.
+        return { path, ephemeral: false };
+    }
+    const path = join(getCacheDir(), `python-${installedPythonTag()}.tar.gz`);
+    console.log(`Fetching embedded Python ${PYTHON_VERSION} (${build.target})...`);
+    try {
+        await downloadTarball(buildDownloadUrl(build), path, build.sha256);
+    }
+    catch (err) {
+        throw new Error(`${err instanceof Error ? err.message : String(err)}${fallbackHint(deps)}`);
+    }
+    return { path, ephemeral: true };
+}
+/**
+ * Extra context for a failed GitHub download, when it would actually help.
+ *
+ * Reaching GitHub means the server offered nothing for this platform. Air-gapped
+ * that can never succeed, and the bare network error gives no hint that a missing
+ * server-side bundle is the cause. But this same path is the normal one for cloud,
+ * where a transient GitHub failure has nothing to do with on-prem bundles — so
+ * only mention them when the CLI is pointed somewhere other than cloud.
+ */
+function fallbackHint(deps) {
+    const baseUrl = deps?.baseUrl ?? getBaseUrl();
+    if (baseUrl === DEFAULT_BASE_URL)
+        return "";
+    return (`\n  The Aximo server at ${baseUrl} offered no embedded Python for ${platformKey()}, ` +
+        "so this fell back to downloading from GitHub.\n" +
+        "  If this machine has no internet access, that server needs the CLI bundle from its " +
+        "on-prem release, or stage the archive locally and set AXIMO_OFFLINE_DIR.");
+}
+/**
+ * Check an archive against the CLI's own compiled-in checksum.
+ *
+ * `removeOnMismatch` matters for recovery, not tidiness: a cached download still
+ * matches the manifest that produced it, so leaving a rejected file in place makes
+ * every later run fail identically until someone clears the cache by hand. A
+ * staged archive belongs to the user, so that one is never removed.
+ */
+function verifyArchive(path, expectedSha256, { removeOnMismatch }) {
+    const actual = hashFile(path);
+    if (actual === expectedSha256)
+        return;
+    if (removeOnMismatch)
+        rmSync(path, { force: true });
+    throw new Error(`SHA256 mismatch for ${path}\n  expected ${expectedSha256}\n  actual ${actual}\n` +
+        "  This CLI and the interpreter it was given do not match. Install the aximo-cli " +
+        "that ships with your current Aximo release.");
+}
+/**
+ * Extract an already-verified Python archive into place and stamp the markers.
+ *
+ * Callers are responsible for integrity: by the time an archive reaches here it
+ * must have been checked against the expected SHA256.
+ */
+export function installPythonArchive(tarball, { keepArchive }) {
     const pythonDir = getPythonDir();
     const cacheDir = getCacheDir();
-    const pythonMarker = getPythonMarkerPath();
-    const depsMarker = getDepsMarkerPath();
     if (existsSync(pythonDir)) {
         rmSync(pythonDir, { recursive: true, force: true });
     }
-    const build = selectBuild();
-    const url = buildDownloadUrl(build);
     mkdirSync(cacheDir, { recursive: true });
-    const tarball = join(cacheDir, `python-${installedPythonTag()}.tar.gz`);
     const staging = join(cacheDir, "python-staging");
     if (existsSync(staging))
         rmSync(staging, { recursive: true, force: true });
-    console.log(`Fetching embedded Python ${PYTHON_VERSION} (${build.target})...`);
-    await downloadTarball(url, tarball, build.sha256);
     console.log("Extracting...");
     extractTarball(tarball, staging);
     const extracted = join(staging, "python");
@@ -118,25 +194,47 @@ async function installEmbeddedPython() {
     mkdirSync(getAximoDir(), { recursive: true });
     renameSync(extracted, pythonDir);
     rmSync(staging, { recursive: true, force: true });
-    rmSync(tarball, { force: true });
-    writeFileSync(pythonMarker, installedPythonTag(), { mode: 0o644 });
+    // A staged or server-cached archive is kept: it belongs to the user, or paying
+    // the download again on the next run costs more than the disk.
+    if (!keepArchive)
+        rmSync(tarball, { force: true });
+    writeFileSync(getPythonMarkerPath(), installedPythonTag(), { mode: 0o644 });
+    const depsMarker = getDepsMarkerPath();
     if (existsSync(depsMarker))
         rmSync(depsMarker, { force: true });
 }
-async function ensurePython() {
+async function installEmbeddedPython(manifest, deps) {
+    mkdirSync(getCacheDir(), { recursive: true });
+    const source = await acquirePythonTarball(selectBuild(), manifest, deps);
+    installPythonArchive(source.path, { keepArchive: !source.ephemeral });
+}
+async function ensurePython(manifest, deps) {
     const binary = getEmbeddedPythonBinary();
     const markerPath = getPythonMarkerPath();
     const marker = existsSync(markerPath) ? readFileSync(markerPath, "utf-8").trim() : "";
     if (marker === installedPythonTag() && existsSync(binary)) {
         return binary;
     }
-    await installEmbeddedPython();
+    await installEmbeddedPython(manifest, deps);
     return binary;
 }
 function hashFile(path) {
     return createHash("sha256").update(readFileSync(path)).digest("hex");
 }
-function ensureDependencies(python, requirementsPath) {
+/** pip argv for the agent's requirements, resolving from wheelsDir when given. */
+export function pipInstallArgs(requirementsPath, wheelsDir) {
+    const args = ["-m", "pip", "install", "--disable-pip-version-check", "--no-warn-script-location"];
+    // --no-index is what makes this airtight: pip must not reach PyPI even for a
+    // single unsatisfied transitive dependency.
+    if (wheelsDir)
+        args.push("--no-index", "--find-links", wheelsDir);
+    args.push("-r", requirementsPath);
+    return args;
+}
+function runPip(file, args) {
+    return spawnSync(file, args, { stdio: "inherit" });
+}
+export function ensureDependencies(python, requirementsPath, options = {}) {
     if (!existsSync(requirementsPath)) {
         throw new Error(`requirements.txt not found at ${requirementsPath}`);
     }
@@ -145,28 +243,37 @@ function ensureDependencies(python, requirementsPath) {
     const marker = existsSync(depsMarker) ? readFileSync(depsMarker, "utf-8").trim() : "";
     if (marker === requirementsHash)
         return;
-    console.log("Installing Python dependencies...");
-    const result = spawnSync(python, [
-        "-m",
-        "pip",
-        "install",
-        "--disable-pip-version-check",
-        "--no-warn-script-location",
-        "-r",
-        requirementsPath,
-    ], { stdio: "inherit" });
+    const { wheelsDir, exec = runPip } = options;
+    console.log(wheelsDir
+        ? `Installing Python dependencies from ${wheelsDir}...`
+        : "Installing Python dependencies...");
+    const result = exec(python, pipInstallArgs(requirementsPath, wheelsDir));
     if (result.status !== 0) {
+        if (wheelsDir) {
+            // Offline, so the usual causes (network, index) don't apply — an
+            // incomplete wheel set almost always means the bundle predates the
+            // requirements the server is now serving.
+            throw new Error(`pip install failed (exit ${result.status}). The wheels in ${wheelsDir} do not satisfy ` +
+                `${requirementsPath}. This usually means the CLI bundle is older than the requirements ` +
+                "your Aximo server is serving — install the CLI bundle from your current on-prem release.");
+        }
         throw new Error(`pip install failed (exit ${result.status})`);
     }
     writeFileSync(depsMarker, requirementsHash, { mode: 0o644 });
 }
 export async function ensurePythonReady(deps) {
-    const pythonPath = await ensurePython();
+    // The agent manifest comes first: it is what tells us whether the server can
+    // supply the interpreter and wheels, which decides where Python comes from.
     const agent = await ensureAgent(deps);
     if (agent.changed) {
         console.log(`Agent script updated to version ${agent.version}`);
     }
-    ensureDependencies(pythonPath, agent.requirementsPath);
+    warnIfCliOutdated(agent.manifest);
+    const pythonPath = await ensurePython(agent.manifest, deps);
+    // Staged files win over the server so a machine that cannot reach it at
+    // all — or is being prepared ahead of time — still works.
+    const wheelsDir = findOfflineWheelsDir() ?? (await ensureServerWheels(agent.manifest, deps));
+    ensureDependencies(pythonPath, agent.requirementsPath, { wheelsDir });
     return {
         pythonPath,
         scriptPath: agent.scriptPath,

package/dist/mobile-control/android-recovery.d.ts

@@ -0,0 +1,5 @@
+import { type ExecFn } from "./exec.js";
+export declare function isWedgedInstrumentationError(err: unknown): boolean;
+export declare const APPIUM_HELPER_PACKAGES: readonly ["io.appium.uiautomator2.server.test", "io.appium.uiautomator2.server", "io.appium.settings"];
+/** Remove stale Appium helper APKs (best-effort) so the driver reinstalls fresh ones. */
+export declare function uninstallAppiumHelpers(serial: string, exec?: ExecFn): Promise<void>;

package/dist/mobile-control/android-recovery.js

@@ -0,0 +1,19 @@
+import { execBinary } from "./exec.js";
+// Helper APKs left by an older driver version can wedge instrumentation: the
+// packages are installed but Android refuses to register the test runner, so
+// every session fails with one of these until the stale APKs are removed.
+const WEDGED_INSTRUMENTATION_PATTERN = /instrumentation process cannot be initialized|Unable to find instrumentation info|INSTRUMENTATION_FAILED/i;
+export function isWedgedInstrumentationError(err) {
+    return err instanceof Error && WEDGED_INSTRUMENTATION_PATTERN.test(err.message);
+}
+export const APPIUM_HELPER_PACKAGES = [
+    "io.appium.uiautomator2.server.test",
+    "io.appium.uiautomator2.server",
+    "io.appium.settings",
+];
+/** Remove stale Appium helper APKs (best-effort) so the driver reinstalls fresh ones. */
+export async function uninstallAppiumHelpers(serial, exec = execBinary) {
+    for (const pkg of APPIUM_HELPER_PACKAGES) {
+        await exec("adb", ["-s", serial, "uninstall", pkg]).catch(() => { });
+    }
+}

package/dist/mobile-control/android-recovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mobile-control/android-recovery.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { APPIUM_HELPER_PACKAGES, isWedgedInstrumentationError, uninstallAppiumHelpers, } from "./android-recovery.js";
+describe("isWedgedInstrumentationError", () => {
+    it("matches the driver's wedged-instrumentation signatures", () => {
+        expect(isWedgedInstrumentationError(new Error("WebDriver POST /session failed: unknown error: The instrumentation process cannot be initialized."))).toBe(true);
+        expect(isWedgedInstrumentationError(new Error("Unable to find instrumentation info for: ComponentInfo{io.appium.uiautomator2.server.test/androidx.test.runner.AndroidJUnitRunner}"))).toBe(true);
+        expect(isWedgedInstrumentationError(new Error("INSTRUMENTATION_FAILED: io.appium.uiautomator2.server.test/..."))).toBe(true);
+    });
+    it("does not match unrelated session errors or non-errors", () => {
+        expect(isWedgedInstrumentationError(new Error("Could not find a connected Android device"))).toBe(false);
+        expect(isWedgedInstrumentationError("instrumentation process cannot be initialized")).toBe(false);
+    });
+});
+describe("uninstallAppiumHelpers", () => {
+    it("uninstalls all helper packages for the given serial", async () => {
+        const calls = [];
+        const exec = async (_file, args) => {
+            calls.push(args);
+            return { stdout: Buffer.from("Success"), stderr: "" };
+        };
+        await uninstallAppiumHelpers("serial-1", exec);
+        expect(calls).toEqual(APPIUM_HELPER_PACKAGES.map((pkg) => ["-s", "serial-1", "uninstall", pkg]));
+    });
+    it("keeps going when an uninstall fails (package not installed)", async () => {
+        const calls = [];
+        const exec = async (_file, args) => {
+            calls.push(args);
+            throw new Error("Failure [DELETE_FAILED_INTERNAL_ERROR]");
+        };
+        await uninstallAppiumHelpers("serial-1", exec);
+        expect(calls).toHaveLength(APPIUM_HELPER_PACKAGES.length);
+    });
+});

package/dist/mobile-control/appium-controller.d.ts

@@ -1,4 +1,5 @@
 import type { ActionResult, MobileController } from "./controller.js";
+import type { ExecFn } from "./exec.js";
 import { type IosSigningConfig } from "./ios-signing.js";
 import { type WebDriverTransport } from "./webdriver.js";
 export interface AppiumControllerOptions {
@@ -19,6 +20,8 @@ export interface AppiumControllerOptions {
      */
     mjpegServerPort?: number | (() => Promise<number>);
     transport?: WebDriverTransport;
+    /** adb runner override for tests (used by the wedged-instrumentation repair). */
+    exec?: ExecFn;
 }
 export declare class AppiumController implements MobileController {
     private readonly session;
@@ -27,6 +30,7 @@ export declare class AppiumController implements MobileController {
     private readonly iosSigning;
     private readonly wdaLocalPort;
     private readonly mjpegServerPort;
+    private readonly exec;
     private resolvedWdaPort;
     private resolvedMjpegPort;
     private sessionReady;

package/dist/mobile-control/appium-controller.js

@@ -1,3 +1,4 @@
+import { isWedgedInstrumentationError, uninstallAppiumHelpers } from "./android-recovery.js";
 import { enrichIosSessionError } from "./ios-session-error.js";
 import { iosSigningCapabilities } from "./ios-signing.js";
 import { fetchTransport, WebDriverSession } from "./webdriver.js";
@@ -38,6 +39,7 @@ export class AppiumController {
     iosSigning;
     wdaLocalPort;
     mjpegServerPort;
+    exec;
     resolvedWdaPort;
     resolvedMjpegPort;
     sessionReady = null;
@@ -48,6 +50,7 @@ export class AppiumController {
         this.iosSigning = opts.iosSigning;
         this.wdaLocalPort = opts.wdaLocalPort;
         this.mjpegServerPort = opts.mjpegServerPort;
+        this.exec = opts.exec;
         const transport = opts.transport ?? fetchTransport(opts.endpoint);
         this.session = new WebDriverSession(transport);
     }
@@ -90,7 +93,18 @@ export class AppiumController {
                     typeof this.mjpegServerPort === "function"
                         ? await this.mjpegServerPort()
                         : this.mjpegServerPort;
-                await this.session.createSession(this.capabilities());
+                try {
+                    await this.session.createSession(this.capabilities());
+                }
+                catch (err) {
+                    // Stale helper APKs from an older driver wedge instrumentation until
+                    // they are removed; wipe them and retry once so the driver reinstalls.
+                    if (this.platform !== "android" || !isWedgedInstrumentationError(err))
+                        throw err;
+                    console.error("Stale Appium helper apps detected on the phone — removing them and retrying once.");
+                    await uninstallAppiumHelpers(this.target, this.exec);
+                    await this.session.createSession(this.capabilities());
+                }
                 await this.applyMjpegSettings();
             })().catch(async (err) => {
                 this.resetSession();

package/dist/mobile-control/appium-controller.test.js

@@ -95,6 +95,84 @@ function lastPointerActions(calls) {
     const groups = body["actions"];
     return groups[0]?.actions ?? [];
 }
+describe("AppiumController wedged-instrumentation recovery", () => {
+    function wedgedTransport(failures) {
+        const calls = [];
+        const transport = {
+            async request(method, path, body) {
+                calls.push({ method, path, body });
+                if (method === "POST" && path === "/session") {
+                    const failure = failures.shift();
+                    if (failure)
+                        throw new Error(failure);
+                    return { sessionId: "sess-1" };
+                }
+                if (path.endsWith("/screenshot"))
+                    return pngWithWidth(4);
+                return {};
+            },
+        };
+        return { transport, calls };
+    }
+    const WEDGED = "WebDriver POST /session failed: The instrumentation process cannot be initialized.";
+    it("uninstalls the helper APKs and retries once when instrumentation is wedged", async () => {
+        const adbCalls = [];
+        const exec = async (_file, args) => {
+            adbCalls.push(args);
+            return { stdout: Buffer.from(""), stderr: "" };
+        };
+        const { transport, calls } = wedgedTransport([WEDGED]);
+        const controller = new AppiumController({
+            endpoint: "http://x",
+            platform: "android",
+            target: "udid-1",
+            transport,
+            exec,
+        });
+        await controller.screenshot();
+        expect(calls.filter((c) => c.path === "/session" && c.method === "POST")).toHaveLength(2);
+        expect(adbCalls.map((a) => a.at(-1))).toEqual([
+            "io.appium.uiautomator2.server.test",
+            "io.appium.uiautomator2.server",
+            "io.appium.settings",
+        ]);
+        expect(adbCalls.every((a) => a[0] === "-s" && a[1] === "udid-1")).toBe(true);
+    });
+    it("does not attempt recovery for unrelated session errors", async () => {
+        const adbCalls = [];
+        const exec = async (_file, args) => {
+            adbCalls.push(args);
+            return { stdout: Buffer.from(""), stderr: "" };
+        };
+        const { transport } = wedgedTransport(["Could not find a connected Android device"]);
+        const controller = new AppiumController({
+            endpoint: "http://x",
+            platform: "android",
+            target: "udid-1",
+            transport,
+            exec,
+        });
+        await expect(controller.screenshot()).rejects.toThrow("connected Android device");
+        expect(adbCalls).toHaveLength(0);
+    });
+    it("does not attempt adb recovery on iOS", async () => {
+        const adbCalls = [];
+        const exec = async (_file, args) => {
+            adbCalls.push(args);
+            return { stdout: Buffer.from(""), stderr: "" };
+        };
+        const { transport } = wedgedTransport([WEDGED]);
+        const controller = new AppiumController({
+            endpoint: "http://x",
+            platform: "ios",
+            target: "udid-1",
+            transport,
+            exec,
+        });
+        await expect(controller.screenshot()).rejects.toThrow();
+        expect(adbCalls).toHaveLength(0);
+    });
+});
 describe("AppiumController session capabilities", () => {
     it("sends Android UiAutomator2 caps", async () => {
         const { controller, calls } = makeController("android");

package/dist/mobile-control/appium-import.js

@@ -1,6 +1,22 @@
 const APPIUM = "appium";
 export async function importAppium() {
-    // Appium 3 is CJS, so its `main` is under `.default` when imported from ESM.
-    const mod = (await import(APPIUM));
-    return mod.default ?? mod;
+    try {
+        // Appium 3 is CJS, so its `main` is under `.default` when imported from ESM.
+        const mod = (await import(APPIUM));
+        return mod.default ?? mod;
+    }
+    catch (err) {
+        // appium is left out of the single-file build — it pulls in native code the
+        // executable cannot carry — but `aximo mobile` still appears in --help.
+        //
+        // Both codes are needed: a CJS require reports MODULE_NOT_FOUND, while the
+        // dynamic ESM import used here reports ERR_MODULE_NOT_FOUND. The raw message
+        // also names the bundle's build-time path, which means nothing to a customer.
+        const code = err?.code;
+        if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") {
+            throw new Error("Mobile commands are unavailable in the single-file aximo build. " +
+                "Install the CLI from npm to use them: npm i -g @autifyhq/aximo-cli");
+        }
+        throw err;
+    }
 }

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>;