@vellumai/cli 0.6.6 → 0.7.1

package/src/lib/local-runtime-client.ts

@@ -0,0 +1,231 @@
+import type { AssistantEntry } from "./assistant-config.js";
+import {
+  authHeaders,
+  parseUnifiedJobStatus,
+  type UnifiedJobStatus,
+} from "./platform-client.js";
+import { resolveRuntimeMigrationUrl } from "./runtime-url.js";
+
+/**
+ * Thrown when the local runtime returns 409 for an export/import request
+ * because another migration of the same type is already in-flight. The
+ * caller can inspect {@link existingJobId} and decide whether to poll the
+ * existing job instead of retrying.
+ */
+export class MigrationInProgressError extends Error {
+  readonly existingJobId: string;
+  readonly kind: "export_in_progress" | "import_in_progress";
+
+  constructor(
+    kind: "export_in_progress" | "import_in_progress",
+    jobId: string,
+  ) {
+    super(
+      `A migration is already in progress (${kind}); existing job_id=${jobId}`,
+    );
+    this.name = "MigrationInProgressError";
+    this.kind = kind;
+    this.existingJobId = jobId;
+  }
+}
+
+function bearerHeaders(token: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+}
+
+/**
+ * Build the auth + content headers for a runtime migration request.
+ *
+ * - For `cloud === "vellum"` we go through the platform's wildcard runtime
+ *   proxy, which authenticates user-session / vak_ tokens via DRF's default
+ *   authentication classes — `authHeaders()` produces the right combination
+ *   (`X-Session-Token` + `Vellum-Organization-Id`, or `Authorization: Bearer
+ *   vak_...`).
+ * - For local/docker the runtime endpoint expects a guardian-token bearer.
+ */
+async function migrationRequestHeaders(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl">,
+  token: string,
+): Promise<Record<string, string>> {
+  if (entry.cloud === "vellum") {
+    return {
+      ...(await authHeaders(token, entry.runtimeUrl)),
+      Accept: "application/json",
+    };
+  }
+  return bearerHeaders(token);
+}
+
+interface Raw409Body {
+  detail?: string;
+  // The runtime's current 409 contract nests the payload under `error`:
+  //   { error: { code: "export_in_progress" | "import_in_progress", job_id } }
+  // We also tolerate a legacy flat shape ({ code, job_id }) for resilience.
+  error?: string | { code?: string; job_id?: string };
+  code?: string;
+  job_id?: string;
+}
+
+/** Common 409 → MigrationInProgressError parsing used by the two POST helpers. */
+async function throwIfInProgress(
+  response: Response,
+  defaultKind: "export_in_progress" | "import_in_progress",
+): Promise<void> {
+  if (response.status !== 409) return;
+  const body = (await response.json().catch(() => ({}))) as Raw409Body;
+  const nested =
+    typeof body.error === "object" && body.error !== null
+      ? body.error
+      : undefined;
+  const jobId = nested?.job_id ?? body.job_id ?? "";
+  const rawKind =
+    nested?.code ??
+    body.code ??
+    (typeof body.error === "string" ? body.error : undefined) ??
+    defaultKind;
+  const kind: "export_in_progress" | "import_in_progress" =
+    rawKind === "export_in_progress" || rawKind === "import_in_progress"
+      ? rawKind
+      : defaultKind;
+  throw new MigrationInProgressError(kind, jobId);
+}
+
+/**
+ * Kick off an async export-to-GCS job on the assistant's runtime.
+ *
+ * For local/docker assistants this POSTs to
+ * `{runtimeUrl}/v1/migrations/export-to-gcs` with guardian-token bearer
+ * auth. For platform-managed (cloud="vellum") assistants the URL is rewritten
+ * to the wildcard-runtime-proxy shape
+ * `{platformUrl}/v1/assistants/<assistantId>/migrations/export-to-gcs` and
+ * authenticated via the platform-token header set the platform's DRF auth
+ * accepts (session / vak_).
+ *
+ * Returns the 202-accepted `job_id`. On 409 (another export in flight)
+ * throws {@link MigrationInProgressError} with the existing job_id.
+ */
+export async function localRuntimeExportToGcs(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  token: string,
+  params: { uploadUrl: string; description?: string },
+): Promise<{ jobId: string }> {
+  const body: Record<string, unknown> = { upload_url: params.uploadUrl };
+  if (params.description !== undefined) {
+    body.description = params.description;
+  }
+
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, "export-to-gcs"),
+    {
+      method: "POST",
+      headers: await migrationRequestHeaders(entry, token),
+      body: JSON.stringify(body),
+    },
+  );
+
+  await throwIfInProgress(response, "export_in_progress");
+
+  if (response.status !== 202) {
+    const errText = await response.text().catch(() => "");
+    throw new Error(
+      `Local runtime export-to-gcs failed (${response.status}): ${
+        errText || response.statusText
+      }`,
+    );
+  }
+
+  const json = (await response.json()) as {
+    job_id: string;
+    status?: string;
+    type?: string;
+  };
+  return { jobId: json.job_id };
+}
+
+/**
+ * Kick off an async import-from-GCS job on the assistant's runtime.
+ *
+ * For local/docker assistants this POSTs to
+ * `{runtimeUrl}/v1/migrations/import-from-gcs` with guardian-token bearer
+ * auth. For platform-managed (cloud="vellum") assistants the URL is rewritten
+ * to the wildcard-runtime-proxy shape
+ * `{platformUrl}/v1/assistants/<assistantId>/migrations/import-from-gcs` and
+ * authenticated via the platform token. On 409 throws
+ * {@link MigrationInProgressError}.
+ */
+export async function localRuntimeImportFromGcs(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  token: string,
+  params: { bundleUrl: string },
+): Promise<{ jobId: string }> {
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, "import-from-gcs"),
+    {
+      method: "POST",
+      headers: await migrationRequestHeaders(entry, token),
+      body: JSON.stringify({ bundle_url: params.bundleUrl }),
+    },
+  );
+
+  await throwIfInProgress(response, "import_in_progress");
+
+  if (response.status !== 202) {
+    const errText = await response.text().catch(() => "");
+    throw new Error(
+      `Local runtime import-from-gcs failed (${response.status}): ${
+        errText || response.statusText
+      }`,
+    );
+  }
+
+  const json = (await response.json()) as {
+    job_id: string;
+    status?: string;
+    type?: string;
+  };
+  return { jobId: json.job_id };
+}
+
+/**
+ * Poll the runtime's unified job-status endpoint.
+ *
+ * For local/docker assistants this GETs
+ * `{runtimeUrl}/v1/migrations/jobs/{jobId}` directly (guardian-token
+ * bearer). For platform-managed assistants it routes through the wildcard
+ * runtime proxy at
+ * `{platformUrl}/v1/assistants/<assistantId>/migrations/jobs/{jobId}` with
+ * platform-token auth — important: the platform's dedicated
+ * `/v1/migrations/jobs/{id}/` endpoint queries platform-side ImportJob
+ * records and would 404 on runtime-created job IDs.
+ */
+export async function localRuntimePollJobStatus(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  token: string,
+  jobId: string,
+): Promise<UnifiedJobStatus> {
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, `jobs/${jobId}`),
+    {
+      headers: await migrationRequestHeaders(entry, token),
+    },
+  );
+
+  if (response.status === 404) {
+    throw new Error("Migration job not found");
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `Local job status check failed: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const raw = (await response.json()) as Parameters<
+    typeof parseUnifiedJobStatus
+  >[0];
+  return parseUnifiedJobStatus(raw);
+}

package/src/lib/local.ts

@@ -1,5 +1,5 @@
 import { execFileSync, execSync, spawn } from "child_process";
-import { randomBytes } from "crypto";
+import { createHash, randomBytes } from "crypto";
 import {
   existsSync,
   mkdirSync,
@@ -8,10 +8,13 @@ import {
   writeFileSync,
 } from "fs";
 import { createRequire } from "module";
-import { homedir, hostname, networkInterfaces, platform } from "os";
+import { homedir, networkInterfaces, platform, tmpdir } from "os";
 import { dirname, join } from "path";
 
-import { type LocalInstanceResources } from "./assistant-config.js";
+import {
+  getDaemonPidPath,
+  type LocalInstanceResources,
+} from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
 import { httpHealthCheck, waitForDaemonReady } from "./http-client.js";
 import { stopProcessByPidFile } from "./process.js";
@@ -19,6 +22,107 @@ import { openLogFile, pipeToLogFile } from "./xdg-log.js";
 
 const _require = createRequire(import.meta.url);
 
+// macOS AF_UNIX path limit (sun_path is 104 bytes, null-terminated → 103 usable).
+const DARWIN_UNIX_SOCKET_MAX_PATH_BYTES = 103;
+
+// The longest socket filename we place in the workspace directory.
+// assistant-skill.sock = 20 chars, plus 1 for the "/" separator = 21 overhead.
+const LONGEST_SOCKET_FILENAME = "assistant-skill.sock";
+
+/**
+ * Warn when an assistant appears to have legacy data in the global workspace.
+ *
+ * Old local startup paths could launch the daemon without
+ * `VELLUM_WORKSPACE_DIR`, causing writes to fall back to `~/.vellum/workspace`.
+ * New local instance launches pin the workspace under
+ * `<instanceDir>/.vellum/workspace`. If we detect data only in the legacy
+ * global path, warn with migration instructions so users are not surprised by
+ * missing history/settings after the fix.
+ */
+function warnIfLegacyWorkspaceFallbackDetected(
+  resources: LocalInstanceResources,
+): void {
+  const instanceWorkspace = join(resources.instanceDir, ".vellum", "workspace");
+  const instanceDbPath = join(instanceWorkspace, "data", "db", "assistant.db");
+
+  const legacyWorkspace = join(homedir(), ".vellum", "workspace");
+  const legacyDbPath = join(legacyWorkspace, "data", "db", "assistant.db");
+
+  // Legacy "first local" entries use ~/.vellum directly; no drift possible.
+  if (instanceWorkspace === legacyWorkspace) return;
+
+  if (existsSync(legacyDbPath) && !existsSync(instanceDbPath)) {
+    console.warn("");
+    console.warn(
+      "WARNING: Detected legacy workspace data in ~/.vellum/workspace for this local assistant.",
+    );
+    console.warn("   What this means:");
+    console.warn(
+      "   - An older startup path likely wrote assistant data to the global workspace.",
+    );
+    console.warn(
+      "   - This assistant now uses its instance workspace instead:",
+    );
+    console.warn(`     ${instanceWorkspace}`);
+    console.warn("   What to do:");
+    console.warn(
+      "   1. Stop the assistant before migrating files (retire/sleep or quit app).",
+    );
+    console.warn(
+      "   2. Copy needed data from ~/.vellum/workspace into the instance workspace.",
+    );
+    console.warn(
+      `      Example: cp -a ~/.vellum/workspace/data/db/assistant.db* ${join(instanceWorkspace, "data", "db")}/`,
+    );
+    console.warn(
+      "   3. Re-launch and confirm history/settings appear as expected.",
+    );
+    console.warn("");
+  }
+}
+
+/**
+ * On macOS, if `{workspaceDir}/assistant-skill.sock` would exceed the
+ * 103-byte AF_UNIX path limit, compute a short tmpdir-based IPC socket
+ * directory and return it.  Returns `undefined` when no override is needed
+ * (the workspace path is short enough, or we're not on macOS).
+ */
+function computeIpcSocketDirOverride(workspaceDir: string): string | undefined {
+  if (platform() !== "darwin") return undefined;
+
+  const longestPath = join(workspaceDir, LONGEST_SOCKET_FILENAME);
+  if (
+    Buffer.byteLength(longestPath, "utf8") <= DARWIN_UNIX_SOCKET_MAX_PATH_BYTES
+  ) {
+    return undefined;
+  }
+
+  // Use a short hash of the workspace dir so multiple instances get
+  // distinct socket directories under /tmp.
+  const hash = createHash("sha256")
+    .update(workspaceDir)
+    .digest("hex")
+    .slice(0, 12);
+  return join(tmpdir(), `vellum-ipc-${hash}`);
+}
+
+/**
+ * If the workspace path is too long for AF_UNIX sockets on macOS, compute
+ * a short override directory and set all IPC socket env vars on the target
+ * env object. No-op on non-macOS or when paths are within limits.
+ */
+function applyIpcSocketDirOverride(env: Record<string, string>): void {
+  const workspaceDir =
+    env.VELLUM_WORKSPACE_DIR || join(homedir(), ".vellum", "workspace");
+  const override = computeIpcSocketDirOverride(workspaceDir);
+  if (!override) return;
+
+  mkdirSync(override, { recursive: true });
+  env.GATEWAY_IPC_SOCKET_DIR = override;
+  env.ASSISTANT_IPC_SOCKET_DIR = override;
+  env.ASSISTANT_SKILL_IPC_SOCKET_DIR = override;
+}
+
 function isAssistantSourceDir(dir: string): boolean {
   const pkgPath = join(dir, "package.json");
   if (!existsSync(pkgPath) || !existsSync(join(dir, "src", "index.ts")))
@@ -222,10 +326,9 @@ async function startDaemonFromSource(
   const daemonMainPath = resolveDaemonMainPath(assistantIndex);
 
   // Ensure the directory containing PID/socket files exists. For named
-  // instances this is instanceDir/.vellum/ (matching daemon's getRootDir()).
-  mkdirSync(dirname(resources.pidFile), { recursive: true });
-
-  const pidFile = resources.pidFile;
+  // instances this is instanceDir/.vellum/workspace/ (matching daemon's getWorkspaceDir()).
+  const pidFile = getDaemonPidPath(resources);
+  mkdirSync(dirname(pidFile), { recursive: true });
 
   // --- Lifecycle guard: prevent split-brain daemon state ---
   if (existsSync(pidFile)) {
@@ -289,12 +392,21 @@ async function startDaemonFromSource(
       : {}),
   };
   if (resources) {
-    env.BASE_DATA_DIR = resources.instanceDir;
+    env.VELLUM_WORKSPACE_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "workspace",
+    );
     env.GATEWAY_SECURITY_DIR = join(
       resources.instanceDir,
       ".vellum",
       "protected",
     );
+    env.CREDENTIAL_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);
@@ -349,9 +461,8 @@ async function startDaemonWatchFromSource(
     throw new Error(`Daemon main.ts not found at ${mainPath}`);
   }
 
-  mkdirSync(dirname(resources.pidFile), { recursive: true });
-
-  const pidFile = resources.pidFile;
+  const pidFile = getDaemonPidPath(resources);
+  mkdirSync(dirname(pidFile), { recursive: true });
 
   // --- Lifecycle guard: prevent split-brain daemon state ---
   // If a daemon is already running, skip spawning a new one.
@@ -416,12 +527,21 @@ async function startDaemonWatchFromSource(
       : {}),
   };
   if (resources) {
-    env.BASE_DATA_DIR = resources.instanceDir;
+    env.VELLUM_WORKSPACE_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "workspace",
+    );
     env.GATEWAY_SECURITY_DIR = join(
       resources.instanceDir,
       ".vellum",
       "protected",
     );
+    env.CREDENTIAL_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);
@@ -563,51 +683,18 @@ export async function discoverPublicUrl(
     return `http://${cloudIp}:${effectivePort}`;
   }
 
