@vellumai/cli 0.10.12-staging.1 → 0.10.12-staging.2

package/src/__tests__/wake.test.ts

@@ -14,8 +14,11 @@ import { join } from "node:path";
 
 import * as assistantConfig from "../lib/assistant-config.js";
 import * as docker from "../lib/docker.js";
+import * as featureFlags from "../lib/feature-flags.js";
 import * as guardianToken from "../lib/guardian-token.js";
+import * as ingressConfig from "../lib/ingress-config.js";
 import * as local from "../lib/local.js";
+import * as nginxIngress from "../lib/nginx-ingress.js";
 import * as ngrok from "../lib/ngrok.js";
 import * as processLib from "../lib/process.js";
 import type { AssistantEntry } from "../lib/assistant-config.js";
@@ -138,11 +141,50 @@ mock.module("../lib/ngrok", () => ({
   maybeStartNgrokTunnel: maybeStartNgrokTunnelMock,
 }));
 
+const realFeatureFlags = { ...featureFlags };
+const realIngressConfig = { ...ingressConfig };
+const realNginxIngress = { ...nginxIngress };
+
+const isAssistantFeatureFlagEnabledMock = mock<
+  typeof featureFlags.isAssistantFeatureFlagEnabled
+>(async () => true);
+
+mock.module("../lib/feature-flags.js", () => ({
+  ...realFeatureFlags,
+  isAssistantFeatureFlagEnabled: isAssistantFeatureFlagEnabledMock,
+}));
+
+const loadRawConfigMock = mock<typeof ingressConfig.loadRawConfig>(() => ({}));
+
+mock.module("../lib/ingress-config.js", () => ({
+  ...realIngressConfig,
+  loadRawConfig: loadRawConfigMock,
+}));
+
+const isIngressRunningMock = mock<typeof nginxIngress.isIngressRunning>(
+  () => false,
+);
+const startRemoteWebIngressMock = mock<
+  typeof nginxIngress.startRemoteWebIngress
+>(async () => ({
+  status: "started",
+  listenPort: 7840,
+  webDistDir: "/tmp/web/dist",
+  version: "nginx/1.25.3",
+}));
+
+mock.module("../lib/nginx-ingress.js", () => ({
+  ...realNginxIngress,
+  isIngressRunning: isIngressRunningMock,
+  startRemoteWebIngress: startRemoteWebIngressMock,
+}));
+
 const { wake } = await import("../commands/wake.js");
 
 let tempDir: string;
 let originalArgv: string[];
 let logSpy: ReturnType<typeof spyOn>;
