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

package/src/lib/nginx-ingress.ts

@@ -13,9 +13,12 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { createServer } from "node:net";
 import { networkInterfaces } from "node:os";
 import { join } from "node:path";
 
+import { z } from "zod";
+
 import { cloudAssistantHubUrl } from "@mycadet/environments";
 
 import {
@@ -27,17 +30,24 @@ import {
 } from "./assistant-config.js";
 import type { RemoteHost } from "./constants.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
-import { waitForDaemonReady } from "./http-client.js";
+import { fetchCurrentVersion, waitForDaemonReady } from "./http-client.js";
 import {
   getDefaultWorkspaceDir,
   isLocalContainerEntry,
   loadRawConfig,
   parseGatewayPortFromEntryUrls,
+  readShellMode,
   saveRawConfig,
 } from "./ingress-config.js";
-import { findWebDistDir } from "./web-dist.js";
+import { stripVersionPrefix } from "./version-compat.js";
+import {
+  findAppDistDir,
+  findWebDistDir,
+  readWebReleaseVersion,
+} from "./web-dist.js";
 
 export { findWebDistDir } from "./web-dist.js";
+export { findAppDistDir } from "./web-dist.js";
 
 /**
  * CLI-managed nginx reverse proxy that fronts the gateway as the canonical
@@ -92,8 +102,8 @@ function nginxDirPath(dir: string): string {
   return dir.endsWith("/") ? dir : `${dir}/`;
 }
 
-function gatewayProxyBlock(gatewayPort: number): string {
-  return `      proxy_pass http://127.0.0.1:${gatewayPort};
+function gatewayProxyBlock(gatewayPort: number, upstreamPath = ""): string {
+  return `      proxy_pass http://127.0.0.1:${gatewayPort}${upstreamPath};
       proxy_http_version 1.1;
       proxy_request_buffering off;
       proxy_buffering off;
@@ -106,40 +116,71 @@ function gatewayProxyBlock(gatewayPort: number): string {
 }
 
 /**
- * Sensitive local-only routes the edge must never expose to the internet,
- * regardless of whether the SPA is being served.
+ * Sensitive local-only gateway paths the edge must never expose to the
+ * internet, regardless of which client bundles are being served. Each exact
+ * path is blocked with and without its trailing slash.
  */
-const DENYLIST_LOCATIONS = `    location = /auth/token { return 404; }
-    location = /auth/token/ { return 404; }
-    location = /v1/pair { return 404; }
-    location = /v1/pair/ { return 404; }
-    location = /v1/pair/web-init { return 404; }
-    location = /v1/pair/web-init/ { return 404; }
-    location = /v1/devices { return 404; }
-    location = /v1/devices/ { return 404; }
-    location = /v1/devices/revoke { return 404; }
-    location = /v1/devices/revoke/ { return 404; }
-    location = /v1/guardian/init { return 404; }
-    location = /v1/guardian/init/ { return 404; }
-    location = /v1/guardian/reset-bootstrap { return 404; }
-    location = /v1/guardian/reset-bootstrap/ { return 404; }
-    location = /v1/remote-web/pairing-requests { return 404; }
-    location = /v1/remote-web/pairing-requests/ { return 404; }
-    location = /v1/remote-web/pairing-requests/approve { return 404; }
-    location = /v1/remote-web/pairing-requests/approve/ { return 404; }
-    location = /v1/remote-web/pairing-requests/deny { return 404; }
-    location = /v1/remote-web/pairing-requests/deny/ { return 404; }
-    location = /v1/remote-web/pairing-verification { return 404; }
-    location = /v1/remote-web/pairing-verification/ { return 404; }
-    location = /v1/shared/invites/redeem { return 404; }
-    location = /v1/shared/invites/redeem/ { return 404; }
-    location ^~ /assistant/__local/ { return 404; }
-    location ^~ /assistant/__gateway/ { return 404; }
-    location ^~ /assistant/__gateway-paired/ { return 404; }`;
+const SENSITIVE_GATEWAY_ROUTES = [
+  "/auth/token",
+  "/v1/pair",
+  "/v1/pair/web-init",
+  "/v1/devices",
+  "/v1/devices/revoke",
+  "/v1/guardian/init",
+  "/v1/guardian/reset-bootstrap",
+  "/v1/remote-web/pairing-requests",
+  "/v1/remote-web/pairing-requests/approve",
+  "/v1/remote-web/pairing-requests/deny",
+  "/v1/remote-web/pairing-verification",
+  "/v1/shared/invites/redeem",
+] as const;
+
+/** Sensitive path prefixes, blocked with a prefix match. */
+const SENSITIVE_GATEWAY_PREFIXES = [
+  "/assistant/__local/",
+  "/assistant/__gateway/",
+  "/assistant/__gateway-paired/",
+] as const;
+
+/**
+ * Denylist locations for gateway paths under one public prefix. The edge
+ * serves from the origin root (web mode) and — in app mode — from the
+ * `/web` iframe prefix, where the web UI's prefix-aware API paths
+ * (`remoteGatewayApiPath`) put the same gateway routes at `/web/v1/...`;
+ * the sensitive ones must be blocked in both spellings.
+ */
+function denylistLocations(prefix = ""): string {
+  const exact = SENSITIVE_GATEWAY_ROUTES.map((route) => {
+    const block = (path: string) =>
+      `    location = ${prefix}${path} { return 404; }`;
+    return `${block(route)}\n${block(`${route}/`)}`;
+  });
+  const prefixes = SENSITIVE_GATEWAY_PREFIXES.map((route) => {
+    return `    location ^~ ${prefix}${route} { return 404; }`;
+  });
+  return [...exact, ...prefixes].join("\n");
+}
+
+const DENYLIST_LOCATIONS = denylistLocations();
 
 export interface RemoteWebIngressOptions {
   webDistDir: string;
+  /**
+   * Standalone app-shell bundle. Present only in app shell mode: the edge
+   * serves this bundle as the outer account/client shell from the origin
+   * root and iframes the web SPA from /web/assistant/. Absent (web mode)
+   * keeps serving the web SPA directly from /assistant/.
+   */
+  appDistDir?: string;
+  /**
+   * The config-injected app-shell document. Defaults to the app bundle's own
+   * index; the edge start path points this at the ingress dir, where the
+   * injected copy is written.
+   */
+  appIndexHtmlPath?: string;
   indexHtmlPath?: string;
+  /** Assistant release verified against the served UI artifact. */
+  version?: string;
   config?: Record<string, unknown>;
   /** Serving assistant's display name, stamped into the served config so
    *  remote clients can label this origin. Absent in older served configs. */
@@ -149,24 +190,41 @@ export interface RemoteWebIngressOptions {
    *  configs. */
   assistantId?: string;
   /** Cloud web SPA base the remote client can hand this origin to (see
-   *  `cloudWebHubUrl`). Absent in older served configs. */
+   *  `cloudAssistantHubUrl`). Absent in older served configs. */
   hubUrl?: string;
 }
 
 /**
- * Cloud web SPA base URL for a build environment. The mapping lives in
- * `@mycadet/environments` (`cloudAssistantHubUrl`) and is shared with the
- * Capacitor shell's `server.url`, so the two consumers cannot drift.
+ * The web UI entry the assistant detail API hands the shell, relative to the
+ * origin root. Web mode serves the web SPA directly at /assistant/; app mode
+ * serves it from the distinct /web/assistant/ iframe namespace so the shell's
+ * own /assistant/* host routes can never load the shell recursively.
  */
-export function cloudWebHubUrl(env: string | undefined): string {
-  return cloudAssistantHubUrl(env);
+export function assistantEntryUrl(appDistDir: string | undefined): string {
+  return appDistDir ? "web/assistant/" : "assistant/";
 }
 
 // The edge serves remote browsers, so the bundle's remote-gateway machinery
 // must always run: it is reached through this self-hosted edge however the
 // cadet itself is hosted. "cloud" is never stamped (the cloud serves its
 // own bundles).
-const EDGE_SERVED_REMOTE: RemoteHost = "custom";
+/** The lockfile's recorded remote kind for the assistant, if one is found. */
+function lockfileAssistantRemote(assistantId: string): string | undefined {
+  const result = lookupAssistantByIdentifier(assistantId);
+  return result.status === "found" ? result.entry.cloud : undefined;
+}
+
+/**
+ * The remote kind stamped into the served SPA config. Docker and custom
+ * cadets are stamped truthfully; every other hosting shape — a local cadet
+ * reached through this edge, paired remotes, unknown entries — reads as
+ * "custom" so the served bundle always runs the remote-gateway machinery
+ * (this edge serves remote browsers however the cadet itself is hosted).
+ * "cloud" is never stamped: the cloud serves its own bundles.
+ */
+export function edgeServedRemote(recorded: string | undefined): RemoteHost {
+  return recorded === "docker" ? "docker" : "custom";
+}
 
 function remoteWebIngressConfig(
   opts: Pick<
@@ -175,7 +233,9 @@ function remoteWebIngressConfig(
   >,
 ): Record<string, unknown> {
   return {
-    remote: EDGE_SERVED_REMOTE,
+    remote: edgeServedRemote(
+      opts.assistantId ? lockfileAssistantRemote(opts.assistantId) : undefined,
+    ),
     apiBaseUrl: "/v1",
     ...(opts.assistantName ? { assistantName: opts.assistantName } : {}),
     ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
@@ -189,17 +249,43 @@ function remoteWebIngressConfig(
  * fingerprint matches, so this must change whenever the generated index or
  * nginx template does.
  */
-export const EDGE_TEMPLATE_VERSION = 10;
+export const EDGE_TEMPLATE_VERSION = 13;
 
 /**
- * Stable fingerprint of the SPA config injected into the served index and
- * `/assistant/__config`, plus the template that renders them. Recorded
+ * Stable fingerprint of the injected SPA config, its source bundles, the
+ * shell mode, and the template that renders them. Recorded
  * alongside the edge state so a reuse decision can tell whether a running edge
  * already serves the requested config (see `IngressState.remoteWebConfigHash`).
  */
-function remoteWebConfigFingerprint(config: Record<string, unknown>): string {
+function remoteWebConfigFingerprint(
+  config: Record<string, unknown>,
+  webDistDir: string,
+  version?: string,
+  appDistDir?: string,
+): string {
   return createHash("sha256")
-    .update(JSON.stringify({ template: EDGE_TEMPLATE_VERSION, config }))
+    .update(
+      JSON.stringify({
+        template: EDGE_TEMPLATE_VERSION,
+        config,
+        webDistDir,
+        version,
+        // The shell mode is part of edge identity: flipping the persisted
+        // shell mode must rotate a running edge onto the requested shell
+        // even though every other fingerprint input may be unchanged.
+        shellMode: appDistDir ? "app" : "web",
+        ...(appDistDir
+          ? {
+              appDistDir,
+              appIndexHtml: readFileSync(
+                join(appDistDir, "index.html"),
+                "utf-8",
+              ),
+            }
+          : {}),
+        indexHtml: readFileSync(join(webDistDir, "index.html"), "utf-8"),
+      }),
+    )
     .digest("hex");
 }
 
@@ -278,9 +364,140 @@ export function hasIpv6Loopback(): boolean {
     .some((addr) => addr.address === "::1");
 }
 
+/** Whether a TCP listener already holds `port` on the given loopback host. */
+async function isPortInUse(
+  port: number,
+  host: "127.0.0.1" | "::1",
+): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => resolve(true));
+    probe.once("listening", () => {
+      probe.close(() => resolve(false));
+    });
+    probe.listen(port, host);
+  });
+}
+
 /**
- * Build the nginx config that forwards tunnel web traffic to the gateway.
+ * The first free loopback port at or above `startPort`, scanning a short band,
+ * or null when the whole band is busy. Both stacks the edge may bind are
+ * probed (the IPv4 loopback always, the IPv6 loopback when the host has one),
+ * so the returned port is one nginx can actually take.
  */
+export async function findAvailableIngressPort(
+  startPort: number,
+  attempts = 20,
+): Promise<number | null> {
+  const checkIpv6 = hasIpv6Loopback();
+  for (let port = startPort; port < startPort + attempts; port++) {
+    if (await isPortInUse(port, "127.0.0.1")) {
+      continue;
+    }
+    if (checkIpv6 && (await isPortInUse(port, "::1"))) {
+      continue;
+    }
+    return port;
+  }
+  return null;
+}
+
+const AssistantHostConfigSchema = z.object({
+  assistantId: z.string().min(1).optional(),
+  assistantName: z.string().optional(),
+  version: z.string().min(1).optional(),
+  hubUrl: z.string().url().optional(),
+  appAllowedOrigins: z.array(z.string().url()).default([]),
+});
+
+function assistantHostConfig(config: Record<string, unknown>) {
+  const result = AssistantHostConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new Error("Invalid assistant host configuration.");
+  }
+  return result.data;
+}
+
+function appOrigins(config: Record<string, unknown>): string[] {
+  const metadata = assistantHostConfig(config);
+  const origins = [
+    ...metadata.appAllowedOrigins,
+    ...(metadata.hubUrl ? [new URL(metadata.hubUrl).origin] : []),
+  ];
+  return [...new Set(origins)].map((origin) => {
+    const url = new URL(origin);
+    if (
+      (url.protocol !== "https:" &&
+        !(
+          url.protocol === "http:" &&
+          ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+        )) ||
+      url.origin !== origin.replace(/\/$/, "")
+    ) {
+      throw new Error(
+        "App origins must be HTTPS origins or loopback HTTP origins.",
+      );
+    }
+    return url.origin;
+  });
+}
+
+function assistantMetadataLocations(config: Record<string, unknown>): string {
+  const metadata = assistantHostConfig(config);
+  const id = metadata.assistantId;
+  const entryUrl =
+    typeof config.entryUrl === "string" ? config.entryUrl : undefined;
+  const choice = id
+    ? {
+        id,
+        ...(metadata.assistantName ? { name: metadata.assistantName } : {}),
+      }
+    : undefined;
+  const responses = [
+    {
+      path: "/v1/assistants",
+      status: 200,
+      body: { results: choice ? [choice] : [], next: null },
+    },
+    ...(choice && id
+      ? [
+          {
+            path: `/v1/assistants/${encodeURIComponent(id)}`,
+            status: metadata.version ? 200 : 409,
+            body: metadata.version
+              ? {
+                  ...choice,
+                  status: "active",
+                  version: metadata.version,
+                  url: entryUrl ?? "assistant/",
+                }
+              : { detail: "assistant is not ready" },
+          },
+        ]
+      : []),
+  ];
+  return responses
+    .flatMap(({ path, status, body }) =>
+      [path, `${path}/`].map(
+        (route) => `
+    location = ${nginxQuoted(route, "assistant API path")} {
+      default_type application/json;
+      add_header Cache-Control "no-store" always;
+      add_header Access-Control-Allow-Origin $cadet_app_origin always;
+      add_header Access-Control-Allow-Credentials "true" always;
+      add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
+      add_header Access-Control-Allow-Headers "Accept, Cadet-Organization-Id" always;
+      add_header Vary "Origin" always;
+      if ($request_method = OPTIONS) { return 204; }
+      if ($request_method !~ ^(GET|HEAD)$) { return 405; }
+      return ${status} ${nginxQuoted(JSON.stringify(body), "assistant metadata")};
+    }`,
+      ),
+    )
+    .join("\n");
+}
+
+/** Build the nginx config for the tunnel edge and its public assistant metadata. */
 export function buildIngressNginxConfig(opts: {
   gatewayPort: number;
   listenPort: number;
@@ -296,12 +513,18 @@ export function buildIngressNginxConfig(opts: {
     ? `    listen [::1]:${opts.listenPort};\n`
     : "";
   const remoteWebIngress = opts.remoteWebIngress;
+  const allowedOrigins = remoteWebIngress
+    ? appOrigins(remoteWebIngressConfig(remoteWebIngress))
+    : [];
   const serverLocations = remoteWebIngress
     ? buildRemoteWebIngressLocations({
         gatewayPort: opts.gatewayPort,
         webDistDir: remoteWebIngress.webDistDir,
+        appDistDir: remoteWebIngress.appDistDir,
+        appIndexHtmlPath: remoteWebIngress.appIndexHtmlPath,
         indexHtmlPath: remoteWebIngress.indexHtmlPath,
         config: remoteWebIngressConfig(remoteWebIngress),
+        version: remoteWebIngress.version,
       })
     : `${DENYLIST_LOCATIONS}
 
@@ -350,6 +573,11 @@ http {
     text/plain txt;
   }
 
+  map $http_origin $cadet_app_origin {
+    default "";
+${allowedOrigins.map((origin) => `    ${nginxQuoted(origin, "app origin")} ${nginxQuoted(origin, "app origin")};`).join("\n")}
+  }
+
   map $http_upgrade $connection_upgrade {
     default upgrade;
     "" close;
@@ -385,22 +613,13 @@ ${serverLocations}
 `;
 }
 
-function buildRemoteWebIngressLocations(opts: {
-  gatewayPort: number;
-  webDistDir: string;
-  indexHtmlPath?: string;
-  config: Record<string, unknown>;
-}): string {
-  const proxyBlock = gatewayProxyBlock(opts.gatewayPort);
-  const webDistDir = nginxDirPath(opts.webDistDir);
-  const webAssetsDir = join(opts.webDistDir, "assets");
-  const indexHtmlPath =
-    opts.indexHtmlPath ?? join(opts.webDistDir, "index.html");
-  const configJson = JSON.stringify(opts.config);
-
-  return `${DENYLIST_LOCATIONS}
-
-    location = /healthz {
+/**
+ * Gateway-facing locations shared by both shell modes: liveness probes and
+ * the runtime API surface, all proxied verbatim.
+ */
+function gatewayProxyLocations(gatewayPort: number): string {
+  const proxyBlock = gatewayProxyBlock(gatewayPort);
+  return `    location = /healthz {
 ${proxyBlock}
     }
 
@@ -414,18 +633,34 @@ ${proxyBlock}
 
     location ^~ /webhooks/ {
 ${proxyBlock}
-    }
+    }`;
+}
 
-    location = /assistant {
-      return 302 /assistant/;
+/**
+ * Serve the web SPA from one path prefix: the exact-mount rewrites, the
+ * injected index, the inline config, and the SPA fallback. Used for the
+ * /assistant/ mount in web mode and the /web/assistant/ iframe mount in
+ * app mode. `prefix` carries both a leading and trailing slash.
+ */
+function webSpaLocations(opts: {
+  prefix: string;
+  webDistDir: string;
+  indexHtmlPath: string;
+  config: Record<string, unknown>;
+}): string {
+  const indexHtmlPath = opts.indexHtmlPath;
+  const configJson = JSON.stringify(opts.config);
+  const prefix = opts.prefix.replace(/\/+$/, "");
+  return `    location = ${prefix} {
+      return 302 ${prefix}/;
     }
 
-    location = /assistant/ {
-      rewrite ^ /assistant/__remote-index.html last;
+    location = ${prefix}/ {
+      rewrite ^ ${prefix}/__remote-index.html last;
     }
 
-    location = /assistant/index.html {
-      rewrite ^ /assistant/__remote-index.html last;
+    location = ${prefix}/index.html {
+      rewrite ^ ${prefix}/__remote-index.html last;
     }
 
     # The shell and the unhashed files beside it revalidate rather than
@@ -433,39 +668,173 @@ ${proxyBlock}
     # disk with a validator, so a repeat load costs a 304 instead of the whole
     # document. __config is the exception below: it is returned inline, so
     # nginx attaches no validator for a revalidation to match against.
-    location = /assistant/__remote-index.html {
+    location = ${prefix}/__remote-index.html {
       internal;
       gzip on;
       alias ${nginxQuoted(indexHtmlPath, "remote web ingress index path")};
       add_header Cache-Control "no-cache";
     }
 
-    location = /assistant/__config {
+    location = ${prefix}/__config {
       default_type application/json;
       add_header Cache-Control "no-store";
       return 200 ${nginxQuoted(configJson, "remote web ingress config")};
     }
 
-    location ^~ /assistant/assets/ {
+    location ^~ ${prefix}/ {
+      gzip on;
+      alias ${nginxQuoted(nginxDirPath(opts.webDistDir), "web dist path")};
+      try_files $uri $uri/ ${prefix}/__remote-index.html;
+      add_header Cache-Control "no-cache";
+    }`;
+}
+
+/** The web bundle's hashed chunks, cached immutably under its dist root. */
+function webAssetsLocations(webDistDir: string): string {
+  return `    location ^~ /assistant/assets/ {
       gzip on;
-      alias ${nginxQuoted(nginxDirPath(webAssetsDir), "web assets path")};
+      alias ${nginxQuoted(
+        nginxDirPath(join(webDistDir, "assets")),
+        "web assets path",
+      )};
       try_files $uri =404;
       add_header Cache-Control "public, max-age=31536000, immutable";
+    }`;
+}
+
+function buildRemoteWebIngressLocations(opts: {
+  gatewayPort: number;
+  webDistDir: string;
+  appDistDir?: string;
+  appIndexHtmlPath?: string;
+  indexHtmlPath?: string;
+  config: Record<string, unknown>;
+  version?: string;
+}): string {
+  const webDistDir = nginxDirPath(opts.webDistDir);
+  const indexHtmlPath =
+    opts.indexHtmlPath ?? join(opts.webDistDir, "index.html");
+
+  if (!opts.appDistDir) {
+    // Web mode: the web SPA IS the served surface, at /assistant/.
+    return `${DENYLIST_LOCATIONS}
+
+${assistantMetadataLocations({ ...opts.config, version: opts.version })}
+
+${gatewayProxyLocations(opts.gatewayPort)}
+
+${webAssetsLocations(opts.webDistDir)}
+
+${webSpaLocations({
+  prefix: "/assistant",
+  webDistDir: opts.webDistDir,
+  indexHtmlPath,
+  config: opts.config,
+})}
+
+    location = / {
+      return 302 /assistant/;
+    }
+
+    location / {
+      return 404;
+    }`;
+  }
+
+  // App mode: the app bundle is the outer shell (origin root, including the
+  // app's own /assistant/* host routes) and the web SPA is iframed from the
+  // distinct /web/assistant/ namespace, so neither surface can load the
+  // other recursively. The web bundle's asset URLs keep their baked
+  // /assistant/ base, so its hashed chunks and public files stay served
+  // under that prefix even though the document now mounts from /web/.
+  const appIndexHtmlPath =
+    opts.appIndexHtmlPath ?? join(opts.appDistDir, "index.html");
+  return `${denylistLocations()}
+
+${denylistLocations("/web")}
+
+${assistantMetadataLocations({
+  ...opts.config,
+  version: opts.version,
+  entryUrl: assistantEntryUrl(opts.appDistDir),
+})}
+
+${gatewayProxyLocations(opts.gatewayPort)}
+
+    location ^~ /web/v1/ {
+${gatewayProxyBlock(opts.gatewayPort, "/v1/")}
     }
 
+${webSpaLocations({
+  prefix: "/web/assistant",
+  webDistDir: opts.webDistDir,
+  indexHtmlPath,
+  config: opts.config,
+})}
+
+    location = /web {
+      return 302 /web/assistant/;
+    }
+
+    # The iframe namespace has no other routes: anything under /web that is
+    # not the assistant mount or its prefixed API path is a probe, not a page.
+    location ^~ /web/ {
+      return 404;
+    }
+
+    # The web bundle's hashed chunks and unhashed public files under its baked
+    # build base. Real files win; anything else falls through to the app
+    # shell, which owns the /assistant/* host routes.
+    location = /assistant {
+      rewrite ^ /__cadet-app-index.html last;
+    }
+
+    location = /assistant/ {
+      rewrite ^ /__cadet-app-index.html last;
+    }
+
+${webAssetsLocations(opts.webDistDir)}
+
     location ^~ /assistant/ {
       gzip on;
       alias ${nginxQuoted(webDistDir, "web dist path")};
-      try_files $uri $uri/ /assistant/__remote-index.html;
+      try_files $uri @cadet_app_shell;
       add_header Cache-Control "no-cache";
     }
 
+    # The app shell: its document is the config-injected standalone index, and
+    # every shell route (/, /account/*, /logout, and the /assistant/* host
+    # routes) resolves through the SPA fallback.
+    location = /__cadet-app-index.html {
+      internal;
+      gzip on;
+      alias ${nginxQuoted(appIndexHtmlPath, "app shell ingress index path")};
+      add_header Cache-Control "no-cache";
+    }
+
+    location @cadet_app_shell {
+      rewrite ^ /__cadet-app-index.html last;
+    }
+
     location = / {
-      return 302 /assistant/;
+      rewrite ^ /__cadet-app-index.html last;
+    }
+
+    location ^~ /assets/ {
+      gzip on;
+      alias ${nginxQuoted(
+        nginxDirPath(join(opts.appDistDir, "assets")),
+        "app assets path",
+      )};
+      try_files $uri =404;
+      add_header Cache-Control "public, max-age=31536000, immutable";
     }
 
     location / {
-      return 404;
+      gzip on;
+      alias ${nginxQuoted(nginxDirPath(opts.appDistDir), "app dist path")};
+      try_files $uri @cadet_app_shell;
+      add_header Cache-Control "no-cache";
     }`;
 }
 
@@ -574,7 +943,7 @@ export interface IngressState {
    */
   gatewayPort?: number;
   /**
-   * Fingerprint of the SPA config injected into the served index. Undefined
+   * Fingerprint of the injected SPA config and its source bundle. Undefined
    * for webhooks-only edges and for SPA records that predate the field; an
    * SPA edge without a recorded fingerprint is treated as drifted and
    * restarted so the served index provably carries the requested config.
@@ -661,6 +1030,19 @@ export function startIngressNginx(opts: {
       remoteWebIngress.indexHtmlPath,
       buildRemoteWebIndexHtml(rawIndexHtml, remoteWebIngress.config),
     );
+    if (remoteWebIngress.appDistDir) {
+      // The app shell gets its own injected document: same remote-web config
+      // (its readers ignore the web-only apiBaseUrl key), written beside the
+      // web one so the generated locations can alias it internally.
+      const rawAppIndexHtml = readFileSync(
+        join(remoteWebIngress.appDistDir, "index.html"),
+        "utf-8",
+      );
+      writeFileSync(
+        join(paths.dir, "app-index.html"),
+        buildRemoteWebIndexHtml(rawAppIndexHtml, remoteWebIngress.config),
+      );
+    }
   }
   writeFileSync(
     paths.confPath,
@@ -688,6 +1070,9 @@ export function startIngressNginx(opts: {
       ? {
           remoteWebConfigHash: remoteWebConfigFingerprint(
             remoteWebIngress.config,
+            remoteWebIngress.webDistDir,
+            remoteWebIngress.version,
+            remoteWebIngress.appDistDir,
           ),
         }
       : {}),
@@ -800,6 +1185,7 @@ export type StartRemoteWebIngressResult =
     }
   | { status: "nginx-missing" }
   | { status: "web-dist-missing" }
+  | { status: "app-dist-missing" }
   | { status: "unreachable"; listenPort: number; logPath: string }
   | { status: "port-conflict"; listenPort: number; logPath: string };
 
@@ -832,6 +1218,13 @@ export async function startRemoteWebIngress(opts: {
    * sensitive-route denylist (webhooks-only mode).
    */
   includeWebApp?: boolean;
+  /**
+   * Which client bundle is the outer shell (default "web"). "app" additionally
+   * serves the standalone app bundle as the outer account/client shell and
+   * hands the shell a /web/assistant/ iframe URL for the web UI; "web" keeps
+   * serving the web SPA directly from /assistant/.
+   */
+  shellMode?: "web" | "app";
   /**
    * Serving assistant's display name, stamped into the served remote-web
    * config (`__CADET_CONFIG__.assistantName`) so remote clients can label
@@ -857,8 +1250,9 @@ export async function startRemoteWebIngress(opts: {
     listenPort: number;
   }) => void;
 }): Promise<StartRemoteWebIngressResult> {
-  const listenPort = opts.listenPort ?? getNginxIngressPort();
+  let listenPort = opts.listenPort ?? getNginxIngressPort();
   const includeWebApp = opts.includeWebApp ?? true;
+  const shellMode = opts.shellMode ?? "web";
 
   const version = getNginxVersion();
   if (!version) {
@@ -868,18 +1262,53 @@ export async function startRemoteWebIngress(opts: {
   const running = isIngressRunning(opts.workspaceDir);
   const recorded = running ? readIngressState(opts.workspaceDir) : null;
   const recordedMode = recorded?.includeWebApp ?? true;
+  if (
+    recorded &&
+    opts.listenPort === undefined &&
+    process.env.CADET_NGINX_INGRESS_PORT === undefined
+  ) {
+    listenPort = recorded.listenPort;
+  }
   // The SPA config the served index must carry, computed up front so the
   // reuse decision and the actual spawn share one value and cannot drift.
   const spaOptions = includeWebApp
     ? {
-        hubUrl: cloudWebHubUrl(getCurrentEnvironment().name),
+        hubUrl: cloudAssistantHubUrl(getCurrentEnvironment().name),
         ...(opts.assistantName ? { assistantName: opts.assistantName } : {}),
         ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
       }
     : undefined;
-  const requestedConfigHash = spaOptions
-    ? remoteWebConfigFingerprint(remoteWebIngressConfig(spaOptions))
+  const webDistDir = includeWebApp ? findWebDistDir() : null;
+  if (includeWebApp && !webDistDir) {
+    return { status: "web-dist-missing" };
+  }
+  const appDistDir =
+    includeWebApp && shellMode === "app"
+      ? (findAppDistDir() ?? undefined)
+      : undefined;
+  if (includeWebApp && shellMode === "app" && !appDistDir) {
+    return { status: "app-dist-missing" };
+  }
+  const runtimeVersion = webDistDir
+    ? await fetchCurrentVersion(`http://127.0.0.1:${opts.gatewayPort}`)
+    : undefined;
+  const webVersion = webDistDir ? readWebReleaseVersion(webDistDir) : undefined;
+  const assistantVersion = runtimeVersion
+    ? stripVersionPrefix(runtimeVersion)
     : undefined;
+  const matchedVersion =
+    assistantVersion && webVersion === assistantVersion
+      ? assistantVersion
+      : undefined;
+  const requestedConfigHash =
+    spaOptions && webDistDir
+      ? remoteWebConfigFingerprint(
+          remoteWebIngressConfig(spaOptions),
+          webDistDir,
+          matchedVersion,
+          appDistDir,
+        )
+      : undefined;
   // Both sides are undefined in webhooks-only mode; an SPA record without a
   // fingerprint predates the field and counts as drifted (see IngressState).
   const configMatches = recorded?.remoteWebConfigHash === requestedConfigHash;
@@ -906,14 +1335,6 @@ export async function startRemoteWebIngress(opts: {
     return alreadyRunning();
   }
 
-  let webDistDir: string | null = null;
-  if (includeWebApp) {
-    webDistDir = findWebDistDir();
-    if (!webDistDir) {
-      return { status: "web-dist-missing" };
-    }
-  }
-
   // The running edge serves the other mode, targets a different gateway
   // port, or injects a stale SPA config; restart it with the requested
   // config. A false stop can mean the old edge exited on its own after the
@@ -926,13 +1347,37 @@ export async function startRemoteWebIngress(opts: {
     return alreadyRunning();
   }
 
+  // A foreign process squatting the default edge port (another assistant's
+  // edge, a stale dev server) must not kill the tunnel: the edge port is
+  // loopback-local and the public tunnel URL never carries it, so moving to
+  // the next free port is invisible to remote clients. Explicit pins
+  // (opts.listenPort / CADET_NGINX_INGRESS_PORT) keep their intent and still
+  // fail on a collision.
+  if (
+    opts.listenPort === undefined &&
+    process.env.CADET_NGINX_INGRESS_PORT === undefined
+  ) {
+    const discovered = await findAvailableIngressPort(listenPort);
+    if (discovered !== null && discovered !== listenPort) {
+      console.log(`Port ${listenPort} in use; using ${discovered} instead.`);
+      listenPort = discovered;
+    }
+  }
+
   opts.onStarting?.({ version, webDistDir, listenPort });
 
   const child = startIngressNginx({
     workspaceDir: opts.workspaceDir,
     gatewayPort: opts.gatewayPort,
     listenPort,
-    remoteWebIngress: webDistDir ? { webDistDir, ...spaOptions } : undefined,
+    remoteWebIngress: webDistDir
+      ? {
+          webDistDir,
+          ...spaOptions,
+          version: matchedVersion,
+          ...(appDistDir ? { appDistDir } : {}),
+        }
+      : undefined,
   });
   let exited = false;
   child.once("exit", () => {
@@ -1005,8 +1450,14 @@ function lockfileAssistantName(assistantId: string): string | undefined {
 }
 
 /** User-facing label for the edge mode, shared by every edge status line. */
-export function formatEdgeMode(includesWebApp: boolean): string {
-  return includesWebApp ? "remote web + webhooks" : "webhooks only";
+export function formatEdgeMode(
+  includesWebApp: boolean,
+  shellMode: "web" | "app" = "web",
+): string {
+  if (!includesWebApp) return "webhooks only";
+  return shellMode === "app"
+    ? "app shell + remote web + webhooks"
+    : "remote web + webhooks";
 }
 
 /**
@@ -1042,6 +1493,7 @@ export async function stopContainerTunnelEdge(
 function stampAppProcessEntry(
   workspaceDir: string,
   assistantId?: string,
+  port = getNginxIngressPort(),
 ): void {
   const pid = getIngressPid(workspaceDir);
   if (pid !== null) {
@@ -1049,6 +1501,7 @@ function stampAppProcessEntry(
       pid,
       startedAt: new Date().toISOString(),
       assistantId,
+      port,
     });
   }
 }
@@ -1059,6 +1512,8 @@ function stampAppProcessEntry(
   /** True when this call started the edge, false when a running one was reused. */
   started: boolean;
   includesWebApp: boolean;
+  /** The shell mode the edge serves (the persisted lockfile setting). */
+  shellMode: "web" | "app";
 }
 
 /**
@@ -1105,10 +1560,15 @@ export async function ensureTunnelEdge(opts: {
   const assistantName = opts.assistantId
     ? lockfileAssistantName(opts.assistantId)
     : undefined;
+  // The persisted lockfile setting owns the shell choice; every edge caller
+  // (tunnel, wake restore, upgrade restore) reads it through here so a mode
+  // flip only needs `cadet tunnel --shell` once.
+  const shellMode = readShellMode();
   const result = await startRemoteWebIngress({
     workspaceDir: opts.workspaceDir,
     gatewayPort: opts.gatewayPort,
     includeWebApp: true,
+    shellMode,
     ...(assistantName ? { assistantName } : {}),
     ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
     ...(opts.onStarting ? { onStarting: opts.onStarting } : {}),
@@ -1116,11 +1576,16 @@ export async function ensureTunnelEdge(opts: {
 
   switch (result.status) {
     case "started":
-      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
+      stampAppProcessEntry(
+        opts.workspaceDir,
+        opts.assistantId,
+        result.listenPort,
+      );
       return {
         port: result.listenPort,
         started: true,
         includesWebApp: true,
+        shellMode,
       };
     case "already-running": {
       // `already-running` also covers a drifted edge whose restart failed, so
@@ -1150,11 +1615,16 @@ export async function ensureTunnelEdge(opts: {
             stuckEdgeRecoveryHint(opts.workspaceDir),
         );
       }
-      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
+      stampAppProcessEntry(
+        opts.workspaceDir,
+        opts.assistantId,
+        result.listenPort,
+      );
       return {
         port: result.listenPort,
         started: false,
         includesWebApp: result.includeWebApp,
+        shellMode,
       };
     }
     case "nginx-missing":
@@ -1169,6 +1639,13 @@ export async function ensureTunnelEdge(opts: {
           "Build the SPA with `cd clients/web && VITE_CLOUD_MODE=false bun run build`, " +
           "or install @mycadet/web so its packaged dist directory is available.",
       );
+    case "app-dist-missing":
+      throw new Error(
+        "The app shell edge mode is selected but no " +
+          "built app bundle is available. Build it with `cd clients/app && bun run build`, " +
+          "or install @mycadet/app so its packaged standalone directory is available. " +
+          "Switch back to the web shell with `cadet tunnel --shell web`.",
+      );
     case "unreachable":
       throw new Error(
         `nginx edge did not become reachable on 127.0.0.1:${result.listenPort}. ` +