@openparachute/hub 0.7.6 → 0.7.7-rc.13

package/src/hub-settings.ts

@@ -92,6 +92,16 @@ export type HubSettingKey =
   // the deprecation window. Stored as the literal string "true" /
   // "false"; any other value parses as "redirect on" (the migration
   // default — operators must opt out, not opt in).
+  //
+  // Mount vocabulary post-W2-12: `/surface/notes` is the LEGACY notes-ui
+  // mount (what existing installs serve — this redirect's target);
+  // `/surface/parachute` is the app's surface mount under its renamed
+  // identity. A separate CONDITIONAL alias (surface-notes-alias.ts, no
+  // hub_settings row — it keys off the manifest's uis{} mounts) bridges
+  // `/surface/notes/*` → `/surface/parachute/*` only on installs where
+  // the legacy mount is gone and the new one exists, so the two
+  // redirects compose for post-rename installs: /notes/x →
+  // /surface/notes/x → /surface/parachute/x.
   | "notes_redirect_disabled"
   // Admin-UI screen-lock PIN (hub admin-lock feature). The argon2id hash of
   // the operator's lock PIN. Absent row = lock feature OFF (today's behavior
@@ -122,7 +132,40 @@ export type HubSettingKey =
   // wizard funnel + pre-admin 503 lockout run BEFORE this redirect, so a
   // not-yet-set-up hub still lands on setup, not a surface that can't work
   // yet.
-  | "root_redirect";
+  | "root_redirect"
+  // hub: how the hub answers its origin root. `"redirect"` (default / absent)
+  // is the historical behavior — the bare `/` 302s to `root_redirect` (a safe
+  // same-origin path, default `/admin`). `"serve-app"` makes the hub SERVE the
+  // installed Parachute app's built bundle AT the origin root (index.html at
+  // `/`, its assets from the same dist, SPA-fallback for HTML deep links) — the
+  // same front-door experience as the hosted door, no redirect hop. The app's
+  // build is root-based (absolute `/assets`, PWA scope `/`, root OAuth redirect
+  // URIs) so serving its dist verbatim at `/` is asset-correct with no rebuild.
+  //
+  // Precedence on each request (resolveRootMode): this row, then
+  // `PARACHUTE_HUB_ROOT_MODE` env, then the `"redirect"` default. DB-first (like
+  // `root_redirect`) so an operator can flip the front door from the admin SPA /
+  // CLI without a redeploy. When `serve-app` is set but the app isn't installed
+  // (its dist can't be resolved), the hub FALLS BACK to redirect behavior (using
+  // `root_redirect` → env → `/admin`) with a one-time log line — so an operator
+  // who set the mode before installing the app never sees a broken root. The
+  // fresh-hub wizard funnel + pre-admin 503 lockout still run BEFORE this, so a
+  // not-yet-set-up hub lands on setup, never a half-working app shell.
+  | "root_mode"
+  // hub-parity P2 (Q2): the RAW token of the newest PUBLIC (multi-use,
+  // `max_uses > 1`) invite — persisted so `GET /.well-known/parachute-account`
+  // can advertise `signup_path` without being able to reconstruct it from the
+  // `invites` table (which stores only `sha256(token)`, see invites.ts's
+  // module doc). Written by `api-invites.ts`'s `handleCreateInvite` right
+  // after a successful multi-use `issueInvite`; read (and lazily cleared once
+  // stale) by `invites.ts`'s `activePublicSignupPath`.
+  //
+  // This does NOT weaken the hash-only posture of single-use friend invites
+  // (`max_uses === 1`, the default) — those NEVER write this row. A
+  // multi-use link is, by construction, the operator's deliberately PUBLIC
+  // signup page (minted to broadcast), so persisting its raw token is no
+  // more sensitive than the link itself already being handed out widely.
+  | "public_signup_token";
 
 export type SetupExposeMode = "localhost" | "tailnet" | "public";
 
@@ -593,3 +636,121 @@ export function resolveRootRedirect(
 ): string {
   return resolveRootRedirectDetailed(db, opts).value;
 }
