@vellumai/cli 0.4.48 → 0.4.50

package/src/lib/http-client.ts

@@ -32,8 +32,7 @@ export function buildDaemonUrl(port: number): string {
  */
 export function readHttpToken(instanceDir?: string): string | undefined {
   const baseDataDir =
-    instanceDir ??
-    (process.env.BASE_DATA_DIR?.trim() || homedir());
+    instanceDir ?? (process.env.BASE_DATA_DIR?.trim() || homedir());
   const tokenPath = join(baseDataDir, ".vellum", "http-token");
   try {
     const token = readFileSync(tokenPath, "utf-8").trim();

package/src/lib/input-history.ts

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+const MAX_ENTRIES = 1000;
+
+function historyPath(): string {
+  return join(homedir(), ".vellum", "input-history");
+}
+
+export function loadHistory(): string[] {
+  try {
+    const path = historyPath();
+    if (!existsSync(path)) return [];
+    const content = readFileSync(path, "utf-8");
+    return content
+      .split("\n")
+      .filter((line) => line.length > 0)
+      .slice(-MAX_ENTRIES);
+  } catch {
+    return [];
+  }
+}
+
+export function appendHistory(entry: string): void {
+  const trimmed = entry.trim();
+  if (!trimmed || trimmed.startsWith("/")) return;
+  try {
+    const path = historyPath();
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const existing = loadHistory();
+    // Deduplicate: remove previous occurrence of the same entry
+    const deduped = existing.filter((e) => e !== trimmed);
+    deduped.push(trimmed);
+    // Keep only the last MAX_ENTRIES
+    const trimmedList = deduped.slice(-MAX_ENTRIES);
+    writeFileSync(path, trimmedList.join("\n") + "\n", { mode: 0o600 });
+  } catch {
+    // Best-effort persistence — don't crash on write failure
+  }
+}

package/src/lib/local.ts

@@ -10,10 +10,7 @@ import { createRequire } from "module";
 import { homedir, hostname, networkInterfaces, platform } from "os";
 import { dirname, join } from "path";
 
-import {
-  loadLatestAssistant,
-  type LocalInstanceResources,
-} from "./assistant-config.js";
+import { type LocalInstanceResources } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
 import { httpHealthCheck, waitForDaemonReady } from "./http-client.js";
 import { stopProcessByPidFile } from "./process.js";
@@ -244,11 +241,6 @@ async function startDaemonFromSource(
     ...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";
-  }
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
@@ -354,16 +346,6 @@ async function startDaemonWatchFromSource(
 }
 
 function resolveGatewayDir(): string {
-  const override = process.env.VELLUM_GATEWAY_DIR?.trim();
-  if (override) {
-    if (!isGatewaySourceDir(override)) {
-      throw new Error(
-        `VELLUM_GATEWAY_DIR is set to "${override}", but it is not a valid gateway source directory.`,
-      );
-    }
-    return override;
-  }
-
   // Source tree: cli/src/lib/ → ../../.. → repo root → gateway/
   const sourceDir = join(import.meta.dir, "..", "..", "..", "gateway");
   if (isGatewaySourceDir(sourceDir)) {
@@ -386,7 +368,7 @@ function resolveGatewayDir(): string {
     return dirname(pkgPath);
   } catch {
     throw new Error(
-      "Gateway not found. Ensure @vellumai/vellum-gateway is installed, run from the source tree, or set VELLUM_GATEWAY_DIR.",
+      "Gateway not found. Ensure @vellumai/vellum-gateway is installed or run from the source tree.",
     );
   }
 }
@@ -397,6 +379,79 @@ function normalizeIngressUrl(value: unknown): string | undefined {
   return normalized || undefined;
 }
 
+// ── Workspace config helpers ──
+
+function getWorkspaceConfigPath(instanceDir?: string): string {
+  const baseDataDir =
+    instanceDir ??
+    (process.env.BASE_DATA_DIR?.trim() || (process.env.HOME ?? homedir()));
+  return join(baseDataDir, ".vellum", "workspace", "config.json");
+}
+
+function loadWorkspaceConfig(instanceDir?: string): Record<string, unknown> {
+  const configPath = getWorkspaceConfigPath(instanceDir);
+  try {
+    if (!existsSync(configPath)) return {};
+    return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+      string,
+      unknown
+    >;
+  } catch {
+    return {};
+  }
+}
+
+function saveWorkspaceConfig(
+  config: Record<string, unknown>,
+  instanceDir?: string,
+): void {
+  const configPath = getWorkspaceConfigPath(instanceDir);
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+/**
+ * Write gateway operational settings to the workspace config file so the
+ * gateway reads them at startup via its config.ts readWorkspaceConfig().
+ */
+function writeGatewayConfig(
+  instanceDir?: string,
+  opts?: {
+    runtimeProxyEnabled?: boolean;
+    runtimeProxyRequireAuth?: boolean;
+    unmappedPolicy?: "reject" | "default";
+    defaultAssistantId?: string;
+    routingEntries?: Array<{
+      type: "conversation_id" | "actor_id";
+      key: string;
+      assistantId: string;
+    }>;
+  },
+): void {
+  const config = loadWorkspaceConfig(instanceDir);
+  const gateway = (config.gateway ?? {}) as Record<string, unknown>;
+
+  if (opts?.runtimeProxyEnabled !== undefined) {
+    gateway.runtimeProxyEnabled = opts.runtimeProxyEnabled;
+  }
+  if (opts?.runtimeProxyRequireAuth !== undefined) {
+    gateway.runtimeProxyRequireAuth = opts.runtimeProxyRequireAuth;
+  }
+  if (opts?.unmappedPolicy !== undefined) {
+    gateway.unmappedPolicy = opts.unmappedPolicy;
+  }
+  if (opts?.defaultAssistantId !== undefined) {
+    gateway.defaultAssistantId = opts.defaultAssistantId;
+  }
+  if (opts?.routingEntries !== undefined) {
+    gateway.routingEntries = opts.routingEntries;
+  }
+
+  config.gateway = gateway;
+  saveWorkspaceConfig(config, instanceDir);
+}
+
 function readWorkspaceIngressPublicBaseUrl(
   instanceDir?: string,
 ): string | undefined {
@@ -472,48 +527,29 @@ export async function discoverPublicUrl(
   port?: number,
 ): Promise<string | undefined> {
   const effectivePort = port ?? GATEWAY_PORT;
-  const cloud = process.env.VELLUM_CLOUD;
 
-  let externalIp: string | undefined;
+  // Discover local and cloud addresses in parallel so the cloud metadata
+  // timeout (1s) doesn't block startup when a local address is immediately
+  // available.
+  const cloudIpPromise = discoverCloudExternalIp();
 
-  // Try cloud-specific metadata services for GCP and AWS.
-  if (cloud === "gcp" || cloud === "aws") {
-    try {
-      if (cloud === "gcp") {
-        const resp = await fetch(
-          "http://169.254.169.254/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip",
-          { headers: { "Metadata-Flavor": "Google" } },
-        );
-        if (resp.ok) externalIp = (await resp.text()).trim();
-      } else if (cloud === "aws") {
-        // Use IMDSv2 (token-based) for compatibility with HttpTokens=required
-        const tokenResp = await fetch(
-          "http://169.254.169.254/latest/api/token",
-          {
-            method: "PUT",
-            headers: { "X-aws-ec2-metadata-token-ttl-seconds": "30" },
-          },
-        );
-        if (tokenResp.ok) {
-          const token = await tokenResp.text();
-          const ipResp = await fetch(
-            "http://169.254.169.254/latest/meta-data/public-ipv4",
-            { headers: { "X-aws-ec2-metadata-token": token } },
-          );
-          if (ipResp.ok) externalIp = (await ipResp.text()).trim();
-        }
-      }
-    } catch {
-      // metadata service not reachable
-    }
+  // Resolve local address synchronously (no I/O).
+  const localUrl = discoverLocalUrl(effectivePort);
 
-    if (externalIp) {
-      console.log(`   Discovered external IP: ${externalIp}`);
-      return `http://${externalIp}:${effectivePort}`;
-    }
+  const cloudIp = await cloudIpPromise;
+  if (cloudIp) {
+    console.log(`   Discovered external IP: ${cloudIp}`);
+    return `http://${cloudIp}:${effectivePort}`;
   }
 
-  // For local and custom environments, use the local LAN address.
+  return localUrl;
+}
+
+/**
+ * Resolve a LAN-reachable URL without any async I/O. Returns the best local
+ * address or falls back to localhost.
+ */
+function discoverLocalUrl(effectivePort: number): string {
   // On macOS, prefer the .local hostname (Bonjour/mDNS) so other devices on
   // the same network can reach the gateway by name.
   if (platform() === "darwin") {
@@ -534,6 +570,58 @@ export async function discoverPublicUrl(
   return `http://localhost:${effectivePort}`;
 }
 
+/**
+ * Attempt to discover the VM's external/public IP via cloud metadata services.
+ * Tries GCP and AWS IMDSv2 in parallel with a short timeout. Returns undefined
+ * on non-cloud machines (the metadata endpoint is unreachable).
+ */
+async function discoverCloudExternalIp(): Promise<string | undefined> {
+  const timeoutMs = 1000;
+
+  const gcpPromise = (async (): Promise<string | undefined> => {
+    try {
+      const resp = await fetch(
+        "http://169.254.169.254/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip",
+        {
+          headers: { "Metadata-Flavor": "Google" },
+          signal: AbortSignal.timeout(timeoutMs),
+        },
+      );
+      if (resp.ok) return (await resp.text()).trim() || undefined;
+    } catch {
+      // metadata service not reachable
+    }
+    return undefined;
+  })();
+
+  const awsPromise = (async (): Promise<string | undefined> => {
+    try {
+      const tokenResp = await fetch("http://169.254.169.254/latest/api/token", {
+        method: "PUT",
+        headers: { "X-aws-ec2-metadata-token-ttl-seconds": "30" },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (tokenResp.ok) {
+        const token = await tokenResp.text();
+        const ipResp = await fetch(
+          "http://169.254.169.254/latest/meta-data/public-ipv4",
+          {
+            headers: { "X-aws-ec2-metadata-token": token },
+            signal: AbortSignal.timeout(timeoutMs),
+          },
+        );
+        if (ipResp.ok) return (await ipResp.text()).trim() || undefined;
+      }
+    } catch {
+      // metadata service not reachable
+    }
+    return undefined;
+  })();
+
+  const [gcpIp, awsIp] = await Promise.all([gcpPromise, awsPromise]);
+  return gcpIp ?? awsIp;
+}
+
 /**
  * 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.
@@ -680,7 +768,6 @@ export async function startLocalDaemon(
       const daemonEnv: Record<string, string> = {
         HOME: process.env.HOME || homedir(),
         PATH: `${bunBinDir}:${basePath}`,
-        VELLUM_DAEMON_TCP_ENABLED: "1",
       };
       // Forward optional config env vars the daemon may need
       for (const key of [
@@ -689,10 +776,6 @@ export async function startLocalDaemon(
         "QDRANT_HTTP_PORT",
         "QDRANT_URL",
         "RUNTIME_HTTP_PORT",
-        "VELLUM_DAEMON_TCP_PORT",
-        "VELLUM_DAEMON_TCP_HOST",
-        "VELLUM_KEYCHAIN_BROKER_SOCKET",
-        "VELLUM_DEBUG",
         "SENTRY_DSN",
         "TMPDIR",
         "USER",
@@ -804,7 +887,6 @@ export async function startLocalDaemon(
 }
 
 export async function startGateway(
-  assistantId?: string,
   watch: boolean = false,
   resources?: LocalInstanceResources,
 ): Promise<string> {
@@ -827,118 +909,35 @@ export async function startGateway(
 
   console.log("🌐 Starting gateway...");
 
-  // Resolve the default assistant ID for the gateway. Prefer the explicitly
-  // provided assistantId (from hatch), then env override, then lockfile.
-  const resolvedAssistantId =
-    assistantId ||
-    process.env.GATEWAY_DEFAULT_ASSISTANT_ID ||
-    loadLatestAssistant()?.assistantId;
-
-  // Read the bearer token so the gateway can authenticate proxied requests
-  // (e.g. from paired iOS devices). Respect VELLUM_HTTP_TOKEN_PATH and
-  // BASE_DATA_DIR for consistency with gateway/config.ts and the daemon.
-  // When resources are provided, the token lives under the instance directory.
-  const httpTokenPath =
-    process.env.VELLUM_HTTP_TOKEN_PATH ??
-    (resources
-      ? join(resources.instanceDir, ".vellum", "http-token")
-      : join(
-          process.env.BASE_DATA_DIR?.trim() || homedir(),
-          ".vellum",
-          "http-token",
-        ));
-  let runtimeProxyBearerToken: string | undefined;
-  try {
-    const tok = readFileSync(httpTokenPath, "utf-8").trim();
-    if (tok) runtimeProxyBearerToken = tok;
-  } catch {
-    // Token file doesn't exist yet — daemon hasn't written it.
-  }
-
-  // If no token is available (first startup — daemon hasn't written it yet),
-  // poll for the file to appear. On fresh installs the daemon may take 60s+
-  // for Qdrant download, migrations, and first-time init. Starting the
-  // gateway without auth is a security risk since the config is loaded once
-  // at startup and never reloads, so we fail rather than silently disabling auth.
-  if (!runtimeProxyBearerToken) {
-    console.log("   Waiting for bearer token file...");
-    const maxWait = 60000;
-    const pollInterval = 500;
-    const start = Date.now();
-    const pidFile =
-      resources?.pidFile ??
-      join(
-        process.env.BASE_DATA_DIR?.trim() || homedir(),
-        ".vellum",
-        "vellum.pid",
-      );
-    while (Date.now() - start < maxWait) {
-      await new Promise((r) => setTimeout(r, pollInterval));
-      try {
-        const tok = readFileSync(httpTokenPath, "utf-8").trim();
-        if (tok) {
-          runtimeProxyBearerToken = tok;
-          break;
-        }
-      } catch {
-        // File still doesn't exist, keep polling.
-      }
-      // Check if the daemon process is still alive — no point waiting if it crashed
-      try {
-        const pid = parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
-        if (pid) process.kill(pid, 0); // throws if process doesn't exist
-      } catch {
-        break; // daemon process is gone
-      }
-    }
-  }
-
-  if (!runtimeProxyBearerToken) {
-    throw new Error(
-      `Bearer token file not found at ${httpTokenPath} after 60s.\n` +
-        "  The gateway cannot start without authentication — this would leave the proxy permanently unauthenticated.\n" +
-        "  Ensure the daemon is running and has written the token file, or set VELLUM_HTTP_TOKEN_PATH to the correct path.",
-    );
-  }
   const effectiveDaemonPort =
     resources?.daemonPort ?? Number(process.env.RUNTIME_HTTP_PORT || "7821");
 
+  // Write gateway operational settings to workspace config before starting
+  // the gateway process. The gateway reads these at startup from config.json.
+  writeGatewayConfig(resources?.instanceDir, {
+    runtimeProxyEnabled: true,
+    runtimeProxyRequireAuth: true,
+    unmappedPolicy: "default",
+    defaultAssistantId: "self",
+  });
+
   const gatewayEnv: Record<string, string> = {
     ...(process.env as Record<string, string>),
-    GATEWAY_RUNTIME_PROXY_ENABLED: "true",
-    GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH: "true",
-    RUNTIME_PROXY_BEARER_TOKEN: runtimeProxyBearerToken,
     RUNTIME_HTTP_PORT: String(effectiveDaemonPort),
     GATEWAY_PORT: String(effectiveGatewayPort),
-    // Skip the drain window for locally-launched gateways — there is no load
-    // balancer draining connections, so waiting serves no purpose and causes
-    // `vellum sleep` to SIGKILL the gateway when the CLI timeout is shorter
-    // than the drain window.  Respect an explicit env override.
-    GATEWAY_SHUTDOWN_DRAIN_MS: process.env.GATEWAY_SHUTDOWN_DRAIN_MS || "0",
     ...(watch ? { VELLUM_DEV: "1" } : {}),
     // Set BASE_DATA_DIR so the gateway loads the correct signing key and
     // credentials for this instance (mirrors the daemon env setup).
     ...(resources ? { BASE_DATA_DIR: resources.instanceDir } : {}),
   };
-
-  if (process.env.GATEWAY_UNMAPPED_POLICY) {
-    gatewayEnv.GATEWAY_UNMAPPED_POLICY = process.env.GATEWAY_UNMAPPED_POLICY;
-  } else {
-    gatewayEnv.GATEWAY_UNMAPPED_POLICY = "default";
-  }
-
-  if (resolvedAssistantId) {
-    gatewayEnv.GATEWAY_DEFAULT_ASSISTANT_ID = resolvedAssistantId;
-  }
+  // The gateway reads the ingress URL from the workspace config file via
+  // ConfigFileCache — no env var passthrough needed. Log the resolved value
+  // for diagnostic visibility during startup.
   const workspaceIngressPublicBaseUrl = readWorkspaceIngressPublicBaseUrl(
     resources?.instanceDir,
   );
-  const ingressPublicBaseUrl =
-    workspaceIngressPublicBaseUrl ??
-    normalizeIngressUrl(process.env.INGRESS_PUBLIC_BASE_URL) ??
-    publicUrl;
+  const ingressPublicBaseUrl = workspaceIngressPublicBaseUrl ?? publicUrl;
   if (ingressPublicBaseUrl) {
-    gatewayEnv.INGRESS_PUBLIC_BASE_URL = ingressPublicBaseUrl;
     console.log(`   Ingress URL: ${ingressPublicBaseUrl}`);
   }
 
@@ -1048,8 +1047,8 @@ export async function stopLocalProcesses(
   await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
 
   // Kill ngrok directly by PID rather than using stopProcessByPidFile, because
-  // isVellumProcess() checks for /vellum|@vellumai|--vellum-gateway/ which
-  // won't match the ngrok binary — resulting in a no-op that leaves ngrok running.
+  // isVellumProcess() won't match the ngrok binary — resulting in a no-op that
+  // leaves ngrok running.
   const ngrokPidFile = join(vellumDir, "ngrok.pid");
   if (existsSync(ngrokPidFile)) {
     try {

package/src/lib/orphan-detection.ts

@@ -13,13 +13,23 @@ export interface RemoteProcess {
 export function classifyProcess(command: string): string {
   if (/qdrant/.test(command)) return "qdrant";
   if (/vellum-gateway/.test(command)) return "gateway";
-  if (/openclaw/.test(command)) return "openclaw-adapter";
+  if (
+    /vellum-openclaw-adapter|openclaw-runtime-server|openclaw-http-server/.test(
+      command,
+    )
+  )
+    return "openclaw-adapter";
   if (/vellum-daemon/.test(command)) return "assistant";
   if (/daemon\s+(start|restart)/.test(command)) return "assistant";
+  if (/vellum-cli/.test(command)) return "vellum";
   // Exclude macOS desktop app processes — their path contains .app/Contents/MacOS/
   // but they are not background service processes.
   if (/\.app\/Contents\/MacOS\//.test(command)) return "unknown";
-  if (/vellum/.test(command)) return "vellum";
+  // Match vellum CLI commands (e.g. "vellum hatch", "vellum sleep") but NOT
+  // unrelated processes whose working directory or repo path happens to contain
+  // "vellum" (e.g. /Users/runner/work/vellum-assistant/vellum-assistant/...).
+  // We require a word boundary before "vellum" to avoid matching repo paths.
+  if (/(?:^|\/)vellum(?:\s|$)/.test(command)) return "vellum";
   return "unknown";
 }
 
@@ -83,7 +93,7 @@ export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
   try {
     const output = await execOutput("sh", [
       "-c",
-      "ps ax -o pid=,ppid=,args= | grep -E 'vellum|vellum-gateway|qdrant|openclaw' | grep -v grep",
+      "ps ax -o pid=,ppid=,args= | grep -E 'vellum|qdrant|openclaw' | grep -v grep",
     ]);
     const procs = parseRemotePs(output);
     const ownPid = String(process.pid);

package/src/lib/process.ts

@@ -13,7 +13,9 @@ function isVellumProcess(pid: number): boolean {
       timeout: 3000,
       stdio: ["ignore", "pipe", "ignore"],
     }).trim();
-    return /vellum|@vellumai|--vellum-gateway/.test(output);
+    return /vellum-daemon|vellum-cli|vellum-gateway|@vellumai|\/vellum\/|\/daemon\/main/.test(
+      output,
+    );
   } catch {
     return false;
   }

package/src/lib/terminal-capabilities.ts

@@ -0,0 +1,133 @@
+/**
+ * Terminal capability detection module.
+ *
+ * Detects color support, unicode availability, and terminal dimensions
+ * by inspecting TERM, COLORTERM, NO_COLOR, and related environment
+ * variables. Designed to enable graceful degradation on dumb terminals
+ * and constrained environments (e.g. SSH to a Raspberry Pi).
+ */
+
+export type ColorLevel = "none" | "basic" | "256" | "truecolor";
+
+export interface TerminalCapabilities {
+  /** Detected color support level */
+  colorLevel: ColorLevel;
+  /** Whether the terminal likely supports unicode glyphs */
+  unicodeSupported: boolean;
+  /** Current terminal width in columns (falls back to 80) */
+  columns: number;
+  /** Current terminal rows (falls back to 24) */
+  rows: number;
+  /** True when TERM=dumb — indicates a terminal with no cursor addressing */
+  isDumb: boolean;
+}
+
+/**
+ * Detect the color support level from environment variables.
+ *
+ * Precedence (highest to lowest):
+ *   1. NO_COLOR or TERM=dumb  → "none"
+ *   2. COLORTERM=truecolor / 24bit → "truecolor"
+ *   3. TERM contains "256color" → "256"
+ *   4. Any other interactive terminal → "basic"
+ *   5. Non-TTY → "none"
+ */
+function detectColorLevel(env: NodeJS.ProcessEnv): ColorLevel {
+  // NO_COLOR spec: https://no-color.org/
+  if (env.NO_COLOR !== undefined) return "none";
+
+  const term = (env.TERM ?? "").toLowerCase();
+  if (term === "dumb") return "none";
+
+  const colorterm = (env.COLORTERM ?? "").toLowerCase();
+
+  if (colorterm === "truecolor" || colorterm === "24bit") return "truecolor";
+  if (term.includes("256color")) return "256";
+
+  // If we have a TERM value at all, assume basic color support
+  if (term.length > 0) return "basic";
+
+  // Fallback: if stdout is a TTY, assume basic
+  if (process.stdout.isTTY) return "basic";
+
+  return "none";
+}
+
+/**
+ * Heuristic for unicode support.
+ *
+ * Checks LANG / LC_ALL / LC_CTYPE for UTF-8. Falls back to false on
+ * dumb terminals since many dumb terminal emulators lack glyph support.
+ */
+function detectUnicode(env: NodeJS.ProcessEnv, isDumb: boolean): boolean {
+  if (isDumb) return false;
+
+  const locale = (env.LC_ALL ?? env.LC_CTYPE ?? env.LANG ?? "").toLowerCase();
+
+  return locale.includes("utf-8") || locale.includes("utf8");
+}
+
+/**
+ * Detect terminal capabilities from the current process environment.
+ *
+ * The result is a plain object (no singletons) so tests can call this
+ * with a mocked env if needed.
+ */
+export function detectCapabilities(
+  env: NodeJS.ProcessEnv = process.env,
+): TerminalCapabilities {
+  const term = (env.TERM ?? "").toLowerCase();
+  const isDumb = term === "dumb";
+  const colorLevel = detectColorLevel(env);
+  const unicodeSupported = detectUnicode(env, isDumb);
+
+  return {
+    colorLevel,
+    unicodeSupported,
+    columns: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+    isDumb,
+  };
+}
+
+/** Lazily-cached capabilities for the current process. */
+let _cached: TerminalCapabilities | undefined;
+
+/**
+ * Return (and cache) the terminal capabilities for the running process.
+ *
+ * Safe to call multiple times — subsequent calls return the cached
+ * result. Use `detectCapabilities()` directly if you need a fresh read
+ * (e.g. after a terminal resize).
+ */
+export function getTerminalCapabilities(): TerminalCapabilities {
+  if (!_cached) {
+    _cached = detectCapabilities();
+  }
+  return _cached;
+}
+
+/**
+ * Clear the cached capabilities so the next `getTerminalCapabilities()`
+ * call re-detects from the current environment. Useful after modifying
+ * `process.env.NO_COLOR` at startup or in tests.
+ */
+export function resetCapabilitiesCache(): void {
+  _cached = undefined;
+}
+
+// ── Convenience helpers ──────────────────────────────────────
+
+/** True when colors should be used (any level above "none"). */
+export function supportsColor(): boolean {
+  return getTerminalCapabilities().colorLevel !== "none";
+}
+
+/**
+ * Return `fancy` when unicode is supported, otherwise `fallback`.
+ *
+ * Example: `unicodeOrFallback("🟢", "[ok]")`
+ */
+export function unicodeOrFallback(fancy: string, fallback: string): string {
+  return getTerminalCapabilities().unicodeSupported ? fancy : fallback;
+}

package/src/lib/xdg-log.ts

@@ -49,14 +49,14 @@ export function resetLogFile(name: string): void {
 /**
  * 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.
+ * file is missing or empty, or when `destDir` does not already exist.
  */
 export function archiveLogFile(name: string, destDir: string): void {
   try {
+    if (!existsSync(destDir)) return;
     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`));