@openparachute/hub 0.7.7-rc.9 → 0.7.7

package/src/oauth-handlers.ts

@@ -418,13 +418,9 @@ function oauthErrorRedirect(
  * Keyed on the SHORT name (resolved from each services.json row via
  * `shortNameForManifest`) rather than the raw manifest name so a row written
  * under a legacy manifest name still counts as installed — e.g. an un-upgraded
- * `parachute-channel` row aliases to short `agent` (channel→agent rename
- * 2026-06-17), so `agent:send` is still correctly advertised until the daemon
- * re-registers under `parachute-agent`.
  */
 const OPTIONAL_MODULE_SCOPES: ReadonlyArray<readonly [prefix: string, short: string]> = [
   ["scribe:", "scribe"],
-  ["agent:", "agent"],
   ["surface:", "surface"],
 ];
 
@@ -1903,13 +1899,7 @@ export async function handleApproveClientPost(
     // Headers logged are non-sensitive (Origin/Referer/Host are public);
     // the bound set is hub's own configuration. Body content not logged.
     console.warn(
-      `[oauth] approve POST same-origin check failed. headers: ` +
-        `origin=${JSON.stringify(req.headers.get("origin"))} ` +
-        `referer=${JSON.stringify(req.headers.get("referer"))} ` +
-        `host=${JSON.stringify(req.headers.get("host"))} ` +
-        `xff-host=${JSON.stringify(req.headers.get("x-forwarded-host"))} ` +
-        `xff-proto=${JSON.stringify(req.headers.get("x-forwarded-proto"))}. ` +
-        `bound origins: ${JSON.stringify(bound)}`,
+      `[oauth] approve POST same-origin check failed. headers: origin=${JSON.stringify(req.headers.get("origin"))} referer=${JSON.stringify(req.headers.get("referer"))} host=${JSON.stringify(req.headers.get("host"))} xff-host=${JSON.stringify(req.headers.get("x-forwarded-host"))} xff-proto=${JSON.stringify(req.headers.get("x-forwarded-proto"))}. bound origins: ${JSON.stringify(bound)}`,
     );
     return htmlError(
       "Cross-origin request rejected",

package/src/operator-token.ts

@@ -104,7 +104,6 @@ export const OPERATOR_TOKEN_SCOPE_SETS: Readonly<Record<OperatorScopeSet, readon
     "parachute:host:vault",
     "vault:admin",
     "scribe:admin",
-    "agent:send",
   ],
 };
 

package/src/origin-check.ts

@@ -198,8 +198,8 @@ const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
  *
  * NOT belted, and why:
  *   - GET/HEAD/OPTIONS — read-shaped; the mint GETs
- *     (`/admin/host-admin-token`, `/admin/agent-token`,
- *     `/admin/module-token/<short>`, `/admin/vault-admin-token/<name>`)
+ *     (`/admin/host-admin-token`, `/admin/module-token/<short>`,
+ *     `/admin/vault-admin-token/<name>`)
  *     enforce GET-only with a 405 and their response bodies are unreadable
  *     cross-origin (no CORS on these routes).
  *   - Bearer-authed requests — a cross-site page cannot attach an

package/src/root-serve.ts

@@ -0,0 +1,156 @@
+#!/usr/bin/env bun
+
+/**
+ * Serving the Parachute app AT the hub's origin root (`root_mode = serve-app`).
+ *
+ * When an operator flips the root mode to `serve-app` (or a fresh hub installs
+ * the app during setup), the hub answers its own origin root with the installed
+ * `@openparachute/parachute-app` bundle instead of 302-ing to `/admin`. This is
+ * the self-hosted mirror of the hosted door: hit your box's URL, land in the
+ * app — no redirect hop.
+ *
+ * Why this is asset-correct with no rebuild: the app's Vite build is ROOT-based
+ * (absolute `/assets/*`, PWA scope `/`, OAuth redirect URIs at the origin root).
+ * The `/app` service mount serves the SAME dist through the `notes-serve.ts`
+ * shim with a `/app` prefix-strip; here we serve that identical dist verbatim at
+ * `/`, which is exactly the origin the build assumes. So `serveAppAtRoot` and
+ * the `/app` mount hand back byte-identical bundle files — the only difference
+ * is the URL prefix.
+ *
+ * Precedence is the caller's job (hub-server.ts): the fresh-hub setup wizard
+ * funnel and the pre-admin 503 lockout run BEFORE the root `/` handler, and
+ * every hub-owned route (/admin, /oauth, /.well-known, /vault, /git, /api,
+ * service mounts) dispatches BEFORE the SPA-fallback tail. This module only
+ * decides "given an already-unclaimed GET, does the app dist answer it?".
+ *
+ * NO chrome injection ever rides a root-served response — the app owns its whole
+ * page (same posture as the public/surface chrome opt-out). We build the
+ * responses here directly rather than routing through `decorateWithChrome`.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveNotesDistFrom } from "./notes-serve.ts";
+
+/** The npm package whose built `dist/` is the app front door. */
+export const APP_PACKAGE = "@openparachute/parachute-app";
+
+/**
+ * Namespaces that keep the hub's branded 404 even in serve-app mode. These are
+ * hub / protocol surfaces, never app client-side routes, so an SPA shell there
+ * would be wrong — and would mask a genuine 404 for an API/OAuth/well-known
+ * typo. (Real dist files never live under these prefixes anyway; this makes the
+ * "don't shell it" decision explicit rather than incidental.)
+ */
+export const ROOT_SERVE_RESERVED_PREFIXES: readonly string[] = [
+  "/api/",
+  "/oauth/",
+  "/.well-known/",
+];
+
+/**
+ * Build a resolver for the installed app's `dist/` directory.
+ *
+ * Resolution goes through the SAME `resolveNotesDistFrom` machinery the `/app`
+ * mount's static-serve shim uses (so root-serve and `/app` resolve to one dist).
+ * A SUCCESSFUL resolution is memoized for the process lifetime — a resolved dist
+ * path doesn't move while the hub runs, and re-walking `Bun.resolveSync` on every
+ * asset request would be needless work. A FAILURE is NOT cached: an operator who
+ * set `serve-app` before installing the app, then runs `parachute install app`,
+ * is picked up on the next request without a hub restart (dynamic recovery).
+ *
+ * `resolve` is the test seam (defaults to the real package resolution). Return
+ * value is the dist dir, or `null` when the app can't be resolved (not installed
+ * / ships no `dist/`).
+ */
+export function makeAppDistResolver(
+  resolve: () => string = () => resolveNotesDistFrom({ pkg: APP_PACKAGE }),
+): () => string | null {
+  let cached: string | null = null;
+  return () => {
+    if (cached !== null) return cached;
+    try {
+      cached = resolve();
+      return cached;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/** MIME overrides Bun.file doesn't infer (mirrors notes-serve.ts). */
+function mimeFor(path: string): string | undefined {
+  // Without this the PWA install prompt sees text/html for the manifest + bails.
+  if (path.endsWith(".webmanifest")) return "application/manifest+json";
+  return undefined;
+}
+
+/**
+ * Answer an already-unclaimed request from the app's root-based `dist/`, or
+ * return `null` to tell the caller to fall through to its normal handling
+ * (the `/` 302 fallback, or the branded 404 tail).
+ *
+ * Contract:
+ *   - non-GET                                     → null (fall through)
+ *   - a reserved hub/protocol prefix              → null (keep the branded 404)
+ *   - GET + an existing file under dist           → that file (asset-correct MIME)
+ *   - GET `/` or a trailing-slash "dir" request   → dist/index.html (SPA shell)
+ *   - GET + no file + Accept: text/html           → dist/index.html (SPA deep link)
+ *   - GET + no file + non-HTML (API probe, etc.)  → null (branded 404)
+ *
+ * `dist` is a resolved directory (from `makeAppDistResolver`); if its
+ * `index.html` has since vanished (app uninstalled after a successful resolve)
+ * we return `null` rather than serving a broken shell.
+ */
+export function serveAppAtRoot(dist: string, req: Request, pathname: string): Response | null {
+  // Only GET is served (HEAD/POST/etc. keep the caller's default — a non-GET to
+  // an unclaimed path stays a 404, and a non-GET `/` keeps its 302).
+  if (req.method !== "GET") return null;
+
+  // Hub/protocol namespaces are never the app's — leave their 404 branded.
+  for (const prefix of ROOT_SERVE_RESERVED_PREFIXES) {
+    if (pathname.startsWith(prefix)) return null;
+  }
+
+  const indexHtml = join(dist, "index.html");
+  // The resolved bundle lost its shell (uninstalled mid-flight) → fall through.
+  if (!existsSync(indexHtml)) return null;
+
+  const spaShell = () =>
+    new Response(Bun.file(indexHtml), {
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+
+  // Bare root or a trailing-slash "directory" request → the SPA shell.
+  if (pathname === "/" || pathname.endsWith("/")) return spaShell();
+
+  // An existing dist file: /assets/*, /icon.svg, /manifest.webmanifest, /sw.js …
+  // Malformed percent-encoding (e.g. `/foo%`, `/assets/%ZZ`) makes
+  // `decodeURIComponent` throw a URIError. Catch it and fall through to the
+  // branded 404 (redirect-mode parity) — WITHOUT the guard the throw escapes to
+  // the dispatch outer catch, which classifies a non-DB error as "other" and
+  // re-throws → a bare 500. This path is reachable pre-auth on a public expose,
+  // so a garbage-encoded asset URL must 404, never 500.
+  let decodedPath: string;
+  try {
+    decodedPath = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  // Path-traversal guard: the joined path must stay strictly under dist/.
+  const filePath = join(dist, decodedPath);
+  if (filePath.startsWith(`${dist}/`) && existsSync(filePath) && statSync(filePath).isFile()) {
+    const mime = mimeFor(filePath);
+    return new Response(
+      Bun.file(filePath),
+      mime ? { headers: { "content-type": mime } } : undefined,
+    );
+  }
+
+  // No matching file. Serve the SPA shell ONLY for HTML navigations (a deep link
+  // like /some-note the app routes client-side). A browser navigation sends
+  // `Accept: text/html`; a non-HTML unclaimed request (API probe, a missing
+  // asset fetched with `Accept: */*`) falls through to the branded 404.
+  const wantsHtml = (req.headers.get("accept") ?? "").includes("text/html");
+  return wantsHtml ? spaShell() : null;
+}

package/src/scope-explanations.ts

@@ -46,7 +46,7 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
       "Read and write everything, plus admin: config & settings, triggers & automation, GitHub backup, and minting access tokens.",
     level: "admin",
   },
-  // Optional-module scopes (scribe / agent / surface). These are in
+  // Optional-module scopes (scribe / surface). These are in
   // FIRST_PARTY_SCOPES (= Object.keys(this map)) but the modules may not be
   // installed — so they're GATED in `OPTIONAL_MODULE_SCOPES` (oauth-handlers.ts)
   // and only advertised in `scopes_supported` when the service is in
@@ -61,10 +61,7 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
     label: "Manage Scribe configuration (provider keys, models, quotas).",
     level: "admin",
   },
-  "agent:send": {
-    label: "Post messages to your Agent.",
-    level: "send",
-  },
+
   // Surface Git Transport scopes (surface-host). `surface:read` = clone/fetch a
   // surface's hub-hosted git repo; `surface:write` = push to it. Named forms
   // (`surface:<name>:<verb>`) collapse to these via the 3→2-segment rule in

package/src/service-spec.ts

@@ -8,7 +8,7 @@ import type { ServiceEntry } from "./services-manifest.ts";
  *
  *   1939  parachute-hub      internal static + proxy, CLI-managed
  *   1940  parachute-vault    committed core
- *   1941  parachute-agent    exploration (renamed from parachute-channel)
+ *   1941  unassigned
  *   1942  parachute-notes    committed core (PWA bundle)
  *   1943  parachute-scribe   committed core
  *   1944  parachute-app      the super-surface front door (PWA bundle,
@@ -70,7 +70,7 @@ export interface PortReservation {
 export const PORT_RESERVATIONS: readonly PortReservation[] = [
   { port: 1939, name: "parachute-hub", status: "assigned" },
   { port: 1940, name: "parachute-vault", status: "assigned" },
-  { port: 1941, name: "parachute-agent", status: "assigned" },
+  { port: 1941, name: "unassigned", status: "reserved" },
   { port: 1942, name: "parachute-notes", status: "assigned" },
   { port: 1943, name: "parachute-scribe", status: "assigned" },
   // hub-parity P5 (2026-07-11): parachute-app's canonical slot — the NEW
@@ -382,8 +382,9 @@ const APP_FALLBACK: FirstPartyFallback = {
     postInstallFooter: () => [
       "",
       "Open your Parachute at <origin>/app — it signs in with your hub account.",
-      "The hub's front page (`/`) now opens the app too, unless you've already",
-      "set a custom root redirect (`parachute hub set-root-redirect` or the admin SPA).",
+      "The hub's front page (`/`) now serves the app directly too, unless you've",
+      "already customized the root (`parachute hub set-root-mode` / `set-root-redirect`",
+      "or the admin SPA).",
     ],
   },
 };
@@ -510,8 +511,8 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
     },
   },
   // NOTE (2026-07-01): `runner` was REMOVED from this registry (decision:
-  // Aaron 2026-07-01 — the module set of record is vault / hub / agent /
-  // scribe / surface). Runner is no longer offered, installable, or
+  // Aaron 2026-07-01 — the module set of record is vault / hub / scribe /
+  // surface). Runner is no longer offered, installable, or
   // lifecycle-addressable by short name from the hub's bootstrap registries.
   // Existing installs stay GRACEFUL: a legacy `parachute-runner` services.json
   // row is handled exactly like any unknown/third-party row — `parachute
@@ -520,29 +521,7 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
   // stamped and logs-and-skips otherwise. Deliberately NOT added to
   // RETIRED_MODULES: that registry GC-drops rows on load, which would break
   // routing for operators still running the runner daemon.
-  agent: {
-    short: "agent",
-    package: "@openparachute/agent",
-    manifestName: "parachute-agent",
-    canonicalPort: 1941,
-    displayName: "Agent",
-    // Mirrors agent's own module.json (the canonical fields below do too —
-    // keep in sync if agent's declaration changes). Renamed from `channel`
-    // 2026-06-17 (parachute-channel → parachute-agent); the module is the
-    // same webhook-fan-out + MCP bridge daemon, on the same port 1941.
-    tagline: "Chat with your Claude Code sessions — a channel per session.",
-    canonicalPaths: ["/agent"],
-    canonicalHealth: "/health",
-    canonicalStripPrefix: true,
-    extras: {
-      // Backward-compat startCmd for rows without installDir — same rationale
-      // as scribe / vault. The bare binary IS the daemon (agent's
-      // package.json bin maps `parachute-agent` → src/daemon.ts).
-      startCmd: () => ["parachute-agent"],
-      // Agent gates its endpoints behind hub-issued JWTs (agent:* scopes).
-      hasAuth: true,
-    },
-  },
+
   surface: {
     short: "surface",
     package: "@openparachute/surface",
@@ -603,20 +582,14 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
  *     entries (no successor reusing the name) still stay forever.
  */
 export const RETIRED_MODULES: Record<string, { retiredAt: string; replacement?: string }> = {
-  // NOTE (2026-06-17, channel→agent rename): the `agent` / `parachute-agent`
-  // names were retired here on 2026-05-20 (the Claude-in-containers module).
-  // They are NOW RE-ASSIGNED to the renamed channel module (parachute-channel
-  // → parachute-agent). Keeping these as RETIRED entries would make
-  // `dropRetiredModuleRows` drop the NEW agent module's services.json row on
-  // load — breaking the live module. The names are no longer retired; they
-  // belong to the active agent module. The retired containers code now lives
-  // under `parachute-agent-legacy` (GitHub) and is not installable, so there
-  // is no live `agent` daemon to GC. (The historical `claw → agent`
-  // migration in services-manifest.ts still rewrites stale paraclaw rows to
-  // `name: "agent"` — they now resolve to the LIVE agent module's mount,
-  // which is harmless / arguably correct since paraclaw was the original
-  // "agent".)
-  //
+  agent: { retiredAt: "2026-07-15", replacement: "Vault and Surface" },
+  channel: { retiredAt: "2026-07-15", replacement: "Vault and Surface" },
+  "parachute-agent": { retiredAt: "2026-07-15", replacement: "Vault and Surface" },
+  "parachute-channel": { retiredAt: "2026-07-15", replacement: "Vault and Surface" },
+  // Agent was removed from Hub on 2026-07-15. All historical service-row
+  // identities are retired so normal manifest reads stop routing or supervising
+  // the deprecated daemon. Generic AI-agent authorization grants/tokens are a
+  // separate Hub capability and remain supported.
   // NOTE (2026-07-11, hub-parity P5 — `app` / `parachute-app` UN-RETIRED):
   // this table carried `app` + `parachute-app` (retired 2026-05-27, the
   // app → surface rename, patterns#102) from hub#219 through hub-parity P4.
@@ -716,8 +689,7 @@ export function knownServices(): string[] {
  *
  *   - `core` — vault / scribe / hub / surface / app (the product surface;
  *     `app` joined 2026-07-11, hub-parity P5 — the super-surface front door).
- *   - `experimental` — agent (legit preview; still OFFERED on a fresh install)
- *     + any unlisted third-party short.
+ *   - `experimental` — any unlisted third-party short.
  *   - `deprecated` — notes (notes-daemon deprecated 2026-05-22; notes-ui moved
  *     into parachute-surface). Still RESOLVABLE (discoverableShorts unchanged)
  *     and SHOWN-IF-INSTALLED so an existing operator can manage/uninstall, but
@@ -734,7 +706,7 @@ const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
   hub: "core",
   surface: "core",
   app: "core",
-  agent: "experimental",
+
   notes: "deprecated",
 };
 
@@ -931,7 +903,6 @@ export async function getSpecFromInstallDir(
  */
 const LEGACY_MANIFEST_ALIASES: Record<string, string> = {
   "parachute-lens": "notes",
-  "parachute-channel": "agent",
 };
 
 /** Short name for a given manifest name, e.g. `parachute-vault` → `vault`.

package/src/services-manifest.ts

@@ -692,10 +692,9 @@ export function readManifest(path: string = SERVICES_MANIFEST_PATH): ServicesMan
   const afterRetired = dropRetiredModuleRows(healed.raw, path);
   const cleaned = dropLegacyShortNameRows(afterRetired.raw, path);
   const validated = validateManifest(cleaned.raw, path);
-  const migrated = migrateClawToAgent(validated);
-  const changed = healed.changed || afterRetired.changed || cleaned.changed || migrated.changed;
-  if (changed) writeManifest(migrated.manifest, path);
-  return migrated.manifest;
+  const changed = healed.changed || afterRetired.changed || cleaned.changed;
+  if (changed) writeManifest(validated, path);
+  return validated;
 }
 
 /**
@@ -732,7 +731,12 @@ function dropRetiredModuleRows(raw: unknown, where: string): { raw: unknown; cha
     if (!row || typeof row !== "object") return true;
     const name = (row as Record<string, unknown>).name;
     if (typeof name !== "string") return true;
-    const retired = RETIRED_MODULES[name];
+    // `claw` is too generic to reserve globally, but the historical Agent row
+    // had a structural identity: name=claw mounted at /claw. Retire only that
+    // shape; an unrelated third-party `claw` on another mount remains valid.
+    const paths = (row as Record<string, unknown>).paths;
+    const retiredClawShape = name === "claw" && Array.isArray(paths) && paths[0] === "/claw";
+    const retired = RETIRED_MODULES[name] ?? (retiredClawShape ? RETIRED_MODULES.agent : undefined);
     if (retired === undefined) return true;
     dropped.push({ name, retiredAt: retired.retiredAt, replacement: retired.replacement });
     return false;
@@ -929,43 +933,6 @@ function dropLegacyShortNameRows(raw: unknown, where: string): { raw: unknown; c
   };
 }
 
-/**
- * Migrate legacy `claw` entries to `agent` in-place. Paraclaw was renamed
- * to parachute-agent across the ecosystem (npm package, mount path, short
- * name); operators who upgraded hub but still have the old paraclaw row
- * in services.json would otherwise see a tile labelled "Claw" and a hub
- * route at `/claw` while their newly-upgraded daemon listens on `/agent`.
- *
- * Idempotent. Only rewrites when both `name === "claw"` AND the first path
- * is `/claw` — narrow enough that a deliberately-named third-party module
- * (e.g. `name: "claw"` on a different mount) is left alone. Health and any
- * `/claw`-rooted paths are rewritten in lockstep.
- */
-function migrateClawToAgent(manifest: ServicesManifest): {
-  manifest: ServicesManifest;
-  changed: boolean;
-} {
-  let changed = false;
-  const services = manifest.services.map((entry) => {
-    if (entry.name !== "claw" || entry.paths[0] !== "/claw") return entry;
-    changed = true;
-    const next: ServiceEntry = {
-      ...entry,
-      name: "agent",
-      paths: entry.paths.map((p) => rewriteClawPath(p)),
-      health: rewriteClawPath(entry.health),
-    };
-    return next;
-  });
-  return { manifest: { services }, changed };
-}
-
-function rewriteClawPath(p: string): string {
-  if (p === "/claw") return "/agent";
-  if (p.startsWith("/claw/")) return `/agent${p.slice("/claw".length)}`;
-  return p;
-}
-
 export function writeManifest(
   manifest: ServicesManifest,
   path: string = SERVICES_MANIFEST_PATH,