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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3-rc.6",
+  "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__/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/);

package/src/api-modules.ts

@@ -15,11 +15,21 @@
  *     / `crashed` / `starting` / `restarting`) + pid. Absent when the
  *     hub is in CLI mode (no supervisor injected through HubFetchDeps).
  *
- * `focus` ("core" | "experimental") comes from each module's `module.json`
- * when declared, else `focusForShort`'s default map. The SPA groups core first
- * + de-emphasizes experimental — it NEVER hides a module. This is what makes a
- * running, self-registered module (channel) visible + installable; the old
- * `CURATED_MODULES = ["vault","scribe"]` whitelist made it invisible.
+ * `focus` ("core" | "experimental" | "deprecated") comes from each module's
+ * `module.json` when declared, else `focusForShort`'s default map. The SPA
+ * groups core first, de-emphasizes experimental, and de-emphasizes
+ * `deprecated` (notes-daemon / runner) further — it NEVER hides an installed
+ * module (so an existing operator can still manage / uninstall a deprecated
+ * one). This is what makes a running, self-registered module (channel) visible
+ * + installable; the old `CURATED_MODULES = ["vault","scribe"]` whitelist made
+ * it invisible.
+ *
+ * `available_to_install` is the fresh-install OFFER (2026-06-25): a module the
+ * hub will push as a new install. It's `available && focus !== "deprecated"`
+ * — so a `deprecated` module that is ALREADY installed still surfaces (via the
+ * `modules` union + `installed: true`) and is manageable, but a deprecated
+ * module is never offered as a fresh install. `agent` (`experimental`) stays
+ * offered.
  *
  * Bearer-gated on `parachute:host:auth` to match the rest of `/api/auth/*`
  * and `/api/grants` — the admin SPA mints this scope via
@@ -199,14 +209,33 @@ interface ModuleWireShape {
   display_name: string;
   tagline: string;
   /**
-   * Discovery tier (2026-06-09 modular-UI architecture). `core` modules render
-   * in the headline group; `experimental` modules render in a de-emphasized
-   * "Experimental" group below — never hidden. Resolved from the module's
-   * `module.json` `focus` when declared, else `focusForShort`'s default map
-   * (vault/scribe/hub/surface → core, channel/runner/others → experimental).
+   * Discovery tier (2026-06-09 modular-UI architecture; `deprecated` added
+   * 2026-06-25). `core` modules render in the headline group; `experimental`
+   * modules render in a de-emphasized "Experimental" group; `deprecated`
+   * modules (notes-daemon / runner) render in a further-de-emphasized
+   * "Deprecated" group — never hidden when installed. Resolved from the
+   * module's `module.json` `focus` when declared, else `focusForShort`'s
+   * default map (vault/scribe/hub/surface → core, notes/runner → deprecated,
+   * others → experimental).
    */
   focus: ModuleFocus;
+  /**
+   * True iff the hub knows how to install this module (`package`/`manifest`
+   * resolvable). Historically "in the curated install catalog". Still set for
+   * every known module; a purely third-party services.json row is false.
+   * NOTE: this is NOT the fresh-install OFFER — a `deprecated` module is still
+   * `available: true` (it's installable for back-compat / re-install) but is
+   * excluded from `available_to_install`.
+   */
   available: boolean;
+  /**
+   * The fresh-install OFFER (2026-06-25): whether the hub presents this module
+   * in the "available to install fresh" set. `available && focus !==
+   * "deprecated"`. The SPA's "Install a module" catalog filters on this so
+   * notes-daemon / runner aren't pushed on a fresh box; an already-installed
+   * deprecated module still surfaces (in the Installed section) for management.
+   */
+  available_to_install: boolean;
   installed: boolean;
   installed_version: string | null;
   latest_version: string | null;
@@ -562,8 +591,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   // module's manifest-declared `focus` (when installed + declared) wins; else
   // the `focusForShort` default map. Sort: `core` group first (with the
   // CURATED_MODULES recommended-install order floated to the top of that
-  // group), then `experimental` — the SPA renders the two groups; `focus`
-  // never hides a module.
+  // group), then `experimental`, then `deprecated` (notes / runner) last — the
+  // SPA renders the groups; `focus` never hides an installed module.
   const recommendedOrder = new Map<string, number>(
     (CURATED_MODULES as readonly string[]).map((s, i) => [s, i]),
   );
@@ -585,6 +614,11 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       // known modules; a purely third-party services.json row (no install
       // package) is not hub-installable → false.
       available: m !== undefined,
+      // Fresh-install OFFER (2026-06-25): installable AND not deprecated. A
+      // deprecated short (notes / runner) stays `available` (re-installable
+      // for back-compat) but is dropped from the offer set so the SPA's
+      // "Install a module" catalog doesn't push it on a fresh box.
+      available_to_install: m !== undefined && focus !== "deprecated",
       installed: installed !== undefined,
       installed_version: installed?.version ?? null,
       latest_version: latestByShort.get(short) ?? null,
@@ -598,7 +632,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
     };
     return row;
   });
