@vellumai/cli 0.8.0 → 0.8.1

package/package.json

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

package/src/__tests__/orphan-detection.test.ts

@@ -0,0 +1,287 @@
+import { describe, test, expect, beforeEach, afterAll } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Point lockfile operations at a temp directory before importing anything that
+// would otherwise resolve real on-host paths.
+const testDir = mkdtempSync(join(tmpdir(), "cli-orphan-detection-test-"));
+process.env.VELLUM_LOCKFILE_DIR = testDir;
+
+import {
+  detectOrphanedProcesses,
+  getKnownPidsFromAssistants,
+} from "../lib/orphan-detection.js";
+import {
+  loadAllAssistantsAcrossEnvs,
+  type AssistantEntry,
+} from "../lib/assistant-config.js";
+import type { EnvironmentDefinition } from "../lib/environments/types.js";
+
+afterAll(() => {
+  rmSync(testDir, { recursive: true, force: true });
+  delete process.env.VELLUM_LOCKFILE_DIR;
+});
+
+function makeLocalEntry(
+  id: string,
+  instanceDir: string,
+  pids: {
+    daemon?: string;
+    gateway?: string;
+    qdrant?: string;
+    embed?: string;
+  } = {},
+): AssistantEntry {
+  const vellumDir = join(instanceDir, ".vellum");
+  mkdirSync(join(vellumDir, "workspace", "data", "qdrant"), {
+    recursive: true,
+  });
+  if (pids.daemon !== undefined) {
+    writeFileSync(join(vellumDir, "workspace", "vellum.pid"), pids.daemon);
+  }
+  if (pids.gateway !== undefined) {
+    writeFileSync(join(vellumDir, "gateway.pid"), pids.gateway);
+  }
+  if (pids.qdrant !== undefined) {
+    writeFileSync(
+      join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid"),
+      pids.qdrant,
+    );
+  }
+  if (pids.embed !== undefined) {
+    writeFileSync(join(vellumDir, "workspace", "embed-worker.pid"), pids.embed);
+  }
+  return {
+    assistantId: id,
+    runtimeUrl: "http://localhost:7821",
+    cloud: "local",
+    resources: {
+      instanceDir,
+      daemonPort: 7821,
+      gatewayPort: 7830,
+      qdrantPort: 6333,
+      cesPort: 8090,
+    },
+  };
+}
+
+describe("getKnownPidsFromAssistants", () => {
+  let perTestDir: string;
+
+  beforeEach(() => {
+    perTestDir = mkdtempSync(join(testDir, "case-"));
+  });
+
+  test("collects daemon, gateway, qdrant, and embed-worker PIDs", () => {
+    const entry = makeLocalEntry(
+      "alpha",
+      join(perTestDir, "alpha"),
+      { daemon: "100", gateway: "200", qdrant: "300", embed: "400" },
+    );
+    const pids = getKnownPidsFromAssistants([entry]);
+    expect(pids).toEqual(new Set(["100", "200", "300", "400"]));
+  });
+
+  test("skips missing PID files without throwing", () => {
+    const entry = makeLocalEntry("beta", join(perTestDir, "beta"), {
+      daemon: "100",
+    });
+    const pids = getKnownPidsFromAssistants([entry]);
+    expect(pids).toEqual(new Set(["100"]));
+  });
+
+  test("includes docker watcherPid when present", () => {
+    const entry: AssistantEntry = {
+      assistantId: "docker-1",
+      runtimeUrl: "http://localhost:18100",
+      cloud: "docker",
+      watcherPid: 555,
+    };
+    const pids = getKnownPidsFromAssistants([entry]);
+    expect(pids).toEqual(new Set(["555"]));
+  });
+
+  test("ignores non-local entries without watcherPid", () => {
+    const entry: AssistantEntry = {
+      assistantId: "managed-1",
+      runtimeUrl: "https://platform.vellum.ai/foo",
+      cloud: "vellum",
+    };
+    const pids = getKnownPidsFromAssistants([entry]);
+    expect(pids.size).toBe(0);
+  });
+
+  test("local entry without resources contributes no PIDs", () => {
+    const entry: AssistantEntry = {
+      assistantId: "legacy",
+      runtimeUrl: "http://localhost:7821",
+      cloud: "local",
+    };
+    const pids = getKnownPidsFromAssistants([entry]);
+    expect(pids.size).toBe(0);
+  });
+
+  test("aggregates PIDs across multiple assistants", () => {
+    const a = makeLocalEntry("a", join(perTestDir, "a"), {
+      daemon: "100",
+      gateway: "200",
+    });
+    const b = makeLocalEntry("b", join(perTestDir, "b"), {
+      daemon: "101",
+      gateway: "201",
+    });
+    const pids = getKnownPidsFromAssistants([a, b]);
+    expect(pids).toEqual(new Set(["100", "200", "101", "201"]));
+  });
+});
+
+describe("loadAllAssistantsAcrossEnvs", () => {
+  function makeEnv(name: string, lockfileDir: string): EnvironmentDefinition {
+    return {
+      name,
+      platformUrl: "https://example.invalid",
+      webUrl: "https://example.invalid",
+      lockfileDirOverride: lockfileDir,
+    };
+  }
+
+  test("aggregates entries from every provided environment's lockfile", () => {
+    const envADir = mkdtempSync(join(testDir, "envA-"));
+    const envBDir = mkdtempSync(join(testDir, "envB-"));
+
+    writeFileSync(
+      join(envADir, "lockfile.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "alpha",
+            runtimeUrl: "http://localhost:7821",
+            cloud: "local",
+          },
+        ],
+      }),
+    );
+    writeFileSync(
+      join(envBDir, "lockfile.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "beta",
+            runtimeUrl: "http://localhost:18100",
+            cloud: "docker",
+            watcherPid: 777,
+          },
+        ],
+      }),
+    );
+
+    const all = loadAllAssistantsAcrossEnvs([
+      makeEnv("envA", envADir),
+      makeEnv("envB", envBDir),
+    ]);
+    const ids = all.map((e) => e.assistantId).sort();
+    expect(ids).toEqual(["alpha", "beta"]);
+  });
+
+  test("returns empty list when no envs have lockfiles", () => {
+    const envDir = mkdtempSync(join(testDir, "empty-"));
+    const all = loadAllAssistantsAcrossEnvs([makeEnv("missing", envDir)]);
+    expect(all).toEqual([]);
+  });
+
+  test("skips malformed JSON without throwing", () => {
+    const envDir = mkdtempSync(join(testDir, "malformed-"));
+    writeFileSync(join(envDir, "lockfile.json"), "{not json");
+    const all = loadAllAssistantsAcrossEnvs([makeEnv("bad", envDir)]);
+    expect(all).toEqual([]);
+  });
+
+  test("skips entries missing required fields", () => {
+    const envDir = mkdtempSync(join(testDir, "partial-"));
+    writeFileSync(
+      join(envDir, "lockfile.json"),
+      JSON.stringify({
+        assistants: [
+          { assistantId: "no-url" }, // missing runtimeUrl
+          { runtimeUrl: "http://x" }, // missing assistantId
+          {
+            assistantId: "good",
+            runtimeUrl: "http://localhost:7821",
+            cloud: "local",
+          },
+        ],
+      }),
+    );
+    const all = loadAllAssistantsAcrossEnvs([makeEnv("partial", envDir)]);
+    expect(all.map((e) => e.assistantId)).toEqual(["good"]);
+  });
+
+  test("end-to-end: dev env's daemon is not flagged as orphan from local env", () => {
+    // Simulate Vargas's reported bug: `local` env has no assistants, but a
+    // `dev` env assistant is running with a recorded daemon PID. The orphan
+    // filter must treat that PID as known.
+    const devDir = mkdtempSync(join(testDir, "dev-"));
+    const instanceDir = join(devDir, "instances", "quiet-finch");
+    makeLocalEntry("quiet-finch", instanceDir, {
+      daemon: "19067",
+      gateway: "19087",
+      qdrant: "19167",
+    });
+
+    writeFileSync(
+      join(devDir, "lockfile.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "quiet-finch",
+            runtimeUrl: "http://127.0.0.1:18100",
+            cloud: "local",
+            resources: {
+              instanceDir,
+              daemonPort: 18000,
+              gatewayPort: 18100,
+              qdrantPort: 18200,
+              cesPort: 18300,
+            },
+          },
+        ],
+      }),
+    );
+
+    const devEntries = loadAllAssistantsAcrossEnvs([makeEnv("dev", devDir)]);
+    expect(devEntries).toHaveLength(1);
+
+    const knownPids = getKnownPidsFromAssistants(devEntries);
+    expect(knownPids).toEqual(new Set(["19067", "19087", "19167"]));
+  });
+});
+
+describe("detectOrphanedProcesses", () => {
+  test("excludes PIDs passed via excludePids", async () => {
+    // The orphan detector calls `ps ax` and filters by regex. The process
+    // running this test (bun) is itself a node-family process whose pid will
+    // not match the vellum/qdrant/openclaw regex, so the natural result of
+    // the scan is "no rows". To assert exclusion semantics deterministically,
+    // we just confirm the function accepts an excludePids option and returns
+    // an array — the meaningful behavior assertion lives in the integration
+    // path (the function's `knownPids.has(p.pid)` short-circuit), which we
+    // exercise indirectly by passing our own PID (guaranteed to never be
+    // double-counted).
+    const ownPid = String(process.pid);
+    const result = await detectOrphanedProcesses({
+      excludePids: new Set([ownPid]),
+    });
+    expect(Array.isArray(result)).toBe(true);
+    for (const orphan of result) {
+      expect(orphan.pid).not.toBe(ownPid);
+    }
+  });
+
+  test("returns an array (smoke)", async () => {
+    const result = await detectOrphanedProcesses({
+      excludePids: new Set(),
+    });
+    expect(Array.isArray(result)).toBe(true);
+  });
+});

