@autifyhq/aximo-cli 0.10.1 → 0.11.1

package/README.md

@@ -222,7 +222,7 @@ Terminology note: **`aximo device list` returns mobile devices** from Device Far
 
 ### Prerequisites
 
-- **Node.js 20.18+**, plus `aximo-cli` installed globally (see [Install](#install)).
+- **Node.js 20.18+**, plus `aximo-cli` installed globally (see [Install](#install)). On-prem releases also ship a single-file executable that needs neither — see [Air-gapped networks](#air-gapped-networks-no-internet-access).
 - **An Aximo API key**, configured via `aximo configure` or env vars.
 - **Active desktop session** — the agent uses `pyautogui` for screenshots and input, so the screen must be unlocked and awake while tests run. On **macOS**, grant the terminal **Accessibility** and **Screen Recording** permissions (System Settings → Privacy & Security) — without them actions silently do nothing.
 - **Outbound WebSocket to port 443** — most corporate firewalls allow this; if yours doesn't, see [Troubleshooting](#byod-troubleshooting).
@@ -298,6 +298,41 @@ export SSL_CERT_FILE="$HOME/.aximo/agent-ca-bundle.pem"
 
 Persist whichever variables you use in your shell profile. Public-CA servers (e.g. `aximo.autify.com`) need none of this.
 
+### Air-gapped networks (no internet access)
+
+Normally setup reaches the internet three times: npm for the CLI, GitHub for the embedded Python, and PyPI for the agent's packages. With no internet, all three fail.
+
+On-prem releases carry all three, and the server hands out the last two — a test machine only needs to reach your Aximo server, which it must anyway to register and run tests. See the on-prem installation guide for the full walkthrough; in short:
+
+```powershell
+# 1. Copy cli-bundle\cli\aximo-<version>-win32-x64.exe off the server onto the machine.
+#    One self-contained file: no npm, no Node.js install needed.
+C:\Aximo\aximo.exe configure          # base URL + API key
+
+# 2. The interpreter and packages come from your server, not the internet.
+C:\Aximo\aximo.exe device setup
+C:\Aximo\aximo.exe device register --name "My PC"
+C:\Aximo\aximo.exe device connect
+```
+
+Nothing declares "I am air-gapped" — the server advertises what it can supply, and the CLI uses GitHub and PyPI only when it cannot. Cloud and proxied setups are unaffected.
+
+**Staging the files by hand.** If you need the interpreter and wheels on a machine that cannot reach the server either (preparing a golden image, for example), point `AXIMO_OFFLINE_DIR` at a directory holding them:
+
+```text
+$AXIMO_OFFLINE_DIR/
+├── cpython-3.12.13+20260414-<target>-install_only.tar.gz
+└── wheels/*.whl
+```
+
+Staged files take precedence over the server. The archive is verified against the same checksum the CLI uses for the GitHub download, so a wrong or corrupted file is rejected rather than installed. Set the variable to an empty value to force the normal online path.
+
+Build the wheels on the platform they will run on — most of the agent's requirements are published as source only, so `pip download --platform ... --only-binary=:all:` cannot resolve them:
+
+```bash
+python -m pip wheel -r requirements.txt -w wheels   # run on the target platform, Python 3.12
+```
+
 ### Managing devices
 
 ```bash
@@ -511,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
 
@@ -528,6 +563,8 @@ Exact labels vary by manufacturer and Android version, but the flow is:
 
 > Keep the phone **unlocked** the first time you run a session: the initial command installs Appium's UiAutomator2 helper and creates the automation session on the device.
 
+> **OPPO / Realme / OnePlus (ColorOS / OxygenOS):** also enable **Developer options → Disable Permission Monitoring**, then **reboot the phone**. These ROMs block the adb commands Appium depends on (hidden-API policy, the Unicode keyboard used for text input) until this is on — sessions may start, but typing and other tools fail with `WRITE_SECURE_SETTINGS` errors. `aximo mobile doctor` detects this lockdown (the **secure settings** check) and confirms the fix after the reboot. The toggle can silently reset after a system update — re-enable it if the check regresses.
+
 ### First-time setup
 
 ```bash
@@ -623,7 +660,7 @@ claude mcp add aximo -- aximo mcp
 
 VS Code (Copilot agent mode) uses the same entry under a `servers` key in `.vscode/mcp.json`.
 
-The server exposes 18 tools: 12 read-only ones for inspecting sessions, cases, and plan runs (`aximo_get_session_timeline` is the load-bearing one for Playwright export; `aximo_list_plan_runs` and `aximo_get_plan_run` cover run-status polling) plus 6 that author content (create and delete cases, create plans, save a session as a case). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
+The server exposes 21 tools: 14 read-only ones for inspecting sessions, cases, plans, and plan runs (`aximo_get_session_timeline` is the load-bearing one for Playwright export; `aximo_list_plans` and `aximo_get_plan` cover plan discovery; `aximo_list_plan_runs` and `aximo_get_plan_run` cover run-status polling) plus 7 that author content (create and delete cases, create and update plans, save a session as a case). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
 
 ## Agent Skills
 

package/dist/cli.js

@@ -35,7 +35,17 @@ const main = defineCommand({
         mcp: () => import("./commands/mcp/index.js").then((m) => m.default),
     },
 });
-// Honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY for every fetch the CLI makes (the
-// embedded-Python download, API calls). No-op unless a proxy is configured.
-await installProxySupport();
-runMain(main);
+// Kept out of top-level await so the entry can also be bundled to CommonJS for
+// the single-file build, which has no equivalent.
+async function start() {
+    // Honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY for every fetch the CLI makes (the
+    // embedded-Python download, API calls). No-op unless a proxy is configured.
+    await installProxySupport();
+    runMain(main);
+}
+start().catch((err) => {
+    // Without this a failure here is an unhandled rejection, which in the single-file
+    // build means a bare V8 trace instead of the CLI's own error shape.
+    process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "internal_error", message: err instanceof Error ? err.message : String(err), retryable: false } })}\n`);
+    process.exitCode = 1;
+});

package/dist/commands/mcp/server.test.js

@@ -24,7 +24,7 @@ async function connect() {
     };
 }
 describe("createMcpServer wiring", () => {
-    it("exposes all 18 tools through tools/list with valid JSON Schema", async () => {
+    it("exposes all 21 tools through tools/list with valid JSON Schema", async () => {
         const { client, cleanup } = await connect();
         try {
             const { tools } = await client.listTools();
@@ -44,6 +44,9 @@ describe("createMcpServer wiring", () => {
                 "aximo_create_plan",
                 "aximo_add_case_to_plan",
                 "aximo_remove_case_from_plan",
+                "aximo_list_plans",
+                "aximo_get_plan",
+                "aximo_update_plan",
                 "aximo_list_plan_runs",
                 "aximo_get_plan_run",
                 "aximo_save_session_as_case",

package/dist/commands/mcp/tools.js

@@ -260,6 +260,49 @@ export function defineTools(deps = {}) {
                 return await request(`/api/plans/${encodeURIComponent(planId)}/cases/${encodeURIComponent(caseId)}`, { method: "DELETE" }, deps);
             }),
         },
+        {
+            name: "aximo_list_plans",
+            title: "List test plans",
+            description: "List a workspace's test plans, most recently updated first, with case counts. apiEnabled marks plans that can be triggered through the API. Filter with search (matches title and description). Use aximo_get_plan for a plan's full detail and cases.",
+            inputSchema: {
+                projectId: z.string().uuid(),
+                search: z.string().optional(),
+                page: z.number().int().positive().optional(),
+                pageSize: z.number().int().positive().max(100).optional(),
+            },
+            handler: async (input) => call(async () => {
+                return await request("/api/plans", { query: buildQuery(input) }, deps);
+            }),
+        },
+        {
+            name: "aximo_get_plan",
+            title: "Get test plan",
+            description: "Get a test plan's full detail: settings (executionMode, stopOnFailure, apiEnabled), plan variables (secret values are masked as ***), and its cases in execution order.",
+            inputSchema: {
+                planId: z.string().uuid(),
+            },
+            handler: async ({ planId }) => call(async () => {
+                return await request(`/api/plans/${encodeURIComponent(planId)}`, {}, deps);
+            }),
+        },
+        {
+            name: "aximo_update_plan",
+            title: "Update test plan",
+            description: "Update a test plan's title, description, executionMode (parallel or sequential), or stopOnFailure (sequential runs only). Omitted fields are left unchanged; at least one field is required.",
+            inputSchema: {
+                planId: z.string().uuid(),
+                title: z.string().min(1).max(500).optional(),
+                description: z.string().optional(),
+                executionMode: z.enum(["parallel", "sequential"]).optional(),
+                stopOnFailure: z.boolean().optional(),
+            },
+            handler: async ({ planId, ...body }) => call(async () => {
+                if (Object.keys(body).length === 0) {
+                    throw new Error("at least one field to update is required");
+                }
+                return await request(`/api/plans/${encodeURIComponent(planId)}`, { method: "PATCH", body }, deps);
+            }),
+        },
         {
             name: "aximo_list_plan_runs",
             title: "List plan runs",

package/dist/commands/mcp/tools.test.js

@@ -36,6 +36,9 @@ describe("defineTools", () => {
             "aximo_create_plan",
             "aximo_add_case_to_plan",
             "aximo_remove_case_from_plan",
+            "aximo_list_plans",
+            "aximo_get_plan",
+            "aximo_update_plan",
             "aximo_list_plan_runs",
             "aximo_get_plan_run",
             "aximo_save_session_as_case",
@@ -143,6 +146,107 @@ describe("aximo_list_projects", () => {
         expect(new URL(captured.url).pathname).toBe("/api/organizations/projects");
     });
 });
+describe("aximo_list_plans", () => {
+    const projectId = "44444444-4444-4444-8444-444444444444";
+    it("calls /api/plans, passing filters through as query params", async () => {
+        let url = null;
+        const payload = {
+            items: [
+                {
+                    id: "55555555-5555-4555-9555-555555555555",
+                    projectId,
+                    title: "Nightly regression",
+                    description: null,
+                    apiEnabled: true,
+                    caseCount: 3,
+                    hasMobileCases: false,
+                    createdAt: "2026-07-01T00:00:00.000Z",
+                    updatedAt: "2026-07-02T00:00:00.000Z",
+                    createdBy: null,
+                },
+            ],
+            totalCount: 1,
+            page: 1,
+            pageSize: 25,
+            totalPages: 1,
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/plans`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_plans");
+        const result = await tool.handler({ projectId, search: "regression", page: 1, pageSize: 25 });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(url).not.toBeNull();
+        expect(url.searchParams.get("projectId")).toBe(projectId);
+        expect(url.searchParams.get("search")).toBe("regression");
+    });
+});
+describe("aximo_get_plan", () => {
+    const planId = "55555555-5555-4555-9555-555555555555";
+    it("calls /api/plans/:id and returns the detail with cases and masked secrets", async () => {
+        const payload = {
+            id: planId,
+            title: "Nightly regression",
+            apiEnabled: true,
+            executionMode: "sequential",
+            stopOnFailure: true,
+            variables: [{ name: "PASSWORD", value: "***", isSecret: true }],
+            cases: [{ id: "66666666-6666-4666-9666-666666666666", order: 1, type: "web" }],
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/plans/${planId}`, () => HttpResponse.json(payload)));
+        const tool = byName(defineTools(), "aximo_get_plan");
+        const result = await tool.handler({ planId });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+    });
+    it("preserves the backend's 404 for an unknown plan", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/plans/${planId}`, () => HttpResponse.json({ error: "Test plan not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_get_plan");
+        const result = await tool.handler({ planId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("Test plan not found");
+    });
+});
+describe("aximo_update_plan", () => {
+    const planId = "55555555-5555-4555-9555-555555555555";
+    it("PATCHes /api/plans/:id with only the provided fields", async () => {
+        let body = null;
+        const payload = {
+            success: true,
+            plan: {
+                id: planId,
+                title: "Renamed",
+                description: null,
+                executionMode: "sequential",
+                stopOnFailure: false,
+                updatedAt: "2026-07-02T00:00:00.000Z",
+            },
+        };
+        server.use(http.patch(`${TEST_BASE_URL}/api/plans/${planId}`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_update_plan");
+        const result = await tool.handler({ planId, title: "Renamed", executionMode: "sequential" });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(body).toEqual({ title: "Renamed", executionMode: "sequential" });
+    });
+    it("rejects an update with no fields instead of issuing an empty PATCH", async () => {
+        let called = false;
+        server.use(http.patch(`${TEST_BASE_URL}/api/plans/${planId}`, () => {
+            called = true;
+            return HttpResponse.json({ success: true });
+        }));
+        const tool = byName(defineTools(), "aximo_update_plan");
+        const result = await tool.handler({ planId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("at least one field to update is required");
+        expect(called).toBe(false);
+    });
+});
 describe("aximo_list_plan_runs", () => {
     const planId = "77777777-7777-4777-9777-777777777777";
     it("calls /api/triggers/plans/:id/runs, passing limit and cursor through", async () => {

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

@@ -1,4 +1,5 @@
 import type { Envelope } from "../../types.js";
+import { type ExecFn } from "../../mobile-control/exec.js";
 export type CheckStatus = "pass" | "warn" | "fail" | "info";
 export interface Check {
     name: string;
@@ -15,11 +16,27 @@ export interface MobileDoctorReport {
         info: number;
     };
 }
-export declare function checkIosTunnel(isHealthy?: (port: number) => Promise<boolean>): Promise<Check>;
+/**
+ * Device-state checks for the connected Android phone: visibility/authorization,
+ * whether adb may write secure settings (ColorOS-family ROMs deny it until
+ * "Disable Permission Monitoring" is enabled), and whether stale Appium helper
+ * APKs have wedged instrumentation. Only called when adb itself is available.
+ */
+export declare function checkAndroidDevice(exec?: ExecFn): 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;
 }
 export declare function runMobileDoctor(options?: RunMobileDoctorOptions): Promise<Envelope<MobileDoctorReport>>;
 export declare function renderDoctorReport(data: MobileDoctorReport): string;

package/dist/commands/mobile/doctor.js

@@ -7,8 +7,11 @@ import { formatSuccess } from "../../output.js";
 import { printMobileResult } from "./output.js";
 import { importAppium } from "../../mobile-control/appium-import.js";
 import { getAppiumHome, resolveAndroidSdk } from "../../mobile-control/appium-server.js";
+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" });
@@ -138,33 +141,197 @@ async function checkIos() {
     });
     return checks;
 }
+const SECURE_SETTINGS_PROBE_KEY = "aximo_doctor_probe";
+const UIA2_TEST_PACKAGE = "io.appium.uiautomator2.server.test";
+/**
+ * Device-state checks for the connected Android phone: visibility/authorization,
+ * whether adb may write secure settings (ColorOS-family ROMs deny it until
+ * "Disable Permission Monitoring" is enabled), and whether stale Appium helper
+ * APKs have wedged instrumentation. Only called when adb itself is available.
+ */
+export async function checkAndroidDevice(exec = execBinary) {
+    let phones;
+    try {
+        phones = (await listAndroidDevices(exec)).filter((d) => !d.serial.startsWith("emulator-"));
+    }
+    catch (err) {
+        return [
+            {
+                name: "android device",
+                status: "warn",
+                message: `could not list devices: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        ];
+    }
+    const ready = phones.filter((d) => d.state === "device");
+    const first = ready[0];
+    if (!first) {
+        if (phones.some((d) => d.state === "unauthorized")) {
+            return [
+                {
+                    name: "android device",
+                    status: "fail",
+                    message: "Android device is unauthorized",
+                    hint: "Unlock the phone and accept the 'Allow USB debugging?' prompt (tick 'Always allow'). If no prompt appears, replug the cable or revoke USB debugging authorizations in Developer options.",
+                },
+            ];
+        }
+        if (phones.some((d) => d.state === "offline")) {
+            return [
+                {
+                    name: "android device",
+                    status: "fail",
+                    message: "Android device is offline",
+                    hint: "Reconnect the USB cable and unlock the phone.",
+                },
+            ];
+        }
+        return [
+            {
+                name: "android device",
+                status: "info",
+                message: "no Android phone detected over USB",
+                hint: "Enable Developer options → USB debugging, use a data-capable cable, and accept the 'Allow USB debugging?' prompt (see 'Enable USB debugging on the phone' in the README).",
+            },
+        ];
+    }
+    const extra = ready.length > 1 ? ` — ${ready.length} connected, probing the first` : "";
+    const checks = [
+        {
+            name: "android device",
+            status: "pass",
+            message: `${first.serial}${first.model ? ` (${first.model})` : ""}${extra}`,
+        },
+    ];
+    checks.push(await probeSecureSettings(first.serial, exec));
+    const wedged = await probeInstrumentation(first.serial, exec);
+    if (wedged)
+        checks.push(wedged);
+    return checks;
+}
+// Behavioral probe: a harmless global-settings write, cleaned up immediately.
+// This is the exact permission the driver needs for the hidden-api policy and
+// the Unicode IME (text input) — ColorOS/OxygenOS deny it to the adb shell
+// until "Disable Permission Monitoring" is enabled (GEN-2741).
+async function probeSecureSettings(serial, exec) {
+    try {
+        await exec("adb", [
+            "-s",
+            serial,
+            "shell",
+            "settings",
+            "put",
+            "global",
+            SECURE_SETTINGS_PROBE_KEY,
+            "1",
+        ]);
+        await exec("adb", [
+            "-s",
+            serial,
+            "shell",
+            "settings",
+            "delete",
+            "global",
+            SECURE_SETTINGS_PROBE_KEY,
+        ]).catch(() => { });
+        return { name: "secure settings", status: "pass", message: "adb can write secure settings" };
+    }
+    catch {
+        return {
+            name: "secure settings",
+            status: "warn",
+            message: "the device blocks adb secure-settings writes",
+            hint: "OPPO/Realme/OnePlus (ColorOS/OxygenOS): enable Developer options → 'Disable Permission Monitoring', reboot the phone, then re-run `aximo mobile doctor`. Without it, sessions start but text input and other adb-backed tools fail. The toggle can reset after a system update.",
+        };
+    }
+}
+// Stale helper APKs from an older driver wedge instrumentation: the package is
+// installed but Android no longer registers its test runner. Best-effort probe;
+// silent when the APKs are absent (fresh device) or healthy.
+async function probeInstrumentation(serial, exec) {
+    try {
+        const { stdout: pkgs } = await exec("adb", [
+            "-s",
+            serial,
+            "shell",
+            "pm",
+            "list",
+            "packages",
+            UIA2_TEST_PACKAGE,
+        ]);
+        if (!pkgs.toString("utf-8").includes(`package:${UIA2_TEST_PACKAGE}`))
+            return null;
+        const { stdout: instr } = await exec("adb", [
+            "-s",
+            serial,
+            "shell",
+            "pm",
+            "list",
+            "instrumentation",
+        ]);
+        if (instr.toString("utf-8").includes(`${UIA2_TEST_PACKAGE}/`))
+            return null;
+        return {
+            name: "appium instrumentation",
+            status: "warn",
+            message: "stale Appium helper apps: instrumentation is not registered (sessions fail with 'instrumentation process cannot be initialized')",
+            hint: "`aximo mobile connect` repairs this automatically on the next session. Manual fix: adb uninstall io.appium.uiautomator2.server.test, then io.appium.uiautomator2.server.",
+        };
+    }
+    catch {
+        return null;
+    }
+}
 // 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()];
     if (options.platform !== "ios") {
-        checks.push(...checkAndroid());
+        const androidChecks = checkAndroid();
+        checks.push(...androidChecks);
+        // Device-state checks need a working adb; skip them when the host check failed.
+        if (androidChecks.some((c) => c.name === "adb" && c.status === "pass")) {
+            checks.push(...(await checkAndroidDevice(options.exec)));
+        }
     }
     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

@@ -1,13 +1,89 @@
 import { describe, expect, it } from "vitest";
-import { checkIosTunnel, renderDoctorReport } from "./doctor.js";
+import { checkAndroidDevice, checkIosTunnel, renderDoctorReport } from "./doctor.js";
+// Canned adb: each key is matched against the joined argv; first hit wins.
+function fakeAdb(handlers) {
+    return async (_file, args) => {
+        const joined = args.join(" ");
+        for (const [key, value] of Object.entries(handlers)) {
+            if (joined.includes(key)) {
+                if (value instanceof Error)
+                    throw value;
+                return { stdout: Buffer.from(value), stderr: "" };
+            }
+        }
+        return { stdout: Buffer.from(""), stderr: "" };
+    };
+}
+const DEVICE_LIST = "List of devices attached\nserial-1  device model:Pixel_9a\n";
+describe("checkAndroidDevice", () => {
+    it("reports info with USB-debugging guidance when no phone is detected", async () => {
+        const checks = await checkAndroidDevice(fakeAdb({ "devices -l": "List of devices attached\n" }));
+        expect(checks).toHaveLength(1);
+        expect(checks[0]).toMatchObject({ name: "android device", status: "info" });
+        expect(checks[0]?.hint).toContain("USB debugging");
+    });
+    it("fails with the RSA-prompt hint when the phone is unauthorized", async () => {
+        const checks = await checkAndroidDevice(fakeAdb({ "devices -l": "List of devices attached\nserial-1  unauthorized\n" }));
+        expect(checks[0]).toMatchObject({ name: "android device", status: "fail" });
+        expect(checks[0]?.hint).toContain("Allow USB debugging");
+    });
+    it("fails when the phone is offline", async () => {
+        const checks = await checkAndroidDevice(fakeAdb({ "devices -l": "List of devices attached\nserial-1  offline\n" }));
+        expect(checks[0]).toMatchObject({ name: "android device", status: "fail" });
+    });
+    it("passes the device and secure-settings checks on a healthy phone", async () => {
+        const checks = await checkAndroidDevice(fakeAdb({ "devices -l": DEVICE_LIST }));
+        expect(checks).toHaveLength(2);
+        expect(checks[0]).toMatchObject({ name: "android device", status: "pass" });
+        expect(checks[0]?.message).toContain("Pixel_9a");
+        expect(checks[1]).toMatchObject({ name: "secure settings", status: "pass" });
+    });
+    it("warns with Disable Permission Monitoring guidance when secure-settings writes are blocked", async () => {
+        const checks = await checkAndroidDevice(fakeAdb({
+            "devices -l": DEVICE_LIST,
+            "settings put": new Error("java.lang.SecurityException: uid 2000 does not have android.permission.WRITE_SECURE_SETTINGS"),
+        }));
+        expect(checks[1]).toMatchObject({ name: "secure settings", status: "warn" });
+        expect(checks[1]?.hint).toContain("Disable Permission Monitoring");
+    });
+    it("warns about stale helper apps when the test APK is installed but unregistered", async () => {
+        const checks = await checkAndroidDevice(fakeAdb({
+            "devices -l": DEVICE_LIST,
+            "pm list packages": "package:io.appium.uiautomator2.server.test\n",
+            "pm list instrumentation": "instrumentation:com.android.something/...\n",
+        }));
+        const wedged = checks.find((c) => c.name === "appium instrumentation");
+        expect(wedged).toMatchObject({ status: "warn" });
+        expect(wedged?.hint).toContain("aximo mobile connect");
+    });
+    it("stays silent about instrumentation when the helper APKs are healthy", async () => {
+        const checks = await checkAndroidDevice(fakeAdb({
+            "devices -l": DEVICE_LIST,
+            "pm list packages": "package:io.appium.uiautomator2.server.test\n",
+            "pm list instrumentation": "instrumentation:io.appium.uiautomator2.server.test/androidx.test.runner.AndroidJUnitRunner (target=io.appium.uiautomator2.server.test)\n",
+        }));
+        expect(checks.find((c) => c.name === "appium instrumentation")).toBeUndefined();
+    });
+});
 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");
     });