@mycadet/cli 0.12.10 → 0.13.0-dev.202610171617.9ea363e

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,11 @@ import {
   buildIngressNginxConfig,
   hasIpv6Loopback,
   buildRemoteWebIndexHtml,
-  cloudWebHubUrl,
   MAX_PRESERVED_MODULE_PRELOADS,
   ensureTunnelEdge,
   EDGE_TEMPLATE_VERSION,
+  findAppDistDir,
+  findWebDistDir,
   startRemoteWebIngress,
   stopContainerTunnelEdge,
   stopIngressNginx,
@@ -123,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)) {
@@ -306,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
@@ -317,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", () => {
@@ -456,9 +462,7 @@ describe("buildRemoteWebIndexHtml", () => {
     expect(result).toContain(
       'window.__CADET_CONFIG__={"remote":"docker","apiBaseUrl":"/v1"}',
     );
-    expect(result.indexOf('"webUrl"')).toBeLessThan(
-      result.indexOf('"docker"'),
-    );
+    expect(result.indexOf('"webUrl"')).toBeLessThan(result.indexOf('"docker"'));
   });
 
   test("escapes config JSON before embedding it in a script tag", () => {
@@ -528,26 +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(
@@ -755,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. */
@@ -846,14 +832,19 @@ const PRODUCTION_HUB_URL = "https://mycadet.ai/assistant";
 
 /**
  * Mirror of the SPA config fingerprint the edge records in its ingress state
- * (sha256 over the edge template version and the injected config JSON). Pins
+ * (sha256 over the template, injected config, bundle directory and index). Pins
  * both the injected config shape and the hash format; assumes the
  * production-pinned environment. The version itself is imported rather than
  * mirrored: bumping it is the correct response to any template edit, so a
  * copy here would fail every such edit without naming a defect.
  */
 function spaConfigHash(
-  opts: { assistantName?: string; assistantId?: string } = {},
+  opts: {
+    assistantName?: string;
+    assistantId?: string;
+    indexHtml?: string;
+    webDistDir?: string;
+  } = {},
 ): string {
   return createHash("sha256")
     .update(
@@ -866,6 +857,12 @@ function spaConfigHash(
           ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
           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,
       }),
     )
     .digest("hex");
@@ -890,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();
@@ -1247,6 +1308,7 @@ describe("startRemoteWebIngress", () => {
     const ws = makeWorkspace();
     mockNginxInstalled();
     mockNginxSpawn();
+    mockWebDistPresent();
     const pid = mockRunningEdge(ws, {
       listenPort: 7845,
       gatewayPort: 7830,
@@ -1300,6 +1362,44 @@ describe("startRemoteWebIngress", () => {
     expect(spawnMock).not.toHaveBeenCalled();
   });
 
+  for (const drift of ["indexHtml", "webDistDir"] as const) {
+    test(`restarts a detached edge when the web bundle ${drift} changes`, async () => {
+      const ws = makeWorkspace();
+      mockNginxInstalled();
+      mockNginxSpawn();
+      mockWebDistPresent();
+      const pid = mockRunningEdge(ws, {
+        listenPort: 7845,
+        includeWebApp: true,
+        gatewayPort: 7830,
+        remoteWebConfigHash: spaConfigHash({
+          ...(drift === "indexHtml"
+            ? {
+                indexHtml:
+                  '<html><head><script src="/assistant/assets/old.js"></script></head></html>',
+              }
+            : { webDistDir: "/old-release/dist" }),
+        }),
+      });
+      const edge = mockKillableNginx(pid);
+      const result = await startRemoteWebIngress({
+        workspaceDir: ws,
+        gatewayPort: 7830,
+      });
+      expect(result).toMatchObject({ status: "started", listenPort: 7845 });
+      expect(edge.killed()).toBe(true);
+      expect(readConfig(ws).ingress?.nginx?.remoteWebConfigHash).toBe(
+        spaConfigHash(),
+      );
+      expect(
+        realFs.readFileSync(
+          join(ws, "data", "ingress", "assistant-index.html"),
+          "utf-8",
+        ),
+      ).not.toContain("old.js");
+    });
+  }
+
   test("restarts the edge when the injected SPA config drifts from the recorded one", async () => {
     const ws = makeWorkspace();
     mockNginxInstalled();
@@ -1801,6 +1901,7 @@ describe("ensureTunnelEdge", () => {
     const ws = makeWorkspace();
     mockNginxInstalled();
     mockNginxSpawn();
+    mockWebDistPresent();
     const pid = mockRunningEdge(ws, {
       listenPort: 7845,
       includeWebApp: true,
@@ -1819,6 +1920,7 @@ describe("ensureTunnelEdge", () => {
       port: 7845,
       started: false,
       includesWebApp: true,
+      shellMode: "web",
     });
     expect(edge.killed()).toBe(false);
     expect(spawnMock).not.toHaveBeenCalled();
@@ -1972,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");
@@ -1996,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");
@@ -2018,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/ {");
@@ -2073,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/ {");
@@ -2223,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/\\"');
+  });
+});