@openparachute/hub 0.6.4-rc.9 → 0.6.4

package/src/__tests__/install.test.ts

@@ -341,6 +341,96 @@ describe("install", () => {
     }
   });
 
+  test("names the squatter holding the canonical port when the walk assigns a fallback (#590)", async () => {
+    // Field bug #590 item 2: a stale pre-supervisor vault zombie squats 1940;
+    // the install-time port walk silently routed to a fallback. Now it names the
+    // holder (pid + command line) + hints it may be a stale daemon. Detection
+    // only — never kills. Reuses the #581 pidOnPort / ownerOfPid seams.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        // Only vault's canonical 1940 is held → the walk picks a fallback in-range.
+        portProbe: async (p) => p === 1940,
+        // Inject the #581 seams: a foreign pid squats 1940.
+        pidOnPort: (p) => (p === 1940 ? 1234 : undefined),
+        ownerOfPid: (pid) => (pid === 1234 ? "bun /opt/vault/src/server.ts" : undefined),
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      // The fallback warning still fires…
+      expect(joined).toMatch(/canonical port 1940 is in use; assigned/);
+      // …and now it NAMES the squatter + hints at a stale daemon.
+      expect(joined).toContain("pid 1234 (bun /opt/vault/src/server.ts)");
+      expect(joined).toMatch(/stale pre-supervisor daemon/);
+      expect(joined).toContain("kill 1234");
+      const entry = findService("parachute-vault", path);
+      expect(entry?.port).not.toBe(1940);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("squatter pid present but command line unreadable → names the pid alone (#590)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async (p) => p === 1940,
+        pidOnPort: (p) => (p === 1940 ? 4321 : undefined),
+        ownerOfPid: () => undefined, // ps failed / pid gone
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("held by pid 4321.");
+      expect(joined).not.toContain("(undefined)");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no squatter naming when the canonical port is free (#590 — no false positive)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      let pidProbed = false;
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false, // canonical 1940 is free
+        pidOnPort: () => {
+          pidProbed = true;
+          return 9999;
+        },
+        ownerOfPid: () => "should-not-appear",
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      // Canonical assigned → no fallback warning, no squatter probe at all.
+      expect(joined).not.toMatch(/is in use; assigned/);
+      expect(joined).not.toContain("should-not-appear");
+      expect(pidProbed).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+
   test("`install lens` aliases to notes with a rename notice", async () => {
     // Transition alias for the brief Notes→Lens rename (Apr 19) that was
     // reverted on launch eve (Apr 22). Accepted for one release cycle so

package/src/__tests__/migrate-cutover.test.ts

@@ -67,6 +67,7 @@ function fakeHubUnitDeps(): HubUnitDeps {
     readFile: () => undefined,
     exists: () => false,
     probeHealth: async () => false,
+    probeHealthVersion: async () => null,
     portListening: async () => false,
     sleep: async () => {},
   };

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

package/src/commands/init.ts

@@ -35,12 +35,18 @@
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import pkg from "../../package.json" with { type: "json" };
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { type ExposeState, readExposeState } from "../expose-state.ts";
 import { type EnsureHubOpts, HUB_DEFAULT_PORT, HUB_SVC, readHubPort } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
-import { ensureHubUnit, installAndStartHubUnit } from "../hub-unit.ts";
+import {
+  type EnsureHubVersionMatchesResult,
+  ensureHubUnit,
+  ensureHubVersionMatches,
+  installAndStartHubUnit,
+} from "../hub-unit.ts";
 import { issueOperatorToken, readOperatorTokenFile } from "../operator-token.ts";
 import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
 import { findService, readManifestLenient } from "../services-manifest.ts";
@@ -81,6 +87,18 @@ export interface InitOpts {
    * Design §3.3 (init row), §4.1/§4.2, appendix (c).
    */
   ensureHub?: (opts: EnsureHubOpts) => Promise<{ pid: number; port: number; started: boolean }>;
+  /**
+   * Test seam: version-check-and-restart at the hub adoption point (#590).
+   * After init confirms a hub is answering on the canonical port, it compares
+   * the RUNNING hub's `/health` version against this installed package version;
+   * on mismatch it restarts the managed unit (once) so a freshly-installed hub
+   * never adopts a stale zombie. Production wires `ensureHubVersionMatches`;
+   * tests stub it to assert the call without touching launchctl / the live hub.
+   */
+  ensureHubVersion?: (ctx: {
+    port: number;
+    log: (line: string) => void;
+  }) => Promise<EnsureHubVersionMatchesResult>;
   /**
    * Test seam: guarantee an operator token exists once the hub is up (design
    * §3.1 / §3.3). Production reads `operator.token`; if absent AND a hub user
@@ -582,6 +600,18 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   // spawn). The `ensureHub` seam is preserved for tests (and the return shape is
   // unchanged); only the production default flipped.
   const ensureHub = opts.ensureHub ?? defaultEnsureHubViaUnit;
+  // #590: after the hub is confirmed up, compare its RUNNING version to the
+  // installed package version and restart the managed unit on mismatch, so a
+  // freshly-installed hub never adopts a stale zombie that merely answers
+  // /health. Injectable for tests.
+  const ensureHubVersion =
+    opts.ensureHubVersion ??
+    ((ctx) =>
+      ensureHubVersionMatches({
+        installedVersion: pkg.version,
+        port: ctx.port,
+        log: ctx.log,
+      }));
   const guaranteeOperatorToken = opts.guaranteeOperatorToken ?? defaultGuaranteeOperatorToken;
   const readExposeStateFn = opts.readExposeStateFn ?? (() => readExposeState());
   const isTty = opts.isTty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -640,6 +670,38 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   // overridden, so the fallback is almost always correct.
   if (hubPort === undefined) hubPort = HUB_DEFAULT_PORT;
 
+  // Step 1.25 (#590): the hub answered /health, but is it the version we just
+  // installed? A zombie LaunchAgent survives `rm -rf ~/.parachute`, so a brand-
+  // new install can adopt month-old code that merely keeps the port. Compare the
+  // RUNNING version to the installed package version; on mismatch, restart the
+  // managed unit (once) so the tunnel/wizard/vault-install downstream bind to the
+  // NEW code. A non-unit-managed hub (legacy detached pid / dev `bun run serve`)
+  // is NOT killed — we surface the mismatch + an actionable message and bail so
+  // the operator decides. A still-mismatched-after-restart (bun-linked branch)
+  // warns + continues rather than looping.
+  try {
+    const versionResult = await ensureHubVersion({ port: hubPort, log });
+    for (const m of versionResult.messages) log(m);
+    if (versionResult.outcome === "not-unit-managed") {
+      // We can't safely take over a hub we don't own. Stop here so init doesn't
+      // wire a fresh tunnel + credentials to a stale runtime (the #590 field bug).
+      log("");
+      log("Resolve the version mismatch above, then re-run `parachute init`.");
+      return 1;
+    }
+    if (versionResult.outcome === "restart-failed") {
+      log("");
+      log("The hub service manager rejected the restart command.");
+      log("Try checking the logs:");
+      log("  parachute logs hub");
+      return 1;
+    }
+    // `match` / `not-running` / `restarted` / `still-mismatched` → continue.
+  } catch (err) {
+    // A version-check failure must never block init — degrade to a note.
+    log(`note: hub version check skipped (${err instanceof Error ? err.message : String(err)})`);
+  }
+
   // Step 1.5: guarantee an operator token exists (design §3.1 / §3.3). Under
   // the unified model every per-module verb is an authenticated module-ops
   // call, so the steady-state operator needs an `operator.token` on disk — the

package/src/commands/install.ts

@@ -5,7 +5,12 @@ import { autoWireScribeAuth } from "../auto-wire.ts";
 import { bunGlobalPrefixes, isLinked as defaultIsLinkedShared } from "../bun-link.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { type ExposeState, readExposeState } from "../expose-state.ts";
-import { HUB_DEFAULT_PORT, readHubPort } from "../hub-control.ts";
+import {
+  HUB_DEFAULT_PORT,
+  type PidOnPortFn,
+  defaultPidOnPort,
+  readHubPort,
+} from "../hub-control.ts";
 import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
 import {
   type ModuleManifest,
@@ -34,6 +39,7 @@ import {
   type DisableStaleModuleUnitsResult,
   disableStaleModuleUnits as defaultDisableStaleModuleUnits,
 } from "../stale-module-units.ts";
+import { type OwnerProbeFn, defaultOwnerOfPid } from "../supervisor.ts";
 import { WELL_KNOWN_PATH } from "../well-known.ts";
 import { type LifecycleOpts, start as lifecycleStart } from "./lifecycle.ts";
 import { migrateNotice } from "./migrate.ts";
@@ -301,6 +307,22 @@ export interface InstallOpts {
    * unless the test populates services.json directly.
    */
   portProbe?: (port: number) => Promise<boolean>;
+  /**
+   * Test seam for the install-time port-squatter naming (#590 item 2). When the
+   * canonical port walk has to assign a fallback port because the canonical one
+   * is held, this looks up the pid LISTENing on the canonical port so the
+   * warning can name the holder (`pid 1234 (bun .../vault/src/server.ts)`) — the
+   * same #581 `pidOnPort` / `ownerOfPid` seams the supervisor start-path uses,
+   * reused (not duplicated). Detection-only — never kills. Production wires
+   * `defaultPidOnPort` (`lsof -ti :<port>`); tests inject a deterministic stub.
+   */
+  pidOnPort?: PidOnPortFn;
+  /**
+   * Test seam for the install-time port-squatter naming (#590 item 2): the
+   * best-effort command line of the squatting pid. Production wires
+   * `defaultOwnerOfPid` (`ps -o command= -p <pid>`); tests inject a stub.
+   */
+  ownerOfPid?: OwnerProbeFn;
   /**
    * Test seam for reading `<packageDir>/.parachute/module.json`. Production
    * uses the real file reader; tests inject a map from package-dir → manifest
@@ -974,6 +996,25 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   });
   if (portResult.warning) {
     log(`⚠ ${portResult.warning}`);
+    // #590 item 2: the canonical port was held, so we walked to a fallback. Name
+    // the squatter — the supervisor start-path does this post-#581; do it here at
+    // install-time too. Reuse the #581 pidOnPort / ownerOfPid seams (detection
+    // only; never kill). When the holder is a foreign pid (not one of OUR rows —
+    // which is the common case when a stale pre-supervisor daemon is squatting),
+    // surface its pid + command line + a hint.
+    if (canonicalPort !== undefined && portResult.source !== "canonical") {
+      const pidOnPort = opts.pidOnPort ?? defaultPidOnPort;
+      const ownerOfPid = opts.ownerOfPid ?? defaultOwnerOfPid;
+      const holder = pidOnPort(canonicalPort);
+      if (holder !== undefined) {
+        const cmdline = ownerOfPid(holder);
+        const who = cmdline ? `pid ${holder} (${cmdline})` : `pid ${holder}`;
+        log(`  canonical port ${canonicalPort} is held by ${who}.`);
+        log(
+          `  This may be a stale pre-supervisor daemon. If so, stop it (kill ${holder}) and re-run \`parachute install ${entryName}\` to reclaim the canonical port.`,
+        );
+      }
+    }
   }
 
   // Find-or-seed the manifest entry. Re-read after the seed write so a silent

package/src/hub-unit.ts

@@ -76,6 +76,16 @@ export interface HubUnitDeps extends ManagedUnitDeps {
    * uses a bounded `fetch`; tests inject a deterministic stub.
    */
   probeHealth: (port: number) => Promise<boolean>;
+  /**
+   * HTTP `/health` probe that ALSO reads the JSON `version` field of the
+   * running hub (#590). Resolves to `{ ok, version }` — `ok` mirrors
+   * {@link probeHealth} (2xx), `version` is the running hub's reported version
+   * (or `undefined` when the body has no `version` field — a very old hub that
+   * predates the field; the caller treats that as a mismatch). Resolves to
+   * `null` when the hub doesn't answer at all (connection-refused / timeout).
+   * Production uses a bounded `fetch`; tests inject a deterministic stub.
+   */
+  probeHealthVersion: (port: number) => Promise<{ ok: boolean; version?: string } | null>;
   /** TCP connect-probe for readiness polling (reuses `defaultPortListening`). */
   portListening: PortListeningFn;
   /** Sleep between readiness polls (tests pin to 0). */
@@ -98,9 +108,41 @@ async function defaultProbeHealth(port: number): Promise<boolean> {
   }
 }
 
+/**
+ * Default version-aware `/health` probe (#590). Reads the JSON body and pulls
+ * out the `version` field. Returns `null` on any network error / timeout (the
+ * hub isn't answering); `{ ok, version }` otherwise — `version` is `undefined`
+ * when the body has no string `version` field (a very old hub, or a non-JSON
+ * body), which the caller treats as a mismatch. 1.5s timeout, mirroring
+ * {@link defaultProbeHealth}.
+ */
+async function defaultProbeHealthVersion(
+  port: number,
+): Promise<{ ok: boolean; version?: string } | null> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    let version: string | undefined;
+    try {
+      const body = (await res.json()) as unknown;
+      if (body && typeof body === "object" && "version" in body) {
+        const v = (body as { version?: unknown }).version;
+        if (typeof v === "string" && v.length > 0) version = v;
+      }
+    } catch {
+      // Non-JSON body → no version. Leave `version` undefined (→ mismatch).
+    }
+    return version !== undefined ? { ok: res.ok, version } : { ok: res.ok };
+  } catch {
+    return null;
+  }
+}
+
 export const defaultHubUnitDeps: HubUnitDeps = {
   ...defaultManagedUnitDeps,
   probeHealth: defaultProbeHealth,
+  probeHealthVersion: defaultProbeHealthVersion,
   portListening: defaultPortListening,
   sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
 };
@@ -158,6 +200,16 @@ export function isHubUnitInstalled(deps: HubUnitDeps): boolean {
  * Is a service manager (systemd / launchd) available on this platform at all?
  * macOS → launchctl; Linux → systemctl. A box with neither (a bare container,
  * an init-less host) has no manager — the foreground-`serve`-only path (R19/D1).
+ *
+ * NOTE: production `deps.which` is `Bun.which`, which resolves against the
+ * process PATH. This ASSUMES `launchctl` (`/bin/launchctl`) / `systemctl` are on
+ * the PATH — true on any normal macOS / systemd box. A deliberately stripped
+ * PATH (a `nix develop` shell that omits `/bin`, a minimal CI image) would make
+ * `which` return null and misclassify a genuinely launchd-managed hub as
+ * not-unit-managed. The #590 version-check then degrades to the "stop it
+ * yourself" path rather than restarting the unit — a safe (never-kill)
+ * degradation, but worth knowing if a dev sees not-unit-managed on a box that
+ * clearly runs the hub under launchd.
  */
 export function hasServiceManager(deps: HubUnitDeps): boolean {
   if (deps.platform === "darwin") return deps.which("launchctl") !== null;
@@ -342,6 +394,209 @@ export function restartHubUnit(deps: HubUnitDeps): HubUnitManagerOpResult {
   return { outcome: "ok", messages: [] };
 }
 
+/**
+ * Outcome of {@link ensureHubVersionMatches} (#590).
+ */
+export type HubVersionOutcome =
+  /** The running hub's version matched the installed version — no action. */
+  | "match"
+  /** Hub wasn't answering `/health` at all — nothing to compare (no-op). */
+  | "not-running"
+  /**
+   * Versions mismatched, the hub is unit-managed, the unit was restarted, and
+   * the running version now matches the installed version. The zombie was
+   * cleared.
+   */
+  | "restarted"
+  /**
+   * Versions mismatched and the hub is unit-managed, but after the (single)
+   * restart the running version STILL doesn't match — e.g. a bun-linked
+   * checkout on a feature branch whose package.json version trails the running
+   * code, or a restart that adopted yet-another stale build. We restart at most
+   * once and then continue rather than loop (the restart-loop guard).
+   */
+  | "still-mismatched"
+  /**
+   * Versions mismatched but the running hub is NOT unit-managed (a legacy
+   * detached pid, or a dev `bun run serve` in a terminal, or no service
+   * manager at all). We do NOT kill it blindly — we surface the mismatch +
+   * an actionable message and stop.
+   */
+  | "not-unit-managed"
+  /**
+   * Versions mismatched, the hub is unit-managed, but the restart command
+   * itself failed (the manager rejected it). Surface the manager's error.
+   */
+  | "restart-failed";
+
+export interface EnsureHubVersionMatchesResult {
+  outcome: HubVersionOutcome;
+  /** The running hub's reported version (undefined when it had no version field / wasn't running). */
+  runningVersion?: string;
+  /** The installed package version we compared against. */
+  installedVersion: string;
+  /** Human-readable lines the caller should surface (mismatch notice, actionable hints). */
+  messages: string[];
+}
+
+export interface EnsureHubVersionMatchesOpts {
+  /** The installed package version (the caller reads its own `package.json`). */
+  installedVersion: string;
+  /** Hub port to probe (default 1939). */
+  port?: number;
+  /** Injectable deps (defaults to production). */
+  deps?: HubUnitDeps;
+  /** Readiness budget after a restart, in ms (default 15s). */
+  readyTimeoutMs?: number;
+  /** Poll interval for the post-restart re-probe, in ms (default 250). */
+  readyPollMs?: number;
+  log?: (line: string) => void;
+}
+
+/**
+ * Version-check-and-restart at a hub adoption point (#590).
+ *
+ * The field bug: a freshly-installed hub (e.g. 0.6.4-rc.9) adopts an
+ * arbitrarily-stale RUNNING hub (0.5.14-rc.4) merely because it answers
+ * `/health` on 1939 — a zombie LaunchAgent survives `rm -rf ~/.parachute`, and
+ * everything downstream (tunnel, wizard, vault install) then binds to month-old
+ * code running against a directory deleted out from under it.
+ *
+ * This helper closes that edge. Given the INSTALLED package version (the caller
+ * reads its own `package.json` at runtime), it:
+ *   1. Probes `/health` for the RUNNING version. Not answering → `not-running`
+ *      (nothing to adopt; the caller's bringup path handles starting it).
+ *   2. Version matches → `match` (today's behavior, no extra restart).
+ *   3. Version mismatches (INCLUDING a hub with no `version` field — a very old
+ *      hub — which reads as "undefined ≠ installed"):
+ *        a. If the running hub is NOT unit-managed (no manager / no unit
+ *           installed) → `not-unit-managed`. We do NOT kill it blindly: a
+ *           detached legacy pid or a dev `bun run serve` may be the operator's,
+ *           and KeepAlive-less processes aren't ours to reap. Surface an
+ *           actionable message and stop.
+ *        b. If it IS unit-managed → restart the unit ONCE
+ *           ({@link restartHubUnit}), then re-probe `/health` until the version
+ *           matches or the timeout elapses:
+ *             - now matches → `restarted` (zombie cleared).
+ *             - still mismatched → `still-mismatched` (restart-loop guard: we
+ *               restart at most once; a bun-linked branch checkout whose
+ *               package.json trails the code stays here — warn + continue, do
+ *               not loop).
+ *             - restart command failed → `restart-failed`.
+ *
+ * The CALLER decides whether a given outcome is fatal. `init` and the expose
+ * chains both want: `match`/`not-running`/`restarted` → continue silently-ish;
+ * `not-unit-managed`/`still-mismatched`/`restart-failed` → warn loudly (and, for
+ * init, optionally bail) so a brand-new tunnel never wires to a zombie.
+ *
+ * Everything is behind the {@link HubUnitDeps} seam — no real launchctl /
+ * systemctl / HTTP call in tests.
+ */
+export async function ensureHubVersionMatches(
+  opts: EnsureHubVersionMatchesOpts,
+): Promise<EnsureHubVersionMatchesResult> {
+  const deps = opts.deps ?? defaultHubUnitDeps;
+  const port = opts.port ?? HUB_UNIT_DEFAULT_PORT;
+  const installedVersion = opts.installedVersion;
+  const readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+  const readyPollMs = opts.readyPollMs ?? 250;
+  const log = opts.log ?? (() => {});
+
+  const probe = await deps.probeHealthVersion(port);
+  if (probe === null) {
+    // Hub isn't answering — nothing to compare. The caller's bringup path owns
+    // starting it; this helper is a no-op here.
+    return { outcome: "not-running", installedVersion, messages: [] };
+  }
+
+  const runningVersion = probe.version;
+  if (runningVersion === installedVersion) {
+    // Exactly today's behavior — versions agree, no extra restart.
+    return { outcome: "match", runningVersion, installedVersion, messages: [] };
+  }
+
+  // Mismatch (includes the no-`version`-field very-old-hub case → undefined).
+  const runningLabel = runningVersion ?? "an older version (no version field)";
+
+  // Is this hub one we can restart through the manager? If there's no manager,
+  // or no unit installed, the running hub is a legacy detached pid / a dev
+  // foreground `serve` — NOT ours to reap. Surface + stop (do not kill blindly).
+  if (!hasServiceManager(deps) || !isHubUnitInstalled(deps)) {
+    return {
+      outcome: "not-unit-managed",
+      runningVersion,
+      installedVersion,
+      messages: [
+        `⚠ the running hub is ${runningLabel} but ${installedVersion} is installed.`,
+        "  The running hub is NOT managed by a Parachute service unit (a detached process or a foreground `parachute serve` / `bun src/cli.ts serve`), so it won't be restarted automatically.",
+        `  Stop it yourself (find it with \`lsof -ti :${port}\` then \`kill <pid>\`, or quit the foreground \`parachute serve\` / \`bun src/cli.ts serve\` on a dev checkout), then re-run so the new code is adopted.`,
+      ],
+    };
+  }
+
+  // Unit-managed mismatch: restart the unit ONCE to pick up the new code.
+  log(
+    `⚠ the running hub is ${runningLabel} but ${installedVersion} is installed — restarting the hub unit to pick up the new code.`,
+  );
+  const restart = restartHubUnit(deps);
+  if (restart.outcome !== "ok") {
+    return {
+      outcome: "restart-failed",
+      runningVersion,
+      installedVersion,
+      messages: [
+        `⚠ the running hub is ${runningLabel} but ${installedVersion} is installed, and the hub unit restart failed.`,
+        ...restart.messages,
+      ],
+    };
+  }
+
+  // Builders for the two terminal outcomes of the post-restart re-probe loop.
+  const restartedResult = (v: string): EnsureHubVersionMatchesResult => ({
+    outcome: "restarted",
+    runningVersion: v,
+    installedVersion,
+    messages: [`✓ hub unit restarted; now running ${installedVersion}.`],
+  });
+  const stillMismatchedResult = (last: string | undefined): EnsureHubVersionMatchesResult => {
+    const reports = last ? ` (reports ${last})` : "";
+    return {
+      outcome: "still-mismatched",
+      ...(last !== undefined ? { runningVersion: last } : {}),
+      installedVersion,
+      messages: [
+        `⚠ restarted the hub unit, but it is still not reporting ${installedVersion}${reports}.`,
+        "  This can happen with a bun-linked checkout on a feature branch whose package.json version trails the running code.",
+        `  Continuing — verify with \`parachute status\` / \`curl http://127.0.0.1:${port}/health\` if the hub should be on a specific version.`,
+      ],
+    };
+  };
+
+  // Re-probe `/health` until the running version matches the installed version
+  // or the readiness budget elapses. Restart-loop guard: we restart AT MOST
+  // once — if it still mismatches after this single restart (e.g. a bun-linked
+  // checkout on a branch), we warn + continue rather than looping.
+  const deadline = Date.now() + readyTimeoutMs;
+  for (;;) {
+    const after = await deps.probeHealthVersion(port);
+    if (after !== null && after.version === installedVersion) {
+      return restartedResult(installedVersion);
+    }
+    if (Date.now() >= deadline) {
+      // Report the last-observed (still-stale) version if the hub came back.
+      return stillMismatchedResult(after?.version ?? runningVersion);
+    }
+    if (readyPollMs > 0) await deps.sleep(readyPollMs);
+    else break;
+  }
+  // readyPollMs === 0 fast-path: one more probe, then settle.
+  const finalProbe = await deps.probeHealthVersion(port);
+  if (finalProbe !== null && finalProbe.version === installedVersion) {
+    return restartedResult(installedVersion);
+  }
+  return stillMismatchedResult(finalProbe?.version ?? runningVersion);
+}
+
 /**
  * Run-state of the hub UNIT as reported by the platform manager (design §6.4).
  * This is the manager's view — NOT a liveness verdict. The hub answering