@vellumai/cli 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/commands/ps.ts

@@ -1,6 +1,7 @@
 import { join } from "path";
 
 import {
+  extractHostFromUrl,
   findAssistantByName,
   formatAssistantLookupError,
   formatAssistantReference,
@@ -9,6 +10,7 @@ import {
   getDaemonPidPath,
   loadAllAssistants,
   lookupAssistantByIdentifier,
+  resolveCloud,
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
@@ -26,7 +28,7 @@ import { existsSync } from "fs";
 import {
   classifyProcess,
   detectOrphanedProcesses,
-  isProcessAlive,
+  isPidAlive,
   parseRemotePs,
   readPidFile,
 } from "../lib/orphan-detection";
@@ -149,35 +151,25 @@ const REMOTE_PS_CMD = [
   "| grep -v grep",
 ].join(" ");
 
-function extractHostFromUrl(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return parsed.hostname;
-  } catch {
-    return url.replace(/^https?:\/\//, "").split(":")[0];
-  }
-}
-
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) return entry.cloud;
-  if (entry.project) return "gcp";
-  if (entry.sshUser) return "custom";
-  return "local";
-}
+const REMOTE_SSH_TIMEOUT_MS = 30_000;
 
 async function getRemoteProcessesGcp(entry: AssistantEntry): Promise<string> {
-  return execOutput("gcloud", [
-    "compute",
-    "ssh",
-    `${entry.sshUser ?? entry.assistantId}@${entry.assistantId}`,
-    `--zone=${entry.zone}`,
-    `--project=${entry.project}`,
-    `--command=${REMOTE_PS_CMD}`,
-    "--ssh-flag=-o StrictHostKeyChecking=no",
-    "--ssh-flag=-o UserKnownHostsFile=/dev/null",
-    "--ssh-flag=-o ConnectTimeout=10",
-    "--ssh-flag=-o LogLevel=ERROR",
-  ]);
+  return execOutput(
+    "gcloud",
+    [
+      "compute",
+      "ssh",
+      `${entry.sshUser ?? entry.assistantId}@${entry.assistantId}`,
+      `--zone=${entry.zone}`,
+      `--project=${entry.project}`,
+      `--command=${REMOTE_PS_CMD}`,
+      "--ssh-flag=-o StrictHostKeyChecking=no",
+      "--ssh-flag=-o UserKnownHostsFile=/dev/null",
+      "--ssh-flag=-o ConnectTimeout=10",
+      "--ssh-flag=-o LogLevel=ERROR",
+    ],
+    { timeoutMs: REMOTE_SSH_TIMEOUT_MS },
+  );
 }
 
 async function getRemoteProcessesCustom(
@@ -185,7 +177,9 @@ async function getRemoteProcessesCustom(
 ): Promise<string> {
   const host = extractHostFromUrl(entry.runtimeUrl);
   const sshUser = entry.sshUser ?? "root";
-  return execOutput("ssh", [...SSH_OPTS, `${sshUser}@${host}`, REMOTE_PS_CMD]);
+  return execOutput("ssh", [...SSH_OPTS, `${sshUser}@${host}`, REMOTE_PS_CMD], {
+    timeoutMs: REMOTE_SSH_TIMEOUT_MS,
+  });
 }
 
 interface ProcessSpec {
@@ -203,9 +197,13 @@ interface DetectedProcess {
   watch: boolean;
 }
 
+const LOCAL_CMD_TIMEOUT_MS = 5_000;
+
 async function isWatchMode(pid: string): Promise<boolean> {
   try {
-    const args = await execOutput("ps", ["-p", pid, "-o", "args="]);
+    const args = await execOutput("ps", ["-p", pid, "-o", "args="], {
+      timeoutMs: LOCAL_CMD_TIMEOUT_MS,
+    });
     return args.includes("--watch");
   } catch {
     return false;
@@ -242,7 +240,7 @@ async function detectProcess(spec: ProcessSpec): Promise<DetectedProcess> {
 
   // Tier 3: PID file fallback
   const filePid = readPidFile(spec.pidFile);
-  if (filePid && isProcessAlive(filePid)) {
+  if (filePid && isPidAlive(filePid)) {
     const watch = await isWatchMode(filePid);
     return {
       name: spec.name,
@@ -320,12 +318,11 @@ async function getDockerContainerState(
   containerName: string,
 ): Promise<string | null> {
   try {
-    const output = await execOutput("docker", [
-      "inspect",
-      "--format",
-      "{{.State.Status}}",
-      containerName,
-    ]);
+    const output = await execOutput(
+      "docker",
+      ["inspect", "--format", "{{.State.Status}}", containerName],
+      { timeoutMs: LOCAL_CMD_TIMEOUT_MS },
+    );
     return output.trim() || "unknown";
   } catch {
     return null;
@@ -447,6 +444,22 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
     return;
   }
 
+  if (cloud === "paired") {
+    // A remote assistant paired from another machine: no local process to
+    // list — probe the remote gateway's health over the bearer token instead.
+    const token = loadGuardianToken(entry.assistantId)?.accessToken;
+    const health = await checkHealth(entry.runtimeUrl, token);
+    const rows: TableRow[] = [
+      {
+        name: "gateway",
+        status: withStatusEmoji(health.status),
+        info: entry.runtimeUrl + (health.detail ? ` | ${health.detail}` : ""),
+      },
+    ];
+    printTable(rows);
+    return;
+  }
+
   let output: string;
   try {
     if (cloud === "gcp") {
@@ -458,9 +471,12 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
       process.exit(1);
     }
   } catch (error) {
-    console.error(
-      `Failed to list processes: ${error instanceof Error ? error.message : error}`,
-    );
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("timed out")) {
+      console.warn(`Warning: remote process listing timed out — ${msg}`);
+      return;
+    }
+    console.error(`Failed to list processes: ${msg}`);
     process.exit(1);
   }
 
@@ -496,7 +512,7 @@ async function getAssistantListHealth(
     // TODO(ATL-306): Remove readPidFile/getDaemonPidPath in favor of
     // fetching daemon PIDs via the health API (Gateway Security Migration).
     const pid = readPidFile(getDaemonPidPath(resources));
-    const alive = pid !== null && isProcessAlive(pid);
+    const alive = pid !== null && isPidAlive(pid);
     if (!alive) {
       return { status: "sleeping", detail: null };
     }

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,15 +2,21 @@ 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 {
+  canPromptForConfirmation,
+  confirmAction,
+} from "../lib/confirm-action.js";
 import { getConfigDir } from "../lib/environments/paths.js";
 import { getCurrentEnvironment } from "../lib/environments/resolve.js";
 import {
@@ -31,28 +37,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 {
@@ -172,51 +156,6 @@ function printRetireTarget(entry: AssistantEntry, cloud: string): void {
   console.log("");
 }
 
-function canPromptForRetireConfirmation(): boolean {
-  return (
-    process.stdin.isTTY === true &&
-    process.stdout.isTTY === true &&
-    typeof process.stdin.setRawMode === "function"
-  );
-}
-
-async function confirmRetireInteractive(): Promise<boolean> {
-  const stdin = process.stdin;
-  const stdout = process.stdout;
-  const wasRaw = stdin.isRaw === true;
-  const wasPaused = stdin.isPaused();
-
-  stdout.write("Press Enter to retire, or Esc/q to cancel: ");
-  stdin.setRawMode(true);
-  stdin.resume();
-
-  return await new Promise<boolean>((resolve) => {
-    const cleanup = () => {
-      stdin.off("data", onData);
-      stdin.setRawMode(wasRaw);
-      if (wasPaused) {
-        stdin.pause();
-      }
-      stdout.write("\n");
-    };
-
-    const onData = (chunk: Buffer) => {
-      const byte = chunk[0];
-      if (byte === 13 || byte === 10) {
-        cleanup();
-        resolve(true);
-        return;
-      }
-      if (byte === 27 || byte === 3 || byte === 113 || byte === 81) {
-        cleanup();
-        resolve(false);
-      }
-    };
-
-    stdin.on("data", onData);
-  });
-}
-
 /** Patch console methods to also append output to the given log file descriptor. */
 function teeConsoleToLogFile(fd: number | "ignore"): void {
   if (fd === "ignore") return;
@@ -310,10 +249,22 @@ async function retireInner(): Promise<void> {
   const assistantId = entry.assistantId;
   const source = parsed.source;
   const cloud = resolveCloud(entry);
+
+  if (cloud === "paired") {
+    // A remote assistant paired from another machine. Retiring tears the
+    // assistant down — that can only happen on its host machine, never from a
+    // paired machine, which holds nothing but a pairing record. (Removing that
+    // local record is `vellum unpair`'s job, not retire's.)
+    console.error(
+      `Error: '${assistantId}' is a remote assistant paired from another machine — it can't be retired from here. Retiring tears down the assistant, which can only be done on its host machine. To remove the local pairing record on this machine, run \`vellum unpair ${assistantId}\`.`,
+    );
+    process.exit(1);
+  }
+
   printRetireTarget(entry, cloud);
 
   if (!parsed.yes) {
-    if (!canPromptForRetireConfirmation()) {
+    if (!canPromptForConfirmation()) {
       console.error(
         "Error: Refusing to retire without confirmation in a non-interactive terminal.",
       );
@@ -321,7 +272,9 @@ async function retireInner(): Promise<void> {
       process.exit(1);
     }
 
-    const confirmed = await confirmRetireInteractive();
+    const confirmed = await confirmAction(
+      "Press Enter to retire, or Esc/q to cancel: ",
+    );
     if (!confirmed) {
       console.log("Retire cancelled.");
       process.exit(1);

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/sleep.ts

@@ -82,6 +82,13 @@ export async function sleep(): Promise<void> {
     process.exit(1);
   }
 
+  if (entry.cloud === "paired") {
+    console.error(
+      `Error: '${entry.assistantId}' is a remote assistant paired from another machine — its lifecycle is managed on its host machine, not here. Use \`vellum client ${entry.assistantId}\` to chat with it.`,
+    );
+    process.exit(1);
+  }
+
   if (entry.cloud && entry.cloud !== "local") {
     console.error(
       `Error: 'vellum sleep' only works with local and docker assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,

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,
+          },
         );
       },
     });