@autifyhq/aximo-cli 0.7.0 → 0.9.0

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

@@ -34,14 +34,18 @@ export declare class AppiumController implements MobileController {
     doubleTap(x: number, y: number): Promise<void>;
     longPress(x: number, y: number, durationMs: number): Promise<void>;
     swipe(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise<void>;
+    pinchZoom(x: number, y: number, scale: number, durationMs: number): Promise<void>;
     private performPointer;
     typeText(text: string): Promise<ActionResult>;
+    private activeElementOrNull;
     clearText(): Promise<ActionResult>;
     pressKey(key: string): Promise<ActionResult>;
     launchApp(app: string): Promise<ActionResult>;
     findElement(text: string): Promise<ActionResult>;
     private locate;
     hideKeyboard(): Promise<ActionResult>;
+    rotateDevice(orientation: "portrait" | "landscape"): Promise<ActionResult>;
+    setLocation(latitude: number, longitude: number, altitude: number): Promise<ActionResult>;
     getDeviceTime(): Promise<{
         datetime: string;
         timezone: string;

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

@@ -12,6 +12,8 @@ const ANDROID_KEY_CODES = {
 };
 const ANDROID_KEYCODE_A = 29;
 const ANDROID_META_CTRL_ON = 4096;
+// Chars that break Android's `mobile: type` (adb shell input text): shell metachars, non-ASCII.
+const ANDROID_INPUT_TEXT_UNSAFE = /[^A-Za-z0-9 @:,./+_=-]/;
 const IOS_BUTTONS = {
     home: "home",
 };
@@ -155,6 +157,31 @@ export class AppiumController {
             { type: "pointerUp", button: 0 },
         ]);
     }
+    // Two-finger vertical pinch: scale < 1 pinches in (zoom out), > 1 spreads (zoom in).
+    async pinchZoom(x, y, scale, durationMs) {
+        await this.ensureSession();
+        const [cx, cy] = await this.toPoint(x, y);
+        const startOffset = 100;
+        const endOffset = startOffset * scale;
+        const duration = Math.max(0, Math.round(durationMs));
+        const finger = (id, startY, endY) => ({
+            type: "pointer",
+            id,
+            parameters: { pointerType: "touch" },
+            actions: [
+                { type: "pointerMove", duration: 0, x: cx, y: Math.round(startY) },
+                { type: "pointerDown", button: 0 },
+                { type: "pause", duration: 50 },
+                { type: "pointerMove", duration, x: cx, y: Math.round(endY) },
+                { type: "pointerUp", button: 0 },
+            ],
+        });
+        await this.session.performActions([
+            finger("finger1", cy - startOffset / 2, cy - endOffset / 2),
+            finger("finger2", cy + startOffset / 2, cy + endOffset / 2),
+        ]);
+        await this.session.releaseActions();
+    }
     async performPointer(actions) {
         await this.session.performActions(this.pointerAction(actions));
         await this.session.releaseActions();
@@ -163,16 +190,42 @@ export class AppiumController {
         await this.ensureSession();
         try {
             if (this.platform === "android") {
+                if (ANDROID_INPUT_TEXT_UNSAFE.test(text)) {
+                    const active = await this.activeElementOrNull();
+                    if (!active) {
+                        return {
+                            ok: false,
+                            error: "Cannot type special or non-ASCII characters: no input field is focused. Tap the field first.",
+                        };
+                    }
+                    await this.session.elementSendKeys(active, text);
+                    return { ok: true };
+                }
                 await this.session.execute("mobile: type", [{ text }]);
                 return { ok: true };
             }
-            await this.session.setValueOnActiveElement(text);
+            // XCUITest: per-char W3C key actions; no focused element required.
+            const actions = [...text].flatMap((char) => [
+                { type: "keyDown", value: char },
+                { type: "keyUp", value: char },
+            ]);
+            await this.session.performActions([{ type: "key", id: "keyboard", actions }]);
+            await this.session.releaseActions();
             return { ok: true };
         }
         catch (error) {
             return fail(error);
         }
     }
+    // Some drivers report "no focus" by rejecting; treat that as null.
+    async activeElementOrNull() {
+        try {
+            return await this.session.getActiveElement();
+        }
+        catch {
+            return null;
+        }
+    }
     async clearText() {
         await this.ensureSession();
         try {
@@ -277,7 +330,8 @@ export class AppiumController {
         for (const [using, value] of strategies) {
             try {
                 const ref = await this.session.findElement(using, value);
-                if (ref)
+                // Skip hidden matches so the next strategy can find a visible one.
+                if (ref && (await this.session.elementDisplayed(ref)))
                     return ref;
             }
             catch { }
@@ -294,6 +348,40 @@ export class AppiumController {
             return { ok: true };
         }
     }
+    async rotateDevice(orientation) {
+        await this.ensureSession();
+        try {
+            const wantLandscape = orientation === "landscape";
+            await this.session.setOrientation(wantLandscape ? "LANDSCAPE" : "PORTRAIT");
+            // Rotation changes the window rect, so the cached pixel->point scale is stale.
+            this.scaling = null;
+            // Poll up to 2s until the OS reports the new dimensions; rotation speed varies.
+            const deadline = Date.now() + 2000;
+            while (Date.now() < deadline) {
+                try {
+                    const rect = await this.session.windowRect();
+                    if (rect.width > rect.height === wantLandscape)
+                        break;
+                }
+                catch { }
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+            return { ok: true };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    async setLocation(latitude, longitude, altitude) {
+        await this.ensureSession();
+        try {
+            await this.session.setGeoLocation({ latitude, longitude, altitude });
+            return { ok: true };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
     async getDeviceTime() {
         await this.ensureSession();
         try {

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

@@ -11,24 +11,47 @@ function fakeTransport(options = {}) {
     const calls = [];
     const windowWidth = options.windowWidth ?? 400;
     const screenshotWidth = options.screenshotWidth ?? 400;
+    const findQueue = options.findElementRefs ? [...options.findElementRefs] : null;
+    let landscape = false;
     const transport = {
         async request(method, path, body) {
             calls.push({ method, path, body });
             if (method === "POST" && path === "/session") {
                 return { sessionId: "sess-1" };
             }
+            if (path.endsWith("/orientation")) {
+                landscape = body.orientation === "LANDSCAPE";
+                return {};
+            }
+            if (path.endsWith("/location")) {
+                if (options.locationError)
+                    throw new Error(options.locationError);
+                return {};
+            }
             if (path.endsWith("/screenshot")) {
                 return pngWithWidth(screenshotWidth);
             }
             if (path.endsWith("/window/rect")) {
-                return { width: windowWidth, height: windowWidth * 2, x: 0, y: 0 };
+                return landscape
+                    ? { width: windowWidth * 2, height: windowWidth, x: 0, y: 0 }
+                    : { width: windowWidth, height: windowWidth * 2, x: 0, y: 0 };
             }
             if (path.endsWith("/element/active")) {
+                if (options.activeElementError)
+                    throw new Error(options.activeElementError);
                 const ref = options.activeElement === undefined ? "active-el" : options.activeElement;
                 return ref ? { [ELEMENT_KEY]: ref } : null;
             }
+            if (method === "GET" && path.endsWith("/displayed")) {
+                const ref = path.split("/").at(-2) ?? "";
+                return options.displayed ? options.displayed(ref) : true;
+            }
             if (method === "POST" && path.endsWith("/element")) {
-                const ref = options.findElementRef === undefined ? "found-el" : options.findElementRef;
+                const ref = findQueue
+                    ? (findQueue.shift() ?? null)
+                    : options.findElementRef === undefined
+                        ? "found-el"
+                        : options.findElementRef;
                 return ref ? { [ELEMENT_KEY]: ref } : null;
             }
             return {};
@@ -66,6 +89,12 @@ function pointerActions(calls) {
     const groups = body["actions"];
     return groups[0]?.actions ?? [];
 }
+function lastPointerActions(calls) {
+    const actionCalls = calls.filter((c) => c.path.endsWith("/actions") && c.method === "POST");
+    const body = (actionCalls[actionCalls.length - 1]?.body ?? {});
+    const groups = body["actions"];
+    return groups[0]?.actions ?? [];
+}
 describe("AppiumController session capabilities", () => {
     it("sends Android UiAutomator2 caps", async () => {
         const { controller, calls } = makeController("android");
@@ -145,6 +174,75 @@ describe("AppiumController touch actions", () => {
         expect(downs).toHaveLength(2);
     });
 });
+describe("AppiumController pinch zoom", () => {
+    it("sends two synchronized touch pointers split around the scaled center", async () => {
+        const { controller, calls } = makeController("ios", { windowWidth: 400, screenshotWidth: 800 });
+        await controller.pinchZoom(200, 400, 2, 500);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/actions") && c.method === "POST");
+        const groups = body["actions"];
+        expect(groups).toHaveLength(2);
+        expect(groups.every((g) => g.type === "pointer" && g.parameters.pointerType === "touch")).toBe(true);
+        expect(groups[0]?.id).not.toBe(groups[1]?.id);
+        // Center scales 2x to (100, 200); start offset ±50, end offset ±100 (100 * scale / 2).
+        expect(groups[0]?.actions[0]).toMatchObject({ type: "pointerMove", x: 100, y: 150 });
+        expect(groups[0]?.actions[3]).toMatchObject({
+            type: "pointerMove",
+            x: 100,
+            y: 100,
+            duration: 500,
+        });
+        expect(groups[1]?.actions[0]).toMatchObject({ type: "pointerMove", x: 100, y: 250 });
+        expect(groups[1]?.actions[3]).toMatchObject({
+            type: "pointerMove",
+            x: 100,
+            y: 300,
+            duration: 500,
+        });
+        expect(calls.some((c) => c.method === "DELETE" && c.path.endsWith("/actions"))).toBe(true);
+    });
+    it("moves fingers toward the center when scale < 1 (zoom out)", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.pinchZoom(100, 300, 0.5, 600);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/actions") && c.method === "POST");
+        const groups = body["actions"];
+        expect(groups[0]?.actions[3]).toMatchObject({ x: 100, y: 275 });
+        expect(groups[1]?.actions[3]).toMatchObject({ x: 100, y: 325 });
+    });
+});
+describe("AppiumController rotation + location", () => {
+    it("rotateDevice posts the W3C orientation and refreshes coordinate scaling", async () => {
+        const { controller, calls } = makeController("ios", { windowWidth: 400, screenshotWidth: 800 });
+        await controller.tap(200, 100); // caches the 2x pixel->point scale
+        const result = await controller.rotateDevice("landscape");
+        expect(result.ok).toBe(true);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/orientation"));
+        expect(body["orientation"]).toBe("LANDSCAPE");
+        // Landscape rect is 800pt wide -> scale is 1 now; a stale cache would halve these.
+        await controller.tap(200, 100);
+        const move = lastPointerActions(calls)[0];
+        expect(move.x).toBe(200);
+        expect(move.y).toBe(100);
+    });
+    it("rotateDevice maps portrait to PORTRAIT", async () => {
+        const { controller, calls } = makeController("android");
+        const result = await controller.rotateDevice("portrait");
+        expect(result.ok).toBe(true);
+        expect(bodyOf(calls, (c) => c.path.endsWith("/orientation"))["orientation"]).toBe("PORTRAIT");
+    });
+    it("setLocation posts the W3C location body", async () => {
+        const { controller, calls } = makeController("android");
+        const result = await controller.setLocation(35.68, 139.69, 10);
+        expect(result.ok).toBe(true);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/location"));
+        expect(body["location"]).toEqual({ latitude: 35.68, longitude: 139.69, altitude: 10 });
+    });
+    it("setLocation returns the WebDriver failure as a structured error", async () => {
+        const { controller } = makeController("android", { locationError: "mock location denied" });
+        const result = await controller.setLocation(1, 2, 0);
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("mock location denied");
+    });
+});
 describe("AppiumController text + keys", () => {
     it("typeText on Android uses mobile: type", async () => {
         const { controller, calls } = makeController("android");
@@ -154,12 +252,41 @@ describe("AppiumController text + keys", () => {
         expect(exec.script).toBe("mobile: type");
         expect(exec.args[0]?.["text"]).toBe("hello");
     });
-    it("typeText on iOS sends keys to the active element", async () => {
-        const { controller, calls } = makeController("ios");
-        await controller.typeText("hi");
-        expect(calls.some((c) => c.path.endsWith("/element/active"))).toBe(true);
-        const send = bodyOf(calls, (c) => c.path.endsWith("/element/active-el/value"));
-        expect(send["text"]).toBe("hi");
+    it("typeText on Android types unsafe text into the focused element", async () => {
+        const { controller, calls } = makeController("android", { activeElement: "el-1" });
+        const result = await controller.typeText("パスワード$1!");
+        expect(result.ok).toBe(true);
+        expect(calls.some((c) => c.path.endsWith("/execute/sync"))).toBe(false);
+        const send = bodyOf(calls, (c) => c.path.endsWith("/element/el-1/value"));
+        expect(send["text"]).toBe("パスワード$1!");
+    });
+    it("typeText on Android returns a clear error for unsafe text with no focused element", async () => {
+        const { controller } = makeController("android", { activeElement: null });
+        const result = await controller.typeText("p@ss!word");
+        expect(result.ok).toBe(false);
+        expect(result.error).toBe("Cannot type special or non-ASCII characters: no input field is focused. Tap the field first.");
+    });
+    it("typeText on Android treats an active-element rejection as no focus", async () => {
+        const { controller } = makeController("android", { activeElementError: "no such element" });
+        const result = await controller.typeText("héllo");
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("no input field is focused");
+    });
+    it("typeText on iOS sends per-char key actions without resolving the active element", async () => {
+        const { controller, calls } = makeController("ios", { activeElement: null });
+        const result = await controller.typeText("hi");
+        expect(result.ok).toBe(true);
+        expect(calls.some((c) => c.path.endsWith("/element/active"))).toBe(false);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/actions") && c.method === "POST");
+        const groups = body["actions"];
+        expect(groups[0]?.type).toBe("key");
+        expect(groups[0]?.actions).toEqual([
+            { type: "keyDown", value: "h" },
+            { type: "keyUp", value: "h" },
+            { type: "keyDown", value: "i" },
+            { type: "keyUp", value: "i" },
+        ]);
+        expect(calls.some((c) => c.method === "DELETE" && c.path.endsWith("/actions"))).toBe(true);
     });
     it("clearText clears the active element when present", async () => {
         const { controller, calls } = makeController("android", { activeElement: "el-9" });
@@ -220,6 +347,27 @@ describe("AppiumController findElement", () => {
         expect(result.ok).toBe(false);
         expect(result.error).toContain("not found");
     });
+    it("skips a non-displayed match and clicks the next strategy's visible one", async () => {
+        const { controller, calls } = makeController("android", {
+            findElementRefs: ["hidden-el", "vis-el"],
+            displayed: (ref) => ref === "vis-el",
+        });
+        const result = await controller.findElement("Sign in");
+        expect(result.ok).toBe(true);
+        expect(calls.some((c) => c.path.endsWith("/element/hidden-el/click"))).toBe(false);
+        expect(calls.some((c) => c.path.endsWith("/element/vis-el/click"))).toBe(true);
+        expect(calls.filter((c) => c.method === "POST" && c.path.endsWith("/element"))).toHaveLength(2);
+    });
+    it("treats a match that is never displayed as not found", async () => {
+        const { controller, calls } = makeController("ios", {
+            findElementRef: "hidden-el",
+            displayed: () => false,
+        });
+        const result = await controller.findElement("OK");
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("not found");
+        expect(calls.some((c) => c.path.includes("/click"))).toBe(false);
+    });
 });
 describe("AppiumController launch + lifecycle", () => {
     it("launchApp uses mobile: activateApp with appId on Android", async () => {

package/dist/mobile-control/bundle-id-map.js

@@ -12,12 +12,15 @@ export function withBundleIdTranslation(controller, map) {
         doubleTap: (x, y) => controller.doubleTap(x, y),
         longPress: (x, y, durationMs) => controller.longPress(x, y, durationMs),
         swipe: (x1, y1, x2, y2, durationMs) => controller.swipe(x1, y1, x2, y2, durationMs),
+        pinchZoom: (x, y, scale, durationMs) => controller.pinchZoom(x, y, scale, durationMs),
         typeText: (text) => controller.typeText(text),
         pressKey: (key) => controller.pressKey(key),
         launchApp: (app) => controller.launchApp(map.get(app) ?? app),
         findElement: (text) => controller.findElement(text),
         clearText: () => controller.clearText(),
         hideKeyboard: () => controller.hideKeyboard(),
+        rotateDevice: (orientation) => controller.rotateDevice(orientation),
+        setLocation: (latitude, longitude, altitude) => controller.setLocation(latitude, longitude, altitude),
         close: () => controller.close(),
     };
     if (controller.getDeviceTime) {

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

@@ -8,12 +8,15 @@ export interface MobileController {
     doubleTap(x: number, y: number): Promise<void>;
     longPress(x: number, y: number, durationMs: number): Promise<void>;
     swipe(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise<void>;
+    pinchZoom(x: number, y: number, scale: number, durationMs: number): Promise<void>;
     typeText(text: string): Promise<ActionResult>;
     pressKey(key: string): Promise<ActionResult>;
     launchApp(app: string): Promise<ActionResult>;
     findElement(text: string): Promise<ActionResult>;
     clearText(): Promise<ActionResult>;
     hideKeyboard(): Promise<ActionResult>;
+    rotateDevice(orientation: "portrait" | "landscape"): Promise<ActionResult>;
+    setLocation(latitude: number, longitude: number, altitude: number): Promise<ActionResult>;
     getDeviceTime?(): Promise<{
         datetime: string;
         timezone: string;

package/dist/mobile-control/exec.d.ts

@@ -2,5 +2,9 @@ export interface ExecResult {
     stdout: Buffer;
     stderr: string;
 }
-export type ExecFn = (file: string, args: string[]) => Promise<ExecResult>;
+export interface ExecOptions {
+    /** Working directory for the child (e.g. to zip relative paths). */
+    cwd?: string;
+}
+export type ExecFn = (file: string, args: string[], opts?: ExecOptions) => Promise<ExecResult>;
 export declare const execBinary: ExecFn;

package/dist/mobile-control/exec.js

@@ -1,7 +1,7 @@
 import { execFile } from "node:child_process";
 // Explicit argv, no shell — payloads can't inject into the local machine.
-export const execBinary = (file, args) => new Promise((resolve, reject) => {
-    execFile(file, args, { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+export const execBinary = (file, args, opts) => new Promise((resolve, reject) => {
+    execFile(file, args, { encoding: "buffer", maxBuffer: 64 * 1024 * 1024, ...(opts?.cwd ? { cwd: opts.cwd } : {}) }, (error, stdout, stderr) => {
         const stderrText = stderr.toString("utf-8");
         if (error) {
             const message = stderrText.trim() || error.message;

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

@@ -6,6 +6,8 @@
  * Older iOS and self-managed setups can opt out with AXIMO_IOS_SKIP_TUNNEL.
  */
 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
@@ -20,8 +22,9 @@ export interface TunnelScriptOptions {
 }
 /**
  * A self-contained shell script that launches the driver's `tunnel-creation` as a
- * detached background daemon. Run as root via the macOS auth prompt; it returns
- * immediately while the tunnel keeps running (health-checked via the registry port).
+ * fully detached daemon (own session, via {@link DAEMONIZE_PERL}). Run as root via
+ * the macOS auth prompt; it returns immediately while the tunnel keeps running
+ * (health-checked via the registry port).
  */
 export declare function buildTunnelScript(opts: TunnelScriptOptions): string;
 /** Prompt for admin rights (password/Touch ID) and run the tunnel script as root. */

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

@@ -13,6 +13,8 @@ import { envFlag } from "./env-flags.js";
  * Older iOS and self-managed setups can opt out with AXIMO_IOS_SKIP_TUNNEL.
  */
 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
@@ -36,17 +38,34 @@ export async function isTunnelHealthy(port = DEFAULT_TUNNEL_REGISTRY_PORT, host
 function shQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
+// Daemonize via perl (always present on macOS). A plain `nohup … &` does NOT
+// survive `do shell script … with administrator privileges`: the security
+// trampoline tears down its child's process group when the script returns, and
+// nohup only blocks SIGHUP — so the tunnel is killed before it initializes.
+// Double-fork + setsid moves the daemon into its own session and process group,
+// out of the trampoline's reach. $ARGV[0] is the log file; $ARGV[1..] the argv.
+const DAEMONIZE_PERL = [
+    "use POSIX qw(setsid);",
+    "open(STDIN, '<', '/dev/null');",
+    "open(STDOUT, '>', $ARGV[0]) or die $!;",
+    "open(STDERR, '>&', STDOUT);",
+    "exit if fork;", // top process (the trampoline's child) returns immediately
+    "setsid();", // child leads a new session — detached from the trampoline
+    "exit if fork;", // grandchild can never reacquire a controlling terminal
+    "exec(@ARGV[1 .. $#ARGV]) or die $!;",
+].join(" ");
 /**
  * A self-contained shell script that launches the driver's `tunnel-creation` as a
- * detached background daemon. Run as root via the macOS auth prompt; it returns
- * immediately while the tunnel keeps running (health-checked via the registry port).
+ * fully detached daemon (own session, via {@link DAEMONIZE_PERL}). Run as root via
+ * the macOS auth prompt; it returns immediately while the tunnel keeps running
+ * (health-checked via the registry port).
  */
 export function buildTunnelScript(opts) {
     return [
         "#!/bin/sh",
         `export APPIUM_HOME=${shQuote(opts.appiumHome)}`,
         'export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"',
-        `nohup ${shQuote(opts.nodePath)} ${shQuote(opts.appiumBin)} driver run xcuitest tunnel-creation > ${shQuote(opts.logFile)} 2>&1 &`,
+        `exec perl -e ${shQuote(DAEMONIZE_PERL)} ${shQuote(opts.logFile)} ${shQuote(opts.nodePath)} ${shQuote(opts.appiumBin)} driver run xcuitest tunnel-creation`,
         "",
     ].join("\n");
 }
@@ -81,7 +100,7 @@ async function pollHealthy(isHealthy, port, timeoutMs, logFile) {
     }
     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: sudo pkill -f tunnel-creation");
+        `be running; stop it before retrying: ${TUNNEL_STOP_COMMAND}`);
 }
 /**
  * Ensure the RemoteXPC tunnel is running so XCUITest can reach WebDriverAgent.
@@ -125,6 +144,7 @@ export async function ensureIosTunnel(options = {}) {
             `${shQuote(appiumBin)} driver run xcuitest tunnel-creation`);
     }
     await pollHealthy(isHealthy, port, options.readyTimeoutMs ?? 45_000, logFile);
-    log(`iOS device tunnel is up (registry on port ${port}).`);
+    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 };
 }

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

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { buildTunnelScript, DEFAULT_TUNNEL_REGISTRY_PORT, ensureIosTunnel } from "./ios-tunnel.js";
 describe("buildTunnelScript", () => {
-    it("backgrounds tunnel-creation as a detached daemon with APPIUM_HOME set", () => {
+    it("launches tunnel-creation as a setsid-detached daemon with APPIUM_HOME set", () => {
         const script = buildTunnelScript({
             appiumHome: "/home/u/.aximo/appium-home",
             nodePath: "/usr/bin/node",
@@ -9,8 +9,13 @@ describe("buildTunnelScript", () => {
             logFile: "/home/u/.aximo/ios-tunnel/tunnel.log",
         });
         expect(script).toContain("export APPIUM_HOME='/home/u/.aximo/appium-home'");
-        expect(script).toContain("nohup '/usr/bin/node' '/cli/node_modules/appium/index.js' driver run xcuitest tunnel-creation");
-        expect(script).toContain("> '/home/u/.aximo/ios-tunnel/tunnel.log' 2>&1 &");
+        // Detached via perl double-fork + setsid so the admin-elevation trampoline
+        // can't reap it (a plain `nohup … &` was killed on script exit).
+        expect(script).toContain("setsid()");
+        expect(script).toContain("'/usr/bin/node' '/cli/node_modules/appium/index.js' driver run xcuitest tunnel-creation");
+        // Log file is passed as the perl daemon's first argv (STDOUT/STDERR sink).
+        expect(script).toContain("'/home/u/.aximo/ios-tunnel/tunnel.log' '/usr/bin/node'");
+        expect(script).not.toContain("nohup");
     });
     it("escapes single quotes in paths", () => {
         const script = buildTunnelScript({

package/dist/mobile-control/ios-wda-preinstall.js

@@ -68,8 +68,11 @@ export async function preinstallWda(options) {
     }
     const scratch = mkdtempSync(join(tmpdir(), "aximo-wda-preinstall-"));
     try {
-        // Wrap the bare .app into Payload/ so it can go through the same resign path
-        // as any other IPA (ditto ships with macOS and handles both directions).
+        // Wrap the bare .app into Payload/ so it goes through the same resign path as
+        // any other IPA. Extract with ditto (it reads the Apple-produced zip cleanly)
+        // but REPACKAGE with `zip`: applesign's own extractor can't parse ditto's
+        // PKZip variant and rejects a ditto-built IPA as "Invalid IPA" (no .app found
+        // in Payload). `zip -qr Payload` from the wrap dir keeps Payload/ at the root.
         const payloadRoot = join(scratch, "wrap");
         const extractDir = join(payloadRoot, "Payload");
         mkdirSync(extractDir, { recursive: true });
@@ -78,7 +81,7 @@ export async function preinstallWda(options) {
             throw new Error(`Prebuilt WDA zip did not contain ${RUNNER_APP} — re-download or report.`);
         }
         const wrappedIpa = join(scratch, "wda.ipa");
-        await exec("ditto", ["-c", "-k", payloadRoot, wrappedIpa]);
+        await exec("zip", ["-qr", wrappedIpa, "Payload"], { cwd: payloadRoot });
         const runnerBundleId = `${options.wdaBundleId}.xctrunner`;
         const resignedIpa = join(scratch, "wda-resigned.ipa");
         log(`Signing WebDriverAgent as ${runnerBundleId}…`);

package/dist/mobile-control/ios-wda-preinstall.test.js

@@ -33,15 +33,19 @@ describe("preinstallWda", () => {
     afterEach(() => {
         rmSync(cacheDir, { recursive: true, force: true });
     });
-    /** ditto fake: -x -k extract creates the runner app; -c -k creates the archive. */
-    const dittoExec = async (file, args) => {
+    /** exec fake: `ditto -x` extracts the runner app; `zip` writes the IPA archive. */
+    const execFake = async (file, args, opts) => {
         if (file === "ditto" && args[0] === "-x") {
             const dest = args[3];
             if (dest)
                 mkdirSync(join(dest, "WebDriverAgentRunner-Runner.app"), { recursive: true });
         }
-        if (file === "ditto" && args[0] === "-c") {
-            const out = args[3];
+        if (file === "zip") {
+            // Like real zip: the relative Payload argument only resolves against opts.cwd.
+            if (!opts?.cwd || !existsSync(join(opts.cwd, "Payload"))) {
+                throw new Error("zip error: Nothing to do (Payload not found in cwd)");
+            }
+            const out = args[1];
             if (out)
                 writeFileSync(out, "zip");
         }
@@ -53,7 +57,7 @@ describe("preinstallWda", () => {
             identityHash: "A".repeat(40),
             profilePath: "/profiles/wda.mobileprovision",
             wdaBundleId: "com.aximo.wda.testteam99",
-            exec: dittoExec,
+            exec: execFake,
             cacheDir,
             wdaVersion: "15.0.0",
             fetchImpl: vi.fn(async (_input) => new Response(new ArrayBuffer(8), { status: 200 })),
@@ -76,7 +80,7 @@ describe("preinstallWda", () => {
             profilePath: "/profiles/wda.mobileprovision",
             bundleId: "com.aximo.wda.testteam99.xctrunner",
         }));
-        expect(opts.install).toHaveBeenCalledWith("UDID-1", expect.stringContaining("wda-resigned"), dittoExec);
+        expect(opts.install).toHaveBeenCalledWith("UDID-1", expect.stringContaining("wda-resigned"), execFake);
         // Second run: cache hit, no new download.
         await preinstallWda(opts);
         expect(opts.fetchImpl).toHaveBeenCalledOnce();
@@ -93,7 +97,7 @@ describe("preinstallWda", () => {
         await expect(preinstallWda(opts)).rejects.toThrow(/aximo mobile setup/);
     });
     it("fails loudly when the zip has an unexpected layout", async () => {
-        const badDitto = async (file, args) => {
+        const badExec = async (file, args) => {
             if (file === "ditto" && args[0] === "-x") {
                 const dest = args[3];
                 if (dest)
@@ -101,7 +105,7 @@ describe("preinstallWda", () => {
             }
             return { stdout: Buffer.from(""), stderr: "" };
         };
-        const opts = { ...makeOptions(), exec: badDitto };
+        const opts = { ...makeOptions(), exec: badExec };
         await expect(preinstallWda(opts)).rejects.toThrow(/did not contain/);
     });
 });