@autifyhq/aximo-cli 0.10.1 → 0.11.0

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
@@ -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/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,20 @@ export interface MobileDoctorReport {
         info: number;
     };
 }
+/**
+ * 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 declare function checkIosTunnel(isHealthy?: (port: number) => Promise<boolean>): Promise<Check>;
 export interface RunMobileDoctorOptions {
     platform?: "ios" | "android" | undefined;
     /** Injectable tunnel probe for tests. */
     isTunnelHealthy?: (port: number) => Promise<boolean>;
+    /** 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,6 +7,8 @@ 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";
 function which(cmd) {
@@ -138,6 +140,147 @@ 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.
@@ -159,7 +302,12 @@ export async function checkIosTunnel(isHealthy = isTunnelHealthy) {
 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()));

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

@@ -1,5 +1,70 @@
 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);

package/dist/desktop-server/agent-sync.d.ts

@@ -3,17 +3,37 @@ export interface AgentAssetInfo {
     sha256: string;
     size: number;
 }
+export interface BundleFileInfo extends AgentAssetInfo {
+    /** Path under /api/devices/agent/bundle/ that serves this file. */
+    path: string;
+}
+export interface BundlePythonInfo extends BundleFileInfo {
+    /** python-build-standalone archive filename, which encodes version + target. */
+    archive: string;
+}
 export interface AgentManifest {
-    manifestVersion: 2;
+    /**
+     * The offline setup fields below are optional additive fields on v2 — the
+     * server does not bump the version for them, because every published CLI
+     * rejects a version it does not recognise. Never gate the offline path on
+     * this number; gate it on whether those fields are present.
+     */
+    manifestVersion: 2 | 3;
     version: string;
+    minCliVersion?: string;
     script: AgentAssetInfo;
     requirements: AgentAssetInfo;
+    /** Offline setup assets, keyed by `${platform}-${arch}`. Absent = use GitHub/PyPI. */
+    python?: Record<string, BundlePythonInfo>;
+    wheels?: Record<string, BundleFileInfo[]>;
 }
 export interface EnsureAgentResult {
     scriptPath: string;
     requirementsPath: string;
     changed: boolean;
     version: string;
+    /** The server's manifest, so callers can see what it offers. */
+    manifest: AgentManifest;
 }
 export declare function ensureAgent(deps?: ClientDeps): Promise<EnsureAgentResult>;
 export declare function readCachedManifest(): AgentManifest | null;

package/dist/desktop-server/agent-sync.js

@@ -18,7 +18,7 @@ function readLocalManifest() {
         if (!parsed || typeof parsed !== "object")
             return null;
         const manifest = parsed;
-        if (manifest.manifestVersion === 2 &&
+        if ((manifest.manifestVersion === 2 || manifest.manifestVersion === 3) &&
             typeof manifest.version === "string" &&
             manifest.script?.sha256 &&
             manifest.requirements?.sha256) {
@@ -58,7 +58,9 @@ function validateManifest(raw) {
         throw new Error("Invalid agent manifest: response is not an object");
     }
     const m = raw;
-    if (m.manifestVersion !== 2) {
+    // v2 servers predate the offline assets; accept them so a newer CLI still
+    // works against an on-prem server that hasn't been upgraded yet.
+    if (m.manifestVersion !== 2 && m.manifestVersion !== 3) {
         throw new Error(`Unsupported agent manifest version: ${m.manifestVersion}. Update aximo-cli to the latest version.`);
     }
     if (typeof m.version !== "string" ||
@@ -111,6 +113,7 @@ export async function ensureAgent(deps) {
             requirementsPath: getAgentRequirementsPath(),
             changed: false,
             version: server.version,
+            manifest: server,
         };
     }
     const [scriptBuffer, requirementsBuffer] = await Promise.all([
@@ -134,6 +137,7 @@ export async function ensureAgent(deps) {
         requirementsPath: getAgentRequirementsPath(),
         changed: true,
         version: server.version,
+        manifest: server,
     };
 }
 export function readCachedManifest() {

package/dist/desktop-server/bundle-sync.d.ts

@@ -0,0 +1,25 @@
+import { type ClientDeps } from "../client.js";
+import type { AgentManifest, BundlePythonInfo } from "./agent-sync.js";
+/** Key the manifest uses for per-platform assets, e.g. win32-x64. */
+export declare function platformKey(): string;
+/**
+ * The server's Python archive for this platform, when it matches what this CLI
+ * expects.
+ *
+ * An archive name encodes the interpreter version and target, so comparing it to
+ * the name the CLI would have downloaded is the version check: a server offering
+ * a different interpreter than this CLI is pinned to is ignored rather than
+ * installed, because the CLI's compiled-in SHA256 would reject it anyway.
+ */
+export declare function resolveServerPython(manifest: AgentManifest, expectedArchive: string): BundlePythonInfo | undefined;
+/** Download the server's Python archive into the cache and verify it. */
+export declare function downloadServerPython(info: BundlePythonInfo, deps?: ClientDeps): Promise<string>;
+/**
+ * Mirror the server's wheels for this platform into the cache.
+ *
+ * Returns the directory to point pip at, or undefined when the server offers no
+ * wheels for this platform. Files the manifest no longer lists are removed:
+ * a leftover wheel from an older release could otherwise satisfy a requirement
+ * with the wrong version.
+ */
+export declare function ensureServerWheels(manifest: AgentManifest, deps?: ClientDeps): Promise<string | undefined>;