@vellumai/cli 0.4.42 → 0.4.44

package/src/lib/local.ts

@@ -1,6 +1,5 @@
 import { execFileSync, execSync, spawn } from "child_process";
 import {
-  closeSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -8,16 +7,15 @@ import {
   writeFileSync,
 } from "fs";
 import { createRequire } from "module";
-import { createConnection } from "net";
 import { homedir, hostname, networkInterfaces, platform } from "os";
 import { dirname, join } from "path";
 
 import {
-  defaultLocalResources,
   loadLatestAssistant,
   type LocalInstanceResources,
 } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
+import { httpHealthCheck, waitForDaemonReady } from "./http-client.js";
 import { stopProcessByPidFile } from "./process.js";
 import { openLogFile, pipeToLogFile } from "./xdg-log.js";
 
@@ -136,23 +134,6 @@ function resolveAssistantIndexPath(): string | undefined {
   return undefined;
 }
 
-async function waitForSocketFile(
-  socketPath: string,
-  timeoutMs = 60000,
-): 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);
-}
-
 function ensureBunInstalled(): void {
   const bunBinDir = join(homedir(), ".bun", "bin");
   const pathWithBun = [
@@ -216,18 +197,15 @@ function resolveDaemonMainPath(assistantIndex: string): string {
 
 async function startDaemonFromSource(
   assistantIndex: string,
-  resources?: LocalInstanceResources,
+  resources: LocalInstanceResources,
 ): Promise<void> {
   const daemonMainPath = resolveDaemonMainPath(assistantIndex);
 
-  const defaults = defaultLocalResources();
-  const res = resources ?? defaults;
   // Ensure the directory containing PID/socket files exists. For named
   // instances this is instanceDir/.vellum/ (matching daemon's getRootDir()).
-  mkdirSync(dirname(res.pidFile), { recursive: true });
+  mkdirSync(dirname(resources.pidFile), { recursive: true });
 
-  const pidFile = res.pidFile;
-  const socketFile = res.socketPath;
+  const pidFile = resources.pidFile;
 
   // --- Lifecycle guard: prevent split-brain daemon state ---
   if (existsSync(pidFile)) {
@@ -247,23 +225,21 @@ async function startDaemonFromSource(
     } catch {}
   }
 
-  if (await isSocketResponsive(socketFile)) {
-    const ownerPid = findSocketOwnerPid(socketFile);
-    if (ownerPid) {
-      writeFileSync(pidFile, String(ownerPid), "utf-8");
+  // PID file was stale or missing — check if daemon is responding via HTTP
+  if (await isDaemonResponsive(resources.daemonPort)) {
+    // Recover PID tracking so lifecycle commands (sleep, retire,
+    // stopLocalProcesses) can manage this daemon process.
+    const recoveredPid = recoverPidFile(pidFile, resources.daemonPort);
+    if (recoveredPid) {
       console.log(
-        `   Assistant socket is responsive (pid ${ownerPid}) — skipping restart\n`,
+        `   Assistant is responsive (pid ${recoveredPid}) — skipping restart\n`,
       );
     } else {
-      console.log("   Assistant socket is responsive — skipping restart\n");
+      console.log("   Assistant is responsive — skipping restart\n");
     }
     return;
   }
 
-  try {
-    unlinkSync(socketFile);
-  } catch {}
-
   const env: Record<string, string | undefined> = {
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
@@ -277,21 +253,17 @@ async function startDaemonFromSource(
     env.BASE_DATA_DIR = resources.instanceDir;
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
-    env.VELLUM_DAEMON_SOCKET = resources.socketPath;
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
     delete env.QDRANT_URL;
   }
 
-  // Use fd inheritance instead of pipes so the daemon's stdout/stderr survive
-  // after the parent (hatch) exits. Bun does not ignore SIGPIPE, so piped
-  // stdio would kill the daemon on its first write after the parent closes.
-  const logFd = openLogFile("hatch.log");
+  const daemonLogFd = openLogFile("hatch.log");
   const child = spawn("bun", ["run", daemonMainPath], {
     detached: true,
-    stdio: ["ignore", logFd, logFd],
+    stdio: ["ignore", "pipe", "pipe"],
     env,
   });
-  if (typeof logFd === "number") closeSync(logFd);
+  pipeToLogFile(child, daemonLogFd, "daemon");
   child.unref();
 
   if (child.pid) {
@@ -305,19 +277,16 @@ async function startDaemonFromSource(
 // assistant-side equivalent.
 async function startDaemonWatchFromSource(
   assistantIndex: string,
-  resources?: LocalInstanceResources,
+  resources: LocalInstanceResources,
 ): Promise<void> {
   const mainPath = resolveDaemonMainPath(assistantIndex);
   if (!existsSync(mainPath)) {
     throw new Error(`Daemon main.ts not found at ${mainPath}`);
   }
 
-  const defaults = defaultLocalResources();
-  const res = resources ?? defaults;
-  mkdirSync(dirname(res.pidFile), { recursive: true });
+  mkdirSync(dirname(resources.pidFile), { recursive: true });
 
-  const pidFile = res.pidFile;
-  const socketFile = res.socketPath;
+  const pidFile = resources.pidFile;
 
   // --- Lifecycle guard: prevent split-brain daemon state ---
   // If a daemon is already running, skip spawning a new one.
@@ -339,26 +308,21 @@ async function startDaemonWatchFromSource(
     } catch {}
   }
 
-  // PID file was stale or missing, but a daemon with a different PID may
-  // still be listening on the socket. Check before starting a new one.
-  if (await isSocketResponsive(socketFile)) {
-    const ownerPid = findSocketOwnerPid(socketFile);
-    if (ownerPid) {
-      writeFileSync(pidFile, String(ownerPid), "utf-8");
+  // PID file was stale or missing — check if daemon is responding via HTTP
+  if (await isDaemonResponsive(resources.daemonPort)) {
+    // Recover PID tracking so lifecycle commands (sleep, retire,
+    // stopLocalProcesses) can manage this daemon process.
+    const recoveredPid = recoverPidFile(pidFile, resources.daemonPort);
+    if (recoveredPid) {
       console.log(
-        `   Assistant socket is responsive (pid ${ownerPid}) — skipping restart\n`,
+        `   Assistant is responsive (pid ${recoveredPid}) — skipping restart\n`,
       );
     } else {
-      console.log("   Assistant socket is responsive — skipping restart\n");
+      console.log("   Assistant is responsive — skipping restart\n");
     }
     return;
   }
 
-  // Socket is unresponsive or missing — safe to clean up and start fresh.
-  try {
-    unlinkSync(socketFile);
-  } catch {}
-
   const env: Record<string, string | undefined> = {
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
@@ -368,7 +332,6 @@ async function startDaemonWatchFromSource(
     env.BASE_DATA_DIR = resources.instanceDir;
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
-    env.VELLUM_DAEMON_SOCKET = resources.socketPath;
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
     delete env.QDRANT_URL;
   }
@@ -457,59 +420,57 @@ function readWorkspaceIngressPublicBaseUrl(
   }
 }
 
-/** 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 {
+/**
+ * Check if the daemon is responsive by hitting its HTTP `/healthz` endpoint.
+ * This replaces the socket-based `isSocketResponsive()` check.
+ */
+async function isDaemonResponsive(daemonPort: number): Promise<boolean> {
+  return httpHealthCheck(daemonPort);
+}
+
+/**
+ * Find the PID of the process listening on the given TCP port.
+ * Uses `lsof` on macOS/Linux. Returns undefined if no listener is found
+ * or the command fails.
+ */
+function findPidListeningOnPort(port: number): 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;
-    }
+      ["-iTCP:" + port, "-sTCP:LISTEN", "-t"],
+      { encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] },
+    ).trim();
+    // lsof -t may return multiple PIDs (one per line); take the first.
+    const pid = parseInt(output.split("\n")[0], 10);
+    return isNaN(pid) ? undefined : pid;
   } catch {
-    // lsof not available or failed — cannot recover PID
+    return undefined;
   }
-  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);
-    });
-  });
+/**
+ * Recover PID tracking for a daemon that is already responsive on its HTTP
+ * port but whose PID file is stale or missing. Looks up the listener PID
+ * via `lsof` and writes it to `pidFile` so lifecycle commands (sleep, retire,
+ * wake) can target the running process.
+ *
+ * Returns the recovered PID, or undefined if recovery failed.
+ */
+function recoverPidFile(
+  pidFile: string,
+  daemonPort: number,
+): number | undefined {
+  const pid = findPidListeningOnPort(daemonPort);
+  if (pid) {
+    mkdirSync(dirname(pidFile), { recursive: true });
+    writeFileSync(pidFile, String(pid), "utf-8");
+  }
+  return pid;
 }
 
-async function discoverPublicUrl(port?: number): Promise<string | undefined> {
+export async function discoverPublicUrl(
+  port?: number,
+): Promise<string | undefined> {
   const effectivePort = port ?? GATEWAY_PORT;
   const cloud = process.env.VELLUM_CLOUD;
 
@@ -577,7 +538,7 @@ async function discoverPublicUrl(port?: number): Promise<string | undefined> {
  * Returns the macOS Bonjour/mDNS `.local` hostname (e.g. "Vargass-Mac-Mini.local"),
  * or undefined if not running on macOS or the hostname cannot be determined.
  */
-function getMacLocalHostname(): string | undefined {
+export function getMacLocalHostname(): string | undefined {
   const host = hostname();
   if (!host) return undefined;
   // macOS hostnames already end with .local when Bonjour is active
@@ -598,7 +559,7 @@ function getMacLocalHostname(): string | undefined {
  * Skips link-local addresses (169.254.x.x) and IPv6.
  * Returns undefined if no suitable address is found.
  */
-function getLocalLanIPv4(): string | undefined {
+export function getLocalLanIPv4(): string | undefined {
   const ifaces = networkInterfaces();
 
   // Priority interfaces in order
@@ -641,7 +602,7 @@ function getLocalLanIPv4(): string | undefined {
 // assistant-side equivalent.
 export async function startLocalDaemon(
   watch: boolean = false,
-  resources?: LocalInstanceResources,
+  resources: LocalInstanceResources,
 ): Promise<void> {
   if (process.env.VELLUM_DESKTOP_APP && !watch) {
     // When running inside the desktop app, the CLI owns the daemon lifecycle.
@@ -656,10 +617,7 @@ export async function startLocalDaemon(
       );
     }
 
-    const defaults = defaultLocalResources();
-    const res = resources ?? defaults;
-    const pidFile = res.pidFile;
-    const socketFile = res.socketPath;
+    const pidFile = resources.pidFile;
 
     // If a daemon is already running, skip spawning a new one.
     // This prevents cascading kill→restart cycles when multiple callers
@@ -685,19 +643,18 @@ export async function startLocalDaemon(
 
     if (!daemonAlive) {
       // 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)) {
+      // may still be listening on the HTTP port (e.g. if the PID file was
+      // overwritten by a crashed restart attempt). Check before starting a new one.
+      if (await isDaemonResponsive(resources.daemonPort)) {
         // 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");
+        const recoveredPid = recoverPidFile(pidFile, resources.daemonPort);
+        if (recoveredPid) {
           console.log(
-            `   Assistant socket is responsive (pid ${ownerPid}) — skipping restart\n`,
+            `   Assistant is responsive (pid ${recoveredPid}) — skipping restart\n`,
           );
         } else {
-          console.log("   Assistant socket is responsive — skipping restart\n");
+          console.log("   Assistant is responsive — skipping restart\n");
         }
         // Ensure bun is available for runtime features (browser, skills install)
         // even when reusing an existing daemon.
@@ -705,17 +662,12 @@ export async function startLocalDaemon(
         return;
       }
 
-      // Socket is unresponsive or missing — safe to clean up and start fresh.
-      try {
-        unlinkSync(socketFile);
-      } catch {}
-
       console.log("🔨 Starting assistant...");
 
       // Ensure bun is available for runtime features (browser, skills install)
       ensureBunInstalled();
 
-      // Ensure the directory containing PID/socket files exists
+      // Ensure the directory containing PID files exists
       mkdirSync(dirname(pidFile), { recursive: true });
 
       // Build a minimal environment for the daemon. When launched from the
@@ -739,7 +691,6 @@ export async function startLocalDaemon(
         "RUNTIME_HTTP_PORT",
         "VELLUM_DAEMON_TCP_PORT",
         "VELLUM_DAEMON_TCP_HOST",
-        "VELLUM_DAEMON_SOCKET",
         "VELLUM_KEYCHAIN_BROKER_SOCKET",
         "VELLUM_DEBUG",
         "SENTRY_DSN",
@@ -757,23 +708,18 @@ export async function startLocalDaemon(
         daemonEnv.BASE_DATA_DIR = resources.instanceDir;
         daemonEnv.RUNTIME_HTTP_PORT = String(resources.daemonPort);
         daemonEnv.GATEWAY_PORT = String(resources.gatewayPort);
-        daemonEnv.VELLUM_DAEMON_SOCKET = resources.socketPath;
         daemonEnv.QDRANT_HTTP_PORT = String(resources.qdrantPort);
         delete daemonEnv.QDRANT_URL;
       }
 
-      // Use fd inheritance instead of pipes so the daemon's stdout/stderr
-      // survive after the parent (hatch) exits. Bun does not ignore SIGPIPE,
-      // so piped stdio would kill the daemon on its first write after the
-      // parent closes.
       const daemonLogFd = openLogFile("hatch.log");
       const child = spawn(daemonBinary, [], {
         cwd: dirname(daemonBinary),
         detached: true,
-        stdio: ["ignore", daemonLogFd, daemonLogFd],
+        stdio: ["ignore", "pipe", "pipe"],
         env: daemonEnv,
       });
-      if (typeof daemonLogFd === "number") closeSync(daemonLogFd);
+      pipeToLogFile(child, daemonLogFd, "daemon");
       child.unref();
       const daemonPid = child.pid;
 
@@ -791,34 +737,34 @@ export async function startLocalDaemon(
       ensureBunInstalled();
     }
 
-    // Wait for socket at ~/.vellum/vellum.sock (up to 60s — fresh installs
+    // Wait for daemon to respond on HTTP (up to 60s — fresh installs
     // may need 30-60s for Qdrant download, migrations, and first-time init)
-    let socketReady = await waitForSocketFile(socketFile, 60000);
+    let daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
 
-    // Dev fallback: if the bundled daemon did not create a socket in time,
+    // Dev fallback: if the bundled daemon did not become ready in time,
     // fall back to source daemon startup so local `./build.sh run` still works.
-    if (!socketReady) {
+    if (!daemonReady) {
       const assistantIndex = resolveAssistantIndexPath();
       if (assistantIndex) {
         console.log(
-          "   Bundled assistant socket not ready after 60s — falling back to source assistant...",
+          "   Bundled assistant not ready after 60s — falling back to source assistant...",
         );
-        // Kill the bundled daemon to avoid two processes competing for the same socket/port
-        await stopProcessByPidFile(pidFile, "bundled daemon", [socketFile]);
+        // Kill the bundled daemon to avoid two processes competing for the same port
+        await stopProcessByPidFile(pidFile, "bundled daemon");
         if (watch) {
           await startDaemonWatchFromSource(assistantIndex, resources);
         } else {
           await startDaemonFromSource(assistantIndex, resources);
         }
-        socketReady = await waitForSocketFile(socketFile, 60000);
+        daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
       }
     }
 
-    if (socketReady) {
-      console.log("   Assistant socket ready\n");
+    if (daemonReady) {
+      console.log("   Assistant ready\n");
     } else {
       console.log(
-        "   ⚠️  Assistant socket did not appear within 60s — continuing anyway\n",
+        "   ⚠️  Assistant did not become ready within 60s — continuing anyway\n",
       );
     }
   } else {
@@ -831,29 +777,26 @@ export async function startLocalDaemon(
           "  Ensure the daemon binary is bundled alongside the CLI, or run from the source tree.",
       );
     }
-    const defaults = defaultLocalResources();
-    const res = resources ?? defaults;
-
     if (watch) {
       await startDaemonWatchFromSource(assistantIndex, resources);
 
-      const socketReady = await waitForSocketFile(res.socketPath, 60000);
-      if (socketReady) {
-        console.log("   Assistant socket ready\n");
+      const daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
+      if (daemonReady) {
+        console.log("   Assistant ready\n");
       } else {
         console.log(
-          "   ⚠️  Assistant socket did not appear within 60s — continuing anyway\n",
+          "   ⚠️  Assistant did not become ready within 60s — continuing anyway\n",
         );
       }
     } else {
       await startDaemonFromSource(assistantIndex, resources);
 
-      const socketReady = await waitForSocketFile(res.socketPath, 60000);
-      if (socketReady) {
-        console.log("   Assistant socket ready\n");
+      const daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
+      if (daemonReady) {
+        console.log("   Assistant ready\n");
       } else {
         console.log(
-          "   ⚠️  Assistant socket did not appear within 60s — continuing anyway\n",
+          "   ⚠️  Assistant did not become ready within 60s — continuing anyway\n",
         );
       }
     }
@@ -867,6 +810,16 @@ export async function startGateway(
 ): Promise<string> {
   const effectiveGatewayPort = resources?.gatewayPort ?? GATEWAY_PORT;
 
+  // Kill any existing gateway process before spawning a new one.
+  // Without this, crashed/stale gateways accumulate as zombies — the old
+  // process holds the port (or lingers after losing it), and every restart
+  // attempt spawns yet another process that fails with EADDRINUSE.
+  const gwPidDir = resources
+    ? join(resources.instanceDir, ".vellum")
+    : join(homedir(), ".vellum");
+  const gwPidFile = join(gwPidDir, "gateway.pid");
+  await stopProcessByPidFile(gwPidFile, "gateway");
+
   const publicUrl = await discoverPublicUrl(effectiveGatewayPort);
   if (publicUrl) {
     console.log(`   Public URL: ${publicUrl}`);
@@ -1003,15 +956,13 @@ export async function startGateway(
       );
     }
 
-    // Use fd inheritance (not pipes) so the gateway survives after the
-    // hatch CLI exits — Bun does not ignore SIGPIPE.
     const gatewayLogFd = openLogFile("hatch.log");
     gateway = spawn(gatewayBinary, [], {
       detached: true,
-      stdio: ["ignore", gatewayLogFd, gatewayLogFd],
+      stdio: ["ignore", "pipe", "pipe"],
       env: gatewayEnv,
     });
-    if (typeof gatewayLogFd === "number") closeSync(gatewayLogFd);
+    pipeToLogFile(gateway, gatewayLogFd, "gateway");
   } else {
     // Source tree / bunx: resolve the gateway source directory and run via bun.
     const gatewayDir = resolveGatewayDir();
@@ -1022,10 +973,10 @@ export async function startGateway(
     gateway = spawn("bun", bunArgs, {
       cwd: gatewayDir,
       detached: true,
-      stdio: ["ignore", gwLogFd, gwLogFd],
+      stdio: ["ignore", "pipe", "pipe"],
       env: gatewayEnv,
     });
-    if (typeof gwLogFd === "number") closeSync(gwLogFd);
+    pipeToLogFile(gateway, gwLogFd, "gateway");
     if (watch) {
       console.log("   Gateway started in watch mode (bun --watch)");
     }
@@ -1078,7 +1029,7 @@ export async function startGateway(
 
 /**
  * Stop any locally-running daemon and gateway processes
- * and clean up PID/socket files. Called when hatch fails partway through
+ * and clean up PID files. Called when hatch fails partway through
  * so we don't leave orphaned processes with no lock file entry.
  *
  * When `resources` is provided, uses instance-specific paths instead of
@@ -1091,8 +1042,7 @@ export async function stopLocalProcesses(
     ? join(resources.instanceDir, ".vellum")
     : join(homedir(), ".vellum");
   const daemonPidFile = resources?.pidFile ?? join(vellumDir, "vellum.pid");
-  const socketFile = resources?.socketPath ?? join(vellumDir, "vellum.sock");
-  await stopProcessByPidFile(daemonPidFile, "daemon", [socketFile]);
+  await stopProcessByPidFile(daemonPidFile, "daemon");
 
   const gatewayPidFile = join(vellumDir, "gateway.pid");
   await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);

package/src/lib/step-runner.ts

@@ -11,6 +11,11 @@ export function exec(
       stdio: ["pipe", "pipe", "pipe"],
     });
 
+    let stdout = "";
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
     let stderr = "";
     child.stderr.on("data", (data: Buffer) => {
       stderr += data.toString();
@@ -21,7 +26,10 @@ export function exec(
         resolve();
       } else {
         const msg = `"${command} ${args.join(" ")}" exited with code ${code}`;
-        reject(new Error(stderr.trim() ? `${msg}\n${stderr.trim()}` : msg));
+        const output = [stderr.trim(), stdout.trim()]
+          .filter(Boolean)
+          .join("\n");
+        reject(new Error(output ? `${msg}\n${output}` : msg));
       }
     });
     child.on("error", reject);

package/src/lib/xdg-log.ts

@@ -1,8 +1,20 @@
-import { closeSync, mkdirSync, openSync, writeSync } from "fs";
 import type { ChildProcess } from "child_process";
+import {
+  closeSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  statSync,
+  writeFileSync,
+  writeSync,
+} from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
+/** Regex matching pino-pretty's short time prefix, e.g. `[12:07:37.467] `. */
+const PINO_TIME_RE = /^\[\d{2}:\d{2}:\d{2}\.\d{3}\]\s*/;
+
 /** Returns the XDG-compatible log directory for Vellum CLI logs. */
 export function getLogDir(): string {
   const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
@@ -23,6 +35,36 @@ export function openLogFile(name: string): number | "ignore" {
   }
 }
 
+/** Truncate (or create) a log file so each session starts fresh. */
+export function resetLogFile(name: string): void {
+  try {
+    const dir = getLogDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, name), "");
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Copy the current log file into `destDir` with a timestamped name so that
+ * previous session logs are preserved for debugging. No-op when the source
+ * file is missing or empty.
+ */
+export function archiveLogFile(name: string, destDir: string): void {
+  try {
+    const srcPath = join(getLogDir(), name);
+    if (!existsSync(srcPath) || statSync(srcPath).size === 0) return;
+
+    mkdirSync(destDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const base = name.replace(/\.log$/, "");
+    copyFileSync(srcPath, join(destDir, `${base}-${ts}.log`));
+  } catch {
+    /* best-effort */
+  }
+}
+
 /** Close a file descriptor returned by openLogFile (no-op for "ignore"). */
 export function closeLogFile(fd: number | "ignore"): void {
   if (typeof fd === "number") {
@@ -46,7 +88,8 @@ export function writeToLogFile(fd: number | "ignore", msg: string): void {
 }
 
 /** Pipe a child process's stdout/stderr to a shared log file descriptor,
- *  prefixing each line with a tag (e.g. "[daemon]" or "[gateway]").
+ *  prefixing each line with an ISO timestamp and tag (e.g. "[daemon]").
+ *  Strips pino-pretty's redundant short time prefix when present.
  *  Streams are unref'd so they don't prevent the parent from exiting.
  *  The fd is closed automatically when both streams end. */
 export function pipeToLogFile(
@@ -80,9 +123,10 @@ export function pipeToLogFile(
       for (let i = 0; i < lines.length; i++) {
         if (i === lines.length - 1 && lines[i] === "") break;
         const nl = i < lines.length - 1 ? "\n" : "";
+        const stripped = lines[i].replace(PINO_TIME_RE, "");
         const prefix = `${new Date().toISOString()} ${tagLabel} `;
         try {
-          writeSync(numFd, prefix + lines[i] + nl);
+          writeSync(numFd, prefix + stripped + nl);
         } catch {
           /* best-effort */
         }