@mycadet/cli 0.12.7 → 0.12.9-dev.202610131452.9acab64

package/src/__tests__/tunnel.test.ts

@@ -10,8 +10,7 @@ import {
   test,
 } from "bun:test";
 import * as childProcess from "node:child_process";
-import type { ChildProcess } from "node:child_process";
-import { EventEmitter } from "node:events";
+import type { ChildProcess, SpawnOptions } from "node:child_process";
 import {
   appendFileSync,
   mkdirSync,
@@ -24,56 +23,81 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { TUNNEL_PROVIDERS } from "@mycadet/service-contracts/ingress";
+import { z } from "zod";
 
-import * as cloudflareTunnel from "../lib/cloudflare-tunnel.js";
-import * as ngrok from "../lib/ngrok.js";
+import * as cloudflareTunnel from "../lib/tunnels/cloudflare.js";
+import * as gatewayNotify from "../lib/tunnels/gateway-notify.js";
+import * as ngrok from "../lib/tunnels/ngrok.js";
 import * as nginxIngress from "../lib/nginx-ingress.js";
-import * as tailscaleTunnel from "../lib/tailscale-tunnel.js";
+import * as tailscaleTunnel from "../lib/tunnels/tailscale.js";
 import { getLogDir } from "../lib/xdg-log.js";
 import type { AssistantEntry } from "../lib/assistant-config.js";
+import { withPreconnect } from "./helpers/http.js";
 
 const realCloudflareTunnel = { ...cloudflareTunnel };
+const realGatewayNotify = { ...gatewayNotify };
 const realNgrok = { ...ngrok };
 const realNginxIngress = { ...nginxIngress };
 const realTailscaleTunnel = { ...tailscaleTunnel };
 const realChildProcess = { ...childProcess };
 
+/** What a mocked provider run hands back: a URL and an already-settled exit. */
+const fakeTunnelResult = (publicUrl: string) => ({
+  publicUrl,
+  waitForExit: Promise.resolve(),
+});
+
 const runCloudflareTunnelMock = mock<
   typeof cloudflareTunnel.runCloudflareTunnel
->(async () => {});
-mock.module("../lib/cloudflare-tunnel.js", () => ({
+>(async () => fakeTunnelResult("https://test.example.cloudflare.dev"));
+mock.module("../lib/tunnels/cloudflare.js", () => ({
   ...realCloudflareTunnel,
   runCloudflareTunnel: runCloudflareTunnelMock,
 }));
 
-const runNgrokTunnelMock = mock<typeof ngrok.runNgrokTunnel>(async () => {});
-mock.module("../lib/ngrok", () => ({
+const runNgrokTunnelMock = mock<typeof ngrok.runNgrokTunnel>(async () =>
+  fakeTunnelResult("https://test.example.ngrok.dev"),
+);
+mock.module("../lib/tunnels/ngrok", () => ({
   ...realNgrok,
   runNgrokTunnel: runNgrokTunnelMock,
 }));
 
 const runTailscaleTunnelMock = mock<typeof tailscaleTunnel.runTailscaleTunnel>(
-  async () => {},
+  async () => fakeTunnelResult("https://test-machine.tailnet.ts.net"),
 );
-mock.module("../lib/tailscale-tunnel.js", () => ({
+mock.module("../lib/tunnels/tailscale.js", () => ({
   ...realTailscaleTunnel,
   runTailscaleTunnel: runTailscaleTunnelMock,
 }));
 
+const notifyGatewayOfPublicUrlMock = mock<
+  typeof gatewayNotify.notifyGatewayOfPublicUrl
+>(async () => {});
+mock.module("../lib/tunnels/gateway-notify.js", () => ({
+  ...realGatewayNotify,
+  notifyGatewayOfPublicUrl: notifyGatewayOfPublicUrlMock,
+}));
+
 const EDGE_PORT = 18080;
 
 const ensureTunnelEdgeMock = mock<typeof nginxIngress.ensureTunnelEdge>(
   async () => ({ port: EDGE_PORT, started: true, includesWebApp: true }),
 );
+const getNginxVersionMock = mock<typeof nginxIngress.getNginxVersion>(
+  () => "nginx version (test)",
+);
 mock.module("../lib/nginx-ingress.js", () => ({
   ...realNginxIngress,
   ensureTunnelEdge: ensureTunnelEdgeMock,
+  getNginxVersion: getNginxVersionMock,
 }));
 
 const { tunnel } = await import("../commands/tunnel.js");
 
 const originalArgv = [...process.argv];
 const originalFetch = globalThis.fetch;
+const originalConfigHome = process.env.XDG_CONFIG_HOME;
 const originalLockfileDir = process.env.CADET_LOCKFILE_DIR;
 const originalWorkspaceDir = process.env.CADET_WORKSPACE_DIR;
 const tempDirs: string[] = [];
@@ -126,10 +150,7 @@ function writeEntryWorkspaceConfig(
   entry: AssistantEntry,
   config: Record<string, unknown>,
 ): string {
-  const workspaceDir = join(
-    entry.resources!.instanceDir,
-    "workspace",
-  );
+  const workspaceDir = join(entry.resources!.instanceDir, "workspace");
   mkdirSync(workspaceDir, { recursive: true });
   writeFileSync(
     join(workspaceDir, "config.json"),
@@ -158,7 +179,7 @@ function writeLockfile(
   process.env.CADET_LOCKFILE_DIR = lockfileDir;
   mkdirSync(lockfileDir, { recursive: true });
   writeFileSync(
-    join(lockfileDir, ".cadet.lock.json"),
+    join(lockfileDir, "lockfile.json"),
     JSON.stringify(
       {
         activeAssistant: activeAssistant ?? entries[0].assistantId,
@@ -170,6 +191,15 @@ function writeLockfile(
   );
 }
 
+const IngressTestConfigSchema = z.object({
+  ingress: z
+    .looseObject({
+      publicBaseUrl: z.string().optional(),
+      ngrok: z.object({ domain: z.string().optional() }).optional(),
+    })
+    .optional(),
+});
+
 /** Run tunnel() expecting exit(1); returns the joined console.error output. */
 async function runTunnelExpectingExit1(): Promise<{
   exited: boolean;
@@ -181,17 +211,17 @@ async function runTunnelExpectingExit1(): Promise<{
       errors.push(a.join(" "));
     },
   );
-  const exitSpy = spyOn(process, "exit").mockImplementation(((
-    code?: number,
-  ) => {
-    throw new Error(`exit:${code}`);
-  }) as never);
+  const exitSpy = spyOn(process, "exit").mockImplementation(
+    (code?: number | string | undefined): never => {
+      throw new Error(`exit:${code}`);
+    },
+  );
 
   let exited = false;
   try {
     await tunnel();
   } catch (e) {
-    exited = (e as Error).message === "exit:1";
+    exited = e instanceof Error && e.message === "exit:1";
   } finally {
     errSpy.mockRestore();
     exitSpy.mockRestore();
@@ -215,17 +245,36 @@ async function runTunnelCapturingLogs(): Promise<string> {
 
 describe("tunnel edge targeting", () => {
   beforeEach(() => {
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "tailscale"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "tailscale",
+      "--foreground",
+    ];
     writeLockfile(makeLocalEntry());
-    globalThis.fetch = (async () => {
+    globalThis.fetch = withPreconnect(async () => {
       throw new Error("gateway unavailable");
-    }) as unknown as typeof globalThis.fetch;
+    });
+    // The ngrok config file lives under the XDG config dir; a fresh one per
+    // test keeps the saved-domain state hermetic.
+    const configHome = mkdtempSync(join(tmpdir(), "cadet-tunnel-xdg-"));
+    tempDirs.push(configHome);
+    process.env.XDG_CONFIG_HOME = configHome;
     runCloudflareTunnelMock.mockReset();
-    runCloudflareTunnelMock.mockResolvedValue(undefined);
+    runCloudflareTunnelMock.mockResolvedValue(
+      fakeTunnelResult("https://test.example.cloudflare.dev"),
+    );
     runNgrokTunnelMock.mockReset();
-    runNgrokTunnelMock.mockResolvedValue(undefined);
+    runNgrokTunnelMock.mockResolvedValue(
+      fakeTunnelResult("https://test.example.ngrok.dev"),
+    );
     runTailscaleTunnelMock.mockReset();
-    runTailscaleTunnelMock.mockResolvedValue(undefined);
+    runTailscaleTunnelMock.mockResolvedValue(
+      fakeTunnelResult("https://test-machine.tailnet.ts.net"),
+    );
+    notifyGatewayOfPublicUrlMock.mockReset();
     ensureTunnelEdgeMock.mockReset();
     ensureTunnelEdgeMock.mockResolvedValue({
       port: EDGE_PORT,
@@ -237,6 +286,12 @@ describe("tunnel edge targeting", () => {
   afterEach(() => {
     process.argv = originalArgv;
     globalThis.fetch = originalFetch;
+    rmSync(realNgrok.ngrokConfigPath(), { force: true });
+    if (originalConfigHome === undefined) {
+      delete process.env.XDG_CONFIG_HOME;
+    } else {
+      process.env.XDG_CONFIG_HOME = originalConfigHome;
+    }
     if (originalLockfileDir === undefined) {
       delete process.env.CADET_LOCKFILE_DIR;
     } else {
@@ -253,9 +308,9 @@ describe("tunnel edge targeting", () => {
   });
 
   afterAll(() => {
-    mock.module("../lib/cloudflare-tunnel.js", () => realCloudflareTunnel);
-    mock.module("../lib/ngrok", () => realNgrok);
-    mock.module("../lib/tailscale-tunnel.js", () => realTailscaleTunnel);
+    mock.module("../lib/tunnels/cloudflare.js", () => realCloudflareTunnel);
+    mock.module("../lib/tunnels/ngrok", () => realNgrok);
+    mock.module("../lib/tunnels/tailscale.js", () => realTailscaleTunnel);
     mock.module("../lib/nginx-ingress.js", () => realNginxIngress);
   });
 
@@ -263,14 +318,18 @@ describe("tunnel edge targeting", () => {
     const entry = makeLocalEntry();
     entry.runtimeUrl = "https://stale-tunnel.ngrok-free.dev";
     writeLockfile(entry);
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const logs = await runTunnelCapturingLogs();
 
-    const workspaceDir = join(
-      entry.resources!.instanceDir,
-      "workspace",
-    );
+    const workspaceDir = join(entry.resources!.instanceDir, "workspace");
     expect(ensureTunnelEdgeMock).toHaveBeenCalledWith({
       assistantId: "assistant-1",
       workspaceDir,
@@ -283,21 +342,45 @@ describe("tunnel edge targeting", () => {
     });
     expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
     expect(logs).toContain(`Started the nginx edge on 127.0.0.1:${EDGE_PORT}`);
-    expect(logs).toContain("serves remote web + webhooks");
+  });
+
+  test("the tunnel level notifies the gateway of the provider's public URL", async () => {
+    writeLockfile(makeLocalEntry());
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
+
+    await runTunnelCapturingLogs();
+
+    // The provider hands its URL back; the notification is the tunnel
+    // level's job, so it holds no matter which provider ran.
+    expect(notifyGatewayOfPublicUrlMock).toHaveBeenCalledWith(
+      "https://test.example.ngrok.dev",
+      "assistant-1",
+    );
   });
 
   test("an active cloud assistant falls back to the sole local entry with a note", async () => {
     const cloud = makeCloudEntry();
     const local = makeLocalEntry();
     writeLockfile([cloud, local], cloud.assistantId);
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const logs = await runTunnelCapturingLogs();
 
-    const workspaceDir = join(
-      local.resources!.instanceDir,
-      "workspace",
-    );
+    const workspaceDir = join(local.resources!.instanceDir, "workspace");
     expect(logs).toContain(
       "Assistant 'cloud-1' runs on Cadet Cloud and needs no tunnel. " +
         "Tunneling the local assistant 'assistant-1' instead.",
@@ -325,6 +408,7 @@ describe("tunnel edge targeting", () => {
       "docker-1",
       "--provider",
       "ngrok",
+      "--foreground",
     ];
 
     await runTunnelCapturingLogs();
@@ -345,7 +429,14 @@ describe("tunnel edge targeting", () => {
     const workspaceDir = useTempDefaultWorkspaceDir();
     const docker = makeDockerEntry();
     writeLockfile(docker, docker.assistantId);
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     await runTunnelCapturingLogs();
 
@@ -365,7 +456,14 @@ describe("tunnel edge targeting", () => {
     const workspaceDir = useTempDefaultWorkspaceDir();
     const cloud = makeCloudEntry();
     writeLockfile([cloud, makeDockerEntry()], cloud.assistantId);
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const logs = await runTunnelCapturingLogs();
 
@@ -382,7 +480,14 @@ describe("tunnel edge targeting", () => {
 
   test("an active cloud assistant with no local entries exits with an error", async () => {
     writeLockfile(makeCloudEntry());
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
 
@@ -401,7 +506,14 @@ describe("tunnel edge targeting", () => {
       [cloud, makeLocalEntry("assistant-a"), makeLocalEntry("assistant-b")],
       cloud.assistantId,
     );
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
 
@@ -426,6 +538,7 @@ describe("tunnel edge targeting", () => {
       "cloud-1",
       "--provider",
       "ngrok",
+      "--foreground",
     ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
@@ -445,14 +558,19 @@ describe("tunnel edge targeting", () => {
     const local = makeLocalEntry();
     local.name = "Ada";
     writeLockfile([makeCloudEntry(), local], "cloud-1");
-    process.argv = ["bun", "cadet", "tunnel", "Ada", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "Ada",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     await runTunnelCapturingLogs();
 
-    const workspaceDir = join(
-      local.resources!.instanceDir,
-      "workspace",
-    );
+    const workspaceDir = join(local.resources!.instanceDir, "workspace");
     expect(runNgrokTunnelMock).toHaveBeenCalledWith({
       port: EDGE_PORT,
       assistantId: "assistant-1",
@@ -472,14 +590,12 @@ describe("tunnel edge targeting", () => {
       "Lovelace",
       "--provider",
       "ngrok",
+      "--foreground",
     ];
 
     await runTunnelCapturingLogs();
 
-    const workspaceDir = join(
-      local.resources!.instanceDir,
-      "workspace",
-    );
+    const workspaceDir = join(local.resources!.instanceDir, "workspace");
     expect(runNgrokTunnelMock).toHaveBeenCalledWith({
       port: EDGE_PORT,
       assistantId: "assistant-1",
@@ -498,6 +614,7 @@ describe("tunnel edge targeting", () => {
       "apple-1",
       "--provider",
       "ngrok",
+      "--foreground",
     ];
 
     await runTunnelCapturingLogs();
@@ -518,7 +635,14 @@ describe("tunnel edge targeting", () => {
     const workspaceDir = useTempDefaultWorkspaceDir();
     const cloud = makeCloudEntry();
     writeLockfile([cloud, makeAppleContainerEntry()], cloud.assistantId);
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const logs = await runTunnelCapturingLogs();
 
@@ -550,6 +674,7 @@ describe("tunnel edge targeting", () => {
       "assistant-b",
       "--provider",
       "ngrok",
+      "--foreground",
     ];
 
     await runTunnelCapturingLogs();
@@ -564,7 +689,15 @@ describe("tunnel edge targeting", () => {
     cloud.name = "Cloudy";
     const local = makeLocalEntry();
     writeLockfile([cloud, local], local.assistantId);
-    process.argv = ["bun", "cadet", "tunnel", "Cloudy", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "Cloudy",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
 
@@ -585,7 +718,15 @@ describe("tunnel edge targeting", () => {
     const second = makeLocalEntry("assistant-b");
     second.name = "Ada";
     writeLockfile([first, second], "assistant-a");
-    process.argv = ["bun", "cadet", "tunnel", "Ada", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "Ada",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
 
@@ -598,7 +739,15 @@ describe("tunnel edge targeting", () => {
   });
 
   test("an unknown positional name errors", async () => {
-    process.argv = ["bun", "cadet", "tunnel", "nope", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "nope",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
 
@@ -611,7 +760,14 @@ describe("tunnel edge targeting", () => {
   test("targets the edge port for cloudflare", async () => {
     const entry = makeLocalEntry();
     writeLockfile(entry);
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "cloudflare"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "cloudflare",
+      "--foreground",
+    ];
 
     await runTunnelCapturingLogs();
 
@@ -626,7 +782,14 @@ describe("tunnel edge targeting", () => {
   test("targets the edge port for tailscale and notes a reused webhooks-only edge", async () => {
     const entry = makeLocalEntry();
     writeLockfile(entry);
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "tailscale"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "tailscale",
+      "--foreground",
+    ];
     ensureTunnelEdgeMock.mockResolvedValue({
       port: EDGE_PORT,
       started: false,
@@ -641,49 +804,42 @@ describe("tunnel edge targeting", () => {
       workspaceDir: join(entry.resources!.instanceDir, "workspace"),
     });
     expect(logs).toContain(`Reusing the nginx edge on 127.0.0.1:${EDGE_PORT}`);
-    expect(logs).toContain("serves webhooks only");
   });
 
-  test("a bare invocation exits listing the providers to choose from", async () => {
-    writeLockfile(makeLocalEntry());
-    process.argv = ["bun", "cadet", "tunnel"];
+  test("a bare invocation tunnels the default provider", async () => {
+    const entry = makeLocalEntry();
+    writeLockfile(entry);
+    process.argv = ["bun", "cadet", "tunnel", "--foreground"];
 
-    const { exited, errors } = await runTunnelExpectingExit1();
+    const logs = await runTunnelCapturingLogs();
 
-    expect(exited).toBe(true);
-    expect(errors).toContain("--provider is required");
-    expect(errors).toContain("cadet tunnel --provider ngrok");
-    expect(errors).toContain("cadet tunnel --provider cloudflare");
-    expect(errors).toContain("cadet tunnel --provider tailscale");
-    // Nothing is started and nothing is recorded until the user has chosen.
-    expect(ensureTunnelEdgeMock).not.toHaveBeenCalled();
+    expect(logs).toContain("Using the default provider: ngrok");
+    expect(runNgrokTunnelMock).toHaveBeenCalledWith({
+      port: EDGE_PORT,
+      assistantId: "assistant-1",
+      workspaceDir: join(entry.resources!.instanceDir, "workspace"),
+    });
+    expect(ensureTunnelEdgeMock).toHaveBeenCalled();
     expect(runTailscaleTunnelMock).not.toHaveBeenCalled();
-    expect(runNgrokTunnelMock).not.toHaveBeenCalled();
     expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
   });
 
-  test("a named assistant without --provider exits before resolving it", async () => {
-    writeLockfile(makeLocalEntry());
-    process.argv = ["bun", "cadet", "tunnel", "Ada"];
-
-    const { exited, errors } = await runTunnelExpectingExit1();
-
-    expect(exited).toBe(true);
-    expect(errors).toContain("--provider is required");
-    // The suggestions keep the assistant that was asked for, so pasting one
-    // cannot tunnel the active assistant instead.
-    expect(errors).toContain("cadet tunnel Ada --provider ngrok");
-    expect(errors).toContain("cadet tunnel Ada --provider tailscale");
-    expect(ensureTunnelEdgeMock).not.toHaveBeenCalled();
-  });
-
-  test("a shell-sensitive assistant name is quoted in the suggestions", async () => {
-    writeLockfile(makeLocalEntry());
-    process.argv = ["bun", "cadet", "tunnel", "Bob&Alice"];
+  test("a named assistant without --provider tunnels it with the default provider", async () => {
+    const entry = makeLocalEntry();
+    entry.name = "Ada";
+    writeLockfile(entry);
+    process.argv = ["bun", "cadet", "tunnel", "Ada", "--foreground"];
 
-    const { errors } = await runTunnelExpectingExit1();
+    const logs = await runTunnelCapturingLogs();
 
-    expect(errors).toContain("cadet tunnel 'Bob&Alice' --provider ngrok");
+    expect(logs).toContain("Using the default provider: ngrok");
+    // The assistant that was asked for is the one tunneled.
+    expect(runNgrokTunnelMock).toHaveBeenCalledWith({
+      port: EDGE_PORT,
+      assistantId: entry.assistantId,
+      workspaceDir: join(entry.resources!.instanceDir, "workspace"),
+    });
+    expect(ensureTunnelEdgeMock).toHaveBeenCalled();
   });
 
   test("--provider tailscale keeps the webhook callback base and says so", async () => {
@@ -692,7 +848,14 @@ describe("tunnel edge targeting", () => {
     const workspaceDir = writeEntryWorkspaceConfig(entry, {
       telegram: { botUsername: "example_bot" },
     });
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "tailscale"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "tailscale",
+      "--foreground",
+    ];
 
     const warnings: string[] = [];
     const warnSpy = spyOn(console, "warn").mockImplementation(
@@ -723,7 +886,14 @@ describe("tunnel edge targeting", () => {
     const entry = makeLocalEntry();
     writeLockfile(entry);
     const workspaceDir = writeEntryWorkspaceConfig(entry, {});
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "tailscale"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "tailscale",
+      "--foreground",
+    ];
 
     await runTunnelCapturingLogs();
 
@@ -740,7 +910,14 @@ describe("tunnel edge targeting", () => {
     const workspaceDir = writeEntryWorkspaceConfig(entry, {
       telegram: { botUsername: "example_bot" },
     });
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
 
     await runTunnelCapturingLogs();
 
@@ -752,11 +929,18 @@ describe("tunnel edge targeting", () => {
   });
 
   test("missing nginx aborts before any provider spawn", async () => {
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "ngrok",
+      "--foreground",
+    ];
     ensureTunnelEdgeMock.mockRejectedValue(
       new Error(
         "nginx is not installed, so the tunnel edge cannot start. " +
-          "Install it (macOS: `brew install nginx`, Linux: `sudo apt install nginx`) " +
+          "See https://nginx.org/en/docs/install.html for how to install, " +
           "or point NGINX_BIN at an existing binary.",
       ),
     );
@@ -764,14 +948,23 @@ describe("tunnel edge targeting", () => {
     const { exited, errors } = await runTunnelExpectingExit1();
 
     expect(exited).toBe(true);
-    expect(errors).toContain("brew install nginx");
+    expect(errors).toContain(
+      "See https://nginx.org/en/docs/install.html for how to install",
+    );
     expect(runNgrokTunnelMock).not.toHaveBeenCalled();
     expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
     expect(runTailscaleTunnelMock).not.toHaveBeenCalled();
   });
 
   test("rejects an unknown --provider with a stale-CLI hint", async () => {
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "bogus"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "bogus",
+      "--foreground",
+    ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
 
@@ -788,7 +981,14 @@ describe("tunnel edge targeting", () => {
     try {
       for (const provider of TUNNEL_PROVIDERS) {
         writeLockfile(makeLocalEntry());
-        process.argv = ["bun", "cadet", "tunnel", "--provider", provider];
+        process.argv = [
+          "bun",
+          "cadet",
+          "tunnel",
+          "--provider",
+          provider,
+          "--foreground",
+        ];
 
         const { exited, errors } = await runTunnelExpectingExit1();
 
@@ -811,6 +1011,7 @@ describe("tunnel edge targeting", () => {
       "ngrok",
       "--domain",
       "foo.ngrok.app",
+      "--foreground",
     ];
 
     await runTunnelCapturingLogs();
@@ -832,13 +1033,14 @@ describe("tunnel edge targeting", () => {
       "cloudflare",
       "--domain",
       "foo.ngrok.app",
+      "--foreground",
     ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
 
     expect(exited).toBe(true);
     expect(errors).toContain(
-      "--domain is only supported with --provider ngrok",
+      "--domain is not supported with --provider cloudflare",
     );
     expect(runNgrokTunnelMock).not.toHaveBeenCalled();
     expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
@@ -847,15 +1049,9 @@ describe("tunnel edge targeting", () => {
   test("--clear-domain drops the saved domain and runs domainless", async () => {
     const entry = makeLocalEntry();
     writeLockfile(entry);
-    const workspaceDir = join(
-      entry.resources!.instanceDir,
-      "workspace",
-    );
+    const workspaceDir = join(entry.resources!.instanceDir, "workspace");
     mkdirSync(workspaceDir, { recursive: true });
-    writeFileSync(
-      join(workspaceDir, "config.json"),
-      JSON.stringify({ ingress: { ngrok: { domain: "dead.ngrok.app" } } }),
-    );
+    realNgrok.saveNgrokDomain("dead.ngrok.app");
     process.argv = [
       "bun",
       "cadet",
@@ -863,15 +1059,14 @@ describe("tunnel edge targeting", () => {
       "--provider",
       "ngrok",
       "--clear-domain",
+      "--foreground",
     ];
 
     const logs = await runTunnelCapturingLogs();
 
-    expect(logs).toContain("Cleared the saved ngrok domain");
-    const config = JSON.parse(
-      readFileSync(join(workspaceDir, "config.json"), "utf-8"),
-    ) as { ingress?: { ngrok?: { domain?: string } } };
-    expect(config.ingress?.ngrok).toBeUndefined();
+    expect(logs).toContain("Cleared the saved reserved domain");
+    // The saved domain lives in the XDG ngrok config, not the workspace config.
+    expect(realNgrok.loadNgrokDomain()).toBeNull();
     // The run proceeds domainless: no `domain` key reaches runNgrokTunnel.
     expect(runNgrokTunnelMock).toHaveBeenCalledWith({
       port: EDGE_PORT,
@@ -890,6 +1085,7 @@ describe("tunnel edge targeting", () => {
       "--domain",
       "foo.ngrok.app",
       "--clear-domain",
+      "--foreground",
     ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
@@ -907,13 +1103,14 @@ describe("tunnel edge targeting", () => {
       "--provider",
       "cloudflare",
       "--clear-domain",
+      "--foreground",
     ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
 
     expect(exited).toBe(true);
     expect(errors).toContain(
-      "--clear-domain is only supported with --provider ngrok",
+      "--clear-domain is not supported with --provider cloudflare",
     );
     expect(runNgrokTunnelMock).not.toHaveBeenCalled();
     expect(runCloudflareTunnelMock).not.toHaveBeenCalled();
@@ -927,6 +1124,7 @@ describe("tunnel edge targeting", () => {
       "--provider",
       "ngrok",
       "--domain",
+      "--foreground",
     ];
 
     const { exited, errors } = await runTunnelExpectingExit1();
@@ -939,13 +1137,20 @@ describe("tunnel edge targeting", () => {
   test("a not-yet-implemented provider error carries the stale-CLI hint", async () => {
     // `cadet` stays valid-but-unimplemented, so it hits this path rather
     // than the unknown-provider one.
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "cadet"];
+    process.argv = [
+      "bun",
+      "cadet",
+      "tunnel",
+      "--provider",
+      "cadet",
+      "--foreground",
+    ];
 
     let err: Error | undefined;
     try {
       await tunnel();
     } catch (e) {
-      err = e as Error;
+      err = e instanceof Error ? e : undefined;
     }
 
     expect(err?.message).toContain("is not yet implemented");
@@ -959,20 +1164,26 @@ describe("tunnel edge targeting", () => {
 
 describe("ngrok --domain spawn args", () => {
   const originalContainerized = process.env.IS_CONTAINERIZED;
-  let lastChild: EventEmitter | null = null;
-
-  const spawnMock = mock((..._args: unknown[]) => {
-    const emitter = new EventEmitter();
-    lastChild = Object.assign(emitter, {
-      stdout: null,
-      stderr: null,
-      killed: false,
-      kill: () => true,
-      unref: () => {},
-      pid: 4242,
-    });
-    return lastChild as unknown as ChildProcess;
-  });
+  let lastChild: ChildProcess | null = null;
+
+  const spawnMock = mock(
+    (
+      _command: string,
+      _args: readonly string[],
+      _options?: SpawnOptions,
+    ): ChildProcess => {
+      const child = new realChildProcess.ChildProcess();
+      // kill() stays stubbed: the fake pid must never be signaled for real.
+      // stdout/stderr: the real class resolves them through a getter over the
+      // internal spawn handle, so null-shadow them via defineProperty — an
+      // Object.assign [[Set]] through the getter-only accessor throws.
+      Object.defineProperty(child, "stdout", { value: null });
+      Object.defineProperty(child, "stderr", { value: null });
+      const fake = Object.assign(child, { pid: 4242, kill: () => true });
+      lastChild = fake;
+      return fake;
+    },
+  );
   const execFileSyncMock = mock(() => "ngrok version 3.9.0");
 
   beforeAll(() => {
@@ -991,11 +1202,22 @@ describe("ngrok --domain spawn args", () => {
     spawnMock.mockClear();
     lastChild = null;
     delete process.env.IS_CONTAINERIZED;
+    // The ngrok config file lives under the XDG config dir; a fresh one per
+    // test keeps the saved-domain state hermetic.
+    const configHome = mkdtempSync(join(tmpdir(), "cadet-ngrok-xdg-"));
+    tempDirs.push(configHome);
+    process.env.XDG_CONFIG_HOME = configHome;
     mockNgrokApiFetch([{ tunnels: [] }]);
   });
 
   afterEach(() => {
     globalThis.fetch = originalFetch;
+    rmSync(realNgrok.ngrokConfigPath(), { force: true });
+    if (originalConfigHome === undefined) {
+      delete process.env.XDG_CONFIG_HOME;
+    } else {
+      process.env.XDG_CONFIG_HOME = originalConfigHome;
+    }
     if (originalContainerized === undefined) {
       delete process.env.IS_CONTAINERIZED;
     } else {
@@ -1021,22 +1243,20 @@ describe("ngrok --domain spawn args", () => {
   /** ngrok local API stub replaying one response per call, last one repeated. */
   function mockNgrokApiFetch(responses: { tunnels: StubTunnel[] }[]): void {
     let call = 0;
-    globalThis.fetch = (async () => {
+    globalThis.fetch = withPreconnect(async () => {
       const body = responses[Math.min(call, responses.length - 1)];
       call++;
       return new Response(JSON.stringify(body), {
         status: 200,
         headers: { "Content-Type": "application/json" },
       });
-    }) as unknown as typeof globalThis.fetch;
+    });
   }
 
   function readIngress(ws: string): Record<string, unknown> {
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as {
-      ingress?: Record<string, unknown>;
-    };
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
     return config.ingress ?? {};
   }
 
@@ -1048,7 +1268,7 @@ describe("ngrok --domain spawn args", () => {
     const lockfileDir = mkdtempSync(join(tmpdir(), "cadet-ngrok-lockfile-"));
     tempDirs.push(lockfileDir);
     writeFileSync(
-      join(lockfileDir, ".cadet.lock.json"),
+      join(lockfileDir, "lockfile.json"),
       JSON.stringify({
         activeAssistant: assistantId,
         assistants: [
@@ -1104,33 +1324,34 @@ describe("ngrok --domain spawn args", () => {
     }
 
     expect(spawnMock).toHaveBeenCalledTimes(1);
-    const [cmd, args] = spawnMock.mock.calls[0] as unknown as [
-      string,
-      string[],
-    ];
+    const [cmd, args] = spawnMock.mock.calls[0];
     expect(cmd).toBe("ngrok");
+    // Plain `ngrok http` so the user's default config — where their
+    // authtoken lives — is what the agent loads.
     expect(args).toEqual([
       "http",
       "127.0.0.1:7831",
       "--log=stdout",
       "--domain=foo.ngrok.app",
     ]);
+    expect(realNgrok.loadNgrokDomain()).toBe("foo.ngrok.app");
 
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as { ingress: { publicBaseUrl?: string; ngrok?: { domain?: string } } };
-    expect(config.ingress.publicBaseUrl).toBe("https://foo.ngrok.app");
-    expect(config.ingress.ngrok?.domain).toBe("foo.ngrok.app");
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
+    expect(config.ingress?.publicBaseUrl).toBe("https://foo.ngrok.app");
   });
 
   function mockTunnelListFetch(publicUrl: string, addr: string): void {
-    globalThis.fetch = (async () =>
-      new Response(
-        JSON.stringify({
-          tunnels: [{ public_url: publicUrl, config: { addr } }],
-        }),
-        { status: 200, headers: { "Content-Type": "application/json" } },
-      )) as unknown as typeof globalThis.fetch;
+    globalThis.fetch = withPreconnect(
+      async () =>
+        new Response(
+          JSON.stringify({
+            tunnels: [{ public_url: publicUrl, config: { addr } }],
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+    );
   }
 
   test("runNgrokTunnel rejects an existing tunnel that mismatches the requested domain", async () => {
@@ -1143,11 +1364,11 @@ describe("ngrok --domain spawn args", () => {
         errors.push(a.join(" "));
       },
     );
-    const exitSpy = spyOn(process, "exit").mockImplementation(((
-      code?: number,
-    ) => {
-      throw new Error(`exit:${code}`);
-    }) as never);
+    const exitSpy = spyOn(process, "exit").mockImplementation(
+      (code?: number | string | undefined): never => {
+        throw new Error(`exit:${code}`);
+      },
+    );
 
     try {
       await expect(
@@ -1170,9 +1391,9 @@ describe("ngrok --domain spawn args", () => {
     expect(combined).toContain("Stop the existing ngrok agent");
     expect(spawnMock).not.toHaveBeenCalled();
 
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as { ingress?: { publicBaseUrl?: string; ngrok?: { domain?: string } } };
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
     expect(config.ingress?.publicBaseUrl).toBeUndefined();
     expect(config.ingress?.ngrok).toBeUndefined();
   });
@@ -1189,6 +1410,8 @@ describe("ngrok --domain spawn args", () => {
     // The adopt path blocks until SIGINT/SIGTERM; pump SIGINT until the
     // listener is registered and the promise settles. Earlier tests leak
     // SIGINT handlers that call process.exit, so no-op it while pumping.
+    // LOAD-BEARING cast: a no-op exit can't honestly be typed `: never` — it
+    // must return so leaked SIGINT handlers can't crash the pump below.
     const exitSpy = spyOn(process, "exit").mockImplementation(
       (() => undefined) as never,
     );
@@ -1201,18 +1424,16 @@ describe("ngrok --domain spawn args", () => {
     }
 
     expect(spawnMock).not.toHaveBeenCalled();
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as { ingress: { publicBaseUrl?: string; ngrok?: { domain?: string } } };
-    expect(config.ingress.publicBaseUrl).toBe("https://foo.ngrok.app");
-    expect(config.ingress.ngrok?.domain).toBe("foo.ngrok.app");
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
+    expect(config.ingress?.publicBaseUrl).toBe("https://foo.ngrok.app");
+    expect(realNgrok.loadNgrokDomain()).toBe("foo.ngrok.app");
   });
 
   test("maybeStartNgrokTunnel rejects a mismatched existing tunnel without adopting or spawning", async () => {
-    const ws = makeWorkspace({
-      telegram: { botUsername: "example_bot" },
-      ingress: { ngrok: { domain: "foo.ngrok.app" } },
-    });
+    const ws = makeWorkspace({ telegram: { botUsername: "example_bot" } });
+    realNgrok.saveNgrokDomain("foo.ngrok.app");
     mockTunnelListFetch("https://other.ngrok-free.app", "localhost:7830");
 
     const warnings: string[] = [];
@@ -1240,13 +1461,13 @@ describe("ngrok --domain spawn args", () => {
       "cadet tunnel --provider ngrok --domain foo.ngrok.app",
     );
 
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as { ingress: { publicBaseUrl?: string; ngrok?: { domain?: string } } };
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
     // The mismatched tunnel is not blessed in config…
-    expect(config.ingress.publicBaseUrl).toBeUndefined();
+    expect(config.ingress?.publicBaseUrl).toBeUndefined();
     // …and the reserved domain stays saved as standing intent.
-    expect(config.ingress.ngrok?.domain).toBe("foo.ngrok.app");
+    expect(realNgrok.loadNgrokDomain()).toBe("foo.ngrok.app");
   });
 
   test("an adopted automatic tunnel records the assistant it fronts", async () => {
@@ -1329,9 +1550,9 @@ describe("ngrok --domain spawn args", () => {
     expect(combined).toContain("not 18080");
     expect(combined).toContain("cadet tunnel --provider ngrok");
 
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as { ingress?: { publicBaseUrl?: string } };
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
     expect(config.ingress?.publicBaseUrl).toBeUndefined();
   });
 
@@ -1345,11 +1566,11 @@ describe("ngrok --domain spawn args", () => {
         errors.push(a.join(" "));
       },
     );
-    const exitSpy = spyOn(process, "exit").mockImplementation(((
-      code?: number,
-    ) => {
-      throw new Error(`exit:${code}`);
-    }) as never);
+    const exitSpy = spyOn(process, "exit").mockImplementation(
+      (code?: number | string | undefined): never => {
+        throw new Error(`exit:${code}`);
+      },
+    );
 
     try {
       await expect(
@@ -1369,17 +1590,15 @@ describe("ngrok --domain spawn args", () => {
     expect(combined).toContain("Stop the existing ngrok agent");
     expect(spawnMock).not.toHaveBeenCalled();
 
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as { ingress?: { publicBaseUrl?: string } };
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
     expect(config.ingress?.publicBaseUrl).toBeUndefined();
   });
 
   test("maybeStartNgrokTunnel passes the saved domain to the spawn args", async () => {
-    const ws = makeWorkspace({
-      telegram: { botUsername: "example_bot" },
-      ingress: { ngrok: { domain: "foo.ngrok.app" } },
-    });
+    const ws = makeWorkspace({ telegram: { botUsername: "example_bot" } });
+    realNgrok.saveNgrokDomain("foo.ngrok.app");
     mockNgrokApiFetch([
       { tunnels: [] },
       {
@@ -1397,11 +1616,10 @@ describe("ngrok --domain spawn args", () => {
 
     expect(child).not.toBeNull();
     expect(spawnMock).toHaveBeenCalledTimes(1);
-    const [cmd, args] = spawnMock.mock.calls[0] as unknown as [
-      string,
-      string[],
-    ];
+    const [cmd, args] = spawnMock.mock.calls[0];
     expect(cmd).toBe("ngrok");
+    // Plain `ngrok http` so the user's default config — where their
+    // authtoken lives — is what the agent loads.
     expect(args).toEqual([
       "http",
       "127.0.0.1:7830",
@@ -1409,16 +1627,15 @@ describe("ngrok --domain spawn args", () => {
       "--domain=foo.ngrok.app",
     ]);
 
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as { ingress: { publicBaseUrl?: string } };
-    expect(config.ingress.publicBaseUrl).toBe("https://foo.ngrok.app");
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
+    expect(config.ingress?.publicBaseUrl).toBe("https://foo.ngrok.app");
   });
 
   test("runNgrokTunnel without --domain reuses the saved domain and does not delete it", async () => {
-    const ws = makeWorkspace({
-      ingress: { ngrok: { domain: "foo.ngrok.app" } },
-    });
+    const ws = makeWorkspace({});
+    realNgrok.saveNgrokDomain("foo.ngrok.app");
     mockNgrokApiFetch([
       { tunnels: [] },
       {
@@ -1440,7 +1657,7 @@ describe("ngrok --domain spawn args", () => {
     }
 
     expect(spawnMock).toHaveBeenCalledTimes(1);
-    const [, args] = spawnMock.mock.calls[0] as unknown as [string, string[]];
+    const [, args] = spawnMock.mock.calls[0];
     expect(args).toEqual([
       "http",
       "127.0.0.1:7831",
@@ -1448,38 +1665,52 @@ describe("ngrok --domain spawn args", () => {
       "--domain=foo.ngrok.app",
     ]);
 
-    const config = JSON.parse(
-      readFileSync(join(ws, "config.json"), "utf-8"),
-    ) as { ingress: { publicBaseUrl?: string; ngrok?: { domain?: string } } };
-    expect(config.ingress.publicBaseUrl).toBe("https://foo.ngrok.app");
-    expect(config.ingress.ngrok?.domain).toBe("foo.ngrok.app");
+    const config = IngressTestConfigSchema.parse(
+      JSON.parse(readFileSync(join(ws, "config.json"), "utf-8")),
+    );
+    expect(config.ingress?.publicBaseUrl).toBe("https://foo.ngrok.app");
+    expect(realNgrok.loadNgrokDomain()).toBe("foo.ngrok.app");
   });
 });
 
-describe("tunnel --detach", () => {
+describe("tunnel background mode", () => {
   const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
 
   function makeFakeChild(pid: number): ChildProcess {
-    const emitter = new EventEmitter();
-    return Object.assign(emitter, {
-      stdout: null,
-      stderr: null,
-      killed: false,
-      kill: () => true,
-      unref: () => {},
-      pid,
-    }) as unknown as ChildProcess;
+    const child = new realChildProcess.ChildProcess();
+    // kill() stays stubbed: the fake pid must never be signaled for real.
+    // stdout/stderr: the real class resolves them through a getter over the
+    // internal spawn handle, so null-shadow them via defineProperty — an
+    // Object.assign [[Set]] through the getter-only accessor throws.
+    Object.defineProperty(child, "stdout", { value: null });
+    Object.defineProperty(child, "stderr", { value: null });
+    return Object.assign(child, { pid, kill: () => true });
   }
 
-  const spawnMock = mock((..._args: unknown[]) => makeFakeChild(9999));
+  const spawnMock = mock(
+    (
+      _command: string,
+      _args: readonly string[],
+      _options?: SpawnOptions,
+    ): ChildProcess => makeFakeChild(9999),
+  );
 
-  // spawnDetachedTunnel() scopes the log filename to its own (parent) pid,
-  // which in-process is this test runner's pid.
   function detachedLogPath(): string {
-    return join(getLogDir(), `tunnel-${process.pid}.log`);
+    return join(getLogDir(), "tunnel.log");
   }
 
   beforeAll(() => {
+    // The edge-targeting describe's afterAll restores the REAL provider
+    // modules; re-establish the fakes the foreground test here needs.
+    mock.module("../lib/tunnels/ngrok", () => ({
+      ...realNgrok,
+      runNgrokTunnel: runNgrokTunnelMock,
+    }));
+    mock.module("../lib/nginx-ingress.js", () => ({
+      ...realNginxIngress,
+      ensureTunnelEdge: ensureTunnelEdgeMock,
+      getNginxVersion: getNginxVersionMock,
+    }));
     mock.module("node:child_process", () => ({
       ...realChildProcess,
       spawn: spawnMock,
@@ -1488,10 +1719,22 @@ describe("tunnel --detach", () => {
 
   afterAll(() => {
     mock.module("node:child_process", () => realChildProcess);
+    mock.module("../lib/tunnels/ngrok", () => realNgrok);
+    mock.module("../lib/nginx-ingress.js", () => realNginxIngress);
   });
 
   beforeEach(() => {
     spawnMock.mockClear();
+    runNgrokTunnelMock.mockReset();
+    runNgrokTunnelMock.mockResolvedValue(
+      fakeTunnelResult("https://test.example.ngrok.dev"),
+    );
+    ensureTunnelEdgeMock.mockReset();
+    ensureTunnelEdgeMock.mockResolvedValue({
+      port: EDGE_PORT,
+      started: true,
+      includesWebApp: true,
+    });
     const configHome = mkdtempSync(join(tmpdir(), "cadet-tunnel-xdg-"));
     tempDirs.push(configHome);
     process.env.XDG_CONFIG_HOME = configHome;
@@ -1509,15 +1752,8 @@ describe("tunnel --detach", () => {
     }
   });
 
-  test("--detach re-invokes without the flag as a detached child and reports readiness", async () => {
-    process.argv = [
-      "bun",
-      "cadet",
-      "tunnel",
-      "--provider",
-      "ngrok",
-      "--detach",
-    ];
+  test("runs detached by default: re-invokes itself as a detached child and reports readiness", async () => {
+    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
 
     // Simulate the detached child writing its readiness line to the log file
     // the moment it is spawned.
@@ -1532,17 +1768,15 @@ describe("tunnel --detach", () => {
     const logs = await runTunnelCapturingLogs();
 
     expect(spawnMock).toHaveBeenCalledTimes(1);
-    const [, args, opts] = spawnMock.mock.calls[0] as unknown as [
-      string,
-      string[],
-      Record<string, unknown>,
-    ];
+    const [, args, opts] = spawnMock.mock.calls[0];
     expect(args).toContain("tunnel");
     expect(args).toContain("--provider");
     expect(args).toContain("ngrok");
-    expect(args).not.toContain("--detach");
-    expect(args).not.toContain("-d");
-    expect(opts.detached).toBe(true);
+    // The child runs the foreground path (it IS the background daemon); the
+    // parent must not hand the default through or the child would daemonize
+    // again.
+    expect(args).toContain("--foreground");
+    expect(opts?.detached).toBe(true);
 
     expect(logs).toContain("Tunnel established: https://foo.ngrok.app");
     expect(logs).toContain("Running in background (pid 9999)");
@@ -1554,37 +1788,30 @@ describe("tunnel --detach", () => {
     expect(ensureTunnelEdgeMock).not.toHaveBeenCalled();
   });
 
-  test("-d is equivalent to --detach", async () => {
-    process.argv = ["bun", "cadet", "tunnel", "--provider", "tailscale", "-d"];
-    spawnMock.mockImplementationOnce(() => {
-      appendFileSync(
-        detachedLogPath(),
-        "Tunnel established: https://tailnet.example.ts.net\n",
-      );
-      return makeFakeChild(1234);
-    });
-
-    await runTunnelCapturingLogs();
-
-    const [, args] = spawnMock.mock.calls[0] as unknown as [string, string[]];
-    expect(args).not.toContain("-d");
-    expect(args).not.toContain("--detach");
-  });
-
-  test("reports an early child exit instead of hanging", async () => {
+  test("--foreground runs the tunnel in this process instead of a detached child", async () => {
     process.argv = [
       "bun",
       "cadet",
       "tunnel",
       "--provider",
       "ngrok",
-      "--detach",
+      "--foreground",
     ];
+
+    await runTunnelCapturingLogs();
+
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(ensureTunnelEdgeMock).toHaveBeenCalled();
+    expect(runNgrokTunnelMock).toHaveBeenCalled();
+  });
+
+  test("reports an early child exit instead of hanging", async () => {
+    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
     spawnMock.mockImplementationOnce(() => {
       const child = makeFakeChild(4242);
       // Listeners attach synchronously right after spawn() returns; defer the
       // exit so they're in place before it fires.
-      setTimeout(() => (child as unknown as EventEmitter).emit("exit", 1), 0);
+      setTimeout(() => child.emit("exit", 1), 0);
       return child;
     });
 
@@ -1596,14 +1823,7 @@ describe("tunnel --detach", () => {
   });
 
   test("an adopted ngrok tunnel gets an accurate stop message, not a false kill claim", async () => {
-    process.argv = [
-      "bun",
-      "cadet",
-      "tunnel",
-      "--provider",
-      "ngrok",
-      "--detach",
-    ];
+    process.argv = ["bun", "cadet", "tunnel", "--provider", "ngrok"];
     spawnMock.mockImplementationOnce(() => {
       appendFileSync(
         detachedLogPath(),