@openparachute/hub 0.6.4-rc.9 → 0.6.5-rc.1

package/package.json

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

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

@@ -3,9 +3,11 @@ import {
   CloudflaredError,
   createTunnel,
   credentialsPath,
+  deleteTunnel,
   findTunnelByName,
   listTunnels,
   routeDns,
+  tunnelConnectionCount,
 } from "../cloudflare/tunnel.ts";
 import type { CommandResult, Runner } from "../tailscale/run.ts";
 
@@ -204,4 +206,80 @@ describe("cloudflare tunnel", () => {
   test("credentialsPath joins uuid under the cloudflared home", () => {
     expect(credentialsPath("abc", "/Users/x/.cloudflared")).toBe("/Users/x/.cloudflared/abc.json");
   });
+
+  test("deleteTunnel passes --force and surfaces failures (#593)", async () => {
+    const { runner, seen } = makeRunner(
+      [["cloudflared", "tunnel", "delete", "--force", "parachute"]],
+      [{ code: 0, stdout: "Deleted tunnel parachute\n", stderr: "" }],
+    );
+    await deleteTunnel(runner, "parachute");
+    expect(seen[0]).toEqual(["cloudflared", "tunnel", "delete", "--force", "parachute"]);
+
+    const fail = makeRunner(
+      [["cloudflared", "tunnel", "delete", "--force", "parachute"]],
+      [{ code: 1, stdout: "", stderr: "tunnel has active connections" }],
+    );
+    await expect(deleteTunnel(fail.runner, "parachute")).rejects.toMatchObject({
+      message: expect.stringContaining("active connections"),
+    });
+  });
+
+  describe("tunnelConnectionCount (#593)", () => {
+    function infoRunner(result: CommandResult): Runner {
+      return async (cmd) => {
+        expect([...cmd]).toEqual([
+          "cloudflared",
+          "tunnel",
+          "info",
+          "--output",
+          "json",
+          "parachute",
+        ]);
+        return result;
+      };
+    }
+
+    test("counts connector entries under `conns`", async () => {
+      const runner = infoRunner({
+        code: 0,
+        stdout: JSON.stringify({ conns: [{ id: "a" }, { id: "b" }] }),
+        stderr: "",
+      });
+      expect(await tunnelConnectionCount(runner, "parachute")).toBe(2);
+    });
+
+    test("counts connector entries under the legacy `connections` shape", async () => {
+      const runner = infoRunner({
+        code: 0,
+        stdout: JSON.stringify({ connections: [{ id: "a" }] }),
+        stderr: "",
+      });
+      expect(await tunnelConnectionCount(runner, "parachute")).toBe(1);
+    });
+
+    test("returns 0 on empty conns, non-zero exit, unparseable JSON, or a runner throw", async () => {
+      expect(
+        await tunnelConnectionCount(
+          infoRunner({ code: 0, stdout: '{"conns":[]}', stderr: "" }),
+          "parachute",
+        ),
+      ).toBe(0);
+      expect(
+        await tunnelConnectionCount(
+          infoRunner({ code: 1, stdout: "", stderr: "not found" }),
+          "parachute",
+        ),
+      ).toBe(0);
+      expect(
+        await tunnelConnectionCount(
+          infoRunner({ code: 0, stdout: "not json", stderr: "" }),
+          "parachute",
+        ),
+      ).toBe(0);
+      const thrower: Runner = async () => {
+        throw new Error("spawn failed");
+      };
+      expect(await tunnelConnectionCount(thrower, "parachute")).toBe(0);
+    });
+  });
 });

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

@@ -12,6 +12,7 @@ import {
 } from "../cloudflare/state.ts";
 import {
   type CloudflaredSpawner,
+  defaultVerifyConnection,
   exposeCloudflareOff,
   exposeCloudflareUp,
 } from "../commands/expose-cloudflare.ts";
@@ -118,6 +119,16 @@ function fakeSpawner(pid: number): { spawner: CloudflaredSpawner; seen: string[]
   return { spawner, seen };
 }
 
