@openparachute/hub 0.7.5 → 0.7.6-rc.3

package/src/__tests__/setup.test.ts

@@ -119,9 +119,12 @@ describe("isOfferable (fresh-install OFFER, 2026-06-25)", () => {
     expect(isOfferable({ short: "agent", installed: false })).toBe(true);
   });
 
-  test("does NOT offer a deprecated module (notes / runner) on a fresh install", () => {
+  test("does NOT offer a deprecated module (notes) on a fresh install", () => {
     expect(isOfferable({ short: "notes", installed: false })).toBe(false);
-    expect(isOfferable({ short: "runner", installed: false })).toBe(false);
+    // runner is stronger than deprecated now: it left the registries entirely
+    // (2026-07-01), so it never reaches the survey → isOfferable never sees
+    // it. (The bare predicate would say true for an unknown short — the OFFER
+    // gate for runner is `knownServices()` no longer containing it.)
   });
 
   test("never offers an already-installed module regardless of tier", () => {
@@ -137,6 +140,9 @@ describe("setup", () => {
       // Pre-seed every first-party shortname so survey returns all-installed.
       // Distinct canonical ports per service — services-manifest.ts now
       // rejects duplicate ports between distinct services (hub#195).
+      // parachute-runner rides along as a LEGACY row (runner left the
+      // registries 2026-07-01): it must neither block the all-installed exit
+      // nor crash the survey.
       const seeds: Array<{ name: string; port: number }> = [
         { name: "parachute-vault", port: 1940 },
         { name: "parachute-notes", port: 1942 },
@@ -175,12 +181,13 @@ describe("setup", () => {
     }
   });
 
-  test("fresh box: the offered 'Available to install' list excludes deprecated notes/runner (2026-06-25)", async () => {
+  test("fresh box: the offered 'Available to install' list excludes deprecated notes + removed runner", async () => {
     const h = makeHarness();
     try {
       // 'all' picks every OFFERED service. With a clean services.json the survey
-      // sees every known short; the offered filter must drop notes + runner
-      // (deprecated) while keeping vault/scribe/surface/agent. Only vault +
+      // sees every known short; the offered filter must drop notes (deprecated,
+      // 2026-06-25) while runner never even reaches the survey (registry
+      // removal, 2026-07-01) — keeping vault/scribe/surface/agent. Only vault +
       // scribe have pre-install follow-up prompts (vault name, scribe provider);
       // surface + agent have none — so the scripted answers below are complete.
       const availability = scriptedAvailability([
@@ -221,10 +228,57 @@ describe("setup", () => {
   test("an already-installed deprecated module still shows in 'Already installed' + isn't re-offered (back-compat)", async () => {
     const h = makeHarness();
     try {
-      // Legacy operator with runner (deprecated) on disk. It must surface in the
-      // "Already installed" banner (so they know it's there + can manage it via
-      // `parachute <verb> runner`), and must NOT reappear in the fresh-install
-      // OFFER list.
+      // Legacy operator with notes-daemon (deprecated) on disk. It must surface
+      // in the "Already installed" banner (so they know it's there + can manage
+      // it via `parachute <verb> notes`), and must NOT reappear in the
+      // fresh-install OFFER list.
+      upsertService(
+        {
+          name: "parachute-notes",
+          version: "0.3.15",
+          port: 1942,
+          paths: ["/notes"],
+          health: "/notes/health",
+        },
+        h.manifestPath,
+      );
+      const availability = scriptedAvailability([
+        "surface", // pick a still-offered module
+      ]);
+      const code = await setup({
+        manifestPath: h.manifestPath,
+        configDir: h.configDir,
+        log: (l) => h.logs.push(l),
+        availability,
+        installFn: async (short, opts) => {
+          h.calls.push({ short, opts });
+          return 0;
+        },
+      });
+      expect(code).toBe(0);
+      const joined = h.logs.join("\n");
+      // Banner lists notes as already installed…
+      const installedBlock = joined.slice(
+        joined.indexOf("Already installed:"),
+        joined.indexOf("Available to install:"),
+      );
+      expect(installedBlock).toMatch(/\bnotes\b/);
+      // …but notes is NOT in the fresh-install offer.
+      const availableBlock = joined.slice(joined.indexOf("Available to install:"));
+      expect(availableBlock).not.toMatch(/\bnotes\b/);
+      expect(h.calls.map((c) => c.short)).not.toContain("notes");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a LEGACY parachute-runner row doesn't break setup and is never offered (registry removal 2026-07-01)", async () => {
+    const h = makeHarness();
+    try {
+      // runner left the registries entirely — the survey no longer knows the
+      // short, so the row is simply invisible to setup (not in "Already
+      // installed", not in the offer). The load-bearing assertions: setup
+      // still runs to completion and never tries to install runner.
       upsertService(
         {
           name: "parachute-runner",
@@ -250,16 +304,10 @@ describe("setup", () => {
       });
       expect(code).toBe(0);
       const joined = h.logs.join("\n");
-      // Banner lists runner as already installed…
-      const installedBlock = joined.slice(
-        joined.indexOf("Already installed:"),
-        joined.indexOf("Available to install:"),
-      );
-      expect(installedBlock).toMatch(/\brunner\b/);
-      // …but runner is NOT in the fresh-install offer.
       const availableBlock = joined.slice(joined.indexOf("Available to install:"));
       expect(availableBlock).not.toMatch(/\brunner\b/);
       expect(h.calls.map((c) => c.short)).not.toContain("runner");
+      expect(h.calls.map((c) => c.short)).toContain("surface");
     } finally {
       h.cleanup();
     }

package/src/__tests__/stale-module-units.test.ts

@@ -55,7 +55,7 @@ function joined(calls: string[][]): string[] {
 describe("targetModuleShorts() — known module shorts, never hub/cloudflared", () => {
   test("includes the canonical module shorts and excludes hub", () => {
     const shorts = targetModuleShorts();
-    // The canonical knownServices() set: vault / scribe / runner / surface / notes / channel.
+    // The canonical knownServices() set: vault / scribe / surface / notes / agent.
     expect(shorts).toContain("vault");
     expect(shorts).toContain("scribe");
     expect(shorts).toContain("surface");

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-connections.ts

@@ -1797,8 +1797,12 @@ function sessionUser(req: Request, deps: ConnectionsDeps): { userId: string } {
  * the rule found this engine minting ~90-day tokens with no registry row — an
  * unrevocable-by-construction credential (`api-revoke-token` 404s unknown
  * jtis; the revocation list only carries registered jtis).
+ *
+ * Exported so other unregistered-by-policy mint sites (git-notify.ts's
+ * fire-and-forget notify/pull tokens) can statically assert their TTLs stay
+ * under this policy line instead of restating `600` in a comment.
  */
-const REGISTERED_MINT_TTL_THRESHOLD_SECONDS = 10 * 60;
+export const REGISTERED_MINT_TTL_THRESHOLD_SECONDS = 10 * 60;
 
 interface MintSpec {
   scopes: string[];

package/src/admin-module-token.ts

@@ -4,7 +4,7 @@
  *
  * Why this exists (2026-06-09 modular-UI architecture, P3): modules now own
  * their config/admin UIs and declare `configUiUrl` in `module.json` (scribe
- * `/scribe/admin`, runner `/runner/admin`, surface `/surface/admin/`, …). The
+ * `/scribe/admin`, surface `/surface/admin/`, …). The
  * hub frames/links those surfaces consistently (the Modules page "Configure"
  * action). Each module-owned config UI, served behind the hub proxy to a
  * logged-in portal operator, needs an admin-scoped hub Bearer to call its own
@@ -16,7 +16,7 @@
  *
  * Scope + audience: `<short>:admin`, audience = `<short>` (the bare service
  * prefix). Modules validate the JWT's `aud` against their literal short name
- * (`scribe`, `runner`, `surface`, `agent`) — the same shape `inferAudience`
+ * (`scribe`, `surface`, `agent`) — the same shape `inferAudience`
  * stamps for the public OAuth flow, so a hub-minted and an OAuth-minted admin
  * token are indistinguishable to the module. This mirrors the per-request
  * `<short>:admin` proxy token `api-modules-config.ts` used to mint; the

package/src/api-modules-ops.ts

@@ -354,13 +354,13 @@ async function authorize(req: Request, deps: ApiModulesOpsDeps): Promise<Respons
  * reach the same spec the API handlers use without duplicating the
  * curated-table lookup.
  *
- * Two source paths (post-FALLBACK-retirement: vault/scribe/runner in
+ * Two source paths (post-FALLBACK-retirement: vault/scribe in
  * hub#310, channel in boundary D3):
  *
  *   - **FIRST_PARTY_FALLBACKS** (notes): vendored manifest is
  *     authoritative pre-install — the embedded `manifest.startCmd` /
  *     `manifest.paths` / etc. drive the install + spawn flow.
- *   - **KNOWN_MODULES** (vault / scribe / runner / channel / surface): no
+ *   - **KNOWN_MODULES** (vault / scribe / agent / surface): no
  *     vendored manifest.
  *     Pre-install we know only the npm package + manifestName + canonical
  *     port + imperative `extras` (init, postInstallFooter, urlForEntry,
@@ -831,7 +831,7 @@ export async function runInstall(
     });
   }
 
-  // KNOWN_MODULES shorts (vault / scribe / runner / channel / surface):
+  // KNOWN_MODULES shorts (vault / scribe / agent / surface):
   // module.json is the canonical source for startCmd. Re-resolve the spec
   // from `<installDir>/.parachute/module.json` when installDir is stamped so
   // the module is authoritative for its own spawn cmd. Falls back to the

package/src/api-modules.ts

@@ -18,7 +18,7 @@
  * `focus` ("core" | "experimental" | "deprecated") comes from each module's
  * `module.json` when declared, else `focusForShort`'s default map. The SPA
  * groups core first, de-emphasizes experimental, and de-emphasizes
- * `deprecated` (notes-daemon / runner) further — it NEVER hides an installed
+ * `deprecated` (notes-daemon) further — it NEVER hides an installed
  * module (so an existing operator can still manage / uninstall a deprecated
  * one). This is what makes a running, self-registered module (channel) visible
  * + installable; the old `CURATED_MODULES = ["vault","scribe"]` whitelist made
@@ -67,7 +67,7 @@ import {
 } from "./service-spec.ts";
 // `FIRST_PARTY_FALLBACKS` and `KNOWN_MODULES` are both consulted by
 // `lookupModule` below — the former for notes (vendored manifest still
-// required) and the latter for vault/scribe/runner/agent (post-FALLBACK
+// required) and the latter for vault/scribe/agent/surface (post-FALLBACK
 // retirement, hub#310). The local helper hides the split from the rest of
 // this file. `discoverableShorts` enumerates their UNION — the
 // self-registration-driven discovery surface that replaced the old
@@ -83,7 +83,7 @@ import type { ModuleStartError, ModuleState, Supervisor } from "./supervisor.ts"
 /**
  * Resolve a known module to the display + install bootstrap data the admin SPA
  * renders. Reads from FIRST_PARTY_FALLBACKS (notes) first,
- * KNOWN_MODULES (vault / scribe / runner / channel / surface) second.
+ * KNOWN_MODULES (vault / scribe / agent / surface) second.
  *
  * Returns `undefined` if the short is in neither table — a genuinely
  * third-party module discovered only via services.json / the supervisor. The
@@ -249,10 +249,10 @@ interface ModuleWireShape {
    * Discovery tier (2026-06-09 modular-UI architecture; `deprecated` added
    * 2026-06-25). `core` modules render in the headline group; `experimental`
    * modules render in a de-emphasized "Experimental" group; `deprecated`
-   * modules (notes-daemon / runner) render in a further-de-emphasized
+   * modules (notes-daemon) render in a further-de-emphasized
    * "Deprecated" group — never hidden when installed. Resolved from the
    * module's `module.json` `focus` when declared, else `focusForShort`'s
-   * default map (vault/scribe/hub/surface → core, notes/runner → deprecated,
+   * default map (vault/scribe/hub/surface → core, notes → deprecated,
    * others → experimental).
    */
   focus: ModuleFocus;
@@ -269,7 +269,7 @@ interface ModuleWireShape {
    * The fresh-install OFFER (2026-06-25): whether the hub presents this module
    * in the "available to install fresh" set. `available && focus !==
    * "deprecated"`. The SPA's "Install a module" catalog filters on this so
-   * notes-daemon / runner aren't pushed on a fresh box; an already-installed
+   * notes-daemon isn't pushed on a fresh box; an already-installed
    * deprecated module still surfaces (in the Installed section) for management.
    */
   available_to_install: boolean;
@@ -315,8 +315,8 @@ interface ModuleWireShape {
   install_dir: string | null;
   /**
    * Hierarchical sub-units beneath this module (hub#313). Empty when the
-   * module's services.json row doesn't declare `uis` (vault, scribe, notes,
-   * runner today). Used by parachute-app to surface each hosted UI as its
+   * module's services.json row doesn't declare `uis` (vault, scribe, notes
+   * today). Used by parachute-app to surface each hosted UI as its
    * own discoverable sub-row under the App module. Per parachute-app
    * design doc §12.
    */
@@ -336,8 +336,8 @@ interface ModuleWireShape {
    *      the operator UI (App today).
    *   3. Null when the module hasn't declared either field — the SPA
    *      renders a disabled "Open" tooltip (pointing at Configure when
-   *      `config_ui_url` is set — runner's shape today — or "module
-   *      hasn't shipped an admin UI yet" otherwise).
+   *      `config_ui_url` is set — or "module hasn't shipped an admin UI
+   *      yet" otherwise).
    *
    * Always an absolute path on the hub origin (leading `/`) — the SPA
    * navigates same-origin, no need to worry about cross-origin
@@ -660,7 +660,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   // module's manifest-declared `focus` (when installed + declared) wins; else
   // the `focusForShort` default map. Sort: `core` group first (with the
   // CURATED_MODULES recommended-install order floated to the top of that
-  // group), then `experimental`, then `deprecated` (notes / runner) last — the
+  // group), then `experimental`, then `deprecated` (notes) last — the
   // SPA renders the groups; `focus` never hides an installed module.
   const recommendedOrder = new Map<string, number>(
     (CURATED_MODULES as readonly string[]).map((s, i) => [s, i]),
@@ -684,7 +684,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       // package) is not hub-installable → false.
       available: m !== undefined,
       // Fresh-install OFFER (2026-06-25): installable AND not deprecated. A
-      // deprecated short (notes / runner) stays `available` (re-installable
+      // deprecated short (notes) stays `available` (re-installable
       // for back-compat) but is dropped from the offer set so the SPA's
       // "Install a module" catalog doesn't push it on a fresh box.
       available_to_install: m !== undefined && focus !== "deprecated",
@@ -867,7 +867,7 @@ let warnedLegacyVaultAdminCandidate = false;
  *   - `undefined` candidate → `undefined` (the module didn't declare it).
  *   - Absolute http(s) URL → returned verbatim (off-origin escape hatch).
  *   - Leading-`/` path → ORIGIN-ABSOLUTE, returned verbatim. Single-instance
- *     modules (surface, scribe, runner, agent) declare their full hub-origin
+ *     modules (surface, scribe, agent) declare their full hub-origin
  *     path this way (`/surface/admin/`, `/scribe/admin`, `/agent/admin`);
  *     vault's daemon-level surface is `/vault/admin/`.
  *   - Relative path (no leading slash) → MOUNT-JOINED: the per-instance form

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 };
     }),
   };