@openparachute/hub 0.7.5 → 0.7.6-rc.3

package/src/commands/install.ts

@@ -65,7 +65,7 @@ export type Runner = (cmd: readonly string[]) => Promise<number>;
  * Rationale: the canonical Render deploy ships the hub container from
  * `main` (which tracks the rc chain per governance rule 2). Without this
  * env var the supervisor's `/admin/modules` install API would still
- * resolve `@latest` for vault / app / scribe / runner — leaving a hub-on-rc
+ * resolve `@latest` for vault / surface / scribe — leaving a hub-on-rc
  * cluster bootstrapping its other modules on stable, which silently
  * fragments the cluster's version axis. Setting `PARACHUTE_INSTALL_CHANNEL=rc`
  * at the platform level cascades the rc-ness across every module install,
@@ -137,6 +137,22 @@ const SERVICE_ALIASES: Record<string, string> = {
   channel: "agent",
 };
 
+/**
+ * Former first-party shorts that were RETIRED from the registries (not
+ * renamed — no alias target). Without this guard the bare short would fall
+ * through resolveInstallTarget's "anything else is npm" arm and `bun add -g`
+ * an UNRELATED npm package that happens to share the name (`runner` is a
+ * real, non-Parachute package on npm). Install refuses with the message
+ * instead.
+ */
+const RETIRED_INSTALL_SHORTS: Record<string, string> = {
+  runner:
+    "parachute-runner was retired from the hub's module registry on 2026-07-01 " +
+    "(the module set of record is vault, hub, agent, scribe, surface). " +
+    "An existing install keeps running under `parachute serve`; to install it anyway, " +
+    "pass the explicit npm package name (@openparachute/runner) or a local checkout path.",
+};
+
 export interface InstallOpts {
   runner?: Runner;
   manifestPath?: string;
@@ -625,7 +641,8 @@ async function readInstalledManifest(
  *   - **fallback**: notes / channel still ship a vendored manifest + extras
  *     in FIRST_PARTY_FALLBACKS. Missing `module.json` is non-fatal — the
  *     embedded manifest carries the install through.
- *   - **known**: vault / scribe / runner have retired their FALLBACK entries.
+ *   - **known**: vault / scribe / agent / surface have retired their FALLBACK
+ *     entries (runner had too, before its 2026-07-01 registry removal).
  *     We know the package + manifestName + imperative extras (init,
  *     postInstallFooter, urlForEntry, hasAuth) but NOT the static manifest;
  *     `module.json` is the contract and a missing one is a hard error,
@@ -672,6 +689,15 @@ function resolveInstallTarget(
   const aliased = SERVICE_ALIASES[input];
   const candidate = aliased ?? input;
 
+  // Retired shorts refuse BEFORE the npm fallback: `install runner` must not
+  // `bun add -g` npm's unrelated `runner` package. Explicit package names /
+  // paths still pass through the arms below.
+  const retiredMessage = RETIRED_INSTALL_SHORTS[candidate];
+  if (retiredMessage !== undefined) {
+    log(`✗ ${retiredMessage}`);
+    return null;
+  }
+
   const fb = FIRST_PARTY_FALLBACKS[candidate];
   if (fb) {
     if (aliased !== undefined) {
@@ -943,7 +969,7 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     manifest = installedManifest ?? target.fallback.manifest;
     extras = target.fallback.extras;
   } else if (target.kind === "known-module") {
-    // KNOWN_MODULES shorts (vault / scribe / runner) carry no vendored
+    // KNOWN_MODULES shorts (vault / scribe / agent / surface) carry no vendored
     // manifest (hub#310). The module's own `.parachute/module.json` is the
     // canonical source. When it's unreadable (legacy installs from before
     // module.json shipped, or test fixtures that mock the disk path without

package/src/commands/migrate.ts

@@ -77,6 +77,11 @@ export const ARCHIVE_PREFIX = ".archive-";
 export function safelistEntries(): Set<string> {
   return new Set<string>([
     ...knownServices(),
+    // `runner` left the registries on 2026-07-01 (module set of record:
+    // vault / hub / agent / scribe / surface) but legacy installs still have
+    // a `~/.parachute/runner/` dir — keep it safelisted so it doesn't count
+    // as unrecognized-root noise in `migrateNotice`.
+    "runner",
     "hub",
     "services.json",
     "expose-state.json",

package/src/commands/serve.ts

@@ -36,6 +36,14 @@ import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { readExposeState } from "../expose-state.ts";
 import { createDbHolder, defaultStatInode, startDbPathLivenessTimer } from "../hub-db-liveness.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  type HubInstanceRecord,
+  type HubSelfProbe,
+  armHubSelfProbe,
+  clearHubInstanceFile,
+  generateInstanceNonce,
+  writeHubInstanceFile,
+} from "../hub-instance.ts";
 import { hubFetch } from "../hub-server.ts";
 import { getHubOrigin } from "../hub-settings.ts";
 import { writeHubFile } from "../hub.ts";
@@ -513,6 +521,13 @@ export async function serve(opts: ServeOpts = {}): Promise<{
 
   const supervisor = opts.supervisor ?? new Supervisor();
 
+  // Per-boot instance nonce (hub#737). Minted BEFORE the listener so it can be
+  // threaded into `/health`; written to disk AFTER a successful bind (below) so
+  // a bind failure never leaves a stale identity file. It's the linchpin of
+  // loopback-hijack detection: `/health` echoes it, and external tools compare
+  // the disk copy to what a loopback `/health` actually returns.
+  const instanceNonce = generateInstanceNonce();
+
   // Claim the hub port FIRST — before booting a single supervised module. If
   // another hub/supervisor already owns it, `Bun.serve` throws here and we
   // exit immediately. The prior order (boot modules, *then* bind) let a
@@ -534,6 +549,7 @@ export async function serve(opts: ServeOpts = {}): Promise<{
           probeDbPath: () => dbHolder.probePath(),
           issuer,
           loopbackPort: port,
+          instanceNonce,
           supervisor,
         }),
       }),
@@ -544,6 +560,38 @@ export async function serve(opts: ServeOpts = {}): Promise<{
     throw err;
   }
 
+  // We own the listener now — record this process's identity on disk (0644) so
+  // `parachute status` / `parachute doctor` can detect a loopback hijack by
+  // comparing this nonce to what a loopback `/health` returns. Best-effort:
+  // a write failure only degrades external detection, never blocks the hub.
+  const instanceRecord: HubInstanceRecord = {
+    instance: instanceNonce,
+    pid: process.pid,
+    port,
+    startedAt: new Date().toISOString(),
+  };
+  writeHubInstanceFile(instanceRecord, { configDir: CONFIG_DIR, log });
+
+  // Arm the loopback self-probe (hub#737): an immediate check right after the
+  // bind catches a hijack that's ALREADY present at boot (the OrbStack VM that
+  // relaunched at reboot and grabbed 127.0.0.1:<port> before us), then a
+  // low-frequency re-probe catches one that appears later. It logs loudly on a
+  // mismatch and records the verdict into hub-instance.json for external tools.
+  // Skipped alongside module boot in tests (`skipModuleBoot`) so the test path
+  // never spawns a real 5-minute timer / loopback fetch.
+  let selfProbe: HubSelfProbe | undefined;
+  if (!opts.skipModuleBoot) {
+    selfProbe = armHubSelfProbe(
+      { port, nonce: instanceNonce, record: instanceRecord, configDir: CONFIG_DIR },
+      { log },
+    );
+    // Fire the startup check without blocking serve's return — a hijack present
+    // at boot surfaces within the probe's bounded timeout, not on the next tick.
+    // `probeOnce` is non-throwing in production, but guard the floating promise
+    // against ever surfacing as an unhandled rejection.
+    void selfProbe.probeOnce().catch(() => {});
+  }
+
   log(
     formatListeningBanner({
       hostname,
@@ -618,8 +666,12 @@ export async function serve(opts: ServeOpts = {}): Promise<{
       for (const state of supervisor.list()) {
         await supervisor.stop(state.short);
       }
+      selfProbe?.stop();
       livenessTimer.stop();
       await server.stop();
+      // Clear our on-disk identity so a cleanly-stopped hub leaves no stale
+      // self-probe verdict for `status` / `doctor` to read (hub#737 review).
+      clearHubInstanceFile(CONFIG_DIR);
       dbHolder.get().close();
     },
   };

package/src/commands/setup.ts

@@ -66,7 +66,7 @@ export interface SetupOpts {
  * Survey row. Pre-install we know manifestName + the optional
  * `urlForEntry` quirk (vault wants `/mcp`, scribe wants the bare port); the
  * full ServiceSpec only exists post-install for KNOWN_MODULES shorts
- * (vault / scribe / runner — hub#310). The survey uses just these two
+ * (vault / scribe / … — hub#310). The survey uses just these two
  * fields, so a minimal shape avoids the spec round-trip pre-install.
  */
 interface ServiceChoice {
@@ -110,17 +110,19 @@ function defaultAvailability(): InteractiveAvailability {
 
 /**
  * Survey ALL known first-party shortnames (vault / notes / scribe / agent /
- * runner / surface) regardless of tier — `installed` is true when the service
+ * 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
+ * notes); 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).
+ * has on disk). A legacy `parachute-runner` row is NOT surveyed (runner left
+ * the registries 2026-07-01 — see the KNOWN_MODULES note in service-spec.ts);
+ * like any unknown row it neither blocks setup nor appears in the offer.
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
  * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
- * (vault / scribe / runner / agent / surface) ship `.parachute/module.json`
+ * (vault / scribe / agent / surface) ship `.parachute/module.json`
  * and self-register; pre-install we know manifestName + the urlForEntry quirk
  * from `KNOWN_MODULES[short].extras`, which is all the survey/summary needs.
  */
@@ -157,7 +159,7 @@ 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
+ * deprecated tier (notes-daemon) 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.
@@ -175,11 +177,10 @@ const BLURBS: Record<string, string> = {
   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 / runner are `deprecated` (not offered on a fresh setup) — these
-  // blurbs only render if a legacy install surfaces them in the survey.
+  // notes is `deprecated` (not offered on a fresh setup) — this blurb only
+  // renders if a legacy install surfaces it 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:
     "(exploratory) chat with your Claude Code sessions — a channel per session (renamed from channel)",
 };

package/src/commands/status.ts

@@ -2,6 +2,7 @@ import type { Database } from "bun:sqlite";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { readHubPort } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { type SelfProbeState, readHubInstanceFile } from "../hub-instance.ts";
 import {
   HUB_UNIT_DEFAULT_PORT,
   type HubUnitDeps,
@@ -90,6 +91,16 @@ export interface StatusOpts {
     openDb?: (configDir: string) => Database;
     /** Loopback hub base URL override (default derives from the hub port). */
     baseUrl?: string;
+    /**
+     * Read the running serve process's last loopback self-probe verdict from
+     * `hub-instance.json` (hub#737). Read from DISK, not over loopback — during
+     * a hijack the loopback /health (and the module-ops API) reach the WRONG
+     * hub, so the on-disk verdict the real serve wrote is the only trustworthy
+     * source. A `hijacked` verdict overrides the hub row (which would otherwise
+     * read `active` off the rogue's 200). Default {@link readHubInstanceFile}'s
+     * `selfProbe`; tests inject a state (or undefined).
+     */
+    readInstanceState?: (configDir: string) => SelfProbeState | undefined;
   };
 }
 
@@ -386,6 +397,7 @@ interface ResolvedStatusSupervisor {
   probeModuleHealth: (port: number, health: string) => Promise<boolean>;
   openDb: (configDir: string) => Database;
   baseUrl: string | undefined;
+  readInstanceState: (configDir: string) => SelfProbeState | undefined;
 }
 
 /**
@@ -402,6 +414,8 @@ function resolveStatusSupervisor(opts: StatusOpts["supervisor"]): ResolvedStatus
     probeModuleHealth: opts?.probeModuleHealth ?? defaultProbeModuleHealth,
     openDb: opts?.openDb ?? ((configDir) => openHubDb(hubDbPath(configDir))),
     baseUrl: opts?.baseUrl,
+    readInstanceState:
+      opts?.readInstanceState ?? ((configDir) => readHubInstanceFile(configDir)?.selfProbe),
   };
 }
 
@@ -671,8 +685,35 @@ async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<Statu
     port,
     hubHealthy,
   });
+  // Loopback-hijack override (hub#737). During a hijack the loopback `/health`
+  // the hub row's liveness probe hit belongs to the ROGUE hub (a 200 → the row
+  // reads `active`), so trust the running serve's own on-disk self-probe verdict
+  // instead — read from disk, never over the hijacked loopback. A `hijacked`
+  // verdict flips the row to `failing` with the loud, actionable note.
+  //
+  // GATED ON `hubHealthy` (review fix): the instance file is written per-boot
+  // and only cleared on a *graceful* stop, so a hard-killed hub can leave a
+  // stale `hijacked` verdict on disk. `hubHealthy` is true exactly when
+  // SOMETHING is answering the loopback port right now — which is precisely the
+  // live-hijack condition (the rogue keeps answering 200), so gating here never
+  // suppresses a real hijack, but it does keep a stopped hub (nothing answering)
+  // from rendering a phantom hijack over its normal down-hub row.
+  let selfProbe: SelfProbeState | undefined;
+  try {
+    selfProbe = sup.readInstanceState(configDir);
+  } catch {
+    selfProbe = undefined;
+  }
+  if (hubHealthy && selfProbe?.status === "hijacked") {
+    hub.stateLabel = "failing";
+    hub.healthy = false;
+    hub.skipped = false;
+    hub.healthDetail = "loopback hijacked — /health answered by a foreign process";
+    hub.managerNote = `LOOPBACK HIJACK on :${port} — module JWKS/API calls are NOT reaching this hub. Run \`parachute doctor\` and \`lsof -nP -iTCP:${port} -sTCP:LISTEN\`.`;
+  }
   // If the degraded-read note never landed on a module row (empty manifest),
-  // surface it on the hub row so the operator still sees the actionable hint.
+  // surface it on the hub row so the operator still sees the actionable hint —
+  // unless the hijack note already claimed it (the hijack is the bigger signal).
   if (moduleReadNote && !hub.managerNote) hub.managerNote = moduleReadNote;
   rows.push(hub);
   return rows;

package/src/connections-store.ts

@@ -113,12 +113,22 @@ export interface ConnectionRecord {
   readonly requestedBy?: string;
 }
 
+/**
+ * On-disk schema version stamped on every write (2026-07-01). Readers treat a
+ * file WITHOUT a `version` field as v1 — every connections.json written before
+ * this field existed is a v1 file, so absence tolerance is the whole
+ * back-compat story. No migration logic exists today; the field is here so a
+ * FUTURE shape change can branch on it instead of sniffing record shapes.
+ */
+export const CONNECTIONS_FILE_VERSION = 1;
+
 interface ConnectionsFile {
+  version: number;
   connections: ConnectionRecord[];
 }
 
 function emptyFile(): ConnectionsFile {
-  return { connections: [] };
+  return { version: CONNECTIONS_FILE_VERSION, connections: [] };
 }
 
 /** Read the store. A missing/garbage file reads as empty (fresh hub). */
@@ -136,6 +146,9 @@ export function readConnections(storePath: string): ConnectionRecord[] {
     return [];
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+  // `version` is deliberately NOT validated here: an absent field is a legacy
+  // v1 file (see CONNECTIONS_FILE_VERSION) and there is only one version
+  // today. When v2 lands, this is where the migration branches.
   const arr = (parsed as { connections?: unknown }).connections;
   if (!Array.isArray(arr)) return [];
   // Lenient: drop any malformed row rather than failing the whole read, so one
@@ -156,7 +169,7 @@ export function readConnections(storePath: string): ConnectionRecord[] {
 
 function writeAll(storePath: string, records: ConnectionRecord[]): void {
   mkdirSync(dirname(storePath), { recursive: true });
-  const file: ConnectionsFile = { connections: records };
+  const file: ConnectionsFile = { version: CONNECTIONS_FILE_VERSION, connections: records };
   // Written WITHOUT 0o600 because this file holds NO secrets — the provisioned
   // webhook bearer lives only in the vault trigger's row, never here; records
   // carry source/sink/trigger-name metadata only. Consistent with the default

package/src/git-notify.ts

@@ -31,6 +31,7 @@
  * validates when it comes back in over loopback.
  */
 import type { Database } from "bun:sqlite";
+import { REGISTERED_MINT_TTL_THRESHOLD_SECONDS } from "./admin-connections.ts";
 import { signAccessToken } from "./jwt-sign.ts";
 
 /** Provenance identity stamped on the hub-internal notify + pull tokens. */
@@ -43,18 +44,46 @@ const SURFACE_AUDIENCE = "surface";
 /**
  * notify-auth TTL. The POST is fired immediately; a small window covers a
  * momentarily-busy loopback without leaving a usable credential lying around.
+ *
+ * Exported for the TTL-policy guard test only.
  */
-const NOTIFY_TTL_SECONDS = 120;
+export const NOTIFY_TTL_SECONDS = 120;
 
 /**
  * pull-token TTL. Long enough for surface-host to `git clone --depth 1` a
  * source surface right after the notify lands, short enough that a leaked
  * token is near-useless. Both TTLs here MUST stay well under the hub's
- * registered-mint threshold (admin-connections REGISTERED_MINT_TTL_THRESHOLD,
- * 600s) so these fire-and-forget tokens remain unregistered-by-policy — bumping
- * either past it without registering them would leak unrevocable tokens.
+ * registered-mint threshold (`REGISTERED_MINT_TTL_THRESHOLD_SECONDS`, 600s —
+ * imported from admin-connections.ts, where the policy lives) so these
+ * fire-and-forget tokens remain unregistered-by-policy — bumping either past
+ * it without registering them would leak unrevocable tokens. Enforced by
+ * {@link assertUnregisteredMintTtl} at module load, not just this comment.
+ *
+ * Exported for the TTL-policy guard test only.
  */
-const PULL_TTL_SECONDS = 300;
+export const PULL_TTL_SECONDS = 300;
+
+/**
+ * Registered-mint policy guard (hub-module-boundary charter): a TTL minted
+ * WITHOUT a tokens-table registration must stay strictly under the
+ * registered-mint threshold. Throws at module load when a future edit bumps
+ * one of this file's fire-and-forget TTLs to/past the line — turning a silent
+ * "unrevocable token" policy leak into an immediate boot failure.
+ *
+ * Exported for tests; not for reuse as a general validator (registered mint
+ * sites legitimately exceed the threshold — they register the jti instead).
+ */
+export function assertUnregisteredMintTtl(name: string, ttlSeconds: number): void {
+  if (ttlSeconds >= REGISTERED_MINT_TTL_THRESHOLD_SECONDS) {
+    throw new Error(
+      `git-notify: ${name} (${ttlSeconds}s) must stay under the registered-mint threshold (${REGISTERED_MINT_TTL_THRESHOLD_SECONDS}s). Tokens minted here are fire-and-forget and never registered in the tokens table — at/above the threshold they'd be long-lived AND unrevocable. Either shorten the TTL or register the mint (see admin-connections.ts registered-mint rule).`,
+    );
+  }
+}
+
+// Module-load enforcement of the policy the comments above describe.
+assertUnregisteredMintTtl("NOTIFY_TTL_SECONDS", NOTIFY_TTL_SECONDS);
+assertUnregisteredMintTtl("PULL_TTL_SECONDS", PULL_TTL_SECONDS);
 
 /** Bound the notify HTTP call so a wedged surface-host can't hang the caller. */
 const NOTIFY_FETCH_TIMEOUT_MS = 10_000;

package/src/grants-store.ts

@@ -143,7 +143,17 @@ export interface GrantRecord {
   readonly approvedAt?: string;
 }
 
+/**
+ * On-disk schema version stamped on every write (2026-07-01). Readers treat a
+ * file WITHOUT a `version` field as v1 — every agent-grants.json written
+ * before this field existed is a v1 file, so absence tolerance is the whole
+ * back-compat story. No migration logic exists today; the field is here so a
+ * FUTURE shape change can branch on it instead of sniffing record shapes.
+ */
+export const GRANTS_FILE_VERSION = 1;
+
 interface GrantsFile {
+  version: number;
   grants: GrantRecord[];
 }
 
@@ -194,7 +204,7 @@ export function grantId(agent: string, spec: ConnectionSpec): string {
 }
 
 function emptyFile(): GrantsFile {
-  return { grants: [] };
+  return { version: GRANTS_FILE_VERSION, grants: [] };
 }
 
 function isConnectionSpec(v: unknown): v is ConnectionSpec {
@@ -221,6 +231,9 @@ export function readGrants(storePath: string): GrantRecord[] {
     return [];
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+  // `version` is deliberately NOT validated here: an absent field is a legacy
+  // v1 file (see GRANTS_FILE_VERSION) and there is only one version today.
+  // When v2 lands, this is where the migration branches.
   const arr = (parsed as { grants?: unknown }).grants;
   if (!Array.isArray(arr)) return [];
   // Lenient: drop a malformed row rather than failing the whole read (mirrors
@@ -245,7 +258,7 @@ export function readGrants(storePath: string): GrantRecord[] {
 
 function writeAll(storePath: string, records: GrantRecord[]): void {
   mkdirSync(dirname(storePath), { recursive: true });
-  const file: GrantsFile = { grants: records };
+  const file: GrantsFile = { version: GRANTS_FILE_VERSION, grants: records };
   // 0600 — UNLIKE connections.json, this file holds the granted secrets
   // (minted vault tokens + pasted service creds in `material`). `writeFileSync`'s
   // `mode` applies at CREATE time (passed to open(O_CREAT)), so a fresh file is

package/src/help.ts

@@ -103,8 +103,8 @@ Flags:
 Environment:
   PARACHUTE_INSTALL_CHANNEL=rc|latest
                             cluster-wide default channel. Lets a Render deploy
-                            running the hub at \`@rc\` cascade rc to vault / app /
-                            scribe / runner installed via the admin SPA — without
+                            running the hub at \`@rc\` cascade rc to vault / surface /
+                            scribe installed via the admin SPA — without
                             an explicit \`--channel\` per call. Loses to \`--channel\`
                             and \`--tag\`. Defaults to \`latest\` when unset.
 
@@ -144,7 +144,7 @@ What it does:
   Fresh-install front door, one command for both laptops AND remote
   servers (EC2, DigitalOcean, Hetzner, any VPS). The admin SPA already
   walks operators through the rest (install vault, set up the admin
-  user, install scribe / runner / app); this command's only job is to
+  user, install scribe / surface); this command's only job is to
   get you to that wizard.
 
   Idempotent — every re-run is safe: