@vellumai/cli 0.11.4-dev.202608190416.3aa24ff → 0.11.4-dev.202608191511.29bfca9

package/node_modules/@vellumai/local-mode/src/devices.test.ts

@@ -0,0 +1,290 @@
+import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
+import { EventEmitter } from "node:events";
+
+import type { CliInvocation } from "./util";
+
+class FakeChild extends EventEmitter {
+  stdout = new EventEmitter();
+  stderr = new EventEmitter();
+  kill = mock(() => true);
+}
+
+let lastChild: FakeChild;
+const spawnArgs: Array<[string, string[], { stdio?: unknown }]> = [];
+const spawnMock = mock(
+  (command: string, args: string[], options: { stdio?: unknown }) => {
+    spawnArgs.push([command, args, options]);
+    lastChild = new FakeChild();
+    return lastChild;
+  },
+);
+
+mock.module("node:child_process", () => ({ spawn: spawnMock }));
+
+let runDevicesList: typeof import("./devices").runDevicesList;
+let runDevicesRevoke: typeof import("./devices").runDevicesRevoke;
+
+beforeAll(async () => {
+  ({ runDevicesList, runDevicesRevoke } = await import("./devices"));
+});
+
+afterEach(() => {
+  spawnArgs.length = 0;
+  spawnMock.mockClear();
+});
+
+const invocation: CliInvocation = { command: "bun", baseArgs: ["run", "cli"] };
+
+describe("runDevicesList", () => {
+  test("spawns the CLI devices command and parses the JSON document", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from(
+        JSON.stringify({
+          devices: [
+            {
+              hashedDeviceId: "hash-a",
+              platform: "ios",
+              issuedAt: 1000,
+              expiresAt: 2000,
+              lastUsedAt: 1500,
+            },
+          ],
+        }),
+      ),
+    );
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({
+      ok: true,
+      devices: [
+        {
+          hashedDeviceId: "hash-a",
+          platform: "ios",
+          issuedAt: 1000,
+          expiresAt: 2000,
+          lastUsedAt: 1500,
+        },
+      ],
+    });
+    expect(spawnArgs[0]).toEqual([
+      "bun",
+      ["run", "cli", "devices", "asst-42", "--json"],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    ]);
+  });
+
+  test("tolerates null and non-numeric timestamps", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from(
+        JSON.stringify({
+          devices: [
+            {
+              hashedDeviceId: "hash-b",
+              platform: "web",
+              issuedAt: null,
+              expiresAt: "soon",
+            },
+          ],
+        }),
+      ),
+    );
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({
+      ok: true,
+      devices: [
+        {
+          hashedDeviceId: "hash-b",
+          platform: "web",
+          issuedAt: null,
+          expiresAt: null,
+          lastUsedAt: null,
+        },
+      ],
+    });
+  });
+
+  test("passes isCurrentHost through only when literally true", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from(
+        JSON.stringify({
+          devices: [
+            {
+              hashedDeviceId: "hash-host",
+              platform: "cli",
+              issuedAt: 1000,
+              expiresAt: null,
+              lastUsedAt: null,
+              isCurrentHost: true,
+            },
+            {
+              hashedDeviceId: "hash-truthy",
+              platform: "ios",
+              issuedAt: 1000,
+              expiresAt: null,
+              lastUsedAt: null,
+              isCurrentHost: "yes",
+            },
+            {
+              hashedDeviceId: "hash-false",
+              platform: "ios",
+              issuedAt: 1000,
+              expiresAt: null,
+              lastUsedAt: null,
+              isCurrentHost: false,
+            },
+          ],
+        }),
+      ),
+    );
+    lastChild.emit("close", 0);
+
+    const result = await pending;
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.devices.map((d) => d.isCurrentHost)).toEqual([
+        true,
+        undefined,
+        undefined,
+      ]);
+      expect("isCurrentHost" in result.devices[1]!).toBe(false);
+    }
+  });
+
+  test("an empty device list parses to no records", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.stdout.emit("data", Buffer.from('{ "devices": [] }'));
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true, devices: [] });
+  });
+
+  test("malformed stdout resolves to a failure with a snippet", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.stdout.emit("data", Buffer.from("not json"));
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({
+      ok: false,
+      error: "CLI returned unparseable devices output: not json",
+    });
+  });
+
+  test("a record missing hashedDeviceId resolves to a failure", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from(JSON.stringify({ devices: [{ platform: "ios" }] })),
+    );
+    lastChild.emit("close", 0);
+
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toStartWith("CLI returned unparseable devices output");
+    }
+  });
+
+  test("a non-zero exit resolves to a failure carrying stderr", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.stderr.emit("data", Buffer.from("devices failed"));
+    lastChild.emit("close", 1);
+
+    expect(await pending).toEqual({
+      ok: false,
+      error: "devices failed",
+    });
+  });
+
+  test("a spawn error resolves to a failure", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.emit("error", new Error("ENOENT"));
+
+    expect(await pending).toEqual({
+      ok: false,
+      error: "Failed to spawn CLI: ENOENT",
+    });
+  });
+});
+
+describe("runDevicesRevoke", () => {
+  test("spawns the CLI revoke command and succeeds on exit 0", async () => {
+    const pending = runDevicesRevoke(invocation, "asst-42", "hash-a");
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from('{ "ok": true, "hashedDeviceId": "hash-a" }'),
+    );
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true });
+    expect(spawnArgs[0]).toEqual([
+      "bun",
+      ["run", "cli", "devices", "revoke", "hash-a", "asst-42", "--yes", "--json"],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    ]);
+  });
+
+  test("a non-zero exit resolves to a failure carrying stderr", async () => {
+    const pending = runDevicesRevoke(invocation, "asst-42", "hash-a");
+    lastChild.stderr.emit("data", Buffer.from("revoke failed"));
+    lastChild.emit("close", 1);
+
+    expect(await pending).toEqual({
+      ok: false,
+      error: "revoke failed",
+    });
+  });
+
+  test("a spawn error resolves to a failure", async () => {
+    const pending = runDevicesRevoke(invocation, "asst-42", "hash-a");
+    lastChild.emit("error", new Error("EACCES"));
+
+    expect(await pending).toEqual({
+      ok: false,
+      error: "Failed to spawn CLI: EACCES",
+    });
+  });
+
+  test("multi-line stderr with a trailing Error: line surfaces just that message", async () => {
+    const pending = runDevicesRevoke(invocation, "asst-42", "hash-a");
+    lastChild.stderr.emit(
+      "data",
+      Buffer.from(
+        [
+          "Device to revoke:",
+          "  Platform: ios",
+          "  Issued:   2026-01-01",
+          "",
+          "Error: Gateway is unreachable",
+          "",
+        ].join("\n"),
+      ),
+    );
+    lastChild.emit("close", 1);
+
+    expect(await pending).toEqual({
+      ok: false,
+      error: "Gateway is unreachable",
+    });
+  });
+
+  test("stderr without an Error: line falls back to the whole stderr", async () => {
+    const pending = runDevicesRevoke(invocation, "asst-42", "hash-a");
+    lastChild.stderr.emit(
+      "data",
+      Buffer.from("Device to revoke:\n  Platform: ios\n"),
+    );
+    lastChild.emit("close", 1);
+
+    expect(await pending).toEqual({
+      ok: false,
+      error: "Device to revoke:\n  Platform: ios",
+    });
+  });
+});

