@vellumai/cli 0.6.2 → 0.6.4

package/src/lib/environments/paths.ts

@@ -0,0 +1,110 @@
+import { homedir } from "os";
+import { join } from "path";
+
+import type { EnvironmentDefinition, PortMap } from "./types.js";
+
+const PRODUCTION_ENVIRONMENT_NAME = "production";
+
+/**
+ * Production lockfile filenames in priority order. The current name is
+ * `.vellum.lock.json`; `.vellum.lockfile.json` is the legacy name kept for
+ * backward compatibility with installs that predate the rename.
+ */
+const PRODUCTION_LOCKFILE_NAMES = [
+  ".vellum.lock.json",
+  ".vellum.lockfile.json",
+] as const;
+
+const DEFAULT_PORTS: Readonly<PortMap> = {
+  daemon: 7821,
+  gateway: 7830,
+  qdrant: 6333,
+  ces: 8090,
+  outboundProxy: 8080,
+  tcp: 8765,
+};
+
+/**
+ * Config directory for an environment.
+ * Production preserves the existing `~/.config/vellum/` location;
+ * non-production environments use `$XDG_CONFIG_HOME/vellum-<env>/`.
+ */
+export function getConfigDir(env: EnvironmentDefinition): string {
+  if (env.configDirOverride) return env.configDirOverride;
+  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
+    return join(xdgConfigHome(), "vellum");
+  }
+  return join(xdgConfigHome(), `vellum-${env.name}`);
+}
+
+/**
+ * Lockfile candidate paths for an environment, in priority order.
+ *
+ * For production, returns both the current `.vellum.lock.json` and the
+ * legacy `.vellum.lockfile.json` so read-side callers can fall back to the
+ * legacy filename on installs that predate the rename. Non-production
+ * environments are new and have a single canonical path under the env-scoped
+ * XDG config directory.
+ *
+ * Read-side callers should iterate this array and use the first existing
+ * file (matching `cli/src/lib/assistant-config.ts:readLockfile`). Write-side
+ * callers should use {@link getLockfilePath}, which returns the first
+ * (canonical) entry.
+ *
+ * `env.lockfileDirOverride` (populated by the resolver from
+ * `VELLUM_LOCKFILE_DIR`) overrides the directory the lockfile lives in for
+ * both production and non-production environments.
+ */
+export function getLockfilePaths(env: EnvironmentDefinition): string[] {
+  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
+    const dir = env.lockfileDirOverride ?? homedir();
+    return PRODUCTION_LOCKFILE_NAMES.map((name) => join(dir, name));
+  }
+  const dir = env.lockfileDirOverride ?? getConfigDir(env);
+  return [join(dir, "lockfile.json")];
+}
+
+/**
+ * Canonical lockfile path for writes. For production this is the current
+ * `.vellum.lock.json` (legacy reads handled by {@link getLockfilePaths}).
+ */
+export function getLockfilePath(env: EnvironmentDefinition): string {
+  return getLockfilePaths(env)[0]!;
+}
+
+/**
+ * Multi-instance root directory for an environment. Production uses
+ * `~/.local/share/vellum/assistants/` — the convention already in
+ * `cli/src/lib/assistant-config.ts`. Non-production environments use
+ * `~/.local/share/vellum-<env>/assistants/`.
+ */
+export function getMultiInstanceDir(env: EnvironmentDefinition): string {
+  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
+    return join(xdgDataHome(), "vellum", "assistants");
+  }
+  return join(xdgDataHome(), `vellum-${env.name}`, "assistants");
+}
+
+/**
+ * Default port set for an environment. Phase 5 (per-env port offsets) was
+ * deferred from MVP — this currently returns the same ports for every
+ * environment. Per-env specialization lands in a later phase without
+ * changing the function signature or call sites. `env.portsOverride` is
+ * merged on top of the defaults when set.
+ */
+export function getDefaultPorts(env: EnvironmentDefinition): PortMap {
+  return {
+    ...DEFAULT_PORTS,
+    ...(env.portsOverride ?? {}),
+  };
+}
+
+function xdgDataHome(): string {
+  return (
+    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share")
+  );
+}
+
+function xdgConfigHome(): string {
+  return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+}

