@openparachute/hub 0.7.7-rc.12 → 0.7.7-rc.13

package/src/api-settings-root-redirect.ts

@@ -1,19 +1,24 @@
 /**
- * `GET|PUT /api/settings/root-redirect` — operator-settable target for the
- * bare-`/` 302.
+ * `GET|PUT /api/settings/root-redirect` — operator-settable behavior for the
+ * hub's origin root: the `root_mode` (redirect vs. serve the app) and the
+ * bare-`/` 302 target.
  *
  * The hub's root (`/`) redirects to `/admin` by default. This endpoint lets an
  * operator point it at a surface instead (e.g. a custom-domain hub fronting a
- * team reading-room surface) without redeploying. The stored value resolves
- * tier-1 in `resolveRootRedirect` (hub-settings.ts):
+ * team reading-room surface), OR flip `root_mode` to `serve-app` so the hub
+ * serves the installed Parachute app AT the origin root (the hosted-door
+ * experience), all without redeploying. The stored values resolve tier-1 in
+ * `resolveRootRedirect` / `resolveRootMode` (hub-settings.ts):
  *
- *   1. hub_settings.root_redirect (this endpoint writes here)
- *   2. PARACHUTE_HUB_ROOT_REDIRECT env
- *   3. `/admin` default (unchanged behavior)
+ *   root_redirect:  hub_settings.root_redirect → PARACHUTE_HUB_ROOT_REDIRECT env → `/admin`
+ *   root_mode:      hub_settings.root_mode     → PARACHUTE_HUB_ROOT_MODE env     → `redirect`
  *
- * The endpoint surfaces both the stored value *and* the resolved value + source
- * so the SPA can render "current: /surface/x (from env)" while the input shows
- * the empty stored row — same separation rationale as `/api/settings/hub-origin`.
+ * The endpoint surfaces both the stored values *and* the resolved values +
+ * sources so the SPA can render "current: /surface/x (from env)" while the
+ * input shows the empty stored row — same separation rationale as
+ * `/api/settings/hub-origin`. PUT accepts `root_redirect` and/or `root_mode`
+ * (at least one); a body with only `root_redirect` (the pre-serve-app shape)
+ * works unchanged.
  *
  * OPEN-REDIRECT SAFETY is the highest-stakes part: the resolved value lands in a
  * `Location:` header, so an off-origin value would be a textbook open redirect.
@@ -29,10 +34,17 @@
 
 import type { Database } from "bun:sqlite";
 import {
+  ROOT_MODES,
+  type RootMode,
+  type RootModeSource,
   type RootRedirectSource,
+  getRootMode,
   getRootRedirect,
+  isRootMode,
   isSafeRedirectPath,
+  resolveRootModeDetailed,
   resolveRootRedirectDetailed,
+  setRootMode,
   setRootRedirect,
 } from "./hub-settings.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
@@ -68,11 +80,19 @@ interface GetResponseBody {
   resolved: string;
   /** Which precedence layer the resolved value came from. */
   source: RootRedirectSource;