-  const focusRank = (f: ModuleFocus): number => (f === "core" ? 0 : 1);
+  const focusRank = (f: ModuleFocus): number => (f === "core" ? 0 : f === "experimental" ? 1 : 2);
   rows.sort((a, b) => {
     if (a.focus !== b.focus) return focusRank(a.focus) - focusRank(b.focus);
     const ai = recommendedOrder.get(a.short) ?? Number.POSITIVE_INFINITY;

package/src/commands/setup.ts

@@ -11,6 +11,7 @@ import {
   KNOWN_MODULES,
   type ServiceSpec,
   composeServiceSpec,
+  focusForShort,
   knownServices,
 } from "../service-spec.ts";
 import type { ServiceEntry } from "../services-manifest.ts";
@@ -108,10 +109,14 @@ function defaultAvailability(): InteractiveAvailability {
 }
 
 /**
- * Survey the eligible services. We include the four first-party shortnames
- * (vault / notes / scribe / agent + runner) but flag agent as exploratory
- * in the blurb so operators don't grab it by reflex. `installed` is true when
- * the service has a row in services.json.
+ * Survey ALL known first-party shortnames (vault / notes / scribe / agent /
+ * runner / surface) 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 / runner); agent (`experimental`) is flagged exploratory in its blurb
+ * but stays offered. Surveying everything keeps `installed` detection complete
+ * (the "already installed" banner still lists a deprecated module an operator
+ * has on disk).
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
  * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
@@ -149,10 +154,30 @@ function surveyServices(manifestPath: string): ServiceChoice[] {
   });
 }
 
+/**
+ * A surveyed service is OFFERED on a fresh setup iff it is not already
+ * installed AND its discovery tier is not `deprecated` (2026-06-25). The
+ * deprecated tier (notes-daemon, runner) stays resolvable + manageable for an
+ * existing install — it just isn't pushed on a fresh box. `agent`
+ * (`experimental`) is still offered. Exported so the setup tests can pin the
+ * exclusion directly.
+ */
+export function isOfferable(choice: { short: string; installed: boolean }): boolean {
+  if (choice.installed) return false;
+  // No `declared` arg: the survey fires PRE-install, before any module.json is
+  // on disk to read a self-declared `focus` from — so the static default map is
+  // the only signal available + the right one here.
+  return focusForShort(choice.short) !== "deprecated";
+}
+
 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)",
-  notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `app`)",
+  // notes / runner are `deprecated` (not offered on a fresh setup) — these
+  // blurbs only render if a legacy install surfaces them in the survey.
+  notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `surface`)",
   scribe: "audio transcription for dictation + recordings",
   runner: "vault-as-job-substrate — scheduled claude -p against vault job notes",
   agent:
@@ -306,7 +331,7 @@ export async function setup(opts: SetupOpts = {}): Promise<number> {
 
   const survey = surveyServices(manifestPath);
   const installed = survey.filter((s) => s.installed);
-  const offered = survey.filter((s) => !s.installed);
+  const offered = survey.filter(isOfferable);
 
   if (installed.length > 0) {
     log("Already installed:");

package/src/module-manifest.ts

@@ -66,16 +66,26 @@ export interface ConfigSchema {
 }
 
 /**
- * Discovery tier (2026-06-09 modular-UI architecture). `core` modules are the
- * product surface (vault / scribe / hub / surface); `experimental` modules
- * (channel / runner / others) render in a de-emphasized group on the Modules
- * screen. **Show all; never hide** — `focus` only sorts + labels.
+ * Discovery tier (2026-06-09 modular-UI architecture). Three tiers today:
+ *   - `core` — the product surface (vault / scribe / hub / surface).
+ *   - `experimental` — legit previews (agent) that render in a de-emphasized
+ *     group but ARE offered on a fresh install.
+ *   - `deprecated` — modules retained for back-compat (notes-daemon, runner)
+ *     that stay resolvable + shown-if-installed (so an existing operator can
+ *     still manage / uninstall them) but are NOT offered on a fresh setup
+ *     (2026-06-25). Distinct from a fully retired module (`RETIRED_MODULES`),
+ *     whose services.json row is GC'd on load.
+ *
+ * **Show all installed; never hide** — `focus` only sorts + labels for an
+ * installed/known module. The one behavioral lever it pulls is the fresh-install
+ * OFFER: `deprecated` shorts are dropped from the setup wizard + the admin SPA's
+ * "available to install" set.
  *
  * Absent in a `module.json` ⇒ the hub falls back to its default map (see
  * `service-spec.focusForShort`), which defaults unlisted modules to
  * `experimental`.
  */
-export type ModuleFocus = "core" | "experimental";
+export type ModuleFocus = "core" | "experimental" | "deprecated";
 
 /**
  * An event a module EMITS — the left-hand side of a Connection (2026-06-09
@@ -324,8 +334,10 @@ export interface ModuleManifest {
    * Discovery tier (2026-06-09 modular-UI architecture). When a module
    * declares `focus`, the hub's Modules screen uses it verbatim; otherwise it
    * falls back to `service-spec.focusForShort` (vault/scribe/hub/surface →
-   * `core`, everything else → `experimental`). **Show all; never hide** —
-   * `focus` only groups + de-emphasizes. Additive + back-compatible.
+   * `core`, notes/runner → `deprecated`, everything else → `experimental`).
+   * **Show all installed; never hide** — `focus` groups + de-emphasizes; the
+   * one behavioral lever is the fresh-install OFFER, which excludes
+   * `deprecated`. Additive + back-compatible.
    */
   readonly focus?: ModuleFocus;
   /**
@@ -711,12 +723,14 @@ function asCredentials(v: unknown, where: string): readonly ModuleCredential[] |
   });
 }
 
-const MODULE_FOCUS_VALUES = new Set<ModuleFocus>(["core", "experimental"]);
+const MODULE_FOCUS_VALUES = new Set<ModuleFocus>(["core", "experimental", "deprecated"]);
 
 function asFocus(v: unknown, where: string): ModuleFocus | undefined {
   if (v === undefined) return undefined;
   if (typeof v !== "string" || !MODULE_FOCUS_VALUES.has(v as ModuleFocus)) {
-    throw new ModuleManifestError(`${where}: "focus" must be "core" | "experimental" if present`);
+    throw new ModuleManifestError(
+      `${where}: "focus" must be "core" | "experimental" | "deprecated" if present`,
+    );
   }
   return v as ModuleFocus;
 }