@openparachute/hub 0.7.2 → 0.7.3-rc.10

package/src/__tests__/rate-limit.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import {
+  AUTH_IP_CEILING_MAX_ATTEMPTS,
   CHANGE_PASSWORD_MAX_ATTEMPTS,
   CHANGE_PASSWORD_WINDOW_MS,
   MAX_ATTEMPTS,
@@ -7,9 +8,12 @@ import {
   UNKNOWN_IP_SENTINEL,
   WINDOW_MS,
   __resetForTests,
+  authIpCeilingRateLimiter,
   changePasswordRateLimiter,
   checkAndRecord,
   clientIpFromRequest,
+  compositeKey,
+  loginRateLimiter,
 } from "../rate-limit.ts";
 
 afterEach(() => {
@@ -302,3 +306,85 @@ describe("changePasswordRateLimiter — tighter floor for /account/change-passwo
     expect(changePasswordRateLimiter.checkAndRecord("user-a", now).allowed).toBe(true);
   });
 });
+
+// The shared-egress-IP fix: the per-account FLOOR is now keyed by
+// `compositeKey(ip, identity)` so a room of users behind ONE NAT'd /
+// Cloudflare egress IP doesn't pool into one 5-slot bucket. A coarse per-IP
+// CEILING (60/15min) backstops username-rotation across the floors.
+describe("compositeKey + shared-egress-IP login floor", () => {
+  test("normalizes identity: trims + lowercases so casing/whitespace share a bucket", () => {
+    expect(compositeKey("1.2.3.4", "Alice")).toBe("1.2.3.4|alice");
+    expect(compositeKey("1.2.3.4", "  ALICE  ")).toBe("1.2.3.4|alice");
+    // Case-flip evasion is closed: 'Alice' and 'alice' resolve to one key.
+    expect(compositeKey("1.2.3.4", "Alice")).toBe(compositeKey("1.2.3.4", "alice"));
+  });
+
+  // (a) REGRESSION: two distinct usernames from the SAME ip each get a full
+  // independent 5/15min floor (the shared-wifi bug). Before the fix both would
+  // have pooled into one per-IP bucket and the second user's 1st attempt would
+  // have been the 6th overall → 429.
+  test("(a) two usernames from the same IP each get an independent 5/15min floor", () => {
+    const ip = "203.0.113.7";
+    const now = new Date("2026-06-25T12:00:00Z");
+    // Alice exhausts her floor.
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "alice"), now).allowed).toBe(true);
+    }
+    expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "alice"), now).allowed).toBe(false);
+    // Bob (same IP, different username) still has a fresh full floor.
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "bob"), now).allowed).toBe(true);
+    }
+    expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "bob"), now).allowed).toBe(false);
+  });
+
+  // (b) a single (ip,username) still denies on the 6th attempt.
+  test("(b) a single (ip,username) still denies on the 6th attempt", () => {
+    const ip = "203.0.113.7";
+    const now = new Date("2026-06-25T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "alice"), now).allowed).toBe(true);
+    }
+    const denied = loginRateLimiter.checkAndRecord(compositeKey(ip, "alice"), now);
+    expect(denied.allowed).toBe(false);
+    expect(denied.retryAfterSeconds).toBe(WINDOW_MS / 1000);
+  });
+
+  // (c) the per-IP ceiling denies on the 61st attempt from one IP even across
+  // rotated usernames (each username's own floor never trips because each only
+  // sees one attempt, but the coarse ceiling caps total per-IP volume).
+  test("(c) per-IP ceiling denies the 61st attempt across rotated usernames", () => {
+    const ip = "203.0.113.7";
+    const now = new Date("2026-06-25T12:00:00Z");
+    for (let i = 0; i < AUTH_IP_CEILING_MAX_ATTEMPTS; i++) {
+      // Rotate a fresh username every attempt so no per-account floor ever fills.
+      expect(loginRateLimiter.checkAndRecord(compositeKey(ip, `u${i}`), now).allowed).toBe(true);
+      expect(authIpCeilingRateLimiter.checkAndRecord(ip, now).allowed).toBe(true);
+    }
+    // 61st attempt: a brand-new username (floor is fresh) but the ceiling is full.
+    expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "u60"), now).allowed).toBe(true);
+    const ceilingDenied = authIpCeilingRateLimiter.checkAndRecord(ip, now);
+    expect(ceilingDenied.allowed).toBe(false);
+    expect(ceilingDenied.retryAfterSeconds).toBe(WINDOW_MS / 1000);
+  });
+
+  test("the ceiling is per-IP: a different IP is unaffected by another's full ceiling", () => {
+    const now = new Date("2026-06-25T12:00:00Z");
+    for (let i = 0; i < AUTH_IP_CEILING_MAX_ATTEMPTS; i++) {
+      authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now);
+    }
+    expect(authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now).allowed).toBe(false);
+    expect(authIpCeilingRateLimiter.checkAndRecord("198.51.100.99", now).allowed).toBe(true);
+  });
+
+  test("ceiling matches the signup precedent (60) and `__resetForTests` clears it", () => {
+    expect(AUTH_IP_CEILING_MAX_ATTEMPTS).toBe(60);
+    const now = new Date("2026-06-25T12:00:00Z");
+    for (let i = 0; i < AUTH_IP_CEILING_MAX_ATTEMPTS; i++) {
+      authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now);
+    }
+    expect(authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now).allowed).toBe(false);
+    __resetForTests();
+    expect(authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now).allowed).toBe(true);
+  });
+});

