@vellumai/cli 0.4.44 → 0.4.46

package/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# CLI Package — Contributing Guidelines
+
+## Module Boundaries
+
+- **Commands must not import from other commands.** Shared logic belongs in `src/lib/`. If two commands need the same function, extract it into an appropriate lib module rather than importing across `src/commands/` files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.4.44",
+  "version": "0.4.46",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -11,7 +11,7 @@
     "./src/commands/*": "./src/commands/*.ts"
   },
   "bin": {
-    "assistant": "./src/index.ts"
+    "vellum": "./src/index.ts"
   },
   "scripts": {
     "format": "prettier --write .",

package/src/adapters/install.sh

@@ -179,27 +179,30 @@ configure_shell_profile() {
     done
 }
 
-# Create a symlink so `vellum` is available without ~/.bun/bin in PATH.
+# Create a symlink so a CLI command is available without ~/.bun/bin in PATH.
 # Tries /usr/local/bin first (works on most systems), falls back to
 # ~/.local/bin (user-writable, no sudo needed).
 # This is best-effort — failure must not abort the install script.
-symlink_vellum() {
-    local vellum_bin="$HOME/.bun/bin/vellum"
-    if [ ! -f "$vellum_bin" ]; then
+#
+# Usage: symlink_cli <command_name>
+symlink_cli() {
+    local cmd_name="$1"
+    local cmd_bin="$HOME/.bun/bin/$cmd_name"
+    if [ ! -f "$cmd_bin" ]; then
         return 0
     fi
 
-    # Skip if vellum is already resolvable outside of ~/.bun/bin
+    # Skip if the command is already resolvable outside of ~/.bun/bin
     local resolved
-    resolved=$(command -v vellum 2>/dev/null || true)
-    if [ -n "$resolved" ] && [ "$resolved" != "$vellum_bin" ]; then
+    resolved=$(command -v "$cmd_name" 2>/dev/null || true)
+    if [ -n "$resolved" ] && [ "$resolved" != "$cmd_bin" ]; then
         return 0
     fi
 
     # Try /usr/local/bin (may need sudo on some systems)
     if [ -d "/usr/local/bin" ] && [ -w "/usr/local/bin" ]; then
-        if ln -sf "$vellum_bin" /usr/local/bin/vellum 2>/dev/null; then
-            success "Symlinked /usr/local/bin/vellum → $vellum_bin"
+        if ln -sf "$cmd_bin" "/usr/local/bin/$cmd_name" 2>/dev/null; then
+            success "Symlinked /usr/local/bin/$cmd_name → $cmd_bin"
             return 0
         fi
     fi
@@ -207,8 +210,8 @@ symlink_vellum() {
     # Fallback: ~/.local/bin
     local local_bin="$HOME/.local/bin"
     mkdir -p "$local_bin" 2>/dev/null || true
-    if ln -sf "$vellum_bin" "$local_bin/vellum" 2>/dev/null; then
-        success "Symlinked $local_bin/vellum → $vellum_bin"
+    if ln -sf "$cmd_bin" "$local_bin/$cmd_name" 2>/dev/null; then
+        success "Symlinked $local_bin/$cmd_name → $cmd_bin"
         # Ensure ~/.local/bin is in PATH in shell profile
         for profile in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile"; do
             if [ -f "$profile" ] && ! grep -q "$local_bin" "$profile" 2>/dev/null; then
@@ -221,6 +224,11 @@ symlink_vellum() {
     return 0
 }
 
+symlink_vellum() {
+    symlink_cli "vellum"
+    symlink_cli "assistant"
+}
+
 # Write a small sourceable env file to ~/.config/vellum/env so callers can
 # pick up PATH changes without restarting their shell:
 #   curl -fsSL https://assistant.vellum.ai/install.sh | bash && . ~/.config/vellum/env
@@ -265,6 +273,11 @@ main() {
     install_vellum
     symlink_vellum
 
+    # Verify the assistant CLI is available
+    if ! command -v assistant >/dev/null 2>&1; then
+        info "Note: 'assistant' command may require opening a new terminal session"
+    fi
+
     # Write a sourceable env file so the quickstart one-liner can pick up
     # PATH changes in the caller's shell:
     #   curl ... | bash && . ~/.config/vellum/env

package/src/commands/clean.ts

@@ -0,0 +1,34 @@
+import { detectOrphanedProcesses } from "../lib/orphan-detection";
+import { stopProcess } from "../lib/process";
+
+export async function clean(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum clean");
+    console.log("");
+    console.log("Kill all orphaned vellum processes that are not tracked by any assistant.");
+    process.exit(0);
+  }
+
+  const orphans = await detectOrphanedProcesses();
+
+  if (orphans.length === 0) {
+    console.log("No orphaned processes found.");
+    return;
+  }
+
+  console.log(`Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"}.\n`);
+
+  let killed = 0;
+  for (const orphan of orphans) {
+    const pid = parseInt(orphan.pid, 10);
+    const stopped = await stopProcess(pid, `${orphan.name} (PID ${orphan.pid})`);
+    if (stopped) {
+      killed++;
+    }
+  }
+
+  console.log(
+    `\nCleaned up ${killed} process${killed === 1 ? "" : "es"}.`,
+  );
+}

package/src/commands/hatch.ts

@@ -47,7 +47,9 @@ import {
   startGateway,
   stopLocalProcesses,
 } from "../lib/local";
-import { isProcessAlive } from "../lib/process";
+import { maybeStartNgrokTunnel } from "../lib/ngrok";
+import { detectOrphanedProcesses } from "../lib/orphan-detection";
+import { isProcessAlive, stopProcess } from "../lib/process";
 import { generateRandomSuffix } from "../lib/random-name";
 import { validateAssistantName } from "../lib/retire-archive";
 import { archiveLogFile, resetLogFile } from "../lib/xdg-log";
@@ -266,7 +268,16 @@ function parseArgs(): HatchArgs {
     }
   }
 
-  return { species, detached, keepAlive, name, remote, daemonOnly, restart, watch };
+  return {
+    species,
+    detached,
+    keepAlive,
+    name,
+    remote,
+    daemonOnly,
+    restart,
+    watch,
+  };
 }
 
 function formatElapsed(ms: number): string {
@@ -721,6 +732,22 @@ async function hatchLocal(
     }
   }
 
+  // On desktop, scan the process table for orphaned vellum processes that
+  // are not tracked by any PID file or lock file entry and kill them before
+  // starting new ones. This prevents resource leaks when the desktop app
+  // crashes or is force-quit without a clean shutdown.
+  if (IS_DESKTOP) {
+    const orphans = await detectOrphanedProcesses();
+    if (orphans.length > 0) {
+      desktopLog(
+        `🧹 Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"} — cleaning up...`,
+      );
+      for (const orphan of orphans) {
+        await stopProcess(parseInt(orphan.pid, 10), `${orphan.name} (PID ${orphan.pid})`);
+      }
+    }
+  }
+
   // Reuse existing resources if re-hatching with --name that matches a known
   // local assistant, otherwise allocate fresh per-instance ports and directories.
   let resources: LocalInstanceResources;
@@ -731,7 +758,13 @@ async function hatchLocal(
     resources = await allocateLocalResources(instanceName);
   }
 
-  const logsDir = join(resources.instanceDir, ".vellum", "workspace", "data", "logs");
+  const logsDir = join(
+    resources.instanceDir,
+    ".vellum",
+    "workspace",
+    "data",
+    "logs",
+  );
   archiveLogFile("hatch.log", logsDir);
   resetLogFile("hatch.log");
 
@@ -754,6 +787,21 @@ async function hatchLocal(
     throw error;
   }
 
+  // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
+  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
+  const prevBaseDataDir = process.env.BASE_DATA_DIR;
+  process.env.BASE_DATA_DIR = resources.instanceDir;
+  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+  if (ngrokChild?.pid) {
+    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+  }
+  if (prevBaseDataDir !== undefined) {
+    process.env.BASE_DATA_DIR = prevBaseDataDir;
+  } else {
+    delete process.env.BASE_DATA_DIR;
+  }
+
   // Read the bearer token (JWT) written by the daemon so the CLI can
   // with the gateway (which requires auth by default). The daemon writes under
   // getRootDir() which resolves to <instanceDir>/.vellum/.
@@ -831,9 +879,7 @@ async function hatchLocal(
         consecutiveFailures++;
       }
       if (consecutiveFailures >= MAX_FAILURES) {
-        console.log(
-          "\n⚠️  Gateway stopped responding — shutting down.",
-        );
+        console.log("\n⚠️  Gateway stopped responding — shutting down.");
         await stopLocalProcesses(resources);
         process.exit(1);
       }
@@ -849,8 +895,16 @@ export async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@vellumai/cli v${cliVersion}`);
 
-  const { species, detached, keepAlive, name, remote, daemonOnly, restart, watch } =
-    parseArgs();
+  const {
+    species,
+    detached,
+    keepAlive,
+    name,
+    remote,
+    daemonOnly,
+    restart,
+    watch,
+  } = parseArgs();
 
   if (restart && remote !== "local") {
     console.error(

package/src/commands/ps.ts

@@ -1,5 +1,3 @@
-import { existsSync, readFileSync } from "fs";
-import { homedir } from "os";
 import { join } from "path";
 
 import {
@@ -9,6 +7,13 @@ import {
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { checkHealth } from "../lib/health-check";
+import {
+  classifyProcess,
+  detectOrphanedProcesses,
+  isProcessAlive,
+  parseRemotePs,
+  readPidFile,
+} from "../lib/orphan-detection";
 import { pgrepExact } from "../lib/pgrep";
 import { probePort } from "../lib/port-probe";
 import { withStatusEmoji } from "../lib/status-emoji";
@@ -77,40 +82,6 @@ const REMOTE_PS_CMD = [
   "| grep -v grep",
 ].join(" ");
 
-interface RemoteProcess {
-  pid: string;
-  ppid: string;
-  command: string;
-}
-
-function classifyProcess(command: string): string {
-  if (/qdrant/.test(command)) return "qdrant";
-  if (/vellum-gateway/.test(command)) return "gateway";
-  if (/openclaw/.test(command)) return "openclaw-adapter";
-  if (/vellum-daemon/.test(command)) return "assistant";
-  if (/daemon\s+(start|restart)/.test(command)) return "assistant";
-  // Exclude macOS desktop app processes — their path contains .app/Contents/MacOS/
-  // but they are not background service processes.
-  if (/\.app\/Contents\/MacOS\//.test(command)) return "unknown";
-  if (/vellum/.test(command)) return "vellum";
-  return "unknown";
-}
-
-function parseRemotePs(output: string): RemoteProcess[] {
-  return output
-    .trim()
-    .split("\n")
-    .filter((line) => line.trim().length > 0)
-    .map((line) => {
-      const trimmed = line.trim();
-      const parts = trimmed.split(/\s+/);
-      const pid = parts[0];
-      const ppid = parts[1];
-      const command = parts.slice(2).join(" ");
-      return { pid, ppid, command };
-    });
-}
-
 function extractHostFromUrl(url: string): string {
   try {
     const parsed = new URL(url);
@@ -157,21 +128,6 @@ interface ProcessSpec {
   pidFile: string;
 }
 
-function readPidFile(pidFile: string): string | null {
-  if (!existsSync(pidFile)) return null;
-  const pid = readFileSync(pidFile, "utf-8").trim();
-  return pid || null;
-}
-
-function isProcessAlive(pid: string): boolean {
-  try {
-    process.kill(parseInt(pid, 10), 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 interface DetectedProcess {
   name: string;
   pid: string | null;
@@ -318,57 +274,6 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   printTable(rows);
 }
 
-// ── Orphaned process detection ──────────────────────────────────
-
-interface OrphanedProcess {
-  name: string;
-  pid: string;
-  source: string;
-}
-
-async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
-  const results: OrphanedProcess[] = [];
-  const seenPids = new Set<string>();
-  const vellumDir = join(homedir(), ".vellum");
-
-  // Strategy 1: PID file scan
-  const pidFiles: Array<{ file: string; name: string }> = [
-    { file: join(vellumDir, "vellum.pid"), name: "assistant" },
-    { file: join(vellumDir, "gateway.pid"), name: "gateway" },
-    { file: join(vellumDir, "qdrant.pid"), name: "qdrant" },
-  ];
-
-  for (const { file, name } of pidFiles) {
-    const pid = readPidFile(file);
-    if (pid && isProcessAlive(pid)) {
-      results.push({ name, pid, source: "pid file" });
-      seenPids.add(pid);
-    }
-  }
-
-  // Strategy 2: Process table scan
-  try {
-    const output = await execOutput("sh", [
-      "-c",
-      "ps ax -o pid=,ppid=,args= | grep -E 'vellum|vellum-gateway|qdrant|openclaw' | grep -v grep",
-    ]);
-    const procs = parseRemotePs(output);
-    const ownPid = String(process.pid);
-
-    for (const p of procs) {
-      if (p.pid === ownPid || seenPids.has(p.pid)) continue;
-      const type = classifyProcess(p.command);
-      if (type === "unknown") continue;
-      results.push({ name: type, pid: p.pid, source: "process table" });
-      seenPids.add(p.pid);
-    }
-  } catch {
-    // grep exits 1 when no matches found — ignore
-  }
-
-  return results;
-}
-
 // ── List all assistants (no arg) ────────────────────────────────
 
 async function listAllAssistants(): Promise<void> {
@@ -387,9 +292,8 @@ async function listAllAssistants(): Promise<void> {
         info: `PID ${o.pid} (from ${o.source})`,
       }));
       printTable(rows);
-      const pids = orphans.map((o) => o.pid).join(" ");
       console.log(
-        `\nHint: Run \`kill ${pids}\` to clean up orphaned processes.`,
+        `\nHint: Run \`vellum clean\` to clean up orphaned processes.`,
       );
     }
 

