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

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__/setup-wizard.test.ts

@@ -4051,6 +4051,116 @@ describe("setup-wizard JSON surface (hub#168 Cuts 2/3)", () => {
     }
   });
 
+  test("JSON probe hands the bootstrap token VALUE to a loopback caller (hub#576)", async () => {
+    const { generateBootstrapToken, _resetBootstrapTokenForTests } = await import(
+      "../bootstrap-token.ts"
+    );
+    _resetBootstrapTokenForTests();
+    const token = generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup", { headers: { accept: "application/json" } }), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+        requestIsLoopback: true,
+      });
+      const body = (await res.json()) as {
+        requireBootstrapToken: boolean;
+        bootstrapToken?: string;
+      };
+      expect(body.requireBootstrapToken).toBe(true);
+      expect(body.bootstrapToken).toBe(token);
+    } finally {
+      _resetBootstrapTokenForTests();
+      db.close();
+    }
+  });
+
+  test("JSON probe withholds the token VALUE from a non-loopback caller (hub#576)", async () => {
+    const { generateBootstrapToken, _resetBootstrapTokenForTests } = await import(
+      "../bootstrap-token.ts"
+    );
+    _resetBootstrapTokenForTests();
+    generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup", { headers: { accept: "application/json" } }), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+        requestIsLoopback: false,
+      });
+      const body = (await res.json()) as {
+        requireBootstrapToken: boolean;
+        bootstrapToken?: string;
+      };
+      // The boolean still tells a public browser a token is required...
+      expect(body.requireBootstrapToken).toBe(true);
+      // ...but the VALUE never leaks to it.
+      expect(body.bootstrapToken).toBeUndefined();
+    } finally {
+      _resetBootstrapTokenForTests();
+      db.close();
+    }
+  });
+
+  test("JSON probe fails CLOSED when loopback is unknown (hub#576)", async () => {
+    const { generateBootstrapToken, _resetBootstrapTokenForTests } = await import(
+      "../bootstrap-token.ts"
+    );
+    _resetBootstrapTokenForTests();
+    generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      // `requestIsLoopback` omitted entirely — must be treated as non-loopback.
+      const res = handleSetupGet(req("/admin/setup", { headers: { accept: "application/json" } }), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const body = (await res.json()) as { bootstrapToken?: string };
+      expect(body.bootstrapToken).toBeUndefined();
+    } finally {
+      _resetBootstrapTokenForTests();
+      db.close();
+    }
+  });
+
+  test("JSON probe omits the token when no admin gate is active (hub#576)", async () => {
+    const { _resetBootstrapTokenForTests } = await import("../bootstrap-token.ts");
+    _resetBootstrapTokenForTests(); // no token minted → not in wizard mode
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup", { headers: { accept: "application/json" } }), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+        requestIsLoopback: true,
+      });
+      const body = (await res.json()) as {
+        requireBootstrapToken: boolean;
+        bootstrapToken?: string;
+      };
+      expect(body.requireBootstrapToken).toBe(false);
+      expect(body.bootstrapToken).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
   test("vault step skip mode short-circuits + persists setup_vault_skipped", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {

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