@openparachute/hub 0.7.6-rc.1 → 0.7.6-rc.4

package/src/__tests__/status-supervisor.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { status } from "../commands/status.ts";
+import type { SelfProbeState } from "../hub-instance.ts";
 import type { HubUnitDeps, HubUnitStateResult } from "../hub-unit.ts";
 import {
   type ModuleStatesResult,
@@ -86,6 +87,12 @@ interface SupervisorArmOpts {
    * network; specific tests override to mark a module live.
    */
   probeModuleHealth?: (port: number, health: string) => Promise<boolean>;
+  /**
+   * Loopback-hijack self-probe verdict read off `hub-instance.json` (hub#737).
+   * Defaults to "no verdict on disk" (undefined) so existing tests are
+   * unaffected; the hijack tests inject a `hijacked` / `ok` verdict.
+   */
+  readInstanceState?: (configDir: string) => SelfProbeState | undefined;
 }
 
 /** Drive `status` through the supervisor arm with fully stubbed seams. */
@@ -104,6 +111,7 @@ function supervisorOpts(configDir: string, path: string, o: SupervisorArmOpts) {
         (async () => o.moduleStates ?? { supervisorAvailable: true, modules: [] }),
       probeModuleHealth: o.probeModuleHealth ?? (async () => false),
       openDb: fakeOpenDb as unknown as (configDir: string) => import("bun:sqlite").Database,
+      readInstanceState: o.readInstanceState ?? (() => undefined),
     },
   };
 }
@@ -651,3 +659,107 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
 // manager + supervisor. The supervisor-path readout is exercised throughout the
 // suites above; a box with no hub unit degrades gracefully (manager `no-unit` /
 // `/health` down → inactive rows), which the hub-row + module-row suites cover.
