@openparachute/hub 0.6.3 → 0.6.4-rc.10

package/src/commands/expose-cloudflare.ts

@@ -51,8 +51,9 @@ import { HUB_DEFAULT_PORT, readHubPort } from "../hub-control.ts";
 import { deriveHubOrigin } from "../hub-origin.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 { readManifestLenient } from "../services-manifest.ts";
 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 { printPublic2FAWarning } from "./expose-2fa-warning.ts";
 import {
@@ -91,6 +92,22 @@ export function isValidHostname(h: string): boolean {
   return h.split(".").every((label) => labelRe.test(label));
 }
 
+/**
+ * Best-effort "is this module registered in services.json?" check, used only
+ * for the courtesy note in the Cloudflare expose path (hub#564). Uses the
+ * LENIENT manifest reader on purpose: the strict `readManifest` can reject an
+ * older manifest shape (the #564 diagnostic — a manifest written by 0.6.3-era
+ * registration that the strict reader bounced), and a courtesy note must never
+ * throw. Any read error is swallowed and treated as "not installed".
+ */
+function serviceInstalled(manifestPath: string, name: string): boolean {
+  try {
+    return readManifestLenient(manifestPath).services.some((s) => s.name === name);
+  } catch {
+    return false;
+  }
+}
+
 export interface CloudflaredSpawner {
   spawn(cmd: readonly string[], logFile: string): number;
 }
@@ -606,12 +623,18 @@ export async function exposeCloudflareUp(
     return 1;
   }
 
-  const manifest = readManifest(r.manifestPath);
-  const vaultEntry = manifest.services.find((s) => s.name === "parachute-vault");
-  if (!vaultEntry) {
-    r.log("parachute-vault is not installed; nothing to route.");
-    r.log("Run: parachute install vault");
-    return 1;
+  // No vault gate here (hub#564). cloudflared's ingress targets the HUB port
+  // (see `servicePort: hubPort` in `writeConfig` below + the long comment
+  // there) — the hub does ALL routing (discovery, admin, OAuth, well-known,
+  // per-vault proxy, generic /<svc>/* dispatch). Vault doesn't have to be
+  // installed for the tunnel to route anything. The old gate
+  // (`parachute-vault is not installed; nothing to route` → return 1) was a
+  // vestige of the pre-2026-05-27 vault-centric ingress, and it dead-ended
+  // fresh-server init: post-#168 init exposes (Step 2) BEFORE it installs the
+  // vault module (Step 2.5), so the gate always tripped on a fresh box and
+  // aborted the whole init. Courtesy note only — never block.
+  if (!serviceInstalled(r.manifestPath, "parachute-vault")) {
+    r.log("vault not installed yet — the admin wizard will set it up. Routing the hub anyway.");
   }
 
   // Resolve the public hub origin before spawning the hub server — it gets
@@ -897,45 +920,58 @@ export async function exposeCloudflareUp(
   // and makes the running vault re-read it immediately rather than waiting for
   // the next reboot.
   //
+  // hub#564: vault may not be installed yet (init exposes BEFORE installing the
+  // vault module). Resolve the entry once, here, and gate the vault-restart +
+  // the Vault-URL footer on it — restarting a not-installed vault would just
+  // fail and print a spurious warning. When present, a well-formed manifest
+  // always lists at least one mount path.
+  const vaultEntry = (() => {
+    try {
+      return readManifestLenient(r.manifestPath).services.find((s) => s.name === "parachute-vault");
+    } catch {
+      return undefined;
+    }
+  })();
+
   // §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",
-    );
+  // `lifecycle.restart` arm. Skipped entirely when vault isn't installed.
+  if (vaultEntry) {
+    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}`;
-  // A well-formed vault manifest always lists at least one mount path. If
-  // it's empty, something went sideways in `parachute install vault` — warn
-  // so the user can fix services.json rather than chasing a phantom 404 on
-  // /vault/default that may or may not exist.
-  if (!vaultEntry.paths[0]) {
-    r.log(
-      `⚠ vault entry in services.json has no paths[]; defaulting to "/vault/default". Check the manifest.`,
-    );
+  let vaultUrl: string | undefined;
+  if (vaultEntry) {
+    if (!vaultEntry.paths[0]) {
+      r.log(
+        `⚠ vault entry in services.json has no paths[]; defaulting to "/vault/default". Check the manifest.`,
+      );
+    }
+    vaultUrl = `${baseUrl}${vaultEntry.paths[0] ?? "/vault/default"}`;
   }
-  const vaultMount = vaultEntry.paths[0] ?? "/vault/default";
-  const vaultUrl = `${baseUrl}${vaultMount}`;
 
   r.log("");
   r.log(`✓ Cloudflare tunnel up (pid ${pid}).`);
   r.log(`  Tunnel:  ${r.tunnelName} (dedicated to this machine)`);
   r.log(`  Open:    ${baseUrl}/`);
   r.log(`  Admin:   ${baseUrl}/admin/`);
-  r.log(`  Vault:   ${vaultUrl}`);
+  if (vaultUrl) r.log(`  Vault:   ${vaultUrl}`);
   r.log(`  OAuth:   ${hubOrigin}`);
   r.log(`  Logs:    ${r.logPath}`);
   r.log("");
@@ -954,10 +990,14 @@ export async function exposeCloudflareUp(
     r.log("background but does NOT survive a reboot. After a reboot, re-run:");
     r.log(`  parachute expose public --cloudflare --domain ${hostname}`);
   }
-  r.log("");
-  r.log("Point a claude.ai / ChatGPT connector at:");
-  r.log(`  ${vaultUrl}`);
-  printAuthGuidance(r.log, vaultUrl);
+  // The connector guidance points at a vault MCP URL — only meaningful once a
+  // vault is installed (hub#564: it may not be yet, when init exposes first).
+  if (vaultUrl) {
+    r.log("");
+    r.log("Point a claude.ai / ChatGPT connector at:");
+    r.log(`  ${vaultUrl}`);
+    printAuthGuidance(r.log, vaultUrl);
+  }
   // 2FA-enrollment warning when /admin/login is now reachable on the public
   // internet but the operator hasn't enrolled TOTP. Cloudflare exposure is
   // always public; tailnet/funnel mirrors this in `expose.ts`. See #186.
@@ -1098,8 +1138,35 @@ export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Prom
   // downstream consumers stop resolving the now-dead public URL (mirrors the
   // up-path write above + the Tailscale off-path's expose-state teardown). When
   // other tunnels survive we leave it — a later off for the last one clears it.
+  //
+  // TODO(multi-tunnel) #588: with TWO CF tunnels up, tearing down the
+  // last-written-up one (whose hostname is what's in vault's `.env`) while the
+  // other survives leaves `.env` carrying the dead tunnel's origin while the
+  // surviving tunnel serves a different one → stale-iss on the next vault
+  // restart. Retention is still the only SAFE choice here: a single
+  // `PARACHUTE_HUB_ORIGIN` field can't represent "which surviving tunnel wins,"
+  // and clearing it would break the survivor's iss check. Properly fixing it
+  // needs re-resolving the effective origin from the survivor (or multi-origin
+  // issuer acceptance vault-side) — larger than the #503 single-tunnel fix, and
+  // multi-CF-tunnel-on-one-box is rare. See #588.
   if (!state) {
     clearExposeState(r.exposeStatePath);
+    // Drop the persisted PARACHUTE_HUB_ORIGIN from vault's `.env` (#503). With
+    // the last Cloudflare tunnel gone, the hub is loopback-only and mints
+    // loopback-`iss` tokens; a stale public origin left in `vault/.env` would
+    // pin a public expected issuer and 401 every request on the next vault
+    // daemon restart ("not signed in to the hub" — the inverse of the bug
+    // selfHealVaultHubOrigin closed). This mirrors exactly what the Tailscale
+    // off-path does (`exposeOff` in expose.ts) — the Cloudflare path had been
+    // the asymmetric gap. expose-state's own `hubOrigin` is cleared above via
+    // clearExposeState, so hub's per-request `resolveIssuer`/`exposeIssuerOrigin`
+    // (which read expose-state) also stop minting the public iss after teardown.
+    // No restart needed for the gap this closes — the next vault restart picks
+    // up the cleared `.env` — but tell the operator so an already-running vault
+    // doesn't keep validating against the now-dead public origin.
+    if (clearVaultHubOrigin(r.configDir, r.log)) {
+      r.log("  Restart vault to apply the loopback issuer now: `parachute restart vault`.");
+    }
   }
   return failed ? 1 : 0;
 }

package/src/commands/expose-interactive.ts

@@ -14,9 +14,16 @@ import { createInterface } from "node:readline/promises";
 import {
   DEFAULT_CLOUDFLARED_HOME,
   cloudflaredInstallHint,
+  cloudflaredLinuxDownloadUrl,
   isCloudflaredInstalled,
   isCloudflaredLoggedIn,
 } from "../cloudflare/detect.ts";
+import {
+  CLOUDFLARED_STATE_PATH,
+  clearPendingHostname,
+  readPendingHostname,
+  writePendingHostname,
+} from "../cloudflare/state.ts";
 import {
   EXPOSE_LAST_PROVIDER_PATH,
   type ExposeProvider,
@@ -73,6 +80,19 @@ export interface ExposeInteractiveOpts {
   prompt?: (question: string) => Promise<string>;
   cloudflaredHome?: string;
   platform?: NodeJS.Platform;
+  /** Test seam: `process.arch` — drives the Linux cloudflared download URL. */
+  arch?: NodeJS.Architecture;
+  /**
+   * Test seam: `process.getuid` — root (uid 0) can write
+   * /usr/local/bin/cloudflared directly; non-root needs `sudo`. Defaults to
+   * `process.getuid` (undefined on platforms without it → treated non-root).
+   */
+  getuid?: () => number;
+  /**
+   * Path to cloudflared-state.json (hub#567 pending-hostname persistence).
+   * Defaults to the canonical `CLOUDFLARED_STATE_PATH`.
+   */
+  statePath?: string;
   lastProviderPath?: string;
   now?: () => Date;
   log?: (line: string) => void;
@@ -110,6 +130,9 @@ interface Resolved {
   prompt: (question: string) => Promise<string>;
   cloudflaredHome: string;
   platform: NodeJS.Platform;
+  arch: NodeJS.Architecture;
+  getuid: () => number;
+  statePath: string;
   lastProviderPath: string;
   now: () => Date;
   log: (line: string) => void;
@@ -129,6 +152,10 @@ function resolve(opts: ExposeInteractiveOpts): Resolved {
     prompt: opts.prompt ?? defaultPrompt,
     cloudflaredHome: opts.cloudflaredHome ?? DEFAULT_CLOUDFLARED_HOME,
     platform: opts.platform ?? process.platform,
+    arch: opts.arch ?? process.arch,
+    // `process.getuid` is absent on Windows; treat missing as non-root (uid 1).
+    getuid: opts.getuid ?? (() => process.getuid?.() ?? 1),
+    statePath: opts.statePath ?? CLOUDFLARED_STATE_PATH,
     lastProviderPath: opts.lastProviderPath ?? EXPOSE_LAST_PROVIDER_PATH,
     now: opts.now ?? (() => new Date()),
     log: opts.log ?? ((line) => console.log(line)),
@@ -185,10 +212,25 @@ async function promptHostname(r: Resolved): Promise<string | undefined> {
   r.log("");
   r.log("Cloudflare needs a hostname under a domain you've added to your Cloudflare account.");
   r.log('Example: vault.example.com   (apex "example.com" must be a Cloudflare zone)');
+  // hub#567: pre-fill with a hostname the operator typed on a prior (failed)
+  // run so a retry is "press Enter", not "redo the whole interview".
+  const pending = readPendingHostname(r.statePath);
+  const promptText = pending
+    ? `Hostname [${pending}] (or blank to quit): `
+    : "Hostname (or blank to quit): ";
   for (let attempt = 0; attempt < 5; attempt++) {
-    const raw = (await r.prompt("Hostname (or blank to quit): ")).trim();
+    const raw = (await r.prompt(promptText)).trim();
+    // Enter on a pre-filled prompt accepts the stashed hostname.
+    if (raw === "" && pending) {
+      return pending;
+    }
     if (raw === "") return undefined;
-    if (isValidHostname(raw)) return raw;
+    if (isValidHostname(raw)) {
+      // Stash it the moment it validates so a downstream failure (cloudflared
+      // login, tunnel/DNS error) doesn't discard it. Cleared on success.
+      writePendingHostname(raw, r.statePath);
+      return raw;
+    }
     r.log(`"${raw}" doesn't look like a hostname. Expected something like vault.example.com.`);
   }
   r.log("Too many invalid entries; aborting.");
@@ -238,11 +280,99 @@ function printTailscaleSetupGuidance(r: Resolved, readiness: ProviderAvailabilit
   r.log("Once those are done, re-run: parachute expose public");
 }
 
+/**
+ * hub#566: offer to install cloudflared on Linux in place (instead of printing
+ * the command and bailing). The install is a single static-binary download
+ * (curl + chmod) we already know how to do.
+ *
+ *   - Confirm with `Install cloudflared now? [Y/n]` (Enter accepts).
+ *   - Run the curl into /usr/local/bin/cloudflared + chmod +x. Root writes
+ *     directly; non-root wraps each step in `sudo -n` (non-interactive — only
+ *     succeeds when sudo creds are already cached / passwordless). We use `-n`
+ *     deliberately: init often runs detached/unattended on a fresh server (SSH
+ *     + tmux, a cloud-init script), where a blocking interactive sudo password
+ *     prompt would hang the whole flow. `-n` fails fast instead, and we fall
+ *     back to printing the manual command.
+ *   - Verify with `cloudflared --version`.
+ *
+ * Returns true only when cloudflared is on PATH afterward. On decline, missing
+ * download URL (unknown arch), or any install/verify failure, prints the
+ * canonical manual instructions + the `--cloudflare` re-run hint and returns
+ * false. Per hub#565 the caller's `false` does NOT abort init.
+ */
+async function offerLinuxCloudflaredInstall(r: Resolved): Promise<boolean> {
+  r.log("");
+  r.log("Cloudflare Tunnel uses the `cloudflared` binary, which isn't installed yet.");
+  const downloadUrl = cloudflaredLinuxDownloadUrl(r.arch);
+
+  const printManualAndBail = () => {
+    r.log("");
+    for (const line of cloudflaredInstallHint("linux", r.arch).split("\n")) r.log(line);
+    r.log("");
+    r.log("After install, re-run: parachute expose public --cloudflare");
+  };
+
+  // No published artifact for this arch → can't auto-install; print + bail.
+  if (!downloadUrl) {
+    printManualAndBail();
+    return false;
+  }
+
+  const answer = (await r.prompt("Install cloudflared now? [Y/n] ")).trim().toLowerCase();
+  if (answer === "n" || answer === "no") {
+    r.log("Skipped auto-install.");
+    printManualAndBail();
+    return false;
+  }
+
+  const isRoot = r.getuid() === 0;
+  const dest = "/usr/local/bin/cloudflared";
+  // Root writes directly; non-root prefixes each privileged step with `sudo -n`
+  // (non-interactive). `-n` never prompts for a password: it exits non-zero
+  // when creds aren't cached, so a detached/unattended init (SSH + tmux, a
+  // cloud-init script) fails fast and falls back to the printed instructions
+  // rather than hanging on a password prompt nobody's there to answer.
+  const sudo = isRoot ? [] : ["sudo", "-n"];
+  const curlCmd = [...sudo, "curl", "-L", "-o", dest, downloadUrl];
+  const chmodCmd = [...sudo, "chmod", "+x", dest];
+
+  r.log("");
+  r.log(`Downloading cloudflared → ${dest} …`);
+  const curlCode = await r.interactiveRunner(curlCmd);
+  if (curlCode !== 0) {
+    r.log(`Download failed (exit ${curlCode}).`);
+    if (!isRoot) {
+      r.log(
+        "(`sudo -n` needs cached credentials; run `sudo -v` first, or use the commands below.)",
+      );
+    }
+    printManualAndBail();
+    return false;
+  }
+  const chmodCode = await r.interactiveRunner(chmodCmd);
+  if (chmodCode !== 0) {
+    r.log(`chmod failed (exit ${chmodCode}).`);
+    printManualAndBail();
+    return false;
+  }
+
+  if (!(await isCloudflaredInstalled(r.runner))) {
+    r.log("Install ran but `cloudflared` still isn't on PATH.");
+    r.log(
+      "Open a fresh shell (so PATH picks up the new binary), then re-run: parachute expose public --cloudflare",
+    );
+    return false;
+  }
+  r.log("✓ cloudflared installed.");
+  return true;
+}
+
 /**
  * Walks the user through installing and logging in cloudflared. On macOS we
- * auto-install via brew (with confirmation); on Linux we print manual-install
- * pointers and bail so the user can pick apt/dnf/tarball. Returns true only
- * when cloudflared is both present and logged in afterwards.
+ * auto-install via brew (with confirmation); on Linux we auto-install the
+ * static binary (hub#566) with confirmation; everywhere else we print
+ * manual-install pointers and bail. Returns true only when cloudflared is
+ * both present and logged in afterwards.
  */
 async function guideCloudflareSetup(
   r: Resolved,
@@ -259,7 +389,11 @@ async function guideCloudflareSetup(
         .trim()
         .toLowerCase();
       if (answer === "n" || answer === "no") {
-        r.log("Skipped auto-install. Install manually, then re-run: parachute expose public");
+        // hub#566: re-run with `--cloudflare` (bare `expose public` defaults
+        // to Tailscale Funnel, the wrong provider for someone who chose CF).
+        r.log(
+          "Skipped auto-install. Install manually, then re-run: parachute expose public --cloudflare",
+        );
         return false;
       }
       const code = await r.interactiveRunner(["brew", "install", "cloudflared"]);
@@ -273,20 +407,26 @@ async function guideCloudflareSetup(
         r.log("Open a fresh shell (so PATH picks up the new binary) and re-run.");
         return false;
       }
+    } else if (r.platform === "linux") {
+      // hub#566: on Linux the install is a single static-binary download we
+      // already know how to do — offer to run it in place instead of dumping
+      // the operator back to a shell. Auto-install requires root (write to
+      // /usr/local/bin) or a working passwordless `sudo -n`. If we can't, or
+      // the operator declines, fall back to printing the instructions (and
+      // per hub#565 init continues regardless of the `false` return here).
+      installed = await offerLinuxCloudflaredInstall(r);
+      if (!installed) return false;
     } else {
-      // 2026-05-27 refresh: distro-package paths (`apt-get`, `dnf`) are
-      // unreliable across versions — Aaron hit `No match for argument:
-      // cloudflared` on Amazon Linux 2023 — and the
-      // pkg.cloudflare.com / developers.cloudflare.com paths the old hint
-      // pointed at now serve HTML/404. Defer to `cloudflaredInstallHint`,
-      // which writes the canonical GitHub-release static-binary path
-      // matching the host's architecture.
+      // Non-darwin/linux (e.g. Windows / misc): no auto-install path. Print
+      // the canonical pointer and bail (init continues per hub#565).
       r.log("");
       r.log("Cloudflare Tunnel uses the `cloudflared` binary, which isn't installed yet.");
       r.log("");
-      for (const line of cloudflaredInstallHint(r.platform).split("\n")) r.log(line);
+      for (const line of cloudflaredInstallHint(r.platform, r.arch).split("\n")) r.log(line);
       r.log("");
-      r.log("After install, re-run: parachute expose public");
+      // hub#566: the bare `parachute expose public` defaults to Tailscale
+      // Funnel — an operator who chose Cloudflare must re-run with the flag.
+      r.log("After install, re-run: parachute expose public --cloudflare");
       return false;
     }
   }
@@ -310,7 +450,7 @@ async function guideCloudflareSetup(
     loggedIn = isCloudflaredLoggedIn(r.cloudflaredHome);
     if (!loggedIn) {
       r.log("Login ran but cert.pem didn't appear in ~/.cloudflared.");
-      r.log("Check the browser flow completed, then re-run: parachute expose public");
+      r.log("Check the browser flow completed, then re-run: parachute expose public --cloudflare");
       return false;
     }
   }
@@ -391,7 +531,13 @@ export async function exposePublicInteractive(opts: ExposeInteractiveOpts = {}):
   }
   writeLastProvider("cloudflare", { path: r.lastProviderPath, now: r.now });
   const code = await r.exposeCloudflareUpImpl(hostname, r.cloudflareOpts);
