@openparachute/hub 0.7.6 → 0.7.7-rc.12

package/src/notes-serve.ts

@@ -1,15 +1,19 @@
 #!/usr/bin/env bun
 
 /**
- * Tiny static-file server for the @openparachute/notes PWA bundle.
+ * Tiny static-file server for a Parachute PWA bundle — originally written
+ * for @openparachute/notes, generalized in hub-parity P5 (2026-07-11) to
+ * also serve @openparachute/parachute-app (the super-surface front door,
+ * port 1944, mount `/app`) via the same shim. Any package matching this
+ * shape (a prebuilt SPA `dist/` with no server of its own) can reuse it.
  *
- * Notes is a SPA — no backend of its own. `parachute start notes` invokes
- * this shim with the installed `dist/` path so the PWA is served at a
- * known port and can be reverse-proxied by `parachute expose` alongside
- * the other services.
+ * A served bundle is a SPA — no backend of its own. `parachute start
+ * <svc>` invokes this shim with the installed `dist/` path so the PWA is
+ * served at a known port and can be reverse-proxied by `parachute expose`
+ * alongside the other services.
  *
  * Invoked as:
- *   bun <this-file> --port <n> [--dist <path>] [--mount <prefix>]
+ *   bun <this-file> --port <n> [--dist <path>] [--mount <prefix>] [--package <npmName>]
  *
  * `--mount` (default `/notes`) is the path prefix the reverse proxy hands
  * us. We strip it before resolving against `dist/` so a request for
@@ -17,27 +21,43 @@
  * `{dist}/notes/sw.js`. Without the strip, the SW + .webmanifest both
  * SPA-fall-back to index.html with content-type text/html, and the PWA
  * install prompt never fires. Pass `--mount ""` (or `--mount /`) when the
- * bundle is served at the origin root.
+ * bundle is served at the origin root. THIS IS LOAD-BEARING for every
+ * package served by this shim, not just notes — keep it exactly as-is.
  *
- * If --dist is omitted, we resolve @openparachute/notes's dist directory
- * via Bun.resolveSync. If that fails (package not installed globally, or
+ * `--package` (default `@openparachute/notes`, back-compat) names the npm
+ * package whose `dist/` we resolve when `--dist` is omitted. Passed by
+ * FIRST_PARTY_FALLBACKS entries whose startCmd composes this shim for a
+ * package other than notes (e.g. `app`'s `--package @openparachute/parachute-app`).
+ *
+ * If --dist is omitted, we resolve the package's dist directory via
+ * Bun.resolveSync. If that fails (package not installed globally, or
  * package doesn't ship dist/), exit 1 with a clear error.
+ *
+ * `/health` (post-mount-strip) always answers 2xx — the doctor/status
+ * probe (`probeModuleHealth`) only cares about the status code, but we
+ * answer explicitly rather than relying on the SPA-shell catch-all so a
+ * missing/corrupt `dist/index.html` can't take the health check down with it.
  */
 
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
+/** Back-compat default — the shim's original (and still primary) consumer. */
+const DEFAULT_PACKAGE = "@openparachute/notes";
+
 interface Args {
   port: number;
   dist?: string;
   mount: string;
+  pkg: string;
 }
 
 function parseArgs(argv: string[]): Args {
   let port = 5173;
   let dist: string | undefined;
   let mount = "/notes";
+  let pkg = DEFAULT_PACKAGE;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--port") {
@@ -56,11 +76,15 @@ function parseArgs(argv: string[]): Args {
       const v = argv[++i];
       if (v === undefined) throw new Error("--mount requires a value");
       mount = normalizeMount(v);
+    } else if (a === "--package") {
+      const v = argv[++i];
+      if (!v) throw new Error("--package requires a value");
+      pkg = v;
     } else {
       throw new Error(`unknown argument: ${a}`);
     }
   }
