@openparachute/hub 0.7.5 → 0.7.6-rc.3

package/src/hub-instance.ts

@@ -0,0 +1,365 @@
+/**
+ * Hub instance identity + loopback-hijack detection (hub#737).
+ *
+ * ## The incident this defends against (2026-07-02 P0)
+ *
+ * The hub binds `*:1939` (INADDR_ANY / `0.0.0.0`). An OrbStack Linux machine
+ * auto-forwarded ITS port 1939 onto the host as a SPECIFIC bind on
+ * `127.0.0.1:1939` — and a specific loopback bind WINS over a wildcard bind for
+ * all loopback traffic. Every module's JWKS/API call to `127.0.0.1:1939`
+ * silently reached the WRONG hub (a fresh container DB → empty JWKS, no admin),
+ * so every hub-JWT validation failed `no applicable key found in the JWKS` and
+ * the ecosystem 401-looped for hours. `lsof -nP -i :1939` showed two LISTENs;
+ * the tell was `/health` reporting the container's version, not the checkout's.
+ *
+ * ## The primitive: a per-process instance nonce
+ *
+ * Each `parachute serve` process generates a random nonce at boot, (a) exposes
+ * it as `instance` in `/health`, and (b) writes it to
+ * `~/.parachute/hub-instance.json` (0644). That file is the linchpin: an
+ * EXTERNAL process (`parachute status`, `parachute doctor`) can learn THIS
+ * hub's true identity from disk WITHOUT traversing the (possibly hijacked)
+ * loopback — then compare it to what a loopback `GET /health` actually returns.
+ * A mismatch means another process owns `127.0.0.1:<port>`.
+ *
+ * The in-process self-probe (armed by `serve`) compares its own in-memory nonce
+ * to the loopback `/health` it fetches, logs loudly on mismatch, and records the
+ * verdict back into the same file's `selfProbe` field so external tools surface
+ * the serve process's own authoritative reading without re-probing.
+ *
+ * Every side effect (fs, network probe) is behind an injectable seam so the
+ * whole module runs deterministically in tests with no real network / disk.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFIG_DIR } from "./config.ts";
+
+/** The public incident reference operators grep for. */
+export const HIJACK_INCIDENT_REF = "hub#737 / team-vault Log/2026-07-02-port-exhaustion-incident";
+
+/** Self-probe verdicts. `ok` = loopback reaches us; `hijacked` = someone else owns loopback. */
+export type SelfProbeStatus = "ok" | "hijacked" | "unreachable";
+
+/**
+ * The serve process's own most-recent loopback self-probe reading, persisted
+ * into the instance file so external readers (`status`) see the authoritative
+ * verdict without re-probing the (possibly hijacked) loopback themselves.
+ */
+export interface SelfProbeState {
+  status: SelfProbeStatus;
+  /** ISO timestamp of the reading. */
+  checkedAt: string;
+  /** The `instance` the loopback `/health` actually returned (present on a `hijacked` reading). */
+  observedInstance?: string;
+  /** One-line human detail (loud message on a hijack; the probe error class on unreachable). */
+  detail?: string;
+}
+
+/** The `~/.parachute/hub-instance.json` record. */
+export interface HubInstanceRecord {
+  /** Per-process random nonce (`crypto.randomUUID`) minted at serve boot. */
+  instance: string;
+  /** The serve process PID (informational — helps an operator map the file to a process). */
+  pid: number;
+  /** The port this serve bound. */
+  port: number;
+  /** ISO timestamp of serve boot. */
+  startedAt: string;
+  /** Last self-probe reading, patched in by the running serve process. */
+  selfProbe?: SelfProbeState;
+}
+
+/** Mint a fresh per-process nonce. */
+export function generateInstanceNonce(): string {
+  return randomUUID();
+}
+
+/** Path to the instance file under a config dir (default `~/.parachute`). */
+export function hubInstancePath(configDir: string = CONFIG_DIR): string {
+  return join(configDir, "hub-instance.json");
+}
+
+/**
+ * Atomically write the instance record (tmp + rename, 0644). Best-effort: a
+ * write failure must NEVER take the hub down — the file is a diagnostic aid, not
+ * a load-bearing runtime dependency. Returns true on success.
+ */
+export function writeHubInstanceFile(
+  record: HubInstanceRecord,
+  opts: { configDir?: string; log?: (line: string) => void } = {},
+): boolean {
+  const path = hubInstancePath(opts.configDir);
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    const dir = dirname(path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o644 });
+    renameSync(tmp, path);
+    return true;
+  } catch (err) {
+    // Don't leave a half-written tmp behind if the rename (or write) failed.
+    try {
+      if (existsSync(tmp)) rmSync(tmp, { force: true });
+    } catch {
+      // Best-effort cleanup — nothing more we can do.
+    }
+    opts.log?.(
+      `parachute serve: could not write ${path} (${err instanceof Error ? err.message : String(err)}); loopback-hijack detection for external tools is degraded, hub start continues.`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Remove the instance file (best-effort). Called on graceful shutdown so a
+ * cleanly-stopped hub doesn't leave a stale identity/self-probe verdict on disk
+ * for `status` / `doctor` to read as a phantom. A hard kill (SIGKILL) can't run
+ * this — the readers additionally gate on live hub liveness, so a leftover file
+ * from a hard kill never surfaces as a false hijack.
+ */
+export function clearHubInstanceFile(configDir: string = CONFIG_DIR): void {
+  try {
+    rmSync(hubInstancePath(configDir), { force: true });
+  } catch {
+    // Best-effort — a missing / unremovable file is not worth surfacing.
+  }
+}
+
+/**
+ * Read + validate the instance file. Returns null on absence / unreadable /
+ * malformed — a missing file is the benign "no nonce-aware serve wrote one yet"
+ * state, never an error.
+ */
+export function readHubInstanceFile(configDir: string = CONFIG_DIR): HubInstanceRecord | null {
+  const path = hubInstancePath(configDir);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as Record<string, unknown>;
+  if (typeof r.instance !== "string" || r.instance.length === 0) return null;
+  if (typeof r.port !== "number") return null;
+  const rec: HubInstanceRecord = {
+    instance: r.instance,
+    pid: typeof r.pid === "number" ? r.pid : -1,
+    port: r.port,
+    startedAt: typeof r.startedAt === "string" ? r.startedAt : "",
+  };
+  const sp = r.selfProbe;
+  if (sp && typeof sp === "object") {
+    const s = sp as Record<string, unknown>;
+    if (s.status === "ok" || s.status === "hijacked" || s.status === "unreachable") {
+      const state: SelfProbeState = {
+        status: s.status,
+        checkedAt: typeof s.checkedAt === "string" ? s.checkedAt : "",
+      };
+      if (typeof s.observedInstance === "string") state.observedInstance = s.observedInstance;
+      if (typeof s.detail === "string") state.detail = s.detail;
+      rec.selfProbe = state;
+    }
+  }
+  return rec;
+}
+
+/** The result of probing a loopback `/health`. */
+export interface LoopbackProbe {
+  /** The socket answered at all (any HTTP status). */
+  reachable: boolean;
+  /** HTTP status, when reachable. */
+  status?: number;
+  /** The `instance` field of the JSON body, when present + parseable. */
+  instance?: string;
+  /** True when the body self-identifies as a parachute hub (`service: "parachute-hub"`). */
+  isHub?: boolean;
+}
+
+/**
+ * Probe `http://127.0.0.1:<port>/health` and extract the instance identity.
+ * Bounded (default 1.5s); never throws — a network error is `{ reachable: false }`.
+ */
+export async function probeLoopbackInstance(
+  port: number,
+  opts: { timeoutMs?: number; fetchFn?: typeof fetch } = {},
+): Promise<LoopbackProbe> {
+  const fetchFn = opts.fetchFn ?? fetch;
+  try {
+    const res = await fetchFn(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 1500),
+    });
+    const out: LoopbackProbe = { reachable: true, status: res.status };
+    try {
+      const body = (await res.json()) as Record<string, unknown>;
+      if (typeof body.instance === "string") out.instance = body.instance;
+      if (body.service === "parachute-hub") out.isHub = true;
+    } catch {
+      // A non-JSON / unparseable body still counts as "reachable" — a foreign
+      // process answering the port with junk is exactly the hijack shape.
+    }
+    return out;
+  } catch {
+    return { reachable: false };
+  }
+}
+
+/**
+ * Classify a loopback probe against our TRUE nonce.
+ *   - not reachable                → `unreachable` (we bound, but loopback refused/timed out — suspicious but soft).
+ *   - reachable, instance === ours → `ok`.
+ *   - reachable, instance !== ours → `hijacked` (a DIFFERENT process owns loopback: another hub, or a foreign
+ *     server answering `/health` with no/other instance — the OrbStack-shadow class).
+ */
+export function classifyLoopback(ourNonce: string, probe: LoopbackProbe): SelfProbeStatus {
+  if (!probe.reachable) return "unreachable";
+  if (probe.instance === ourNonce) return "ok";
+  return "hijacked";
+}
+
+/**
+ * The LOUD, structured hijack alert. Names the class + the exact diagnosis
+ * commands + the incident reference so an operator scanning logs can act
+ * immediately. Repeated verbatim on every probe while mismatched (by design —
+ * a single line scrolls away; a hijack is a standing emergency).
+ */
+export function hijackAlertMessage(port: number, observedInstance?: string): string {
+  const observed = observedInstance
+    ? `a DIFFERENT hub (instance=${observedInstance})`
+    : "a foreign process (no hub instance nonce in its /health)";
+  return [
+    `parachute serve: LOOPBACK HIJACK on 127.0.0.1:${port} — this hub bound the port but loopback /health is answered by ${observed}.`,
+    "  Loopback traffic (module JWKS/API calls, CLI probes) is NOT reaching this hub — every hub-JWT validation downstream will fail.",
+    `  A specific 127.0.0.1:${port} bind (commonly an OrbStack/container port-forward) wins over this hub's wildcard bind.`,
+    `  Diagnose:  lsof -nP -iTCP:${port} -sTCP:LISTEN   (expect ONE listener — this hub)`,
+    `             orb list   (stop/delete any VM auto-forwarding ${port}, e.g. a leftover smoke-test machine)`,
+    `  Incident:  ${HIJACK_INCIDENT_REF}`,
+  ].join("\n");
+}
+
+/** The softer "we're listening but loopback didn't answer" note (logged once per state change). */
+export function unreachableNote(port: number): string {
+  return `parachute serve: loopback /health on 127.0.0.1:${port} did not answer, yet this hub is bound — transient, or another process is interfering with loopback. Watching (will re-probe).`;
+}
+
+// ---------------------------------------------------------------------------
+// Self-probe timer (armed by `serve` after the listener is up)
+// ---------------------------------------------------------------------------
+
+export interface HubSelfProbe {
+  /** Stop the interval. */
+  stop(): void;
+  /** Run exactly one probe now (used for the immediate startup check + tests). */
+  probeOnce(): Promise<SelfProbeStatus>;
+  /** The most recent in-memory verdict (tests). */
+  getState(): SelfProbeState | undefined;
+}
+
+export interface HubSelfProbeDeps<H = unknown> {
+  /** Poll cadence in ms. Default 300_000 (5 min) — a safety net, not a hot path. */
+  intervalMs?: number;
+  /** Loopback probe (default {@link probeLoopbackInstance}). */
+  probe?: (port: number) => Promise<LoopbackProbe>;
+  /** Persist the verdict (default: patch the instance file's `selfProbe`). */
+  writeState?: (state: SelfProbeState) => void;
+  /** Loud log sink (default `console.error`). */
+  log?: (line: string) => void;
+  /** Clock seam (default `() => new Date()`). */
+  now?: () => Date;
+  /** Injectable scheduler (default `setInterval`). Tests drive ticks manually. */
+  setIntervalFn?: (cb: () => void, ms: number) => H;
+  /** Injectable clear (default `clearInterval`). */
+  clearIntervalFn?: (handle: H) => void;
+}
+
+/**
+ * Arm the loopback self-probe. On each tick (and on the immediate startup
+ * `probeOnce`) it fetches loopback `/health`, compares the returned instance to
+ * OUR nonce, logs per the incident-severity rules, and persists the verdict:
+ *
+ *   - `hijacked`   → LOUD structured alert EVERY tick (standing emergency), verdict persisted.
+ *   - `unreachable`→ softer note, logged ONLY on a state change (avoid a spinning log on a flaky loopback).
+ *   - `ok`         → recovery line logged once when clearing a prior non-ok verdict.
+ *
+ * The verdict is written to the instance file's `selfProbe` field so external
+ * tools (`status`) read the authoritative reading without re-probing the
+ * hijacked loopback. Overlapping ticks are guarded (a slow probe never stacks).
+ * The interval is `unref`'d so it never keeps the event loop alive on its own.
+ */
+export function armHubSelfProbe<H = ReturnType<typeof setInterval>>(
+  args: { port: number; nonce: string; record: HubInstanceRecord; configDir?: string },
+  deps: HubSelfProbeDeps<H> = {},
+): HubSelfProbe {
+  const { port, nonce, record } = args;
+  const intervalMs = deps.intervalMs ?? 300_000;
+  const probe = deps.probe ?? probeLoopbackInstance;
+  const log = deps.log ?? ((line: string) => console.error(line));
+  const now = deps.now ?? (() => new Date());
+  const writeState =
+    deps.writeState ??
+    ((state: SelfProbeState) =>
+      writeHubInstanceFile(
+        { ...record, selfProbe: state },
+        { ...(args.configDir !== undefined ? { configDir: args.configDir } : {}), log },
+      ));
+  const setIntervalFn =
+    deps.setIntervalFn ?? ((cb: () => void, ms: number) => setInterval(cb, ms) as unknown as H);
+  const clearIntervalFn =
+    deps.clearIntervalFn ??
+    ((h: H) => clearInterval(h as unknown as ReturnType<typeof setInterval>));
+
+  let last: SelfProbeState | undefined;
+  let inFlight = false;
+
+  async function probeOnce(): Promise<SelfProbeStatus> {
+    if (inFlight) return last?.status ?? "ok";
+    inFlight = true;
+    try {
+      const result = await probe(port);
+      const status = classifyLoopback(nonce, result);
+      const state: SelfProbeState = { status, checkedAt: now().toISOString() };
+      if (status === "hijacked") {
+        if (result.instance !== undefined) state.observedInstance = result.instance;
+        state.detail = hijackAlertMessage(port, result.instance);
+        // LOUD every tick — a hijack is a standing emergency, not a one-shot notice.
+        log(state.detail);
+      } else if (status === "unreachable") {
+        state.detail = unreachableNote(port);
+        if (last?.status !== "unreachable") log(state.detail);
+      } else {
+        // ok — announce recovery once when clearing a prior non-ok verdict.
+        if (last && last.status !== "ok") {
+          log(
+            `parachute serve: loopback /health on 127.0.0.1:${port} is back to this hub (instance=${nonce}). Hijack cleared.`,
+          );
+        }
+      }
+      last = state;
+      try {
+        writeState(state);
+      } catch {
+        // Persisting the verdict is best-effort; the loud log already fired.
+      }
+      return status;
+    } finally {
+      inFlight = false;
+    }
+  }
+
+  const handle = setIntervalFn(() => {
+    void probeOnce();
+  }, intervalMs);
+  (handle as { unref?: () => void }).unref?.();
+
+  return {
+    stop() {
+      clearIntervalFn(handle);
+    },
+    probeOnce,
+    getState() {
+      return last;
+    },
+  };
+}

