@autifyhq/aximo-cli 0.4.0 → 0.5.0

package/README.md

@@ -64,40 +64,46 @@ Credentials and device registrations are **per-environment** — to switch betwe
 
 Run `aximo <command> --help` for detailed usage. `aximo schema [command.path]` returns machine-readable argument introspection (e.g. `aximo schema session.create`).
 
-| Command                      | Description                                          |
-| ---------------------------- | ---------------------------------------------------- |
-| `aximo configure`            | Save credentials to `$AXIMO_HOME/config.json`        |
-| `aximo health check`         | Check API reachability                               |
-| `aximo project list`         | List organization projects                           |
-| `aximo session create`       | Create and queue a test session                      |
-| `aximo session get`          | Get session status                                   |
-| `aximo session save-as-case` | Save a finished session as a reusable test case      |
-| `aximo case create`          | Create a test case                                   |
-| `aximo case delete`          | Delete a test case                                   |
-| `aximo plan create`          | Create a test plan                                   |
-| `aximo plan add-case`        | Add a case to a plan                                 |
-| `aximo plan remove-case`     | Remove a case from a plan                            |
-| `aximo trigger case run`     | Trigger a dashboard-created test case                |
-| `aximo trigger case get`     | Get triggered case status                            |
-| `aximo trigger plan run`     | Trigger a test plan                                  |
-| `aximo trigger plan get`     | Get plan run status                                  |
-| `aximo upload create`        | Create an upload slot for an APK/IPA                 |
-| `aximo upload list`          | List previously uploaded apps                        |
-| `aximo upload get`           | Poll upload processing status                        |
-| `aximo upload put`           | Upload binary file to the slot                       |
-| `aximo upload submit`        | Finalize upload and trigger processing               |
-| `aximo device list`          | List mobile devices from Device Farm                 |
-| `aximo device setup`         | First-time BYOD onboarding (API + Python + register) |
-| `aximo device register`      | Register this machine as a BYOD device               |
-| `aximo device connect`       | Start the BYOD agent and connect to the relay        |
-| `aximo device status`        | List your organization's BYOD devices                |
-| `aximo device ping`          | Check your BYOD device's server-side status          |
-| `aximo device doctor`        | Diagnose BYOD setup (env, Python, relay, status)     |
-| `aximo device logs`          | Show the BYOD agent log                              |
-| `aximo device unregister`    | Remove a BYOD device server-side + clear local creds |
-| `aximo device reset`         | Remove BYOD local state (Python, deps, credentials)  |
-| `aximo schema`               | Show CLI surface as JSON                             |
-| `aximo mcp`                  | Run a stdio MCP server for agents (see below)        |
+| Command                      | Description                                            |
+| ---------------------------- | ------------------------------------------------------ |
+| `aximo configure`            | Save credentials to `$AXIMO_HOME/config.json`          |
+| `aximo health check`         | Check API reachability                                 |
+| `aximo project list`         | List organization projects                             |
+| `aximo session create`       | Create and queue a test session                        |
+| `aximo session get`          | Get session status                                     |
+| `aximo session save-as-case` | Save a finished session as a reusable test case        |
+| `aximo case create`          | Create a test case                                     |
+| `aximo case delete`          | Delete a test case                                     |
+| `aximo plan create`          | Create a test plan                                     |
+| `aximo plan add-case`        | Add a case to a plan                                   |
+| `aximo plan remove-case`     | Remove a case from a plan                              |
+| `aximo trigger case run`     | Trigger a dashboard-created test case                  |
+| `aximo trigger case get`     | Get triggered case status                              |
+| `aximo trigger plan run`     | Trigger a test plan                                    |
+| `aximo trigger plan get`     | Get plan run status                                    |
+| `aximo upload create`        | Create an upload slot for an APK/IPA                   |
+| `aximo upload list`          | List previously uploaded apps                          |
+| `aximo upload get`           | Poll upload processing status                          |
+| `aximo upload put`           | Upload binary file to the slot                         |
+| `aximo upload submit`        | Finalize upload and trigger processing                 |
+| `aximo device list`          | List mobile devices from Device Farm                   |
+| `aximo device setup`         | First-time BYOD onboarding (API + Python + register)   |
+| `aximo device register`      | Register this machine as a BYOD device                 |
+| `aximo device connect`       | Start the BYOD agent and connect to the relay          |
+| `aximo device status`        | List your organization's BYOD devices                  |
+| `aximo device ping`          | Check your BYOD device's server-side status            |
+| `aximo device doctor`        | Diagnose BYOD setup (env, Python, relay, status)       |
+| `aximo device logs`          | Show the BYOD agent log                                |
+| `aximo device unregister`    | Remove a BYOD device server-side + clear local creds   |
+| `aximo device reset`         | Remove BYOD local state (Python, deps, credentials)    |
+| `aximo mobile list`          | List physically-connected phones (Android via adb)     |
+| `aximo mobile setup`         | Install the Appium drivers used to drive phones        |
+| `aximo mobile doctor`        | Diagnose Appium prerequisites (adb, SDK, driver)       |
+| `aximo mobile register`      | Register a connected Android phone as an Aximo device  |
+| `aximo mobile connect`       | Start managed Appium + open the tunnel for the phone   |
+| `aximo mobile unregister`    | Remove a local mobile device server-side + local creds |
+| `aximo schema`               | Show CLI surface as JSON                               |
+| `aximo mcp`                  | Run a stdio MCP server for agents (see below)          |
 
 Mutating commands support `--json '<raw body>'` for direct OpenAPI payloads and `--dry-run` to preview requests without executing.
 