+  /** Raw stored value from hub_settings.root_mode, or null. */
+  root_mode: RootMode | null;
+  /** Resolved root mode (precedence-aware): "redirect" (302) or "serve-app". */
+  resolved_mode: RootMode;
+  /** Which precedence layer the resolved mode came from. */
+  mode_source: RootModeSource;
 }
 
 interface PutResponseBody {
-  /** Echo of the now-stored value (null if cleared). */
+  /** Echo of the now-stored redirect (null if cleared / not part of this PUT). */
   root_redirect: string | null;
+  /** Echo of the now-stored mode (null if cleared / default). */
+  root_mode: RootMode | null;
 }
 
 /**
@@ -108,6 +128,30 @@ export function validateRootRedirect(value: unknown): ValidateOutcome {
   return { ok: true, normalized: value };
 }
 
+/** Validation outcome for `root_mode` — string (a valid mode) or null (clear). */
+type ValidateModeOutcome =
+  | { ok: true; normalized: RootMode | null }
+  | { ok: false; description: string };
+
+/**
+ * Validate the body's `root_mode` field. Accepts:
+ *   - `null` (or empty string) → clear the stored value, revert to env/default
+ *     (the `redirect` default).
+ *   - `"redirect"` | `"serve-app"` — a valid {@link RootMode}.
+ * Everything else → 400 with an operator-friendly description.
+ */
+export function validateRootMode(value: unknown): ValidateModeOutcome {
+  if (value === null) return { ok: true, normalized: null };
+  if (typeof value !== "string") {
+    return { ok: false, description: `root_mode must be a string or null (got ${typeof value})` };
+  }
+  if (value.length === 0) return { ok: true, normalized: null };
+  if (!isRootMode(value)) {
+    return { ok: false, description: `root_mode must be one of ${ROOT_MODES.join(", ")}` };
+  }
+  return { ok: true, normalized: value };
+}
+
 export async function handleApiSettingsRootRedirect(
   req: Request,
   deps: ApiSettingsRootRedirectDeps,
@@ -156,10 +200,14 @@ export async function handleApiSettingsRootRedirect(
 
   if (req.method === "GET") {
     const resolved = resolveRootRedirectDetailed(deps.db, { env: deps.env });
+    const resolvedMode = resolveRootModeDetailed(deps.db, { env: deps.env });
     const body: GetResponseBody = {
       root_redirect: getRootRedirect(deps.db),
       resolved: resolved.value,
       source: resolved.source,
+      root_mode: getRootMode(deps.db),
+      resolved_mode: resolvedMode.value,
+      mode_source: resolvedMode.source,
     };
     return new Response(JSON.stringify(body), {
       status: 200,
@@ -167,7 +215,12 @@ export async function handleApiSettingsRootRedirect(
     });
   }
 
-  // PUT — parse + validate body.
+  // PUT — parse + validate body. Either `root_redirect` OR `root_mode` (or
+  // both) may be present; at least one is required. Each is validated +
+  // applied independently, so an operator can flip just the mode, just the
+  // redirect target, or both in one call. Back-compat: a body with only
+  // `root_redirect` (the pre-serve-app shape the admin SPA / CLI already send)
+  // works unchanged.
   let parsed: unknown;
   try {
     parsed = await req.json();
@@ -177,17 +230,40 @@ export async function handleApiSettingsRootRedirect(
   if (typeof parsed !== "object" || parsed === null) {
     return jsonError(400, "invalid_request", "request body must be a JSON object");
   }
-  if (!("root_redirect" in parsed)) {
-    return jsonError(400, "invalid_request", "request body must include a `root_redirect` field");
+  const hasRedirect = "root_redirect" in parsed;
+  const hasMode = "root_mode" in parsed;
+  if (!hasRedirect && !hasMode) {
+    return jsonError(
+      400,
+      "invalid_request",
+      "request body must include a `root_redirect` and/or `root_mode` field",
+    );
+  }
+
+  // Validate BOTH before applying EITHER — a partial write (redirect stored,
+  // mode rejected) would leave the operator's config half-applied.
+  let redirectNormalized: string | null | undefined;
+  if (hasRedirect) {
+    const result = validateRootRedirect((parsed as { root_redirect: unknown }).root_redirect);
+    if (!result.ok) return jsonError(400, "invalid_root_redirect", result.description);
+    redirectNormalized = result.normalized;
   }
-  const result = validateRootRedirect((parsed as { root_redirect: unknown }).root_redirect);
-  if (!result.ok) {
-    return jsonError(400, "invalid_root_redirect", result.description);
+  let modeNormalized: RootMode | null | undefined;
+  if (hasMode) {
+    const result = validateRootMode((parsed as { root_mode: unknown }).root_mode);
+    if (!result.ok) return jsonError(400, "invalid_root_mode", result.description);
+    modeNormalized = result.normalized;
   }
 
-  setRootRedirect(deps.db, result.normalized);
+  if (redirectNormalized !== undefined) setRootRedirect(deps.db, redirectNormalized);
+  if (modeNormalized !== undefined) setRootMode(deps.db, modeNormalized);
 
-  const body: PutResponseBody = { root_redirect: result.normalized };
+  // Echo the now-current stored values (re-read so an untouched field reflects
+  // what's actually in the row, not `undefined`).
+  const body: PutResponseBody = {
+    root_redirect: getRootRedirect(deps.db),
+    root_mode: getRootMode(deps.db),
+  };
   return new Response(JSON.stringify(body), {
     status: 200,
     headers: { "content-type": "application/json" },

package/src/commands/hub.ts

@@ -34,8 +34,11 @@ import { CONFIG_DIR } from "../config.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import {
   DEFAULT_ROOT_REDIRECT,
+  ROOT_MODES,
+  isRootMode,
   isSafeRedirectPath,
   setHubOrigin,
+  setRootMode,
   setRootRedirect,
 } from "../hub-settings.ts";
 import { type CommandResult, type Runner, defaultRunner } from "../tailscale/run.ts";
@@ -427,6 +430,84 @@ export async function hubSetRootRedirect(
   return 0;
 }
 
+/**
+ * `parachute hub set-root-mode <redirect|serve-app>` — persist how the hub
+ * answers its origin root into `hub_settings.root_mode` (tier-1 in
+ * `resolveRootMode`).
+ *
+ *   - `redirect` (the default) — the bare `/` 302s to `root_redirect` (default
+ *     `/admin`). This is what `--clear` reverts to.
+ *   - `serve-app` — the hub SERVES the installed Parachute app AT the origin
+ *     root (the hosted-door experience), no redirect hop. Requires the app to
+ *     be installed (`parachute install app`); if it isn't, `/` falls back to
+ *     the redirect until it is.
+ *
+ * Takes effect on the next request, no restart. Returns 0 on success, 1 on a
+ * usage / validation / DB-write failure. Mirrors `hubSetRootRedirect`'s shape.
+ */
+export async function hubSetRootMode(
+  args: readonly string[],
+  deps: HubCommandDeps = {},
+): Promise<number> {
+  const configDir = deps.configDir ?? CONFIG_DIR;
+  const log = deps.log ?? ((line) => console.log(line));
+  const err = (line: string) => console.error(line);
+  const openDb = deps.openDb ?? ((dir: string) => openHubDb(hubDbPath(dir)));
+
+  const clear = args.includes("--clear");
+  const positional = args.filter((a) => !a.startsWith("-"));
+
+  if (clear) {
+    if (positional.length > 0) {
+      err("parachute hub set-root-mode: --clear takes no mode argument");
+      return 1;
+    }
+    const db = openDb(configDir);
+    try {
+      setRootMode(db, null);
+    } finally {
+      db.close();
+    }
+    log("✓ Cleared the root mode — `/` reverts to the redirect default.");
+    return 0;
+  }
+
+  const raw = positional[0];
+  if (raw === undefined) {
+    err(`usage: parachute hub set-root-mode <${ROOT_MODES.join("|")}>   (or --clear)`);
+    err("example: parachute hub set-root-mode serve-app");
+    return 1;
+  }
+  if (positional.length > 1) {
+    err(`parachute hub set-root-mode: unexpected argument "${positional[1]}"`);
+    err(`usage: parachute hub set-root-mode <${ROOT_MODES.join("|")}>   (or --clear)`);
+    return 1;
+  }
+  if (!isRootMode(raw)) {
+    err(`parachute hub set-root-mode: "${raw}" is not a valid mode`);
+    err(`  Expected one of: ${ROOT_MODES.join(", ")}. Example: serve-app`);
+    return 1;
+  }
+
+  const db = openDb(configDir);
+  try {
+    setRootMode(db, raw);
+  } finally {
+    db.close();
+  }
+
+  if (raw === "serve-app") {
+    log("✓ Bare `/` now serves the Parachute app (root_mode=serve-app).");
+    log("  Requires the app to be installed (`parachute install app`); otherwise `/`");
+    log("  falls back to the redirect. Takes effect on the next request, no restart.");
+    log("  Revert with: parachute hub set-root-mode redirect  (or --clear)");
+  } else {
+    log("✓ Bare `/` now uses redirect mode (the default).");
+    log("  Stored in hub_settings.root_mode — takes effect on the next request.");
+  }
+  return 0;
+}
+
 /**
  * `parachute hub <subcommand>` dispatcher. Mirrors `auth`'s shape (a thin
  * router over subcommand handlers, each catching its own errors).
@@ -457,6 +538,16 @@ export async function hub(args: readonly string[], deps: HubCommandDeps = {}): P
       return 1;
     }
   }
+  if (sub === "set-root-mode") {
+    try {
+      return await hubSetRootMode(args.slice(1), deps);
+    } catch (err) {
+      console.error(
+        `parachute hub set-root-mode: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return 1;
+    }
+  }
   console.error(`parachute hub: unknown subcommand "${sub}"`);
   console.error("");
   console.error(hubHelp());
@@ -469,6 +560,7 @@ export function hubHelp(): string {
 Usage:
   parachute hub set-origin <url> [--no-caddy] [--no-restart]
   parachute hub set-root-redirect <path> | --clear
+  parachute hub set-root-mode <redirect|serve-app> | --clear
 
 Subcommands:
   set-origin <url>    Persist the canonical public origin (OAuth issuer) to the
@@ -500,11 +592,23 @@ Subcommands:
                       \`/\\\`, scheme, or whitespace). Pass --clear to revert to the
                       env / /admin default. (Env equivalent: PARACHUTE_HUB_ROOT_REDIRECT.)
 
+  set-root-mode <mode>
+                      How the hub answers its origin root: \`redirect\` (default —
+                      the bare \`/\` 302s to the set-root-redirect target) or
+                      \`serve-app\` (the hub SERVES the installed Parachute app AT
+                      \`/\`, the hosted-door experience, no redirect hop). serve-app
+                      needs the app installed (\`parachute install app\`); until then
+                      \`/\` falls back to the redirect. Stored in hub_settings.root_mode;
+                      takes effect on the next request, no restart. Pass --clear to
+                      revert to the redirect default. (Env equivalent: PARACHUTE_HUB_ROOT_MODE.)
+
 Examples:
   parachute hub set-origin https://box.sslip.io
   parachute hub set-origin https://parachute.example.com
   parachute hub set-origin https://parachute.example.com --no-caddy
   parachute hub set-root-redirect /surface/reading-room
   parachute hub set-root-redirect --clear
+  parachute hub set-root-mode serve-app
+  parachute hub set-root-mode --clear
 `;
 }

package/src/commands/install.ts

@@ -17,7 +17,11 @@ import {
   readHubPort,
 } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { resolveRootRedirectDetailed, setRootRedirect } from "../hub-settings.ts";
+import {
+  resolveRootModeDetailed,
+  resolveRootRedirectDetailed,
+  setRootMode,
+} from "../hub-settings.ts";
 import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
 import {
   type ModuleManifest,
@@ -1398,30 +1402,37 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     }
   }
 
-  // App-only: default the hub's bare `/` redirect to the app's front door on
-  // first install (hub-parity P5, 2026-07-11) — SET-IF-UNSET ONLY, never
-  // clobbering an operator's existing choice (`parachute hub
-  // set-root-redirect` or the admin SPA PUT both still win on any later run,
-  // and either can change it back). "Unset" means the resolved redirect is
-  // still the built-in `/admin` DEFAULT — i.e. NEITHER the DB row NOR the
-  // `PARACHUTE_HUB_ROOT_REDIRECT` env var (container deploys pin their landing
-  // page there) has set it. Gating on `getRootRedirect(db) === null` would
-  // miss the env tier and silently override an env-configured operator, since
-  // the DB row we'd write wins over env on read (`resolveRootRedirectDetailed`
-  // is DB-first). Gated on the same production-vs-test discriminant the
-  // guidance probe below uses: a test driving install against a tempdir
-  // manifestPath never opens the real `~/.parachute/hub.db` unless it opts in
-  // via `opts.rootRedirectDb`.
+  // App-only: default the hub's origin root to SERVE the app on first install
+  // (the self-hosted mirror of the hosted door — hit the box's URL, land in the
+  // app, no redirect hop). SET-IF-UNSET ONLY, never clobbering an operator's
+  // existing choice. We only flip `root_mode` to `serve-app` when the hub's
+  // root behavior is entirely PRISTINE DEFAULT — i.e. the resolved mode is still
+  // `redirect` (no `root_mode` DB row, no `PARACHUTE_HUB_ROOT_MODE` env) AND the
+  // resolved redirect is still the built-in `/admin` (no `root_redirect` DB row,
+  // no `PARACHUTE_HUB_ROOT_REDIRECT` env). If the operator has set EITHER (a
+  // custom landing surface, a pinned env, or an explicit mode), we leave their
+  // choice untouched. This also means a hub that ran the PRIOR app-install code
+  // (which wrote `root_redirect = /app/`) is NOT flipped — its redirect is no
+  // longer default, so it keeps 302-ing to `/app/`. Later runs of
+  // `parachute hub set-root-mode` / `set-root-redirect` (or the admin SPA PUT)
+  // still win over this and can change it back. Gated on the same
+  // production-vs-test discriminant the guidance probe below uses: a test
+  // driving install against a tempdir manifestPath never opens the real
+  // `~/.parachute/hub.db` unless it opts in via `opts.rootRedirectDb`.
   if (short === "app") {
     const dbProbeAllowed =
       opts.rootRedirectDb !== undefined || manifestPath === SERVICES_MANIFEST_PATH;
     if (dbProbeAllowed) {
       const db = opts.rootRedirectDb ?? openHubDb(hubDbPath(configDir));
       try {
-        if (resolveRootRedirectDetailed(db).source === "default") {
-          setRootRedirect(db, "/app/");
-          log("✓ The hub's front page (`/`) now opens the app at /app/.");
-          log("  Change it any time: `parachute hub set-root-redirect <path>` or the admin SPA.");
+        const modePristine = resolveRootModeDetailed(db).source === "default";
+        const redirectPristine = resolveRootRedirectDetailed(db).source === "default";
+        if (modePristine && redirectPristine) {
+          setRootMode(db, "serve-app");
+          log("✓ The hub's front page (`/`) now serves the Parachute app.");
+          log(
+            "  Change it any time: `parachute hub set-root-mode redirect` (or set-root-redirect) or the admin SPA.",
+          );
         }
       } finally {
         if (!opts.rootRedirectDb) db.close();

package/src/hub-server.ts

@@ -38,7 +38,15 @@
  *                                                installs (surface-notes-alias.ts)
  *
  *   # Discovery + well-known.
- *   /, /hub.html                               → hub.html (the discovery page)
+ *   /                                          → root_mode-dependent: `redirect`
+ *                                                (default) 302s to root_redirect
+ *                                                (default /admin); `serve-app`
+ *                                                serves the installed app's dist
+ *                                                index.html AT `/` (no chrome).
+ *                                                Fresh-hub wizard funnel + pre-
+ *                                                admin 503 still preempt it.
+ *   /hub.html                                  → hub.html (the discovery page;
+ *                                                unaffected by root_mode)
  *   /.well-known/parachute.json                → built dynamically from services.json
  *   /.well-known/parachute-revocation.json     → revoked-jti list (hub#212 Phase 1)
  *   /.well-known/jwks.json                     → JWKS from hub.db
@@ -171,7 +179,13 @@
  *   # Generic services.json-driven proxy (non-vault modules: notes, scribe, agent).
  *   /<service-mount>/*                         → proxy via services.json longest-prefix
  *
- *   anything else                              → 404
+ *   # serve-app tail (only when root_mode = serve-app): an unclaimed GET is
+ *   # handed to the app's root-based dist — an existing bundle file (/assets/*,
+ *   # /icon.svg, /manifest.webmanifest, /sw.js) serves that file; an HTML deep
+ *   # link gets the SPA shell. Inert in redirect mode (the 404 below is
+ *   # byte-identical to before). See root-serve.ts.
+ *   anything else                              → 404 (or app asset / SPA shell
+ *                                                in serve-app mode)
  *
  * Invoked as:
  *   bun <this-file> --port <n> --well-known-dir <path> [--db <path>] [--issuer <url>]
@@ -297,7 +311,7 @@ import {
   startDbPathLivenessTimer,
 } from "./hub-db-liveness.ts";
 import { hubDbPath, openHubDb } from "./hub-db.ts";
-import { getHubOrigin, resolveRootRedirect } from "./hub-settings.ts";
+import { getHubOrigin, resolveRootMode, resolveRootRedirect } from "./hub-settings.ts";
 import { type RenderHubOpts, renderHub } from "./hub.ts";
 import { pemToJwk } from "./jwks.ts";
 import {
@@ -321,6 +335,7 @@ import { clearPid, writePid } from "./process-state.ts";
 import { toResponse as proxyErrorToResponse, renderProxyError } from "./proxy-error-ui.ts";
 import { classifyUpstream } from "./proxy-state.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
+import { makeAppDistResolver, serveAppAtRoot } from "./root-serve.ts";
 import {
   FIRST_PARTY_FALLBACKS,
   KNOWN_MODULES,
@@ -1420,6 +1435,15 @@ export interface HubFetchDeps {
    * tracker between fetch fn and bridge handlers is impossible.
    */
   wsConnectionTracker?: WsConnectionTracker;
+  /**
+   * Resolve the installed app's `dist/` directory for `root_mode = serve-app`.
+   * Returns the dist dir, or `null` when the app isn't installed (→ serve-app
+   * falls back to the redirect). Production defaults to a memoizing resolver
+   * over the real `@openparachute/parachute-app` package (`makeAppDistResolver`);
+   * tests inject a fixture dir or a `() => null` to drive the not-installed
+   * fallback without a real global install.
+   */
+  resolveAppDist?: () => string | null;
 }
 
 /**
@@ -2119,6 +2143,13 @@ export function hubFetch(
   const manifestPath = deps?.manifestPath ?? SERVICES_MANIFEST_PATH;
   const gitRoot = deps?.gitRoot ?? join(CONFIG_DIR, "hub", "git");
   const spaDistDir = deps?.spaDistDir ?? defaultSpaDistDir();
+  // `root_mode = serve-app` resolver (memoizing over the real app package by
+  // default; tests inject their own). Instantiated once per hubFetch so the
+  // success-memoization spans the serve process's lifetime.
+  const resolveAppDist = deps?.resolveAppDist ?? makeAppDistResolver();
+  // One-shot log guard: when serve-app is set but the app can't be resolved we
+  // fall back to the redirect and say so ONCE, not on every `/` hit.
+  let warnedAppServeFallback = false;
   const loopbackPort = deps?.loopbackPort;
   const loadExposeHubOrigin =
     deps?.loadExposeHubOrigin ??
@@ -2636,6 +2667,24 @@ export function hubFetch(
       // page (used by the static `parachute expose --set-path=/` disk file and
       // any bookmark to the explicit `.html`). Only the bare `/` redirects.
       if (pathname === "/") {
+        // `root_mode = serve-app`: serve the installed app's shell AT the origin
+        // root (no redirect hop), the self-hosted mirror of the hosted door.
+        // GET only — a non-GET `/` keeps its 302 below. Runs AFTER the fresh-hub
+        // wizard funnel + pre-admin 503 above (a not-yet-set-up hub still lands
+        // on setup, never a half-working app shell). Falls back to the redirect
+        // when the app isn't installed (dist unresolvable), with a one-time log.
+        if (req.method === "GET" && resolveRootMode(getDb ? getDb() : null) === "serve-app") {
+          const dist = resolveAppDist();
+          if (dist) {
+            const served = serveAppAtRoot(dist, req, "/");
+            if (served) return served;
+          } else if (!warnedAppServeFallback) {
+            warnedAppServeFallback = true;
+            console.warn(
+              "[hub] root_mode=serve-app but the Parachute app is not installed (its dist could not be resolved) — falling back to the root redirect. Install it with `parachute install app`.",
+            );
+          }
+        }
         return new Response(null, {
           status: 302,
           headers: { location: resolveRootRedirect(getDb ? getDb() : null) },
@@ -4210,6 +4259,25 @@ export function hubFetch(
         );
       }
 
+      // serve-app tail (`root_mode = serve-app`). This is exactly the "would
+      // have been the branded 404" point: every hub-owned prefix above (/,
+      // /admin, /oauth, /.well-known, /vault, /git, /api, service mounts) has
+      // already had its turn, so anything here is genuinely unclaimed. Hand an
+      // unclaimed GET to the app's root-based dist — an existing bundle file
+      // (/assets/*, /icon.svg, /manifest.webmanifest, /sw.js) serves that file;
+      // an HTML deep link the app routes client-side gets the SPA shell.
+      // `serveAppAtRoot` returns null (→ branded 404 below) for a non-GET, a
+      // non-HTML unclaimed request, or a reserved /api|/oauth|/.well-known
+      // prefix. NO chrome injection — the app owns its whole page. In redirect
+      // mode this branch is inert and the tail stays byte-identical to before.
+      if (req.method === "GET" && resolveRootMode(getDb ? getDb() : null) === "serve-app") {
+        const dist = resolveAppDist();
+        if (dist) {
+          const served = serveAppAtRoot(dist, req, pathname);
+          if (served) return served;
+        }
+      }
+
       // Branded fall-through 404 (closes hub#392) — the operator who mistyped
       // a URL sees a clear "not found" page with a path back home, not the
       // browser's default empty-body chrome. Only HTML clients get the