@openparachute/hub 0.5.14-rc.3 → 0.5.14-rc.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.14-rc.3",
+  "version": "0.5.14-rc.5",
   "description": "parachute \u2014 the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/cloudflare-detect.test.ts

@@ -59,10 +59,65 @@ describe("cloudflare detect", () => {
     }
   });
 
-  test("install hint names brew on darwin and a URL elsewhere", () => {
-    expect(cloudflaredInstallHint("darwin")).toContain("brew install cloudflared");
-    expect(cloudflaredInstallHint("linux")).toContain(
-      "developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads",
-    );
+  describe("cloudflaredInstallHint", () => {
+    test("darwin: names brew + points at GitHub releases as fallback", () => {
+      const hint = cloudflaredInstallHint("darwin", "arm64");
+      expect(hint).toContain("brew install cloudflared");
+      expect(hint).toContain("https://github.com/cloudflare/cloudflared/releases/latest");
+    });
+
+    test("linux x64: writes the curl line with the amd64 artifact suffix", () => {
+      // Refresh of stale URLs (2026-05-27). Aaron hit this on a fresh
+      // Amazon Linux 2023 install — `sudo dnf install cloudflared`
+      // returned 'No match for argument: cloudflared', and the hub's
+      // hint pointed at developers.cloudflare.com paths that 404. The
+      // GitHub release is the reliable cross-distro path.
+      const hint = cloudflaredInstallHint("linux", "x64");
+      expect(hint).toContain("curl -L -o /usr/local/bin/cloudflared");
+      expect(hint).toContain(
+        "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64",
+      );
+      expect(hint).toContain("sudo chmod +x /usr/local/bin/cloudflared");
+    });
+
+    test("linux arm64: writes the arm64 artifact suffix", () => {
+      const hint = cloudflaredInstallHint("linux", "arm64");
+      expect(hint).toContain("cloudflared-linux-arm64");
+    });
+
+    test("linux arm (32-bit): writes the arm artifact suffix", () => {
+      const hint = cloudflaredInstallHint("linux", "arm");
+      expect(hint).toContain("cloudflared-linux-arm");
+    });
+
+    test("linux exotic arch: falls back to a generic GitHub releases pointer", () => {
+      // riscv64 / ppc64 / mips64 — no cloudflared artifact published, so
+      // we don't fabricate a 404-bound download URL; we point the user at
+      // the releases page and surface what their arch is so they can pick.
+      const hint = cloudflaredInstallHint("linux", "riscv64");
+      expect(hint).toContain("https://github.com/cloudflare/cloudflared/releases/latest");
+      expect(hint).toContain("riscv64");
+      expect(hint).not.toContain("curl -L -o /usr/local/bin/cloudflared");
+    });
+
+    test("no stale developers.cloudflare.com or pkg.cloudflare.com paths anywhere", () => {
+      // Aaron caught both URL shapes returning HTML/404 on 2026-05-27 —
+      // they had been the hub's installer instructions for months.
+      // Hard-assert they're gone so they don't regress.
+      for (const platform of ["darwin", "linux"] as const) {
+        for (const arch of ["x64", "arm64"] as const) {
+          const hint = cloudflaredInstallHint(platform, arch);
+          expect(hint).not.toContain("developers.cloudflare.com");
+          expect(hint).not.toContain("pkg.cloudflare.com");
+        }
+      }
+    });
+
+    test("non-Linux, non-darwin platform: GitHub releases pointer with no curl line", () => {
+      const hint = cloudflaredInstallHint("win32", "x64");
+      expect(hint).toContain("https://github.com/cloudflare/cloudflared/releases/latest");
+      expect(hint).not.toContain("brew install");
+      expect(hint).not.toContain("curl -L -o");
+    });
   });
 });

package/src/__tests__/expose-cloudflare.test.ts

@@ -14,8 +14,13 @@ import {
   exposeCloudflareOff,
   exposeCloudflareUp,
 } from "../commands/expose-cloudflare.ts";
