@openparachute/hub 0.7.5 → 0.7.6-rc.3

package/src/__tests__/hub-instance.test.ts

@@ -0,0 +1,297 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type HubInstanceRecord,
+  type LoopbackProbe,
+  type SelfProbeState,
+  armHubSelfProbe,
+  classifyLoopback,
+  clearHubInstanceFile,
+  generateInstanceNonce,
+  hijackAlertMessage,
+  hubInstancePath,
+  probeLoopbackInstance,
+  readHubInstanceFile,
+  writeHubInstanceFile,
+} from "../hub-instance.ts";
+
+/**
+ * hub#737 loopback-hijack detection. The nonce file is the linchpin — an
+ * external process learns THIS hub's true identity from disk, then compares it
+ * to what a (possibly hijacked) loopback /health returns. Every side effect
+ * (fs, network) is exercised against a tmp dir / injected fetch.
+ */
+
+function makeDir(): { configDir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "parachute-instance-test-"));
+  return { configDir: dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+function record(over: Partial<HubInstanceRecord> = {}): HubInstanceRecord {
+  return {
+    instance: "nonce-1",
+    pid: 4242,
+    port: 1939,
+    startedAt: "2026-07-02T00:00:00.000Z",
+    ...over,
+  };
+}
+
+describe("nonce + instance file", () => {
+  test("generateInstanceNonce yields distinct UUID-shaped values", () => {
+    const a = generateInstanceNonce();
+    const b = generateInstanceNonce();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  test("write → read round-trips the record (incl. selfProbe)", () => {
+    const { configDir, cleanup } = makeDir();
+    try {
+      const sp: SelfProbeState = {
+        status: "ok",
+        checkedAt: "2026-07-02T00:01:00.000Z",
+      };
+      expect(writeHubInstanceFile(record({ selfProbe: sp }), { configDir })).toBe(true);
+      const back = readHubInstanceFile(configDir);
+      expect(back?.instance).toBe("nonce-1");
+      expect(back?.port).toBe(1939);
+      expect(back?.pid).toBe(4242);
+      expect(back?.selfProbe?.status).toBe("ok");
+      // Written 0644 (world-readable diagnostic aid, not a secret).
+      const raw = readFileSync(hubInstancePath(configDir), "utf8");
+      expect(raw.endsWith("\n")).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("read returns null on absent / malformed / instance-less files", () => {
+    const { configDir, cleanup } = makeDir();
+    try {
+      expect(readHubInstanceFile(configDir)).toBeNull(); // absent
+      writeFileSync(hubInstancePath(configDir), "not json{");
+      expect(readHubInstanceFile(configDir)).toBeNull(); // malformed
+      writeFileSync(hubInstancePath(configDir), JSON.stringify({ port: 1939 }));
+      expect(readHubInstanceFile(configDir)).toBeNull(); // no instance field
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("clearHubInstanceFile removes the file (graceful-shutdown hygiene) + no-ops when absent", () => {
+    const { configDir, cleanup } = makeDir();
+    try {
+      writeHubInstanceFile(record(), { configDir });
+      expect(readHubInstanceFile(configDir)).not.toBeNull();
+      clearHubInstanceFile(configDir);
+      expect(readHubInstanceFile(configDir)).toBeNull();
+      // Idempotent — clearing an already-absent file must not throw.
+      expect(() => clearHubInstanceFile(configDir)).not.toThrow();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("write failure is swallowed (returns false, logs) — never throws", () => {
+    const logs: string[] = [];
+    // An un-writable path (a file where a dir must be) forces the mkdir/write to
+    // fail; the helper must degrade, not throw.
+    const { configDir, cleanup } = makeDir();
+    try {
+      const filePath = join(configDir, "blocker");
+      writeFileSync(filePath, "x");
+      const ok = writeHubInstanceFile(record(), {
+        configDir: join(filePath, "nested"),
+        log: (l) => logs.push(l),
+      });
+      expect(ok).toBe(false);
+      expect(logs.length).toBe(1);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("classifyLoopback", () => {
+  test("unreachable when the probe didn't answer", () => {
+    expect(classifyLoopback("n1", { reachable: false })).toBe("unreachable");
+  });
+  test("ok when the returned instance matches ours", () => {
+    expect(classifyLoopback("n1", { reachable: true, status: 200, instance: "n1" })).toBe("ok");
+  });
+  test("hijacked when a different instance answers", () => {
+    expect(classifyLoopback("n1", { reachable: true, status: 200, instance: "n2" })).toBe(
+      "hijacked",
+    );
+  });
+  test("hijacked when a reachable process carries NO instance (old/foreign hub)", () => {
+    expect(classifyLoopback("n1", { reachable: true, status: 200 })).toBe("hijacked");
+  });
+});
+
+describe("probeLoopbackInstance", () => {
+  test("extracts instance + isHub from a well-formed /health body", async () => {
+    const fetchFn = (async () =>
+      new Response(JSON.stringify({ service: "parachute-hub", instance: "xyz" }), {
+        status: 200,
+      })) as unknown as typeof fetch;
+    const out = await probeLoopbackInstance(1939, { fetchFn });
+    expect(out).toEqual({ reachable: true, status: 200, instance: "xyz", isHub: true });
+  });
+
+  test("reachable-but-junk body → reachable with no instance (foreign server shape)", async () => {
+    const fetchFn = (async () =>
+      new Response("<html>not a hub</html>", { status: 200 })) as unknown as typeof fetch;
+    const out = await probeLoopbackInstance(1939, { fetchFn });
+    expect(out.reachable).toBe(true);
+    expect(out.instance).toBeUndefined();
+    expect(out.isHub).toBeUndefined();
+  });
+
+  test("network error → not reachable, never throws", async () => {
+    const fetchFn = (async () => {
+      throw new Error("ECONNREFUSED");
+    }) as unknown as typeof fetch;
+    const out = await probeLoopbackInstance(1939, { fetchFn });
+    expect(out).toEqual({ reachable: false });
+  });
+});
+
+describe("armHubSelfProbe", () => {
+  /** A probe stub that returns a fixed LoopbackProbe. */
+  function fixedProbe(p: LoopbackProbe): (port: number) => Promise<LoopbackProbe> {
+    return async () => p;
+  }
+
+  test("ok verdict: writes state, stays quiet (no loud log)", async () => {
+    const logs: string[] = [];
+    const states: SelfProbeState[] = [];
+    const probe = armHubSelfProbe(
+      { port: 1939, nonce: "n1", record: record() },
+      {
+        probe: fixedProbe({ reachable: true, status: 200, instance: "n1" }),
+        writeState: (s) => states.push(s),
+        log: (l) => logs.push(l),
+        setIntervalFn: () => 0,
+      },
+    );
+    const verdict = await probe.probeOnce();
+    expect(verdict).toBe("ok");
+    expect(logs).toEqual([]);
+    expect(states.at(-1)?.status).toBe("ok");
+  });
+
+  test("hijacked verdict: LOUD alert on EVERY probe + observedInstance persisted", async () => {
+    const logs: string[] = [];
+    const states: SelfProbeState[] = [];
+    const probe = armHubSelfProbe(
+      { port: 1939, nonce: "n1", record: record() },
+      {
+        probe: fixedProbe({ reachable: true, status: 200, instance: "rogue-9" }),
+        writeState: (s) => states.push(s),
+        log: (l) => logs.push(l),
+        setIntervalFn: () => 0,
+      },
+    );
+    expect(await probe.probeOnce()).toBe("hijacked");
+    expect(await probe.probeOnce()).toBe("hijacked");
+    // Repeated verbatim — a hijack is a standing emergency, not a one-shot.
+    expect(logs.length).toBe(2);
+    expect(logs[0]).toContain("LOOPBACK HIJACK");
+    expect(logs[0]).toContain("lsof -nP -iTCP:1939");
+    expect(states.at(-1)?.observedInstance).toBe("rogue-9");
+    expect(states.at(-1)?.status).toBe("hijacked");
+  });
+
+  test("unreachable verdict: logs ONCE per state change, not per tick", async () => {
+    const logs: string[] = [];
+    const probe = armHubSelfProbe(
+      { port: 1939, nonce: "n1", record: record() },
+      {
+        probe: fixedProbe({ reachable: false }),
+        writeState: () => {},
+        log: (l) => logs.push(l),
+        setIntervalFn: () => 0,
+      },
+    );
+    await probe.probeOnce();
+    await probe.probeOnce();
+    expect(logs.length).toBe(1); // second consecutive unreachable is silent
+    expect(logs[0]).toContain("did not answer");
+  });
+
+  test("recovery: hijacked → ok logs a single 'cleared' line", async () => {
+    const logs: string[] = [];
+    let current: LoopbackProbe = { reachable: true, status: 200, instance: "rogue" };
+    const probe = armHubSelfProbe(
+      { port: 1939, nonce: "n1", record: record() },
+      {
+        probe: async () => current,
+        writeState: () => {},
+        log: (l) => logs.push(l),
+        setIntervalFn: () => 0,
+      },
+    );
+    expect(await probe.probeOnce()).toBe("hijacked");
+    current = { reachable: true, status: 200, instance: "n1" };
+    expect(await probe.probeOnce()).toBe("ok");
+    expect(logs.length).toBe(2);
+    expect(logs[1]).toContain("Hijack cleared");
+  });
+
+  test("stop() clears the interval handle", () => {
+    let cleared: unknown;
+    const probe = armHubSelfProbe(
+      { port: 1939, nonce: "n1", record: record() },
+      {
+        probe: fixedProbe({ reachable: true, instance: "n1" }),
+        writeState: () => {},
+        setIntervalFn: () => "the-handle",
+        clearIntervalFn: (h) => {
+          cleared = h;
+        },
+      },
+    );
+    probe.stop();
+    expect(cleared).toBe("the-handle");
+  });
+
+  test("default writeState patches selfProbe into the real instance file", async () => {
+    const { configDir, cleanup } = makeDir();
+    try {
+      const rec = record();
+      writeHubInstanceFile(rec, { configDir });
+      const probe = armHubSelfProbe(
+        { port: 1939, nonce: "n1", record: rec, configDir },
+        {
+          probe: fixedProbe({ reachable: true, status: 200, instance: "someone-else" }),
+          log: () => {},
+          setIntervalFn: () => 0,
+        },
+      );
+      await probe.probeOnce();
+      const back = readHubInstanceFile(configDir);
+      expect(back?.selfProbe?.status).toBe("hijacked");
+      expect(back?.instance).toBe("nonce-1"); // base record preserved
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("hijackAlertMessage", () => {
+  test("names the observed instance + the diagnosis commands + incident ref", () => {
+    const msg = hijackAlertMessage(1939, "rogue-42");
+    expect(msg).toContain("instance=rogue-42");
+    expect(msg).toContain("lsof -nP -iTCP:1939 -sTCP:LISTEN");
+    expect(msg).toContain("orb list");
+    expect(msg).toContain("hub#737");
+  });
+  test("degrades gracefully when the foreign process carries no nonce", () => {
+    const msg = hijackAlertMessage(1939);
+    expect(msg).toContain("no hub instance nonce");
+  });
+});

package/src/__tests__/hub-server.test.ts

@@ -15,6 +15,7 @@ import {
   layerOf,
   parseArgs,
   resolveClientIp,
+  stripHopByHopHeaders,
 } from "../hub-server.ts";
 import { setNotesRedirectDisabled } from "../hub-settings.ts";
 import { clearNotesRedirectLogState } from "../notes-redirect.ts";
@@ -139,6 +140,27 @@ describe("hubFetch routing", () => {
     }
   });
 
+  test("/health echoes the instance nonce when set, omits it when absent (hub#737)", async () => {
+    const h = makeHarness();
+    try {
+      // With a nonce threaded in, /health carries it as `instance`.
+      const withNonce = (await (
+        await hubFetch(h.dir, { instanceNonce: "nonce-abc-123" })(req("/health"))
+      ).json()) as { service: string; instance?: string };
+      expect(withNonce.service).toBe("parachute-hub");
+      expect(withNonce.instance).toBe("nonce-abc-123");
+
+      // Without one (DB-less / dev entrypoint), the field is omitted — additive,
+      // so no strict /health consumer breaks.
+      const withoutNonce = (await (await hubFetch(h.dir, {})(req("/health"))).json()) as {
+        instance?: string;
+      };
+      expect(withoutNonce.instance).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("/health surfaces db:error:path-gone when the proactive probe sees a wiped path (#610)", async () => {
     // The ghost-fd lie: SELECT 1 still succeeds against the unlinked inode, so
     // probeDbLiveness alone would report ok. probeDbPath stat()s the PATH and
@@ -5963,6 +5985,153 @@ describe("substrate trust headers — X-Parachute-Layer / X-Parachute-Client-IP
   });
 });
 
+describe("stripHopByHopHeaders (hub#738)", () => {
+  test("drops the standard hop-by-hop set", () => {
+    const h = new Headers({
+      connection: "keep-alive",
+      "keep-alive": "timeout=5",
+      "proxy-authorization": "Basic xxx",
+      te: "trailers",
+      "transfer-encoding": "chunked",
+      upgrade: "h2c",
+      authorization: "Bearer keep-me",
+      "content-type": "application/json",
+    });
+    stripHopByHopHeaders(h);
+    expect(h.has("connection")).toBe(false);
+    expect(h.has("keep-alive")).toBe(false);
+    expect(h.has("proxy-authorization")).toBe(false);
+    expect(h.has("te")).toBe(false);
+    expect(h.has("transfer-encoding")).toBe(false);
+    expect(h.has("upgrade")).toBe(false);
+    // End-to-end headers survive.
+    expect(h.get("authorization")).toBe("Bearer keep-me");
+    expect(h.get("content-type")).toBe("application/json");
+  });
+
+  test("drops headers NAMED in the Connection field-value (RFC 9110 §7.6.1)", () => {
+    const h = new Headers({
+      connection: "close, X-Custom-Hop",
+      "x-custom-hop": "should-go",
+      "x-real-header": "should-stay",
+    });
+    stripHopByHopHeaders(h);
+    expect(h.has("connection")).toBe(false);
+    expect(h.has("x-custom-hop")).toBe(false);
+    expect(h.get("x-real-header")).toBe("should-stay");
+  });
+});
+
+describe("proxy upstream keep-alive (hub#738)", () => {
+  const fakeServer = (address: string) => ({ requestIP: () => ({ address }) });
+
+  function writeUpstreamService(h: Harness, port: number): void {
+    writeManifest(
+      {
+        services: [
+          {
+            name: "keepalive-svc",
+            port,
+            paths: ["/keepalive-svc"],
+            health: "/keepalive-svc/health",
+            version: "0.1.0",
+          },
+        ],
+      },
+      h.manifestPath,
+    );
+  }
+
+  test("200 proxied requests reuse a handful of upstream sockets even when the client sends Connection: close", async () => {
+    // Regression for hub#738: the proxy forwarded the client's hop-by-hop
+    // `Connection: close` verbatim, so Bun opened a FRESH ephemeral socket per
+    // proxied request instead of reusing its per-origin pool → 16k+ TIME_WAIT
+    // → host-wide port exhaustion (the 2026-07-02 incident, amplifying an agent
+    // reconciler 401 loop). We count the distinct client (ephemeral) ports the
+    // upstream sees: a working pool reuses one (occasionally a couple); the bug
+    // produced ~N distinct ports.
+    const seenPorts = new Set<number>();
+    const upstream = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: (r, server) => {
+        const ip = server.requestIP(r);
+        if (ip) seenPorts.add(ip.port);
+        return new Response("unauthorized", { status: 401 }); // the incident's 401 loop
+      },
+    });
+    const h = makeHarness();
+    try {
+      writeUpstreamService(h, upstream.port as number);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const N = 200;
+      for (let i = 0; i < N; i++) {
+        const res = await fetcher(
+          req("/keepalive-svc/x", { headers: { connection: "close" } }),
+          fakeServer("127.0.0.1"),
+        );
+        await res.arrayBuffer(); // fully drain so the socket returns to the pool
+      }
+      expect(seenPorts.size).toBeLessThanOrEqual(8);
+    } finally {
+      upstream.stop(true);
+      h.cleanup();
+    }
+  });
+
+  test("a client hang-up mid-stream aborts the upstream fetch (socket released, not left streaming to nobody)", async () => {
+    // Without forwarding req.signal, an aborted client left the upstream
+    // streaming its whole body to a gone client and holding the socket. We
+    // forward the signal so the upstream is torn down (cancel() fires or the
+    // enqueue loop errors) instead of running to completion.
+    let tornDown = false;
+    const upstream = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () =>
+        new Response(
+          new ReadableStream({
+            async start(controller) {
+              try {
+                for (let i = 0; i < 40; i++) {
+                  controller.enqueue(new TextEncoder().encode(`chunk ${i}\n`));
+                  await Bun.sleep(10);
+                }
+                controller.close();
+              } catch {
+                tornDown = true; // enqueue threw after the peer dropped
+              }
+            },
+            cancel() {
+              tornDown = true; // Bun cancelled the source on disconnect
+            },
+          }),
+          { headers: { "content-type": "text/plain" } },
+        ),
+    });
+    const h = makeHarness();
+    try {
+      writeUpstreamService(h, upstream.port as number);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const ac = new AbortController();
+      const res = await fetcher(
+        req("/keepalive-svc/stream", { signal: ac.signal }),
+        fakeServer("127.0.0.1"),
+      );
+      const reader = res.body!.getReader();
+      await reader.read(); // consume one chunk, then hang up
+      ac.abort();
+      // Full stream is 40 * 10ms = 400ms; wait past it. With the signal
+      // forwarded the upstream tears down early; without, it runs to close.
+      await Bun.sleep(700);
+      expect(tornDown).toBe(true);
+    } finally {
+      upstream.stop(true);
+      h.cleanup();
+    }
+  });
+});
+
 describe("resolveClientIp (H2)", () => {
   test("CF-Connecting-IP wins over X-Forwarded-For and peer", () => {
     const r = req("/", {

package/src/__tests__/install.test.ts

@@ -34,6 +34,34 @@ describe("install", () => {
     }
   });
 
+  test("refuses `install runner` with a retirement message — never bun-adds npm's unrelated `runner` package (2026-07-01)", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install("runner", {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(1);
+      // The load-bearing bit: no `bun add -g runner` ever fires. Without the
+      // retired-short guard the bare short falls through the npm arm and
+      // installs an unrelated package that happens to be named `runner`.
+      expect(calls).toEqual([]);
+      expect(logs.join("\n")).toMatch(/retired from the hub's module registry/);
+      expect(logs.join("\n")).toMatch(/@openparachute\/runner/);
+    } finally {
+      cleanup();
+    }
+  });
+
   test("runs bun add -g then init; seeds manifest when service didn't write one", async () => {
     const { path, cleanup } = makeTempPath();
     try {

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

@@ -333,6 +333,66 @@ describe("bootSupervisedModules", () => {
     expect(recorder.calls).toEqual([]);
     expect(logs.some((l) => l.includes("no startCmd resolvable"))).toBe(true);
   });
+
+  test("a LEGACY parachute-runner row boots gracefully post-registry-removal (2026-07-01)", async () => {
+    // runner left the bootstrap registries (decision: Aaron 2026-07-01 — the
+    // module set of record is vault / hub / agent / scribe / surface). An
+    // existing operator's services.json still carries the row, and it must
+    // take the unknown/third-party path, never crash the boot sweep:
+    //   - with installDir + module.json → spawned via the module's own
+    //     declared startCmd (third-party convention);
+    //   - without installDir → logged + skipped (`no-spec`).
+    const installDir = join(h.dir, "runner-install");
+    mkdirSync(join(installDir, ".parachute"), { recursive: true });
+    writeFileSync(
+      join(installDir, ".parachute", "module.json"),
+      JSON.stringify({
+        name: "runner",
+        manifestName: "parachute-runner",
+        port: 1945,
+        paths: ["/runner", "/.parachute"],
+        health: "/runner/healthz",
+        startCmd: ["parachute-runner", "serve"],
+      }),
+    );
+    const withInstallDir: ServiceEntry = {
+      name: "parachute-runner",
+      port: 1945,
+      paths: ["/runner", "/.parachute"],
+      health: "/runner/healthz",
+      version: "0.2.0",
+      installDir,
+    };
+    writeManifest({ services: [withInstallDir] }, h.manifestPath);
+    const recorder = makeRecorder();
+    const sup = new Supervisor({ spawnFn: recorder.spawn });
+    const results = await bootSupervisedModules(sup, {
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.status).toBe("started");
+    // The short is the row name now (no registry mapping survives), and the
+    // spawn cmd comes from the module's OWN module.json.
+    expect(results[0]?.short).toBe("parachute-runner");
+    expect(recorder.calls[0]?.cmd).toEqual(["parachute-runner", "serve"]);
+
+    // Same row WITHOUT installDir: skipped with reason, no crash.
+    const { installDir: _drop, ...bare } = withInstallDir;
+    writeManifest({ services: [bare] }, h.manifestPath);
+    const recorder2 = makeRecorder();
+    const sup2 = new Supervisor({ spawnFn: recorder2.spawn });
+    const logs: string[] = [];
+    const results2 = await bootSupervisedModules(sup2, {
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      log: (l) => logs.push(l),
+    });
+    expect(results2).toHaveLength(1);
+    expect(results2[0]?.status).toBe("skipped");
+    expect(results2[0]?.reason).toBe("no-spec");
+    expect(recorder2.calls).toEqual([]);
+  });
 });
 
 // agent (then channel)#41 — a transiently-wrong (drifted) services.json port for a

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

@@ -6,6 +6,7 @@ import {
   findServiceByShort,
   focusForShort,
   isKnownModuleShort,
+  shortNameForManifest,
 } from "../service-spec.ts";
 
 // 2026-06-09 modular-UI architecture (P2): discovery is driven by the union of
@@ -26,7 +27,7 @@ describe("discoverableShorts", () => {
 
   test("includes agent (the module the whitelist used to hide) + the core set", () => {
     const shorts = discoverableShorts();
-    for (const s of ["vault", "scribe", "surface", "runner", "agent", "notes"]) {
+    for (const s of ["vault", "scribe", "surface", "agent", "notes"]) {
       expect(shorts).toContain(s);
     }
   });
@@ -55,10 +56,8 @@ describe("focusForShort", () => {
     expect(focusForShort("surface")).toBe("core");
     // agent stays a legit experimental preview — still offered on a fresh install.
     expect(focusForShort("agent")).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");
+    // notes (notes-daemon, deprecated 2026-05-22) is `deprecated`: still
+    // resolvable + shown-if-installed, but NOT offered on a fresh setup.
     expect(focusForShort("notes")).toBe("deprecated");
   });
 
@@ -74,18 +73,42 @@ describe("focusForShort", () => {
   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.
+    // notes 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);
+  });
+});
+
+// Runner registry removal (decision: Aaron 2026-07-01 — the module set of
+// record is vault / hub / agent / scribe / surface). Runner is fully out of
+// the bootstrap registries: not discoverable, not a known short, and its
+// manifest name no longer resolves. It is NOT in RETIRED_MODULES (that would
+// GC a legacy operator's services.json row on load) — an existing install is
+// handled as an unknown/third-party row instead (see serve-boot tests).
+describe("runner registry removal (2026-07-01)", () => {
+  test("runner is no longer a known/discoverable short", () => {
+    expect(isKnownModuleShort("runner")).toBe(false);
+    expect(discoverableShorts()).not.toContain("runner");
+    expect("runner" in KNOWN_MODULES).toBe(false);
+    expect("runner" in FIRST_PARTY_FALLBACKS).toBe(false);
+  });
+
+  test("parachute-runner no longer resolves to a short — legacy rows are third-party-shaped", () => {
+    // Consumers (status / serve-boot / api-modules) fall back to the row's
+    // own name when this returns undefined, which is what keeps an existing
+    // runner install rendering + booting instead of crashing.
+    expect(shortNameForManifest("parachute-runner")).toBeUndefined();
+  });
+
+  test("an unlisted runner short defaults to the experimental tier, like any third-party", () => {
+    expect(focusForShort("runner")).toBe("experimental");
   });
 });
 
 describe("isKnownModuleShort", () => {
   test("true for every known module (the install/config gate)", () => {
-    for (const s of ["vault", "scribe", "surface", "runner", "agent", "notes"]) {
+    for (const s of ["vault", "scribe", "surface", "agent", "notes"]) {
       expect(isKnownModuleShort(s)).toBe(true);
     }
   });