package/src/hub-server.ts

@@ -782,6 +782,52 @@ export function wsCapBucketKey(req: Request, peerAddr: string | null): string {
   return peer ?? WS_CAP_SHARED_BUCKET;
 }
 
+/**
+ * Hop-by-hop headers (RFC 9110 §7.6.1) — connection-scoped, meaningful only
+ * on a single transport hop. An intermediary MUST NOT forward them, and the
+ * hub is exactly such an intermediary between the client and each loopback
+ * module.
+ *
+ * Forwarding a client's `Connection: close` verbatim was the P0 amplifier in
+ * the 2026-07-02 port exhaustion (hub#738): Bun's fetch honors the forwarded
+ * `Connection: close` and opens a FRESH ephemeral socket per proxied request
+ * instead of reusing its per-origin keep-alive pool. A hot client loop then
+ * converts request volume 1:1 into 30s TIME_WAIT entries (macOS: ~16k
+ * ephemeral ports), exhausting the range and taking out all host outbound.
+ * With these stripped, Bun reuses a handful of pooled sockets to each 127.0.0.1
+ * upstream regardless of what the client sends.
+ */
+const HOP_BY_HOP_HEADERS = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+] as const;
+
+/**
+ * Delete hop-by-hop headers from an outgoing proxy header bag (mutates in
+ * place). The `Connection` field-value can NAME further headers to drop
+ * (RFC 9110 §7.6.1 — e.g. `Connection: close, X-Custom`), so those tokens are
+ * collected and deleted before the standard set. WebSocket upgrades never
+ * reach the fetch-based proxy (the Bun-native bridge handles them before
+ * dispatch — see `proxyRequest`'s docstring), so dropping `Upgrade`/`Connection`
+ * here only ever touches non-declaring mounts, which see a plain request.
+ */
+export function stripHopByHopHeaders(headers: Headers): void {
+  const connectionValue = headers.get("connection");
+  if (connectionValue) {
+    for (const token of connectionValue.split(",")) {
+      const named = token.trim().toLowerCase();
+      if (named) headers.delete(named);
+    }
+  }
+  for (const name of HOP_BY_HOP_HEADERS) headers.delete(name);
+}
+
 /**
  * Forward a request to a loopback service on `127.0.0.1:<port>`. By default
  * the incoming pathname + query are preserved verbatim; pass `targetPath` to
@@ -847,6 +893,12 @@ async function proxyRequest(
   // Host comes from the requester (tailnet FQDN); the loopback target wants
   // its own. Bun's fetch fills it in when omitted.
   headers.delete("host");
+  // Strip hop-by-hop headers before forwarding (RFC 9110 §7.6.1). Critically
+  // this drops a client-supplied `Connection: close`, which Bun's fetch would
+  // otherwise honor by disabling keep-alive and burning a fresh ephemeral
+  // socket per request — the P0 amplifier in hub#738. Bun refills the
+  // connection framing for the upstream hop itself.
+  stripHopByHopHeaders(headers);
   // Force upstreams to reply with uncompressed bodies. The chrome-strip
   // injector (workstream G) buffers + TextDecoders the HTML response to
   // inject the persistent chrome; without this, a gzip- or br-compressed
@@ -887,6 +939,13 @@ async function proxyRequest(
     method: req.method,
     headers,
     redirect: "manual",
+    // Forward the incoming request's abort signal to the upstream hop. When a
+    // client hangs up mid-response, this aborts the loopback fetch so the
+    // upstream stops streaming to a gone client and its socket is released
+    // back to the pool (or closed) instead of running the full body out and
+    // holding the connection — a secondary socket-retention leak alongside the
+    // TIME_WAIT churn (hub#738). `req.signal` is present on Bun.serve requests.
+    signal: req.signal,
   };
   if (req.method !== "GET" && req.method !== "HEAD") {
     init.body = req.body;
@@ -895,6 +954,14 @@ async function proxyRequest(
   try {
     return await fetch(upstream, init);
   } catch (err) {
+    // Client hung up mid-flight: the upstream fetch was aborted via req.signal
+    // (forwarded above), not an upstream failure. The client is gone, so the
+    // response is discarded — don't run the boot-readiness classifier or
+    // render a "module unreachable" page that would misclassify a normal
+    // disconnect. 499 = client closed request (nginx convention).
+    if (req.signal?.aborted) {
+      return new Response(null, { status: 499 });
+    }
     const msg = err instanceof Error ? err.message : String(err);
     // Classify the failure (transient boot-window vs persistent crash) and
     // render either an HTML page or a JSON error per the request's Accept.
@@ -1261,6 +1328,17 @@ export interface HubFetchDeps {
    * rejected" because Origin ≠ tailnet issuer).
    */
   loopbackPort?: number;