-  // Log the local address source only when we actually use it.
-  if (localResult.source === "hostname") {
-    console.log(`   Discovered macOS local hostname: ${localResult.label}`);
-  } else if (localResult.source === "lan") {
-    console.log(`   Discovered LAN IP: ${localResult.label}`);
-  }
-
   return localResult.url;
 }
 
 /**
- * Resolve a LAN-reachable URL without any async I/O. Returns the best local
- * address or falls back to localhost. Does not emit any logs — the caller
- * decides whether to log based on which result is actually used.
+ * Returns the localhost URL for the gateway on the given port.
  */
 function discoverLocalUrl(effectivePort: number): {
   url: string;
-  source: "hostname" | "lan" | "localhost";
-  label?: string;
+  source: "localhost";
 } {
-  // On macOS, prefer the .local hostname (Bonjour/mDNS) so other devices on
-  // the same network can reach the gateway by name.
-  if (platform() === "darwin") {
-    const localHostname = getMacLocalHostname();
-    if (localHostname) {
-      return {
-        url: `http://${localHostname}:${effectivePort}`,
-        source: "hostname",
-        label: localHostname,
-      };
-    }
-  }
-
-  const lanIp = getLocalLanIPv4();
-  if (lanIp) {
-    return {
-      url: `http://${lanIp}:${effectivePort}`,
-      source: "lan",
-      label: lanIp,
-    };
-  }
-
-  // Final fallback to localhost when no LAN address could be discovered.
   return {
-    url: `http://localhost:${effectivePort}`,
+    url: `http://127.0.0.1:${effectivePort}`,
     source: "localhost",
   };
 }
