@vellumai/cli 0.10.3-staging.2 → 0.10.4-dev.202607010028.1a4efcc

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

@@ -0,0 +1,79 @@
+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[], { env?: NodeJS.ProcessEnv; stdio?: unknown }]
+> = [];
+const spawnMock = mock(
+  (
+    command: string,
+    args: string[],
+    options: { env?: NodeJS.ProcessEnv; stdio?: unknown },
+  ) => {
+    spawnArgs.push([command, args, options]);
+    lastChild = new FakeChild();
+    return lastChild;
+  },
+);
+
+mock.module("node:child_process", () => ({ spawn: spawnMock }));
+
+let runRetire: typeof import("../retire").runRetire;
+
+beforeAll(async () => {
+  ({ runRetire } = await import("../retire"));
+});
+
+afterEach(() => {
+  spawnArgs.length = 0;
+  spawnMock.mockClear();
+  delete process.env.VELLUM_PLATFORM_TOKEN;
+});
+
+const invocation: CliInvocation = { command: "bun", baseArgs: ["run", "cli"] };
+
+describe("runRetire", () => {
+  test("spawns the CLI retire command", async () => {
+    const pending = runRetire(invocation, "asst-42");
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true });
+    expect(spawnArgs[0]).toEqual([
+      "bun",
+      ["run", "cli", "retire", "asst-42", "--yes"],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    ]);
+  });
+
+  test("passes a host platform token to the CLI subprocess", async () => {
+    const pending = runRetire(invocation, "asst-42", {
+      platformToken: "session-token",
+    });
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true });
+    expect(spawnArgs[0]?.[2].env?.VELLUM_PLATFORM_TOKEN).toBe("session-token");
+    expect(process.env.VELLUM_PLATFORM_TOKEN).toBeUndefined();
+  });
+
+  test("a non-zero exit resolves to a failure carrying the CLI output", async () => {
+    const pending = runRetire(invocation, "asst-42");
+    lastChild.stderr.emit("data", Buffer.from("retire failed"));
+    lastChild.emit("close", 1);
+
+    expect(await pending).toEqual({
+      ok: false,
+      status: 500,
+      error: "retire failed",
+    });
+  });
+});

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

@@ -14,9 +14,18 @@ export {
   resolveDevCliInvocation,
 } from "./util";
 export type { CliInvocation } from "./util";
-export { resolveLocalConfigFromEnv, resolveLockfilePaths, resolveConfigDir, guardianTokenPath } from "./config";
+export {
+  resolveLocalConfigFromEnv,
+  resolveLockfilePaths,
+  resolveConfigDir,
+  guardianTokenPath,
+} from "./config";
 export type { LocalEndpointConfig } from "./config";
