@openparachute/hub 0.6.3 → 0.6.4-rc.10

package/src/__tests__/invites.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Core invite-primitive tests (`src/invites.ts`). Mirrors the auth-codes
+ * test shape: issue, lookup-by-raw, status derivation, redeemable assertion
+ * (not-found / expired / used / revoked), single-use consume, revoke.
+ *
+ * Security invariants asserted here: 256-bit raw token, sha256 at rest (the
+ * raw token never appears in the row), single-use via used_at, expiry
+ * enforced at redeem, revocable.
+ */
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  DEFAULT_INVITE_TTL_SECONDS,
+  InviteExpiredError,
+  InviteNotFoundError,
+  InviteRevokedError,
+  InviteUsedError,
+  assertInviteRedeemable,
+  consumeInvite,
+  findInviteByRawToken,
+  hashInviteToken,
+  inviteStatus,
+  issueInvite,
+  listInvites,
+  revokeInvite,
+} from "../invites.ts";
+import { createUser } from "../users.ts";
+
+async function makeDb() {
+  const dir = mkdtempSync(join(tmpdir(), "phub-invites-"));
+  const db = openHubDb(hubDbPath(dir));
+  const admin = await createUser(db, "operator", "operator-password-1");
+  return {
+    db,
+    adminId: admin.id,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("issueInvite", () => {
+  test("returns a 256-bit raw token and stores ONLY its sha256", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const { rawToken, invite } = issueInvite(db, { createdBy: adminId, vaultName: "maya" });
+      // base64url of 32 bytes ≈ 43 chars — comfortably high entropy.
+      expect(rawToken.length).toBeGreaterThan(40);
+      expect(invite.tokenHash).toBe(hashInviteToken(rawToken));
+      expect(invite.tokenHash).not.toBe(rawToken);
+      // The row stores the hash, never the raw token.
+      const row = db
+        .query<{ token: string }, [string]>("SELECT token FROM invites WHERE token = ?")
+        .get(createHash("sha256").update(rawToken).digest("hex"));
+      expect(row?.token).toBe(invite.tokenHash);
+      const rawRow = db
+        .query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM invites WHERE token = ?")
+        .get(rawToken);
+      expect(rawRow?.n).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("defaults: role=write, provision_vault=1, 7-day expiry", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const now = new Date("2026-06-04T00:00:00Z");
+      const { invite } = issueInvite(db, { createdBy: adminId, now: () => now });
+      expect(invite.role).toBe("write");
+      expect(invite.provisionVault).toBe(true);
+      expect(invite.vaultName).toBeNull();
+      const expiry = new Date(invite.expiresAt).getTime() - now.getTime();
+      expect(Math.round(expiry / 1000)).toBe(DEFAULT_INVITE_TTL_SECONDS);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("findInviteByRawToken", () => {
+  test("hashes then finds; unknown/tampered token → null", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const { rawToken } = issueInvite(db, { createdBy: adminId });
+      expect(findInviteByRawToken(db, rawToken)).not.toBeNull();
+      expect(findInviteByRawToken(db, `${rawToken}x`)).toBeNull();
+      expect(findInviteByRawToken(db, "totally-unknown")).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("assertInviteRedeemable", () => {
+  test("unknown token → InviteNotFoundError", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      expect(() => assertInviteRedeemable(db, "nope")).toThrow(InviteNotFoundError);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("expired token → InviteExpiredError", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const now = new Date("2026-06-04T00:00:00Z");
+      const { rawToken } = issueInvite(db, {
+        createdBy: adminId,
+        expiresInSeconds: 60,
+        now: () => now,
+      });
+      const later = new Date(now.getTime() + 61_000);
+      expect(() => assertInviteRedeemable(db, rawToken, later)).toThrow(InviteExpiredError);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("used token → InviteUsedError", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const { rawToken, invite } = issueInvite(db, { createdBy: adminId });
+      consumeInvite(db, invite.tokenHash, adminId);
+      expect(() => assertInviteRedeemable(db, rawToken)).toThrow(InviteUsedError);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("revoked token → InviteRevokedError", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const { rawToken, invite } = issueInvite(db, { createdBy: adminId });
+      revokeInvite(db, invite.tokenHash);
+      expect(() => assertInviteRedeemable(db, rawToken)).toThrow(InviteRevokedError);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("consumeInvite — single-use", () => {
+  test("first consume wins; second returns false (replay rejected)", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const { invite } = issueInvite(db, { createdBy: adminId });
+      expect(consumeInvite(db, invite.tokenHash, adminId)).toBe(true);
+      expect(consumeInvite(db, invite.tokenHash, adminId)).toBe(false);
+      const fresh = db
+        .query<{ used_at: string | null; redeemed_user_id: string | null }, [string]>(
+          "SELECT used_at, redeemed_user_id FROM invites WHERE token = ?",
+        )
+        .get(invite.tokenHash);
+      expect(fresh?.used_at).not.toBeNull();
+      expect(fresh?.redeemed_user_id).toBe(adminId);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("revokeInvite", () => {
+  test("revokes a pending invite; refuses one already used", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const a = issueInvite(db, { createdBy: adminId });
+      expect(revokeInvite(db, a.invite.tokenHash)).toBe(true);
+      expect(revokeInvite(db, a.invite.tokenHash)).toBe(false); // already revoked
+
+      const b = issueInvite(db, { createdBy: adminId });
+      consumeInvite(db, b.invite.tokenHash, adminId);
+      expect(revokeInvite(db, b.invite.tokenHash)).toBe(false); // already used
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("inviteStatus / listInvites", () => {
+  test("derives pending / redeemed / expired / revoked", async () => {
+    const { db, adminId, cleanup } = await makeDb();
+    try {
+      const now = new Date("2026-06-04T00:00:00Z");
+      const pending = issueInvite(db, { createdBy: adminId, now: () => now });
+      const redeemed = issueInvite(db, { createdBy: adminId, now: () => now });
+      consumeInvite(db, redeemed.invite.tokenHash, adminId, now);
+      const revoked = issueInvite(db, { createdBy: adminId, now: () => now });
+      revokeInvite(db, revoked.invite.tokenHash, now);
+      const expired = issueInvite(db, {
+        createdBy: adminId,
+        expiresInSeconds: 10,
+        now: () => now,
+      });
+
+      const later = new Date(now.getTime() + 60_000);
+      // `consumeInvite`/`revokeInvite` mutate the DB row, not the in-memory
+      // snapshot — re-read each to assert status off persisted state.
+      const fresh = (raw: string) => findInviteByRawToken(db, raw);
+      expect(inviteStatus(fresh(pending.rawToken)!, later)).toBe("pending");
+      expect(inviteStatus(fresh(redeemed.rawToken)!, later)).toBe("redeemed");
+      expect(inviteStatus(fresh(revoked.rawToken)!, later)).toBe("revoked");
+      expect(inviteStatus(fresh(expired.rawToken)!, later)).toBe("expired");
+
+      const list = listInvites(db, later);
+      expect(list.length).toBe(4);
+      // listInvites annotates status + newest-first ordering.
+      const statuses = new Set(list.map((i) => i.status));
+      expect(statuses).toEqual(new Set(["pending", "redeemed", "revoked", "expired"]));
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/launchctl-guard.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, test } from "bun:test";
+import { defaultHubUnitDeps } from "../hub-unit.ts";
+import {
+  guardServiceManagerCommand,
+  isDestructiveServiceManagerCommand,
+} from "../launchctl-guard.ts";
+import { defaultManagedUnitDeps } from "../managed-unit.ts";
+
+// ===========================================================================
+// hub#535 — test-isolation boundary guard for destructive service-manager verbs.
+//
+// THE OUTAGE: a hub test on a LIVE machine reached the PRODUCTION default Runner
+// (`Bun.spawnSync(["launchctl","bootout","computer.parachute.hub"])`) — a daemon-
+// op helper was called with the default `deps`, not an injected fake — and
+// `launchctl bootout`'d the real running hub daemon, taking the whole ecosystem
+// down. The guard makes that impossible: under a test runner the default Runner
+// REFUSES destructive launchd/systemd verbs and THROWS, so a test that forgets to
+// inject a fake `run` fails loudly instead of nuking the operator's daemon.
+//
+// These tests run under `bun test` ⇒ NODE_ENV === "test" ⇒ the guard is ACTIVE.
+// ===========================================================================
+
+describe("isDestructiveServiceManagerCommand — classification", () => {
+  test("launchd destructive verbs are flagged", () => {
+    for (const verb of ["bootout", "bootstrap", "load", "unload", "kickstart"]) {
+      expect(
+        isDestructiveServiceManagerCommand(["launchctl", verb, "gui/501/computer.parachute.hub"]),
+      ).toBe(true);
+    }
+  });
+
+  test("launchd read-only verbs are NOT flagged", () => {
+    // `print` (state descriptor) and `list` are diagnostics — tests legitimately
+    // exercise these through the default deps, so the guard must leave them alone.
+    expect(
+      isDestructiveServiceManagerCommand(["launchctl", "print", "gui/501/computer.parachute.hub"]),
+    ).toBe(false);
+    expect(isDestructiveServiceManagerCommand(["launchctl", "list"])).toBe(false);
+  });
+
+  test("systemd destructive verbs are flagged (incl. --user / --now flags skipped)", () => {
+    expect(
+      isDestructiveServiceManagerCommand([
+        "systemctl",
+        "--user",
+        "enable",
+        "--now",
+        "parachute-hub.service",
+      ]),
+    ).toBe(true);
+    expect(
+      isDestructiveServiceManagerCommand([
+        "systemctl",
+        "disable",
+        "--now",
+        "parachute-vault.service",
+      ]),
+    ).toBe(true);
+    for (const verb of ["start", "stop", "restart", "daemon-reload", "mask"]) {
+      expect(
+        isDestructiveServiceManagerCommand(["systemctl", "--user", verb, "parachute-hub.service"]),
+      ).toBe(true);
+    }
+  });
+
+  test("systemd read-only verbs are NOT flagged", () => {
+    expect(
+      isDestructiveServiceManagerCommand([
+        "systemctl",
+        "--user",
+        "is-active",
+        "parachute-hub.service",
+      ]),
+    ).toBe(false);
+    expect(
+      isDestructiveServiceManagerCommand(["systemctl", "is-enabled", "parachute-vault.service"]),
+    ).toBe(false);
+  });
+
+  test("unrelated tools / loginctl / journalctl are NOT flagged", () => {
+    expect(isDestructiveServiceManagerCommand(["loginctl", "enable-linger", "op"])).toBe(false);
+    expect(
+      isDestructiveServiceManagerCommand(["journalctl", "--user", "-u", "parachute-hub.service"]),
+    ).toBe(false);
+    expect(isDestructiveServiceManagerCommand(["ps", "-o", "command=", "-p", "123"])).toBe(false);
+    expect(isDestructiveServiceManagerCommand([])).toBe(false);
+  });
+
+  test("absolute-path tool is still classified (basename match)", () => {
+    // Defense in depth: in this repo every invocation is bare, but if one ever
+    // used an absolute path the guard must still recognize it.
+    expect(
+      isDestructiveServiceManagerCommand([
+        "/bin/launchctl",
+        "bootout",
+        "gui/0/computer.parachute.hub",
+      ]),
+    ).toBe(true);
+  });
+});
+
+describe("guardServiceManagerCommand — throws under a test runner", () => {
+  test("throws on launchctl bootout (the exact outage command)", () => {
+    expect(() =>
+      guardServiceManagerCommand(["launchctl", "bootout", "gui/501/computer.parachute.hub"]),
+    ).toThrow(/launchctl-guard.*Refusing to run a destructive service-manager command/s);
+  });
+
+  test("does NOT throw on a read-only command", () => {
+    expect(() =>
+      guardServiceManagerCommand(["launchctl", "print", "gui/501/computer.parachute.hub"]),
+    ).not.toThrow();
+  });
+
+  test("opt-out env var (PARACHUTE_ALLOW_REAL_LAUNCHCTL) lets a deliberate call through", () => {
+    const prev = process.env.PARACHUTE_ALLOW_REAL_LAUNCHCTL;
+    process.env.PARACHUTE_ALLOW_REAL_LAUNCHCTL = "1";
+    try {
+      expect(() =>
+        guardServiceManagerCommand(["launchctl", "bootout", "gui/501/computer.parachute.SAFE"]),
+      ).not.toThrow();
+    } finally {
+      // Restore — `= undefined` to clear (the codebase convention; biome flags
+      // `delete process.env.X` as a perf foot-gun. See hub-settings.test.ts).
+      if (prev === undefined) process.env.PARACHUTE_ALLOW_REAL_LAUNCHCTL = undefined;
+      else process.env.PARACHUTE_ALLOW_REAL_LAUNCHCTL = prev;
+    }
+  });
+});
+
+// ===========================================================================
+// THE REGRESSION TEST (hub#535 layer c): the PRODUCTION default deps — the ones a
+// daemon-op helper falls back to when a test forgets to inject a fake `run` — must
+// REFUSE the real launchctl under a test runner. If the guard regresses (someone
+// removes it from `defaultManagedUnitDeps.run`), these flip from "throws" to
+// "spawns the real launchctl" and this test fails — BEFORE the change can reach a
+// machine and bootout the live daemon.
+//
+// We assert via `defaultManagedUnitDeps.run` directly (the single chokepoint every
+// bare-launchctl call in the codebase routes through) and via `defaultHubUnitDeps`
+// (which spreads the same `run`), proving both seams are protected.
+// ===========================================================================
+describe("default Runner refuses real launchctl under test (regression — hub#535)", () => {
+  test("defaultManagedUnitDeps.run THROWS on `launchctl bootout` instead of spawning", () => {
+    expect(() =>
+      defaultManagedUnitDeps.run(["launchctl", "bootout", "gui/501/computer.parachute.hub"]),
+    ).toThrow(/launchctl-guard/);
+  });
+
+  test("defaultHubUnitDeps.run (inherits the guard via spread) THROWS on `launchctl kickstart`", () => {
+    expect(() =>
+      defaultHubUnitDeps.run(["launchctl", "kickstart", "-k", "gui/501/computer.parachute.hub"]),
+    ).toThrow(/launchctl-guard/);
+  });
+
+  test("default deps THROW on `systemctl --user disable --now` too", () => {
+    expect(() =>
+      defaultManagedUnitDeps.run([
+        "systemctl",
+        "--user",
+        "disable",
+        "--now",
+        "parachute-vault.service",
+      ]),
+    ).toThrow(/launchctl-guard/);
+  });
+
+  test("default deps still RUN a read-only `launchctl print` (guard is verb-scoped, not a blanket block)", () => {
+    // The property under test: the GUARD does not block a read-only `print`
+    // (verb-scoped, not a blanket launchctl block) — so it never throws the
+    // `/launchctl-guard/` error for it. What happens AFTER the guard allows it
+    // through is environment-dependent and NOT under test:
+    //   - dev Mac under the test PATH shim → fake launchctl, exit 0, no throw
+    //   - real Mac → `launchctl print` of a non-loaded label returns nonzero, no throw
+    //   - Linux CI (no launchctl on PATH) → the spawn throws ENOENT
+    //     ("Executable not found in $PATH") — which is NOT the guard, and still
+    //     proves the guard let the command reach the spawn.
+    // So: assert only that no error thrown here is a GUARD throw.
+    try {
+      defaultManagedUnitDeps.run(["launchctl", "print", "gui/501/computer.parachute.NONEXISTENT"]);
+    } catch (err) {
+      expect(String((err as { message?: unknown })?.message ?? err)).not.toMatch(/launchctl-guard/);
+    }
+  });
+});

package/src/__tests__/migrate-cutover.test.ts

@@ -67,6 +67,7 @@ function fakeHubUnitDeps(): HubUnitDeps {
     readFile: () => undefined,
     exists: () => false,
     probeHealth: async () => false,
+    probeHealthVersion: async () => null,
     portListening: async () => false,
     sleep: async () => {},
   };
@@ -490,6 +491,12 @@ describe("teardownHubUnit (§7.4)", () => {
     const log: string[] = [];
     const res = teardownHubUnit({
       log: (l) => log.push(l),
+      // hub#535: inject fake deps so teardown NEVER falls back to the production
+      // default Runner (which would shell out to the real launchctl/systemctl).
+      // The injected fakes below mean no service-manager call is even attempted,
+      // but pinning `deps` removes the latent "forgot to inject → real bootout"
+      // hazard at the source.
+      deps: fakeHubUnitDeps(),
       remove: (opts): ManagedUnitRemoveResult => {
         removeArgs = { launchdLabel: opts.launchdLabel, systemdUnitName: opts.systemdUnitName };
         return { removed: true, messages: [opts.removedSystemdMessage(opts.systemdUnitName)] };
@@ -514,6 +521,9 @@ describe("teardownHubUnit (§7.4)", () => {
     const log: string[] = [];
     const res = teardownHubUnit({
       log: (l) => log.push(l),
+      // hub#535: inject fake deps (see the success-path test above) so this never
+      // reaches the production default Runner / real service manager.
+      deps: fakeHubUnitDeps(),
       remove: (): ManagedUnitRemoveResult => ({ removed: false, messages: [] }),
       disableStaleModuleUnits: () => {
         staleCalled = true;
@@ -526,6 +536,29 @@ describe("teardownHubUnit (§7.4)", () => {
     expect(staleCalled).toBe(true);
     expect(log.join("\n")).toContain("nothing to tear down");
   });
+
+  test("removal failure (removed:false WITH messages) → surfaces the reason, not 'nothing installed' (hub#534)", () => {
+    // A future / defensive `removeManagedUnit` that returns removed:false WITH a
+    // failure reason must NOT be reported as the benign "nothing was installed"
+    // line — the operator (and the CLI's non-zero exit) need the real detail.
+    const log: string[] = [];
+    const res = teardownHubUnit({
+      log: (l) => log.push(l),
+      deps: fakeHubUnitDeps(),
+      remove: (): ManagedUnitRemoveResult => ({
+        removed: false,
+        messages: ["systemctl disable failed: permission denied"],
+      }),
+      disableStaleModuleUnits: () => ({ actions: [] }),
+    });
+    expect(res.removed).toBe(false);
+    expect(res.messages).toEqual(["systemctl disable failed: permission denied"]);
+    const out = log.join("\n");
+    expect(out).toContain("did not complete");
+    expect(out).toContain("permission denied");
+    // Must NOT claim nothing was installed when there was a real failure.
+    expect(out).not.toContain("nothing to tear down");
+  });
 });
 
 // ===========================================================================

package/src/__tests__/module-ops-client.test.ts

@@ -183,6 +183,27 @@ describe("driveModuleOp — auth + transport", () => {
     expect(calls).toHaveLength(0);
   });
 
+  test("non-2xx with NO error body → fallback names the HTTP status, not bare 'request failed' (hub#536)", async () => {
+    h = await makeHarnessWithToken();
+    // An empty `{}` body models a handler crash that produced a bodyless 500
+    // (pre-fix this collapsed to an unactionable "request failed").
+    const { fetch: f } = fakeFetch([{ status: 500, body: {} }]);
+    let err: unknown;
+    try {
+      await driveModuleOp("vault", "start", {
+        db: h.db,
+        issuer: ISSUER,
+        configDir: h.dir,
+        fetch: f,
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(ModuleOpHttpError);
+    expect((err as ModuleOpHttpError).status).toBe(500);
+    expect((err as Error).message).toContain("hub returned HTTP 500 with no error detail");
+  });
+
   test("non-2xx hub response → ModuleOpHttpError carrying status + code", async () => {
     h = await makeHarnessWithToken();
     const { fetch: f } = fakeFetch([
@@ -471,6 +492,53 @@ describe("fetchModuleStates", () => {
     expect((scribe?.supervisor_start_error as { binary?: string } | null)?.binary).toBe("scribe");
   });
 
+  test("parses the `supervised` array — non-curated modules' run-state (hub#539)", async () => {
+    h = await makeHarnessWithToken();
+    const { fetch: f } = fakeFetch([
+      {
+        status: 200,
+        body: {
+          supervisor_available: true,
+          modules: [], // curated catalog can omit a running module (e.g. surface)…
+          supervised: [
+            {
+              short: "surface",
+              installed: true,
+              installed_version: null,
+              supervisor_status: "running",
+              pid: 8739,
+              supervisor_start_error: null,
+            },
+          ],
+        },
+      },
+    ]);
+    const result = await fetchModuleStates({
+      db: h.db,
+      issuer: ISSUER,
+      configDir: h.dir,
+      fetch: f,
+    });
+    expect(result.supervised).toHaveLength(1);
+    const surf = result.supervised?.find((m) => m.short === "surface");
+    expect(surf?.supervisor_status).toBe("running");
+    expect(surf?.pid).toBe(8739);
+  });
+
+  test("omitted `supervised` (older hub) parses to [] — hub#539 forward-compat", async () => {
+    h = await makeHarnessWithToken();
+    const { fetch: f } = fakeFetch([
+      { status: 200, body: { supervisor_available: true, modules: [] } },
+    ]);
+    const result = await fetchModuleStates({
+      db: h.db,
+      issuer: ISSUER,
+      configDir: h.dir,
+      fetch: f,
+    });
+    expect(result.supervised).toEqual([]);
+  });
+
   test("no operator token → NoOperatorTokenError before any fetch", async () => {
     h = await makeHarnessNoToken();
     const { fetch: f, calls } = fakeFetch([{ status: 200, body: { modules: [] } }]);

package/src/__tests__/scope-explanations.test.ts

@@ -4,6 +4,7 @@ import {
   NON_REQUESTABLE_SCOPES,
   SCOPE_EXPLANATIONS,
   explainScope,
+  isNonRequestableScope,
   isRequestableScope,
   isWellFormedOrNonVaultScope,
   scopeIsAdmin,
@@ -162,6 +163,21 @@ describe("isRequestableScope", () => {
     expect(isRequestableScope("vault:default:read")).toBe(true);
     expect(isRequestableScope("vault:work:write")).toBe(true);
   });
+
+  // Item C — case-insensitive guard. A casing variant of a host-level scope
+  // must NOT slip past the exact-string membership check as "requestable."
+  test("uppercase / mixed-case host scopes are non-requestable (item C)", () => {
+    expect(isRequestableScope("PARACHUTE:HOST:AUTH")).toBe(false);
+    expect(isRequestableScope("Parachute:Host:Admin")).toBe(false);
+    expect(isRequestableScope("parachute:HOST:vault")).toBe(false);
+    // And the direct predicate agrees.
+    expect(isNonRequestableScope("PARACHUTE:HOST:AUTH")).toBe(true);
+    expect(isNonRequestableScope("parachute:Host:Install")).toBe(true);
+    // Canonical lowercase still works unchanged.
+    expect(isNonRequestableScope("parachute:host:auth")).toBe(true);
+    // A non-host scope (even uppercased) stays requestable.
+    expect(isNonRequestableScope("HUB:ADMIN")).toBe(false);
+  });
 });
 
 // Mint-time shape guard (defensive hygiene, audit 2026-05-28). Rejects only the

package/src/__tests__/serve-boot.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { bootSupervisedModules } from "../commands/serve-boot.ts";
+import { bootSupervisedModules, buildModuleSpawnRequest } from "../commands/serve-boot.ts";
 import { type ServiceEntry, writeManifest } from "../services-manifest.ts";
 import { type SpawnRequest, type SupervisedProc, Supervisor } from "../supervisor.ts";
 
@@ -164,6 +164,79 @@ describe("bootSupervisedModules", () => {
     expect(recorder.calls[0]?.env?.SCRIBE_URL).toBe("http://127.0.0.1:3200");
   });
 
+  test("services.json entry.port wins over a stale .env PORT (hub#537)", async () => {
+    // Pre-hub#206 installs wrote `PORT=` into the per-service .env. A leftover
+    // PORT there that disagrees with services.json (e.g. scribe's stale 1944 vs
+    // canonical 1943) must NOT shadow entry.port — otherwise the supervisor
+    // injects + probes the wrong port and records a false `started_but_unbound`.
+    writeManifest({ services: [VAULT_ENTRY] }, h.manifestPath);
+    mkdirSync(join(h.dir, "vault"), { recursive: true });
+    writeFileSync(join(h.dir, "vault", ".env"), "PORT=1944\nSCRIBE_AUTH_TOKEN=secret-token\n");
+
+    const recorder = makeRecorder();
+    const sup = new Supervisor({ spawnFn: recorder.spawn });
+
+    await bootSupervisedModules(sup, {
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+    });
+
+    // entry.port (1940) wins; the stale .env PORT is dropped. Other .env
+    // values still merge.
+    expect(recorder.calls[0]?.env?.PORT).toBe("1940");
+    expect(recorder.calls[0]?.env?.SCRIBE_AUTH_TOKEN).toBe("secret-token");
+  });
+
+  test("extraEnv PORT still wins over entry.port (layer 4 — test seam / first-boot)", () => {
+    // Dropping a stale .env PORT must not affect the documented layer-4 override:
+    // an explicit `opts.extraEnv.PORT` (programmatic, not a stale on-disk file)
+    // still wins last.
+    const req = buildModuleSpawnRequest("vault", VAULT_ENTRY, ["parachute-vault", "serve"], {
+      configDir: h.dir,
+      extraEnv: { PORT: "9999" },
+    });
+    expect(req.env?.PORT).toBe("9999");
+  });
+
+  test("injects an enriched PATH carrying the inherited process PATH (hub launchd-PATH fix)", () => {
+    // The hub unit bakes a minimal PATH and Bun.spawn defaults to empty env, so
+    // without this injection the child can't find operator tools (scribe's
+    // parakeet-mlx / ffmpeg). The req must carry a PATH, and it must preserve
+    // whatever the hub process inherited.
+    const req = buildModuleSpawnRequest("vault", VAULT_ENTRY, ["parachute-vault", "serve"], {
+      configDir: h.dir,
+    });
+    expect(req.env?.PATH).toBeDefined();
+    expect(req.env?.PATH?.length).toBeGreaterThan(0);
+    // Every entry the hub inherited is still present (enrichment appends, never
+    // drops). process.env.PATH is always set in the test runner.
+    for (const entry of (process.env.PATH ?? "").split(":").filter((e) => e.length > 0)) {
+      expect(req.env?.PATH?.split(":")).toContain(entry);
+    }
+  });
+
+  test("a per-service .env PATH wins over the injected enrichment (operator intent)", () => {
+    mkdirSync(join(h.dir, "vault"), { recursive: true });
+    writeFileSync(join(h.dir, "vault", ".env"), "PATH=/operator/pinned/bin\n");
+    const req = buildModuleSpawnRequest("vault", VAULT_ENTRY, ["parachute-vault", "serve"], {
+      configDir: h.dir,
+    });
+    expect(req.env?.PATH).toBe("/operator/pinned/bin");
+  });
+
+  test("the API-start path (buildModuleSpawnRequest reuse) also carries the enriched PATH", () => {
+    // handleStart() in api-modules-ops.ts routes through buildModuleSpawnRequest,
+    // so the /api/modules/:short/start path inherits the same PATH fix. Assert
+    // the shared builder is the single source — extraEnv (the start handler's
+    // spawnEnv seam) does NOT clobber PATH unless it explicitly sets one.
+    const req = buildModuleSpawnRequest("vault", VAULT_ENTRY, ["parachute-vault", "serve"], {
+      configDir: h.dir,
+      extraEnv: { SOME_FLAG: "1" },
+    });
+    expect(req.env?.PATH).toBeDefined();
+    expect(req.env?.SOME_FLAG).toBe("1");
+  });
+
   test("hubOrigin wins over a stale .env entry on collision", async () => {
     writeManifest({ services: [VAULT_ENTRY] }, h.manifestPath);
     mkdirSync(join(h.dir, "vault"), { recursive: true });