+import { writeHubPort } from "../hub-control.ts";
 import type { CommandResult, Runner } from "../tailscale/run.ts";
 
+// Default seeded hub port used by tests with `skipHub: true`. The cloudflared
+// path reads `<configDir>/hub/run/hub.port` instead of spawning a real hub.
+const TEST_HUB_PORT = 1939;
+
 interface TestEnv {
   configDir: string;
   manifestPath: string;
@@ -41,6 +46,11 @@ function makeEnv(opts: { includeVault?: boolean; loggedIn?: boolean } = {}): Tes
   require("node:fs").mkdirSync(configDir, { recursive: true });
   require("node:fs").mkdirSync(cloudflaredHome, { recursive: true });
 
+  // Seed the hub port so `skipHub: true` invocations can resolve a port
+  // without spawning the actual hub process. Matches the seam pattern used
+  // by expose.test.ts (which threads `hubEnsureOpts` for the same purpose).
+  writeHubPort(TEST_HUB_PORT, configDir);
+
   if (loggedIn) {
     writeFileSync(join(cloudflaredHome, "cert.pem"), "---");
   }
@@ -128,6 +138,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         now: () => new Date("2026-04-22T12:00:00Z"),
       });
 
@@ -170,7 +182,12 @@ describe("exposeCloudflareUp", () => {
       const yaml = readFileSync(env.configPath, "utf8");
       expect(yaml).toContain(`tunnel: ${uuid}`);
       expect(yaml).toContain("- hostname: vault.example.com");
-      expect(yaml).toContain("service: http://localhost:1940");
+      // Routes through the hub (not directly at vault). The hub dispatches
+      // discovery / admin / OAuth / per-vault proxy / generic /<svc>/* —
+      // same shape Tailscale Funnel uses. Pre-2026-05-27 this was
+      // http://localhost:1940 (vault's port), which served vault's own 404
+      // page on every request that wasn't /vault/<name>/...
+      expect(yaml).toContain(`service: http://localhost:${TEST_HUB_PORT}`);
 
       // Security copy surfaces both paths plus a pointer to the auth doc.
       const joined = logs.join("\n");
@@ -209,6 +226,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
       expect(code).toBe(0);
       // No `tunnel create` — only list + route.
@@ -236,6 +255,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -262,6 +283,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         tunnelName: "bad name with spaces",
       });
 
@@ -291,6 +314,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -317,6 +342,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -342,6 +369,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -376,6 +405,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -425,6 +456,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(0);
@@ -462,6 +495,8 @@ describe("exposeCloudflareUp", () => {
         manifestPath: env.manifestPath,
         statePath: env.statePath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         // Use defaults for configPath/logPath so they're per-tunnel-derived.
       });
       expect(code1).toBe(0);
@@ -487,6 +522,8 @@ describe("exposeCloudflareUp", () => {
         manifestPath: env.manifestPath,
         statePath: env.statePath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         tunnelName: "second",
       });
       expect(code2).toBe(0);