package/node_modules/@vellumai/local-mode/src/devices.ts

@@ -0,0 +1,188 @@
+import { spawn } from "node:child_process";
+
+import type { CliInvocation } from "./util";
+
+// Fast loopback HTTP calls; well under the lifecycle-op timeouts.
+const DEVICES_TIMEOUT_MS = 30_000;
+
+/**
+ * Mirrors one row of the gateway's `GET /v1/devices` response. The gateway
+ * stores only the HASHED device id, so `hashedDeviceId` is both the display
+ * identifier and the revocation key.
+ */
+export interface DeviceRecord {
+  hashedDeviceId: string;
+  platform: string;
+  issuedAt: number | null;
+  expiresAt: number | null;
+  lastUsedAt: number | null;
+  /** True when this row is the hosting machine's own guardian credential. */
+  isCurrentHost?: boolean;
+}
+
+export type DevicesListResult =
+  | { ok: true; devices: DeviceRecord[] }
+  | { ok: false; error: string };
+
+export type DevicesRevokeResult =
+  { ok: true } | { ok: false; error: string };
+
+type CliRunResult =
+  | { ok: true; stdout: string }
+  | { ok: false; error: string };
+
+// The CLI prints an identity preamble before acting, so a failure transcript
+// is multi-line; surface only the final "Error:" line when one exists.
+function extractCliError(stderr: string, stdout: string): string {
+  const errorLines = stderr
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("Error:"));
+  const last = errorLines[errorLines.length - 1];
+  if (last) {
+    return last.slice("Error:".length).trim();
+  }
+  return (stderr || stdout).trim();
+}
+
+function runDevicesCli(
+  invocation: CliInvocation,
+  args: string[],
+): Promise<CliRunResult> {
+  return new Promise((resolve) => {
+    const child = spawn(
+      invocation.command,
+      [...invocation.baseArgs, ...args],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const finish = (result: CliRunResult) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({
+        ok: false,
+        error: `Devices command timed out after ${DEVICES_TIMEOUT_MS / 1000} seconds`,
+      });
+    }, DEVICES_TIMEOUT_MS);
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        finish({ ok: true, stdout });
+      } else {
+        finish({ ok: false, error: extractCliError(stderr, stdout) });
+      }
+    });
+
+    child.on("error", (err) => {
+      finish({
+        ok: false,
+        error: `Failed to spawn CLI: ${err.message}`,
+      });
+    });
+  });
+}
+
+function toTimestamp(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function parseDeviceRecords(stdout: string): DeviceRecord[] | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const devices = (parsed as { devices?: unknown }).devices;
+  if (!Array.isArray(devices)) {
+    return null;
+  }
+
+  const records: DeviceRecord[] = [];
+  for (const entry of devices) {
+    if (typeof entry !== "object" || entry === null) {
+      return null;
+    }
+    const {
+      hashedDeviceId,
+      platform,
+      issuedAt,
+      expiresAt,
+      lastUsedAt,
+      isCurrentHost,
+    } = entry as Record<string, unknown>;
+    if (typeof hashedDeviceId !== "string" || typeof platform !== "string") {
+      return null;
+    }
+    records.push({
+      hashedDeviceId,
+      platform,
+      issuedAt: toTimestamp(issuedAt),
+      expiresAt: toTimestamp(expiresAt),
+      lastUsedAt: toTimestamp(lastUsedAt),
+      // Tolerant passthrough: only a literal `true` survives.
+      ...(isCurrentHost === true ? { isCurrentHost: true } : {}),
+    });
+  }
+  return records;
+}
+
+export async function runDevicesList(
+  invocation: CliInvocation,
+  assistantId: string,
+): Promise<DevicesListResult> {
+  const result = await runDevicesCli(invocation, [
+    "devices",
+    assistantId,
+    "--json",
+  ]);
+  if (!result.ok) {
+    return result;
+  }
+  const devices = parseDeviceRecords(result.stdout);
+  if (!devices) {
+    const snippet = result.stdout.trim().slice(0, 200);
+    return {
+      ok: false,
+      error: `CLI returned unparseable devices output: ${snippet}`,
+    };
+  }
+  return { ok: true, devices };
+}
+
+export async function runDevicesRevoke(
+  invocation: CliInvocation,
+  assistantId: string,
+  hashedDeviceId: string,
+): Promise<DevicesRevokeResult> {
+  const result = await runDevicesCli(invocation, [
+    "devices",
+    "revoke",
+    hashedDeviceId,
+    assistantId,
+    "--yes",
+    "--json",
+  ]);
+  return result.ok ? { ok: true } : result;
+}

