@vellumai/cli 0.8.5 → 0.8.6

package/src/commands/recover.ts

@@ -1,6 +1,12 @@
-import { existsSync, readFileSync, unlinkSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+} from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { basename, dirname, join } from "path";
 
 import { saveAssistantEntry } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
@@ -21,8 +27,22 @@ export async function recover(): Promise<void> {
       "Restore a previously retired local assistant from its archive.",
     );
     console.log("");
+    console.log(
+      "Extracts the archived workspace data back to its original location,",
+    );
+    console.log(
+      "restores the lockfile entry, and starts the assistant and gateway.",
+    );
+    console.log(
+      "Archives are stored in $XDG_DATA_HOME/vellum/retired/ (default: ~/.local/share/vellum/retired/).",
+    );
+    console.log("");
     console.log("Arguments:");
     console.log("  <name>    Name of the retired assistant to recover");
+    console.log("");
+    console.log("Examples:");
+    console.log("  $ vellum recover my-assistant");
+    console.log("  $ vellum recover aria-7f3a");
     process.exit(0);
   }
 
@@ -61,11 +81,27 @@ export async function recover(): Promise<void> {
     process.exit(1);
   }
 
-  // 4. Extract archive
-  // TODO: extraction target is hardcoded to homedir(); multi-instance entries
-  //       whose instanceDir differs from homedir will extract to the wrong
-  //       location. Tracked separately from the collision-check regression.
-  await exec("tar", ["xzf", archivePath, "-C", homedir()]);
+  // 4. Determine the original target directory, then extract and rename.
+  //
+  // retireLocal archives either the full instanceDir (named instances) or just
+  // the .vellum/ subdirectory (default instance whose instanceDir === homedir()).
+  // The directory is staged under `<archive>.staging` inside the retired dir
+  // before being packed with `tar -C <retiredDir> <stagingBasename>`, so the
+  // top-level entry inside the tarball is always `<name>.tar.gz.staging`.
+  //
+  // Correct restoration: extract to retiredDir, then rename the staging entry
+  // back to the original target path.  Using homedir() as the -C target was
+  // wrong for any instance stored outside the home directory.
+  const isNamedInstance = entry.resources.instanceDir !== homedir();
+  const targetDir = isNamedInstance
+    ? entry.resources.instanceDir
+    : join(entry.resources.instanceDir, ".vellum");
+  const retiredDir = dirname(archivePath);
+  const extractedPath = join(retiredDir, basename(archivePath) + ".staging");
+
+  await exec("tar", ["xzf", archivePath, "-C", retiredDir]);
+  mkdirSync(dirname(targetDir), { recursive: true });
+  renameSync(extractedPath, targetDir);
 
   // 5. Restore lockfile entry
   saveAssistantEntry(entry);
@@ -74,14 +110,16 @@ export async function recover(): Promise<void> {
   unlinkSync(archivePath);
   unlinkSync(metadataPath);
 
-  // 7. Persist signing key so it survives daemon/gateway restarts (same as wake)
+  // 7. Persist signing key and bootstrap secret so they survive daemon/gateway restarts
   const signingKey = generateLocalSigningKey();
+  const bootstrapSecret = generateLocalSigningKey();
   entry.resources = { ...entry.resources, signingKey };
+  entry.guardianBootstrapSecret = bootstrapSecret;
   saveAssistantEntry(entry);
 
   // 8. Start daemon + gateway
   await startLocalDaemon(false, entry.resources, { signingKey });
-  await startGateway(false, entry.resources, { signingKey });
+  await startGateway(false, entry.resources, { signingKey, bootstrapSecret });
 
   console.log(`✅ Recovered assistant '${name}'.`);
 }

package/src/commands/restore.ts

