@openparachute/hub 0.7.7-rc.8 → 0.7.7

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,59 @@ 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 serves the app directly too, unless you've",
+      "already customized the root (`parachute hub set-root-mode` / `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 +401,7 @@ const NOTES_FALLBACK: FirstPartyFallback = {
  */
 export const FIRST_PARTY_FALLBACKS: Record<string, FirstPartyFallback> = {
   notes: NOTES_FALLBACK,
+  app: APP_FALLBACK,
 };
 
 /**
@@ -438,8 +511,8 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
     },
   },
   // NOTE (2026-07-01): `runner` was REMOVED from this registry (decision:
-  // Aaron 2026-07-01 — the module set of record is vault / hub / agent /
-  // scribe / surface). Runner is no longer offered, installable, or
+  // Aaron 2026-07-01 — the module set of record is vault / hub / scribe /
+  // surface). Runner is no longer offered, installable, or
   // lifecycle-addressable by short name from the hub's bootstrap registries.
   // Existing installs stay GRACEFUL: a legacy `parachute-runner` services.json
   // row is handled exactly like any unknown/third-party row — `parachute
@@ -448,29 +521,7 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
   // stamped and logs-and-skips otherwise. Deliberately NOT added to
   // RETIRED_MODULES: that registry GC-drops rows on load, which would break
   // routing for operators still running the runner daemon.
-  agent: {
-    short: "agent",
-    package: "@openparachute/agent",
-    manifestName: "parachute-agent",
-    canonicalPort: 1941,
-    displayName: "Agent",
-    // Mirrors agent's own module.json (the canonical fields below do too —
-    // keep in sync if agent's declaration changes). Renamed from `channel`
-    // 2026-06-17 (parachute-channel → parachute-agent); the module is the
-    // same webhook-fan-out + MCP bridge daemon, on the same port 1941.
-    tagline: "Chat with your Claude Code sessions — a channel per session.",
-    canonicalPaths: ["/agent"],
-    canonicalHealth: "/health",
-    canonicalStripPrefix: true,
-    extras: {
-      // Backward-compat startCmd for rows without installDir — same rationale
-      // as scribe / vault. The bare binary IS the daemon (agent's
-      // package.json bin maps `parachute-agent` → src/daemon.ts).
-      startCmd: () => ["parachute-agent"],
-      // Agent gates its endpoints behind hub-issued JWTs (agent:* scopes).
-      hasAuth: true,
-    },
-  },
+
   surface: {
     short: "surface",
     package: "@openparachute/surface",
@@ -520,39 +571,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 +687,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 +705,8 @@ const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
   scribe: "core",
   hub: "core",
   surface: "core",
-  agent: "experimental",
+  app: "core",
+
   notes: "deprecated",
 };
 
@@ -738,7 +794,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 +903,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 {

package/src/services-manifest.ts

@@ -623,7 +623,8 @@ export function readManifestLenient(
     );
     return { services: [] };
   }
-  const afterRetired = dropRetiredModuleRows(raw, path);
+  const healed = healStaleUiHostAppRows(raw, path);
+  const afterRetired = dropRetiredModuleRows(healed.raw, path);
   const cleaned = dropLegacyShortNameRows(afterRetired.raw, path);
   // `typeof null === "object"` in JS, so the `!cleaned.raw` part of this
   // guard is load-bearing for the null case — not a typo or redundancy.
@@ -671,23 +672,29 @@ export function readManifest(path: string = SERVICES_MANIFEST_PATH): ServicesMan
       `failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`,
     );
   }
-  // Retired-module + legacy short-name row cleanup runs BEFORE shape
+  // Row-heal + retired-module + legacy short-name cleanup all run BEFORE shape
   // validation because the bugs they heal (rows that conflict on port with
   // a current row) would otherwise throw inside `validateManifest`'s
-  // duplicate-port gate. Order matters: drop retired-module rows FIRST so
-  // their absence can unmask a `parachute-<X>` ↔ `<X>` pair underneath that
-  // `dropLegacyShortNameRows` then handles. The reverse order would leave
-  // a retired row that the short-name pass doesn't recognize. Both passes
-  // mutate the raw JSON object's `services` array; we re-validate against
-  // the cleaned shape. See `dropRetiredModuleRows` + `dropLegacyShortNameRows`
-  // for the full discipline.
-  const afterRetired = dropRetiredModuleRows(raw, path);
+  // duplicate-port gate. Order matters:
+  //   1. `healStaleUiHostAppRows` FIRST — a pre-rename operator can carry BOTH
+  //      a `parachute-app` AND an `app` stale row (2026-05-22 double-write
+  //      reproducer); dropping by OLD-UI-host shape here clears both, whereas
+  //      `dropLegacyShortNameRows` would keep the `parachute-app` half. Runs
+  //      ahead of the retired-module pass too (the `app`/`parachute-app`
+  //      RETIRED_MODULES entries were removed in hub-parity P5 — the names are
+  //      the NEW app's now — so this shape-gated heal is their replacement).
+  //   2. `dropRetiredModuleRows` — drop genuinely-retired rows so their
+  //      absence can unmask a `parachute-<X>` ↔ `<X>` pair underneath that
+  //   3. `dropLegacyShortNameRows` then handles.
+  // Each pass mutates the raw JSON object's `services` array; we re-validate
+  // against the cleaned shape. See the three helpers for the full discipline.
+  const healed = healStaleUiHostAppRows(raw, path);
+  const afterRetired = dropRetiredModuleRows(healed.raw, path);
   const cleaned = dropLegacyShortNameRows(afterRetired.raw, path);
   const validated = validateManifest(cleaned.raw, path);
-  const migrated = migrateClawToAgent(validated);
-  const changed = afterRetired.changed || cleaned.changed || migrated.changed;
-  if (changed) writeManifest(migrated.manifest, path);
-  return migrated.manifest;
+  const changed = healed.changed || afterRetired.changed || cleaned.changed;
+  if (changed) writeManifest(validated, path);
+  return validated;
 }
 
 /**
@@ -724,7 +731,12 @@ function dropRetiredModuleRows(raw: unknown, where: string): { raw: unknown; cha
     if (!row || typeof row !== "object") return true;
     const name = (row as Record<string, unknown>).name;
     if (typeof name !== "string") return true;
-    const retired = RETIRED_MODULES[name];
+    // `claw` is too generic to reserve globally, but the historical Agent row
+    // had a structural identity: name=claw mounted at /claw. Retire only that
+    // shape; an unrelated third-party `claw` on another mount remains valid.
+    const paths = (row as Record<string, unknown>).paths;
+    const retiredClawShape = name === "claw" && Array.isArray(paths) && paths[0] === "/claw";
+    const retired = RETIRED_MODULES[name] ?? (retiredClawShape ? RETIRED_MODULES.agent : undefined);
     if (retired === undefined) return true;
     dropped.push({ name, retiredAt: retired.retiredAt, replacement: retired.replacement });
     return false;
@@ -745,6 +757,91 @@ function dropRetiredModuleRows(raw: unknown, where: string): { raw: unknown; cha
   };
 }
 
+/**
+ * Heal stale OLD-UI-host `app`/`parachute-app` rows on load (hub-parity P5,
+ * 2026-07-11).
+ *
+ * Context: the name `parachute-app` originally belonged to the UI-host module
+ * that renamed to `parachute-surface` on 2026-05-27 (patterns#102). Its
+ * retirement used to be handled by a `RETIRED_MODULES` entry that
+ * `dropRetiredModuleRows` GC'd unconditionally. Hub-parity P5 REUSES the
+ * `parachute-app` manifestName (+ the bare `app` short) for a genuinely NEW,
+ * unrelated module — the super-surface front door — so that retirement entry
+ * had to be removed (keeping it would GC the new module's own row on every
+ * read). This heal is the surgically narrow replacement for the ONE case the
+ * removed retirement still needs to cover: an operator upgrading DIRECTLY from
+ * a pre-rename release (~0.5.13-stable) who skipped every intermediate boot
+ * that would have GC'd their stale row. Without a heal, that stale row would:
+ *   - crash-loop on boot — `reconcilePortToCanonical` rewrites its port to
+ *     1944, then the supervisor spawns the app static-serve shim against a
+ *     `@openparachute/parachute-app` that isn't installed → exit 1 → a
+ *     forever-restarting "app" unit the operator never installed;
+ *   - hijack `/surface/*` if a real `parachute-surface` row is also present
+ *     (both claim `/surface`);
+ *   - and, after `parachute install app`, keep its stale `/surface` mount so
+ *     the app serves under `/surface` while the install's `root_redirect=/app/`
+ *     points the front page at a 404.
+ *
+ * Discriminant (structural — pinned against the OLD-UI-host row shape verified
+ * in `git show origin/main`'s retired-`app` + legacy-short-name test fixtures:
+ * `port: 1946`, `paths: ["/surface"]`, `health: "/surface/..."`):
+ *   - `name` is exactly `"app"` or `"parachute-app"`, AND
+ *   - it is NOT the NEW app's own row (the new app mounts at `/app` — never
+ *     healed regardless of port), AND
+ *   - it carries the OLD-UI-host signature: `paths[0]` is `/surface`-rooted OR
+ *     `port === 1946` (the old canonical slot; now `parachute-surface`'s).
+ *
+ * The NEW app row (`paths: ["/app"]`, port 1944) is structurally disjoint on
+ * BOTH clauses, so it is always left intact. Matches `dropRetiredModuleRows`'s
+ * behavior: a plain DROP + a stderr warning steering the operator to
+ * `parachute install surface` (the same replacement the retirement named).
+ *
+ * Operates on raw JSON (before `validateManifest`) because a stale row can
+ * collide on port 1946 with a real `parachute-surface` row and would otherwise
+ * trip the duplicate-port gate before this heal runs. Runs FIRST in the load
+ * pipeline (ahead of `dropRetiredModuleRows` / `dropLegacyShortNameRows`): a
+ * pre-rename operator can carry BOTH a `parachute-app` and an `app` stale row
+ * (the 2026-05-22 double-write reproducer) — dropping by shape here clears
+ * both, whereas `dropLegacyShortNameRows` would keep the `parachute-app` half.
+ */
+function healStaleUiHostAppRows(raw: unknown, where: string): { raw: unknown; changed: boolean } {
+  if (!raw || typeof raw !== "object") return { raw, changed: false };
+  const services = (raw as Record<string, unknown>).services;
+  if (!Array.isArray(services)) return { raw, changed: false };
+
+  const dropped: string[] = [];
+  const nextServices = services.filter((row) => {
+    if (!row || typeof row !== "object") return true;
+    const rec = row as Record<string, unknown>;
+    const name = rec.name;
+    if (name !== "app" && name !== "parachute-app") return true;
+    const paths = rec.paths;
+    const first = Array.isArray(paths) && typeof paths[0] === "string" ? paths[0] : undefined;
+    // NEW super-surface app mounts at `/app` (port 1944) — never heal it,
+    // whatever its port happens to be after a reconcile/collision walk.
+    if (first === "/app" || first?.startsWith("/app/")) return true;
+    const port = rec.port;
+    const oldSurfaceMount = first === "/surface" || first?.startsWith("/surface/") === true;
+    const oldCanonicalPort = port === 1946;
+    if (!oldSurfaceMount && !oldCanonicalPort) return true;
+    dropped.push(String(name));
+    return false;
+  });
+
+  if (dropped.length === 0) return { raw, changed: false };
+
+  for (const name of dropped) {
+    console.error(
+      `${where}: dropped stale pre-rename '${name}' row (the OLD UI-host module, renamed to parachute-surface 2026-05-27). The name now belongs to the new Parachute app (mount /app, port 1944). If an old daemon is still running, stop it; install the current UI host with \`parachute install surface\`.`,
+    );
+  }
+
+  return {
+    raw: { ...(raw as Record<string, unknown>), services: nextServices },
+    changed: true,
+  };
+}
+
 /**
  * Drop legacy short-name rows when a same-module manifestName row exists
  * on the same port. Handles the duplicate-row class introduced when a
@@ -836,43 +933,6 @@ function dropLegacyShortNameRows(raw: unknown, where: string): { raw: unknown; c
   };
 }
 
-/**
- * Migrate legacy `claw` entries to `agent` in-place. Paraclaw was renamed
- * to parachute-agent across the ecosystem (npm package, mount path, short
- * name); operators who upgraded hub but still have the old paraclaw row
- * in services.json would otherwise see a tile labelled "Claw" and a hub
- * route at `/claw` while their newly-upgraded daemon listens on `/agent`.
- *
- * Idempotent. Only rewrites when both `name === "claw"` AND the first path
- * is `/claw` — narrow enough that a deliberately-named third-party module
- * (e.g. `name: "claw"` on a different mount) is left alone. Health and any
- * `/claw`-rooted paths are rewritten in lockstep.
- */
-function migrateClawToAgent(manifest: ServicesManifest): {
-  manifest: ServicesManifest;
-  changed: boolean;
-} {
-  let changed = false;
-  const services = manifest.services.map((entry) => {
-    if (entry.name !== "claw" || entry.paths[0] !== "/claw") return entry;
-    changed = true;
-    const next: ServiceEntry = {
-      ...entry,
-      name: "agent",
-      paths: entry.paths.map((p) => rewriteClawPath(p)),
-      health: rewriteClawPath(entry.health),
-    };
-    return next;
-  });
-  return { manifest: { services }, changed };
-}
-
-function rewriteClawPath(p: string): string {
-  if (p === "/claw") return "/agent";
-  if (p.startsWith("/claw/")) return `/agent${p.slice("/claw".length)}`;
-  return p;
-}
-
 export function writeManifest(
   manifest: ServicesManifest,
   path: string = SERVICES_MANIFEST_PATH,