@vellumai/cli 0.4.6 → 0.4.8

package/package.json

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

package/src/adapters/install.sh

@@ -28,17 +28,47 @@ ensure_git() {
         # Try installing CLT first before falling back to Homebrew.
         if ! xcode-select -p >/dev/null 2>&1; then
             info "Installing Xcode Command Line Tools (includes git)..."
-            xcode-select --install 2>/dev/null || true
-            info "Please follow the on-screen dialog to install. Waiting..."
-            local waited=0
-            while ! xcode-select -p >/dev/null 2>&1; do
-                sleep 5
-                waited=$((waited + 5))
-                if [ "$waited" -ge 600 ]; then
-                    error "Timed out waiting for Xcode Command Line Tools. Please install manually and re-run."
-                    exit 1
-                fi
-            done
+
+            # Use softwareupdate to install CLT non-interactively instead of
+            # xcode-select --install which opens a GUI dialog requiring manual
+            # confirmation.
+            touch /tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress
+            local clt_package
+            # softwareupdate -l output has two relevant lines per update:
+            #   * Label: Command Line Tools for Xcode-16.0       <-- label (what -i expects)
+            #       Title: Command Line Tools for Xcode, ...      <-- description
+            # We need the label, which is on lines starting with "* ".
+            # Use the same parsing approach as Homebrew's installer.
+            clt_package=$(softwareupdate -l 2>/dev/null \
+                | grep -B 1 -E 'Command Line Tools' \
+                | awk -F'*' '/^\*/{print $2}' \
+                | sed -e 's/^ Label: //' -e 's/^ *//' \
+                | sort -V \
+                | tail -1)
+
+            if [ -n "$clt_package" ]; then
+                info "Found package: $clt_package"
+                softwareupdate -i "$clt_package" --verbose 2>&1 | while IFS= read -r line; do
+                    printf "  %s\n" "$line"
+                done
+            else
+                # Fallback: if softwareupdate can't find the package, try
+                # xcode-select --install and wait for user interaction.
+                info "Could not find CLT package via softwareupdate, falling back to xcode-select..."
+                xcode-select --install 2>/dev/null || true
+                info "Please follow the on-screen dialog to install. Waiting..."
+                local waited=0
+                while ! xcode-select -p >/dev/null 2>&1; do
+                    sleep 5
+                    waited=$((waited + 5))
+                    if [ "$waited" -ge 600 ]; then
+                        error "Timed out waiting for Xcode Command Line Tools. Please install manually and re-run."
+                        exit 1
+                    fi
+                done
+            fi
+
+            rm -f /tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress
             hash -r 2>/dev/null || true
         fi
 

package/src/commands/hatch.ts

@@ -504,11 +504,40 @@ function installCLISymlink(): void {
   console.log(`   ⚠ Could not create symlink for vellum CLI (tried ${preferredPath} and ${fallbackPath})`);
 }
 
+async function waitForDaemonReady(runtimeUrl: string, bearerToken: string | undefined, timeoutMs = 15000): Promise<boolean> {
+  const start = Date.now();
+  const pollInterval = 1000;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(`${runtimeUrl}/v1/health`, {
+        method: "GET",
+        headers: bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {},
+        signal: AbortSignal.timeout(2000),
+      });
+      if (res.ok) return true;
+    } catch {
+      // Daemon not ready yet
+    }
+    await new Promise((r) => setTimeout(r, pollInterval));
+  }
+  return false;
+}
+
 async function displayPairingQRCode(runtimeUrl: string, bearerToken: string | undefined): Promise<void> {
   try {
     const pairingRequestId = randomUUID();
     const pairingSecret = randomBytes(32).toString("hex");
 
+    // The daemon's HTTP server may not be fully ready even though the gateway
+    // health check passed (the gateway is up, but the upstream daemon HTTP
+    // endpoint it proxies to may still be initializing). Poll the daemon's
+    // health endpoint through the gateway to ensure it's reachable.
+    const daemonReady = await waitForDaemonReady(runtimeUrl, bearerToken);
+    if (!daemonReady) {
+      console.warn("⚠ Daemon health check did not pass within 15s. Run `vellum pair` to try again.\n");
+      return;
+    }
+
     const registerRes = await fetch(`${runtimeUrl}/pairing/register`, {
       method: "POST",
       headers: {

package/src/commands/retire.ts

@@ -10,6 +10,7 @@ import { retireInstance as retireGcpInstance } from "../lib/gcp";
 import { stopProcessByPidFile } from "../lib/process";
 import { getArchivePath, getMetadataPath } from "../lib/retire-archive";
 import { exec } from "../lib/step-runner";
+import { openLogFile, closeLogFile, writeToLogFile } from "../lib/xdg-log";
 
 function resolveCloud(entry: AssistantEntry): string {
   if (entry.cloud) {
@@ -120,7 +121,42 @@ function parseSource(): string | undefined {
   return undefined;
 }
 
+/** Patch console methods to also append output to the given log file descriptor. */
+function teeConsoleToLogFile(fd: number | "ignore"): void {
+  if (fd === "ignore") return;
+
+  const origLog = console.log.bind(console);
+  const origWarn = console.warn.bind(console);
+  const origError = console.error.bind(console);
+
+  const timestamp = () => new Date().toISOString();
+
+  console.log = (...args: unknown[]) => {
+    origLog(...args);
+    writeToLogFile(fd, `[${timestamp()}] ${args.map(String).join(" ")}\n`);
+  };
+  console.warn = (...args: unknown[]) => {
+    origWarn(...args);
+    writeToLogFile(fd, `[${timestamp()}] WARN: ${args.map(String).join(" ")}\n`);
+  };
+  console.error = (...args: unknown[]) => {
+    origError(...args);
+    writeToLogFile(fd, `[${timestamp()}] ERROR: ${args.map(String).join(" ")}\n`);
+  };
+}
+
 export async function retire(): Promise<void> {
+  const logFd = process.env.VELLUM_DESKTOP_APP ? openLogFile("retire.log") : "ignore";
+  teeConsoleToLogFile(logFd);
+
+  try {
+    await retireInner();
+  } finally {
+    closeLogFile(logFd);
+  }
+}
+
+async function retireInner(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
     console.log("Usage: vellum retire <name> [--source <source>]");

package/src/components/DefaultMainScreen.tsx

@@ -1,6 +1,6 @@
 import { spawn } from "child_process";
 import { createHash, randomBytes, randomUUID } from "crypto";
-import { hostname, userInfo } from "os";
+import { hostname, platform, userInfo } from "os";
 import { basename } from "path";
 import qrcode from "qrcode-terminal";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactElement } from "react";
@@ -135,6 +135,7 @@ async function runtimeRequest<T>(
   path: string,
   init?: RequestInit,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<T> {
   const url = `${baseUrl}/v1/assistants/${assistantId}${path}`;
   const response = await fetch(url, {
@@ -142,6 +143,7 @@ async function runtimeRequest<T>(
     headers: {
       "Content-Type": "application/json",
       ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+      ...(actorToken ? { "X-Actor-Token": actorToken } : {}),
       ...(init?.headers as Record<string, string> | undefined),
     },
   });
@@ -177,10 +179,47 @@ async function checkHealthRuntime(baseUrl: string): Promise<HealthResponse> {
   return response.json() as Promise<HealthResponse>;
 }
 
+async function bootstrapActorToken(baseUrl: string, bearerToken?: string): Promise<string> {
+  if (!bearerToken) {
+    throw new Error("Missing bearer token; cannot bootstrap actor identity");
+  }
+
+  const deviceId = `vellum-cli:${platform()}:${hostname()}:${userInfo().username}`;
+  const url = `${baseUrl}/v1/integrations/guardian/vellum/bootstrap`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${bearerToken}`,
+    },
+    body: JSON.stringify({ platform: "cli", deviceId }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`HTTP ${response.status}: ${body || response.statusText}`);
+  }
+
+  const json: unknown = await response.json();
+
+  if (typeof json !== "object" || json === null) {
+    throw new Error("Invalid bootstrap response from gateway/runtime");
+  }
+
+  const actorToken = (json as Record<string, unknown>).actorToken;
+  if (typeof actorToken !== "string" || actorToken.length === 0) {
+    throw new Error("Invalid bootstrap response from gateway/runtime");
+  }
+
+  return actorToken;
+}
+
 async function pollMessages(
   baseUrl: string,
   assistantId: string,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<ListMessagesResponse> {
   const params = new URLSearchParams({ conversationKey: assistantId });
   return runtimeRequest<ListMessagesResponse>(
@@ -189,6 +228,7 @@ async function pollMessages(
     `/messages?${params.toString()}`,
     undefined,
     bearerToken,
+    actorToken,
   );
 }
 
@@ -198,6 +238,7 @@ async function sendMessage(
   content: string,
   signal?: AbortSignal,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<SendMessageResponse> {
   return runtimeRequest<SendMessageResponse>(
     baseUrl,
@@ -209,6 +250,7 @@ async function sendMessage(
       signal,
     },
     bearerToken,
+    actorToken,
   );
 }
 
@@ -218,6 +260,7 @@ async function submitDecision(
   requestId: string,
   decision: "allow" | "deny",
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<SubmitDecisionResponse> {
   return runtimeRequest<SubmitDecisionResponse>(
     baseUrl,
@@ -228,6 +271,7 @@ async function submitDecision(
       body: JSON.stringify({ requestId, decision }),
     },
     bearerToken,
+    actorToken,
   );
 }
 
@@ -239,6 +283,7 @@ async function addTrustRule(
   scope: string,
   decision: "allow" | "deny",
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<AddTrustRuleResponse> {
   return runtimeRequest<AddTrustRuleResponse>(
     baseUrl,
@@ -249,6 +294,7 @@ async function addTrustRule(
       body: JSON.stringify({ requestId, pattern, scope, decision }),
     },
     bearerToken,
+    actorToken,
   );
 }
 
@@ -256,6 +302,7 @@ async function pollPendingInteractions(
   baseUrl: string,
   assistantId: string,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<PendingInteractionsResponse> {
   const params = new URLSearchParams({ conversationKey: assistantId });
   return runtimeRequest<PendingInteractionsResponse>(
@@ -264,6 +311,7 @@ async function pollPendingInteractions(
     `/pending-interactions?${params.toString()}`,
     undefined,
     bearerToken,
+    actorToken,
   );
 }
 
@@ -301,6 +349,7 @@ async function handleConfirmationPrompt(
   confirmation: PendingConfirmation,
   chatApp: ChatAppHandle,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<void> {
   const preview = formatConfirmationPreview(confirmation.toolName, confirmation.input);
   const allowlistOptions = confirmation.allowlistOptions ?? [];
@@ -320,7 +369,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, actorToken);
     chatApp.addStatus("\u2714 Allowed", "green");
     return;
   }
@@ -333,6 +382,7 @@ async function handleConfirmationPrompt(
       chatApp,
       "always_allow",
       bearerToken,
+      actorToken,
     );
     return;
   }
@@ -345,11 +395,12 @@ async function handleConfirmationPrompt(
       chatApp,
       "always_deny",
       bearerToken,
+      actorToken,
     );
     return;
   }
 
-  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken, actorToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -361,6 +412,7 @@ async function handlePatternSelection(
   chatApp: ChatAppHandle,
   trustDecision: TrustDecision,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<void> {
   const allowlistOptions = confirmation.allowlistOptions ?? [];
   const label = trustDecision === "always_deny" ? "Denylist" : "Allowlist";
@@ -379,11 +431,12 @@ async function handlePatternSelection(
       selectedPattern,
       trustDecision,
       bearerToken,
+      actorToken,
     );
     return;
   }
 
-  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken, actorToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -396,6 +449,7 @@ async function handleScopeSelection(
   selectedPattern: string,
   trustDecision: TrustDecision,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<void> {
   const scopeOptions = confirmation.scopeOptions ?? [];
   const label = trustDecision === "always_deny" ? "Denylist" : "Allowlist";
@@ -413,6 +467,7 @@ async function handleScopeSelection(
       scopeOptions[index].scope,
       ruleDecision,
       bearerToken,
+      actorToken,
     );
     await submitDecision(
       baseUrl,
@@ -420,6 +475,7 @@ async function handleScopeSelection(
       requestId,
       ruleDecision === "deny" ? "deny" : "allow",
       bearerToken,
+      actorToken,
     );
     const ruleLabel = trustDecision === "always_deny" ? "Denylisted" : "Allowlisted";
     const ruleColor = trustDecision === "always_deny" ? "yellow" : "green";
@@ -430,7 +486,7 @@ async function handleScopeSelection(
     return;
   }
 
-  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken, actorToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -1025,6 +1081,7 @@ function ChatApp({
   const pollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const doctorSessionIdRef = useRef(randomUUID());
   const handleRef_ = useRef<ChatAppHandle | null>(null);
+  const actorTokenRef = useRef<string | undefined>(undefined);
 
   const { stdout } = useStdout();
   const terminalRows = stdout.rows || DEFAULT_TERMINAL_ROWS;
@@ -1250,6 +1307,9 @@ function ChatApp({
 
     try {
       const health = await checkHealthRuntime(runtimeUrl);
+      if (!actorTokenRef.current) {
+        actorTokenRef.current = await bootstrapActorToken(runtimeUrl, bearerToken);
+      }
       h.hideSpinner();
       h.updateHealthStatus(health.status);
       if (health.status === "healthy" || health.status === "ok") {
@@ -1265,7 +1325,12 @@ function ChatApp({
       h.showSpinner("Loading conversation history...");
 
       try {
-        const historyResponse = await pollMessages(runtimeUrl, assistantId, bearerToken);
+        const historyResponse = await pollMessages(
+          runtimeUrl,
+          assistantId,
+          bearerToken,
+          actorTokenRef.current,
+        );
         h.hideSpinner();
         if (historyResponse.messages.length > 0) {
           for (const msg of historyResponse.messages) {
@@ -1279,7 +1344,12 @@ function ChatApp({
 
       pollTimerRef.current = setInterval(async () => {
         try {
-          const response = await pollMessages(runtimeUrl, assistantId, bearerToken);
+          const response = await pollMessages(
+            runtimeUrl,
+            assistantId,
+            bearerToken,
+            actorTokenRef.current,
+          );
           for (const msg of response.messages) {
             if (!seenMessageIdsRef.current.has(msg.id)) {
               seenMessageIdsRef.current.add(msg.id);
@@ -1296,11 +1366,12 @@ function ChatApp({
       connectedRef.current = true;
       connectingRef.current = false;
       return true;
-    } catch {
+    } catch (err) {
       h.hideSpinner();
       connectingRef.current = false;
       h.updateHealthStatus("unreachable");
-      h.addStatus(`${statusEmoji("unreachable")} Failed to connect: Timeout`, "red");
+      const msg = err instanceof Error ? err.message : String(err);
+      h.addStatus(`${statusEmoji("unreachable")} Failed to connect: ${msg}`, "red");
       return false;
     }
   }, [runtimeUrl, assistantId, bearerToken]);
@@ -1561,6 +1632,7 @@ function ChatApp({
             trimmed,
             controller.signal,
             bearerToken,
+            actorTokenRef.current,
           );
           clearTimeout(timeoutId);
           if (!sendResult.accepted) {
@@ -1586,7 +1658,12 @@ function ChatApp({
 
           // Check for pending confirmations/secrets
           try {
-            const pending = await pollPendingInteractions(runtimeUrl, assistantId, bearerToken);
+            const pending = await pollPendingInteractions(
+              runtimeUrl,
+              assistantId,
+              bearerToken,
+              actorTokenRef.current,
+            );
 
             if (pending.pendingConfirmation) {
               h.hideSpinner();
@@ -1597,6 +1674,7 @@ function ChatApp({
                 pending.pendingConfirmation,
                 h,
                 bearerToken,
+                actorTokenRef.current,
               );
               h.showSpinner("Working...");
               continue;
@@ -1615,6 +1693,7 @@ function ChatApp({
                     body: JSON.stringify({ requestId: secretRequestId, value, delivery }),
                   },
                   bearerToken,
+                  actorTokenRef.current,
                 );
               });
               h.showSpinner("Working...");
@@ -1626,7 +1705,12 @@ function ChatApp({
 
           // Poll for new messages to detect completion
           try {
-            const pollResult = await pollMessages(runtimeUrl, assistantId, bearerToken);
+            const pollResult = await pollMessages(
+              runtimeUrl,
+              assistantId,
+              bearerToken,
+              actorTokenRef.current,
+            );
             for (const msg of pollResult.messages) {
               if (!seenMessageIdsRef.current.has(msg.id)) {
                 seenMessageIdsRef.current.add(msg.id);
@@ -1800,46 +1884,48 @@ function ChatApp({
         healthStatus={healthStatus}
       />
 
-      {visibleWindow.hiddenAbove > 0 ? (
-        <Text dimColor>
-          {"\u2191"} {visibleWindow.hiddenAbove} more above (Shift+\u2191/Cmd+\u2191)
-        </Text>
-      ) : null}
-
-      {visibleWindow.items.map((item, i) => {
-        const feedIndex = visibleWindow.startIndex + i;
-        if (isRuntimeMessage(item)) {
-          return (
-            <Box key={feedIndex} flexDirection="column" marginBottom={1}>
-              <MessageDisplay msg={item} />
-            </Box>
-          );
-        }
-        if (item.type === "status") {
-          return (
-            <Text key={feedIndex} color={item.color as "green" | "yellow" | "red" | undefined}>
-              {item.text}
-            </Text>
-          );
-        }
-        if (item.type === "help") {
-          return <HelpDisplay key={feedIndex} />;
-        }
-        if (item.type === "error") {
-          return (
-            <Text key={feedIndex} color="red">
-              {item.text}
-            </Text>
-          );
-        }
-        return null;
-      })}
+      <Box flexDirection="column" flexGrow={1} overflow="hidden">
+        {visibleWindow.hiddenAbove > 0 ? (
+          <Text dimColor>
+            {"\u2191"} {visibleWindow.hiddenAbove} more above (Shift+\u2191/Cmd+\u2191)
+          </Text>
+        ) : null}
+
+        {visibleWindow.items.map((item, i) => {
+          const feedIndex = visibleWindow.startIndex + i;
+          if (isRuntimeMessage(item)) {
+            return (
+              <Box key={feedIndex} flexDirection="column" marginBottom={1}>
+                <MessageDisplay msg={item} />
+              </Box>
+            );
+          }
+          if (item.type === "status") {
+            return (
+              <Text key={feedIndex} color={item.color as "green" | "yellow" | "red" | undefined}>
+                {item.text}
+              </Text>
+            );
+          }
+          if (item.type === "help") {
+            return <HelpDisplay key={feedIndex} />;
+          }
+          if (item.type === "error") {
+            return (
+              <Text key={feedIndex} color="red">
+                {item.text}
+              </Text>
+            );
+          }
+          return null;
+        })}
 
-      {visibleWindow.hiddenBelow > 0 ? (
-        <Text dimColor>
-          {"\u2193"} {visibleWindow.hiddenBelow} more below (Shift+\u2193/Cmd+\u2193)
-        </Text>
-      ) : null}
+        {visibleWindow.hiddenBelow > 0 ? (
+          <Text dimColor>
+            {"\u2193"} {visibleWindow.hiddenBelow} more below (Shift+\u2193/Cmd+\u2193)
+          </Text>
+        ) : null}
+      </Box>
 
       {spinnerText ? <SpinnerDisplay text={spinnerText} /> : null}
 

package/src/lib/local.ts

@@ -1,5 +1,5 @@
 import { execFileSync, spawn } from "child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { createRequire } from "module";
 import { createConnection } from "net";
 import { homedir } from "os";
@@ -8,35 +8,10 @@ import { dirname, join } from "path";
 import { loadLatestAssistant } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
 import { stopProcessByPidFile } from "./process.js";
+import { openLogFile, closeLogFile } from "./xdg-log.js";
 
 const _require = createRequire(import.meta.url);
 
-/** Returns the XDG-compatible log directory for Vellum hatch logs. */
-function getHatchLogDir(): string {
-  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-  return join(configHome, "vellum", "logs");
-}
-
-/** Open (or create) a log file in append mode, returning the file descriptor.
- *  Creates the parent directory if it doesn't exist. Returns "ignore" if the
- *  directory or file cannot be created (permissions, read-only filesystem, etc.)
- *  so that spawn falls back to discarding output instead of aborting startup. */
-function openHatchLogFile(name: string): number | "ignore" {
-  try {
-    const dir = getHatchLogDir();
-    mkdirSync(dir, { recursive: true });
-    return openSync(join(dir, name), "a");
-  } catch {
-    return "ignore";
-  }
-}
-
-/** Close a file descriptor returned by openHatchLogFile (no-op for "ignore"). */
-function closeHatchLogFile(fd: number | "ignore"): void {
-  if (typeof fd === "number") {
-    try { closeSync(fd); } catch { /* best-effort */ }
-  }
-}
 
 function isAssistantSourceDir(dir: string): boolean {
   const pkgPath = join(dir, "package.json");
@@ -307,6 +282,12 @@ async function discoverPublicUrl(): Promise<string | undefined> {
     // metadata service not reachable
   }
 
+  // For custom hardware or when cloud-specific metadata didn't resolve,
+  // fall back to a public IP discovery service.
+  if (!externalIp) {
+    externalIp = await discoverPublicIpFallback();
+  }
+
   if (externalIp) {
     console.log(`   Discovered external IP: ${externalIp}`);
     return `http://${externalIp}:${GATEWAY_PORT}`;
@@ -314,6 +295,32 @@ async function discoverPublicUrl(): Promise<string | undefined> {
   return undefined;
 }
 
+/** Try to discover the machine's public IP using external services.
+ *  Attempts multiple providers for resilience. */
+async function discoverPublicIpFallback(): Promise<string | undefined> {
+  const services = [
+    "https://api.ipify.org",
+    "https://ifconfig.me/ip",
+    "https://icanhazip.com",
+  ];
+
+  for (const url of services) {
+    try {
+      const resp = await fetch(url, { signal: AbortSignal.timeout(3000) });
+      if (resp.ok) {
+        const ip = (await resp.text()).trim();
+        // Basic validation: must look like an IPv4 or IPv6 address
+        if (ip && /^[\d.:a-fA-F]+$/.test(ip)) {
+          return ip;
+        }
+      }
+    } catch {
+      // Service unreachable, try the next one
+    }
+  }
+  return undefined;
+}
+
 export async function startLocalDaemon(): Promise<void> {
   if (process.env.VELLUM_DESKTOP_APP) {
     // When running inside the desktop app, the CLI owns the daemon lifecycle.
@@ -403,7 +410,7 @@ export async function startLocalDaemon(): Promise<void> {
         }
       }
 
-      const daemonLogFd = openHatchLogFile("daemon.log");
+      const daemonLogFd = openLogFile("daemon.log");
       let daemonPid: number | undefined;
       try {
         const child = spawn(daemonBinary, [], {
@@ -415,7 +422,7 @@ export async function startLocalDaemon(): Promise<void> {
         child.unref();
         daemonPid = child.pid;
       } finally {
-        closeHatchLogFile(daemonLogFd);
+        closeLogFile(daemonLogFd);
       }
 
       // Write PID file immediately so the health monitor can find the process
@@ -568,7 +575,7 @@ export async function startGateway(assistantId?: string): Promise<string> {
       );
     }
 
-    const gatewayLogFd = openHatchLogFile("gateway.log");
+    const gatewayLogFd = openLogFile("gateway.log");
     try {
       gateway = spawn(gatewayBinary, [], {
         detached: true,
@@ -576,12 +583,12 @@ export async function startGateway(assistantId?: string): Promise<string> {
         env: gatewayEnv,
       });
     } finally {
-      closeHatchLogFile(gatewayLogFd);
+      closeLogFile(gatewayLogFd);
     }
   } else {
     // Source tree / bunx: resolve the gateway source directory and run via bun.
     const gatewayDir = resolveGatewayDir();
-    const gwLogFd = openHatchLogFile("gateway.log");
+    const gwLogFd = openLogFile("gateway.log");
     try {
       gateway = spawn("bun", ["run", "src/index.ts"], {
         cwd: gatewayDir,
@@ -590,7 +597,7 @@ export async function startGateway(assistantId?: string): Promise<string> {
         env: gatewayEnv,
       });
     } finally {
-      closeHatchLogFile(gwLogFd);
+      closeLogFile(gwLogFd);
     }
   }
 

package/src/lib/xdg-log.ts

@@ -0,0 +1,37 @@
+import { closeSync, mkdirSync, openSync, writeSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+/** Returns the XDG-compatible log directory for Vellum CLI logs. */
+export function getLogDir(): string {
+  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(configHome, "vellum", "logs");
+}
+
+/** Open (or create) a log file in append mode, returning the file descriptor.
+ *  Creates the parent directory if it doesn't exist. Returns "ignore" if the
+ *  directory or file cannot be created (permissions, read-only filesystem, etc.)
+ *  so that callers can fall back to discarding output instead of aborting. */
+export function openLogFile(name: string): number | "ignore" {
+  try {
+    const dir = getLogDir();
+    mkdirSync(dir, { recursive: true });
+    return openSync(join(dir, name), "a");
+  } catch {
+    return "ignore";
+  }
+}
+
+/** Close a file descriptor returned by openLogFile (no-op for "ignore"). */
+export function closeLogFile(fd: number | "ignore"): void {
+  if (typeof fd === "number") {
+    try { closeSync(fd); } catch { /* best-effort */ }
+  }
+}
+
+/** Write a string to a file descriptor returned by openLogFile (no-op for "ignore"). */
+export function writeToLogFile(fd: number | "ignore", msg: string): void {
+  if (typeof fd === "number") {
+    try { writeSync(fd, msg); } catch { /* best-effort */ }
+  }
+}