@@ -544,6 +581,8 @@ describe("exposeCloudflareUp", () => {
           configPath: env.configPath,
           logPath: env.logPath,
           cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
           // No password, no 2FA — fully wide open. The warning should still
           // fire; password-recovery copy already lives in `printAuthGuidance`.
           vaultAuthStatus: {
@@ -592,6 +631,8 @@ describe("exposeCloudflareUp", () => {
           configPath: env.configPath,
           logPath: env.logPath,
           cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
           vaultAuthStatus: {
             hasOwnerPassword: true,
             hasTotp: true,
@@ -612,6 +653,68 @@ describe("exposeCloudflareUp", () => {
       }
     });
   });
+
+  describe("routes through hub, not vault", () => {
+    test("config.yml targets the hub port; success log mentions Admin + OAuth URLs", async () => {
+      // Regression guard for the 2026-05-27 cut. Aaron ran `parachute expose
+      // public` on a fresh EC2 box, configured Cloudflare with a custom
+      // domain, and hit it — and got vault's 404 page rather than the hub's
+      // discovery / admin. The pre-fix cloudflared config routed straight at
+      // vault's port; the fix routes at the hub, mirroring the Tailscale
+      // Funnel shape (single mount → hub catchall; hub dispatches per-request).
+      const env = makeEnv();
+      try {
+        // Re-seed hub port to a non-default value so the assertion is
+        // unambiguous about *which* port got into the yaml.
+        writeHubPort(1949, env.configDir);
+
+        const uuid = "ffff0000-0000-0000-0000-00000000beef";
+        const { runner } = queueRunner([
+          { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+          { code: 0, stdout: "[]", stderr: "" },
+          {
+            code: 0,
+            stdout: `Created tunnel parachute with id ${uuid}\n`,
+            stderr: "",
+          },
+          { code: 0, stdout: "", stderr: "" },
+        ]);
+        const { spawner } = fakeSpawner(60001);
+        const logs: string[] = [];
+
+        const code = await exposeCloudflareUp("gitcoin.parachute.computer", {
+          runner,
+          spawner,
+          alive: () => false,
+          kill: () => {},
+          log: (l) => logs.push(l),
+          manifestPath: env.manifestPath,
+          statePath: env.statePath,
+          configPath: env.configPath,
+          logPath: env.logPath,
+          cloudflaredHome: env.cloudflaredHome,
+          configDir: env.configDir,
+          skipHub: true,
+        });
+
+        expect(code).toBe(0);
+        const yaml = readFileSync(env.configPath, "utf8");
+        // Routes through the hub on its loopback port.
+        expect(yaml).toContain("service: http://localhost:1949");
+        // Does NOT route directly at vault's port (1940 per makeEnv default).
+        expect(yaml).not.toContain("service: http://localhost:1940");
+
+        const joined = logs.join("\n");
+        // Discoverable surfaces: open / admin / vault / OAuth all surfaced.
+        expect(joined).toContain("https://gitcoin.parachute.computer/");
+        expect(joined).toContain("Admin:   https://gitcoin.parachute.computer/admin/");
+        expect(joined).toContain("Vault:   https://gitcoin.parachute.computer/vault/default");
+        expect(joined).toContain("OAuth:   https://gitcoin.parachute.computer");
+      } finally {
+        env.cleanup();
+      }
+    });
+  });
 });
 
 describe("exposeCloudflareOff", () => {

package/src/__tests__/expose-interactive.test.ts

@@ -469,10 +469,16 @@ describe("exposePublicInteractive — neither ready", () => {
       expect(interactiveCalled).toBe(false);
       expect(cloudflareCalled).toBe(false);
       const joined = logs.join("\n");
-      expect(joined).toMatch(/apt-get|dnf/);
-      expect(joined).toContain(
-        "developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads",
-      );
+      // Post 2026-05-27 cloudflared-URL refresh: the install hint moved
+      // off apt-get / dnf / developers.cloudflare.com (all unreliable —
+      // Aaron hit `No match for argument: cloudflared` on AL2023 and
+      // 404s from the docs URL on the same box) onto the static binary
+      // from GitHub releases.
+      expect(joined).toContain("github.com/cloudflare/cloudflared/releases/latest");
+      expect(joined).toContain("curl -L -o /usr/local/bin/cloudflared");
+      expect(joined).not.toContain("developers.cloudflare.com");
+      expect(joined).not.toContain("pkg.cloudflare.com");
+      expect(joined).not.toContain("sudo dnf install cloudflared");
     } finally {
       env.cleanup();
     }

package/src/__tests__/expose-public-auto.test.ts

@@ -126,7 +126,11 @@ describe("exposePublicAutoPick — neither ready", () => {
     expect(code).toBe(1);
     const joined = logs.join("\n");
     expect(joined).toContain("tailscale.com/download");
-    expect(joined).toContain("developers.cloudflare.com");
+    // Post 2026-05-27 cloudflared-URL refresh: the install hint now points
+    // at GitHub releases (developers.cloudflare.com / pkg.cloudflare.com
+    // both returned HTML/404 on Aaron's fresh AL2023 EC2 box).
+    expect(joined).toContain("github.com/cloudflare/cloudflared/releases/latest");
+    expect(joined).not.toContain("developers.cloudflare.com");
     expect(joined).toContain("--skip-provider-check");
   });
 

package/src/__tests__/init.test.ts

@@ -0,0 +1,344 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { init, resolveAdminUrl } from "../commands/init.ts";
+import type { ExposeState } from "../expose-state.ts";
+import { writeHubPort } from "../hub-control.ts";
+import { writePid } from "../process-state.ts";
+
+interface Harness {
+  configDir: string;
+  manifestPath: string;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-init-"));
+  const manifestPath = join(dir, "services.json");
+  writeFileSync(manifestPath, JSON.stringify({ services: [] }));
+  return {
+    configDir: dir,
+    manifestPath,
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+function seedVault(manifestPath: string): void {
+  writeFileSync(
+    manifestPath,
+    JSON.stringify({
+      services: [
+        {
+          name: "parachute-vault",
+          version: "0.5.0",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/health",
+          icon: "/icon.svg",
+          auth: { type: "none" },
+          mcp: {},
+        },
+      ],
+    }),
+  );
+}
+
+describe("resolveAdminUrl", () => {
+  test("prefers expose-state FQDN when present", () => {
+    const state: ExposeState = {
+      version: 1,
+      layer: "tailnet",
+      mode: "path",
+      canonicalFqdn: "box-1.tailnet.ts.net",
+      port: 443,
+      funnel: false,
+      entries: [],
+      hubOrigin: "https://box-1.tailnet.ts.net",
+    };
+    expect(resolveAdminUrl(state, 1939)).toBe("https://box-1.tailnet.ts.net/admin/");
+  });
+
+  test("falls back to loopback + hub port when no exposure", () => {
+    expect(resolveAdminUrl(undefined, 1939)).toBe("http://127.0.0.1:1939/admin/");
+  });
+
+  test("undefined when neither expose-state nor a hub port is known", () => {
+    expect(resolveAdminUrl(undefined, undefined)).toBeUndefined();
+  });
+});
+
+describe("init", () => {
+  test("starts the hub when not running and prints the loopback admin URL", async () => {
+    const h = makeHarness();
+    try {
+      const calls: string[] = [];
+      const logs: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => logs.push(l),
+        alive: () => false,
+        ensureHub: async () => {
+          calls.push("ensureHub");
+          // Seed the port file as a real ensureHubRunning would.
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(calls).toEqual(["ensureHub"]);
+      const joined = logs.join("\n");
+      expect(joined).toContain("Hub not running — starting it now");
+      expect(joined).toContain("Hub started (pid 5555, port 1939)");
+      expect(joined).toContain("http://127.0.0.1:1939/admin/");
+      expect(joined).toContain("finish setup in the admin wizard");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("idempotent: skips ensureHub and confirms 'looks good' when hub up + vault configured", async () => {
+    const h = makeHarness();
+    try {
+      // Seed: hub running + vault row exists.
+      mkdirSync(join(h.configDir, "hub", "run"), { recursive: true });
+      writePid("hub", 1234, h.configDir);
+      writeHubPort(1939, h.configDir);
+      seedVault(h.manifestPath);
+
+      const calls: string[] = [];
+      const logs: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => logs.push(l),
+        alive: () => true,
+        ensureHub: async () => {
+          calls.push("ensureHub");
+          return { pid: 1234, port: 1939, started: false };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      // Hub was already running — ensureHub should not have been called.
+      expect(calls).toEqual([]);
+      const joined = logs.join("\n");
+      expect(joined).toContain("Hub already running (pid 1234, port 1939)");
+      expect(joined).toContain("Looks good");
+      expect(joined).toContain("http://127.0.0.1:1939/admin/");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("prefers the exposed FQDN over loopback", async () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.configDir, "hub", "run"), { recursive: true });
+      writePid("hub", 4321, h.configDir);
+      writeHubPort(1939, h.configDir);
+
+      const state: ExposeState = {
+        version: 1,
+        layer: "public",
+        mode: "path",
+        canonicalFqdn: "gitcoin.parachute.computer",
+        port: 443,
+        funnel: false,
+        entries: [],
+        hubOrigin: "https://gitcoin.parachute.computer",
+      };
+
+      const logs: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => logs.push(l),
+        alive: () => true,
+        ensureHub: async () => ({ pid: 4321, port: 1939, started: false }),
+        readExposeStateFn: () => state,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(logs.join("\n")).toContain("https://gitcoin.parachute.computer/admin/");
+      // Not the loopback fallback.
+      expect(logs.join("\n")).not.toContain("http://127.0.0.1");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("offers to open the browser in a TTY; 'y' invokes openBrowser", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      const opened: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => ({ pid: 7, port: 1939, started: true }),
+        readExposeStateFn: () => undefined,
+        isTty: true,
+        platform: "darwin",
+        prompt: async () => "y",
+        openBrowser: (url) => {
+          opened.push(url);
+          return true;
+        },
+      });
+      expect(code).toBe(0);
+      expect(opened).toEqual(["http://127.0.0.1:1939/admin/"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("offers to open the browser in a TTY; 'n' skips openBrowser", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      const opened: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => ({ pid: 7, port: 1939, started: true }),
+        readExposeStateFn: () => undefined,
+        isTty: true,
+        platform: "darwin",
+        prompt: async () => "n",
+        openBrowser: (url) => {
+          opened.push(url);
+          return true;
+        },
+      });
+      expect(code).toBe(0);
+      expect(opened).toEqual([]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--no-browser skips the prompt and openBrowser entirely", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      const opened: string[] = [];
+      let prompted = false;
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => ({ pid: 7, port: 1939, started: true }),
+        readExposeStateFn: () => undefined,
+        isTty: true,
+        platform: "darwin",
+        prompt: async () => {
+          prompted = true;
+          return "y";
+        },
+        openBrowser: (url) => {
+          opened.push(url);
+          return true;
+        },
+        noBrowser: true,
+      });
+      expect(code).toBe(0);
+      expect(prompted).toBe(false);
+      expect(opened).toEqual([]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("non-TTY prints the URL and exits without prompting", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      let prompted = false;
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => ({ pid: 7, port: 1939, started: true }),
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "darwin",
+        prompt: async () => {
+          prompted = true;
+          return "y";
+        },
+        openBrowser: () => true,
+      });
+      expect(code).toBe(0);
+      expect(prompted).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("Windows / unsupported platform: skip browser launch, just print", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      const opened: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => ({ pid: 7, port: 1939, started: true }),
+        readExposeStateFn: () => undefined,
+        isTty: true,
+        platform: "win32",
+        prompt: async () => "y",
+        openBrowser: (url) => {
+          opened.push(url);
+          return true;
+        },
+      });
+      expect(code).toBe(0);
+      // No prompt offered on Windows — just URL printed.
+      expect(opened).toEqual([]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("ensureHub failure exits 1 with an actionable hint", async () => {
+    const h = makeHarness();
+    try {
+      const logs: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => logs.push(l),
+        alive: () => false,
+        ensureHub: async () => {
+          throw new Error("port 1939 is in use");
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(1);
+      const joined = logs.join("\n");
+      expect(joined).toContain("Hub failed to start: port 1939 is in use");
+      expect(joined).toContain("parachute logs hub");
+    } finally {
+      h.cleanup();
+    }
+  });
+});