@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/commands/expose-cloudflare.ts

@@ -47,21 +47,21 @@ import {
   clearExposeState,
   writeExposeState,
 } from "../expose-state.ts";
-import {
-  type EnsureHubOpts,
-  HUB_DEFAULT_PORT,
-  ensureHubRunning,
-  readHubPort,
-} from "../hub-control.ts";
+import { HUB_DEFAULT_PORT, readHubPort } from "../hub-control.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
-import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
+import { HUB_UNIT_DEFAULT_PORT } from "../hub-unit.ts";
+import { type AliveFn, defaultAlive } from "../process-state.ts";
 import { readManifest } from "../services-manifest.ts";
 import { type Runner, defaultRunner } from "../tailscale/run.ts";
-import { persistVaultHubOrigin } from "../vault-hub-origin-env.ts";
 import type { VaultAuthStatus } from "../vault/auth-status.ts";
-import { WELL_KNOWN_DIR } from "../well-known.ts";
 import { printPublic2FAWarning } from "./expose-2fa-warning.ts";
-import { restart } from "./lifecycle.ts";
+import {
+  type ExposeSupervisorOpts,
+  type ResolvedExposeSupervisor,
+  ensureHubUnitForExpose,
+  resolveExposeSupervisor,
+  restartHubDependentViaSupervisor,
+} from "./expose-supervisor.ts";
 
 const AUTH_DOC_URL =
   "https://github.com/ParachuteComputer/parachute-vault/blob/main/docs/auth-model.md";