+
+// --- domain helpers: root mode (redirect vs serve the app at `/`) ---------
+
+/**
+ * How the hub answers its origin root.
+ *
+ *   - `"redirect"` — historical behavior: the bare `/` 302s to the resolved
+ *     `root_redirect` (default `/admin`). Every unclaimed path keeps the
+ *     branded 404.
+ *   - `"serve-app"` — the hub serves the installed Parachute app's built
+ *     bundle AT the origin root (index.html at `/`, its assets from the same
+ *     dist, SPA-fallback for HTML deep links), matching the hosted door's
+ *     front-door experience. Falls back to `redirect` when the app isn't
+ *     installed (dist unresolvable).
+ */
+export type RootMode = "redirect" | "serve-app";
+
+/** Exported so the API handler + the CLI can share validation. */
+export const ROOT_MODES: readonly RootMode[] = ["redirect", "serve-app"];
+
+export function isRootMode(s: unknown): s is RootMode {
+  return typeof s === "string" && ROOT_MODES.includes(s as RootMode);
+}
+
+/** Env override for the root mode. Below the DB row, above the default. */
+export const PARACHUTE_HUB_ROOT_MODE_ENV = "PARACHUTE_HUB_ROOT_MODE";
+
+/** Fallback when neither DB row nor env is set — historical redirect behavior. */
+export const DEFAULT_ROOT_MODE: RootMode = "redirect";
+
+/**
+ * Read the raw stored root mode from hub_settings (or `null` when absent),
+ * WITHOUT applying env / default precedence — mirrors `getRootRedirect`. The
+ * admin GET surfaces this raw value so the operator sees exactly what's stored.
+ */
+export function getRootMode(db: Database): RootMode | null {
+  const raw = getSetting(db, "root_mode");
+  if (raw === undefined) return null;
+  return isRootMode(raw) ? raw : null;
+}
+
+/**
+ * Write or clear the root mode. Passing `null` (or the `"redirect"` default)
+ * deletes the row, reverting to env / default precedence — the absent-row
+ * state IS the redirect default, so leaving an explicit `"redirect"` in the
+ * row would be a footgun if a future default flip ever made absence mean
+ * something else (mirrors `setRootRedirect` / `setHubOrigin` semantics). The
+ * caller must have validated via `isRootMode`; the typed signature enforces it
+ * at TypeScript-clean call sites.
+ */
+export function setRootMode(db: Database, mode: RootMode | null): void {
+  if (mode === null || mode === DEFAULT_ROOT_MODE) {
+    deleteSetting(db, "root_mode");
+    return;
+  }
+  setSetting(db, "root_mode", mode);
+}
+
+/** Which precedence layer the resolved mode came from. */
+export type RootModeSource = "db" | "env" | "default";
+
+export interface ResolvedRootMode {
+  /** The mode the origin root should apply. */
+  value: RootMode;
+  /** Which layer it came from (for admin-UI attribution + install set-if-unset). */
+  source: RootModeSource;
+}
+
+/**
+ * Resolve the root mode with source attribution.
+ *
+ * Precedence: hub_settings.root_mode → `PARACHUTE_HUB_ROOT_MODE` env →
+ * `"redirect"` default. An invalid value at any layer is warned + skipped so a
+ * hand-edited row / typo'd env can never wedge the root (worst case falls to
+ * the redirect default — today's behavior).
+ *
+ * `db` may be `null` (hub-server running without state) — the DB layer is then
+ * skipped and resolution starts from env. The `env` / `warn` knobs are test
+ * seams (production uses `process.env` + `console.warn`).
+ */
+export function resolveRootModeDetailed(
+  db: Database | null,
+  opts: { env?: NodeJS.ProcessEnv; warn?: (msg: string) => void } = {},
+): ResolvedRootMode {
+  const env = opts.env ?? process.env;
+  const warn = opts.warn ?? ((msg: string) => console.warn(msg));
+
+  // 1. DB row (operator-set via the admin PUT / `parachute hub set-root-mode`).
+  if (db) {
+    const fromDb = getSetting(db, "root_mode");
+    if (fromDb !== undefined) {
+      if (isRootMode(fromDb)) return { value: fromDb, source: "db" };
+      warn(
+        `[hub-settings] root_mode="${fromDb}" in hub_settings is not a valid mode (expected one of ${ROOT_MODES.join(", ")}) — ignoring (falling through to env/default).`,
+      );
+    }
+  }
+
+  // 2. Env override.
+  const fromEnv = env[PARACHUTE_HUB_ROOT_MODE_ENV];
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (isRootMode(fromEnv)) return { value: fromEnv, source: "env" };
+    warn(
+      `[hub-settings] ${PARACHUTE_HUB_ROOT_MODE_ENV}="${fromEnv}" is not a valid mode — falling back to "${DEFAULT_ROOT_MODE}".`,
+    );
+  }
+
+  // 3. Default — historical redirect behavior.
+  return { value: DEFAULT_ROOT_MODE, source: "default" };
+}
+
+/** Convenience: just the resolved mode (see `resolveRootModeDetailed`). */
+export function resolveRootMode(
+  db: Database | null,
+  opts: { env?: NodeJS.ProcessEnv; warn?: (msg: string) => void } = {},
+): RootMode {
+  return resolveRootModeDetailed(db, opts).value;
+}

