@openparachute/hub 0.7.7-rc.8 → 0.7.7

package/src/commands/wizard-transcription.ts

@@ -72,6 +72,14 @@ export interface TranscriptionStepOpts {
 
 /** Default readline prompt (matches wizard.ts's defaultPrompt). */
 async function defaultPrompt(question: string): Promise<string> {
+  // Non-TTY guard (headless-hardening): unlike wizard.ts's required-step
+  // prompts (which throw), the transcription step is optional and must NEVER
+  // block setup. On a closed / non-interactive stdin, return the empty answer
+  // — which the callers already treat as a benign default (a blank cloud API
+  // key means "set it later"; a blank local-install confirm takes the [Y]
+  // default). `resolveChoice` short-circuits to "none" before ever reaching
+  // here without a flag; this covers the flag-supplied-mode downstream prompts.
+  if (!process.stdin.isTTY) return "";
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
     return await rl.question(question);
@@ -139,6 +147,22 @@ async function resolveChoice(
   log: (l: string) => void,
 ): Promise<ResolvedChoice> {
   if (opts.transcribeMode !== undefined) return opts.transcribeMode;
+  // Non-TTY guard (headless-hardening): with no `--transcribe-mode` flag AND a
+  // closed / non-interactive stdin (cloud-init, ssh heredoc, the e2e
+  // container), the real `defaultPrompt`'s `prompt("Pick [1]:")` would busy-hang
+  // forever on Bun's `readline/promises` question() — the exact wedge that
+  // timed out the Tier-1 e2e. Transcription is optional / opt-in and documented
+  // as NEVER blocking setup, so we DEFAULT to "none" (not throw — unlike the
+  // required account / vault / expose prompts in wizard.ts) with an honest log
+  // line. Guarded on `opts.prompt === undefined` so an injected prompt seam (a
+  // scripted test queue, or a caller supplying its own reader) is still honored
+  // — the wedge only exists for the real readline-backed default prompt.
+  if (opts.prompt === undefined && !process.stdin.isTTY) {
+    log("");
+    log("  stdin is not interactive — defaulting transcription to none.");
+    log("  Turn it on later with `parachute install scribe` (or re-run with --transcribe-mode).");
+    return "none";
+  }
   log("");
   log("  1) None — skip transcription (default)");
   log("  2) Local — run the engine on this box (no API key, needs ~2 GB RAM)");

package/src/commands/wizard.ts

@@ -156,8 +156,24 @@ interface FetchSetupResult {
 /**
  * Default readline prompt. Lives at module scope so tests can inject a
  * deterministic alternative through `opts.prompt`.
+ *
+ * Non-TTY guard (headless-hardening): Bun's `readline/promises` `question()`
+ * NEVER settles when stdin is closed / not a terminal (cloud-init, `ssh
+ * <host> 'parachute setup-wizard …'`, the e2e container's `run.sh`-exec'd
+ * stages.sh) — it busy-waits forever, wedging the wizard until the outer job
+ * timeout kills it. So when stdin is not interactive we FAIL FAST with an
+ * actionable message naming the flag that would have answered the prompt,
+ * rather than blocking on a prompt no one can ever answer. Account / vault /
+ * expose are required steps, so a missing answer here is fatal (the
+ * transcription step, being optional, defaults to "none" instead — see
+ * wizard-transcription.ts).
  */
 async function defaultPrompt(question: string): Promise<string> {
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      `stdin is not interactive, so the wizard cannot prompt for: ${question.trim()}\nRe-run non-interactively by passing the corresponding flag (e.g. --account-username / --account-password / --vault-mode / --vault-name / --expose-mode / --transcribe-mode), or run in a real terminal.`,
+    );
+  }
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
     return await rl.question(question);
@@ -224,6 +240,14 @@ async function setupFetch(
     // Don't auto-follow — the wizard returns 303 to /admin/setup, and
     // we want to inspect the Location header rather than chase it.
     redirect: "manual",
+    // Per-request 30s ceiling so a wedged hub call TRIPS instead of
+    // suspending forever. `pollOperation` (below) bounds the whole op with
+    // POLL_TIMEOUT_MS, but that deadline is only checked BETWEEN fetches — a
+    // single fetch that never resolves would defeat it. AbortSignal.timeout
+    // makes each individual call fail-fast; a real hub responds in well under
+    // 30s. Test-injected fetch stubs ignore the signal, so this is inert in
+    // unit tests.
+    signal: AbortSignal.timeout(30_000),
   });
   const bodyText = await res.text();
   // Collect Set-Cookie. Try `getAll` first (Bun + node18+ supported it
@@ -783,7 +807,16 @@ export async function runCliWizard(opts: RunCliWizardOpts): Promise<number> {
     await walkTranscriptionStep({
       configDir: opts.configDir,
       log,
-      prompt,
+      // Only forward a REAL injected prompt seam — NOT the resolved
+      // `prompt` (which is the throwing `defaultPrompt` when the caller
+      // supplied none). Passing the default here would defeat
+      // `resolveChoice`'s `opts.prompt === undefined` non-TTY guard: on a
+      // headless box with no `--transcribe-mode`, the transcription step
+      // would call the throwing default mid-wizard instead of defaulting to
+      // `none`. With the seam forwarded only when present, headless runs hit
+      // the guard (default none) and interactive/test runs still get their
+      // reader.
+      ...(opts.prompt !== undefined ? { prompt: opts.prompt } : {}),
       ...(opts.transcribeMode !== undefined ? { transcribeMode: opts.transcribeMode } : {}),
       ...(opts.transcribeApiKey !== undefined ? { transcribeApiKey: opts.transcribeApiKey } : {}),
       ...(opts.transcribeRunCommand !== undefined ? { runCommand: opts.transcribeRunCommand } : {}),

package/src/help.ts

@@ -362,11 +362,11 @@ Exit codes:
 
 Example:
   $ parachute status
-  SERVICE          PORT  VERSION  STATE   PID    UPTIME  LATENCY  SOURCE
-  parachute-vault  1940  0.2.4    active  12345  2h 13m  2ms      bun-linked → parachute-vault @ 8aa167b
+  SERVICE            PORT  VERSION  STATE   PID    UPTIME  LATENCY  SOURCE
+  parachute-vault    1940  0.2.4    active  12345  2h 13m  2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
-  parachute-app    1946  0.2.0    active  12346  2h 12m  3ms      npm (0.2.0-rc.4)
-    → http://127.0.0.1:1946/surface/notes
+  parachute-surface  1946  0.2.0    active  12346  2h 12m  3ms      npm (0.2.0-rc.4)
+    → http://127.0.0.1:1946/surface
 `;
 }
 
@@ -551,8 +551,8 @@ Examples:
 Module start commands (run by the supervisor under \`serve\`):
   vault     parachute-vault serve
   scribe    parachute-scribe serve
-  app       parachute-app serve
-  agent     parachute-agent
+  surface   parachute-surface serve
+  app       bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]> --package @openparachute/parachute-app
   notes     bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]>   # back-compat: legacy notes-daemon
 `;
 }

package/src/hub-server.ts

@@ -24,12 +24,29 @@
  *   /admin/login, /admin/logout                → 301 → /login, /logout
  *
  *   # Notes-as-app migration Phase 2 (parachute-app design doc §16).
+ *   # `/surface/notes` = the legacy notes-ui mount (existing installs);
+ *   # `/surface/parachute` = the app's surface mount post-W2-12 rename.
  *   /notes, /notes/, /notes/*                  → 301 → /surface/notes[/...]
  *                                                (opt-out via
  *                                                 hub_settings.notes_redirect_disabled)
+ *   /surface/notes[/...]                       → 301 → /surface/parachute[/...]
+ *                                                CONDITIONAL (W2-12, dispatched just
+ *                                                before the generic services proxy):
+ *                                                only when uis{} mounts show
+ *                                                /surface/notes gone + /surface/parachute
+ *                                                present — inert on existing notes-ui
+ *                                                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
@@ -59,8 +76,6 @@
  *   /account/vaults/<name>/caps   (GET/PUT)    → read / set the storage cap
  *   /admin/host-admin-token       (GET)        → SPA bearer mint (cookie-gated)
  *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
- *   /admin/agent-token            (GET)        → agent UI bearer mint (cookie-gated)
- *   /admin/channel-token          (GET)        → 301 → /admin/agent-token (legacy; channel→agent rename 2026-06-17)
  *   /admin/module-token/<short>   (GET)        → generic module config-UI bearer mint <short>:admin (cookie-gated)
  *   /api/connections/catalog      (GET)        → events/actions across installed modules (cookie-gated)
  *   /admin/connections            (POST/GET)   → connection provision/list (cookie-gated; POST CSRF-belted)
@@ -164,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>]
@@ -208,7 +229,7 @@ import {
   handleAgentGrants,
   handleOAuthGrantCallback,
 } from "./admin-agent-grants.ts";
-import { handleAgentToken } from "./admin-agent-token.ts";
+
 import { adminAuthErrorResponse } from "./admin-auth.ts";
 import { handleApproveClient, handleDeleteClient, handleGetClient } from "./admin-clients.ts";
 import {
@@ -290,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 {
@@ -314,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,
@@ -333,6 +355,7 @@ import {
 } from "./setup-wizard.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
 import type { Supervisor } from "./supervisor.ts";
+import { isSurfaceNotesPath, maybeRedirectSurfaceNotes } from "./surface-notes-alias.ts";
 import { handleTwoFactorGet, handleTwoFactorPost } from "./two-factor-handlers.ts";
 import { getUserById, userCount } from "./users.ts";
 import { sanitizePublicOrigin } from "./vault-hub-origin-env.ts";
@@ -1412,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;
 }
 
 /**
@@ -2111,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 ??
@@ -2350,27 +2389,6 @@ export function hubFetch(
         }
       }
 
-      // `/channel/*` 301-redirects to `/agent/*` — back-compat for the
-      // 2026-06-17 channel→agent module rename. Operator bookmarks, an
-      // un-upgraded chat/config UI's deep links, and any externally-shared
-      // `/channel/mcp/<name>` URL keep resolving for one release cycle while
-      // the module's canonical mount moves to `/agent`. Method-agnostic, same
-      // shape as the `/notes/*` redirect above (the agent's read-write surface
-      // is its own daemon API, not the hub mount, so a re-issued GET is fine).
-      // Matches `/channel` exactly and any `/channel/...` subpath, but NOT a
-      // longer-prefix module like a hypothetical `/channelthing` — the guard is
-      // exact-or-slash-delimited. Query string is preserved. (The generic
-      // services-proxy fallthrough below would otherwise 404 a `/channel/*`
-      // request once the module self-registers under `/agent`.)
-      if (pathname === "/channel" || pathname.startsWith("/channel/")) {
-        const dest = new URL(req.url);
-        dest.pathname = `/agent${pathname.slice("/channel".length)}`;
-        return new Response("", {
-          status: 301,
-          headers: { location: dest.pathname + dest.search },
-        });
-      }
-
       // CORS preflight for the public OAuth + discovery surface. Browsers
       // issue OPTIONS before any non-simple cross-origin request — third-party
       // SPAs hitting `/oauth/register` (RFC 7591 DCR), `/oauth/token`,
@@ -2649,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) },
@@ -3063,31 +3099,13 @@ export function hubFetch(
         });
       }
 
-      // Back-compat: the agent module's admin-token mint moved from
-      // `/admin/channel-token` to `/admin/agent-token` in the 2026-06-17
-      // channel→agent rename. 301-redirect the old path so operator bookmarks
-      // + any un-upgraded UI fallback keep working for one release cycle.
-      if (pathname === "/admin/channel-token") {
-        const dest = new URL(req.url);
-        dest.pathname = "/admin/agent-token";
-        return Response.redirect(dest.toString(), 301);
-      }
-
-      if (pathname === "/admin/agent-token") {
-        if (!getDb) return dbNotConfigured();
-        return handleAgentToken(req, {
-          db: getDb(),
-          issuer: oauthDeps(req).issuer,
-        });
-      }
-
       // Generic per-module config-UI bearer mint (2026-06-09 modular-UI
       // architecture, P3). `<short>:admin` for any single-audience module —
       // the admin scope each module-owned config UI needs to call its own
-      // endpoints. Cookie-gated to the first-admin operator, exactly like
-      // /admin/agent-token + /admin/vault-admin-token. Gated on
-      // self-registration (services.json row + readable module.json) with the
-      // bootstrap registries as a fallback (boundary C5) — a genuinely
+      // endpoints. Cookie-gated to the first-admin operator, matching the
+      // host/vault admin-token endpoints. Gated on self-registration
+      // (services.json row + readable module.json) with the bootstrap
+      // registries as a fallback (boundary C5) — a genuinely
       // third-party module mints here with zero hub code changes. Vault is
       // per-instance and routed to /admin/vault-admin-token/<name> instead.
       if (pathname.startsWith("/admin/module-token/")) {
@@ -3105,9 +3123,7 @@ export function hubFetch(
 
       // Note: the legacy `/admin/channels` bespoke vault-channel orchestration
       // endpoint (pre-Connections, hub#624 era) was retired in boundary D1 —
-      // superseded by the general engine below. The agent module's own admin
-      // page (renamed from channel 2026-06-17) drives `/admin/connections` +
-      // `/admin/agent-token`.
+      // superseded by the general engine below.
 
       // Connections — the GENERAL module event→action engine (2026-06-09
       // modular-UI architecture, P5). `/api/connections/catalog` (GET) returns
@@ -3410,7 +3426,7 @@ export function hubFetch(
       // the 2026-06-09 modular-UI architecture P3. Config is module-owned +
       // hub-framed now: the Modules page "Configure" action opens the module's
       // OWN config UI (`configUiUrl`), which mints its admin Bearer from the
-      // cookie-gated `/admin/module-token/<short>` (or `/admin/agent-token`).
+      // cookie-gated `/admin/module-token/<short>`.
 
       // Per-module action endpoints: /api/modules/:short/{install,restart,upgrade,uninstall}.
       if (pathname.startsWith("/api/modules/")) {
@@ -4173,6 +4189,28 @@ export function hubFetch(
       // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,
       // `/api/*` are excluded by ordering, not by an explicit denylist (#182).
       //
+      // W2-12 — conditional `/surface/notes/*` → `/surface/parachute/*`
+      // alias, the "never 404 an old bookmark after an in-place upgrade"
+      // safety net for the app's notes→parachute surface-identity rename.
+      // Fires ONLY when the manifest's `uis{}` sub-units show the legacy
+      // `/surface/notes` mount gone AND a `/surface/parachute` mount
+      // present (see surface-notes-alias.ts for the full condition +
+      // inert-today proof). On every existing notes-ui install the
+      // condition fails and dispatch falls through to the generic proxy
+      // below unchanged. Reads the same lenient manifest source
+      // `resolveUiMount` consumes — hoisted to one read shared by both.
+      const manifestServices = readManifestLenient(manifestPath).services;
+      if (isSurfaceNotesPath(pathname)) {
+        const aliasTarget = maybeRedirectSurfaceNotes(pathname, url.search, manifestServices);
+        if (aliasTarget !== undefined) {
+          logNotesRedirect(pathname, aliasTarget);
+          return new Response("", {
+            status: 301,
+            headers: { location: aliasTarget },
+          });
+        }
+      }
+
       // H3 — per-UI audience gate. When the path falls under a declared UI
       // sub-unit (a `uis{}` entry on the matched service row — surface-hosted
       // UI mounts like /surface/<name>/*), the sub-unit's audience is
@@ -4187,7 +4225,7 @@ export function hubFetch(
       // which also means a 'surface'/'public' mount on a loopback-only row
       // stays unreachable from tailnet/funnel: exposure is orthogonal to
       // audience.
-      const uiMatch = resolveUiMount(readManifestLenient(manifestPath).services, pathname);
+      const uiMatch = resolveUiMount(manifestServices, pathname);
       if (uiMatch) {
         const cloaked =
           effectivePublicExposure(uiMatch.entry) === "loopback" &&
@@ -4221,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

package/src/hub-settings.ts

@@ -92,6 +92,16 @@ export type HubSettingKey =
   // the deprecation window. Stored as the literal string "true" /
   // "false"; any other value parses as "redirect on" (the migration
   // default — operators must opt out, not opt in).
+  //
+  // Mount vocabulary post-W2-12: `/surface/notes` is the LEGACY notes-ui
+  // mount (what existing installs serve — this redirect's target);
+  // `/surface/parachute` is the app's surface mount under its renamed
+  // identity. A separate CONDITIONAL alias (surface-notes-alias.ts, no
+  // hub_settings row — it keys off the manifest's uis{} mounts) bridges
+  // `/surface/notes/*` → `/surface/parachute/*` only on installs where
+  // the legacy mount is gone and the new one exists, so the two
+  // redirects compose for post-rename installs: /notes/x →
+  // /surface/notes/x → /surface/parachute/x.
   | "notes_redirect_disabled"
   // Admin-UI screen-lock PIN (hub admin-lock feature). The argon2id hash of
   // the operator's lock PIN. Absent row = lock feature OFF (today's behavior
@@ -123,6 +133,25 @@ export type HubSettingKey =
   // not-yet-set-up hub still lands on setup, not a surface that can't work
   // yet.
   | "root_redirect"
+  // hub: how the hub answers its origin root. `"redirect"` (default / absent)
+  // is the historical behavior — the bare `/` 302s to `root_redirect` (a safe
+  // same-origin path, default `/admin`). `"serve-app"` makes the hub SERVE the
+  // installed Parachute app's built bundle AT the origin root (index.html at
+  // `/`, its assets from the same dist, SPA-fallback for HTML deep links) — the
+  // same front-door experience as the hosted door, no redirect hop. The app's
+  // build is root-based (absolute `/assets`, PWA scope `/`, root OAuth redirect
+  // URIs) so serving its dist verbatim at `/` is asset-correct with no rebuild.
+  //
+  // Precedence on each request (resolveRootMode): this row, then
+  // `PARACHUTE_HUB_ROOT_MODE` env, then the `"redirect"` default. DB-first (like
+  // `root_redirect`) so an operator can flip the front door from the admin SPA /
+  // CLI without a redeploy. When `serve-app` is set but the app isn't installed
+  // (its dist can't be resolved), the hub FALLS BACK to redirect behavior (using
+  // `root_redirect` → env → `/admin`) with a one-time log line — so an operator
+  // who set the mode before installing the app never sees a broken root. The
+  // fresh-hub wizard funnel + pre-admin 503 lockout still run BEFORE this, so a
+  // not-yet-set-up hub lands on setup, never a half-working app shell.
+  | "root_mode"
   // hub-parity P2 (Q2): the RAW token of the newest PUBLIC (multi-use,
   // `max_uses > 1`) invite — persisted so `GET /.well-known/parachute-account`
   // can advertise `signup_path` without being able to reconstruct it from the
@@ -607,3 +636,121 @@ export function resolveRootRedirect(
 ): string {
   return resolveRootRedirectDetailed(db, opts).value;
 }
+
+// --- domain helpers: root mode (redirect vs serve the app at `/`) ---------
+
+/**
+ * How the hub answers its origin root.
+ *
+ *   - `"redirect"` — historical behavior: the bare `/` 302s to the resolved
+ *     `root_redirect` (default `/admin`). Every unclaimed path keeps the
+ *     branded 404.
+ *   - `"serve-app"` — the hub serves the installed Parachute app's built
+ *     bundle AT the origin root (index.html at `/`, its assets from the same
+ *     dist, SPA-fallback for HTML deep links), matching the hosted door's
+ *     front-door experience. Falls back to `redirect` when the app isn't
+ *     installed (dist unresolvable).
+ */
+export type RootMode = "redirect" | "serve-app";
+
+/** Exported so the API handler + the CLI can share validation. */
+export const ROOT_MODES: readonly RootMode[] = ["redirect", "serve-app"];
+
+export function isRootMode(s: unknown): s is RootMode {
+  return typeof s === "string" && ROOT_MODES.includes(s as RootMode);
+}
+
+/** Env override for the root mode. Below the DB row, above the default. */
+export const PARACHUTE_HUB_ROOT_MODE_ENV = "PARACHUTE_HUB_ROOT_MODE";
+
+/** Fallback when neither DB row nor env is set — historical redirect behavior. */
+export const DEFAULT_ROOT_MODE: RootMode = "redirect";
+
+/**
+ * Read the raw stored root mode from hub_settings (or `null` when absent),
+ * WITHOUT applying env / default precedence — mirrors `getRootRedirect`. The
+ * admin GET surfaces this raw value so the operator sees exactly what's stored.
+ */
+export function getRootMode(db: Database): RootMode | null {
+  const raw = getSetting(db, "root_mode");
+  if (raw === undefined) return null;
+  return isRootMode(raw) ? raw : null;
+}
+
+/**
+ * Write or clear the root mode. Passing `null` (or the `"redirect"` default)
+ * deletes the row, reverting to env / default precedence — the absent-row
+ * state IS the redirect default, so leaving an explicit `"redirect"` in the
+ * row would be a footgun if a future default flip ever made absence mean
+ * something else (mirrors `setRootRedirect` / `setHubOrigin` semantics). The
+ * caller must have validated via `isRootMode`; the typed signature enforces it
+ * at TypeScript-clean call sites.
+ */
+export function setRootMode(db: Database, mode: RootMode | null): void {
+  if (mode === null || mode === DEFAULT_ROOT_MODE) {
+    deleteSetting(db, "root_mode");
+    return;
+  }
+  setSetting(db, "root_mode", mode);
+}
+
+/** Which precedence layer the resolved mode came from. */
+export type RootModeSource = "db" | "env" | "default";
+
+export interface ResolvedRootMode {
+  /** The mode the origin root should apply. */
+  value: RootMode;
+  /** Which layer it came from (for admin-UI attribution + install set-if-unset). */
+  source: RootModeSource;
+}
+
+/**
+ * Resolve the root mode with source attribution.
+ *
+ * Precedence: hub_settings.root_mode → `PARACHUTE_HUB_ROOT_MODE` env →
+ * `"redirect"` default. An invalid value at any layer is warned + skipped so a
+ * hand-edited row / typo'd env can never wedge the root (worst case falls to
+ * the redirect default — today's behavior).
+ *
+ * `db` may be `null` (hub-server running without state) — the DB layer is then
+ * skipped and resolution starts from env. The `env` / `warn` knobs are test
+ * seams (production uses `process.env` + `console.warn`).
+ */
+export function resolveRootModeDetailed(
+  db: Database | null,
+  opts: { env?: NodeJS.ProcessEnv; warn?: (msg: string) => void } = {},
+): ResolvedRootMode {
+  const env = opts.env ?? process.env;
+  const warn = opts.warn ?? ((msg: string) => console.warn(msg));
+
+  // 1. DB row (operator-set via the admin PUT / `parachute hub set-root-mode`).
+  if (db) {
+    const fromDb = getSetting(db, "root_mode");
+    if (fromDb !== undefined) {
+      if (isRootMode(fromDb)) return { value: fromDb, source: "db" };
+      warn(
+        `[hub-settings] root_mode="${fromDb}" in hub_settings is not a valid mode (expected one of ${ROOT_MODES.join(", ")}) — ignoring (falling through to env/default).`,
+      );
+    }
+  }
+
+  // 2. Env override.
+  const fromEnv = env[PARACHUTE_HUB_ROOT_MODE_ENV];
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (isRootMode(fromEnv)) return { value: fromEnv, source: "env" };
+    warn(
+      `[hub-settings] ${PARACHUTE_HUB_ROOT_MODE_ENV}="${fromEnv}" is not a valid mode — falling back to "${DEFAULT_ROOT_MODE}".`,
+    );
+  }
+
+  // 3. Default — historical redirect behavior.
+  return { value: DEFAULT_ROOT_MODE, source: "default" };
+}
+
+/** Convenience: just the resolved mode (see `resolveRootModeDetailed`). */
+export function resolveRootMode(
+  db: Database | null,
+  opts: { env?: NodeJS.ProcessEnv; warn?: (msg: string) => void } = {},
+): RootMode {
+  return resolveRootModeDetailed(db, opts).value;
+}