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

package/package.json

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