@openparachute/hub 0.7.7-rc.8 → 0.7.7

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,
@@ -119,7 +163,8 @@ export async function handleApiSettingsRootRedirect(
   // Bearer presence + parsing — identical shape to api-settings-hub-origin
   // for consistency across hub-internal admin endpoints.
   const auth = req.headers.get("authorization");
-  if (!auth || !auth.startsWith("Bearer ")) {
+  // Bearer scheme is case-insensitive per RFC 7235; token passed verbatim (V1.4/C1.3 parity).
+  if (!auth || !/^Bearer\s+/i.test(auth)) {
     return jsonError(401, "unauthenticated", "Authorization: Bearer <token> required");
   }
   const bearer = auth.slice("Bearer ".length).trim();
@@ -155,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,
@@ -166,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();
@@ -176,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/api-tokens.ts

@@ -113,7 +113,8 @@ export async function handleApiTokens(req: Request, deps: ApiTokensDeps): Promis
 
   // 1. Bearer presence + parsing.
   const auth = req.headers.get("authorization");
-  if (!auth || !auth.startsWith("Bearer ")) {
+  // Bearer scheme is case-insensitive per RFC 7235; token passed verbatim (V1.4/C1.3 parity).
+  if (!auth || !/^Bearer\s+/i.test(auth)) {
     return jsonError(401, "unauthenticated", "Authorization: Bearer <token> required");
   }
   const bearer = auth.slice("Bearer ".length).trim();

package/src/audience-gate.ts

@@ -235,7 +235,8 @@ export async function gateUiAudience(
   if (session) return null;
 
   const auth = req.headers.get("authorization");
-  if (auth?.startsWith("Bearer ")) {
+  // Bearer scheme is case-insensitive per RFC 7235; token passed verbatim (V1.4/C1.3 parity).
+  if (auth && /^Bearer\s+/i.test(auth)) {
     const token = auth.slice("Bearer ".length).trim();
     try {
       const validated = await validateHostAdminToken(db, token, [...deps.knownIssuers()]);

package/src/chrome-strip.ts

@@ -17,7 +17,12 @@
  * is the canonical opt-out — it owns its own chrome (see design-system §7
  * "Where NOT to inject" + AUDIT §4: "Notes is the proof this can work: own
  * application, looks distinctively Notes, reads as Parachute because the
- * tokens are continuous").
+ * tokens are continuous"). `/surface/parachute/*` (W2-12) is the same
+ * application under its post-rename surface identity — the parachute-app
+ * super-surface mounted as a surface — and owns its own chrome for the
+ * same reason. `/surface/notes/` stays on the list for existing notes-ui
+ * installs (legacy mount); the two entries coexist, they don't replace
+ * each other.
  *
  * H5 (surface-runtime design): the opt-out generalized — when a UI
  * sub-unit's declared `audience` resolves `public` at the proxy's audience
@@ -53,10 +58,17 @@ import { CSRF_FIELD_NAME, ensureCsrfToken } from "./csrf.ts";
  * prefix" or "pathname startsWith prefix" — the same shape as
  * `findServiceUpstream`'s mount comparison.
  *
- * `/surface/notes/` covers the Notes PWA bundled by parachute-app. Notes is a
- * destination, not chrome; it owns its own header (see design-system.md §7).
+ * `/surface/notes/` covers the legacy notes-ui mount (existing installs keep
+ * this identity on disk). `/surface/parachute/` covers the app's surface
+ * mount — the same application under its renamed surface identity (W2-12).
+ * Both are destinations, not chrome; each owns its own header (see
+ * design-system.md §7). Additive: neither entry replaces the other, so an
+ * install serving either mount (or, transiently, both) gets the opt-out.
  */
-export const CHROME_OPT_OUT_PREFIXES: readonly string[] = ["/surface/notes/"];
+export const CHROME_OPT_OUT_PREFIXES: readonly string[] = [
+  "/surface/notes/",
+  "/surface/parachute/",
+];
 
 /**
  * Buffer size cap. Responses larger than this are passed through unchanged.

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

@@ -1,3 +1,4 @@
+import type { Database } from "bun:sqlite";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
@@ -15,6 +16,12 @@ import {
   defaultSleep,
   readHubPort,
 } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  resolveRootModeDetailed,
+  resolveRootRedirectDetailed,
+  setRootMode,
+} from "../hub-settings.ts";
 import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
 import {
   type ModuleManifest,
@@ -33,6 +40,7 @@ import {
   type FirstPartyFallback,
   KNOWN_MODULES,
   type KnownModule,
+  RETIRED_MODULES,
   type ServiceSpec,
   composeServiceSpec,
   isCanonicalPort,
@@ -126,15 +134,9 @@ export function resolveInstallChannel(opts: {
  * launch sinks in and `parachute install lens` has stopped appearing
  * in support threads.
  *
- * `channel → agent` (2026-06-17): parachute-channel was renamed to
- * parachute-agent. `parachute install channel` keeps resolving to the
- * agent module for one release cycle so operators mid-upgrade aren't
- * stranded. Remove alongside the `parachute-channel → agent` legacy
- * manifest alias in service-spec.ts.
  */
 const SERVICE_ALIASES: Record<string, string> = {
   lens: "notes",
-  channel: "agent",
 };
 
 /**
@@ -145,14 +147,41 @@ const SERVICE_ALIASES: Record<string, string> = {
  * real, non-Parachute package on npm). Install refuses with the message
  * instead.
  */
+const AGENT_RETIRED_MESSAGE =
+  "parachute-agent was retired from the hub on 2026-07-15. " +
+  "Parachute product development is focused on Vault and Surface.";
+
 const RETIRED_INSTALL_SHORTS: Record<string, string> = {
+  agent: AGENT_RETIRED_MESSAGE,
+  channel:
+    "parachute-channel (later parachute-agent) was retired from the hub on 2026-07-15. " +
+    "Parachute product development is focused on Vault and Surface.",
   runner:
     "parachute-runner was retired from the hub's module registry on 2026-07-01 " +
-    "(the module set of record is vault, hub, agent, scribe, surface). " +
+    "(the module set of record is vault, hub, scribe, surface, app). " +
     "An existing install keeps running under `parachute serve`; to install it anyway, " +
     "pass the explicit npm package name (@openparachute/runner) or a local checkout path.",
 };
 
+const RETIRED_AGENT_PACKAGES = [
+  "@openparachute/agent",
+  "@openparachute/parachute-agent",
+  "@openparachute/channel",
+  "@openparachute/parachute-channel",
+] as const;
+
+function isRetiredAgentPackage(packageName: string): boolean {
+  return RETIRED_AGENT_PACKAGES.some(
+    (retired) => packageName === retired || packageName.startsWith(`${retired}@`),
+  );
+}
+
+function isRetiredAgentManifest(manifest: ModuleManifest): boolean {
+  if (RETIRED_MODULES[manifest.name] !== undefined) return true;
+  if (manifest.manifestName && RETIRED_MODULES[manifest.manifestName] !== undefined) return true;
+  return manifest.name === "claw" && manifest.paths[0] === "/claw";
+}
+
 export interface InstallOpts {
   runner?: Runner;
   manifestPath?: string;
@@ -408,6 +437,16 @@ export interface InstallOpts {
    * origin for stable assertions.
    */
   wellKnownOrigin?: string;
+  /**
+   * Test seam for the `app`-only set-if-unset root-redirect write (hub-parity
+   * P5). Production opens `openHubDb(hubDbPath(configDir))` fresh and closes
+   * it after the write; passing this injects an already-open DB (e.g. a
+   * tempdir `hub.db`) so a test never touches the real `~/.parachute/hub.db`.
+   * Passing this ALSO opts a tempdir-manifestPath test INTO the write path —
+   * mirrors `guidanceCtx`'s discriminant: without it, the production gate
+   * (`manifestPath === SERVICES_MANIFEST_PATH`) skips the write entirely.
+   */
+  rootRedirectDb?: Database;
 }
 
 async function defaultRunner(cmd: readonly string[]): Promise<number> {
@@ -734,12 +773,20 @@ function resolveInstallTarget(
       log(`✗ ${input} has no readable package.json — can't install as a Parachute module.`);
       return null;
     }
+    if (isRetiredAgentPackage(packageName)) {
+      log(`✗ ${AGENT_RETIRED_MESSAGE}`);
+      return null;
+    }
     return { kind: "local-path", absPath: input, packageName };
   }
 
   // Anything else is treated as an npm package (bare or @scope/name). The
   // module.json contract gates this — third-party packages without a
   // manifest fail post-install with a clear error, not silently.
+  if (isRetiredAgentPackage(input)) {
+    log(`✗ ${AGENT_RETIRED_MESSAGE}`);
+    return null;
+  }
   return { kind: "npm", packageName: input };
 }
 
@@ -962,6 +1009,10 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     log,
   });
   if (installedManifest === "error") return 1;
+  if (installedManifest && isRetiredAgentManifest(installedManifest)) {
+    log(`✗ ${target.packageName}: ${AGENT_RETIRED_MESSAGE}`);
+    return 1;
+  }
 
   let manifest: ModuleManifest;
   let extras: FirstPartyExtras | undefined;
@@ -969,7 +1020,7 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     manifest = installedManifest ?? target.fallback.manifest;
     extras = target.fallback.extras;
   } else if (target.kind === "known-module") {
-    // KNOWN_MODULES shorts (vault / scribe / agent / surface) carry no vendored
+    // KNOWN_MODULES shorts (vault / scribe / surface) carry no vendored
     // manifest (hub#310). The module's own `.parachute/module.json` is the
     // canonical source. When it's unreadable (legacy installs from before
     // module.json shipped, or test fixtures that mock the disk path without
@@ -1351,6 +1402,44 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     }
   }
 
+  // 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 {
+        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();
+      }
+    }
+  }
+
   // Per-service install footer — canonical next-step URLs and configuration
   // hints. Vault prints its own (richer) footer from `parachute-vault init`
   // (PR #166), so the spec leaves vault out and we don't double up here.

package/src/commands/migrate.ts

@@ -106,7 +106,11 @@ export function safelistEntries(): Set<string> {
  * list once enough operator cycles have passed to be confident no
  * install is still on the Lens-era code path.
  */
-export const KNOWN_ARCHIVABLE_DIRS: ReadonlySet<string> = new Set<string>(["lens"]);
+export const KNOWN_ARCHIVABLE_DIRS: ReadonlySet<string> = new Set<string>([
+  "lens",
+  "agent",
+  "channel",
+]);
 
 /**
  * Known-cruft rules. Each rule names a label (the friendly description in

package/src/commands/setup.ts

@@ -110,7 +110,7 @@ function defaultAvailability(): InteractiveAvailability {
 
 /**
  * Survey ALL known first-party shortnames (vault / notes / scribe / agent /
- * surface) regardless of tier — `installed` is true when the service
+ * surface / app) regardless of tier — `installed` is true when the service
  * has a row in services.json. The fresh-install OFFER is narrowed downstream
  * by `isOfferable` (drops already-installed + `deprecated`-tier shorts —
  * notes); agent (`experimental`) is flagged exploratory in its blurb
@@ -121,7 +121,7 @@ function defaultAvailability(): InteractiveAvailability {
  * like any unknown row it neither blocks setup nor appears in the offer.
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
- * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
+ * shorts (notes / app — both carry a vendored manifest). KNOWN_MODULES shorts
  * (vault / scribe / agent / surface) ship `.parachute/module.json`
  * and self-register; pre-install we know manifestName + the urlForEntry quirk
  * from `KNOWN_MODULES[short].extras`, which is all the survey/summary needs.
@@ -175,14 +175,17 @@ export function isOfferable(choice: { short: string; installed: boolean }): bool
 const BLURBS: Record<string, string> = {
   vault: "knowledge graph (MCP) — your owner-authenticated note + tag store",
   surface: "Parachute UI host — auto-installs Notes on first boot (the recommended UI path)",
-  // `app` is the pre-2026-05-27 name for `surface`; kept for any legacy survey row.
-  app: "Parachute UI host — auto-installs Notes on first boot (recommended over notes-daemon)",
+  // hub-parity P5 (2026-07-11): `app` is now the NEW super-surface front
+  // door (@openparachute/parachute-app) — a real FIRST_PARTY_FALLBACKS
+  // entry, not a legacy survey row. It is UNRELATED to the pre-2026-05-27
+  // `app` package that renamed to `surface` (that blurb lives under the
+  // `surface` key above); the two just happen to share the short name
+  // across a rename.
+  app: "the super-surface front door — one app to sign in, browse your vault, and manage your hub/cloud",
   // notes is `deprecated` (not offered on a fresh setup) — this blurb only
   // renders if a legacy install surfaces it in the survey.
   notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `surface`)",
   scribe: "audio transcription for dictation + recordings",
-  agent:
-    "(exploratory) chat with your Claude Code sessions — a channel per session (renamed from channel)",
 };
 
 function blurbFor(choice: ServiceChoice): string {