@openparachute/hub 0.7.3-rc.5 → 0.7.3-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3-rc.5",
+  "version": "0.7.3-rc.7",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/api-modules.test.ts

@@ -219,9 +219,11 @@ describe("GET /api/modules", () => {
     // yet. Post-2026-06-09 (modular-UI architecture, P2) discovery is driven
     // by the UNION of the bootstrap registries (KNOWN_MODULES ∪
     // FIRST_PARTY_FALLBACKS), NOT a curated whitelist. Every known module
-    // surfaces — core (vault/scribe/surface) in the headline tier, the rest
-    // (agent/runner/notes) as `experimental` — so the agent-not-installed
-    // class (running but invisible) can't recur.
+    // surfaces — core (vault/scribe/surface) in the headline tier, agent as
+    // `experimental`, and notes/runner as `deprecated` (2026-06-25, still
+    // resolvable but not offered for fresh installs) — so the agent-not-installed
+    // class (running but invisible) can't recur while deprecated modules stop
+    // being pushed on a fresh box.
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
     const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
       db: h.db,
@@ -233,8 +235,9 @@ describe("GET /api/modules", () => {
     const body = (await res.json()) as {
       modules: Array<{
         short: string;
-        focus: "core" | "experimental";
+        focus: "core" | "experimental" | "deprecated";
         available: boolean;
+        available_to_install: boolean;
         installed: boolean;
         latest_version: string | null;
       }>;
@@ -242,12 +245,14 @@ describe("GET /api/modules", () => {
     };
     const shorts = body.modules.map((m) => m.short);
     // The core tier leads, in the recommended install order (vault → scribe),
-    // ahead of every experimental module.
+    // ahead of every experimental module, which lead the deprecated ones.
     expect(shorts.indexOf("vault")).toBeLessThan(shorts.indexOf("scribe"));
     expect(shorts.indexOf("scribe")).toBeLessThan(shorts.indexOf("agent"));
-    expect(shorts.indexOf("scribe")).toBeLessThan(shorts.indexOf("runner"));
-    // Every known module is discoverable — vault/scribe/surface (core) +
-    // agent/runner/notes (experimental).
+    // agent (experimental) sorts ahead of notes/runner (deprecated).
+    expect(shorts.indexOf("agent")).toBeLessThan(shorts.indexOf("runner"));
+    expect(shorts.indexOf("agent")).toBeLessThan(shorts.indexOf("notes"));
+    // Every known module is discoverable — vault/scribe/surface (core),
+    // agent (experimental), notes/runner (deprecated).
     for (const s of ["vault", "scribe", "surface", "agent", "runner", "notes"]) {
       expect(shorts).toContain(s);
     }
@@ -257,15 +262,65 @@ describe("GET /api/modules", () => {
     expect(byShort.get("scribe")?.focus).toBe("core");
     expect(byShort.get("surface")?.focus).toBe("core");
     expect(byShort.get("agent")?.focus).toBe("experimental");
-    expect(byShort.get("runner")?.focus).toBe("experimental");
-    expect(byShort.get("notes")?.focus).toBe("experimental");
+    expect(byShort.get("runner")?.focus).toBe("deprecated");
+    expect(byShort.get("notes")?.focus).toBe("deprecated");
+    // `available` stays true for every known module (re-installable), but the
+    // fresh-install OFFER (`available_to_install`) drops the deprecated tier —
+    // notes/runner aren't pushed on a fresh box; agent (experimental) still is.
     expect(body.modules.every((m) => m.available)).toBe(true);
+    expect(byShort.get("vault")?.available_to_install).toBe(true);
+    expect(byShort.get("scribe")?.available_to_install).toBe(true);
+    expect(byShort.get("surface")?.available_to_install).toBe(true);
+    expect(byShort.get("agent")?.available_to_install).toBe(true);
+    expect(byShort.get("runner")?.available_to_install).toBe(false);
+    expect(byShort.get("notes")?.available_to_install).toBe(false);
     expect(body.modules.every((m) => !m.installed)).toBe(true);
     expect(body.modules.every((m) => m.latest_version === "0.9.9")).toBe(true);
     // Supervisor wasn't injected → flag reflects that.
     expect(body.supervisor_available).toBe(false);
   });
 
+  test("an installed deprecated module (runner) still surfaces for management but is not offered for fresh install (2026-06-25)", async () => {
+    // A legacy operator with runner on disk: the row must remain visible
+    // (installed: true) + manageable, in the `deprecated` tier — but
+    // `available_to_install` is false so the SPA's install catalog won't push
+    // it. Mirrors the notes-daemon back-compat posture.
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-runner",
+        port: 1945,
+        paths: ["/runner", "/.parachute"],
+        health: "/runner/healthz",
+        version: "0.2.0",
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => null,
+    });
+    const body = (await res.json()) as {
+      modules: Array<{
+        short: string;
+        focus: "core" | "experimental" | "deprecated";
+        installed: boolean;
+        installed_version: string | null;
+        available: boolean;
+        available_to_install: boolean;
+      }>;
+    };
+    const runner = body.modules.find((m) => m.short === "runner");
+    expect(runner).toBeDefined();
+    expect(runner?.installed).toBe(true);
+    expect(runner?.installed_version).toBe("0.2.0");
+    expect(runner?.focus).toBe("deprecated");
+    // Still hub-installable (re-install path) but NOT offered fresh.
+    expect(runner?.available).toBe(true);
+    expect(runner?.available_to_install).toBe(false);
+  });
+
   test("scribe row carries package + display props from KNOWN_MODULES", async () => {
     // Spot-check the wire shape resolves scribe-specific fields
     // (package, displayName, tagline) from KNOWN_MODULES rather than a

package/src/__tests__/api-vault-caps.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Tests for `/api/vault-caps*` (B5 admin visibility / D-slice).
+ * Covers:
+ *
+ *   - Auth boundary: GET + PUT require a bearer carrying `parachute:host:admin`.
+ *   - GET joins services.json vault names with persisted caps (uncapped =
+ *     null cap_bytes), ordered by name.
+ *   - PUT sets/updates a cap (upsert), validates positive cap, refuses a
+ *     vault not registered in services.json (400 vault_not_found).
+ *   - 405 on wrong methods.
+ */
+import type { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { handleListVaultCaps, handleSetVaultCap } from "../api-vault-caps.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { signAccessToken } from "../jwt-sign.ts";
+import { createUser } from "../users.ts";
+import { getVaultCapBytes, setVaultCap } from "../vault-caps.ts";
+
+const ISSUER = "https://hub.test";
+const HOST_ADMIN_SCOPE = "parachute:host:admin";
+
+interface Harness {
+  db: Database;
+  manifestPath: string;
+  cleanup: () => void;
+}
+
+function manifestWithVaults(...names: string[]): string {
+  const paths = names.map((n) => `/vault/${n}`);
+  return JSON.stringify({
+    services: [
+      { name: "parachute-vault", port: 4101, paths, health: "/health", version: "0.0.0-test" },
+    ],
+  });
+}
+
+function makeHarness(servicesJson?: string): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-api-vault-caps-"));
+  const db = openHubDb(hubDbPath(dir));
+  const manifestPath = join(dir, "services.json");
+  writeFileSync(manifestPath, servicesJson ?? manifestWithVaults("beta", "personal"));
+  return {
+    db,
+    manifestPath,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+let harness: Harness;
+beforeEach(() => {
+  harness = makeHarness();
+});
+afterEach(() => {
+  harness.cleanup();
+});
+
+async function makeAdminBearer(scopes = [HOST_ADMIN_SCOPE]): Promise<string> {
+  const user = await createUser(harness.db, "operator", "any-password", {
+    allowMulti: true,
+    passwordChanged: true,
+  });
+  const minted = await signAccessToken(harness.db, {
+    sub: user.id,
+    scopes,
+    audience: "hub",
+    clientId: "parachute-hub-spa",
+    issuer: ISSUER,
+    ttlSeconds: 600,
+  });
+  return minted.token;
+}
+
+function req(path: string, init: RequestInit = {}): Request {
+  return new Request(`${ISSUER}${path}`, init);
+}
+
+function withBearer(path: string, bearer: string, init: RequestInit = {}): Request {
+  const headers = new Headers(init.headers ?? {});
+  headers.set("authorization", `Bearer ${bearer}`);
+  return new Request(`${ISSUER}${path}`, { ...init, headers });
+}
+
+function deps() {
+  return { db: harness.db, issuer: ISSUER, manifestPath: harness.manifestPath };
+}
+
+describe("handleListVaultCaps", () => {
+  test("401 with no Authorization header", async () => {
+    const res = await handleListVaultCaps(req("/api/vault-caps"), deps());
+    expect(res.status).toBe(401);
+  });
+
+  test("403 when bearer lacks parachute:host:admin", async () => {
+    const bearer = await makeAdminBearer(["other:scope"]);
+    const res = await handleListVaultCaps(withBearer("/api/vault-caps", bearer), deps());
+    expect(res.status).toBe(403);
+  });
+
+  test("405 on POST", async () => {
+    const bearer = await makeAdminBearer();
+    const res = await handleListVaultCaps(
+      withBearer("/api/vault-caps", bearer, { method: "POST" }),
+      deps(),
+    );
+    expect(res.status).toBe(405);
+  });
+
+  test("joins services.json vaults with caps, uncapped = null cap_bytes", async () => {
+    const bearer = await makeAdminBearer();
+    // Only "beta" has a persisted cap; "personal" stays uncapped.
+    setVaultCap(harness.db, "beta", 1024 * 1024 * 1024);
+    const res = await handleListVaultCaps(withBearer("/api/vault-caps", bearer), deps());
+    expect(res.status).toBe(200);
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    const body = (await res.json()) as {
+      vault_caps: Array<{ vault_name: string; cap_bytes: number | null }>;
+    };
+    // Both vaults present, ordered by name (beta, personal).
+    expect(body.vault_caps.map((c) => c.vault_name)).toEqual(["beta", "personal"]);
+    const beta = body.vault_caps.find((c) => c.vault_name === "beta");
+    const personal = body.vault_caps.find((c) => c.vault_name === "personal");
+    expect(beta?.cap_bytes).toBe(1024 * 1024 * 1024);
+    expect(personal?.cap_bytes).toBeNull();
+  });
+});
+
+describe("handleSetVaultCap", () => {
+  test("401 with no Authorization header", async () => {
+    const res = await handleSetVaultCap(
+      req("/api/vault-caps/beta", {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ cap_bytes: 1000 }),
+      }),
+      "beta",
+      deps(),
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("403 when bearer lacks parachute:host:admin", async () => {
+    const bearer = await makeAdminBearer(["other:scope"]);
+    const res = await handleSetVaultCap(
+      withBearer("/api/vault-caps/beta", bearer, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ cap_bytes: 1000 }),
+      }),
+      "beta",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("400 on a fractional (non-integer) cap", async () => {
+    const bearer = await makeAdminBearer();
+    const res = await handleSetVaultCap(
+      withBearer("/api/vault-caps/beta", bearer, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ cap_bytes: 1.5 }),
+      }),
+      "beta",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("405 on GET", async () => {
+    const bearer = await makeAdminBearer();
+    const res = await handleSetVaultCap(withBearer("/api/vault-caps/beta", bearer), "beta", deps());
+    expect(res.status).toBe(405);
+  });
+
+  test("sets a cap on a registered vault and persists it (upsert)", async () => {
+    const bearer = await makeAdminBearer();
+    const res = await handleSetVaultCap(
+      withBearer("/api/vault-caps/beta", bearer, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ cap_bytes: 2 * 1024 * 1024 * 1024 }),
+      }),
+      "beta",
+      deps(),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { vault_cap: { cap_bytes: number } };
+    expect(body.vault_cap.cap_bytes).toBe(2 * 1024 * 1024 * 1024);
+    expect(getVaultCapBytes(harness.db, "beta")).toBe(2 * 1024 * 1024 * 1024);
+  });
+
+  test("400 vault_not_found for a vault not in services.json", async () => {
+    const bearer = await makeAdminBearer();
+    const res = await handleSetVaultCap(
+      withBearer("/api/vault-caps/ghost", bearer, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ cap_bytes: 1000 }),
+      }),
+      "ghost",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("vault_not_found");
+    // Nothing persisted for the rejected name.
+    expect(getVaultCapBytes(harness.db, "ghost")).toBeNull();
+  });
+
+  test("400 on non-positive cap", async () => {
+    const bearer = await makeAdminBearer();
+    const res = await handleSetVaultCap(
+      withBearer("/api/vault-caps/beta", bearer, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ cap_bytes: 0 }),
+      }),
+      "beta",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("invalid_request");
+  });
+});

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

@@ -277,11 +277,13 @@ describe("validateModuleManifest", () => {
   // --- 2026-06-09 modular-UI architecture P1 fields: focus / configUiUrl /
   //     adminCapabilities / events / actions. All optional + additive. ---
 
-  test("focus accepts core / experimental and rejects anything else", () => {
+  test("focus accepts core / experimental / deprecated and rejects anything else", () => {
     expect(validateModuleManifest({ ...VALID, focus: "core" }, "x").focus).toBe("core");
     expect(validateModuleManifest({ ...VALID, focus: "experimental" }, "x").focus).toBe(
       "experimental",
     );
+    // `deprecated` tier (2026-06-25) — a module can self-declare it.
+    expect(validateModuleManifest({ ...VALID, focus: "deprecated" }, "x").focus).toBe("deprecated");
     // Absent stays absent (hub falls back to its default map downstream).
     expect(validateModuleManifest(VALID, "x").focus).toBeUndefined();
     expect(() => validateModuleManifest({ ...VALID, focus: "headline" }, "x")).toThrow(/focus/);

package/src/__tests__/service-spec-discovery.test.ts

@@ -53,14 +53,34 @@ describe("focusForShort", () => {
     expect(focusForShort("vault")).toBe("core");
     expect(focusForShort("scribe")).toBe("core");
     expect(focusForShort("surface")).toBe("core");
+    // agent stays a legit experimental preview — still offered on a fresh install.
     expect(focusForShort("agent")).toBe("experimental");
-    expect(focusForShort("runner")).toBe("experimental");
-    expect(focusForShort("notes")).toBe("experimental");
+    // notes (notes-daemon, deprecated 2026-05-22) + runner (per Aaron
+    // 2026-06-25, not for new installs) are `deprecated`: still resolvable +
+    // shown-if-installed, but NOT offered on a fresh setup.
+    expect(focusForShort("runner")).toBe("deprecated");
+    expect(focusForShort("notes")).toBe("deprecated");
   });
 
   test("unlisted shorts default to experimental", () => {
     expect(focusForShort("some-third-party-module")).toBe("experimental");
   });
+
+  test("a declared deprecated focus is honored over the default map", () => {
+    // A module can self-declare `deprecated` in its module.json.
+    expect(focusForShort("agent", "deprecated")).toBe("deprecated");
+  });
+
+  test("deprecated shorts stay resolvable (discoverable) — back-compat for existing installs", () => {
+    // The deprecated tier de-emphasizes + drops the fresh-install OFFER; it does
+    // NOT remove the short from the resolution surface, so an existing
+    // notes/runner install keeps routing + lifecycle.
+    const shorts = discoverableShorts();
+    expect(shorts).toContain("notes");
+    expect(shorts).toContain("runner");
+    expect(isKnownModuleShort("notes")).toBe(true);
+    expect(isKnownModuleShort("runner")).toBe(true);
+  });
 });
 
 describe("isKnownModuleShort", () => {

package/src/__tests__/setup.test.ts

@@ -3,7 +3,7 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { InstallOpts } from "../commands/install.ts";
-import { parseServicePicks, setup } from "../commands/setup.ts";
+import { isOfferable, parseServicePicks, setup } from "../commands/setup.ts";
 import { upsertService } from "../services-manifest.ts";
 
 interface InstallCall {
@@ -110,6 +110,26 @@ describe("parseServicePicks", () => {
   });
 });
 
+describe("isOfferable (fresh-install OFFER, 2026-06-25)", () => {
+  test("offers an uninstalled core/experimental module", () => {
+    expect(isOfferable({ short: "vault", installed: false })).toBe(true);
+    expect(isOfferable({ short: "scribe", installed: false })).toBe(true);
+    expect(isOfferable({ short: "surface", installed: false })).toBe(true);
+    // agent stays a legit experimental preview — still offered.
+    expect(isOfferable({ short: "agent", installed: false })).toBe(true);
+  });
+
+  test("does NOT offer a deprecated module (notes / runner) on a fresh install", () => {
+    expect(isOfferable({ short: "notes", installed: false })).toBe(false);
+    expect(isOfferable({ short: "runner", installed: false })).toBe(false);
+  });
+
+  test("never offers an already-installed module regardless of tier", () => {
+    expect(isOfferable({ short: "vault", installed: true })).toBe(false);
+    expect(isOfferable({ short: "notes", installed: true })).toBe(false);
+  });
+});
+
 describe("setup", () => {
   test("exits 0 with friendly note when every known service is installed", async () => {
     const h = makeHarness();
@@ -155,6 +175,96 @@ describe("setup", () => {
     }
   });
 
+  test("fresh box: the offered 'Available to install' list excludes deprecated notes/runner (2026-06-25)", async () => {
+    const h = makeHarness();
+    try {
+      // 'all' picks every OFFERED service. With a clean services.json the survey
+      // sees every known short; the offered filter must drop notes + runner
+      // (deprecated) while keeping vault/scribe/surface/agent. Only vault +
+      // scribe have pre-install follow-up prompts (vault name, scribe provider);
+      // surface + agent have none — so the scripted answers below are complete.
+      const availability = scriptedAvailability([
+        "all", // pick everything offered
+        "default", // vault name (vault is in the offered set)
+        "1", // scribe provider
+      ]);
+      const code = await setup({
+        manifestPath: h.manifestPath,
+        configDir: h.configDir,
+        log: (l) => h.logs.push(l),
+        availability,
+        installFn: async (short, opts) => {
+          h.calls.push({ short, opts });
+          return 0;
+        },
+      });
+      expect(code).toBe(0);
+      // The "Available to install" banner must NOT list notes / runner.
+      const joined = h.logs.join("\n");
+      const availableBlock = joined.slice(joined.indexOf("Available to install:"));
+      expect(availableBlock).not.toMatch(/\bnotes\b/);
+      expect(availableBlock).not.toMatch(/\brunner\b/);
+      // …and `install()` is never invoked for the deprecated shorts.
+      const installedShorts = h.calls.map((c) => c.short);
+      expect(installedShorts).not.toContain("notes");
+      expect(installedShorts).not.toContain("runner");
+      // The non-deprecated set is still offered + installed.
+      expect(installedShorts).toContain("vault");
+      expect(installedShorts).toContain("scribe");
+      expect(installedShorts).toContain("surface");
+      expect(installedShorts).toContain("agent");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("an already-installed deprecated module still shows in 'Already installed' + isn't re-offered (back-compat)", async () => {
+    const h = makeHarness();
+    try {
+      // Legacy operator with runner (deprecated) on disk. It must surface in the
+      // "Already installed" banner (so they know it's there + can manage it via
+      // `parachute <verb> runner`), and must NOT reappear in the fresh-install
+      // OFFER list.
+      upsertService(
+        {
+          name: "parachute-runner",
+          version: "0.2.0",
+          port: 1945,
+          paths: ["/runner"],
+          health: "/runner/healthz",
+        },
+        h.manifestPath,
+      );
+      const availability = scriptedAvailability([
+        "surface", // pick a still-offered module
+      ]);
+      const code = await setup({
+        manifestPath: h.manifestPath,
+        configDir: h.configDir,
+        log: (l) => h.logs.push(l),
+        availability,
+        installFn: async (short, opts) => {
+          h.calls.push({ short, opts });
+          return 0;
+        },
+      });
+      expect(code).toBe(0);
+      const joined = h.logs.join("\n");
+      // Banner lists runner as already installed…
+      const installedBlock = joined.slice(
+        joined.indexOf("Already installed:"),
+        joined.indexOf("Available to install:"),
+      );
+      expect(installedBlock).toMatch(/\brunner\b/);
+      // …but runner is NOT in the fresh-install offer.
+      const availableBlock = joined.slice(joined.indexOf("Available to install:"));
+      expect(availableBlock).not.toMatch(/\brunner\b/);
+      expect(h.calls.map((c) => c.short)).not.toContain("runner");
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("rejects non-TTY when there's work to offer", async () => {
     const h = makeHarness();
     try {
@@ -220,7 +330,9 @@ describe("setup", () => {
     const h = makeHarness();
     try {
       const availability = scriptedAvailability([
-        "notes", // single pick — no follow-up prompts
+        // surface — a non-deprecated module with no follow-up prompts. (notes,
+        // the prior pick, is now `deprecated` → not in the offered set.)
+        "surface",
       ]);
       const code = await setup({
         manifestPath: h.manifestPath,
@@ -231,10 +343,10 @@ describe("setup", () => {
           h.calls.push({ short, opts });
           upsertService(
             {
-              name: "parachute-notes",
+              name: "parachute-surface",
               version: "0.1.0",
-              port: 1942,
-              paths: ["/notes"],
+              port: 1946,
+              paths: ["/surface"],
               health: "/health",
             },
             opts.manifestPath ?? h.manifestPath,
@@ -257,7 +369,8 @@ describe("setup", () => {
     const h = makeHarness();
     try {
       const availability = scriptedAvailability([
-        "vault, notes", // multi-select
+        // surface replaces the prior `notes` pick (now deprecated → not offered).
+        "vault, surface", // multi-select
         "default", // vault name
       ]);
       const code = await setup({
@@ -270,10 +383,10 @@ describe("setup", () => {
           if (short === "vault") return 7; // fail vault
           upsertService(
             {
-              name: "parachute-notes",
+              name: "parachute-surface",
               version: "0.1.0",
-              port: 1942,
-              paths: ["/notes"],
+              port: 1946,
+              paths: ["/surface"],
               health: "/health",
             },
             opts.manifestPath ?? h.manifestPath,
@@ -282,7 +395,7 @@ describe("setup", () => {
         },
       });
       expect(code).toBe(7);
-      expect(h.calls.map((c) => c.short)).toEqual(["vault", "notes"]);
+      expect(h.calls.map((c) => c.short)).toEqual(["vault", "surface"]);
       expect(h.logs.join("\n")).toMatch(/non-zero exit code/);
     } finally {
       h.cleanup();
@@ -295,7 +408,8 @@ describe("setup", () => {
       const availability = scriptedAvailability([
         "9", // out-of-range index — loop re-prompts
         "nope", // unknown name — loop re-prompts again
-        "notes", // single pick, no follow-up prompts
+        // surface — a non-deprecated single pick with no follow-up prompts.
+        "surface",
       ]);
       const code = await setup({
         manifestPath: h.manifestPath,
@@ -306,10 +420,10 @@ describe("setup", () => {
           h.calls.push({ short, opts });
           upsertService(
             {
-              name: "parachute-notes",
+              name: "parachute-surface",
               version: "0.1.0",
-              port: 1942,
-              paths: ["/notes"],
+              port: 1946,
+              paths: ["/surface"],
               health: "/health",
             },
             opts.manifestPath ?? h.manifestPath,
@@ -318,7 +432,7 @@ describe("setup", () => {
         },
       });
       expect(code).toBe(0);
-      expect(h.calls.map((c) => c.short)).toEqual(["notes"]);
+      expect(h.calls.map((c) => c.short)).toEqual(["surface"]);
       expect(availability.remaining()).toBe(0);
       const joined = h.logs.join("\n");
       expect(joined).toMatch(/out-of-range/);