package/node_modules/@vellumai/local-mode/src/index.ts

@@ -64,6 +64,12 @@ export { runSleep } from "./sleep";
 export type { SleepResult } from "./sleep";
 export { runWake } from "./wake";
 export type { WakeOptions, WakeResult } from "./wake";
+export { runDevicesList, runDevicesRevoke } from "./devices";
+export type {
+  DeviceRecord,
+  DevicesListResult,
+  DevicesRevokeResult,
+} from "./devices";
 export { runUpgrade, isValidReleaseVersion } from "./upgrade";
 export type { UpgradeOptions, UpgradeResult } from "./upgrade";
 export { getLocalAssistantStatus } from "./status";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.11.4-dev.202608190416.3aa24ff",
+  "version": "0.11.4-dev.202608191511.29bfca9",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/devices.test.ts

@@ -24,8 +24,11 @@ const ORIGINAL_CONFIG_HOME = process.env.XDG_CONFIG_HOME;
 const ORIGINAL_ARGV = [...process.argv];
 const ORIGINAL_FETCH = globalThis.fetch;
 
+import { createHash } from "node:crypto";
+
 import { devices } from "../commands/devices.js";
 import { saveAssistantEntry } from "../lib/assistant-config.js";
+import { computeDeviceId } from "../lib/guardian-token.js";
 
 interface FetchCall {
   url: string;
@@ -178,6 +181,112 @@ describe("vellum devices", () => {
     expect(keys).not.toContain("x-forwarded-for");
   });
 
+  // Matches currentHostHashedDeviceId in the command: sha256 of the same
+  // stable device id the host's guardian lease registered with the gateway.
+  function hostHash(): string {
+    return createHash("sha256").update(computeDeviceId()).digest("hex");
+  }
+
+  test("labels this machine's own host credential in the human list", async () => {
+    seedLocal("host-label", "http://127.0.0.1:7837");
+    stubFetch((url) =>
+      url.endsWith("/v1/devices")
+        ? jsonResponse({
+            devices: [
+              {
+                hashedDeviceId: hostHash(),
+                platform: "cli",
+                issuedAt: 1_700_000_000_000,
+                expiresAt: null,
+                lastUsedAt: null,
+              },
+              {
+                hashedDeviceId: "hashBBB222",
+                platform: "ios",
+                issuedAt: 1_700_000_000_000,
+                expiresAt: null,
+                lastUsedAt: null,
+              },
+            ],
+          })
+        : jsonResponse({ error: "unexpected" }, 500),
+    );
+
+    process.argv = ["bun", "vellum", "devices", "host-label"];
+    const { exited, logs } = await runDevices();
+
+    expect(exited).toBe(false);
+    const label = "this machine's host credential";
+    expect(logs).toContain(label);
+    // Only the host record carries the label.
+    expect(logs.split(label)).toHaveLength(2);
+    const hostIdx = logs.indexOf(hostHash());
+    const otherIdx = logs.indexOf("hashBBB222");
+    const labelIdx = logs.indexOf(label);
+    expect(labelIdx).toBeGreaterThan(hostIdx);
+    expect(labelIdx).toBeLessThan(otherIdx);
+  });
+
+  test("list --json marks only the host credential with isCurrentHost", async () => {
+    seedLocal("host-json", "http://127.0.0.1:7838");
+    const hostRecord = {
+      hashedDeviceId: hostHash(),
+      platform: "cli",
+      issuedAt: 1_700_000_000_000,
+      expiresAt: null,
+      lastUsedAt: null,
+    };
+    const otherRecord = {
+      hashedDeviceId: "hashBBB222",
+      platform: "ios",
+      issuedAt: 1_700_000_000_000,
+      expiresAt: null,
+      lastUsedAt: null,
+    };
+    stubFetch((url) =>
+      url.endsWith("/v1/devices")
+        ? jsonResponse({ devices: [hostRecord, otherRecord] })
+        : jsonResponse({ error: "unexpected" }, 500),
+    );
+
+    process.argv = ["bun", "vellum", "devices", "host-json", "--json"];
+    const { exited, logs } = await runDevices();
+
+    expect(exited).toBe(false);
+    const parsed = JSON.parse(logs) as {
+      devices: Array<Record<string, unknown>>;
+    };
+    expect(parsed.devices[0]).toEqual({ ...hostRecord, isCurrentHost: true });
+    // Non-host records omit the field entirely (lean wire).
+    expect(parsed.devices[1]).toEqual(otherRecord);
+    expect("isCurrentHost" in parsed.devices[1]!).toBe(false);
+  });
+
+  test("revoking the host credential warns on stderr but proceeds", async () => {
+    seedLocal("host-revoke", "http://127.0.0.1:7839");
+    stubFetch((url) =>
+      url.endsWith("/v1/devices/revoke")
+        ? jsonResponse({ revoked: true })
+        : jsonResponse({ error: "unexpected" }, 500),
+    );
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "devices",
+      "revoke",
+      hostHash(),
+      "host-revoke",
+      "--yes",
+    ];
+    const { exited, logs, errors } = await runDevices();
+
+    expect(exited).toBe(false);
+    expect(errors).toContain("own host credential");
+    expect(logs).toContain(`Revoked device ${hostHash()}`);
+    expect(fetchCalls).toHaveLength(1);
+  });
+
   test("prints a clear message when no devices are paired", async () => {
     seedLocal("empty-host");
     stubFetch(() => jsonResponse({ devices: [] }));
@@ -259,6 +368,111 @@ describe("vellum devices", () => {
     expect(fetchCalls).toHaveLength(0);
   });
 
+  test("list --json emits a single JSON document and no human text", async () => {
+    seedLocal("json-host", "http://127.0.0.1:7835");
+    const records = [
+      {
+        hashedDeviceId: "hashAAA111",
+        platform: "cli",
+        issuedAt: 1_700_000_000_000,
+        expiresAt: 1_800_000_000_000,
+        lastUsedAt: null,
+      },
+    ];
+    stubFetch((url) =>
+      url.endsWith("/v1/devices")
+        ? jsonResponse({ devices: records })
+        : jsonResponse({ error: "unexpected" }, 500),
+    );
+
+    process.argv = ["bun", "vellum", "devices", "json-host", "--json"];
+    const { exited, logs, errors } = await runDevices();
+
+    expect(exited).toBe(false);
+    expect(errors).toBe("");
+    // Exactly one line on stdout, parseable, and zero prose.
+    expect(logs).not.toContain("\n");
+    expect(JSON.parse(logs)).toEqual({ devices: records });
+    expect(logs).not.toContain("Devices paired to");
+  });
+
+  test('list --json with zero devices emits {"devices":[]}', async () => {
+    seedLocal("json-empty-host");
+    stubFetch(() => jsonResponse({ devices: [] }));
+
+    process.argv = ["bun", "vellum", "devices", "json-empty-host", "--json"];
+    const { exited, logs } = await runDevices();
+
+    expect(exited).toBe(false);
+    expect(logs).toBe('{"devices":[]}');
+  });
+
+  test("revoke --json --yes emits one JSON line; identity preamble on stderr", async () => {
+    seedLocal("json-revoke-host", "http://127.0.0.1:7836");
+    stubFetch((url) =>
+      url.endsWith("/v1/devices/revoke")
+        ? jsonResponse({ revoked: true, hashedDeviceId: "hashAAA111" })
+        : jsonResponse({ error: "unexpected" }, 500),
+    );
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "devices",
+      "revoke",
+      "hashAAA111",
+      "json-revoke-host",
+      "--yes",
+      "--json",
+    ];
+    const { exited, logs, errors } = await runDevices();
+
+    expect(exited).toBe(false);
+    // Stdout is exactly one JSON document, no prose.
+    expect(logs).not.toContain("\n");
+    expect(JSON.parse(logs)).toEqual({
+      ok: true,
+      hashedDeviceId: "hashAAA111",
+      assistantId: "json-revoke-host",
+    });
+    expect(logs).not.toContain("Device to revoke");
+    // Destructive-identity preamble still printed, on stderr (cli/AGENTS.md).
+    expect(errors).toContain("Device to revoke:");
+    expect(errors).toContain("hashAAA111");
+  });
+
+  test("revoke --json without --yes exits 1 with empty stdout", async () => {
+    seedLocal("json-noyes-host");
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "devices",
+      "revoke",
+      "hashAAA111",
+      "json-noyes-host",
+      "--json",
+    ];
+    const { exited, logs, errors } = await runDevices();
+
+    expect(exited).toBe(true);
+    expect(logs).toBe("");
+    expect(errors).toContain("--json requires --yes");
+    expect(fetchCalls).toHaveLength(0);
+  });
+
+  test("list --json still exits 1 with stderr on a non-2xx gateway response", async () => {
+    seedLocal("json-err-host");
+    stubFetch(() => jsonResponse({ error: { code: "FORBIDDEN" } }, 403));
+
+    process.argv = ["bun", "vellum", "devices", "json-err-host", "--json"];
+    const { exited, logs, errors } = await runDevices();
+
+    expect(exited).toBe(true);
+    expect(logs).toBe("");
+    expect(errors).toContain("403");
+  });
+
   test("surfaces a non-2xx gateway response on list", async () => {
     seedLocal("err-host");
     stubFetch(() => jsonResponse({ error: { code: "FORBIDDEN" } }, 403));

package/src/commands/client.ts

@@ -35,6 +35,8 @@ import {
   isActiveAssistant,
   isPairedLockfileEntry,
   PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR,
+  runDevicesList,
+  runDevicesRevoke,
   runHatch,
   runRetire,
   connectImport,
@@ -427,6 +429,8 @@ const LOCKFILE_PATTERN = /^(?:\/assistant)?\/__local\/lockfile$/;
 const HATCH_PATTERN = /^(?:\/assistant)?\/__local\/hatch$/;
 const RETIRE_PATTERN = /^(?:\/assistant)?\/__local\/retire$/;
 const UNPAIR_PATTERN = /^(?:\/assistant)?\/__local\/unpair$/;
+const DEVICES_PATTERN = /^(?:\/assistant)?\/__local\/devices$/;
+const DEVICES_REVOKE_PATTERN = /^(?:\/assistant)?\/__local\/devices-revoke$/;
 const CONNECT_IMPORT_PATTERN = /^(?:\/assistant)?\/__local\/connect-import$/;
 const GUARDIAN_TOKEN_PATTERN =
   /^(?:\/assistant)?\/__local\/guardian-token\/([^/]+)$/;
@@ -483,6 +487,8 @@ async function handleLocalEndpoints(
     HATCH_PATTERN.test(pathname) ||
     RETIRE_PATTERN.test(pathname) ||
     UNPAIR_PATTERN.test(pathname) ||
+    DEVICES_PATTERN.test(pathname) ||
+    DEVICES_REVOKE_PATTERN.test(pathname) ||
     CONNECT_IMPORT_PATTERN.test(pathname) ||
     GUARDIAN_TOKEN_PATTERN.test(pathname) ||
     PLATFORM_SESSION_PATTERN.test(pathname) ||
@@ -706,6 +712,60 @@ async function handleLocalEndpoints(
     );
   }
 
+  // Paired devices: list and revoke via the CLI (`vellum devices … --json`).
+  // Always 200 with `ok` discriminating success, matching the other hosts.
+  const isDevicesRevoke = DEVICES_REVOKE_PATTERN.test(pathname);
+  if (DEVICES_PATTERN.test(pathname) || isDevicesRevoke) {
+    if (req.method !== "POST") {
+      return new Response(null, { status: 405 });
+    }
+
+    let body: { assistantId?: unknown; hashedDeviceId?: unknown };
+    try {
+      body = (await req.json()) as typeof body;
+    } catch {
+      return Response.json(
+        { ok: false, error: "Invalid JSON body" },
+        { status: 400 },
+      );
+    }
+
+    const { assistantId, hashedDeviceId } = body;
+    if (typeof assistantId !== "string" || !assistantId) {
+      return Response.json(
+        { ok: false, error: "Missing assistantId" },
+        { status: 400 },
+      );
+    }
+    let revokeHash: string | null = null;
+    if (isDevicesRevoke) {
+      if (typeof hashedDeviceId !== "string" || !hashedDeviceId) {
+        return Response.json(
+          { ok: false, error: "Missing hashedDeviceId" },
+          { status: 400 },
+        );
+      }
+      revokeHash = hashedDeviceId;
+    }
+
+    let invocation: CliInvocation;
+    try {
+      invocation = resolveDevCliInvocation(_baseDir);
+    } catch (err) {
+      return Response.json(
+        { ok: false, error: err instanceof Error ? err.message : String(err) },
+        { status: 500 },
+      );
+    }
+
+    if (revokeHash !== null) {
+      return Response.json(
+        await runDevicesRevoke(invocation, assistantId, revokeHash),
+      );
+    }
+    return Response.json(await runDevicesList(invocation, assistantId));
+  }
+
   // Connect-import: register a pairing bundle from another machine (guardian
   // token + paired lockfile entry), the write counterpart of unpair.
   if (CONNECT_IMPORT_PATTERN.test(pathname)) {

package/src/commands/devices.ts

@@ -13,12 +13,17 @@
  * that runs the assistant (server side).
  */
 
+import { createHash } from "node:crypto";
+
+import type { DeviceRecord } from "@vellumai/local-mode";
+
 import {
   type AssistantEntry,
   formatAssistantReference,
   getAssistantDisplayName,
   resolveTargetAssistant,
 } from "../lib/assistant-config";
+import { computeDeviceId } from "../lib/guardian-token.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import {
   CLI_INTERFACE_ID,
@@ -30,14 +35,6 @@ import {
 } from "../lib/confirm-action.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
-interface DeviceRecord {
-  hashedDeviceId: string;
-  platform: string;
-  issuedAt: number | null;
-  expiresAt: number | null;
-  lastUsedAt: number | null;
-}
-
 function printUsage(): void {
   console.log(`vellum devices [beta] - List and revoke devices paired to a local assistant
 
@@ -51,6 +48,7 @@ ARGUMENTS:
 
 OPTIONS:
     --yes              Skip the interactive confirmation prompt when revoking (for automation)
+    --json             Print machine-readable JSON on stdout (revoke requires --yes)
 
 Lists the devices paired to a local (host-side) assistant, or revokes one by its
 hashed id. Runs on the machine that hosts the assistant — paired connections
@@ -98,13 +96,28 @@ function resolveLoopbackBase(entry: AssistantEntry): string {
   return base.replace(/\/+$/, "");
 }
 
+/**
+ * The hashed device id the gateway stores for THIS machine's own guardian
+ * credential (`leaseGuardianToken` registers it device-bound as
+ * sha256(deviceId)). It shows up in `/v1/devices` next to remotely paired
+ * devices; revoking it locks this host out of its own assistant until
+ * guardian repair.
+ */
+function currentHostHashedDeviceId(): string {
+  return createHash("sha256").update(computeDeviceId()).digest("hex");
+}
+
 /** Format an epoch-ms timestamp as ISO, or a placeholder when absent. */
 function formatTimestamp(ms: number | null, absent: string): string {
   if (typeof ms !== "number" || !Number.isFinite(ms)) return absent;
   return new Date(ms).toISOString();
 }
 
-async function listDevices(entry: AssistantEntry, base: string): Promise<void> {
+async function listDevices(
+  entry: AssistantEntry,
+  base: string,
+  jsonOutput: boolean,
+): Promise<void> {
   const displayName = getAssistantDisplayName(entry);
 
   let response: Response;
@@ -130,7 +143,17 @@ async function listDevices(entry: AssistantEntry, base: string): Promise<void> {
   }
 
   const body = (await response.json()) as { devices?: DeviceRecord[] };
-  const devices = body.devices ?? [];
+  const hostHash = currentHostHashedDeviceId();
+  const devices = (body.devices ?? []).map((device) =>
+    device.hashedDeviceId === hostHash
+      ? { ...device, isCurrentHost: true as const }
+      : device,
+  );
+
+  if (jsonOutput) {
+    console.log(JSON.stringify({ devices }));
+    return;
+  }
 
   if (devices.length === 0) {
     console.log(`No devices are paired to ${displayName}.`);
@@ -147,6 +170,11 @@ async function listDevices(entry: AssistantEntry, base: string): Promise<void> {
     console.log(
       `    last used:  ${formatTimestamp(device.lastUsedAt, "never")}`,
     );
+    if (device.isCurrentHost) {
+      console.log(
+        "    this machine's host credential; revoking locks this host out until guardian repair",
+      );
+    }
     console.log("");
   }
   console.log(
@@ -159,14 +187,34 @@ async function revokeDevice(
   base: string,
   hashedDeviceId: string,
   yes: boolean,
+  jsonOutput: boolean,
 ): Promise<void> {
   const displayName = getAssistantDisplayName(entry);
 
-  // Print the resolved identity before acting (cli/AGENTS.md).
-  console.log("Device to revoke:");
-  console.log(`  Assistant: ${formatAssistantReference(entry)}`);
-  console.log(`  Device:    ${hashedDeviceId}`);
-  console.log("");
+  if (jsonOutput && !yes) {
+    console.error(
+      "Error: --json requires --yes; the revoke confirmation prompt would corrupt JSON stdout.",
+    );
+    process.exit(1);
+  }
+
+  // Print the resolved identity before acting (cli/AGENTS.md). In --json mode
+  // it goes to stderr so stdout stays a single JSON document.
+  const printIdentity = jsonOutput ? console.error : console.log;
+  printIdentity("Device to revoke:");
+  printIdentity(`  Assistant: ${formatAssistantReference(entry)}`);
+  printIdentity(`  Device:    ${hashedDeviceId}`);
+  printIdentity("");
+
+  // Warn (don't block; recoverable via guardian repair) when the target is
+  // this machine's own host credential. --json is app-driven; the UI disables
+  // the host row, so the warning stays out of automation transcripts.
+  if (!jsonOutput && hashedDeviceId === currentHostHashedDeviceId()) {
+    console.error(
+      "Warning: this is this machine's own host credential. Revoking it locks this host out of the assistant until guardian repair.",
+    );
+    console.error("");
+  }
 
   if (!yes) {
     if (!canPromptForConfirmation()) {
@@ -211,19 +259,33 @@ async function revokeDevice(
     process.exit(1);
   }
 
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({
+        ok: true,
+        hashedDeviceId,
+        assistantId: entry.assistantId,
+      }),
+    );
+    return;
+  }
+
   console.log(
     `Revoked device ${hashedDeviceId} from ${displayName}. Its tokens are invalidated; that machine must re-pair to reconnect.`,
   );
 }
 
 export async function devices(): Promise<void> {
-  const args = process.argv.slice(3);
+  const rawArgs = process.argv.slice(3);
 
-  if (args.includes("--help") || args.includes("-h")) {
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
     printUsage();
     return;
   }
 
+  const jsonOutput = rawArgs.includes("--json");
+  const args = rawArgs.filter((a) => a !== "--json");
+
   if (args[0] === "revoke") {
     const rest = args.slice(1);
     const yes = rest.includes("--yes");
@@ -237,12 +299,12 @@ export async function devices(): Promise<void> {
     const nameArg = positionals.slice(1).join(" ") || undefined;
     const entry = resolveTargetAssistant(nameArg);
     const base = resolveLoopbackBase(entry);
-    await revokeDevice(entry, base, hashedDeviceId, yes);
+    await revokeDevice(entry, base, hashedDeviceId, yes, jsonOutput);
     return;
   }
 
   const nameArg = parseAssistantTargetArg(args, []);
   const entry = resolveTargetAssistant(nameArg);
   const base = resolveLoopbackBase(entry);
-  await listDevices(entry, base);
+  await listDevices(entry, base, jsonOutput);
 }