@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/__tests__/serve.test.ts

@@ -6,12 +6,34 @@ import { _resetBootstrapTokenForTests, getBootstrapToken } from "../bootstrap-to
 import {
   formatBootstrapTokenBanner,
   formatListeningBanner,
+  hubPortConflictMessage,
   resolveStartupIssuer,
   seedInitialAdminIfNeeded,
 } from "../commands/serve.ts";
 import { openHubDb } from "../hub-db.ts";
 import { getUserByUsername, userCount } from "../users.ts";
 
+describe("hubPortConflictMessage (hub#536)", () => {
+  test("maps a port-in-use error to a clear duplicate-supervisor message", () => {
+    // Bun surfaces a port conflict as "...Is port 1939 in use?"; node-style is
+    // "EADDRINUSE: address already in use". Both must map to the clear message.
+    for (const m of [
+      "EADDRINUSE: address already in use 127.0.0.1:1939",
+      "Failed to start server. Is port 1939 in use?",
+    ]) {
+      const out = hubPortConflictMessage(new Error(m), 1939);
+      expect(out).toContain("already in use");
+      expect(out).toContain("duplicate supervisor");
+      expect(out).toContain("1939");
+    }
+  });
+
+  test("returns null for an unrelated error (caller re-throws the original)", () => {
+    expect(hubPortConflictMessage(new Error("permission denied"), 1939)).toBeNull();
+    expect(hubPortConflictMessage("not even an Error", 1939)).toBeNull();
+  });
+});
+
 describe("seedInitialAdminIfNeeded", () => {
   let dir: string;
   let dbPath: string;
@@ -248,6 +270,13 @@ describe("bootstrap-token wiring under needs-setup", () => {
 });
 
 describe("resolveStartupIssuer — precedence chain (hub#365)", () => {
+  // Stub "no exposure recorded" so the undefined-asserting tests are
+  // isolated from the host's real ~/.parachute/expose-state.json — the
+  // default reader picks up a live exposure on the dev box and the expose
+  // tier (#531) would otherwise shadow the "no source → undefined" cases.
+  // The expose tier itself is exercised in its own describe block below.
+  const noExpose = (): string | undefined => undefined;
+
   test("explicit opts.issuer wins over everything", () => {
     const got = resolveStartupIssuer(
       { issuer: "https://override.example" },
@@ -296,9 +325,9 @@ describe("resolveStartupIssuer — precedence chain (hub#365)", () => {
   });
 
   test("returns undefined when no source has a value", () => {
-    expect(resolveStartupIssuer({}, {})).toBeUndefined();
-    expect(resolveStartupIssuer({}, { RENDER_EXTERNAL_URL: "" })).toBeUndefined();
-    expect(resolveStartupIssuer({}, { PARACHUTE_HUB_ORIGIN: "" })).toBeUndefined();
+    expect(resolveStartupIssuer({}, {}, noExpose)).toBeUndefined();
+    expect(resolveStartupIssuer({}, { RENDER_EXTERNAL_URL: "" }, noExpose)).toBeUndefined();
+    expect(resolveStartupIssuer({}, { PARACHUTE_HUB_ORIGIN: "" }, noExpose)).toBeUndefined();
   });
 
   test("empty string after slash-strip collapses to undefined (defensive)", () => {
@@ -306,7 +335,7 @@ describe("resolveStartupIssuer — precedence chain (hub#365)", () => {
     // Guards against a misconfigured env where someone sets the var to "/"
     // expecting it to mean "root" (it doesn't — leaves hub without a usable
     // origin, which is the same as not setting it at all).
-    expect(resolveStartupIssuer({}, { PARACHUTE_HUB_ORIGIN: "/" })).toBeUndefined();
+    expect(resolveStartupIssuer({}, { PARACHUTE_HUB_ORIGIN: "/" }, noExpose)).toBeUndefined();
   });
 
   // Fly.io self-host path (patterns#100). resolveStartupIssuer is the
@@ -341,11 +370,96 @@ describe("resolveStartupIssuer — precedence chain (hub#365)", () => {
   });
 
   test("FLY_APP_NAME with slash rejected (defensive — Fly slugs don't contain /)", () => {
-    expect(resolveStartupIssuer({}, { FLY_APP_NAME: "a/b" })).toBeUndefined();
-    expect(resolveStartupIssuer({}, { FLY_APP_NAME: "../etc/passwd" })).toBeUndefined();
+    expect(resolveStartupIssuer({}, { FLY_APP_NAME: "a/b" }, noExpose)).toBeUndefined();
+    expect(resolveStartupIssuer({}, { FLY_APP_NAME: "../etc/passwd" }, noExpose)).toBeUndefined();
   });
 
   test("FLY_APP_NAME empty string → no fallback", () => {
-    expect(resolveStartupIssuer({}, { FLY_APP_NAME: "" })).toBeUndefined();
+    expect(resolveStartupIssuer({}, { FLY_APP_NAME: "" }, noExpose)).toBeUndefined();
+  });
+});
+
+describe("resolveStartupIssuer — expose-state fallback (#531)", () => {
+  // The reboot-persistent bug: the launchd plist / systemd unit that keeps
+  // `parachute serve` alive carries no PARACHUTE_HUB_ORIGIN, so on every
+  // reboot the hub boots with no flag/env/platform origin and would stamp
+  // iss from the per-request origin — which exposed resource servers (vault)
+  // reject until they restart. Reading expose-state.json's hubOrigin makes
+  // iss deterministic across reboots. The readExpose seam lets us drive this
+  // without touching the real ~/.parachute.
+  const EXPOSED = "https://parachute.taildf9ce2.ts.net";
+
+  test("returns expose-state.hubOrigin when no flag/env/platform set", () => {
+    const got = resolveStartupIssuer({}, {}, () => EXPOSED);
+    expect(got).toBe(EXPOSED);
+  });
+
+  test("explicit opts.issuer wins over expose-state", () => {
+    const got = resolveStartupIssuer({ issuer: "https://override.example" }, {}, () => EXPOSED);
+    expect(got).toBe("https://override.example");
+  });
+
+  test("PARACHUTE_HUB_ORIGIN wins over expose-state", () => {
+    const got = resolveStartupIssuer(
+      {},
+      { PARACHUTE_HUB_ORIGIN: "https://env.example" },
+      () => EXPOSED,
+    );
+    expect(got).toBe("https://env.example");
+  });
+
+  test("RENDER_EXTERNAL_URL wins over expose-state", () => {
+    const got = resolveStartupIssuer(
+      {},
+      { RENDER_EXTERNAL_URL: "https://app.onrender.com" },
+      () => EXPOSED,
+    );
+    expect(got).toBe("https://app.onrender.com");
+  });
+
+  test("FLY_APP_NAME wins over expose-state", () => {
+    const got = resolveStartupIssuer({}, { FLY_APP_NAME: "my-parachute" }, () => EXPOSED);
+    expect(got).toBe("https://my-parachute.fly.dev");
+  });
+
+  test("returns undefined when expose-state is absent (no hubOrigin recorded)", () => {
+    expect(resolveStartupIssuer({}, {}, () => undefined)).toBeUndefined();
+  });
+
+  test("strips trailing slashes from the expose origin", () => {
+    expect(resolveStartupIssuer({}, {}, () => `${EXPOSED}/`)).toBe(EXPOSED);
+    expect(resolveStartupIssuer({}, {}, () => `${EXPOSED}//`)).toBe(EXPOSED);
+  });
+
+  test("ignores a loopback expose hubOrigin (never re-pin the degraded mode)", () => {
+    expect(resolveStartupIssuer({}, {}, () => "http://127.0.0.1:1939")).toBeUndefined();
+    expect(resolveStartupIssuer({}, {}, () => "http://localhost:1939")).toBeUndefined();
+    expect(resolveStartupIssuer({}, {}, () => "http://[::1]:1939")).toBeUndefined();
+    expect(resolveStartupIssuer({}, {}, () => "http://0.0.0.0:1939")).toBeUndefined();
+  });
+
+  test("ignores a non-http(s) or malformed expose origin", () => {
+    expect(resolveStartupIssuer({}, {}, () => "ftp://parachute.example")).toBeUndefined();
+    expect(resolveStartupIssuer({}, {}, () => "not-a-url")).toBeUndefined();
+    expect(resolveStartupIssuer({}, {}, () => "")).toBeUndefined();
+  });
+
+  test("default reader is swallowed-safe (no real ~/.parachute) — does not throw", () => {
+    // The default readExpose swallows a malformed-file throw; with no
+    // exposure recorded under the test PARACHUTE_HOME it just yields
+    // undefined → undefined issuer. The key assertion is "doesn't throw."
+    expect(() => resolveStartupIssuer({}, {})).not.toThrow();
+  });
+
+  test("a throwing injected reader can't crash startup (returns undefined)", () => {
+    // The readExpose() call is try/catch-wrapped so even a non-swallowing
+    // reader can't propagate into boot. With no flag/env/platform origin set
+    // and a throwing reader, the issuer resolves to undefined (the degraded
+    // request-origin mode) rather than crashing `parachute serve`.
+    const throwing = () => {
+      throw new Error("malformed expose-state.json");
+    };
+    expect(() => resolveStartupIssuer({}, {}, throwing)).not.toThrow();
+    expect(resolveStartupIssuer({}, {}, throwing)).toBeUndefined();
   });
 });

package/src/__tests__/spawn-path.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type EnrichedPathDeps,
+  enrichedPath,
+  enrichedUnitPath,
+  operatorToolDirs,
+} from "../spawn-path.ts";
+
+/**
+ * Build EnrichedPathDeps with a fake fs (set of existing paths) + pinned
+ * platform/arch/home so tests never touch the real disk or host.
+ */
+function fakeDeps(opts: {
+  home?: string;
+  platform?: NodeJS.Platform;
+  arch?: string;
+  existing?: string[];
+}): EnrichedPathDeps {
+  const existing = new Set(opts.existing ?? []);
+  return {
+    homeDir: () => opts.home ?? "/home/op",
+    exists: (p) => existing.has(p),
+    platform: opts.platform ?? "darwin",
+    arch: opts.arch ?? "arm64",
+  };
+}
+
+describe("enrichedPath — operator-tool PATH enrichment", () => {
+  test("preserves the inherited PATH and keeps its order", () => {
+    const deps = fakeDeps({ existing: [] });
+    const result = enrichedPath({ PATH: "/usr/bin:/bin" }, deps);
+    expect(result).toBe("/usr/bin:/bin");
+  });
+
+  test("appends operator-tool dirs only when they exist on disk", () => {
+    // .local/bin + brew exist; .bun/bin does NOT → only the two existing append.
+    const deps = fakeDeps({
+      home: "/home/op",
+      platform: "darwin",
+      arch: "arm64",
+      existing: ["/home/op/.local/bin", "/opt/homebrew/bin"],
+    });
+    const result = enrichedPath({ PATH: "/usr/bin" }, deps);
+    expect(result).toBe("/usr/bin:/home/op/.local/bin:/opt/homebrew/bin");
+    expect(result).not.toContain("/home/op/.bun/bin");
+  });
+
+  test("inherited PATH wins over appended defaults (append, not prepend)", () => {
+    const deps = fakeDeps({ existing: ["/home/op/.local/bin"] });
+    const result = enrichedPath({ PATH: "/first:/second" }, deps);
+    const parts = result.split(":");
+    expect(parts[0]).toBe("/first");
+    expect(parts[1]).toBe("/second");
+    expect(parts[2]).toBe("/home/op/.local/bin");
+  });
+
+  test("dedupes — an appended dir already in the inherited PATH is not duplicated", () => {
+    const deps = fakeDeps({ existing: ["/home/op/.local/bin"] });
+    const result = enrichedPath({ PATH: "/usr/bin:/home/op/.local/bin" }, deps);
+    expect(result).toBe("/usr/bin:/home/op/.local/bin");
+    expect(result.split(":").filter((p) => p === "/home/op/.local/bin")).toHaveLength(1);
+  });
+
+  test("PARACHUTE_EXTRA_PATH is PREPENDED so an operator can intentionally shadow", () => {
+    const deps = fakeDeps({ existing: ["/home/op/.local/bin"] });
+    const result = enrichedPath(
+      { PATH: "/usr/bin", PARACHUTE_EXTRA_PATH: "/opt/custom/bin:/opt/more" },
+      deps,
+    );
+    const parts = result.split(":");
+    expect(parts[0]).toBe("/opt/custom/bin");
+    expect(parts[1]).toBe("/opt/more");
+    expect(parts[2]).toBe("/usr/bin");
+    expect(parts[3]).toBe("/home/op/.local/bin");
+  });
+
+  test("PARACHUTE_EXTRA_PATH dedupes against inherited (extra-first wins position)", () => {
+    const deps = fakeDeps({ existing: [] });
+    const result = enrichedPath({ PATH: "/usr/bin:/dup", PARACHUTE_EXTRA_PATH: "/dup" }, deps);
+    expect(result).toBe("/dup:/usr/bin");
+  });
+
+  test("empty inherited PATH yields just the existing appended dirs", () => {
+    const deps = fakeDeps({
+      home: "/home/op",
+      platform: "darwin",
+      arch: "arm64",
+      existing: ["/home/op/.local/bin", "/opt/homebrew/bin", "/home/op/.bun/bin"],
+    });
+    const result = enrichedPath({ PATH: "" }, deps);
+    expect(result).toBe("/home/op/.local/bin:/opt/homebrew/bin:/home/op/.bun/bin");
+  });
+
+  describe("platform / arch branches", () => {
+    test("darwin arm64 → /opt/homebrew/bin", () => {
+      const deps = fakeDeps({
+        platform: "darwin",
+        arch: "arm64",
+        existing: ["/opt/homebrew/bin"],
+      });
+      expect(enrichedPath({ PATH: "/usr/bin" }, deps)).toBe("/usr/bin:/opt/homebrew/bin");
+    });
+
+    test("darwin x64 → /usr/local/bin (Intel brew)", () => {
+      const deps = fakeDeps({
+        platform: "darwin",
+        arch: "x64",
+        existing: ["/usr/local/bin"],
+      });
+      // /usr/local/bin is the brew bin on Intel macOS; here it's the only existing dir.
+      expect(enrichedPath({ PATH: "/usr/bin" }, deps)).toBe("/usr/bin:/usr/local/bin");
+    });
+
+    test("linux → only $HOME/.local/bin + $HOME/.bun/bin, no brew bin", () => {
+      const deps = fakeDeps({
+        home: "/home/op",
+        platform: "linux",
+        arch: "x64",
+        existing: ["/home/op/.local/bin", "/home/op/.bun/bin", "/opt/homebrew/bin"],
+      });
+      const result = enrichedPath({ PATH: "/usr/bin" }, deps);
+      expect(result).toBe("/usr/bin:/home/op/.local/bin:/home/op/.bun/bin");
+      // /opt/homebrew/bin exists in the fake fs but is NOT a Linux candidate dir.
+      expect(result).not.toContain("/opt/homebrew/bin");
+    });
+  });
+});
+
+describe("operatorToolDirs — candidate dir list", () => {
+  test("darwin arm64: .local/bin, /opt/homebrew/bin, .bun/bin (in order)", () => {
+    expect(operatorToolDirs("/home/op", "darwin", "arm64")).toEqual([
+      "/home/op/.local/bin",
+      "/opt/homebrew/bin",
+      "/home/op/.bun/bin",
+    ]);
+  });
+
+  test("darwin x64: brew is /usr/local/bin", () => {
+    expect(operatorToolDirs("/home/op", "darwin", "x64")).toEqual([
+      "/home/op/.local/bin",
+      "/usr/local/bin",
+      "/home/op/.bun/bin",
+    ]);
+  });
+
+  test("linux: no brew dir", () => {
+    expect(operatorToolDirs("/home/op", "linux", "x64")).toEqual([
+      "/home/op/.local/bin",
+      "/home/op/.bun/bin",
+    ]);
+  });
+});
+
+describe("enrichedUnitPath — launchd/systemd unit PATH", () => {
+  test("bun bin first, then system dirs, then operator-tool dirs (darwin arm64)", () => {
+    const result = enrichedUnitPath("/home/op/.bun", "/home/op", "darwin", "arm64", undefined);
+    expect(result).toBe(
+      "/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin:/home/op/.local/bin:/opt/homebrew/bin",
+    );
+  });
+
+  test("dedupes — Intel brew /usr/local/bin already present in the base is not duplicated", () => {
+    // darwin x64 brew dir == /usr/local/bin, which the base already carries.
+    const result = enrichedUnitPath("/home/op/.bun", "/home/op", "darwin", "x64", undefined);
+    expect(result.split(":").filter((p) => p === "/usr/local/bin")).toHaveLength(1);
+    expect(result).toBe("/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin:/home/op/.local/bin");
+  });
+
+  test("linux: appends $HOME/.local/bin (no brew dir)", () => {
+    const result = enrichedUnitPath("/home/op/.bun", "/home/op", "linux", "x64", undefined);
+    expect(result).toBe("/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin:/home/op/.local/bin");
+  });
+
+  test("includes operator-tool dirs unconditionally (no existence check)", () => {
+    // No fs seam here — the unit-side dirs are baked in even if absent on disk.
+    const result = enrichedUnitPath("/home/op/.bun", "/home/op", "darwin", "arm64", undefined);
+    expect(result).toContain("/home/op/.local/bin");
+    expect(result).toContain("/opt/homebrew/bin");
+  });
+
+  test("PARACHUTE_EXTRA_PATH is prepended", () => {
+    const result = enrichedUnitPath(
+      "/home/op/.bun",
+      "/home/op",
+      "darwin",
+      "arm64",
+      "/opt/custom/bin",
+    );
+    expect(result.split(":")[0]).toBe("/opt/custom/bin");
+  });
+});

package/src/__tests__/status.test.ts

@@ -256,4 +256,68 @@ describe("status — per-module URL deep-links (manifestRowBase / urlForEntry)",
       cleanup();
     }
   });
+
+  test("non-curated supervised module reads `active` via the `supervised` fallback — hub#539", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      // surface is supervised but absent from the curated `modules` catalog
+      // (which only carries vault/scribe). Before hub#539 it mapped to
+      // `inactive` despite running; now `status` falls back to `supervised`.
+      upsertService(
+        {
+          name: "parachute-surface",
+          port: 1946,
+          paths: ["/surface"],
+          health: "/surface/healthz",
+          version: "0.2.2",
+        },
+        path,
+      );
+      const lines: string[] = [];
+      await status({
+        ...supervisorOpts(configDir, path, {
+          // `modules` empty (curated catalog omits surface); run-state ONLY in
+          // `supervised` — exactly the wire shape the live hub now returns.
+          moduleStates: {
+            supervisorAvailable: true,
+            modules: [],
+            supervised: [runningModule("surface")],
+          },
+        }),
+        print: (l) => lines.push(l),
+      });
+      const surfaceLine = lines.find((l) => l.includes("parachute-surface")) ?? "";
+      expect(surfaceLine).toMatch(/\bactive\b/);
+      expect(surfaceLine).not.toMatch(/\binactive\b/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("module absent from BOTH modules and supervised stays `inactive` — hub#539 boundary", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        {
+          name: "parachute-surface",
+          port: 1946,
+          paths: ["/surface"],
+          health: "/surface/healthz",
+          version: "0.2.2",
+        },
+        path,
+      );
+      const lines: string[] = [];
+      await status({
+        ...supervisorOpts(configDir, path, {
+          moduleStates: { supervisorAvailable: true, modules: [], supervised: [] },
+        }),
+        print: (l) => lines.push(l),
+      });
+      const surfaceLine = lines.find((l) => l.includes("parachute-surface")) ?? "";
+      expect(surfaceLine).toMatch(/\binactive\b/);
+    } finally {
+      cleanup();
+    }
+  });
 });

package/src/__tests__/supervisor.test.ts

@@ -595,6 +595,113 @@ describe("Supervisor.restart", () => {
     sup.stop("vault");
     second.resolveExit(0);
   });
+
+  test("replays entry.req when no nextReq is supplied", async () => {
+    const first = makeFakeProc(101);
+    const second = makeFakeProc(102);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first);
+    spawner.enqueue(second);
+
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+    });
+    await sup.start({
+      short: "vault",
+      cmd: ["bun", "vault.ts"],
+      env: { PARACHUTE_HUB_ORIGIN: "https://origin.example" },
+    });
+
+    const restartPromise = sup.restart("vault");
+    first.closeStreams();
+    first.resolveExit(0);
+    await restartPromise;
+
+    // No nextReq → the re-spawn replays the original env (legacy behavior).
+    expect(spawner.calls[1]?.env?.PARACHUTE_HUB_ORIGIN).toBe("https://origin.example");
+    expect(spawner.calls[1]?.cmd).toEqual(["bun", "vault.ts"]);
+
+    second.closeStreams();
+    sup.stop("vault");
+    second.resolveExit(0);
+  });
+
+  test("nextReq re-spawns with the refreshed req AND propagates to crash-restart (hub#532)", async () => {
+    const first = makeFakeProc(101);
+    const second = makeFakeProc(102); // restart re-spawn
+    const third = makeFakeProc(103); // crash-restart respawn
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first);
+    spawner.enqueue(second);
+    spawner.enqueue(third);
+
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+    });
+    // First start with the OLD origin.
+    await sup.start({
+      short: "vault",
+      cmd: ["bun", "vault.ts"],
+      env: { PARACHUTE_HUB_ORIGIN: "https://old.example" },
+    });
+
+    // Restart WITH a refreshed req carrying the NEW origin.
+    const restartPromise = sup.restart("vault", {
+      short: "vault",
+      cmd: ["bun", "vault.ts"],
+      env: { PARACHUTE_HUB_ORIGIN: "https://new.example" },
+    });
+    first.closeStreams();
+    first.resolveExit(0);
+    await restartPromise;
+
+    // The restart re-spawn carries the NEW origin.
+    expect(spawner.calls[1]?.env?.PARACHUTE_HUB_ORIGIN).toBe("https://new.example");
+
+    // Now crash the restart-spawned child (resolveExit with a non-stop code).
+    // handleExit → spawnAndWatch replays entry.req, which `start` stored from
+    // the refreshed nextReq — so the crash-restart ALSO carries the new origin.
+    second.closeStreams();
+    second.resolveExit(1);
+    await tick(20);
+
+    expect(spawner.calls).toHaveLength(3);
+    expect(spawner.calls[2]?.env?.PARACHUTE_HUB_ORIGIN).toBe("https://new.example");
+
+    third.closeStreams();
+    sup.stop("vault");
+    third.resolveExit(0);
+  });
+
+  test("throws when nextReq.short mismatches the restarted short (state-corruption guard)", async () => {
+    const proc = makeFakeProc(101);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(proc);
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+    });
+    await sup.start({ short: "vault", cmd: ["bun", "vault.ts"] });
+
+    // A nextReq for a DIFFERENT short would re-register under the wrong map key.
+    await expect(
+      sup.restart("vault", { short: "scribe", cmd: ["bun", "scribe.ts"] }),
+    ).rejects.toThrow(/nextReq\.short is "scribe"/);
+    // The original entry is untouched — no spurious stop/respawn happened.
+    expect(spawner.calls).toHaveLength(1);
+
+    proc.closeStreams();
+    sup.stop("vault");
+    proc.resolveExit(0);
+  });
 });
 
 describe("Supervisor output multiplexing", () => {
@@ -833,6 +940,76 @@ describe("Supervisor port-readiness + structured start-error (§6.5)", () => {
     proc.resolveExit(0);
   });
 
+  test("(b2) late bind AFTER the window → the background watch clears the started-but-unbound note", async () => {
+    // Heavy modules (vault — SQLite + git mirror + well-known init) routinely
+    // bind a moment after the readiness window. Pre-fix, the note recorded at
+    // window-elapse stuck for the module's whole lifetime and `parachute
+    // status` showed a perpetual "failed to start" on a healthy module.
+    const proc = makeFakeProc(103);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(proc);
+    let bound = false;
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      portListening: async () => bound,
+      startReadyMs: 30,
+      startReadyPollMs: 5,
+      lateBindWatchMs: 2_000,
+      lateBindPollMs: 5,
+      sleep: () => Promise.resolve(),
+    });
+    const state = await sup.start(reqWithPort("vault", 1940));
+    // Window elapsed unbound → note recorded (status stays running)…
+    expect(state.startError?.error_type).toBe("started_but_unbound");
+
+    // …then the port binds late. The watch must clear the note.
+    bound = true;
+    let cleared = false;
+    const deadline = Date.now() + 1_500;
+    while (Date.now() < deadline) {
+      if (sup.list()[0]?.startError === undefined) {
+        cleared = true;
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 10));
+    }
+    expect(cleared).toBe(true);
+    expect(sup.list()[0]?.status).toBe("running");
+
+    proc.closeStreams();
+    sup.stop("vault");
+    proc.resolveExit(0);
+  });
+
+  test("(b3) never binds → the watch gives up at its deadline and the note persists", async () => {
+    // A genuinely-unbound module must KEEP its diagnostic — the watch is a
+    // bounded grace window, not an eraser.
+    const proc = makeFakeProc(104);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(proc);
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      portListening: async () => false,
+      startReadyMs: 20,
+      startReadyPollMs: 5,
+      lateBindWatchMs: 40,
+      lateBindPollMs: 5,
+      sleep: () => Promise.resolve(),
+    });
+    const state = await sup.start(reqWithPort("vault", 1940));
+    expect(state.startError?.error_type).toBe("started_but_unbound");
+
+    // Let the 40ms watch budget expire; the note must remain.
+    await new Promise((r) => setTimeout(r, 120));
+    expect(sup.list()[0]?.startError?.error_type).toBe("started_but_unbound");
+
+    proc.closeStreams();
+    sup.stop("vault");
+    proc.resolveExit(0);
+  });
+
   test("(c) preflight MissingDependencyError → structured start-error, NO spawn", async () => {
     const spawner = makeQueueSpawner();
     // No proc enqueued — if start() tried to spawn, the queue spawner throws.

package/src/__tests__/users.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { recordTokenMint, signAccessToken } from "../jwt-sign.ts";
+import { createSession, findSession } from "../sessions.ts";
 import {
   PASSWORD_MIN_LEN,
   SingleUserModeError,
@@ -499,6 +500,32 @@ describe("resetUserPassword", () => {
     }
   });
 
+  // Item G — a reset also kills active sessions (not just tokens), so the
+  // attacker/holder of a live session cookie must re-authenticate.
+  test("deletes the user's active sessions (item G)", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const alice = await createUser(db, "alice", "alice-strong-passphrase", {
+        passwordChanged: true,
+      });
+      const bob = await createUser(db, "bob", "bob-strong-passphrase", {
+        passwordChanged: true,
+        allowMulti: true,
+      });
+      const aliceSession = createSession(db, { userId: alice.id });
+      const bobSession = createSession(db, { userId: bob.id });
+      expect(findSession(db, aliceSession.id)).not.toBeNull();
+
+      expect(await resetUserPassword(db, alice.id, "new-temp-passphrase")).toBe(true);
+
+      // Alice's session is gone; Bob's (a different user) is untouched.
+      expect(findSession(db, aliceSession.id)).toBeNull();
+      expect(findSession(db, bobSession.id)).not.toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
   test("does not re-revoke an already-revoked token", async () => {
     // Defense-in-depth: a previously-revoked token shouldn't have its
     // revoked_at timestamp overwritten by a fresh reset. The UPDATE's