@@ -388,6 +394,64 @@ Default `$AXIMO_HOME` is `~/.aximo` on macOS/Linux, `%USERPROFILE%\.aximo` on Wi
 
 > Devices are registered per-environment (see [Configuration](#configuration)) — a device registered against sandbox can't connect to production and vice versa.
 
+## Mobile (local Android phone)
+
+The `mobile` commands let you register a **physically-connected Android phone** as an Aximo device and drive it locally, over the same gateway tunnel as desktop BYOD. Aximo's agent controls the phone through a CLI-managed [Appium](https://appium.io) (UiAutomator2) server — useful for running mobile tests against your own handset instead of a Device Farm device.
+
+> **Android only today.** iOS local devices are not yet supported — `aximo mobile register --platform ios` is blocked, and registration accepts only `--platform android`. (The Appium XCUITest plumbing is partially present but disabled; iOS local devices are planned for a future release.)
+
+Terminology note: **`aximo mobile list`** shows phones plugged into _this_ machine; **`aximo device list`** (under [Device / BYOD](#device-byod--bring-your-own-device)) returns mobile devices from AWS Device Farm. Don't confuse the two.
+
+### Prerequisites
+
+- **Node.js 20+**, plus `aximo-cli` installed globally (see [Install](#install)).
+- **An Aximo API key**, configured via `aximo configure` or env vars.
+- **A USB-connected Android phone** with **USB debugging** enabled in Developer Options, plugged in, and authorized (accept the "Allow USB debugging?" prompt on the phone).
+- **adb** (Android platform-tools) on your `PATH` — Appium delegates to it. Install via `brew install --cask android-platform-tools` (macOS), your distro's `adb` package (Linux), or the Android Studio SDK Manager (Windows).
+- **The Android SDK**, with `ANDROID_HOME` (or `ANDROID_SDK_ROOT`) set — e.g. installed via Android Studio. Appium's UiAutomator2 driver requires it even though adb is already on PATH.
+
+> The Appium server is bundled with the CLI, and the UiAutomator2 driver is installed by `aximo mobile setup` — you don't manage Appium yourself.
+
+### First-time setup
+
+```bash
+aximo mobile setup                          # installs the UiAutomator2 Appium driver
+aximo mobile doctor                         # checks adb / Android SDK / driver / bundled server
+```
+
+`setup` installs the Appium driver, then prints what (if anything) is still missing. `doctor` is the first thing to run when anything's off — it reports the bundled Appium server, the UiAutomator2 driver, `adb`, and the Android SDK in one shot, and exits non-zero if a required check fails.
+
+### Registering and connecting
+
+```bash
+aximo mobile list                                            # see connected phones + their adb serials
+aximo mobile register --name "My Pixel" --platform android   # --platform defaults to android
+aximo mobile connect                                         # starts managed Appium + opens the tunnel
+# Ctrl+C to disconnect
+```
+
+`register` writes credentials to `$AXIMO_HOME/mobile-devices/<deviceId>.json` (mode `0600`). It targets the single connected phone by default — pass `--serial` to pick a specific one when several are attached. `connect` re-checks prerequisites, starts the managed Appium server, and opens the tunnel; it runs until Ctrl+C. If you have more than one registered phone, pass `--device-id` to choose which to connect.
+
+Once connected, create a **mobile session in Aximo targeting this local device** — the agent routes its actions through the tunnel to the phone over Appium.
+
+### Managing devices
+
+```bash
+aximo mobile unregister                       # remove the locally registered device (server-side + local creds)
+aximo mobile unregister --device-id DEVICE_ID # target a specific device when several are registered
+```
+
+### Flags reference
+
+| Command                   | Flags                                                                               |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| `aximo mobile list`       | _(none)_                                                                            |
+| `aximo mobile setup`      | _(none)_                                                                            |
+| `aximo mobile doctor`     | _(none)_                                                                            |
+| `aximo mobile register`   | `--name <name>` (required), `--platform android` (default), `--serial <adb-serial>` |
+| `aximo mobile connect`    | `--device-id <id>` (required only if multiple devices are registered)               |
+| `aximo mobile unregister` | `--device-id <id>` (defaults to the locally registered device)                      |
+
 ## MCP server
 
 `aximo mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, exposing your recorded sessions, screenshots, and test cases to MCP-capable agents (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, …). The motivating use: let an agent read a finished session and generate a Playwright spec without you piping JSON between commands.

package/dist/cli.js

@@ -27,6 +27,7 @@ const main = defineCommand({
         plan: () => import("./commands/plan/index.js").then((m) => m.default),
         trigger: () => import("./commands/trigger/index.js").then((m) => m.default),
         device: () => import("./commands/device/index.js").then((m) => m.default),
+        mobile: () => import("./commands/mobile/index.js").then((m) => m.default),
         upload: () => import("./commands/upload/index.js").then((m) => m.default),
         project: () => import("./commands/project/index.js").then((m) => m.default),
         schema: () => import("./commands/schema.js").then((m) => m.default),

package/dist/commands/device/device-config.d.ts

@@ -0,0 +1,14 @@
+export interface DeviceConfig {
+    deviceId: string;
+    deviceToken: string;
+    name: string;
+    registeredAt: string;
+    baseUrl?: string;
+}
+/**
+ * Read and validate the local device registration (~/.aximo/device.json).
+ * Returns null when the file is missing, unreadable, or malformed.
+ */
+export declare function readDeviceConfig(): DeviceConfig | null;
+/** Persist the local device registration with owner-only permissions. */
+export declare function writeDeviceConfig(config: DeviceConfig): void;

package/dist/commands/device/device-config.js

@@ -0,0 +1,46 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { getAximoDir, getDeviceConfigPath } from "./paths.js";
+/**
+ * Read and validate the local device registration (~/.aximo/device.json).
+ * Returns null when the file is missing, unreadable, or malformed.
+ */
+export function readDeviceConfig() {
+    const path = getDeviceConfigPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const raw = parsed;
+        if (typeof raw.deviceId !== "string" ||
+            typeof raw.deviceToken !== "string" ||
+            typeof raw.name !== "string") {
+            return null;
+        }
+        return {
+            deviceId: raw.deviceId,
+            deviceToken: raw.deviceToken,
+            name: raw.name,
+            registeredAt: typeof raw.registeredAt === "string" ? raw.registeredAt : "",
+            ...(typeof raw.baseUrl === "string" ? { baseUrl: raw.baseUrl } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the local device registration with owner-only permissions. */
+export function writeDeviceConfig(config) {
+    const dir = getAximoDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = getDeviceConfigPath();
+    writeFileSync(path, JSON.stringify(config, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // chmod may fail on Windows; file-level ACLs apply instead.
+    }
+}

package/dist/commands/device/device-config.test.d.ts

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

package/dist/commands/device/device-config.test.js

@@ -0,0 +1,56 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readDeviceConfig, writeDeviceConfig } from "./device-config.js";
+let tempHome;
+beforeEach(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-device-config-"));
+    process.env["AXIMO_HOME"] = tempHome;
+});
+afterEach(() => {
+    delete process.env["AXIMO_HOME"];
+    rmSync(tempHome, { recursive: true, force: true });
+});
+function devicePath() {
+    return join(tempHome, "device.json");
+}
+describe("device-config", () => {
+    it("returns null when the file is missing", () => {
+        expect(readDeviceConfig()).toBeNull();
+    });
+    it("round-trips a config including baseUrl", () => {
+        writeDeviceConfig({
+            deviceId: "d1",
+            deviceToken: "tok",
+            name: "mac",
+            registeredAt: "2026-06-29T00:00:00.000Z",
+            baseUrl: "https://srv:8443",
+        });
+        expect(readDeviceConfig()).toEqual({
+            deviceId: "d1",
+            deviceToken: "tok",
+            name: "mac",
+            registeredAt: "2026-06-29T00:00:00.000Z",
+            baseUrl: "https://srv:8443",
+        });
+    });
+    it("reads a pre-AT-577 file with no baseUrl (backward compatible)", () => {
+        writeFileSync(devicePath(), JSON.stringify({ deviceId: "d1", deviceToken: "tok", name: "mac", registeredAt: "t" }));
+        const cfg = readDeviceConfig();
+        expect(cfg).not.toBeNull();
+        expect(cfg?.deviceId).toBe("d1");
+        expect(cfg?.baseUrl).toBeUndefined();
+    });
+    it("returns null for malformed json or a missing deviceId", () => {
+        writeFileSync(devicePath(), "{ not json");
+        expect(readDeviceConfig()).toBeNull();
+        writeFileSync(devicePath(), JSON.stringify({ deviceToken: "tok", name: "mac" }));
+        expect(readDeviceConfig()).toBeNull();
+    });
+    it("writes the file with owner-only permissions", () => {
+        writeDeviceConfig({ deviceId: "d1", deviceToken: "tok", name: "mac", registeredAt: "t" });
+        // Sanity: file is valid JSON and readable back.
+        expect(JSON.parse(readFileSync(devicePath(), "utf-8"))).toMatchObject({ deviceId: "d1" });
+    });
+});

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

@@ -17,6 +17,19 @@ export interface DoctorReport {
     };
 }
 export declare function relayProbeUrl(): string;
+export type TlsProbeResult = {
+    ok: true;
+} | {
+    ok: false;
+    kind: "cert" | "conn";
+    reason: string;
+};
+export interface AgentTlsDeps {
+    env?: NodeJS.ProcessEnv;
+    baseUrl?: string;
+    probe?: (host: string, port: number, ca: Buffer) => Promise<TlsProbeResult>;
+}
+export declare function checkAgentTlsTrust(deps?: AgentTlsDeps): Promise<Check>;
 export interface RunDoctorOptions {
     skipRelay?: boolean;
     skipApi?: boolean;

package/dist/commands/device/doctor.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { platform } from "node:os";
+import { connect as tlsConnect } from "node:tls";
 import { defineCommand } from "citty";
 import { WebSocket } from "ws";
 import { getBaseUrl, request } from "../../client.js";
@@ -8,6 +9,7 @@ import { loadConfig } from "../../config.js";
 import { readCachedManifest } from "../../desktop-server/agent-sync.js";
 import { installedPythonTag, PYTHON_RELEASE, PYTHON_VERSION } from "../../desktop-server/setup.js";
 import { formatSuccess, printResult } from "../../output.js";
+import { readDeviceConfig } from "./device-config.js";
 import { getAgentRequirementsPath, getAgentScriptPath, getDepsMarkerPath, getDeviceConfigPath, getEmbeddedPythonBinary, getPythonDir, getPythonMarkerPath, } from "./paths.js";
 function redactKey(value) {
     if (value.length <= 8)
@@ -68,8 +70,7 @@ async function checkApiHealth(deps) {
     }
 }
 function checkDeviceConfig() {
-    const configPath = getDeviceConfigPath();
-    if (!existsSync(configPath)) {
+    if (!existsSync(getDeviceConfigPath())) {
         return {
             check: {
                 name: "device registered",
@@ -79,37 +80,25 @@ function checkDeviceConfig() {
             },
         };
     }
-    try {
-        const config = JSON.parse(readFileSync(configPath, "utf-8"));
-        if (!config.deviceId) {
-            return {
-                check: {
-                    name: "device registered",
-                    status: "fail",
-                    message: "device.json missing deviceId",
-                    hint: "Re-register: aximo device register --name ...",
-                },
-            };
-        }
-        return {
-            check: {
-                name: "device registered",
-                status: "pass",
-                message: `${config.name ?? "(unnamed)"} · ${config.deviceId}`,
-            },
-            config,
-        };
-    }
-    catch (err) {
+    const config = readDeviceConfig();
+    if (!config) {
         return {
             check: {
                 name: "device registered",
                 status: "fail",
-                message: `device.json unreadable: ${err instanceof Error ? err.message : String(err)}`,
+                message: "device.json unreadable or missing required fields",
                 hint: "Delete the file and re-register",
             },
         };
     }
+    return {
+        check: {
+            name: "device registered",
+            status: "pass",
+            message: `${config.name} · ${config.deviceId}`,
+        },
+        config,
+    };
 }
 function checkEmbeddedPython() {
     if (!existsSync(getPythonDir())) {
@@ -303,6 +292,133 @@ function checkRelayReachable() {
         });
     });
 }
+const NET_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EAI_AGAIN",
+    "EPIPE",
+]);
+function classifyTlsError(err) {
+    const code = err.code ?? "";
+    if (NET_ERROR_CODES.has(code))
+        return "conn";
+    if (/CERT|SELF_SIGNED/.test(code) ||
+        /certificate|self.signed|verify|altname/i.test(err.message)) {
+        return "cert";
+    }
+    return "conn";
+}
+// TLS handshake to host:port trusting ONLY `ca`. Mirrors how the Python agent
+// verifies the relay via SSL_CERT_FILE, which replaces the whole trust store —
+// passing `ca` to tls.connect likewise replaces Node's default roots.
+function defaultTlsProbe(host, port, ca) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(r);
+        };
+        const socket = tlsConnect({ host, port, ca, servername: host, rejectUnauthorized: true }, () => {
+            socket.end();
+            finish({ ok: true });
+        });
+        socket.setTimeout(5_000, () => {
+            socket.destroy();
+            finish({ ok: false, kind: "conn", reason: "timed out" });
+        });
+        socket.on("error", (err) => {
+            socket.destroy();
+            finish({ ok: false, kind: classifyTlsError(err), reason: err.message });
+        });
+    });
+}
+const AGENT_TLS_CHECK_NAME = "agent TLS trust";
+// The desktop agent (Python) verifies the wss:// relay against SSL_CERT_FILE — a
+// different trust path than the Node CLI's NODE_EXTRA_CA_CERTS. A stale
+// SSL_CERT_FILE (e.g. a bundle from a previous ephemeral on-prem box) makes the
+// agent fail TLS even though every CLI check — including the relay handshake
+// above — passes. Catch that gap by validating the relay against the same bundle
+// the agent will use.
+export async function checkAgentTlsTrust(deps = {}) {
+    const name = AGENT_TLS_CHECK_NAME;
+    const env = deps.env ?? process.env;
+    const rawBase = deps.baseUrl ?? getBaseUrl();
+    let url;
+    try {
+        url = new URL(rawBase);
+    }
+    catch {
+        return { name, status: "info", message: `base URL not parseable: ${rawBase}` };
+    }
+    if (url.protocol !== "https:") {
+        return {
+            name,
+            status: "info",
+            message: "relay is plain ws:// (no TLS); SSL_CERT_FILE not used",
+        };
+    }
+    const sslCertFile = env["SSL_CERT_FILE"];
+    if (!sslCertFile) {
+        return env["NODE_EXTRA_CA_CERTS"]
+            ? {
+                name,
+                status: "info",
+                message: "SSL_CERT_FILE unset; agent bundle is built from NODE_EXTRA_CA_CERTS at connect",
+            }
+            : { name, status: "info", message: "SSL_CERT_FILE unset; agent trusts public CAs (certifi)" };
+    }
+    const unsetHint = "Unset SSL_CERT_FILE so the CLI rebuilds it from NODE_EXTRA_CA_CERTS, or regenerate the bundle for this server.";
+    if (!existsSync(sslCertFile)) {
+        return {
+            name,
+            status: "fail",
+            message: `SSL_CERT_FILE points at a missing file: ${sslCertFile}`,
+            hint: unsetHint,
+        };
+    }
+    let ca;
+    try {
+        ca = readFileSync(sslCertFile);
+    }
+    catch (err) {
+        return {
+            name,
+            status: "fail",
+            message: `SSL_CERT_FILE unreadable (${sslCertFile}): ${err instanceof Error ? err.message : String(err)}`,
+            hint: unsetHint,
+        };
+    }
+    const host = url.hostname;
+    const port = url.port ? Number(url.port) : 443;
+    const probe = deps.probe ?? defaultTlsProbe;
+    const result = await probe(host, port, ca);
+    if (result.ok) {
+        return {
+            name,
+            status: "pass",
+            message: `SSL_CERT_FILE verifies ${host}:${port} (agent TLS OK)`,
+        };
+    }
+    if (result.kind === "cert") {
+        return {
+            name,
+            status: "fail",
+            message: `SSL_CERT_FILE is set (${sslCertFile}) but does not verify ${host}:${port}: ${result.reason}`,
+            hint: unsetHint,
+        };
+    }
+    return {
+        name,
+        status: "info",
+        message: `could not reach ${host}:${port} to test SSL_CERT_FILE trust: ${result.reason}`,
+    };
+}
 async function checkCurrentStatus(deviceId, deps) {
     const name = "device status";
     try {
@@ -399,6 +515,7 @@ export async function runDeviceDoctor(options = {}, deps) {
     }
     if (!options.skipRelay) {
         checks.push(await checkRelayReachable());
+        checks.push(await checkAgentTlsTrust());
     }
     if (config?.deviceId && !options.skipApi && checks[0]?.status !== "fail") {
         checks.push(await checkCurrentStatus(config.deviceId, deps));

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

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
-import { relayProbeUrl, runDeviceDoctor } from "./doctor.js";
+import { checkAgentTlsTrust, relayProbeUrl, runDeviceDoctor } from "./doctor.js";
 let tempHome;
 beforeAll(() => {
     tempHome = mkdtempSync(join(tmpdir(), "aximo-doctor-"));
@@ -93,3 +93,63 @@ describe("relayProbeUrl", () => {
         expect(relayProbeUrl()).toBe(`${wsBase}/devices/tunnel/?EIO=4&transport=websocket`);
     });
 });
+describe("checkAgentTlsTrust", () => {
+    const HTTPS = "https://relay.test:8443";
+    it("is not applicable for a plain-http base (relay is ws://)", async () => {
+        const c = await checkAgentTlsTrust({ baseUrl: "http://relay.test:8080", env: {} });
+        expect(c.status).toBe("info");
+        expect(c.message).toContain("plain ws");
+    });
+    it("reports info when SSL_CERT_FILE is unset (CLI builds the bundle)", async () => {
+        const c = await checkAgentTlsTrust({
+            baseUrl: HTTPS,
+            env: { NODE_EXTRA_CA_CERTS: "/x/ca.pem" },
+        });
+        expect(c.status).toBe("info");
+        expect(c.message).toContain("NODE_EXTRA_CA_CERTS");
+    });
+    it("passes when SSL_CERT_FILE verifies the relay host", async () => {
+        const bundle = join(tempHome, "bundle.pem");
+        writeFileSync(bundle, "x");
+        const c = await checkAgentTlsTrust({
+            baseUrl: HTTPS,
+            env: { SSL_CERT_FILE: bundle },
+            probe: () => Promise.resolve({ ok: true }),
+        });
+        expect(c.status).toBe("pass");
+    });
+    it("fails when SSL_CERT_FILE is stale and can't verify the relay (the AT-577 trap)", async () => {
+        const bundle = join(tempHome, "bundle.pem");
+        writeFileSync(bundle, "x");
+        const c = await checkAgentTlsTrust({
+            baseUrl: HTTPS,
+            env: { SSL_CERT_FILE: bundle },
+            probe: () => Promise.resolve({
+                ok: false,
+                kind: "cert",
+                reason: "self signed certificate in certificate chain",
+            }),
+        });
+        expect(c.status).toBe("fail");
+        expect(c.message).toContain("does not verify");
+        expect(c.hint).toContain("Unset SSL_CERT_FILE");
+    });
+    it("reports info (not fail) when the relay host is unreachable", async () => {
+        const bundle = join(tempHome, "bundle.pem");
+        writeFileSync(bundle, "x");
+        const c = await checkAgentTlsTrust({
+            baseUrl: HTTPS,
+            env: { SSL_CERT_FILE: bundle },
+            probe: () => Promise.resolve({ ok: false, kind: "conn", reason: "ECONNREFUSED" }),
+        });
+        expect(c.status).toBe("info");
+    });
+    it("fails when SSL_CERT_FILE points at a missing file", async () => {
+        const c = await checkAgentTlsTrust({
+            baseUrl: HTTPS,
+            env: { SSL_CERT_FILE: join(tempHome, "nope.pem") },
+        });
+        expect(c.status).toBe("fail");
+        expect(c.message).toContain("missing file");
+    });
+});

package/dist/commands/device/register.d.ts

@@ -4,6 +4,8 @@ export interface RegisterResult {
     deviceId: string;
     name: string;
     registeredAt: string;
+    replacedStale?: boolean;
+    previousBaseUrl?: string;
 }
 export declare function runDeviceRegister(options: {
     name: string;