package/src/commands/wake.ts

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 
 import { resolveTargetAssistant } from "../lib/assistant-config.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 import { startLocalDaemon, startGateway } from "../lib/local";
+import { maybeStartNgrokTunnel } from "../lib/ngrok";
 
 export async function wake(): Promise<void> {
   const args = process.argv.slice(3);
@@ -95,5 +96,20 @@ export async function wake(): Promise<void> {
     }
   }
 
+  // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
+  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
+  const prevBaseDataDir = process.env.BASE_DATA_DIR;
+  process.env.BASE_DATA_DIR = resources.instanceDir;
+  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+  if (ngrokChild?.pid) {
+    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+  }
+  if (prevBaseDataDir !== undefined) {
+    process.env.BASE_DATA_DIR = prevBaseDataDir;
+  } else {
+    delete process.env.BASE_DATA_DIR;
+  }
+
   console.log("Wake complete.");
 }

package/src/components/DefaultMainScreen.tsx

@@ -34,6 +34,7 @@ export const ANSI = {
 } as const;
 
 export const SLASH_COMMANDS = [
+  "/btw",
   "/clear",
   "/doctor",
   "/exit",
@@ -98,7 +99,7 @@ const MIN_FEED_ROWS = 3;
 // Feed item height estimation
 const TOOL_CALL_CHROME_LINES = 2; // header (┌) + footer (└)
 const MESSAGE_SPACING = 1;
-const HELP_DISPLAY_HEIGHT = 6;
+const HELP_DISPLAY_HEIGHT = 8;
 
 interface ListMessagesResponse {
   messages: RuntimeMessage[];
@@ -372,13 +373,7 @@ async function handleConfirmationPrompt(
   const index = await chatApp.showSelection("Tool Approval", options);
 
   if (index === 0) {
-    await submitDecision(
-      baseUrl,
-      assistantId,
-      requestId,
-      "allow",
-      bearerToken,
-    );
+    await submitDecision(baseUrl, assistantId, requestId, "allow", bearerToken);
     chatApp.addStatus("\u2714 Allowed", "green");
     return;
   }
@@ -407,13 +402,7 @@ async function handleConfirmationPrompt(
     return;
   }
 
-  await submitDecision(
-    baseUrl,
-    assistantId,
-    requestId,
-    "deny",
-    bearerToken,
-  );
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -450,13 +439,7 @@ async function handlePatternSelection(
     return;
   }
 
-  await submitDecision(
-    baseUrl,
-    assistantId,
-    requestId,
-    "deny",
-    bearerToken,
-  );
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -504,13 +487,7 @@ async function handleScopeSelection(
     return;
   }
 
-  await submitDecision(
-    baseUrl,
-    assistantId,
-    requestId,
-    "deny",
-    bearerToken,
-  );
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -642,6 +619,10 @@ function HelpDisplay(): ReactElement {
   return (
     <Box flexDirection="column">
       <Text bold>Commands:</Text>
+      <Text>
+        {"  /btw <question>   "}
+        <Text dimColor>Ask a side question while the assistant is working</Text>
+      </Text>
       <Text>
         {"  /doctor [question] "}
         <Text dimColor>Run diagnostics on the remote instance via SSH</Text>
@@ -1265,7 +1246,6 @@ function ChatApp({
 
   const showSpinner = useCallback((text: string) => {
     setSpinnerText(text);
-    setInputFocused(false);
   }, []);
 
   const hideSpinner = useCallback(() => {
@@ -1501,79 +1481,6 @@ function ChatApp({
         return;
       }
 
-      if (trimmed === "/pair") {
-        h.showSpinner("Generating pairing credentials...");
-
-        const isConnected = await ensureConnected();
-        if (!isConnected) {
-          h.hideSpinner();
-          h.showError("Cannot pair — not connected to the assistant runtime.");
-          return;
-        }
-
-        try {
-          const pairingRequestId = randomUUID();
-          const pairingSecret = randomBytes(32).toString("hex");
-          const gatewayUrl = runtimeUrl;
-
-          // Call /pairing/register on the gateway (dedicated pairing proxy route)
-          const registerUrl = `${runtimeUrl}/pairing/register`;
-          const registerRes = await fetch(registerUrl, {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json",
-              ...(bearerToken
-                ? { Authorization: `Bearer ${bearerToken}` }
-                : {}),
-            },
-            body: JSON.stringify({
-              pairingRequestId,
-              pairingSecret,
-              gatewayUrl,
-            }),
-          });
-
-          if (!registerRes.ok) {
-            const body = await registerRes.text().catch(() => "");
-            throw new Error(
-              `HTTP ${registerRes.status}: ${body || registerRes.statusText}`,
-            );
-          }
-
-          const hostId = createHash("sha256")
-            .update(hostname() + userInfo().username)
-            .digest("hex");
-          const payload = JSON.stringify({
-            type: "vellum-daemon",
-            v: 4,
-            id: hostId,
-            g: gatewayUrl,
-            pairingRequestId,
-            pairingSecret,
-          });
-
-          const qrString = await new Promise<string>((resolve) => {
-            qrcode.generate(payload, { small: true }, (code: string) => {
-              resolve(code);
-            });
-          });
-
-          h.hideSpinner();
-          h.addStatus(
-            `Pairing Ready\n\n` +
-              `Scan this QR code with the Vellum iOS app:\n\n` +
-              `${qrString}\n` +
-              `This pairing request expires in 5 minutes. Run /pair again to generate a new one.`,
-          );
-        } catch (err) {
-          h.hideSpinner();
-          h.showError(
-            `Pairing failed: ${err instanceof Error ? err.message : err}`,
-          );
-        }
-        return;
-      }
-
       if (trimmed === "/retire") {
         if (!project || !zone) {
           h.showError(
@@ -1727,6 +1634,214 @@ function ChatApp({
         return;
       }
 
+      // If a connection attempt is already in progress, don't silently drop input
+      if (connectingRef.current) {
+        h.addStatus(
+          "Still connecting — please wait a moment and try again.",
+          "yellow",
+        );
+        return;
+      }
+
+      if (trimmed.startsWith("/btw ")) {
+        const question = trimmed.slice(5).trim();
+        if (!question) return;
+
+        h.addStatus(`/btw ${question}`, "gray");
+
+        const isConnected = await ensureConnected();
+        if (!isConnected) return;
+
+        try {
+          const res = await fetch(
+            `${runtimeUrl}/v1/assistants/${assistantId}/btw`,
+            {
+              method: "POST",
+              headers: {
+                "Content-Type": "application/json",
+                ...(bearerToken
+                  ? { Authorization: `Bearer ${bearerToken}` }
+                  : {}),
+              },
+              body: JSON.stringify({
+                conversationKey: assistantId,
+                content: question,
+              }),
+              signal: AbortSignal.timeout(30_000),
+            },
+          );
+
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+
+          let fullText = "";
+          let sseError = "";
+          const reader = res.body?.getReader();
+          const decoder = new TextDecoder();
+          if (reader) {
+            let buffer = "";
+            let currentEvent = "";
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              buffer += decoder.decode(value, { stream: true });
+              const lines = buffer.split("\n");
+              buffer = lines.pop() ?? "";
+              for (const line of lines) {
+                if (line.startsWith("event: ")) {
+                  currentEvent = line.slice(7).trim();
+                } else if (line.startsWith("data: ")) {
+                  try {
+                    const data = JSON.parse(line.slice(6));
+                    if (currentEvent === "btw_error" || data.error) {
+                      sseError = data.error ?? data.text ?? "Unknown error";
+                    } else if (data.text) {
+                      fullText += data.text;
+                    }
+                  } catch {
+                    /* skip malformed */
+                  }
+                } else if (line.trim() === "") {
+                  // Empty line marks end of SSE event; reset event type
+                  currentEvent = "";
+                }
+              }
+            }
+          }
+          if (sseError) {
+            h.showError(`/btw: ${sseError}`);
+          } else {
+            h.addStatus(fullText || "No response");
+          }
+        } catch (err) {
+          h.showError(
+            `/btw failed: ${err instanceof Error ? err.message : err}`,
+          );
+        }
+        return;
+      }
+
+      if (trimmed === "/pair") {
+        h.showSpinner("Generating pairing credentials...");
+
+        const isConnected = await ensureConnected();
+        if (!isConnected) {
+          h.hideSpinner();
+          h.showError("Cannot pair — not connected to the assistant runtime.");
+          return;
+        }
+
+        try {
+          const pairingRequestId = randomUUID();
+          const pairingSecret = randomBytes(32).toString("hex");
+          const gatewayUrl = runtimeUrl;
+
+          // Call /pairing/register on the gateway (dedicated pairing proxy route)
+          const registerUrl = `${runtimeUrl}/pairing/register`;
+          const registerRes = await fetch(registerUrl, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              ...(bearerToken
+                ? { Authorization: `Bearer ${bearerToken}` }
+                : {}),
+            },
+            body: JSON.stringify({
+              pairingRequestId,
+              pairingSecret,
+              gatewayUrl,
+            }),
+          });
+
+          if (!registerRes.ok) {
+            const body = await registerRes.text().catch(() => "");
+            throw new Error(
+              `HTTP ${registerRes.status}: ${body || registerRes.statusText}`,
+            );
+          }
+
+          const hostId = createHash("sha256")
+            .update(hostname() + userInfo().username)
+            .digest("hex");
+          const payload = JSON.stringify({
+            type: "vellum-daemon",
+            v: 4,
+            id: hostId,
+            g: gatewayUrl,
+            pairingRequestId,
+            pairingSecret,
+          });
+
+          const qrString = await new Promise<string>((resolve) => {
+            qrcode.generate(payload, { small: true }, (code: string) => {
+              resolve(code);
+            });
+          });
+
+          h.hideSpinner();
+          h.addStatus(
+            `Pairing Ready\n\n` +
+              `Scan this QR code with the Vellum iOS app:\n\n` +
+              `${qrString}\n` +
+              `This pairing request expires in 5 minutes. Run /pair again to generate a new one.`,
+          );
+        } catch (err) {
+          h.hideSpinner();
+          h.showError(
+            `Pairing failed: ${err instanceof Error ? err.message : err}`,
+          );
+        }
+        return;
+      }
+
+      if (busyRef.current) {
+        // /btw is already handled above this block
+        if (!trimmed.startsWith("/")) {
+          const userMsg: RuntimeMessage = {
+            id: "local-user-" + Date.now(),
+            role: "user",
+            content: trimmed,
+            timestamp: new Date().toISOString(),
+          };
+          h.addMessage(userMsg);
+        }
+        const isConnected = await ensureConnected();
+        if (!isConnected) {
+          h.showError("Cannot send — not connected to the assistant.");
+          setInputFocused(true);
+          return;
+        }
+        try {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(
+            () => controller.abort(),
+            SEND_TIMEOUT_MS,
+          );
+          const sendResult = await sendMessage(
+            runtimeUrl,
+            assistantId,
+            trimmed,
+            controller.signal,
+            bearerToken,
+          );
+          clearTimeout(timeoutId);
+          if (sendResult.accepted) {
+            chatLogRef.current.push({ role: "user", content: trimmed });
+            h.addStatus(
+              "Message queued — will be processed after current response",
+              "gray",
+            );
+          } else {
+            h.showError("Message was not accepted by the assistant");
+          }
+        } catch (err) {
+          h.showError(
+            `Failed to queue message: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+        setInputFocused(true);
+        return;
+      }
+
       if (!trimmed.startsWith("/")) {
         const userMsg: RuntimeMessage = {
           id: "local-user-" + Date.now(),

package/src/index.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import cliPkg from "../package.json";
+import { clean } from "./commands/clean";
 import { client } from "./commands/client";
 import { hatch } from "./commands/hatch";
 import { login, logout, whoami } from "./commands/login";
@@ -15,6 +16,7 @@ import { use } from "./commands/use";
 import { wake } from "./commands/wake";
 
 const commands = {
+  clean,
   client,
   hatch,
   login,
@@ -46,6 +48,7 @@ async function main() {
     console.log("Usage: vellum <command> [options]");
     console.log("");
     console.log("Commands:");
+    console.log("  clean    Kill orphaned vellum processes");
     console.log("  client   Connect to a hatched assistant");
     console.log("  hatch    Create a new assistant instance");
     console.log("  login    Log in to the Vellum platform");

package/src/lib/aws.ts

@@ -513,7 +513,6 @@ export async function hatchAws(
     const awsEntry: AssistantEntry = {
       assistantId: instanceName,
       runtimeUrl,
-      bearerToken,
       cloud: "aws",
       instanceId,
       region,

package/src/lib/docker.ts

@@ -10,7 +10,12 @@ import type { Species } from "./constants";
 import { discoverPublicUrl } from "./local";
 import { generateRandomSuffix } from "./random-name";
 import { exec, execOutput } from "./step-runner";
-import { closeLogFile, openLogFile, resetLogFile, writeToLogFile } from "./xdg-log";
+import {
+  closeLogFile,
+  openLogFile,
+  resetLogFile,
+  writeToLogFile,
+} from "./xdg-log";
 
 const _require = createRequire(import.meta.url);
 
@@ -26,7 +31,7 @@ interface DockerRoot {
  * Dockerfiles live under `meta/`, but when installed as an npm package they
  * are at the package root.
  */
-function findDockerRoot(): DockerRoot {
+function findDockerRoot(developmentMode: boolean = false): DockerRoot {
   // Source tree: cli/src/lib/ -> repo root (Dockerfiles in meta/)
   const sourceTreeRoot = join(import.meta.dir, "..", "..", "..");
   if (existsSync(join(sourceTreeRoot, "meta", "Dockerfile"))) {
@@ -50,6 +55,27 @@ function findDockerRoot(): DockerRoot {
     dir = parent;
   }
 
+  // In development mode, walk up from the executable path to find the repo
+  // root. This handles the macOS app bundle case where the binary lives inside
+  // the repo at e.g. clients/macos/dist/Vellum.app/Contents/MacOS/.
+  if (developmentMode) {
+    let execDir = dirname(process.execPath);
+    while (true) {
+      if (existsSync(join(execDir, "meta", "Dockerfile.development"))) {
+        return { root: execDir, dockerfileDir: "meta" };
+      }
+      const parent = dirname(execDir);
+      if (parent === execDir) break;
+      execDir = parent;
+    }
+  }
+
+  // macOS app bundle: Contents/MacOS/vellum-cli -> Contents/Resources/Dockerfile
+  const appResourcesDir = join(dirname(process.execPath), "..", "Resources");
+  if (existsSync(join(appResourcesDir, "Dockerfile"))) {
+    return { root: appResourcesDir, dockerfileDir: "." };
+  }
+
   // Fall back to Node module resolution for the `vellum` package
   try {
     const vellumPkgPath = _require.resolve("vellum/package.json");
@@ -152,19 +178,41 @@ export async function hatchDocker(
   name: string | null,
   watch: boolean,
 ): Promise<void> {
-  const { root: repoRoot, dockerfileDir } = findDockerRoot();
+  resetLogFile("hatch.log");
+
+  let repoRoot: string;
+  let dockerfileDir: string;
+  try {
+    ({ root: repoRoot, dockerfileDir } = findDockerRoot(watch));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const logFd = openLogFile("hatch.log");
+    writeToLogFile(
+      logFd,
+      `[docker-hatch] ${new Date().toISOString()} ERROR\n${message}\n`,
+    );
+    closeLogFile(logFd);
+    console.error(message);
+    throw err;
+  }
+
   const instanceName = name ?? `${species}-${generateRandomSuffix()}`;
   const dockerfileName = watch ? "Dockerfile.development" : "Dockerfile";
   const dockerfile = join(dockerfileDir, dockerfileName);
   const dockerfilePath = join(repoRoot, dockerfile);
 
   if (!existsSync(dockerfilePath)) {
-    console.error(`Error: ${dockerfile} not found at ${dockerfilePath}`);
+    const message = `Error: ${dockerfile} not found at ${dockerfilePath}`;
+    const logFd = openLogFile("hatch.log");
+    writeToLogFile(
+      logFd,
+      `[docker-hatch] ${new Date().toISOString()} ERROR\n${message}\n`,
+    );
+    closeLogFile(logFd);
+    console.error(message);
     process.exit(1);
   }
 
-  resetLogFile("hatch.log");
-
   console.log(`🥚 Hatching Docker assistant: ${instanceName}`);
   console.log(`   Species: ${species}`);
   console.log(`   Dockerfile: ${dockerfile}`);
@@ -182,7 +230,10 @@ export async function hatchDocker(
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    writeToLogFile(logFd, `[docker-build] ${new Date().toISOString()} ERROR\n${message}\n`);
+    writeToLogFile(
+      logFd,
+      `[docker-build] ${new Date().toISOString()} ERROR\n${message}\n`,
+    );
     closeLogFile(logFd);
     throw err;
   }
@@ -244,13 +295,21 @@ export async function hatchDocker(
   // requires an extra argument the Dockerfile doesn't include.
   const containerCmd: string[] =
     species !== "vellum"
-      ? ["vellum", "hatch", species, ...(watch ? ["--watch"] : []), "--keep-alive"]
+      ? [
+          "vellum",
+          "hatch",
+          species,
+          ...(watch ? ["--watch"] : []),
+          "--keep-alive",
+        ]
       : [];
 
   // Always start the container detached so it keeps running after the CLI exits.
   runArgs.push("-d");
   console.log("🚀 Starting Docker container...");
-  await exec("docker", [...runArgs, imageTag, ...containerCmd], { cwd: repoRoot });
+  await exec("docker", [...runArgs, imageTag, ...containerCmd], {
+    cwd: repoRoot,
+  });
 
   if (detached) {
     console.log("\n✅ Docker assistant hatched!\n");
@@ -304,7 +363,13 @@ export async function hatchDocker(
       child.on("close", (code) => {
         // The log tail may exit if the container stops before the sentinel
         // is seen, or we killed it after detecting the sentinel.
-        if (code === 0 || code === null || code === 130 || code === 137 || code === 143) {
+        if (
+          code === 0 ||
+          code === null ||
+          code === 130 ||
+          code === 137 ||
+          code === 143
+        ) {
           resolve();
         } else {
           reject(new Error(`Docker container exited with code ${code}`));

package/src/lib/gcp.ts

@@ -441,45 +441,6 @@ async function recoverFromCurlFailure(
   } catch {}
 }
 
-async function fetchRemoteBearerToken(
-  instanceName: string,
-  project: string,
-  zone: string,
-  sshUser: string,
-  account?: string,
-): Promise<string | null> {
-  try {
-    const remoteCmd =
-      'cat ~/.vellum.lock.json 2>/dev/null || cat ~/.vellum.lockfile.json 2>/dev/null || echo "{}"';
-    const args = [
-      "compute",
-      "ssh",
-      `${sshUser}@${instanceName}`,
-      `--project=${project}`,
-      `--zone=${zone}`,
-      "--quiet",
-      "--ssh-flag=-o StrictHostKeyChecking=no",
-      "--ssh-flag=-o UserKnownHostsFile=/dev/null",
-      "--ssh-flag=-o ConnectTimeout=10",
-      "--ssh-flag=-o LogLevel=ERROR",
-      `--command=${remoteCmd}`,
-    ];
-    if (account) args.push(`--account=${account}`);
-    const output = await execOutput("gcloud", args);
-    const data = JSON.parse(output.trim());
-    const assistants = data.assistants;
-    if (Array.isArray(assistants) && assistants.length > 0) {
-      const token = assistants[0].bearerToken;
-      if (typeof token === "string" && token) {
-        return token;
-      }
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
 export async function hatchGcp(
   species: Species,
   detached: boolean,
@@ -629,7 +590,6 @@ export async function hatchGcp(
     const gcpEntry: AssistantEntry = {
       assistantId: instanceName,
       runtimeUrl,
-      bearerToken,
       cloud: "gcp",
       project,
       zone,
@@ -694,18 +654,6 @@ export async function hatchGcp(
         }
       }
 
-      const remoteBearerToken = await fetchRemoteBearerToken(
-        instanceName,
-        project,
-        zone,
-        sshUser,
-        account,
-      );
-      if (remoteBearerToken) {
-        gcpEntry.bearerToken = remoteBearerToken;
-        saveAssistantEntry(gcpEntry);
-      }
-
       console.log("Instance details:");
       console.log(`  Name: ${instanceName}`);
       console.log(`  Project: ${project}`);

package/src/lib/local.ts

@@ -1046,4 +1046,20 @@ export async function stopLocalProcesses(
 
   const gatewayPidFile = join(vellumDir, "gateway.pid");
   await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
+
+  // Kill ngrok directly by PID rather than using stopProcessByPidFile, because
+  // isVellumProcess() checks for /vellum|@vellumai|--vellum-gateway/ which
+  // won't match the ngrok binary — resulting in a no-op that leaves ngrok running.
+  const ngrokPidFile = join(vellumDir, "ngrok.pid");
+  if (existsSync(ngrokPidFile)) {
+    try {
+      const pid = parseInt(readFileSync(ngrokPidFile, "utf-8").trim(), 10);
+      if (!isNaN(pid)) {
+        try {
+          process.kill(pid, "SIGTERM");
+        } catch {}
+      }
+      unlinkSync(ngrokPidFile);
+    } catch {}
+  }
 }

package/src/lib/ngrok.ts

@@ -115,6 +115,7 @@ export async function findExistingTunnel(
  */
 export function startNgrokProcess(targetPort: number): ChildProcess {
   const child = spawn("ngrok", ["http", String(targetPort), "--log=stdout"], {
+    detached: true,
     stdio: ["ignore", "pipe", "pipe"],
   });
   return child;
@@ -168,6 +169,97 @@ function clearIngressUrl(): void {
   saveRawConfig(config);
 }
 
+/**
+ * Check whether any webhook-based integrations (e.g. Telegram) are configured
+ * that require a public ingress URL.
+ */
+function hasWebhookIntegrationsConfigured(): boolean {
+  try {
+    const config = loadRawConfig();
+    const telegram = config.telegram as Record<string, unknown> | undefined;
+    if (telegram?.botUsername) return true;
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check whether a non-ngrok ingress URL is already configured (e.g. custom
+ * domain or cloud deployment), meaning ngrok is not needed.
+ */
+function hasNonNgrokIngressUrl(): boolean {
+  try {
+    const config = loadRawConfig();
+    const ingress = config.ingress as Record<string, unknown> | undefined;
+    const publicBaseUrl = ingress?.publicBaseUrl;
+    if (!publicBaseUrl || typeof publicBaseUrl !== "string") return false;
+    return !publicBaseUrl.includes("ngrok");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Auto-start an ngrok tunnel if webhook integrations are configured and no
+ * non-ngrok ingress URL is present. Designed to be called during daemon/gateway
+ * startup. Non-fatal: if ngrok is unavailable or fails, startup continues.
+ *
+ * Returns the spawned ngrok child process (for PID tracking) or null.
+ */
+export async function maybeStartNgrokTunnel(
+  targetPort: number,
+): Promise<ChildProcess | null> {
+  if (!hasWebhookIntegrationsConfigured()) return null;
+  if (hasNonNgrokIngressUrl()) return null;
+
+  const version = getNgrokVersion();
+  if (!version) return null;
+
+  // Reuse an existing tunnel if one is already running
+  const existingUrl = await findExistingTunnel(targetPort);
+  if (existingUrl) {
+    console.log(`   Found existing ngrok tunnel: ${existingUrl}`);
+    saveIngressUrl(existingUrl);
+    return null;
+  }
+
+  console.log(`   Starting ngrok tunnel for webhook integrations...`);
+  const ngrokProcess = startNgrokProcess(targetPort);
+
+  // Pipe output for debugging but don't block on it
+  ngrokProcess.stdout?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[ngrok] ${line}`);
+  });
+  ngrokProcess.stderr?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.error(`[ngrok] ${line}`);
+  });
+
+  try {
+    const publicUrl = await waitForNgrokUrl();
+    saveIngressUrl(publicUrl);
+    console.log(`   Tunnel established: ${publicUrl}`);
+
+    // Detach the ngrok process so the CLI (hatch/wake) can exit without
+    // keeping it alive. Remove stdout/stderr listeners and unref all handles.
+    ngrokProcess.stdout?.removeAllListeners("data");
+    ngrokProcess.stderr?.removeAllListeners("data");
+    ngrokProcess.stdout?.destroy();
+    ngrokProcess.stderr?.destroy();
+    ngrokProcess.unref();
+
+    return ngrokProcess;
+  } catch {
+    console.warn(
+      `   ⚠ Could not start ngrok tunnel. Webhook integrations may not work until you run \`vellum tunnel\`.`,
+    );
+    if (!ngrokProcess.killed) ngrokProcess.kill("SIGTERM");
+    return null;
+  }
+}
+
 /**
  * Run the ngrok tunnel workflow: check installation, find or start a tunnel,
  * save the public URL to config, and block until exit or signal.

package/src/lib/orphan-detection.ts

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+import { execOutput } from "./step-runner";
+
+export interface RemoteProcess {
+  pid: string;
+  ppid: string;
+  command: string;
+}
+
+export function classifyProcess(command: string): string {
+  if (/qdrant/.test(command)) return "qdrant";
+  if (/vellum-gateway/.test(command)) return "gateway";
+  if (/openclaw/.test(command)) return "openclaw-adapter";
+  if (/vellum-daemon/.test(command)) return "assistant";
+  if (/daemon\s+(start|restart)/.test(command)) return "assistant";
+  // Exclude macOS desktop app processes — their path contains .app/Contents/MacOS/
+  // but they are not background service processes.
+  if (/\.app\/Contents\/MacOS\//.test(command)) return "unknown";
+  if (/vellum/.test(command)) return "vellum";
+  return "unknown";
+}
+
+export function parseRemotePs(output: string): RemoteProcess[] {
+  return output
+    .trim()
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      const trimmed = line.trim();
+      const parts = trimmed.split(/\s+/);
+      const pid = parts[0];
+      const ppid = parts[1];
+      const command = parts.slice(2).join(" ");
+      return { pid, ppid, command };
+    });
+}
+
+export function readPidFile(pidFile: string): string | null {
+  if (!existsSync(pidFile)) return null;
+  const pid = readFileSync(pidFile, "utf-8").trim();
+  return pid || null;
+}
+
+export function isProcessAlive(pid: string): boolean {
+  try {
+    process.kill(parseInt(pid, 10), 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface OrphanedProcess {
+  name: string;
+  pid: string;
+  source: string;
+}
+
+export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
+  const results: OrphanedProcess[] = [];
+  const seenPids = new Set<string>();
+  const vellumDir = join(homedir(), ".vellum");
+
+  // Strategy 1: PID file scan
+  const pidFiles: Array<{ file: string; name: string }> = [
+    { file: join(vellumDir, "vellum.pid"), name: "assistant" },
+    { file: join(vellumDir, "gateway.pid"), name: "gateway" },
+    { file: join(vellumDir, "qdrant.pid"), name: "qdrant" },
+  ];
+
+  for (const { file, name } of pidFiles) {
+    const pid = readPidFile(file);
+    if (pid && isProcessAlive(pid)) {
+      results.push({ name, pid, source: "pid file" });
+      seenPids.add(pid);
+    }
+  }
+
+  // Strategy 2: Process table scan
+  try {
+    const output = await execOutput("sh", [
+      "-c",
+      "ps ax -o pid=,ppid=,args= | grep -E 'vellum|vellum-gateway|qdrant|openclaw' | grep -v grep",
+    ]);
+    const procs = parseRemotePs(output);
+    const ownPid = String(process.pid);
+
+    for (const p of procs) {
+      if (p.pid === ownPid || seenPids.has(p.pid)) continue;
+      const type = classifyProcess(p.command);
+      if (type === "unknown") continue;
+      results.push({ name: type, pid: p.pid, source: "process table" });
+      seenPids.add(p.pid);
+    }
+  } catch {
+    // grep exits 1 when no matches found — ignore
+  }
+
+  return results;
+}