@@ -664,19 +751,6 @@ async function discoverCloudExternalIp(): Promise<string | undefined> {
   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.
- */
-export function getMacLocalHostname(): string | undefined {
-  const host = hostname();
-  if (!host) return undefined;
-  // macOS hostnames already end with .local when Bonjour is active
-  if (host.endsWith(".local")) return host;
-  // Otherwise, append .local — macOS resolves <ComputerName>.local via mDNS
-  return `${host}.local`;
-}
-
 /**
  * Returns the local IPv4 address most likely to be reachable from other
  * devices on the same LAN.
@@ -769,6 +843,8 @@ export async function startLocalDaemon(
   resources: LocalInstanceResources,
   options?: DaemonStartOptions,
 ): Promise<void> {
+  warnIfLegacyWorkspaceFallbackDetected(resources);
+
   const foreground = options?.foreground ?? false;
   // Check for a compiled daemon binary adjacent to the CLI executable.
   // This covers both the desktop app (VELLUM_DESKTOP_APP) and the case where
@@ -779,7 +855,7 @@ export async function startLocalDaemon(
     // In watch mode, skip the bundled binary and use source (bun --watch
     // only works with source files, not compiled binaries).
 
-    const pidFile = resources.pidFile;
+    const pidFile = getDaemonPidPath(resources);
 
     // If a daemon is already running, skip spawning a new one.
     // This prevents cascading kill→restart cycles when multiple callers
@@ -874,8 +950,8 @@ export async function startLocalDaemon(
       for (const key of [
         "ANTHROPIC_API_KEY",
         "APP_VERSION",
-        "BASE_DATA_DIR",
         "GATEWAY_SECURITY_DIR",
+        "CREDENTIAL_SECURITY_DIR",
         "VELLUM_ENVIRONMENT",
         "VELLUM_PLATFORM_URL",
         "QDRANT_HTTP_PORT",
@@ -901,12 +977,21 @@ export async function startLocalDaemon(
       // When running a named instance, override env so the daemon resolves
       // all paths under the instance directory and listens on its own port.
       if (resources) {
-        daemonEnv.BASE_DATA_DIR = resources.instanceDir;
+        daemonEnv.VELLUM_WORKSPACE_DIR = join(
+          resources.instanceDir,
+          ".vellum",
+          "workspace",
+        );
         daemonEnv.GATEWAY_SECURITY_DIR = join(
           resources.instanceDir,
           ".vellum",
           "protected",
         );
+        daemonEnv.CREDENTIAL_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);
@@ -917,6 +1002,8 @@ export async function startLocalDaemon(
         daemonEnv.ACTOR_TOKEN_SIGNING_KEY = options.signingKey;
       }
 
+      applyIpcSocketDirOverride(daemonEnv);
+
       // Write a sentinel PID file before spawning so concurrent hatch() calls
       // see the file and fall through to the isDaemonResponsive() port check
       // instead of racing to spawn a duplicate daemon.
@@ -1044,7 +1131,7 @@ export async function startGateway(
 
   const publicUrl = await discoverPublicUrl(effectiveGatewayPort);
   if (publicUrl) {
-    console.log(`   Public URL: ${publicUrl}`);
+    console.log(`   HTTP URL: ${publicUrl}`);
   }
 
   console.log("🌐 Starting gateway...");
@@ -1058,7 +1145,6 @@ export async function startGateway(
     GATEWAY_PORT: String(effectiveGatewayPort),
     // Pass gateway operational settings via env vars so the CLI does not
     // need direct access to the workspace config file.
-    RUNTIME_PROXY_ENABLED: "true",
     RUNTIME_PROXY_REQUIRE_AUTH: "true",
     UNMAPPED_POLICY: "default",
     DEFAULT_ASSISTANT_ID: "self",
@@ -1071,12 +1157,11 @@ export async function startGateway(
           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).
+    // Pin gateway workspace/security paths to the named instance so parent
+    // env vars cannot leak a different workspace. The gateway opens the
+    // assistant DB directly for guardian bootstrap.
     ...(resources
       ? {
-          BASE_DATA_DIR: resources.instanceDir,
           VELLUM_WORKSPACE_DIR: join(
             resources.instanceDir,
             ".vellum",
@@ -1087,11 +1172,19 @@ export async function startGateway(
             ".vellum",
             "protected",
           ),
+          CREDENTIAL_SECURITY_DIR: join(
+            resources.instanceDir,
+            ".vellum",
+            "protected",
+          ),
         }
       : {}),
   };
+
+  applyIpcSocketDirOverride(gatewayEnv);
+
   if (publicUrl) {
-    console.log(`   Ingress URL: ${publicUrl}`);
+    console.log(`   HTTP URL: ${publicUrl}`);
   }
 
   let gateway;
@@ -1186,7 +1279,7 @@ export async function stopLocalProcesses(
   const vellumDir = resources
     ? join(resources.instanceDir, ".vellum")
     : join(homedir(), ".vellum");
-  const daemonPidFile = resources?.pidFile ?? join(vellumDir, "vellum.pid");
+  const daemonPidFile = getDaemonPidPath(resources);
   await stopProcessByPidFile(daemonPidFile, "daemon");
 
   const gatewayPidFile = join(vellumDir, "gateway.pid");

package/src/lib/orphan-detection.ts

@@ -1,8 +1,5 @@
 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 {
@@ -74,38 +71,8 @@ export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
   const results: OrphanedProcess[] = [];
   const seenPids = new Set<string>();
 
-  // 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 || seenPids.has(pid)) continue;
-      if (isProcessAlive(pid)) {
-        results.push({ name, pid, source: "pid file" });
-        seenPids.add(pid);
-      }
-    }
-  }
-
-  // Strategy 2: Process table scan
+  // Process table scan — discover orphaned processes by scanning the OS
+  // process table rather than reading PID files from the workspace.
   try {
     const output = await execOutput("sh", [
       "-c",