@mycadet/cli 0.12.9 → 0.12.11

package/src/lib/local.ts

@@ -79,7 +79,7 @@ import {
 } from "./process.js";
 import { stopTunnelProcess } from "./tunnel.js";
 import { stripVersionPrefix } from "./version-compat.js";
-import { openLogFile, pipeToLogFile } from "./xdg-log.js";
+import { openLogFile, openRuntimeLogFile, pipeToLogFile } from "./xdg-log.js";
 
 const _require = createRequire(import.meta.url);
 
@@ -839,7 +839,7 @@ async function startDaemonFromSource(
         windowsHide: true,
       })
     : (() => {
-        const daemonLogFd = openLogFile("hatch.log");
+        const daemonLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "assistant");
         const c = spawn(bunPath, ["run", resolve(daemonMainPath)], {
           cwd: spawnStateRoot(),
           detached: true,
@@ -912,7 +912,7 @@ async function startDaemonWatchFromSource(
   // detect the in-progress spawn and wait instead of racing.
   writeFileSync(pidFile, "starting", "utf-8");
 
-  const daemonLogFd = openLogFile("hatch.log");
+  const daemonLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "assistant");
   const child = spawn(
     resolveBunExecutable(),
     ["--watch", "run", resolve(mainPath)],
@@ -984,6 +984,41 @@ function resolveGatewayDir(resources?: LocalInstanceResources): string {
   }
 }
 
+/**
+ * How to invoke a `gateway <subcommand>` CLI process so it resolves the same
+ * workspace AND gateway security dir as the locally spawned gateway server:
+ * run the gateway package's CLI entry through bun with the spawn state root
+ * as cwd and the instance-pinned CADET_WORKSPACE_DIR / GATEWAY_SECURITY_DIR
+ * the server was given (the file-backed pairing store must resolve
+ * identically in both processes). Callers pass the resolved assistant
+ * entry's `resources` (undefined for the default instance, where both
+ * processes fall back to the same cwd-relative paths).
+ */
+export function gatewayCliInvocation(resources?: LocalInstanceResources): {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string | undefined>;
+} {
+  return {
+    command: resolveBunExecutable(),
+    args: ["run", join(resolveGatewayDir(resources), "src/cli/index.ts")],
+    cwd: spawnStateRoot(),
+    env: {
+      ...process.env,
+      ...(resources
+        ? {
+            CADET_WORKSPACE_DIR: join(resources.instanceDir, "workspace"),
+            GATEWAY_SECURITY_DIR: join(
+              resources.instanceDir,
+              "gateway-security",
+            ),
+          }
+        : {}),
+    },
+  };
+}
+
 function resolveCesDir(resources?: LocalInstanceResources): string {
   const runtimeCesDir = localRuntimeCesDir(resources);
   if (runtimeCesDir) return runtimeCesDir;
@@ -1118,9 +1153,7 @@ export async function startCes(
     // Source tree / bunx: run the CES entry point via bun.
     const cesDir = runtimeCesDir ?? resolveCesDir(resources);
     const cesEntry = join(cesDir, "src/main.ts");
-    const bunArgs = watch
-      ? ["--watch", "run", cesEntry]
-      : ["run", cesEntry];
+    const bunArgs = watch ? ["--watch", "run", cesEntry] : ["run", cesEntry];
     const cesLogFd = openLogFile("hatch.log");
     ces = spawn(resolveBunExecutable(), bunArgs, {
       cwd: spawnStateRoot(),
@@ -1666,7 +1699,7 @@ export async function startLocalDaemon(
             windowsHide: true,
           })
         : (() => {
-            const daemonLogFd = openLogFile("hatch.log");
+            const daemonLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "assistant");
             const c = spawn(daemonBinary, [], {
               cwd: spawnStateRoot(),
               detached: true,
@@ -1872,7 +1905,7 @@ export async function startGateway(
     // Use the compiled gateway binary when available (desktop app or compiled
     // CLI invoked from the terminal). In watch mode, skip the bundled binary
     // and use source (bun --watch only works with source files).
-    const gatewayLogFd = openLogFile("hatch.log");
+    const gatewayLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "gateway");
     gateway = spawn(gatewayBinary, [], {
       cwd: spawnStateRoot(),
       detached: true,
@@ -1888,7 +1921,7 @@ export async function startGateway(
     const bunArgs = watch
       ? ["--watch", "run", gatewayEntry, "--cadet-gateway"]
       : ["run", gatewayEntry, "--cadet-gateway"];
-    const gwLogFd = openLogFile("hatch.log");
+    const gwLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "gateway");
     gateway = spawn(resolveBunExecutable(), bunArgs, {
       cwd: spawnStateRoot(),
       detached: true,

package/src/lib/nginx-ingress.ts

@@ -13,6 +13,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { createServer } from "node:net";
 import { networkInterfaces } from "node:os";
 import { join } from "node:path";
 
@@ -166,7 +167,23 @@ export function cloudWebHubUrl(env: string | undefined): string {
 // must always run: it is reached through this self-hosted edge however the
 // cadet itself is hosted. "cloud" is never stamped (the cloud serves its
 // own bundles).
-const EDGE_SERVED_REMOTE: RemoteHost = "custom";
+/** The lockfile's recorded remote kind for the assistant, if one is found. */
+function lockfileAssistantRemote(assistantId: string): string | undefined {
+  const result = lookupAssistantByIdentifier(assistantId);
+  return result.status === "found" ? result.entry.cloud : undefined;
+}
+
+/**
+ * The remote kind stamped into the served SPA config. Docker and custom
+ * cadets are stamped truthfully; every other hosting shape — a local cadet
+ * reached through this edge, paired remotes, unknown entries — reads as
+ * "custom" so the served bundle always runs the remote-gateway machinery
+ * (this edge serves remote browsers however the cadet itself is hosted).
+ * "cloud" is never stamped: the cloud serves its own bundles.
+ */
+export function edgeServedRemote(recorded: string | undefined): RemoteHost {
+  return recorded === "docker" ? "docker" : "custom";
+}
 
 function remoteWebIngressConfig(
   opts: Pick<
@@ -175,10 +192,10 @@ function remoteWebIngressConfig(
   >,
 ): Record<string, unknown> {
   return {
-    remote: EDGE_SERVED_REMOTE,
+    remote: edgeServedRemote(
+      opts.assistantId ? lockfileAssistantRemote(opts.assistantId) : undefined,
+    ),
     apiBaseUrl: "/v1",
-    cloudDisabled: true,
-    disableCloud: true,
     ...(opts.assistantName ? { assistantName: opts.assistantName } : {}),
     ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
     ...(opts.hubUrl ? { hubUrl: opts.hubUrl } : {}),
@@ -191,17 +208,27 @@ function remoteWebIngressConfig(
  * fingerprint matches, so this must change whenever the generated index or
  * nginx template does.
  */
-export const EDGE_TEMPLATE_VERSION = 9;
+export const EDGE_TEMPLATE_VERSION = 10;
 
 /**
- * Stable fingerprint of the SPA config injected into the served index and
- * `/assistant/__config`, plus the template that renders them. Recorded
+ * Stable fingerprint of the injected SPA config, its source bundle, and
+ * the template that renders them. Recorded
  * alongside the edge state so a reuse decision can tell whether a running edge
  * already serves the requested config (see `IngressState.remoteWebConfigHash`).
  */
-function remoteWebConfigFingerprint(config: Record<string, unknown>): string {
+function remoteWebConfigFingerprint(
+  config: Record<string, unknown>,
+  webDistDir: string,
+): string {
   return createHash("sha256")
-    .update(JSON.stringify({ template: EDGE_TEMPLATE_VERSION, config }))
+    .update(
+      JSON.stringify({
+        template: EDGE_TEMPLATE_VERSION,
+        config,
+        webDistDir,
+        indexHtml: readFileSync(join(webDistDir, "index.html"), "utf-8"),
+      }),
+    )
     .digest("hex");
 }
 
@@ -280,6 +307,44 @@ export function hasIpv6Loopback(): boolean {
     .some((addr) => addr.address === "::1");
 }
 
+/** Whether a TCP listener already holds `port` on the given loopback host. */
+async function isPortInUse(
+  port: number,
+  host: "127.0.0.1" | "::1",
+): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => resolve(true));
+    probe.once("listening", () => {
+      probe.close(() => resolve(false));
+    });
+    probe.listen(port, host);
+  });
+}
+
+/**
+ * The first free loopback port at or above `startPort`, scanning a short band,
+ * or null when the whole band is busy. Both stacks the edge may bind are
+ * probed (the IPv4 loopback always, the IPv6 loopback when the host has one),
+ * so the returned port is one nginx can actually take.
+ */
+export async function findAvailableIngressPort(
+  startPort: number,
+  attempts = 20,
+): Promise<number | null> {
+  const checkIpv6 = hasIpv6Loopback();
+  for (let port = startPort; port < startPort + attempts; port++) {
+    if (await isPortInUse(port, "127.0.0.1")) {
+      continue;
+    }
+    if (checkIpv6 && (await isPortInUse(port, "::1"))) {
+      continue;
+    }
+    return port;
+  }
+  return null;
+}
+
 /**
  * Build the nginx config that forwards tunnel web traffic to the gateway.
  */
@@ -576,7 +641,7 @@ export interface IngressState {
    */
   gatewayPort?: number;
   /**
-   * Fingerprint of the SPA config injected into the served index. Undefined
+   * Fingerprint of the injected SPA config and its source bundle. Undefined
    * for webhooks-only edges and for SPA records that predate the field; an
    * SPA edge without a recorded fingerprint is treated as drifted and
    * restarted so the served index provably carries the requested config.
@@ -690,6 +755,7 @@ export function startIngressNginx(opts: {
       ? {
           remoteWebConfigHash: remoteWebConfigFingerprint(
             remoteWebIngress.config,
+            remoteWebIngress.webDistDir,
           ),
         }
       : {}),
@@ -859,7 +925,7 @@ export async function startRemoteWebIngress(opts: {
     listenPort: number;
   }) => void;
 }): Promise<StartRemoteWebIngressResult> {
-  const listenPort = opts.listenPort ?? getNginxIngressPort();
+  let listenPort = opts.listenPort ?? getNginxIngressPort();
   const includeWebApp = opts.includeWebApp ?? true;
 
   const version = getNginxVersion();
@@ -870,6 +936,13 @@ export async function startRemoteWebIngress(opts: {
   const running = isIngressRunning(opts.workspaceDir);
   const recorded = running ? readIngressState(opts.workspaceDir) : null;
   const recordedMode = recorded?.includeWebApp ?? true;
+  if (
+    recorded &&
+    opts.listenPort === undefined &&
+    process.env.CADET_NGINX_INGRESS_PORT === undefined
+  ) {
+    listenPort = recorded.listenPort;
+  }
   // The SPA config the served index must carry, computed up front so the
   // reuse decision and the actual spawn share one value and cannot drift.
   const spaOptions = includeWebApp
@@ -879,9 +952,17 @@ export async function startRemoteWebIngress(opts: {
         ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
       }
     : undefined;
-  const requestedConfigHash = spaOptions
-    ? remoteWebConfigFingerprint(remoteWebIngressConfig(spaOptions))
-    : undefined;
+  const webDistDir = includeWebApp ? findWebDistDir() : null;
+  if (includeWebApp && !webDistDir) {
+    return { status: "web-dist-missing" };
+  }
+  const requestedConfigHash =
+    spaOptions && webDistDir
+      ? remoteWebConfigFingerprint(
+          remoteWebIngressConfig(spaOptions),
+          webDistDir,
+        )
+      : undefined;
   // Both sides are undefined in webhooks-only mode; an SPA record without a
   // fingerprint predates the field and counts as drifted (see IngressState).
   const configMatches = recorded?.remoteWebConfigHash === requestedConfigHash;
@@ -908,14 +989,6 @@ export async function startRemoteWebIngress(opts: {
     return alreadyRunning();
   }
 
-  let webDistDir: string | null = null;
-  if (includeWebApp) {
-    webDistDir = findWebDistDir();
-    if (!webDistDir) {
-      return { status: "web-dist-missing" };
-    }
-  }
-
   // The running edge serves the other mode, targets a different gateway
   // port, or injects a stale SPA config; restart it with the requested
   // config. A false stop can mean the old edge exited on its own after the
@@ -928,6 +1001,23 @@ export async function startRemoteWebIngress(opts: {
     return alreadyRunning();
   }
 
+  // A foreign process squatting the default edge port (another assistant's
+  // edge, a stale dev server) must not kill the tunnel: the edge port is
+  // loopback-local and the public tunnel URL never carries it, so moving to
+  // the next free port is invisible to remote clients. Explicit pins
+  // (opts.listenPort / CADET_NGINX_INGRESS_PORT) keep their intent and still
+  // fail on a collision.
+  if (
+    opts.listenPort === undefined &&
+    process.env.CADET_NGINX_INGRESS_PORT === undefined
+  ) {
+    const discovered = await findAvailableIngressPort(listenPort);
+    if (discovered !== null && discovered !== listenPort) {
+      console.log(`Port ${listenPort} in use; using ${discovered} instead.`);
+      listenPort = discovered;
+    }
+  }
+
   opts.onStarting?.({ version, webDistDir, listenPort });
 
   const child = startIngressNginx({
@@ -1044,6 +1134,7 @@ export async function stopContainerTunnelEdge(
 function stampAppProcessEntry(
   workspaceDir: string,
   assistantId?: string,
+  port = getNginxIngressPort(),
 ): void {
   const pid = getIngressPid(workspaceDir);
   if (pid !== null) {
@@ -1051,6 +1142,7 @@ function stampAppProcessEntry(
       pid,
       startedAt: new Date().toISOString(),
       assistantId,
+      port,
     });
   }
 }
@@ -1118,7 +1210,11 @@ export async function ensureTunnelEdge(opts: {
 
   switch (result.status) {
     case "started":
-      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
+      stampAppProcessEntry(
+        opts.workspaceDir,
+        opts.assistantId,
+        result.listenPort,
+      );
       return {
         port: result.listenPort,
         started: true,
@@ -1152,7 +1248,11 @@ export async function ensureTunnelEdge(opts: {
             stuckEdgeRecoveryHint(opts.workspaceDir),
         );
       }
-      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
+      stampAppProcessEntry(
+        opts.workspaceDir,
+        opts.assistantId,
+        result.listenPort,
+      );
       return {
         port: result.listenPort,
         started: false,

package/src/lib/step-runner.ts

@@ -112,11 +112,16 @@ export function execWithStdin(
 export function execOutput(
   command: string,
   args: string[],
-  options: { cwd?: string; timeoutMs?: number } = {},
+  options: {
+    cwd?: string;
+    timeoutMs?: number;
+    env?: Record<string, string | undefined>;
+  } = {},
 ): Promise<string> {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
       cwd: options.cwd,
+      env: options.env,
       stdio: ["pipe", "pipe", "pipe"],
       windowsHide: true,
     });

package/src/lib/tunnel.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+import { TUNNEL_PROVIDERS } from "@mycadet/service-contracts/ingress";
 import {
   clearRootProcess,
   loadAllAssistants,
@@ -24,26 +26,24 @@ import { waitForDaemonReady } from "./http-client.js";
 import {
   hasWebhookIntegrations,
   IngressConfigSchema,
-  isNgrokProcess,
   maybeStartNgrokTunnel,
   NGROK_TUNNEL_META,
-  runNgrokTunnel,
+  NGROK_PROVIDER,
   saveNgrokDomain,
 } from "./tunnels/ngrok.js";
-import { stopProcess } from "./process.js";
 import { shellArg } from "./shell-arg.js";
 import { notifyGatewayOfPublicUrl } from "./tunnels/gateway-notify.js";
 import {
   selectRestartTunnelRecord,
   type TunnelProviderName,
 } from "@mycadet/service-contracts/ingress";
-import { runCadetTunnel, CADET_TUNNEL_META } from "./tunnels/cadet.js";
+import { CADET_PROVIDER, CADET_TUNNEL_META } from "./tunnels/cadet.js";
 import {
-  runCloudflareTunnel,
+  CLOUDFLARE_PROVIDER,
   CLOUDFLARE_TUNNEL_META,
 } from "./tunnels/cloudflare.js";
 import {
-  runTailscaleTunnel,
+  TAILSCALE_PROVIDER,
   TAILSCALE_TUNNEL_META,
 } from "./tunnels/tailscale.js";
 
@@ -119,6 +119,25 @@ export interface ProviderTunnelResult {
   waitForExit: Promise<void>;
 }
 
+export interface ProviderStopOptions {
+  record: RootProcessRecord;
+  assistantId?: string;
+  workspaceDir?: string;
+}
+
+export interface TunnelProvider {
+  run(opts: ProviderTunnelOptions): Promise<ProviderTunnelResult>;
+  stop(opts: ProviderStopOptions): Promise<boolean>;
+}
+
+const providers: Record<TunnelProviderName, TunnelProvider> = {
+  ngrok: NGROK_PROVIDER,
+  cloudflare: CLOUDFLARE_PROVIDER,
+  tailscale: TAILSCALE_PROVIDER,
+  cadet: CADET_PROVIDER,
+};
+const providerNameSchema = z.enum(TUNNEL_PROVIDERS);
+
 /**
  * Run a tunnel provider by name — the dispatch `cadet tunnel` uses, so the
  * command layer never names a provider implementation directly. Notifies the
@@ -140,29 +159,7 @@ function runProvider(
   provider: TunnelProviderName,
   opts: ProviderTunnelOptions,
 ): Promise<ProviderTunnelResult> {
-  const base = {
-    port: opts.port,
-    assistantId: opts.assistantId,
-    workspaceDir: opts.workspaceDir,
-  };
-  if (provider === "ngrok") {
-    return runNgrokTunnel({
-      ...base,
-      ...(opts.domain ? { domain: opts.domain } : {}),
-    });
-  }
-  if (provider === "cadet") {
-    return runCadetTunnel(opts);
-  }
-  if (provider === "cloudflare") {
-    return runCloudflareTunnel(base);
-  }
-  return runTailscaleTunnel({
-    ...base,
-    ...(opts.preserveIngressUrl
-      ? { preserveIngressUrl: opts.preserveIngressUrl }
-      : {}),
-  });
+  return providers[provider].run(opts);
 }
 
 /** Drop the saved reserved-domain record (providers that keep one). */
@@ -176,13 +173,31 @@ export function clearReservedDomain(): void {
  * signaling — a stale entry after PID reuse must not kill an unrelated
  * process.
  */
-export async function stopTunnelProcess(): Promise<void> {
+export async function stopTunnelProcess(
+  assistantId?: string,
+  workspaceDir?: string,
+): Promise<boolean> {
   const recorded: RootProcessRecord | undefined = readRootProcesses().tunnel;
-  if (!recorded) return;
-  if (isNgrokProcess(recorded.pid)) {
-    await stopProcess(recorded.pid, "tunnel");
+  if (!recorded) return false;
+  if (
+    assistantId &&
+    recorded.assistantId &&
+    recorded.assistantId !== assistantId
+  ) {
+    throw new Error(
+      `The recorded tunnel belongs to '${recorded.assistantId}', not '${assistantId}'.`,
+    );
   }
-  clearRootProcess("tunnel");
+  const provider = providerNameSchema.parse(
+    recorded.provider ?? DEFAULT_TUNNEL_PROVIDER,
+  );
+  const stopped = await providers[provider].stop({
+    record: recorded,
+    assistantId,
+    workspaceDir,
+  });
+  clearRootProcess("tunnel", recorded.pid);
+  return stopped;
 }
 
 /**
@@ -197,6 +212,43 @@ export function adoptedTunnelStopNotice(pid: number | undefined): string {
   );
 }
 
+/**
+ * Pull the single most meaningful failure line out of a tunnel log so the
+ * `cadet tunnel` wrapper can name why the child died instead of only pointing
+ * at the log file. Priority: nginx emerg/bind failures, ngrok error codes,
+ * auth/usage failures, then any generic error/fatal/failed line — the LAST
+ * match wins (the freshest), capped to keep the console line readable. Falls
+ * back to the last non-empty log line, or null for an empty log.
+ */
+export function summarizeStartupFailure(logText: string): string | null {
+  const lines = logText
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length === 0) {
+    return null;
+  }
+  const patterns: RegExp[] = [
+    /\[emerg\]/,
+    /bind\(\).*failed/i,
+    /address already in use/i,
+    /ERR_NGROK_\d+/,
+    /authtoken|authentication failed|usage limit|unauthorized/i,
+    /\berror\b|\bfatal\b|\bfailed\b/i,
+  ];
+  const cap = (line: string): string =>
+    line.length > 200 ? `${line.slice(0, 200)}…` : line;
+  for (const pattern of patterns) {
+    const matches = lines.filter((line) => pattern.test(line));
+    const last = matches.at(-1);
+    if (last !== undefined) {
+      return cap(last);
+    }
+  }
+  const lastLine = lines.at(-1);
+  return lastLine === undefined ? null : cap(lastLine);
+}
+
 export {
   ADOPTED_TUNNEL_RE,
   hasWebhookIntegrationsConfigured,

package/src/lib/tunnels/cadet.ts

@@ -1,5 +1,9 @@
 import { STALE_CLI_UPDATE_HINT } from "../stale-cli-hint.js";
-import type { ProviderMeta, ProviderTunnelOptions } from "../tunnel.js";
+import type {
+  TunnelProvider,
+  ProviderMeta,
+  ProviderTunnelOptions,
+} from "../tunnel.js";
 
 /**
  * The managed `cadet` tunnel. It is listed in the shared registry so the
@@ -27,3 +31,10 @@ export async function runCadetTunnel(
 ): Promise<never> {
   throw cadetTunnelComingSoonError("cadet");
 }
+
+export const CADET_PROVIDER: TunnelProvider = {
+  run: runCadetTunnel,
+  async stop() {
+    throw cadetTunnelComingSoonError("cadet");
+  },
+};

package/src/lib/tunnels/cloudflare.ts

@@ -1,4 +1,11 @@
-import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+import { clearRootProcess, stampRootProcess } from "../assistant-config.js";
+import { readProcessCommandLine } from "../process.js";
+import { stopOwnedTunnelAgent } from "./process-lifecycle.js";
+import type {
+  TunnelProvider,
+  ProviderMeta,
+  ProviderTunnelResult,
+} from "../tunnel.js";
 
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
 
@@ -106,6 +113,7 @@ export function waitForCloudflareTunnelUrl(
     });
 
     child.on("exit", (code) => {
+      if (child.pid) clearRootProcess("tunnel", child.pid);
       if (resolved) return;
       clearTimeout(timer);
       reject(
@@ -177,6 +185,7 @@ export async function runCloudflareTunnel(
 
   const cleanup = (): void => {
     if (!child.killed) child.kill("SIGTERM");
+    if (child.pid) clearRootProcess("tunnel", child.pid);
     if (publicUrl) {
       console.log("\nClearing ingress URL from config...");
       clearIngressUrl(workspaceDir, opts.assistantId);
@@ -198,6 +207,7 @@ export async function runCloudflareTunnel(
   });
 
   child.on("exit", (code) => {
+    if (child.pid) clearRootProcess("tunnel", child.pid);
     // Always clear the saved ingress URL when the tunnel process ends so
     // webhook integrations don't keep hitting a dead endpoint.
     if (publicUrl !== undefined) {
@@ -233,6 +243,13 @@ export async function runCloudflareTunnel(
   console.log("");
 
   saveIngressUrl(workspaceDir, publicUrl, opts.assistantId, "cloudflare");
+  if (child.pid)
+    stampRootProcess("tunnel", {
+      pid: child.pid,
+      provider: "cloudflare",
+      assistantId: opts.assistantId,
+      startedAt: new Date().toISOString(),
+    });
   console.log("Ingress URL saved to config.");
   console.log("");
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
@@ -251,3 +268,21 @@ export const CLOUDFLARE_TUNNEL_META: ProviderMeta = {
   notes: ["No Cloudflare account required for quick tunnels."],
   supportsReservedDomain: false,
 };
+
+export const CLOUDFLARE_PROVIDER: TunnelProvider = {
+  run: runCloudflareTunnel,
+  stop: (opts) =>
+    stopOwnedTunnelAgent(
+      opts,
+      (pid) => {
+        try {
+          return /(?:^|[\\/\s])cloudflared(?:\.exe)?(?:\s|$)/i.test(
+            readProcessCommandLine(pid),
+          );
+        } catch {
+          return false;
+        }
+      },
+      "cloudflared",
+    ),
+};

package/src/lib/tunnels/ngrok.ts

@@ -25,7 +25,12 @@ import { getCurrentEnvironment } from "../environments/resolve.js";
 import { loopbackSafeFetch } from "../loopback-fetch.js";
 import { readProcessCommandLine } from "../process.js";
 import { z } from "zod";
-import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+import { stopOwnedTunnelAgent } from "./process-lifecycle.js";
+import type {
+  TunnelProvider,
+  ProviderMeta,
+  ProviderTunnelResult,
+} from "../tunnel.js";
 import { notifyGatewayOfPublicUrl } from "./gateway-notify.js";
 
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
@@ -631,8 +636,12 @@ export async function runNgrokTunnel(
     console.log("Ingress URL saved to config.");
     console.log("");
     console.log(
-      "Tunnel is already running. Press Ctrl+C to detach (tunnel stays active).",
+      `An ngrok agent from an earlier run is still up serving 127.0.0.1:${port} (${existingUrl}) — this run adopts it instead of starting a new agent.`,
     );
+    console.log(
+      "Adopted agents do not appear in `cadet ps` because this run does not own the process.",
+    );
+    console.log("Press Ctrl+C to detach (tunnel stays active).");
 
     // Block until SIGINT/SIGTERM
     const waitForExit = new Promise<void>((resolve) => {
@@ -783,3 +792,8 @@ export async function runNgrokTunnel(
   // Unreachable: the loop only exits via return, process.exit, or a throw.
   throw new Error("ngrok tunnel did not start.");
 }
+
+export const NGROK_PROVIDER: TunnelProvider = {
+  run: runNgrokTunnel,
+  stop: (opts) => stopOwnedTunnelAgent(opts, isNgrokProcess, "ngrok"),
+};