@vellumai/cli 0.3.19 → 0.3.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/commands/config.ts

@@ -2,6 +2,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
+import { syncConfigToLockfile } from "../lib/assistant-config";
+
 interface AllowlistConfig {
   values?: string[];
   prefixes?: string[];
@@ -176,6 +178,7 @@ export function config(): void {
       }
       setNestedValue(raw, key, parsed);
       saveRawConfig(raw);
+      syncConfigToLockfile();
       console.log(`Set ${key} = ${JSON.stringify(parsed)}`);
       break;
     }

package/src/commands/hatch.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync } from "fs";
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync } from "fs";
 import { homedir, userInfo } from "os";
 import { join } from "path";
 
@@ -6,7 +6,7 @@ import { join } from "path";
 import cliPkg from "../../package.json";
 
 import { buildOpenclawStartupScript } from "../adapters/openclaw";
-import { loadAllAssistants, saveAssistantEntry } from "../lib/assistant-config";
+import { loadAllAssistants, saveAssistantEntry, syncConfigToLockfile } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import { hatchAws } from "../lib/aws";
 import {
@@ -392,12 +392,11 @@ function watchHatchingDesktop(
   });
 }
 
-function installCLISymlink(): void {
-  const cliBinary = process.execPath;
-  if (!cliBinary || !existsSync(cliBinary)) return;
-
-  const symlinkPath = "/usr/local/bin/vellum";
-
+/**
+ * Attempts to place a symlink at the given path pointing to cliBinary.
+ * Returns true if the symlink was created (or already correct), false on failure.
+ */
+function trySymlink(cliBinary: string, symlinkPath: string): boolean {
   try {
     // Use lstatSync (not existsSync) to detect dangling symlinks —
     // existsSync follows symlinks and returns false for broken links.
@@ -405,30 +404,80 @@ function installCLISymlink(): void {
       const stats = lstatSync(symlinkPath);
       if (!stats.isSymbolicLink()) {
         // Real file — don't overwrite (developer's local install)
-        return;
+        return false;
       }
       // Already a symlink — skip if it already points to our binary
       const dest = readlinkSync(symlinkPath);
-      if (dest === cliBinary) return;
+      if (dest === cliBinary) return true;
       // Stale or dangling symlink — remove before creating new one
       unlinkSync(symlinkPath);
     } catch (e) {
-      if ((e as NodeJS.ErrnoException)?.code !== "ENOENT") throw e;
+      if ((e as NodeJS.ErrnoException)?.code !== "ENOENT") return false;
       // Path doesn't exist — proceed to create symlink
     }
 
-    const dir = "/usr/local/bin";
+    const dir = join(symlinkPath, "..");
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
     }
     symlinkSync(cliBinary, symlinkPath);
-    console.log(`   Symlinked ${symlinkPath} → ${cliBinary}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensures ~/.local/bin is present in the user's shell profile so that
+ * symlinks placed there are on PATH in new terminal sessions.
+ */
+function ensureLocalBinInShellProfile(localBinDir: string): void {
+  const shell = process.env.SHELL ?? "";
+  const home = homedir();
+  // Determine the appropriate shell profile to modify
+  const profilePath = shell.endsWith("/zsh")
+    ? join(home, ".zshrc")
+    : shell.endsWith("/bash")
+      ? join(home, ".bash_profile")
+      : null;
+  if (!profilePath) return;
+
+  try {
+    const contents = existsSync(profilePath) ? readFileSync(profilePath, "utf-8") : "";
+    // Check if ~/.local/bin is already referenced in PATH exports
+    if (contents.includes(localBinDir)) return;
+    const line = `\nexport PATH="${localBinDir}:\$PATH"\n`;
+    appendFileSync(profilePath, line);
+    console.log(`   Added ${localBinDir} to ${profilePath}`);
   } catch {
-    // Permission denied or other error — not critical
-    console.log(`   ⚠ Could not create symlink at ${symlinkPath} (run with sudo or create manually)`);
+    // Not critical — user can add it manually
   }
 }
 
+function installCLISymlink(): void {
+  const cliBinary = process.execPath;
+  if (!cliBinary || !existsSync(cliBinary)) return;
+
+  // Preferred location — works on most Macs where /usr/local/bin exists
+  const preferredPath = "/usr/local/bin/vellum";
+  if (trySymlink(cliBinary, preferredPath)) {
+    console.log(`   Symlinked ${preferredPath} → ${cliBinary}`);
+    return;
+  }
+
+  // Fallback — use ~/.local/bin which is user-writable and doesn't need root.
+  // On some Macs /usr/local doesn't exist and creating it requires admin privileges.
+  const localBinDir = join(homedir(), ".local", "bin");
+  const fallbackPath = join(localBinDir, "vellum");
+  if (trySymlink(cliBinary, fallbackPath)) {
+    console.log(`   Symlinked ${fallbackPath} → ${cliBinary}`);
+    ensureLocalBinInShellProfile(localBinDir);
+    return;
+  }
+
+  console.log(`   ⚠ Could not create symlink for vellum CLI (tried ${preferredPath} and ${fallbackPath})`);
+}
+
 async function hatchLocal(species: Species, name: string | null, daemonOnly: boolean = false): Promise<void> {
   const instanceName =
     name ?? process.env.VELLUM_ASSISTANT_NAME ?? `${species}-${generateRandomSuffix()}`;
@@ -487,6 +536,7 @@ async function hatchLocal(species: Species, name: string | null, daemonOnly: boo
   };
   if (!daemonOnly) {
     saveAssistantEntry(localEntry);
+    syncConfigToLockfile();
 
     if (process.env.VELLUM_DESKTOP_APP) {
       installCLISymlink();

package/src/commands/ps.ts

@@ -7,10 +7,16 @@ import {
   loadAllAssistants,
   type AssistantEntry,
 } from "../lib/assistant-config";
+import { GATEWAY_PORT } from "../lib/constants";
 import { checkHealth } from "../lib/health-check";
+import { pgrepExact } from "../lib/pgrep";
+import { probePort } from "../lib/port-probe";
 import { withStatusEmoji } from "../lib/status-emoji";
 import { execOutput } from "../lib/step-runner";
 
+const RUNTIME_HTTP_PORT = Number(process.env.RUNTIME_HTTP_PORT) || 7821;
+const QDRANT_PORT = 6333;
+
 // ── Table formatting helpers ────────────────────────────────────
 
 interface TableRow {
@@ -149,62 +155,86 @@ async function getRemoteProcessesCustom(
   ]);
 }
 
-function checkPidFile(pidFile: string): { status: string; pid: string | null } {
-  if (!existsSync(pidFile)) {
-    return { status: "not running", pid: null };
-  }
+interface ProcessSpec {
+  name: string;
+  pgrepName: string;
+  port: number;
+  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 { status: "running", pid };
+    return true;
   } catch {
-    return { status: "not running", pid };
+    return false;
   }
 }
 
-async function getLocalProcesses(entry: AssistantEntry): Promise<TableRow[]> {
-  const vellumDir = entry.baseDataDir ?? join(homedir(), ".vellum");
-  const rows: TableRow[] = [];
-
-  // Check daemon PID
-  const daemon = checkPidFile(join(vellumDir, "vellum.pid"));
-  rows.push({
-    name: "daemon",
-    status: withStatusEmoji(daemon.status),
-    info: daemon.pid ? `PID ${daemon.pid}` : "no PID file",
-  });
+interface DetectedProcess {
+  name: string;
+  pid: string | null;
+  port: number;
+  running: boolean;
+}
 
-  // Check qdrant PID
-  const qdrant = checkPidFile(join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid"));
-  rows.push({
-    name: "qdrant",
-    status: withStatusEmoji(qdrant.status),
-    info: qdrant.pid ? `PID ${qdrant.pid} | port 6333` : "no PID file",
-  });
+async function detectProcess(spec: ProcessSpec): Promise<DetectedProcess> {
+  // Tier 1: pgrep by process title
+  const pids = await pgrepExact(spec.pgrepName);
+  if (pids.length > 0) {
+    return { name: spec.name, pid: pids[0], port: spec.port, running: true };
+  }
 
-  // Check gateway PID
-  const gateway = checkPidFile(join(vellumDir, "gateway.pid"));
-  rows.push({
-    name: "gateway",
-    status: withStatusEmoji(gateway.status),
-    info: gateway.pid ? `PID ${gateway.pid} | port 7830` : "no PID file",
-  });
+  // Tier 2: TCP port probe
+  const listening = await probePort(spec.port);
+  if (listening) {
+    const filePid = readPidFile(spec.pidFile);
+    return {
+      name: spec.name,
+      pid: filePid,
+      port: spec.port,
+      running: true,
+    };
+  }
 
-  // If no PID files found, fall back to health check
-  const allMissingPid = !daemon.pid && !qdrant.pid && !gateway.pid;
-  if (allMissingPid) {
-    const health = await checkHealth(entry.runtimeUrl);
-    if (health.status === "healthy" || health.status === "ok") {
-      rows.length = 0;
-      rows.push({
-        name: "daemon",
-        status: withStatusEmoji("running"),
-        info: "no PID file (detected via health check)",
-      });
-    }
+  // Tier 3: PID file fallback
+  const filePid = readPidFile(spec.pidFile);
+  if (filePid && isProcessAlive(filePid)) {
+    return { name: spec.name, pid: filePid, port: spec.port, running: true };
   }
 
-  return rows;
+  return { name: spec.name, pid: null, port: spec.port, running: false };
+}
+
+function formatDetectionInfo(proc: DetectedProcess): string {
+  const parts: string[] = [];
+  if (proc.pid) parts.push(`PID ${proc.pid}`);
+  parts.push(`port ${proc.port}`);
+  return parts.join(" | ");
+}
+
+async function getLocalProcesses(entry: AssistantEntry): Promise<TableRow[]> {
+  const vellumDir = entry.baseDataDir ?? join(homedir(), ".vellum");
+
+  const specs: ProcessSpec[] = [
+    { name: "daemon", pgrepName: "vellum-daemon", port: RUNTIME_HTTP_PORT, pidFile: join(vellumDir, "vellum.pid") },
+    { name: "qdrant", pgrepName: "qdrant", port: QDRANT_PORT, pidFile: join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid") },
+    { name: "gateway", pgrepName: "vellum-gateway", port: GATEWAY_PORT, pidFile: join(vellumDir, "gateway.pid") },
+  ];
+
+  const results = await Promise.all(specs.map(detectProcess));
+
+  return results.map((proc) => ({
+    name: proc.name,
+    status: withStatusEmoji(proc.running ? "running" : "not running"),
+    info: proc.running ? formatDetectionInfo(proc) : "not detected",
+  }));
 }
 
 async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
@@ -270,10 +300,10 @@ async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
   ];
 
   for (const { file, name } of pidFiles) {
-    const result = checkPidFile(file);
-    if (result.status === "running" && result.pid) {
-      results.push({ name, pid: result.pid, source: "pid file" });
-      seenPids.add(result.pid);
+    const pid = readPidFile(file);
+    if (pid && isProcessAlive(pid)) {
+      results.push({ name, pid, source: "pid file" });
+      seenPids.add(pid);
     }
   }
 

package/src/components/DefaultMainScreen.tsx

@@ -11,6 +11,7 @@ import { callDoctorDaemon, type ChatLogEntry } from "../lib/doctor-client";
 import { checkHealth } from "../lib/health-check";
 import { statusEmoji, withStatusEmoji } from "../lib/status-emoji";
 import TextInput from "./TextInput";
+import { Tooltip } from "./Tooltip";
 
 export const ANSI = {
   reset: "\x1b[0m",
@@ -682,7 +683,9 @@ function DefaultMainScreen({
       </Box>
       <Text dimColor>{"─".repeat(totalWidth)}</Text>
       <Text> </Text>
-      <Text dimColor> ? for shortcuts</Text>
+      <Tooltip text="Type ? or /help for available commands" delay={1000}>
+        <Text dimColor> ? for shortcuts</Text>
+      </Tooltip>
       <Text> </Text>
     </Box>
   );
@@ -841,7 +844,7 @@ function SelectionWindow({
         );
       })}
       <Text>{"\u2514" + "\u2500".repeat(windowWidth - 2) + "\u2518"}</Text>
-      <Text dimColor>{"  \u2191/\u2193 navigate  Enter select  Esc cancel"}</Text>
+      <Tooltip text="\u2191/\u2193 navigate  Enter select  Esc cancel" delay={1000} />
     </Box>
   );
 }
@@ -901,7 +904,7 @@ function SecretInputWindow({
         {"\u2502"}
       </Text>
       <Text>{"\u2514" + "\u2500".repeat(windowWidth - 2) + "\u2518"}</Text>
-      <Text dimColor>{"  Enter submit  Esc cancel"}</Text>
+      <Tooltip text="Enter submit  Esc cancel" delay={1000} />
     </Box>
   );
 }
@@ -984,13 +987,16 @@ function ChatApp({
   const terminalRows = stdout.rows || 24;
   const terminalColumns = stdout.columns || 80;
   const headerHeight = calculateHeaderHeight(species);
+  const tooltipBubbleHeight = 3;
+  const showTooltip = inputFocused && inputValue.length === 0;
+  const tooltipHeight = showTooltip ? tooltipBubbleHeight : 0;
   const bottomHeight = selection
-    ? selection.options.length + 3
+    ? selection.options.length + 3 + tooltipBubbleHeight
     : secretInput
-      ? 5
+      ? 5 + tooltipBubbleHeight
       : spinnerText
         ? 4
-        : 3;
+        : 3 + tooltipHeight;
   const availableRows = Math.max(3, terminalRows - headerHeight - bottomHeight);
 
   const addMessage = useCallback((msg: RuntimeMessage) => {
@@ -1814,6 +1820,12 @@ function ChatApp({
 
       {!selection && !secretInput ? (
         <Box flexDirection="column">
+          <Tooltip
+            text="Type a message or /help for commands"
+            visible={inputFocused && inputValue.length === 0}
+            position="above"
+            delay={1000}
+          />
           <Text dimColor>{"\u2500".repeat(terminalColumns)}</Text>
           <Box paddingLeft={1}>
             <Text color="green" bold>

package/src/components/Tooltip.tsx

@@ -0,0 +1,66 @@
+import { useEffect, useState, type ReactElement, type ReactNode } from "react";
+import { Box, Text } from "ink";
+
+export interface TooltipProps {
+  /** The tooltip text to display */
+  text: string;
+  /** Whether the tooltip trigger condition is active. When true, starts the delay timer. */
+  visible?: boolean;
+  /** Position relative to children: "above" or "below" */
+  position?: "above" | "below";
+  /** Delay in ms before showing the tooltip (default: 1000) */
+  delay?: number;
+  /** Children to wrap */
+  children?: ReactNode;
+}
+
+/**
+ * A Codex-style tooltip component for Ink terminal UI.
+ *
+ * Wraps children and shows a styled tooltip bubble (rounded border, bold text)
+ * after a configurable delay when `visible` is true.
+ *
+ * Usage:
+ *   <Tooltip text="Attach files" visible={isFocused}>
+ *     <Text>📎</Text>
+ *   </Tooltip>
+ */
+export function Tooltip({
+  text,
+  visible = true,
+  position = "below",
+  delay = 1000,
+  children,
+}: TooltipProps): ReactElement | null {
+  const [show, setShow] = useState(false);
+
+  useEffect(() => {
+    if (!visible) {
+      setShow(false);
+      return;
+    }
+
+    const timer = setTimeout(() => setShow(true), delay);
+    return () => clearTimeout(timer);
+  }, [visible, delay]);
+
+  const bubble = show ? (
+    <Box borderStyle="round" borderColor="gray" alignSelf="flex-start">
+      <Text bold> {text} </Text>
+    </Box>
+  ) : null;
+
+  if (!children) {
+    return bubble ?? null;
+  }
+
+  return (
+    <Box flexDirection="column">
+      {position === "above" && bubble}
+      {children}
+      {position === "below" && bubble}
+    </Box>
+  );
+}
+
+export default Tooltip;

package/src/lib/assistant-config.ts

@@ -20,6 +20,7 @@ export interface AssistantEntry {
 
 interface LockfileData {
   assistants?: AssistantEntry[];
+  platformBaseUrl?: string;
   [key: string]: unknown;
 }
 
@@ -102,3 +103,23 @@ export function saveAssistantEntry(entry: AssistantEntry): void {
   entries.unshift(entry);
   writeAssistants(entries);
 }
+
+/**
+ * Read the assistant config file and sync client-relevant values to the
+ * lockfile. This lets external tools (e.g. vel) discover the platform URL
+ * without importing the assistant config schema.
+ */
+export function syncConfigToLockfile(): void {
+  const configPath = join(getBaseDir(), ".vellum", "workspace", "config.json");
+  if (!existsSync(configPath)) return;
+
+  try {
+    const raw = JSON.parse(readFileSync(configPath, "utf-8")) as Record<string, unknown>;
+    const platform = raw.platform as Record<string, unknown> | undefined;
+    const data = readLockfile();
+    data.platformBaseUrl = (platform?.baseUrl as string) || undefined;
+    writeLockfile(data);
+  } catch {
+    // Config file unreadable — skip sync
+  }
+}

package/src/lib/local.ts

@@ -1,6 +1,7 @@
-import { spawn } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { createRequire } from "module";
+import { createConnection } from "net";
 import { homedir } from "os";
 import { dirname, join } from "path";
 
@@ -10,6 +11,35 @@ import { stopProcessByPidFile } from "./process.js";
 
 const _require = createRequire(import.meta.url);
 
+function isAssistantSourceDir(dir: string): boolean {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath) || !existsSync(join(dir, "src", "index.ts"))) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.name === "@vellumai/assistant";
+  } catch {
+    return false;
+  }
+}
+
+function findAssistantSourceFrom(startDir: string): string | undefined {
+  let current = startDir;
+  while (true) {
+    if (isAssistantSourceDir(current)) {
+      return current;
+    }
+    const nestedCandidate = join(current, "assistant");
+    if (isAssistantSourceDir(nestedCandidate)) {
+      return nestedCandidate;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+}
+
 function isGatewaySourceDir(dir: string): boolean {
   const pkgPath = join(dir, "package.json");
   if (!existsSync(pkgPath) || !existsSync(join(dir, "src", "index.ts"))) return false;
@@ -39,6 +69,83 @@ function findGatewaySourceFromCwd(): string | undefined {
   }
 }
 
+function resolveAssistantIndexPath(): string | undefined {
+  // Source tree layout: cli/src/lib/ -> ../../.. -> repo root -> assistant/src/index.ts
+  const sourceTreeIndex = join(import.meta.dir, "..", "..", "..", "assistant", "src", "index.ts");
+  if (existsSync(sourceTreeIndex)) {
+    return sourceTreeIndex;
+  }
+
+  // bunx layout: @vellumai/cli/src/lib/ -> ../../../.. -> node_modules/vellum/src/index.ts
+  const bunxIndex = join(import.meta.dir, "..", "..", "..", "..", "vellum", "src", "index.ts");
+  if (existsSync(bunxIndex)) {
+    return bunxIndex;
+  }
+
+  const cwdSourceDir = findAssistantSourceFrom(process.cwd());
+  if (cwdSourceDir) {
+    return join(cwdSourceDir, "src", "index.ts");
+  }
+
+  const execSourceDir = findAssistantSourceFrom(dirname(process.execPath));
+  if (execSourceDir) {
+    return join(execSourceDir, "src", "index.ts");
+  }
+
+  try {
+    const vellumPkgPath = _require.resolve("vellum/package.json");
+    const resolved = join(dirname(vellumPkgPath), "src", "index.ts");
+    if (existsSync(resolved)) {
+      return resolved;
+    }
+  } catch {
+    // resolution failed
+  }
+
+  return undefined;
+}
+
+async function waitForSocketFile(socketPath: string, timeoutMs = 15000): Promise<boolean> {
+  if (existsSync(socketPath)) return true;
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(socketPath)) {
+      return true;
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+
+  return existsSync(socketPath);
+}
+
+async function startDaemonFromSource(assistantIndex: string): Promise<void> {
+  const env: Record<string, string | undefined> = {
+    ...process.env,
+    RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
+  };
+  // Preserve TCP listener flag when falling back from bundled desktop daemon
+  if (process.env.VELLUM_DESKTOP_APP) {
+    env.VELLUM_DAEMON_TCP_ENABLED = process.env.VELLUM_DAEMON_TCP_ENABLED || "1";
+  }
+
+  const child = spawn("bun", ["run", assistantIndex, "daemon", "start"], {
+    stdio: "inherit",
+    env,
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Daemon start exited with code ${code}`));
+      }
+    });
+    child.on("error", reject);
+  });
+}
+
 function resolveGatewayDir(): string {
   const override = process.env.VELLUM_GATEWAY_DIR?.trim();
   if (override) {
@@ -95,6 +202,51 @@ function readWorkspaceIngressPublicBaseUrl(): string | undefined {
   }
 }
 
+/** Use lsof to discover the PID of the process listening on a Unix socket.
+ *  Returns the PID if found, undefined otherwise. */
+function findSocketOwnerPid(socketPath: string): number | undefined {
+  try {
+    const output = execFileSync("lsof", ["-U", "-a", "-F", "p", "--", socketPath], {
+      encoding: "utf-8",
+      timeout: 3000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    // lsof -F p outputs lines like "p1234" — extract the first PID
+    const match = output.match(/^p(\d+)/m);
+    if (match) {
+      const pid = parseInt(match[1], 10);
+      if (!isNaN(pid)) return pid;
+    }
+  } catch {
+    // lsof not available or failed — cannot recover PID
+  }
+  return undefined;
+}
+
+/** Try a TCP connect to the Unix socket. Returns true if the handshake
+ *  completes within the timeout — false on connection refused, timeout,
+ *  or missing socket file. */
+function isSocketResponsive(socketPath: string, timeoutMs = 1500): Promise<boolean> {
+  if (!existsSync(socketPath)) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const socket = createConnection(socketPath);
+    const timer = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, timeoutMs);
+    socket.on("connect", () => {
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(true);
+    });
+    socket.on("error", () => {
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
 async function discoverPublicUrl(): Promise<string | undefined> {
   const cloud = process.env.VELLUM_CLOUD;
   if (!cloud || cloud === "local") {
@@ -172,7 +324,23 @@ export async function startLocalDaemon(): Promise<void> {
     }
 
     if (!daemonAlive) {
-      // Remove stale socket so we can detect the fresh one
+      // The PID file was stale or missing, but a daemon with a different PID
+      // may still be listening on the socket (e.g. if the PID file was
+      // overwritten by a crashed restart attempt). Check before deleting.
+      if (await isSocketResponsive(socketFile)) {
+        // Restore PID tracking so lifecycle commands (sleep, retire,
+        // stopLocalProcesses) can manage this daemon process.
+        const ownerPid = findSocketOwnerPid(socketFile);
+        if (ownerPid) {
+          writeFileSync(pidFile, String(ownerPid), "utf-8");
+          console.log(`   Daemon socket is responsive (pid ${ownerPid}) — skipping restart\n`);
+        } else {
+          console.log("   Daemon socket is responsive — skipping restart\n");
+        }
+        return;
+      }
+
+      // Socket is unresponsive or missing — safe to clean up and start fresh.
       try { unlinkSync(socketFile); } catch {}
 
       console.log("🔨 Starting daemon...");
@@ -223,17 +391,22 @@ export async function startLocalDaemon(): Promise<void> {
     }
 
     // Wait for socket at ~/.vellum/vellum.sock (up to 15s)
-    if (!existsSync(socketFile)) {
-      const maxWait = 15000;
-      const start = Date.now();
-      while (Date.now() - start < maxWait) {
-        if (existsSync(socketFile)) {
-          break;
-        }
-        await new Promise((r) => setTimeout(r, 100));
+    let socketReady = await waitForSocketFile(socketFile, 15000);
+
+    // Dev fallback: if the bundled daemon did not create a socket in time,
+    // fall back to source daemon startup so local `./build.sh run` still works.
+    if (!socketReady) {
+      const assistantIndex = resolveAssistantIndexPath();
+      if (assistantIndex) {
+        console.log("   Bundled daemon socket not ready after 15s — falling back to source daemon...");
+        // Kill the bundled daemon to avoid two processes competing for the same socket/port
+        await stopProcessByPidFile(pidFile, "bundled daemon", [socketFile]);
+        await startDaemonFromSource(assistantIndex);
+        socketReady = await waitForSocketFile(socketFile, 15000);
       }
     }
-    if (existsSync(socketFile)) {
+
+    if (socketReady) {
       console.log("   Daemon socket ready\n");
     } else {
       console.log("   ⚠️  Daemon socket did not appear within 15s — continuing anyway\n");
@@ -241,50 +414,14 @@ export async function startLocalDaemon(): Promise<void> {
   } else {
     console.log("🔨 Starting local daemon...");
 
-    // Source tree layout: cli/src/commands/ -> ../../.. -> repo root -> assistant/src/index.ts
-    const sourceTreeIndex = join(import.meta.dir, "..", "..", "..", "assistant", "src", "index.ts");
-    // bunx layout: @vellumai/cli/src/commands/ -> ../../../.. -> node_modules/ -> vellum/src/index.ts
-    const bunxIndex = join(import.meta.dir, "..", "..", "..", "..", "vellum", "src", "index.ts");
-    let assistantIndex = sourceTreeIndex;
-
-    if (!existsSync(assistantIndex)) {
-      assistantIndex = bunxIndex;
-    }
-
-    if (!existsSync(assistantIndex)) {
-      try {
-        const vellumPkgPath = _require.resolve("vellum/package.json");
-        assistantIndex = join(dirname(vellumPkgPath), "src", "index.ts");
-      } catch {
-        // resolve failed, will fall through to existsSync check below
-      }
-    }
-
-    if (!existsSync(assistantIndex)) {
+    const assistantIndex = resolveAssistantIndexPath();
+    if (!assistantIndex) {
       throw new Error(
         "vellum-daemon binary not found and assistant source not available.\n" +
           "  Ensure the daemon binary is bundled alongside the CLI, or run from the source tree.",
       );
     }
-
-    const child = spawn("bun", ["run", assistantIndex, "daemon", "start"], {
-      stdio: "inherit",
-      env: {
-        ...process.env,
-        RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
-      },
-    });
-
-    await new Promise<void>((resolve, reject) => {
-      child.on("close", (code) => {
-        if (code === 0) {
-          resolve();
-        } else {
-          reject(new Error(`Daemon start exited with code ${code}`));
-        }
-      });
-      child.on("error", reject);
-    });
+    await startDaemonFromSource(assistantIndex);
   }
 }
 

package/src/lib/pgrep.ts

@@ -0,0 +1,10 @@
+import { execOutput } from "./step-runner";
+
+export async function pgrepExact(name: string): Promise<string[]> {
+  try {
+    const output = await execOutput("pgrep", ["-x", name]);
+    return output.trim().split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/src/lib/port-probe.ts

@@ -0,0 +1,23 @@
+import { Socket } from "node:net";
+
+const PROBE_TIMEOUT_MS = 750;
+
+export function probePort(port: number, host = "127.0.0.1"): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new Socket();
+    socket.setTimeout(PROBE_TIMEOUT_MS);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("timeout", () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.once("error", () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.connect(port, host);
+  });
+}