-export { defaultEnvironmentFilePath, readDefaultEnvironment, resolveEnvironmentName } from "./environment";
+export {
+  defaultEnvironmentFilePath,
+  readDefaultEnvironment,
+  resolveEnvironmentName,
+} from "./environment";
 export {
   getLockfileData,
   upsertLockfileAssistant,
@@ -34,7 +43,7 @@ export type {
 export { runHatch } from "./hatch";
 export type { HatchResult } from "./hatch";
 export { runRetire } from "./retire";
-export type { RetireResult } from "./retire";
+export type { RetireOptions, RetireResult } from "./retire";
 export { runSleep } from "./sleep";
 export type { SleepResult } from "./sleep";
 export { runWake } from "./wake";

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

@@ -5,18 +5,32 @@ import type { CliInvocation } from "./util";
 const RETIRE_TIMEOUT_MS = 60_000;
 
 export type RetireResult =
-  | { ok: true }
-  | { ok: false; status: number; error: string };
+  { ok: true } | { ok: false; status: number; error: string };
+
+export interface RetireOptions {
+  platformToken?: string;
+}
 
 export function runRetire(
   invocation: CliInvocation,
   assistantId: string,
+  options: RetireOptions = {},
 ): Promise<RetireResult> {
   return new Promise((resolve) => {
     const child = spawn(
       invocation.command,
       [...invocation.baseArgs, "retire", assistantId, "--yes"],
-      { stdio: ["ignore", "pipe", "pipe"] },
+      {
+        ...(options.platformToken
+          ? {
+              env: {
+                ...process.env,
+                VELLUM_PLATFORM_TOKEN: options.platformToken,
+              },
+            }
+          : {}),
+        stdio: ["ignore", "pipe", "pipe"],
+      },
     );
 
     let stdout = "";
@@ -32,7 +46,11 @@ export function runRetire(
 
     const timeout = setTimeout(() => {
       child.kill("SIGTERM");
-      finish({ ok: false, status: 500, error: "Retire timed out after 60 seconds" });
+      finish({
+        ok: false,
+        status: 500,
+        error: "Retire timed out after 60 seconds",
+      });
     }, RETIRE_TIMEOUT_MS);
 
     child.stdout.on("data", (data: Buffer) => {
@@ -52,7 +70,11 @@ export function runRetire(
     });
 
     child.on("error", (err) => {
-      finish({ ok: false, status: 500, error: `Failed to spawn CLI: ${err.message}` });
+      finish({
+        ok: false,
+        status: 500,
+        error: `Failed to spawn CLI: ${err.message}`,
+      });
     });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.3-staging.2",
+  "version": "0.10.4-dev.202607010028.1a4efcc",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/flags.test.ts

@@ -83,10 +83,10 @@ describe("vellum flags --assistant routing", () => {
       fetchCalls.push({ url, method });
       if (method === "PATCH") {
         return jsonResponse({
-          key: "external-plugins",
+          key: "voice-mode",
           enabled: true,
           defaultEnabled: false,
-          label: "External Plugins",
+          label: "Voice Mode",
           description: "test",
         });
       }
@@ -133,7 +133,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
       "--assistant",
       "Bob",
@@ -146,7 +146,7 @@ describe("vellum flags --assistant routing", () => {
     // bob-2 has assistantId.length === 5, so port = 7800 + 5 = 7805.
     expect(fetchCalls[0].url).toContain("http://127.0.0.1:7805");
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/bob-2/feature-flags/external-plugins",
+      "/v1/assistants/bob-2/feature-flags/voice-mode",
     );
   });
 
@@ -166,7 +166,7 @@ describe("vellum flags --assistant routing", () => {
       "--assistant",
       "Bob",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
     ];
 
@@ -174,7 +174,7 @@ describe("vellum flags --assistant routing", () => {
 
     expect(fetchCalls.length).toBe(1);
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/bob-2/feature-flags/external-plugins",
+      "/v1/assistants/bob-2/feature-flags/voice-mode",
     );
   });
 
@@ -193,7 +193,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
     ];
 
@@ -203,7 +203,7 @@ describe("vellum flags --assistant routing", () => {
     // alice-1 has assistantId.length === 7, so port = 7800 + 7 = 7807.
     expect(fetchCalls[0].url).toContain("http://127.0.0.1:7807");
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/alice-1/feature-flags/external-plugins",
+      "/v1/assistants/alice-1/feature-flags/voice-mode",
     );
   });
 
@@ -214,7 +214,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
       "--assistant",
       "Ghost",
@@ -234,7 +234,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "external-plugins",
+      "voice-mode",
       "true",
       "--assistant",
     ];

package/src/__tests__/recover.test.ts

@@ -13,6 +13,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
@@ -220,37 +221,43 @@ describe("recover error cases", () => {
 describe("recover extraction path — default instance (instanceDir === homedir())", () => {
   test("extracts to retiredDir and renames staging dir to instanceDir/.vellum", async () => {
     const name = "default-instance";
-    // Default instance: instanceDir is the real home directory
     const entry = makeEntry(name, homedir());
     const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
 
     const expectedTargetDir = join(homedir(), ".vellum");
-
-    process.argv = ["bun", "vellum", "recover", name];
-    await recover();
-
-    // exec must have been called with -C retiredDir, NOT -C homedir()
-    expect(execMock).toHaveBeenCalledTimes(1);
-    const [cmd, args] = execMock.mock.calls[0] as [string, string[]];
-    expect(cmd).toBe("tar");
-    expect(args).toContain("-C");
-    const cIndex = args.indexOf("-C");
-    expect(args[cIndex + 1]).toBe(retiredDir);
-    expect(args[cIndex + 1]).not.toBe(homedir());
-
-    // Staging dir was renamed to the correct target
-    expect(existsSync(extractedPath)).toBe(false);
-    expect(existsSync(expectedTargetDir)).toBe(true);
-
-    // Archive and metadata were cleaned up
-    expect(existsSync(archivePath)).toBe(false);
-
-    // Daemon and gateway were started
-    expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
-    expect(startGatewayMock).toHaveBeenCalledTimes(1);
-
-    // Clean up so we don't leave a .vellum dir in the real home dir
-    rmSync(expectedTargetDir, { recursive: true, force: true });
+    // If a real ~/.vellum exists (e.g. the machine runs a live assistant),
+    // temporarily move it aside so the collision guard doesn't fire.
+    const backupDir = join(homedir(), ".vellum-recover-test-bak");
+    const hadExisting = existsSync(expectedTargetDir);
+    if (hadExisting) renameSync(expectedTargetDir, backupDir);
+
+    try {
+      process.argv = ["bun", "vellum", "recover", name];
+      await recover();
+
+      // exec must have been called with -C retiredDir, NOT -C homedir()
+      expect(execMock).toHaveBeenCalledTimes(1);
+      const [cmd, args] = execMock.mock.calls[0] as [string, string[]];
+      expect(cmd).toBe("tar");
+      expect(args).toContain("-C");
+      const cIndex = args.indexOf("-C");
+      expect(args[cIndex + 1]).toBe(retiredDir);
+      expect(args[cIndex + 1]).not.toBe(homedir());
+
+      // Staging dir was renamed to the correct target
+      expect(existsSync(extractedPath)).toBe(false);
+      expect(existsSync(expectedTargetDir)).toBe(true);
+
+      // Archive and metadata were cleaned up
+      expect(existsSync(archivePath)).toBe(false);
+
+      // Daemon and gateway were started
+      expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
+      expect(startGatewayMock).toHaveBeenCalledTimes(1);
+    } finally {
+      rmSync(expectedTargetDir, { recursive: true, force: true });
+      if (hadExisting) renameSync(backupDir, expectedTargetDir);
+    }
   });
 });
 

package/src/__tests__/retire.test.ts

@@ -20,30 +20,74 @@ import { join } from "node:path";
 
 import type { AssistantEntry } from "../lib/assistant-config.js";
 import { loadAllAssistants } from "../lib/assistant-config.js";
+import * as loopbackFetchModule from "../lib/loopback-fetch.js";
+import * as platformClientModule from "../lib/platform-client.js";
 import * as retireLocalModule from "../lib/retire-local.js";
 
 const testDir = mkdtempSync(join(tmpdir(), "cli-retire-test-"));
 const originalArgv = [...process.argv];
 const originalExit = process.exit;
 const originalLockfileDir = process.env.VELLUM_LOCKFILE_DIR;
+const originalPlatformToken = process.env.VELLUM_PLATFORM_TOKEN;
 const originalStdinIsTTY = process.stdin.isTTY;
 const originalStdoutIsTTY = process.stdout.isTTY;
 const originalStdinIsRaw = process.stdin.isRaw;
 const originalSetRawMode = process.stdin.setRawMode;
 const originalStdoutWrite = process.stdout.write;
 const realRetireLocalModule = { ...retireLocalModule };
+const realPlatformClientModule = { ...platformClientModule };
+const realLoopbackFetchModule = { ...loopbackFetchModule };
 
 const retireLocalMock = mock(async () => {});
+const readPlatformTokenMock = mock((): string | null => null);
+const authHeadersMock = mock(async () => ({
+  "Content-Type": "application/json",
+  "X-Session-Token": "session-token",
+}));
+const authHeadersForKnownOrganizationMock = mock(
+  (token: string, organizationId: string) => ({
+    "Content-Type": "application/json",
+    "X-Session-Token": token,
+    "Vellum-Organization-Id": organizationId,
+  }),
+);
+const getPlatformUrlMock = mock(() => "https://platform.example.com");
+const readGatewayCredentialMock = mock(
+  async (
+    _gatewayUrl: string,
+    _name: string,
+    _bearerToken?: string,
+  ): Promise<{ value: string | null; unreachable: boolean }> => ({
+    value: null,
+    unreachable: false,
+  }),
+);
+const loopbackSafeFetchMock = mock(
+  async (): Promise<Response> => new Response(null, { status: 204 }),
+);
 
 mock.module("../lib/retire-local.js", () => ({
   ...realRetireLocalModule,
   retireLocal: retireLocalMock,
 }));
 
+mock.module("../lib/platform-client.js", () => ({
+  authHeaders: authHeadersMock,
+  authHeadersForKnownOrganization: authHeadersForKnownOrganizationMock,
+  getPlatformUrl: getPlatformUrlMock,
+  readGatewayCredential: readGatewayCredentialMock,
+  readPlatformToken: readPlatformTokenMock,
+}));
+
+mock.module("../lib/loopback-fetch.js", () => ({
+  loopbackSafeFetch: loopbackSafeFetchMock,
+}));
+
 import { retire } from "../commands/retire.js";
 
 let consoleLogSpy: ReturnType<typeof spyOn>;
 let consoleErrorSpy: ReturnType<typeof spyOn>;
+let consoleWarnSpy: ReturnType<typeof spyOn>;
 
 function makeEntry(
   assistantId: string,
@@ -123,6 +167,7 @@ function restoreTerminal(): void {
 describe("vellum retire", () => {
   beforeEach(() => {
     process.env.VELLUM_LOCKFILE_DIR = testDir;
+    delete process.env.VELLUM_PLATFORM_TOKEN;
     rmSync(join(testDir, ".vellum.lock.json"), { force: true });
     process.argv = ["bun", "vellum", "retire"];
     process.exit = ((code?: number) => {
@@ -130,9 +175,36 @@ describe("vellum retire", () => {
     }) as typeof process.exit;
     retireLocalMock.mockReset();
     retireLocalMock.mockResolvedValue(undefined);
+    readPlatformTokenMock.mockReset();
+    readPlatformTokenMock.mockReturnValue(null);
+    authHeadersMock.mockReset();
+    authHeadersMock.mockResolvedValue({
+      "Content-Type": "application/json",
+      "X-Session-Token": "session-token",
+    });
+    authHeadersForKnownOrganizationMock.mockReset();
+    authHeadersForKnownOrganizationMock.mockImplementation(
+      (token: string, organizationId: string) => ({
+        "Content-Type": "application/json",
+        "X-Session-Token": token,
+        "Vellum-Organization-Id": organizationId,
+      }),
+    );
+    getPlatformUrlMock.mockReset();
+    getPlatformUrlMock.mockReturnValue("https://platform.example.com");
+    readGatewayCredentialMock.mockReset();
+    readGatewayCredentialMock.mockResolvedValue({
+      value: null,
+      unreachable: false,
+    });
+    loopbackSafeFetchMock.mockReset();
+    loopbackSafeFetchMock.mockResolvedValue(
+      new Response(null, { status: 204 }),
+    );
     setTerminalMode(false);
     consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
     consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+    consoleWarnSpy = spyOn(console, "warn").mockImplementation(() => {});
   });
 
   afterEach(() => {
@@ -141,15 +213,23 @@ describe("vellum retire", () => {
     restoreTerminal();
     consoleLogSpy.mockRestore();
     consoleErrorSpy.mockRestore();
+    consoleWarnSpy.mockRestore();
   });
 
   afterAll(() => {
     mock.module("../lib/retire-local.js", () => realRetireLocalModule);
+    mock.module("../lib/platform-client.js", () => realPlatformClientModule);
+    mock.module("../lib/loopback-fetch.js", () => realLoopbackFetchModule);
     if (originalLockfileDir === undefined) {
       delete process.env.VELLUM_LOCKFILE_DIR;
     } else {
       process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
     }
+    if (originalPlatformToken === undefined) {
+      delete process.env.VELLUM_PLATFORM_TOKEN;
+    } else {
+      process.env.VELLUM_PLATFORM_TOKEN = originalPlatformToken;
+    }
     rmSync(testDir, { recursive: true, force: true });
   });
 
@@ -170,6 +250,218 @@ describe("vellum retire", () => {
     );
   });
 
+  test("local retire unregisters the self-hosted platform record first", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    readPlatformTokenMock.mockReturnValue("session-token");
+    getPlatformUrlMock.mockReturnValue("https://platform.example.test/api");
+    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
+      if (name === "vellum:platform_assistant_id") {
+        return { value: "platform-assistant-1", unreachable: false };
+      }
+      if (name === "vellum:platform_base_url") {
+        return { value: "https://platform.example.test", unreachable: false };
+      }
+      if (name === "vellum:platform_organization_id") {
+        return { value: "org-123", unreachable: false };
+      }
+      return { value: null, unreachable: false };
+    });
+    process.argv = ["bun", "vellum", "retire", "assistant-1", "--yes"];
+
+    await retire();
+
+    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
+      entry.localUrl ?? entry.runtimeUrl,
+      "vellum:platform_assistant_id",
+      entry.bearerToken,
+    );
+    expect(authHeadersMock).not.toHaveBeenCalled();
+    expect(loopbackSafeFetchMock).toHaveBeenCalledWith(
+      "https://platform.example.test/api/v1/assistants/platform-assistant-1/retire/",
+      {
+        method: "DELETE",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Session-Token": "session-token",
+          "Vellum-Organization-Id": "org-123",
+        },
+      },
+    );
+    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
+    expect(loadAllAssistants()).toEqual([]);
+  });
+
+  test("local retire reads platform registration through the loopback gateway URL", async () => {
+    const localGatewayUrl = "http://127.0.0.1:7831";
+    const entry = makeEntry("assistant-1", {
+      name: "Example Assistant",
+      runtimeUrl: "http://assistant-1.local:7831",
+      localUrl: localGatewayUrl,
+    });
+    writeLockfile([entry]);
+    readPlatformTokenMock.mockReturnValue("session-token");
+    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
+    readGatewayCredentialMock.mockImplementation(async (gatewayUrl, name) => {
+      expect(gatewayUrl).toBe(localGatewayUrl);
+      if (name === "vellum:platform_assistant_id") {
+        return { value: "platform-assistant-1", unreachable: false };
+      }
+      if (name === "vellum:platform_base_url") {
+        return { value: "https://platform.example.test", unreachable: false };
+      }
+      if (name === "vellum:platform_organization_id") {
+        return { value: "org-123", unreachable: false };
+      }
+      return { value: null, unreachable: false };
+    });
+    process.argv = ["bun", "vellum", "retire", "assistant-1", "--yes"];
+
+    await retire();
+
+    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
+      localGatewayUrl,
+      "vellum:platform_assistant_id",
+      entry.bearerToken,
+    );
+    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
+      localGatewayUrl,
+      "vellum:platform_base_url",
+      entry.bearerToken,
+    );
+    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
+      localGatewayUrl,
+      "vellum:platform_organization_id",
+      entry.bearerToken,
+    );
+    expect(loopbackSafeFetchMock).toHaveBeenCalledWith(
+      "https://platform.example.test/v1/assistants/platform-assistant-1/retire/",
+      expect.any(Object),
+    );
+    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
+  });
+
+  test("local retire skips platform unregister when stored platform URL origin mismatches", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    readPlatformTokenMock.mockReturnValue("session-token");
+    getPlatformUrlMock.mockReturnValue("https://platform.example.com");
+    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
+      if (name === "vellum:platform_assistant_id") {
+        return { value: "platform-assistant-1", unreachable: false };
+      }
+      if (name === "vellum:platform_base_url") {
+        return { value: "https://malicious.example.test", unreachable: false };
+      }
+      if (name === "vellum:platform_organization_id") {
+        return { value: "org-123", unreachable: false };
+      }
+      return { value: null, unreachable: false };
+    });
+    process.argv = ["bun", "vellum", "retire", "assistant-1", "--yes"];
+
+    await retire();
+
+    expect(loopbackSafeFetchMock).not.toHaveBeenCalled();
+    expect(consoleWarnSpy.mock.calls.flat().join("\n")).toContain(
+      "Stored platform URL does not match the configured platform URL",
+    );
+    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
+  });
+
+  test("local retire skips platform unregister when stored organization ID is missing", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    readPlatformTokenMock.mockReturnValue("session-token");
+    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
+    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
+      if (name === "vellum:platform_assistant_id") {
+        return { value: "platform-assistant-1", unreachable: false };
+      }
+      if (name === "vellum:platform_base_url") {
+        return { value: "https://platform.example.test", unreachable: false };
+      }
+      return { value: null, unreachable: false };
+    });
+    process.argv = ["bun", "vellum", "retire", "assistant-1", "--yes"];
+
+    await retire();
+
+    expect(loopbackSafeFetchMock).not.toHaveBeenCalled();
+    expect(consoleWarnSpy.mock.calls.flat().join("\n")).toContain(
+      "Could not read platform organization ID",
+    );
+    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
+    expect(loadAllAssistants()).toEqual([]);
+  });
+
+  test("local retire uses injected platform token from the app host", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    process.env.VELLUM_PLATFORM_TOKEN = "host-session-token";
+    readPlatformTokenMock.mockReturnValue(null);
+    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
+    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
+      if (name === "vellum:platform_assistant_id") {
+        return { value: "platform-assistant-1", unreachable: false };
+      }
+      if (name === "vellum:platform_base_url") {
+        return { value: "https://platform.example.test", unreachable: false };
+      }
+      if (name === "vellum:platform_organization_id") {
+        return { value: "org-123", unreachable: false };
+      }
+      return { value: null, unreachable: false };
+    });
+    process.argv = ["bun", "vellum", "retire", "assistant-1", "--yes"];
+
+    await retire();
+
+    expect(loopbackSafeFetchMock).toHaveBeenCalledWith(
+      "https://platform.example.test/v1/assistants/platform-assistant-1/retire/",
+      {
+        method: "DELETE",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Session-Token": "host-session-token",
+          "Vellum-Organization-Id": "org-123",
+        },
+      },
+    );
+    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
+  });
+
+  test("local retire continues when self-hosted platform unregister fails", async () => {
+    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    writeLockfile([entry]);
+    readPlatformTokenMock.mockReturnValue("session-token");
+    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
+    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
+      if (name === "vellum:platform_assistant_id") {
+        return { value: "platform-assistant-1", unreachable: false };
+      }
+      if (name === "vellum:platform_base_url") {
+        return { value: "https://platform.example.test", unreachable: false };
+      }
+      if (name === "vellum:platform_organization_id") {
+        return { value: "org-123", unreachable: false };
+      }
+      return { value: null, unreachable: false };
+    });
+    loopbackSafeFetchMock.mockResolvedValue(
+      new Response("platform unavailable", { status: 503 }),
+    );
+    process.argv = ["bun", "vellum", "retire", "assistant-1", "--yes"];
+
+    await retire();
+
+    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
+    expect(loadAllAssistants()).toEqual([]);
+    expect(consoleWarnSpy.mock.calls.flat().join("\n")).toContain(
+      "Platform self-hosted unregister failed (503): platform unavailable",
+    );
+  });
+
   test("non-interactive retire without --yes fails before deleting", async () => {
     const entry = makeEntry("assistant-1", { name: "Example Assistant" });
     writeLockfile([entry]);

package/src/__tests__/teleport.test.ts

@@ -259,12 +259,27 @@ const localRuntimePollJobStatusMock = mock<
   },
 }));
 
