@vellumai/cli 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/src/lib/orphan-detection.ts

@@ -14,6 +14,8 @@ export interface RemoteProcess {
   command: string;
 }
 
+const VELLUM_PROCESS_MARKER = /vellum|qdrant|openclaw/;
+
 export function classifyProcess(command: string): string {
   if (/qdrant/.test(command)) return "qdrant";
   if (/vellum-gateway/.test(command)) return "gateway";
@@ -23,9 +25,9 @@ export function classifyProcess(command: string): string {
     )
   )
     return "openclaw-adapter";
-  if (/vellum-daemon/.test(command)) return "assistant";
+  if (/vellum-daemon|[\\/]daemon[\\/]main/.test(command)) return "assistant";
   if (/daemon\s+(start|restart)/.test(command)) return "assistant";
-  if (/vellum-cli/.test(command)) return "vellum";
+  if (/vellum-cli|[\\/]vellum(?:-cli)?\.exe/.test(command)) return "vellum";
   // Exclude macOS desktop app processes — their path contains .app/Contents/MacOS/
   // but they are not background service processes.
   if (/\.app\/Contents\/MacOS\//.test(command)) return "unknown";
@@ -56,7 +58,8 @@ export function classifyProcess(command: string): string {
  * logs in the terminal).
  */
 export function isInteractiveCliSession(command: string): boolean {
-  const vellumToken = /(?:^|\/)vellum(?:-cli)?(?:\s+--(?:no-color|plain))*/;
+  const vellumToken =
+    /(?:^|[\\/])vellum(?:-cli)?(?:\.exe)?["']?(?:\s+--(?:no-color|plain))*/;
   const interactiveSubcommand = new RegExp(
     vellumToken.source +
       String.raw`\s+(?:tunnel|events|logs|client|terminal|ssh|exec|message|workflows)\b`,
@@ -154,6 +157,28 @@ export interface DetectOrphansOptions {
    * avoid touching the real on-host lockfiles.
    */
   excludePids?: Set<string>;
+  platform?: NodeJS.Platform;
+}
+
+const WINDOWS_PROCESS_LIST_SCRIPT =
+  'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId) $($_.CommandLine)" }';
+
+export function processTableCommand(hostPlatform: NodeJS.Platform): {
+  command: string;
+  args: string[];
+} {
+  if (hostPlatform === "win32") {
+    return {
+      command: "powershell.exe",
+      args: [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        WINDOWS_PROCESS_LIST_SCRIPT,
+      ],
+    };
+  }
+  return { command: "ps", args: ["ax", "-o", "pid=,ppid=,args="] };
 }
 
 export async function detectOrphanedProcesses(
@@ -173,20 +198,17 @@ export async function detectOrphanedProcesses(
   // 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",
-        "ps ax -o pid=,ppid=,args= | grep -E 'vellum|qdrant|openclaw' | grep -v grep",
-      ],
-      { timeoutMs: 5_000 },
-    );
+    const table = processTableCommand(options.platform ?? process.platform);
+    const output = await execOutput(table.command, table.args, {
+      timeoutMs: 5_000,
+    });
     const procs = parseRemotePs(output);
     const ownPid = String(process.pid);
 
     for (const p of procs) {
       if (p.pid === ownPid || seenPids.has(p.pid)) continue;
       if (knownPids.has(p.pid)) continue;
+      if (!VELLUM_PROCESS_MARKER.test(p.command)) continue;
       // Live interactive sessions are spared before classification so that
       // service substrings in their argv cannot mark them as orphans.
       if (isInteractiveCliSession(p.command)) {

package/src/lib/pgrep.ts

@@ -1,12 +1,30 @@
 import { execOutput } from "./step-runner";
+import { executableName, parseTasklistCsv } from "./process.js";
 
 const PGREP_TIMEOUT_MS = 5_000;
 
-export async function pgrepExact(name: string): Promise<string[]> {
+export async function pgrepExact(
+  name: string,
+  hostPlatform: NodeJS.Platform = process.platform,
+): Promise<string[]> {
   try {
-    const output = await execOutput("pgrep", ["-x", name], {
+    const command = hostPlatform === "win32" ? "tasklist.exe" : "pgrep";
+    const args =
+      hostPlatform === "win32"
+        ? [
+            "/FI",
+            `IMAGENAME eq ${executableName(name, hostPlatform)}`,
+            "/FO",
+            "CSV",
+            "/NH",
+          ]
+        : ["-x", name];
+    const output = await execOutput(command, args, {
       timeoutMs: PGREP_TIMEOUT_MS,
     });
+    if (hostPlatform === "win32") {
+      return parseTasklistCsv(output).map(({ pid }) => String(pid));
+    }
     return output.trim().split("\n").filter(Boolean);
   } catch {
     return [];

package/src/lib/process.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "child_process";
 import { existsSync, readFileSync, unlinkSync } from "fs";
+import { platform } from "os";
 
 import {
   httpHealthCheck,
@@ -8,21 +9,115 @@ import {
   waitForDaemonReady,
 } from "./http-client.js";
 
+const VELLUM_COMMAND_PATTERN =
+  /vellum-daemon|vellum-cli|vellum-gateway|credential-executor|@vellumai|[\\/]\.?vellum[\\/]|[\\/]daemon[\\/]main|[\\/]\.vellum[\\/].*qdrant[\\/]bin[\\/]qdrant/;
+
+export const isVellumCommandLine = (command: string): boolean =>
+  VELLUM_COMMAND_PATTERN.test(command);
+
 /**
  * Verify that a PID belongs to a vellum-related process by inspecting its
  * command line via `ps`. Prevents killing unrelated processes when a PID file
  * is stale and the OS has reused the PID.
  */
-export function isVellumProcess(pid: number): boolean {
+export function executableName(
+  name: string,
+  hostPlatform: NodeJS.Platform = platform(),
+): string {
+  return hostPlatform === "win32" && !name.endsWith(".exe")
+    ? `${name}.exe`
+    : name;
+}
+
+export function pathListDelimiter(
+  hostPlatform: NodeJS.Platform = platform(),
+): string {
+  return hostPlatform === "win32" ? ";" : ":";
+}
+
+export interface TasklistProcess {
+  imageName: string;
+  pid: number;
+}
+
+export function parseTasklistCsv(output: string): TasklistProcess[] {
+  const processes: TasklistProcess[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^"([^"]+)","(\d+)"/);
+    if (match) {
+      processes.push({ imageName: match[1], pid: Number(match[2]) });
+    }
+  }
+  return processes;
+}
+
+function readWindowsProcesses(pid?: number): TasklistProcess[] {
+  const args = pid
+    ? ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"]
+    : ["/FO", "CSV", "/NH"];
+  const output = execFileSync("tasklist.exe", args, {
+    encoding: "utf-8",
+    timeout: 5000,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  return parseTasklistCsv(output);
+}
+
+export function windowsCommandLineLookupArgs(pid: number): string[] {
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    throw new Error(`Invalid process ID: ${pid}`);
+  }
+  return [
+    "-NoProfile",
+    "-NonInteractive",
+    "-Command",
+    `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}').CommandLine`,
+  ];
+}
+
+function readWindowsCommandLine(pid: number): string {
+  return execFileSync("powershell.exe", windowsCommandLineLookupArgs(pid), {
+    encoding: "utf8",
+    timeout: 3000,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+}
+
+export function isVellumWindowsProcess(
+  imageName: string,
+  commandLine = "",
+): boolean {
+  if (/^qdrant\.exe$/i.test(imageName)) {
+    return isVellumCommandLine(commandLine);
+  }
+  if (
+    /^(?:vellum|vellum-cli|vellum-daemon|vellum-gateway|credential-executor)\.exe$/i.test(
+      imageName,
+    )
+  ) {
+    return true;
+  }
+  return /^bun\.exe$/i.test(imageName) && isVellumCommandLine(commandLine);
+}
+
+export function isVellumProcess(
+  pid: number,
+  hostPlatform: NodeJS.Platform = platform(),
+): boolean {
   try {
+    if (hostPlatform === "win32") {
+      const imageName = readWindowsProcesses(pid)[0]?.imageName ?? "";
+      const commandLine = /^(?:bun|qdrant)\.exe$/i.test(imageName)
+        ? readWindowsCommandLine(pid)
+        : "";
+      return isVellumWindowsProcess(imageName, commandLine);
+    }
     const output = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
       encoding: "utf-8",
       timeout: 3000,
       stdio: ["ignore", "pipe", "ignore"],
     }).trim();
-    return /vellum-daemon|vellum-cli|vellum-gateway|credential-executor|@vellumai|\/\.?vellum\/|\/daemon\/main|\/\.vellum\/.*qdrant\/bin\/qdrant/.test(
-      output,
-    );
+    return isVellumCommandLine(output);
   } catch {
     return false;
   }
@@ -89,6 +184,7 @@ export async function isProcessHealthy(
  * - `"migration_failed"` — process is alive and healthy, but its DB migrations
  *   failed: a terminal state that never recovers without a restart. The
  *   process is kept alive (same keep-alive rule as `"unready"`).
+ * - `"stuck"`: process is unresponsive and could not be terminated.
  * - `"needs_start"` — process was dead, hung (and killed), or a stale PID
  *   was cleaned up. Caller should start a fresh process.
  */
@@ -96,6 +192,7 @@ export type ProcessState =
   | { status: "healthy"; pid: number }
   | { status: "unready"; pid: number }
   | { status: "migration_failed"; pid: number }
+  | { status: "stuck"; pid: number }
   | { status: "needs_start"; pid: number | null };
 
 /**
@@ -140,7 +237,10 @@ export async function resolveProcessState(
         console.log(
           `${label} process alive (pid ${result.pid}) but not responding — killing and restarting...`,
         );
-        await stopProcess(result.pid, label);
+        const stopped = await stopProcess(result.pid, label);
+        if (!stopped && isProcessAlive(pidFile).alive) {
+          return { status: "stuck", pid: result.pid };
+        }
       } else {
         console.log(
           `Stale PID file (pid ${result.pid} is not a Vellum process) — cleaning up...`,
@@ -177,12 +277,20 @@ export async function resolveProcessState(
 
 /**
  * Stop a process by PID: SIGTERM, wait up to `timeoutMs`, then SIGKILL if still alive.
- * Returns true if the process was stopped, false if it wasn't alive.
+ * Returns true if the process was stopped, false if it wasn't alive or
+ * termination failed.
  */
 export async function stopProcess(
   pid: number,
   label: string,
   timeoutMs: number = 2000,
+  hostPlatform: NodeJS.Platform = platform(),
+  runTaskkill: (args: string[], timeout: number) => void = (args, timeout) => {
+    execFileSync("taskkill.exe", args, {
+      timeout,
+      stdio: "ignore",
+    });
+  },
 ): Promise<boolean> {
   try {
     process.kill(pid, 0);
@@ -191,10 +299,19 @@ export async function stopProcess(
   }
 
   console.log(`Stopping ${label} (pid ${pid})...`);
-  process.kill(pid, "SIGTERM");
+  let waitForGracefulExit = true;
+  if (hostPlatform === "win32") {
+    try {
+      runTaskkill(["/PID", String(pid), "/T"], timeoutMs);
+    } catch {
+      waitForGracefulExit = false;
+    }
+  } else {
+    process.kill(pid, "SIGTERM");
+  }
 
   const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
+  while (waitForGracefulExit && Date.now() < deadline) {
     try {
       process.kill(pid, 0);
       await new Promise((r) => setTimeout(r, 100));
@@ -205,13 +322,33 @@ export async function stopProcess(
 
   try {
     process.kill(pid, 0);
-    console.log(`${label} did not exit after SIGTERM, sending SIGKILL...`);
-    process.kill(pid, "SIGKILL");
   } catch {
-    // Already dead
+    return true;
+  }
+  if (hostPlatform === "win32") {
+    console.log(`${label} did not exit, terminating its process tree...`);
+    try {
+      runTaskkill(["/PID", String(pid), "/T", "/F"], timeoutMs);
+    } catch {
+      return false;
+    }
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch {
+      return true;
+    }
+  }
+  console.log(`${label} did not exit after SIGTERM, sending SIGKILL...`);
+  try {
+    process.kill(pid, "SIGKILL");
+    return true;
+  } catch (error) {
+    return (
+      error instanceof Error &&
+      (error as NodeJS.ErrnoException).code === "ESRCH"
+    );
   }
-
-  return true;
 }
 
 /** Remove one or more files, ignoring missing-file errors. */
@@ -235,6 +372,12 @@ export async function stopProcessByPidFile(
   label: string,
   extraCleanupFiles?: string[],
   timeoutMs?: number,
+  stop: (
+    pid: number,
+    label: string,
+    timeoutMs?: number,
+  ) => Promise<boolean> = stopProcess,
+  ownsProcess: (pid: number) => boolean = isVellumProcess,
 ): Promise<boolean> {
   const { alive, pid } = isProcessAlive(pidFile);
 
@@ -246,7 +389,7 @@ export async function stopProcessByPidFile(
   // Verify the PID actually belongs to a vellum process before killing.
   // If the PID file is stale and the OS reused the PID, skip the kill
   // and clean up the stale files instead.
-  if (!isVellumProcess(pid)) {
+  if (!ownsProcess(pid)) {
     console.log(
       `PID ${pid} is not a vellum process — cleaning up stale ${label} PID file.`,
     );
@@ -254,8 +397,10 @@ export async function stopProcessByPidFile(
     return false;
   }
 
-  const stopped = await stopProcess(pid, label, timeoutMs);
-  removeFiles(pidFile, extraCleanupFiles);
+  const stopped = await stop(pid, label, timeoutMs);
+  if (stopped || !isProcessAlive(pidFile).alive) {
+    removeFiles(pidFile, extraCleanupFiles);
+  }
   return stopped;
 }
 
@@ -265,7 +410,33 @@ export async function stopProcessByPidFile(
  *
  * Returns true if at least one process was stopped.
  */
-export async function stopOrphanedDaemonProcesses(): Promise<boolean> {
+export async function stopOrphanedDaemonProcesses(
+  excludePids: ReadonlySet<string> = new Set(),
+  hostPlatform: NodeJS.Platform = platform(),
+): Promise<boolean> {
+  if (hostPlatform === "win32") {
+    try {
+      const results = await Promise.all(
+        readWindowsProcesses()
+          .filter(
+            ({ imageName, pid }) =>
+              pid !== process.pid &&
+              !excludePids.has(String(pid)) &&
+              (/^vellum-daemon\.exe$/i.test(imageName) ||
+                (/^bun\.exe$/i.test(imageName) &&
+                  /vellum-daemon|[\\/]assistant[\\/]src[\\/](?:index|daemon[\\/]main)\.ts/i.test(
+                    readWindowsCommandLine(pid),
+                  ))),
+          )
+          .map(({ pid }) =>
+            stopProcess(pid, "orphaned assistant", 2000, hostPlatform),
+          ),
+      );
+      return results.some(Boolean);
+    } catch {
+      return false;
+    }
+  }
   let output: string;
   try {
     output = execFileSync("ps", ["-axww", "-o", "pid=,command="], {
@@ -284,7 +455,9 @@ export async function stopOrphanedDaemonProcesses(): Promise<boolean> {
     const spaceIdx = trimmed.indexOf(" ");
     if (spaceIdx === -1) continue;
     const pid = parseInt(trimmed.slice(0, spaceIdx), 10);
-    if (isNaN(pid) || pid === process.pid) continue;
+    if (isNaN(pid) || pid === process.pid || excludePids.has(String(pid))) {
+      continue;
+    }
     const cmd = trimmed.slice(spaceIdx + 1);
 
     if (cmd.includes("vellum-daemon")) {

package/src/lib/retire-archive.ts

@@ -1,6 +1,20 @@
 import { mkdirSync } from "fs";
 import { homedir } from "os";
-import { basename, join, resolve } from "path";
+import { join, posix, win32 } from "path";
+
+function isPathInside(
+  parent: string,
+  candidate: string,
+  pathApi: typeof posix,
+): boolean {
+  const relativePath = pathApi.relative(parent, candidate);
+  return (
+    relativePath !== "" &&
+    relativePath !== ".." &&
+    !relativePath.startsWith(`..${pathApi.sep}`) &&
+    !pathApi.isAbsolute(relativePath)
+  );
+}
 
 export function getRetiredDir(): string {
   const xdgData =
@@ -23,21 +37,37 @@ export function validateAssistantName(name: string): void {
   }
 }
 
-function safeName(assistantId: string): string {
+function safeName(
+  assistantId: string,
+  retiredDir: string,
+  pathApi: typeof posix,
+): string {
   validateAssistantName(assistantId);
   // Canonicalize and verify the result stays inside the retired directory
-  const retiredDir = getRetiredDir();
-  const candidate = resolve(retiredDir, basename(assistantId));
-  if (!candidate.startsWith(retiredDir + "/")) {
+  const candidate = pathApi.resolve(retiredDir, pathApi.basename(assistantId));
+  if (!isPathInside(retiredDir, candidate, pathApi)) {
     throw new Error(`Invalid assistant name: '${assistantId}'`);
   }
-  return basename(assistantId);
+  return pathApi.basename(assistantId);
+}
+
+export function resolveRetiredFilePath(
+  assistantId: string,
+  extension: "tar.gz" | "json",
+  retiredDir: string,
+  hostPlatform: NodeJS.Platform = process.platform,
+): string {
+  const pathApi = hostPlatform === "win32" ? win32 : posix;
+  return pathApi.join(
+    retiredDir,
+    `${safeName(assistantId, retiredDir, pathApi)}.${extension}`,
+  );
 }
 
 export function getArchivePath(assistantId: string): string {
-  return join(getRetiredDir(), `${safeName(assistantId)}.tar.gz`);
+  return resolveRetiredFilePath(assistantId, "tar.gz", getRetiredDir());
 }
 
 export function getMetadataPath(assistantId: string): string {
-  return join(getRetiredDir(), `${safeName(assistantId)}.json`);
+  return resolveRetiredFilePath(assistantId, "json", getRetiredDir());
 }

package/src/lib/retire-local.ts

@@ -1,11 +1,16 @@
 import { spawn } from "child_process";
 import { homedir } from "os";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
-import { basename, dirname, join } from "path";
+import { basename, dirname, join, win32 } from "path";
 
-import { getDaemonPidPath, loadAllAssistants } from "./assistant-config.js";
+import {
+  getDaemonPidPath,
+  loadAllAssistants,
+  loadAllAssistantsAcrossEnvs,
+} from "./assistant-config.js";
 import type { AssistantEntry } from "./assistant-config.js";
 import { stopIngressNginx } from "./nginx-ingress.js";
+import { getKnownPidsFromAssistants } from "./orphan-detection.js";
 import {
   stopOrphanedDaemonProcesses,
   stopProcessByPidFile,
@@ -26,6 +31,61 @@ export interface RetireLocalResult {
   sharedDataDir?: boolean;
 }
 
+interface RetireArchiveCommand {
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+}
+
+const WINDOWS_RETIRE_ARCHIVE_SCRIPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "& tar.exe -czf $env:VELLUM_RETIRE_ARCHIVE_PATH -C $env:VELLUM_RETIRE_ARCHIVE_PARENT $env:VELLUM_RETIRE_STAGING_NAME",
+  "if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }",
+  "Remove-Item -LiteralPath $env:VELLUM_RETIRE_STAGING_DIR -Recurse -Force",
+].join("; ");
+
+export function getRetireArchiveCommand(
+  archivePath: string,
+  stagingDir: string,
+  hostPlatform: NodeJS.Platform = process.platform,
+): RetireArchiveCommand {
+  const archiveParent =
+    hostPlatform === "win32" ? win32.dirname(stagingDir) : dirname(stagingDir);
+  const stagingName =
+    hostPlatform === "win32"
+      ? win32.basename(stagingDir)
+      : basename(stagingDir);
+  if (hostPlatform === "win32") {
+    return {
+      command: "powershell.exe",
+      args: [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        WINDOWS_RETIRE_ARCHIVE_SCRIPT,
+      ],
+      env: {
+        VELLUM_RETIRE_ARCHIVE_PATH: archivePath,
+        VELLUM_RETIRE_ARCHIVE_PARENT: archiveParent,
+        VELLUM_RETIRE_STAGING_NAME: stagingName,
+        VELLUM_RETIRE_STAGING_DIR: stagingDir,
+      },
+    };
+  }
+  return {
+    command: "sh",
+    args: [
+      "-c",
+      'tar czf "$1" -C "$2" "$3" && rm -rf "$4"',
+      "vellum-retire",
+      archivePath,
+      archiveParent,
+      stagingName,
+      stagingDir,
+    ],
+  };
+}
+
 export async function retireLocal(
   name: string,
   entry: AssistantEntry,
@@ -99,7 +159,14 @@ export async function retireLocal(
   // If the PID file didn't track a running daemon, scan for orphaned
   // daemon processes that may have been started without writing a PID.
   if (!daemonStopped) {
-    await stopOrphanedDaemonProcesses();
+    const otherAssistantPids = getKnownPidsFromAssistants(
+      [...loadAllAssistantsAcrossEnvs(), ...loadAllAssistants()].filter(
+        (other) =>
+          other.assistantId !== name ||
+          other.resources?.instanceDir !== resources.instanceDir,
+      ),
+    );
+    await stopOrphanedDaemonProcesses(otherAssistantPids);
   }
 
   // For named instances (instanceDir differs from the base directory),
@@ -140,14 +207,13 @@ export async function retireLocal(
 
   // Spawn tar + cleanup in the background and detach so the CLI can exit
   // immediately. The staging directory is removed once the archive is written.
-  const tarCmd = [
-    `tar czf ${JSON.stringify(archivePath)} -C ${JSON.stringify(dirname(stagingDir))} ${JSON.stringify(basename(stagingDir))}`,
-    `rm -rf ${JSON.stringify(stagingDir)}`,
-  ].join(" && ");
-
-  const child = spawn("sh", ["-c", tarCmd], {
+  const archiveCommand = getRetireArchiveCommand(archivePath, stagingDir);
+  const child = spawn(archiveCommand.command, archiveCommand.args, {
     stdio: "ignore",
     detached: true,
+    ...(archiveCommand.env
+      ? { env: { ...process.env, ...archiveCommand.env } }
+      : {}),
   });
   child.unref();
 

package/src/lib/tunnel-edge.ts

@@ -10,17 +10,6 @@ import {
 } from "./nginx-ingress.js";
 import { hasWebhookIntegrations, maybeStartNgrokTunnel } from "./ngrok.js";
 
-/**
- * Retry policy for the flag lookup inside the tunnel-edge restore. The gateway
- * has typically been up for milliseconds at this point and answers
- * `503 {"status":"starting"}` (or refuses connections) until its startup
- * completes, so a single lookup races it.
- */
-export const WEB_INGRESS_FLAG_RETRY = {
-  attempts: 15,
-  intervalMs: 2_000,
-};
-
 /**
  * Whether the workspace ingress config wants the remote-web edge: explicitly
  * enabled with a saved public URL.
@@ -53,14 +42,14 @@ function wantsTunnelEdge(workspaceDir: string): boolean {
  * Bring the nginx edge back up after a wake or local upgrade and point the
  * webhook auto-tunnel at it. The edge is wanted when webhook integrations are
  * configured or the workspace ingress config is enabled with a saved public
- * URL; `ensureTunnelEdge` picks SPA vs webhooks-only mode off the
- * `web-remote-ingress` flag, retrying the lookup through the gateway's startup
- * window. A healthy edge whose recorded state already targets the requested
- * gateway port is reused without the flag lookup or the `remoteWebConfigHash`
- * comparison `startRemoteWebIngress` performs; both flag-driven mode drift
- * and injected-config drift (a renamed assistant, a changed hub URL) are
- * repaired by the next explicit `vellum tunnel` or `vellum nginx-ingress up`,
- * not by background wakes. Edge failures warn
+ * URL. A healthy SPA edge whose recorded state already targets the requested
+ * gateway port is reused without the `remoteWebConfigHash` comparison
+ * `startRemoteWebIngress` performs; injected-config drift (a renamed
+ * assistant, a changed hub URL) is repaired by the next explicit
+ * `vellum tunnel` or `vellum nginx-ingress up`, not by background wakes.
+ * A recorded webhooks-only edge is never reused: it goes through
+ * `ensureTunnelEdge` so the wake upgrades it to the SPA edge.
+ * Edge failures warn
  * (with the error's install or diagnostic text) and fall back to tunneling the
  * gateway port directly, which `maybeStartNgrokTunnel` only does when webhook
  * integrations are configured, so webhook channels on nginx-less machines
@@ -79,11 +68,15 @@ export async function restoreTunnelEdgeAndAutoTunnel(
       ? readIngressState(workspaceDir)
       : null;
     let edge: TunnelEdge | null = null;
-    if (recorded !== null && recorded.gatewayPort === gatewayPort) {
+    if (
+      recorded !== null &&
+      recorded.gatewayPort === gatewayPort &&
+      recorded.includeWebApp
+    ) {
       edge = {
         port: recorded.listenPort,
         started: false,
-        includesWebApp: recorded.includeWebApp,
+        includesWebApp: true,
       };
     } else {
       try {
@@ -91,7 +84,6 @@ export async function restoreTunnelEdgeAndAutoTunnel(
           assistantId,
           workspaceDir,
           gatewayPort,
-          flagRetry: WEB_INGRESS_FLAG_RETRY,
         });
       } catch (err) {
         console.warn(