@mycadet/cli 0.12.11 → 0.13.0-dev.202610171626.d97b8b8

package/src/__tests__/nginx-ingress.test.ts

@@ -26,6 +26,7 @@ import { z } from "zod";
 
 import * as httpClient from "../lib/http-client.js";
 import type { AssistantEntry } from "../lib/assistant-config.js";
+import { saveShellMode } from "../lib/ingress-config.js";
 
 const realChildProcess = { ...childProcess };
 const realFs = { ...fsModule };
@@ -51,6 +52,10 @@ mock.module("node:fs", () => ({
   readFileSync: readFileSyncMock,
 }));
 
+const fetchCurrentVersionMock = mock<typeof httpClient.fetchCurrentVersion>(
+  async () => "1.2.3",
+);
+
 const waitForDaemonReadyMock = mock<typeof httpClient.waitForDaemonReady>(
   async () => true,
 );
@@ -58,6 +63,7 @@ const waitForDaemonReadyMock = mock<typeof httpClient.waitForDaemonReady>(
 mock.module("../lib/http-client.js", () => ({
   ...httpClient,
   waitForDaemonReady: waitForDaemonReadyMock,
+  fetchCurrentVersion: fetchCurrentVersionMock,
 }));
 
 // Restore the real modules once this file finishes so the mocks do not leak
@@ -72,10 +78,10 @@ import {
   buildIngressNginxConfig,
   hasIpv6Loopback,
   buildRemoteWebIndexHtml,
-  cloudWebHubUrl,
   MAX_PRESERVED_MODULE_PRELOADS,
   ensureTunnelEdge,
   EDGE_TEMPLATE_VERSION,
+  findAppDistDir,
   findWebDistDir,
   startRemoteWebIngress,
   stopContainerTunnelEdge,
@@ -124,6 +130,8 @@ afterEach(() => {
   existsSyncMock.mockImplementation(realFs.existsSync);
   readFileSyncMock.mockReset();
   readFileSyncMock.mockImplementation(realFs.readFileSync);
+  fetchCurrentVersionMock.mockReset();
+  fetchCurrentVersionMock.mockImplementation(async () => "1.2.3");
   waitForDaemonReadyMock.mockReset();
   waitForDaemonReadyMock.mockImplementation(async () => true);
   for (const dir of workspaces.splice(0)) {
@@ -307,7 +315,7 @@ describe("buildIngressNginxConfig", () => {
     ).toEqual([]);
   });
 
-  test("revalidates the shell and forbids storing only the inline config", () => {
+  test("revalidates the shell and forbids storing inline config", () => {
     const blocks = locationBlocks(remoteConf);
     const cacheControlOf = (matcher: string) =>
       blocks
@@ -318,11 +326,8 @@ describe("buildIngressNginxConfig", () => {
     expect(cacheControlOf("^~ /assistant/assets/")).toBe(
       "public, max-age=31536000, immutable",
     );
-    // Only the inline __config return, which nginx gives no validator, still
-    // refuses storage. A second no-store means a revalidating location
-    // regressed to re-sending its whole body on every load.
+    // Inline config has no validator and must not be stored.
     expect(cacheControlOf("= /assistant/__config")).toBe("no-store");
-    expect(remoteConf.match(/no-store/g)).toHaveLength(1);
   });
 
   test("serves remote web config for the SPA", () => {
@@ -527,18 +532,6 @@ describe("buildRemoteWebIndexHtml", () => {
   });
 });
 
-describe("cloudWebHubUrl", () => {
-  test("maps build environments to their cloud SPA base", () => {
-    expect(cloudWebHubUrl("production")).toBe("https://mycadet.ai/assistant");
-    expect(cloudWebHubUrl("staging")).toBe(
-      "https://staging.mycadet.ai/assistant",
-    );
-    expect(cloudWebHubUrl("dev")).toBe("https://dev.mycadet.ai/assistant");
-    expect(cloudWebHubUrl("local")).toBe("https://dev.mycadet.ai/assistant");
-    expect(cloudWebHubUrl(undefined)).toBe("https://dev.mycadet.ai/assistant");
-  });
-});
-
 describe("nginx ingress process state", () => {
   function writeIngressState(workspaceDir: string, listenPort: number): void {
     writeFileSync(
@@ -746,17 +739,19 @@ function mockWebDistMissing(): void {
 }
 
 /** Force findWebDistDir() to resolve a dist dir, regardless of checkout state. */
-function mockWebDistPresent(): void {
+function mockWebDistPresent(version: string | null = "1.2.3"): void {
   existsSyncMock.mockImplementation((path) =>
     String(path).endsWith(WEB_INDEX_SUFFIX) ? true : realFs.existsSync(path),
   );
   readFileSyncMock.mockImplementation(((path, options) =>
     String(path).endsWith(WEB_INDEX_SUFFIX)
       ? FAKE_INDEX_HTML
-      : realFs.readFileSync(
-          path as never,
-          options as never,
-        )) as typeof readFileSync);
+      : String(path).endsWith("release.json")
+        ? JSON.stringify(version === null ? {} : { version })
+        : realFs.readFileSync(
+            path as never,
+            options as never,
+          )) as typeof readFileSync);
 }
 
 /** Record a running edge: ingress state, live pidfile, matching ps output. */
@@ -863,6 +858,10 @@ function spaConfigHash(
           hubUrl: PRODUCTION_HUB_URL,
         },
         webDistDir: opts.webDistDir ?? findWebDistDir(),
+        version: "1.2.3",
+        // Web mode is the default shell; the fingerprint covers the mode so
+        // an edge built for the other shell is never mistaken for this one.
+        shellMode: "web",
         indexHtml: opts.indexHtml ?? FAKE_INDEX_HTML,
       }),
     )
@@ -888,6 +887,70 @@ function pinProductionEnvironment(): void {
 describe("startRemoteWebIngress", () => {
   pinProductionEnvironment();
 
+  for (const [webVersion, runtimeVersion, ready] of [
+    ["1.2.3", "1.2.3", true],
+    ["1.2.3", "v1.2.3", true],
+    ["1.2.2", "1.2.3", false],
+    ["1.2.3", undefined, false],
+    [null, "1.2.3", false],
+  ] as const) {
+    test(`release resolution: UI ${webVersion}, assistant ${runtimeVersion}`, async () => {
+      const ws = makeWorkspace();
+      mockNginxInstalled();
+      mockNginxSpawn();
+      mockWebDistPresent(webVersion);
+      fetchCurrentVersionMock.mockResolvedValue(runtimeVersion);
+      const result = await startRemoteWebIngress({
+        workspaceDir: ws,
+        gatewayPort: 7830,
+        listenPort: 7845,
+        assistantId: "assistant-1",
+      });
+      expect(result.status).toBe("started");
+      expect(fetchCurrentVersionMock).toHaveBeenCalledWith(
+        "http://127.0.0.1:7830",
+      );
+      const conf = realFs.readFileSync(ingressConfPath(ws), "utf8");
+      const detail = conf
+        .split('location = "/v1/assistants/assistant-1/" {')[1]
+        ?.split("\n    }")[0];
+      expect(detail).toContain(`return ${ready ? 200 : 409} `);
+      if (ready) {
+        expect(detail).toContain('\\"version\\":\\"1.2.3\\"');
+      } else {
+        expect(detail).not.toContain('\\"url\\"');
+      }
+    });
+  }
+
+  test("restarts an edge when its verified assistant/UI release changes", async () => {
+    const ws = makeWorkspace();
+    mockNginxInstalled();
+    mockNginxSpawn();
+    mockWebDistPresent("1.2.3");
+    fetchCurrentVersionMock.mockResolvedValue("1.2.4");
+    const pid = mockRunningEdge(ws, {
+      listenPort: 7845,
+      includeWebApp: true,
+      gatewayPort: 7830,
+      remoteWebConfigHash: spaConfigHash({ assistantId: "assistant-1" }),
+    });
+    const edge = mockKillableNginx(pid);
+    const result = await startRemoteWebIngress({
+      workspaceDir: ws,
+      gatewayPort: 7830,
+      listenPort: 7845,
+      assistantId: "assistant-1",
+    });
+    expect(result.status).toBe("started");
+    expect(edge.killed()).toBe(true);
+    const conf = realFs.readFileSync(ingressConfPath(ws), "utf8");
+    const detail = conf
+      .split('location = "/v1/assistants/assistant-1/" {')[1]
+      ?.split("\n    }")[0];
+    expect(detail).toContain("return 409 ");
+  });
+
   test("webhooks-only mode starts the denylist+proxy edge without a web dist", async () => {
     const ws = makeWorkspace();
     mockNginxInstalled();
@@ -1857,6 +1920,7 @@ describe("ensureTunnelEdge", () => {
       port: 7845,
       started: false,
       includesWebApp: true,
+      shellMode: "web",
     });
     expect(edge.killed()).toBe(false);
     expect(spawnMock).not.toHaveBeenCalled();
@@ -2010,6 +2074,7 @@ describe("ensureTunnelEdge", () => {
       port: REQUESTED_PORT,
       started: true,
       includesWebApp: true,
+      shellMode: "web",
     });
     expect(edge.killed()).toBe(true);
     const conf = realFs.readFileSync(ingressConfPath(ws), "utf-8");
@@ -2034,6 +2099,7 @@ describe("ensureTunnelEdge", () => {
       port: REQUESTED_PORT,
       started: true,
       includesWebApp: true,
+      shellMode: "web",
     });
     expect(edge.killed()).toBe(true);
     const conf = realFs.readFileSync(ingressConfPath(ws), "utf-8");
@@ -2056,6 +2122,7 @@ describe("ensureTunnelEdge", () => {
       port: REQUESTED_PORT,
       started: true,
       includesWebApp: true,
+      shellMode: "web",
     });
     const conf = realFs.readFileSync(ingressConfPath(ws), "utf-8");
     expect(conf).toContain("location ^~ /assistant/ {");
@@ -2111,6 +2178,7 @@ describe("ensureTunnelEdge", () => {
       port: REQUESTED_PORT,
       started: true,
       includesWebApp: true,
+      shellMode: "web",
     });
     const conf = realFs.readFileSync(ingressConfPath(ws), "utf-8");
     expect(conf).toContain("location ^~ /assistant/ {");
@@ -2261,3 +2329,448 @@ describe("stopContainerTunnelEdge", () => {
     expect(await stopContainerTunnelEdge(containerEntry(7930))).toBe(false);
   });
 });
+
+describe("assistant metadata API", () => {
+  function config(id = "assistant-1") {
+    return buildIngressNginxConfig({
+      gatewayPort: 7830,
+      listenPort: 7840,
+      remoteWebIngress: {
+        webDistDir: "/tmp/web",
+        version: "1.2.3",
+        assistantId: id,
+        assistantName: "My assistant",
+        config: { appAllowedOrigins: ["https://parent.example"] },
+      },
+    });
+  }
+  function body(conf: string, path: string, status = 200): unknown {
+    const location = conf
+      .split(`location = "${path}" {`)[1]
+      ?.split("\n    }")[0];
+    const value = location?.match(/return (200|409) ("(?:\\.|[^"\\])*");/);
+    expect(Number(value?.[1])).toBe(status);
+    if (!value) {
+      throw new Error(`Missing metadata for ${path}`);
+    }
+    return JSON.parse(JSON.parse(value[2]));
+  }
+  test("lists only this host's assistant and returns its actual UI version and URL", () => {
+    const conf = config();
+    expect(body(conf, "/v1/assistants/")).toEqual({
+      results: [{ id: "assistant-1", name: "My assistant" }],
+      next: null,
+    });
+    expect(body(conf, "/v1/assistants/assistant-1/")).toEqual({
+      id: "assistant-1",
+      name: "My assistant",
+      status: "active",
+      version: "1.2.3",
+      url: "assistant/",
+    });
+    expect(conf).not.toContain('location = "/v1/assistants/other/"');
+  });
+  test("metadata supports both slash forms and only read methods", () => {
+    const conf = config();
+    for (const path of [
+      "/v1/assistants",
+      "/v1/assistants/",
+      "/v1/assistants/assistant-1",
+      "/v1/assistants/assistant-1/",
+    ]) {
+      expect(body(conf, path)).toBeDefined();
+    }
+    expect(conf).toContain(
+      "if ($request_method !~ ^(GET|HEAD)$) { return 405; }",
+    );
+    expect(conf).toContain(
+      '"https://parent.example" "https://parent.example";',
+    );
+    expect(conf).toContain(
+      "add_header Access-Control-Allow-Origin $cadet_app_origin always;",
+    );
+  });
+  test("unknown identity yields an empty list without inventing an assistant ID", () => {
+    const conf = buildIngressNginxConfig({
+      gatewayPort: 7830,
+      listenPort: 7840,
+      remoteWebIngress: { webDistDir: "/tmp/web" },
+    });
+    expect(body(conf, "/v1/assistants/")).toEqual({ results: [], next: null });
+  });
+  test("a known assistant without a UI bundle returns 409 on both detail paths", () => {
+    const conf = buildIngressNginxConfig({
+      gatewayPort: 7830,
+      listenPort: 7840,
+      remoteWebIngress: { webDistDir: "/tmp/web", assistantId: "assistant-1" },
+    });
+    expect(body(conf, "/v1/assistants/")).toEqual({
+      results: [{ id: "assistant-1" }],
+      next: null,
+    });
+    for (const path of [
+      "/v1/assistants/assistant-1",
+      "/v1/assistants/assistant-1/",
+    ]) {
+      expect(body(conf, path, 409)).toEqual({
+        detail: "assistant is not ready",
+      });
+    }
+  });
+  test("invalid browser origins fail before nginx starts", () => {
+    expect(() =>
+      buildIngressNginxConfig({
+        gatewayPort: 7830,
+        listenPort: 7840,
+        remoteWebIngress: {
+          webDistDir: "/tmp/web",
+          config: { appAllowedOrigins: ["https://parent.example/path"] },
+        },
+      }),
+    ).toThrow("App origins");
+  });
+});
+
+const APP_INDEX_SUFFIX = join("standalone", "index.html");
+const FAKE_APP_INDEX_HTML =
+  "<!doctype html><html><head><title>app</title></head><body>app-shell</body></html>";
+
+/**
+ * Force findAppDistDir() to resolve a standalone bundle. The web-dist mock
+ * below always pairs with it: app mode serves both bundles.
+ */
+function mockAppDistPresent(): void {
+  const previousExists = existsSyncMock.getMockImplementation();
+  existsSyncMock.mockImplementation((path) =>
+    String(path).endsWith(APP_INDEX_SUFFIX)
+      ? true
+      : previousExists
+        ? previousExists(path)
+        : realFs.existsSync(path),
+  );
+  const previousRead = readFileSyncMock.getMockImplementation();
+  readFileSyncMock.mockImplementation(((path, options) =>
+    String(path).endsWith(APP_INDEX_SUFFIX)
+      ? FAKE_APP_INDEX_HTML
+      : previousRead
+        ? previousRead(path as never, options as never)
+        : realFs.readFileSync(
+            path as never,
+            options as never,
+          )) as typeof readFileSync);
+}
+
+/** The fingerprint the edge must record for an app-mode SPA config. */
+function appConfigHash(
+  opts: {
+    assistantName?: string;
+    assistantId?: string;
+  } = {},
+): string {
+  return createHash("sha256")
+    .update(
+      JSON.stringify({
+        template: EDGE_TEMPLATE_VERSION,
+        config: {
+          remote: "custom",
+          apiBaseUrl: "/v1",
+          ...(opts.assistantName ? { assistantName: opts.assistantName } : {}),
+          ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
+          hubUrl: PRODUCTION_HUB_URL,
+        },
+        webDistDir: findWebDistDir(),
+        version: "1.2.3",
+        shellMode: "app",
+        appDistDir: findAppDistDir(),
+        appIndexHtml: FAKE_APP_INDEX_HTML,
+        indexHtml: FAKE_INDEX_HTML,
+      }),
+    )
+    .digest("hex");
+}
+
+describe("app shell mode", () => {
+  pinProductionEnvironment();
+
+  function appConf() {
+    return buildIngressNginxConfig({
+      gatewayPort: 7830,
+      listenPort: 7840,
+      remoteWebIngress: {
+        webDistDir: "/tmp/cadet web/dist",
+        appDistDir: "/tmp/cadet app/dist/standalone",
+        version: "1.2.3",
+        assistantId: "assistant-1",
+        config: {},
+      },
+    });
+  }
+
+  test("serves the app bundle as the outer shell from the origin root", () => {
+    const conf = appConf();
+    // The injected app document is internal-only and every shell route
+    // (/, /account/*, /logout, and the /assistant/* host routes) falls back
+    // to it through the named location.
+    expect(conf).toContain("location = /__cadet-app-index.html {");
+    // Without an explicit app index path, the config aliases the bundle's own
+    // index; the edge start path points this at the ingress dir (below).
+    expect(conf).toContain('alias "/tmp/cadet app/dist/standalone/index.html"');
+    expect(conf).toContain("location @cadet_app_shell {");
+    expect(conf).toContain("rewrite ^ /__cadet-app-index.html last;");
+    expect(conf).toContain(
+      "location = / {\n      rewrite ^ /__cadet-app-index.html last;\n    }",
+    );
+    expect(conf).toContain('alias "/tmp/cadet app/dist/standalone/assets/";');
+    expect(conf).toContain('alias "/tmp/cadet app/dist/standalone/";');
+    // The shell owns the /assistant/* host routes; the exact mounts load the
+    // app document rather than the web SPA.
+    expect(conf).toContain(
+      "location = /assistant {\n      rewrite ^ /__cadet-app-index.html last;\n    }",
+    );
+    expect(conf).toContain(
+      "location = /assistant/ {\n      rewrite ^ /__cadet-app-index.html last;\n    }",
+    );
+    expect(conf).toContain("try_files $uri @cadet_app_shell;");
+    // No recursive loading: the web SPA's exact mount is gone from the shell.
+    expect(conf).not.toContain(
+      "location = /assistant/ {\n      rewrite ^ /assistant/__remote-index.html last;\n    }",
+    );
+  });
+
+  test("iframes the web UI from the distinct /web/assistant namespace", () => {
+    const conf = appConf();
+    expect(conf).toContain('location = "/v1/assistants/assistant-1/"');
+    expect(conf).toContain('\\"url\\":\\"web/assistant/\\"');
+    expect(conf).toContain('\\"version\\":\\"1.2.3\\"');
+    expect(conf).toContain(
+      "location = /web/assistant/ {\n      rewrite ^ /web/assistant/__remote-index.html last;\n    }",
+    );
+    expect(conf).toContain("location = /web/assistant/__remote-index.html {");
+    expect(conf).toContain('alias "/tmp/cadet web/dist/index.html"');
+    expect(conf).toContain("location = /web/assistant/__config {");
+    expect(conf).toContain("location ^~ /web/assistant/ {");
+    expect(conf).toContain(
+      "try_files $uri $uri/ /web/assistant/__remote-index.html;",
+    );
+    // The web bundle's asset URLs keep their baked /assistant/ base.
+    expect(conf).toContain(
+      'location ^~ /assistant/assets/ {\n      gzip on;\n      alias "/tmp/cadet web/dist/assets/"',
+    );
+    // Prefixed API paths the web UI builds from its serving prefix.
+    expect(conf).toContain("location ^~ /web/v1/ {");
+    expect(conf).toContain("proxy_pass http://127.0.0.1:7830/v1/;");
+    // Nothing else under /web exists, so the namespace cannot serve the shell
+    // (or anything else) recursively.
+    expect(conf).toContain("location ^~ /web/ {\n      return 404;\n    }");
+  });
+
+  test("blocks the sensitive gateway routes under both prefixes", () => {
+    const conf = appConf();
+    for (const route of ["/v1/pair", "/v1/devices", "/v1/guardian/init"]) {
+      expect(conf).toContain(`location = ${route} { return 404; }`);
+      expect(conf).toContain(`location = /web${route} { return 404; }`);
+    }
+    expect(conf).toContain(
+      "location ^~ /web/assistant/__local/ { return 404; }",
+    );
+  });
+
+  test("proxies runtime API paths verbatim for both surfaces", () => {
+    const conf = appConf();
+    expect(conf).toContain(
+      "location ^~ /v1/ {\n      proxy_pass http://127.0.0.1:7830;",
+    );
+    expect(conf).toContain(
+      "location ^~ /webhooks/ {\n      proxy_pass http://127.0.0.1:7830;",
+    );
+    expect(conf).toContain(
+      "location = /healthz {\n      proxy_pass http://127.0.0.1:7830;",
+    );
+  });
+
+  test("app mode starts, injects both documents, and records the app fingerprint", async () => {
+    const ws = makeWorkspace();
+    mockNginxInstalled();
+    mockNginxSpawn();
+    mockWebDistPresent();
+    mockAppDistPresent();
+    fetchCurrentVersionMock.mockResolvedValue("1.2.3");
+
+    const result = await startRemoteWebIngress({
+      workspaceDir: ws,
+      gatewayPort: 7830,
+      listenPort: 7845,
+      shellMode: "app",
+      assistantId: "assistant-1",
+    });
+
+    expect(result.status).toBe("started");
+    const ingressDir = join(ws, "data", "ingress");
+    const appIndex = realFs.readFileSync(
+      join(ingressDir, "app-index.html"),
+      "utf-8",
+    );
+    expect(appIndex).toContain("__CADET_CONFIG__");
+    expect(appIndex).toContain(`"assistantId":"assistant-1"`);
+    const conf = realFs.readFileSync(ingressConfPath(ws), "utf-8");
+    expect(conf).toContain("location = /__cadet-app-index.html {");
+    expect(conf).toContain('\\"url\\":\\"web/assistant/\\"');
+    expect(readConfig(ws).ingress?.nginx).toMatchObject({
+      listenPort: 7845,
+      includeWebApp: true,
+      gatewayPort: 7830,
+      remoteWebConfigHash: appConfigHash({ assistantId: "assistant-1" }),
+    });
+  });
+
+  test("fails fast when the app bundle is not built", async () => {
+    const ws = makeWorkspace();
+    mockNginxInstalled();
+    mockNginxSpawn();
+    mockWebDistPresent();
+    // A real build in the checkout would satisfy the lookup; the failure
+    // path needs the lookup to resolve nothing, regardless of checkout state.
+    // Web dist stays present so the app-dist check is the one that fires.
+    const previousExists = existsSyncMock.getMockImplementation();
+    existsSyncMock.mockImplementation((path) =>
+      String(path).endsWith(APP_INDEX_SUFFIX)
+        ? false
+        : previousExists
+          ? previousExists(path)
+          : realFs.existsSync(path),
+    );
+
+    const result = await startRemoteWebIngress({
+      workspaceDir: ws,
+      gatewayPort: 7830,
+      listenPort: 7845,
+      shellMode: "app",
+    });
+
+    expect(result).toEqual({ status: "app-dist-missing" });
+    expect(realFs.existsSync(ingressConfPath(ws))).toBe(false);
+  });
+
+  test("restarting an edge between shell modes rotates onto the requested mode", async () => {
+    const ws = makeWorkspace();
+    mockNginxInstalled();
+    mockNginxSpawn();
+    mockWebDistPresent();
+    mockAppDistPresent();
+    // A running web-mode edge whose fingerprint predates app mode.
+    mockRunningEdge(ws, {
+      listenPort: 7845,
+      includeWebApp: true,
+      gatewayPort: 7830,
+      remoteWebConfigHash: spaConfigHash({ assistantId: "assistant-1" }),
+    });
+    const edge = mockKillableNginx(123_460);
+
+    const result = await startRemoteWebIngress({
+      workspaceDir: ws,
+      gatewayPort: 7830,
+      listenPort: 7845,
+      shellMode: "app",
+      assistantId: "assistant-1",
+    });
+
+    expect(result.status).toBe("started");
+    expect(edge.killed()).toBe(true);
+    expect(readConfig(ws).ingress?.nginx).toMatchObject({
+      remoteWebConfigHash: appConfigHash({ assistantId: "assistant-1" }),
+    });
+  });
+
+  test("reuses an already-running app-mode edge", async () => {
+    const ws = makeWorkspace();
+    mockNginxInstalled();
+    mockNginxSpawn();
+    mockWebDistPresent();
+    mockAppDistPresent();
+    mockRunningEdge(ws, {
+      listenPort: 7845,
+      includeWebApp: true,
+      gatewayPort: 7830,
+      remoteWebConfigHash: appConfigHash({ assistantId: "assistant-1" }),
+    });
+    const edge = mockKillableNginx(123_460);
+
+    const result = await startRemoteWebIngress({
+      workspaceDir: ws,
+      gatewayPort: 7830,
+      listenPort: 7845,
+      shellMode: "app",
+      assistantId: "assistant-1",
+    });
+
+    expect(result).toMatchObject({
+      status: "already-running",
+      listenPort: 7845,
+    });
+    expect(edge.killed()).toBe(false);
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  test("ensureTunnelEdge reads the persisted shell mode from the lockfile", async () => {
+    const ws = makeWorkspace();
+    mockNginxInstalled();
+    mockNginxSpawn();
+    mockWebDistPresent();
+    mockAppDistPresent();
+    const originalLockfileDir = process.env.CADET_LOCKFILE_DIR;
+    const lockfileDir = join(ws, "lockfile");
+    mkdirSync(lockfileDir, { recursive: true });
+    process.env.CADET_LOCKFILE_DIR = lockfileDir;
+    try {
+      saveShellMode("app");
+
+      const result = await ensureTunnelEdge({
+        assistantId: "assistant-1",
+        workspaceDir: ws,
+        gatewayPort: 7830,
+      });
+
+      expect(result.shellMode).toBe("app");
+    } finally {
+      if (originalLockfileDir === undefined) {
+        delete process.env.CADET_LOCKFILE_DIR;
+      } else {
+        process.env.CADET_LOCKFILE_DIR = originalLockfileDir;
+      }
+    }
+    const conf = realFs.readFileSync(ingressConfPath(ws), "utf-8");
+    expect(conf).toContain("location = /__cadet-app-index.html {");
+    expect(conf).toContain('\\"url\\":\\"web/assistant/\\"');
+  });
+
+  test("ensureTunnelEdge defaults to the web shell", async () => {
+    const ws = makeWorkspace();
+    mockNginxInstalled();
+    mockNginxSpawn();
+    mockWebDistPresent();
+    // Hermetic lockfile dir: no edgeShell key means the web default, even if
+    // the machine running the tests has its own shell selection persisted.
+    const originalLockfileDir = process.env.CADET_LOCKFILE_DIR;
+    const lockfileDir = join(ws, "lockfile");
+    mkdirSync(lockfileDir, { recursive: true });
+    process.env.CADET_LOCKFILE_DIR = lockfileDir;
+    try {
+      const result = await ensureTunnelEdge({
+        assistantId: "assistant-1",
+        workspaceDir: ws,
+        gatewayPort: 7830,
+      });
+
+      expect(result.shellMode).toBe("web");
+    } finally {
+      if (originalLockfileDir === undefined) {
+        delete process.env.CADET_LOCKFILE_DIR;
+      } else {
+        process.env.CADET_LOCKFILE_DIR = originalLockfileDir;
+      }
+    }
+    const conf = realFs.readFileSync(ingressConfPath(ws), "utf-8");
+    expect(conf).not.toContain("__cadet-app-index");
+    expect(conf).toContain('\\"url\\":\\"assistant/\\"');
+  });
+});

package/src/__tests__/orphan-detection.test.ts

@@ -107,7 +107,7 @@ describe("getKnownPidsFromAssistants", () => {
     const entry: AssistantEntry = {
       assistantId: "managed-1",
       runtimeUrl: "https://cloud.mycadet.ai/foo",
-      cloud: "cadet",
+      cloud: "cloud",
     };
     const pids = getKnownPidsFromAssistants([entry]);
     expect(pids.size).toBe(0);