@openparachute/hub 0.6.5-rc.8 → 0.7.0

package/src/api-modules-ops.ts

@@ -36,10 +36,10 @@ import type { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 import { MissingDependencyError, type MissingDependencyWire } from "@openparachute/depcheck";
-import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
+import type { CuratedModuleShort } from "./api-modules.ts";
 import { isLinked as defaultIsLinked } from "./bun-link.ts";
 import { PARACHUTE_INSTALL_CHANNEL_ENV } from "./commands/install.ts";
-import { buildModuleSpawnRequest } from "./commands/serve-boot.ts";
+import { buildModuleSpawnRequest, reconcilePortToCanonical } from "./commands/serve-boot.ts";
 import { validateHostAdminToken } from "./host-admin-token-validation.ts";
 import { getModuleInstallChannel } from "./hub-settings.ts";
 import { readModuleManifest } from "./module-manifest.ts";
@@ -49,6 +49,7 @@ import {
   type ServiceSpec,
   composeKnownModuleSpec,
   getSpec,
+  isKnownModuleShort,
   synthesizeManifestForKnownModule,
 } from "./service-spec.ts";
 import { findService, readManifestLenient, removeService } from "./services-manifest.ts";
@@ -263,6 +264,15 @@ export interface ApiModulesOpsDeps {
    * per-request HTTP build stay aligned.
    */
   readModuleManifest?: Parameters<typeof regenerateWellKnown>[0]["readModuleManifest"];
+  /**
+   * Diagnostic log sink for spawn-path events that aren't tied to an op-log
+   * (e.g. the canonical-port reconcile in `resolveSpawnRequest`: a drift fixed,
+   * a held-canonical decline, or a persist failure). Without this, those events
+   * are swallowed on an operator-triggered start/restart while the boot path
+   * logs them. Defaults to `console.error` (stderr — same destination as the
+   * serve-boot path's logger). Tests inject a collector to assert the events.
+   */
+  log?: (line: string) => void;
 }
 
 interface PathMatch {
@@ -272,9 +282,15 @@ interface PathMatch {
 
 /**
  * Parse `/api/modules/<short>/<rest>` into the canonical short name +
- * the action suffix. Rejects unknown shorts to keep arbitrary
- * services.json names from driving the install pathway (curated-only
- * for v0.6).
+ * the action suffix. Rejects shorts the hub can't resolve a package/manifest
+ * 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.
+ *
+ * The hub (`hub`) and genuinely third-party services.json rows still fall
+ * through to undefined: there's no install package to act on.
  */
 export function parseModulesPath(pathname: string): PathMatch | undefined {
   const prefix = "/api/modules/";
@@ -284,7 +300,7 @@ export function parseModulesPath(pathname: string): PathMatch | undefined {
   if (slash <= 0) return undefined;
   const short = tail.slice(0, slash);
   const rest = tail.slice(slash + 1);
-  if (!CURATED_MODULES.includes(short as CuratedModuleShort)) return undefined;
+  if (!isKnownModuleShort(short)) return undefined;
   return { short: short as CuratedModuleShort, rest };
 }
 
@@ -336,12 +352,14 @@ async function authorize(req: Request, deps: ApiModulesOpsDeps): Promise<Respons
  * reach the same spec the API handlers use without duplicating the
  * curated-table lookup.
  *
- * Two source paths (hub#310, post-FALLBACK-retirement for vault/scribe/runner):
+ * Two source paths (post-FALLBACK-retirement: vault/scribe/runner in
+ * hub#310, channel in boundary D3):
  *
- *   - **FIRST_PARTY_FALLBACKS** (notes / channel): vendored manifest is
+ *   - **FIRST_PARTY_FALLBACKS** (notes): vendored manifest is
  *     authoritative pre-install — the embedded `manifest.startCmd` /
  *     `manifest.paths` / etc. drive the install + spawn flow.
- *   - **KNOWN_MODULES** (vault / scribe / runner): no vendored manifest.
+ *   - **KNOWN_MODULES** (vault / scribe / runner / channel / surface): no
+ *     vendored manifest.
  *     Pre-install we know only the npm package + manifestName + canonical
  *     port + imperative `extras` (init, postInstallFooter, urlForEntry,
  *     hasAuth). Post-install, `runInstall` reads `<installDir>/.parachute/module.json`
@@ -440,7 +458,14 @@ async function resolveSpawnRequest(
     if (resolved) spawnSpec = resolved;
   }
 
-  const cmd = spawnSpec.startCmd?.(entry);
+  // Snap a drifted fixed-port row back to canonical before deriving startCmd
+  // (notes' startCmd embeds the port) / PORT / probe / proxy from it
+  // (channel#41). No-op on the common path. Mirror of the serve-boot path so a
+  // module started from the admin SPA gets the same canonical-port reconciliation
+  // — including the same diagnostic logging (deps.log, default stderr).
+  const spawnEntry = reconcilePortToCanonical(entry, deps.manifestPath, deps.log ?? console.error);
+
+  const cmd = spawnSpec.startCmd?.(spawnEntry);
   if (!cmd || cmd.length === 0) {
     return {
       ok: false,
@@ -455,7 +480,7 @@ async function resolveSpawnRequest(
   // / live HUB_ORIGIN / enriched PATH). The test-seam / first-boot `spawnEnv`
   // rides the shared helper's `extraEnv` and wins last, matching
   // `spawnSupervised`'s precedence.
-  const req = buildModuleSpawnRequest(short, entry, cmd, {
+  const req = buildModuleSpawnRequest(short, spawnEntry, cmd, {
     configDir: deps.configDir,
     ...(deps.issuer ? { hubOrigin: deps.issuer } : {}),
     ...(deps.spawnEnv ? { extraEnv: deps.spawnEnv } : {}),
@@ -793,13 +818,13 @@ export async function runInstall(
     });
   }
 
-  // KNOWN_MODULES shorts (vault / scribe / runner — hub#310): module.json
-  // is the canonical source for startCmd. Re-resolve the spec from
-  // `<installDir>/.parachute/module.json` when installDir is stamped so the
-  // module is authoritative for its own spawn cmd. Falls back to the
+  // KNOWN_MODULES shorts (vault / scribe / runner / channel / surface):
+  // module.json is the canonical source for startCmd. Re-resolve the spec
+  // from `<installDir>/.parachute/module.json` when installDir is stamped so
+  // the module is authoritative for its own spawn cmd. Falls back to the
   // imperative `extras.startCmd` carried by `spec` (from `specFor`) when
   // installDir is absent or module.json is unreadable. FIRST_PARTY_FALLBACKS
-  // shorts (notes / channel) don't take this path — they're already in
+  // shorts (notes) don't take this path — they're already in
   // KNOWN_MODULES[short] === undefined so the short-circuit applies.
   let spawnSpec: ServiceSpec = spec;
   if (installDir && KNOWN_MODULES[short]) {

package/src/api-modules.ts

@@ -1,19 +1,26 @@
 /**
  * `GET /api/modules` — admin SPA's module-management surface.
  *
- * Combines three sources into a single per-module row:
+ * Discovery is driven by SELF-REGISTRATION, not a whitelist (2026-06-09
+ * modular-UI architecture, P2). The catalog is the UNION of three sources,
+ * deduped by short name, each row carrying a `focus` tier:
  *
- *   - **Curated availability** — vault, scribe (the launch focus per
- *     Aaron 2026-05-27). The list was previously broader; trimmed for
- *     the launch arc. The Phase-2 marketplace will broaden this; for
- *     now it's hardcoded so the admin UI has a stable "what can I
- *     install?" list even on a fresh container where services.json is
- *     empty.
- *   - **Installed state** — services.json reads (version, installDir).
+ *   - **Known/discoverable registry** — `discoverableShorts()` (KNOWN_MODULES ∪
+ *     FIRST_PARTY_FALLBACKS): every module the hub can resolve a package +
+ *     manifest for, so a fresh container shows the full "what can I install?"
+ *     catalog even with an empty services.json.
+ *   - **Installed state** — services.json reads (version, installDir). Any
+ *     self-registered row surfaces here even if it isn't in the known registry.
  *   - **Supervisor state** — per-module run status (`running` / `stopped`
  *     / `crashed` / `starting` / `restarting`) + pid. Absent when the
  *     hub is in CLI mode (no supervisor injected through HubFetchDeps).
  *
+ * `focus` ("core" | "experimental") comes from each module's `module.json`
+ * when declared, else `focusForShort`'s default map. The SPA groups core first
+ * + de-emphasizes experimental — it NEVER hides a module. This is what makes a
+ * running, self-registered module (channel) visible + installable; the old
+ * `CURATED_MODULES = ["vault","scribe"]` whitelist made it invisible.
+ *
  * Bearer-gated on `parachute:host:auth` to match the rest of `/api/auth/*`
  * and `/api/grants` — the admin SPA mints this scope via
  * `/admin/host-admin-token` and threads it as `Authorization: Bearer`.
@@ -37,12 +44,21 @@ import {
   type ModuleManifest,
   readModuleManifest as defaultReadModuleManifest,
 } from "./module-manifest.ts";
-import { FIRST_PARTY_FALLBACKS, KNOWN_MODULES } from "./service-spec.ts";
+import type { ModuleFocus } from "./module-manifest.ts";
+import {
+  FIRST_PARTY_FALLBACKS,
+  KNOWN_MODULES,
+  discoverableShorts,
+  focusForShort,
+  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
 // retirement, hub#310). The local helper hides the split from the rest of
-// this file.
+// this file. `discoverableShorts` enumerates their UNION — the
+// self-registration-driven discovery surface that replaced the old
+// `CURATED_MODULES` whitelist (2026-06-09 modular-UI architecture, P2).
 import {
   type UiSubUnit,
   type UiSubUnitStatus,
@@ -52,13 +68,14 @@ import {
 import type { ModuleStartError, ModuleState, Supervisor } from "./supervisor.ts";
 
 /**
- * Resolve a curated module to the display + install bootstrap data the
- * admin SPA renders. Reads from FIRST_PARTY_FALLBACKS (notes / channel)
- * first, KNOWN_MODULES (vault / scribe / runner) second.
+ * Resolve a known module to the display + install bootstrap data the admin SPA
+ * renders. Reads from FIRST_PARTY_FALLBACKS (notes) first,
+ * KNOWN_MODULES (vault / scribe / runner / channel / surface) second.
  *
- * Returns `undefined` if the short isn't curated — `CURATED_MODULES` is a
- * const tuple intersected with both tables, so undefined here is a programmer
- * error (caught by the type system in practice).
+ * Returns `undefined` if the short is in neither table — a genuinely
+ * third-party module discovered only via services.json / the supervisor. The
+ * discovery handler synthesizes a minimal row for those rather than dropping
+ * them (2026-06-09 modular-UI architecture — show all self-registered modules).
  */
 function lookupModule(
   short: string,
@@ -88,31 +105,26 @@ function lookupModule(
 export const API_MODULES_REQUIRED_SCOPE = "parachute:host:auth";
 
 /**
- * Curated module short-names. The admin UI offers exactly these for install
- * + management. Order is the recommended install order (vault first, scribe
- * second).
- *
- * Trimmed 2026-05-27 (Aaron-directed launch focus) from the prior set of
- * `["vault", "surface", "notes", "scribe", "runner"]`. The dropped modules
- * are still published on npm and still work — they're just not the focus:
+ * Recommended fresh-install ORDER for the `core`-tier modules. NO LONGER a
+ * discovery/install whitelist (2026-06-09 modular-UI architecture, P2 —
+ * retired the gating role). Discovery now enumerates the UNION of
+ * `services.json` ∪ `discoverableShorts()` (KNOWN_MODULES ∪
+ * FIRST_PARTY_FALLBACKS) ∪ supervisor, so every self-registered/known
+ * module appears — the channel-not-installed bug (running but invisible)
+ * is gone.
  *
- *   - `notes` (notes-daemon): retired. Notes-UI now lives at
- *     `notes.parachute.computer` as a hosted SPA — operators don't install
- *     a notes daemon anymore. The npm package `@openparachute/notes-ui`
- *     is a library imported by `parachute-surface` and by custom-surface
- *     builders.
- *   - `surface` (host module): de-emphasized. `@openparachute/surface-client`
- *     remains the canonical library for folks building their own UIs
- *     against a Parachute hub; running the surface-host module on your
- *     own box is no longer the headline path (use notes.parachute.computer
- *     or build your own).
- *   - `runner`: experimental, not in the focus set for launch.
+ * This constant survives only as a sort hint: shorts listed here float to the
+ * top of the `core` group in the given order (vault first, scribe second).
+ * Any `core`-tier module not named here still appears, sorted after these.
+ * The install-path gate (`parseModulesPath`) now accepts any known short via
+ * `isKnownModuleShort`, NOT membership in this tuple.
  *
- * Re-adding any of these is one line — keep the list small until use
- * cases demand otherwise.
+ * `CuratedModuleShort` is retained as a loose typed-string key for the
+ * lookup helpers (`getSpec`, `lookupModule`) that consume a short name — it
+ * is no longer a closed enum of the only installable modules.
  */
 export const CURATED_MODULES = ["vault", "scribe"] as const;
-export type CuratedModuleShort = (typeof CURATED_MODULES)[number];
+export type CuratedModuleShort = string;
 
 export interface ApiModulesDeps {
   db: Database;
@@ -186,6 +198,14 @@ interface ModuleWireShape {
   package: string;
   display_name: string;
   tagline: string;
+  /**
+   * Discovery tier (2026-06-09 modular-UI architecture). `core` modules render
+   * in the headline group; `experimental` modules render in a de-emphasized
+   * "Experimental" group below — never hidden. Resolved from the module's
+   * `module.json` `focus` when declared, else `focusForShort`'s default map
+   * (vault/scribe/hub/surface → core, channel/runner/others → experimental).
+   */
+  focus: ModuleFocus;
   available: boolean;
   installed: boolean;
   installed_version: string | null;
@@ -231,9 +251,9 @@ interface ModuleWireShape {
    *      declared surface — for modules where the user-facing UI IS
    *      the operator UI (App today).
    *   3. Null when the module hasn't declared either field — the SPA
-   *      renders a disabled "Open" tooltip ("module hasn't shipped an
-   *      admin UI yet"). Tracked as follow-up issues per module
-   *      (scribe#53, runner#8 today).
+   *      renders a disabled "Open" tooltip (pointing at Configure when
+   *      `config_ui_url` is set — runner's shape today — or "module
+   *      hasn't shipped an admin UI yet" otherwise).
    *
    * Always an absolute path on the hub origin (leading `/`) — the SPA
    * navigates same-origin, no need to worry about cross-origin
@@ -241,6 +261,23 @@ interface ModuleWireShape {
    * surfaces, unused by first-party modules today).
    */
   management_url: string | null;
+  /**
+   * Where the module's OWN config/admin surface lives (2026-06-09 modular-UI
+   * architecture, P3). Resolved server-side from the module's
+   * `.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
+   * `/scribe/admin`, …), which mints its admin Bearer from the hub's
+   * cookie-gated `/admin/module-token/<short>` (or `/admin/channel-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`;
+   * vault declares `managementUrl` (its admin SPA is the config surface).
+   */
+  config_ui_url: string | null;
 }
 
 /**
@@ -395,34 +432,33 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
     }
   >();
   for (const entry of manifest.services) {
-    // Join services.json rows to CURATED_MODULES by manifestName. The
-    // mapping table lives in lookupModule (which consults both
-    // FIRST_PARTY_FALLBACKS and KNOWN_MODULES) — so a row written by a
-    // self-registered vault / scribe / runner matches even though those
-    // shorts no longer have FALLBACK entries (hub#310).
-    for (const short of CURATED_MODULES) {
-      const m = lookupModule(short);
-      if (m?.manifestName === entry.name) {
-        const value: {
-          version: string;
-          installDir?: string;
-          uis?: Record<string, UiSubUnit>;
-          mountPath?: string;
-        } = { version: entry.version };
-        if (entry.installDir !== undefined) value.installDir = entry.installDir;
-        if (entry.uis !== undefined) value.uis = entry.uis;
-        // First non-`.parachute` path is the module's user-facing mount
-        // (`/app`, `/scribe`, `/vault/<name>`). Used below to resolve
-        // a relative `managementUrl` to a full hub-origin path. Skips
-        // `.parachute` entries because those are protocol mounts, not
-        // user surfaces — every module declares one.
-        const userPath = (entry.paths ?? []).find(
-          (p) => p !== "/.parachute" && !p.startsWith("/.parachute/"),
-        );
-        if (userPath !== undefined) value.mountPath = userPath;
-        installedByShort.set(short, value);
-      }
-    }
+    // Join services.json rows to a short via `shortNameForManifest` — covers
+    // every known module (FIRST_PARTY_FALLBACKS ∪ KNOWN_MODULES ∪ legacy
+    // aliases), so a self-registered channel / runner / surface row matches
+    // and becomes discoverable. Rows whose manifestName resolves to no known
+    // short (genuinely third-party) fall back to the row's own name as the
+    // short — they still surface as installed, de-emphasized (2026-06-09
+    // modular-UI architecture, P2 — discovery from self-registration, not the
+    // CURATED_MODULES whitelist).
+    const short = shortNameForManifest(entry.name) ?? entry.name;
+    const value: {
+      version: string;
+      installDir?: string;
+      uis?: Record<string, UiSubUnit>;
+      mountPath?: string;
+    } = { version: entry.version };
+    if (entry.installDir !== undefined) value.installDir = entry.installDir;
+    if (entry.uis !== undefined) value.uis = entry.uis;
+    // First non-`.parachute` path is the module's user-facing mount
+    // (`/surface`, `/scribe`, `/vault/<name>`). Used below to resolve a
+    // relative `managementUrl` to a full hub-origin path. Skips `.parachute`
+    // entries because those are protocol mounts, not user surfaces — every
+    // module declares one.
+    const userPath = (entry.paths ?? []).find(
+      (p) => p !== "/.parachute" && !p.startsWith("/.parachute/"),
+    );
+    if (userPath !== undefined) value.mountPath = userPath;
+    installedByShort.set(short, value);
   }
 
   // Read each installed module's `.parachute/module.json` so we can
@@ -432,49 +468,39 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   // management_url and the SPA shows the disabled "Open" tooltip.
   const readModuleManifestFn = deps.readModuleManifest ?? defaultReadModuleManifest;
   const managementUrlByShort = new Map<string, string>();
+  // The module's OWN config surface (2026-06-09 modular-UI architecture, P3) —
+  // resolved from `configUiUrl` the same way `managementUrl` is. Drives the
+  // consistent Configure action.
+  const configUiUrlByShort = new Map<string, string>();
+  // Manifest-declared `focus` per installed short. Prefer this over the default
+  // map when composing the wire shape (2026-06-09 modular-UI architecture).
+  const declaredFocusByShort = new Map<string, ModuleFocus>();
   await Promise.all(
     Array.from(installedByShort.entries()).map(async ([short, value]) => {
       if (!value.installDir) return;
       try {
         const m = await readModuleManifestFn(value.installDir);
         if (!m) return;
+        if (m.focus !== undefined) declaredFocusByShort.set(short, m.focus);
         // Resolution per the module-ui-declaration.md hierarchy:
-        // managementUrl > uiUrl. Both are EITHER an absolute
-        // http(s) URL OR a relative path. Relative paths are joined
-        // against the module's mount path (entry.paths[0]) since both
-        // surfaces conventionally live under it (vault's `/admin`,
-        // app's `/admin`). Absolute URLs pass through verbatim.
-        const candidate = m.managementUrl ?? m.uiUrl;
-        if (candidate === undefined) return;
-        if (/^https?:\/\//i.test(candidate)) {
-          managementUrlByShort.set(short, candidate);
-          return;
-        }
-        const mount = value.mountPath;
-        if (mount === undefined) {
-          // No user-facing mount declared — we can't resolve a relative
-          // path. Skip rather than guess. Vault rows hit this when
-          // services.json was hand-edited to remove the mount; the
-          // disabled-tooltip state in the SPA is the right surface.
-          return;
-        }
-        // Resolution rule (per module-ui-declaration.md):
-        //   - Multi-instance modules (vault) declare a per-instance
-        //     relative path (e.g. `/admin/`); hub prepends the mount
-        //     (e.g. `/vault/default` + `/admin/` → `/vault/default/admin/`).
-        //   - Single-instance modules (app, scribe, runner) declare a
-        //     full hub-origin path that ALREADY includes the mount
-        //     (e.g. `/surface/admin/`, `/scribe/admin`); the mount must NOT
-        //     be prepended again or the result is `/app/surface/admin/`
-        //     (the audit bug caught 2026-05-25 on the SPA's Services
-        //     dropdown).
-        // Detect by checking if candidate is already mount-prefixed.
-        const tail = candidate.startsWith("/") ? candidate : `/${candidate}`;
-        const alreadyMountPrefixed = tail === mount || tail.startsWith(`${mount}/`);
-        managementUrlByShort.set(short, alreadyMountPrefixed ? tail : `${mount}${tail}`);
+        // managementUrl > uiUrl. Unified semantics (B4): http(s):// verbatim ·
+        // leading-"/" = origin-absolute verbatim · relative = joined under the
+        // module's mount path (entry.paths[0]) — the per-instance form.
+        const resolvedManagement = resolveModuleUrl(
+          m.managementUrl ?? m.uiUrl,
+          value.mountPath,
+          short,
+        );
+        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)
+        // alongside a separate `uiUrl`.
+        const resolvedConfig = resolveModuleUrl(m.configUiUrl, value.mountPath, short);
+        if (resolvedConfig !== undefined) configUiUrlByShort.set(short, resolvedConfig);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`api-modules: skipping managementUrl for ${short}: ${msg}`);
+        console.warn(`api-modules: skipping module URLs for ${short}: ${msg}`);
       }
     }),
   );
@@ -488,6 +514,17 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
     }
   }
 
+  // Discovery short list = UNION of the bootstrap registries (KNOWN_MODULES ∪
+  // FIRST_PARTY_FALLBACKS via `discoverableShorts`), every services.json row's
+  // short, and every supervised module's short — deduped, preserving registry
+  // order first so the canonical modules lead (2026-06-09 modular-UI
+  // architecture, P2). Every self-registered/known module appears; the
+  // running-but-invisible class (channel) is gone.
+  const discoverySet = new Set<string>(discoverableShorts());
+  for (const short of installedByShort.keys()) discoverySet.add(short);
+  for (const short of stateByShort.keys()) discoverySet.add(short);
+  const discoveryShorts = Array.from(discoverySet);
+
   // Resolve npm dist-tag in parallel — short timeout per request, cache
   // shared across requests so a fast UI poll doesn't slam the registry.
   // Channel-aware: an operator on @rc sees the rc-tagged version as the
@@ -500,9 +537,11 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
 
   const latestByShort = new Map<string, string | null>();
   await Promise.all(
-    CURATED_MODULES.map(async (short) => {
+    discoveryShorts.map(async (short) => {
       const m = lookupModule(short);
       if (!m) {
+        // Third-party module known only from services.json / supervisor — no
+        // npm package to probe.
         latestByShort.set(short, null);
         return;
       }
@@ -519,21 +558,33 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
     }),
   );
 
-  // Compose the wire shape. Curated order is the recommended install order;
-  // installed modules outside the curated list (uncommon — only third-party)
-  // are appended at the end with `available: false`.
-  const modules: ModuleWireShape[] = [];
-  for (const short of CURATED_MODULES) {
+  // Compose one wire row per discovered short. `focus` resolution: the
+  // module's manifest-declared `focus` (when installed + declared) wins; else
+  // the `focusForShort` default map. Sort: `core` group first (with the
+  // CURATED_MODULES recommended-install order floated to the top of that
+  // group), then `experimental` — the SPA renders the two groups; `focus`
+  // never hides a module.
+  const recommendedOrder = new Map<string, number>(
+    (CURATED_MODULES as readonly string[]).map((s, i) => [s, i]),
+  );
+  const rows = discoveryShorts.map((short) => {
     const m = lookupModule(short);
-    if (!m) continue;
     const installed = installedByShort.get(short);
     const state = stateByShort.get(short);
-    modules.push({
+    const focus = focusForShort(short, declaredFocusByShort.get(short));
+    const row: ModuleWireShape = {
       short,
-      package: m.package,
-      display_name: m.displayName,
-      tagline: m.tagline,
-      available: true,
+      // Third-party (no known table entry) → fall back to the short as the
+      // package label + the row's own display fields.
+      package: m?.package ?? short,
+      display_name: m?.displayName ?? short,
+      tagline: m?.tagline ?? "",
+      focus,
+      // `available` historically meant "in the curated install catalog". Every
+      // discovered short is now installable/managed, so it's always true for
+      // known modules; a purely third-party services.json row (no install
+      // package) is not hub-installable → false.
+      available: m !== undefined,
       installed: installed !== undefined,
       installed_version: installed?.version ?? null,
       latest_version: latestByShort.get(short) ?? null,
@@ -543,8 +594,19 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       install_dir: installed?.installDir ?? null,
       uis: toUisWireShape(installed?.uis),
       management_url: managementUrlByShort.get(short) ?? null,
-    });
-  }
+      config_ui_url: configUiUrlByShort.get(short) ?? null,
+    };
+    return row;
+  });
+  const focusRank = (f: ModuleFocus): number => (f === "core" ? 0 : 1);
+  rows.sort((a, b) => {
+    if (a.focus !== b.focus) return focusRank(a.focus) - focusRank(b.focus);
+    const ai = recommendedOrder.get(a.short) ?? Number.POSITIVE_INFINITY;
+    const bi = recommendedOrder.get(b.short) ?? Number.POSITIVE_INFINITY;
+    if (ai !== bi) return ai - bi;
+    return a.short.localeCompare(b.short);
+  });
+  const modules: ModuleWireShape[] = rows;
 
   // Every supervised module's run-state — curated AND non-curated (hub#539).
   // Built from the same supervisor.list() snapshot already in `stateByShort`.
@@ -663,6 +725,66 @@ function jsonError(status: number, code: string, description: string): Response
   });
 }
 
+/**
+ * The literal legacy per-instance candidates the COMPAT SHIM recognizes on a
+ * vault entry (see `resolveModuleUrl`). One-release shim — remove once vault's
+ * new manifest (`managementUrl: "admin/"`) reaches @latest.
+ */
+const LEGACY_VAULT_ADMIN_CANDIDATES = new Set(["/admin", "/admin/"]);
+let warnedLegacyVaultAdminCandidate = false;
+
+/**
+ * Resolve a module-declared "path or http(s) URL" surface field (`managementUrl`,
+ * `uiUrl`, `configUiUrl`) to a full hub-origin path the SPA can navigate to.
+ *
+ * Unified URL-resolution semantics (B4 of the 2026-06-09 hub-module-boundary
+ * migration — same doctrine as `buildWellKnown`'s uiUrl branch and the
+ * `resolveManagementUrl` pair):
+ *
+ *   - `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`);
+ *     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
+ *     no mount to join → `undefined` (can't resolve; the SPA renders the
+ *     disabled/omitted state rather than guessing).
+ *
+ * COMPAT SHIM (one release): the literal legacy `"/admin"`/`"/admin/"` on a
+ * VAULT entry is the OLD per-instance relative declaration — deployed vaults
+ * still ship it until the vault wave's manifest lands — and mount-joins with
+ * a one-time deprecation log instead of resolving origin-absolute (which
+ * would point at the daemon-level `/vault/admin` mount, not the instance).
+ *
+ * Shared by `managementUrl`/`uiUrl` (the Open action) and `configUiUrl` (the
+ * Configure action, 2026-06-09 modular-UI architecture P3) so the two resolve
+ * identically.
+ */
+function resolveModuleUrl(
+  candidate: string | undefined,
+  mount: string | undefined,
+  short: string,
+): string | undefined {
+  if (candidate === undefined) return undefined;
+  if (/^https?:\/\//i.test(candidate)) return candidate;
+  const mountBase = mount?.replace(/\/+$/, "");
+  if (short === "vault" && LEGACY_VAULT_ADMIN_CANDIDATES.has(candidate)) {
+    if (!warnedLegacyVaultAdminCandidate) {
+      warnedLegacyVaultAdminCandidate = true;
+      console.warn(
+        `api-modules: vault declares the legacy per-instance form ${JSON.stringify(candidate)}; mount-joining for one release. New semantics: relative ("admin/") = per-instance mount-join, leading-"/" = origin-absolute. Upgrade the vault module to clear this.`,
+      );
+    }
+    if (mountBase === undefined) return undefined;
+    return `${mountBase}${candidate}`;
+  }
+  if (candidate.startsWith("/")) return candidate;
+  if (mountBase === undefined) return undefined;
+  return `${mountBase}/${candidate}`;
+}
+
 /**
  * Map a services.json `uis` record to the snake-case wire shape the SPA
  * consumes. Each missing optional field on the source becomes an explicit