package/src/__tests__/ps-platform-status.test.ts

@@ -0,0 +1,182 @@
+import { afterAll, afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Temp directory for lockfile isolation
+// ---------------------------------------------------------------------------
+
+const testDir = mkdtempSync(join(tmpdir(), "cli-ps-platform-status-test-"));
+process.env.VELLUM_LOCKFILE_DIR = testDir;
+
+// ---------------------------------------------------------------------------
+// Mocks — set up before importing the command under test. All spies are
+// restored in afterAll so we don't leak module state to neighbouring suites.
+// ---------------------------------------------------------------------------
+
+import * as assistantConfig from "../lib/assistant-config.js";
+import * as orphanDetection from "../lib/orphan-detection.js";
+import * as platformClient from "../lib/platform-client.js";
+
+const loadAllAssistantsMock = spyOn(
+  assistantConfig,
+  "loadAllAssistants",
+).mockReturnValue([]);
+const getActiveAssistantMock = spyOn(
+  assistantConfig,
+  "getActiveAssistant",
+).mockReturnValue(null);
+const detectOrphanedProcessesMock = spyOn(
+  orphanDetection,
+  "detectOrphanedProcesses",
+).mockResolvedValue([]);
+const getPlatformUrlMock = spyOn(
+  platformClient,
+  "getPlatformUrl",
+).mockReturnValue("http://platform.test");
+
+// Per-test toggle for `readPlatformToken`.
+const readPlatformTokenMock = spyOn(
+  platformClient,
+  "readPlatformToken",
+).mockReturnValue(null);
+
+// `fetchCurrentUser` + `fetchPlatformAssistants` are spied so we can assert
+// they're never invoked on the no-token path, and re-shaped per-test for the
+// token-but-unreachable path.
+const fetchCurrentUserMock = spyOn(
+  platformClient,
+  "fetchCurrentUser",
+).mockResolvedValue({
+  id: "u1",
+  email: "test@example.com",
+  display: "Test",
+});
+const fetchPlatformAssistantsMock = spyOn(
+  platformClient,
+  "fetchPlatformAssistants",
+).mockResolvedValue([]);
+
+// ---------------------------------------------------------------------------
+// stdout / stderr capture
+// ---------------------------------------------------------------------------
+
+let stdout: string[];
+let stderr: string[];
+let originalLog: typeof console.log;
+let originalError: typeof console.error;
+
+beforeEach(() => {
+  stdout = [];
+  stderr = [];
+  originalLog = console.log;
+  originalError = console.error;
+  console.log = ((...args: unknown[]) => {
+    stdout.push(args.map((a) => String(a)).join(" "));
+  }) as typeof console.log;
+  console.error = ((...args: unknown[]) => {
+    stderr.push(args.map((a) => String(a)).join(" "));
+  }) as typeof console.error;
+});
+
+afterEach(() => {
+  console.log = originalLog;
+  console.error = originalError;
+  readPlatformTokenMock.mockReturnValue(null);
+  fetchCurrentUserMock.mockReset();
+  fetchCurrentUserMock.mockResolvedValue({
+    id: "u1",
+    email: "test@example.com",
+    display: "Test",
+  });
+  fetchPlatformAssistantsMock.mockReset();
+  fetchPlatformAssistantsMock.mockResolvedValue([]);
+});
+
+afterAll(() => {
+  loadAllAssistantsMock.mockRestore();
+  getActiveAssistantMock.mockRestore();
+  detectOrphanedProcessesMock.mockRestore();
+  getPlatformUrlMock.mockRestore();
+  readPlatformTokenMock.mockRestore();
+  fetchCurrentUserMock.mockRestore();
+  fetchPlatformAssistantsMock.mockRestore();
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// Import the command under test AFTER mocks are wired up
+// ---------------------------------------------------------------------------
+
+import { listAllAssistants } from "../commands/ps.js";
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("vellum ps — platform status line", () => {
+  test("no local token: prints 'Platform: not logged in' and skips ALL network fetches", async () => {
+    readPlatformTokenMock.mockReturnValue(null);
+
+    await listAllAssistants(false);
+
+    // The status line is present, exactly once, with no redundant error log.
+    expect(stdout.filter((l) => l.startsWith("Platform:"))).toEqual([
+      "Platform: not logged in",
+    ]);
+    expect(
+      stderr.some((l) => l.includes("Failed to fetch organization")),
+    ).toBe(false);
+    expect(
+      stdout.some((l) => l.includes("Failed to fetch organization")),
+    ).toBe(false);
+
+    // Structural guarantee: we never even tried to talk to the platform.
+    expect(fetchCurrentUserMock).not.toHaveBeenCalled();
+    expect(fetchPlatformAssistantsMock).not.toHaveBeenCalled();
+  });
+
+  test("local token present but platform is unreachable: still shows 'Platform: not logged in' with no leaked org-fetch error", async () => {
+    readPlatformTokenMock.mockReturnValue("session_abc123");
+    // Simulate the exact Bun connect failure the user reported:
+    //   "Unable to connect. Is the computer able to access the url?"
+    const connectError = new Error(
+      "Unable to connect. Is the computer able to access the url?",
+    );
+    fetchCurrentUserMock.mockRejectedValue(connectError);
+    fetchPlatformAssistantsMock.mockRejectedValue(connectError);
+
+    await listAllAssistants(false);
+
+    expect(stdout.filter((l) => l.startsWith("Platform:"))).toEqual([
+      "Platform: not logged in",
+    ]);
+    expect(
+      stderr.some((l) => l.includes("Failed to fetch organization")),
+    ).toBe(false);
+    expect(
+      stdout.some((l) => l.includes("Failed to fetch organization")),
+    ).toBe(false);
+    expect(
+      stderr.some((l) => l.includes("Unable to connect")),
+    ).toBe(false);
+  });
+
+  test("local token present and platform reachable: prints 'Platform: logged in as <email>'", async () => {
+    readPlatformTokenMock.mockReturnValue("session_abc123");
+    fetchCurrentUserMock.mockResolvedValue({
+      id: "u1",
+      email: "vargas@vellum.ai",
+      display: "Vargas",
+    });
+    fetchPlatformAssistantsMock.mockResolvedValue([]);
+
+    await listAllAssistants(false);
+
+    expect(stdout).toContain("Platform: logged in as vargas@vellum.ai");
+    expect(
+      stderr.some((l) => l.includes("Failed to fetch organization")),
+    ).toBe(false);
+  });
+});

package/src/__tests__/search-provider-env-var-parity.test.ts

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import { SEARCH_PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
+
+/**
+ * Drift guard for the CLI-side search provider env-var mirror.
+ *
+ * `cli/src/shared/provider-env-vars.ts` hardcodes the search env-var names so
+ * the CLI doesn't need to import the assistant's
+ * `SEARCH_PROVIDER_CATALOG` (no CLI → assistant cross-package imports exist).
+ * This test pulls the catalog JSON at `meta/web-search-provider-catalog.json`
+ * — which is kept in sync with `SEARCH_PROVIDER_CATALOG` by
+ * `assistant/src/__tests__/web-search-catalog-parity.test.ts` — and asserts
+ * the CLI's mirror matches the catalog's `envVar` entries.
+ *
+ * Mirrors `llm-provider-env-var-parity.test.ts`.
+ */
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
+
+interface SearchCatalogEntry {
+  id: string;
+  kind: "managed" | "byok";
+  envVar?: string;
+}
+
+interface SearchCatalog {
+  version: number;
+  providers: SearchCatalogEntry[];
+}
+
+function loadSearchCatalog(): SearchCatalog {
+  const path = join(REPO_ROOT, "meta", "web-search-provider-catalog.json");
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+describe("CLI search provider env-var parity", () => {
+  test("SEARCH_PROVIDER_ENV_VAR_NAMES matches meta/web-search-provider-catalog.json entries with envVar", () => {
+    const catalog = loadSearchCatalog();
+    const expected: Record<string, string> = {};
+    for (const provider of catalog.providers) {
+      if (provider.envVar) expected[provider.id] = provider.envVar;
+    }
+    expect(SEARCH_PROVIDER_ENV_VAR_NAMES).toEqual(expected);
+  });
+});

package/src/__tests__/sync-events.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, spyOn, test } from "bun:test";
+
+import { renderMarkdown } from "../commands/events.js";
+
+type AssistantEvent = Parameters<typeof renderMarkdown>[0];
+
+function makeEvent(message: AssistantEvent["message"]): AssistantEvent {
+  return {
+    id: "event-123",
+    assistantId: "assistant-123",
+    emittedAt: "2026-01-01T00:00:00.000Z",
+    message,
+  };
+}
+
+describe("sync_changed events", () => {
+  test("renders sync tags clearly in vellum events markdown output", () => {
+    const consoleLog = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      renderMarkdown(
+        makeEvent({
+          type: "sync_changed",
+          tags: ["assistant:self:avatar", "conversations:list"],
+        }),
+      );
+
+      expect(consoleLog).toHaveBeenCalledWith(
+        "\n> **Sync changed:** `assistant:self:avatar`, `conversations:list`",
+      );
+    } finally {
+      consoleLog.mockRestore();
+    }
+  });
+
+  test("tolerates malformed sync tags without throwing", () => {
+    const consoleLog = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      expect(() =>
+        renderMarkdown(
+          makeEvent({
+            type: "sync_changed",
+            tags: ["assistant:self:avatar", 42, null],
+          }),
+        ),
+      ).not.toThrow();
+
+      expect(consoleLog).toHaveBeenCalledWith(
+        "\n> **Sync changed:** `assistant:self:avatar`",
+      );
+    } finally {
+      consoleLog.mockRestore();
+    }
+  });
+});

package/src/commands/client.ts

@@ -1,4 +1,6 @@
-import { hostname } from "os";
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
 
 import {
   findAssistantByName,
@@ -14,6 +16,7 @@ import { loadGuardianToken } from "../lib/guardian-token";
 import { getLocalLanIPv4 } from "../lib/local";
 import {
   CLI_INTERFACE_ID,
+  WEB_INTERFACE_ID,
   getClientRegistrationHeaders,
 } from "../lib/client-identity";
 import {
@@ -22,7 +25,7 @@ import {
 } from "../lib/platform-client";
 import { tuiLog } from "../lib/tui-log";
 
-const SUPPORTED_INTERFACES = ["cli"] as const;
+const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
 
 const ANSI = {
@@ -133,12 +136,6 @@ function parseArgs(): ParsedArgs {
       assistantId = flagArgs[++i];
     } else if ((flag === "--interface" || flag === "-i") && flagArgs[i + 1]) {
       const value = flagArgs[++i];
-      if (value === "web") {
-        console.error(
-          `--interface web is not yet supported. Coming soon.`,
-        );
-        process.exit(1);
-      }
       if (!(SUPPORTED_INTERFACES as readonly string[]).includes(value)) {
         console.error(
           `Unknown interface '${value}'. Supported: ${SUPPORTED_INTERFACES.join(", ")}.`,
@@ -213,7 +210,7 @@ ${ANSI.bold}ARGUMENTS:${ANSI.reset}
 ${ANSI.bold}OPTIONS:${ANSI.reset}
     -u, --url <url>            Runtime URL
     -a, --assistant-id <id>    Assistant ID
-    -i, --interface <id>       Interface identifier (default: cli)
+    -i, --interface <id>       Interface identifier: cli (default) or web
     -h, --help                 Show this help message
 
 ${ANSI.bold}DEFAULTS:${ANSI.reset}
@@ -228,6 +225,66 @@ ${ANSI.bold}EXAMPLES:${ANSI.reset}
 `);
 }
 
+/**
+ * Walk up from this file's location to find a sibling `clients/web` package.
+ *
+ * Returns the absolute path to its directory, or null when not found —
+ * e.g. when the CLI is installed via npm/bunx, where the `clients/web`
+ * source isn't shipped alongside `@vellumai/cli`. For now we treat the
+ * `--interface web` path as source-checkout-only.
+ */
+function findClientsWebDir(): string | null {
+  let dir = import.meta.dir;
+  for (let depth = 0; depth < 8; depth++) {
+    const candidate = path.join(dir, "clients", "web", "package.json");
+    if (existsSync(candidate)) {
+      return path.dirname(candidate);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Spawn the `clients/web` package's `local` script and proxy its lifecycle.
+ *
+ * The web client is deliberately not declared as a dependency of `@vellumai/cli`:
+ * the CLI is published, the web package is not. Locating it on disk and
+ * shelling out keeps the two packages independent.
+ */
+async function runWebInterface(): Promise<void> {
+  const webDir = findClientsWebDir();
+  if (!webDir) {
+    console.error(
+      `${ANSI.bold}--interface web${ANSI.reset}: unable to locate ` +
+        `clients/web. This interface currently requires running ` +
+        `vellum from a source checkout of vellum-assistant.`,
+    );
+    process.exit(1);
+  }
+
+  const child = Bun.spawn({
+    cmd: ["bun", "run", "local"],
+    cwd: webDir,
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+
+  const forward = (signal: "SIGINT" | "SIGTERM"): void => {
+    try {
+      child.kill(signal);
+    } catch {
+      // Child already exited; nothing to forward.
+    }
+  };
+  process.on("SIGINT", () => forward("SIGINT"));
+  process.on("SIGTERM", () => forward("SIGTERM"));
+
+  const exitCode = await child.exited;
+  process.exit(typeof exitCode === "number" ? exitCode : 0);
+}
+
 export async function client(): Promise<void> {
   const {
     runtimeUrl,
@@ -241,6 +298,11 @@ export async function client(): Promise<void> {
     zone,
   } = parseArgs();
 
+  if (interfaceId === WEB_INTERFACE_ID) {
+    await runWebInterface();
+    return;
+  }
+
   tuiLog.init();
   tuiLog.info("session start", {
     runtimeUrl,

package/src/commands/events.ts

@@ -49,13 +49,14 @@ interface AssistantEvent {
     content?: string;
     message?: string;
     chunk?: string;
+    tags?: unknown;
     conversationId?: string;
     [key: string]: unknown;
   };
 }
 
 /** Render an event as human-readable markdown to stdout. */
-function renderMarkdown(event: AssistantEvent): void {
+export function renderMarkdown(event: AssistantEvent): void {
   const msg = event.message;
   switch (msg.type) {
     case "assistant_text_delta":
@@ -94,6 +95,17 @@ function renderMarkdown(event: AssistantEvent): void {
     case "user_message_echo":
       console.log(`\n**You:** ${msg.text}`);
       break;
+    case "sync_changed": {
+      const tags = Array.isArray(msg.tags)
+        ? msg.tags.filter((tag): tag is string => typeof tag === "string")
+        : [];
+      const renderedTags =
+        tags.length > 0
+          ? tags.map((tag) => `\`${tag}\``).join(", ")
+          : "(no tags)";
+      console.log(`\n> **Sync changed:** ${renderedTags}`);
+      break;
+    }
     default:
       // Silently skip events that don't have a markdown representation
       // (e.g. heartbeat comments, activity states, etc.)

package/src/commands/login.ts

@@ -287,9 +287,10 @@ export async function login(): Promise<void> {
 
     // Sync cloud assistants from the platform into the local lockfile.
     // This ensures `vellum ps` shows managed assistants immediately
-    // after login (e.g. after a retire-and-rehatch cycle).
+    // after login (e.g. after a retire-and-rehatch cycle). We've just
+    // saved this token, so it's guaranteed non-empty here.
     try {
-      const result = await syncCloudAssistants();
+      const result = await syncCloudAssistants(token);
       if (result) {
         const total = result.added + result.removed;
         if (total > 0) {

package/src/commands/ps.ts

@@ -15,6 +15,7 @@ import {
   fetchManagedPs,
   type ManagedProcessEntry,
 } from "../lib/health-check";
+import { readPlatformToken } from "../lib/platform-client";
 import { dockerResourceNames } from "../lib/docker";
 import { existsSync } from "fs";
 import {
@@ -472,7 +473,7 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
 
 // ── List all assistants (no arg) ────────────────────────────────
 
-async function listAllAssistants(verbose: boolean): Promise<void> {
+export async function listAllAssistants(verbose: boolean): Promise<void> {
   const { name: envName, source: envSource } = resolveEnvironmentSource();
   const sourceLabels: Record<typeof envSource, string> = {
     flag: "--environment flag",
@@ -486,23 +487,33 @@ async function listAllAssistants(verbose: boolean): Promise<void> {
     ? (msg) => console.log(`  [verbose] ${msg}`)
     : undefined;
 
-  // Refresh cloud assistants from the platform before listing.
-  const syncResult = await syncCloudAssistants({ log });
-
-  // Show platform login status
-  if (syncResult) {
-    const parts = [`Platform: logged in`];
-    if (syncResult.email) parts[0] += ` as ${syncResult.email}`;
-    if (syncResult.added > 0 || syncResult.removed > 0) {
-      const changes: string[] = [];
-      if (syncResult.added > 0) changes.push(`${syncResult.added} added`);
-      if (syncResult.removed > 0)
-        changes.push(`${syncResult.removed} removed`);
-      parts.push(`(${changes.join(", ")})`);
-    }
-    console.log(parts.join(" "));
-  } else {
+  // Decide platform login status FIRST, before touching the network. With no
+  // local token we never enter the platform fetch path — so unreachable-host
+  // errors from the org-ID/user lookups can't leak onto stderr ahead of the
+  // "Platform: not logged in" line.
+  const platformToken = readPlatformToken();
+  if (!platformToken) {
+    log?.("No platform token found — skipping cloud sync");
     console.log("Platform: not logged in");
+  } else {
+    const syncResult = await syncCloudAssistants(platformToken, { log });
+    if (syncResult) {
+      const parts = [`Platform: logged in`];
+      if (syncResult.email) parts[0] += ` as ${syncResult.email}`;
+      if (syncResult.added > 0 || syncResult.removed > 0) {
+        const changes: string[] = [];
+        if (syncResult.added > 0) changes.push(`${syncResult.added} added`);
+        if (syncResult.removed > 0)
+          changes.push(`${syncResult.removed} removed`);
+        parts.push(`(${changes.join(", ")})`);
+      }
+      console.log(parts.join(" "));
+    } else {
+      // We had a token but the platform fetch failed (offline, expired, etc.).
+      // Treat it the same as "not logged in" from a UX perspective — the user
+      // can't reach cloud-managed assistants right now either way.
+      console.log("Platform: not logged in");
+    }
   }
   console.log("");
 

package/src/components/DefaultMainScreen.tsx

@@ -333,6 +333,8 @@ interface SseEvent {
   allowedDomains?: string[];
   // message_complete fields
   source?: "main" | "aux";
+  // sync_changed fields
+  tags?: string[];
   [key: string]: unknown;
 }
 
@@ -1856,6 +1858,11 @@ function ChatApp({
                 hRef.setBusy(false);
                 break;
 
+              case "sync_changed":
+                // The interactive CLI does not currently keep any sync-tagged
+                // caches, so generic invalidations are intentionally ignored.
+                break;
+
               default:
                 // Ignore events we don't handle (activity state, traces, etc.)
                 break;
@@ -2265,15 +2272,7 @@ function ChatApp({
       // racing with SSE events that may arrive during the sendMessage await.
       h.showSpinner("Working...");
     },
-    [
-      runtimeUrl,
-      assistantId,
-      auth,
-      project,
-      zone,
-      cleanup,
-      ensureConnected,
-    ],
+    [runtimeUrl, assistantId, auth, project, zone, cleanup, ensureConnected],
   );
 
   const handleSubmit = useCallback(

package/src/lib/__tests__/docker.test.ts

@@ -128,6 +128,17 @@ describe("buildServiceRunArgs — gateway", () => {
       buildGatewayArgs().some((arg) => arg.startsWith("VELAY_BASE_URL=")),
     ).toBe(false);
   });
+
+  test("forces gateway to run as uid 0 so it can connect to the assistant's root-owned IPC socket (mirrors K8s securityContext.runAsUser=0)", () => {
+    const args = buildGatewayArgs();
+    const userIdx = args.indexOf("--user");
+    expect(userIdx).toBeGreaterThan(-1);
+    expect(args[userIdx + 1]).toBe("0");
+  });
+
+  test("assistant container does NOT get a --user override (image USER root wins)", () => {
+    expect(buildAssistantArgs().includes("--user")).toBe(false);
+  });
 });
 
 describe("VELLUM_AVATAR_DEVICE passthrough", () => {

package/src/lib/assistant-config.ts

@@ -18,6 +18,8 @@ import {
   getMultiInstanceDir,
 } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
+import { SEEDS } from "./environments/seeds.js";
+import type { EnvironmentDefinition } from "./environments/types.js";
 import { probePort } from "./port-probe.js";
 
 /**
@@ -327,6 +329,69 @@ export function loadAllAssistants(): AssistantEntry[] {
   return readAssistants();
 }
 
+/**
+ * Read the first existing lockfile for an explicitly-provided environment,
+ * without applying legacy migrations. This is the cross-env read path used by
+ * {@link loadAllAssistantsAcrossEnvs}: it deliberately bypasses
+ * {@link readLockfile} (which always resolves the *current* env) so callers
+ * can enumerate state from every env without flipping `process.env` or the
+ * persisted default. Migrations are skipped because we never want to write
+ * to another env's lockfile from the current env's process.
+ */
+function readLockfileForEnv(env: EnvironmentDefinition): LockfileData {
+  for (const lockfilePath of getLockfilePaths(env)) {
+    if (!existsSync(lockfilePath)) continue;
+    try {
+      const raw = readFileSync(lockfilePath, "utf-8");
+      const parsed = JSON.parse(raw) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as LockfileData;
+      }
+    } catch {
+      // Malformed; try next candidate
+    }
+  }
+  return {};
+}
+
+/**
+ * Load assistant entries from every known environment's lockfile.
+ *
+ * Each {@link SEEDS} entry has its own on-host data layout (config dir,
+ * lockfile path, data dir). A running assistant from `dev` is invisible to
+ * `loadAllAssistants()` when the current env is `local`, but its host
+ * processes (daemon/gateway/qdrant) still show up in `ps ax`. The orphan
+ * detector and `vellum clean` need the union of all envs' entries to avoid
+ * misclassifying — or worse, killing — another env's running services.
+ *
+ * Optional `envs` override is provided for testability so call sites can
+ * inject a curated env list with `lockfileDirOverride` set, without having
+ * to manipulate the global SEEDS table or process.env.
+ */
+export function loadAllAssistantsAcrossEnvs(
+  envs?: EnvironmentDefinition[],
+): AssistantEntry[] {
+  const envList = envs ?? Object.values(SEEDS).map((env) => ({ ...env }));
+  const all: AssistantEntry[] = [];
+  for (const env of envList) {
+    const data = readLockfileForEnv(env);
+    const entries = data.assistants;
+    if (!Array.isArray(entries)) continue;
+    for (const raw of entries) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+      const entry = raw as AssistantEntry;
+      if (
+        typeof entry.assistantId !== "string" ||
+        typeof entry.runtimeUrl !== "string"
+      ) {
+        continue;
+      }
+      all.push(entry);
+    }
+  }
+  return all;
+}
+
 export function getActiveAssistant(): string | null {
   const data = readLockfile();
   return data.activeAssistant ?? null;

package/src/lib/client-identity.ts

@@ -12,6 +12,7 @@ import { homedir } from "os";
 import { join } from "path";
 
 export const CLI_INTERFACE_ID = "cli";
+export const WEB_INTERFACE_ID = "web";
 
 let cached: string | null = null;
 

package/src/lib/orphan-detection.ts

@@ -1,5 +1,11 @@
 import { existsSync, readFileSync } from "fs";
+import { join } from "path";
 
+import {
+  getDaemonPidPath,
+  loadAllAssistantsAcrossEnvs,
+  type AssistantEntry,
+} from "./assistant-config.js";
 import { execOutput } from "./step-runner";
 
 export interface RemoteProcess {
@@ -67,10 +73,68 @@ export interface OrphanedProcess {
   source: string;
 }
 
-export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
+/**
+ * Collect PIDs that belong to a known assistant in any environment.
+ *
+ * For local entries this reads the daemon/gateway/qdrant/embed-worker PID
+ * files under each entry's `instanceDir`. For docker entries we include the
+ * `watcherPid` field when present (the file watcher runs as a host process,
+ * unlike the containers themselves). Other cloud topologies don't have
+ * host-side processes that show up in `ps ax`.
+ *
+ * This set is the basis for filtering the orphan list: if a running process
+ * matches a recorded PID for *any* env's assistant, it's not an orphan.
+ */
+export function getKnownPidsFromAssistants(
+  entries: AssistantEntry[],
+): Set<string> {
+  const pids = new Set<string>();
+  for (const entry of entries) {
+    if (entry.cloud === "local" && entry.resources) {
+      const vellumDir = join(entry.resources.instanceDir, ".vellum");
+      const candidates = [
+        getDaemonPidPath(entry.resources),
+        join(vellumDir, "gateway.pid"),
+        join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid"),
+        join(vellumDir, "workspace", "embed-worker.pid"),
+      ];
+      for (const file of candidates) {
+        const pid = readPidFile(file);
+        if (pid) pids.add(pid);
+      }
+    }
+    if (typeof entry.watcherPid === "number") {
+      pids.add(String(entry.watcherPid));
+    }
+  }
+  return pids;
+}
+
+export interface DetectOrphansOptions {
+  /**
+   * Set of PIDs to treat as known and exclude from the orphan list. When
+   * omitted, defaults to the union of every env's recorded assistant PIDs
+   * via {@link loadAllAssistantsAcrossEnvs} +
+   * {@link getKnownPidsFromAssistants}. Tests can inject an explicit set to
+   * avoid touching the real on-host lockfiles.
+   */
+  excludePids?: Set<string>;
+}
+
+export async function detectOrphanedProcesses(
+  options: DetectOrphansOptions = {},
+): Promise<OrphanedProcess[]> {
   const results: OrphanedProcess[] = [];
   const seenPids = new Set<string>();
 
+  // PIDs that belong to a known assistant in *any* environment are not
+  // orphans. Without this filter, running `vellum ps` from an env that has
+  // no assistants — or `vellum clean` from any env — would flag (or kill)
+  // another env's healthy services as orphans.
+  const knownPids =
+    options.excludePids ??
+    getKnownPidsFromAssistants(loadAllAssistantsAcrossEnvs());
+
   // Process table scan — discover orphaned processes by scanning the OS
   // process table rather than reading PID files from the workspace.
   try {
@@ -83,6 +147,7 @@ export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
 
     for (const p of procs) {
       if (p.pid === ownPid || seenPids.has(p.pid)) continue;
+      if (knownPids.has(p.pid)) continue;
       const type = classifyProcess(p.command);
       if (type === "unknown") continue;
       results.push({ name: type, pid: p.pid, source: "process table" });

package/src/lib/platform-client.ts

@@ -129,9 +129,12 @@ export function invalidateOrgIdCache(
  * The org ID is cached per (token, platformUrl) for 60 seconds to avoid
  * redundant HTTP requests in tight polling loops.
  *
- * Auth errors (401 / 403) from the org-ID fetch are logged with a
- * user-friendly message before re-throwing, so callers don't need to
- * repeat that logic.
+ * Auth errors (401 / 403) from the org-ID fetch are wrapped in a
+ * user-friendly Error message before re-throwing, so callers can surface
+ * a useful message without doing their own classification. Callers that
+ * handle the throw (e.g. `syncCloudAssistants`) stay silent on stderr;
+ * callers that let it bubble get a single clean line from the top-level
+ * runner.
  */
 export async function authHeaders(
   token: string,
@@ -163,11 +166,9 @@ export async function authHeaders(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("401") || msg.includes("403")) {
-      console.error("Authentication failed. Run 'vellum login' to refresh.");
-    } else {
-      console.error(`Failed to fetch organization: ${msg}`);
+      throw new Error("Authentication failed. Run 'vellum login' to refresh.");
     }
-    throw err;
+    throw new Error(`Failed to fetch organization: ${msg}`);
   }
 }
 

package/src/lib/statefulset.ts

@@ -99,6 +99,11 @@ export interface DockerContainerSpec {
   ports?: PortSpec[];
   env: EnvEntry[];
   volumeMounts: VolumeMount[];
+  /**
+   * Optional `--user` override for `docker run`. Mirrors K8s
+   * `securityContext.runAsUser`. Omitted ⇒ image's `USER` directive wins.
+   */
+  user?: string;
 }
 
 export interface DockerVolumeClaimTemplate {
@@ -168,6 +173,7 @@ export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
         { kind: "static", name: "DEBUG_STDOUT_LOGS",         value: "1" },
         { kind: "static", name: "VELLUM_CLOUD",              value: "docker" },
         { kind: "static", name: "RUNTIME_HTTP_HOST",         value: "0.0.0.0" },
+        { kind: "static", name: "RUNTIME_HTTP_PORT",         value: `${ASSISTANT_INTERNAL_PORT}` },
         { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
         { kind: "static", name: "VELLUM_BACKUP_DIR",         value: "/workspace/.backups" },
         { kind: "static", name: "VELLUM_BACKUP_KEY_PATH",    value: "/workspace/.backup.key" },
@@ -196,6 +202,7 @@ export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
       name: "gateway-sidecar",
       internalName: "gateway",
       network: "container",
+      user: "0",
       env: [
         { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
         { kind: "static", name: "GATEWAY_SECURITY_DIR",      value: "/gateway-security" },
@@ -300,6 +307,11 @@ export function buildServiceRunArgs(
             : res.cesContainer;
       args.push("--name", containerName);
 
+      // User override (mirrors K8s securityContext.runAsUser)
+      if (container.user !== undefined) {
+        args.push("--user", container.user);
+      }
+
       // Network
       if (container.network === "bridge") {
         args.push(`--network=${res.network}`);

package/src/lib/sync-cloud-assistants.ts

@@ -6,6 +6,11 @@
  *   (e.g. retired assistants).
  *
  * Used by both `vellum login` and `vellum ps` to keep the lockfile fresh.
+ *
+ * **Contract:** callers must verify the user is logged in (i.e. a non-empty
+ * platform token exists) before invoking this helper. The "is there a token?"
+ * decision belongs at the command level so commands can render the right
+ * "Platform: …" status without ever entering the platform fetch path.
  */
 
 import {
@@ -17,7 +22,6 @@ import {
   fetchCurrentUser,
   fetchPlatformAssistants,
   getPlatformUrl,
-  readPlatformToken,
 } from "./platform-client.js";
 
 export type SyncLogger = (message: string) => void;
@@ -34,21 +38,24 @@ export interface SyncOptions {
 
 /**
  * Fetch platform assistants and reconcile against the lockfile.
- * Returns the number of entries added/removed, or `null` if the user
- * is not logged in or the fetch fails.
+ *
+ * Returns the number of entries added/removed, or `null` if the fetch fails
+ * (e.g. platform unreachable, invalid token). Callers must pre-verify a
+ * non-empty token; this function assumes one is present and will throw if
+ * called with an empty string.
  */
 export async function syncCloudAssistants(
+  token: string,
   options?: SyncOptions,
 ): Promise<SyncResult | null> {
+  if (!token) {
+    throw new Error(
+      "syncCloudAssistants called without a token. Callers must check `readPlatformToken()` first.",
+    );
+  }
   const log = options?.log;
   const platformUrl = getPlatformUrl();
   log?.(`Platform URL: ${platformUrl}`);
-
-  const token = readPlatformToken();
-  if (!token) {
-    log?.("No platform token found — skipping cloud sync");
-    return null;
-  }
   log?.(
     `Token found (${token.length} chars, prefix: ${token.slice(0, 6)}…)`,
   );

package/src/lib/upgrade-lifecycle.ts

@@ -18,7 +18,6 @@ import {
 import { getStateDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { loadGuardianToken } from "./guardian-token.js";
-import { getPlatformUrl } from "./platform-client.js";
 import { resolveImageRefs } from "./platform-releases.js";
 import { exec, execOutput } from "./step-runner.js";
 import { compareVersions } from "./version-compat.js";
@@ -481,42 +480,6 @@ export async function performDockerRollback(
   console.log("🔍 Resolving image references...");
   const { imageTags: targetImageTags } = await resolveImageRefs(targetVersion);
 
-  // Fetch target migration ceiling from releases API
-  let targetMigrationCeiling: {
-    dbVersion?: number;
-    workspaceMigrationId?: string;
-  } = {};
-  try {
-    const platformUrl = getPlatformUrl();
-    const releasesResp = await fetch(
-      `${platformUrl}/v1/releases/?stable=true`,
-      { signal: AbortSignal.timeout(10000) },
-    );
-    if (releasesResp.ok) {
-      const releases = (await releasesResp.json()) as Array<{
-        version: string;
-        db_migration_version?: number | null;
-        last_workspace_migration_id?: string;
-      }>;
-      const normalizedTag = targetVersion.replace(/^v/, "");
-      const targetRelease = releases.find(
-        (r) => r.version?.replace(/^v/, "") === normalizedTag,
-      );
-      if (
-        targetRelease?.db_migration_version != null ||
-        targetRelease?.last_workspace_migration_id
-      ) {
-        targetMigrationCeiling = {
-          dbVersion: targetRelease.db_migration_version ?? undefined,
-          workspaceMigrationId:
-            targetRelease.last_workspace_migration_id || undefined,
-        };
-      }
-    }
-  } catch {
-    // Best-effort — fall back to rollbackToRegistryCeiling post-swap
-  }
-
   // Capture current image digests for auto-rollback on failure
   console.log("📸 Capturing current image references for rollback...");
   const currentImageRefs = await captureImageRefs(res);
@@ -702,26 +665,6 @@ export async function performDockerRollback(
   }
   console.log("✅ Docker images pulled\n");
 
-  // Pre-swap migration rollback to target ceiling on the CURRENT (newer) daemon
-  let preSwapRollbackOk = true;
-  if (
-    targetMigrationCeiling.dbVersion !== undefined ||
-    targetMigrationCeiling.workspaceMigrationId !== undefined
-  ) {
-    console.log("🔄 Reverting database changes...");
-    await broadcastUpgradeEvent(
-      entry.runtimeUrl,
-      entry.assistantId,
-      buildProgressEvent(UPGRADE_PROGRESS.REVERTING_MIGRATIONS),
-    );
-    preSwapRollbackOk = await rollbackMigrations(
-      entry.runtimeUrl,
-      entry.assistantId,
-      targetMigrationCeiling.dbVersion,
-      targetMigrationCeiling.workspaceMigrationId,
-    );
-  }
-
   // Progress: switching version
   await broadcastUpgradeEvent(
     entry.runtimeUrl,
@@ -757,22 +700,15 @@ export async function performDockerRollback(
   if (ready) {
     // Success path
 
-    // Post-swap migration rollback fallback: if pre-swap rollback failed
-    // or no ceiling metadata was available, ask the now-running old daemon
-    // to roll back migrations above its own registry ceiling.
-    if (
-      !preSwapRollbackOk ||
-      (targetMigrationCeiling.dbVersion === undefined &&
-        targetMigrationCeiling.workspaceMigrationId === undefined)
-    ) {
-      await rollbackMigrations(
-        entry.runtimeUrl,
-        entry.assistantId,
-        undefined,
-        undefined,
-        true,
-      );
-    }
+    // Post-swap migration rollback: ask the now-running old daemon to roll
+    // back any migrations above its own registry ceiling.
+    await rollbackMigrations(
+      entry.runtimeUrl,
+      entry.assistantId,
+      undefined,
+      undefined,
+      true,
+    );
 
     // Capture new digests from the rolled-back containers
     const newDigests = await captureImageRefs(res);

package/src/shared/provider-env-vars.ts

@@ -1,13 +1,16 @@
 /**
  * Provider API key environment variable names, keyed by provider ID.
  *
- * Two sources are merged into a single combined map:
+ * Two sources are merged into a single combined map. Both are locally-
+ * maintained mirrors of canonical catalogs in `assistant/src/providers/`
+ * — the CLI does not import from `assistant/src/`, so drift is caught by
+ * dedicated parity tests:
  *
- *   1. Search-provider env vars — hardcoded below (Brave, Perplexity).
- *   2. LLM-provider env vars — sourced from `PROVIDER_CATALOG` in
- *      `assistant/src/providers/model-catalog.ts` via a locally-maintained
- *      mirror (the CLI does not import from `assistant/src/`; drift is caught
- *      by `cli/src/__tests__/llm-provider-env-var-parity.test.ts`).
+ *   1. LLM-provider env vars — mirrors `PROVIDER_CATALOG` entries with an
+ *      `envVar`. Drift guard: `cli/src/__tests__/llm-provider-env-var-parity.test.ts`.
+ *   2. Search-provider env vars — mirrors `SEARCH_PROVIDER_CATALOG`
+ *      entries with an `envVar`. Drift guard:
+ *      `cli/src/__tests__/search-provider-env-var-parity.test.ts`.
  *
  * The combined map is what cloud-infra code (docker.ts, aws.ts, gcp.ts)
  * iterates to forward provider API keys from the caller's environment into
@@ -25,10 +28,11 @@ export const LLM_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   openrouter: "OPENROUTER_API_KEY",
 };
 
-/** Search-provider env var names. */
+/** Search-provider env var names. Mirrors `SEARCH_PROVIDER_CATALOG` BYOK entries. */
 export const SEARCH_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
-  brave: "BRAVE_API_KEY",
   perplexity: "PERPLEXITY_API_KEY",
+  brave: "BRAVE_API_KEY",
+  tavily: "TAVILY_API_KEY",
 };
 
 /**