@openparachute/hub 0.7.7-rc.8 → 0.7.7-rc.9

package/src/__tests__/services-manifest.test.ts

@@ -1,7 +1,8 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { RETIRED_MODULES } from "../service-spec.ts";
 import {
   type ServiceEntry,
   ServicesManifestError,
@@ -1024,6 +1025,14 @@ describe("claw → agent migration", () => {
 // file so the next read is clean.
 describe("legacy short-name row de-dupe (parachute-app#13 / runner#4)", () => {
   test("drops the short-name row when a same-port manifestName row exists", () => {
+    // Fixture uses `surface` (the ACTUAL short-name twin of `parachute-surface`
+    // per the structural rule: b.name === `parachute-${a.name}`) rather than
+    // `app`. Pre-hub-parity-P5 this test used `app` here, but that only
+    // passed because `app` was ALSO in RETIRED_MODULES at the time — the
+    // unconditional retired-module GC (not this structural short-name rule)
+    // was doing the dropping. Now that `app`/`parachute-app` are un-retired
+    // (hub-parity P5, a new unrelated module claims them), this fixture is
+    // corrected to actually exercise `dropLegacyShortNameRows`.
     const { path, cleanup } = makeTempPath();
     try {
       writeFileSync(
@@ -1038,7 +1047,7 @@ describe("legacy short-name row de-dupe (parachute-app#13 / runner#4)", () => {
               version: "0.2.0",
             },
             {
-              name: "app",
+              name: "surface",
               port: 1946,
               paths: ["/surface"],
               health: "/surface/healthz",
@@ -1195,6 +1204,9 @@ describe("legacy short-name row de-dupe (parachute-app#13 / runner#4)", () => {
   });
 
   test("idempotent — second read leaves the cleaned file alone", () => {
+    // See the fixture note on the first test in this describe block — `app`
+    // is renamed to `surface` here for the same reason (un-retired 2026-07-11,
+    // hub-parity P5).
     const { path, cleanup } = makeTempPath();
     try {
       writeFileSync(
@@ -1209,7 +1221,7 @@ describe("legacy short-name row de-dupe (parachute-app#13 / runner#4)", () => {
               version: "0.2.0",
             },
             {
-              name: "app",
+              name: "surface",
               port: 1946,
               paths: ["/surface"],
               health: "/surface/healthz",
@@ -1232,21 +1244,37 @@ describe("legacy short-name row de-dupe (parachute-app#13 / runner#4)", () => {
 
 // Retired-module row cleanup (hub#334 — Aaron's actual reproducer on
 // 2026-05-22). His services.json originally carried a stale `agent` row at
-// 1946 colliding with `parachute-app`'s canonical slot. NOTE: post the
-// 2026-06-17 channel→agent rename, `agent` is a LIVE module again, so these
-// fixtures use the still-retired `app` (parachute-app) name to exercise the
-// same GC. The legacy-short-name de-dupe doesn't help — a retired short
-// isn't the short-name twin of the colliding row. The retired-module GC
-// fires unconditionally on rows whose name appears in `RETIRED_MODULES`,
-// regardless of port collision.
+// 1946 colliding with `parachute-app`'s canonical slot. The legacy-short-name
+// de-dupe doesn't help — a retired short isn't the short-name twin of the
+// colliding row. The retired-module GC fires unconditionally on rows whose
+// name appears in `RETIRED_MODULES`, regardless of port collision.
+//
+// NOTE (2026-07-11, hub-parity P5): the original fixtures used `agent` —
+// which was a RETIRED_MODULES entry until the 2026-06-17 channel→agent
+// rename re-assigned that name to the live (renamed-from-channel) module —
+// and were later updated to use `app` (parachute-app, retired 2026-05-27).
+// `app`/`parachute-app` are now THEMSELVES un-retired (a new, unrelated
+// module — the real parachute-app super-surface — claims the name for
+// real; see service-spec.ts's RETIRED_MODULES comment). So these tests now
+// inject a throwaway synthetic retired entry via a describe-scoped
+// beforeEach/afterEach rather than depending on production RETIRED_MODULES
+// having a spare non-live name to spend on test fixtures — this mechanism
+// has now been renamed out from under these tests twice.
 describe("retired-module row de-dupe (hub#334)", () => {
-  // NOTE: the original fixtures used `agent` — which was a RETIRED_MODULES
-  // entry until the 2026-06-17 channel→agent rename re-assigned that name to
-  // the live (renamed-from-channel) module. These tests now use `app`
-  // (parachute-app, retired 2026-05-27 — still in RETIRED_MODULES) so they
-  // keep exercising the retired-module GC mechanism on a name that is still
-  // genuinely retired.
-  test("drops a row whose name is in RETIRED_MODULES (app)", () => {
+  const RETIRED_FIXTURE_NAME = "legacy-test-retired-module";
+
+  beforeEach(() => {
+    RETIRED_MODULES[RETIRED_FIXTURE_NAME] = {
+      retiredAt: "2020-01-01",
+      replacement: "n/a — test-only fixture, not a real retirement",
+    };
+  });
+
+  afterEach(() => {
+    delete RETIRED_MODULES[RETIRED_FIXTURE_NAME];
+  });
+
+  test("drops a row whose name is in RETIRED_MODULES", () => {
     const { path, cleanup } = makeTempPath();
     try {
       writeFileSync(
@@ -1254,10 +1282,10 @@ describe("retired-module row de-dupe (hub#334)", () => {
         JSON.stringify({
           services: [
             {
-              name: "app",
+              name: RETIRED_FIXTURE_NAME,
               port: 1946,
-              paths: ["/app"],
-              health: "/app/health",
+              paths: ["/legacy"],
+              health: "/legacy/health",
               version: "0.1.4",
             },
           ],
@@ -1275,7 +1303,7 @@ describe("retired-module row de-dupe (hub#334)", () => {
 
   test("retirement is unconditional — no other rows required", () => {
     // Verifies dropRetiredModuleRows doesn't depend on a collision
-    // partner (unlike dropLegacyShortNameRows). An app row sitting
+    // partner (unlike dropLegacyShortNameRows). A retired row sitting
     // alone is still stale.
     const { path, cleanup } = makeTempPath();
     try {
@@ -1284,10 +1312,10 @@ describe("retired-module row de-dupe (hub#334)", () => {
         JSON.stringify({
           services: [
             {
-              name: "app",
+              name: RETIRED_FIXTURE_NAME,
               port: 9999,
-              paths: ["/app"],
-              health: "/app/health",
+              paths: ["/legacy"],
+              health: "/legacy/health",
               version: "0.1.4",
             },
           ],
@@ -1329,10 +1357,9 @@ describe("retired-module row de-dupe (hub#334)", () => {
   });
 
   test("Aaron's reproducer — retired row + parachute-surface at same port resolves cleanly", () => {
-    // The motivating bug for hub#334 (originally an `agent` row; `agent` is
-    // a live module again post-rename, so this uses the still-retired `app`).
-    // With dropRetiredModuleRows running before validateManifest, the stale
-    // retired row is GC'd and the duplicate-port gate doesn't trip downstream.
+    // The motivating bug for hub#334. With dropRetiredModuleRows running
+    // before validateManifest, the stale retired row is GC'd and the
+    // duplicate-port gate doesn't trip downstream.
     const { path, cleanup } = makeTempPath();
     try {
       writeFileSync(
@@ -1340,10 +1367,10 @@ describe("retired-module row de-dupe (hub#334)", () => {
         JSON.stringify({
           services: [
             {
-              name: "app",
+              name: RETIRED_FIXTURE_NAME,
               port: 1946,
-              paths: ["/app"],
-              health: "/app/health",
+              paths: ["/legacy"],
+              health: "/legacy/health",
               version: "0.1.4",
             },
             {
@@ -1366,12 +1393,11 @@ describe("retired-module row de-dupe (hub#334)", () => {
 
   test("interaction — retired row + legacy short-name pair both cleaned, correct order", () => {
     // Drop order matters: retired-module cleanup runs first, then
-    // legacy-short-name cleanup. This test ensures both passes
-    // compose correctly on a services.json that exercises both
-    // shapes simultaneously. The `app` row is unconditional retire
-    // (the original `agent` fixture is a live module again post-rename);
-    // the parachute-runner + runner pair triggers legacy-short-name
-    // dedup at port 1945.
+    // legacy-short-name cleanup. This test ensures both passes compose
+    // correctly on a services.json that exercises both shapes
+    // simultaneously. The retired-fixture row is unconditional retire; the
+    // parachute-runner + runner pair triggers legacy-short-name dedup at
+    // port 1945.
     const { path, cleanup } = makeTempPath();
     try {
       writeFileSync(
@@ -1379,10 +1405,10 @@ describe("retired-module row de-dupe (hub#334)", () => {
         JSON.stringify({
           services: [
             {
-              name: "app",
+              name: RETIRED_FIXTURE_NAME,
               port: 1946,
-              paths: ["/app"],
-              health: "/app/health",
+              paths: ["/legacy"],
+              health: "/legacy/health",
               version: "0.1.4",
             },
             {
@@ -1411,6 +1437,290 @@ describe("retired-module row de-dupe (hub#334)", () => {
   });
 });
 
+// Stale OLD-UI-host `app`/`parachute-app` row heal (hub-parity P5, B1). The
+// name `parachute-app` used to belong to the UI-host that renamed to
+// `parachute-surface` 2026-05-27; hub-parity P5 reuses the name for the NEW
+// super-surface app (mount /app, port 1944), so the RETIRED_MODULES entry that
+// used to GC the old row was removed. `healStaleUiHostAppRows` is its
+// shape-gated replacement for operators upgrading DIRECTLY from a pre-rename
+// release who still carry the stale `/surface`/1946 row. The load-bearing
+// assertion: a stale old-app row does NOT survive to spawn a crash-looping
+// unit, while the NEW app row (paths:["/app"], port 1944) is left intact.
+describe("stale OLD-UI-host app row heal (hub-parity P5, B1)", () => {
+  test("heals (drops) a stale `parachute-app` row with the old /surface + 1946 shape", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "parachute-app",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.1.4",
+            },
+          ],
+        }),
+      );
+      const m = readManifest(path);
+      // The stale row is gone — it never survives to spawn a crash-looping
+      // `--package @openparachute/parachute-app` unit the operator never
+      // installed.
+      expect(m.services).toHaveLength(0);
+      // Rewritten clean on disk too.
+      const onDisk = JSON.parse(readFileSync(path, "utf8"));
+      expect(onDisk.services).toHaveLength(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("heals a bare-short `app` row with the old shape (the pre-rename self-register name)", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "app",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.1.4",
+            },
+          ],
+        }),
+      );
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("heals on port 1946 even if the stale row's paths got mangled (port discriminant)", () => {
+    // Corroborating OR-clause: a stale row squatting the old canonical 1946
+    // is healed even if paths[0] isn't /surface-rooted anymore.
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "parachute-app",
+              port: 1946,
+              paths: ["/whatever"],
+              health: "/whatever/health",
+              version: "0.1.4",
+            },
+          ],
+        }),
+      );
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("leaves the NEW app row (paths:['/app'], port 1944) intact — structurally disjoint", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "parachute-app",
+              port: 1944,
+              paths: ["/app"],
+              health: "/app/health",
+              version: "0.4.0",
+            },
+          ],
+        }),
+      );
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(1);
+      expect(m.services[0]?.name).toBe("parachute-app");
+      expect(m.services[0]?.port).toBe(1944);
+      expect(m.services[0]?.paths).toEqual(["/app"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("never heals a /app-mounted app row, whatever its port (new-app protection)", () => {
+    // Defensive: even if a new-app row somehow drifted onto a weird port, its
+    // `/app` mount alone protects it from the heal.
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "app",
+              port: 1946,
+              paths: ["/app"],
+              health: "/app/health",
+              version: "0.4.0",
+            },
+          ],
+        }),
+      );
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(1);
+      expect(m.services[0]?.paths).toEqual(["/app"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("coexistence — stale old-app + real parachute-surface both at 1946: stale healed, surface keeps /surface", () => {
+    // The load-bearing coexistence case. Without the heal, the two rows collide
+    // on port 1946 and trip the duplicate-port gate (or the stale row hijacks
+    // /surface). With the heal running first, the stale row is dropped by shape
+    // and surface survives clean.
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "parachute-app",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.1.4",
+            },
+            {
+              name: "parachute-surface",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.2.0",
+            },
+          ],
+        }),
+      );
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(1);
+      expect(m.services[0]?.name).toBe("parachute-surface");
+      expect(m.services[0]?.paths).toEqual(["/surface"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("double-write reproducer — stale `parachute-app` + `app` both at 1946/'/surface' → both healed", () => {
+    // A pre-rename operator hit by the 2026-05-22 double-write carries BOTH
+    // rows. The heal drops both by shape (running ahead of dropLegacyShortNameRows,
+    // which would otherwise keep the `parachute-app` half — still stale).
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "parachute-app",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.1.4",
+            },
+            {
+              name: "app",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.1.4",
+            },
+          ],
+        }),
+      );
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("coexistence — NEW app (/app, 1944) + real surface (/surface, 1946): both survive", () => {
+    // The steady-state post-P5 world: the new app and surface installed side by
+    // side. Neither is healed; both route on their own mounts.
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "parachute-app",
+              port: 1944,
+              paths: ["/app"],
+              health: "/app/health",
+              version: "0.4.0",
+            },
+            {
+              name: "parachute-surface",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.2.0",
+            },
+          ],
+        }),
+      );
+      const m = readManifest(path);
+      const names = m.services.map((s) => s.name).sort();
+      expect(names).toEqual(["parachute-app", "parachute-surface"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("readManifestLenient heals the same stale old-app shape", () => {
+    // The lenient reader shares the same raw-JSON heal pipeline — verify the
+    // crash-loop row is dropped there too (the supervisor's boot path reads
+    // lenient).
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeFileSync(
+        path,
+        JSON.stringify({
+          services: [
+            {
+              name: "parachute-app",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.1.4",
+            },
+            {
+              name: "parachute-vault",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.8",
+            },
+          ],
+        }),
+      );
+      const m = readManifestLenient(path, { warn: () => {} });
+      expect(m.services.map((s) => s.name)).toEqual(["parachute-vault"]);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 describe("readManifestLenient — skips bad entries instead of throwing (hub#406)", () => {
   test("returns the healthy entries when one row has port=0 (the rc.4 app bug)", () => {
     // Reproduces what hub saw 2026-05-26: a fresh deploy installed

package/src/__tests__/setup.test.ts

@@ -142,7 +142,10 @@ describe("setup", () => {
       // rejects duplicate ports between distinct services (hub#195).
       // parachute-runner rides along as a LEGACY row (runner left the
       // registries 2026-07-01): it must neither block the all-installed exit
-      // nor crash the survey.
+      // nor crash the survey. parachute-app (hub-parity P5, 2026-07-11) is
+      // included so this fixture stays truly "everything installed" — without
+      // it, `app` is a genuinely offered-but-uninstalled service and the
+      // non-tty exit code flips from 0 to 1 (nothing left vs. work-to-offer).
       const seeds: Array<{ name: string; port: number }> = [
         { name: "parachute-vault", port: 1940 },
         { name: "parachute-notes", port: 1942 },
@@ -150,6 +153,7 @@ describe("setup", () => {
         { name: "parachute-agent", port: 1941 },
         { name: "parachute-runner", port: 1945 },
         { name: "parachute-surface", port: 1946 },
+        { name: "parachute-app", port: 1944 },
       ];
       for (const s of seeds) {
         upsertService(

package/src/api-modules.ts

@@ -82,7 +82,7 @@ import type { ModuleStartError, ModuleState, Supervisor } from "./supervisor.ts"
 
 /**
  * Resolve a known module to the display + install bootstrap data the admin SPA
- * renders. Reads from FIRST_PARTY_FALLBACKS (notes) first,
+ * renders. Reads from FIRST_PARTY_FALLBACKS (notes / app) first,
  * KNOWN_MODULES (vault / scribe / agent / surface) second.
  *
  * Returns `undefined` if the short is in neither table — a genuinely

package/src/commands/install.ts

@@ -1,3 +1,4 @@
+import type { Database } from "bun:sqlite";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
@@ -15,6 +16,8 @@ import {
   defaultSleep,
   readHubPort,
 } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { resolveRootRedirectDetailed, setRootRedirect } from "../hub-settings.ts";
 import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
 import {
   type ModuleManifest,
@@ -408,6 +411,16 @@ export interface InstallOpts {
    * origin for stable assertions.
    */
   wellKnownOrigin?: string;
+  /**
+   * Test seam for the `app`-only set-if-unset root-redirect write (hub-parity
+   * P5). Production opens `openHubDb(hubDbPath(configDir))` fresh and closes
+   * it after the write; passing this injects an already-open DB (e.g. a
+   * tempdir `hub.db`) so a test never touches the real `~/.parachute/hub.db`.
+   * Passing this ALSO opts a tempdir-manifestPath test INTO the write path —
+   * mirrors `guidanceCtx`'s discriminant: without it, the production gate
+   * (`manifestPath === SERVICES_MANIFEST_PATH`) skips the write entirely.
+   */
+  rootRedirectDb?: Database;
 }
 
 async function defaultRunner(cmd: readonly string[]): Promise<number> {
@@ -1351,6 +1364,37 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     }
   }
 
+  // App-only: default the hub's bare `/` redirect to the app's front door on
+  // first install (hub-parity P5, 2026-07-11) — SET-IF-UNSET ONLY, never
+  // clobbering an operator's existing choice (`parachute hub
+  // set-root-redirect` or the admin SPA PUT both still win on any later run,
+  // and either can change it back). "Unset" means the resolved redirect is
+  // still the built-in `/admin` DEFAULT — i.e. NEITHER the DB row NOR the
+  // `PARACHUTE_HUB_ROOT_REDIRECT` env var (container deploys pin their landing
+  // page there) has set it. Gating on `getRootRedirect(db) === null` would
+  // miss the env tier and silently override an env-configured operator, since
+  // the DB row we'd write wins over env on read (`resolveRootRedirectDetailed`
+  // is DB-first). Gated on the same production-vs-test discriminant the
+  // guidance probe below uses: a test driving install against a tempdir
+  // manifestPath never opens the real `~/.parachute/hub.db` unless it opts in
+  // via `opts.rootRedirectDb`.
+  if (short === "app") {
+    const dbProbeAllowed =
+      opts.rootRedirectDb !== undefined || manifestPath === SERVICES_MANIFEST_PATH;
+    if (dbProbeAllowed) {
+      const db = opts.rootRedirectDb ?? openHubDb(hubDbPath(configDir));
+      try {
+        if (resolveRootRedirectDetailed(db).source === "default") {
+          setRootRedirect(db, "/app/");
+          log("✓ The hub's front page (`/`) now opens the app at /app/.");
+          log("  Change it any time: `parachute hub set-root-redirect <path>` or the admin SPA.");
+        }
+      } finally {
+        if (!opts.rootRedirectDb) db.close();
+      }
+    }
+  }
+
   // Per-service install footer — canonical next-step URLs and configuration
   // hints. Vault prints its own (richer) footer from `parachute-vault init`
   // (PR #166), so the spec leaves vault out and we don't double up here.

package/src/commands/setup.ts

@@ -110,7 +110,7 @@ function defaultAvailability(): InteractiveAvailability {
 
 /**
  * Survey ALL known first-party shortnames (vault / notes / scribe / agent /
- * surface) regardless of tier — `installed` is true when the service
+ * surface / app) regardless of tier — `installed` is true when the service
  * has a row in services.json. The fresh-install OFFER is narrowed downstream
  * by `isOfferable` (drops already-installed + `deprecated`-tier shorts —
  * notes); agent (`experimental`) is flagged exploratory in its blurb
@@ -121,7 +121,7 @@ function defaultAvailability(): InteractiveAvailability {
  * like any unknown row it neither blocks setup nor appears in the offer.
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
- * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
+ * shorts (notes / app — both carry a vendored manifest). KNOWN_MODULES shorts
  * (vault / scribe / agent / surface) ship `.parachute/module.json`
  * and self-register; pre-install we know manifestName + the urlForEntry quirk
  * from `KNOWN_MODULES[short].extras`, which is all the survey/summary needs.
@@ -175,8 +175,13 @@ export function isOfferable(choice: { short: string; installed: boolean }): bool
 const BLURBS: Record<string, string> = {
   vault: "knowledge graph (MCP) — your owner-authenticated note + tag store",
   surface: "Parachute UI host — auto-installs Notes on first boot (the recommended UI path)",
-  // `app` is the pre-2026-05-27 name for `surface`; kept for any legacy survey row.
-  app: "Parachute UI host — auto-installs Notes on first boot (recommended over notes-daemon)",
+  // hub-parity P5 (2026-07-11): `app` is now the NEW super-surface front
+  // door (@openparachute/parachute-app) — a real FIRST_PARTY_FALLBACKS
+  // entry, not a legacy survey row. It is UNRELATED to the pre-2026-05-27
+  // `app` package that renamed to `surface` (that blurb lives under the
+  // `surface` key above); the two just happen to share the short name
+  // across a rename.
+  app: "the super-surface front door — one app to sign in, browse your vault, and manage your hub/cloud",
   // notes is `deprecated` (not offered on a fresh setup) — this blurb only
   // renders if a legacy install surfaces it in the survey.
   notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `surface`)",

package/src/help.ts

@@ -362,11 +362,11 @@ Exit codes:
 
 Example:
   $ parachute status
-  SERVICE          PORT  VERSION  STATE   PID    UPTIME  LATENCY  SOURCE
-  parachute-vault  1940  0.2.4    active  12345  2h 13m  2ms      bun-linked → parachute-vault @ 8aa167b
+  SERVICE            PORT  VERSION  STATE   PID    UPTIME  LATENCY  SOURCE
+  parachute-vault    1940  0.2.4    active  12345  2h 13m  2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
-  parachute-app    1946  0.2.0    active  12346  2h 12m  3ms      npm (0.2.0-rc.4)
-    → http://127.0.0.1:1946/surface/notes
+  parachute-surface  1946  0.2.0    active  12346  2h 12m  3ms      npm (0.2.0-rc.4)
+    → http://127.0.0.1:1946/surface
 `;
 }
 
@@ -551,8 +551,9 @@ Examples:
 Module start commands (run by the supervisor under \`serve\`):
   vault     parachute-vault serve
   scribe    parachute-scribe serve
-  app       parachute-app serve
+  surface   parachute-surface serve
   agent     parachute-agent
+  app       bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]> --package @openparachute/parachute-app
   notes     bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]>   # back-compat: legacy notes-daemon
 `;
 }