@openparachute/hub 0.6.3-rc.3 → 0.6.3

package/package.json

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

package/src/__tests__/account-home-ui.test.ts

@@ -175,6 +175,103 @@ describe("renderAccountHome", () => {
     expect(html).not.toContain('data-testid="mcp-connect"');
   });
 
+  test("get-started card — links to the two onboarding prompts, placed before the vault card", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    // The card renders with both onboarding-prompt links (mirrors the
+    // operator setup-wizard's starter-prompts section).
+    expect(html).toContain('data-testid="get-started-card"');
+    expect(html).toContain("Get started with your AI");
+    expect(html).toContain("https://parachute.computer/onboarding/vault-setup/");
+    expect(html).toContain("https://parachute.computer/onboarding/surface-build/");
+    expect(html).toContain('data-testid="starter-vault-setup"');
+    expect(html).toContain('data-testid="starter-surface-build"');
+    // External links open safely.
+    expect(html).toContain('rel="noopener"');
+    // Placed prominently — before the vault card in document order.
+    expect(html.indexOf('data-testid="get-started-card"')).toBeLessThan(
+      html.indexOf('data-testid="vault-card"'),
+    );
+  });
+
+  test("get-started card — present on the admin branch, hidden on the no-vault branch", () => {
+    // The on-ramp belongs on branches that have a vault to act against (admin +
+    // assigned-vault). It's suppressed on the no-vault branch, where the page
+    // says "You don't have a vault yet" — a do-the-thing card there would
+    // contradict the you-lack-the-prerequisite message.
+    const admin = renderAccountHome({
+      username: "admin",
+      assignedVaults: [],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: true,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    expect(admin).toContain('data-testid="get-started-card"');
+
+    const noVault = renderAccountHome({
+      username: "ghost",
+      assignedVaults: [],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    // No-vault branch: card suppressed, and the no-vault message stands alone.
+    expect(noVault).not.toContain('data-testid="get-started-card"');
+    expect(noVault).toContain('data-testid="no-vault-card"');
+  });
+
+  test("connect-any-client hint bridges MCP ↔ ChatGPT 'connector' terminology", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    // The "any other client" hint now names the ChatGPT "connector" term so
+    // a friend who only knows that word can find the right place to paste.
+    // Assert the NEW hint string specifically — a bare toContain("connector")
+    // was already satisfied pre-PR by the Claude.ai "Connectors" block, so it
+    // wouldn't catch a regression that drops this bridging copy.
+    expect(html).toContain('data-testid="connect-any-client-hint"');
+    expect(html).toContain('call these "connectors."');
+  });
+
+  test("account card — security actions collapse into a secondary <details>", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    // Username + sign-out stay prominent; change-password + 2FA tuck into a
+    // collapsed "Security & password" details so the card reads calmer.
+    expect(html).toContain('data-testid="account-security"');
+    expect(html).toContain("Security &amp; password");
+    // The security actions live inside the details block (after its summary).
+    const securityIdx = html.indexOf('data-testid="account-security"');
+    expect(securityIdx).toBeGreaterThan(-1);
+    expect(html.indexOf('data-testid="change-password-link"')).toBeGreaterThan(securityIdx);
+    // Sign-out form comes BEFORE the security details — it stays prominent.
+    expect(html.indexOf('data-testid="signout-form"')).toBeLessThan(securityIdx);
+  });
+
   test("account card — change-password link and sign-out form are present", () => {
     const html = renderAccountHome({
       username: "alice",

package/src/__tests__/managed-unit.test.ts

@@ -429,10 +429,13 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(() => hubUnit(f.deps)).toThrow(/'bun' not found on PATH/);
   });
 
-  test("env carries the 4 vars and INTENTIONALLY OMITS PARACHUTE_HUB_ORIGIN", () => {
+  test("env carries the 5 vars and INTENTIONALLY OMITS PARACHUTE_HUB_ORIGIN", () => {
     const f = fakeDeps({ platform: "linux" });
     const unit = hubUnit(f.deps);
     expect(unit.env).toEqual({
+      // Forced loopback (security): a self-hosted supervised hub must NOT inherit
+      // serve.ts's container-first 0.0.0.0 default and bare-serve all-interfaces.
+      PARACHUTE_BIND_HOST: "127.0.0.1",
       PARACHUTE_HOME: "/home/op/.parachute",
       PORT: "1939",
       PATH: "/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin",
@@ -441,6 +444,17 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(unit.env.PARACHUTE_HUB_ORIGIN).toBeUndefined();
   });
 
+  test("env forces PARACHUTE_BIND_HOST=127.0.0.1 (loopback trust model — never 0.0.0.0)", () => {
+    const f = fakeDeps({ platform: "linux" });
+    const unit = hubUnit(f.deps);
+    // The whole point of the fix: the supervised hub unit binds loopback, NOT
+    // the serve.ts container-first 0.0.0.0 default. Covers both init + migrate
+    // (both route through buildHubManagedUnit) and both platforms (the env is
+    // platform-agnostic; systemd/launchd render shapes are asserted below).
+    expect(unit.env.PARACHUTE_BIND_HOST).toBe("127.0.0.1");
+    expect(unit.env.PARACHUTE_BIND_HOST).not.toBe("0.0.0.0");
+  });
+
   test("PARACHUTE_HOME is the captured param, NOT the default (§4.2)", () => {
     const f = fakeDeps({ platform: "linux" });
     const unit = buildHubManagedUnit({
@@ -468,11 +482,14 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(unit.env.PORT).toBe("2939");
   });
 
-  test("rendered systemd SYSTEM unit: 4 Environment= vars, User= present, StartLimit present", () => {
+  test("rendered systemd SYSTEM unit: 5 Environment= vars, User= present, StartLimit present", () => {
     const f = fakeDeps({ platform: "linux", getuid: () => 0, userName: () => "op" });
     const unit = renderManagedSystemdUnit(hubUnit(f.deps), { root: true, userName: "op" });
     expect(unit).toContain("Description=Parachute hub (serve + supervisor)");
     expect(unit).toContain("User=op");
+    // Forced loopback bind (security): the supervised hub must bind 127.0.0.1.
+    expect(unit).toContain("Environment=PARACHUTE_BIND_HOST=127.0.0.1");
+    expect(unit).not.toContain("PARACHUTE_BIND_HOST=0.0.0.0");
     expect(unit).toContain("Environment=PARACHUTE_HOME=/home/op/.parachute");
     expect(unit).toContain("Environment=PORT=1939");
     expect(unit).toContain("Environment=PATH=/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin");
@@ -494,7 +511,7 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(unit).toContain("WantedBy=default.target");
   });
 
-  test("rendered launchd plist: EnvironmentVariables dict (4 vars) + ThrottleInterval + abs ProgramArguments", () => {
+  test("rendered launchd plist: EnvironmentVariables dict (5 vars) + ThrottleInterval + abs ProgramArguments", () => {
     const f = fakeDeps({ platform: "darwin" });
     const plist = renderManagedLaunchdPlist(hubUnit(f.deps));
     expect(plist).toContain("<key>Label</key>\n  <string>computer.parachute.hub</string>");
@@ -502,6 +519,9 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(plist).toContain("<string>/home/op/parachute-hub/src/cli.ts</string>");
     expect(plist).toContain("<string>serve</string>");
     expect(plist).toContain("<key>EnvironmentVariables</key>");
+    // Forced loopback bind (security): the supervised hub must bind 127.0.0.1.
+    expect(plist).toContain("<key>PARACHUTE_BIND_HOST</key>\n    <string>127.0.0.1</string>");
+    expect(plist).not.toContain("<string>0.0.0.0</string>");
     expect(plist).toContain("<key>PARACHUTE_HOME</key>\n    <string>/home/op/.parachute</string>");
     expect(plist).toContain("<key>PORT</key>\n    <string>1939</string>");
     expect(plist).toContain("<key>BUN_INSTALL</key>\n    <string>/home/op/.bun</string>");

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

@@ -122,6 +122,12 @@ function makeFakeCutover(over: Partial<CutoverDeps> = {}): FakeCutover {
         messages: ["started unit"],
       };
     },
+    // Hermetic default: the stale-unit disable is a no-op (no real
+    // systemctl/launchctl). Tests that exercise #522 override this to trace + act.
+    disableStaleModuleUnits: () => {
+      trace.push("disableStaleUnits");
+      return { actions: [] };
+    },
     ...over,
   };
   // Expose the world via closure for tests that want to manipulate it.
@@ -184,6 +190,43 @@ describe("cutoverToSupervised — happy path (§7.1)", () => {
     }
   });
 
+  test("#522: stale-unit disable runs in the STOP phase — after detached stop, before unit start", async () => {
+    const h = makeHarness();
+    try {
+      seedManifest(h.manifestPath, [{ name: "vault", port: 1940 }]);
+      const fc = makeFakeCutover();
+      const w = getWorld(fc.deps);
+      w.listening.add(1939);
+      w.listening.add(1940);
+      w.alivePids.add(5555);
+      writePid("vault", 5555, h.configDir);
+      const baseKill = fc.deps.kill;
+      fc.deps.kill = (pid, signal) => {
+        baseKill?.(pid, signal);
+        if (pid === 5555) getWorld(fc.deps).listening.delete(1940);
+      };
+      const result = await cutoverToSupervised({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        deps: fc.deps,
+        log: () => {},
+        pollMs: 0,
+      });
+      expect(result.outcome).toBe("migrated");
+      const stopIdx = fc.trace.indexOf("stopHub");
+      const disableIdx = fc.trace.indexOf("disableStaleUnits");
+      const startIdx = fc.trace.indexOf("startUnit");
+      // The disable runs AFTER the detached stop and BEFORE the unit start, so a
+      // KeepAlive/Restart=always unit can't re-grab the port between freeing it
+      // and the supervised module binding it.
+      expect(disableIdx).toBeGreaterThanOrEqual(0);
+      expect(stopIdx).toBeLessThan(disableIdx);
+      expect(disableIdx).toBeLessThan(startIdx);
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("verify-ports-free runs before start (start never races a held port)", async () => {
     const h = makeHarness();
     try {
@@ -443,6 +486,7 @@ describe("cutoverToSupervised — fail-safe recovery states", () => {
 describe("teardownHubUnit (§7.4)", () => {
   test("removes the hub unit (idempotent success path)", () => {
     let removeArgs: { launchdLabel: string; systemdUnitName: string } | undefined;
+    let staleCalled = false;
     const log: string[] = [];
     const res = teardownHubUnit({
       log: (l) => log.push(l),
@@ -450,21 +494,36 @@ describe("teardownHubUnit (§7.4)", () => {
         removeArgs = { launchdLabel: opts.launchdLabel, systemdUnitName: opts.systemdUnitName };
         return { removed: true, messages: [opts.removedSystemdMessage(opts.systemdUnitName)] };
       },
+      // Hermetic stub — no real systemctl/launchctl.
+      disableStaleModuleUnits: () => {
+        staleCalled = true;
+        return { actions: [] };
+      },
     });
     expect(res.removed).toBe(true);
     expect(removeArgs?.launchdLabel).toBe("computer.parachute.hub");
     expect(removeArgs?.systemdUnitName).toBe("parachute-hub.service");
+    // #522: teardown also runs the stale-per-module-autostart disable.
+    expect(staleCalled).toBe(true);
     // Surfaces the fallback hint.
     expect(log.join("\n")).toContain("parachute serve");
   });
 
-  test("no unit installed → no-op, friendly message", () => {
+  test("no unit installed → no-op, friendly message (still runs the stale-unit disable)", () => {
+    let staleCalled = false;
     const log: string[] = [];
     const res = teardownHubUnit({
       log: (l) => log.push(l),
       remove: (): ManagedUnitRemoveResult => ({ removed: false, messages: [] }),
+      disableStaleModuleUnits: () => {
+        staleCalled = true;
+        return { actions: [] };
+      },
     });
     expect(res.removed).toBe(false);
+    // #522: a leftover module autostart must be cleaned even when the hub unit was
+    // never installed (a partial / never-migrated box rolling back).
+    expect(staleCalled).toBe(true);
     expect(log.join("\n")).toContain("nothing to tear down");
   });
 });

package/src/__tests__/stale-module-units.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, test } from "bun:test";
+import type { ManagedUnitDeps, ServiceCommandResult } from "../managed-unit.ts";
+import {
+  disableStaleModuleUnits,
+  moduleLaunchdLabel,
+  moduleSystemdUnitName,
+  targetModuleShorts,
+} from "../stale-module-units.ts";
+
+/**
+ * #522 — migrate/teardown must DETECT + DISABLE any stale per-module autostart
+ * unit (a leftover `parachute-<short>.service` systemd KeepAlive / a
+ * `computer.parachute.<short>` launchd KeepAlive) so it stops respawning an
+ * unsupervised module that fights the supervised hub for the module's port.
+ *
+ * ALL tests run against a stubbed `ManagedUnitDeps.run` — NO real
+ * systemctl/launchctl. Each fake records the commands it received so we can
+ * assert exactly which units were disabled, which were skipped, and that a
+ * disable failure / system-level unit is non-fatal.
+ */
+
+type RunResponder = (cmd: readonly string[]) => ServiceCommandResult;
+
+function ok(stdout = ""): ServiceCommandResult {
+  return { code: 0, stdout, stderr: "" };
+}
+function fail(stderr = "boom", code = 1): ServiceCommandResult {
+  return { code, stdout: "", stderr };
+}
+
+function makeDeps(platform: NodeJS.Platform, respond: RunResponder) {
+  const calls: string[][] = [];
+  const deps: ManagedUnitDeps = {
+    platform,
+    getuid: () => 501,
+    homeDir: () => "/home/op",
+    userName: () => "op",
+    which: (b) => (b === "systemctl" || b === "launchctl" ? `/usr/bin/${b}` : null),
+    run: (cmd) => {
+      calls.push([...cmd]);
+      return respond(cmd);
+    },
+    writeFile: () => {},
+    removeFile: () => {},
+    readFile: () => undefined,
+    exists: () => false,
+  };
+  return { deps, calls };
+}
+
+function joined(calls: string[][]): string[] {
+  return calls.map((c) => c.join(" "));
+}
+
+describe("targetModuleShorts() — known module shorts, never hub/cloudflared", () => {
+  test("includes the canonical module shorts and excludes hub", () => {
+    const shorts = targetModuleShorts();
+    // The canonical knownServices() set: vault / scribe / runner / surface / notes / channel.
+    expect(shorts).toContain("vault");
+    expect(shorts).toContain("scribe");
+    expect(shorts).toContain("surface");
+    expect(shorts).toContain("notes");
+    // hub is the supervised model itself — never a target.
+    expect(shorts).not.toContain("hub");
+    expect(shorts).not.toContain("cloudflared");
+  });
+});
+
+describe("disableStaleModuleUnits — systemd (Linux)", () => {
+  test("a stale ENABLED user unit parachute-vault.service is disabled --now + reported", () => {
+    const { deps, calls } = makeDeps("linux", (cmd) => {
+      const line = cmd.join(" ");
+      // Only vault's USER unit reads enabled; everything else is disabled.
+      if (line === "systemctl --user is-enabled parachute-vault.service") return ok("enabled\n");
+      if (line.startsWith("systemctl --user is-enabled")) return fail("disabled", 1);
+      if (line.startsWith("systemctl is-enabled")) return fail("disabled", 1);
+      if (line === "systemctl --user disable --now parachute-vault.service") return ok();
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+
+    // Exactly one unit acted on: vault, disabled at user scope.
+    expect(res.actions).toHaveLength(1);
+    expect(res.actions[0]).toMatchObject({
+      short: "vault",
+      kind: "systemd-user",
+      unit: "parachute-vault.service",
+      result: "disabled",
+    });
+    // The disable --now command was actually invoked.
+    expect(joined(calls)).toContain("systemctl --user disable --now parachute-vault.service");
+    // The action is reported so the operator sees what changed.
+    expect(log.join("\n")).toContain("Disabled stale parachute-vault.service");
+    expect(log.join("\n")).toContain("vault's port");
+  });
+
+  test("SKIPS the hub unit + cloudflared units — never queried, never disabled", () => {
+    const { deps, calls } = makeDeps("linux", () => fail("disabled", 1));
+    disableStaleModuleUnits({ deps });
+    const lines = joined(calls);
+    // The hub unit is never probed or disabled by this sweep.
+    expect(lines.some((l) => l.includes("parachute-hub.service"))).toBe(false);
+    // No cloudflared connector unit is touched.
+    expect(lines.some((l) => l.includes("parachute-cloudflared"))).toBe(false);
+    // And no disable command runs at all (everything reads disabled).
+    expect(lines.some((l) => l.includes("disable"))).toBe(false);
+  });
+
+  test("a non-matching / arbitrary unit is never touched (only parachute-<known-short> is queried)", () => {
+    const { deps, calls } = makeDeps("linux", () => fail("disabled", 1));
+    disableStaleModuleUnits({ deps });
+    const lines = joined(calls);
+    // Every is-enabled probe targets a parachute-<known-short>.service and nothing else.
+    const probes = lines.filter((l) => l.includes("is-enabled"));
+    expect(probes.length).toBeGreaterThan(0);
+    for (const probe of probes) {
+      const m = probe.match(/is-enabled (parachute-[a-z]+\.service)$/);
+      expect(m).not.toBeNull();
+      const unit = m?.[1] ?? "";
+      // The probed unit must be a known module short, and never the hub/cloudflared.
+      expect(targetModuleShorts().map(moduleSystemdUnitName)).toContain(unit);
+      expect(unit).not.toBe("parachute-hub.service");
+    }
+  });
+
+  test("idempotent: every unit already disabled → clean no-op (no disable, no actions)", () => {
+    const { deps, calls } = makeDeps("linux", () => fail("disabled", 1));
+    const res = disableStaleModuleUnits({ deps });
+    expect(res.actions).toHaveLength(0);
+    expect(joined(calls).some((l) => l.includes("disable"))).toBe(false);
+  });
+
+  test("system-level unit (no --user enabled, system enabled) → WARNS with manual sudo command, doesn't abort, doesn't sudo", () => {
+    const { deps, calls } = makeDeps("linux", (cmd) => {
+      const line = cmd.join(" ");
+      // vault's USER unit is NOT enabled, but the SYSTEM unit IS.
+      if (line === "systemctl --user is-enabled parachute-vault.service")
+        return fail("disabled", 1);
+      if (line === "systemctl is-enabled parachute-vault.service") return ok("enabled\n");
+      if (line.startsWith("systemctl --user is-enabled")) return fail("disabled", 1);
+      if (line.startsWith("systemctl is-enabled")) return fail("disabled", 1);
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+
+    const vaultAction = res.actions.find((a) => a.short === "vault");
+    expect(vaultAction).toMatchObject({ kind: "systemd-system", result: "warn-system" });
+    const out = log.join("\n");
+    // The exact manual command is surfaced.
+    expect(out).toContain("sudo systemctl disable --now parachute-vault.service");
+    // It NEVER attempted a sudo / system disable itself.
+    expect(joined(calls)).not.toContain("systemctl disable --now parachute-vault.service");
+    expect(joined(calls).some((l) => l.startsWith("sudo"))).toBe(false);
+  });
+
+  test("non-fatal: a disable command that fails → warn + continue (the other units are still swept)", () => {
+    const { deps, calls } = makeDeps("linux", (cmd) => {
+      const line = cmd.join(" ");
+      // Both vault + scribe user units read enabled; vault's disable FAILS.
+      if (line === "systemctl --user is-enabled parachute-vault.service") return ok("enabled\n");
+      if (line === "systemctl --user is-enabled parachute-scribe.service") return ok("enabled\n");
+      if (line.startsWith("systemctl --user is-enabled")) return fail("disabled", 1);
+      if (line.startsWith("systemctl is-enabled")) return fail("disabled", 1);
+      if (line === "systemctl --user disable --now parachute-vault.service")
+        return fail("permission denied");
+      if (line === "systemctl --user disable --now parachute-scribe.service") return ok();
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+
+    const vault = res.actions.find((a) => a.short === "vault");
+    const scribe = res.actions.find((a) => a.short === "scribe");
+    // vault's disable failed → warned, not fatal; scribe was still disabled.
+    expect(vault?.result).toBe("failed");
+    expect(scribe?.result).toBe("disabled");
+    // Both disable attempts ran — the failure didn't abort the sweep.
+    expect(joined(calls)).toContain("systemctl --user disable --now parachute-vault.service");
+    expect(joined(calls)).toContain("systemctl --user disable --now parachute-scribe.service");
+    expect(log.join("\n")).toContain("Could not disable");
+  });
+
+  test("no systemctl on the box → clean no-op", () => {
+    const calls: string[][] = [];
+    const deps: ManagedUnitDeps = {
+      platform: "linux",
+      getuid: () => 501,
+      homeDir: () => "/home/op",
+      userName: () => "op",
+      which: () => null, // no systemctl
+      run: (cmd) => {
+        calls.push([...cmd]);
+        return ok();
+      },
+      writeFile: () => {},
+      removeFile: () => {},
+      readFile: () => undefined,
+      exists: () => false,
+    };
+    const res = disableStaleModuleUnits({ deps });
+    expect(res.actions).toHaveLength(0);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("disableStaleModuleUnits — launchd (Mac)", () => {
+  test("a loaded computer.parachute.vault LaunchAgent is booted out + reported", () => {
+    const { deps, calls } = makeDeps("darwin", (cmd) => {
+      const line = cmd.join(" ");
+      // Only vault's label is loaded (print succeeds with content); others print empty.
+      if (line === "launchctl print gui/501/computer.parachute.vault")
+        return ok("com.apple...\nstate = running\n");
+      if (line.startsWith("launchctl print")) return ok(""); // not loaded
+      if (line === "launchctl bootout gui/501/computer.parachute.vault") return ok();
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+
+    expect(res.actions).toHaveLength(1);
+    expect(res.actions[0]).toMatchObject({
+      short: "vault",
+      kind: "launchd",
+      unit: "computer.parachute.vault",
+      result: "disabled",
+    });
+    expect(joined(calls)).toContain("launchctl bootout gui/501/computer.parachute.vault");
+    expect(log.join("\n")).toContain("Disabled stale computer.parachute.vault");
+  });
+
+  test("SKIPS the hub label + cloudflared labels — never printed, never booted out", () => {
+    const { deps, calls } = makeDeps("darwin", () => ok("")); // nothing loaded
+    disableStaleModuleUnits({ deps });
+    const lines = joined(calls);
+    expect(lines.some((l) => l.includes("computer.parachute.hub"))).toBe(false);
+    expect(lines.some((l) => l.includes("computer.parachute.cloudflared"))).toBe(false);
+    // Every print targets a parachute.<known-short> label.
+    const prints = lines.filter((l) => l.startsWith("launchctl print"));
+    for (const p of prints) {
+      const m = p.match(/computer\.parachute\.([a-z]+)$/);
+      expect(m).not.toBeNull();
+      expect(targetModuleShorts()).toContain(m?.[1] ?? "");
+    }
+  });
+
+  test("idempotent: nothing loaded → clean no-op (no bootout, no actions)", () => {
+    const { deps, calls } = makeDeps("darwin", () => ok("")); // print returns empty for all
+    const res = disableStaleModuleUnits({ deps });
+    expect(res.actions).toHaveLength(0);
+    expect(joined(calls).some((l) => l.includes("bootout"))).toBe(false);
+  });
+
+  test("non-fatal: a bootout that fails → warn + continue", () => {
+    const { deps } = makeDeps("darwin", (cmd) => {
+      const line = cmd.join(" ");
+      if (line === "launchctl print gui/501/computer.parachute.vault")
+        return ok("state = running\n");
+      if (line.startsWith("launchctl print")) return ok("");
+      if (line === "launchctl bootout gui/501/computer.parachute.vault")
+        return fail("Operation not permitted");
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+    expect(res.actions.find((a) => a.short === "vault")?.result).toBe("failed");
+    expect(log.join("\n")).toContain("Could not disable the stale LaunchAgent");
+  });
+});
+
+describe("disableStaleModuleUnits — unsupported platform", () => {
+  test("no per-platform manager (e.g. win32) → clean no-op", () => {
+    const { deps, calls } = makeDeps("win32", () => ok());
+    const res = disableStaleModuleUnits({ deps });
+    expect(res.actions).toHaveLength(0);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("unit-name helpers", () => {
+  test("moduleSystemdUnitName / moduleLaunchdLabel build the exact per-module names", () => {
+    expect(moduleSystemdUnitName("vault")).toBe("parachute-vault.service");
+    expect(moduleLaunchdLabel("vault")).toBe("computer.parachute.vault");
+  });
+});