package/src/__tests__/scribe-config.test.ts

@@ -3,10 +3,15 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "nod
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
+  MIN_RAM_MIB,
   SCRIBE_DEFAULT_PROVIDER,
   SCRIBE_PROVIDERS,
   apiKeyEnvFor,
+  clearScribeProvider,
+  decideLocalProvider,
   isKnownScribeProvider,
+  platformLocalProvider,
+  readAvailableRamMib,
   readScribeProviderState,
   scribeConfigPath,
   scribeEnvPath,
@@ -41,6 +46,118 @@ describe("provider catalog", () => {
   });
 });
 
+describe("platformLocalProvider — the Linux 'local' trap fix", () => {
+  test("macOS → parakeet-mlx", () => {
+    expect(platformLocalProvider("darwin")).toBe("parakeet-mlx");
+  });
+
+  test("Linux → onnx-asr (NOT the macOS-only parakeet-mlx)", () => {
+    expect(platformLocalProvider("linux")).toBe("onnx-asr");
+  });
+
+  test("unsupported platform → null (steer to cloud)", () => {
+    expect(platformLocalProvider("win32")).toBeNull();
+  });
+});
+
+describe("readAvailableRamMib", () => {
+  test("non-Linux returns a positive number (totalmem fallback) or null", () => {
+    const ram = readAvailableRamMib("darwin");
+    // On any real CI/dev box totalmem is well-defined + positive.
+    expect(ram === null || (typeof ram === "number" && ram > 0)).toBe(true);
+  });
+
+  test("Linux path reads /proc/meminfo (or null when unreadable)", () => {
+    const ram = readAvailableRamMib("linux");
+    // On macOS CI there's no /proc/meminfo → null; on Linux CI a positive MiB.
+    expect(ram === null || (typeof ram === "number" && ram > 0)).toBe(true);
+  });
+});
+
+describe("decideLocalProvider — the RAM/platform gate", () => {
+  test("Linux with ample RAM → ok, onnx-asr", () => {
+    const d = decideLocalProvider("linux", 4096);
+    expect(d.ok).toBe(true);
+    expect(d.provider).toBe("onnx-asr");
+  });
+
+  test("macOS with ample RAM → ok, parakeet-mlx", () => {
+    const d = decideLocalProvider("darwin", 16384);
+    expect(d.ok).toBe(true);
+    expect(d.provider).toBe("parakeet-mlx");
+  });
+
+  test("below the RAM floor → refused, steers to groq, carries a reason", () => {
+    const d = decideLocalProvider("linux", MIN_RAM_MIB - 1);
+    expect(d.ok).toBe(false);
+    expect(d.steerTo).toBe("groq");
+    expect(d.reason).toContain(String(MIN_RAM_MIB));
+  });
+
+  test("exactly at the floor is OK (>= floor)", () => {
+    expect(decideLocalProvider("linux", MIN_RAM_MIB).ok).toBe(true);
+  });
+
+  test("unknown RAM (null) does not refuse on a supported platform", () => {
+    expect(decideLocalProvider("linux", null).ok).toBe(true);
+  });
+
+  test("unsupported platform → refused regardless of RAM, steers to groq", () => {
+    const d = decideLocalProvider("win32", 99999);
+    expect(d.ok).toBe(false);
+    expect(d.steerTo).toBe("groq");
+  });
+});
+
+describe("clearScribeProvider", () => {
+  test("removes transcribe.provider, preserving other keys", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({
+          transcribe: { provider: "onnx-asr", language: "en" },
+          auth: { required_token: "keep" },
+        }),
+      );
+      clearScribeProvider(h.dir);
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed.transcribe).toEqual({ language: "en" });
+      expect(parsed.auth).toEqual({ required_token: "keep" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("drops the transcribe block entirely when provider was its only key", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({ transcribe: { provider: "onnx-asr" }, auth: { required_token: "x" } }),
+      );
+      clearScribeProvider(h.dir);
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed.transcribe).toBeUndefined();
+      expect(parsed.auth).toEqual({ required_token: "x" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no-op when the file is absent", () => {
+    const h = makeHarness();
+    try {
+      // No file written.
+      expect(() => clearScribeProvider(h.dir)).not.toThrow();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 describe("readScribeProviderState", () => {
   test("missing file: configExists false, no provider", () => {
     const h = makeHarness();

package/src/__tests__/serve-boot.test.ts

@@ -125,6 +125,51 @@ describe("bootSupervisedModules", () => {
     expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGIN).toBe("https://hub.example");
   });
 
+  test("forwards PARACHUTE_HUB_ORIGINS (the multi-origin iss-set) alongside the single origin", async () => {
+    // Multi-origin iss-set (onboarding-streamline 2026-06-25): a resource
+    // server on scope-guard ≥0.5.0 widens its accepted-`iss` check to this set
+    // so a token minted under one URL of a multi-URL box validates via another.
+    // The set always carries the issuer + loopback aliases (the deterministic
+    // members); expose-state / platform members vary by box.
+    writeManifest({ services: [VAULT_ENTRY] }, h.manifestPath);
+    const recorder = makeRecorder();
+    const sup = new Supervisor({ spawnFn: recorder.spawn });
+
+    await bootSupervisedModules(sup, {
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      hubOrigin: "https://hub.example",
+    });
+
+    const origins = recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGINS;
+    expect(origins).toBeDefined();
+    const set = (origins ?? "").split(",");
+    expect(set).toContain("https://hub.example");
+    // SECURITY: the set is hub-controlled (issuer + loopback + expose +
+    // platform) — never a request Host. Loopback aliases are always present.
+    expect(set.some((o) => o.startsWith("http://127.0.0.1:"))).toBe(true);
+    expect(set.some((o) => o.startsWith("http://localhost:"))).toBe(true);
+    // And the single canonical origin is still written for back-compat.
+    expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGIN).toBe("https://hub.example");
+  });
+
+  test("no PARACHUTE_HUB_ORIGINS when hubOrigin is unset (no widening, single-origin only)", async () => {
+    // Back-compat: a boot with no hubOrigin neither sets PARACHUTE_HUB_ORIGIN
+    // nor the set — the child keeps its own loopback default + scope-guard's
+    // single-origin behavior.
+    writeManifest({ services: [VAULT_ENTRY] }, h.manifestPath);
+    const recorder = makeRecorder();
+    const sup = new Supervisor({ spawnFn: recorder.spawn });
+
+    await bootSupervisedModules(sup, {
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+    });
+
+    expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGIN).toBeUndefined();
+    expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGINS).toBeUndefined();
+  });
+
   test("sets PORT in child env from services.json entry (hub#357)", async () => {
     // Container deploys (Render etc.) set PORT in hub's process.env via
     // Dockerfile / platform injection. The supervisor's defaultSpawnFn

package/src/__tests__/serve.test.ts

@@ -21,7 +21,9 @@ describe("hubServeOptions — the production listener wires the WS bridge", () =
   // upgrades (the channel in-page terminal) 500'd through the hub
   // ("set the websocket object in Bun.serve({})"). The listener MUST declare a
   // websocket handler or `server.upgrade()` throws.
-  const fakeFetch = (() => new Response("ok")) as unknown as Parameters<typeof hubServeOptions>[0]["fetch"];
+  const fakeFetch = (() => new Response("ok")) as unknown as Parameters<
+    typeof hubServeOptions
+  >[0]["fetch"];
 
   test("declares a websocket handler set (open/message/close)", () => {
     const o = hubServeOptions({ port: 0, hostname: "127.0.0.1", fetch: fakeFetch });
@@ -404,6 +406,70 @@ describe("resolveStartupIssuer — precedence chain (hub#365)", () => {
   test("FLY_APP_NAME empty string → no fallback", () => {
     expect(resolveStartupIssuer({}, { FLY_APP_NAME: "" }, noExpose)).toBeUndefined();
   });
+
+  // onboarding-streamline 2026-06-25 — the Caddy-direct zero-SSH boot-issuer
+  // fix. The operator-set `hub_settings.hub_origin` (tier-1 in resolveIssuer)
+  // MUST also drive the boot-time issuer, else a box whose ONLY canonical-
+  // origin source is the DB row boots without an issuer and injects only
+  // loopback into supervised children's PARACHUTE_HUB_ORIGINS.
+  describe("dbHubOrigin tier (DB hub_settings.hub_origin)", () => {
+    test("dbHubOrigin wins over env/platform/expose (mirrors resolveIssuer tier-1)", () => {
+      const got = resolveStartupIssuer(
+        { dbHubOrigin: "https://box.sslip.io" },
+        {
+          PARACHUTE_HUB_ORIGIN: "https://env.example",
+          RENDER_EXTERNAL_URL: "https://render.example.onrender.com",
+        },
+        () => "https://exposed.example",
+      );
+      expect(got).toBe("https://box.sslip.io");
+    });
+
+    test("dbHubOrigin even wins over explicit opts.issuer (DB is the operator's deliberate canonical)", () => {
+      const got = resolveStartupIssuer(
+        { issuer: "https://flag.example", dbHubOrigin: "https://box.sslip.io" },
+        {},
+        noExpose,
+      );
+      expect(got).toBe("https://box.sslip.io");
+    });
+
+    test("dbHubOrigin trailing slash is stripped", () => {
+      expect(resolveStartupIssuer({ dbHubOrigin: "https://box.sslip.io/" }, {}, noExpose)).toBe(
+        "https://box.sslip.io",
+      );
+    });
+
+    test("a loopback dbHubOrigin is rejected (sanitized) → falls through to next tier", () => {
+      // A stray loopback value in the DB must NOT pin the issuer to a non-
+      // public origin; fall through to env so the box keeps a usable issuer.
+      const got = resolveStartupIssuer(
+        { dbHubOrigin: "http://127.0.0.1:1939" },
+        { PARACHUTE_HUB_ORIGIN: "https://env.example" },
+        noExpose,
+      );
+      expect(got).toBe("https://env.example");
+    });
+
+    test("a non-http(s) dbHubOrigin is rejected → falls through", () => {
+      const got = resolveStartupIssuer(
+        { dbHubOrigin: "ftp://box.example" },
+        {},
+        () => "https://exposed.example",
+      );
+      expect(got).toBe("https://exposed.example");
+    });
+
+    test("undefined dbHubOrigin is a no-op (unchanged precedence)", () => {
+      expect(
+        resolveStartupIssuer(
+          { dbHubOrigin: undefined },
+          { PARACHUTE_HUB_ORIGIN: "https://e.x" },
+          noExpose,
+        ),
+      ).toBe("https://e.x");
+    });
+  });
 });
 
 describe("resolveStartupIssuer — expose-state fallback (#531)", () => {

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-wizard.test.ts

@@ -1825,6 +1825,24 @@ describe("handleSetupVaultPost", () => {
     expect(cfg?.cleanup).toEqual({ provider: "anthropic", default: true });
     expect(cfg?.cleanupProviders).toEqual({ anthropic: { apiKey: "sk-ant-cleanup-key" } });
   });
+
+  test("scribe transcribe=local resolves to the host platform's backend (the Linux trap fix)", async () => {
+    // The bug: `local` mapped UNCONDITIONALLY to parakeet-mlx (macOS-only),
+    // silently broken on every Linux box. After the fix it resolves to the
+    // platform backend. We assert against the actual host so it's correct on
+    // both Mac (parakeet-mlx) and Linux CI (onnx-asr). The RAM gate only kicks
+    // in below 2 GB — CI/dev boxes clear it, so the choice stays `local`.
+    const { platformLocalProvider } = await import("../scribe-config.ts");
+    const expected = platformLocalProvider(process.platform);
+    const { response } = await postVaultWithFields(h, { scribe_provider: "local" });
+    expect(response.status).toBe(303);
+    const cfg = readScribeConfig(h.dir);
+    if (expected !== null) {
+      // On a supported platform with enough RAM, `local` resolves to the
+      // platform backend — NOT a hardcoded parakeet-mlx on Linux.
+      expect(cfg?.transcribe).toEqual({ provider: expected });
+    }
+  });
 });
 
 // --- end-to-end through hubFetch -----------------------------------------

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/);