@openparachute/hub 0.6.4-rc.6 → 0.6.4-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.4-rc.6",
+  "version": "0.6.4-rc.7",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/install.test.ts

@@ -40,6 +40,9 @@ describe("install", () => {
       const calls: string[][] = [];
       const logs: string[] = [];
       const code = await install("vault", {
+        // --interactive: opt back into vault's full `init` (#579). The light
+        // default skips it; this test exercises the interactive path.
+        interactive: true,
         runner: async (cmd) => {
           calls.push([...cmd]);
           return 0;
@@ -67,6 +70,8 @@ describe("install", () => {
     try {
       const logs: string[] = [];
       const code = await install("vault", {
+        // --interactive: this test asserts init wrote the authoritative entry.
+        interactive: true,
         runner: async (cmd) => {
           if (cmd[0] === "parachute-vault") {
             upsertService(
@@ -133,6 +138,8 @@ describe("install", () => {
       const calls: string[][] = [];
       const logs: string[] = [];
       const code = await install("vault", {
+        // --interactive: this test asserts init still ran after the bun quirk.
+        interactive: true,
         runner: async (cmd) => {
           calls.push([...cmd]);
           // `bun add -g` exits 1; `parachute-vault init` succeeds.
@@ -796,12 +803,14 @@ describe("install", () => {
     }
   });
 
-  test("linked vault still runs init and defers to init's manifest write", async () => {
+  test("linked vault still runs init and defers to init's manifest write (--interactive)", async () => {
     const { path, cleanup } = makeTempPath();
     try {
       const calls: string[][] = [];
       const logs: string[] = [];
       const code = await install("vault", {
+        // --interactive: this test asserts vault's own init wrote the entry.
+        interactive: true,
         runner: async (cmd) => {
           calls.push([...cmd]);
           if (cmd[0] === "parachute-vault") {
@@ -1722,6 +1731,330 @@ describe("install", () => {
   });
 });
 
+describe("#579 / #580 item 1 — light manual install + guidance", () => {
+  test("default vault install skips the interactive init (no parachute-vault init runs)", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install("vault", {
+        // No `interactive` flag → the light default path.
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      // bun add ran; vault's interactive init did NOT.
+      expect(calls).toEqual([["bun", "add", "-g", "@openparachute/vault"]]);
+      expect(calls).not.toContainEqual(["parachute-vault", "init"]);
+      // The skip is announced + points at the admin UI / --interactive.
+      expect(logs.join("\n")).toMatch(/skipping parachute-vault init/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("default vault install still starts the module under the supervisor", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const startCalls: string[] = [];
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async (short) => {
+          startCalls.push(short);
+          return 0;
+        },
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      // Light ≠ no-start: the supervisor owns the lifecycle; vault is started.
+      expect(startCalls).toEqual(["vault"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("guidance block prints the admin URL + extras on a supervised box (loopback)", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        // Deterministic supervised-box context: hub unit installed, not exposed.
+        guidanceCtx: { hubUnitInstalled: true, exposeState: undefined, hubPort: 1939 },
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toMatch(/Manage \+ create vaults in the admin UI/);
+      expect(joined).toMatch(/http:\/\/127\.0\.0\.1:1939\/admin\//);
+      expect(joined).toMatch(/parachute-vault mcp-install/);
+      expect(joined).toMatch(/--interactive/);
+      // It does NOT mint a token or wire MCP — just points there.
+      expect(joined).toMatch(/Mint an API token.*admin UI/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("guidance uses the exposed public FQDN when the hub is exposed", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        guidanceCtx: {
+          hubUnitInstalled: true,
+          exposeState: {
+            version: 1,
+            layer: "public",
+            mode: "path",
+            canonicalFqdn: "friends.parachute.computer",
+            port: 1939,
+            funnel: false,
+            entries: [],
+          },
+          hubPort: 1939,
+        },
+      });
+      const joined = logs.join("\n");
+      expect(joined).toMatch(/https:\/\/friends\.parachute\.computer\/admin\//);
+      expect(joined).not.toMatch(/127\.0\.0\.1/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no guidance block on a non-supervised box (no hub unit)", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        guidanceCtx: { hubUnitInstalled: false, exposeState: undefined, hubPort: 1939 },
+      });
+      const joined = logs.join("\n");
+      expect(joined).not.toMatch(/Manage \+ create vaults in the admin UI/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("--interactive runs vault init and suppresses the guidance block", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install("vault", {
+        interactive: true,
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        // Even on a supervised box, --interactive means the service's own
+        // init owns the next-steps surface — no light guidance block.
+        guidanceCtx: { hubUnitInstalled: true, exposeState: undefined, hubPort: 1939 },
+      });
+      expect(code).toBe(0);
+      expect(calls).toContainEqual(["parachute-vault", "init"]);
+      expect(logs.join("\n")).not.toMatch(/Manage \+ create vaults in the admin UI/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("scribe (no interactive init) is unaffected — no skip log, no vault guidance", async () => {
+    const { path, cleanup } = makeTempPath();
+    const configDir = join(path, "..");
+    try {
+      const logs: string[] = [];
+      const code = await install("scribe", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        scribeAvailability: { kind: "not-tty" },
+        log: (l) => logs.push(l),
+        guidanceCtx: { hubUnitInstalled: true, exposeState: undefined, hubPort: 1939 },
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).not.toMatch(/skipping/);
+      expect(joined).not.toMatch(/Manage \+ create vaults in the admin UI/);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("#580 item 3 — install-time stale-unit sweep", () => {
+  test("sweeps stale per-module units before starting on a supervised box", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      let sweepCalls = 0;
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        guidanceCtx: { hubUnitInstalled: true, exposeState: undefined, hubPort: 1939 },
+        disableStaleModuleUnits: () => {
+          sweepCalls += 1;
+          return {
+            actions: [
+              {
+                short: "vault",
+                kind: "launchd",
+                unit: "computer.parachute.vault",
+                result: "disabled",
+                messages: ["  ✓ Disabled stale computer.parachute.vault"],
+              },
+            ],
+          };
+        },
+      });
+      expect(code).toBe(0);
+      expect(sweepCalls).toBe(1);
+      expect(logs.join("\n")).toMatch(
+        /Swept 1 stale per-module autostart unit\(s\).*computer\.parachute\.vault/,
+      );
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("does NOT sweep on a non-supervised box (no hub unit)", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      let sweepCalls = 0;
+      await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: () => {},
+        guidanceCtx: { hubUnitInstalled: false, exposeState: undefined, hubPort: 1939 },
+        disableStaleModuleUnits: () => {
+          sweepCalls += 1;
+          return { actions: [] };
+        },
+      });
+      // No supervised hub → the per-module unit is the legitimate lifecycle;
+      // the sweep must not run.
+      expect(sweepCalls).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("does NOT sweep under --no-start (caller owns the process model)", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      let sweepCalls = 0;
+      await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        noStart: true,
+        log: () => {},
+        guidanceCtx: { hubUnitInstalled: true, exposeState: undefined, hubPort: 1939 },
+        disableStaleModuleUnits: () => {
+          sweepCalls += 1;
+          return { actions: [] };
+        },
+      });
+      expect(sweepCalls).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("does NOT sweep under --no-create (wizard defers the start; N2)", async () => {
+    // Parallel to the --no-start guard above. `noCreate` (the wizard's
+    // install path) also suppresses the start — and the sweep touches real
+    // launchctl/systemctl on a live box, so it must NOT fire when we're not
+    // about to start the module. A silent regression here would have the
+    // wizard disabling operator units mid-init.
+    const { path, cleanup } = makeTempPath();
+    try {
+      let sweepCalls = 0;
+      await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        noCreate: true,
+        log: () => {},
+        guidanceCtx: { hubUnitInstalled: true, exposeState: undefined, hubPort: 1939 },
+        disableStaleModuleUnits: () => {
+          sweepCalls += 1;
+          return { actions: [] };
+        },
+      });
+      expect(sweepCalls).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a clean no-op sweep (nothing stale) logs nothing extra", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (l) => logs.push(l),
+        guidanceCtx: { hubUnitInstalled: true, exposeState: undefined, hubPort: 1939 },
+        disableStaleModuleUnits: () => ({ actions: [] }),
+      });
+      expect(logs.join("\n")).not.toMatch(/Swept .* stale per-module/);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 describe("hub#573 — install auto-start converges on supervised detection", () => {
   test("the default start opts opt into real supervisor detection + the migrate offer", () => {
     const log = () => {};

package/src/__tests__/supervisor.test.ts

@@ -178,6 +178,203 @@ describe("Supervisor.start + status transitions", () => {
   });
 });
 
+describe("Supervisor port-squatter detection (#580 item 4)", () => {
+  test("foreign pid on the module port → port_squatter error, no spawn", async () => {
+    const spawner = makeQueueSpawner();
+    // Note: NOTHING enqueued — if `start` tried to spawn, the spawner throws.
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      // A rogue pid 1921 holds :1940; it is NOT one of our children.
+      pidOnPort: (port) => (port === 1940 ? 1921 : undefined),
+      ownerOfPid: (pid) => (pid === 1921 ? "bun /x/vault/src/server.ts" : undefined),
+    });
+
+    const state = await sup.start({
+      short: "vault",
+      cmd: ["bun", "vault.ts"],
+      env: { PORT: "1940" },
+    });
+
+    // No spawn attempted (spawner.calls empty), module is `crashed` with the
+    // structured, actionable squatter error.
+    expect(spawner.calls).toHaveLength(0);
+    expect(state.status).toBe("crashed");
+    expect(state.pid).toBeUndefined();
+    expect(state.startError?.error_type).toBe("port_squatter");
+    expect(state.startError?.error_description).toContain("port 1940 is held by pid 1921");
+    expect(state.startError?.error_description).toContain("bun /x/vault/src/server.ts");
+    expect(state.startError?.error_description).toContain("kill 1921 && parachute start vault");
+  });
+
+  test("squatter message omits cmdline when ownerOfPid can't read it", async () => {
+    const spawner = makeQueueSpawner();
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      pidOnPort: () => 4242,
+      ownerOfPid: () => undefined,
+    });
+
+    const state = await sup.start({
+      short: "vault",
+      cmd: ["bun", "vault.ts"],
+      env: { PORT: "1940" },
+    });
+    expect(state.startError?.error_type).toBe("port_squatter");
+    expect(state.startError?.error_description).toContain("port 1940 is held by pid 4242");
+    expect(state.startError?.error_description).toContain("kill 4242 && parachute start vault");
+    // No parenthetical cmdline.
+    expect(state.startError?.error_description).not.toContain("(");
+  });
+
+  test("free port → no squatter error, module spawns normally", async () => {
+    const proc = makeFakeProc(500);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(proc);
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      pidOnPort: () => undefined, // port free / detection unavailable
+    });
+
+    const state = await sup.start({
+      short: "vault",
+      cmd: ["bun", "vault.ts"],
+      env: { PORT: "1940" },
+    });
+    expect(spawner.calls).toHaveLength(1);
+    expect(state.status).toBe("running");
+    expect(state.startError).toBeUndefined();
+
+    proc.closeStreams();
+    sup.stop("vault");
+    proc.resolveExit(0);
+  });
+
+  test("port held by one of OUR OWN children is not a squatter", async () => {
+    // vault is up on pid 700 holding :1940; starting a sibling (scribe) that
+    // somehow reports the same holder pid must NOT be flagged — the holder is
+    // a supervised child, not a foreign rogue.
+    const vaultProc = makeFakeProc(700);
+    const scribeProc = makeFakeProc(701);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(vaultProc);
+    spawner.enqueue(scribeProc);
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      // vault's port (1940) is free so vault spawns (pid 700). scribe's port
+      // (1943) then reports vault's pid 700 as the holder — a supervised child,
+      // NOT a foreign rogue, so scribe must still spawn.
+      pidOnPort: (port) => (port === 1943 ? 700 : undefined),
+    });
+
+    await sup.start({ short: "vault", cmd: ["bun", "vault.ts"], env: { PORT: "1940" } });
+    const scribe = await sup.start({
+      short: "scribe",
+      cmd: ["bun", "scribe.ts"],
+      env: { PORT: "1943" },
+    });
+    // scribe spawned (no false-positive squatter); both children spawned.
+    expect(spawner.calls).toHaveLength(2);
+    expect(scribe.status).toBe("running");
+    expect(scribe.startError).toBeUndefined();
+
+    vaultProc.closeStreams();
+    scribeProc.closeStreams();
+    sup.stop("vault");
+    sup.stop("scribe");
+    vaultProc.resolveExit(0);
+    scribeProc.resolveExit(0);
+  });
+
+  test("a CRASHED child's stale pid does NOT vouch for a port holder (N1 liveness)", async () => {
+    // vault spawns (pid 800), then crashes for good (maxRestarts: 1). Its entry
+    // keeps `proc.pid === 800` (never cleared on exit) but status is `crashed`.
+    // A fresh `start` where pid 800 now holds :1940 must be flagged as a
+    // SQUATTER — the stale pid of a dead child must not excuse the holder.
+    const first = makeFakeProc(800);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first);
+    let portHeld = false;
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      maxRestarts: 1,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      // Free before the crash; pid 800 "holds" :1940 after we flip portHeld.
+      pidOnPort: (port) => (portHeld && port === 1940 ? 800 : undefined),
+      ownerOfPid: () => "bun /x/vault/src/server.ts",
+    });
+
+    await sup.start({ short: "vault", cmd: ["bun", "vault.ts"], env: { PORT: "1940" } });
+    // Crash past the budget → status `crashed`, entry.proc.pid still 800.
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+    expect(sup.get("vault")?.status).toBe("crashed");
+
+    // Now pid 800 holds the port. A re-start must NOT treat 800 as "ours".
+    portHeld = true;
+    const restarted = await sup.start({
+      short: "vault",
+      cmd: ["bun", "vault.ts"],
+      env: { PORT: "1940" },
+    });
+    expect(restarted.status).toBe("crashed");
+    expect(restarted.startError?.error_type).toBe("port_squatter");
+    expect(restarted.startError?.error_description).toContain("port 1940 is held by pid 800");
+    // No second spawn — the squatter check aborted before re-spawning.
+    expect(spawner.calls).toHaveLength(1);
+  });
+
+  test("no declared PORT → squatter check skipped (request without env.PORT)", async () => {
+    const proc = makeFakeProc(900);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(proc);
+    let probed = false;
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      pidOnPort: () => {
+        probed = true;
+        return 1;
+      },
+    });
+
+    const state = await sup.start({ short: "vault", cmd: ["bun", "vault.ts"] });
+    // No PORT in the request → we never probe a port, and the module spawns.
+    expect(probed).toBe(false);
+    expect(state.status).toBe("running");
+
+    proc.closeStreams();
+    sup.stop("vault");
+    proc.resolveExit(0);
+  });
+
+  test("stub-spawner path defaults to no squatter (existing fake-proc tests unaffected)", async () => {
+    const proc = makeFakeProc(123);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(proc);
+    // No pidOnPort injected → on the stub-spawner (test) path it defaults to
+    // "no squatter", so a request carrying a PORT still spawns.
+    const sup = new Supervisor({ spawnFn: spawner.spawn, killFn: noopKill });
+    const state = await sup.start({
+      short: "vault",
+      cmd: ["bun", "vault.ts"],
+      env: { PORT: "1940" },
+    });
+    expect(spawner.calls).toHaveLength(1);
+    expect(state.status).toBe("running");
+
+    proc.closeStreams();
+    sup.stop("vault");
+    proc.resolveExit(0);
+  });
+});
+
 describe("Supervisor restart-on-crash", () => {
   test("restarts a crashed module within the budget", async () => {
     const first = makeFakeProc(101);

package/src/cli.ts

@@ -449,11 +449,14 @@ async function main(argv: string[]): Promise<number> {
         return 1;
       }
       const noStart = keyExtract.rest.includes("--no-start");
-      const installArgs = keyExtract.rest.filter((a) => a !== "--no-start");
+      const interactive = keyExtract.rest.includes("--interactive");
+      const installArgs = keyExtract.rest.filter(
+        (a) => a !== "--no-start" && a !== "--interactive",
+      );
       const service = installArgs[0];
       if (!service) {
         console.error(
-          "usage: parachute install <service|all> [--channel rc|latest] [--tag <name>] [--no-start]",
+          "usage: parachute install <service|all> [--channel rc|latest] [--tag <name>] [--no-start] [--interactive]",
         );
         console.error(
           "       parachute install scribe [--scribe-provider <name>] [--scribe-key <key>]",
@@ -467,6 +470,7 @@ async function main(argv: string[]): Promise<number> {
         installOpts.channel = channelExtract.value;
       }
       if (noStart) installOpts.noStart = true;
+      if (interactive) installOpts.interactive = true;
       if (providerExtract.value) installOpts.scribeProvider = providerExtract.value;
       if (keyExtract.value) installOpts.scribeKey = keyExtract.value;
       const mod = await loadCommand("install", () => import("./commands/install.ts"));

package/src/commands/install.ts

@@ -4,6 +4,9 @@ import { dirname, join } from "node:path";
 import { autoWireScribeAuth } from "../auto-wire.ts";
 import { bunGlobalPrefixes, isLinked as defaultIsLinkedShared } from "../bun-link.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { type ExposeState, readExposeState } from "../expose-state.ts";
+import { HUB_DEFAULT_PORT, readHubPort } from "../hub-control.ts";
+import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
 import {
   type ModuleManifest,
   ModuleManifestError,
@@ -26,6 +29,11 @@ import {
   synthesizeManifestForKnownModule,
 } from "../service-spec.ts";
 import { findService, readManifest, upsertService } from "../services-manifest.ts";
+import {
+  type DisableStaleModuleUnitsOpts,
+  type DisableStaleModuleUnitsResult,
+  disableStaleModuleUnits as defaultDisableStaleModuleUnits,
+} from "../stale-module-units.ts";
 import { WELL_KNOWN_PATH } from "../well-known.ts";
 import { type LifecycleOpts, start as lifecycleStart } from "./lifecycle.ts";
 import { migrateNotice } from "./migrate.ts";
@@ -215,6 +223,60 @@ export interface InstallOpts {
    * leave it false so today's behavior is unchanged.
    */
   noCreate?: boolean;
+  /**
+   * `parachute install vault --interactive` (#579 / #580 item 1): opt back into
+   * the FULL interactive module setup — the service's own `spec.init` (vault's
+   * vault-name prompt, "install as MCP in Claude Code?", "mint an API token?")
+   * and, for vault, its self-registered standalone daemon.
+   *
+   * Default: false. The manual `parachute install <svc>` path is now LIGHT
+   * (matching `parachute init`'s Step 2.5): install the package, seed/register
+   * services.json, start under the supervisor, and print a short guidance block
+   * pointing at the admin UI + the optional extras (`parachute-vault
+   * mcp-install`, token minting in the UI). No interactive interview, no
+   * vault-side daemon registration that would race the supervisor for :1940.
+   *
+   * The old "drag me through the full init" behavior is opt-in via this flag.
+   * When `true` AND the spec ships an `init` command, install runs `spec.init`
+   * as it did pre-#579. When `false` (the default) for a module whose `init`
+   * would otherwise run an interview, install SKIPS `spec.init` (the
+   * `noCreate`-equivalent quiet path) and emits the guidance block instead.
+   *
+   * Orthogonal to `noCreate` (which `parachute init` uses to ALSO skip the
+   * post-install start). The light manual path still starts the module under
+   * the supervisor; only the interactive interview is suppressed.
+   */
+  interactive?: boolean;
+  /**
+   * Test seam for the supervised-hub probe + admin-URL resolution that drive
+   * the light-install guidance block. Production reads the real expose-state /
+   * hub-port / hub-unit deps; tests inject deterministic values so the guidance
+   * assertions don't depend on the operator's live box.
+   */
+  guidanceCtx?: {
+    /** Is a hub unit installed (→ supervised box)? Defaults to the real probe. */
+    hubUnitInstalled?: boolean;
+    /** Hub-unit deps for the real `isHubUnitInstalled` probe. */
+    hubUnitDeps?: HubUnitDeps;
+    /** Live expose state (→ public admin URL). Defaults to `readExposeState()`. */
+    exposeState?: ExposeState | undefined;
+    /** Hub loopback port for the admin URL fallback. Defaults to `readHubPort()`. */
+    hubPort?: number | undefined;
+  };
+  /**
+   * Test seam for the install-time stale-unit sweep (#580 item 3). Production
+   * wires `disableStaleModuleUnits` (the #522 migrate/teardown sweep, reused
+   * verbatim — known-module shorts only, hub + cloudflared skipped, idempotent,
+   * non-fatal). Tests inject a fake so no real launchctl/systemctl runs and the
+   * sweep's invocation (and logged actions) can be asserted.
+   *
+   * The sweep fires only when a supervised hub is present (the same
+   * `guidanceCtx.hubUnitInstalled` discriminant) and the module is being
+   * started — a leftover standalone `parachute-<short>` unit (KeepAlive /
+   * RunAtLoad) would otherwise keep an unsupervised module bound to the port,
+   * crash-looping the supervisor's own child (the #580 field signature).
+   */
+  disableStaleModuleUnits?: (opts?: DisableStaleModuleUnitsOpts) => DisableStaleModuleUnitsResult;
   /**
    * `parachute install scribe` only: pre-pick the transcription provider so
    * the prompt doesn't fire. Validated against scribe's known providers — an
@@ -586,6 +648,78 @@ export function defaultStartLifecycleOpts(ctx: {
   };
 }
 
+/**
+ * Read the expose-state, swallowing a malformed-file error to undefined so the
+ * guidance block degrades to the loopback admin URL instead of throwing mid-
+ * install. Mirrors init's tolerant read of the same file.
+ */
+function safeReadExposeState(): ExposeState | undefined {
+  try {
+    return readExposeState();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the canonical admin URL the light-install guidance points at — the
+ * SAME resolution `parachute init` uses (`init.ts:resolveAdminUrl`): the live
+ * expose-state public FQDN when the hub is exposed, otherwise the loopback
+ * `http://127.0.0.1:<port>/admin/`. Kept as a thin local copy (rather than
+ * importing init.ts) so the install command doesn't pull in the wizard module
+ * graph; the shape is asserted against init's in tests.
+ */
+function resolveGuidanceAdminUrl(
+  exposeState: ExposeState | undefined,
+  hubPort: number | undefined,
+): string {
+  if (exposeState?.canonicalFqdn) {
+    return `https://${exposeState.canonicalFqdn}/admin/`;
+  }
+  return `http://127.0.0.1:${hubPort ?? HUB_DEFAULT_PORT}/admin/`;
+}
+
+/**
+ * The post-install guidance block for the LIGHT manual install path (#579).
+ *
+ * Replaces the old interactive interview ("name your vault / install MCP / mint
+ * a token") with a short pointer to where the operator manages + creates vaults
+ * (the admin UI) plus one-liners for the optional extras they used to be dragged
+ * through up front. Aaron's framing: "I just wanna install vault and then I'm
+ * managing it through the UI" — the install confirms the module is up and tells
+ * them where to go next, no token minted, no MCP wired, until they ask.
+ *
+ * Returns an empty array for modules that don't carry the interactive-init
+ * footprint (so the generic `postInstallFooter` stays the surface for those).
+ *
+ * VAULT-ONLY for now, intentionally (N4). Vault is the only SERVICE_SPECS module
+ * that ships an interactive `spec.init` today, so it's the only one whose light
+ * path drops an interview that needs replacing with guidance. When a FUTURE
+ * module ships its own `spec.init` (and thus takes the light-path skip), add its
+ * guidance arm HERE — or, if the per-module copy starts to diverge meaningfully,
+ * lift the guidance text onto the ServiceSpec shape (e.g. a
+ * `lightInstallGuidance?: (adminUrl) => string[]` extra) so each module owns its
+ * own next-steps block instead of this central switch. The empty-array fallback
+ * keeps every other module silent here regardless.
+ */
+export function buildLightInstallGuidance(short: string, adminUrl: string): string[] {
+  if (short === "vault") {
+    return [
+      "",
+      "Vault is installed and running under the hub supervisor.",
+      "Manage + create vaults in the admin UI:",
+      `  ${adminUrl}`,
+      "",
+      "Optional, when you want them (not needed to start):",
+      "  • Connect a vault to Claude Code:  parachute-vault mcp-install",
+      "  • Mint an API token for other MCP clients: do it from the admin UI (Tokens).",
+      "",
+      "Run the full interactive setup instead with: parachute install vault --interactive",
+    ];
+  }
+  return [];
+}
+
 export async function install(input: string, opts: InstallOpts = {}): Promise<number> {
   const runner = opts.runner ?? defaultRunner;
   const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
@@ -766,7 +900,35 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
       ? spec.manifestName
       : manifest.name;
 
-  if (spec.init && !opts.noCreate) {
+  // Whether to run the module's interactive `spec.init` (#579 / #580 item 1).
+  //
+  // The manual `parachute install <svc>` path is now LIGHT by default: we do
+  // NOT drag the operator through `spec.init`'s interview (for vault: vault-name
+  // prompt, "install as MCP?", "mint a token?", and a self-registered standalone
+  // daemon that would race the supervisor for :1940). The operator installs the
+  // module and manages it from the admin UI. `spec.init` runs ONLY when the
+  // caller explicitly opts back in with `--interactive` (and isn't in the
+  // `noCreate` quiet path the wizard uses). Modules without a `spec.init` are
+  // unaffected — there's no interview to suppress.
+  const runInteractiveInit = spec.init !== undefined && opts.interactive === true && !opts.noCreate;
+  if (runInteractiveInit && spec.init) {
+    // Reviewer surprise 2 / #580: the interactive path runs the module's OWN
+    // init, which (for vault today) registers a standalone platform daemon
+    // (launchd KeepAlive / systemd Restart=always). On a SUPERVISED hub that
+    // daemon races the supervisor for the module's port — the exact #580
+    // EADDRINUSE-crash-loop condition the light path avoids by not running init.
+    // Warn so an operator who reaches for --interactive on a supervised box
+    // knows to pass the daemon-off flag (or prefer the light default).
+    const supervisedForWarn =
+      opts.guidanceCtx?.hubUnitInstalled ??
+      (opts.guidanceCtx !== undefined || manifestPath === SERVICES_MANIFEST_PATH
+        ? isHubUnitInstalled(opts.guidanceCtx?.hubUnitDeps ?? defaultHubUnitDeps)
+        : false);
+    if (supervisedForWarn) {
+      log(
+        `⚠ --interactive runs ${short}'s own setup, which may register a standalone daemon. On a supervised hub that daemon races the supervisor for ${short}'s port (#580). Prefer the light default, or pass --no-autostart through to ${short}'s init.`,
+      );
+    }
     // Forward --vault-name from the InstallOpts when set so `parachute setup`
     // (and any future programmatic caller) can pre-answer the name prompt.
     const initCmd =
@@ -781,6 +943,15 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     }
   } else if (spec.init && opts.noCreate) {
     log(`(skipping ${spec.init.join(" ")} — --no-create: module installed, no instance created)`);
+  } else if (spec.init) {
+    // Light path: the module ships an interactive init but the operator didn't
+    // ask for it. Skip the interview; the guidance block at the end of install
+    // tells them where to manage + create instances. The supervisor (started
+    // below) owns the lifecycle, so vault's own daemon registration is
+    // deliberately NOT triggered here — that's the :1940 race #580 fixed.
+    log(
+      `(skipping ${spec.init.join(" ")} — manage ${short} from the admin UI; re-run with --interactive for the full setup)`,
+    );
   }
 
   // Hub-as-port-authority (#53): pick the service's port now and reflect it
@@ -903,6 +1074,40 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   const notice = migrateNotice(configDir, now());
   if (notice) log(notice);
 
+  // Install-time stale-unit sweep (#580 item 3 / #522 part 2). Before we start
+  // the module under the supervisor, disable any leftover STANDALONE per-module
+  // autostart unit (a pre-supervisor `parachute-<short>.service` with
+  // Restart=always, or a `computer.parachute.<short>` LaunchAgent with
+  // KeepAlive). Such a unit keeps RESPAWNING an unsupervised module that binds
+  // the module's port; the supervised child then EADDRINUSE-crash-loops and
+  // lands `crashed` — the recurring field signature in #580 / #522. Reuses the
+  // exact #522 migrate/teardown sweep (`disableStaleModuleUnits`): known-module
+  // shorts only, hub + cloudflared explicitly skipped, idempotent (already-
+  // disabled/absent = silent no-op), non-fatal (a failed disable warns +
+  // continues). Gated on a supervised hub being present — on a non-supervised
+  // box the per-module unit IS the legitimate lifecycle and we must not touch
+  // it. Only runs on the start path (skipped under --no-start / --no-create).
+  const willStart = !opts.noStart && !opts.noCreate;
+  if (willStart) {
+    const gctx = opts.guidanceCtx;
+    const sweepAllowed =
+      opts.disableStaleModuleUnits !== undefined || manifestPath === SERVICES_MANIFEST_PATH;
+    const supervisedForSweep =
+      gctx?.hubUnitInstalled ?? isHubUnitInstalled(gctx?.hubUnitDeps ?? defaultHubUnitDeps);
+    if (sweepAllowed && supervisedForSweep) {
+      const sweep = opts.disableStaleModuleUnits ?? defaultDisableStaleModuleUnits;
+      const result = sweep({ log: (l) => log(l) });
+      const disabled = result.actions.filter((a) => a.result === "disabled");
+      if (disabled.length > 0) {
+        log(
+          `Swept ${disabled.length} stale per-module autostart unit(s) so the supervisor owns the port(s): ${disabled
+            .map((a) => a.unit)
+            .join(", ")}.`,
+        );
+      }
+    }
+  }
+
   // Auto-start: vault and notes' inits historically left a daemon running, but
   // scribe (and any service without a daemon-launching init) didn't — so
   // launch-day `install scribe` ended with a silent install and the user
@@ -932,6 +1137,44 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     for (const line of footer) log(line);
   }
 
+  // Light-install guidance block (#579 / #580 item 1). When we suppressed the
+  // module's interactive init (light path: it ships an init, the operator
+  // didn't pass --interactive, and this isn't the wizard's noCreate path),
+  // replace the absent interview with a short pointer to the admin UI + the
+  // optional extras. Skipped for --interactive (the service's own footer
+  // covers it) and for noCreate (the wizard prints its own admin URL).
+  //
+  // INFORMATIONAL, independent of the start path (N3): this block is *guidance*,
+  // not an action, so it deliberately does NOT gate on `willStart` /
+  // `!opts.noStart` the way the stale-unit sweep above does. Even under
+  // `--no-start` (CI / piped installs) the operator still benefits from "here's
+  // where to manage it once it's up" — the admin URL + extras are equally true
+  // whether or not THIS invocation started the daemon.
+  //
+  // The supervised-hub probe + admin-URL resolution touch real on-disk state
+  // (the hub plist / expose-state / hub-port file). Gate the production probe
+  // on `manifestPath === SERVICES_MANIFEST_PATH` — the same isolation gate the
+  // well-known regen uses — so a test driving install against a tempdir
+  // manifestPath never reads the operator's real `~/.parachute`. Tests opt into
+  // the guidance assertions by passing `guidanceCtx` explicitly.
+  const guidanceProbeAllowed =
+    opts.guidanceCtx !== undefined || manifestPath === SERVICES_MANIFEST_PATH;
+  if (spec.init && !opts.interactive && !opts.noCreate && guidanceProbeAllowed) {
+    const gctx = opts.guidanceCtx;
+    const supervised =
+      gctx?.hubUnitInstalled ?? isHubUnitInstalled(gctx?.hubUnitDeps ?? defaultHubUnitDeps);
+    // Only emit the "managed under the supervisor" guidance when there's a
+    // supervised hub to manage it through. On a non-supervised box (no hub
+    // unit) the admin UI may not be reachable, so we stay quiet and let the
+    // generic install output stand — the operator can run --interactive.
+    if (supervised) {
+      const exposeState = gctx && "exposeState" in gctx ? gctx.exposeState : safeReadExposeState();
+      const hubPort = gctx && "hubPort" in gctx ? gctx.hubPort : readHubPort(configDir);
+      const adminUrl = resolveGuidanceAdminUrl(exposeState, hubPort);
+      for (const line of buildLightInstallGuidance(short, adminUrl)) log(line);
+    }
+  }
+
   // Final registration check — the service may have written its own
   // authoritative entry during init or first boot, replacing the seed (or
   // filling a gap when the service had no seedEntry). Re-read at exit so the

package/src/help.ts

@@ -42,7 +42,7 @@ export function installHelp(): string {
   return `parachute install — install and register a Parachute service
 
 Usage:
-  parachute install <service> [--channel rc|latest] [--tag <name>] [--no-start]
+  parachute install <service> [--channel rc|latest] [--tag <name>] [--no-start] [--interactive]
   parachute install all       [--channel rc|latest] [--tag <name>] [--no-start]
   parachute install scribe    [--scribe-provider <name>] [--scribe-key <key>]
 
@@ -52,7 +52,10 @@ Services:
 
 What it does:
   1. bun add -g @openparachute/<service>[@<tag>]
-  2. run any service-specific init (e.g. \`parachute-vault init\`)
+  2. register + start the module under the hub supervisor (LIGHT by default —
+     no interactive interview; for vault: no vault-name / MCP / token prompts
+     and no competing standalone daemon). Pass \`--interactive\` to run the
+     service's own full setup (e.g. \`parachute-vault init\`) instead.
   3. assign a canonical port (1939–1949) and reflect it in
      \`~/.parachute/services.json\` — the single source of truth at boot
      (services follow a 4-tier resolvePort ladder; services.json wins).
@@ -73,6 +76,15 @@ Flags:
                             Skipped if the package is already \`bun link\`-ed locally.
   --no-start                skip the post-install daemon start. For piped / CI
                             installs that own their own process model.
+  --interactive             run the module's full interactive setup instead of
+                            the light default. For vault: the vault-name /
+                            "install MCP in Claude Code?" / "mint a token?"
+                            interview + its own standalone daemon registration.
+                            On a supervised hub that standalone daemon can RACE
+                            the supervisor for the module's port (EADDRINUSE
+                            crash-loop, #580) — prefer the light default + manage
+                            from the admin UI unless you specifically want the
+                            old interview.
   --scribe-provider <name>  set scribe's transcription provider non-interactively.
                             Known: parakeet-mlx (default), onnx-asr, whisper, groq, openai.
                             Skips the interactive picker.
@@ -89,7 +101,8 @@ Environment:
                             and \`--tag\`. Defaults to \`latest\` when unset.
 
 Examples:
-  parachute install vault                                   # installs, runs init, starts vault
+  parachute install vault                                   # light: installs + starts vault, points you at the admin UI
+  parachute install vault --interactive                     # full interactive vault init (name / MCP / token prompts)
   parachute install surface                                 # installs surface (auto-bootstraps Notes)
   parachute install notes                                   # back-compat: legacy notes-daemon (Phase 2 deprecating)
   parachute install scribe                                  # installs, prompts for provider, starts scribe

package/src/supervisor.ts

@@ -34,14 +34,55 @@
  * child state to disk (transient — re-derived from services.json on every boot).
  */
 
+import { spawnSync } from "node:child_process";
 import {
   MissingDependencyError,
   type MissingDependencyWire,
   ensureExecutable,
   rethrowIfMissing,
 } from "@openparachute/depcheck";
+import { defaultPidOnPort } from "./hub-control.ts";
 import { type PortListeningFn, defaultPortListening } from "./port-probe.ts";
 
+/**
+ * Which pid (if any) holds a TCP LISTEN on `port`. Production wires
+ * `hub-control.ts:defaultPidOnPort` (an `lsof -ti :<port> -sTCP:LISTEN`
+ * shell-out, macOS + Linux); a box without `lsof` / on an unsupported platform
+ * returns undefined → the squatter check degrades gracefully (falls back to the
+ * existing started-but-unbound error). Injectable so tests stay deterministic.
+ */
+export type PidOnPortFn = (port: number) => number | undefined;
+
+/**
+ * Best-effort command line of a pid (the squatter-surfacing detail). Returns
+ * undefined when it can't be read; the message then omits the cmdline.
+ */
+export type OwnerProbeFn = (pid: number) => string | undefined;
+
+/**
+ * Production `ownerOfPid`: `ps -o command= -p <pid>` → the process's full argv
+ * (one line). Mirrors `migrate-cutover.ts:defaultOwnerOfPid` (inlined rather
+ * than imported to keep the supervisor off the heavy command-module graph).
+ * Any failure (no `ps`, pid gone, permission, garbage) → undefined, so the
+ * squatter message degrades to "command line unavailable".
+ */
+export const defaultOwnerOfPid: OwnerProbeFn = (pid) => {
+  try {
+    const result = spawnSync("ps", ["-o", "command=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: 2000,
+    });
+    if (result.status !== 0) return undefined;
+    const line = result.stdout
+      .split("\n")
+      .map((s) => s.trim())
+      .find((s) => s.length > 0);
+    return line === undefined || line.length === 0 ? undefined : line;
+  } catch {
+    return undefined;
+  }
+};
+
 export type ModuleStatus = "starting" | "running" | "stopped" | "crashed" | "restarting";
 
 /**
@@ -221,6 +262,29 @@ export interface SupervisorOpts {
    * Tests exercising the missing-binary branch inject `which: () => null`.
    */
   readonly which?: (cmd: string) => string | null;
+  /**
+   * Pre-spawn port-squatter detection (#580 item 4). Returns the pid holding a
+   * TCP LISTEN on the module's port, or undefined when the port is free /
+   * undetectable. Before spawning a module, the supervisor checks whether the
+   * declared port is already held by a pid it does NOT own (not one of its live
+   * children). If so it records a structured `port_squatter` start-error with
+   * an actionable message and DOES NOT spawn — so a rogue process holding the
+   * port (the #580 field signature: a bare `vault/src/server.ts` outside the
+   * supervisor on :1940) surfaces in `status` instead of the supervised child
+   * EADDRINUSE-crash-looping into a bare `supervisor: crashed`.
+   *
+   * Detection ONLY — never auto-kills (that's an operator's unrelated process).
+   * Defaults to `hub-control.ts:defaultPidOnPort` on the production path; the
+   * stub-spawner test path defaults to "no squatter" (returns undefined) so
+   * existing fake-proc tests are unaffected unless they inject this explicitly.
+   */
+  readonly pidOnPort?: PidOnPortFn;
+  /**
+   * Best-effort cmdline probe for the squatter pid (the actionable message
+   * detail). Defaults to {@link defaultOwnerOfPid} on the production path; the
+   * stub-spawner test path defaults to "unknown" (returns undefined).
+   */
+  readonly ownerOfPid?: OwnerProbeFn;
 }
 
 /**
@@ -336,6 +400,12 @@ export class Supervisor {
       lateBindWatchMs: opts.lateBindWatchMs ?? DEFAULT_LATE_BIND_WATCH_MS,
       lateBindPollMs: opts.lateBindPollMs ?? DEFAULT_LATE_BIND_POLL_MS,
       which: opts.which ?? (isProductionPath ? Bun.which : () => "/stub/bin/preflight-skipped"),
+      // Squatter detection (#580 item 4): real probes on the production path;
+      // the stub-spawner test path defaults to "no squatter / unknown owner" so
+      // fake-proc tests (which never hold a real port) aren't tripped. Tests
+      // opt in by injecting `pidOnPort` / `ownerOfPid`.
+      pidOnPort: opts.pidOnPort ?? (isProductionPath ? defaultPidOnPort : () => undefined),
+      ownerOfPid: opts.ownerOfPid ?? (isProductionPath ? defaultOwnerOfPid : () => undefined),
     };
   }
 
@@ -389,6 +459,25 @@ export class Supervisor {
       }
     }
 
+    // Pre-spawn port-squatter detection (#580 item 4). If the module's declared
+    // port is already held by a process the supervisor does NOT own (not one of
+    // its live children), spawning would EADDRINUSE-crash-loop the child into a
+    // bare `supervisor: crashed` with no clue why. Detect the foreign holder and
+    // record a structured, actionable `port_squatter` start-error INSTEAD of
+    // spawning — the operator sees the offending pid + cmdline + a copy-paste
+    // recovery in `status` / the SPA. Detection only: we never kill someone
+    // else's process (it may be the operator's unrelated dev server).
+    const squatter = this.detectPortSquatter(entry);
+    if (squatter) {
+      entry.state = {
+        ...entry.state,
+        status: "crashed",
+        pid: undefined,
+        startError: squatter,
+      };
+      return entry.state;
+    }
+
     // Belt-and-suspenders for a spawn that slips past the preflight (binary
     // removed between check + spawn, or a path that didn't preflight): a
     // not-found spawn throw becomes the same structured MissingDependencyError
@@ -428,6 +517,65 @@ export class Supervisor {
     return entry.state;
   }
 
+  /**
+   * The set of pids the supervisor currently owns AND that are still alive — its
+   * live children's pids. Used by the squatter check to decide whether a process
+   * holding a module's port is "ours" (a re-probe of our own just-spawned child,
+   * or a sibling) vs a foreign rogue.
+   *
+   * Liveness guard (N1): `entry.proc` is NEVER cleared on exit (`handleExit`
+   * only updates `entry.state`), so a recycled OS pid could otherwise be
+   * misclassified as "our own child" and wrongly excused from the squatter
+   * check. We therefore only count an entry whose child is actually running —
+   * `state.status` is `running` or `starting`. A `crashed` / `restarting` /
+   * `stopped` module's recorded pid is stale (the process is gone or being
+   * replaced) and must not vouch for whoever now holds the port. An entry with
+   * no `proc` (never spawned) contributes no pid either.
+   */
+  private supervisedPids(): Set<number> {
+    const pids = new Set<number>();
+    for (const entry of this.modules.values()) {
+      if (entry.state.status !== "running" && entry.state.status !== "starting") continue;
+      const pid = entry.proc?.pid;
+      if (typeof pid === "number" && pid > 0) pids.add(pid);
+    }
+    return pids;
+  }
+
+  /**
+   * Pre-spawn port-squatter check (#580 item 4). Returns a structured
+   * `port_squatter` start-error when the module's declared port is held by a
+   * process the supervisor does NOT own; undefined when the port is free, the
+   * holder is one of our own children, or detection isn't available on this
+   * platform (no `lsof` → `pidOnPort` returns undefined → we degrade to the
+   * existing started-but-unbound path post-spawn).
+   *
+   * Ownership precedent mirrors `migrate-cutover.ts:sweepOrphanOnPort`'s "is
+   * this mine?" check — here the discriminant is "is the holder one of my live
+   * children's pids?". We deliberately do NOT kill the holder (detection only):
+   * a foreign pid on a module port may be the operator's unrelated process.
+   */
+  private detectPortSquatter(entry: ModuleEntry): ModuleStartError | undefined {
+    const portStr = entry.req.env?.PORT;
+    const port = portStr ? Number(portStr) : Number.NaN;
+    if (!Number.isFinite(port) || port <= 0) return undefined; // No declared port.
+
+    const holder = this.opts.pidOnPort(port);
+    if (holder === undefined) return undefined; // Port free, or detection unavailable.
+    if (this.supervisedPids().has(holder)) return undefined; // Our own child.
+
+    const cmdline = this.opts.ownerOfPid(holder);
+    const who = cmdline ? `pid ${holder} (${cmdline})` : `pid ${holder}`;
+    const short = entry.req.short;
+    return {
+      error_type: "port_squatter",
+      error_description:
+        `port ${port} is held by ${who} outside the supervisor — ` +
+        `kill it and retry: kill ${holder} && parachute start ${short}`,
+      at: new Date(this.opts.now()).toISOString(),
+    };
+  }
+
   /**
    * Poll the module's port until it binds or `startReadyMs` elapses (§6.5).
    * Skipped when the gate is disabled (stub-spawner test path) or the request