+let warnSpy: ReturnType<typeof spyOn>;
 
 function makeLocalEntry(): AssistantEntry {
   tempDir = mkdtempSync(join(tmpdir(), "vellum-wake-test-"));
@@ -167,6 +209,7 @@ beforeEach(() => {
   tempDir = "";
   process.argv = ["bun", "vellum", "wake", "--watch", "local-assistant"];
   logSpy = spyOn(console, "log").mockImplementation(() => {});
+  warnSpy = spyOn(console, "warn").mockImplementation(() => {});
 
   const entry = makeLocalEntry();
   resolveTargetAssistantMock.mockReset();
@@ -213,11 +256,25 @@ beforeEach(() => {
   );
   maybeStartNgrokTunnelMock.mockReset();
   maybeStartNgrokTunnelMock.mockResolvedValue(null);
+  isAssistantFeatureFlagEnabledMock.mockReset();
+  isAssistantFeatureFlagEnabledMock.mockResolvedValue(true);
+  loadRawConfigMock.mockReset();
+  loadRawConfigMock.mockReturnValue({});
+  isIngressRunningMock.mockReset();
+  isIngressRunningMock.mockReturnValue(false);
+  startRemoteWebIngressMock.mockReset();
+  startRemoteWebIngressMock.mockResolvedValue({
+    status: "started",
+    listenPort: 7840,
+    webDistDir: "/tmp/web/dist",
+    version: "nginx/1.25.3",
+  });
 });
 
 afterEach(() => {
   process.argv = originalArgv;
   logSpy.mockRestore();
+  warnSpy.mockRestore();
   if (tempDir) {
     rmSync(tempDir, { recursive: true, force: true });
   }
@@ -230,6 +287,9 @@ afterAll(() => {
   mock.module("../lib/process", () => realProcessLib);
   mock.module("../lib/local", () => realLocal);
   mock.module("../lib/ngrok", () => realNgrok);
+  mock.module("../lib/feature-flags.js", () => realFeatureFlags);
+  mock.module("../lib/ingress-config.js", () => realIngressConfig);
+  mock.module("../lib/nginx-ingress.js", () => realNginxIngress);
 });
 
 describe("vellum wake", () => {
@@ -342,3 +402,121 @@ describe("vellum wake", () => {
     expect(startLocalDaemonMock).not.toHaveBeenCalled();
   });
 });
+
+describe("vellum wake — web ingress restore", () => {
+  const enabledConfig = {
+    ingress: { enabled: true, publicBaseUrl: "https://assistant.example.com" },
+  };
+
+  beforeEach(() => {
+    process.argv = ["bun", "vellum", "wake", "local-assistant"];
+  });
+
+  test("restores the edge when ingress is enabled, the flag is on, and it is not already running", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+
+    await wake();
+
+    expect(isAssistantFeatureFlagEnabledMock).toHaveBeenCalledWith(
+      "local-assistant",
+      "web-remote-ingress",
+      { runtimeUrl: "http://127.0.0.1:7830" },
+    );
+    expect(startRemoteWebIngressMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workspaceDir: join(tempDir, ".vellum", "workspace"),
+        gatewayPort: 7830,
+      }),
+    );
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+
+  test("does not attempt a restore when ingress is disabled", async () => {
+    loadRawConfigMock.mockReturnValue({ ingress: { enabled: false } });
+
+    await wake();
+
+    expect(isAssistantFeatureFlagEnabledMock).not.toHaveBeenCalled();
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+  });
+
+  test("does not attempt a restore when ingress config is absent", async () => {
+    loadRawConfigMock.mockReturnValue({});
+
+    await wake();
+
+    expect(isAssistantFeatureFlagEnabledMock).not.toHaveBeenCalled();
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+  });
+
+  test("does not attempt a restore when enabled but the public URL is missing", async () => {
+    loadRawConfigMock.mockReturnValue({ ingress: { enabled: true } });
+
+    await wake();
+
+    expect(isAssistantFeatureFlagEnabledMock).not.toHaveBeenCalled();
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+  });
+
+  test("does not start a second edge when one is already running", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    isIngressRunningMock.mockReturnValue(true);
+
+    await wake();
+
+    // Already up — skip the flag probe and the start entirely.
+    expect(isAssistantFeatureFlagEnabledMock).not.toHaveBeenCalled();
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+  });
+
+  test("skips the restore quietly with a hint when the flag is off", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    isAssistantFeatureFlagEnabledMock.mockResolvedValue(false);
+
+    await wake();
+
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("web-remote-ingress"),
+    );
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+
+  test("a thrown restore failure warns but does not fail the wake", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    startRemoteWebIngressMock.mockRejectedValue(new Error("nginx boom"));
+
+    await wake();
+
+    expect(startRemoteWebIngressMock).toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+
+  test("an unreachable edge warns but does not fail the wake", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    startRemoteWebIngressMock.mockResolvedValue({
+      status: "unreachable",
+      listenPort: 7840,
+      logPath: "/tmp/nginx-ingress.log",
+    });
+
+    await wake();
+
+    expect(warnSpy).toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+
+  test("a failed flag probe warns and leaves the edge down without failing the wake", async () => {
+    loadRawConfigMock.mockReturnValue(enabledConfig);
+    isAssistantFeatureFlagEnabledMock.mockRejectedValue(
+      new Error("gateway unreachable"),
+    );
+
+    await wake();
+
+    expect(startRemoteWebIngressMock).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+});

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/nginx-ingress.ts

@@ -14,22 +14,16 @@ import {
   isAssistantFeatureFlagEnabled,
   WEB_REMOTE_INGRESS_FLAG,
 } from "../lib/feature-flags.js";
-import { waitForDaemonReady } from "../lib/http-client.js";
 import {
   DEFAULT_NGINX_INGRESS_PORT,
-  findWebDistDir,
   getIngressPaths,
   getIngressPid,
-  getNginxIngressPort,
-  getNginxVersion,
   isIngressRunning,
   resolveTunnelTargetPort,
-  startIngressNginx,
+  startRemoteWebIngress,
   stopIngressNginx,
 } from "../lib/nginx-ingress.js";
 
-const READY_TIMEOUT_MS = 5_000;
-
 function printHelp(): void {
   console.log("Usage: vellum nginx-ingress <subcommand> [<name>] [options]");
   console.log("");
@@ -164,79 +158,71 @@ async function assertWebRemoteIngressEnabled(
 
 async function up(target: NginxIngressTarget): Promise<void> {
   const { workspaceDir, gatewayPort } = target;
-  const listenPort = getNginxIngressPort();
 
   await assertWebRemoteIngressEnabled(target);
 
-  const version = getNginxVersion();
-  if (!version) {
-    console.error("Error: nginx is not installed.");
-    console.error("");
-    console.error("Install nginx:");
-    console.error("  macOS:  brew install nginx");
-    console.error("  Linux:  sudo apt install nginx");
-    console.error("");
-    console.error(
-      "Or point NGINX_BIN at an existing binary: NGINX_BIN=/path/to/nginx",
-    );
-    process.exit(1);
-  }
-
-  if (isIngressRunning(workspaceDir)) {
-    console.log("nginx ingress is already running.");
-    await status(target);
-    return;
-  }
-
-  const webDistDir = findWebDistDir();
-  if (!webDistDir) {
-    console.error(
-      "Error: unable to locate built web assets for remote web ingress.",
-    );
-    console.error("");
-    console.error("Build the SPA first:");
-    console.error("  cd clients/web && VITE_PLATFORM_MODE=false bun run build");
-    console.error("");
-    console.error(
-      "Or install @vellumai/web so its packaged dist directory is available.",
-    );
-    process.exit(1);
-  }
-
-  console.log(`Using ${version}`);
-  console.log(
-    `Starting nginx ingress on 127.0.0.1:${listenPort} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
-  );
-
-  const child = startIngressNginx({
+  const result = await startRemoteWebIngress({
     workspaceDir,
     gatewayPort,
-    listenPort,
-    remoteWebIngress: { webDistDir },
+    onStarting: ({ version, webDistDir, listenPort }) => {
+      console.log(`Using ${version}`);
+      console.log(
+        `Starting nginx ingress on 127.0.0.1:${listenPort} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
+      );
+    },
   });
-  child.unref();
 
-  // /healthz proxies through nginx to the gateway, so a 200 proves the whole
-  // ingress → gateway path works.
-  const ready = await waitForDaemonReady(listenPort, READY_TIMEOUT_MS);
-  if (!ready) {
-    const { logPath } = getIngressPaths(workspaceDir);
-    await stopIngressNginx(workspaceDir);
-    console.error(
-      `Error: nginx ingress did not become reachable on 127.0.0.1:${listenPort}.`,
-    );
-    console.error(`Check the nginx log: ${logPath}`);
-    process.exit(1);
+  switch (result.status) {
+    case "already-running":
+      console.log("nginx ingress is already running.");
+      await status(target);
+      return;
+    case "started":
+      console.log("");
+      console.log(
+        `nginx ingress running: http://127.0.0.1:${result.listenPort}`,
+      );
+      console.log("");
+      console.log("Next steps:");
+      console.log(
+        "  vellum tunnel --provider ngrok   # tunnel now targets nginx ingress",
+      );
+      console.log("  vellum nginx-ingress down        # stop the proxy");
+      return;
+    case "nginx-missing":
+      console.error("Error: nginx is not installed.");
+      console.error("");
+      console.error("Install nginx:");
+      console.error("  macOS:  brew install nginx");
+      console.error("  Linux:  sudo apt install nginx");
+      console.error("");
+      console.error(
+        "Or point NGINX_BIN at an existing binary: NGINX_BIN=/path/to/nginx",
+      );
+      break;
+    case "web-dist-missing":
+      console.error(
+        "Error: unable to locate built web assets for remote web ingress.",
+      );
+      console.error("");
+      console.error("Build the SPA first:");
+      console.error(
+        "  cd clients/web && VITE_PLATFORM_MODE=false bun run build",
+      );
+      console.error("");
+      console.error(
+        "Or install @vellumai/web so its packaged dist directory is available.",
+      );
+      break;
+    case "unreachable":
+      console.error(
+        `Error: nginx ingress did not become reachable on 127.0.0.1:${result.listenPort}.`,
+      );
+      console.error(`Check the nginx log: ${result.logPath}`);
+      break;
   }
 
-  console.log("");
-  console.log(`nginx ingress running: http://127.0.0.1:${listenPort}`);
-  console.log("");
-  console.log("Next steps:");
-  console.log(
-    "  vellum tunnel --provider ngrok   # tunnel now targets nginx ingress",
-  );
-  console.log("  vellum nginx-ingress down        # stop the proxy");
+  process.exit(1);
 }
 
 async function down(target: NginxIngressTarget): Promise<void> {

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/commands/wake.ts

@@ -30,6 +30,15 @@ import {
   startGateway,
 } from "../lib/local";
 import { maybeStartNgrokTunnel } from "../lib/ngrok";
+import {
+  isAssistantFeatureFlagEnabled,
+  WEB_REMOTE_INGRESS_FLAG,
+} from "../lib/feature-flags.js";
+import { loadRawConfig } from "../lib/ingress-config.js";
+import {
+  isIngressRunning,
+  startRemoteWebIngress,
+} from "../lib/nginx-ingress.js";
 
 export async function wake(): Promise<void> {
   const args = process.argv.slice(3);
@@ -379,6 +388,17 @@ export async function wake(): Promise<void> {
     writeFileSync(ngrokPidFile, String(ngrokChild.pid));
   }
 
+  // Restore the nginx web ingress edge when the workspace config still wants
+  // it. A TLS-terminating front (tailscale serve / tunnel) persists across
+  // restarts and keeps proxying to the edge's loopback port, but the edge has
+  // a manual lifecycle — so a routine restart otherwise leaves the self-hosted
+  // remote-web path dead (502 / blank page) until someone runs it back up.
+  await restoreWebIngressIfEnabled(
+    entry.assistantId,
+    resources.gatewayPort,
+    workspaceDir,
+  );
+
   if (daemonMigrationsFailed) {
     console.log(
       "Assistant database migrations FAILED — DB-backed routes will return 503 until the assistant is restarted. Check the daemon logs.",
@@ -404,3 +424,101 @@ export async function wake(): Promise<void> {
     });
   }
 }
+
+/**
+ * Bring the nginx web ingress edge back up after a wake when the workspace
+ * config still wants it. Only restores when ingress is explicitly enabled with
+ * a saved public URL and the `web-remote-ingress` flag is on — the edge is
+ * pointless without the flag, so a disabled flag skips quietly with a hint.
+ *
+ * Reads the same workspace config the edge serves. Any failure to restore
+ * warns with the manual `vellum nginx-ingress up` command and never fails the
+ * wake — a down edge is a degraded remote-web path, not a broken assistant.
+ */
+async function restoreWebIngressIfEnabled(
+  assistantId: string,
+  gatewayPort: number,
+  workspaceDir: string,
+): Promise<void> {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = config.ingress as
+    | { enabled?: unknown; publicBaseUrl?: unknown }
+    | undefined;
+  const enabled = ingress?.enabled === true;
+  const publicBaseUrl =
+    typeof ingress?.publicBaseUrl === "string"
+      ? ingress.publicBaseUrl.trim()
+      : "";
+  if (!enabled || !publicBaseUrl) {
+    return;
+  }
+
+  // The edge already survived (or was manually brought back) — nothing to do.
+  if (isIngressRunning(workspaceDir)) {
+    return;
+  }
+
+  let flagEnabled: boolean;
+  try {
+    flagEnabled = await isAssistantFeatureFlagEnabled(
+      assistantId,
+      WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl: `http://127.0.0.1:${gatewayPort}` },
+    );
+  } catch (err) {
+    console.warn(
+      `   Could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` flag to restore the web ingress edge; leaving it down. Bring it up manually with \`vellum nginx-ingress up\`. ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return;
+  }
+  if (!flagEnabled) {
+    console.log(
+      `   Web ingress edge not restored: the \`${WEB_REMOTE_INGRESS_FLAG}\` flag is off. Enable it and run \`vellum nginx-ingress up\` to serve remote web access.`,
+    );
+    return;
+  }
+
+  try {
+    const result = await startRemoteWebIngress({
+      workspaceDir,
+      gatewayPort,
+      onStarting: ({ listenPort }) => {
+        console.log(
+          `Restoring web ingress edge on 127.0.0.1:${listenPort} (ingress.enabled)...`,
+        );
+      },
+    });
+    switch (result.status) {
+      case "started":
+        console.log(
+          `   Web ingress edge running: http://127.0.0.1:${result.listenPort}`,
+        );
+        break;
+      case "already-running":
+        break;
+      case "nginx-missing":
+        console.warn(
+          "   Could not restore the web ingress edge: nginx is not installed. Bring it up manually with `vellum nginx-ingress up`.",
+        );
+        break;
+      case "web-dist-missing":
+        console.warn(
+          "   Could not restore the web ingress edge: built web assets were not found. Bring it up manually with `vellum nginx-ingress up`.",
+        );
+        break;
+      case "unreachable":
+        console.warn(
+          `   Web ingress edge did not become reachable on 127.0.0.1:${result.listenPort}; check ${result.logPath}. Bring it up manually with \`vellum nginx-ingress up\`.`,
+        );
+        break;
+    }
+  } catch (err) {
+    console.warn(
+      `   Failed to restore the web ingress edge: ${
+        err instanceof Error ? err.message : String(err)
+      }. Bring it up manually with \`vellum nginx-ingress up\`.`,
+    );
+  }
+}

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>'.`,