-  return { port, dist, mount };
+  return { port, dist, mount, pkg };
 }
 
 export function normalizeMount(raw: string): string {
@@ -70,22 +94,22 @@ export function normalizeMount(raw: string): string {
 
 /**
  * Candidate base directories that `Bun.resolveSync` walks from when looking
- * for `@openparachute/notes/package.json`. Order matters:
+ * for `<package>/package.json`. Order matters:
  *
- *   1. `process.cwd()` — works when notes-serve is invoked from inside the
- *      notes checkout (e.g. via `installDir` cwd in lifecycle.ts) or from
- *      any project that depends on `@openparachute/notes`.
+ *   1. `process.cwd()` — works when the shim is invoked from inside the
+ *      package's own checkout (e.g. via `installDir` cwd in lifecycle.ts) or
+ *      from any project that depends on the package.
  *   2. `~/.bun/install/global/node_modules` — modern Bun's global-install
- *      layout. This is where `bun add -g @openparachute/notes` lands the
- *      package, and where `bun link @openparachute/notes` symlinks it.
+ *      layout. This is where `bun add -g <package>` lands the package, and
+ *      where `bun link <package>` symlinks it.
  *   3. `~/.bun/install/global` — defensive fallback for older Bun layouts.
  *
- * Hub itself does NOT depend on `@openparachute/notes`, so when
- * `parachute start notes` is run from the hub repo dir, the cwd-relative
- * resolve walks ancestral node_modules and finds nothing. Bun does not
- * auto-consult the global install dir, so bun-linked installs fail to
- * resolve without (2)/(3). hub#194: Aaron hit silent 502 on tailnet
- * `/notes/` because of this — fixed by trying the global install dirs.
+ * Hub itself does NOT depend on the served package, so when `parachute
+ * start <svc>` is run from the hub repo dir, the cwd-relative resolve walks
+ * ancestral node_modules and finds nothing. Bun does not auto-consult the
+ * global install dir, so bun-linked installs fail to resolve without
+ * (2)/(3). hub#194: Aaron hit silent 502 on tailnet `/notes/` because of
+ * this — fixed by trying the global install dirs.
  *
  * Exported (and parameterized via `cwd`/`home`) so tests can drive the
  * resolution order against a real fixture install without monkey-patching
@@ -98,6 +122,8 @@ export function notesDistCandidates(cwd: string, home: string): string[] {
 export interface ResolveNotesDistDeps {
   cwd?: string;
   home?: string;
+  /** npm package name to resolve. Defaults to `@openparachute/notes` (back-compat). */
+  pkg?: string;
   /** Override `Bun.resolveSync` for tests. */
   resolveSync?: (specifier: string, base: string) => string;
   existsSync?: (path: string) => boolean;
@@ -106,6 +132,7 @@ export interface ResolveNotesDistDeps {
 export function resolveNotesDistFrom(deps: ResolveNotesDistDeps = {}): string {
   const cwd = deps.cwd ?? process.cwd();
   const home = deps.home ?? homedir();
+  const pkg = deps.pkg ?? DEFAULT_PACKAGE;
   const resolveSync = deps.resolveSync ?? Bun.resolveSync;
   const exists = deps.existsSync ?? existsSync;
   const candidates = notesDistCandidates(cwd, home);
@@ -113,7 +140,7 @@ export function resolveNotesDistFrom(deps: ResolveNotesDistDeps = {}): string {
   for (const base of candidates) {
     let pkgPath: string;
     try {
-      pkgPath = resolveSync("@openparachute/notes/package.json", base);
+      pkgPath = resolveSync(`${pkg}/package.json`, base);
     } catch (err) {
       resolveErrors.push(`  - ${base}: ${err instanceof Error ? err.message : String(err)}`);
       continue;
@@ -126,18 +153,18 @@ export function resolveNotesDistFrom(deps: ResolveNotesDistDeps = {}): string {
       // other candidates — they'd resolve to the same package and report
       // the same problem.
       throw new Error(
-        `@openparachute/notes resolved at ${root} has no dist/ directory at ${dist}. The package may not ship a prebuilt bundle — ask the notes maintainer to add a prepublishOnly build step.`,
+        `${pkg} resolved at ${root} has no dist/ directory at ${dist}. The package may not ship a prebuilt bundle — ask the ${pkg} maintainer to add a prepublishOnly build step.`,
       );
     }
     return dist;
   }
   throw new Error(
-    `Could not resolve @openparachute/notes from any of:\n${resolveErrors.join("\n")}\nIs the package installed? Try \`bun add -g @openparachute/notes\` or \`parachute install notes\`.`,
+    `Could not resolve ${pkg} from any of:\n${resolveErrors.join("\n")}\nIs the package installed? Try \`bun add -g ${pkg}\` or the matching \`parachute install <short>\`.`,
   );
 }
 
-function resolveNotesDist(): string {
-  return resolveNotesDistFrom();
+function resolveNotesDist(pkg: string): string {
+  return resolveNotesDistFrom({ pkg });
 }
 
 function mimeFor(path: string): string | undefined {
@@ -160,6 +187,17 @@ export function notesFetch(dist: string, mount: string): (req: Request) => Respo
     if (mount && (pathname === mount || pathname.startsWith(`${mount}/`))) {
       pathname = pathname.slice(mount.length) || "/";
     }
+    if (pathname === "/health") {
+      // Explicit rather than falling through to the SPA shell: the doctor /
+      // status probe (`probeModuleHealth`) only checks for a 2xx status, but
+      // answering directly means a missing/corrupt `dist/index.html` can't
+      // take the health check down with it. Every FIRST_PARTY_FALLBACKS
+      // entry served by this shim declares `health` under its own mount
+      // (e.g. `/notes/health`, `/app/health`) — this answers all of them.
+      return new Response(JSON.stringify({ status: "ok" }), {
+        headers: { "content-type": "application/json" },
+      });
+    }
     if (pathname === "/" || pathname.endsWith("/")) {
       return spaShell();
     }
@@ -200,17 +238,21 @@ export function notesServeOptions(
 }
 
 if (import.meta.main) {
-  const { port, dist: distArg, mount } = parseArgs(process.argv.slice(2));
+  const { port, dist: distArg, mount, pkg } = parseArgs(process.argv.slice(2));
 
   let dist: string;
   try {
-    dist = distArg ?? resolveNotesDist();
+    dist = distArg ?? resolveNotesDist(pkg);
   } catch (err) {
-    console.error(`parachute-notes-serve: ${err instanceof Error ? err.message : String(err)}`);
+    console.error(
+      `parachute-static-serve (${pkg}): ${err instanceof Error ? err.message : String(err)}`,
+    );
     process.exit(1);
   }
 
   Bun.serve(notesServeOptions(port, dist, mount));
 
-  console.log(`notes static-serve listening on :${port} (dist=${dist}, mount=${mount || "/"})`);
+  console.log(
+    `static-serve listening on :${port} (pkg=${pkg}, dist=${dist}, mount=${mount || "/"})`,
+  );
 }

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/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
@@ -112,8 +109,34 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
     label: "Administer vaults on this host (create, configure, delete).",
     level: "admin",
   },
+  // Account scopes (Parachute App campaign, Phase 2 — the `/account/*` door
+  // contract). `account:<id>:admin` authorizes every account mutation
+  // (create/delete/import vaults, mint per-vault tokens, set caps); `:read`
+  // authorizes the read side (list vaults, read caps/usage). On a self-host
+  // hub `<id>` is the sentinel `self` (account ≡ box). These are minted ONLY
+  // by the cookie→bearer `POST /account/token` exchange, NEVER via the public
+  // OAuth flow — they're in NON_REQUESTABLE_SCOPES below, like the host scopes.
+  // Listed here (a) so `NON_REQUESTABLE_SCOPES ⊆ FIRST_PARTY_SCOPES` holds and
+  // (b) so scope-guard's `admin ⊇ read` inheritance recognizes the grammar
+  // (`account:self:admin` satisfies `account:self:read`).
+  "account:self:admin": {
+    label:
+      "Manage your Parachute account — create, delete, and configure your vaults, and mint access tokens for them.",
+    level: "admin",
+  },
+  "account:self:read": {
+    label: "View your Parachute account — list your vaults and read their settings and usage.",
+    level: "read",
+  },
 };
 
+/** Account scope strings (Parachute App campaign, Phase 2). Exported so the
+ * `POST /account/token` mint and the `/account/*` route gates reference the
+ * canonical constants rather than re-literaling the strings. `self` is the
+ * self-host account sentinel (account ≡ box). */
+export const ACCOUNT_SELF_ADMIN_SCOPE = "account:self:admin";
+export const ACCOUNT_SELF_READ_SCOPE = "account:self:read";
+
 /**
  * Sorted list of every first-party scope the hub recognizes. Used as the
  * baseline for `scopes_supported` in the OAuth-AS metadata; module-declared
@@ -170,6 +193,13 @@ export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set([
   // Service-admin scopes: operator-only, never requestable via /oauth/authorize.
   "hub:admin",
   "scribe:admin",
+  // Account scopes (Parachute App campaign, Phase 2): cookie-minted only via
+  // `POST /account/token`, NEVER OAuth-requestable. A third-party app pointed
+  // at the hub AS must not be able to consent its way to account authority
+  // (create/delete vaults, mint per-vault tokens) — the account credential is
+  // exclusively the same-origin app's cookie→bearer exchange.
+  ACCOUNT_SELF_ADMIN_SCOPE,
+  ACCOUNT_SELF_READ_SCOPE,
 ]);
 
 /**

package/src/service-spec.ts

@@ -8,10 +8,16 @@ 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–1949  unassigned
+ *   1944  parachute-app      the super-surface front door (PWA bundle,
+ *                            hub-parity P5) — see the PORT_RESERVATIONS
+ *                            comment below for why this is a DIFFERENT
+ *                            module from the pre-2026-05-27 `app`
+ *   1945  unassigned
+ *   1946  parachute-surface  UI host (renamed from `app` 2026-05-27)
+ *   1947–1949  unassigned
  *
  * Hub pins 1939: `parachute expose` composes hub targets as
  * `http://127.0.0.1:1939/` and that URL has to be stable across machines for
@@ -64,15 +70,27 @@ 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" },
-  { port: 1944, name: "unassigned", status: "reserved" },
+  // hub-parity P5 (2026-07-11): parachute-app's canonical slot — the NEW
+  // super-surface front door (@openparachute/parachute-app), landing as a
+  // FIRST_PARTY_FALLBACKS entry (short "app") with its own hub-side static-
+  // serve shim (notes-serve.ts --package). This is a DIFFERENT, unrelated
+  // module from the pre-2026-05-27 `app` package described in the 1946
+  // comment below — the two just happen to share the name across a rename.
+  // Status `assigned` keeps the fallback-port walker (`assignPort` in
+  // port-assign.ts) from handing this port to a colliding third-party
+  // module.
+  { port: 1944, name: "parachute-app", status: "assigned" },
   { port: 1945, name: "unassigned", status: "reserved" },
-  // hub#323: parachute-app's canonical slot. Status `assigned` keeps the
-  // fallback-port walker (`assignPort` in port-assign.ts) from handing this
-  // port out to a colliding third-party module. The matching KNOWN_MODULES
-  // row carries the canonicalPort + paths for status/expose surfaces.
+  // hub#323 (historical): this WAS `parachute-app`'s canonical slot back
+  // when "app" meant the UI-host module. That module renamed to
+  // `parachute-surface` 2026-05-27 (patterns#102); port 1944 above is the
+  // different, new parachute-app (super-surface) from hub-parity P5. Status
+  // `assigned` keeps the fallback-port walker from handing 1946 to a
+  // colliding third-party module. The matching KNOWN_MODULES row carries
+  // the canonicalPort + paths for status/expose surfaces.
   { port: 1946, name: "parachute-surface", status: "assigned" },
   { port: 1947, name: "unassigned", status: "reserved" },
   { port: 1948, name: "unassigned", status: "reserved" },
@@ -278,9 +296,15 @@ export function composeServiceSpec(opts: {
 //     — its startCmd is composed from the services.json entry's port + mount,
 //     which is hub-side logic, not something notes itself runs. (The archive
 //     isn't done — notes-daemon Phase 3 retirement hasn't landed.)
+//   - app: the NEW super-surface front door (@openparachute/parachute-app,
+//     hub-parity P5, 2026-07-11) — same shape as notes: a frontend bundle
+//     with no server of its own, served by the SAME hub-side shim
+//     (`notes-serve.ts --package @openparachute/parachute-app`). Unrelated
+//     to the pre-2026-05-27 `app` package that renamed to `surface` (see
+//     the KNOWN_MODULES.surface tagline + the RETIRED_MODULES note below).
 //
-// The remaining entry keeps its "FALLBACK: Delete when …" marker so the
-// next cleanup pass is a one-grep operation.
+// Each entry keeps its "FALLBACK: Delete when …" marker so the next cleanup
+// pass is a one-grep operation.
 // ---------------------------------------------------------------------------
 
 // FALLBACK: Delete when @openparachute/notes ships .parachute/module.json AND
@@ -317,11 +341,58 @@ const NOTES_FALLBACK: FirstPartyFallback = {
   },
 };
 
+// FALLBACK: Delete when @openparachute/parachute-app ships
+// .parachute/module.json AND self-registers its services.json row at boot.
+// As of hub-parity P5 the app repo doesn't carry the real module.json yet —
+// only a stale `dist/.parachute/info` artifact (name: "parachute-notes")
+// left over from seeding the app off notes-ui, which is a DIFFERENT file
+// (module-manifest.ts's runtime `/.parachute/info`, not the static
+// `.parachute/module.json` contract this fallback stands in for) and
+// doesn't block this fallback path. parachute-app is a frontend bundle (the
+// super-surface front door) with no server of its own, so — same as notes —
+// its startCmd is hub-side logic composed from the services.json entry
+// (port + mount), running through the SAME `notes-serve.ts` shim
+// generalized in hub-parity P5 via `--package`.
+const APP_FALLBACK: FirstPartyFallback = {
+  package: "@openparachute/parachute-app",
+  manifest: {
+    name: "app",
+    manifestName: "parachute-app",
+    displayName: "Parachute",
+    tagline: "The Parachute app — your parachute's front door.",
+    port: 1944,
+    paths: ["/app"],
+    health: "/app/health",
+  },
+  extras: {
+    startCmd: (entry) => {
+      const first = entry.paths[0] ?? "/app";
+      const mount = first === "/" ? "" : first.replace(/\/+$/, "");
+      return [
+        "bun",
+        NOTES_SERVE_PATH,
+        "--port",
+        String(entry.port),
+        "--mount",
+        mount,
+        "--package",
+        "@openparachute/parachute-app",
+      ];
+    },
+    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).",
+    ],
+  },
+};
+
 /**
  * Vendored manifests + extras for first-party modules that still need them.
  * Indexed by short name (the `parachute install <X>` token).
  *
- * Only notes remains — see the block comment above for the rationale
+ * notes + app remain — see the block comment above for the rationale
  * (vault/scribe/agent now self-register and ship their own
  * module.json). Other code paths consult both this table AND `KNOWN_MODULES`
  * (which carries the post-self-register-retirement entries) via the helpers
@@ -329,6 +400,7 @@ const NOTES_FALLBACK: FirstPartyFallback = {
  */
 export const FIRST_PARTY_FALLBACKS: Record<string, FirstPartyFallback> = {
   notes: NOTES_FALLBACK,
+  app: APP_FALLBACK,
 };
 
 /**
@@ -438,8 +510,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
@@ -448,29 +520,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",
@@ -520,39 +570,43 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
  *     legacy operators. `notes` (the daemon) is the canonical
  *     "deprecating-but-not-retired" case as of 2026-05-22: do not add
  *     until its Phase 3 retirement lands.
- *   - Entries stay forever. Removing an entry would let a stale row
- *     reappear silently on legacy installs.
+ *   - Entries stay forever — UNLESS the retired name is later reclaimed by a
+ *     genuinely new, unrelated module that needs to self-register under it
+ *     for real (see the `app` / `parachute-app` un-retirement note below).
+ *     That's the one case where removal is correct: keeping a retirement
+ *     entry alongside a live FIRST_PARTY_FALLBACKS/KNOWN_MODULES entry of
+ *     the SAME name would make `dropRetiredModuleRows` GC the live module's
+ *     own services.json row on every read — an outright regression, not a
+ *     conservative default. Ordinary "this module is genuinely gone"
+ *     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".)
-  //
-  // The `parachute-app` row name retires 2026-05-27 along with the
-  // app → surface rename (patterns#102). Operators upgrading from
-  // 0.5.13-stable will have a `parachute-app` row in services.json
-  // pointing at the now-removed @openparachute/app package; this entry
-  // drops it on load + steers them at `parachute install surface`.
-  // The short-name `app` form is included for legacy rows that used
-  // the short name as the `name` field.
-  app: {
-    retiredAt: "2026-05-27",
-    replacement: "parachute-surface (renamed from parachute-app — `parachute install surface`)",
-  },
-  "parachute-app": {
-    retiredAt: "2026-05-27",
-    replacement: "parachute-surface (renamed from parachute-app — `parachute install surface`)",
-  },
+  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.
+  // They are REMOVED as of this note: a NEW, unrelated module — the real
+  // `@openparachute/parachute-app` super-surface front door (see
+  // FIRST_PARTY_FALLBACKS.app + PORT_RESERVATIONS' port-1944 comment) —
+  // claims the `parachute-app` manifestName (and the bare `app` short) for
+  // real. Keeping these entries would make `dropRetiredModuleRows`
+  // unconditionally GC the new module's services.json row on every read,
+  // breaking it outright — see the curation-rule exception above. An
+  // operator with a genuinely stale PRE-2026-05-27 `app`/`parachute-app` row
+  // (from the old, now-defunct @openparachute/app package) is handled the
+  // same as any other unrecognized row once un-retired: `parachute status`
+  // renders it, and `parachute serve` boots it via installDir's
+  // module.json if present and logs-and-skips otherwise — the same
+  // graceful fallback the `runner` registry removal (2026-07-01, see
+  // KNOWN_MODULES below) relies on. In practice the real parachute-app
+  // module's own first boot overwrites any stale row sharing its name.
 };
 
 /**
@@ -632,9 +686,9 @@ export function knownServices(): string[] {
  * manifest-declared `focus`; this map is the fallback when `module.json` omits
  * it (and the bootstrap value before a module is installed).
  *
- *   - `core` — vault / scribe / hub / surface (the product surface).
- *   - `experimental` — agent (legit preview; still OFFERED on a fresh install)
- *     + any unlisted third-party short.
+ *   - `core` — vault / scribe / hub / surface / app (the product surface;
+ *     `app` joined 2026-07-11, hub-parity P5 — the super-surface front door).
+ *   - `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
@@ -650,7 +704,8 @@ const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
   scribe: "core",
   hub: "core",
   surface: "core",
-  agent: "experimental",
+  app: "core",
+
   notes: "deprecated",
 };
 
@@ -738,7 +793,7 @@ export function canonicalPortForManifest(manifestName: string): number | undefin
 /**
  * Resolve the runtime spec for a known short name.
  *
- * FIRST_PARTY_FALLBACKS shorts (notes) return a fully-composed
+ * FIRST_PARTY_FALLBACKS shorts (notes / app) return a fully-composed
  * spec with embedded manifest + extras — the vendored manifest is the
  * source of truth pre-install and the install path preserves it through.
  *
@@ -847,11 +902,10 @@ 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`.
- *  Consults both FIRST_PARTY_FALLBACKS (notes) and KNOWN_MODULES
+ *  Consults both FIRST_PARTY_FALLBACKS (notes / app) and KNOWN_MODULES
  *  (vault / scribe / agent / surface — post-FALLBACK-retirement).
  *  Returns undefined for unknown manifests. */
 export function shortNameForManifest(manifestName: string): string | undefined {