@openparachute/hub 0.7.7-rc.9 → 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

@@ -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,
@@ -36,6 +40,7 @@ import {
   type FirstPartyFallback,
   KNOWN_MODULES,
   type KnownModule,
+  RETIRED_MODULES,
   type ServiceSpec,
   composeServiceSpec,
   isCanonicalPort,
@@ -129,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",
 };
 
 /**
@@ -148,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;
@@ -747,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 };
 }
 
@@ -975,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;
@@ -982,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
@@ -1364,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/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

@@ -186,8 +186,6 @@ const BLURBS: Record<string, string> = {
   // 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 {

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)");