package/src/lib/environments/resolve.ts

@@ -0,0 +1,96 @@
+import { SEEDS } from "./seeds.js";
+import type { EnvironmentDefinition } from "./types.js";
+
+const DEFAULT_ENVIRONMENT_NAME = "production";
+
+/**
+ * Look up a seed entry by name. Returns `undefined` if no seed matches.
+ * Callers that need the full resolution stack (env-var overrides, default
+ * fallback, error on unknown) should use {@link getCurrentEnvironment}
+ * instead. The returned definition is a shallow copy so mutations by the
+ * caller don't leak back into the seed table.
+ */
+export function getSeed(name: string): EnvironmentDefinition | undefined {
+  const seed = SEEDS[name];
+  if (!seed) return undefined;
+  return { ...seed };
+}
+
+/**
+ * Resolve the current environment definition.
+ *
+ * Priority:
+ *   1. `override` argument (from a `--environment` CLI flag, when wired)
+ *   2. `VELLUM_ENVIRONMENT` env var
+ *   3. (future) user context file
+ *   4. Default: `production`
+ *
+ * Per-field env-var overrides are honored on the resolved definition as
+ * ad-hoc escape hatches (they do not materialize new environments):
+ *   - `VELLUM_PLATFORM_URL` overrides `platformUrl`
+ *   - `VELLUM_ASSISTANT_PLATFORM_URL` overrides `assistantPlatformUrl`
+ *   - `VELLUM_LOCKFILE_DIR` overrides `lockfileDirOverride` (legacy e2e
+ *     test hook)
+ *
+ * This function should be the single entrypoint for environment resolution.
+ * No other code should drive off `VELLUM_ENVIRONMENT` directly.
+ */
+export function getCurrentEnvironment(
+  override?: string,
+): EnvironmentDefinition {
+  const name = resolveEnvironmentName(override);
+  const seed = SEEDS[name];
+  if (!seed) {
+    if (name !== DEFAULT_ENVIRONMENT_NAME) {
+      // Warn on stderr instead of throwing, to match the silent-fallback
+      // behavior in assistant/src/util/platform.ts:getXdgVellumConfigDirName
+      // and clients/shared/App/VellumEnvironment.swift:current. Those two
+      // silently fall back to production; the CLI should agree so all three
+      // writers don't end up in disjoint states on a typo.
+      process.stderr.write(
+        `warning: unknown environment "${name}"; falling back to "${DEFAULT_ENVIRONMENT_NAME}". ` +
+          `Add it to cli/src/lib/environments/seeds.ts and rebuild if this was intentional.\n`,
+      );
+    }
+    const fallback = SEEDS[DEFAULT_ENVIRONMENT_NAME];
+    if (!fallback) {
+      throw new Error(
+        `fatal: default environment "${DEFAULT_ENVIRONMENT_NAME}" missing from seed table — this is a build error`,
+      );
+    }
+    return { ...fallback };
+  }
+
+  const resolved: EnvironmentDefinition = { ...seed };
+
+  const platformUrlOverride = process.env.VELLUM_PLATFORM_URL?.trim();
+  if (platformUrlOverride) {
+    resolved.platformUrl = platformUrlOverride;
+  }
+
+  const assistantPlatformUrlOverride =
+    process.env.VELLUM_ASSISTANT_PLATFORM_URL?.trim();
+  if (assistantPlatformUrlOverride) {
+    resolved.assistantPlatformUrl = assistantPlatformUrlOverride;
+  }
+
+  const lockfileDirOverride = process.env.VELLUM_LOCKFILE_DIR?.trim();
+  if (lockfileDirOverride) {
+    resolved.lockfileDirOverride = lockfileDirOverride;
+  }
+
+  return resolved;
+}
+
+function resolveEnvironmentName(override: string | undefined): string {
+  const trimmedOverride = override?.trim();
+  if (trimmedOverride && trimmedOverride.length > 0) {
+    return trimmedOverride;
+  }
+  const envVar = process.env.VELLUM_ENVIRONMENT?.trim();
+  if (envVar && envVar.length > 0) {
+    return envVar;
+  }
+
+  return DEFAULT_ENVIRONMENT_NAME;
+}

