@vellumai/cli 0.4.43 → 0.4.44

package/package.json

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

package/src/__tests__/assistant-config.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeEach, afterAll } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -14,6 +14,7 @@ import {
   loadAllAssistants,
   saveAssistantEntry,
   getActiveAssistant,
+  migrateLegacyEntry,
   type AssistantEntry,
 } from "../lib/assistant-config.js";
 
@@ -180,3 +181,250 @@ describe("assistant-config", () => {
     expect(all[0].assistantId).toBe("valid");
   });
 });
+
+describe("migrateLegacyEntry", () => {
+  test("rewrites baseDataDir as resources.instanceDir", () => {
+    /**
+     * Tests that a legacy entry with top-level baseDataDir gets migrated
+     * to the current resources.instanceDir format.
+     */
+
+    // GIVEN a legacy entry with baseDataDir set at the top level
+    const entry: Record<string, unknown> = {
+      assistantId: "my-assistant",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      baseDataDir: "/home/user/.local/share/vellum/assistants/my-assistant",
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN the entry should be mutated
+    expect(changed).toBe(true);
+
+    // AND baseDataDir should be removed
+    expect(entry.baseDataDir).toBeUndefined();
+
+    // AND resources.instanceDir should contain the old baseDataDir value
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.instanceDir).toBe(
+      "/home/user/.local/share/vellum/assistants/my-assistant",
+    );
+  });
+
+  test("synthesises full resources when none exist", () => {
+    /**
+     * Tests that a legacy local entry with no resources object gets a
+     * complete resources object synthesised with default ports and pidFile.
+     */
+
+    // GIVEN a local entry with no resources
+    const entry: Record<string, unknown> = {
+      assistantId: "old-assistant",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN the entry should be mutated
+    expect(changed).toBe(true);
+
+    // AND resources should be fully populated
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.instanceDir).toContain("old-assistant");
+    expect(resources.daemonPort).toBe(7821);
+    expect(resources.gatewayPort).toBe(7830);
+    expect(resources.qdrantPort).toBe(6333);
+    expect(resources.pidFile).toContain("vellum.pid");
+  });
+
+  test("infers gateway port from runtimeUrl", () => {
+    /**
+     * Tests that the gateway port is extracted from the runtimeUrl when
+     * synthesising resources for a legacy entry.
+     */
+
+    // GIVEN a local entry with a non-default gateway port in the runtimeUrl
+    const entry: Record<string, unknown> = {
+      assistantId: "custom-port",
+      runtimeUrl: "http://localhost:9999",
+      cloud: "local",
+    };
+
+    // WHEN we migrate the entry
+    migrateLegacyEntry(entry);
+
+    // THEN the gateway port should match the runtimeUrl port
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.gatewayPort).toBe(9999);
+  });
+
+  test("skips non-local entries", () => {
+    /**
+     * Tests that remote (non-local) entries are left untouched.
+     */
+
+    // GIVEN a GCP entry without resources
+    const entry: Record<string, unknown> = {
+      assistantId: "gcp-assistant",
+      runtimeUrl: "https://example.com",
+      cloud: "gcp",
+    };
+
+    // WHEN we attempt to migrate it
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN nothing should change
+    expect(changed).toBe(false);
+    expect(entry.resources).toBeUndefined();
+  });
+
+  test("backfills missing fields on partial resources", () => {
+    /**
+     * Tests that an entry with a partial resources object (e.g. only
+     * instanceDir) gets the remaining fields backfilled.
+     */
+
+    // GIVEN an entry with partial resources (only instanceDir)
+    const entry: Record<string, unknown> = {
+      assistantId: "partial",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      resources: {
+        instanceDir: "/custom/path",
+      },
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN the entry should be mutated
+    expect(changed).toBe(true);
+
+    // AND all missing resources fields should be filled in
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.instanceDir).toBe("/custom/path");
+    expect(resources.daemonPort).toBe(7821);
+    expect(resources.gatewayPort).toBe(7830);
+    expect(resources.qdrantPort).toBe(6333);
+    expect(resources.pidFile).toBe("/custom/path/.vellum/vellum.pid");
+  });
+
+  test("does not overwrite existing resources fields", () => {
+    /**
+     * Tests that an entry with a complete resources object is left untouched.
+     */
+
+    // GIVEN an entry with a complete resources object
+    const entry: Record<string, unknown> = {
+      assistantId: "complete",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      resources: {
+        instanceDir: "/my/path",
+        daemonPort: 8000,
+        gatewayPort: 8001,
+        qdrantPort: 8002,
+        pidFile: "/my/path/.vellum/vellum.pid",
+      },
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN nothing should change
+    expect(changed).toBe(false);
+
+    // AND existing values should be preserved
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.daemonPort).toBe(8000);
+    expect(resources.gatewayPort).toBe(8001);
+    expect(resources.qdrantPort).toBe(8002);
+  });
+
+  test("baseDataDir does not overwrite existing resources.instanceDir", () => {
+    /**
+     * Tests that when both baseDataDir and resources.instanceDir exist,
+     * the existing instanceDir is preserved and baseDataDir is removed.
+     */
+
+    // GIVEN an entry with both baseDataDir and resources.instanceDir
+    const entry: Record<string, unknown> = {
+      assistantId: "conflict",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      baseDataDir: "/old/path",
+      resources: {
+        instanceDir: "/new/path",
+        daemonPort: 7821,
+        gatewayPort: 7830,
+        qdrantPort: 6333,
+        pidFile: "/new/path/.vellum/vellum.pid",
+      },
+    };
+
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+
+    // THEN baseDataDir should be removed
+    expect(changed).toBe(true);
+    expect(entry.baseDataDir).toBeUndefined();
+
+    // AND the existing instanceDir should be preserved
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.instanceDir).toBe("/new/path");
+  });
+});
+
+describe("legacy migration via loadAllAssistants", () => {
+  beforeEach(() => {
+    try {
+      rmSync(join(testDir, ".vellum.lock.json"));
+    } catch {
+      // file may not exist
+    }
+  });
+
+  test("migrates legacy entries and persists to disk on read", () => {
+    /**
+     * Tests that reading assistants from a lockfile with legacy entries
+     * triggers migration and persists the updated format to disk.
+     */
+
+    // GIVEN a lockfile with a legacy entry containing baseDataDir
+    writeLockfile({
+      assistants: [
+        {
+          assistantId: "legacy-bot",
+          runtimeUrl: "http://localhost:7830",
+          cloud: "local",
+          baseDataDir: "/home/user/.local/share/vellum/assistants/legacy-bot",
+        },
+      ],
+    });
+
+    // WHEN we load assistants
+    const all = loadAllAssistants();
+
+    // THEN the entry should have resources populated
+    expect(all).toHaveLength(1);
+    expect(all[0].resources).toBeDefined();
+    expect(all[0].resources!.instanceDir).toBe(
+      "/home/user/.local/share/vellum/assistants/legacy-bot",
+    );
+    expect(all[0].resources!.gatewayPort).toBe(7830);
+
+    // AND the lockfile on disk should reflect the migration
+    const rawDisk = JSON.parse(
+      readFileSync(join(testDir, ".vellum.lock.json"), "utf-8"),
+    );
+    const diskEntry = rawDisk.assistants[0];
+    expect(diskEntry.baseDataDir).toBeUndefined();
+    expect(diskEntry.resources.instanceDir).toBe(
+      "/home/user/.local/share/vellum/assistants/legacy-bot",
+    );
+  });
+});

