@openparachute/hub 0.6.5-rc.4 → 0.6.5-rc.5

package/package.json

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

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

@@ -1,6 +1,14 @@
 import { Database } from "bun:sqlite";
 import { describe, expect, test } from "bun:test";
-import { classifyDbError, createDbHolder, probeDbLiveness } from "../hub-db-liveness.ts";
+import {
+  type DbInode,
+  type StatInodeFn,
+  classifyDbError,
+  classifyPathLiveness,
+  createDbHolder,
+  probeDbLiveness,
+  startDbPathLivenessTimer,
+} from "../hub-db-liveness.ts";
 
 /** Build a `SQLiteError`-shaped object with the given code + message. */
 function sqliteErr(code: string, message: string): Error & { code: string } {
@@ -137,3 +145,209 @@ describe("createDbHolder (#594)", () => {
     initial.close();
   });
 });
+
+const INODE_A: DbInode = { dev: 1, ino: 100 };
+const INODE_B: DbInode = { dev: 1, ino: 200 };
+
+describe("classifyPathLiveness (#610)", () => {
+  test("same inode → ok", () => {
+    expect(classifyPathLiveness({ expected: INODE_A, current: INODE_A })).toBe("ok");
+    expect(classifyPathLiveness({ expected: INODE_A, current: { ...INODE_A } })).toBe("ok");
+  });
+  test("ENOENT on the path (current undefined) → gone", () => {
+    expect(classifyPathLiveness({ expected: INODE_A, current: undefined })).toBe("gone");
+  });
+  test("different inode → replaced", () => {
+    expect(classifyPathLiveness({ expected: INODE_A, current: INODE_B })).toBe("replaced");
+    // a different device counts too
+    expect(classifyPathLiveness({ expected: INODE_A, current: { dev: 2, ino: 100 } })).toBe(
+      "replaced",
+    );
+  });
+  test("no baseline snapshot (expected undefined) → unknown, never self-heals", () => {
+    expect(classifyPathLiveness({ expected: undefined, current: INODE_A })).toBe("unknown");
+    expect(classifyPathLiveness({ expected: undefined, current: undefined })).toBe("unknown");
+  });
+});
+
+describe("DbHolder.probePath (#610 proactive detection)", () => {
+  /** A holder whose path stat is driven by the injected `statInode`. */
+  function makeHolder(opts: {
+    initialInode: DbInode | undefined;
+    statInode: StatInodeFn;
+    onReopen?: () => Database;
+  }) {
+    const initial = new Database(":memory:");
+    let reopens = 0;
+    let exits = 0;
+    let exitCode: number | undefined;
+    const holder = createDbHolder(initial, {
+      dbPath: "/fake/hub.db",
+      initialInode: opts.initialInode,
+      statInode: opts.statInode,
+      reopen: () => {
+        reopens += 1;
+        return opts.onReopen ? opts.onReopen() : new Database(":memory:");
+      },
+      exit: (code) => {
+        exits += 1;
+        exitCode = code;
+      },
+      log: () => {},
+    });
+    return {
+      holder,
+      stats: () => ({ reopens, exits, exitCode }),
+      cleanup: () => {
+        try {
+          initial.close();
+        } catch {}
+      },
+    };
+  }
+
+  test("healthy path (same inode) → no reopen, no exit", () => {
+    const h = makeHolder({ initialInode: INODE_A, statInode: () => INODE_A });
+    expect(h.holder.probePath()).toBe("ok");
+    expect(h.stats().reopens).toBe(0);
+    expect(h.stats().exits).toBe(0);
+    h.cleanup();
+  });
+
+  test("path GONE (ENOENT) → reopen attempted; reopen verify fails → exit(1)", () => {
+    // Reopen returns a closed handle (the dir is still gone) → SELECT 1 throws
+    // → exit. This is the genuine `rm -rf ~/.parachute` field shape.
+    const dead = new Database(":memory:");
+    dead.close();
+    const h = makeHolder({
+      initialInode: INODE_A,
+      statInode: () => undefined, // ENOENT
+      onReopen: () => dead,
+    });
+    expect(h.holder.probePath()).toBe("gone");
+    expect(h.stats().reopens).toBe(1);
+    expect(h.stats().exits).toBe(1);
+    expect(h.stats().exitCode).toBe(1);
+    h.cleanup();
+  });
+
+  test("path REPLACED (different inode) → reopen + swap (heals, no exit)", () => {
+    const h = makeHolder({
+      initialInode: INODE_A,
+      statInode: () => INODE_B, // path now resolves to a different inode
+      onReopen: () => new Database(":memory:"),
+    });
+    expect(h.holder.probePath()).toBe("replaced");
+    expect(h.stats().reopens).toBe(1);
+    expect(h.stats().exits).toBe(0);
+    h.cleanup();
+  });
+
+  test("NEVER fires on a transient stat throw (EACCES) — returns ok, no reopen/exit", () => {
+    const h = makeHolder({
+      initialInode: INODE_A,
+      statInode: () => {
+        const e = new Error("permission denied") as Error & { code: string };
+        e.code = "EACCES";
+        throw e;
+      },
+    });
+    expect(h.holder.probePath()).toBe("ok");
+    expect(h.stats().reopens).toBe(0);
+    expect(h.stats().exits).toBe(0);
+    h.cleanup();
+  });
+
+  test("no baseline inode → unknown, never self-heals (safe degradation)", () => {
+    const h = makeHolder({ initialInode: undefined, statInode: () => undefined });
+    expect(h.holder.probePath()).toBe("unknown");
+    expect(h.stats().reopens).toBe(0);
+    expect(h.stats().exits).toBe(0);
+    h.cleanup();
+  });
+
+  test("no dbPath configured → probePath is a no-op (unknown)", () => {
+    const initial = new Database(":memory:");
+    const holder = createDbHolder(initial, {
+      reopen: () => new Database(":memory:"),
+      exit: () => {},
+      log: () => {},
+    });
+    expect(holder.probePath()).toBe("unknown");
+    initial.close();
+  });
+
+  test("after a heal (replaced), the inode baseline is re-snapshotted to the new file", () => {
+    // First probe sees INODE_B (replaced) → reopen; statInode then returns
+    // INODE_B again so the NEXT probe sees the SAME inode → ok (not a loop).
+    let exits = 0;
+    const initial = new Database(":memory:");
+    const holder = createDbHolder(initial, {
+      dbPath: "/fake/hub.db",
+      initialInode: INODE_A,
+      statInode: () => INODE_B,
+      reopen: () => new Database(":memory:"),
+      exit: () => {
+        exits += 1;
+      },
+      log: () => {},
+    });
+    expect(holder.probePath()).toBe("replaced"); // A → B, heal
+    expect(holder.probePath()).toBe("ok"); // B → B, no further action
+    expect(exits).toBe(0);
+    initial.close();
+  });
+});
+
+describe("startDbPathLivenessTimer (#610 bounded watchdog)", () => {
+  test("each tick calls probePath exactly once; stop() clears the timer", () => {
+    let probes = 0;
+    const fakeHolder = {
+      get: () => new Database(":memory:"),
+      healOrExit: () => "ignored" as const,
+      probePath: () => {
+        probes += 1;
+        return "ok" as const;
+      },
+    };
+    let registered: (() => void) | undefined;
+    let cleared = false;
+    const timer = startDbPathLivenessTimer<number>(fakeHolder, {
+      setIntervalFn: (cb) => {
+        registered = cb;
+        return 42;
+      },
+      clearIntervalFn: (h) => {
+        expect(h).toBe(42);
+        cleared = true;
+      },
+    });
+    expect(registered).toBeDefined();
+    registered?.();
+    registered?.();
+    expect(probes).toBe(2);
+    timer.stop();
+    expect(cleared).toBe(true);
+  });
+
+  test("a probe that throws is swallowed (the timer callback never crashes the process)", () => {
+    const fakeHolder = {
+      get: () => new Database(":memory:"),
+      healOrExit: () => "ignored" as const,
+      probePath: (): "ok" => {
+        throw new Error("unexpected");
+      },
+    };
+    let registered: (() => void) | undefined;
+    startDbPathLivenessTimer<number>(fakeHolder, {
+      setIntervalFn: (cb) => {
+        registered = cb;
+        return 1;
+      },
+      clearIntervalFn: () => {},
+      log: () => {},
+    });
+    // Must NOT throw out of the callback.
+    expect(() => registered?.()).not.toThrow();
+  });
+});

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

