@openparachute/hub 0.7.1 → 0.7.2-rc.1

package/src/api-admin-lock.ts

@@ -0,0 +1,335 @@
+/**
+ * Admin screen-lock management API (hub admin-lock feature).
+ *
+ * All endpoints are session-cookie-gated to the first admin — the same gate
+ * the admin-token mints use (`isFirstAdmin`). These manage the lock itself, so
+ * they are NOT behind the lock gate (you must be able to unlock + set the PIN
+ * even when the surface is locked).
+ *
+ *   GET  /api/admin-lock           → status { configured, locked, idle_seconds, unlock_seconds_remaining }
+ *   POST /api/admin-lock/set       → set the FIRST PIN (no PIN configured yet)
+ *   POST /api/admin-lock/change    → rotate PIN (requires current PIN or unlocked session)
+ *   POST /api/admin-lock/remove    → turn the feature OFF (requires current PIN or unlocked session)
+ *   POST /api/admin-lock/unlock    → verify PIN, open an unlock window
+ *   POST /api/admin-lock/lock      → "Lock now" — drop the session's unlock window
+ *   POST /api/admin-lock/heartbeat → slide the idle window forward on activity
+ *
+ * The chicken-and-egg: setting the FIRST PIN is an authenticated admin action
+ * (logged-in session, no PIN yet → allowed). Once a PIN exists, change/remove
+ * require proving knowledge of the current PIN OR an already-unlocked session
+ * (the operator just unlocked, so they hold the PIN — re-typing would be
+ * friction). Setting over an existing PIN is rejected (use change).
+ *
+ * State-changing POSTs additionally require a CSRF token (`__csrf`) — these
+ * are JSON endpoints on the same origin as the cookie, and SameSite=Lax alone
+ * doesn't stop same-site CSRF (see src/csrf.ts). The SPA sources the token
+ * from `/api/me`.
+ */
+import type { Database } from "bun:sqlite";
+import {
+  clampIdleSeconds,
+  clearPin,
+  getIdleSeconds,
+  isLockConfigured,
+  isSessionUnlocked,
+  lockSession,
+  recordUnlock,
+  refreshActivity,
+  setIdleSeconds,
+  setPin,
+  unlockLimiter,
+  unlockSecondsRemaining,
+  validatePin,
+  verifyPin,
+} from "./admin-lock.ts";
+import { verifyCsrfToken } from "./csrf.ts";
+import { findSession, parseSessionCookie } from "./sessions.ts";
+import { isFirstAdmin } from "./users.ts";
+
+export interface AdminLockDeps {
+  db: Database;
+  /** Injectable clock for tests. */
+  now?: () => Date;
+}
+
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+function err(status: number, error: string, description: string): Response {
+  return json(status, { error, error_description: description });
+}
+
+/**
+ * Resolve the first-admin session for this request, or an error Response.
+ * Mirrors the gate the token-mint endpoints apply, so the lock-management
+ * surface has the same audience.
+ */
+function requireAdminSession(
+  db: Database,
+  req: Request,
+): { ok: true; sessionId: string; userId: string } | { ok: false; res: Response } {
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  const session = sid ? findSession(db, sid) : null;
+  if (!session || !sid) {
+    return {
+      ok: false,
+      res: err(401, "unauthenticated", "no admin session — sign in at /login first"),
+    };
+  }
+  if (!isFirstAdmin(db, session.userId)) {
+    return {
+      ok: false,
+      res: err(
+        403,
+        "not_admin",
+        "admin lock management is restricted to the hub admin — your account home is at /account/",
+      ),
+    };
+  }
+  return { ok: true, sessionId: sid, userId: session.userId };
+}
+
+async function readJsonBody(req: Request): Promise<Record<string, unknown>> {
+  try {
+    const body = (await req.json()) as unknown;
+    return body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function checkCsrf(req: Request, body: Record<string, unknown>): boolean {
+  const token = typeof body.__csrf === "string" ? body.__csrf : null;
+  return verifyCsrfToken(req, token);
+}
+
+/**
+ * The lock-management router. `subpath` is the path AFTER `/api/admin-lock`
+ * (e.g. "" for status, "/unlock", "/set"). The hub-server dispatcher slices it.
+ */
+export async function handleAdminLock(
+  req: Request,
+  subpath: string,
+  deps: AdminLockDeps,
+): Promise<Response> {
+  const { db } = deps;
+  const now = deps.now ?? (() => new Date());
+
+  // GET status (no body, no CSRF — read-only).
+  if (subpath === "" || subpath === "/") {
+    if (req.method !== "GET") return err(405, "method_not_allowed", "use GET");
+    const gate = requireAdminSession(db, req);
+    if (!gate.ok) return gate.res;
+    const configured = isLockConfigured(db);
+    const nowMs = now().getTime();
+    const locked = configured && !isSessionUnlocked(gate.sessionId, nowMs);
+    return json(200, {
+      configured,
+      locked,
+      idle_seconds: getIdleSeconds(db),
+      unlock_seconds_remaining: configured ? unlockSecondsRemaining(gate.sessionId, nowMs) : 0,
+    });
+  }
+
+  // Everything below is a POST.
+  if (req.method !== "POST") return err(405, "method_not_allowed", "use POST");
+  const gate = requireAdminSession(db, req);
+  if (!gate.ok) return gate.res;
+  const body = await readJsonBody(req);
+  if (!checkCsrf(req, body)) {
+    return err(403, "csrf_failed", "missing or invalid CSRF token");
+  }
+
+  switch (subpath) {
+    case "/set":
+      return handleSet(db, gate.sessionId, body);
+    case "/change":
+      return handleChange(db, gate.sessionId, body, now);
+    case "/remove":
+      return handleRemove(db, gate.sessionId, body, now);
+    case "/unlock":
+      return handleUnlock(db, gate.sessionId, gate.userId, body, now);
+    case "/lock":
+      lockSession(gate.sessionId);
+      return json(200, { locked: true });
+    case "/heartbeat":
+      // Slide the idle window forward if (and only if) currently unlocked.
+      refreshActivity(gate.sessionId, getIdleSeconds(db), now().getTime());
+      return json(200, {
+        locked: isLockConfigured(db) && !isSessionUnlocked(gate.sessionId, now().getTime()),
+        unlock_seconds_remaining: unlockSecondsRemaining(gate.sessionId, now().getTime()),
+      });
+    default:
+      return err(404, "not_found", `no admin-lock route at /api/admin-lock${subpath}`);
+  }
+}
+
+/** Optional idle-seconds override from a request body field. Clamped; undefined when absent/invalid. */
+function readIdleSeconds(body: Record<string, unknown>): number | undefined {
+  const raw = body.idle_seconds;
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return undefined;
+  return clampIdleSeconds(raw);
+}
+
+async function handleSet(
+  db: Database,
+  sessionId: string,
+  body: Record<string, unknown>,
+): Promise<Response> {
+  // Setting the FIRST PIN — refuse if one already exists (use /change).
+  if (isLockConfigured(db)) {
+    return err(409, "already_configured", "a PIN is already set — use /api/admin-lock/change");
+  }
+  const pin = typeof body.pin === "string" ? body.pin : "";
+  if (!validatePin(pin).valid) {
+    return err(400, "invalid_pin", "PIN must be 4–12 digits");
+  }
+  const idle = readIdleSeconds(body);
+  if (idle !== undefined) setIdleSeconds(db, idle);
+  await setPin(db, pin);
+  // Setting the PIN immediately opens an unlock window for this session — the
+  // operator who just typed it isn't locked out of their own current session.
+  recordUnlock(sessionId, getIdleSeconds(db));
+  return json(201, { configured: true, locked: false, idle_seconds: getIdleSeconds(db) });
+}
+
+async function handleChange(
+  db: Database,
+  sessionId: string,
+  body: Record<string, unknown>,
+  now: () => Date,
+): Promise<Response> {
+  if (!isLockConfigured(db)) {
+    return err(409, "not_configured", "no PIN is set — use /api/admin-lock/set");
+  }
+  const newPin = typeof body.new_pin === "string" ? body.new_pin : "";
+  if (!validatePin(newPin).valid) {
+    return err(400, "invalid_pin", "new PIN must be 4–12 digits");
+  }
+  // Authorize the change: an already-unlocked session OR a correct current PIN.
+  const authorized = await authorizeMutation(db, sessionId, body, now);
+  if (!authorized.ok) return authorized.res;
+  const idle = readIdleSeconds(body);
+  if (idle !== undefined) setIdleSeconds(db, idle);
+  await setPin(db, newPin);
+  // Re-open the unlock window for this session under the new PIN.
+  recordUnlock(sessionId, getIdleSeconds(db), now().getTime());
+  return json(200, { configured: true, locked: false, idle_seconds: getIdleSeconds(db) });
+}
+
+async function handleRemove(
+  db: Database,
+  sessionId: string,
+  body: Record<string, unknown>,
+  now: () => Date,
+): Promise<Response> {
+  if (!isLockConfigured(db)) {
+    // Idempotent — already off.
+    return json(200, { configured: false, locked: false });
+  }
+  const authorized = await authorizeMutation(db, sessionId, body, now);
+  if (!authorized.ok) return authorized.res;
+  clearPin(db);
+  // Feature is off now — drop any unlock window (it no longer means anything).
+  lockSession(sessionId);
+  return json(200, { configured: false, locked: false });
+}
+
+/**
+ * Shared authorization for change/remove: succeed when the session is already
+ * unlocked, OR a correct `current_pin` is supplied. The current-PIN path runs
+ * through the same brute-force limiter as /unlock.
+ */
+async function authorizeMutation(
+  db: Database,
+  sessionId: string,
+  body: Record<string, unknown>,
+  now: () => Date,
+): Promise<{ ok: true } | { ok: false; res: Response }> {
+  if (isSessionUnlocked(sessionId, now().getTime())) return { ok: true };
+  const currentPin = typeof body.current_pin === "string" ? body.current_pin : "";
+  if (!currentPin) {
+    return {
+      ok: false,
+      res: err(
+        401,
+        "pin_required",
+        "this session is locked — supply current_pin (or unlock first)",
+      ),
+    };
+  }
+  // Rate-limit BEFORE the argon2id verify (a stolen cookie shouldn't grind).
+  const rl = unlockLimiter.checkAndRecord(sessionId, now());
+  if (!rl.allowed) {
+    return {
+      ok: false,
+      res: new Response(
+        JSON.stringify({
+          error: "too_many_attempts",
+          error_description: `too many PIN attempts — retry in ${rl.retryAfterSeconds}s`,
+        }),
+        {
+          status: 429,
+          headers: {
+            "content-type": "application/json",
+            "cache-control": "no-store",
+            "retry-after": String(rl.retryAfterSeconds ?? 60),
+          },
+        },
+      ),
+    };
+  }
+  const ok = await verifyPin(db, currentPin);
+  if (!ok) return { ok: false, res: err(401, "wrong_pin", "incorrect PIN") };
+  return { ok: true };
+}
+
+async function handleUnlock(
+  db: Database,
+  sessionId: string,
+  _userId: string,
+  body: Record<string, unknown>,
+  now: () => Date,
+): Promise<Response> {
+  if (!isLockConfigured(db)) {
+    // No PIN → nothing to unlock; treat as already-open so the SPA proceeds.
+    return json(200, { unlocked: true, configured: false, idle_seconds: getIdleSeconds(db) });
+  }
+  const pin = typeof body.pin === "string" ? body.pin : "";
+  // Rate-limit BEFORE the argon2id verify — keyed by session (the session
+  // already identifies the actor; a stolen cookie shouldn't get fresh buckets
+  // across IPs). The denied attempt still counts toward the bucket so a wrong
+  // PIN can't be retried infinitely.
+  const rl = unlockLimiter.checkAndRecord(sessionId, now());
+  if (!rl.allowed) {
+    return new Response(
+      JSON.stringify({
+        error: "too_many_attempts",
+        error_description: `too many PIN attempts — retry in ${rl.retryAfterSeconds}s`,
+      }),
+      {
+        status: 429,
+        headers: {
+          "content-type": "application/json",
+          "cache-control": "no-store",
+          "retry-after": String(rl.retryAfterSeconds ?? 60),
+        },
+      },
+    );
+  }
+  const ok = await verifyPin(db, pin);
+  if (!ok) {
+    return err(401, "wrong_pin", "incorrect PIN");
+  }
+  recordUnlock(sessionId, getIdleSeconds(db), now().getTime());
+  return json(200, {
+    unlocked: true,
+    configured: true,
+    idle_seconds: getIdleSeconds(db),
+    unlock_seconds_remaining: unlockSecondsRemaining(sessionId, now().getTime()),
+  });
+}

package/src/api-modules-ops.ts

@@ -286,8 +286,9 @@ interface PathMatch {
  * for — but the gate is now "is this a KNOWN module" (`isKnownModuleShort`:
  * KNOWN_MODULES ∪ FIRST_PARTY_FALLBACKS), NOT the old `CURATED_MODULES`
  * whitelist (2026-06-09 modular-UI architecture, P2). This is what makes
- * `POST /api/modules/channel/install` resolve — channel was discoverable +
- * running yet un-installable because it sat outside the whitelist.
+ * `POST /api/modules/agent/install` resolve — the agent module (then named
+ * channel) was discoverable + running yet un-installable because it sat
+ * outside the whitelist.
  *
  * The hub (`hub`) and genuinely third-party services.json rows still fall
  * through to undefined: there's no install package to act on.

package/src/api-modules.ts

@@ -53,8 +53,8 @@ import {
   shortNameForManifest,
 } from "./service-spec.ts";
 // `FIRST_PARTY_FALLBACKS` and `KNOWN_MODULES` are both consulted by
-// `lookupModule` below — the former for notes/channel (vendored manifests
-// still required) and the latter for vault/scribe/runner (post-FALLBACK
+// `lookupModule` below — the former for notes (vendored manifest still
+// required) and the latter for vault/scribe/runner/agent (post-FALLBACK
 // retirement, hub#310). The local helper hides the split from the rest of
 // this file. `discoverableShorts` enumerates their UNION — the
 // self-registration-driven discovery surface that replaced the old
@@ -267,14 +267,14 @@ interface ModuleWireShape {
    * `.parachute/module.json` `configUiUrl`, joined against its mount path the
    * same way `management_url` resolves `managementUrl`/`uiUrl`. Drives the
    * Modules page's consistent **Configure** action — clicking lands the
-   * operator on the module's own config UI (channel `/channel/admin`, scribe
+   * operator on the module's own config UI (agent `/agent/admin`, scribe
    * `/scribe/admin`, …), which mints its admin Bearer from the hub's
-   * cookie-gated `/admin/module-token/<short>` (or `/admin/channel-token`).
+   * cookie-gated `/admin/module-token/<short>` (or `/admin/agent-token`).
    *
    * Null when the module hasn't declared `configUiUrl` — the SPA omits the
    * Configure action for that module rather than rendering a dead button.
    * Distinct from `management_url`: a module may declare one, both, or
-   * neither. Channel declares `configUiUrl: "/channel/admin"` + `uiUrl`;
+   * neither. Agent declares `configUiUrl: "/agent/admin"` + `uiUrl`;
    * vault declares `managementUrl` (its admin SPA is the config surface).
    */
   config_ui_url: string | null;
@@ -493,8 +493,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
         );
         if (resolvedManagement !== undefined) managementUrlByShort.set(short, resolvedManagement);
         // The config surface resolves with the SAME rule. A module may declare
-        // `configUiUrl` independently of `managementUrl` — channel ships
-        // `configUiUrl: "/channel/admin"` (single-instance, origin-absolute)
+        // `configUiUrl` independently of `managementUrl` — agent ships
+        // `configUiUrl: "/agent/admin"` (single-instance, origin-absolute)
         // alongside a separate `uiUrl`.
         const resolvedConfig = resolveModuleUrl(m.configUiUrl, value.mountPath, short);
         if (resolvedConfig !== undefined) configUiUrlByShort.set(short, resolvedConfig);
@@ -744,8 +744,8 @@ let warnedLegacyVaultAdminCandidate = false;
  *   - `undefined` candidate → `undefined` (the module didn't declare it).
  *   - Absolute http(s) URL → returned verbatim (off-origin escape hatch).
  *   - Leading-`/` path → ORIGIN-ABSOLUTE, returned verbatim. Single-instance
- *     modules (surface, scribe, runner, channel) declare their full hub-origin
- *     path this way (`/surface/admin/`, `/scribe/admin`, `/channel/admin`);
+ *     modules (surface, scribe, runner, agent) declare their full hub-origin
+ *     path this way (`/surface/admin/`, `/scribe/admin`, `/agent/admin`);
  *     vault's daemon-level surface is `/vault/admin/`.
  *   - Relative path (no leading slash) → MOUNT-JOINED: the per-instance form
  *     (`admin/` on a `/vault/default` mount → `/vault/default/admin/`). With

package/src/cli.ts

@@ -939,7 +939,19 @@ async function main(argv: string[]): Promise<number> {
       // after `vault` (including --help) is passed through verbatim.
       if (rest.length === 0) return await mod.dispatchVault(["--help"]);
 
-      // Everything under `vault` forwards transparently to `parachute-vault`.
+      // Intercept the delete verbs BEFORE the transparent passthrough (B3):
+      // `parachute vault remove <name>` must route through the hub's identity
+      // cascade (`DELETE /vaults/<name>`), NOT forward verbatim to
+      // `parachute-vault remove` (mechanics-only — orphans hub-side tokens,
+      // grants, user_vaults rows). `rm` is a convenience alias to the same path.
+      const sub = rest[0];
+      if (sub === "remove" || sub === "rm") {
+        const rm = await loadCommand("vault-remove", () => import("./commands/vault-remove.ts"));
+        if (!rm) return 1;
+        return await rm.vaultRemove(rest.slice(1));
+      }
+
+      // Everything else under `vault` forwards transparently to `parachute-vault`.
       // `vault tokens create` used to route through a guided interactive
       // wrapper, but the pvt_* DROP (vault#412 / hub#466) removed that vault
       // subcommand — it now exits 1 with migration guidance. Access tokens are

package/src/clients.ts

@@ -215,6 +215,94 @@ export function requireRegisteredRedirectUri(client: OAuthClient, candidate: str
   return candidate;
 }
 
+/**
+ * Cross-hub-origin redirect_uri expansion for hub-served DCR clients
+ * (surface#118; the "hub assist" half of the fix).
+ *
+ * THE PROBLEM. A hub-served module (surface-host, notes) registers its OAuth
+ * client at install time, when the only origin it knows is the loopback hub
+ * URL (`http://127.0.0.1:1939`). Once the operator runs `parachute expose`,
+ * the browser loads the surface from the PUBLIC hub origin and the
+ * surface-client runtime computes its `redirect_uri` from `window.location.
+ * origin` (the public one) — which was never registered. Authorize-time
+ * matching is deliberately strict exact-match (`requireRegisteredRedirectUri`,
+ * RFC 8252 anti-open-redirect), so the public-origin redirect_uri is rejected
+ * ("Redirect mismatch") and no off-localhost user can sign in.
+ *
+ * THE FIX. At DCR time, for each submitted redirect_uri WHOSE ORIGIN IS ONE
+ * OF THE HUB'S OWN KNOWN ORIGINS (issuer, expose-state hubOrigin, platform
+ * origin, loopback aliases — i.e. the same set `buildHubBoundOrigins`
+ * produces), ALSO register the same PATH on every OTHER known hub origin. A
+ * loopback-registered hub-served client thus becomes valid on the public hub
+ * origin too, without ever loosening the strict authorize-time match.
+ *
+ * THE INVARIANT (no open redirect). Expansion ONLY ever produces URIs rooted
+ * at the hub's OWN known origins. A submitted redirect_uri whose origin is
+ * FOREIGN — a separate-origin surface on its own domain (e.g. my-vault-ui at
+ * `https://notes.example`), a third-party app — is stored VERBATIM: not
+ * expanded onto any hub origin, and not dropped. Only hub-origin-rooted URIs
+ * receive the cross-origin fan-out. Because authorize-time matching stays
+ * strict exact-match against this stored set, an attacker who registers a
+ * foreign redirect_uri gets back exactly what they submitted (no hub-origin
+ * variant minted for them), and a hub-origin-rooted URI only ever fans out to
+ * other hub origins the operator already controls.
+ *
+ * Order-preserving + de-duplicated: the originally-submitted URIs come first
+ * (preserving caller order), with the synthesized hub-origin variants
+ * appended in a stable order; duplicates are collapsed.
+ */
+export function expandRedirectUrisForHubOrigins(
+  submitted: readonly string[],
+  hubOrigins: readonly string[],
+): string[] {
+  // Parse the hub's known origins into a Set for membership tests. Malformed
+  // entries are skipped — the function fails safe (no expansion) rather than
+  // throwing.
+  const hubOriginSet = new Set<string>();
+  for (const raw of hubOrigins) {
+    try {
+      hubOriginSet.add(new URL(raw).origin);
+    } catch {
+      // Skip malformed hub origin.
+    }
+  }
+
+  // Preserve submitted order + dedupe; append synthesized variants after.
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const push = (uri: string) => {
+    if (seen.has(uri)) return;
+    seen.add(uri);
+    out.push(uri);
+  };
+
+  // 1) Every submitted URI is stored as-is (foreign + hub-origin alike). This
+  //    is what guarantees a foreign redirect_uri is never dropped.
+  for (const uri of submitted) push(uri);
+
+  // 2) For each submitted URI rooted at a hub origin, synthesize the same path
+  //    on every OTHER hub origin. Foreign-origin URIs are skipped here — they
+  //    never spawn a hub-origin variant (the open-redirect guard).
+  if (hubOriginSet.size > 1) {
+    for (const uri of submitted) {
+      let parsed: URL;
+      try {
+        parsed = new URL(uri);
+      } catch {
+        continue;
+      }
+      if (!hubOriginSet.has(parsed.origin)) continue; // foreign → no expansion
+      const pathSuffix = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+      for (const origin of hubOriginSet) {
+        if (origin === parsed.origin) continue;
+        push(`${origin}${pathSuffix}`);
+      }
+    }
+  }
+
+  return out;
+}
+
 export function verifyClientSecret(client: OAuthClient, presented: string): boolean {
   if (!client.clientSecretHash) return false;
   const presentedHash = createHash("sha256").update(presented).digest("hex");

package/src/commands/install.ts

@@ -125,9 +125,16 @@ export function resolveInstallChannel(opts: {
  * install lens` during the ~3-day window keeps working. Remove after
  * 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",
 };
 
 export interface InstallOpts {

package/src/commands/serve-boot.ts

@@ -78,12 +78,13 @@ export interface BuildSpawnRequestOpts {
  *
  * Why (channel#41): the hub is the port authority, and a first-party module
  * with a compiled-in canonical port (`canonicalPortForManifest` ≠ undefined —
- * vault / scribe / surface / channel / notes / runner) has exactly ONE correct
+ * vault / scribe / surface / agent / notes / runner) has exactly ONE correct
  * port: its canonical one. The injected `PORT`, the supervisor's readiness
  * probe, and the reverse-proxy target are ALL derived from the services.json
- * row's `port`. So once a transiently-wrong port lands in that row (the channel
- * row was observed live carrying `19415` instead of `1941`), it self-perpetuates:
- * the supervisor probes/proxies the wrong port forever and `/channel/*` routes
+ * row's `port`. So once a transiently-wrong port lands in that row (the agent
+ * row — then named channel — was observed live carrying `19415` instead of
+ * `1941`), it self-perpetuates:
+ * the supervisor probes/proxies the wrong port forever and `/agent/*` routes
  * to a dead port. The canonical port is authoritative, so we reconcile the row
  * before spawn rather than honoring the drift.
  *

package/src/commands/serve.ts

@@ -38,6 +38,7 @@ import { createDbHolder, defaultStatInode, startDbPathLivenessTimer } from "../h
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
 import { writeHubFile } from "../hub.ts";
+import { createWsBridgeHandlers } from "../ws-bridge.ts";
 import { enrichedPath } from "../spawn-path.ts";
 import { Supervisor } from "../supervisor.ts";
 import { createUser, userCount } from "../users.ts";
@@ -45,6 +46,35 @@ import { sanitizePublicOrigin } from "../vault-hub-origin-env.ts";
 import { WELL_KNOWN_DIR } from "../well-known.ts";
 import { bootSupervisedModules } from "./serve-boot.ts";
 
+/**
+ * Build the `Bun.serve` options for the hub listener. Extracted (pure) so the
+ * load-bearing wiring — crucially the `websocket` bridge handler — is unit-
+ * testable and can't silently drift from the other `Bun.serve` in
+ * `hub-server.ts`. That drift is exactly how the in-page-terminal WS upgrade
+ * started 500ing: the bridge was wired into hub-server.ts's serve but NOT this
+ * production `parachute serve` path, so `server.upgrade()` (in `hubFetch`'s
+ * `maybeUpgradeWebSocket`) threw "set the websocket object in Bun.serve({})".
+ */
+export function hubServeOptions(args: {
+  port: number;
+  hostname: string;
+  fetch: ReturnType<typeof hubFetch>;
+}) {
+  return {
+    port: args.port,
+    hostname: args.hostname,
+    // Hold idle keep-alive connections for Bun's maximum 255s so reverse-proxy
+    // edges (Render, Cloudflare, fly.io) don't race us reusing pooled
+    // connections (hub#399).
+    idleTimeout: 255,
+    fetch: args.fetch,
+    // The WebSocket upgrade bridge. `maybeUpgradeWebSocket` (in `hubFetch`) calls
+    // `server.upgrade()`, which THROWS unless the server declares this handler —
+    // so it MUST be present on every Bun.serve that runs `hubFetch`.
+    websocket: createWsBridgeHandlers(),
+  };
+}
+
 export interface ServeOpts {
   /** Override PORT (test-only). Real callers thread env via process.env. */
   port?: number;
@@ -456,26 +486,22 @@ export async function serve(opts: ServeOpts = {}): Promise<{
   // fail fast and cleanly, leaving the live hub's children untouched.
   let server: ReturnType<typeof Bun.serve>;
   try {
-    server = Bun.serve({
-      port,
-      hostname,
-      // Hold idle keep-alive connections for Bun's maximum 255s so reverse-
-      // proxy edges (Render, Cloudflare, fly.io) don't race us when reusing
-      // pooled connections. See `src/hub-server.ts` for the full rationale —
-      // this is the active code path for `bun src/cli.ts serve` (the Docker
-      // CMD), so the fix has to land here too. Closes hub#399.
-      idleTimeout: 255,
-      fetch: hubFetch(WELL_KNOWN_DIR, {
-        getDb: () => dbHolder.get(),
-        onDbError: (err) => dbHolder.healOrExit(err),
-        // #610: /health's db check probes the path so monitoring + the #591
-        // adoption probe see a wipe instead of the ghost-fd lie.
-        probeDbPath: () => dbHolder.probePath(),
-        issuer,
-        loopbackPort: port,
-        supervisor,
+    server = Bun.serve(
+      hubServeOptions({
+        port,
+        hostname,
+        fetch: hubFetch(WELL_KNOWN_DIR, {
+          getDb: () => dbHolder.get(),
+          onDbError: (err) => dbHolder.healOrExit(err),
+          // #610: /health's db check probes the path so monitoring + the #591
+          // adoption probe see a wipe instead of the ghost-fd lie.
+          probeDbPath: () => dbHolder.probePath(),
+          issuer,
+          loopbackPort: port,
+          supervisor,
+        }),
       }),
-    });
+    );
   } catch (err) {
     const conflict = hubPortConflictMessage(err, port);
     if (conflict) throw new Error(conflict);

package/src/commands/setup.ts

@@ -109,13 +109,13 @@ function defaultAvailability(): InteractiveAvailability {
 
 /**
  * Survey the eligible services. We include the four first-party shortnames
- * (vault / notes / scribe / channel + runner) but flag channel as exploratory
+ * (vault / notes / scribe / agent + runner) but flag agent as exploratory
  * in the blurb so operators don't grab it by reflex. `installed` is true when
  * the service has a row in services.json.
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
  * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
- * (vault / scribe / runner / channel / surface) ship `.parachute/module.json`
+ * (vault / scribe / runner / 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.
  */
@@ -155,7 +155,8 @@ const BLURBS: Record<string, string> = {
   notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `app`)",
   scribe: "audio transcription for dictation + recordings",
   runner: "vault-as-job-substrate — scheduled claude -p against vault job notes",
-  channel: "(exploratory — may retire) notification fan-out across modules",
+  agent:
+    "(exploratory) chat with your Claude Code sessions — a channel per session (renamed from channel)",
 };
 
 function blurbFor(choice: ServiceChoice): string {