@vellumai/cli 0.11.2 → 0.11.3-staging.2

package/src/lib/ngrok.ts

@@ -6,11 +6,12 @@ import { GATEWAY_PORT } from "./constants.js";
 import {
   clearIngressUrl,
   getDefaultWorkspaceDir,
+  loadNgrokDomain,
   loadRawConfig,
   saveIngressUrl,
+  saveNgrokDomain,
 } from "./ingress-config.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
-import { resolveTunnelTargetPort } from "./nginx-ingress.js";
 
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
 const NGROK_POLL_INTERVAL_MS = 500;
@@ -59,40 +60,59 @@ async function queryNgrokTunnels(): Promise<NgrokTunnel[] | null> {
   }
 }
 
-/**
- * Find an existing ngrok tunnel that targets the given local address.
- * Returns the HTTPS public URL if found, null otherwise.
- */
-export async function findExistingTunnel(
-  targetPort: number,
-): Promise<string | null> {
-  const tunnels = await queryNgrokTunnels();
-  if (!tunnels || tunnels.length === 0) return null;
-
+/** Whether a tunnel targets the given local port, under any addr spelling. */
+function tunnelTargetsPort(tunnel: NgrokTunnel, targetPort: number): boolean {
   const targetAddrs = [
     `localhost:${targetPort}`,
     `127.0.0.1:${targetPort}`,
     `http://localhost:${targetPort}`,
     `http://127.0.0.1:${targetPort}`,
   ];
+  return targetAddrs.includes(tunnel.config?.addr ?? "");
+}
 
-  // Prefer HTTPS tunnel
-  for (const t of tunnels) {
-    const addr = t.config?.addr ?? "";
-    if (targetAddrs.includes(addr) && t.public_url.startsWith("https://")) {
-      return t.public_url;
-    }
-  }
+/** Pick the tunnel for the target port (and domain, when set), HTTPS first. */
+function pickMatchingTunnel(
+  tunnels: NgrokTunnel[],
+  targetPort: number,
+  domain?: string,
+): string | null {
+  const matches = tunnels.filter(
+    (t) =>
+      tunnelTargetsPort(t, targetPort) &&
+      (!domain || urlMatchesDomain(t.public_url, domain)),
+  );
+  const httpsTunnel = matches.find((t) => t.public_url.startsWith("https://"));
+  if (httpsTunnel) return httpsTunnel.public_url;
+  return matches.find((t) => t.public_url)?.public_url ?? null;
+}
 
-  // Fall back to any tunnel pointing at the target
-  for (const t of tunnels) {
-    const addr = t.config?.addr ?? "";
-    if (targetAddrs.includes(addr) && t.public_url) {
-      return t.public_url;
-    }
-  }
+/** Render listed tunnels as `url -> addr` pairs for mismatch diagnostics. */
+function describeTunnels(tunnels: NgrokTunnel[]): string {
+  return tunnels
+    .map((t) => `${t.public_url} -> ${t.config?.addr ?? "unknown target"}`)
+    .join(", ");
+}
+
+/** Diagnostic for a running ngrok agent whose tunnels all miss the target port. */
+function staleAgentDiagnostic(tunnels: NgrokTunnel[], port: number): string {
+  return `an ngrok agent is already running but tunnels a different local port (${describeTunnels(tunnels)}), not ${port}. It was likely started before the tunnel edge unification or by an external process.`;
+}
 
-  return null;
+/** Recovery copy for a saved domain whose reservation may have lapsed. */
+function savedDomainRecoveryHint(domain: string): string {
+  return `The saved ngrok domain '${domain}' (ingress.ngrok.domain in the workspace config) may no longer be reserved. Run \`vellum tunnel --provider ngrok --clear-domain\` to drop it and tunnel without one.`;
+}
+
+/** Whether a tunnel public URL's host equals the given reserved domain. */
+function urlMatchesDomain(publicUrl: string, domain: string): boolean {
+  try {
+    return (
+      new URL(publicUrl).hostname.toLowerCase() === domain.trim().toLowerCase()
+    );
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -103,11 +123,15 @@ export async function findExistingTunnel(
  * parent process — which would either prevent the CLI from exiting (if
  * handles are left open) or send SIGPIPE to ngrok (if destroyed).
  *
+ * When `domain` is set, the tunnel binds that reserved ngrok domain via
+ * `--domain=<domain>`.
+ *
  * Returns the spawned child process.
  */
 export function startNgrokProcess(
   targetPort: number,
   logFilePath?: string,
+  domain?: string,
 ): ChildProcess {
   let stdio: ("ignore" | "pipe" | number)[] = ["ignore", "pipe", "pipe"];
   let fd: number | undefined;
@@ -118,7 +142,14 @@ export function startNgrokProcess(
     stdio = ["ignore", fd, fd];
   }
 
-  const child = spawn("ngrok", ["http", String(targetPort), "--log=stdout"], {
+  // Explicit over a bare port, which ngrok expands to `localhost`, whose ::1
+  // answer resolves first on macOS and races the edge's IPv4 bind.
+  const args = ["http", `127.0.0.1:${targetPort}`, "--log=stdout"];
+  if (domain) {
+    args.push(`--domain=${domain}`);
+  }
+
+  const child = spawn("ngrok", args, {
     detached: true,
     stdio,
   });
@@ -134,22 +165,21 @@ export function startNgrokProcess(
 }
 
 /**
- * Poll the ngrok local API until an HTTPS tunnel URL appears.
+ * Poll the ngrok local API until a tunnel appears for the target port (and
+ * reserved domain, when one is requested), preferring HTTPS.
  * Returns the public URL, or throws if the timeout is exceeded.
  */
 export async function waitForNgrokUrl(
+  targetPort: number,
+  domain?: string,
   timeoutMs: number = NGROK_POLL_TIMEOUT_MS,
 ): Promise<string> {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
     const tunnels = await queryNgrokTunnels();
     if (tunnels && tunnels.length > 0) {
-      // Prefer HTTPS
-      const httpsTunnel = tunnels.find((t) =>
-        t.public_url.startsWith("https://"),
-      );
-      if (httpsTunnel) return httpsTunnel.public_url;
-      if (tunnels[0]?.public_url) return tunnels[0].public_url;
+      const url = pickMatchingTunnel(tunnels, targetPort, domain);
+      if (url) return url;
     }
     await new Promise((r) => setTimeout(r, NGROK_POLL_INTERVAL_MS));
   }
@@ -158,18 +188,27 @@ export async function waitForNgrokUrl(
   );
 }
 
+/**
+ * Check whether an already-loaded workspace config has webhook-based
+ * integrations (e.g. Telegram, Twilio) that require a public ingress URL.
+ */
+export function hasWebhookIntegrations(
+  config: Record<string, unknown>,
+): boolean {
+  const telegram = config.telegram as Record<string, unknown> | undefined;
+  if (telegram?.botUsername) return true;
+  const twilio = config.twilio as Record<string, unknown> | undefined;
+  if (twilio?.accountSid || twilio?.phoneNumber) return true;
+  return false;
+}
+
 /**
  * Check whether any webhook-based integrations (e.g. Telegram, Twilio) are
  * configured that require a public ingress URL.
  */
 function hasWebhookIntegrationsConfigured(workspaceDir: string): boolean {
   try {
-    const config = loadRawConfig(workspaceDir);
-    const telegram = config.telegram as Record<string, unknown> | undefined;
-    if (telegram?.botUsername) return true;
-    const twilio = config.twilio as Record<string, unknown> | undefined;
-    if (twilio?.accountSid || twilio?.phoneNumber) return true;
-    return false;
+    return hasWebhookIntegrations(loadRawConfig(workspaceDir));
   } catch {
     return false;
   }
@@ -215,13 +254,34 @@ export async function maybeStartNgrokTunnel(
   const version = getNgrokVersion();
   if (!version) return null;
 
+  const savedDomain = loadNgrokDomain(workspaceDir) ?? undefined;
+
   // Reuse an existing tunnel if one is already running
-  const existingUrl = await findExistingTunnel(targetPort);
+  const runningTunnels = (await queryNgrokTunnels()) ?? [];
+  const existingUrl = pickMatchingTunnel(runningTunnels, targetPort);
   if (existingUrl) {
+    if (savedDomain && !urlMatchesDomain(existingUrl, savedDomain)) {
+      // Spawning a second agent would collide (ERR_NGROK_334), and saving the
+      // mismatched URL would clobber the reserved-domain intent. Leave the
+      // tunnel running but refuse to bless it in config.
+      console.warn(
+        `   ⚠ Existing ngrok tunnel ${existingUrl} does not match the reserved domain '${savedDomain}'. Ignoring it. Stop the running ngrok agent and run \`vellum tunnel --provider ngrok --domain ${savedDomain}\` to bind the reserved domain.`,
+      );
+      return null;
+    }
     console.log(`   Found existing ngrok tunnel: ${existingUrl}`);
     saveIngressUrl(workspaceDir, existingUrl);
     return null;
   }
+  if (runningTunnels.length > 0) {
+    // An agent is up but tunnels some other local port (likely started before
+    // the edge unification, or by an external process). Spawning a second
+    // agent would collide (ERR_NGROK_334) on single-agent plans, so skip.
+    console.warn(
+      `   ⚠ ${staleAgentDiagnostic(runningTunnels, targetPort)} Stop that ngrok agent, then run \`vellum tunnel --provider ngrok\` to tunnel the local edge.`,
+    );
+    return null;
+  }
 
   console.log(`   Starting ngrok tunnel for webhook integrations...`);
 
@@ -232,33 +292,39 @@ export async function maybeStartNgrokTunnel(
   // Writing to a log file sidesteps both issues — the file descriptor is
   // inherited by the detached ngrok process and remains valid after CLI exit.
   const ngrokLogPath = join(workspaceDir, "data", "logs", "ngrok.log");
-  const ngrokProcess = startNgrokProcess(targetPort, ngrokLogPath);
+  const ngrokProcess = startNgrokProcess(targetPort, ngrokLogPath, savedDomain);
   ngrokProcess.unref();
 
   try {
-    const publicUrl = await waitForNgrokUrl();
+    const publicUrl = await waitForNgrokUrl(targetPort, savedDomain);
     saveIngressUrl(workspaceDir, publicUrl);
     console.log(`   Tunnel established: ${publicUrl}`);
 
     return ngrokProcess;
   } catch {
     console.warn(
-      `   ⚠ Could not start ngrok tunnel. Webhook integrations may not work until you run \`vellum tunnel\`.`,
+      `   ⚠ Could not start ngrok tunnel. Webhook integrations may not work until you run \`vellum tunnel --provider ngrok\`.`,
     );
+    if (savedDomain) {
+      console.warn(`   ⚠ ${savedDomainRecoveryHint(savedDomain)}`);
+    }
     if (!ngrokProcess.killed) ngrokProcess.kill("SIGTERM");
     return null;
   }
 }
 
 export interface RunNgrokTunnelOptions {
-  /** Gateway port to forward. Defaults to the global GATEWAY_PORT. */
+  /** Local edge port to forward. Defaults to the global GATEWAY_PORT. */
   port?: number;
   /** Workspace directory for config read/write. Defaults to ~/.vellum/workspace. */
   workspaceDir?: string;
-  /** Prefer nginx ingress over the gateway port when it is running. */
-  preferNginxIngress?: boolean;
   /** Lockfile entry to mirror the ingress URL onto (`ingressUrl`). */
   assistantId?: string;
+  /**
+   * Reserved ngrok domain to bind. Persisted so wake restores reuse it.
+   * When omitted, a previously saved domain is reused without being rewritten.
+   */
+  domain?: string;
 }
 
 /**
@@ -286,23 +352,42 @@ export async function runNgrokTunnel(
   console.log(`Using ${version}`);
 
   const workspaceDir = opts.workspaceDir ?? getDefaultWorkspaceDir();
-  const gatewayPort = opts.port ?? GATEWAY_PORT;
-  const { port, viaIngress } = resolveTunnelTargetPort(
-    workspaceDir,
-    gatewayPort,
-    { preferNginxIngress: opts.preferNginxIngress === true },
-  );
-  if (viaIngress) {
-    console.log(
-      `nginx ingress detected — tunneling to it on 127.0.0.1:${port}.`,
-    );
+  const port = opts.port ?? GATEWAY_PORT;
+
+  // The saved domain is standing intent: a run without --domain reuses it,
+  // and only an explicit --domain rewrites it.
+  const domain = opts.domain ?? loadNgrokDomain(workspaceDir) ?? undefined;
+  if (domain && !opts.domain) {
+    console.log(`Using saved ngrok domain: ${domain}`);
   }
 
-  // Check for an existing ngrok tunnel pointing at the gateway
-  const existingUrl = await findExistingTunnel(port);
+  // Check for an existing ngrok tunnel pointing at the local edge
+  const runningTunnels = (await queryNgrokTunnels()) ?? [];
+  const existingUrl = pickMatchingTunnel(runningTunnels, port);
+  if (!existingUrl && runningTunnels.length > 0) {
+    // Spawning a second agent would collide (ERR_NGROK_334) on single-agent
+    // plans; fail loudly instead, matching the domain-mismatch path.
+    console.error(`Error: ${staleAgentDiagnostic(runningTunnels, port)}`);
+    console.error(
+      "Stop the existing ngrok agent first, then re-run this command to tunnel the local edge.",
+    );
+    process.exit(1);
+  }
   if (existingUrl) {
+    if (domain && !urlMatchesDomain(existingUrl, domain)) {
+      console.error(
+        `Error: an ngrok tunnel is already running on port ${port} at ${existingUrl}, which does not match the ${opts.domain ? "requested" : "saved"} domain '${domain}'.`,
+      );
+      console.error(
+        "Stop the existing ngrok agent first, then re-run this command to bind the reserved domain.",
+      );
+      process.exit(1);
+    }
     console.log(`Found existing ngrok tunnel: ${existingUrl}`);
     saveIngressUrl(workspaceDir, existingUrl, opts.assistantId);
+    if (opts.domain) {
+      saveNgrokDomain(workspaceDir, opts.domain);
+    }
     console.log("Ingress URL saved to config.");
     console.log("");
     console.log(
@@ -321,7 +406,7 @@ export async function runNgrokTunnel(
 
   let publicUrl: string | undefined;
 
-  const ngrokProcess = startNgrokProcess(port);
+  const ngrokProcess = startNgrokProcess(port, undefined, domain);
 
   const cleanup = () => {
     if (!ngrokProcess.killed) {
@@ -368,9 +453,12 @@ export async function runNgrokTunnel(
   });
 
   try {
-    publicUrl = await waitForNgrokUrl();
+    publicUrl = await waitForNgrokUrl(port, domain);
   } catch (err) {
     cleanup();
+    if (domain && !opts.domain) {
+      console.error(savedDomainRecoveryHint(domain));
+    }
     throw err;
   }
 
@@ -378,7 +466,12 @@ export async function runNgrokTunnel(
   console.log(`Tunnel established: ${publicUrl}`);
   console.log(`Forwarding to:     localhost:${port}`);
 
+  // The domain is standing intent, not tunnel state: cleanup clears the
+  // ingress URL but leaves the domain saved for wake/daemon restores.
   saveIngressUrl(workspaceDir, publicUrl, opts.assistantId);
+  if (opts.domain) {
+    saveNgrokDomain(workspaceDir, opts.domain);
+  }
   console.log("Ingress URL saved to config.");
   console.log("");
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");

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

@@ -0,0 +1,167 @@
+import { afterAll, describe, expect, mock, test } from "bun:test";
+
+import {
+  classifyProcess,
+  detectOrphanedProcesses,
+  isInteractiveCliSession,
+} from "./orphan-detection.js";
+
+// `mock.restore()` does not undo `mock.module()`; keep the real module so it
+// can be restored in afterAll for later test files in the same run.
+const realStepRunner = { ...(await import("./step-runner")) };
+
+describe("isInteractiveCliSession", () => {
+  test("matches a live tunnel session launched via a script path", () => {
+    expect(
+      isInteractiveCliSession(
+        "bun /Users/x/.nvm/versions/node/v22.14.0/bin/vellum tunnel --provider ngrok",
+      ),
+    ).toBe(true);
+  });
+
+  test("matches interactive subcommands like logs and terminal", () => {
+    expect(isInteractiveCliSession("vellum logs foo")).toBe(true);
+    expect(isInteractiveCliSession("vellum terminal")).toBe(true);
+  });
+
+  test("matches the other long-running interactive subcommands", () => {
+    expect(isInteractiveCliSession("vellum events")).toBe(true);
+    expect(isInteractiveCliSession("vellum client")).toBe(true);
+    expect(isInteractiveCliSession("vellum ssh quiet-finch")).toBe(true);
+    expect(isInteractiveCliSession("vellum message quiet-finch hi")).toBe(true);
+    expect(isInteractiveCliSession("vellum workflows")).toBe(true);
+    expect(isInteractiveCliSession("vellum-cli tunnel --provider ngrok")).toBe(
+      true,
+    );
+  });
+
+  test("allows the known global flags before the subcommand", () => {
+    expect(isInteractiveCliSession("vellum --plain tunnel")).toBe(true);
+    expect(isInteractiveCliSession("vellum --no-color logs foo")).toBe(true);
+    expect(isInteractiveCliSession("vellum --no-color --plain events")).toBe(
+      true,
+    );
+  });
+
+  test("matches exec sessions even when argv mentions a service name", () => {
+    expect(
+      isInteractiveCliSession(
+        "vellum exec -it --service vellum-gateway -- /bin/sh",
+      ),
+    ).toBe(true);
+  });
+
+  test("does not match non-interactive CLI wrappers", () => {
+    expect(isInteractiveCliSession("vellum hatch")).toBe(false);
+    expect(isInteractiveCliSession("/usr/bin/vellum sleep")).toBe(false);
+    expect(isInteractiveCliSession("vellum wake")).toBe(false);
+    expect(isInteractiveCliSession("vellum wake --watch")).toBe(false);
+  });
+
+  test("matches the implicit TUI client (bare vellum)", () => {
+    expect(isInteractiveCliSession("vellum")).toBe(true);
+    expect(isInteractiveCliSession("bun /Users/x/.nvm/bin/vellum")).toBe(true);
+    expect(isInteractiveCliSession("vellum --plain")).toBe(true);
+  });
+
+  test("matches a foreground wake session", () => {
+    expect(isInteractiveCliSession("vellum wake --foreground")).toBe(true);
+    expect(isInteractiveCliSession("vellum wake --watch --foreground")).toBe(
+      true,
+    );
+    expect(
+      isInteractiveCliSession("bun /Users/x/bin/vellum wake --foreground"),
+    ).toBe(true);
+  });
+
+  test("interactive names in later argv tokens do not match", () => {
+    expect(isInteractiveCliSession("vellum hatch --name logs")).toBe(false);
+    expect(isInteractiveCliSession("vellum sleep logs")).toBe(false);
+  });
+
+  test("unknown flags before the subcommand do not match", () => {
+    expect(isInteractiveCliSession("vellum --verbose tunnel")).toBe(false);
+  });
+
+  test("repo paths containing vellum do not match", () => {
+    expect(
+      isInteractiveCliSession(
+        "node /Users/runner/work/vellum-assistant/vellum-assistant/scripts/build.js",
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("classifyProcess", () => {
+  test("labels interactive CLI sessions as vellum like any other wrapper", () => {
+    expect(classifyProcess("vellum tunnel --provider ngrok")).toBe("vellum");
+    expect(classifyProcess("vellum logs foo")).toBe("vellum");
+    expect(classifyProcess("vellum-cli tunnel --provider ngrok")).toBe(
+      "vellum",
+    );
+  });
+
+  test("classifies non-interactive CLI wrappers as vellum", () => {
+    expect(classifyProcess("vellum hatch")).toBe("vellum");
+    expect(classifyProcess("vellum")).toBe("vellum");
+    expect(classifyProcess("/usr/bin/vellum sleep")).toBe("vellum");
+    expect(classifyProcess("vellum hatch --name logs")).toBe("vellum");
+    expect(classifyProcess("vellum sleep logs")).toBe("vellum");
+  });
+
+  test("service process classifications are unchanged", () => {
+    expect(classifyProcess("/opt/homebrew/bin/qdrant --config foo")).toBe(
+      "qdrant",
+    );
+    expect(classifyProcess("bun /x/bin/vellum-gateway --port 7830")).toBe(
+      "gateway",
+    );
+    expect(classifyProcess("bun /x/bin/vellum-daemon start")).toBe("assistant");
+    expect(classifyProcess("node daemon start")).toBe("assistant");
+    expect(
+      classifyProcess("bun /x/bin/vellum-openclaw-adapter --port 9000"),
+    ).toBe("openclaw-adapter");
+  });
+
+  test("macOS desktop app processes stay excluded", () => {
+    expect(
+      classifyProcess("/Applications/Vellum.app/Contents/MacOS/Vellum"),
+    ).toBe("unknown");
+  });
+
+  test("repo paths containing vellum do not match", () => {
+    expect(
+      classifyProcess(
+        "node /Users/runner/work/vellum-assistant/vellum-assistant/scripts/build.js",
+      ),
+    ).toBe("unknown");
+  });
+});
+
+describe("detectOrphanedProcesses", () => {
+  afterAll(() => {
+    mock.module("./step-runner", () => realStepRunner);
+  });
+
+  test("skips live interactive sessions but still reports orphaned services", async () => {
+    const psOutput = [
+      "101 1 bun /Users/x/bin/vellum tunnel --provider ngrok",
+      "102 1 vellum exec -it --service vellum-gateway -- /bin/sh",
+      "103 1 vellum --plain logs foo",
+      "104 1 bun /x/bin/vellum-gateway --port 7830",
+      "105 1 vellum hatch",
+    ].join("\n");
+    mock.module("./step-runner", () => ({
+      ...realStepRunner,
+      execOutput: async () => psOutput,
+    }));
+
+    const orphans = await detectOrphanedProcesses({
+      excludePids: new Set<string>(),
+    });
+
+    expect(orphans.map((o) => o.pid).sort()).toEqual(["104", "105"]);
+    expect(orphans.find((o) => o.pid === "104")?.name).toBe("gateway");
+    expect(orphans.find((o) => o.pid === "105")?.name).toBe("vellum");
+  });
+});

package/src/lib/orphan-detection.ts

@@ -37,6 +37,41 @@ export function classifyProcess(command: string): string {
   return "unknown";
 }
 
+/**
+ * True when the command line is a deliberate long-running interactive CLI
+ * session (e.g. a live `vellum tunnel` in someone's terminal). Such sessions
+ * have no PID-file registration, so `vellum clean` would otherwise kill them
+ * mid-session. The command line may be "bun /path/to/bin/vellum tunnel ...",
+ * so match the subcommand right after the vellum binary/script path (allowing
+ * only the known global flags in between; see GLOBAL_FLAGS in cli/src/index.ts).
+ * Later argv tokens (e.g. "vellum hatch --name logs") must not match.
+ *
+ * `detectOrphanedProcesses` consults this before classification so that
+ * service-like substrings in later argv (e.g. `vellum exec -it --service
+ * vellum-gateway -- /bin/sh`) cannot re-flag a live session, while
+ * `classifyProcess` stays a pure display label for `vellum ps`.
+ *
+ * Also spared: bare `vellum` (no subcommand launches the implicit TUI client
+ * via tryLaunchClient) and `vellum wake --foreground` (stays attached with
+ * logs in the terminal).
+ */
+export function isInteractiveCliSession(command: string): boolean {
+  const vellumToken = /(?:^|\/)vellum(?:-cli)?(?:\s+--(?:no-color|plain))*/;
+  const interactiveSubcommand = new RegExp(
+    vellumToken.source +
+      String.raw`\s+(?:tunnel|events|logs|client|terminal|ssh|exec|message|workflows)\b`,
+  );
+  const implicitTuiClient = new RegExp(vellumToken.source + String.raw`\s*$`);
+  const foregroundWake = new RegExp(
+    vellumToken.source + String.raw`\s+wake\b(?:\s+\S+)*\s--foreground\b`,
+  );
+  return (
+    interactiveSubcommand.test(command) ||
+    implicitTuiClient.test(command) ||
+    foregroundWake.test(command)
+  );
+}
+
 export function parseRemotePs(output: string): RemoteProcess[] {
   return output
     .trim()
@@ -152,6 +187,11 @@ export async function detectOrphanedProcesses(
     for (const p of procs) {
       if (p.pid === ownPid || seenPids.has(p.pid)) continue;
       if (knownPids.has(p.pid)) continue;
+      // Live interactive sessions are spared before classification so that
+      // service substrings in their argv cannot mark them as orphans.
+      if (isInteractiveCliSession(p.command)) {
+        continue;
+      }
       const type = classifyProcess(p.command);
       if (type === "unknown") continue;
       results.push({ name: type, pid: p.pid, source: "process table" });

package/src/lib/pair.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+
+import { REMOTE_WEB_PAIRING_CODE_TTL_MS } from "@vellumai/service-contracts/remote-web-pairing";
+
+import { formatWebApproveFailure, parseGatewayErrorCode } from "./pair.js";
+
+const GATEWAY_URL = "http://127.0.0.1:20100";
+// Callers pass formatAssistantReference() output: display name plus stable ID.
+const ASSISTANT_REFERENCE = "example-assistant (asst_0123456789abcdef)";
+const ENV_NAME = "local";
+const TTL_NOTE = `expire after ${Math.round(REMOTE_WEB_PAIRING_CODE_TTL_MS / 60_000)} minutes`;
+
+describe("formatWebApproveFailure", () => {
+  test("INVALID_USER_CODE names the gateway, assistant reference, and environment", () => {
+    const message = formatWebApproveFailure(
+      GATEWAY_URL,
+      ASSISTANT_REFERENCE,
+      ENV_NAME,
+      "INVALID_USER_CODE",
+    );
+    expect(message).not.toBeNull();
+    expect(message).toContain(`No such pairing code on ${GATEWAY_URL}`);
+    expect(message).toContain(`assistant "${ASSISTANT_REFERENCE}"`);
+    expect(message).toContain("asst_0123456789abcdef");
+    expect(message).toContain(`environment "${ENV_NAME}"`);
+  });
+
+  test("INVALID_USER_CODE includes the TTL note and the cross-environment hint", () => {
+    const message = formatWebApproveFailure(
+      GATEWAY_URL,
+      ASSISTANT_REFERENCE,
+      ENV_NAME,
+      "INVALID_USER_CODE",
+    );
+    expect(message).toContain(TTL_NOTE);
+    expect(message).toContain("single-use");
+    expect(message).toContain("different assistant or environment");
+    expect(message).toContain("VELLUM_ENVIRONMENT");
+  });
+
+  test("EXPIRED_USER_CODE gets the same diagnostic with an expiry lead line", () => {
+    const message = formatWebApproveFailure(
+      GATEWAY_URL,
+      ASSISTANT_REFERENCE,
+      ENV_NAME,
+      "EXPIRED_USER_CODE",
+    );
+    expect(message).toContain(`Pairing code expired on ${GATEWAY_URL}`);
+    expect(message).toContain(TTL_NOTE);
+    expect(message).toContain("VELLUM_ENVIRONMENT");
+  });
+
+  test("unknown error codes return null so callers fall back to the generic HTTP error", () => {
+    for (const code of ["RATE_LIMITED", "BAD_REQUEST", "", null]) {
+      expect(
+        formatWebApproveFailure(
+          GATEWAY_URL,
+          ASSISTANT_REFERENCE,
+          ENV_NAME,
+          code,
+        ),
+      ).toBeNull();
+    }
+  });
+});
+
+describe("parseGatewayErrorCode", () => {
+  test("extracts the code from a gateway error envelope", () => {
+    const body = JSON.stringify({
+      error: { code: "INVALID_USER_CODE", message: "invalid pairing code" },
+    });
+    expect(parseGatewayErrorCode(body)).toBe("INVALID_USER_CODE");
+  });
+
+  test("returns null for non-JSON bodies", () => {
+    expect(parseGatewayErrorCode("Not Found")).toBeNull();
+    expect(parseGatewayErrorCode("")).toBeNull();
+  });
+
+  test("returns null when the envelope carries no string code", () => {
+    expect(parseGatewayErrorCode(JSON.stringify({ error: {} }))).toBeNull();
+    expect(
+      parseGatewayErrorCode(JSON.stringify({ error: { code: 404 } })),
+    ).toBeNull();
+    expect(parseGatewayErrorCode(JSON.stringify({}))).toBeNull();
+  });
+});