@@ -110,6 +110,69 @@ describe("hubFetch routing", () => {
     }
   });
 
+  test("/health reports db:ok when getDb is live and the proactive path probe is ok (#610)", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          probeDbPath: () => "ok",
+        })(req("/health"));
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { status: string; db: string };
+        expect(body.status).toBe("ok");
+        expect(body.db).toBe("ok");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("/health surfaces db:error:path-gone when the proactive probe sees a wiped path (#610)", async () => {
+    // The ghost-fd lie: SELECT 1 still succeeds against the unlinked inode, so
+    // probeDbLiveness alone would report ok. probeDbPath stat()s the PATH and
+    // returns "gone" → /health must report the fault instead of lying.
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          probeDbPath: () => "gone",
+        })(req("/health"));
+        expect(res.status).toBe(200); // /health stays 200 (process liveness)
+        const body = (await res.json()) as { db: string };
+        expect(body.db).toBe("error: path-gone");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("/health surfaces db:error:path-replaced when the proactive probe sees an inode swap (#610)", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          probeDbPath: () => "replaced",
+        })(req("/health"));
+        const body = (await res.json()) as { db: string };
+        expect(body.db).toBe("error: path-replaced");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("/ renders the signed-out indicator dynamically when DB is configured but no session cookie (rc.13)", async () => {
     // The dynamic path takes over from the static disk file the moment a
     // DB is configured. With no session cookie, we still render — just

package/src/__tests__/install.test.ts

@@ -377,6 +377,127 @@ describe("install", () => {
     }
   });
 
+  test("ADOPT-KILLS an attributable same-module orphan on the canonical port + reclaims it (#609)", async () => {
+    // Wipe-recovery: `rm -rf ~/.parachute` + re-`init` leaves the supervised
+    // vault child running on :1940. The fresh install must reclaim the canonical
+    // port (adopt-kill the attributable orphan) rather than port-walk to 1944.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const kills: Array<{ pid: number; signal: string | number }> = [];
+      // installDir = /opt/.parachute/vault → the orphan's cmdline carries it, so
+      // attribution (per-module marker = installDir) succeeds.
+      const installDirPkg = "/opt/.parachute/vault/package.json";
+      // Port 1940 is held UNTIL the SIGTERM lands; after the kill the re-probe
+      // (collectOccupiedPorts) sees it free, so the assignment lands on 1940.
+      let killed = false;
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        findGlobalInstall: () => installDirPkg,
+        portProbe: async (p) => p === 1940 && !killed,
+        pidOnPort: (p) => (p === 1940 && !killed ? 7777 : undefined),
+        ownerOfPid: (pid) =>
+          pid === 7777 ? "parachute-vault --port 1940 (/opt/.parachute/vault)" : undefined,
+        killPid: (pid, signal) => {
+          kills.push({ pid, signal });
+          killed = true; // the orphan releases the port on SIGTERM
+        },
+        sleep: async () => {},
+        reclaimDelayMs: 0,
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      // We adopt-killed the attributable orphan…
+      expect(joined).toMatch(/attributable prior vault instance \(pid 7777/);
+      expect(joined).toMatch(/reclaiming it \(adopt-kill\)/);
+      expect(kills.map((k) => k.signal)).toContain("SIGTERM");
+      // …and the fresh install landed on the CANONICAL port, not a fallback.
+      const entry = findService("parachute-vault", path);
+      expect(entry?.port).toBe(1940);
+      expect(joined).not.toMatch(/is in use; assigned/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("escalates to SIGKILL when the orphan ignores SIGTERM (#609)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const signals: Array<string | number> = [];
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        findGlobalInstall: () => "/opt/.parachute/vault/package.json",
+        // Orphan never releases 1940 → install ultimately walks (degrades
+        // gracefully), but it MUST have escalated to SIGKILL first.
+        portProbe: async (p) => p === 1940,
+        pidOnPort: (p) => (p === 1940 ? 8888 : undefined),
+        ownerOfPid: (pid) => (pid === 8888 ? "parachute-vault (/opt/.parachute/vault)" : undefined),
+        killPid: (_pid, signal) => {
+          signals.push(signal);
+        },
+        sleep: async () => {},
+        reclaimDelayMs: 0,
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      expect(signals).toContain("SIGTERM");
+      expect(signals).toContain("SIGKILL");
+      expect(logs.join("\n")).toMatch(/escalated to SIGKILL/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("does NOT kill a FOREIGN holder on the canonical port — walks + warns instead (#609 safety)", async () => {
+    // The crux: a non-attributable holder (an operator's unrelated process, or a
+    // sibling module) on :1940 must NEVER be killed. We fall through to the #590
+    // warn-and-walk path unchanged.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      let killCalled = false;
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        findGlobalInstall: () => "/opt/.parachute/vault/package.json",
+        portProbe: async (p) => p === 1940,
+        pidOnPort: (p) => (p === 1940 ? 5555 : undefined),
+        // Foreign cmdline — does NOT contain the vault installDir marker.
+        ownerOfPid: (pid) => (pid === 5555 ? "/usr/bin/python3 /opt/my-own-server.py" : undefined),
+        killPid: () => {
+          killCalled = true;
+        },
+        sleep: async () => {},
+        reclaimDelayMs: 0,
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      expect(killCalled).toBe(false); // NEVER kill a foreign process
+      const joined = logs.join("\n");
+      // The #590 warn-and-walk path is unchanged for the foreign holder.
+      expect(joined).toMatch(/canonical port 1940 is in use; assigned/);
+      expect(joined).toContain("pid 5555 (/usr/bin/python3 /opt/my-own-server.py)");
+      expect(joined).toMatch(/stale pre-supervisor daemon/);
+      const entry = findService("parachute-vault", path);
+      expect(entry?.port).not.toBe(1940); // walked, not reclaimed
+    } finally {
+      cleanup();
+    }
+  });
+
   test("squatter pid present but command line unreadable → names the pid alone (#590)", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {

package/src/__tests__/setup-wizard.test.ts

@@ -179,6 +179,46 @@ describe("deriveWizardState", () => {
     }
   });
 
+  test("vault step when admin exists and only the SEED placeholder vault row is present (hub#607)", async () => {
+    // `parachute init` seeds a `parachute-vault` placeholder into
+    // services.json at SEED_VERSION ("0.0.0-linked") under hub#168 Cut 1
+    // (`noCreate`): the MODULE is installed, but no instance exists yet.
+    // Pre-#607, `hasVault` keyed off a bare `findService(...) !== undefined`
+    // check, which the placeholder satisfied — so the wizard silently
+    // skipped its vault step on EVERY init'd box and the operator finished
+    // setup with no vault. The placeholder must NOT count as a real vault.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.0.0-linked",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      // The placeholder is module-installed-but-no-instance, so the wizard
+      // still owns vault creation: it presents the create/import/skip step.
+      expect(s.step).toBe("vault");
+      expect(s.hasAdmin).toBe(true);
+      expect(s.hasVault).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
   test("expose step when admin + vault exist but expose mode not set yet (hub#268 Item 2)", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
@@ -1506,6 +1546,105 @@ describe("handleSetupVaultPost", () => {
     }
   });
 
+  test("create on a SEED-placeholder box: does NOT short-circuit + drives the supervisor to start vault (hub#607 + hub#608)", async () => {
+    // hub#607 + hub#608 coupled fresh-operator flow. On an init'd box,
+    // services.json already carries a `parachute-vault` placeholder at
+    // SEED_VERSION ("0.0.0-linked") — the MODULE is installed, no instance
+    // exists. With the hub#607 `hasVault` discrimination, the wizard's vault
+    // step still appears (the placeholder isn't a real vault), so a
+    // `mode=create` POST must NOT be treated as "already provisioned" and
+    // short-circuit to expose. It runs `runInstall`, which seeds/stamps the
+    // row and — the hub#608 fix — drives `supervisor.start(...)` so the
+    // freshly-created vault is ACTIVE immediately, not inactive-until-
+    // restart. We assert both: the install op fired (no short-circuit) AND
+    // the supervisor now reports a live vault child.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const { createSession, SESSION_COOKIE_NAME: SC } = await import("../sessions.ts");
+      const session = createSession(db, { userId: user.id });
+      // Simulate `parachute init`: the vault MODULE is seeded as a
+      // placeholder, no supervisor entry yet (init ran with noStart).
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.0.0-linked",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      const supervisor = makeSupervisor();
+      // Sanity: no vault child before the wizard create.
+      expect(supervisor.get("vault")).toBeUndefined();
+      const runCalls: string[][] = [];
+      const stubbedRun = async (cmd: readonly string[]) => {
+        runCalls.push([...cmd]);
+        return 0;
+      };
+      const post = await handleSetupVaultPost(
+        req("/admin/setup/vault", {
+          method: "POST",
+          body: new URLSearchParams({
+            [CSRF_FIELD_NAME]: csrf,
+            mode: "create",
+            vault_name: "myvault",
+            scribe_provider: "none",
+          }).toString(),
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE_NAME}=${csrf}; ${SC}=${session.id}`,
+          },
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
+          issuer: "https://hub.example",
+          supervisor,
+          registry: getDefaultOperationsRegistry(),
+          run: stubbedRun,
+          isLinked: () => false,
+        },
+      );
+      // Not short-circuited: the placeholder is not a real vault, so the
+      // POST enqueues an install op rather than redirecting to expose.
+      expect(post.status).toBe(303);
+      const location = post.headers.get("location") ?? "";
+      expect(location).toMatch(/^\/admin\/setup\?op=/);
+      // Let the background runInstall promise reach the runner + supervisor.
+      await new Promise((r) => setTimeout(r, 50));
+      // #607 proof: the install actually ran (not the "already provisioned"
+      // short-circuit, which fires no `bun add`).
+      expect(runCalls.some((c) => c.join(" ").includes("bun add -g @openparachute/vault"))).toBe(
+        true,
+      );
+      // #608 proof: the supervisor was driven to start the vault child, so
+      // the vault is live immediately after the wizard create — no manual
+      // `parachute start vault` / hub restart needed.
+      const vaultState = supervisor.get("vault");
+      expect(vaultState).toBeDefined();
+      expect(["starting", "running", "restarting"]).toContain(vaultState?.status ?? "");
+    } finally {
+      db.close();
+    }
+  });
+
   // --- scribe cleanup sub-form (2026-05-27) -----------------------------
   //
   // The vault step's scribe sub-form was extended with a second radio

package/src/commands/install.ts

@@ -7,8 +7,12 @@ import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { type ExposeState, readExposeState } from "../expose-state.ts";
 import {
   HUB_DEFAULT_PORT,
+  type KillFn,
   type PidOnPortFn,
+  type SleepFn,
+  defaultKill,
   defaultPidOnPort,
+  defaultSleep,
   readHubPort,
 } from "../hub-control.ts";
 import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
@@ -18,6 +22,7 @@ import {
   readModuleManifest,
   validateModuleManifest,
 } from "../module-manifest.ts";
+import { orphanAttributable } from "../orphan-attribution.ts";
 import { assignServicePort } from "../port-assign.ts";
 import { finalizeModuleInstall, stampInstallDirOnRow } from "../post-install.ts";
 import {
@@ -323,6 +328,30 @@ export interface InstallOpts {
    * `defaultOwnerOfPid` (`ps -o command= -p <pid>`); tests inject a stub.
    */
   ownerOfPid?: OwnerProbeFn;
+  /**
+   * Test seam for the install-time canonical-port ADOPT-KILL (#609). When the
+   * canonical port is held by an attributable prior instance of THE SAME module
+   * (a surviving orphan child after `rm -rf ~/.parachute` + re-`init`), we
+   * SIGTERM→SIGKILL it to reclaim the canonical port instead of walking to a
+   * non-canonical fallback. Reuses the #601 `orphanAttributable` machinery in
+   * per-module mode (marker = this install's `installDir`); a foreign /
+   * unattributable holder is NEVER killed — it falls through to the #590
+   * warn-and-walk path. Production wires `defaultKill` (`process.kill`); tests
+   * inject a spy so no real process is signalled.
+   */
+  killPid?: KillFn;
+  /**
+   * Test seam for the grace delay between SIGTERM and the SIGKILL escalation in
+   * the #609 adopt-kill. Production wires `defaultSleep`; tests inject a no-op
+   * so the path runs instantly.
+   */
+  sleep?: SleepFn;
+  /**
+   * Test seam: ms to wait after SIGTERM before re-probing + escalating to
+   * SIGKILL in the #609 adopt-kill. Default 1500ms (a listener-release grace);
+   * tests pass 0.
+   */
+  reclaimDelayMs?: number;
   /**
    * Test seam for reading `<packageDir>/.parachute/module.json`. Production
    * uses the real file reader; tests inject a map from package-dir → manifest
@@ -452,6 +481,50 @@ async function collectOccupiedPorts(
   return ports;
 }
 
+/**
+ * Adopt-kill an ATTRIBUTABLE orphan holding the canonical port (#609). The
+ * caller has ALREADY confirmed attribution (per-module marker) — this is purely
+ * the signal sequence, mirroring the supervisor's `adoptKillOrphanOnPort`:
+ * SIGTERM, a listener-release grace, then SIGKILL only if the SAME pid still
+ * holds the SAME port. Best-effort: a kill that doesn't free the port degrades
+ * to the normal warn-and-walk path (the subsequent `collectOccupiedPorts` still
+ * sees the port held and `assignServicePort` walks).
+ *
+ * The re-probe before SIGKILL is deliberately NOT re-attributed: we already
+ * attributed `holder` to this module, and only escalate if that exact pid still
+ * holds the port (the same accepted, vanishingly-small TOCTOU window the
+ * supervisor + migrate sweep carry).
+ */
+async function adoptKillOnPort(args: {
+  port: number;
+  holder: number;
+  kill: KillFn;
+  sleep: SleepFn;
+  pidOnPort: PidOnPortFn;
+  delayMs: number;
+  log: (line: string) => void;
+}): Promise<void> {
+  const { port, holder, kill, sleep, pidOnPort, delayMs, log } = args;
+  try {
+    kill(holder, "SIGTERM");
+  } catch {
+    // ESRCH (already gone) / EPERM (can't signal) — nothing more to do; the
+    // re-probe + walk path handles a still-held port.
+    return;
+  }
+  await sleep(delayMs);
+  if (pidOnPort(port) === holder) {
+    try {
+      kill(holder, "SIGKILL");
+      log(`  pid ${holder} did not release ${port} on SIGTERM; escalated to SIGKILL.`);
+    } catch {
+      // Already gone / can't signal — best-effort; fall through to the walk.
+    }
+  } else {
+    log(`  reclaimed canonical port ${port} (pid ${holder} released it).`);
+  }
+}
+
 function defaultFindGlobalInstall(pkg: string): string | null {
   for (const prefix of bunGlobalPrefixes()) {
     const pkgJsonPath = join(prefix, ...pkg.split("/"), "package.json");
@@ -988,23 +1061,98 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   // future installs no longer touch them.
   const preInitEntry = findService(entryName, manifestPath);
   const probe = opts.portProbe ?? defaultPortProbe;
-  const occupied = await collectOccupiedPorts(manifestPath, entryName, preInitEntry?.port, probe);
+  const pidOnPort = opts.pidOnPort ?? defaultPidOnPort;
+  const ownerOfPid = opts.ownerOfPid ?? defaultOwnerOfPid;
   const canonicalPort = spec.seedEntry?.().port ?? preInitEntry?.port;
+
+  // #609 wipe-recovery adopt-kill: BEFORE assigning, if the canonical port is
+  // held by an attributable prior instance of THE SAME module (the classic
+  // `rm -rf ~/.parachute` + re-`init` case — the supervised vault child keeps
+  // running on :1940 and the fresh install would otherwise port-walk to 1944),
+  // reclaim the port by adopt-killing the orphan rather than walking. Reuses the
+  // #601 `orphanAttributable` machinery in PER-MODULE mode (marker = THIS
+  // install's installDir, the same module-specific marker the supervisor's
+  // crash-restart path uses) so a FOREIGN / sibling-module / operator process is
+  // NEVER killed — it falls through to the #590 warn-and-walk path below.
+  // Detection + module-specific attribution only; the kill is gated hard.
+  // Gate the probe on the canonical port actually being OCCUPIED — when it's
+  // free there's nothing to reclaim, and probing pid would be wasted work (and
+  // a false "I looked at the port" signal). `probe` is the same TCP listen probe
+  // `collectOccupiedPorts` uses below; a services.json row on the canonical port
+  // also counts as occupied (a prior install's lingering entry).
+  const canonicalOccupied =
+    canonicalPort !== undefined &&
+    (preInitEntry?.port === canonicalPort ||
+      (await (async () => {
+        try {
+          return await probe(canonicalPort);
+        } catch {
+          return false;
+        }
+      })()));
+  if (canonicalPort !== undefined && installDir && canonicalOccupied) {
+    const holder = pidOnPort(canonicalPort);
+    if (holder !== undefined && holder !== process.pid) {
+      const { attributable, cmdline } = orphanAttributable({
+        orphan: holder,
+        // No recorded pid to trust here — a wiped services.json carries none —
+        // so attribution rides entirely on the per-module cmdline marker.
+        recordedPid: undefined,
+        short,
+        startCmdHint: undefined,
+        ownerOfPid,
+        // Per-module marker = installDir (e.g. `~/.parachute/vault/`); a prior
+        // instance of this module was launched from there, so its `ps` cmdline
+        // carries it. NOT the broad `parachute` marker — that would let a
+        // sibling module's orphan on this port be (wrongly) adopted.
+        moduleMarker: installDir,
+      });
+      if (attributable) {
+        log(
+          `Canonical port ${canonicalPort} is held by an attributable prior ${short} instance (pid ${holder}${cmdline ? `, ${cmdline}` : ""}) — reclaiming it (adopt-kill) instead of walking to a fallback (#609).`,
+        );
+        await adoptKillOnPort({
+          port: canonicalPort,
+          holder,
+          kill: opts.killPid ?? defaultKill,
+          sleep: opts.sleep ?? defaultSleep,
+          pidOnPort,
+          delayMs: opts.reclaimDelayMs ?? 1500,
+          log,
+        });
+      }
+    }
+  }
+
+  // Hub-as-port-authority (#53): pick the service's port now and reflect it
+  // in services.json. Pre-hub#206 the install path also wrote `PORT=<port>`
+  // into the service's `.env`; post-#206 (option A) services.json is the
+  // single source of truth — services follow the 4-tier resolvePort ladder
+  // (services.json → service config → bare PORT env → compiled-in default,
+  // per parachute-scribe#41 / parachute-agent#146 / parachute-agent#148 /
+  // parachute-patterns#45), so the duplicate `.env` PORT was at best dead
+  // weight and at worst a source of drift on re-install. Existing `.env`
+  // PORT lines on operator machines stay where they are — harmless — and
+  // future installs no longer touch them.
+  //
+  // collectOccupiedPorts runs AFTER the #609 adopt-kill above so a reclaimed
+  // canonical port is seen as free and the assignment lands on it (no walk).
+  const occupied = await collectOccupiedPorts(manifestPath, entryName, preInitEntry?.port, probe);
   const portResult = assignServicePort({
     canonical: canonicalPort,
     occupied,
   });
   if (portResult.warning) {
     log(`⚠ ${portResult.warning}`);
-    // #590 item 2: the canonical port was held, so we walked to a fallback. Name
-    // the squatter — the supervisor start-path does this post-#581; do it here at
-    // install-time too. Reuse the #581 pidOnPort / ownerOfPid seams (detection
-    // only; never kill). When the holder is a foreign pid (not one of OUR rows —
-    // which is the common case when a stale pre-supervisor daemon is squatting),
-    // surface its pid + command line + a hint.
+    // #590 item 2: the canonical port was held by a NON-attributable holder (the
+    // #609 adopt-kill above already reclaimed an attributable same-module
+    // orphan), so we walked to a fallback. Name the squatter — the supervisor
+    // start-path does this post-#581; do it here at install-time too. Reuse the
+    // #581 pidOnPort / ownerOfPid seams (detection only; never kill). When the
+    // holder is a foreign pid (not one of OUR rows — which is the common case
+    // when a stale pre-supervisor daemon is squatting), surface its pid +
+    // command line + a hint.
     if (canonicalPort !== undefined && portResult.source !== "canonical") {
-      const pidOnPort = opts.pidOnPort ?? defaultPidOnPort;
-      const ownerOfPid = opts.ownerOfPid ?? defaultOwnerOfPid;
       const holder = pidOnPort(canonicalPort);
       if (holder !== undefined) {
         const cmdline = ownerOfPid(holder);

package/src/hub-db-liveness.ts

@@ -1,7 +1,8 @@
 import type { Database } from "bun:sqlite";
+import { statSync } from "node:fs";
 
 /**
- * SQLite-handle liveness + self-heal policy (#594).
+ * SQLite-handle liveness + self-heal policy (#594, #610).
  *
  * Field repro: an operator deleted `~/.parachute` while the hub unit was
  * running. The process kept an fd to the now-unlinked `hub.db` inode — cached
@@ -12,12 +13,33 @@ import type { Database } from "bun:sqlite";
  * /health is the worst possible failure shape — a crash-restart would have
  * self-healed in seconds (the platform manager re-`openHubDb`s a fresh handle).
  *
- * The policy here: on a request that hits the persistent-corruption error
- * class, attempt ONE reopen of the handle; if reopen fails OR the error
- * recurs immediately, log loudly and `process.exit(1)` so the platform
- * manager (launchd / systemd / container runtime) restarts with a fresh
- * handle. We are careful to scope "fatal" to the persistent class — a
- * transient `SQLITE_BUSY` (a momentary write lock) must NOT kill the hub.
+ * The REACTIVE policy (#594): on a request that hits the persistent-corruption
+ * error class, attempt ONE reopen of the handle; if reopen fails OR the error
+ * recurs immediately, log loudly and `process.exit(1)` so the platform manager
+ * (launchd / systemd / container runtime) restarts with a fresh handle. We are
+ * careful to scope "fatal" to the persistent class — a transient `SQLITE_BUSY`
+ * (a momentary write lock) must NOT kill the hub.
+ *
+ * The PROACTIVE policy (#610): the reactive path above only fires on a THROWN
+ * error. But on Linux, `rm -rf ~/.parachute` under a running hub does NOT throw
+ * — the kernel keeps the unlinked `hub.db` inode alive behind the open fd, so
+ * `SELECT 1` and even writes keep succeeding against the ghost (deleted) inode
+ * indefinitely. Nothing throws ⇒ the reactive self-heal never fires ⇒ `/health`
+ * lies `db:"ok"` forever against a database that's gone from disk. The proactive
+ * check closes this gap WITHOUT relying on a thrown error: at open time we record
+ * the db file's inode (`st_dev`/`st_ino`); a low-frequency probe (and `/health`'s
+ * db check) re-`stat()`s the configured path and compares. ENOENT on the path, or
+ * an inode mismatch, means the on-disk DB the handle points at is gone / replaced
+ * ⇒ trigger the SAME reopen-or-exit machinery (here the path is gone, so reopen's
+ * verify fails and we exit, letting the platform manager restart with a fresh,
+ * on-disk handle in seconds rather than "never").
+ *
+ * SAFETY (both policies): we only ever escalate to reopen/exit on the genuine
+ * persistent signal — a thrown fatal error, or a definitively gone/replaced path.
+ * Transient conditions (SQLITE_BUSY, a momentary lock, a stat() that fails for a
+ * reason OTHER than ENOENT — e.g. EACCES, EINTR) NEVER trigger it. The exit fn is
+ * injectable so no test can kill the test process (hub#535 precedent), and the
+ * proactive timer is bounded so it can't spin.
  */
 
 /**
@@ -120,12 +142,92 @@ export function probeDbLiveness(db: Database): "ok" | string {
   }
 }
 
+/**
+ * The identity of an on-disk file — `st_dev`/`st_ino`, the only two fields that
+ * uniquely identify an inode across a delete+recreate. We snapshot this for the
+ * db path at open time so the proactive probe (#610) can tell "same file the
+ * handle points at" from "path now resolves to a DIFFERENT (or no) inode".
+ */
+export interface DbInode {
+  dev: number;
+  ino: number;
+}
+
+/**
+ * Injectable `stat` of the db PATH (not the open handle). Production wires
+ * {@link defaultStatInode} (`fs.statSync`); tests inject a function that returns
+ * a chosen inode, `undefined` for ENOENT (path gone), or throws a non-ENOENT
+ * error (e.g. EACCES — a TRANSIENT failure that must NOT trigger self-heal).
+ *
+ * Contract: return the {@link DbInode} on success, `undefined` when the path
+ * does not exist (ENOENT — the genuine "wiped" signal), and THROW for any other
+ * error (so the caller can treat it as transient and leave the hub alone).
+ */
+export type StatInodeFn = (path: string) => DbInode | undefined;
+
+/**
+ * Production `stat`: returns the path's inode, or `undefined` on ENOENT. Any
+ * other error (EACCES, EINTR, …) is re-thrown so the caller classifies it as
+ * transient — we only ever self-heal on a DEFINITIVELY-gone path.
+ */
+export const defaultStatInode: StatInodeFn = (path) => {
+  try {
+    const st = statSync(path);
+    return { dev: st.dev, ino: st.ino };
+  } catch (err) {
+    if (err && typeof err === "object" && (err as { code?: unknown }).code === "ENOENT") {
+      return undefined;
+    }
+    throw err;
+  }
+};
+
+/**
+ * The verdict of a proactive path-liveness check (#610), against the inode the
+ * handle was opened on:
+ *   - `"ok"`       → the path still resolves to the SAME inode the handle holds.
+ *   - `"gone"`     → the path no longer exists (ENOENT) — the state dir was wiped.
+ *   - `"replaced"` → the path exists but resolves to a DIFFERENT inode — the DB
+ *                    file was deleted + recreated underneath the handle.
+ *   - `"unknown"`  → we couldn't snapshot the open inode (no baseline) so we
+ *                    can't compare; treated as a non-signal (never self-heals).
+ *
+ * Only `"gone"`/`"replaced"` are the genuine wipe signal that triggers self-heal.
+ */
+export type PathLivenessClass = "ok" | "gone" | "replaced" | "unknown";
+
+/**
+ * Pure classifier: compare the inode the path resolves to NOW (or `undefined`
+ * for ENOENT) against the inode the open handle was created on. No I/O — the
+ * caller does the `stat()` and the open-inode snapshot; this is the decision so
+ * it's trivially unit-testable and the "never fire on transient" rule is a
+ * single, auditable function.
+ *
+ * A non-ENOENT stat error is NOT represented here — the caller (`statInode`'s
+ * contract) THROWS on it, and the probe treats a thrown stat as transient
+ * (leaves the hub alone). Only a clean ENOENT (`current === undefined`) or a
+ * clean inode mismatch reaches a self-heal verdict.
+ */
+export function classifyPathLiveness(args: {
+  /** The inode the open db handle was created on (snapshot at open). */
+  expected: DbInode | undefined;
+  /** The inode the path resolves to NOW, or `undefined` for ENOENT. */
+  current: DbInode | undefined;
+}): PathLivenessClass {
+  const { expected, current } = args;
+  // No baseline → we can't compare; never self-heal on a missing snapshot.
+  if (expected === undefined) return "unknown";
+  if (current === undefined) return "gone";
+  if (current.dev === expected.dev && current.ino === expected.ino) return "ok";
+  return "replaced";
+}
+
 /**
  * A mutable holder for the hub's `Database` handle so a request handler that
  * hits the fatal error class can swap in a freshly-reopened handle without
  * re-threading the closure-captured `db` through every call site. `getDb()`
- * in hub-server reads `holder.get()`; the self-heal path calls
- * `holder.healOrExit(err)`.
+ * in hub-server reads `holder.get()`; the reactive self-heal path calls
+ * `holder.healOrExit(err)`; the proactive (#610) path calls `holder.probePath()`.
  */
 export interface DbHolder {
   /** The current live handle. */
@@ -145,6 +247,20 @@ export interface DbHolder {
    * gone), we exit rather than loop — the platform manager owns the restart.
    */
   healOrExit(err: unknown): "ignored" | "healed" | "exited";
+  /**
+   * PROACTIVE path-liveness probe (#610). `stat()`s the configured db PATH and
+   * compares its inode to the one the open handle was created on. On a genuine
+   * wipe signal (`"gone"`/`"replaced"`) it triggers the SAME reopen-or-exit
+   * machinery as `healOrExit` (here the path is gone, so reopen's verify fails
+   * → exit → platform manager restarts with a fresh on-disk handle). On `"ok"`,
+   * `"unknown"`, or a thrown (transient) stat it does NOTHING.
+   *
+   * Returns the {@link PathLivenessClass} verdict so `/health` and tests can see
+   * what was observed; the `"healed"`/`"exited"` side effects mirror `healOrExit`.
+   * Wired into the bounded liveness timer in hub-server AND into `/health`'s db
+   * check, so monitoring + the #591 adoption probe see the fault instead of a lie.
+   */
+  probePath(): PathLivenessClass;
 }
 
 export interface DbHolderDeps {
@@ -156,6 +272,20 @@ export interface DbHolderDeps {
   exit?: (code: number) => void;
   /** Close a (presumed-dead) handle best-effort before swapping (default `db.close()`). */
   closeOld?: (db: Database) => void;
+  /**
+   * The on-disk db PATH the proactive probe (#610) stat()s. When omitted,
+   * `probePath()` is a no-op (`"unknown"`) — backwards-compatible for the
+   * reactive-only callers + tests that don't exercise the proactive path.
+   */
+  dbPath?: string;
+  /** Injectable path stat for the proactive probe (default {@link defaultStatInode}). */
+  statInode?: StatInodeFn;
+  /**
+   * The inode the INITIAL handle was opened on. Production passes the snapshot
+   * taken right after `openHubDb`; when omitted (or when the snapshot itself
+   * failed), `probePath()` returns `"unknown"` and never self-heals.
+   */
+  initialInode?: DbInode | undefined;
 }
 
 /**
@@ -166,8 +296,13 @@ export interface DbHolderDeps {
  */
 export function createDbHolder(initial: Database, deps: DbHolderDeps): DbHolder {
   let current = initial;
+  // The inode the CURRENT handle is bound to. Updated on every successful
+  // reopen so the proactive probe (#610) compares against the live handle, not
+  // a one-time snapshot that would go stale after a heal.
+  let currentInode: DbInode | undefined = deps.initialInode;
   const log = deps.log ?? ((line) => console.error(line));
   const exit = deps.exit ?? ((code) => process.exit(code));
+  const statInode = deps.statInode ?? defaultStatInode;
   const closeOld =
     deps.closeOld ??
     ((db) => {
@@ -178,34 +313,159 @@ export function createDbHolder(initial: Database, deps: DbHolderDeps): DbHolder
       }
     });
 
+  /**
+   * Shared reopen-once-or-exit core for BOTH the reactive (`healOrExit`) and
+   * proactive (`probePath`) self-heal paths. `reason` is the loud-log preamble
+   * describing what triggered it. Returns `"healed"` (fresh handle swapped in +
+   * verified) or `"exited"` (reopen failed / new handle dead → exit, which only
+   * returns in tests where `exit` is a non-killing spy).
+   */
+  const reopenOrExit = (reason: string): "healed" | "exited" => {
+    log(`parachute hub: ${reason}. Attempting one DB handle reopen…`);
+
+    let reopened: Database;
+    try {
+      reopened = deps.reopen();
+      // Confirm the fresh handle is actually live before trusting it.
+      reopened.query("SELECT 1").get();
+    } catch (reopenErr) {
+      const rd = reopenErr instanceof Error ? reopenErr.message : String(reopenErr);
+      log(
+        `parachute hub: DB reopen failed (${rd}); exiting so the platform manager restarts the hub with a fresh handle.`,
+      );
+      exit(1);
+      return "exited";
+    }
+
+    // Reopen succeeded + verified. Swap it in; the old handle is dead.
+    closeOld(current);
+    current = reopened;
+    // Re-snapshot the inode of the path the fresh handle now points at, so the
+    // proactive probe tracks the NEW file (best-effort — a failed snapshot
+    // leaves `currentInode` undefined → probe returns "unknown", never fires).
+    if (deps.dbPath !== undefined) {
+      try {
+        currentInode = statInode(deps.dbPath);
+      } catch {
+        currentInode = undefined;
+      }
+    }
+    log("parachute hub: DB handle reopened successfully; continuing.");
+    return "healed";
+  };
+
   return {
     get: () => current,
     healOrExit(err: unknown) {
       const klass = classifyDbError(err);
       if (klass !== "fatal") return "ignored";
-
       const detail = err instanceof Error ? err.message : String(err);
-      log(`parachute hub: persistent SQLite failure (${detail}). Attempting one DB handle reopen…`);
+      return reopenOrExit(`persistent SQLite failure (${detail})`);
+    },
+    probePath(): PathLivenessClass {
+      // No path configured → proactive probe disabled (reactive-only callers).
+      if (deps.dbPath === undefined) return "unknown";
 
-      let reopened: Database;
+      // `pathInode` (NOT `current`) — the inode the db PATH resolves to right
+      // now. Named distinctly from the outer `current` (the live Database
+      // handle) so a reader can't misread this as the DB handle.
+      let pathInode: DbInode | undefined;
       try {
-        reopened = deps.reopen();
-        // Confirm the fresh handle is actually live before trusting it.
-        reopened.query("SELECT 1").get();
-      } catch (reopenErr) {
-        const rd = reopenErr instanceof Error ? reopenErr.message : String(reopenErr);
-        log(
-          `parachute hub: DB reopen failed (${rd}); exiting so the platform manager restarts the hub with a fresh handle.`,
-        );
-        exit(1);
-        return "exited";
+        pathInode = statInode(deps.dbPath);
+      } catch {
+        // A non-ENOENT stat failure (EACCES, EINTR, a transient FS hiccup) is
+        // explicitly NOT a wipe signal. Leave the hub alone — the next probe
+        // re-reads. This is the "never fire on transient" guard for the
+        // proactive path; only a clean ENOENT/mismatch below self-heals.
+        return "ok";
       }
 
-      // Reopen succeeded + verified. Swap it in; the old handle is dead.
-      closeOld(current);
-      current = reopened;
-      log("parachute hub: DB handle reopened successfully; continuing.");
-      return "healed";
+      const verdict = classifyPathLiveness({ expected: currentInode, current: pathInode });
+      if (verdict === "ok" || verdict === "unknown") return verdict;
+
+      // Genuine wipe signal: the on-disk DB the handle points at is gone
+      // ("gone") or was replaced underneath us ("replaced"). Trigger the SAME
+      // reopen-or-exit machinery. When the path is gone, reopen's SELECT-1
+      // verify fails → exit → platform manager restarts with a fresh on-disk
+      // handle (seconds, not "never"). When replaced, we adopt the fresh inode.
+      //
+      // ONE-TICK /health ANOMALY (intentional): on a "replaced" verdict the
+      // reopenOrExit below heals SYNCHRONOUSLY, but we still RETURN "replaced"
+      // for this one call — so the /health request that drove this probe reports
+      // `db:"error: path-replaced"` even though the handle is now healthy; the
+      // very next request reads `ok`. We don't mask it (returning "ok" here would
+      // hide that a heal just happened, which is exactly what monitoring wants to
+      // see). It's safe because #591's adoption probe checks only HTTP 200
+      // (`res.ok`), not the specific `db` string, so a single transient error
+      // string can't cascade.
+      reopenOrExit(
+        verdict === "gone"
+          ? `db path ${deps.dbPath} no longer exists (state dir wiped under a running hub, #610)`
+          : `db path ${deps.dbPath} now resolves to a different inode (DB file replaced underneath the open handle, #610)`,
+      );
+      return verdict;
+    },
+  };
+}
+
+/** Handle to stop a running proactive-liveness timer (test cleanup + shutdown). */
+export interface DbLivenessTimer {
+  stop(): void;
+}
+
+export interface DbLivenessTimerDeps<H = unknown> {
+  /** Poll cadence in ms. Default 15_000 (low-frequency — this is a safety net,
+   * not a hot path; the cost is one `stat()` syscall per tick). */
+  intervalMs?: number;
+  /** Injectable scheduler (default `setInterval`). Tests drive ticks manually. */
+  setIntervalFn?: (cb: () => void, ms: number) => H;
+  /** Injectable clear (default `clearInterval`). */
+  clearIntervalFn?: (handle: H) => void;
+  /** Loud log sink for an unexpected probe throw (default `console.error`). */
+  log?: (line: string) => void;
+}
+
+/**
+ * Start the bounded, low-frequency PROACTIVE liveness timer (#610). Each tick
+ * calls `holder.probePath()` — which self-heals (reopen-or-exit) on a genuine
+ * wipe and no-ops otherwise. The cadence is fixed (default 15s) so it can NEVER
+ * spin: a tick does exactly one `stat()` then sleeps the full interval; even if
+ * the probe self-heals + exits, that's terminal. We swallow any unexpected
+ * probe throw (logged) rather than let an interval callback crash the process —
+ * the probe is a safety net, not a load-bearing request path.
+ *
+ * `unref()` is called so this timer never keeps the event loop alive on its own
+ * (it's purely a watchdog over the already-running server).
+ */
+export function startDbPathLivenessTimer<H = ReturnType<typeof setInterval>>(
+  holder: DbHolder,
+  deps: DbLivenessTimerDeps<H> = {},
+): DbLivenessTimer {
+  const intervalMs = deps.intervalMs ?? 15_000;
+  const setIntervalFn =
+    deps.setIntervalFn ?? ((cb: () => void, ms: number) => setInterval(cb, ms) as unknown as H);
+  const clearIntervalFn =
+    deps.clearIntervalFn ??
+    ((h: H) => clearInterval(h as unknown as ReturnType<typeof setInterval>));
+  const log = deps.log ?? ((line) => console.error(line));
+
+  const handle = setIntervalFn(() => {
+    try {
+      holder.probePath();
+    } catch (err) {
+      // A probe should never throw (statInode swallows non-ENOENT, the holder
+      // handles the rest), but if it somehow does, don't take the process down
+      // from inside a timer callback — log and let the next tick retry.
+      const detail = err instanceof Error ? err.message : String(err);
+      log(`parachute hub: proactive DB-liveness probe threw unexpectedly (${detail}); ignoring.`);
+    }
+  }, intervalMs);
+  // Don't let the watchdog alone keep the process alive.
+  (handle as { unref?: () => void }).unref?.();
+
+  return {
+    stop() {
+      clearIntervalFn(handle);
     },
   };
 }

package/src/hub-server.ts

@@ -184,7 +184,13 @@ import { applyCorsHeaders, corsPreflightResponse, isCorsAllowedRoute } from "./c
 import { ensureCsrfToken } from "./csrf.ts";
 import { readExposeState } from "./expose-state.ts";
 import { HUB_DEFAULT_PORT, HUB_SVC, clearHubPort, writeHubPort } from "./hub-control.ts";
-import { classifyDbError, createDbHolder, probeDbLiveness } from "./hub-db-liveness.ts";
+import {
+  classifyDbError,
+  createDbHolder,
+  defaultStatInode,
+  probeDbLiveness,
+  startDbPathLivenessTimer,
+} from "./hub-db-liveness.ts";
 import { hubDbPath, openHubDb } from "./hub-db.ts";
 import { getHubOrigin } from "./hub-settings.ts";
 import { type RenderHubOpts, renderHub } from "./hub.ts";
@@ -842,6 +848,17 @@ export interface HubFetchDeps {
    * the response. Absent in tests that don't exercise the DB-error path.
    */
   onDbError?: (err: unknown) => "ignored" | "healed" | "exited";
+  /**
+   * PROACTIVE db-path liveness probe (#610). Production wires the
+   * {@link DbHolder}'s `probePath` so the `/health` db check `stat()`s the
+   * configured db path and compares its inode to the open handle's — catching
+   * the "operator wiped `~/.parachute` under a running hub" case that NEVER
+   * throws on Linux (the unlinked-but-open ghost inode keeps `SELECT 1`
+   * succeeding). Returns the path-liveness verdict; on a genuine wipe it ALSO
+   * triggers the reopen-or-exit self-heal. Absent in tests that don't exercise
+   * the proactive path — `/health` then falls back to the `SELECT 1` probe only.
+   */
+  probeDbPath?: () => "ok" | "gone" | "replaced" | "unknown";
   /**
    * Hub origin used as the OAuth `iss` claim and to build the authorization-
    * server metadata document. When omitted, OAuth endpoints fall back to the
@@ -1605,7 +1622,26 @@ export function hubFetch(
         let db: "ok" | string = "unconfigured";
         if (getDb) {
           try {
-            db = probeDbLiveness(getDb());
+            // PROACTIVE path check FIRST (#610): on Linux a wiped state dir
+            // doesn't throw — the unlinked-but-open ghost inode keeps SELECT 1
+            // succeeding, so `probeDbLiveness` alone would report `db:"ok"` on a
+            // database that's gone from disk (the /health lie the issue calls
+            // out). `probeDbPath` stat()s the path + compares inodes; on a
+            // gone/replaced verdict it ALSO self-heals (reopen-or-exit) and we
+            // surface the fault so the #591 adoption probe + monitoring see it.
+            const pathVerdict = deps?.probeDbPath?.();
+            if (pathVerdict === "gone" || pathVerdict === "replaced") {
+              // One-request anomaly on "replaced": probeDbPath already healed the
+              // handle synchronously, but THIS request still reports the fault
+              // (the next /health reads `db:"ok"`). Intentional — we surface that
+              // a heal just occurred rather than masking it. Safe because #591's
+              // adoption probe gates on HTTP 200 (`res.ok`), not the `db` string,
+              // so a single transient error string can't cascade. ("gone" exits
+              // the process, usually before this response is even sent.)
+              db = `error: path-${pathVerdict}`;
+            } else {
+              db = probeDbLiveness(getDb());
+            }
           } catch {
             // getDb() itself threw (e.g. openHubDb failed) — report it as an
             // error class without letting /health 500.
@@ -2769,12 +2805,36 @@ if (import.meta.main) {
   // touch the DB still works before first open. Once opened, the holder owns
   // reopen-once-or-exit on a persistent SQLite fault.
   let holder: ReturnType<typeof createDbHolder> | undefined;
-  const getDb = () => {
+  let livenessTimer: ReturnType<typeof startDbPathLivenessTimer> | undefined;
+  const ensureHolder = (): ReturnType<typeof createDbHolder> => {
     if (!holder) {
-      holder = createDbHolder(openHubDb(dbPath), { reopen: () => openHubDb(dbPath) });
+      const db = openHubDb(dbPath);
+      // Snapshot the inode the handle is bound to NOW, so the proactive probe
+      // (#610) can later notice the path has gone / been replaced. Best-effort
+      // — a failed snapshot leaves the proactive probe at "unknown" (it never
+      // self-heals without a baseline), while the reactive path still covers
+      // thrown faults.
+      let initialInode: ReturnType<typeof defaultStatInode> | undefined;
+      try {
+        initialInode = defaultStatInode(dbPath);
+      } catch {
+        initialInode = undefined;
+      }
+      holder = createDbHolder(db, {
+        reopen: () => openHubDb(dbPath),
+        dbPath,
+        statInode: defaultStatInode,
+        initialInode,
+      });
+      // Start the bounded proactive-liveness watchdog (#610) once the handle is
+      // open. It stat()s the db path on a low-frequency timer and self-heals
+      // (reopen-or-exit) the moment the on-disk DB is wiped — closing the
+      // ghost-fd gap the reactive path can't see (no thrown error on Linux).
+      livenessTimer = startDbPathLivenessTimer(holder);
     }
-    return holder.get();
+    return holder;
   };
+  const getDb = () => ensureHolder().get();
   const onDbError = (err: unknown): "ignored" | "healed" | "exited" =>
     holder ? holder.healOrExit(err) : "ignored";
   Bun.serve({
@@ -2792,7 +2852,13 @@ if (import.meta.main) {
     // Bun's equivalent is this. 255s comfortably exceeds Render's edge
     // pool TTL (community-observed ~120s). Closes hub#399.
     idleTimeout: 255,
-    fetch: hubFetch(wellKnownDir, { getDb, onDbError, issuer, loopbackPort: port }),
+    fetch: hubFetch(wellKnownDir, {
+      getDb,
+      onDbError,
+      probeDbPath: () => holder?.probePath() ?? "unknown",
+      issuer,
+      loopbackPort: port,
+    }),
   });
   // Register PID + port from the running hub itself so any startup path
   // (spawn-via-`ensureHubRunning` or a direct `bun src/hub-server.ts` from
@@ -2802,6 +2868,7 @@ if (import.meta.main) {
   writePid(HUB_SVC, process.pid);
   writeHubPort(port);
   const cleanup = () => {
+    livenessTimer?.stop();
     clearPid(HUB_SVC);
     clearHubPort();
   };

package/src/setup-wizard.ts

@@ -75,6 +75,7 @@ import {
   readOperatorTokenFile,
 } from "./operator-token.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
+import { SEED_VERSION } from "./service-spec.ts";
 import { findService, readManifestLenient } from "./services-manifest.ts";
 import {
   SESSION_TTL_MS,
@@ -274,13 +275,29 @@ export function deriveWizardState(deps: {
   // which maps to `parachute-vault` in services.json.
   const vaultSpec = specFor(FIRST_VAULT_SHORT);
   const vaultEntry = findService(vaultSpec.manifestName, deps.manifestPath);
+  // hub#607: distinguish the SEED placeholder from a real vault instance.
+  // `parachute init` installs the vault MODULE without creating an instance
+  // (hub#168 Cut 1: `noCreate`), seeding a services.json entry at
+  // SEED_VERSION ("0.0.0-linked") with the canonical `/vault/default` mount.
+  // Vault's own first-boot overwrites that entry with the real instance once
+  // a vault is actually created. A bare `findService(...) !== undefined`
+  // check matches the placeholder, so on EVERY init'd box the wizard treated
+  // the vault step as already-done and skipped straight to expose — the
+  // operator finished setup with no vault and no prompt. Treat a
+  // SEED_VERSION row as "module installed, no instance" so the wizard still
+  // presents its create / import / skip step. This is the SAME
+  // discrimination `buildWellKnown` gained in hub#577 (it suppresses the
+  // phantom `vaults[]` row at SEED_VERSION); both surfaces must agree that a
+  // placeholder is not a real vault.
+  const vaultIsPlaceholder = vaultEntry !== undefined && vaultEntry.version === SEED_VERSION;
+  const hasRealVault = vaultEntry !== undefined && !vaultIsPlaceholder;
   // hub#168 Cut 2: `setup_vault_skipped === "true"` advances the wizard
   // past the vault step even when no vault row exists. The operator
   // explicitly chose Skip; the module is installed (Cut 1) but no
   // instance was provisioned. Treat as "vault step is done" for the
   // purposes of state-derivation so the wizard moves to expose.
   const vaultSkipped = getSetting(deps.db, "setup_vault_skipped") === "true";
-  const hasVault = vaultEntry !== undefined || vaultSkipped;
+  const hasVault = hasRealVault || vaultSkipped;
   // Expose-mode is the operator's "how will this hub be reached?" answer
   // (hub#268 Item 2). Stored as a hub_setting; the wizard's expose step
   // sets it; absence means we should still ask. EXCEPT — if we're