+
+describe("status — loopback-hijack override (hub#737)", () => {
+  test("selfProbe hijacked flips the hub row to failing despite a healthy /health", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const lines: string[] = [];
+      const opts = supervisorOpts(configDir, path, {
+        // The rogue answers /health 200, so the raw liveness probe says healthy —
+        // the on-disk self-probe verdict is what corrects the row.
+        managerState: { state: "active" },
+        hubHealthy: true,
+        moduleStates: { supervisorAvailable: true, modules: [] },
+        readInstanceState: () => ({
+          status: "hijacked",
+          checkedAt: "2026-07-02T00:00:00.000Z",
+          observedInstance: "rogue-hub",
+        }),
+      });
+      const code = await status({ ...opts, print: (l) => lines.push(l) });
+      expect(code).toBe(1);
+      const out = lines.join("\n");
+      const hubLine = lines.find((l) => l.includes("parachute-hub (internal)"));
+      expect(hubLine).toMatch(/\bfailing\b/);
+      expect(out).toContain("LOOPBACK HIJACK on :1939");
+      expect(out).toMatch(/lsof -nP -iTCP:1939 -sTCP:LISTEN/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("hub down + STALE hijacked verdict on disk → NO phantom hijack, normal down-hub row", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const lines: string[] = [];
+      // A hard-killed hub can leave a stale `hijacked` verdict in hub-instance.json
+      // (it's only cleared on a graceful stop). With nothing answering loopback
+      // (hubHealthy=false), status must render the ordinary down-hub row, not a
+      // phantom LOOPBACK HIJACK warning.
+      const opts = supervisorOpts(configDir, path, {
+        managerState: { state: "inactive" },
+        hubHealthy: false,
+        readInstanceState: () => ({
+          status: "hijacked",
+          checkedAt: "2026-07-02T00:00:00.000Z",
+          observedInstance: "rogue-from-a-past-run",
+        }),
+      });
+      const code = await status({ ...opts, print: (l) => lines.push(l) });
+      const out = lines.join("\n");
+      expect(out).not.toContain("LOOPBACK HIJACK");
+      const hubLine = lines.find((l) => l.includes("parachute-hub (internal)"));
+      expect(hubLine).toMatch(/\binactive\b/);
+      // An inactive hub is `skipped` (expected-stopped), so exit 0 — the point is
+      // simply that no phantom hijack was injected on top of the normal row.
+      expect(code).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("selfProbe ok leaves a healthy hub row untouched (active)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const lines: string[] = [];
+      const opts = supervisorOpts(configDir, path, {
+        managerState: { state: "active" },
+        hubHealthy: true,
+        moduleStates: { supervisorAvailable: true, modules: [] },
+        readInstanceState: () => ({
+          status: "ok",
+          checkedAt: "2026-07-02T00:00:00.000Z",
+        }),
+      });
+      const code = await status({ ...opts, print: (l) => lines.push(l) });
+      expect(code).toBe(0);
+      const hubLine = lines.find((l) => l.includes("parachute-hub (internal)"));
+      expect(hubLine).toMatch(/\bactive\b/);
+      expect(lines.join("\n")).not.toContain("LOOPBACK HIJACK");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no self-probe verdict on disk → no override (default read returns undefined)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const lines: string[] = [];
+      // No readInstanceState override + no file on disk → the default reader
+      // returns undefined and the row is unchanged.
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          moduleStates: { supervisorAvailable: true, modules: [] },
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      expect(lines.join("\n")).not.toContain("LOOPBACK HIJACK");
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/admin-clients.ts

@@ -39,7 +39,7 @@
  * UX is preserved.
  *
  * Two cases, one route — `return_to` is the discriminator. The pattern
- * doc is `parachute-patterns/patterns/oauth-dcr-approval.md` §"SPA
+ * doc is `docs/contracts/oauth-dcr-approval.md` §"SPA
  * approve page (two cases, one route)".
  *
  * Validation reuses `isSafeAuthorizeReturnTo` from oauth-handlers.ts so

package/src/admin-module-token.ts

@@ -132,7 +132,7 @@ export async function handleModuleToken(
   //      installDir carries a readable module.json. This is the canonical
   //      gate — any module (first- or third-party) that completed
   //      self-registration mints with zero hub code changes, per
-  //      `parachute-patterns/patterns/hub-module-boundary.md` (the seam,
+  //      `docs/contracts/hub-module-boundary.md` (the seam,
   //      mechanism 1).
   //   2. KNOWN bootstrap short (KNOWN_MODULES ∪ FIRST_PARTY_FALLBACKS): kept
   //      as a fallback so a first-party module mid-install (row not yet

package/src/brand.ts

@@ -7,7 +7,7 @@
  * mark or the tagline copy happens in ONE place; every consumer follows.
  *
  * Source of truth for the brand mark + tagline lives in the design-system
- * pattern doc (`parachute-patterns/patterns/design-system.md` §2). This file
+ * contract doc (`docs/contracts/design-system.md` §2). This file
  * is the hub's vendored copy of that mark so the chrome injector + the
  * server-rendered surfaces can render without fetching anything at runtime.
  * Keep this file's SVG path corpus in sync with the design-system doc; the

package/src/chrome-strip.ts

@@ -6,7 +6,7 @@
  * so an operator always knows where they are and how to navigate back to the
  * hub root. The structural fix to the "where-am-I confusion" called out in
  * `AUDIT-UI-UX.md` §2.5 + §5 row G, with the HTML + CSS shape pinned in
- * `parachute-patterns/patterns/design-system.md` §7.
+ * `docs/contracts/design-system.md` §7.
  *
  * Injection mechanism: buffer-and-replace on the first `<body...>` tag.
  * Responses larger than `MAX_INJECT_SIZE_BYTES` are passed through unchanged
@@ -90,7 +90,7 @@ const BRAND_MARK_SVG = brandMarkSvg(16, "chrome-1");
  * hasn't yet adopted the canonical palette tokens. Once a surface declares
  * `:root { --bg-soft: ...; }` of its own, those win via cascade.
  *
- * Sourced from `parachute-patterns/patterns/design-system.md` §7 verbatim,
+ * Sourced from `docs/contracts/design-system.md` §7 verbatim,
  * with the `:host` token shim added for cross-surface portability.
  */
 const CHROME_STYLE = `

package/src/commands/doctor.ts

@@ -53,6 +53,13 @@ import { decodeJwt } from "jose";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { type ExposeState, readExposeState } from "../expose-state.ts";
 import { HUB_SVC, readHubPort } from "../hub-control.ts";
+import {
+  HIJACK_INCIDENT_REF,
+  type HubInstanceRecord,
+  type LoopbackProbe,
+  probeLoopbackInstance,
+  readHubInstanceFile,
+} from "../hub-instance.ts";
 import {
   HUB_UNIT_DEFAULT_PORT,
   type HubUnitDeps,
@@ -157,6 +164,25 @@ export interface DoctorDeps {
    * readline; tests inject a canned answer.
    */
   readLine?: (prompt: string) => Promise<string>;
+  /**
+   * Loopback-hijack check (hub#737): read THIS hub's on-disk identity
+   * (`hub-instance.json`, written by the running `serve`). Default
+   * {@link readHubInstanceFile}; tests inject a fixture record (or null).
+   */
+  readInstanceRecord?: (configDir: string) => HubInstanceRecord | null;
+  /**
+   * Loopback-hijack check: probe `127.0.0.1:<port>/health` and read its
+   * `instance`. Default {@link probeLoopbackInstance}; tests inject the
+   * matched / mismatched / unreachable outcomes.
+   */
+  probeLoopbackInstance?: (port: number) => Promise<LoopbackProbe>;
+  /**
+   * Loopback-hijack check: count LISTEN sockets on the hub port (a second
+   * listener is the OrbStack-shadow fingerprint). Default shells `lsof`;
+   * returns `undefined` when it can't determine a count (lsof absent / errored)
+   * so the check degrades to the instance comparison alone. Tests inject a count.
+   */
+  countHubListeners?: (port: number) => number | undefined;
 }
 
 export interface DoctorOpts {
@@ -217,6 +243,33 @@ async function defaultProbePublicHealth(origin: string): Promise<boolean> {
   }
 }
 
+/**
+ * Count LISTEN sockets on `port` via `lsof`. A hijack shows TWO (this hub's
+ * wildcard bind + the shadowing process's specific loopback bind). Bounded +
+ * best-effort: returns `undefined` on any failure (lsof absent, non-zero exit,
+ * unparseable) so the check degrades to the instance-comparison signal alone
+ * rather than false-flagging. Counts DISTINCT pids across the LISTEN rows.
+ */
+function defaultCountHubListeners(port: number): number | undefined {
+  try {
+    const proc = Bun.spawnSync(["lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-FpP"], {
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    // lsof exits non-zero when there are zero matches — that's a real "0", not
+    // an error. Only treat a missing binary (spawn failure) as indeterminate.
+    if (proc.exitCode !== 0 && (proc.stdout?.length ?? 0) === 0) return 0;
+    const text = new TextDecoder().decode(proc.stdout ?? new Uint8Array());
+    const pids = new Set<string>();
+    for (const line of text.split("\n")) {
+      if (line.startsWith("p")) pids.add(line.slice(1));
+    }
+    return pids.size;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Both ends of the pipe must be a TTY for an interactive confirm to make sense. */
 function defaultIsInteractive(): boolean {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -243,6 +296,9 @@ interface ResolvedDeps {
   now: () => Date;
   isInteractive: () => boolean;
   readLine: (prompt: string) => Promise<string>;
+  readInstanceRecord: (configDir: string) => HubInstanceRecord | null;
+  probeLoopbackInstance: (port: number) => Promise<LoopbackProbe>;
+  countHubListeners: (port: number) => number | undefined;
 }
 
 function resolveDeps(d: DoctorDeps | undefined): ResolvedDeps {
@@ -257,6 +313,9 @@ function resolveDeps(d: DoctorDeps | undefined): ResolvedDeps {
     now: d?.now ?? (() => new Date()),
     isInteractive: d?.isInteractive ?? defaultIsInteractive,
     readLine: d?.readLine ?? defaultReadLine,
+    readInstanceRecord: d?.readInstanceRecord ?? readHubInstanceFile,
+    probeLoopbackInstance: d?.probeLoopbackInstance ?? probeLoopbackInstance,
+    countHubListeners: d?.countHubListeners ?? defaultCountHubListeners,
   };
 }
 
@@ -337,6 +396,110 @@ async function checkHubReachable(configDir: string, deps: ResolvedDeps): Promise
   };
 }
 
+/**
+ * Loopback-hijack detection (hub#737) — the 2026-07-02 P0's root trigger. This
+ * hub binds `*:<port>` (wildcard); a foreign process that grabs a SPECIFIC
+ * `127.0.0.1:<port>` bind (classically an OrbStack VM auto-forwarding the port)
+ * WINS all loopback traffic, so every module's JWKS/API call silently reaches
+ * the wrong hub. Detection compares THIS hub's on-disk identity nonce
+ * (`hub-instance.json`, written by `serve`) to what a loopback `/health`
+ * actually returns:
+ *   - no instance file → the running hub predates nonce detection, or isn't
+ *     running under `serve` (the Hub check owns "down") → PASS (benign info,
+ *     never a false FAIL per #717).
+ *   - loopback not answering → defer to the Hub check → PASS (info).
+ *   - loopback nonce === ours → loopback reaches THIS hub. A second LISTEN on
+ *     the port (lsof) is a latent shadow → WARN; a single listener → PASS.
+ *   - loopback nonce ≠ ours (or missing) → ACTIVE HIJACK → FAIL with the exact
+ *     lsof/orb remediation + the incident reference. Detect-only (no `--fix`).
+ * Never throws — every read is bounded + degrades to a benign verdict.
+ */
+async function checkLoopbackHijack(configDir: string, deps: ResolvedDeps): Promise<CheckResult> {
+  const port = readHubPort(configDir) ?? HUB_UNIT_DEFAULT_PORT;
+  const title = `No loopback hijack on :${port}`;
+
+  let record: HubInstanceRecord | null = null;
+  try {
+    record = deps.readInstanceRecord(configDir);
+  } catch {
+    record = null;
+  }
+  if (!record) {
+    return {
+      name: "loopback-hijack",
+      title,
+      status: "pass",
+      detail:
+        "no hub-instance.json — the running hub predates loopback-nonce detection or isn't running under `parachute serve` (see the Hub check)",
+    };
+  }
+
+  let probe: LoopbackProbe;
+  try {
+    probe = await deps.probeLoopbackInstance(port);
+  } catch {
+    probe = { reachable: false };
+  }
+  if (!probe.reachable) {
+    return {
+      name: "loopback-hijack",
+      title,
+      status: "pass",
+      detail: `loopback /health on 127.0.0.1:${port} didn't answer — nothing to compare (the Hub check covers a down hub)`,
+    };
+  }
+
+  // Reachable but a DIFFERENT identity answers → active hijack.
+  if (probe.instance !== record.instance) {
+    let listeners: number | undefined;
+    try {
+      listeners = deps.countHubListeners(port);
+    } catch {
+      listeners = undefined;
+    }
+    const who = probe.instance
+      ? `a different hub (instance ${probe.instance})`
+      : "a foreign process (its /health carries no hub instance nonce)";
+    const listenerNote =
+      listeners !== undefined && listeners > 1
+        ? ` lsof shows ${listeners} listeners on the port.`
+        : "";
+    return {
+      name: "loopback-hijack",
+      title,
+      status: "fail",
+      detail: `loopback 127.0.0.1:${port} is answered by ${who}, NOT this hub (instance ${record.instance}) — module JWKS/API calls are reaching the wrong hub.${listenerNote} Incident: ${HIJACK_INCIDENT_REF}`,
+      fix: `lsof -nP -iTCP:${port} -sTCP:LISTEN  # find the shadow; then \`orb list\` and stop any VM auto-forwarding ${port}`,
+    };
+  }
+
+  // Loopback reaches us. A second listener is a latent shadow that could win the
+  // next reboot — WARN so the operator clears it before it flips to a FAIL.
+  let listeners: number | undefined;
+  try {
+    listeners = deps.countHubListeners(port);
+  } catch {
+    listeners = undefined;
+  }
+  if (listeners !== undefined && listeners > 1) {
+    return {
+      name: "loopback-hijack",
+      title,
+      status: "warn",
+      detail: `loopback reaches this hub, but lsof shows ${listeners} listeners on :${port} — a second bind is a latent shadow that could win loopback after a restart`,
+      fix: `lsof -nP -iTCP:${port} -sTCP:LISTEN  # identify + stop the extra listener (e.g. \`orb list\`)`,
+    };
+  }
+  return {
+    name: "loopback-hijack",
+    title,
+    status: "pass",
+    detail: `loopback 127.0.0.1:${port}/health returns this hub's instance nonce${
+      listeners === 1 ? " (single listener)" : ""
+    }`,
+  };
+}
+
 /**
  * Each CONFIGURED module alive via its own loopback `/health` (2xx OR 401).
  * Only modules present in services.json are checked — an absent module is
@@ -1017,7 +1180,8 @@ async function runChecks(
   const hub = await checkHubReachable(configDir, deps);
   const hubHealthy = hub.status === "pass";
 
-  const [modules, bins, exposure] = await Promise.all([
+  const [hijack, modules, bins, exposure] = await Promise.all([
+    checkLoopbackHijack(configDir, deps),
     checkModulesAlive(manifest, hubHealthy, deps),
     checkModuleBins(manifest, deps),
     checkExposure(configDir, deps),
@@ -1032,7 +1196,7 @@ async function runChecks(
   const add = (group: Group, checks: CheckResult[]) => {
     for (const c of checks) grouped.push({ ...c, group });
   };
-  add("Hub", [hub]);
+  add("Hub", [hub, hijack]);
   add("Modules", [...modules, ...bins]);
   add("Configuration", [manifestCheck, portDrift, operator]);
   add("Migration", migration);
@@ -1208,8 +1372,7 @@ async function fixPortDrift(
   const canonicalByName = new Map(drifted.map((d) => [d.name, d.canonical]));
   const next = {
     services: parsed.services.map((row) => {
-      const canonical =
-        typeof row.name === "string" ? canonicalByName.get(row.name) : undefined;
+      const canonical = typeof row.name === "string" ? canonicalByName.get(row.name) : undefined;
       return canonical === undefined ? row : { ...row, port: canonical };
     }),
   };

package/src/commands/install.ts

@@ -955,7 +955,7 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   // first-party we fall back to the vendored manifest when absent; for
   // third-party (npm / local-path) the manifest is the contract — its
   // absence hard-errors here. See
-  // `parachute-patterns/patterns/module-json-extensibility.md`.
+  // `docs/contracts/module-json-extensibility.md`.
   const installDir = resolveInstallDir(target, findGlobalInstall);
   const installedManifest = await readInstalledManifest(target, installDir, {
     readManifest,
@@ -990,7 +990,7 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     if (!installedManifest) {
       log(`✗ ${target.packageName} does not ship .parachute/module.json — not a Parachute module.`);
       log(
-        "  Authors: see parachute-patterns/patterns/module-json-extensibility.md for the contract.",
+        "  Authors: see parachute-hub/docs/contracts/module-json-extensibility.md for the contract.",
       );
       return 1;
     }

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/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;
   };
 }
 
@@ -101,8 +112,8 @@ function formatRow(cells: string[], widths: number[]): string {
 }
 
 /**
- * Canonical user-facing state vocabulary, per [parachute-patterns/patterns/
- * design-system.md §6](../parachute-patterns/patterns/design-system.md)
+ * Canonical user-facing state vocabulary, per [docs/contracts/
+ * design-system.md §6](../../docs/contracts/design-system.md)
  * (workstream F). Replaces the pre-F two-column `PROCESS` (running/stopped)
  * + `HEALTH` (ok/down/http <code>) split with a single rollup column the
  * SPA, well-known doc, and CLI all share.
@@ -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/commands/upgrade.ts

@@ -206,7 +206,8 @@ export interface UpgradeOpts {
    * `@latest` otherwise.
    *
    * Per governance rule 2 (pre-1.0 RC versioning,
-   * `parachute-patterns/patterns/governance.md`), operators on the dev
+   * https://github.com/ParachuteComputer/parachute-workspace/blob/main/docs/process/governance.md),
+   * operators on the dev
    * chain run `@rc`; `@latest` is the explicit-stable channel. The default
    * `parachute upgrade` (pre hub#332) hard-coded `@latest`, which silently
    * downgraded rc operators when `@latest` pointed at a prior stable.
@@ -324,7 +325,8 @@ function resolveUpgradeSupervisor(opts: UpgradeOpts["supervisor"]): {
 
 /**
  * Channel detection from a semver-ish version string. Pre-1.0 governance
- * (parachute-patterns/patterns/governance.md rule 2) ships rc chains as
+ * (https://github.com/ParachuteComputer/parachute-workspace/blob/main/docs/process/governance.md
+ * rule 2) ships rc chains as
  * `<x>.<y>.<z>-rc.<N>` (or sometimes `-rc` with no N). Anything matching that
  * trailing suffix is the rc channel; everything else is the stable channel.
  */

package/src/help.ts

@@ -332,7 +332,7 @@ What it does:
   modules installed.
 
   The STATE column rolls process state + probe result into one of four
-  canonical labels (per parachute-patterns/patterns/design-system.md §6):
+  canonical labels (per parachute-hub/docs/contracts/design-system.md §6):
     active    supervised, running, last probe ok
     pending   supervised, needs operator action (OAuth / config) —
               not reachable from \`parachute status\` today; surfaces in