+  /**
+   * This serve process's per-boot instance nonce (hub#737). When present it's
+   * echoed as `instance` in `/health` so an external reader can tell whether a
+   * loopback `/health` actually reached THIS hub or a foreign process that has
+   * shadowed the port (the OrbStack loopback-hijack class). `serve` mints it,
+   * writes it to `~/.parachute/hub-instance.json`, and threads it here; absent
+   * on the DB-less / test / `bun src/hub-server.ts` paths, where `/health`
+   * simply omits the field (additive — no consumer parses `/health` for
+   * `instance` strictly).
+   */
+  instanceNonce?: string;
   /**
    * Test seam for reading `expose-state.json`'s `hubOrigin`. Production reads
    * the operator's `~/.parachute/expose-state.json` via `readExposeState`;
@@ -2314,7 +2392,17 @@ export function hubFetch(
           }
         }
         return new Response(
-          JSON.stringify({ status: "ok", service: "parachute-hub", version: pkg.version, db }),
+          JSON.stringify({
+            status: "ok",
+            service: "parachute-hub",
+            version: pkg.version,
+            db,
+            // Per-boot instance nonce (hub#737): lets an external reader detect a
+            // loopback hijack (foreign process shadowing 127.0.0.1:<port>) by
+            // comparing this to the nonce serve wrote to hub-instance.json.
+            // Omitted when unset (DB-less / test / dev-entrypoint paths).
+            ...(deps?.instanceNonce ? { instance: deps.instanceNonce } : {}),
+          }),
           {
             headers: {
               "content-type": "application/json",

package/src/install-source.ts

@@ -123,7 +123,7 @@ function packageNameFor(entryName: string): string | undefined {
   if (short === undefined) return undefined;
   const fb = FIRST_PARTY_FALLBACKS[short];
   if (fb) return fb.package;
-  // KNOWN_MODULES (vault / scribe / runner — post hub#310 FALLBACK
+  // KNOWN_MODULES (vault / scribe / agent / surface — post hub#310 FALLBACK
   // retirement) carries the package name without an embedded manifest.
   return KNOWN_MODULES[short]?.package;
 }

package/src/service-spec.ts

@@ -322,7 +322,7 @@ const NOTES_FALLBACK: FirstPartyFallback = {
  * Indexed by short name (the `parachute install <X>` token).
  *
  * Only notes remains — see the block comment above for the rationale
- * (vault/scribe/runner/agent now self-register and ship their own
+ * (vault/scribe/agent now self-register and ship their own
  * module.json). Other code paths consult both this table AND `KNOWN_MODULES`
  * (which carries the post-self-register-retirement entries) via the helpers
  * in this file (`shortNameForManifest`, `knownServices`, …).
@@ -437,27 +437,17 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
       ],
     },
   },
-  runner: {
-    short: "runner",
-    package: "@openparachute/runner",
-    manifestName: "parachute-runner",
-    canonicalPort: 1945,
-    displayName: "Runner",
-    tagline:
-      "Vault-as-job-substrate engine — spawns claude -p against vault job notes on schedule.",
-    canonicalPaths: ["/runner", "/.parachute"],
-    canonicalHealth: "/runner/healthz",
-    canonicalStripPrefix: false,
-    extras: {
-      // Backward-compat startCmd — same rationale as scribe / vault above.
-      startCmd: () => ["parachute-runner", "serve"],
-      // Runner's HTTP routes (everything past `/healthz`) gate on a
-      // hub-issued JWT carrying `runner:admin` scope (see runner's
-      // `src/auth.ts`). Surfaces in `parachute status` as auth-required by
-      // default, same posture as vault.
-      hasAuth: true,
-    },
-  },
+  // NOTE (2026-07-01): `runner` was REMOVED from this registry (decision:
+  // Aaron 2026-07-01 — the module set of record is vault / hub / agent /
+  // scribe / surface). Runner is no longer offered, installable, or
+  // lifecycle-addressable by short name from the hub's bootstrap registries.
+  // Existing installs stay GRACEFUL: a legacy `parachute-runner` services.json
+  // row is handled exactly like any unknown/third-party row — `parachute
+  // status` renders it (short falls back to the row name), `parachute serve`
+  // boots it via `<installDir>/.parachute/module.json` when installDir is
+  // stamped and logs-and-skips otherwise. Deliberately NOT added to
+  // RETIRED_MODULES: that registry GC-drops rows on load, which would break
+  // routing for operators still running the runner daemon.
   agent: {
     short: "agent",
     package: "@openparachute/agent",
@@ -474,7 +464,7 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
     canonicalStripPrefix: true,
     extras: {
       // Backward-compat startCmd for rows without installDir — same rationale
-      // as scribe / vault / runner. The bare binary IS the daemon (agent's
+      // as scribe / vault. The bare binary IS the daemon (agent's
       // package.json bin maps `parachute-agent` → src/daemon.ts).
       startCmd: () => ["parachute-agent"],
       // Agent gates its endpoints behind hub-issued JWTs (agent:* scopes).
@@ -498,14 +488,14 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
     canonicalHealth: "/surface/healthz",
     canonicalStripPrefix: false,
     extras: {
-      // Backward-compat startCmd — same rationale as scribe / vault / runner
+      // Backward-compat startCmd — same rationale as scribe / vault
       // above. Post-self-register, lifecycle reads module.json's startCmd via
       // `composeKnownModuleSpec` and that path wins.
       startCmd: () => ["parachute-surface", "serve"],
       // Surface's admin + per-UI surfaces gate behind hub-issued JWTs (design
       // doc §6 same-hub auto-trust + scope `surface:admin`). Surfaces in
-      // `parachute status` as auth-required by default, same posture as vault
-      // + runner.
+      // `parachute status` as auth-required by default, same posture as
+      // vault.
       hasAuth: true,
     },
   },
@@ -646,10 +636,11 @@ export function knownServices(): string[] {
  *   - `experimental` — agent (legit preview; still OFFERED on a fresh install)
  *     + any unlisted third-party short.
  *   - `deprecated` — notes (notes-daemon deprecated 2026-05-22; notes-ui moved
- *     into parachute-surface) + runner (per Aaron 2026-06-25: not for new
- *     installs). Still RESOLVABLE (discoverableShorts unchanged) and
- *     SHOWN-IF-INSTALLED so an existing operator can manage/uninstall, but NOT
- *     OFFERED on a fresh setup.
+ *     into parachute-surface). Still RESOLVABLE (discoverableShorts unchanged)
+ *     and SHOWN-IF-INSTALLED so an existing operator can manage/uninstall, but
+ *     NOT OFFERED on a fresh setup. `runner` used to sit here too (deprecated
+ *     2026-06-25) until its full registry removal on 2026-07-01 — see the note
+ *     in KNOWN_MODULES.
  *
  * **Show all installed; never hide** — `focus` groups + labels; the one
  * behavioral lever is the fresh-install OFFER, which drops `deprecated` shorts.
@@ -660,7 +651,6 @@ const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
   hub: "core",
   surface: "core",
   agent: "experimental",
-  runner: "deprecated",
   notes: "deprecated",
 };
 
@@ -671,7 +661,7 @@ const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
  * returns undefined — the Modules screen always has a tier to group by.
  *
  * Tier semantics: `core`/`experimental` are both OFFERED on a fresh install;
- * `deprecated` (notes / runner) is NOT offered on a fresh setup but stays
+ * `deprecated` (notes) is NOT offered on a fresh setup but stays
  * resolvable + shown-if-installed (the `isKnownModuleShort` /
  * `discoverableShorts` resolution surface is unchanged). The fresh-install
  * filters in `setup.ts` + `api-modules.ts` consult this tier to drop
@@ -689,14 +679,16 @@ export function focusForShort(short: string, declared?: ModuleFocus): ModuleFocu
  * `CURATED_MODULES` whitelist (2026-06-09 modular-UI architecture, P2): every
  * module the hub can resolve a package/manifest for is discoverable + installable,
  * regardless of `focus` tier. Deduped, with FIRST_PARTY_FALLBACKS shorts first
- * (notes) then KNOWN_MODULES (vault / scribe / runner / agent / surface).
- *
- * `notes` (and `runner`) are intentionally included — still resolvable
- * (vendored fallback / KNOWN_MODULES) for legacy installs; they surface as
- * `deprecated` (2026-06-25) and aren't OFFERED on a fresh install. The
- * fresh-install OFFER (setup wizard + admin SPA) filters by tier
- * (`focus !== "deprecated"`); `discoverableShorts` itself stays the full
- * resolution surface so existing installs keep working.
+ * (notes) then KNOWN_MODULES (vault / scribe / agent / surface).
+ *
+ * `notes` is intentionally included — still resolvable (vendored fallback)
+ * for legacy installs; it surfaces as `deprecated` (2026-06-25) and isn't
+ * OFFERED on a fresh install. The fresh-install OFFER (setup wizard + admin
+ * SPA) filters by tier (`focus !== "deprecated"`); `discoverableShorts`
+ * itself stays the full resolution surface so existing installs keep working.
+ * `runner` is NOT here anymore (registry removal 2026-07-01 — see the
+ * KNOWN_MODULES note); a legacy runner install is handled as an
+ * unknown/third-party row.
  */
 export function discoverableShorts(): string[] {
   const seen = new Set<string>();
@@ -750,7 +742,7 @@ export function canonicalPortForManifest(manifestName: string): number | undefin
  * spec with embedded manifest + extras — the vendored manifest is the
  * source of truth pre-install and the install path preserves it through.
  *
- * KNOWN_MODULES shorts (vault / scribe / runner / agent / surface — post
+ * KNOWN_MODULES shorts (vault / scribe / agent / surface — post
  * FALLBACK retirement) return a **minimal** spec carrying `package`, `manifestName`,
  * and the imperative `extras` fields
  * (`init`, `hasAuth`, `urlForEntry`, `postInstallFooter`). They do NOT carry
@@ -860,7 +852,7 @@ const LEGACY_MANIFEST_ALIASES: Record<string, string> = {
 
 /** Short name for a given manifest name, e.g. `parachute-vault` → `vault`.
  *  Consults both FIRST_PARTY_FALLBACKS (notes) and KNOWN_MODULES
- *  (vault / scribe / runner / agent / surface — post-FALLBACK-retirement).
+ *  (vault / scribe / agent / surface — post-FALLBACK-retirement).
  *  Returns undefined for unknown manifests. */
 export function shortNameForManifest(manifestName: string): string | undefined {
   for (const [short, fb] of Object.entries(FIRST_PARTY_FALLBACKS)) {
@@ -887,7 +879,7 @@ export function shortNameForManifest(manifestName: string): string | undefined {
  * here — `shortNameForManifest` only knows the canonical `parachute-vault`, so
  * `findServiceByShort(services, "vault")` returns undefined even when a vault is
  * installed. Vault rows are resolved by mount path via `findVaultUpstream`; this
- * helper is for single-instance modules (agent / scribe / runner / surface).
+ * helper is for single-instance modules (agent / scribe / surface).
  */
 export function findServiceByShort<T extends { name: string }>(
   services: readonly T[],
@@ -901,7 +893,7 @@ export function findServiceByShort<T extends { name: string }>(
  * manifest data the caller has on hand (typically read from
  * `<installDir>/.parachute/module.json`).
  *
- * Used at install-time and lifecycle-time for vault / scribe / runner —
+ * Used at install-time and lifecycle-time for vault / scribe / surface —
  * where hub no longer vendors the manifest (services.json + module.json
  * are authoritative) but still needs the imperative `extras` bits
  * (`init`, `postInstallFooter`, `urlForEntry`, `hasAuth`) the CLI install