@openparachute/hub 0.6.1 → 0.6.3-rc.1

package/src/__tests__/init.test.ts

@@ -103,8 +103,11 @@ describe("init", () => {
       expect(code).toBe(0);
       expect(calls).toEqual(["ensureHub"]);
       const joined = logs.join("\n");
-      expect(joined).toContain("Hub not running — starting it now");
-      expect(joined).toContain("Hub started (pid 5555, port 1939)");
+      // A genuinely-started unit reports the port only — no `pid 0` sentinel,
+      // no misleading "starting it now" preamble.
+      expect(joined).toContain("Hub unit started (port 1939)");
+      expect(joined).not.toContain("pid 0");
+      expect(joined).not.toContain("starting it now");
       expect(joined).toContain("http://127.0.0.1:1939/admin/");
       expect(joined).toContain("finish setup in the admin wizard");
     } finally {
@@ -112,6 +115,46 @@ describe("init", () => {
     }
   });
 
+  test("unit-managed re-run against a live hub logs 'already running', not 'pid 0'", async () => {
+    // A unit-managed hub writes no pidfile, so `processState(HUB_SVC)` reports
+    // not-running on every re-run — but `ensureHub` probes /health and returns
+    // started:false when the hub is already up. The log must be honest: no
+    // "starting it now", no "Hub unit started", no `pid 0` sentinel.
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      const calls: string[] = [];
+      const logs: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => logs.push(l),
+        // No pidfile (unit-managed) → processState reports not-running.
+        alive: () => false,
+        ensureHub: async () => {
+          calls.push("ensureHub");
+          // Hub already answered /health — ensureHubUnit's already-up arm.
+          return { pid: 0, port: 1939, started: false };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "darwin",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      // ensureHub IS called (processState can't see a unit-managed hub) but
+      // reports started:false.
+      expect(calls).toEqual(["ensureHub"]);
+      const joined = logs.join("\n");
+      expect(joined).toContain("Hub already running (port 1939)");
+      expect(joined).not.toContain("pid 0");
+      expect(joined).not.toContain("starting it now");
+      expect(joined).not.toContain("Hub unit started");
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("idempotent: skips ensureHub and confirms 'looks good' when hub up + vault configured", async () => {
     const h = makeHarness();
     try {
@@ -879,6 +922,180 @@ describe("init exposure chain", () => {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // Phase 3a cutover (design §3.3 init row, §3.1, §4.1/§4.2): init installs +
+  // starts the hub UNIT (not a detached spawn) and guarantees an operator
+  // token. The `ensureHub` + `guaranteeOperatorToken` seams stay injectable;
+  // these tests drive them as stubs (and exercise the REAL operator-token
+  // guarantee against a seeded hub DB).
+  // -------------------------------------------------------------------------
+
+  test("calls guaranteeOperatorToken after the hub is up, then falls through to the wizard", async () => {
+    const h = makeHarness();
+    try {
+      const order: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => {
+          order.push("ensureHub");
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        guaranteeOperatorToken: async (ctx) => {
+          order.push("guaranteeOperatorToken");
+          // The hub is up before the token guarantee runs (§3.2 step 4 — read
+          // the token AFTER readiness so we don't race the start-hub iss
+          // self-heal).
+          expect(ctx.hubPort).toBe(1939);
+          return "present";
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      // hub-up first, then token guarantee — in that order.
+      expect(order).toEqual(["ensureHub", "guaranteeOperatorToken"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("real guarantee: MINTS the operator token when absent + a hub user exists", async () => {
+    const h = makeHarness();
+    try {
+      const { openHubDb, hubDbPath } = await import("../hub-db.ts");
+      const { createUser } = await import("../users.ts");
+      const { readOperatorTokenFile } = await import("../operator-token.ts");
+      // Seed a first-admin so the guarantee has someone to mint for.
+      const db = openHubDb(hubDbPath(h.configDir));
+      await createUser(db, "owner", "owner-password-123");
+      db.close();
+
+      // No operator.token yet.
+      expect(await readOperatorTokenFile(h.configDir)).toBeNull();
+
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        // No guaranteeOperatorToken seam → exercises the REAL default.
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      // The default minted + wrote the token.
+      expect(await readOperatorTokenFile(h.configDir)).not.toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("real guarantee: does NOT double-mint when a token already exists", async () => {
+    const h = makeHarness();
+    try {
+      const { openHubDb, hubDbPath } = await import("../hub-db.ts");
+      const { createUser } = await import("../users.ts");
+      const { writeOperatorTokenFile, readOperatorTokenFile } = await import(
+        "../operator-token.ts"
+      );
+      const db = openHubDb(hubDbPath(h.configDir));
+      await createUser(db, "owner", "owner-password-123");
+      db.close();
+      // Plant a sentinel token on disk.
+      await writeOperatorTokenFile("SENTINEL.PRE-EXISTING.TOKEN", h.configDir);
+
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      // Untouched — the guarantee left the pre-existing token in place.
+      expect(await readOperatorTokenFile(h.configDir)).toBe("SENTINEL.PRE-EXISTING.TOKEN");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("real guarantee: no hub user yet → no token minted, init still succeeds (no-user, not an error)", async () => {
+    const h = makeHarness();
+    try {
+      const { readOperatorTokenFile } = await import("../operator-token.ts");
+      // No user seeded — the common fresh-box case where init runs before the
+      // wizard creates first-admin.
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      // No token (the wizard mints it when the admin is created).
+      expect(await readOperatorTokenFile(h.configDir)).toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub-unit bringup failure (e.g. no service manager) → init exits 1 with the actionable message", async () => {
+    const h = makeHarness();
+    try {
+      const logs: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => logs.push(l),
+        alive: () => false,
+        // Mirror what the production default throws when there's no manager.
+        ensureHub: async () => {
+          throw new Error(
+            "no service manager (systemd/launchd) found — run `parachute serve` in the foreground, or use a platform that provides one",
+          );
+        },
+        guaranteeOperatorToken: async () => "no-user",
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(1);
+      const joined = logs.join("\n");
+      expect(joined).toContain("no service manager (systemd/launchd) found");
+      expect(joined).toContain("parachute logs hub");
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("after exposure runs, the admin URL re-reads expose state for the FQDN", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/lifecycle.test.ts

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
+  type LifecycleOpts,
   defaultAlive,
   defaultKill,
   defaultSpawner,
@@ -14,7 +15,14 @@ import {
 import { readEnvFileValues } from "../env-file.ts";
 import { writeHubPort } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
+import type { HubUnitManagerOpResult } from "../hub-unit.ts";
 import { validateAccessToken } from "../jwt-sign.ts";
+import {
+  type ModuleOp,
+  ModuleOpHttpError,
+  type ModuleOpResult,
+  NoOperatorTokenError,
+} from "../module-ops-client.ts";
 import {
   OPERATOR_TOKEN_SCOPE_SET_CLAIM,
   issueOperatorToken,
@@ -1862,3 +1870,418 @@ describe("parachute start|stop|restart hub", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Phase 3b dual-dispatch (design §3.3): when a hub UNIT is installed, the verbs
+// drive the running supervisor / platform manager; when no unit is installed,
+// the existing detached arm is taken UNCHANGED. These suites exercise both arms
+// via injected `supervisor` seams (unit arm) and a stub spawner (detached arm).
+// ---------------------------------------------------------------------------
+
+interface SupervisorStub {
+  opts: NonNullable<LifecycleOpts["supervisor"]>;
+  driveCalls: Array<{ short: string; op: ModuleOp }>;
+  ensureCalls: Array<{ port?: number }>;
+  stopHubCalls: number;
+  restartHubCalls: number;
+  healthProbes: number;
+}
+
+/**
+ * Build a `supervisor` seam that forces the unit-installed arm and records the
+ * supervisor / manager calls. `driveResponder` lets a test return a result or
+ * throw a module-ops error per (short, op). The default responder returns a
+ * benign sync-op result. `health` controls `probeHubHealth`.
+ */
+function makeSupervisorStub(opts?: {
+  health?: boolean;
+  ensureOutcome?: "already-up" | "started" | "no-unit" | "no-manager" | "timeout" | "start-failed";
+  ensureMessages?: string[];
+  driveResponder?: (short: string, op: ModuleOp) => ModuleOpResult | Promise<ModuleOpResult>;
+  stopHubResult?: HubUnitManagerOpResult;
+  restartHubResult?: HubUnitManagerOpResult;
+}): SupervisorStub {
+  const driveCalls: Array<{ short: string; op: ModuleOp }> = [];
+  const ensureCalls: Array<{ port?: number }> = [];
+  const stub: SupervisorStub = {
+    driveCalls,
+    ensureCalls,
+    stopHubCalls: 0,
+    restartHubCalls: 0,
+    healthProbes: 0,
+    opts: {
+      unitInstalled: true,
+      // openDb is never exercised by the stub driveModuleOp, but the dispatch
+      // opens+closes it around the call — hand back a no-op closer.
+      openDb: () => ({ close() {} }) as unknown as import("bun:sqlite").Database,
+      driveModuleOp: async (short, op) => {
+        driveCalls.push({ short, op });
+        if (opts?.driveResponder) return await opts.driveResponder(short, op);
+        return { status: 200, body: { short, state: { status: "running" } } };
+      },
+      ensureHubUnit: async (o) => {
+        ensureCalls.push({ port: o.port });
+        return {
+          outcome: opts?.ensureOutcome ?? "already-up",
+          port: o.port ?? 1939,
+          messages: opts?.ensureMessages ?? [],
+        };
+      },
+      stopHubUnit: () => {
+        stub.stopHubCalls++;
+        return opts?.stopHubResult ?? { outcome: "ok", messages: [] };
+      },
+      restartHubUnit: () => {
+        stub.restartHubCalls++;
+        return opts?.restartHubResult ?? { outcome: "ok", messages: [] };
+      },
+      probeHubHealth: async () => {
+        stub.healthProbes++;
+        return opts?.health ?? true;
+      },
+    },
+  };
+  return stub;
+}
+
+describe("Phase 3b dual-dispatch — start", () => {
+  test("module svc, unit-installed → ensureHubUnit then driveModuleOp(start)", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub();
+      const log: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.ensureCalls).toHaveLength(1);
+      expect(sup.driveCalls).toEqual([{ short: "vault", op: "start" }]);
+      expect(log.join("\n")).toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no svc, unit-installed → ensureHubUnit only (boots all modules), no driveModuleOp", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub();
+      const code = await start(undefined, {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.ensureCalls).toHaveLength(1);
+      expect(sup.driveCalls).toHaveLength(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("module svc, NO unit → existing detached spawner path (unchanged)", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawner([4242]);
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        log: () => {},
+        // supervisor omitted → detached arm, deterministically.
+      });
+      expect(code).toBe(0);
+      expect(spawner.calls).toHaveLength(1);
+      expect(spawner.calls[0]?.cmd).toEqual(["parachute-vault", "serve"]);
+      expect(readPid("vault", h.configDir)).toBe(4242);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("module svc, NoOperatorTokenError → actionable message surfaced (not raw-thrown)", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub({
+        driveResponder: () => {
+          throw new NoOperatorTokenError();
+        },
+      });
+      const log: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(1);
+      expect(log.join("\n")).toMatch(/no operator token/);
+      expect(log.join("\n")).toMatch(/parachute auth rotate-operator/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("module svc, 400 not_installed → actionable install hint", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub({
+        driveResponder: () => {
+          throw new ModuleOpHttpError(400, "not_installed", "vault is not installed");
+        },
+      });
+      const log: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(1);
+      expect(log.join("\n")).toMatch(/not installed/);
+      expect(log.join("\n")).toMatch(/parachute install vault/);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("Phase 3b dual-dispatch — stop", () => {
+  test("module svc, hub UP → driveModuleOp(stop), no ensureHubUnit", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub({ health: true });
+      const log: string[] = [];
+      const code = await stop("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.healthProbes).toBe(1);
+      expect(sup.driveCalls).toEqual([{ short: "vault", op: "stop" }]);
+      expect(sup.ensureCalls).toHaveLength(0); // never start the hub just to stop a module
+      expect(log.join("\n")).toMatch(/✓ vault stopped/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("module svc, hub DOWN → success WITHOUT starting the hub or driving stop", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub({ health: false });
+      const log: string[] = [];
+      const code = await stop("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.healthProbes).toBe(1);
+      expect(sup.driveCalls).toHaveLength(0); // nothing to stop — module already down
+      expect(sup.ensureCalls).toHaveLength(0); // did NOT ensureHubUnit
+      expect(log.join("\n")).toMatch(/already stopped/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("stop hub → platform manager (stopHubUnit), never a PID signal", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub();
+      // A kill seam that fails the test if ANY PID signal is sent.
+      const kill = () => {
+        throw new Error("stop hub must NOT signal a PID — it must go through the manager");
+      };
+      const log: string[] = [];
+      const code = await stop("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        kill,
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.stopHubCalls).toBe(1);
+      expect(sup.healthProbes).toBe(0);
+      expect(log.join("\n")).toMatch(/✓ hub stopped/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no svc, unit-installed → stop the hub unit (manager)", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub();
+      const code = await stop(undefined, {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.stopHubCalls).toBe(1);
+      expect(sup.driveCalls).toHaveLength(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("module svc, NO unit → existing detached stop path (unchanged)", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      writePid("vault", 4242, h.configDir);
+      const killed: Array<{ pid: number; sig: NodeJS.Signals | number }> = [];
+      const code = await stop("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        kill: (pid, sig) => killed.push({ pid, sig }),
+        alive: (() => {
+          let n = 0;
+          return () => n++ < 1; // alive once (for the SIGTERM), then dead.
+        })(),
+        log: () => {},
+        // supervisor omitted → detached arm.
+      });
+      expect(code).toBe(0);
+      expect(killed[0]).toEqual({ pid: 4242, sig: "SIGTERM" });
+      expect(readPid("vault", h.configDir)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("Phase 3b dual-dispatch — restart", () => {
+  test("module svc, unit-installed → ensureHubUnit then driveModuleOp(restart)", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub();
+      const log: string[] = [];
+      const code = await restart("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.ensureCalls).toHaveLength(1);
+      expect(sup.driveCalls).toEqual([{ short: "vault", op: "restart" }]);
+      expect(log.join("\n")).toMatch(/✓ vault restarted/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("404 not_supervised on restart → fall through to driveModuleOp(start)", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub({
+        driveResponder: (_short, op) => {
+          if (op === "restart") {
+            throw new ModuleOpHttpError(404, "not_supervised", "vault is not currently supervised");
+          }
+          return { status: 200, body: { short: "vault", state: { status: "running" } } };
+        },
+      });
+      const log: string[] = [];
+      const code = await restart("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      // restart was attempted, then start as the 404-fallthrough (§6.2).
+      expect(sup.driveCalls).toEqual([
+        { short: "vault", op: "restart" },
+        { short: "vault", op: "start" },
+      ]);
+      expect(log.join("\n")).toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("restart hub → platform manager (restartHubUnit), never a PID signal", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub();
+      const kill = () => {
+        throw new Error("restart hub must NOT signal a PID — it must go through the manager");
+      };
+      const log: string[] = [];
+      const code = await restart("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => log.push(l),
+        kill,
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.restartHubCalls).toBe(1);
+      expect(sup.driveCalls).toHaveLength(0); // NOT a per-module fan-out
+      expect(log.join("\n")).toMatch(/✓ hub restarted/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no svc, unit-installed → restart the hub unit (manager), not a fan-out", async () => {
+    const h = makeHarness();
+    try {
+      const sup = makeSupervisorStub();
+      const code = await restart(undefined, {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        supervisor: sup.opts,
+      });
+      expect(code).toBe(0);
+      expect(sup.restartHubCalls).toBe(1);
+      expect(sup.driveCalls).toHaveLength(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("module svc, NO unit → existing detached stop-then-start path (unchanged)", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      writePid("vault", 4242, h.configDir);
+      const spawner = makeSpawner([7777]);
+      const killed: Array<{ pid: number; sig: NodeJS.Signals | number }> = [];
+      const code = await restart("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        kill: (pid, sig) => killed.push({ pid, sig }),
+        // Stale 4242 is dead (stop's stale-pid path cleans up without a kill);
+        // freshly spawned 7777 is alive past the post-spawn settle (hub#194).
+        // Per-pid differentiation, mirroring the existing detached-restart test.
+        alive: (pid) => pid === 7777,
+        sleep: async () => {},
+        log: () => {},
+        // supervisor omitted → detached arm (stop then start).
+      });
+      expect(code).toBe(0);
+      expect(killed).toHaveLength(0); // stale pid → detached cleanup, no kill
+      expect(spawner.calls).toHaveLength(1); // detached start ran (NOT the supervisor)
+      expect(readPid("vault", h.configDir)).toBe(7777);
+    } finally {
+      h.cleanup();
+    }
+  });
+});