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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.5-rc.4",
+  "version": "0.6.5-rc.6",
   "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