@@ -97,6 +97,7 @@ async function getAccessToken(
   runtimeUrl: string,
   assistantId: string,
   displayName: string,
+  bootstrapSecret?: string,
 ): Promise<string> {
   const tokenData = loadGuardianToken(assistantId);
 
@@ -105,7 +106,11 @@ async function getAccessToken(
   }
 
   try {
-    const freshToken = await leaseGuardianToken(runtimeUrl, assistantId);
+    const freshToken = await leaseGuardianToken(
+      runtimeUrl,
+      assistantId,
+      bootstrapSecret,
+    );
     return freshToken.accessToken;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -574,6 +579,7 @@ export async function restore(): Promise<void> {
     entry.runtimeUrl,
     entry.assistantId,
     name,
+    entry.guardianBootstrapSecret,
   );
 
   if (dryRun) {
@@ -679,6 +685,7 @@ export async function restore(): Promise<void> {
         entry.runtimeUrl,
         entry.assistantId,
         name,
+        entry.guardianBootstrapSecret,
       );
     }
 

package/src/commands/retire.ts

@@ -2,14 +2,16 @@ import { existsSync, unlinkSync } from "fs";
 import { join } from "path";
 
 import {
+  extractHostFromUrl,
   formatAssistantLookupError,
   formatAssistantReference,
   getAssistantDisplayName,
   loadAllAssistants,
   lookupAssistantByIdentifier,
   removeAssistantEntry,
+  resolveCloud,
+  type AssistantEntry,
 } from "../lib/assistant-config.js";
-import type { AssistantEntry } from "../lib/assistant-config.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import { getConfigDir } from "../lib/environments/paths.js";
 import { getCurrentEnvironment } from "../lib/environments/resolve.js";
@@ -31,28 +33,6 @@ import {
   writeToLogFile,
 } from "../lib/xdg-log.js";
 
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) {
-    return entry.cloud;
-  }
-  if (entry.project) {
-    return "gcp";
-  }
-  if (entry.sshUser) {
-    return "custom";
-  }
-  return "local";
-}
-
-function extractHostFromUrl(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return parsed.hostname;
-  } catch {
-    return url.replace(/^https?:\/\//, "").split(":")[0];
-  }
-}
-
 export { retireLocal };
 
 interface RetireArgs {

package/src/commands/rollback.ts

@@ -4,9 +4,10 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  resolveCloud,
   saveAssistantEntry,
+  type AssistantEntry,
 } from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
 import {
   captureImageRefs,
   GATEWAY_INTERNAL_PORT,
@@ -90,19 +91,6 @@ function parseArgs(): { name: string | null; version: string | null } {
   return { name, version };
 }
 
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) {
-    return entry.cloud;
-  }
-  if (entry.project) {
-    return "gcp";
-  }
-  if (entry.sshUser) {
-    return "custom";
-  }
-  return "local";
-}
-
 /**
  * Resolve which assistant to target for the rollback command. Priority:
  * 1. Explicit name argument

package/src/commands/ssh.ts

@@ -1,7 +1,10 @@
 import { spawn } from "child_process";
 
-import { resolveAssistant } from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
+import {
+  extractHostFromUrl,
+  resolveAssistant,
+  resolveCloud,
+} from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
 import { getPlatformUrl, readPlatformToken } from "../lib/platform-client";
 import { sshAppleContainer } from "../lib/ssh-apple-container";
@@ -18,28 +21,6 @@ const SSH_OPTS = [
   "LogLevel=ERROR",
 ];
 
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) {
-    return entry.cloud;
-  }
-  if (entry.project) {
-    return "gcp";
-  }
-  if (entry.sshUser) {
-    return "custom";
-  }
-  return "local";
-}
-
-function extractHostFromUrl(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return parsed.hostname;
-  } catch {
-    return url.replace(/^https?:\/\//, "").split(":")[0];
-  }
-}
-
 export async function ssh(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {

package/src/commands/teleport.ts

@@ -3,10 +3,11 @@ import {
   loadAllAssistants,
   getDaemonPidPath,
   removeAssistantEntry,
+  resolveCloud,
   saveAssistantEntry,
   setActiveAssistant,
+  type AssistantEntry,
 } from "../lib/assistant-config.js";
-import type { AssistantEntry } from "../lib/assistant-config.js";
 import {
   loadGuardianToken,
   leaseGuardianToken,
@@ -214,12 +215,6 @@ export function parseArgs(argv: string[]): {
   return { from, to, targetEnv, targetName, keepSource, dryRun, help };
 }
 
-function resolveCloud(entry: AssistantEntry): string {
-  return (
-    entry.cloud || (entry.project ? "gcp" : entry.sshUser ? "custom" : "local")
-  );
-}
-
 // ---------------------------------------------------------------------------
 // Auth helper — same pattern as restore.ts
 // ---------------------------------------------------------------------------
@@ -228,7 +223,7 @@ async function getAccessToken(
   runtimeUrl: string,
   assistantId: string,
   displayName: string,
-  options?: { forceRefresh?: boolean },
+  options?: { forceRefresh?: boolean; bootstrapSecret?: string },
 ): Promise<string> {
   // When forceRefresh is set (e.g. after a runtime 401 on the cached token)
   // we skip the cache and lease a brand-new token from the gateway, so a
@@ -242,7 +237,11 @@ async function getAccessToken(
   }
 
   try {
-    const freshToken = await leaseGuardianToken(runtimeUrl, assistantId);
+    const freshToken = await leaseGuardianToken(
+      runtimeUrl,
+      assistantId,
+      options?.bootstrapSecret,
+    );
     return freshToken.accessToken;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -281,11 +280,15 @@ function isRuntime401(err: unknown): boolean {
  * — propagates to the caller.
  */
 async function callRuntimeWithAuthRetry<T>(
-  runtimeUrl: string,
-  assistantId: string,
+  entry: AssistantEntry,
   fn: (token: string) => Promise<T>,
 ): Promise<T> {
-  const firstToken = await getAccessToken(runtimeUrl, assistantId, assistantId);
+  const firstToken = await getAccessToken(
+    entry.runtimeUrl,
+    entry.assistantId,
+    entry.assistantId,
+    { bootstrapSecret: entry.guardianBootstrapSecret },
+  );
   try {
     return await fn(firstToken);
   } catch (err) {
@@ -293,10 +296,13 @@ async function callRuntimeWithAuthRetry<T>(
       throw err;
     }
     const refreshedToken = await getAccessToken(
-      runtimeUrl,
-      assistantId,
-      assistantId,
-      { forceRefresh: true },
+      entry.runtimeUrl,
+      entry.assistantId,
+      entry.assistantId,
+      {
+        forceRefresh: true,
+        bootstrapSecret: entry.guardianBootstrapSecret,
+      },
     );
     return await fn(refreshedToken);
   }
@@ -386,8 +392,7 @@ async function exportFromAssistant(
     let sourceRuntimeVersion: string;
     try {
       const identity = await callRuntimeWithAuthRetry(
-        entry.runtimeUrl,
-        entry.assistantId,
+        entry,
         async (token) => localRuntimeIdentity(entry, token),
       );
       sourceRuntimeVersion = identity.version;
@@ -423,8 +428,7 @@ async function exportFromAssistant(
     let accessToken: string;
     try {
       const result = await callRuntimeWithAuthRetry(
-        entry.runtimeUrl,
-        entry.assistantId,
+        entry,
         async (token) => {
           const r = await localRuntimeExportToGcs(entry, token, {
             uploadUrl,
@@ -462,7 +466,10 @@ async function exportFromAssistant(
           entry.runtimeUrl,
           entry.assistantId,
           entry.assistantId,
-          { forceRefresh: true },
+          {
+            forceRefresh: true,
+            bootstrapSecret: entry.guardianBootstrapSecret,
+          },
         );
       },
     });
@@ -728,8 +735,7 @@ async function importToAssistant(
     let targetRuntimeVersion: string;
     try {
       const identity = await callRuntimeWithAuthRetry(
-        entry.runtimeUrl,
-        entry.assistantId,
+        entry,
         (token) => localRuntimeIdentity(entry, token),
       );
       targetRuntimeVersion = identity.version;
@@ -774,8 +780,7 @@ async function importToAssistant(
     let accessToken: string;
     try {
       const result = await callRuntimeWithAuthRetry(
-        entry.runtimeUrl,
-        entry.assistantId,
+        entry,
         async (token) => {
           const r = await localRuntimeImportFromGcs(entry, token, {
             bundleUrl,
@@ -806,7 +811,10 @@ async function importToAssistant(
           entry.runtimeUrl,
           entry.assistantId,
           entry.assistantId,
-          { forceRefresh: true },
+          {
+            forceRefresh: true,
+            bootstrapSecret: entry.guardianBootstrapSecret,
+          },
         );
       },
     });

package/src/commands/upgrade.ts

@@ -7,9 +7,10 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  resolveCloud,
   saveAssistantEntry,
+  type AssistantEntry,
 } from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
 import {
   captureImageRefs,
   GATEWAY_INTERNAL_PORT,
@@ -145,19 +146,6 @@ function parseArgs(): UpgradeArgs {
   return { name, version, latest, prepare, finalize };
 }
 
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) {
-    return entry.cloud;
-  }
-  if (entry.project) {
-    return "gcp";
-  }
-  if (entry.sshUser) {
-    return "custom";
-  }
-  return "local";
-}
-
 /**
  * Resolve which assistant to target for the upgrade command. Priority:
  * 1. Explicit name argument
@@ -512,7 +500,10 @@ async function upgradeDocker(
   } else {
     console.error(`\n❌ Containers failed to become ready within the timeout.`);
 
-    const logDir = await captureUpgradeFailureLogs(res, `${instanceName}-upgrade-failure`);
+    const logDir = await captureUpgradeFailureLogs(
+      res,
+      `${instanceName}-upgrade-failure`,
+    );
     if (logDir) {
       console.log(`📋 Container logs saved to: ${logDir}`);
     }
@@ -938,7 +929,8 @@ async function resolveLatestAndMaybeSelfUpdate(
     );
     if (installResult.error || installResult.status !== 0) {
       const detail =
-        installResult.error?.message ?? `exited with code ${installResult.status}`;
+        installResult.error?.message ??
+        `exited with code ${installResult.status}`;
       console.error(`\n❌ CLI self-update failed: ${detail}`);
       emitCliError("CLI_UPDATE_FAILED", "CLI self-update failed", detail);
       process.exit(1);

package/src/commands/wake.ts

@@ -8,7 +8,7 @@ import {
 } from "../lib/assistant-config.js";
 import { dockerResourceNames, wakeContainers } from "../lib/docker.js";
 import { seedGuardianTokenFromSiblingEnv } from "../lib/guardian-token.js";
-import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
+import { resolveProcessState, stopProcessByPidFile } from "../lib/process";
 import {
   generateLocalSigningKey,
   isAssistantWatchModeAvailable,
@@ -85,36 +85,26 @@ export async function wake(): Promise<void> {
 
   const pidFile = getDaemonPidPath(resources);
 
-  // Check if daemon is already running
   let daemonRunning = false;
-  if (existsSync(pidFile)) {
-    const pidStr = readFileSync(pidFile, "utf-8").trim();
-    const pid = parseInt(pidStr, 10);
-    if (!isNaN(pid)) {
-      try {
-        process.kill(pid, 0);
-        daemonRunning = true;
-        if (watch) {
-          // Restart in watch mode — but only if source files are available.
-          // Watch mode requires bun --watch with .ts sources; packaged desktop
-          // builds only have a compiled binary. Stopping the daemon without a
-          // viable watch-mode path would leave the user with no running assistant.
-          if (!isAssistantWatchModeAvailable()) {
-            console.log(
-              `Assistant running (pid ${pid}) — watch mode not available (no source files). Keeping existing process.`,
-            );
-          } else {
-            console.log(
-              `Assistant running (pid ${pid}) — restarting in watch mode...`,
-            );
-            await stopProcessByPidFile(pidFile, "assistant");
-            daemonRunning = false;
-          }
-        } else {
-          console.log(`Assistant already running (pid ${pid}).`);
-        }
-      } catch {
-        // Process not alive, will start below
+  const daemonState = await resolveProcessState(
+    pidFile,
+    resources.daemonPort,
+    "Assistant",
+  );
+  if (daemonState.status === "healthy") {
+    if (watch && isAssistantWatchModeAvailable()) {
+      console.log(
+        `Assistant running (pid ${daemonState.pid}) — restarting in watch mode...`,
+      );
+      await stopProcessByPidFile(pidFile, "assistant");
+    } else {
+      daemonRunning = true;
+      if (watch) {
+        console.log(
+          `Assistant running (pid ${daemonState.pid}) — watch mode not available (no source files). Keeping existing process.`,
+        );
+      } else {
+        console.log(`Assistant already running (pid ${daemonState.pid}).`);
       }
     }
   }
@@ -153,6 +143,15 @@ export async function wake(): Promise<void> {
     saveAssistantEntry(entry);
   }
 
+  let bootstrapSecret = entry.guardianBootstrapSecret;
+  let bootstrapSecretBackfilled = false;
+  if (!bootstrapSecret) {
+    bootstrapSecret = generateLocalSigningKey();
+    entry.guardianBootstrapSecret = bootstrapSecret;
+    saveAssistantEntry(entry);
+    bootstrapSecretBackfilled = true;
+  }
+
   if (!daemonRunning) {
     await startLocalDaemon(watch, resources, { foreground, signingKey });
   }
@@ -161,26 +160,47 @@ export async function wake(): Promise<void> {
   {
     const vellumDir = join(resources.instanceDir, ".vellum");
     const gatewayPidFile = join(vellumDir, "gateway.pid");
-    const { alive, pid } = isProcessAlive(gatewayPidFile);
-    if (alive) {
-      if (watch) {
-        // Guard gateway restart separately: check gateway source availability.
-        if (!isGatewayWatchModeAvailable()) {
+    const gatewayState = await resolveProcessState(
+      gatewayPidFile,
+      resources.gatewayPort,
+      "Gateway",
+    );
+    const gatewayAlive = gatewayState.status === "healthy";
+    const needsRestart = bootstrapSecretBackfilled && gatewayAlive;
+    if (needsRestart) {
+      const restartWithWatch = watch && isGatewayWatchModeAvailable();
+      if (restartWithWatch) {
+        console.log(
+          `Gateway running (pid ${gatewayState.pid}) — restarting to apply bootstrap secret...`,
+        );
+      } else {
+        console.log(
+          `Gateway running (pid ${gatewayState.pid}) — restarting without watch mode to apply bootstrap secret...`,
+        );
+      }
+      await stopProcessByPidFile(gatewayPidFile, "gateway");
+      await startGateway(restartWithWatch, resources, {
+        signingKey,
+        bootstrapSecret,
+      });
+    } else if (gatewayAlive) {
+      if (watch && isGatewayWatchModeAvailable()) {
+        console.log(
+          `Gateway running (pid ${gatewayState.pid}) — restarting in watch mode...`,
+        );
+        await stopProcessByPidFile(gatewayPidFile, "gateway");
+        await startGateway(watch, resources, { signingKey, bootstrapSecret });
+      } else {
+        if (watch) {
           console.log(
-            `Gateway running (pid ${pid}) — watch mode not available (no source files). Keeping existing process.`,
+            `Gateway running (pid ${gatewayState.pid}) — watch mode not available (no source files). Keeping existing process.`,
           );
         } else {
-          console.log(
-            `Gateway running (pid ${pid}) — restarting in watch mode...`,
-          );
-          await stopProcessByPidFile(gatewayPidFile, "gateway");
-          await startGateway(watch, resources, { signingKey });
+          console.log(`Gateway already running (pid ${gatewayState.pid}).`);
         }
-      } else {
-        console.log(`Gateway already running (pid ${pid}).`);
       }
     } else {
-      await startGateway(watch, resources, { signingKey });
+      await startGateway(watch, resources, { signingKey, bootstrapSecret });
     }
   }
 
@@ -196,7 +216,10 @@ export async function wake(): Promise<void> {
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
   const workspaceDir = join(resources.instanceDir, ".vellum", "workspace");
-  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort, workspaceDir);
+  const ngrokChild = await maybeStartNgrokTunnel(
+    resources.gatewayPort,
+    workspaceDir,
+  );
   if (ngrokChild?.pid) {
     const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
     writeFileSync(ngrokPidFile, String(ngrokChild.pid));

package/src/index.ts

@@ -7,6 +7,8 @@ import { client } from "./commands/client";
 import { env } from "./commands/env";
 import { events } from "./commands/events";
 import { exec } from "./commands/exec";
+import { flags } from "./commands/flags";
+import { gateway } from "./commands/gateway";
 import { hatch } from "./commands/hatch";
 import { login, logout, whoami } from "./commands/login";
 import { logs } from "./commands/logs";
@@ -37,6 +39,8 @@ const commands = {
   env,
   events,
   exec,
+  flags,
+  gateway,
   hatch,
   login,
   logout,
@@ -72,6 +76,8 @@ function printHelp(): void {
   console.log("  env      Manage the default CLI environment");
   console.log("  events   Stream events from a running assistant");
   console.log("  exec     Execute a command inside an assistant's container");
+  console.log("  flags    Show and toggle feature flags");
+  console.log("  gateway  Gateway management commands");
   console.log("  hatch    Create a new assistant instance");
   console.log("  logs     View logs from an assistant instance");
   console.log("  login    Log in to the Vellum platform");