@autifyhq/aximo-cli 0.4.0 → 0.6.0

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;

package/dist/commands/device/register.js

@@ -1,10 +1,9 @@
-import { defineCommand } from "citty";
-import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { platform, release } from "node:os";
-import { request } from "../../client.js";
+import { defineCommand } from "citty";
+import { getBaseUrl, request } from "../../client.js";
 import { handleApiError } from "../../errors.js";
 import { formatError, formatSuccess, printResult } from "../../output.js";
-import { getAximoDir, getDeviceConfigPath } from "./paths.js";
+import { readDeviceConfig, writeDeviceConfig } from "./device-config.js";
 function detectPlatform() {
     const p = platform();
     if (p === "win32")
@@ -22,42 +21,59 @@ function detectOs() {
         return `macOS ${r}`;
     return `Linux ${r}`;
 }
+/** Whether deviceId is present among the user's devices on the targeted server. */
+async function deviceExistsOnServer(deviceId, deps) {
+    const res = await request("/api/devices/user", {}, deps);
+    return (res.devices ?? []).some((d) => d.id === deviceId);
+}
 export async function runDeviceRegister(options, deps) {
     try {
-        const configPath = getDeviceConfigPath();
-        if (existsSync(configPath) && !options.force) {
-            return formatError("validation_error", "A device is already registered on this machine. Run 'aximo device unregister' first, or pass --force to overwrite (this orphans the previous server-side device).", false);
+        const clientDeps = deps ?? {};
+        const baseUrl = clientDeps.baseUrl ?? getBaseUrl();
+        let replacedStale = false;
+        let previousBaseUrl;
+        const existing = readDeviceConfig();
+        if (existing && !options.force) {
+            // A local registration exists. It only truly conflicts if that device is
+            // still present on the server we're targeting. If it's gone — deleted, or
+            // registered against a different server (common when rotating ephemeral
+            // on-prem test boxes) — the local file is stale and we re-register instead
+            // of hard-blocking. When the server can't be reached to check, stay safe
+            // and block rather than silently clobber a possibly-valid registration.
+            let liveHere;
+            try {
+                liveHere = await deviceExistsOnServer(existing.deviceId, clientDeps);
+            }
+            catch (err) {
+                return formatError("validation_error", `A device is already registered on this machine and its status on ${baseUrl} ` +
+                    `could not be verified (${err instanceof Error ? err.message : String(err)}). ` +
+                    "Run 'aximo device unregister' first, or pass --force to overwrite.", false);
+            }
+            if (liveHere) {
+                return formatError("validation_error", `A device (${existing.deviceId}) is already registered on this machine and active on ${baseUrl}. ` +
+                    "Run 'aximo device unregister' first, or pass --force to overwrite (this orphans the previous server-side device).", false);
+            }
+            replacedStale = true;
+            previousBaseUrl = existing.baseUrl;
         }
         const res = await request("/api/devices/register", {
             method: "POST",
-            body: {
-                name: options.name,
-                platform: detectPlatform(),
-                os: detectOs(),
-            },
-        }, deps ?? {});
-        const aximoDir = getAximoDir();
-        if (!existsSync(aximoDir)) {
-            mkdirSync(aximoDir, { recursive: true });
-        }
+            body: { name: options.name, platform: detectPlatform(), os: detectOs() },
+        }, clientDeps);
         const registeredAt = new Date().toISOString();
-        const config = {
+        writeDeviceConfig({
             deviceId: res.deviceId,
             deviceToken: res.deviceToken,
             name: options.name,
             registeredAt,
-        };
-        writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
-        try {
-            chmodSync(configPath, 0o600);
-        }
-        catch {
-            // chmod may fail on Windows, file-level ACLs apply instead
-        }
+            baseUrl,
+        });
         return formatSuccess({
             deviceId: res.deviceId,
             name: options.name,
             registeredAt,
+            ...(replacedStale ? { replacedStale: true } : {}),
+            ...(previousBaseUrl ? { previousBaseUrl } : {}),
         });
     }
     catch (err) {
@@ -67,17 +83,19 @@ export async function runDeviceRegister(options, deps) {
 export default defineCommand({
     meta: { name: "register", description: "Register this machine as a BYOD device" },
     args: {
-        name: {
-            type: "string",
-            description: "Device name",
-            required: true,
-        },
+        name: { type: "string", description: "Device name", required: true },
         force: {
             type: "boolean",
             description: "Overwrite an existing local registration (orphans the previous device)",
         },
     },
     async run({ args }) {
-        printResult(await runDeviceRegister({ name: args.name, force: Boolean(args.force) }));
+        const result = await runDeviceRegister({ name: args.name, force: Boolean(args.force) });
+        printResult(result);
+        if (result.ok && result.data.replacedStale) {
+            const prev = result.data.previousBaseUrl;
+            console.error(`\nNote: replaced a stale local registration${prev ? ` (previously registered against ${prev})` : ""}. ` +
+                "If that device still exists on another server it is now orphaned — unregister it there if you no longer need it.");
+        }
     },
 });

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

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

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

@@ -0,0 +1,95 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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 { runDeviceRegister } from "./register.js";
+let tempHome;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-register-"));
+    process.env["AXIMO_HOME"] = tempHome;
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    process.env["AXIMO_API_KEY"] = "test-key";
+    server.listen();
+});
+afterAll(() => {
+    delete process.env["AXIMO_HOME"];
+    delete process.env["AXIMO_BASE_URL"];
+    delete process.env["AXIMO_API_KEY"];
+    server.close();
+    rmSync(tempHome, { recursive: true, force: true });
+});
+beforeEach(() => {
+    rmSync(tempHome, { recursive: true, force: true });
+    mkdirSync(tempHome, { recursive: true });
+});
+afterEach(() => server.resetHandlers());
+function devicePath() {
+    return join(tempHome, "device.json");
+}
+function seedDevice(cfg) {
+    writeFileSync(devicePath(), JSON.stringify(cfg), { mode: 0o600 });
+}
+function readDevice() {
+    return JSON.parse(readFileSync(devicePath(), "utf-8"));
+}
+describe("runDeviceRegister", () => {
+    it("registers fresh when no local device exists", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/devices/register`, () => HttpResponse.json({ deviceId: "new-1", deviceToken: "tok" })));
+        const result = await runDeviceRegister({ name: "mac" });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.deviceId).toBe("new-1");
+            expect(result.data.replacedStale).toBeUndefined();
+        }
+        expect(readDevice()).toMatchObject({ deviceId: "new-1", name: "mac", baseUrl: TEST_BASE_URL });
+    });
+    it("blocks when the local device is still live on the targeted server", async () => {
+        seedDevice({ deviceId: "dev-live", deviceToken: "t", name: "x", baseUrl: TEST_BASE_URL });
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ devices: [{ id: "dev-live" }] })));
+        const result = await runDeviceRegister({ name: "mac" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("validation_error");
+            expect(result.error.message).toContain("active on");
+        }
+        // Local file untouched (no POST happened).
+        expect(readDevice()).toMatchObject({ deviceId: "dev-live" });
+    });
+    it("re-registers when the local device is absent on the targeted server (stale)", async () => {
+        seedDevice({ deviceId: "dev-old", deviceToken: "t", name: "x", baseUrl: "https://old.server" });
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ devices: [] })), http.post(`${TEST_BASE_URL}/api/devices/register`, () => HttpResponse.json({ deviceId: "dev-new", deviceToken: "tok2" })));
+        const result = await runDeviceRegister({ name: "mac" });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.deviceId).toBe("dev-new");
+            expect(result.data.replacedStale).toBe(true);
+            // The replaced registration's server is surfaced, not silently dropped.
+            expect(result.data.previousBaseUrl).toBe("https://old.server");
+        }
+        expect(readDevice()).toMatchObject({ deviceId: "dev-new", baseUrl: TEST_BASE_URL });
+    });
+    it("blocks conservatively when the server cannot be reached to verify", async () => {
+        seedDevice({ deviceId: "dev-x", deviceToken: "t", name: "x" });
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ error: "boom" }, { status: 500 })));
+        const result = await runDeviceRegister({ name: "mac" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("validation_error");
+            expect(result.error.message).toContain("could not be verified");
+        }
+        expect(readDevice()).toMatchObject({ deviceId: "dev-x" });
+    });
+    it("--force overwrites without checking the server", async () => {
+        seedDevice({ deviceId: "dev-live", deviceToken: "t", name: "x", baseUrl: TEST_BASE_URL });
+        // The device list would 500; if --force consulted it, register would block.
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ error: "boom" }, { status: 500 })), http.post(`${TEST_BASE_URL}/api/devices/register`, () => HttpResponse.json({ deviceId: "dev-forced", deviceToken: "tok" })));
+        const result = await runDeviceRegister({ name: "mac", force: true });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.deviceId).toBe("dev-forced");
+            expect(result.data.replacedStale).toBeUndefined();
+        }
+        expect(readDevice()).toMatchObject({ deviceId: "dev-forced", baseUrl: TEST_BASE_URL });
+    });
+});

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

@@ -1,10 +1,12 @@
 import { type ClientDeps } from "../../client.js";
 import type { Envelope } from "../../types.js";
+export interface UnregisterResult {
+    success: boolean;
+    serverDeleted: boolean;
+}
 export declare function runDeviceUnregister(options: {
     deviceId?: string;
-}, deps?: ClientDeps): Promise<Envelope<{
-    success: boolean;
-}>>;
+}, deps?: ClientDeps): Promise<Envelope<UnregisterResult>>;
 declare const _default: import("citty").CommandDef<{
     readonly "device-id": {
         readonly type: "string";

package/dist/commands/device/unregister.js

@@ -1,49 +1,44 @@
+import { existsSync, unlinkSync } from "node:fs";
 import { defineCommand } from "citty";
-import { existsSync, unlinkSync, readFileSync } from "node:fs";
 import { request } from "../../client.js";
 import { handleApiError } from "../../errors.js";
-import { formatSuccess, formatError, printResult } from "../../output.js";
+import { formatError, formatSuccess, printResult } from "../../output.js";
+import { readDeviceConfig } from "./device-config.js";
 import { getDeviceConfigPath } from "./paths.js";
+function isNotFound(err) {
+    return typeof err === "object" && err !== null && err.status === 404;
+}
 export async function runDeviceUnregister(options, deps) {
-    let deviceId = options.deviceId;
-    if (!deviceId && existsSync(getDeviceConfigPath())) {
-        try {
-            const config = JSON.parse(readFileSync(getDeviceConfigPath(), "utf-8"));
-            if (config &&
-                typeof config === "object" &&
-                typeof config.deviceId === "string") {
-                deviceId = config.deviceId;
-            }
-            else {
-                return formatError("validation_error", "Device config is malformed: missing deviceId", false);
-            }
-        }
-        catch {
-            return formatError("validation_error", "Failed to read device config", false);
-        }
-    }
+    const local = readDeviceConfig();
+    const deviceId = options.deviceId ?? local?.deviceId;
     if (!deviceId) {
+        if (existsSync(getDeviceConfigPath())) {
+            return formatError("validation_error", "Local device config is unreadable. Pass a device ID, or clear it with: aximo device reset --device", false);
+        }
         return formatError("validation_error", "No device ID provided and no local device config found. " +
             "Pass a device ID or register first with: aximo device register", false);
     }
+    let serverDeleted = true;
     try {
         await request(`/api/devices/user/${deviceId}`, { method: "DELETE" }, deps ?? {});
-        if (existsSync(getDeviceConfigPath())) {
-            try {
-                const config = JSON.parse(readFileSync(getDeviceConfigPath(), "utf-8"));
-                if (config.deviceId === deviceId) {
-                    unlinkSync(getDeviceConfigPath());
-                }
-            }
-            catch {
-                // non-fatal
-            }
-        }
-        return formatSuccess({ success: true });
     }
     catch (err) {
-        return handleApiError(err);
+        // Already gone server-side — local cleanup is still the goal, so clear the
+        // file and report success. Re-surface any other error.
+        if (!isNotFound(err))
+            return handleApiError(err);
+        serverDeleted = false;
+    }
+    // Remove the local registration when it matches the device we just unregistered.
+    if (local && local.deviceId === deviceId && existsSync(getDeviceConfigPath())) {
+        try {
+            unlinkSync(getDeviceConfigPath());
+        }
+        catch {
+            // non-fatal
+        }
     }
+    return formatSuccess({ success: true, serverDeleted });
 }
 export default defineCommand({
     meta: { name: "unregister", description: "Unregister a device" },
@@ -55,6 +50,10 @@ export default defineCommand({
     },
     async run({ args }) {
         const deviceId = args["device-id"];
-        printResult(await runDeviceUnregister(deviceId ? { deviceId } : {}));
+        const result = await runDeviceUnregister(deviceId ? { deviceId } : {});
+        printResult(result);
+        if (result.ok && !result.data.serverDeleted) {
+            console.error("\nNote: the device was already absent on the server; cleared the local registration.");
+        }
     },
 });

package/dist/commands/device/unregister.test.d.ts

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