-  if (code === 0) await runPreflightSafely(r);
+  if (code === 0) {
+    // hub#567: routing succeeded — the tunnel record now carries the live
+    // hostname, so drop the pending one (a retry shouldn't pre-fill a
+    // hostname that's already exposed).
+    clearPendingHostname(r.statePath);
+    await runPreflightSafely(r);
+  }
   return code;
 }
 

package/src/commands/expose-supervisor.ts

@@ -16,15 +16,18 @@
  * `expose-cloudflare.ts` (cloudflared) use so the two paths can't drift.
  */
 
+import pkg from "../../package.json" with { type: "json" };
 import { readHubPort } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import {
   type EnsureHubUnitOpts,
   type EnsureHubUnitResult,
+  type EnsureHubVersionMatchesResult,
   HUB_UNIT_DEFAULT_PORT,
   type HubUnitDeps,
   defaultHubUnitDeps,
   ensureHubUnit as ensureHubUnitImpl,
+  ensureHubVersionMatches as ensureHubVersionMatchesImpl,
 } from "../hub-unit.ts";
 import {
   type DriveModuleOpDeps,
@@ -54,6 +57,17 @@ export interface ExposeSupervisorOpts {
   hubUnitDeps?: HubUnitDeps;
   /** Ensure the hub unit is up before / during expose (§3.2 / §4.3a). */
   ensureHubUnit?: (opts: EnsureHubUnitOpts) => Promise<EnsureHubUnitResult>;
+  /**
+   * Version-check-and-restart at the expose adoption point (#590). After the
+   * hub unit is confirmed up, compare the RUNNING hub's `/health` version to the
+   * installed package version; restart the managed unit on mismatch so an expose
+   * never wires a tunnel to a stale zombie. Production wires
+   * `ensureHubVersionMatches`; tests inject a stub.
+   */
+  ensureHubVersion?: (ctx: {
+    port: number;
+    log: (line: string) => void;
+  }) => Promise<EnsureHubVersionMatchesResult>;
   /** Drive a per-module op against the running hub (reads operator.token). */
   driveModuleOp?: (short: string, op: ModuleOp, deps: DriveModuleOpDeps) => Promise<ModuleOpResult>;
   /**
@@ -83,6 +97,10 @@ export interface ExposeSupervisorOpts {
 export interface ResolvedExposeSupervisor {
   hubUnitDeps: HubUnitDeps;
   ensureHubUnit: (opts: EnsureHubUnitOpts) => Promise<EnsureHubUnitResult>;
+  ensureHubVersion: (ctx: {
+    port: number;
+    log: (line: string) => void;
+  }) => Promise<EnsureHubVersionMatchesResult>;
   driveModuleOp: (short: string, op: ModuleOp, deps: DriveModuleOpDeps) => Promise<ModuleOpResult>;
   openDb: (configDir: string) => import("bun:sqlite").Database;
   selfHealOperatorTokenIssuer: (
@@ -105,6 +123,15 @@ export function resolveExposeSupervisor(
   return {
     hubUnitDeps,
     ensureHubUnit: opts?.ensureHubUnit ?? ensureHubUnitImpl,
+    ensureHubVersion:
+      opts?.ensureHubVersion ??
+      ((ctx) =>
+        ensureHubVersionMatchesImpl({
+          installedVersion: pkg.version,
+          port: ctx.port,
+          deps: hubUnitDeps,
+          log: ctx.log,
+        })),
     driveModuleOp: opts?.driveModuleOp ?? driveModuleOpImpl,
     openDb: opts?.openDb ?? ((configDir) => openHubDb(hubDbPath(configDir))),
     selfHealOperatorTokenIssuer:
@@ -145,6 +172,24 @@ export async function ensureHubUnitForExpose(
 ): Promise<{ ok: boolean; port: number }> {
   const ensured = await sup.ensureHubUnit({ port, deps: sup.hubUnitDeps, log });
   if (ensured.outcome === "already-up" || ensured.outcome === "started") {
+    // #590: the hub is up — but is it the version we installed? A zombie that
+    // merely answers /health must not become the target of a fresh tunnel.
+    // Compare + restart-on-mismatch (once). A non-unit-managed mismatch is NOT
+    // killed: surface it + fail the expose so the operator resolves it; a
+    // still-mismatched-after-restart (bun-linked branch) warns + continues.
+    try {
+      const versionResult = await sup.ensureHubVersion({ port: ensured.port, log });
+      for (const m of versionResult.messages) log(m);
+      if (
+        versionResult.outcome === "not-unit-managed" ||
+        versionResult.outcome === "restart-failed"
+      ) {
+        return { ok: false, port: ensured.port };
+      }
+    } catch (err) {
+      // A version-check failure must never block expose — degrade to a note.
+      log(`note: hub version check skipped (${err instanceof Error ? err.message : String(err)})`);
+    }
     return { ok: true, port: ensured.port };
   }
   for (const m of ensured.messages) log(m);