@vellumai/cli 0.10.11-dev.202607240139.777dbcd → 0.10.11-dev.202607240310.e82c8d4

package/node_modules/@vellumai/local-mode/src/lockfile-contract.test.ts

@@ -24,6 +24,7 @@ describe("parseLockfile", () => {
           platformAssistantId: "platform-assistant-1",
           platformBaseUrl: "https://platform.example.com",
           platformOrganizationId: "org_1",
+          ingressUrl: "https://tunnel.example.ts.net",
           resources: { gatewayPort: 7777, daemonPort: 7778 },
         },
       ],
@@ -186,6 +187,30 @@ describe("parseLockfile", () => {
     ]);
   });
 
+  test("keeps a well-typed ingressUrl and drops it when mistyped", () => {
+    // The tunnel-recorded public URL rides the entry so remote-web pairing
+    // surfaces can prefill it; a mistyped value is dropped, entry preserved.
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          ingressUrl: "https://tunnel.example.ts.net",
+        },
+        { assistantId: "asst_2", cloud: "local", ingressUrl: 7 }, // mistyped
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      {
+        assistantId: "asst_1",
+        cloud: "local",
+        ingressUrl: "https://tunnel.example.ts.net",
+      },
+      { assistantId: "asst_2", cloud: "local" },
+    ]);
+  });
+
   test("drops a resources object missing its numeric ports", () => {
     const raw = {
       assistants: [

package/node_modules/@vellumai/local-mode/src/lockfile-contract.ts

@@ -115,6 +115,13 @@ export const LockfileAssistantSchema = z.object({
   platformBaseUrl: z.string().optional(),
   /** Platform organization UUID used for a self-hosted local assistant registration. */
   platformOrganizationId: z.string().optional(),
+  /**
+   * Public https URL a `vellum tunnel` provider recorded for this assistant
+   * (mirrored from the workspace ingress config). A public address, so it is
+   * renderer-safe: remote-web pairing surfaces (the CLI `--qr` flow, the web
+   * "Pair a device" card) default to it instead of asking the user to retype it.
+   */
+  ingressUrl: z.string().optional(),
   resources: LocalAssistantResourcesSchema.optional(),
 });
 

package/node_modules/@vellumai/local-mode/src/lockfile.test.ts

@@ -81,6 +81,30 @@ describe("getLockfileData", () => {
     }
   });
 
+  test("surfaces a tunnel-recorded ingressUrl to the renderer", () => {
+    // The exact read the "Pair a device" card relies on: `vellum tunnel` stamps
+    // ingressUrl onto the entry, and the host read must carry it through.
+    writeOnDisk({
+      activeAssistant: "asst_1",
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          runtimeUrl: "http://127.0.0.1:7777",
+          ingressUrl: "https://tunnel.example.ts.net",
+        },
+      ],
+    });
+
+    const result = getLockfileData([lockfilePath]);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.assistants[0]?.ingressUrl).toBe(
+        "https://tunnel.example.ts.net",
+      );
+    }
+  });
+
   test("fails with status 500 on malformed JSON", () => {
     fs.writeFileSync(lockfilePath, "{ not json");
     const result = getLockfileData([lockfilePath]);

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -109,12 +109,77 @@ export type RemoteWebPairingTokenResponse =
 // only) so both Node and browser callers share one implementation.
 
 /** Why a public base URL can't be advertised in a pairing challenge. */
-export type PublicBaseUrlRejection = "unparseable" | "loopback" | "non-https";
+export type PublicBaseUrlRejection =
+  | "unparseable"
+  | "loopback"
+  | "non-https"
+  | "service-website";
 
 export type PublicBaseUrlResult =
   | { ok: true; url: string }
   | { ok: false; reason: PublicBaseUrlRejection };
 
+/**
+ * Hosts that are a tunnel/ingress vendor's own website, not a user's assistant
+ * endpoint. These are the tunnel vendors our docs mention, and their sites are
+ * exactly where a lost user grabs a URL from — e.g. a Tailscale admin invite
+ * link (`login.tailscale.com/admin/invite/…`), which is https and non-loopback
+ * and so clears every other check. Pairing refuses them with a targeted message
+ * rather than minting a challenge the scanning device can never reach.
+ */
+export const TUNNEL_PROVIDER_WEBSITE_HOSTS = [
+  "login.tailscale.com",
+  "tailscale.com",
+  "www.tailscale.com",
+  "ngrok.com",
+  "dashboard.ngrok.com",
+  "dash.cloudflare.com",
+  "cloudflare.com",
+  "www.cloudflare.com",
+] as const;
+
+/**
+ * A URL whose exact host is a tunnel/ingress vendor's own website (see
+ * {@link TUNNEL_PROVIDER_WEBSITE_HOSTS}). Exact-host only: a user's real
+ * Tailscale endpoint (`*.ts.net`) or Cloudflare-fronted domain is never a
+ * listed host, so a legitimate address is never mistaken for a vendor site.
+ */
+export function isTunnelProviderWebsiteUrl(url: string): boolean {
+  let hostname: string;
+  try {
+    // WHATWG URL lowercases the hostname during parsing.
+    hostname = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  return (TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(
+    hostname,
+  );
+}
+
+/**
+ * The display name of the tunnel/ingress vendor a service-website URL points
+ * at (`"Tailscale"` / `"ngrok"` / `"Cloudflare"`), or null when the host is not
+ * a known vendor site. Drives the "This is <Name>'s website" pairing guidance.
+ */
+export function tunnelProviderWebsiteName(url: string): string | null {
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+  if (
+    !(TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(hostname)
+  ) {
+    return null;
+  }
+  if (hostname.includes("tailscale")) return "Tailscale";
+  if (hostname.includes("ngrok")) return "ngrok";
+  if (hostname.includes("cloudflare")) return "Cloudflare";
+  return null;
+}
+
 /**
  * A loopback URL — `localhost`, `[::1]`, or `127.x.x.x`. A pairing link that
  * encodes a loopback address is unreachable from the scanning device.
@@ -167,6 +232,9 @@ export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
   if (isLoopbackPublicUrl(normalized)) {
     return { ok: false, reason: "loopback" };
   }
+  if (isTunnelProviderWebsiteUrl(normalized)) {
+    return { ok: false, reason: "service-website" };
+  }
   if (new URL(normalized).protocol !== "https:") {
     return { ok: false, reason: "non-https" };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.11-dev.202607240139.777dbcd",
+  "version": "0.10.11-dev.202607240310.e82c8d4",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-config.test.ts

@@ -1,5 +1,19 @@
-import { describe, test, expect, beforeEach, afterAll } from "bun:test";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  describe,
+  test,
+  expect,
+  beforeEach,
+  afterEach,
+  afterAll,
+  spyOn,
+} from "bun:test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -16,6 +30,7 @@ import {
   lookupAssistantByIdentifier,
   removeAssistantEntry,
   loadAllAssistants,
+  resolveTargetAssistant,
   saveAssistantEntry,
   getActiveAssistant,
   migrateLegacyEntry,
@@ -700,3 +715,104 @@ describe("env-scoped lockfile and migration", () => {
     }
   });
 });
+
+describe("cross-environment hint on resolution failure", () => {
+  let dataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    dataHome = mkdtempSync(join(tmpdir(), "cli-config-xdg-"));
+    process.env.XDG_DATA_HOME = dataHome;
+    // Pin the current env to production so the detector skips it and the hint
+    // copy is deterministic. The current-env lockfile is emptied so resolution
+    // genuinely finds nothing.
+    process.env.VELLUM_ENVIRONMENT = "production";
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    rmSync(join(testDir, ".vellum.lockfile.json"), { force: true });
+  });
+
+  afterEach(() => {
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(dataHome, { recursive: true, force: true });
+  });
+
+  // A dev-env assistant lives under the dev data dir, invisible to this
+  // production CLI — the exact split the hint explains.
+  function seedDevAssistant(): void {
+    mkdirSync(join(dataHome, "vellum-dev", "assistants", "dev-bot"), {
+      recursive: true,
+    });
+  }
+
+  function captureResolveTargetAssistantError(): string {
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation(
+      (...args: unknown[]) => {
+        errors.push(args.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      _code?: number,
+    ) => {
+      throw new Error("exit");
+    }) as typeof process.exit);
+    try {
+      expect(() => resolveTargetAssistant()).toThrow("exit");
+    } finally {
+      errorSpy.mockRestore();
+      exitSpy.mockRestore();
+    }
+    return errors.join("\n");
+  }
+
+  test("formatAssistantLookupError appends the hint when another env has assistants", () => {
+    seedDevAssistant();
+    const msg = formatAssistantLookupError("ghost", { status: "not_found" });
+    expect(msg).toContain("No assistant found with name or ID 'ghost'.");
+    expect(msg).toContain("Install vellum Command");
+    expect(msg).toContain("VELLUM_ENVIRONMENT=dev");
+  });
+
+  test("formatAssistantLookupError stays bare when no other env has assistants", () => {
+    // dataHome is empty — detection finds nothing, so the message is intact.
+    const msg = formatAssistantLookupError("ghost", { status: "not_found" });
+    expect(msg).toBe("No assistant found with name or ID 'ghost'.");
+  });
+
+  test("ambiguous lookup never gets the hint", () => {
+    seedDevAssistant();
+    const msg = formatAssistantLookupError("Alice", {
+      status: "ambiguous",
+      matches: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Alice" }),
+      ],
+    });
+    expect(msg).not.toContain("Install vellum Command");
+  });
+
+  test("resolveTargetAssistant zero-assistants error carries the hint", () => {
+    seedDevAssistant();
+    const combined = captureResolveTargetAssistantError();
+    expect(combined).toContain("No assistant found. Run 'vellum hatch' first.");
+    expect(combined).toContain("Install vellum Command");
+  });
+
+  test("resolveTargetAssistant zero-assistants error stays bare without other envs", () => {
+    const combined = captureResolveTargetAssistantError();
+    expect(combined).toContain("No assistant found. Run 'vellum hatch' first.");
+    expect(combined).not.toContain("Install vellum Command");
+  });
+});

package/src/__tests__/flags.test.ts

@@ -239,3 +239,80 @@ describe("vellum flags --assistant routing", () => {
     expect(fetchCalls.length).toBe(0);
   });
 });
+
+describe("vellum flags cross-environment hint", () => {
+  let xdgDataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    xdgDataHome = mkdtempSync(join(tmpdir(), "cli-flags-hint-xdg-"));
+    process.env.XDG_DATA_HOME = xdgDataHome;
+    // Pin production so the detector skips it and the lockfile routes to
+    // testDir; the VELLUM_ENVIRONMENT var beats this machine's env config.
+    process.env.VELLUM_ENVIRONMENT = "production";
+    // An unreachable gateway: every request throws like a dead socket would.
+    // Cast through `unknown` since an always-throwing stub returns
+    // `Promise<never>`, which does not structurally overlap with `fetch`.
+    globalThis.fetch = (async () => {
+      throw new TypeError("fetch failed");
+    }) as unknown as typeof globalThis.fetch;
+    process.exit = ((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as typeof process.exit;
+    consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+    consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    process.exit = originalExit;
+    globalThis.fetch = originalFetch;
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(xdgDataHome, { recursive: true, force: true });
+  });
+
+  // A dev-env assistant lives under the dev data dir, invisible to this
+  // production CLI — the split the hint explains.
+  function seedDevAssistant(): void {
+    mkdirSync(join(xdgDataHome, "vellum-dev", "assistants", "dev-bot"), {
+      recursive: true,
+    });
+  }
+
+  test("gateway-unreachable error gains the hint when another env has assistants", async () => {
+    writeLockfile([makeEntry("alice-1", { name: "Alice" })], "alice-1");
+    seedDevAssistant();
+    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    await expect(flags()).rejects.toThrow(/Install vellum Command/);
+  });
+
+  test("gateway-unreachable error stays bare when no other env has assistants", async () => {
+    writeLockfile([makeEntry("alice-1", { name: "Alice" })], "alice-1");
+    // xdgDataHome is empty — detection finds nothing, so the message is intact.
+    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    let error: Error | undefined;
+    try {
+      await flags();
+    } catch (e) {
+      error = e as Error;
+    }
+    expect(error?.message).toContain("Could not reach the assistant gateway");
+    expect(error?.message).not.toContain("Install vellum Command");
+  });
+});

package/src/__tests__/pair.test.ts

@@ -159,6 +159,100 @@ describe("pair command", () => {
     expect(fetchCalled).toBe(true);
   });
 
+  test("rejects an unknown --flag before any network call", async () => {
+    let fetchCalled = false;
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = ["bun", "vellum", "pair", "--frobnicate"];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // A `--` flag this version doesn't know is a hard error, and it points at
+    // the CLI self-update path — never a silent fall-through to another flow.
+    expect(exited).toBe(true);
+    const joined = errors.join("\n");
+    expect(joined).toContain("unknown option '--frobnicate'");
+    expect(joined).toContain("your CLI may be out of date");
+    expect(joined).toContain("bun install -g vellum@latest");
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("rejects an unknown --flag even alongside a multi-word positional name", async () => {
+    writeFileSync(
+      join(testDir, ".vellum.lock.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "pair-test",
+            name: "My Assistant",
+            runtimeUrl: RUNTIME_URL,
+            localUrl: LOCAL_URL,
+            cloud: "local",
+          },
+        ],
+        activeAssistant: "pair-test",
+      }),
+    );
+
+    let fetchCalled = false;
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    // Positional name tokens must not rescue an unknown flag from rejection.
+    process.argv = ["bun", "vellum", "pair", "My", "Assistant", "--frobnicate"];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain("unknown option '--frobnicate'");
+    expect(fetchCalled).toBe(false);
+  });
+
   test("refuses to advertise a loopback URL without --url (suggests the assistant's own port)", async () => {
     // Local hatch on a NON-default gateway port (e.g. a 2nd instance).
     const LOOPBACK_CUSTOM = "http://127.0.0.1:7842";
@@ -211,6 +305,11 @@ describe("pair command", () => {
     expect(errors.join("\n")).toContain(":7842");
     expect(errors.join("\n")).not.toContain(":7830");
 
+    // The refusal cross-points to the QR flow (the phone-pairing path) and its
+    // https prerequisite, so a user who wanted a QR isn't left at a dead end.
+    expect(errors.join("\n")).toContain("vellum pair --qr");
+    expect(errors.join("\n")).toContain("vellum tunnel --provider tailscale");
+
     // Exited with an error before minting — no token created for a dead URL.
     expect(exited).toBe(true);
     expect(fetchCalled).toBe(false);
@@ -748,6 +847,53 @@ describe("pair command", () => {
     expect(fetchCalled).toBe(false);
   });
 
+  test("--qr refuses a tunnel-provider website URL (Tailscale admin invite) without minting", async () => {
+    let fetchCalled = false;
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--qr",
+      "--url",
+      "https://login.tailscale.com/admin/invite/abc123",
+    ];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // The admin-invite link is a vendor website — named as such, not mislabeled
+    // as non-https, and refused before any challenge is minted.
+    expect(exited).toBe(true);
+    const joined = errors.join("\n");
+    expect(joined).toContain("Tailscale's website");
+    expect(joined).not.toContain("is not https");
+    expect(fetchCalled).toBe(false);
+  });
+
   test("--qr refuses when the web remote ingress feature flag is off", async () => {
     const calls: Array<[string, RequestInit | undefined]> = [];
     const origFetch = globalThis.fetch;

package/src/__tests__/tunnel.test.ts

@@ -5,6 +5,7 @@ import {
   describe,
   expect,
   mock,
+  spyOn,
   test,
 } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -162,4 +163,56 @@ describe("tunnel nginx ingress feature flag", () => {
     expect(runNgrokTunnelMock).not.toHaveBeenCalled();
     expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
   });
+
+  test("rejects an unknown --provider with a stale-CLI hint", async () => {
+    process.argv = ["bun", "vellum", "tunnel", "--provider", "bogus"];
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    let exited = false;
+    try {
+      await tunnel();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+    }
+
+    expect(exited).toBe(true);
+    const joined = errors.join("\n");
+    expect(joined).toContain("unknown tunnel provider 'bogus'");
+    expect(joined).toContain("your CLI may be out of date");
+    expect(joined).toContain("bun install -g vellum@latest");
+    expect(runNgrokTunnelMock).not.toHaveBeenCalled();
+    expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
+  });
+
+  test("a not-yet-implemented provider error carries the stale-CLI hint", async () => {
+    // The default `vellum` provider has no runtime yet, so it exercises the
+    // not-yet-implemented path without any network call.
+    process.argv = ["bun", "vellum", "tunnel", "--provider", "vellum"];
+
+    let err: Error | undefined;
+    try {
+      await tunnel();
+    } catch (e) {
+      err = e as Error;
+    }
+
+    expect(err?.message).toContain("is not yet implemented");
+    expect(err?.message).toContain("your CLI may be out of date");
+    expect(err?.message).toContain("bun install -g vellum@latest");
+    expect(runNgrokTunnelMock).not.toHaveBeenCalled();
+    expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
+  });
 });

package/src/commands/flags.ts

@@ -4,6 +4,7 @@ import {
   formatAssistantLookupError,
   lookupAssistantByIdentifier,
 } from "../lib/assistant-config.js";
+import { crossEnvironmentAssistantHint } from "../lib/environments/detect.js";
 
 type FeatureFlagEntry = {
   key: string;
@@ -132,7 +133,9 @@ function rethrowFetchError(err: unknown): never {
     (err.message.includes("fetch") || err.message.includes("connect"))
   ) {
     throw new Error(
-      "Could not reach the assistant gateway. Is it running? Try 'vellum wake'.",
+      `Could not reach the assistant gateway. Is it running? Try 'vellum wake'.${
+        crossEnvironmentAssistantHint() ?? ""
+      }`,
     );
   }
   throw err;

package/src/commands/pair.ts

@@ -19,6 +19,7 @@ import {
   buildRemoteWebPairingUrl,
   normalizePublicBaseUrl,
   resolvePublicBaseUrl,
+  tunnelProviderWebsiteName,
   type PublicBaseUrlRejection,
   type RemoteWebPairingChallengeRequest,
   type RemoteWebPairingChallengeResponse,
@@ -46,6 +47,7 @@ import {
 } from "../lib/feature-flags.js";
 import { getLocalLanIPv4 } from "../lib/local.js";
 import { isLoopbackUrl, loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import { STALE_CLI_UPDATE_HINT } from "../lib/stale-cli-hint.js";
 
 function assistantDisplayName(entry: AssistantEntry): string {
   return entry.name || entry.assistantName || entry.assistantId;
@@ -277,6 +279,22 @@ export async function pair(): Promise<void> {
   );
   args = afterAppScheme;
 
+  // Any `--`-prefixed token left after known-flag extraction is an option this
+  // CLI version doesn't support. Fail loud before any network call rather than
+  // letting it fall through: an unknown flag would otherwise be silently
+  // dropped and the command would run the wrong flow (e.g. `--qr` on an older
+  // CLI minting a copy-paste bundle instead of a QR). Positional names never
+  // start with `--`, so multi-word assistant targets are unaffected.
+  const unknownFlag = args.find((a) => a.startsWith("--"));
+  if (unknownFlag) {
+    console.error(`Error: unknown option '${unknownFlag}'.`);
+    console.error("Run `vellum pair --help` to see available options.");
+    console.error(
+      `If this option is from newer docs, ${STALE_CLI_UPDATE_HINT}`,
+    );
+    process.exit(1);
+  }
+
   if (webPairing && webApproveCode) {
     console.error("Error: use either --web or --web-approve, not both.");
     process.exit(1);
@@ -371,6 +389,10 @@ export async function pair(): Promise<void> {
     console.error(
       `Re-run with a reachable URL, e.g.:\n  vellum pair --url ${suggestion}`,
     );
+    console.error(
+      "Pairing a phone by QR instead? Use: vellum pair --qr " +
+        "(needs an https URL — run `vellum tunnel --provider tailscale` first).",
+    );
     process.exit(1);
   }
 
@@ -451,6 +473,9 @@ export async function pair(): Promise<void> {
         unparseable: `${advertisedUrl} isn't a valid URL`,
         loopback: `${advertisedUrl} is a loopback address`,
         "non-https": `${advertisedUrl} is not https`,
+        "service-website": `${advertisedUrl} is ${
+          tunnelProviderWebsiteName(advertisedUrl) ?? "a tunnel provider"
+        }'s website, not your assistant's address`,
       };
       console.error(
         "Error: --qr needs a public https URL the phone can open — " +

package/src/commands/tunnel.ts

@@ -8,6 +8,7 @@ import {
   WEB_REMOTE_INGRESS_FLAG,
 } from "../lib/feature-flags.js";
 import { runNgrokTunnel } from "../lib/ngrok";
+import { STALE_CLI_UPDATE_HINT } from "../lib/stale-cli-hint.js";
 import { runTailscaleTunnel } from "../lib/tailscale-tunnel.js";
 
 const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
@@ -78,12 +79,21 @@ function parseArgs(): TunnelArgs {
       process.exit(0);
     } else if (arg === "--provider") {
       const next = args[i + 1];
-      if (!next || !VALID_PROVIDERS.includes(next as TunnelProvider)) {
+      if (!next || next.startsWith("-")) {
         console.error(
           `Error: --provider requires one of: ${VALID_PROVIDERS.join(", ")}`,
         );
         process.exit(1);
       }
+      if (!VALID_PROVIDERS.includes(next as TunnelProvider)) {
+        console.error(
+          `Error: unknown tunnel provider '${next}'. Valid providers: ${VALID_PROVIDERS.join(", ")}.`,
+        );
+        console.error(
+          `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
+        );
+        process.exit(1);
+      }
       provider = next as TunnelProvider;
       i++;
     } else if (arg.startsWith("-")) {
@@ -199,5 +209,8 @@ export async function tunnel(): Promise<void> {
     return;
   }
 
-  throw new Error(`Tunnel provider '${provider}' is not yet implemented.`);
+  throw new Error(
+    `Tunnel provider '${provider}' is not yet implemented. ` +
+      `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
+  );
 }

package/src/lib/assistant-config.ts

@@ -18,6 +18,7 @@ import {
 } from "@vellumai/local-mode/contract";
 
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./constants.js";
+import { crossEnvironmentAssistantHint } from "./environments/detect.js";
 import {
   getDefaultPorts,
   getLockfilePath,
@@ -423,7 +424,7 @@ export function formatAssistantLookupError(
     return `Multiple assistants match '${identifier}': ${matches}. Use the assistant ID to disambiguate.`;
   }
 
-  return `No assistant found with name or ID '${identifier}'.`;
+  return `No assistant found with name or ID '${identifier}'.${crossEnvironmentAssistantHint() ?? ""}`;
 }
 
 export function removeAssistantEntry(assistantId: string): void {
@@ -580,7 +581,9 @@ export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
     if (all.length === 1) return all[0];
 
     if (all.length === 0) {
-      console.error("No assistant found. Run 'vellum hatch' first.");
+      console.error(
+        `No assistant found. Run 'vellum hatch' first.${crossEnvironmentAssistantHint() ?? ""}`,
+      );
     } else {
       console.error(
         `Multiple assistants found. Set an active assistant with 'vellum use <name>'.`,

package/src/lib/environments/__tests__/detect.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  crossEnvironmentAssistantHint,
+  detectOtherEnvironmentAssistants,
+} from "../detect.js";
+import { getSeed } from "../resolve.js";
+
+const prod = getSeed("production")!;
+
+/** Create `<XDG_DATA_HOME>/vellum-<env>/assistants/<id>/` for a non-prod env. */
+function seedAssistantDir(dataHome: string, envName: string, id: string): void {
+  mkdirSync(join(dataHome, `vellum-${envName}`, "assistants", id), {
+    recursive: true,
+  });
+}
+
+describe("cross-environment assistant detection", () => {
+  let dataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    dataHome = mkdtempSync(join(tmpdir(), "cli-detect-xdg-"));
+    process.env.XDG_DATA_HOME = dataHome;
+    // Pin the current env so the hint's "this CLI targets '<env>'" copy and
+    // the current-env skip are deterministic regardless of machine config.
+    process.env.VELLUM_ENVIRONMENT = "production";
+  });
+
+  afterEach(() => {
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(dataHome, { recursive: true, force: true });
+  });
+
+  test("finds an env whose data dir holds an assistant subdirectory", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    expect(detectOtherEnvironmentAssistants(prod)).toContain("dev");
+  });
+
+  test("reports every other env that holds assistants", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    seedAssistantDir(dataHome, "staging", "staging-bot");
+    const others = detectOtherEnvironmentAssistants(prod);
+    expect(others).toContain("dev");
+    expect(others).toContain("staging");
+  });
+
+  test("skips the current environment even when it holds assistants", () => {
+    // production's own multi-instance dir (no env suffix).
+    mkdirSync(join(dataHome, "vellum", "assistants", "prod-bot"), {
+      recursive: true,
+    });
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("ignores an env dir that holds no assistant subdirectory", () => {
+    mkdirSync(join(dataHome, "vellum-dev", "assistants"), { recursive: true });
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("returns empty when no env data dirs exist", () => {
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("swallows fs errors (data root is a file, not a dir) and returns empty", () => {
+    const filePath = join(dataHome, "not-a-dir");
+    writeFileSync(filePath, "x");
+    process.env.XDG_DATA_HOME = filePath;
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+    expect(crossEnvironmentAssistantHint()).toBeNull();
+  });
+
+  test("hint names the env, the current env, and both fixes", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    const hint = crossEnvironmentAssistantHint();
+    expect(hint).not.toBeNull();
+    expect(hint).toContain("'dev'");
+    expect(hint).toContain("This CLI targets 'production'");
+    expect(hint).toContain("Install vellum Command");
+    expect(hint).toContain("VELLUM_ENVIRONMENT=dev");
+  });
+
+  test("hint is null when no other env has assistants", () => {
+    expect(crossEnvironmentAssistantHint()).toBeNull();
+  });
+});

package/src/lib/environments/detect.ts

@@ -0,0 +1,79 @@
+import { readdirSync } from "fs";
+
+import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+
+import { getMultiInstanceDir } from "./paths.js";
+import { getCurrentEnvironment } from "./resolve.js";
+
+/**
+ * Names of OTHER environments (every seed except `currentEnv`) whose
+ * multi-instance data dir exists and holds at least one assistant
+ * subdirectory.
+ *
+ * Each environment has its own on-host data layout — see
+ * {@link getMultiInstanceDir}. A user who hatched via a dev/staging desktop
+ * app but runs the production npm CLI (or vice versa) targets a different
+ * layout than the app did, so the assistant the app created is invisible to
+ * this CLI. This cheap filesystem scan surfaces that split so callers can
+ * point the user at the environment that actually holds their assistants.
+ *
+ * Never throws: a missing or unreadable dir just means that environment has no
+ * discoverable assistants, so it is skipped. Returns an empty array on any
+ * error.
+ */
+export function detectOtherEnvironmentAssistants(
+  currentEnv: EnvironmentDefinition,
+): string[] {
+  const found: string[] = [];
+  for (const env of Object.values(SEEDS)) {
+    if (env.name === currentEnv.name) {
+      continue;
+    }
+    try {
+      const hasAssistant = readdirSync(getMultiInstanceDir(env), {
+        withFileTypes: true,
+      }).some((dirent) => dirent.isDirectory());
+      if (hasAssistant) {
+        found.push(env.name);
+      }
+    } catch {
+      // Missing or unreadable dir — this environment has no discoverable
+      // assistants. Skip it.
+    }
+  }
+  return found;
+}
+
+/**
+ * One-line hint appended to "no assistant found" and "gateway unreachable"
+ * errors when another environment's data dir holds assistants. A first-time
+ * user who hatched via a dev/staging desktop app while running the production
+ * npm CLI otherwise gets a bare failure with no clue the two tools target
+ * different environments.
+ *
+ * Returns null when nothing is found so callers can append unconditionally:
+ * `message + (crossEnvironmentAssistantHint() ?? "")`. Detection failure never
+ * propagates — the caller's original error must survive intact.
+ */
+export function crossEnvironmentAssistantHint(): string | null {
+  let currentEnv: EnvironmentDefinition;
+  let others: string[];
+  try {
+    currentEnv = getCurrentEnvironment();
+    others = detectOtherEnvironmentAssistants(currentEnv);
+  } catch {
+    return null;
+  }
+  if (others.length === 0) {
+    return null;
+  }
+
+  const quoted = others.map((name) => `'${name}'`).join(", ");
+  const noun = others.length > 1 ? "environments" : "environment";
+  return (
+    `\n\nFound assistants in the ${quoted} ${noun} (managed by a dev/staging ` +
+    `desktop app). This CLI targets '${currentEnv.name}'. Use the desktop ` +
+    `app's 'Install vellum Command…' menu item to get a matching CLI, or ` +
+    `set VELLUM_ENVIRONMENT=${others[0]}.`
+  );
+}

package/src/lib/stale-cli-hint.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared tail for errors where this CLI doesn't recognize an option or provider
+ * the user named. The name may be valid in a newer release, so point the user
+ * at the self-update path before they conclude the feature doesn't exist.
+ *
+ * `bun install -g vellum@latest` refreshes the `vellum` binary directly — the
+ * mechanism the installer and the CLI's own self-update use. (`vellum upgrade`
+ * targets the assistant runtime, not the CLI binary, for local assistants.)
+ */
+export const STALE_CLI_UPDATE_HINT =
+  "your CLI may be out of date — update it with `bun install -g vellum@latest` and retry.";