@mycadet/cli 0.12.7-dev.202610111049.d2b52a8 → 0.12.8

package/src/commands/tunnel.ts

@@ -14,41 +14,36 @@ import {
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
-import { runCloudflareTunnel } from "../lib/cloudflare-tunnel.js";
 import { relaunchDetached } from "../lib/detached-process.js";
 import {
   getDefaultWorkspaceDir,
   isLocalContainerEntry,
   parseGatewayPortFromEntryUrls,
-  saveNgrokDomain,
 } from "../lib/ingress-config.js";
 import {
   ensureTunnelEdge,
   formatEdgeMode,
   type TunnelEdge,
 } from "../lib/nginx-ingress.js";
-import { hasWebhookIntegrationsConfigured, runNgrokTunnel } from "../lib/ngrok";
-import { shellArg } from "../lib/shell-arg.js";
 import { STALE_CLI_UPDATE_HINT } from "../lib/stale-cli-hint.js";
-import { runTailscaleTunnel } from "../lib/tailscale-tunnel.js";
-
-// `cadet` is the cloud option this command owns; the local providers come
-// from the shared registry so validation here cannot drift from what the
-// workspace config accepts.
-const VALID_PROVIDERS = ["cadet", ...TUNNEL_PROVIDERS] as const;
-type TunnelProvider = (typeof VALID_PROVIDERS)[number];
-
-// How far each provider's URL reaches, for the chooser a missing `--provider`
-// prints. Keyed off the registry so a new provider cannot ship unoffered.
-const PROVIDER_REACH: Record<TunnelProviderName, string> = {
-  ngrok: "Public tunnel that webhook integrations can reach",
-  cloudflare: "Public tunnel that webhook integrations can reach",
-  tailscale: "Tailnet-only tunnel, reachable from your own devices",
-};
+import {
+  ADOPTED_TUNNEL_RE,
+  DEFAULT_TUNNEL_PROVIDER,
+  PROVIDER_META,
+  adoptedTunnelStopNotice,
+  cadetTunnelComingSoonError,
+  clearReservedDomain,
+  hasWebhookIntegrationsConfigured,
+  providerSupportsReservedDomain,
+  runProviderTunnel,
+} from "../lib/tunnel.js";
+
+// The accepted `--provider` values ARE the shared registry, so validation
+// here cannot drift from what the workspace config accepts.
 
 interface TunnelArgs {
   assistantName: string | null;
-  provider: TunnelProvider;
+  provider: TunnelProviderName;
   domain: string | null;
   clearDomain: boolean;
   detach: boolean;
@@ -58,7 +53,7 @@ const FLAGS_WITH_VALUES = ["--provider", "--domain"] as const;
 
 function parseArgs(): TunnelArgs {
   const args = process.argv.slice(3);
-  let provider: TunnelProvider | null = null;
+  let provider: TunnelProviderName | null = null;
   let domain: string | null = null;
   let clearDomain = false;
   let detach = false;
@@ -76,14 +71,13 @@ function parseArgs(): TunnelArgs {
       );
       console.log("");
       console.log(
-        "How far that URL reaches depends on the provider, so --provider is required.",
-      );
-      console.log(
-        "A tailscale tunnel is reachable only from your own tailnet; webhook",
+        "How far that URL reaches depends on the provider; omit --provider for",
       );
+      console.log("the default. A tailscale tunnel is reachable only from your");
       console.log(
-        "integrations need a public tunnel: --provider ngrok or --provider cloudflare.",
+        "own tailnet; webhook integrations need a public tunnel (see Providers",
       );
+      console.log("below).");
       console.log("");
       console.log(
         "The tunnel always fronts the local nginx edge, which is started automatically.",
@@ -99,19 +93,21 @@ function parseArgs(): TunnelArgs {
       console.log("");
       console.log("Options:");
       console.log(
-        `  --provider <provider>         Required. Tunnel provider: ${VALID_PROVIDERS.join(", ")}`,
+        `  --provider <provider>         Tunnel provider: ${TUNNEL_PROVIDERS.join(", ")}`,
       );
+      console.log(`                                (default: ${DEFAULT_TUNNEL_PROVIDER})`);
       console.log(
-        "  --domain <domain>             Reserved ngrok domain to bind (ngrok provider only).",
+        "  --domain <domain>             Reserved domain to bind, for providers that support",
       );
       console.log(
-        "                                Saved to the workspace config so `cadet wake` restores reuse it.",
+        "                                one. Saved to the workspace config so `cadet wake` restores",
       );
+      console.log("                                reuse it.");
       console.log(
-        "  --clear-domain                Clear the saved ngrok domain (ngrok provider only) and tunnel",
+        "  --clear-domain                Clear the saved reserved domain (same providers) and",
       );
       console.log(
-        "                                without one. Cannot be combined with --domain.",
+        "                                tunnel without one. Cannot be combined with --domain.",
       );
       console.log(
         `  -d, --detach                  Run the tunnel in the background. Waits up to ${TUNNEL_BACKGROUND_START_TIMEOUT_MS / 1000}s for the`,
@@ -123,72 +119,64 @@ function parseArgs(): TunnelArgs {
         "                                the CLI log directory. Stop it with `kill <pid>`, except when it",
       );
       console.log(
-        "                                adopted an already-running ngrok tunnel (started outside this",
+        "                                adopted an already-running tunnel (started outside this",
       );
       console.log(
         "                                command): killing the supervisor then leaves that tunnel running.",
       );
       console.log("");
       console.log("Providers:");
-      console.log(
-        "  cadet       Managed tunnel via Cadet Cloud (not yet available)",
-      );
-      console.log(
-        "  ngrok        ngrok tunnel — install: brew install ngrok/ngrok/ngrok",
-      );
-      console.log(
-        "  cloudflare   Cloudflare quick tunnel — install: brew install cloudflare/cloudflare/cloudflared",
-      );
-      console.log(
-        "               No Cloudflare account required for quick tunnels.",
-      );
-      console.log(
-        "  tailscale    Tailscale serve. Install: https://tailscale.com/download, then run `tailscale up`",
-      );
-      console.log(
-        "               Reachable only from your own tailnet (private; LetsEncrypt cert).",
-      );
-      console.log(
-        "               When webhook integrations are configured it records its URL for device",
-      );
-      console.log(
-        "               pairing only, leaving the saved webhook callback base as it is.",
-      );
+      for (const name of TUNNEL_PROVIDERS) {
+        const meta = PROVIDER_META[name];
+        console.log(`  ${name.padEnd(12)}${meta.reach}`);
+        console.log(`  ${" ".repeat(12)}${meta.install}`);
+        for (const note of meta.notes ?? []) {
+          console.log(`  ${" ".repeat(12)}${note}`);
+        }
+      }
       console.log("");
       console.log("Examples:");
-      console.log("  $ cadet tunnel --provider ngrok");
-      console.log(
-        "  $ cadet tunnel --provider ngrok --domain my-assistant.ngrok.app",
-      );
-      console.log("  $ cadet tunnel --provider ngrok --clear-domain");
+      console.log(`  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER}`);
+      const domainExample = PROVIDER_META[DEFAULT_TUNNEL_PROVIDER].domainExample;
+      if (domainExample) {
+        console.log(
+          `  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER} --domain ${domainExample}`,
+        );
+        console.log(
+          `  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER} --clear-domain`,
+        );
+      }
       console.log("  $ cadet tunnel --provider cloudflare");
       console.log("  $ cadet tunnel my-assistant --provider tailscale");
-      console.log("  $ cadet tunnel --provider ngrok --detach");
+      console.log(
+        `  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER} --detach`,
+      );
       process.exit(0);
     } else if (arg === "--provider") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
         console.error(
-          `Error: --provider requires one of: ${VALID_PROVIDERS.join(", ")}`,
+          `Error: --provider requires one of: ${TUNNEL_PROVIDERS.join(", ")}`,
         );
         process.exit(1);
       }
-      if (!VALID_PROVIDERS.includes(next as TunnelProvider)) {
+      if (!TUNNEL_PROVIDERS.includes(next as TunnelProviderName)) {
         console.error(
-          `Error: unknown tunnel provider '${next}'. Valid providers: ${VALID_PROVIDERS.join(", ")}.`,
+          `Error: unknown tunnel provider '${next}'. Valid providers: ${TUNNEL_PROVIDERS.join(", ")}.`,
         );
         console.error(
           `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
         );
         process.exit(1);
       }
-      provider = next as TunnelProvider;
+      provider = next as TunnelProviderName;
       i++;
     } else if (arg === "--domain") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
+        const domainExample = PROVIDER_META[DEFAULT_TUNNEL_PROVIDER].domainExample;
         console.error(
-          "Error: --domain requires a value, e.g. --domain my-assistant.ngrok.app",
+          `Error: --domain requires a value${domainExample ? `, e.g. --domain ${domainExample}` : ""}`,
         );
         process.exit(1);
       }
@@ -210,32 +198,22 @@ function parseArgs(): TunnelArgs {
     parseAssistantTargetArg(args, FLAGS_WITH_VALUES) ?? null;
 
   if (provider === null) {
-    console.error(
-      "Error: --provider is required. How far the tunnel URL reaches depends on it, so there is no default.",
+    provider = DEFAULT_TUNNEL_PROVIDER;
+    console.log(
+      `Using the default provider: ${provider} (pass --provider to choose another).`,
     );
-    console.error("");
-    console.error("Run one of:");
-    // Carries the assistant through: dropping it would suggest a command that
-    // tunnels the active assistant instead of the one that was asked for.
-    const target = assistantName ? ` ${shellArg(assistantName)}` : "";
-    for (const name of TUNNEL_PROVIDERS) {
-      console.error(
-        `  cadet tunnel${target} --provider ${name.padEnd(13)}${PROVIDER_REACH[name]}`,
-      );
-    }
-    process.exit(1);
   }
 
-  if (domain && provider !== "ngrok") {
+  if (domain && !providerSupportsReservedDomain(provider)) {
     console.error(
-      `Error: --domain is only supported with --provider ngrok (got '${provider}').`,
+      `Error: --domain is not supported with --provider ${provider} (reserved domains have no equivalent there).`,
     );
     process.exit(1);
   }
 
-  if (clearDomain && provider !== "ngrok") {
+  if (clearDomain && !providerSupportsReservedDomain(provider)) {
     console.error(
-      `Error: --clear-domain is only supported with --provider ngrok (got '${provider}').`,
+      `Error: --clear-domain is not supported with --provider ${provider} (reserved domains have no equivalent there).`,
     );
     process.exit(1);
   }
@@ -350,8 +328,8 @@ function guardTailnetOnlyWebhookIngress(workspaceDir: string): boolean {
   console.warn(
     "⚠ Webhook integrations are configured, and the tailscale tunnel is reachable only from your own tailnet, " +
       "so it cannot serve their callbacks. The saved ingress base URL stays as it is and the tailnet URL is " +
-      "recorded for device pairing only. For a tunnel those integrations can reach too, use --provider ngrok " +
-      "or --provider cloudflare.",
+      "recorded for device pairing only. For a tunnel those integrations can reach too, run `cadet tunnel --help` " +
+      "to see the public providers.",
   );
   return true;
 }
@@ -359,16 +337,15 @@ function guardTailnetOnlyWebhookIngress(workspaceDir: string): boolean {
 // Generous cap so a slow provider handshake (e.g. cloudflared's own ~30s
 // quick-tunnel timeout) still counts as a successful, if slow, start.
 const TUNNEL_BACKGROUND_START_TIMEOUT_MS = 35_000;
-// Matches the "just established" line every provider prints, or ngrok's
-// "found an already-running agent" adoption line (captured separately since
-// that case does not own the tunnel it adopted).
+// Matches the "just established" line every provider prints, or the adoption
+// line printed when a run adopts an already-running agent's tunnel (captured
+// separately since that case does not own the tunnel it adopted).
 const TUNNEL_ESTABLISHED_RE = /Tunnel established: (\S+)/;
-const TUNNEL_ADOPTED_RE = /Found existing ngrok tunnel: (\S+)/;
 
 /**
  * Re-invoke `cadet tunnel` (without `-d`/`--detach`) as a detached background
  * process via `relaunchDetached`, waiting for the child to either print its
- * "Tunnel established"/"Found existing ngrok tunnel" line (readiness) or
+ * "Tunnel established" or adopted-tunnel line (readiness) or
  * exit early (failure), so a misconfigured provider still fails loudly in
  * the terminal that ran `-d`.
  *
@@ -404,7 +381,7 @@ async function spawnDetachedTunnel(): Promise<void> {
         publicUrl = established[1];
         return true;
       }
-      const adoptedMatch = TUNNEL_ADOPTED_RE.exec(logText);
+      const adoptedMatch = ADOPTED_TUNNEL_RE.exec(logText);
       if (adoptedMatch) {
         publicUrl = adoptedMatch[1];
         adopted = true;
@@ -430,11 +407,7 @@ async function spawnDetachedTunnel(): Promise<void> {
   }
   console.log(`Running in background (pid ${child.pid}). Logs: ${logPath}`);
   if (adopted) {
-    console.log(
-      `That ngrok agent was already running outside this command, so \`kill ${child.pid}\` only ` +
-        "stops this supervisor, not the ngrok tunnel or its saved ingress URL. Stop the ngrok agent " +
-        "directly to end the tunnel.",
-    );
+    console.log(adoptedTunnelStopNotice(child.pid));
   } else {
     console.log(`Stop with: kill ${child.pid}`);
   }
@@ -449,11 +422,8 @@ export const tunnel = Object.assign(
     return;
   }
 
-  if (provider === "cadet") {
-    throw new Error(
-      `Tunnel provider '${provider}' is not yet implemented. ` +
-        `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
-    );
+  if (PROVIDER_META[provider].comingSoon) {
+    throw cadetTunnelComingSoonError(provider);
   }
 
   const { entry, gatewayPort, workspaceDir } =
@@ -463,8 +433,8 @@ export const tunnel = Object.assign(
     provider === "tailscale" && guardTailnetOnlyWebhookIngress(workspaceDir);
 
   if (clearDomain) {
-    saveNgrokDomain(workspaceDir, null);
-    console.log("Cleared the saved ngrok domain from the workspace config.");
+    clearReservedDomain();
+    console.log("Cleared the saved reserved domain.");
   }
 
   let edge: TunnelEdge;
@@ -490,21 +460,9 @@ export const tunnel = Object.assign(
     workspaceDir,
   };
 
-  if (provider === "ngrok") {
-    await runNgrokTunnel({
-      ...baseTunnelOpts,
-      ...(domain ? { domain } : {}),
-    });
-    return;
-  }
-
-  if (provider === "cloudflare") {
-    await runCloudflareTunnel(baseTunnelOpts);
-    return;
-  }
-
-  await runTailscaleTunnel({
+  await runProviderTunnel(provider, {
     ...baseTunnelOpts,
+    ...(domain ? { domain } : {}),
     ...(preserveIngressUrl ? { preserveIngressUrl } : {}),
   });
 },

package/src/commands/upgrade.ts

@@ -1,7 +1,6 @@
 import { resolveExistingLocalSigningKey } from "@mycadet/local-mode";
 import { isCloudHome } from "../lib/cloud-values.js";
 import { spawnSync } from "child_process";
-import { writeFileSync } from "fs";
 import { join } from "path";
 
 import cliPkg from "../../package.json";
@@ -77,7 +76,7 @@ import {
   startLocalDaemon,
   stopLocalProcesses,
 } from "../lib/local.js";
-import { restoreTunnelEdgeAndAutoTunnel } from "../lib/tunnel-edge.js";
+import { restoreTunnelEdgeAndAutoTunnel } from "../lib/tunnel.js";
 import {
   leaseGuardianToken,
   resetGuardianBootstrap,
@@ -1018,17 +1017,11 @@ async function upgradeLocal(
   console.log("✅ Local assistant processes started\n");
 
   const workspaceDir = join(entry.resources.instanceDir, "workspace");
-  const ngrokChild = await restoreTunnelEdgeAndAutoTunnel(
+  await restoreTunnelEdgeAndAutoTunnel(
     entry.assistantId,
     entry.resources.gatewayPort,
     workspaceDir,
   );
-  if (ngrokChild?.pid) {
-    writeFileSync(
-      join(entry.resources.instanceDir, "ngrok.pid"),
-      String(ngrokChild.pid),
-    );
-  }
 
   console.log("Waiting for assistant to become ready...");
   const ready = await waitForReady(adminUrl);

package/src/commands/wake.ts

@@ -2,7 +2,6 @@ import {
   SigningKeyContinuityError,
   resolveExistingLocalSigningKey,
 } from "@mycadet/local-mode";
-import { writeFileSync } from "fs";
 import { join } from "path";
 
 import {
@@ -47,7 +46,7 @@ import {
   DOCKER_GATEWAY_READY_TIMEOUT_MS,
   restoreContainerTunnelEdge,
   restoreTunnelEdgeAndAutoTunnel,
-} from "../lib/tunnel-edge.js";
+} from "../lib/tunnel.js";
 
 export const wake = Object.assign(
   async function wake(): Promise<void> {
@@ -582,18 +581,15 @@ async function wakeAssistant(
     }
   }
 
-  // Restore the nginx edge and point the webhook auto-tunnel at it. Non-fatal:
-  // a down edge is a degraded remote-web/webhook path, not a broken assistant.
+  // Restore the nginx edge and point the auto-tunnel at it. The spawned agent
+  // records itself in the root lockfile under `tunnel`. Non-fatal: a down
+  // edge is a degraded remote-web/webhook path, not a broken assistant.
   const workspaceDir = join(resources.instanceDir, "workspace");
-  const ngrokChild = await restoreTunnelEdgeAndAutoTunnel(
+  await restoreTunnelEdgeAndAutoTunnel(
     entry.assistantId,
     resources.gatewayPort,
     workspaceDir,
   );
-  if (ngrokChild?.pid) {
-    const ngrokPidFile = join(resources.instanceDir, "ngrok.pid");
-    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-  }
 
   if (daemonMigrationsFailed) {
     console.log(

package/src/lib/assistant-config.ts

@@ -152,9 +152,28 @@ interface LockfileData {
   assistants?: Record<string, unknown>[];
   activeAssistant?: string;
   cloudBaseUrl?: string;
+  tunnel?: RootProcessRecord;
+  app?: RootProcessRecord;
   [key: string]: unknown;
 }
 
+/**
+ * A CLI-managed OS process recorded at the lockfile root, keyed by what it is
+ * for — `tunnel` (the auto-tunnel agent fronting the edge) and `app` (the
+ * nginx ingress edge). `cadet ps` renders these alongside the per-assistant
+ * process trees, and the stop paths verify the pid before signaling it.
+ */
+export interface RootProcessRecord {
+  pid: number;
+  /** Which tunnel provider owns the process; "tunnel" entries only. */
+  provider?: string;
+  /** The assistant the process fronts, so `cadet ps` can nest the row. */
+  assistantId?: string;
+  startedAt: string;
+}
+
+export type RootProcessKind = "tunnel" | "app";
+
 /**
  * Derive the daemon PID file path from a resources object. The PID file
  * lives inside the instance's workspace directory. When no resources are
@@ -216,6 +235,40 @@ function withCliLockfileLock<T>(fn: () => T): T {
   return locked.value;
 }
 
+/** Record a CLI-managed root process (tunnel agent, app edge) by pid. */
+export function stampRootProcess(
+  kind: RootProcessKind,
+  record: RootProcessRecord,
+): void {
+  withCliLockfileLock(() => {
+    const data = readLockfile();
+    data[kind] = record;
+    writeLockfileUnlocked(data);
+  });
+}
+
+/** Drop the recorded root process entry, e.g. once the process is stopped. */
+export function clearRootProcess(kind: RootProcessKind): void {
+  withCliLockfileLock(() => {
+    const data = readLockfile();
+    if (data[kind] === undefined) return;
+    delete data[kind];
+    writeLockfileUnlocked(data);
+  });
+}
+
+/**
+ * Read the root-level process entries for `cadet ps`. Read-only: no lock, so
+ * a concurrently-updating lockfile is fine — the pid is verified separately.
+ */
+export function readRootProcesses(): {
+  tunnel?: RootProcessRecord;
+  app?: RootProcessRecord;
+} {
+  const data = readLockfile();
+  return { tunnel: data.tunnel, app: data.app };
+}
+
 /**
  * Try to extract a port number from a URL string (e.g. `http://localhost:7830`).
  * Returns undefined if the URL is malformed or has no explicit port.

package/src/lib/detached-process.ts

@@ -6,7 +6,7 @@ import { isCompiledCli } from "./local.js";
 import { getLogDir, openLogFile, resetLogFile } from "./xdg-log.js";
 
 export interface RelaunchDetachedOptions {
-  /** argv for the re-invoked CLI command, e.g. ["tunnel", "--provider", "ngrok"]. */
+  /** argv for the re-invoked CLI command, e.g. ["tunnel", "--provider", "cloudflare"]. */
   args: string[];
   /** Log file basename under the XDG log dir; truncated before spawn. */
   logFile: string;

package/src/lib/ingress-config.ts

@@ -18,14 +18,13 @@ import { getStateDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 
 /**
- * Shared workspace-config helpers for tunnel providers (ngrok, cloudflare,
- * tailscale) and the nginx ingress proxy. Each provider fronts the local edge
- * and records the resulting public URL under `ingress.publicBaseUrl` so webhook
- * integrations can reach the assistant. The workspace config is the
- * gateway-facing contract; when an `assistantId` is supplied, the URL is also
- * mirrored onto the lockfile entry (`ingressUrl`) — the CLI-owned contract
- * that CLI features (e.g. remote-web pairing defaults) read, per the
- * no-`.cadet/`-reads boundary in cli/AGENTS.md.
+ * Shared workspace-config helpers for tunnel providers and the nginx ingress
+ * proxy. Each provider fronts the local edge and records the resulting public
+ * URL under `ingress.publicBaseUrl` so webhook integrations can reach the
+ * assistant. The workspace config is the gateway-facing contract; when an
+ * `assistantId` is supplied, the URL is also mirrored onto the lockfile entry
+ * (`ingressUrl`) — the CLI-owned contract that CLI features (e.g. remote-web
+ * pairing defaults) read, per the no-`.cadet/`-reads boundary in cli/AGENTS.md.
  */
 
 function parsePortFromUrl(url: unknown): number | undefined {
@@ -186,32 +185,6 @@ export function savePairingTunnel(
   saveRawConfig(workspaceDir, config);
 }
 
-/** Persist a reserved ngrok domain under `ingress.ngrok.domain`; null clears it. */
-export function saveNgrokDomain(
-  workspaceDir: string,
-  domain: string | null,
-): void {
-  const config = loadRawConfig(workspaceDir);
-  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
-  if (domain) {
-    ingress.ngrok = { domain };
-  } else {
-    delete ingress.ngrok;
-  }
-  config.ingress = ingress;
-  saveRawConfig(workspaceDir, config);
-}
-
-/** Read the reserved ngrok domain from the workspace config, if saved. */
-export function loadNgrokDomain(workspaceDir: string): string | null {
-  const ingress = loadRawConfig(workspaceDir).ingress as
-    | Record<string, unknown>
-    | undefined;
-  const ngrok = ingress?.ngrok as Record<string, unknown> | undefined;
-  const domain = ngrok?.domain;
-  return typeof domain === "string" && domain.trim() ? domain : null;
-}
-
 /** Clear the ingress public base URL from the workspace config. */
 export function clearIngressUrl(
   workspaceDir: string,

package/src/lib/local.ts

@@ -74,11 +74,10 @@ import {
   executableName,
   isProcessAlive,
   pathListDelimiter,
-  readProcessCommandLine,
   resolveProcessState,
-  stopProcess,
   stopProcessByPidFile,
 } from "./process.js";
+import { stopTunnelProcess } from "./tunnel.js";
 import { stripVersionPrefix } from "./version-compat.js";
 import { openLogFile, pipeToLogFile } from "./xdg-log.js";
 
@@ -1931,16 +1930,6 @@ export async function startGateway(
   return gatewayUrl;
 }
 
-/** Check whether a PID belongs to an ngrok process via its command line. */
-function isNgrokProcess(pid: number): boolean {
-  try {
-    const output = readProcessCommandLine(pid);
-    return /ngrok/i.test(output);
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Stop any locally-running daemon and gateway processes
  * and clean up PID files. Called when hatch fails partway through
@@ -1969,22 +1958,12 @@ export async function stopLocalProcesses(
   const cesPidFile = join(cadetDir, "ces.pid");
   await stopProcessByPidFile(cesPidFile, "credential-executor");
 
-  // Kill ngrok directly by PID rather than using stopProcessByPidFile, because
-  // isCadetProcess() won't match the ngrok binary — resulting in a no-op that
-  // leaves ngrok running. Verify the PID still belongs to ngrok before killing
-  // to avoid hitting an unrelated process if the OS has reused the PID.
-  const ngrokPidFile = join(cadetDir, "ngrok.pid");
-  if (existsSync(ngrokPidFile)) {
-    try {
-      const pid = parseInt(readFileSync(ngrokPidFile, "utf-8").trim(), 10);
-      if (!isNaN(pid) && isNgrokProcess(pid)) {
-        await stopProcess(pid, "ngrok");
-      }
-      unlinkSync(ngrokPidFile);
-    } catch {}
-  }
+  // Stop the tunnel agent this CLI spawned (root lockfile `tunnel` entry),
+  // verifying the pid still belongs to the provider's binary before signaling
+  // it — PID reuse must never send an unrelated process a signal.
+  await stopTunnelProcess();
 
   // Stop the nginx ingress if one is fronting this gateway (it guards against
-  // PID reuse itself, mirroring the ngrok handling above).
+  // PID reuse itself).
   await stopIngressNginx(join(cadetDir, "workspace"));
 }