package/src/__tests__/multi-local.test.ts

@@ -94,21 +94,22 @@ describe("multi-local", () => {
   });
 
   describe("allocateLocalResources() produces non-conflicting ports", () => {
-    test("first instance gets XDG path and default ports", async () => {
+    test("first instance gets home directory and default ports", async () => {
       // GIVEN no local assistants exist in the lockfile
 
       // WHEN we allocate resources for the first instance
       const res = await allocateLocalResources("instance-a");
 
-      // THEN it gets an XDG instance directory under the home dir
-      expect(res.instanceDir).toBe(
-        join(testDir, ".local", "share", "vellum", "assistants", "instance-a"),
-      );
+      // THEN it gets the home directory as its instance root
+      expect(res.instanceDir).toBe(testDir);
 
       // AND it gets the default ports since no other instances exist
       expect(res.daemonPort).toBe(DEFAULT_DAEMON_PORT);
       expect(res.gatewayPort).toBe(DEFAULT_GATEWAY_PORT);
       expect(res.qdrantPort).toBe(DEFAULT_QDRANT_PORT);
+
+      // AND the PID file is under ~/.vellum/
+      expect(res.pidFile).toBe(join(testDir, ".vellum", "vellum.pid"));
     });
 
     test("second instance gets distinct ports and dir when first instance is saved", async () => {

package/src/commands/hatch.ts

@@ -50,6 +50,7 @@ import {
 import { isProcessAlive } from "../lib/process";
 import { generateRandomSuffix } from "../lib/random-name";
 import { validateAssistantName } from "../lib/retire-archive";
+import { archiveLogFile, resetLogFile } from "../lib/xdg-log";
 
 export type { PollResult, WatchHatchingResult } from "../lib/gcp";
 
@@ -730,6 +731,10 @@ async function hatchLocal(
     resources = await allocateLocalResources(instanceName);
   }
 
+  const logsDir = join(resources.instanceDir, ".vellum", "workspace", "data", "logs");
+  archiveLogFile("hatch.log", logsDir);
+  resetLogFile("hatch.log");
+
   console.log(`🥚 Hatching local assistant: ${instanceName}`);
   console.log(`   Species: ${species}`);
   console.log("");

package/src/components/DefaultMainScreen.tsx

@@ -152,6 +152,19 @@ interface HealthResponse {
   message?: string;
 }
 
+/** Extract human-readable message from a daemon JSON error response. */
+function friendlyErrorMessage(status: number, body: string): string {
+  try {
+    const parsed = JSON.parse(body) as { error?: { message?: string } };
+    if (parsed?.error?.message) {
+      return parsed.error.message;
+    }
+  } catch {
+    // Not JSON — fall through
+  }
+  return `HTTP ${status}: ${body || "Unknown error"}`;
+}
+
 async function runtimeRequest<T>(
   baseUrl: string,
   assistantId: string,
@@ -171,7 +184,7 @@ async function runtimeRequest<T>(
 
   if (!response.ok) {
     const body = await response.text().catch(() => "");
-    throw new Error(`HTTP ${response.status}: ${body || response.statusText}`);
+    throw new Error(friendlyErrorMessage(response.status, body));
   }
 
   if (response.status === 204) {
@@ -1758,7 +1771,8 @@ function ChatApp({
           clearTimeout(timeoutId);
           h.setBusy(false);
           h.hideSpinner();
-          const errorMsg = `Failed to send: ${sendErr instanceof Error ? sendErr.message : sendErr}`;
+          const errorMsg =
+            sendErr instanceof Error ? sendErr.message : String(sendErr);
           h.showError(errorMsg);
           chatLogRef.current.push({ role: "error", content: errorMsg });
           return;

package/src/lib/assistant-config.ts

@@ -16,7 +16,9 @@ import { probePort } from "./port-probe.js";
  */
 export interface LocalInstanceResources {
   /**
-   * Instance-specific data root at `~/.local/share/vellum/assistants/<name>/`.
+   * Instance-specific data root. The first local assistant uses `~` (home
+   * directory) with default ports. Subsequent instances are placed under
+   * `~/.local/share/vellum/assistants/<name>/`.
    * The daemon's `.vellum/` directory lives inside it.
    */
   instanceDir: string;
@@ -28,6 +30,7 @@ export interface LocalInstanceResources {
   qdrantPort: number;
   /** Absolute path to the daemon PID file */
   pidFile: string;
+  [key: string]: unknown;
 }
 
 export interface AssistantEntry {
@@ -48,10 +51,11 @@ export interface AssistantEntry {
   hatchedAt?: string;
   /** Per-instance resource config. Present for local entries in multi-instance setups. */
   resources?: LocalInstanceResources;
+  [key: string]: unknown;
 }
 
 interface LockfileData {
-  assistants?: AssistantEntry[];
+  assistants?: Record<string, unknown>[];
   activeAssistant?: string;
   platformBaseUrl?: string;
   [key: string]: unknown;
@@ -92,14 +96,132 @@ function writeLockfile(data: LockfileData): void {
   writeFileSync(lockfilePath, JSON.stringify(data, null, 2) + "\n");
 }
 
+/**
+ * Try to extract a port number from a URL string (e.g. `http://localhost:7830`).
+ * Returns undefined if the URL is malformed or has no explicit port.
+ */
+function parsePortFromUrl(url: unknown): number | undefined {
+  if (typeof url !== "string") return undefined;
+  try {
+    const parsed = new URL(url);
+    const port = parseInt(parsed.port, 10);
+    return isNaN(port) ? undefined : port;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Detect and migrate legacy lockfile entries to the current format.
+ *
+ * Legacy entries stored `baseDataDir` as a top-level field. The current
+ * format nests this under `resources.instanceDir`. This function also
+ * synthesises a full `resources` object when one is missing by inferring
+ * ports from the entry's `runtimeUrl` and falling back to defaults.
+ *
+ * Returns `true` if the entry was mutated (so the caller can persist).
+ */
+export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
+  if (typeof raw.cloud === "string" && raw.cloud !== "local") {
+    return false;
+  }
+
+  let mutated = false;
+
+  // Migrate top-level `baseDataDir` → `resources.instanceDir`
+  if (typeof raw.baseDataDir === "string" && raw.baseDataDir) {
+    if (!raw.resources || typeof raw.resources !== "object") {
+      raw.resources = {};
+    }
+    const res = raw.resources as Record<string, unknown>;
+    if (!res.instanceDir) {
+      res.instanceDir = raw.baseDataDir;
+      mutated = true;
+    }
+    delete raw.baseDataDir;
+    mutated = true;
+  }
+
+  // Synthesise missing `resources` for local entries
+  if (!raw.resources || typeof raw.resources !== "object") {
+    const gatewayPort =
+      parsePortFromUrl(raw.runtimeUrl) ?? DEFAULT_GATEWAY_PORT;
+    const instanceDir = join(
+      homedir(),
+      ".local",
+      "share",
+      "vellum",
+      "assistants",
+      typeof raw.assistantId === "string" ? raw.assistantId : "default",
+    );
+    raw.resources = {
+      instanceDir,
+      daemonPort: DEFAULT_DAEMON_PORT,
+      gatewayPort,
+      qdrantPort: DEFAULT_QDRANT_PORT,
+      pidFile: join(instanceDir, ".vellum", "vellum.pid"),
+    };
+    mutated = true;
+  } else {
+    // Backfill any missing fields on an existing partial `resources` object
+    const res = raw.resources as Record<string, unknown>;
+    if (!res.instanceDir) {
+      res.instanceDir = join(
+        homedir(),
+        ".local",
+        "share",
+        "vellum",
+        "assistants",
+        typeof raw.assistantId === "string" ? raw.assistantId : "default",
+      );
+      mutated = true;
+    }
+    if (typeof res.daemonPort !== "number") {
+      res.daemonPort = DEFAULT_DAEMON_PORT;
+      mutated = true;
+    }
+    if (typeof res.gatewayPort !== "number") {
+      res.gatewayPort =
+        parsePortFromUrl(raw.runtimeUrl) ?? DEFAULT_GATEWAY_PORT;
+      mutated = true;
+    }
+    if (typeof res.qdrantPort !== "number") {
+      res.qdrantPort = DEFAULT_QDRANT_PORT;
+      mutated = true;
+    }
+    if (typeof res.pidFile !== "string") {
+      res.pidFile = join(
+        res.instanceDir as string,
+        ".vellum",
+        "vellum.pid",
+      );
+      mutated = true;
+    }
+  }
+
+  return mutated;
+}
+
 function readAssistants(): AssistantEntry[] {
   const data = readLockfile();
   const entries = data.assistants;
   if (!Array.isArray(entries)) {
     return [];
   }
+
+  let migrated = false;
+  for (const entry of entries) {
+    if (migrateLegacyEntry(entry)) {
+      migrated = true;
+    }
+  }
+
+  if (migrated) {
+    writeLockfile(data);
+  }
+
   return entries.filter(
-    (e) =>
+    (e): e is AssistantEntry =>
       typeof e.assistantId === "string" && typeof e.runtimeUrl === "string",
   );
 }
@@ -131,14 +253,14 @@ export function findAssistantByName(name: string): AssistantEntry | null {
 export function removeAssistantEntry(assistantId: string): void {
   const data = readLockfile();
   const entries = (data.assistants ?? []).filter(
-    (e: AssistantEntry) => e.assistantId !== assistantId,
+    (e) => e.assistantId !== assistantId,
   );
   data.assistants = entries;
   // Reassign active assistant if it matches the removed entry
   if (data.activeAssistant === assistantId) {
     const remaining = entries[0];
     if (remaining) {
-      data.activeAssistant = remaining.assistantId;
+      data.activeAssistant = String(remaining.assistantId);
     } else {
       delete data.activeAssistant;
     }
@@ -229,12 +351,28 @@ async function findAvailablePort(
 
 /**
  * Allocate an isolated set of resources for a named local instance.
- * Each assistant is placed under
+ * The first local assistant uses the home directory with default ports.
+ * Subsequent assistants are placed under
  * `~/.local/share/vellum/assistants/<name>/` with scanned ports.
  */
 export async function allocateLocalResources(
   instanceName: string,
 ): Promise<LocalInstanceResources> {
+  // First local assistant gets the home directory with default ports.
+  const existingLocals = loadAllAssistants().filter((e) => e.cloud === "local");
+  if (existingLocals.length === 0) {
+    const home = homedir();
+    const vellumDir = join(home, ".vellum");
+    mkdirSync(vellumDir, { recursive: true });
+    return {
+      instanceDir: home,
+      daemonPort: DEFAULT_DAEMON_PORT,
+      gatewayPort: DEFAULT_GATEWAY_PORT,
+      qdrantPort: DEFAULT_QDRANT_PORT,
+      pidFile: join(vellumDir, "vellum.pid"),
+    };
+  }
+
   const instanceDir = join(
     homedir(),
     ".local",

package/src/lib/docker.ts

@@ -10,7 +10,7 @@ import type { Species } from "./constants";
 import { discoverPublicUrl } from "./local";
 import { generateRandomSuffix } from "./random-name";
 import { exec, execOutput } from "./step-runner";
-import { closeLogFile, openLogFile, writeToLogFile } from "./xdg-log";
+import { closeLogFile, openLogFile, resetLogFile, writeToLogFile } from "./xdg-log";
 
 const _require = createRequire(import.meta.url);
 
@@ -163,6 +163,8 @@ export async function hatchDocker(
     process.exit(1);
   }
 
+  resetLogFile("hatch.log");
+
   console.log(`🥚 Hatching Docker assistant: ${instanceName}`);
   console.log(`   Species: ${species}`);
   console.log(`   Dockerfile: ${dockerfile}`);

package/src/lib/local.ts

@@ -1,6 +1,5 @@
 import { execFileSync, execSync, spawn } from "child_process";
 import {
-  closeSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -258,16 +257,13 @@ async function startDaemonFromSource(
     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) {
@@ -472,7 +468,9 @@ function recoverPidFile(
   return pid;
 }
 
-export 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;
 
@@ -714,18 +712,14 @@ export async function startLocalDaemon(
         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;
 
@@ -816,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}`);
@@ -952,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();
@@ -971,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)");
     }

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 */
         }