@@ -325,8 +325,8 @@ export interface ExposeCloudflareOpts {
   cloudflaredHome?: string;
   /**
    * Config root for hub PID / port / log files. Defaults to `~/.parachute`.
-   * Threaded into `ensureHubRunning` so cloudflared's ingress target stays
-   * in sync with where the hub actually bound.
+   * Threaded through so cloudflared's ingress target stays in sync with where
+   * the hub actually bound.
    */
   configDir?: string;
   /**
@@ -336,22 +336,10 @@ export interface ExposeCloudflareOpts {
    */
   hubOrigin?: string;
   /**
-   * Overrides for hub lifecycle — primarily for tests. Tests pass
-   * `skipHubLifecycle: true` (above) plus a seeded `hub.port` file so the
-   * cloudflare path can resolve a port without actually spawning a hub.
-   */
-  hubEnsureOpts?: Omit<EnsureHubOpts, "configDir" | "wellKnownDir" | "log">;
-  /**
-   * Directory holding hub.html (passed through to the hub server on first
-   * spawn). Defaults to the same `well-known/` resolution the Tailscale
-   * path uses.
-   */
-  wellKnownDir?: string;
-  /**
-   * Skip spawning the hub server. Tests flip this on and pre-seed
+   * Skip ensuring the hub unit. Tests flip this on and pre-seed
    * `<configDir>/hub/run/hub.port` so `readHubPort` can resolve the
-   * cloudflared target without a live process. Production always leaves
-   * this off so the bringup self-heals a missing hub.
+   * cloudflared target without a live hub. Production always leaves this off so
+   * the bringup ensures the hub unit is up.
    */
   skipHub?: boolean;
   now?: () => Date;
@@ -368,13 +356,20 @@ export interface ExposeCloudflareOpts {
    */
   vaultAuthStatus?: VaultAuthStatus;
   /**
-   * Restart a hub-dependent service so it re-reads the new public hub origin.
-   * Mirrors the Tailscale path's `restartService` seam (`expose.ts`). Defaults
-   * to lifecycle `restart`; tests inject a fake to assert the call without
-   * spawning a real daemon. Only invoked for vault (the only `iss`-validating
-   * service) and only when it's already running.
+   * Supervisor-path seams (design §4.3) — the ONLY runtime as of Phase 5b.
+   * "ensure the hub" ensures the UNIT is up (not a detached spawn), and the
+   * post-route vault restart drives the running Supervisor over the loopback
+   * module-ops API (re-injecting the new public origin + firing the operator-
+   * token / vault `.env` self-heal). The cloudflared CONNECTOR unit is
+   * unchanged — it already installs/removes its own ManagedUnit
+   * (`installConnectorService` / `removeConnectorService`), independent of the
+   * hub's lifecycle.
+   *
+   * Production CLI dispatch passes `supervisor: {}` so the real
+   * `isHubUnitInstalled` probe resolves the seams; tests inject the seams they
+   * want to assert.
    */
-  restartService?: (short: string) => Promise<number>;
+  supervisor?: ExposeSupervisorOpts;
 }
 
 interface Resolved {
@@ -400,13 +395,11 @@ interface Resolved {
   cloudflaredHome: string;
   configDir: string;
   hubOrigin: string | undefined;
-  hubEnsureOpts: Omit<EnsureHubOpts, "configDir" | "wellKnownDir" | "log">;
-  wellKnownDir: string;
   skipHub: boolean;
   now: () => Date;
   vaultHome: string | undefined;
   vaultAuthStatus: VaultAuthStatus | undefined;
-  restartService: (short: string) => Promise<number>;
+  sup: ResolvedExposeSupervisor;
 }
 
 /**
@@ -488,20 +481,11 @@ function resolve(opts: ExposeCloudflareOpts, tunnelNameDefault: string): Resolve
     cloudflaredHome: opts.cloudflaredHome ?? DEFAULT_CLOUDFLARED_HOME,
     configDir,
     hubOrigin: opts.hubOrigin,
-    hubEnsureOpts: opts.hubEnsureOpts ?? {},
-    wellKnownDir: opts.wellKnownDir ?? WELL_KNOWN_DIR,
     skipHub: opts.skipHub ?? false,
     now: opts.now ?? (() => new Date()),
     vaultHome: opts.vaultHome,
     vaultAuthStatus: opts.vaultAuthStatus,
-    restartService:
-      opts.restartService ??
-      ((short: string) =>
-        restart(short, {
-          manifestPath: opts.manifestPath,
-          configDir,
-          log: opts.log ?? (() => {}),
-        })),
+    sup: resolveExposeSupervisor(opts.supervisor),
   };
 }
 
@@ -656,17 +640,16 @@ export async function exposeCloudflareUp(
     }
     hubPort = existing;
   } else {
-    const hub = await ensureHubRunning({
-      reservedPorts: manifest.services.map((s) => s.port),
-      ...r.hubEnsureOpts,
-      configDir: r.configDir,
-      wellKnownDir: r.wellKnownDir,
-      issuer: hubOrigin,
-      log: r.log,
-    });
-    hubPort = hub.port;
-    if (hub.started) r.log(`✓ hub started (pid ${hub.pid}, port ${hub.port}).`);
-    else r.log(`✓ hub already running (pid ${hub.pid}, port ${hub.port}).`);
+    // §4.3a: "ensure the hub" = ensure the hub UNIT is up. The unit pins the
+    // canonical 1939 (no walking fallback), so that's the target cloudflared's
+    // ingress proxies to. Phase 5b retired the detached `ensureHubRunning`
+    // bringup — a box with no hub unit gets `ensureHubUnit`'s actionable "run
+    // `parachute migrate`" message, never a detached spawn.
+    const probePort = readHubPort(r.configDir) ?? HUB_UNIT_DEFAULT_PORT;
+    const ensured = await ensureHubUnitForExpose(r.sup, probePort, r.log);
+    if (!ensured.ok) return 1;
+    hubPort = ensured.port;
+    r.log(`✓ hub unit up (port ${hubPort}).`);
   }
   if (hubPort === 0) hubPort = HUB_DEFAULT_PORT;
 
@@ -909,20 +892,29 @@ export async function exposeCloudflareUp(
   // is the public origin) failed the `iss` check → 401 → "You're not signed in
   // to the hub." We mirror the Tailscale path here exactly.
   //
-  // `persistVaultHubOrigin` writes the durable `.env` (skips loopback itself,
-  // so a `--hub-origin http://127.0.0.1` override never bakes a dead issuer in);
-  // the restart makes the running vault re-read it immediately rather than
-  // waiting for the next reboot.
-  persistVaultHubOrigin(r.configDir, hubOrigin, r.log);
-  if (processState("vault", r.configDir, r.alive).status === "running") {
-    r.log("");
-    r.log("Restarting vault to pick up new hub origin…");
-    const rcode = await r.restartService("vault");
-    if (rcode !== 0) {
-      r.log(
-        "⚠ vault restart failed. Run manually once the issue is resolved: parachute restart vault",
-      );
-    }
+  // The supervised restart helper writes the durable `.env` (skipping loopback,
+  // so a `--hub-origin http://127.0.0.1` override never bakes a dead issuer in)
+  // and makes the running vault re-read it immediately rather than waiting for
+  // the next reboot.
+  //
+  // §4.3c: drive the restart through the running Supervisor
+  // (`driveModuleOp("vault", "restart")`), which re-injects the hub's current
+  // origin; `restartHubDependentViaSupervisor` also persists the durable `.env`
+  // + self-heals the operator-token issuer. Phase 5b retired the detached
+  // `lifecycle.restart` arm.
+  r.log("");
+  r.log("Restarting vault to pick up new hub origin…");
+  const rcode = await restartHubDependentViaSupervisor({
+    short: "vault",
+    hubOrigin,
+    configDir: r.configDir,
+    sup: r.sup,
+    log: r.log,
+  });
+  if (rcode !== 0) {
+    r.log(
+      "⚠ vault restart failed. Run manually once the issue is resolved: parachute restart vault",
+    );
   }
 
   const baseUrl = `https://${hostname}`;

package/src/commands/expose-supervisor.ts

@@ -0,0 +1,247 @@
+/**
+ * Expose-path supervisor seams (design
+ * `parachute.computer/design/2026-06-01-hub-as-supervisor-unification.md` §4.3).
+ *
+ * Under the hub-as-supervisor unification, `expose` / `expose off` are decoupled
+ * from the hub's lifecycle. As of Phase 5b the supervised path is the ONLY
+ * runtime:
+ *   - "ensure the hub" means "ensure the hub UNIT is up" (`ensureHubUnit`); a box
+ *     with no unit gets `ensureHubUnit`'s actionable "run `parachute migrate`"
+ *     message rather than a detached spawn.
+ *   - the post-expose hub-dependent service restart goes through the RUNNING
+ *     hub's in-process Supervisor over the loopback module-ops API
+ *     (`driveModuleOp(short, "restart")`), NOT a detached `lifecycle.restart`.
+ *
+ * This module is the shared seam BOTH `expose.ts` (Tailscale) and
+ * `expose-cloudflare.ts` (cloudflared) use so the two paths can't drift.
+ */
+
+import { readHubPort } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  type EnsureHubUnitOpts,
+  type EnsureHubUnitResult,
+  HUB_UNIT_DEFAULT_PORT,
+  type HubUnitDeps,
+  defaultHubUnitDeps,
+  ensureHubUnit as ensureHubUnitImpl,
+} from "../hub-unit.ts";
+import {
+  type DriveModuleOpDeps,
+  type ModuleOp,
+  ModuleOpHttpError,
+  type ModuleOpResult,
+  NoOperatorTokenError,
+  OperatorTokenExpiredError,
+  driveModuleOp as driveModuleOpImpl,
+} from "../module-ops-client.ts";
+import {
+  type OperatorIssuerHealStatus,
+  selfHealOperatorTokenIssuer as selfHealOperatorTokenIssuerImpl,
+} from "../operator-token.ts";
+import { persistVaultHubOrigin, selfHealVaultHubOrigin } from "../vault-hub-origin-env.ts";
+
+/**
+ * Injectable supervisor-path seams shared by the Tailscale + cloudflared expose
+ * paths. Mirrors `LifecycleOpts.supervisor`: everything is injectable so tests
+ * can assert the `ensureHubUnit` / `driveModuleOp` / operator-token-self-heal
+ * calls without a live hub or a real launchd/systemd. Production wires the real
+ * impls against an opened hub.db + the resolved hub origin; the CLI dispatch
+ * passes `supervisor: {}`.
+ */
+export interface ExposeSupervisorOpts {
+  /** Deps for the ensure-hub-unit call + the module-op self-heal. */
+  hubUnitDeps?: HubUnitDeps;
+  /** Ensure the hub unit is up before / during expose (§3.2 / §4.3a). */
+  ensureHubUnit?: (opts: EnsureHubUnitOpts) => Promise<EnsureHubUnitResult>;
+  /** Drive a per-module op against the running hub (reads operator.token). */
+  driveModuleOp?: (short: string, op: ModuleOp, deps: DriveModuleOpDeps) => Promise<ModuleOpResult>;
+  /**
+   * Open the hub DB used to validate/auto-rotate the operator token in
+   * `driveModuleOp` + to self-heal its issuer. Production opens
+   * `<configDir>/hub.db`; tests inject an in-memory/seeded db. Returns a handle
+   * the caller closes.
+   */
+  openDb?: (configDir: string) => import("bun:sqlite").Database;
+  /**
+   * Self-heal the operator token's stale `iss` toward the new public origin
+   * BEFORE the supervised restart (§4.3c). After `expose up` the running hub
+   * re-resolves its issuer to the public origin, so a loopback-minted operator
+   * token must be re-minted under that origin or the CLI's own `driveModuleOp`
+   * would fail iss-validation. Mirrors lifecycle's `selfHealOperatorTokenOnStart`.
+   * Production delegates to `selfHealOperatorTokenIssuer`; tests inject a stub.
+   */
+  selfHealOperatorTokenIssuer?: (
+    db: import("bun:sqlite").Database,
+    opts: { issuer: string; configDir: string; log: (line: string) => void },
+  ) => Promise<OperatorIssuerHealStatus>;
+  /** Loopback hub base URL override (default derives from the hub port). */
+  baseUrl?: string;
+}
+
+/** Resolved expose supervisor-path seams (see {@link ExposeSupervisorOpts}). */
+export interface ResolvedExposeSupervisor {
+  hubUnitDeps: HubUnitDeps;
+  ensureHubUnit: (opts: EnsureHubUnitOpts) => Promise<EnsureHubUnitResult>;
+  driveModuleOp: (short: string, op: ModuleOp, deps: DriveModuleOpDeps) => Promise<ModuleOpResult>;
+  openDb: (configDir: string) => import("bun:sqlite").Database;
+  selfHealOperatorTokenIssuer: (
+    db: import("bun:sqlite").Database,
+    opts: { issuer: string; configDir: string; log: (line: string) => void },
+  ) => Promise<OperatorIssuerHealStatus>;
+  baseUrl: string | undefined;
+}
+
+/**
+ * Resolve the expose supervisor seams. Production passes `supervisor: {}` (or
+ * omits it) and gets the real impls; tests inject the seams they want to assert.
+ * Phase 5b retired the dual-dispatch discriminant — the supervised path is the
+ * only runtime, so there is no longer an `isHubUnitInstalled` probe here.
+ */
+export function resolveExposeSupervisor(
+  opts: ExposeSupervisorOpts | undefined,
+): ResolvedExposeSupervisor {
+  const hubUnitDeps = opts?.hubUnitDeps ?? defaultHubUnitDeps;
+  return {
+    hubUnitDeps,
+    ensureHubUnit: opts?.ensureHubUnit ?? ensureHubUnitImpl,
+    driveModuleOp: opts?.driveModuleOp ?? driveModuleOpImpl,
+    openDb: opts?.openDb ?? ((configDir) => openHubDb(hubDbPath(configDir))),
+    selfHealOperatorTokenIssuer:
+      opts?.selfHealOperatorTokenIssuer ?? selfHealOperatorTokenIssuerImpl,
+    baseUrl: opts?.baseUrl,
+  };
+}
+
+/**
+ * Resolve the issuer the operator token's `iss` is validated against on the
+ * loopback module-ops call. Mirrors lifecycle's `resolveOperatorTokenIssuer`:
+ * the operator token ALWAYS carries an `iss`, so this falls back to the
+ * canonical loopback origin (`http://127.0.0.1:<hubPort>`) when no public
+ * origin is known. The CLI hits the hub on loopback, and the hub validates the
+ * bearer against its per-request issuer — which for a loopback request is the
+ * loopback origin — so the operator token must remain validatable there.
+ */
+function resolveExposeOperatorTokenIssuer(
+  hubOrigin: string | undefined,
+  configDir: string,
+): string {
+  if (hubOrigin) return hubOrigin;
+  const port = readHubPort(configDir) ?? HUB_UNIT_DEFAULT_PORT;
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * Ensure the hub UNIT is up for an expose, mapping `ensureHubUnit`'s structured
+ * outcome to a simple ok/not-ok the caller turns into an exit code. Returns the
+ * probed port so the caller can plan tailscale/cloudflared against it (§4.3a:
+ * tailscale needs only the hub reachable on loopback, which the unit
+ * guarantees). On a non-up outcome the messages are surfaced.
+ */
+export async function ensureHubUnitForExpose(
+  sup: ResolvedExposeSupervisor,
+  port: number,
+  log: (line: string) => void,
+): Promise<{ ok: boolean; port: number }> {
+  const ensured = await sup.ensureHubUnit({ port, deps: sup.hubUnitDeps, log });
+  if (ensured.outcome === "already-up" || ensured.outcome === "started") {
+    return { ok: true, port: ensured.port };
+  }
+  for (const m of ensured.messages) log(m);
+  return { ok: false, port: ensured.port };
+}
+
+/**
+ * Restart a hub-dependent service (today: vault) via the running hub's
+ * Supervisor after an expose changed the public origin (§4.3c). The supervised
+ * restart re-injects the hub's current per-request-resolved origin into the
+ * module's env; this helper ALSO fires the durable origin self-heals that the
+ * detached `lifecycle.restart` path used to provide:
+ *   - `selfHealOperatorTokenIssuer` — re-mint the operator token under the new
+ *     public origin BEFORE the module-op, so the CLI's own `driveModuleOp`
+ *     bearer validates (and a later supervised restart's iss is current).
+ *   - `persistVaultHubOrigin` / `selfHealVaultHubOrigin` — write the public
+ *     origin into vault's `.env` so a future out-of-band boot also validates.
+ *
+ * Returns the module-op exit code (0 on success). Errors are surfaced as
+ * actionable lines (never a raw 401 / thrown HTTP error) and mapped to a
+ * non-zero code so the caller can warn-and-continue exactly as the detached
+ * restart path does.
+ */
+export async function restartHubDependentViaSupervisor(args: {
+  short: string;
+  hubOrigin: string;
+  configDir: string;
+  sup: ResolvedExposeSupervisor;
+  log: (line: string) => void;
+}): Promise<number> {
+  const { short, hubOrigin, configDir, sup, log } = args;
+  const issuer = resolveExposeOperatorTokenIssuer(hubOrigin, configDir);
+  const db = sup.openDb(configDir);
+  try {
+    // Self-heal the operator token's iss toward the NEW public origin first, so
+    // the bearer the CLI presents on the loopback module-op validates and a
+    // subsequent supervised restart's injected iss is current. The loopback /
+    // provenance guards live inside `selfHealOperatorTokenIssuer`, so passing
+    // the resolved (possibly loopback) origin is safe — it no-ops on loopback.
+    try {
+      const status = await sup.selfHealOperatorTokenIssuer(db, {
+        issuer: hubOrigin,
+        configDir,
+        log,
+      });
+      if (status.kind === "rotated") {
+        log(`  refreshed operator.token issuer → ${hubOrigin} (was stale after exposure)`);
+      }
+    } catch (err) {
+      // A self-heal failure must never block the restart — degrade to a note.
+      log(
+        `  note: operator.token issuer self-heal skipped (${
+          err instanceof Error ? err.message : String(err)
+        })`,
+      );
+    }
+    // Durable .env persistence + vault-side self-heal (parity with the detached
+    // `persistVaultHubOriginForStart`). Both are called for parity with that
+    // detached path: `persistVaultHubOrigin` is the PRIMARY write — it stamps
+    // the new public origin into vault's `.env` (skipping loopback / unchanged
+    // values itself). `selfHealVaultHubOrigin` is a deliberate no-op in the
+    // normal case here — persist just wrote the public origin, so selfHeal's
+    // `current !== undefined && !isLoopbackOrigin(current)` guard short-circuits.
+    // It only fires for OLD installs where `.env` was left stale-loopback (the
+    // persist write can be skipped on edge cases), keeping the pair behaviorally
+    // identical to the detached path.
+    if (short === "vault") {
+      persistVaultHubOrigin(configDir, hubOrigin, log);
+      selfHealVaultHubOrigin(configDir, log, `${configDir}/expose-state.json`);
+    }
+
+    const deps: DriveModuleOpDeps = {
+      db,
+      issuer,
+      configDir,
+      ...(sup.baseUrl !== undefined ? { baseUrl: sup.baseUrl } : {}),
+    };
+    try {
+      await sup.driveModuleOp(short, "restart", deps);
+      return 0;
+    } catch (err) {
+      if (err instanceof NoOperatorTokenError || err instanceof OperatorTokenExpiredError) {
+        log(`✗ ${short}: ${err.message}`);
+        return 1;
+      }
+      if (err instanceof ModuleOpHttpError) {
+        // A not-supervised module (404) after an expose just means it wasn't
+        // running — the detached path's `processState !== running` guard simply
+        // skips it. Treat 404 the same: nothing to restart, not a failure.
+        if (err.status === 404 && err.code === "not_supervised") return 0;
+        log(`✗ ${short}: ${err.message}`);
+        return 1;
+      }
+      log(`✗ ${short}: ${err instanceof Error ? err.message : String(err)}`);
+      return 1;
+    }
+  } finally {
+    db.close();
+  }
+}

package/src/commands/expose.ts

@@ -8,17 +8,10 @@ import {
   readExposeState,
   writeExposeState,
 } from "../expose-state.ts";
-import {
-  type EnsureHubOpts,
-  type StopHubOpts,
-  defaultPortProbe,
-  ensureHubRunning,
-  readHubPort,
-  stopHub,
-} from "../hub-control.ts";
+import { defaultPortProbe, readHubPort } from "../hub-control.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
+import { HUB_UNIT_DEFAULT_PORT } from "../hub-unit.ts";
 import { HUB_PATH, writeHubFile } from "../hub.ts";
-import { type AliveFn, processState } from "../process-state.ts";
 import { shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
 import { type ServeEntry, bringupCommand, teardownCommand } from "../tailscale/commands.ts";
@@ -27,7 +20,6 @@ import { type Runner, defaultRunner } from "../tailscale/run.ts";
 import { clearVaultHubOrigin } from "../vault-hub-origin-env.ts";
 import type { VaultAuthStatus } from "../vault/auth-status.ts";
 import {
-  WELL_KNOWN_DIR,
   WELL_KNOWN_MOUNT,
   WELL_KNOWN_PATH,
   buildWellKnown,
@@ -35,7 +27,12 @@ import {
   writeWellKnownFile,
 } from "../well-known.ts";
 import { printPublic2FAWarning } from "./expose-2fa-warning.ts";
-import { restart } from "./lifecycle.ts";
+import {
+  type ExposeSupervisorOpts,
+  ensureHubUnitForExpose,
+  resolveExposeSupervisor,
+  restartHubDependentViaSupervisor,
+} from "./expose-supervisor.ts";
 
 /**
  * Two exposure layers share a single tailscale serve config on this node.
@@ -67,17 +64,12 @@ export interface ExposeOpts {
   statePath?: string;
   wellKnownPath?: string;
   hubPath?: string;
-  /** Directory holding hub.html (passed to the hub server). */
-  wellKnownDir?: string;
   configDir?: string;
   port?: number;
   log?: (line: string) => void;
   /** Override detected FQDN — primarily for tests. */
   fqdnOverride?: string;
-  /** Overrides for the hub lifecycle — primarily for tests. */
-  hubEnsureOpts?: Omit<EnsureHubOpts, "configDir" | "wellKnownDir" | "log">;
-  hubStopOpts?: Omit<StopHubOpts, "configDir" | "log">;
-  /** Skip spawning the hub server. Tests flip this off to verify it's called. */
+  /** Skip ensuring the hub unit. Tests seed a `hub.port` and flip this on. */
   skipHub?: boolean;
   /**
    * Probe a port to decide whether a service is responding. Returns true when
@@ -93,14 +85,6 @@ export interface ExposeOpts {
    * through to vault (and future services) via PARACHUTE_HUB_ORIGIN.
    */
   hubOrigin?: string;
-  /** Process-liveness check for auto-restart — test seam. */
-  alive?: AliveFn;
-  /**
-   * Restart a service by short name after exposure changes. Defaults to the
-   * lifecycle `restart`; tests inject a fake to assert the call without
-   * spawning real child processes.
-   */
-  restartService?: (short: string) => Promise<number>;
   /**
    * Override `~/.parachute/vault` for the 2FA-enrollment probe on the public
    * (Funnel) layer. Tests point at a tmp dir; production omits and the probe
@@ -113,6 +97,20 @@ export interface ExposeOpts {
    * `<vaultHome>/config.yaml` from disk. (#186)
    */
   vaultAuthStatus?: VaultAuthStatus;
+  /**
+   * Supervisor-path seams (design §4.3) — the ONLY runtime as of Phase 5b.
+   * `expose` "ensures the hub" by ensuring the UNIT is up (not a detached spawn),
+   * the post-expose hub-dependent restart drives the running Supervisor over the
+   * loopback module-ops API, and `expose off` leaves the hub RUNNING (a managed
+   * hub with Restart=always/KeepAlive would just respawn a stopped one — D3).
+   * A box with no hub unit gets `ensureHubUnit`'s actionable "run `parachute
+   * migrate`" message rather than a detached spawn.
+   *
+   * The production CLI dispatch passes `supervisor: {}` so the real
+   * `isHubUnitInstalled` probe resolves the seams; tests inject the seams they
+   * want to assert.
+   */
+  supervisor?: ExposeSupervisorOpts;
 }
 
 /**
@@ -235,11 +233,14 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
   const statePath = opts.statePath ?? EXPOSE_STATE_PATH;
   const wellKnownFilePath = opts.wellKnownPath ?? WELL_KNOWN_PATH;
   const hubFilePath = opts.hubPath ?? HUB_PATH;
-  const wellKnownDir = opts.wellKnownDir ?? WELL_KNOWN_DIR;
   const configDir = opts.configDir ?? CONFIG_DIR;
   const port = opts.port ?? 443;
   const log = opts.log ?? ((line) => console.log(line));
   const funnel = layer === "public";
+  // §4.3: ensure the hub UNIT is up (it guarantees loopback reachability) +
+  // restart hub-dependent services via the Supervisor. The detached arm was
+  // retired in Phase 5b.
+  const sup = resolveExposeSupervisor(opts.supervisor);
 
   if (!(await isTailscaleInstalled(runner))) {
     log("tailscale is not installed or not on PATH.");
@@ -320,17 +321,17 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
     }
     hubPort = existing;
   } else {
-    const hub = await ensureHubRunning({
-      reservedPorts: manifest.services.map((s) => s.port),
-      ...(opts.hubEnsureOpts ?? {}),
-      configDir,
-      wellKnownDir,
-      issuer: hubOrigin,
-      log,
-    });
-    hubPort = hub.port;
-    if (hub.started) log(`✓ hub started (pid ${hub.pid}, port ${hub.port}).`);
-    else log(`✓ hub already running (pid ${hub.pid}, port ${hub.port}).`);
+    // §4.3a: "ensure the hub" = ensure the hub UNIT is up. The unit guarantees
+    // the hub is reachable on loopback (all tailscale needs); it pins the
+    // canonical 1939 (no walking fallback), so that's the target. Phase 5b
+    // retired the detached `ensureHubRunning` bringup — a box with no hub unit
+    // gets `ensureHubUnit`'s actionable "run `parachute migrate`" message, never
+    // a detached spawn.
+    const probePort = readHubPort(configDir) ?? HUB_UNIT_DEFAULT_PORT;
+    const ensured = await ensureHubUnitForExpose(sup, probePort, log);
+    if (!ensured.ok) return 1;
+    hubPort = ensured.port;
+    log(`✓ hub unit up (port ${hubPort}).`);
   }
 
   const entries = planEntries(hubPort);
@@ -392,13 +393,20 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
   // claude.ai MCP failed with a cryptic "Couldn't reach the MCP server". The
   // old output told the user to restart manually; it got buried in the wall
   // of expose output. Do the restart ourselves.
-  const doRestart =
-    opts.restartService ?? ((short: string) => restart(short, { manifestPath, configDir, log }));
+  // §4.3c: the hub-dependent restart goes through the running Supervisor
+  // (`driveModuleOp(short, "restart")`), which re-injects the hub's current
+  // origin; the origin self-heal (operator-token iss + vault `.env`) fires there.
+  // Phase 5b retired the detached `lifecycle.restart` arm.
   for (const short of HUB_DEPENDENT_SHORTS) {
-    if (processState(short, configDir, opts.alive).status !== "running") continue;
     log("");
     log(`Restarting ${short} to pick up new hub origin…`);
-    const rcode = await doRestart(short);
+    const rcode = await restartHubDependentViaSupervisor({
+      short,
+      hubOrigin,
+      configDir,
+      sup,
+      log,
+    });
     if (rcode !== 0) {
       log(
         `⚠ ${short} restart failed. Run manually once the issue is resolved: parachute restart ${short}`,
@@ -415,6 +423,10 @@ export async function exposeOff(layer: ExposeLayer, opts: ExposeOpts = {}): Prom
   const hubFilePath = opts.hubPath ?? HUB_PATH;
   const configDir = opts.configDir ?? CONFIG_DIR;
   const log = opts.log ?? ((line) => console.log(line));
+  // D3 (§4.3a): `expose off` tears down ONLY the exposure layer and leaves the
+  // hub running — the hub is a persistent platform unit now, so stopping it
+  // would just be respawned by the manager. The detached `stopHub` arm was
+  // retired in Phase 5b, so there is no longer any hub-lifecycle dispatch here.
 
   const state = readExposeState(statePath);
   if (!state || state.entries.length === 0) {
@@ -455,13 +467,12 @@ export async function exposeOff(layer: ExposeLayer, opts: ExposeOpts = {}): Prom
     unlinkSync(hubFilePath);
   }
 
-  // Hub lives only as long as some layer is exposed. State was just cleared,
-  // so no layer is active — stop the hub. (Layer switch doesn't go through
-  // here; that path reuses the running hub.)
-  if (!opts.skipHub) {
-    const stopped = await stopHub({ ...(opts.hubStopOpts ?? {}), configDir, log });
-    if (stopped) log("✓ hub stopped.");
-  }
+  // D3 (§4.3a) — `expose off` no longer stops the hub. The hub is a persistent
+  // platform unit (Restart=always / KeepAlive) that runs whether or not a layer
+  // is exposed: the "hub exists only while exposed" invariant inverted under the
+  // supervised model, and the detached `stopHub` arm was retired in Phase 5b
+  // (stopping it would just be respawned by the manager). We tear down ONLY the
+  // exposure layer above and leave the hub running.
 
   log(`✓ ${layerLabel(layer)} exposure removed.`);
   return 0;