package/src/hub.ts

@@ -541,43 +541,76 @@ const DISCOVERY_SCRIPT = `<script>
   /**
    * Render the "Get started" section (hub#342) above the Services grid.
    *
-   * One hardcoded target, conditional on its prerequisite being installed:
-   *   - "Open Notes" → /surface/notes/  (requires parachute-surface installed;
-   *     Surface auto-bootstraps Notes-as-UI per parachute-surface §17, so the
-   *     mere presence of Surface means /surface/notes/ is live)
+   * Driven by the uis[] sub-unit arrays the well-known doc already carries
+   * (W2-12 — retires the hardcoded "Open Notes" → /surface/notes/ tile):
+   * one tile per ACTIVE uis[] entry across every services[] row, each
+   * carrying its own displayName + tagline + mount path. Under the app's
+   * notes→parachute surface-identity rename this stays correct whichever
+   * mount an install serves — an existing notes-ui install renders its
+   * "notes" entry at /surface/notes, a post-rename install renders its
+   * "parachute" entry at /surface/parachute, no hub-side name knowledge
+   * required. Entries named "parachute" / "notes" sort first (they're the
+   * end-user "browse my content" CTA — the audience that needs the
+   * strongest above-the-fold prompt); the rest follow alphabetically.
    *
-   * The earlier "Browse Vault" tile retired in workstream C (2026-05-25)
-   * once vault declared uiUrl in its module.json (per patterns#96). With
-   * the multi-instance prefix lifted into buildWellKnown, every vault
-   * instance now renders its own tile in the Services grid below — one
-   * per instance, with the actual instance name in the discovery doc
-   * rather than a hub-side guess at "first vault."
-   *
-   * Notes stays here because Notes is the end-user CTA (the audience
-   * that needs the strongest above-the-fold prompt); the Services grid
-   * positions it equally with admin tiles, which underweights the
-   * "browse my content" path for a returning operator.
+   * Legacy fallback: a surface-host row that predates uis{}
+   * self-registration carries no uis[] even while it serves notes-ui at
+   * /surface/notes (the hub proxies /surface/* blind — mounts are
+   * surface-host's on-disk state, not the manifest's). When no uis[]
+   * entries exist anywhere but parachute-surface IS installed, keep
+   * rendering the pre-W2-12 "Open Notes" tile so those installs' discovery
+   * page is untouched. The fallback dies naturally the first time the
+   * surface-host re-registers with uis{}.
    *
-   * If the prerequisite is not met (fresh install pre-wizard, no app)
-   * the section stays hidden. The hardcoded shape mirrors the wizard's
-   * own done-screen "Start using your vault" tile — same architectural
-   * shape (single obvious entry point) at a different surface.
+   * The earlier "Browse Vault" tile retired in workstream C (2026-05-25)
+   * once vault declared uiUrl in its module.json (per patterns#96) — vault
+   * instances render in the Services grid below.
    *
-   * Not driven by /api/modules because discovery is unauth — the
-   * services list from /.well-known/parachute.json is sufficient
-   * (it carries the same install-detection signal we need, no
-   * Bearer required).
+   * If nothing qualifies (fresh install pre-wizard, no app) the section
+   * stays hidden. Not driven by /api/modules because discovery is unauth —
+   * the services list from /.well-known/parachute.json is sufficient (it
+   * carries the uis[] fan-out, no Bearer required).
    */
   function renderGetStarted(services) {
     if (!getStartedGrid || !getStartedSection) return;
-    const tiles = [];
-    const hasSurface = services.some((s) => s && s.name === 'parachute-surface');
-    if (hasSurface) {
-      tiles.push({
-        title: 'Open Notes',
-        desc: 'Browse + capture in the Notes app — reads from your vault.',
-        href: '/surface/notes/',
-      });
+    const uiEntries = [];
+    const seenPaths = new Set();
+    for (const svc of services) {
+      if (!svc || !Array.isArray(svc.uis)) continue;
+      for (const ui of svc.uis) {
+        if (!ui || typeof ui.path !== 'string' || ui.path === '') continue;
+        // Absent status means active (services-manifest.ts UiSubUnitStatus).
+        if (ui.status && ui.status !== 'active') continue;
+        // Multi-path parent rows repeat the same uis[] on every path —
+        // de-duplicate by mount (well-known.ts's documented consumer duty).
+        if (seenPaths.has(ui.path)) continue;
+        seenPaths.add(ui.path);
+        uiEntries.push(ui);
+      }
+    }
+    const rank = (ui) => (ui.name === 'parachute' ? 0 : ui.name === 'notes' ? 1 : 2);
+    uiEntries.sort(
+      (a, b) =>
+        rank(a) - rank(b) ||
+        (a.displayName || a.name || '').localeCompare(b.displayName || b.name || ''),
+    );
+    const tiles = uiEntries.map((ui) => ({
+      title: ui.displayName || ui.name || ui.path,
+      desc: ui.tagline || '',
+      // Trailing slash keeps relative asset URLs resolving under the mount
+      // (same reason the retired hardcode pointed at /surface/notes/).
+      href: ui.path.endsWith('/') ? ui.path : ui.path + '/',
+    }));
+    if (tiles.length === 0) {
+      // Legacy fallback (see docstring): pre-uis surface-host installs.
+      const hasSurface = services.some((s) => s && s.name === 'parachute-surface');
+      if (hasSurface) {
+        tiles.push({
+          title: 'Open Notes',
+          desc: 'Browse + capture in the Notes app — reads from your vault.',
+          href: '/surface/notes/',
+        });
+      }
     }
     if (tiles.length === 0) {
       getStartedSection.setAttribute('hidden', '');

package/src/invites.ts

@@ -57,6 +57,7 @@
  */
 import type { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
+import { deleteSetting, getSetting } from "./hub-settings.ts";
 
 /** Default invite lifetime — long enough to deliver out-of-band (no email), short enough to bound a leaked link. */
 export const DEFAULT_INVITE_TTL_SECONDS = 7 * 24 * 60 * 60;
@@ -502,3 +503,44 @@ export function revokeInvitesForVault(
     .run(now.toISOString(), vaultName);
   return Number(res.changes);
 }
+
+/**
+ * Q2 (hub-parity P2) — the account descriptor's conditional `signup_path`.
+ * The hub cannot derive a redemption URL from the `invites` table (only
+ * `sha256(token)` is stored, never the raw value — see the module doc), so
+ * this reads back the ONE raw token persisted at mint time for a
+ * deliberately PUBLIC (multi-use) invite (`api-invites.ts`'s
+ * `handleCreateInvite`, which writes `hub_settings.public_signup_token`
+ * after `issueInvite` when `maxUses > 1`) and re-validates it's still live.
+ *
+ * Returns `/account/setup/<token>` when the persisted invite is still
+ * `"pending"`, still multi-use (`maxUses > 1`), AND provisioning
+ * (`provisionVault` — each redeemer gets their own new vault); `null` on ANY
+ * miss (never set, redeemed, revoked, exhausted, expired, or a non-provisioning
+ * shared-vault link) — and lazily clears the stale setting in that case. No
+ * separate revoke/exhaust/expire hook is needed: `inviteStatus` already derives
+ * all four terminal states from the invite's own columns, so every miss flows
+ * through this one status check.
+ *
+ * The `maxUses > 1` AND `provisionVault` re-checks are defense-in-depth mirrors
+ * of `handleCreateInvite`'s write condition (which only persists for a
+ * multi-use provisioning link): even a hand-edited settings row pointing at a
+ * single-use OR a shared-vault (`provision_vault=false`) invite must never be
+ * advertised as public signup — a shared-vault link would leak team-vault write
+ * on the anonymous, wildcard-CORS descriptor.
+ */
+export function activePublicSignupPath(db: Database, now: Date = new Date()): string | null {
+  const raw = getSetting(db, "public_signup_token");
+  if (!raw) return null;
+  const invite = findInviteByRawToken(db, raw);
+  if (
+    !invite ||
+    inviteStatus(invite, now) !== "pending" ||
+    invite.maxUses <= 1 ||
+    !invite.provisionVault
+  ) {
+    deleteSetting(db, "public_signup_token");
+    return null;
+  }
+  return `/account/setup/${encodeURIComponent(raw)}`;
+}

package/src/module-ops-client.ts

@@ -376,7 +376,8 @@ export async function fetchModuleStates(deps: DriveModuleOpDeps): Promise<Module
   try {
     res = await doFetch(`${baseUrl}/api/modules`, {
       method: "GET",
-      // `/api/modules` parses the scheme-cased `Bearer ` prefix; match it exactly.
+      // `/api/modules` parses the Bearer scheme case-insensitively (RFC 7235,
+      // V1.4/C1.3 parity); we still emit the canonical `Bearer ` prefix.
       headers: { authorization: `Bearer ${bearer}` },
       // Bound the read so a wedged hub handler degrades `status` rather than
       // hanging it. AbortSignal.timeout fires `AbortError` once the ceiling

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