+/**
+ * Write a fake `~/.cloudflared/<uuid>.json` credentials file so the reuse-path
+ * credentials check (#593) sees a healthy local tunnel and reuses it instead of
+ * triggering the delete+recreate self-heal. Reuse-path tests that want to
+ * exercise the plain reuse behavior call this after `makeEnv()`.
+ */
+function seedCreds(env: TestEnv, uuid: string): void {
+  writeFileSync(join(env.cloudflaredHome, `${uuid}.json`), "{}");
+}
+
 describe("exposeCloudflareUp", () => {
   test("happy path: creates tunnel, routes DNS, writes config + state, spawns cloudflared", async () => {
     const env = makeEnv();
@@ -350,6 +361,7 @@ describe("exposeCloudflareUp", () => {
     const env = makeEnv();
     try {
       const uuid = "bbbbbbbb-0000-0000-0000-000000000002";
+      seedCreds(env, uuid); // healthy local creds → plain reuse, no recreate (#593)
       const { runner, calls } = queueRunner([
         { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
         {
@@ -563,6 +575,7 @@ describe("exposeCloudflareUp", () => {
     const env = makeEnv();
     try {
       const uuid = "2c1a7c7e-1234-5678-9abc-def012345678";
+      seedCreds(env, uuid); // healthy local creds → plain reuse, no recreate (#593)
       const { runner } = queueRunner([
         { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
         { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
@@ -605,6 +618,8 @@ describe("exposeCloudflareUp", () => {
   test("stops a prior cloudflared process before spawning a new one", async () => {
     const env = makeEnv();
     try {
+      // Healthy local creds for the reused tunnel → plain reuse, no recreate (#593).
+      seedCreds(env, "cccccccc-0000-0000-0000-000000000003");
       const priorRecord: CloudflaredTunnelRecord = {
         pid: 99999,
         tunnelUuid: "old-tunnel-uuid",
@@ -668,6 +683,7 @@ describe("exposeCloudflareUp", () => {
     const env = makeEnv();
     try {
       const uuid = "cccccccc-0000-0000-0000-000000000003";
+      seedCreds(env, uuid); // healthy local creds → plain reuse, no recreate (#593)
       const priorRecord: CloudflaredTunnelRecord = {
         pid: 99999,
         tunnelUuid: uuid,
@@ -727,6 +743,7 @@ describe("exposeCloudflareUp", () => {
     const env = makeEnv();
     try {
       const uuid = "dddddddd-0000-0000-0000-000000000004";
+      seedCreds(env, uuid); // healthy local creds → plain reuse, no recreate (#593)
       const { runner } = queueRunner([
         { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
         { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
@@ -774,6 +791,7 @@ describe("exposeCloudflareUp", () => {
     const env = makeEnv();
     try {
       const uuid = "eeeeeeee-0000-0000-0000-000000000006";
+      seedCreds(env, uuid); // healthy local creds → plain reuse, no recreate (#593)
       const { runner } = queueRunner([
         { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
         { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
@@ -817,6 +835,7 @@ describe("exposeCloudflareUp", () => {
     const env = makeEnv();
     try {
       const uuid = "ffffffff-0000-0000-0000-000000000007";
+      seedCreds(env, uuid); // healthy local creds → plain reuse, no recreate (#593)
       const { runner } = queueRunner([
         { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
         { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
@@ -1158,6 +1177,7 @@ describe("exposeCloudflareUp", () => {
       const env = makeEnv();
       try {
         const uuid = "bbbb8888-1111-2222-3333-444455556666";
+        seedCreds(env, uuid); // healthy local creds → plain reuse, no recreate (#593)
         const legacy: CloudflaredTunnelRecord = {
           pid: 71001,
           tunnelUuid: uuid,
@@ -1379,6 +1399,239 @@ describe("exposeCloudflareUp", () => {
       }
     });
   });
+
+  describe("#593: reuse-path credentials self-heal", () => {
+    test("recreates the tunnel when the local credentials file is missing", async () => {
+      const env = makeEnv();
+      try {
+        const staleUuid = "11110000-0000-0000-0000-0000000005aa";
+        const freshUuid = "22220000-0000-0000-0000-0000000005bb";
+        // NO seedCreds → the reused tunnel's local creds file is absent, the
+        // exact field state (account-side tunnel survives, local creds lost).
+        const { runner, calls } = queueRunner([
+          { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" }, // --version
+          {
+            code: 0,
+            stdout: JSON.stringify([{ id: staleUuid, name: "parachute" }]),
+            stderr: "",
+          }, // tunnel list (exists account-side)
+          { code: 0, stdout: "Deleted tunnel parachute\n", stderr: "" }, // tunnel delete --force
+          {
+            code: 0,
+            stdout: `Created tunnel parachute with id ${freshUuid}\n`,
+            stderr: "",
+          }, // tunnel create (fresh creds)
+          { code: 0, stdout: "", stderr: "" }, // route dns
+        ]);
+        const { spawner } = fakeSpawner(43000);
+        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,
+          exposeStatePath: env.exposeStatePath,
+          configPath: env.configPath,
+          logPath: env.logPath,
+          cloudflaredHome: env.cloudflaredHome,
+          configDir: env.configDir,
+          skipHub: true,
+          tunnelName: "parachute",
+        });
+
+        expect(code).toBe(0);
+        const cmds = calls.map((c) => c.cmd.join(" "));
+        expect(cmds).toContain("cloudflared tunnel delete --force parachute");
+        expect(cmds).toContain("cloudflared tunnel create parachute");
+        // State + config reflect the FRESH uuid, not the stale one.
+        const state = readCloudflaredState(env.statePath);
+        expect(findTunnelRecord(state, "parachute")?.tunnelUuid).toBe(freshUuid);
+        const yaml = readFileSync(env.configPath, "utf8");
+        expect(yaml).toContain(`tunnel: ${freshUuid}`);
+        const joined = logs.join("\n");
+        expect(joined).toContain("local credentials");
+        expect(joined).toContain("Recreated tunnel");
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    test("fails with recovery commands when the stale-tunnel delete itself fails", async () => {
+      const env = makeEnv();
+      try {
+        const staleUuid = "11110000-0000-0000-0000-0000000005cc";
+        const { runner, calls } = queueRunner([
+          { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" }, // --version
+          {
+            code: 0,
+            stdout: JSON.stringify([{ id: staleUuid, name: "parachute" }]),
+            stderr: "",
+          }, // tunnel list
+          { code: 1, stdout: "", stderr: "tunnel has active connections" }, // delete fails
+        ]);
+        const { spawner } = fakeSpawner(43001);
+        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,
+          exposeStatePath: env.exposeStatePath,
+          configPath: env.configPath,
+          logPath: env.logPath,
+          cloudflaredHome: env.cloudflaredHome,
+          configDir: env.configDir,
+          skipHub: true,
+          tunnelName: "parachute",
+        });
+
+        expect(code).toBe(1);
+        // No connector spawned, no success print.
+        const joined = logs.join("\n");
+        expect(joined).toContain("Couldn't delete the stale tunnel");
+        expect(joined).toContain("cloudflared tunnel delete --force parachute");
+        expect(joined).not.toContain("Cloudflare tunnel up");
+        // create + route never ran.
+        const cmds = calls.map((c) => c.cmd.join(" "));
+        expect(cmds.some((c) => c.startsWith("cloudflared tunnel create"))).toBe(false);
+      } finally {
+        env.cleanup();
+      }
+    });
+  });
+
+  describe("#593: post-start connection verification", () => {
+    test("fails loudly when the connector never registers a connection (timeout)", async () => {
+      const env = makeEnv();
+      try {
+        const uuid = "33330000-0000-0000-0000-0000000005dd";
+        seedCreds(env, uuid);
+        const { runner } = queueRunner([
+          { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+          { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+          { code: 0, stdout: "", stderr: "" }, // route dns
+        ]);
+        const { spawner } = fakeSpawner(43002);
+        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,
+          exposeStatePath: env.exposeStatePath,
+          configPath: env.configPath,
+          logPath: env.logPath,
+          cloudflaredHome: env.cloudflaredHome,
+          configDir: env.configDir,
+          skipHub: true,
+          tunnelName: "parachute",
+          // Drive the timeout branch directly (no real cloudflared/poll).
+          verifyConnection: async () => false,
+        });
+
+        expect(code).toBe(1);
+        const joined = logs.join("\n");
+        expect(joined).toContain("never registered a tunnel connection");
+        expect(joined).toContain("error 1033");
+        expect(joined).toContain(env.logPath); // names the connector log
+        expect(joined).not.toContain("✓ Cloudflare tunnel up");
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    test("prints success when the connector verifies connected", async () => {
+      const env = makeEnv();
+      try {
+        const uuid = "44440000-0000-0000-0000-0000000005ee";
+        seedCreds(env, uuid);
+        const { runner } = queueRunner([
+          { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+          { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+          { code: 0, stdout: "", stderr: "" }, // route dns
+        ]);
+        const { spawner } = fakeSpawner(43003);
+        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,
+          exposeStatePath: env.exposeStatePath,
+          configPath: env.configPath,
+          logPath: env.logPath,
+          cloudflaredHome: env.cloudflaredHome,
+          configDir: env.configDir,
+          skipHub: true,
+          tunnelName: "parachute",
+          verifyConnection: async () => true,
+        });
+
+        expect(code).toBe(0);
+        const joined = logs.join("\n");
+        expect(joined).toContain("Connector connected.");
+        expect(joined).toContain("✓ Cloudflare tunnel up");
+      } finally {
+        env.cleanup();
+      }
+    });
+
+    test("defaultVerifyConnection polls tunnelConnectionCount and returns true once connected", async () => {
+      // Drives the real default poll loop against a queued runner — first
+      // `tunnel info` reports no conns, the second reports one. No real sleep.
+      let infoCalls = 0;
+      const runner: Runner = async (cmd) => {
+        if (cmd.join(" ").startsWith("cloudflared tunnel info")) {
+          infoCalls += 1;
+          return infoCalls === 1
+            ? { code: 0, stdout: JSON.stringify({ conns: [] }), stderr: "" }
+            : { code: 0, stdout: JSON.stringify({ conns: [{ id: "c1" }] }), stderr: "" };
+        }
+        return { code: 0, stdout: "", stderr: "" };
+      };
+      const connected = await defaultVerifyConnection({
+        runner,
+        tunnelName: "parachute",
+        timeoutMs: 5_000,
+        pollMs: 1,
+        sleep: async () => {},
+      });
+      expect(connected).toBe(true);
+      expect(infoCalls).toBe(2);
+    });
+
+    test("defaultVerifyConnection returns false when the budget elapses with no connection", async () => {
+      const runner: Runner = async () => ({
+        code: 0,
+        stdout: JSON.stringify({ conns: [] }),
+        stderr: "",
+      });
+      const connected = await defaultVerifyConnection({
+        runner,
+        tunnelName: "parachute",
+        timeoutMs: 0, // immediate deadline → one probe then false
+        pollMs: 1,
+        sleep: async () => {},
+      });
+      expect(connected).toBe(false);
+    });
+  });
 });
 
 describe("exposeCloudflareOff", () => {

package/src/__tests__/expose-supervisor-version.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import { ensureHubUnitForExpose, resolveExposeSupervisor } from "../commands/expose-supervisor.ts";
+import type { EnsureHubVersionMatchesResult } from "../hub-unit.ts";
+
+/**
+ * #590: `ensureHubUnitForExpose` must run the version-check-and-restart at the
+ * expose adoption point, so an expose never wires a tunnel to a stale zombie
+ * that merely answers /health on the canonical port. These tests drive the
+ * version-check seam directly (no real launchctl / live hub).
+ */
+describe("ensureHubUnitForExpose — version-check at the expose adoption point (#590)", () => {
+  function sup(
+    ensureHubUnitOutcome: "already-up" | "started" | "no-unit",
+    versionResult: EnsureHubVersionMatchesResult,
+    versionSpy?: (port: number) => void,
+  ) {
+    return resolveExposeSupervisor({
+      ensureHubUnit: async ({ port }) => ({
+        outcome: ensureHubUnitOutcome,
+        port: port ?? 1939,
+        messages: ensureHubUnitOutcome === "no-unit" ? ["no hub unit installed"] : [],
+      }),
+      ensureHubVersion: async ({ port }) => {
+        versionSpy?.(port);
+        return versionResult;
+      },
+    });
+  }
+
+  test("hub up + version matches → ok, version check ran with the probed port", async () => {
+    const logs: string[] = [];
+    let checkedPort: number | undefined;
+    const s = sup(
+      "already-up",
+      {
+        outcome: "match",
+        runningVersion: "0.6.4-rc.9",
+        installedVersion: "0.6.4-rc.9",
+        messages: [],
+      },
+      (p) => {
+        checkedPort = p;
+      },
+    );
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(true);
+    expect(checkedPort).toBe(1939);
+  });
+
+  test("hub up but a stale zombie → restarted → ok (tunnel binds to NEW code)", async () => {
+    const logs: string[] = [];
+    const s = sup("already-up", {
+      outcome: "restarted",
+      runningVersion: "0.6.4-rc.9",
+      installedVersion: "0.6.4-rc.9",
+      messages: ["✓ hub unit restarted; now running 0.6.4-rc.9."],
+    });
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(true);
+    expect(logs.join("\n")).toContain("now running 0.6.4-rc.9");
+  });
+
+  test("hub up but mismatch + NOT unit-managed → expose FAILS (don't tunnel to a zombie)", async () => {
+    const logs: string[] = [];
+    const s = sup("already-up", {
+      outcome: "not-unit-managed",
+      runningVersion: "0.5.14-rc.4",
+      installedVersion: "0.6.4-rc.9",
+      messages: ["⚠ the running hub is 0.5.14-rc.4 but 0.6.4-rc.9 is installed."],
+    });
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(false);
+    expect(logs.join("\n")).toContain("0.5.14-rc.4");
+  });
+
+  test("still-mismatched after restart → expose CONTINUES (warn, don't block)", async () => {
+    const logs: string[] = [];
+    const s = sup("already-up", {
+      outcome: "still-mismatched",
+      runningVersion: "0.6.4-rc.8",
+      installedVersion: "0.6.4-rc.9",
+      messages: ["⚠ restarted the hub unit, but it is still not reporting 0.6.4-rc.9."],
+    });
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(true);
+    expect(logs.join("\n")).toContain("still not reporting");
+  });
+
+  test("hub NOT up (no unit) → fails BEFORE the version check (no false adoption)", async () => {
+    const logs: string[] = [];
+    let versionRan = false;
+    const s = sup(
+      "no-unit",
+      { outcome: "match", installedVersion: "0.6.4-rc.9", messages: [] },
+      () => {
+        versionRan = true;
+      },
+    );
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(false);
+    // The version check only runs once the hub is confirmed up.
+    expect(versionRan).toBe(false);
+  });
+});

package/src/__tests__/hub-db-liveness.test.ts

@@ -0,0 +1,139 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+import { classifyDbError, createDbHolder, probeDbLiveness } from "../hub-db-liveness.ts";
+
+/** Build a `SQLiteError`-shaped object with the given code + message. */
+function sqliteErr(code: string, message: string): Error & { code: string } {
+  const e = new Error(message) as Error & { code: string };
+  e.name = "SQLiteError";
+  e.code = code;
+  return e;
+}
+
+describe("classifyDbError (#594)", () => {
+  test("the persistent-corruption class is fatal", () => {
+    expect(classifyDbError(sqliteErr("SQLITE_IOERR", "disk I/O error"))).toBe("fatal");
+    expect(classifyDbError(new Error("disk I/O error"))).toBe("fatal");
+    expect(classifyDbError(sqliteErr("SQLITE_CORRUPT", "database disk image is malformed"))).toBe(
+      "fatal",
+    );
+    expect(classifyDbError(sqliteErr("SQLITE_NOTADB", "file is not a database"))).toBe("fatal");
+  });
+
+  test("transient locks are NOT fatal", () => {
+    expect(classifyDbError(sqliteErr("SQLITE_BUSY", "database is locked"))).toBe("transient");
+    expect(classifyDbError(sqliteErr("SQLITE_LOCKED", "database table is locked"))).toBe(
+      "transient",
+    );
+  });
+
+  test("unrelated errors classify as other", () => {
+    expect(classifyDbError(new Error("UNIQUE constraint failed: users.id"))).toBe("other");
+    expect(classifyDbError(new TypeError("undefined is not a function"))).toBe("other");
+    expect(classifyDbError(null)).toBe("other");
+  });
+});
+
+describe("probeDbLiveness (#594)", () => {
+  test("returns ok on a live in-memory db", () => {
+    const db = new Database(":memory:");
+    expect(probeDbLiveness(db)).toBe("ok");
+    db.close();
+  });
+
+  test("returns error: <class> on a closed handle, never throws", () => {
+    const db = new Database(":memory:");
+    db.close();
+    const result = probeDbLiveness(db);
+    expect(result.startsWith("error:")).toBe(true);
+  });
+});
+
+describe("createDbHolder (#594)", () => {
+  test("non-fatal errors are ignored (no reopen, no exit)", () => {
+    const initial = new Database(":memory:");
+    let reopens = 0;
+    let exits = 0;
+    const holder = createDbHolder(initial, {
+      reopen: () => {
+        reopens += 1;
+        return new Database(":memory:");
+      },
+      exit: () => {
+        exits += 1;
+      },
+      log: () => {},
+    });
+    expect(holder.healOrExit(sqliteErr("SQLITE_BUSY", "database is locked"))).toBe("ignored");
+    expect(holder.healOrExit(new Error("UNIQUE constraint failed"))).toBe("ignored");
+    expect(reopens).toBe(0);
+    expect(exits).toBe(0);
+    expect(holder.get()).toBe(initial);
+  });
+
+  test("a fatal error reopens the handle ONCE and swaps it in", () => {
+    const initial = new Database(":memory:");
+    const fresh = new Database(":memory:");
+    let reopens = 0;
+    let exits = 0;
+    let closedOld = false;
+    const holder = createDbHolder(initial, {
+      reopen: () => {
+        reopens += 1;
+        return fresh;
+      },
+      exit: () => {
+        exits += 1;
+      },
+      closeOld: () => {
+        closedOld = true;
+      },
+      log: () => {},
+    });
+    expect(holder.healOrExit(sqliteErr("SQLITE_IOERR", "disk I/O error"))).toBe("healed");
+    expect(reopens).toBe(1);
+    expect(exits).toBe(0);
+    expect(closedOld).toBe(true);
+    expect(holder.get()).toBe(fresh);
+    fresh.close();
+  });
+
+  test("a fatal error exits(1) when reopen throws", () => {
+    const initial = new Database(":memory:");
+    let exitCode: number | undefined;
+    const holder = createDbHolder(initial, {
+      reopen: () => {
+        throw sqliteErr("SQLITE_IOERR", "disk I/O error");
+      },
+      // Non-exiting spy so the test process survives.
+      exit: (code) => {
+        exitCode = code;
+      },
+      log: () => {},
+    });
+    expect(holder.healOrExit(sqliteErr("SQLITE_IOERR", "disk I/O error"))).toBe("exited");
+    expect(exitCode).toBe(1);
+    // Handle is unchanged (we couldn't reopen).
+    expect(holder.get()).toBe(initial);
+    initial.close();
+  });
+
+  test("a fatal error exits(1) when the REOPENED handle is also dead", () => {
+    const initial = new Database(":memory:");
+    // Reopen returns an already-closed handle → the holder's SELECT 1 verify
+    // throws → exit. This is the "state dir still gone after reopen" case.
+    const deadFresh = new Database(":memory:");
+    deadFresh.close();
+    let exitCode: number | undefined;
+    const holder = createDbHolder(initial, {
+      reopen: () => deadFresh,
+      exit: (code) => {
+        exitCode = code;
+      },
+      log: () => {},
+    });
+    expect(holder.healOrExit(sqliteErr("SQLITE_IOERR", "disk I/O error"))).toBe("exited");
+    expect(exitCode).toBe(1);
+    initial.close();
+  });
+});