+const localRuntimePreflightFromGcsMock = mock<
+  typeof localRuntimeClient.localRuntimePreflightFromGcs
+>(async () => ({
+  can_import: true,
+  summary: {
+    files_to_create: 2,
+    files_to_overwrite: 1,
+    files_unchanged: 0,
+    total_files: 3,
+  },
+  files: [],
+  conflicts: [],
+}));
+
 mock.module("../lib/local-runtime-client.js", () => ({
   ...realLocalRuntimeClient,
   localRuntimeExportToGcs: localRuntimeExportToGcsMock,
   localRuntimeImportFromGcs: localRuntimeImportFromGcsMock,
   localRuntimeIdentity: localRuntimeIdentityMock,
   localRuntimePollJobStatus: localRuntimePollJobStatusMock,
+  localRuntimePreflightFromGcs: localRuntimePreflightFromGcsMock,
 }));
 
 const hatchLocalMock = mock(async () => {});
@@ -483,6 +498,18 @@ beforeEach(() => {
   localRuntimeImportFromGcsMock.mockResolvedValue({
     jobId: "local-import-job-1",
   });
+  localRuntimePreflightFromGcsMock.mockReset();
+  localRuntimePreflightFromGcsMock.mockResolvedValue({
+    can_import: true,
+    summary: {
+      files_to_create: 2,
+      files_to_overwrite: 1,
+      files_unchanged: 0,
+      total_files: 3,
+    },
+    files: [],
+    conflicts: [],
+  });
   localRuntimeIdentityMock.mockReset();
   localRuntimeIdentityMock.mockResolvedValue({ version: "0.6.5" });
   localRuntimePollJobStatusMock.mockReset();
@@ -1932,7 +1959,7 @@ describe("dry-run", () => {
     }
   });
 
-  test("dry-run against local target fails fast (no preflight-from-gcs runtime endpoint yet)", async () => {
+  test("dry-run with existing local target calls preflight-from-gcs on runtime", async () => {
     setArgv("--from", "my-platform", "--local", "my-local", "--dry-run");
 
     const platformEntry = makeEntry("my-platform", {
@@ -1947,26 +1974,24 @@ describe("dry-run", () => {
       return null;
     });
 
-    platformPollJobStatusMock.mockResolvedValue({
-      jobId: "platform-export-job-1",
-      type: "export",
-      status: "complete",
-      bundleKey: "bundle-key-from-platform",
-    });
-
     const restoreFetch = installTrackingFetch();
     try {
-      await expect(teleport()).rejects.toThrow("process.exit:1");
-      expect(consoleErrorSpy).toHaveBeenCalledWith(
-        expect.stringContaining(
-          "--dry-run is not yet supported for local or docker targets",
-        ),
+      await teleport();
+
+      // Preflight was run against the local runtime
+      expect(localRuntimePreflightFromGcsMock).toHaveBeenCalledTimes(1);
+      expect(localRuntimePreflightFromGcsMock).toHaveBeenCalledWith(
+        expect.objectContaining({ assistantId: "my-local" }),
+        expect.any(String),
+        { bundleUrl: "https://storage.googleapis.com/bucket/signed-download" },
       );
 
-      // Must fail BEFORE any export work — no signed URL request, no runtime
-      // export kickoff, nothing that costs time or bandwidth.
-      expect(platformRequestSignedUrlMock).not.toHaveBeenCalled();
-      expect(localRuntimeExportToGcsMock).not.toHaveBeenCalled();
+      // No actual import happened — dry-run only
+      expect(localRuntimeImportFromGcsMock).not.toHaveBeenCalled();
+
+      // Source was not retired
+      expect(retireLocalMock).not.toHaveBeenCalled();
+      expect(retireDockerMock).not.toHaveBeenCalled();
     } finally {
       restoreFetch();
     }

package/src/commands/flags.ts

@@ -98,7 +98,7 @@ function printHelp(): void {
     "  $ vellum flags set voice-mode true                           # enable a flag",
   );
   console.log(
-    "  $ vellum flags set external-plugins true --assistant eval-1  # target by name/id",
+    "  $ vellum flags set voice-mode true --assistant eval-1       # target by name/id",
   );
 }
 

package/src/commands/retire.ts

@@ -20,7 +20,9 @@ import { getConfigDir } from "../lib/environments/paths.js";
 import { getCurrentEnvironment } from "../lib/environments/resolve.js";
 import {
   authHeaders,
+  authHeadersForKnownOrganization,
   getPlatformUrl,
+  readGatewayCredential,
   readPlatformToken,
 } from "../lib/platform-client.js";
 import { retireInstance as retireAwsInstance } from "../lib/aws.js";
@@ -45,6 +47,128 @@ interface RetireArgs {
   yes: boolean;
 }
 
+const PLATFORM_TOKEN_ENV = "VELLUM_PLATFORM_TOKEN";
+
+function readPlatformRetireToken(): string | null {
+  const envToken = process.env[PLATFORM_TOKEN_ENV]?.trim();
+  if (envToken) return envToken;
+  return readPlatformToken();
+}
+
+function platformOrigin(platformUrl: string): string | null {
+  try {
+    return new URL(platformUrl).origin;
+  } catch {
+    return null;
+  }
+}
+
+function resolveTrustedSelfHostedPlatformUrl(
+  storedPlatformUrl: string | null,
+): string | null {
+  const configuredPlatformUrl = getPlatformUrl();
+  if (!storedPlatformUrl) return configuredPlatformUrl;
+
+  const storedOrigin = platformOrigin(storedPlatformUrl);
+  const configuredOrigin = platformOrigin(configuredPlatformUrl);
+  if (storedOrigin && configuredOrigin && storedOrigin === configuredOrigin) {
+    return configuredPlatformUrl;
+  }
+
+  console.warn(
+    "⚠️  Stored platform URL does not match the configured platform URL; skipping platform unregister.",
+  );
+  return null;
+}
+
+async function deletePlatformAssistant(
+  assistantId: string,
+  options: {
+    token: string;
+    platformUrl?: string;
+    organizationId?: string;
+    label: string;
+    successMessage: string;
+    alreadyGoneMessage: string;
+  },
+): Promise<void> {
+  const platformUrl = options.platformUrl || getPlatformUrl();
+  const url = `${platformUrl}/v1/assistants/${encodeURIComponent(assistantId)}/retire/`;
+  const headers = options.organizationId
+    ? authHeadersForKnownOrganization(options.token, options.organizationId)
+    : await authHeaders(options.token, platformUrl);
+
+  const response = await loopbackSafeFetch(url, {
+    method: "DELETE",
+    headers,
+  });
+
+  if (!response.ok && response.status !== 404) {
+    const body = await response.text();
+    throw new Error(`${options.label} failed (${response.status}): ${body}`);
+  }
+
+  if (response.status === 404) {
+    console.log(options.alreadyGoneMessage);
+  } else {
+    console.log(options.successMessage);
+  }
+}
+
+async function unregisterSelfHostedLocalPlatformRecord(
+  entry: AssistantEntry,
+): Promise<void> {
+  const token = readPlatformRetireToken();
+  if (!token) return;
+
+  const gatewayUrl = entry.localUrl ?? entry.runtimeUrl;
+  const platformAssistant = await readGatewayCredential(
+    gatewayUrl,
+    "vellum:platform_assistant_id",
+    entry.bearerToken,
+  );
+  if (platformAssistant.unreachable) {
+    console.warn(
+      "\u26a0\ufe0f  Could not read platform registration from the local assistant; skipping platform unregister.",
+    );
+    return;
+  }
+  if (!platformAssistant.value) return;
+
+  const [platformBaseUrl, organizationId] = await Promise.all([
+    readGatewayCredential(
+      gatewayUrl,
+      "vellum:platform_base_url",
+      entry.bearerToken,
+    ),
+    readGatewayCredential(
+      gatewayUrl,
+      "vellum:platform_organization_id",
+      entry.bearerToken,
+    ),
+  ]);
+  const platformUrl = resolveTrustedSelfHostedPlatformUrl(
+    platformBaseUrl.value,
+  );
+  if (!platformUrl) return;
+  if (!organizationId.value) {
+    console.warn(
+      "⚠️  Could not read platform organization ID from the local assistant; skipping platform unregister.",
+    );
+    return;
+  }
+
+  await deletePlatformAssistant(platformAssistant.value, {
+    token,
+    platformUrl,
+    organizationId: organizationId.value,
+    label: "Platform self-hosted unregister",
+    successMessage: "\u2705 Platform self-hosted registration unregistered.",
+    alreadyGoneMessage:
+      "\u2705 Platform self-hosted registration already unregistered (404).",
+  });
+}
+
 async function retireCustom(entry: AssistantEntry): Promise<void> {
   const host = extractHostFromUrl(entry.runtimeUrl);
   const sshUser = entry.sshUser ?? "root";
@@ -86,7 +210,7 @@ async function retireVellum(
 ): Promise<void> {
   console.log("\u{1F5D1}\ufe0f  Retiring platform-hosted instance...\n");
 
-  const token = readPlatformToken();
+  const token = readPlatformRetireToken();
   if (!token) {
     console.error(
       "Error: Not logged in. Run `vellum login --token <token>` first.",
@@ -94,33 +218,21 @@ async function retireVellum(
     process.exit(1);
   }
 
-  const platformUrl = runtimeUrl || getPlatformUrl();
-  const url = `${platformUrl}/v1/assistants/${encodeURIComponent(assistantId)}/retire/`;
-  const response = await loopbackSafeFetch(url, {
-    method: "DELETE",
-    headers: await authHeaders(token, runtimeUrl),
-  });
-
-  // Treat 404 as success: the assistant is already gone from the platform
-  // (previously retired, deleted from the web UI, or retired from another
-  // device) so the caller's job is done. Falling through to the lockfile
-  // cleanup avoids leaving a stale entry that would otherwise wedge the
-  // macOS app in a permanent health-check loop.
-  if (!response.ok && response.status !== 404) {
-    const body = await response.text();
+  try {
+    await deletePlatformAssistant(assistantId, {
+      token,
+      platformUrl: runtimeUrl,
+      label: "Platform retire",
+      successMessage: "\u2705 Platform-hosted instance retired.",
+      alreadyGoneMessage:
+        "\u2705 Platform-hosted instance already retired (404) \u2014 cleaning up local state.",
+    });
+  } catch (error) {
     console.error(
-      `Error: Platform retire failed (${response.status}): ${body}`,
+      `Error: ${error instanceof Error ? error.message : String(error)}`,
     );
     process.exit(1);
   }
-
-  if (response.status === 404) {
-    console.log(
-      "\u2705 Platform-hosted instance already retired (404) — cleaning up local state.",
-    );
-  } else {
-    console.log("\u2705 Platform-hosted instance retired.");
-  }
 }
 
 function parseRetireArgs(args: string[]): RetireArgs {
@@ -303,6 +415,15 @@ async function retireInner(): Promise<void> {
   } else if (cloud === "docker") {
     await retireDocker(assistantId);
   } else if (cloud === "local") {
+    try {
+      await unregisterSelfHostedLocalPlatformRecord(entry);
+    } catch (error) {
+      console.warn(
+        `⚠️  Platform self-hosted unregister failed; continuing local retire: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
     await retireLocal(assistantId, entry);
   } else if (cloud === "custom") {
     await retireCustom(entry);

package/src/commands/teleport.ts

@@ -33,6 +33,7 @@ import {
   localRuntimeExportToGcs,
   localRuntimeIdentity,
   localRuntimeImportFromGcs,
+  localRuntimePreflightFromGcs,
   localRuntimePollJobStatus,
   MigrationInProgressError,
 } from "../lib/local-runtime-client.js";
@@ -707,11 +708,46 @@ async function importToAssistant(
 
   if (cloud === "local" || cloud === "docker") {
     if (dryRun) {
-      // TODO(cli): support dry-run against local targets
-      console.error(
-        "Error: --dry-run is not yet supported for local or docker targets (no preflight-from-gcs endpoint on the runtime).",
+      console.log("Running preflight analysis...\n");
+
+      // Query the target runtime's version before requesting a signed
+      // download URL — the platform uses it for the bundle compatibility check.
+      let targetRuntimeVersion: string;
+      try {
+        const identity = await callRuntimeWithAuthRetry(entry, (token) =>
+          localRuntimeIdentity(entry, token),
+        );
+        targetRuntimeVersion = identity.version;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(
+          `Error: Could not read target runtime version from '${entry.assistantId}': ${msg}`,
+        );
+        console.error(`Try: vellum wake ${entry.assistantId}`);
+        process.exit(1);
+      }
+
+      let bundleUrl: string;
+      try {
+        const result = await platformRequestSignedUrl(
+          { operation: "download", bundleKey, targetRuntimeVersion },
+          platformToken,
+          bundlePlatformUrl,
+        );
+        bundleUrl = result.url;
+      } catch (err) {
+        if (err instanceof VersionMismatchError) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+        throw err;
+      }
+
+      const preflightData = await callRuntimeWithAuthRetry(entry, (token) =>
+        localRuntimePreflightFromGcs(entry, token, { bundleUrl }),
       );
-      process.exit(1);
+      printPreflightSummary(preflightData as unknown as PreflightResponse);
+      return;
     }
 
     // Ask the platform for a signed download URL and hand it to the local
@@ -1231,18 +1267,8 @@ export async function teleport(): Promise<void> {
         process.exit(1);
       }
 
-      // Dry-run feasibility check — reject local/docker targets BEFORE any
-      // export work. The local runtime has no preflight-from-gcs endpoint yet,
-      // so we can't actually run a dry-run against it; burning a GCS upload
-      // just to fail afterwards would be wasteful.
-      // TODO(cli): support dry-run against local targets (needs a
-      // preflight-from-gcs endpoint on the runtime).
-      if (toCloud === "local" || toCloud === "docker") {
-        console.error(
-          "Error: --dry-run is not yet supported for local or docker targets (no preflight-from-gcs endpoint on the runtime).",
-        );
-        process.exit(1);
-      }
+      // Nothing to reject — preflight-from-gcs is now implemented for all
+      // target topologies including local and docker.
 
       // Version guard: block platform→non-platform when target is behind
       if (fromCloud === "vellum" && toCloud !== "vellum") {

package/src/lib/local-runtime-client.ts

@@ -195,6 +195,44 @@ export async function localRuntimeImportFromGcs(
   return { jobId: json.job_id };
 }
 
+/**
+ * Run a dry-run preflight analysis on a .vbundle archive stored at a signed
+ * GCS download URL.
+ *
+ * For local/docker assistants this POSTs to
+ * `{runtimeUrl}/v1/migrations/preflight-from-gcs` with guardian-token bearer
+ * auth. The daemon fetches the bundle from GCS, validates it, and returns a
+ * report of what would change on import — without writing anything to disk.
+ *
+ * Returns the raw preflight response body. Callers should cast to their
+ * local `PreflightResponse` shape (mirrors the `/import-preflight` shape).
+ */
+export async function localRuntimePreflightFromGcs(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  token: string,
+  params: { bundleUrl: string },
+): Promise<Record<string, unknown>> {
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, "preflight-from-gcs"),
+    {
+      method: "POST",
+      headers: await migrationRequestHeaders(entry, token),
+      body: JSON.stringify({ bundle_url: params.bundleUrl }),
+    },
+  );
+
+  if (response.status !== 200) {
+    const errText = await response.text().catch(() => "");
+    throw new Error(
+      `Local runtime preflight-from-gcs failed (${response.status}): ${
+        errText || response.statusText
+      }`,
+    );
+  }
+
+  return (await response.json()) as Record<string, unknown>;
+}
+
 /**
  * Poll the runtime's unified job-status endpoint.
  *

package/src/lib/platform-client.ts

@@ -96,6 +96,20 @@ function tokenAuthHeader(token: string): Record<string, string> {
   return { "X-Session-Token": token };
 }
 
+export function authHeadersForKnownOrganization(
+  token: string,
+  organizationId: string,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...tokenAuthHeader(token),
+  };
+  if (!token.startsWith(VAK_PREFIX)) {
+    headers["Vellum-Organization-Id"] = organizationId;
+  }
+  return headers;
+}
+
 /** Module-level cache for org IDs to avoid redundant fetches in polling loops. */
 const orgIdCache = new Map<string, { orgId: string; expiresAt: number }>();
 const ORG_ID_CACHE_TTL_MS = 60_000; // 60 seconds