package/src/lib/environments/seeds.ts

@@ -0,0 +1,46 @@
+import type { EnvironmentDefinition } from "./types.js";
+
+/**
+ * Built-in environment definitions. Mirrors Swift's
+ * `clients/macos/vellum-assistant/App/VellumEnvironment.swift` enum and is
+ * the TS-side source of truth for the set of known environment names.
+ * Two other TS sites duplicate the name list:
+ *   - `assistant/src/util/platform.ts` (`KNOWN_ENVIRONMENTS`)
+ *   - `clients/chrome-extension/native-host/src/lockfile.ts`
+ *     (`NON_PRODUCTION_ENVIRONMENTS`, excludes `production`)
+ * Drift between these three sites is caught at test time by
+ * `cli/src/__tests__/env-drift.test.ts`. Fast follow: hoist the shared
+ * list into a `packages/environments` package so all three sites import
+ * from one place.
+ *
+ * Custom environments via a user config file are a future phase — see the
+ * "Coexisting environments" design doc. Until then, a call site that needs a
+ * new environment must add it here and rebuild.
+ */
+export const SEEDS: Record<string, EnvironmentDefinition> = {
+  production: {
+    name: "production",
+    platformUrl: "https://platform.vellum.ai",
+  },
+  staging: {
+    name: "staging",
+    platformUrl: "https://staging-platform.vellum.ai",
+  },
+  test: {
+    name: "test",
+    // Non-functional URL — used only by unit tests for URL resolution, never
+    // hit in production.
+    platformUrl: "https://test-platform.vellum.ai",
+  },
+  dev: {
+    name: "dev",
+    platformUrl: "https://dev-platform.vellum.ai",
+  },
+  local: {
+    name: "local",
+    platformUrl: "http://localhost:8000",
+    // assistantPlatformUrl: "http://host.docker.internal:8000",
+    // ^ uncomment this once dockerized hatch path is live.
+    // The assistant runs in a different network namespace than the host.
+  },
+};

package/src/lib/environments/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Environment type definitions. Environments are deployment targets with
+ * their own platform backend and their own isolated on-host state. See the
+ * "Coexisting environments" design doc for the full model.
+ */
+
+/**
+ * Per-service default port set. Phase 5 (per-environment port offsets) is
+ * deferred from MVP, so today every environment uses the same port set. The
+ * shape exists so the rest of the stack can call `getDefaultPorts(env)` and
+ * gain per-env offsets later without changing any call sites.
+ */
+export interface PortMap {
+  daemon: number;
+  gateway: number;
+  qdrant: number;
+  ces: number;
+  outboundProxy: number;
+  tcp: number;
+}
+
+/**
+ * A resolved environment definition. Required fields are `name` and
+ * `platformUrl`. All other fields are optional and declared upfront — new
+ * fields are additive, never breaking. `name` is intentionally typed as
+ * `string` (not `keyof SEEDS`) so custom environments can be represented by
+ * future layers (user config file, ad-hoc env vars, etc.).
+ */
+export interface EnvironmentDefinition {
+  name: string;
+  platformUrl: string;
+
+  /**
+   * Override for the platform URL the assistant process itself uses. Only
+   * differs from `platformUrl` when the assistant runs in a different network
+   * namespace than the host (e.g. Docker on macOS, where the host's localhost
+   * is reached via `host.docker.internal`). Falls back to `platformUrl` when
+   * unset.
+   */
+  assistantPlatformUrl?: string;
+
+  /** Human-readable label for UI surfaces. */
+  displayName?: string;
+
+  /** Hint for UI surfaces that want to tint or badge their display. */
+  tintColor?: string;
+
+  /** Per-service port overrides merged on top of defaults. */
+  portsOverride?: Partial<PortMap>;
+
+  /** Override for the XDG config directory. */
+  configDirOverride?: string;
+
+  /**
+   * Override for the directory containing the lockfile. Populated by the
+   * resolver from `VELLUM_LOCKFILE_DIR` (an existing e2e test escape hatch)
+   * so path helpers don't read env vars directly.
+   */
+  lockfileDirOverride?: string;
+}

