@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/__tests__/expose.test.ts

@@ -2,11 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import type { ExposeSupervisorOpts } from "../commands/expose-supervisor.ts";
 import { exposePublic, exposeTailnet } from "../commands/expose.ts";
 import { readEnvFileValues } from "../env-file.ts";
 import { readExposeState, writeExposeState } from "../expose-state.ts";
-import type { EnsureHubOpts, HubSpawner, StopHubOpts } from "../hub-control.ts";
-import { writePid } from "../process-state.ts";
+import type { EnsureHubUnitOpts } from "../hub-unit.ts";
+import { type ModuleOp, ModuleOpHttpError } from "../module-ops-client.ts";
 import { upsertService } from "../services-manifest.ts";
 import type { Runner } from "../tailscale/run.ts";
 
@@ -54,36 +55,16 @@ function makeRunner(): { runner: Runner; calls: string[][] } {
   return { runner, calls };
 }
 
-function makeHubSpawner(pid: number): { spawner: HubSpawner; calls: string[][] } {
-  const calls: string[][] = [];
-  const spawner: HubSpawner = {
-    spawn(cmd) {
-      calls.push([...cmd]);
-      return pid;
-    },
-  };
-  return { spawner, calls };
-}
-
-/** Default hub overrides for expose tests — no real subprocess, no sleep. */
-function hubEnsureOpts(
-  spawner: HubSpawner,
-): Omit<EnsureHubOpts, "configDir" | "wellKnownDir" | "log"> {
-  return {
-    spawner,
-    alive: () => true,
-    probe: async () => true,
-    readyWaitMs: 0,
-  };
-}
-
-function hubStopOpts(): Omit<StopHubOpts, "configDir" | "log"> {
-  return {
-    kill: () => {},
-    alive: () => false,
-    sleep: async () => {},
-    now: () => 0,
-  };
+/**
+ * A minimal expose `supervisor` seam that forces the unit-installed arm with a
+ * benign `ensureHubUnit → already-up` + no-op `driveModuleOp` / self-heal. Most
+ * expose tests just need the hub-bringup to succeed so they can assert the
+ * tailscale plan / expose-state / well-known behavior; this stub provides that
+ * without a real launchd/systemd or hub. (Phase 5b retired the detached hub
+ * spawner that the old `makeHubSpawner` / `hubEnsureOpts` stubs simulated.)
+ */
+function supervisorUp(): ExposeSupervisorOpts {
+  return makeExposeSupervisorStub().opts;
 }
 
 function seedServices(path: string): void {
@@ -122,7 +103,6 @@ describe("expose tailnet up", () => {
     try {
       seedServices(h.manifestPath);
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposeTailnet("up", {
         runner,
@@ -130,9 +110,8 @@ describe("expose tailnet up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
       });
@@ -172,31 +151,31 @@ describe("expose tailnet up", () => {
     }
   });
 
-  test("spawns hub server with --port + --well-known-dir", async () => {
+  test("ensures the hub UNIT (not a detached spawn) before exposing", async () => {
+    // Phase 5b: "ensure the hub" = ensure the hub UNIT is up (§4.3a). The old
+    // detached `bun hub-server.ts --port …` spawn is retired — its bringup is now
+    // init's `installAndStartHubUnit` (asserted in init.test.ts / hub-unit.test.ts).
+    // Here we just confirm expose drives the unit-ensure seam, then proceeds.
     const h = makeHarness();
     try {
       seedServices(h.manifestPath);
       const { runner } = makeRunner();
-      const { spawner, calls: hubCalls } = makeHubSpawner(7777);
+      const sup = makeExposeSupervisorStub();
+      const logs: string[] = [];
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: sup.opts,
         servicePortProbe: allServicesUp,
-        log: () => {},
+        log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
-      expect(hubCalls).toHaveLength(1);
-      const cmd = hubCalls[0] ?? [];
-      expect(cmd[0]).toBe("bun");
-      expect(cmd).toContain("--port");
-      expect(cmd).toContain("--well-known-dir");
-      expect(cmd).toContain(h.wellKnownDir);
+      expect(sup.ensureCalls).toHaveLength(1);
+      expect(logs.join("\n")).toMatch(/hub unit up/);
     } finally {
       h.cleanup();
     }
@@ -220,16 +199,14 @@ describe("expose tailnet up", () => {
         h.manifestPath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -258,7 +235,6 @@ describe("expose tailnet up", () => {
         h.manifestPath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposeTailnet("up", {
         runner,
@@ -266,9 +242,8 @@ describe("expose tailnet up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
       });
@@ -291,7 +266,6 @@ describe("expose tailnet up", () => {
     const h = makeHarness();
     try {
       const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposeTailnet("up", {
         runner,
@@ -299,9 +273,8 @@ describe("expose tailnet up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
       });
@@ -319,7 +292,6 @@ describe("expose tailnet up", () => {
       const runner: Runner = async () => {
         throw new Error("spawn tailscale ENOENT");
       };
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposeTailnet("up", {
         runner,
@@ -327,9 +299,8 @@ describe("expose tailnet up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
       });
@@ -364,16 +335,14 @@ describe("expose tailnet up", () => {
         h.statePath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -395,7 +364,6 @@ describe("expose tailnet up", () => {
     try {
       seedServices(h.manifestPath);
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposeTailnet("up", {
         runner,
@@ -403,9 +371,8 @@ describe("expose tailnet up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         // vault is up; notes is down.
         servicePortProbe: async (port) => port === 1940,
         log: (l) => logs.push(l),
@@ -444,7 +411,6 @@ describe("expose tailnet up", () => {
         }
         return { code: 0, stdout: "", stderr: "" };
       };
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposeTailnet("up", {
         runner,
@@ -452,9 +418,8 @@ describe("expose tailnet up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
       });
@@ -473,16 +438,14 @@ describe("expose tailnet up", () => {
     try {
       seedServices(h.manifestPath);
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -520,16 +483,14 @@ describe("expose tailnet up", () => {
         h.manifestPath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -549,16 +510,14 @@ describe("expose tailnet up", () => {
     try {
       seedServices(h.manifestPath);
       const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         hubOrigin: "https://hub.example.com/",
         log: () => {},
@@ -580,7 +539,6 @@ describe("expose tailnet up", () => {
     try {
       seedServices(h.manifestPath);
       const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposeTailnet("up", {
         runner,
@@ -588,9 +546,8 @@ describe("expose tailnet up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
         vaultAuthStatus: {
@@ -619,9 +576,7 @@ describe("expose tailnet off", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: hubStopOpts(),
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
@@ -632,7 +587,7 @@ describe("expose tailnet off", () => {
     }
   });
 
-  test("tears down every tracked entry, stops hub, and clears state", async () => {
+  test("tears down every tracked entry + clears state, leaves the hub running (D3)", async () => {
     const h = makeHarness();
     try {
       writeExposeState(
@@ -662,27 +617,15 @@ describe("expose tailnet off", () => {
       );
       await Bun.write(h.wellKnownPath, "{}\n");
       await Bun.write(h.hubPath, "<html/>\n");
-      writePid("hub", 4242, h.configDir);
       const { runner, calls } = makeRunner();
-      const signals: NodeJS.Signals[] = [];
-      let aliveNow = true;
+      const logs: string[] = [];
       const code = await exposeTailnet("off", {
         runner,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: {
-          kill: (_pid, sig) => {
-            signals.push(sig as NodeJS.Signals);
-            aliveNow = false;
-          },
-          alive: () => aliveNow,
-          sleep: async () => {},
-          now: () => 0,
-        },
-        log: () => {},
+        log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
       expect(calls.every((c) => c[c.length - 1] === "off")).toBe(true);
@@ -690,8 +633,10 @@ describe("expose tailnet off", () => {
       expect(existsSync(h.statePath)).toBe(false);
       expect(existsSync(h.wellKnownPath)).toBe(false);
       expect(existsSync(h.hubPath)).toBe(false);
-      // Hub was running and got stopped.
-      expect(signals).toContain("SIGTERM");
+      // D3 (Phase 5b): the hub is a persistent platform unit — `expose off` tears
+      // down only the exposure and leaves the hub running. No "hub stopped" line.
+      expect(logs.join("\n")).not.toMatch(/hub stopped/);
+      expect(logs.join("\n")).toMatch(/exposure removed/);
     } finally {
       h.cleanup();
     }
@@ -729,7 +674,6 @@ describe("expose tailnet off", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
         skipHub: true,
         log: () => {},
@@ -773,9 +717,7 @@ describe("expose tailnet off", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: hubStopOpts(),
         log: (l) => logs.push(l),
       });
       expect(code).toBe(5);
@@ -807,31 +749,19 @@ describe("expose tailnet off", () => {
         },
         h.statePath,
       );
-      writePid("hub", 4242, h.configDir);
       const { runner, calls } = makeRunner();
-      let killCalled = false;
       const logs: string[] = [];
       const code = await exposeTailnet("off", {
         runner,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: {
-          kill: () => {
-            killCalled = true;
-          },
-          alive: () => false,
-          sleep: async () => {},
-          now: () => 0,
-        },
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
       expect(calls).toHaveLength(0);
       expect(existsSync(h.statePath)).toBe(true);
-      expect(killCalled).toBe(false);
       expect(logs.join("\n")).toMatch(/Current exposure is Public/);
     } finally {
       h.cleanup();
@@ -845,7 +775,6 @@ describe("expose public up", () => {
     try {
       seedServices(h.manifestPath);
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposePublic("up", {
         runner,
@@ -853,9 +782,8 @@ describe("expose public up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
       });
@@ -908,16 +836,14 @@ describe("expose public up", () => {
         h.statePath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -956,16 +882,14 @@ describe("expose public up", () => {
         h.statePath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposePublic("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -987,7 +911,6 @@ describe("expose public up", () => {
     try {
       seedServices(h.manifestPath);
       const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposePublic("up", {
         runner,
@@ -995,9 +918,8 @@ describe("expose public up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
         vaultAuthStatus: {
@@ -1025,7 +947,6 @@ describe("expose public up", () => {
     try {
       seedServices(h.manifestPath);
       const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposePublic("up", {
         runner,
@@ -1033,9 +954,8 @@ describe("expose public up", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: (l) => logs.push(l),
         vaultAuthStatus: {
@@ -1082,9 +1002,7 @@ describe("expose public off", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: hubStopOpts(),
         log: () => {},
       });
       expect(code).toBe(0);
@@ -1127,9 +1045,7 @@ describe("expose public off", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: hubStopOpts(),
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
@@ -1180,16 +1096,14 @@ describe("expose plan is layer-agnostic — gating moved to hub", () => {
         h.manifestPath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -1237,16 +1151,14 @@ describe("expose plan is layer-agnostic — gating moved to hub", () => {
         h.manifestPath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -1265,114 +1177,49 @@ describe("expose auto-restart of hub-dependent services", () => {
   // Launch-day bug (2026-04-23): `expose public` updated hubOrigin in
   // expose-state.json, but a vault already running kept its stale
   // PARACHUTE_HUB_ORIGIN in memory, so the OAuth issuer didn't match what
-  // clients saw and claude.ai MCP failed to reach the server. The CLI used
-  // to print a "Restart vault to pick up…" hint that got lost in the wall
-  // of expose output. Auto-restart the service instead.
-  test("restarts vault when vault is running", async () => {
-    const h = makeHarness();
-    try {
-      seedServices(h.manifestPath);
-      writePid("vault", 4242, h.configDir);
-      const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
-      const restarted: string[] = [];
-      const code = await exposePublic("up", {
-        runner,
-        manifestPath: h.manifestPath,
-        statePath: h.statePath,
-        wellKnownPath: h.wellKnownPath,
-        hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
-        configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
-        servicePortProbe: allServicesUp,
-        alive: () => true,
-        restartService: async (short) => {
-          restarted.push(short);
-          return 0;
-        },
-        log: () => {},
-      });
-      expect(code).toBe(0);
-      expect(restarted).toEqual(["vault"]);
-    } finally {
-      h.cleanup();
-    }
-  });
-
-  test("skips restart when vault is not running", async () => {
+  // clients saw and claude.ai MCP failed to reach the server. Auto-restart the
+  // service so it picks up the new origin.
+  //
+  // Phase 5b: the restart goes through the running supervisor
+  // (`driveModuleOp("vault", "restart")`), NOT a pidfile-gated detached
+  // `lifecycle.restart`. So the restart is unconditional (the supervisor decides
+  // whether the module is live); the old "skips when not running / stale pidfile"
+  // cases no longer apply — a not-supervised vault surfaces as a 404 the helper
+  // treats as "nothing to restart" (asserted in the Phase 4 dual-dispatch suite).
+  test("restarts vault via the supervisor after expose", async () => {
     const h = makeHarness();
     try {
       seedServices(h.manifestPath);
-      // No writePid → vault has no pidfile → processState returns "unknown".
       const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
-      const restarted: string[] = [];
+      const sup = makeExposeSupervisorStub();
       const code = await exposePublic("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: sup.opts,
         servicePortProbe: allServicesUp,
-        alive: () => true,
-        restartService: async (short) => {
-          restarted.push(short);
-          return 0;
-        },
         log: () => {},
       });
       expect(code).toBe(0);
-      expect(restarted).toEqual([]);
+      expect(sup.driveCalls).toEqual([{ short: "vault", op: "restart" }]);
     } finally {
       h.cleanup();
     }
   });
 
-  test("skips restart when pidfile is stale (process dead)", async () => {
+  test("restart failure logs a warning but expose still succeeds", async () => {
     const h = makeHarness();
     try {
       seedServices(h.manifestPath);
-      writePid("vault", 4242, h.configDir);
       const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
-      const restarted: string[] = [];
-      const code = await exposePublic("up", {
-        runner,
-        manifestPath: h.manifestPath,
-        statePath: h.statePath,
-        wellKnownPath: h.wellKnownPath,
-        hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
-        configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
-        servicePortProbe: allServicesUp,
-        // Simulate pid-file-present-but-process-dead. processState returns
-        // "stopped", not "running", so we should skip.
-        alive: () => false,
-        restartService: async (short) => {
-          restarted.push(short);
-          return 0;
-        },
-        log: () => {},
+      // A non-404 module-op error → surfaced as a warning, non-zero rcode mapped
+      // to a warn-and-continue (expose still exits 0).
+      const sup = makeExposeSupervisorStub({
+        driveThrows: () => new ModuleOpHttpError(500, "internal", "vault restart blew up"),
       });
-      expect(code).toBe(0);
-      expect(restarted).toEqual([]);
-    } finally {
-      h.cleanup();
-    }
-  });
-
-  test("restart failure logs warning but expose still succeeds", async () => {
-    const h = makeHarness();
-    try {
-      seedServices(h.manifestPath);
-      writePid("vault", 4242, h.configDir);
-      const { runner } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const logs: string[] = [];
       const code = await exposePublic("up", {
         runner,
@@ -1380,12 +1227,9 @@ describe("expose auto-restart of hub-dependent services", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: sup.opts,
         servicePortProbe: allServicesUp,
-        alive: () => true,
-        restartService: async () => 1,
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
@@ -1446,9 +1290,7 @@ describe("expose teardown tolerance for already-gone entries", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: hubStopOpts(),
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
@@ -1485,9 +1327,7 @@ describe("expose teardown tolerance for already-gone entries", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: hubStopOpts(),
         log: () => {},
       });
       expect(code).toBe(0);
@@ -1517,9 +1357,7 @@ describe("expose teardown tolerance for already-gone entries", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubStopOpts: hubStopOpts(),
         log: (l) => logs.push(l),
       });
       expect(code).toBe(1);
@@ -1538,7 +1376,6 @@ describe("expose teardown tolerance for already-gone entries", () => {
     try {
       seedServices(h.manifestPath);
       makePublicPriorState(h.statePath, 2);
-      const { spawner } = makeHubSpawner(1111);
       const bringupCalls: string[][] = [];
       const runner: Runner = async (cmd) => {
         if (cmd[0] === "tailscale" && cmd[1] === "version") {
@@ -1569,9 +1406,8 @@ describe("expose teardown tolerance for already-gone entries", () => {
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -1607,16 +1443,14 @@ describe("expose: vault routing fully internal to hub", () => {
         h.manifestPath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -1657,16 +1491,14 @@ describe("expose: vault routing fully internal to hub", () => {
         h.manifestPath,
       );
       const { runner, calls } = makeRunner();
-      const { spawner } = makeHubSpawner(1111);
       const code = await exposeTailnet("up", {
         runner,
         manifestPath: h.manifestPath,
         statePath: h.statePath,
         wellKnownPath: h.wellKnownPath,
         hubPath: h.hubPath,
-        wellKnownDir: h.wellKnownDir,
         configDir: h.configDir,
-        hubEnsureOpts: hubEnsureOpts(spawner),
+        supervisor: supervisorUp(),
         servicePortProbe: allServicesUp,
         log: () => {},
       });
@@ -1680,3 +1512,191 @@ describe("expose: vault routing fully internal to hub", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Phase 4 dual-dispatch (design §4.3): when a hub UNIT is installed, `expose`
+// ensures the hub UNIT (not a detached spawn), the post-expose vault restart
+// drives the running Supervisor over the loopback module-ops API (firing the
+// operator-token + vault `.env` self-heal), and `expose off` leaves the hub
+// RUNNING (D3 — a managed hub with Restart=always/KeepAlive would just respawn
+// a stopped one). The no-unit arm keeps today's behavior unchanged.
+// ---------------------------------------------------------------------------
+
+interface ExposeSupervisorStub {
+  opts: ExposeSupervisorOpts;
+  ensureCalls: Array<{ port?: number }>;
+  driveCalls: Array<{ short: string; op: ModuleOp }>;
+  selfHealCalls: Array<{ issuer: string }>;
+}
+
+/**
+ * Build an expose `supervisor` seam that forces the unit-installed arm and
+ * records the `ensureHubUnit` / `driveModuleOp` / operator-token-self-heal
+ * calls. `driveThrows` makes a module-op throw a chosen error; `ensureOutcome`
+ * controls the ensure-hub result.
+ */
+function makeExposeSupervisorStub(opts?: {
+  ensureOutcome?: "already-up" | "started" | "no-unit" | "no-manager" | "timeout" | "start-failed";
+  ensurePort?: number;
+  driveThrows?: (short: string, op: ModuleOp) => unknown;
+}): ExposeSupervisorStub {
+  const ensureCalls: Array<{ port?: number }> = [];
+  const driveCalls: Array<{ short: string; op: ModuleOp }> = [];
+  const selfHealCalls: Array<{ issuer: string }> = [];
+  return {
+    ensureCalls,
+    driveCalls,
+    selfHealCalls,
+    opts: {
+      // openDb is opened+closed around the drive/self-heal — hand back a no-op closer.
+      openDb: () => ({ close() {} }) as unknown as import("bun:sqlite").Database,
+      ensureHubUnit: async (o: EnsureHubUnitOpts) => {
+        ensureCalls.push({ port: o.port });
+        return {
+          outcome: opts?.ensureOutcome ?? "already-up",
+          port: opts?.ensurePort ?? o.port ?? 1939,
+          messages: [],
+        };
+      },
+      driveModuleOp: async (short, op) => {
+        driveCalls.push({ short, op });
+        if (opts?.driveThrows) throw opts.driveThrows(short, op);
+        return { status: 200, body: { short, state: { status: "running" } } };
+      },
+      selfHealOperatorTokenIssuer: async (_db, o) => {
+        selfHealCalls.push({ issuer: o.issuer });
+        return { kind: "fresh" };
+      },
+    },
+  };
+}
+
+describe("Phase 4 expose dual-dispatch — unit-managed", () => {
+  test("expose up unit-managed → ensureHubUnit (not detached spawn) + driveModuleOp(restart) for vault", async () => {
+    const h = makeHarness();
+    try {
+      seedServices(h.manifestPath);
+      const { runner } = makeRunner();
+      const sup = makeExposeSupervisorStub();
+      const logs: string[] = [];
+      const code = await exposeTailnet("up", {
+        runner,
+        manifestPath: h.manifestPath,
+        statePath: h.statePath,
+        wellKnownPath: h.wellKnownPath,
+        hubPath: h.hubPath,
+        configDir: h.configDir,
+        servicePortProbe: allServicesUp,
+        supervisor: sup.opts,
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      // Ensured the hub UNIT (the detached hub spawner was never invoked).
+      expect(sup.ensureCalls).toHaveLength(1);
+      // Post-expose vault restart drove the supervisor, not lifecycle.restart.
+      expect(sup.driveCalls).toEqual([{ short: "vault", op: "restart" }]);
+      // The operator-token issuer self-heal fired toward the public origin.
+      expect(sup.selfHealCalls).toHaveLength(1);
+      expect(sup.selfHealCalls[0]?.issuer).toMatch(/^https:\/\//);
+      expect(logs.join("\n")).toMatch(/hub unit up/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("expose up unit-managed: ensureHubUnit failure aborts before exposing", async () => {
+    const h = makeHarness();
+    try {
+      seedServices(h.manifestPath);
+      const { runner, calls } = makeRunner();
+      const sup = makeExposeSupervisorStub({ ensureOutcome: "no-manager" });
+      const code = await exposeTailnet("up", {
+        runner,
+        manifestPath: h.manifestPath,
+        statePath: h.statePath,
+        wellKnownPath: h.wellKnownPath,
+        hubPath: h.hubPath,
+        configDir: h.configDir,
+        servicePortProbe: allServicesUp,
+        supervisor: sup.opts,
+        log: () => {},
+      });
+      expect(code).toBe(1);
+      // Never ran the tailscale bringup — we bailed on the failed ensure.
+      expect(calls.filter((c) => c[0] === "tailscale" && c[1] === "serve")).toHaveLength(0);
+      expect(sup.driveCalls).toHaveLength(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("expose up unit-managed: a not_supervised vault (404) is not a failure", async () => {
+    const h = makeHarness();
+    try {
+      seedServices(h.manifestPath);
+      const { runner } = makeRunner();
+      const sup = makeExposeSupervisorStub({
+        driveThrows: () => new ModuleOpHttpError(404, "not_supervised", "vault is not supervised"),
+      });
+      const code = await exposeTailnet("up", {
+        runner,
+        manifestPath: h.manifestPath,
+        statePath: h.statePath,
+        wellKnownPath: h.wellKnownPath,
+        hubPath: h.hubPath,
+        configDir: h.configDir,
+        servicePortProbe: allServicesUp,
+        supervisor: sup.opts,
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      expect(sup.driveCalls).toEqual([{ short: "vault", op: "restart" }]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("expose off unit-managed → exposure torn down, hub NOT stopped, no 'hub stopped' line", async () => {
+    const h = makeHarness();
+    try {
+      writeExposeState(
+        {
+          version: 1,
+          layer: "tailnet",
+          mode: "path",
+          canonicalFqdn: "parachute.taildf9ce2.ts.net",
+          port: 443,
+          funnel: false,
+          entries: [{ kind: "proxy", mount: "/", target: "http://127.0.0.1:1939", service: "hub" }],
+        },
+        h.statePath,
+      );
+      const { runner, calls } = makeRunner();
+      const sup = makeExposeSupervisorStub();
+      const logs: string[] = [];
+      const code = await exposeTailnet("off", {
+        runner,
+        statePath: h.statePath,
+        wellKnownPath: h.wellKnownPath,
+        hubPath: h.hubPath,
+        configDir: h.configDir,
+        supervisor: sup.opts,
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      // The exposure layer was torn down…
+      expect(calls.every((c) => c[c.length - 1] === "off" || c[1] === "version")).toBe(true);
+      expect(existsSync(h.statePath)).toBe(false);
+      // …but the hub was left running: no stop, no "hub stopped" line.
+      expect(logs.join("\n")).not.toMatch(/hub stopped/);
+      expect(logs.join("\n")).toMatch(/exposure removed/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // The "expose off NO unit → hub stopped (detached arm)" test was removed: Phase
+  // 5b retired the detached arm, so `expose off` NEVER stops the hub (D3). The
+  // "exposure torn down, hub NOT stopped" invariant is the test above + the
+  // "leaves the hub running (D3)" test in the `expose tailnet off` suite.
+});