@openparachute/hub 0.6.4-rc.7 → 0.6.4-rc.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.4-rc.7",
+  "version": "0.6.4-rc.9",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/account-home-ui.test.ts

@@ -660,6 +660,47 @@ describe("renderAccountHome", () => {
     expect(html).toContain('data-testid="vault-card"');
   });
 
+  test("onboarding condensed state keeps a 'Connect another AI' expander with the full instructions (hub#583)", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      connectedVault: true,
+    });
+    // The expander itself...
+    expect(html).toContain('data-testid="onboarding-connect-another"');
+    expect(html).toContain('data-testid="onboarding-connect-another-summary"');
+    expect(html).toContain("Connect another AI");
+    // ...re-reveals the endpoint + BOTH connect methods that the condensed
+    // line used to delete entirely (the hub#583 defect).
+    expect(html).toContain('data-testid="onboarding-mcp-endpoint"');
+    expect(html).toContain('data-testid="onboarding-mcp-add-command"');
+    expect(html).toContain("Claude.ai (web)");
+    expect(html).toContain("Claude Code (terminal)");
+  });
+
+  test("onboarding NON-condensed (not connected) state has no 'Connect another AI' expander (hub#583)", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      connectedVault: false,
+    });
+    // Full checklist already shows the inline instructions in step 2, so the
+    // expander is condensed-state-only.
+    expect(html).not.toContain('data-testid="onboarding-connect-another"');
+    expect(html).toContain('data-testid="onboarding-step-2"');
+    expect(html).toContain('data-testid="onboarding-mcp-endpoint"');
+  });
+
   test("onboarding checklist — leads the page: BEFORE the vault card and the starter prompts", () => {
     const html = renderAccountHome({
       username: "alice",

package/src/__tests__/api-account.test.ts

@@ -28,7 +28,9 @@ import {
   handleAccountHomeGet,
   markPasswordChanged,
 } from "../api-account.ts";
+import { registerClient } from "../clients.ts";
 import { CSRF_COOKIE_NAME, CSRF_FIELD_NAME } from "../csrf.ts";
+import { recordGrant } from "../grants.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { recordTokenMint } from "../jwt-sign.ts";
 import {
@@ -832,6 +834,65 @@ describe("handleAccountHomeGet", () => {
     expect(html).toContain(`https://notes.parachute.computer/add?url=${encoded}`);
   });
 
+  test("onboarding NOT condensed when only a first-party browser grant exists (hub#583, GET /account/)", async () => {
+    // The exact field report: create account → open Notes (a first-party OAuth
+    // client that writes a vault-scoped grant) → later visit /account/ to wire
+    // up Claude. The checklist must NOT already be condensed.
+    await createUser(harness.db, "admin", "admin-passphrase", { passwordChanged: true });
+    const friend = await createUser(harness.db, "alice", "alice-passphrase", {
+      allowMulti: true,
+      passwordChanged: true,
+      assignedVaults: ["alice"],
+    });
+    // Notes signs in via DCR (generated client_id, client_name "Notes") and
+    // records a vault-scoped grant.
+    const notes = registerClient(harness.db, {
+      redirectUris: ["https://hub.test/notes/cb"],
+      clientName: "Notes",
+    });
+    recordGrant(harness.db, friend.id, notes.client.clientId, ["vault:alice:read"]);
+
+    const session = createSession(harness.db, { userId: friend.id });
+    const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+    const req = new Request(`${HUB_ORIGIN}/account/`, { headers: { cookie } });
+    const res = await handleAccountHomeGet(req, { db: harness.db, hubOrigin: HUB_ORIGIN });
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    // Full checklist (not condensed): the connect step is present, the
+    // "you're connected" done-line is NOT.
+    expect(html).toContain('data-connected="false"');
+    expect(html).toContain('data-testid="onboarding-step-2"');
+    expect(html).not.toContain('data-testid="onboarding-done-line"');
+  });
+
+  test("onboarding condensed when an external AI client grant exists (hub#583, GET /account/)", async () => {
+    await createUser(harness.db, "admin", "admin-passphrase", { passwordChanged: true });
+    const friend = await createUser(harness.db, "alice", "alice-passphrase", {
+      allowMulti: true,
+      passwordChanged: true,
+      assignedVaults: ["alice"],
+    });
+    // Claude Code: a genuine external MCP client.
+    const claude = registerClient(harness.db, {
+      redirectUris: ["https://claude.ai/cb"],
+      clientName: "Claude",
+    });
+    recordGrant(harness.db, friend.id, claude.client.clientId, ["vault:alice:read"]);
+
+    const session = createSession(harness.db, { userId: friend.id });
+    const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+    const req = new Request(`${HUB_ORIGIN}/account/`, { headers: { cookie } });
+    const res = await handleAccountHomeGet(req, { db: harness.db, hubOrigin: HUB_ORIGIN });
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    // Condensed done-state.
+    expect(html).toContain('data-connected="true"');
+    expect(html).toContain('data-testid="onboarding-done-line"');
+    expect(html).toContain("You're connected");
+    // And it still keeps the "Connect another AI" expander.
+    expect(html).toContain('data-testid="onboarding-connect-another"');
+  });
+
   test("200 + admin branch when the first-admin signs in (no vault assignments)", async () => {
     // The first-created user with no vault pin is the admin posture.
     const admin = await createUser(harness.db, "admin", "admin-passphrase", {

package/src/__tests__/api-modules-ops.test.ts

@@ -1671,13 +1671,19 @@ describe("well-known regen after module ops", () => {
     const vaultRow = manifest.services.find((s) => s.name === "parachute-vault");
     expect(vaultRow?.installDir).toBe(install.installDir);
 
-    // The on-disk well-known doc reflects the new module.
+    // The on-disk well-known doc reflects the new module in `services`...
     const doc = JSON.parse(readFileSync(wkPath, "utf8")) as {
       services: Array<{ name: string; version: string }>;
       vaults: Array<{ name: string }>;
     };
     expect(doc.services.some((s) => s.name === "parachute-vault")).toBe(true);
-    expect(doc.vaults.some((v) => v.name === "default")).toBe(true);
+    // ...but does NOT fabricate a phantom `default` vault row (hub#577). The
+    // install seeds the entry at SEED_VERSION ("module installed, no instance
+    // booted"); vault's own boot registers the real instance later. Until then
+    // the vaults[] list is honestly empty so the management page reads "No
+    // vaults yet" rather than showing a `default` that doesn't exist.
+    expect(doc.vaults.some((v) => v.name === "default")).toBe(false);
+    expect(doc.vaults).toEqual([]);
   });
 
   test("runInstall sets PORT in child env from services.json entry (hub#356)", async () => {

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

@@ -1464,6 +1464,109 @@ describe("exposeCloudflareOff", () => {
     }
   });
 
+  test("clears stale PARACHUTE_HUB_ORIGIN from vault/.env on last-tunnel down (#503)", async () => {
+    const env = makeEnv();
+    try {
+      // Seed the stale public origin the up-path persisted into vault/.env.
+      // After teardown the hub is loopback-only, so leaving this would pin a
+      // public expected issuer and 401 every request on the next vault restart.
+      const vaultEnvPath = join(env.configDir, "vault", ".env");
+      require("node:fs").mkdirSync(join(env.configDir, "vault"), { recursive: true });
+      writeFileSync(vaultEnvPath, "PARACHUTE_HUB_ORIGIN=https://vault.example.com\n");
+
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            parachute: {
+              pid: 55557,
+              tunnelUuid: "ffffffff-0000-0000-0000-000000000006",
+              tunnelName: "parachute",
+              hostname: "vault.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+
+      const logs: string[] = [];
+      const code = await exposeCloudflareOff({
+        configDir: env.configDir,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => false,
+        kill: () => {},
+        log: (l) => logs.push(l),
+      });
+
+      expect(code).toBe(0);
+      // The stale public origin is gone — vault reverts to its loopback default.
+      expect(readEnvFileValues(vaultEnvPath).PARACHUTE_HUB_ORIGIN).toBeUndefined();
+      // Operator is told what to restart so a running vault picks up the change.
+      expect(logs.join("\n")).toContain("cleared PARACHUTE_HUB_ORIGIN");
+      expect(logs.join("\n")).toContain("parachute restart vault");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("leaves vault/.env untouched while other tunnels survive (#503)", async () => {
+    const env = makeEnv();
+    try {
+      const vaultEnvPath = join(env.configDir, "vault", ".env");
+      require("node:fs").mkdirSync(join(env.configDir, "vault"), { recursive: true });
+      writeFileSync(vaultEnvPath, "PARACHUTE_HUB_ORIGIN=https://vault.example.com\n");
+
+      // Two tunnels; tear down only one by name → the box stays exposed, so the
+      // persisted public origin must remain (clearing it would break the live
+      // tunnel's iss check). Symmetric with the expose-state.json retention.
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            alpha: {
+              pid: 55558,
+              tunnelUuid: "11111111-0000-0000-0000-000000000007",
+              tunnelName: "alpha",
+              hostname: "alpha.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+            beta: {
+              pid: 55559,
+              tunnelUuid: "22222222-0000-0000-0000-000000000008",
+              tunnelName: "beta",
+              hostname: "beta.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+
+      const code = await exposeCloudflareOff({
+        configDir: env.configDir,
+        tunnelName: "alpha",
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => false,
+        kill: () => {},
+        log: () => {},
+      });
+
+      expect(code).toBe(0);
+      // Beta tunnel survives → public origin stays.
+      expect(readEnvFileValues(vaultEnvPath).PARACHUTE_HUB_ORIGIN).toBe(
+        "https://vault.example.com",
+      );
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("clears stale state when the process is already gone", async () => {
     const env = makeEnv();
     try {

package/src/__tests__/grants.test.ts

@@ -8,9 +8,11 @@ import {
   findGrantByClientName,
   isCoveredByGrant,
   isCoveredByGrantForClientName,
+  isFirstPartyBrowserClient,
   listGrantsForUser,
   recordGrant,
   revokeGrant,
+  userHasExternalAiGrant,
   userHasVaultGrant,
 } from "../grants.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
@@ -395,3 +397,100 @@ describe("findGrantByClientName / isCoveredByGrantForClientName (hub#409)", () =
     }
   });
 });
+
+describe("userHasExternalAiGrant / isFirstPartyBrowserClient (hub#583)", () => {
+  test("isFirstPartyBrowserClient matches fixed first-party client_ids", () => {
+    expect(isFirstPartyBrowserClient("parachute-hub-spa", null)).toBe(true);
+    expect(isFirstPartyBrowserClient("parachute-account", null)).toBe(true);
+    expect(isFirstPartyBrowserClient("some-random-dcr-id", null)).toBe(false);
+  });
+
+  test("isFirstPartyBrowserClient matches Notes by client_name (case-insensitive)", () => {
+    expect(isFirstPartyBrowserClient("dcr-generated-id", "Notes")).toBe(true);
+    expect(isFirstPartyBrowserClient("dcr-generated-id", "notes")).toBe(true);
+    expect(isFirstPartyBrowserClient("dcr-generated-id", "Claude")).toBe(false);
+    expect(isFirstPartyBrowserClient("dcr-generated-id", null)).toBe(false);
+  });
+
+  test("a first-party browser grant does NOT count as a connected AI", async () => {
+    const h = await harness();
+    try {
+      // Notes signs in via DCR (generated client_id, client_name "Notes") and
+      // writes a vault-scoped grant — the exact false-positive in hub#583.
+      const notes = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "Notes",
+      });
+      recordGrant(h.db, h.userId, notes.client.clientId, ["vault:default:read"]);
+      // The coarse signal lights up...
+      expect(userHasVaultGrant(h.db, h.userId, "default")).toBe(true);
+      // ...but the AI-connection signal does NOT.
+      expect(userHasExternalAiGrant(h.db, h.userId, "default")).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("the fixed first-party SPA client_id does NOT count as a connected AI", async () => {
+    const h = await harness();
+    try {
+      registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientId: "parachute-hub-spa",
+      });
+      recordGrant(h.db, h.userId, "parachute-hub-spa", ["vault:default:read"]);
+      expect(userHasExternalAiGrant(h.db, h.userId, "default")).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("an external AI/MCP client grant DOES count as connected", async () => {
+    const h = await harness();
+    try {
+      // Claude Code: DCR-registered, ordinary client_name, vault scope.
+      const claude = registerClient(h.db, {
+        redirectUris: ["https://claude.ai/cb"],
+        clientName: "Claude",
+      });
+      recordGrant(h.db, h.userId, claude.client.clientId, ["vault:default:read"]);
+      expect(userHasExternalAiGrant(h.db, h.userId, "default")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("external grant is scoped to the named vault", async () => {
+    const h = await harness();
+    try {
+      const claude = registerClient(h.db, {
+        redirectUris: ["https://claude.ai/cb"],
+        clientName: "Claude",
+      });
+      recordGrant(h.db, h.userId, claude.client.clientId, ["vault:other:read"]);
+      expect(userHasExternalAiGrant(h.db, h.userId, "default")).toBe(false);
+      expect(userHasExternalAiGrant(h.db, h.userId, "other")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("Notes + Claude both granted: still counts (the external one wins)", async () => {
+    const h = await harness();
+    try {
+      const notes = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "Notes",
+      });
+      const claude = registerClient(h.db, {
+        redirectUris: ["https://claude.ai/cb"],
+        clientName: "Claude",
+      });
+      recordGrant(h.db, h.userId, notes.client.clientId, ["vault:default:read"]);
+      recordGrant(h.db, h.userId, claude.client.clientId, ["vault:default:read"]);
+      expect(userHasExternalAiGrant(h.db, h.userId, "default")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/hub-server.test.ts

@@ -1630,6 +1630,139 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
     }
   });
 
+  // #525: bare `/vault/<name>` POST (no `/mcp` suffix) half-connects MCP
+  // clients. The fix 308-redirects the bare-path POST to `<mount>/mcp` BEFORE
+  // proxying, so a compliant client re-POSTs to the right endpoint and clients
+  // that don't follow redirects at least get an actionable Location + JSON body
+  // (vs the old opaque vault 405).
+  test("POST to bare /vault/<name> 308-redirects to /vault/<name>/mcp with an actionable body (#525)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("aaron")] }, h.manifestPath);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/vault/aaron", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ jsonrpc: "2.0", method: "initialize", id: 1 }),
+        }),
+      );
+      expect(res.status).toBe(308);
+      expect(res.headers.get("location")).toBe("/vault/aaron/mcp");
+      // 308 is permanently cacheable by default — no-store prevents a cached
+      // redirect outliving a remount.
+      expect(res.headers.get("cache-control")).toBe("no-store");
+      const body = (await res.json()) as { error: string; mcp_url: string; message: string };
+      expect(body.error).toBe("missing_mcp_suffix");
+      expect(body.mcp_url).toBe("/vault/aaron/mcp");
+      expect(body.message).toContain("/vault/aaron/mcp");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("bare-path 308 honors a trailing-slash mount: POST /vault/default → /vault/default/mcp (#525)", async () => {
+    // Mounts in services.json sometimes carry a trailing slash (#197). The
+    // redirect target must be built from the *normalized* mount so it stays
+    // `/vault/default/mcp`, never `/vault/default//mcp`.
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-default",
+              port: 1940,
+              paths: ["/vault/default/"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/default", { method: "POST" }));
+      expect(res.status).toBe(308);
+      expect(res.headers.get("location")).toBe("/vault/default/mcp");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET to bare /vault/<name> is NOT redirected — proxies through untouched (#525)", async () => {
+    // Only POST (the MCP transport verb) is caught. A browser GET to the bare
+    // path keeps its existing proxy behavior so we don't break any bare-path
+    // GET surface.
+    const h = makeHarness();
+    const upstream = startUpstream("bare-get");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-aaron",
+              port: upstream.port,
+              paths: ["/vault/aaron"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/aaron", { method: "GET" }));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; method: string; pathname: string };
+      expect(body.tag).toBe("bare-get");
+      expect(body.method).toBe("GET");
+      expect(body.pathname).toBe("/vault/aaron");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("POST to the canonical /vault/<name>/mcp sub-path is NOT redirected — proxies through (#525)", async () => {
+    // The real MCP endpoint must keep working: a POST that already carries the
+    // `/mcp` suffix is a sub-path (not the exact bare mount) and proxies
+    // straight to the vault backend.
+    const h = makeHarness();
+    const upstream = startUpstream("mcp-post");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-aaron",
+              port: upstream.port,
+              paths: ["/vault/aaron"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/vault/aaron/mcp", {
+          method: "POST",
+          body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", id: 2 }),
+        }),
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; method: string; pathname: string };
+      expect(body.tag).toBe("mcp-post");
+      expect(body.method).toBe("POST");
+      expect(body.pathname).toBe("/vault/aaron/mcp");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
   test("synthesizes X-Forwarded-Proto when edge didn't set it (direct HTTPS to hub)", async () => {
     // Non-Render shape: hub bound directly to https (e.g. local TLS or a
     // proxy that doesn't set X-Forwarded-Proto). isHttpsRequest sees the

package/src/__tests__/init.test.ts

@@ -485,6 +485,142 @@ describe("init", () => {
   });
 });
 
+describe("init bootstrap-token first-claim (hub#576)", () => {
+  function publicState(): ExposeState {
+    return {
+      version: 1,
+      layer: "public",
+      mode: "path",
+      canonicalFqdn: "demo.parachute.computer",
+      port: 443,
+      funnel: false,
+      entries: [],
+      hubOrigin: "https://demo.parachute.computer",
+    };
+  }
+
+  test("publicly-exposed + wizard mode: prints the bootstrap token in the terminal", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      const probed: string[] = [];
+      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: () => publicState(),
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+        fetchBootstrapTokenImpl: async (loopbackUrl) => {
+          probed.push(loopbackUrl);
+          return "parachute-bootstrap-XYZ";
+        },
+      });
+      expect(code).toBe(0);
+      // Probed the LOOPBACK hub, not the public FQDN.
+      expect(probed).toEqual(["http://127.0.0.1:1939"]);
+      const joined = logs.join("\n");
+      expect(joined).toContain("parachute-bootstrap-XYZ");
+      expect(joined).toContain("bootstrap token");
+      // Still prints the public admin URL.
+      expect(joined).toContain("https://demo.parachute.computer/admin/");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("loopback-only install: does NOT probe or print a token", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      let probedCount = 0;
+      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: () => undefined, // no public exposure
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+        fetchBootstrapTokenImpl: async () => {
+          probedCount++;
+          return "parachute-bootstrap-XYZ";
+        },
+      });
+      expect(code).toBe(0);
+      expect(probedCount).toBe(0);
+      expect(logs.join("\n")).not.toContain("parachute-bootstrap-");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("admin already exists (no token): prints the URL without a token block", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      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: () => publicState(),
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+        // Hub returns undefined → already-claimed / no token to surface.
+        fetchBootstrapTokenImpl: async () => undefined,
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("https://demo.parachute.computer/admin/");
+      expect(joined).not.toContain("bootstrap token");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("CLI wizard is driven against the LOOPBACK hub, not the public FQDN", async () => {
+    const h = makeHarness();
+    try {
+      writeHubPort(1939, h.configDir);
+      const wizardUrls: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => true,
+        ensureHub: async () => ({ pid: 4321, port: 1939, started: false }),
+        readExposeStateFn: () => publicState(),
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+        wizardChoice: "cli",
+        fetchBootstrapTokenImpl: async () => "parachute-bootstrap-XYZ",
+        runCliWizardImpl: async ({ hubUrl }) => {
+          wizardUrls.push(hubUrl);
+          return 0;
+        },
+      });
+      expect(code).toBe(0);
+      // The CLI wizard runs on-box → must use loopback (where the hub hands it
+      // the token transparently), never the public FQDN.
+      expect(wizardUrls).toEqual(["http://127.0.0.1:1939"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 describe("looksLikeServer heuristic", () => {
   test("macOS is never a server", () => {
     expect(looksLikeServer("darwin", { SSH_CONNECTION: "1.2.3.4 22 5.6.7.8 22" })).toBe(false);