@openparachute/hub 0.6.3 → 0.6.4-rc.10

package/src/__tests__/auto-wire.test.ts

@@ -2,7 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { SCRIBE_AUTH_ENV_KEY, SCRIBE_URL_ENV_KEY, autoWireScribeAuth } from "../auto-wire.ts";
+import {
+  SCRIBE_AUTH_ENV_KEY,
+  SCRIBE_URL_ENV_KEY,
+  autoWireScribeAuth,
+  selfHealScribeAuth,
+} from "../auto-wire.ts";
 import { writePid } from "../process-state.ts";
 
 function makeHarness(): { dir: string; cleanup: () => void } {
@@ -281,3 +286,98 @@ describe("autoWireScribeAuth", () => {
     }
   });
 });
+
+// Item H — serve-boot self-heal of scribe's auth token from vault's .env.
+describe("selfHealScribeAuth", () => {
+  function seedVaultToken(dir: string, token: string): void {
+    mkdirSync(join(dir, "vault"), { recursive: true });
+    writeFileSync(join(dir, "vault", ".env"), `${SCRIBE_AUTH_ENV_KEY}=${token}\n`);
+  }
+  function seedScribeConfig(dir: string, config: Record<string, unknown>): void {
+    mkdirSync(join(dir, "scribe"), { recursive: true });
+    writeFileSync(join(dir, "scribe", "config.json"), `${JSON.stringify(config, null, 2)}\n`);
+  }
+  function readScribeConfig(dir: string): Record<string, unknown> {
+    return JSON.parse(readFileSync(join(dir, "scribe", "config.json"), "utf8"));
+  }
+
+  test("vault .env has token + scribe config missing auth → self-heal writes it", () => {
+    const h = makeHarness();
+    try {
+      seedVaultToken(h.dir, "shared-secret-xyz");
+      seedScribeConfig(h.dir, { provider: "openai", model: "whisper-1" });
+      const logs: string[] = [];
+      const result = selfHealScribeAuth({ configDir: h.dir, log: (l) => logs.push(l) });
+      expect(result.healed).toBe(true);
+      const cfg = readScribeConfig(h.dir);
+      expect((cfg.auth as Record<string, unknown>).required_token).toBe("shared-secret-xyz");
+      // Other config keys preserved (merge-don't-clobber).
+      expect(cfg.provider).toBe("openai");
+      expect(cfg.model).toBe("whisper-1");
+      expect(logs.join("\n")).toMatch(/Self-healed scribe auth/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("scribe config wholly absent → self-heal creates it with the token", () => {
+    const h = makeHarness();
+    try {
+      seedVaultToken(h.dir, "shared-secret-xyz");
+      // No scribe/config.json at all.
+      const result = selfHealScribeAuth({ configDir: h.dir });
+      expect(result.healed).toBe(true);
+      expect((readScribeConfig(h.dir).auth as Record<string, unknown>).required_token).toBe(
+        "shared-secret-xyz",
+      );
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("scribe token mismatches vault → re-synced to vault's value", () => {
+    const h = makeHarness();
+    try {
+      seedVaultToken(h.dir, "vault-token-NEW");
+      seedScribeConfig(h.dir, { auth: { required_token: "stale-token-OLD" }, model: "x" });
+      const result = selfHealScribeAuth({ configDir: h.dir });
+      expect(result.healed).toBe(true);
+      const cfg = readScribeConfig(h.dir);
+      expect((cfg.auth as Record<string, unknown>).required_token).toBe("vault-token-NEW");
+      expect(cfg.model).toBe("x");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("already in sync → no-op (idempotent), config untouched", () => {
+    const h = makeHarness();
+    try {
+      seedVaultToken(h.dir, "same-token");
+      seedScribeConfig(h.dir, { auth: { required_token: "same-token" }, extra: "keep" });
+      const before = readFileSync(join(h.dir, "scribe", "config.json"), "utf8");
+      const result = selfHealScribeAuth({ configDir: h.dir });
+      expect(result.healed).toBe(false);
+      expect(result.reason).toBe("already-synced");
+      // Byte-identical — no rewrite.
+      expect(readFileSync(join(h.dir, "scribe", "config.json"), "utf8")).toBe(before);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("vault has no SCRIBE_AUTH_TOKEN → no-op (nothing to sync)", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "vault"), { recursive: true });
+      writeFileSync(join(h.dir, "vault", ".env"), "FOO=bar\n");
+      const result = selfHealScribeAuth({ configDir: h.dir });
+      expect(result.healed).toBe(false);
+      expect(result.reason).toBe("no-token");
+      // Scribe config not created.
+      expect(existsSync(join(h.dir, "scribe", "config.json"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/cli.test.ts

@@ -1,9 +1,10 @@
-import { describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { appendFileSync, cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 const CLI = join(import.meta.dir, "..", "cli.ts");
+const REPO_ROOT = join(import.meta.dir, "..", "..");
 
 async function runCli(
   args: string[],
@@ -277,6 +278,191 @@ describe("cli per-subcommand help", () => {
   });
 });
 
+describe("cli lazy-import isolation (feedback #9)", () => {
+  // Regression for the eager-import fragility: `cli.ts` used to import every
+  // command module at top-level, so a module that THREW at eval-time (the 0.6.2
+  // `migrate-cutover.ts` ReferenceError) aborted the entire CLI load — even
+  // `parachute --help` — because top-level import evaluation runs before
+  // `run()`'s try/catch is reached. Per-arm lazy `await import()` isolates a
+  // broken module to its own command.
+  //
+  // We exercise the REAL dispatcher: copy the live `src/` tree (plus the repo
+  // `package.json`, which `cli.ts` imports as `../package.json`) into a sandbox
+  // *inside the repo* so workspace `node_modules` resolution still works, then
+  // corrupt one command module so it throws at module-eval. `node_modules` is
+  // NOT copied — Bun walks up to the repo's. The corruption never touches the
+  // real source tree, so concurrent suites are unaffected.
+  let sandbox: string;
+  let sandboxCli: string;
+
+  beforeAll(() => {
+    // The sandbox lives INSIDE the repo (`<repo>/.tmp-cli-iso-*`) on purpose: it
+    // copies `src/` + `package.json` but NOT `node_modules`. The sandboxed CLI
+    // still resolves workspace packages (`@openparachute/depcheck`, etc.) by Bun
+    // walking up the directory tree to the **repo-root** `node_modules` — the same
+    // walk a nested file uses. So this suite REQUIRES `node_modules` installed at
+    // the repo root. CI must `bun install` before running it; a fresh worktree
+    // without an install will see `Cannot find module '@openparachute/...'`
+    // failures that are worktree-resolution artifacts, NOT a regression in the
+    // code under test. (A temp dir under `os.tmpdir()` would break this walk and
+    // also break `cli.ts`'s `../package.json` import, hence the in-repo sandbox.)
+    sandbox = mkdtempSync(join(REPO_ROOT, ".tmp-cli-iso-"));
+    cpSync(join(REPO_ROOT, "src"), join(sandbox, "src"), { recursive: true });
+    cpSync(join(REPO_ROOT, "package.json"), join(sandbox, "package.json"));
+    sandboxCli = join(sandbox, "src", "cli.ts");
+    // Append an unconditional throw so the module fails at eval. `migrate-cutover`
+    // is the canonical real-world case (the 0.6.2 bug) AND it's reachable by both
+    // eager paths the fix addresses: the direct `cli.ts` import and the transitive
+    // `cli.ts → lifecycle.ts → migrate-offer.ts → migrate-cutover.ts` chain.
+    appendFileSync(
+      join(sandbox, "src", "commands", "migrate-cutover.ts"),
+      '\nthrow new ReferenceError("boom: migrate-cutover failed at module eval");\n',
+    );
+  });
+
+  afterAll(() => {
+    if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  async function runSandbox(
+    args: string[],
+  ): Promise<{ code: number; stdout: string; stderr: string }> {
+    const proc = Bun.spawn([process.execPath, sandboxCli, ...args], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        HOME: "/tmp/parachute-hub-nonexistent-home",
+        PARACHUTE_HOME: "/tmp/parachute-hub-nonexistent-home",
+      },
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { code, stdout, stderr };
+  }
+
+  test("a command module that throws at eval does NOT abort --help", async () => {
+    const { code, stdout } = await runSandbox(["--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/parachute install/);
+  });
+
+  test("an unrelated command still dispatches when one module is broken", async () => {
+    // `status` doesn't touch migrate-cutover at all — it must still run to
+    // completion (exit 0) rather than dying at top-level import.
+    const { code } = await runSandbox(["status"]);
+    expect(code).toBe(0);
+  });
+
+  test("lifecycle commands survive the broken transitive path", async () => {
+    // `stop` pulls in `migrate-offer.ts` (for the §7.5 detect-and-offer), which
+    // used to EAGERLY import the broken `migrate-cutover.ts`. With the import now
+    // `import type` + lazy, `stop --help` must not crash.
+    const { code, stdout } = await runSandbox(["stop", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/parachute stop/);
+  });
+
+  test("the broken command itself exits 1 with a 'failed to load' message", async () => {
+    const { code, stderr } = await runSandbox(["migrate", "--to-supervised"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/parachute migrate: failed to load/);
+    expect(stderr).toMatch(/boom: migrate-cutover failed at module eval/);
+  });
+});
+
+// hub#534: `migrate --teardown` must surface teardownHubUnit's outcome — pre-fix
+// it ignored `removed` + `messages` and always exited 0, so a non-removal looked
+// like success. We exercise the REAL CLI arm via the in-repo sandbox (same shape
+// as the lazy-import suite above) so the arm's exit-code mapping runs end-to-end
+// without shelling out to real launchctl/systemctl: the sandboxed
+// `teardownHubUnit` is replaced with a stub keyed off an env var.
+describe("cli migrate --teardown exit-code policy (hub#534)", () => {
+  let sandbox: string;
+  let sandboxCli: string;
+
+  beforeAll(() => {
+    sandbox = mkdtempSync(join(REPO_ROOT, ".tmp-cli-teardown-"));
+    cpSync(join(REPO_ROOT, "src"), join(sandbox, "src"), { recursive: true });
+    cpSync(join(REPO_ROOT, "package.json"), join(sandbox, "package.json"));
+    sandboxCli = join(sandbox, "src", "cli.ts");
+    // Replace migrate-cutover.ts entirely with a minimal stub exporting only the
+    // `teardownHubUnit` the CLI arm calls. Its result is driven by
+    // `TEARDOWN_FAKE` so one rewrite covers all three outcomes. It logs the same
+    // human-facing lines the real function would (so the stdout assertions match
+    // real behavior), and the CLI owns the exit code.
+    writeFileSync(
+      join(sandbox, "src", "commands", "migrate-cutover.ts"),
+      [
+        "export function teardownHubUnit() {",
+        '  const mode = process.env.TEARDOWN_FAKE ?? "removed";',
+        '  if (mode === "removed") {',
+        '    console.log("Removed systemd unit parachute-hub.service — the hub no longer starts on boot.");',
+        "    return { removed: true, messages: [] };",
+        "  }",
+        '  if (mode === "failure") {',
+        '    console.log("Hub-unit teardown did not complete:");',
+        '    console.log("  systemctl disable failed: permission denied");',
+        '    return { removed: false, messages: ["systemctl disable failed: permission denied"] };',
+        "  }",
+        '  console.log("No hub unit was installed — nothing to tear down.");',
+        "  return { removed: false, messages: [] };",
+        "}",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  afterAll(() => {
+    if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  async function runTeardown(
+    fake: string,
+  ): Promise<{ code: number; stdout: string; stderr: string }> {
+    const proc = Bun.spawn([process.execPath, sandboxCli, "migrate", "--teardown"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        HOME: "/tmp/parachute-hub-nonexistent-home",
+        PARACHUTE_HOME: "/tmp/parachute-hub-nonexistent-home",
+        TEARDOWN_FAKE: fake,
+      },
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { code, stdout, stderr };
+  }
+
+  test("removed → exit 0 with the removal message", async () => {
+    const { code, stdout } = await runTeardown("removed");
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/Removed systemd unit/);
+  });
+
+  test("nothing installed → informational exit 0", async () => {
+    const { code, stdout } = await runTeardown("nothing");
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/nothing to tear down/);
+  });
+
+  test("removal failure (messages present) → exit 1, reason on stderr", async () => {
+    const { code, stdout, stderr } = await runTeardown("failure");
+    expect(code).toBe(1);
+    // The function logged the failure header to stdout; the CLI re-surfaces the
+    // detail on stderr so a script's `2>` capture sees the reason.
+    expect(stdout).toMatch(/did not complete/);
+    expect(stderr).toMatch(/permission denied/);
+  });
+});
+
 describe("cli friendly errors", () => {
   test("malformed services.json prints friendly error not stack trace", async () => {
     const dir = mkdtempSync(join(tmpdir(), "pcli-bad-"));

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

@@ -7,12 +7,15 @@ import {
   CloudflaredStateError,
   type CloudflaredTunnelRecord,
   clearCloudflaredState,
+  clearPendingHostname,
   findTunnelRecord,
   listTunnelRecords,
   readCloudflaredState,
+  readPendingHostname,
   withTunnelRecord,
   withoutTunnelRecord,
   writeCloudflaredState,
+  writePendingHostname,
 } from "../cloudflare/state.ts";
 
 function makeTempPath(): { path: string; cleanup: () => void } {
@@ -250,3 +253,104 @@ describe("cloudflared state — record helpers", () => {
     expect(listTunnelRecords(undefined)).toEqual([]);
   });
 });
+
+describe("hub#567 pending hostname", () => {
+  test("read returns undefined when no state file / no pending hostname", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      expect(readPendingHostname(path)).toBeUndefined();
+      writeCloudflaredState(sample, path);
+      expect(readPendingHostname(path)).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("write then read round-trips the pending hostname (seeds empty state)", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writePendingHostname("techne.parachute.computer", path);
+      expect(readPendingHostname(path)).toBe("techne.parachute.computer");
+      const state = readCloudflaredState(path);
+      expect(state?.pendingHostname).toBe("techne.parachute.computer");
+      expect(state?.tunnels).toEqual({});
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("write preserves existing tunnel records", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeCloudflaredState(sample, path);
+      writePendingHostname("techne.parachute.computer", path);
+      const state = readCloudflaredState(path);
+      expect(state?.pendingHostname).toBe("techne.parachute.computer");
+      expect(state?.tunnels.parachute).toEqual(sampleRecord);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("clear drops the pending hostname but keeps tunnel records", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writeCloudflaredState({ ...sample, pendingHostname: "techne.parachute.computer" }, path);
+      clearPendingHostname(path);
+      const state = readCloudflaredState(path);
+      expect(state?.pendingHostname).toBeUndefined();
+      expect(state?.tunnels.parachute).toEqual(sampleRecord);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("clear removes the state file entirely when no tunnels remain", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      writePendingHostname("techne.parachute.computer", path);
+      expect(existsSync(path)).toBe(true);
+      clearPendingHostname(path);
+      expect(existsSync(path)).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("validate preserves a pending hostname round-tripped through the bytes", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const withPending: CloudflaredState = { ...sample, pendingHostname: "a.example.com" };
+      writeCloudflaredState(withPending, path);
+      expect(readCloudflaredState(path)).toEqual(withPending);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("withTunnelRecord preserves an existing pending hostname", () => {
+    const seed: CloudflaredState = { version: 2, tunnels: {}, pendingHostname: "a.example.com" };
+    const next = withTunnelRecord(seed, sampleRecord);
+    expect(next.pendingHostname).toBe("a.example.com");
+    expect(next.tunnels.parachute).toEqual(sampleRecord);
+  });
+
+  test("withoutTunnelRecord carries the pending hostname when it's the only thing left", () => {
+    const seed: CloudflaredState = {
+      version: 2,
+      tunnels: { parachute: sampleRecord },
+      pendingHostname: "a.example.com",
+    };
+    // Removing the last tunnel must NOT discard a typed-but-not-routed hostname.
+    expect(withoutTunnelRecord(seed, "parachute")).toEqual({
+      version: 2,
+      tunnels: {},
+      pendingHostname: "a.example.com",
+    });
+  });
+
+  test("withoutTunnelRecord returns undefined when no tunnels AND no pending hostname remain", () => {
+    const seed: CloudflaredState = { version: 2, tunnels: { parachute: sampleRecord } };
+    expect(withoutTunnelRecord(seed, "parachute")).toBeUndefined();
+  });
+});

package/src/__tests__/expose-2fa-warning.test.ts

@@ -87,13 +87,16 @@ describe("printPublic2FAWarning", () => {
     });
     expect(fired).toBe(true);
     const joined = logs.join("\n");
-    // hub#473: real hub-login 2FA. The warning now recommends the real
-    // `parachute auth 2fa enroll` path (+ the /account/2fa browser path) and
-    // still nudges a strong owner password.
-    expect(joined).toContain("/login is now reachable on the public internet");
+    // hub#473: real hub-login 2FA. The recommendation now leads with the
+    // friendly "strongly recommended" framing, points at both the /account/2fa
+    // browser path and the `parachute auth 2fa enroll` CLI path, makes clear
+    // it's not a requirement, and still nudges a strong owner password.
+    expect(joined).toContain("Strongly recommended: turn on two-factor authentication");
+    expect(joined).toContain("reachable from the public internet");
     expect(joined).toContain("https://vault.example.com/login");
+    expect(joined).toContain("https://vault.example.com/account/2fa");
     expect(joined).toContain("parachute auth 2fa enroll");
-    expect(joined).toContain("/account/2fa");
+    expect(joined).toContain("It's a recommendation, not a requirement");
     expect(joined).toContain("parachute auth set-password");
   });
 
@@ -120,9 +123,9 @@ describe("printPublic2FAWarning", () => {
       publicUrl: "https://vault.example.com",
     });
     expect(fired).toBe(true);
-    expect(logs.some((l) => l.includes("/login is now reachable on the public internet"))).toBe(
-      true,
-    );
+    expect(
+      logs.some((l) => l.includes("Strongly recommended: turn on two-factor authentication")),
+    ).toBe(true);
   });
 
   test("embeds the supplied publicUrl into the /login pointer", () => {

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

@@ -509,16 +509,31 @@ describe("exposeCloudflareUp", () => {
     }
   });
 
-  test("errors out when vault isn't installed", async () => {
+  test("hub#564: continues (no vault gate) when vault isn't installed — routes the hub anyway", async () => {
     const env = makeEnv({ includeVault: false });
     try {
-      const { runner } = queueRunner([{ code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" }]);
-      const { spawner } = fakeSpawner(0);
+      const uuid = "3d2b8d8f-2345-6789-abcd-ef0123456789";
+      const derived = "parachute-vault-example-com";
+      // The full chain must run now that the vault gate is gone: version,
+      // tunnel list, tunnel create, route dns.
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" }, // --version
+        { code: 0, stdout: "[]", stderr: "" }, // tunnel list
+        {
+          code: 0,
+          stdout: `Created tunnel ${derived} with id ${uuid}\n`,
+          stderr: "",
+        }, // create
+        { code: 0, stdout: "", stderr: "" }, // route dns
+      ]);
+      const { spawner } = fakeSpawner(42000);
       const logs: string[] = [];
 
       const code = await exposeCloudflareUp("vault.example.com", {
         runner,
         spawner,
+        alive: () => false,
+        kill: () => {},
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
@@ -528,10 +543,17 @@ describe("exposeCloudflareUp", () => {
         cloudflaredHome: env.cloudflaredHome,
         configDir: env.configDir,
         skipHub: true,
+        now: () => new Date("2026-04-22T12:00:00Z"),
       });
 
-      expect(code).toBe(1);
-      expect(logs.join("\n")).toContain("parachute install vault");
+      // The expose succeeds (the hub is what gets routed), with a courtesy
+      // note instead of a dead-end. No "install vault" gate, no Vault-URL
+      // footer (vault isn't there to point at).
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("vault not installed yet");
+      expect(joined).not.toContain("nothing to route");
+      expect(joined).not.toMatch(/^\s*Vault:/m);
     } finally {
       env.cleanup();
     }
@@ -1230,9 +1252,10 @@ describe("exposeCloudflareUp", () => {
 
         expect(code).toBe(0);
         const joined = logs.join("\n");
-        // hub#473: real hub-login 2FA — the warning now recommends the real
-        // `parachute auth 2fa enroll` path.
-        expect(joined).toContain("/login is now reachable on the public internet");
+        // hub#473: real hub-login 2FA — the recommendation now leads with the
+        // friendly "strongly recommended" framing and the real `parachute auth
+        // 2fa enroll` / `/account/2fa` paths.
+        expect(joined).toContain("Strongly recommended: turn on two-factor authentication");
         expect(joined).toContain("https://vault.example.com/login");
         expect(joined).toContain("parachute auth 2fa enroll");
       } finally {
@@ -1281,7 +1304,7 @@ describe("exposeCloudflareUp", () => {
 
         expect(code).toBe(0);
         const joined = logs.join("\n");
-        expect(joined).not.toContain("/login is now reachable on the public internet");
+        expect(joined).not.toContain("Strongly recommended: turn on two-factor authentication");
         // The contextual 2FA warning is suppressed (2FA already enrolled); the
         // always-shown owner-password guidance from `printAuthGuidance` still
         // appears, and it now (hub#473) also surfaces the real `2fa enroll`
@@ -1441,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 {