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

package/src/lib/nginx-ingress.ts

@@ -17,6 +17,8 @@ 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 {
@@ -28,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
@@ -93,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;
@@ -107,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 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.
  */
-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; }`;
+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. */
@@ -150,17 +190,18 @@ 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
@@ -208,17 +249,19 @@ 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 injected SPA config, its source bundle, and
- * 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>,
   webDistDir: string,
+  version?: string,
+  appDistDir?: string,
 ): string {
   return createHash("sha256")
     .update(
@@ -226,6 +269,20 @@ function remoteWebConfigFingerprint(
         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"),
       }),
     )
@@ -345,9 +402,102 @@ export async function findAvailableIngressPort(
   return null;
 }
 
-/**
- * Build the nginx config that forwards tunnel web traffic to the gateway.
- */
+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;
@@ -363,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}
 
@@ -417,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;
@@ -452,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}
     }
 
@@ -481,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
@@ -500,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(webAssetsDir), "web assets path")};
+      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(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";
     }`;
 }
 
@@ -728,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,
@@ -756,6 +1071,8 @@ export function startIngressNginx(opts: {
           remoteWebConfigHash: remoteWebConfigFingerprint(
             remoteWebIngress.config,
             remoteWebIngress.webDistDir,
+            remoteWebIngress.version,
+            remoteWebIngress.appDistDir,
           ),
         }
       : {}),
@@ -868,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 };
 
@@ -900,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
@@ -927,6 +1252,7 @@ export async function startRemoteWebIngress(opts: {
 }): Promise<StartRemoteWebIngressResult> {
   let listenPort = opts.listenPort ?? getNginxIngressPort();
   const includeWebApp = opts.includeWebApp ?? true;
+  const shellMode = opts.shellMode ?? "web";
 
   const version = getNginxVersion();
   if (!version) {
@@ -947,7 +1273,7 @@ export async function startRemoteWebIngress(opts: {
   // 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 } : {}),
       }
@@ -956,11 +1282,31 @@ export async function startRemoteWebIngress(opts: {
   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
@@ -1024,7 +1370,14 @@ export async function startRemoteWebIngress(opts: {
     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", () => {
@@ -1097,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";
 }
 
 /**
@@ -1153,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";
 }
 
 /**
@@ -1199,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 } : {}),
@@ -1219,6 +1585,7 @@ export async function ensureTunnelEdge(opts: {
         port: result.listenPort,
         started: true,
         includesWebApp: true,
+        shellMode,
       };
     case "already-running": {
       // `already-running` also covers a drifted edge whose restart failed, so
@@ -1257,6 +1624,7 @@ export async function ensureTunnelEdge(opts: {
         port: result.listenPort,
         started: false,
         includesWebApp: result.includeWebApp,
+        shellMode,
       };
     }
     case "nginx-missing":
@@ -1271,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}. ` +