@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/__tests__/api-modules-ops.test.ts

@@ -323,6 +323,13 @@ describe("POST /api/modules/:short/install", () => {
     expect(manifest.services.some((s) => s.name === "parachute-vault")).toBe(true);
     // Supervisor was handed the spawn.
     expect(spawns.find((s) => s.short === "vault")?.cmd).toEqual(["parachute-vault", "serve"]);
+    // The install-time spawn path (spawnSupervised) injects the enriched PATH
+    // so a module installed via /admin/modules can find operator tools (scribe's
+    // parakeet-mlx / ffmpeg) — same fix as the serve-boot path, second spawn
+    // site (hub launchd-PATH regression). It must carry the inherited PATH.
+    const vaultEnv = spawns.find((s) => s.short === "vault")?.env;
+    expect(vaultEnv?.PATH).toBeDefined();
+    expect(vaultEnv?.PATH?.length).toBeGreaterThan(0);
   });
 
   test("idempotent: already-installed + running returns succeeded immediately", async () => {
@@ -842,6 +849,31 @@ describe("POST /api/modules/:short/start", () => {
     expect(res.status).toBe(403);
   });
 
+  test("supervisor.start throw → structured 500 module_op_failed, not a naked 500 (hub#536)", async () => {
+    seedVault();
+    // Models the hub#536 wedge: Bun.spawn throwing because the module's
+    // installDir/cwd no longer exists (NOT a missing binary — the preflight
+    // + rethrowIfMissing nets don't catch it, so it propagates out of
+    // supervisor.start). Pre-fix this escaped the handler as a bodyless 500
+    // and the CLI showed an opaque "request failed".
+    const supervisor = new Supervisor({
+      spawnFn: () => {
+        throw new Error("simulated spawn failure: cwd /gone/parachute-app does not exist");
+      },
+    });
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleStart(
+      postReq("/api/modules/vault/start", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string; error_description: string };
+    expect(body.error).toBe("module_op_failed");
+    expect(body.error_description).toContain("vault start failed");
+    expect(body.error_description).toContain("cwd /gone/parachute-app does not exist");
+  });
+
   test("pure supervisor.start of an installed module — NOT install (no bun add)", async () => {
     seedVault();
     const { supervisor, spawns } = makeIdleSupervisor();
@@ -1096,7 +1128,44 @@ describe("POST /api/modules/:short/restart", () => {
   });
   afterEach(() => h.cleanup());
 
-  test("404 not_supervised when module isn't running", async () => {
+  /** Seed a minimal installed vault row (in services.json). */
+  function seedVault(port = 1940): void {
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.0.0-linked",
+      },
+    ]);
+  }
+
+  test("400 not_installed when the module isn't in services.json", async () => {
+    // restart rebuilds the spawn req from services.json (hub#532), so a
+    // missing row is a `not_installed` 400 (mirrors `start`) — before the
+    // supervisor is even consulted.
+    const { supervisor } = makeIdleSupervisor();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleRestart(
+      postReq("/api/modules/vault/restart", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run: async () => 0,
+      },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("not_installed");
+  });
+
+  test("404 not_supervised when installed but not currently running", async () => {
+    seedVault();
     const { supervisor } = makeIdleSupervisor();
     const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
     const res = await handleRestart(
@@ -1117,6 +1186,7 @@ describe("POST /api/modules/:short/restart", () => {
   });
 
   test("returns new state on success", async () => {
+    seedVault();
     const { supervisor } = makeIdleSupervisor();
     await supervisor.start({ short: "vault", cmd: ["parachute-vault", "serve"] });
 
@@ -1140,6 +1210,122 @@ describe("POST /api/modules/:short/restart", () => {
     // on timing — either is acceptable here as long as it's not crashed/stopped.
     expect(["restarting", "running", "starting"]).toContain(body.state.status);
   });
+
+  test("re-injects the CURRENT hub origin on restart (hub#532)", async () => {
+    // The core hub#532 fix: a module first started under one issuer, then
+    // restarted after the canonical origin changed (e.g. post-expose), must
+    // re-spawn with the NEW PARACHUTE_HUB_ORIGIN — not replay the stale
+    // first-start snapshot. We drive the supervisor directly to control the
+    // first-start env, then restart through the handler with a different
+    // `deps.issuer` and assert the recorded spawn carries the new origin.
+    seedVault(1940);
+    const { supervisor, spawns } = makeIdleSupervisor();
+    // First start with the OLD origin baked in (as boot would have).
+    await supervisor.start({
+      short: "vault",
+      cmd: ["parachute-vault", "serve"],
+      env: { PORT: "1940", PARACHUTE_HUB_ORIGIN: "https://old.example" },
+    });
+    const spawnsBefore = spawns.length;
+
+    const NEW_ORIGIN = "https://new.example";
+    // The bearer was minted at the prior (loopback) ISSUER; the canonical
+    // origin has since moved to NEW_ORIGIN. `knownIssuers` accepts the older
+    // bearer iss while `deps.issuer` is the current canonical origin — exactly
+    // the post-expose scenario hub#532 describes.
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleRestart(
+      postReq("/api/modules/vault/restart", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: NEW_ORIGIN,
+        knownIssuers: [ISSUER, NEW_ORIGIN],
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run: async () => 0,
+      },
+    );
+    expect(res.status).toBe(200);
+    // A fresh spawn happened, and it carries the NEW origin (rebuilt from the
+    // live deps.issuer), not the stale one from first start.
+    const reSpawn = spawns[spawnsBefore];
+    expect(reSpawn?.env?.PARACHUTE_HUB_ORIGIN).toBe(NEW_ORIGIN);
+    expect(reSpawn?.env?.PORT).toBe("1940");
+  });
+
+  test("crash-restart after a restart reuses the REFRESHED req (hub#532)", async () => {
+    // The refreshed SpawnRequest must become the supervisor entry's `req` so
+    // a SUBSEQUENT crash-restart (handleExit → spawnAndWatch, which replays
+    // `entry.req`) also carries the current env — not the original snapshot.
+    seedVault(1940);
+    // Controllable supervisor: spawns record env; each fake exposes a `crash()`
+    // resolving `exited` with code 1 (a crash, not an operator stop). `kill()`
+    // (driven by the injected group-aware `killFn`) resolves with 0 so the
+    // handler's restart-stop completes promptly. Distinct codes let us crash a
+    // specific child without tripping the stop path.
+    const spawns: SpawnRequest[] = [];
+    const procs: Array<{ pid: number; crash: () => void; kill: () => void }> = [];
+    let nextPid = 8000;
+    const spawnFn = (req: SpawnRequest): SupervisedProc => {
+      spawns.push(req);
+      const pid = nextPid++;
+      let resolveExit!: (c: number | null) => void;
+      const exited = new Promise<number | null>((r) => {
+        resolveExit = r;
+      });
+      const proc = {
+        pid,
+        exited,
+        stdout: null,
+        stderr: null,
+        kill: () => resolveExit(0),
+      };
+      procs.push({ pid, crash: () => resolveExit(1), kill: proc.kill });
+      return proc;
+    };
+    const killFn = (pid: number): void => {
+      procs.find((p) => p.pid === Math.abs(pid))?.kill();
+    };
+    const supervisor = new Supervisor({ spawnFn, killFn, restartDelayMs: 1, startReadyMs: 0 });
+
+    // First start with the OLD origin.
+    await supervisor.start({
+      short: "vault",
+      cmd: ["parachute-vault", "serve"],
+      env: { PORT: "1940", PARACHUTE_HUB_ORIGIN: "https://old.example" },
+    });
+
+    const NEW_ORIGIN = "https://new.example";
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    await handleRestart(
+      postReq("/api/modules/vault/restart", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: NEW_ORIGIN,
+        knownIssuers: [ISSUER, NEW_ORIGIN],
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run: async () => 0,
+      },
+    );
+    // The restart re-spawn is the most recent — confirm the NEW origin landed.
+    const restartSpawnIdx = spawns.length - 1;
+    expect(spawns[restartSpawnIdx]?.env?.PARACHUTE_HUB_ORIGIN).toBe(NEW_ORIGIN);
+
+    // Crash the restart-spawned child → the supervisor's crash-restart replays
+    // entry.req (which `start` stored from the refreshed req).
+    procs[restartSpawnIdx]?.crash();
+    // Wait for the crash watcher's restartDelay + respawn.
+    await new Promise((r) => setTimeout(r, 40));
+    expect(spawns.length).toBeGreaterThan(restartSpawnIdx + 1);
+    const crashRespawn = spawns[spawns.length - 1];
+    // The crash-restart inherited the REFRESHED req → still the new origin.
+    expect(crashRespawn?.env?.PARACHUTE_HUB_ORIGIN).toBe(NEW_ORIGIN);
+  });
 });
 
 describe("POST /api/modules/:short/upgrade", () => {

package/src/__tests__/api-modules.test.ts

@@ -317,6 +317,45 @@ describe("GET /api/modules", () => {
     expect(shorts).not.toContain("surface");
   });
 
+  test("non-curated supervised modules appear in `supervised` (not `modules`) — hub#539", async () => {
+    // surface (the UI host) is supervised but not curated. Its run-state must
+    // surface in `supervised` so `parachute status` reads it `active`, while it
+    // stays OUT of the curated `modules` catalog (which drives the install UI).
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.4.5",
+      },
+    ]);
+    const { supervisor } = makeIdleSupervisor();
+    await supervisor.start({ short: "vault", cmd: ["parachute-vault", "serve"] });
+    await supervisor.start({ short: "surface", cmd: ["parachute-surface", "serve"] });
+
+    const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      supervisor,
+      fetchLatestVersion: async () => null,
+    });
+    const body = (await res.json()) as {
+      modules: Array<{ short: string }>;
+      supervised: Array<{ short: string; supervisor_status: string | null; pid: number | null }>;
+    };
+    // surface stays out of the curated catalog…
+    expect(body.modules.map((m) => m.short)).not.toContain("surface");
+    // …but its run-state is in `supervised`, marked running with a pid.
+    const surf = body.supervised.find((m) => m.short === "surface");
+    expect(surf?.supervisor_status).toBe("running");
+    expect(typeof surf?.pid).toBe("number");
+    // Curated modules appear in `supervised` too (consumers dedupe by short).
+    expect(body.supervised.find((m) => m.short === "vault")?.supervisor_status).toBe("running");
+  });
+
   test("surfaces installed_version from services.json", async () => {
     writeManifest(h.manifestPath, [
       {
@@ -716,10 +755,7 @@ describe("GET /api/modules", () => {
     // Second back-to-back request must not re-hit the registry. The
     // UI may poll this endpoint; we don't want it to slam npm.
     let calls = 0;
-    const probe = async (
-      _pkg: string,
-      _channel: "latest" | "rc",
-    ): Promise<string | null> => {
+    const probe = async (_pkg: string, _channel: "latest" | "rc"): Promise<string | null> => {
       calls++;
       return "0.5.0";
     };

package/src/__tests__/api-settings-hub-origin.test.ts

@@ -83,6 +83,11 @@ function putReq(body: unknown, headers: Record<string, string> = {}): Request {
   });
 }
 
+// Stub "no exposure recorded" so resolveIssuer / resolveIssuerSource don't
+// pick up the host's real ~/.parachute/expose-state.json (the #531 expose
+// tier would otherwise shadow the request-origin source these tests assert).
+const noExpose = (): string | undefined => undefined;
+
 function deps(
   h: Harness,
   overrides: Partial<Parameters<typeof handleApiSettingsHubOrigin>[1]> = {},
@@ -90,8 +95,8 @@ function deps(
   return {
     db: h.db,
     issuer: ISSUER,
-    resolvedIssuer: resolveIssuer(getReq(), h.db, undefined),
-    resolvedSource: resolveIssuerSource(h.db, undefined),
+    resolvedIssuer: resolveIssuer(getReq(), h.db, undefined, noExpose),
+    resolvedSource: resolveIssuerSource(h.db, undefined, noExpose),
     ...overrides,
   };
 }
@@ -414,8 +419,8 @@ describe("change takes effect on the next request (no restart needed)", () => {
     const g1 = await handleApiSettingsHubOrigin(getReq({ authorization: `Bearer ${bearer}` }), {
       db: h.db,
       issuer: ISSUER,
-      resolvedIssuer: resolveIssuer(getReq(), h.db, undefined),
-      resolvedSource: resolveIssuerSource(h.db, undefined),
+      resolvedIssuer: resolveIssuer(getReq(), h.db, undefined, noExpose),
+      resolvedSource: resolveIssuerSource(h.db, undefined, noExpose),
     });
     const b1 = (await g1.json()) as { source: string; resolved_issuer: string };
     expect(b1.source).toBe("request");
@@ -426,8 +431,8 @@ describe("change takes effect on the next request (no restart needed)", () => {
       {
         db: h.db,
         issuer: ISSUER,
-        resolvedIssuer: resolveIssuer(putReq({}), h.db, undefined),
-        resolvedSource: resolveIssuerSource(h.db, undefined),
+        resolvedIssuer: resolveIssuer(putReq({}), h.db, undefined, noExpose),
+        resolvedSource: resolveIssuerSource(h.db, undefined, noExpose),
       },
     );
     expect(p.status).toBe(200);
@@ -437,8 +442,8 @@ describe("change takes effect on the next request (no restart needed)", () => {
     const g2 = await handleApiSettingsHubOrigin(getReq({ authorization: `Bearer ${bearer}` }), {
       db: h.db,
       issuer: ISSUER,
-      resolvedIssuer: resolveIssuer(getReq(), h.db, undefined),
-      resolvedSource: resolveIssuerSource(h.db, undefined),
+      resolvedIssuer: resolveIssuer(getReq(), h.db, undefined, noExpose),
+      resolvedSource: resolveIssuerSource(h.db, undefined, noExpose),
     });
     const b2 = (await g2.json()) as {
       hub_origin: string | null;

package/src/__tests__/auto-wire.test.ts

@@ -2,7 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { SCRIBE_AUTH_ENV_KEY, SCRIBE_URL_ENV_KEY, autoWireScribeAuth } from "../auto-wire.ts";
+import {
+  SCRIBE_AUTH_ENV_KEY,
+  SCRIBE_URL_ENV_KEY,
+  autoWireScribeAuth,
+  selfHealScribeAuth,
+} from "../auto-wire.ts";
 import { writePid } from "../process-state.ts";
 
 function makeHarness(): { dir: string; cleanup: () => void } {
@@ -281,3 +286,98 @@ describe("autoWireScribeAuth", () => {
     }
   });
 });
+
+// Item H — serve-boot self-heal of scribe's auth token from vault's .env.
+describe("selfHealScribeAuth", () => {
+  function seedVaultToken(dir: string, token: string): void {
+    mkdirSync(join(dir, "vault"), { recursive: true });
+    writeFileSync(join(dir, "vault", ".env"), `${SCRIBE_AUTH_ENV_KEY}=${token}\n`);
+  }
+  function seedScribeConfig(dir: string, config: Record<string, unknown>): void {
+    mkdirSync(join(dir, "scribe"), { recursive: true });
+    writeFileSync(join(dir, "scribe", "config.json"), `${JSON.stringify(config, null, 2)}\n`);
+  }
+  function readScribeConfig(dir: string): Record<string, unknown> {
+    return JSON.parse(readFileSync(join(dir, "scribe", "config.json"), "utf8"));
+  }
+
+  test("vault .env has token + scribe config missing auth → self-heal writes it", () => {
+    const h = makeHarness();
+    try {
+      seedVaultToken(h.dir, "shared-secret-xyz");
+      seedScribeConfig(h.dir, { provider: "openai", model: "whisper-1" });
+      const logs: string[] = [];
+      const result = selfHealScribeAuth({ configDir: h.dir, log: (l) => logs.push(l) });
+      expect(result.healed).toBe(true);
+      const cfg = readScribeConfig(h.dir);
+      expect((cfg.auth as Record<string, unknown>).required_token).toBe("shared-secret-xyz");
+      // Other config keys preserved (merge-don't-clobber).
+      expect(cfg.provider).toBe("openai");
+      expect(cfg.model).toBe("whisper-1");
+      expect(logs.join("\n")).toMatch(/Self-healed scribe auth/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("scribe config wholly absent → self-heal creates it with the token", () => {
+    const h = makeHarness();
+    try {
+      seedVaultToken(h.dir, "shared-secret-xyz");
+      // No scribe/config.json at all.
+      const result = selfHealScribeAuth({ configDir: h.dir });
+      expect(result.healed).toBe(true);
+      expect((readScribeConfig(h.dir).auth as Record<string, unknown>).required_token).toBe(
+        "shared-secret-xyz",
+      );
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("scribe token mismatches vault → re-synced to vault's value", () => {
+    const h = makeHarness();
+    try {
+      seedVaultToken(h.dir, "vault-token-NEW");
+      seedScribeConfig(h.dir, { auth: { required_token: "stale-token-OLD" }, model: "x" });
+      const result = selfHealScribeAuth({ configDir: h.dir });
+      expect(result.healed).toBe(true);
+      const cfg = readScribeConfig(h.dir);
+      expect((cfg.auth as Record<string, unknown>).required_token).toBe("vault-token-NEW");
+      expect(cfg.model).toBe("x");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("already in sync → no-op (idempotent), config untouched", () => {
+    const h = makeHarness();
+    try {
+      seedVaultToken(h.dir, "same-token");
+      seedScribeConfig(h.dir, { auth: { required_token: "same-token" }, extra: "keep" });
+      const before = readFileSync(join(h.dir, "scribe", "config.json"), "utf8");
+      const result = selfHealScribeAuth({ configDir: h.dir });
+      expect(result.healed).toBe(false);
+      expect(result.reason).toBe("already-synced");
+      // Byte-identical — no rewrite.
+      expect(readFileSync(join(h.dir, "scribe", "config.json"), "utf8")).toBe(before);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("vault has no SCRIBE_AUTH_TOKEN → no-op (nothing to sync)", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "vault"), { recursive: true });
+      writeFileSync(join(h.dir, "vault", ".env"), "FOO=bar\n");
+      const result = selfHealScribeAuth({ configDir: h.dir });
+      expect(result.healed).toBe(false);
+      expect(result.reason).toBe("no-token");
+      // Scribe config not created.
+      expect(existsSync(join(h.dir, "scribe", "config.json"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/cli.test.ts

@@ -1,9 +1,10 @@
-import { describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { appendFileSync, cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 const CLI = join(import.meta.dir, "..", "cli.ts");
+const REPO_ROOT = join(import.meta.dir, "..", "..");
 
 async function runCli(
   args: string[],
@@ -277,6 +278,191 @@ describe("cli per-subcommand help", () => {
   });
 });
 
+describe("cli lazy-import isolation (feedback #9)", () => {
+  // Regression for the eager-import fragility: `cli.ts` used to import every
+  // command module at top-level, so a module that THREW at eval-time (the 0.6.2
+  // `migrate-cutover.ts` ReferenceError) aborted the entire CLI load — even
+  // `parachute --help` — because top-level import evaluation runs before
+  // `run()`'s try/catch is reached. Per-arm lazy `await import()` isolates a
+  // broken module to its own command.
+  //
+  // We exercise the REAL dispatcher: copy the live `src/` tree (plus the repo
+  // `package.json`, which `cli.ts` imports as `../package.json`) into a sandbox
+  // *inside the repo* so workspace `node_modules` resolution still works, then
+  // corrupt one command module so it throws at module-eval. `node_modules` is
+  // NOT copied — Bun walks up to the repo's. The corruption never touches the
+  // real source tree, so concurrent suites are unaffected.
+  let sandbox: string;
+  let sandboxCli: string;
+
+  beforeAll(() => {
+    // The sandbox lives INSIDE the repo (`<repo>/.tmp-cli-iso-*`) on purpose: it
+    // copies `src/` + `package.json` but NOT `node_modules`. The sandboxed CLI
+    // still resolves workspace packages (`@openparachute/depcheck`, etc.) by Bun
+    // walking up the directory tree to the **repo-root** `node_modules` — the same
+    // walk a nested file uses. So this suite REQUIRES `node_modules` installed at
+    // the repo root. CI must `bun install` before running it; a fresh worktree
+    // without an install will see `Cannot find module '@openparachute/...'`
+    // failures that are worktree-resolution artifacts, NOT a regression in the
+    // code under test. (A temp dir under `os.tmpdir()` would break this walk and
+    // also break `cli.ts`'s `../package.json` import, hence the in-repo sandbox.)
+    sandbox = mkdtempSync(join(REPO_ROOT, ".tmp-cli-iso-"));
+    cpSync(join(REPO_ROOT, "src"), join(sandbox, "src"), { recursive: true });
+    cpSync(join(REPO_ROOT, "package.json"), join(sandbox, "package.json"));
+    sandboxCli = join(sandbox, "src", "cli.ts");
+    // Append an unconditional throw so the module fails at eval. `migrate-cutover`
+    // is the canonical real-world case (the 0.6.2 bug) AND it's reachable by both
+    // eager paths the fix addresses: the direct `cli.ts` import and the transitive
+    // `cli.ts → lifecycle.ts → migrate-offer.ts → migrate-cutover.ts` chain.
+    appendFileSync(
+      join(sandbox, "src", "commands", "migrate-cutover.ts"),
+      '\nthrow new ReferenceError("boom: migrate-cutover failed at module eval");\n',
+    );
+  });
+
+  afterAll(() => {
+    if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  async function runSandbox(
+    args: string[],
+  ): Promise<{ code: number; stdout: string; stderr: string }> {
+    const proc = Bun.spawn([process.execPath, sandboxCli, ...args], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        HOME: "/tmp/parachute-hub-nonexistent-home",
+        PARACHUTE_HOME: "/tmp/parachute-hub-nonexistent-home",
+      },
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { code, stdout, stderr };
+  }
+
+  test("a command module that throws at eval does NOT abort --help", async () => {
+    const { code, stdout } = await runSandbox(["--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/parachute install/);
+  });
+
+  test("an unrelated command still dispatches when one module is broken", async () => {
+    // `status` doesn't touch migrate-cutover at all — it must still run to
+    // completion (exit 0) rather than dying at top-level import.
+    const { code } = await runSandbox(["status"]);
+    expect(code).toBe(0);
+  });
+
+  test("lifecycle commands survive the broken transitive path", async () => {
+    // `stop` pulls in `migrate-offer.ts` (for the §7.5 detect-and-offer), which
+    // used to EAGERLY import the broken `migrate-cutover.ts`. With the import now
+    // `import type` + lazy, `stop --help` must not crash.
+    const { code, stdout } = await runSandbox(["stop", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/parachute stop/);
+  });
+
+  test("the broken command itself exits 1 with a 'failed to load' message", async () => {
+    const { code, stderr } = await runSandbox(["migrate", "--to-supervised"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/parachute migrate: failed to load/);
+    expect(stderr).toMatch(/boom: migrate-cutover failed at module eval/);
+  });
+});
+
+// hub#534: `migrate --teardown` must surface teardownHubUnit's outcome — pre-fix
+// it ignored `removed` + `messages` and always exited 0, so a non-removal looked
+// like success. We exercise the REAL CLI arm via the in-repo sandbox (same shape
+// as the lazy-import suite above) so the arm's exit-code mapping runs end-to-end
+// without shelling out to real launchctl/systemctl: the sandboxed
+// `teardownHubUnit` is replaced with a stub keyed off an env var.
+describe("cli migrate --teardown exit-code policy (hub#534)", () => {
+  let sandbox: string;
+  let sandboxCli: string;
+
+  beforeAll(() => {
+    sandbox = mkdtempSync(join(REPO_ROOT, ".tmp-cli-teardown-"));
+    cpSync(join(REPO_ROOT, "src"), join(sandbox, "src"), { recursive: true });
+    cpSync(join(REPO_ROOT, "package.json"), join(sandbox, "package.json"));
+    sandboxCli = join(sandbox, "src", "cli.ts");
+    // Replace migrate-cutover.ts entirely with a minimal stub exporting only the
+    // `teardownHubUnit` the CLI arm calls. Its result is driven by
+    // `TEARDOWN_FAKE` so one rewrite covers all three outcomes. It logs the same
+    // human-facing lines the real function would (so the stdout assertions match
+    // real behavior), and the CLI owns the exit code.
+    writeFileSync(
+      join(sandbox, "src", "commands", "migrate-cutover.ts"),
+      [
+        "export function teardownHubUnit() {",
+        '  const mode = process.env.TEARDOWN_FAKE ?? "removed";',
+        '  if (mode === "removed") {',
+        '    console.log("Removed systemd unit parachute-hub.service — the hub no longer starts on boot.");',
+        "    return { removed: true, messages: [] };",
+        "  }",
+        '  if (mode === "failure") {',
+        '    console.log("Hub-unit teardown did not complete:");',
+        '    console.log("  systemctl disable failed: permission denied");',
+        '    return { removed: false, messages: ["systemctl disable failed: permission denied"] };',
+        "  }",
+        '  console.log("No hub unit was installed — nothing to tear down.");',
+        "  return { removed: false, messages: [] };",
+        "}",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  afterAll(() => {
+    if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  async function runTeardown(
+    fake: string,
+  ): Promise<{ code: number; stdout: string; stderr: string }> {
+    const proc = Bun.spawn([process.execPath, sandboxCli, "migrate", "--teardown"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        HOME: "/tmp/parachute-hub-nonexistent-home",
+        PARACHUTE_HOME: "/tmp/parachute-hub-nonexistent-home",
+        TEARDOWN_FAKE: fake,
+      },
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { code, stdout, stderr };
+  }
+
+  test("removed → exit 0 with the removal message", async () => {
+    const { code, stdout } = await runTeardown("removed");
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/Removed systemd unit/);
+  });
+
+  test("nothing installed → informational exit 0", async () => {
+    const { code, stdout } = await runTeardown("nothing");
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/nothing to tear down/);
+  });
+
+  test("removal failure (messages present) → exit 1, reason on stderr", async () => {
+    const { code, stdout, stderr } = await runTeardown("failure");
+    expect(code).toBe(1);
+    // The function logged the failure header to stdout; the CLI re-surfaces the
+    // detail on stderr so a script's `2>` capture sees the reason.
+    expect(stdout).toMatch(/did not complete/);
+    expect(stderr).toMatch(/permission denied/);
+  });
+});
+
 describe("cli friendly errors", () => {
   test("malformed services.json prints friendly error not stack trace", async () => {
     const dir = mkdtempSync(join(tmpdir(), "pcli-bad-"));