package/src/lib/gcp.ts

@@ -503,7 +503,18 @@ export async function hatchGcp(
       }
     }
 
-    const sshUser = userInfo().username;
+    let sshUser: string;
+    try {
+      sshUser = userInfo().username;
+    } catch {
+      sshUser = process.env.USER ?? "";
+    }
+    if (!sshUser) {
+      console.error(
+        "Error: Could not determine SSH username. Set the USER environment variable and try again.",
+      );
+      process.exit(1);
+    }
     const hatchedBy = process.env.VELLUM_HATCHED_BY;
     const providerApiKeys: Record<string, string> = {};
     for (const [, envVar] of Object.entries(PROVIDER_ENV_VAR_NAMES)) {

package/src/lib/guardian-token.ts

@@ -7,9 +7,12 @@ import {
   readFileSync,
   writeFileSync,
 } from "fs";
-import { homedir, platform } from "os";
+import { platform } from "os";
 import { dirname, join } from "path";
 
+import { getConfigDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
+
 const DEVICE_ID_SALT = "vellum-assistant-host-id";
 
 export interface GuardianTokenData {
@@ -24,14 +27,9 @@ export interface GuardianTokenData {
   leasedAt: string;
 }
 
-function getXdgConfigHome(): string {
-  return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
-}
-
 function getGuardianTokenPath(assistantId: string): string {
   return join(
-    getXdgConfigHome(),
-    "vellum",
+    getConfigDir(getCurrentEnvironment()),
     "assistants",
     assistantId,
     "guardian-token.json",
@@ -39,7 +37,7 @@ function getGuardianTokenPath(assistantId: string): string {
 }
 
 function getPersistedDeviceIdPath(): string {
-  return join(getXdgConfigHome(), "vellum", "device-id");
+  return join(getConfigDir(getCurrentEnvironment()), "device-id");
 }
 
 function hashWithSalt(input: string): string {
@@ -82,7 +80,7 @@ function getWindowsMachineGuid(): string | null {
   }
 }
 
-function getOrCreatePersistedDeviceId(): string {
+export function getOrCreatePersistedDeviceId(): string {
   const path = getPersistedDeviceIdPath();
   try {
     const existing = readFileSync(path, "utf-8").trim();
@@ -161,7 +159,7 @@ export function saveGuardianToken(
 /**
  * Call POST /v1/guardian/init on the remote gateway to bootstrap a JWT
  * credential pair. The returned tokens are persisted locally under
- * `$XDG_CONFIG_HOME/vellum/assistants/<assistantId>/guardian-token.json`.
+ * `$XDG_CONFIG_HOME/vellum{-env}/assistants/<assistantId>/guardian-token.json`.
  */
 export async function leaseGuardianToken(
   gatewayUrl: string,

package/src/lib/hatch-local.ts

@@ -144,18 +144,10 @@ function installCLISymlink(): void {
 export async function hatchLocal(
   species: Species,
   name: string | null,
-  restart: boolean = false,
   watch: boolean = false,
   keepAlive: boolean = false,
   configValues: Record<string, string> = {},
 ): Promise<void> {
-  if (restart && !name && !process.env.VELLUM_ASSISTANT_NAME) {
-    console.error(
-      "Error: Cannot restart without a known assistant ID. Provide --name or ensure VELLUM_ASSISTANT_NAME is set.",
-    );
-    process.exit(1);
-  }
-
   const instanceName = generateInstanceName(
     species,
     name ?? process.env.VELLUM_ASSISTANT_NAME,
@@ -320,20 +312,9 @@ export async function hatchLocal(
   }
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
-  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
-  const prevBaseDataDir = process.env.BASE_DATA_DIR;
-  process.env.BASE_DATA_DIR = resources.instanceDir;
-  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-  if (ngrokChild?.pid) {
-    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-  }
-  if (prevBaseDataDir !== undefined) {
-    process.env.BASE_DATA_DIR = prevBaseDataDir;
-  } else {
-    delete process.env.BASE_DATA_DIR;
-  }
-
+  // Set BASE_DATA_DIR so ngrok reads the correct instance config. Keep the
+  // lockfile save/sync inside the same scope so syncConfigToLockfile() reads
+  // this instance's workspace/config.json rather than a stale default path.
   const localEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,
@@ -341,28 +322,42 @@ export async function hatchLocal(
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),
-    serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
     resources: { ...resources, signingKey },
   };
-  emitProgress(7, 7, "Saving configuration...");
-  if (!restart) {
+
+  const prevBaseDataDir = process.env.BASE_DATA_DIR;
+  process.env.BASE_DATA_DIR = resources.instanceDir;
+  try {
+    const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+    if (ngrokChild?.pid) {
+      const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+      writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+    }
+
+    emitProgress(7, 7, "Saving configuration...");
     saveAssistantEntry(localEntry);
     setActiveAssistant(instanceName);
     syncConfigToLockfile();
-
-    if (process.env.VELLUM_DESKTOP_APP) {
-      installCLISymlink();
+  } finally {
+    if (prevBaseDataDir !== undefined) {
+      process.env.BASE_DATA_DIR = prevBaseDataDir;
+    } else {
+      delete process.env.BASE_DATA_DIR;
     }
+  }
 
-    console.log("");
-    console.log(`✅ Local assistant hatched!`);
-    console.log("");
-    console.log("Instance details:");
-    console.log(`  Name: ${instanceName}`);
-    console.log(`  Runtime: ${runtimeUrl}`);
-    console.log("");
+  if (process.env.VELLUM_DESKTOP_APP) {
+    installCLISymlink();
   }
 
+  console.log("");
+  console.log(`✅ Local assistant hatched!`);
+  console.log("");
+  console.log("Instance details:");
+  console.log(`  Name: ${instanceName}`);
+  console.log(`  Runtime: ${runtimeUrl}`);
+  console.log("");
+
   if (keepAlive) {
     const healthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
     const healthTarget = "Gateway";

package/src/lib/local.ts

@@ -283,12 +283,18 @@ async function startDaemonFromSource(
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
     VELLUM_CLOUD: "local",
     VELLUM_DEV: "1",
+    VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
+    env.GATEWAY_SECURITY_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "protected",
+    );
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -404,12 +410,18 @@ async function startDaemonWatchFromSource(
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
     VELLUM_DEV: "1",
+    VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
+    env.GATEWAY_SECURITY_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "protected",
+    );
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -855,11 +867,16 @@ export async function startLocalDaemon(
         HOME: process.env.HOME || home,
         PATH: [...extraDirs, basePath].filter(Boolean).join(":"),
       };
-      // Forward optional config env vars the daemon may need
+      // Forward optional config env vars the daemon may need.
+      // `VELLUM_ENVIRONMENT` must be forwarded so the daemon resolves
+      // env-scoped paths (device ID, platform/guardian tokens, XDG
+      // config dir) to the same location as the CLI that spawned it.
       for (const key of [
         "ANTHROPIC_API_KEY",
         "APP_VERSION",
         "BASE_DATA_DIR",
+        "GATEWAY_SECURITY_DIR",
+        "VELLUM_ENVIRONMENT",
         "VELLUM_PLATFORM_URL",
         "QDRANT_HTTP_PORT",
         "QDRANT_URL",
@@ -885,6 +902,11 @@ export async function startLocalDaemon(
       // all paths under the instance directory and listens on its own port.
       if (resources) {
         daemonEnv.BASE_DATA_DIR = resources.instanceDir;
+        daemonEnv.GATEWAY_SECURITY_DIR = join(
+          resources.instanceDir,
+          ".vellum",
+          "protected",
+        );
         daemonEnv.RUNTIME_HTTP_PORT = String(resources.daemonPort);
         daemonEnv.GATEWAY_PORT = String(resources.gatewayPort);
         daemonEnv.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -1043,10 +1065,29 @@ export async function startGateway(
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
-    ...(watch ? { VELLUM_DEV: "1" } : {}),
-    // Set BASE_DATA_DIR so the gateway loads the correct credentials and
-    // workspace config for this instance (mirrors the daemon env setup).
-    ...(resources ? { BASE_DATA_DIR: resources.instanceDir } : {}),
+    ...(watch
+      ? {
+          VELLUM_DEV: "1",
+          VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
+        }
+      : {}),
+    // Set VELLUM_WORKSPACE_DIR and GATEWAY_SECURITY_DIR so the gateway
+    // loads the correct credentials and workspace config for this instance
+    // (mirrors the daemon env setup).
+    ...(resources
+      ? {
+          VELLUM_WORKSPACE_DIR: join(
+            resources.instanceDir,
+            ".vellum",
+            "workspace",
+          ),
+          GATEWAY_SECURITY_DIR: join(
+            resources.instanceDir,
+            ".vellum",
+            "protected",
+          ),
+        }
+      : {}),
   };
   if (publicUrl) {
     console.log(`   Ingress URL: ${publicUrl}`);

package/src/lib/orphan-detection.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
+import { loadAllAssistants } from "./assistant-config.js";
 import { execOutput } from "./step-runner";
 
 export interface RemoteProcess {
@@ -72,20 +73,35 @@ export interface OrphanedProcess {
 export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
   const results: OrphanedProcess[] = [];
   const seenPids = new Set<string>();
-  const vellumDir = join(homedir(), ".vellum");
 
-  // Strategy 1: PID file scan
-  const pidFiles: Array<{ file: string; name: string }> = [
-    { file: join(vellumDir, "vellum.pid"), name: "assistant" },
-    { file: join(vellumDir, "gateway.pid"), name: "gateway" },
-    { file: join(vellumDir, "qdrant.pid"), name: "qdrant" },
-  ];
+  // Collect every known local instance's `.vellum/` directory from the
+  // lockfile so orphan detection scans all containers under the current
+  // multi-instance data layout, not just the legacy `~/.vellum/` root.
+  const dirs = new Set<string>();
+  for (const entry of loadAllAssistants()) {
+    if (entry.cloud !== "local" || !entry.resources) continue;
+    dirs.add(join(entry.resources.instanceDir, ".vellum"));
+  }
+  // Preserve the legacy root scan for installs that predate multi-instance
+  // tracking. This catches orphans from a pre-upgrade `~/.vellum/` that
+  // may not have a lockfile entry at all.
+  dirs.add(join(homedir(), ".vellum"));
+
+  // Strategy 1: PID file scan — check every known data directory.
+  for (const dir of dirs) {
+    const pidFiles: Array<{ file: string; name: string }> = [
+      { file: join(dir, "vellum.pid"), name: "assistant" },
+      { file: join(dir, "gateway.pid"), name: "gateway" },
+      { file: join(dir, "qdrant.pid"), name: "qdrant" },
+    ];
 
-  for (const { file, name } of pidFiles) {
-    const pid = readPidFile(file);
-    if (pid && isProcessAlive(pid)) {
-      results.push({ name, pid, source: "pid file" });
-      seenPids.add(pid);
+    for (const { file, name } of pidFiles) {
+      const pid = readPidFile(file);
+      if (!pid || seenPids.has(pid)) continue;
+      if (isProcessAlive(pid)) {
+        results.push({ name, pid, source: "pid file" });
+        seenPids.add(pid);
+      }
     }
   }