@openparachute/hub 0.6.3-rc.3 → 0.6.3-rc.4

package/package.json

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

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");
+  });
+});

package/src/cloudflare/connector-service.ts

@@ -69,10 +69,21 @@ export type ConnectorServiceDeps = ManagedUnitDeps;
 
 export const defaultServiceDeps: ConnectorServiceDeps = defaultManagedUnitDeps;
 
+/**
+ * Reverse-DNS prefix for the launchd label + plist filename. Exported so the
+ * migrate/teardown stale-per-module-autostart sweep (`src/stale-module-units.ts`,
+ * hub#522) can reuse it as a SKIP-list anchor — the connector unit is owned by
+ * the supervised model (`expose off --cloudflare` tears it down), and the sweep
+ * must never touch it. Reusing the constant keeps the skip-list from drifting if
+ * this prefix ever changes.
+ */
+export const CLOUDFLARED_LAUNCHD_LABEL_PREFIX = "computer.parachute.cloudflared";
+/** systemd unit name prefix. Exported for the same skip-list reason as above. */
+export const CLOUDFLARED_SYSTEMD_UNIT_PREFIX = "parachute-cloudflared-";
 /** Reverse-DNS prefix for the launchd label + plist filename. */
-const LAUNCHD_LABEL_PREFIX = "computer.parachute.cloudflared";
+const LAUNCHD_LABEL_PREFIX = CLOUDFLARED_LAUNCHD_LABEL_PREFIX;
 /** systemd unit name prefix. */
-const SYSTEMD_UNIT_PREFIX = "parachute-cloudflared-";
+const SYSTEMD_UNIT_PREFIX = CLOUDFLARED_SYSTEMD_UNIT_PREFIX;
 /** Provenance comment baked into every rendered connector unit file. */
 const CONNECTOR_HEADER = "Generated by parachute expose public --cloudflare — do not edit by hand.";
 

package/src/commands/migrate-cutover.ts

@@ -86,6 +86,11 @@ import { type PortListeningFn, defaultPortListening } from "../port-probe.ts";
 import { type AliveFn, clearPid, readPid } from "../process-state.ts";
 import { shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifestLenient } from "../services-manifest.ts";
+import {
+  type DisableStaleModuleUnitsOpts,
+  type DisableStaleModuleUnitsResult,
+  disableStaleModuleUnits,
+} from "../stale-module-units.ts";
 
 /**
  * Absolute path to this hub checkout's `src/cli.ts` — the entry the hub unit's
@@ -180,6 +185,19 @@ export interface CutoverDeps {
   sleep: (ms: number) => Promise<void>;
   /** The hub-unit deps for install / detect / manager calls. */
   hubUnitDeps: HubUnitDeps;
+  /**
+   * Detect + DISABLE any stale per-module autostart unit (#522 — the load-bearing
+   * fix). A leftover standalone `parachute-<short>.service` (systemd KeepAlive) /
+   * `computer.parachute.<short>` (launchd KeepAlive) from the pre-supervisor era
+   * keeps RESPAWNING an unsupervised module that binds the module's port — the
+   * supervised child then EADDRINUSE-crash-loops. Killing the process is
+   * whack-a-mole (the unit resurrects it); we must disable the UNIT. Run in the
+   * STOP phase (after the per-module detached stop, before the port-free verify)
+   * so the freed port lets the supervised module bind. Ownership-safe (known
+   * module shorts only; hub + cloudflared skipped), idempotent, non-fatal.
+   * Injectable so tests never touch real systemctl/launchctl.
+   */
+  disableStaleModuleUnits: (opts?: DisableStaleModuleUnitsOpts) => DisableStaleModuleUnitsResult;
 }
 
 export interface WriteUnitOpts {
@@ -329,6 +347,7 @@ export const defaultCutoverDeps: CutoverDeps = {
   probeHealth: defaultHubUnitDeps.probeHealth,
   sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
   hubUnitDeps: defaultHubUnitDeps,
+  disableStaleModuleUnits,
 };
 
 export interface CutoverOpts {
@@ -673,6 +692,22 @@ export async function cutoverToSupervised(opts: CutoverOpts = {}): Promise<Cutov
     await stopDetachedModule(target, configDir, deps, timeoutMs, pollMs, log);
   }
 
+  // --- Step 3b (#522): DISABLE stale per-module autostart UNITS. ---
+  // The load-bearing fix for the recurring "port 1940 taken" crash-loop: a
+  // leftover standalone `parachute-<short>.service` (systemd KeepAlive) or
+  // `computer.parachute.<short>` (launchd KeepAlive) from the pre-supervisor era
+  // keeps RESPAWNING an unsupervised module that binds the port — so the
+  // per-module stop above (and the orphan sweep below) is whack-a-mole: the unit
+  // resurrects the process within seconds, serving OLD code. We must DISABLE the
+  // UNIT so the port stays free for the supervised child. MUST run HERE — after
+  // the detached stop, BEFORE the verify-ports-free + unit start — so the freed
+  // port lets the supervised module bind. Ownership-safe (known module shorts
+  // only; hub + cloudflared skipped), idempotent, non-fatal (a failed disable
+  // warns + continues; a system-level unit it can't disable → warn with the
+  // manual sudo command). Every disabled unit is reported.
+  log("Checking for stale per-module autostart units to disable…");
+  deps.disableStaleModuleUnits({ deps: deps.hubUnitDeps, log: (l) => log(l) });
+
   // --- Step 4: §7.2 ORPHAN SWEEP — per services.json port + the hub port. ---
   // The HUB port keeps the pre-existing blind-adopt (mirrors stopHub's 1939
   // orphan-adoption — out of scope for MUST-FIX 2). The MODULE ports get the
@@ -797,6 +832,13 @@ export interface TeardownOpts {
     removedLaunchdMessage: (label: string) => string;
     removedSystemdMessage: (unitName: string) => string;
   }) => ManagedUnitRemoveResult;
+  /**
+   * Test seam: the stale-per-module-autostart disable (#522). Teardown also
+   * disables any leftover standalone module autostart unit so a rollback to
+   * foreground `serve` doesn't leave a competing module respawning at boot.
+   * Injectable so tests never touch real systemctl/launchctl.
+   */
+  disableStaleModuleUnits?: (opts?: DisableStaleModuleUnitsOpts) => DisableStaleModuleUnitsResult;
 }
 
 /**
@@ -815,6 +857,7 @@ export function teardownHubUnit(opts: TeardownOpts = {}): { removed: boolean; me
   const log = opts.log ?? ((line) => console.log(line));
   const deps = opts.deps ?? defaultHubUnitDeps;
   const remove = opts.remove ?? removeManagedUnit;
+  const disableStale = opts.disableStaleModuleUnits ?? disableStaleModuleUnits;
   const res = remove({
     launchdLabel: HUB_LAUNCHD_LABEL,
     systemdUnitName: HUB_SYSTEMD_UNIT_NAME,
@@ -824,6 +867,11 @@ export function teardownHubUnit(opts: TeardownOpts = {}): { removed: boolean; me
     removedSystemdMessage: (unitName) =>
       `Removed systemd unit ${unitName} — the hub no longer starts on boot.`,
   });
+  // #522: also disable any leftover standalone per-module autostart unit so a
+  // rollback to foreground `serve` doesn't leave a competing module respawning at
+  // boot to race whatever the operator brings up next. Ownership-safe (known
+  // module shorts only; hub + cloudflared skipped), idempotent, non-fatal.
+  disableStale({ deps, log });
   if (res.removed) {
     for (const m of res.messages) log(m);
     log("");

package/src/managed-unit.ts

@@ -648,10 +648,25 @@ export interface BuildHubManagedUnitOpts {
  *
  * Resolves the absolute `bun` path via the `which` seam (launchd/systemd don't
  * search `$PATH` — mirrors how the connector resolves cloudflared). The env
- * carries `PARACHUTE_HOME` / `PORT` / `PATH` / `BUN_INSTALL` — and INTENTIONALLY
- * OMITS `PARACHUTE_HUB_ORIGIN`: baking a stale origin here would re-create the
- * iss-mismatch class; `resolveStartupIssuer` derives it and start-hub self-heals
- * the operator token + vault `.env` to the current origin (design §4.1 comment).
+ * carries `PARACHUTE_BIND_HOST` / `PARACHUTE_HOME` / `PORT` / `PATH` /
+ * `BUN_INSTALL` — and INTENTIONALLY OMITS `PARACHUTE_HUB_ORIGIN`: baking a stale
+ * origin here would re-create the iss-mismatch class; `resolveStartupIssuer`
+ * derives it and start-hub self-heals the operator token + vault `.env` to the
+ * current origin (design §4.1 comment).
+ *
+ * BIND HOST — `PARACHUTE_BIND_HOST=127.0.0.1` is forced here so every
+ * self-hosted supervised hub binds loopback. `parachute serve` itself defaults
+ * the bind host to `0.0.0.0` (serve.ts), which is correct for the container
+ * shape (the platform's HTTP forwarder must reach the hub) but WRONG for a
+ * self-hosted box — bare `serve` would expose the admin/OAuth surfaces on every
+ * interface, contradicting the pre-supervisor detached behavior and the trust
+ * model `layerOf` (hub-server.ts) assumes (header-absent ⇒ "loopback"). The
+ * container path never calls this builder (the Dockerfile pins
+ * `ENV PARACHUTE_BIND_HOST=0.0.0.0` + runs `serve` directly), so it stays
+ * 0.0.0.0. The canonical expose path is unaffected: cloudflared/tailscale dial
+ * `127.0.0.1:<port>` from the same host, and the hub's own proxy targets
+ * `http://127.0.0.1:<port>` (hub-server.ts). An operator who genuinely wants
+ * all-interfaces can override the generated unit; the default is loopback.
  *
  * NOT called by any command in this PR (additive — Phase 3 wires it into `init`).
  */
@@ -676,6 +691,11 @@ export function buildHubManagedUnit(opts: BuildHubManagedUnitOpts): ManagedUnit
     systemdDescription: "Parachute hub (serve + supervisor)",
     execStart: [bunPath, opts.cliPath, "serve"],
     env: {
+      // Force loopback on every self-hosted supervised hub. serve.ts defaults
+      // to 0.0.0.0 (container-first); a self-hosted box must NOT bare-serve
+      // all-interfaces. Container path bypasses this builder (Dockerfile pins
+      // its own 0.0.0.0). See the docstring for the full trust-model rationale.
+      PARACHUTE_BIND_HOST: "127.0.0.1",
       // PARACHUTE_HOME captured at install time (design §4.2) — NOT the default.
       PARACHUTE_HOME: opts.parachuteHome,
       PORT: String(port),

package/src/stale-module-units.ts

@@ -0,0 +1,374 @@
+/**
+ * Detect + disable STALE per-module autostart units during the
+ * detached→supervised cutover + teardown (hub#522, design
+ * `parachute.computer/design/2026-06-01-hub-as-supervisor-unification.md` §7.2).
+ *
+ * THE BUG (validated hands-on on friends.parachute.computer): after a box
+ * migrates to the supervised model, a leftover STANDALONE per-module autostart
+ * unit from the pre-supervisor era — a systemd user unit `parachute-vault.service`
+ * with `Restart=always`, or a launchd `computer.parachute.vault` LaunchAgent with
+ * `KeepAlive` — keeps RESPAWNING an unsupervised vault that binds port 1940. The
+ * supervised hub's own vault child then can't bind → EADDRINUSE crash-loop →
+ * `crashed`, giving up. Killing the squatting PROCESS is whack-a-mole: the unit's
+ * KeepAlive / Restart=always resurrects it within seconds, serving OLD code.
+ *
+ * THE FIX (the load-bearing half of #522): the cutover must DISABLE THE UNIT, not
+ * just kill the process. Disabling deregisters the keep-alive intent so the
+ * module stays down and the supervised hub owns the port. The complementary half
+ * — the supervisor reclaiming its own port on EADDRINUSE at every start — is a
+ * separate follow-on; THIS module is the unit-disable that stops the respawn at
+ * the source.
+ *
+ * SCOPE + OWNERSHIP SAFETY (the hard constraint): we ONLY ever disable a unit
+ * whose name EXACTLY matches `parachute-<short>.service` (systemd) or
+ * `computer.parachute.<short>` (launchd) for a KNOWN module short
+ * (`knownServices()` — vault / scribe / runner / surface / notes / channel). We
+ * NEVER disable an arbitrary or unrecognized unit — an unknown unit is invisible
+ * to this sweep by construction (we look up exact names, never enumerate-and-
+ * match-loosely). On top of that we EXPLICITLY exclude the units the supervised
+ * model legitimately owns:
+ *   - the hub unit (`computer.parachute.hub` / `parachute-hub.service`), and
+ *   - the cloudflared connector (`computer.parachute.cloudflared.*` /
+ *     `parachute-cloudflared-*`, owned by `expose off --cloudflare`).
+ * The skip-list reuses the canonical name constants (HUB_* + the cloudflared
+ * prefixes) so it can't drift.
+ *
+ * BEHAVIOR per platform (reuses the `ManagedUnitDeps` seam — `which` / `run`):
+ *   - systemd (Linux): for each known short, query the USER unit
+ *     `systemctl --user is-enabled parachute-<short>.service`. If it reads
+ *     enabled (`enabled` / `enabled-runtime` / `static` / `alias`/`indirect`-ish)
+ *     → `systemctl --user disable --now parachute-<short>.service`. A SYSTEM-level
+ *     unit of the same name (detected via `systemctl is-enabled` without --user)
+ *     is NOT touched (migrate has no sudo) — we WARN with the exact manual
+ *     `sudo systemctl disable --now …` command instead.
+ *   - launchd (Mac): for each known short, `launchctl print
+ *     gui/<uid>/computer.parachute.<short>`; if the label is loaded → `launchctl
+ *     bootout gui/<uid>/computer.parachute.<short>`.
+ *
+ * IDEMPOTENT: a unit that's already disabled / not-enabled / absent is a clean
+ * no-op (we never report disabling it). NON-FATAL: a disable that fails (perms,
+ * launchctl quirk) WARNS + continues — it never aborts the cutover. EVERYTHING
+ * behind the injectable `ManagedUnitDeps` seam so tests never touch real
+ * systemctl/launchctl.
+ */
+
+import {
+  CLOUDFLARED_LAUNCHD_LABEL_PREFIX,
+  CLOUDFLARED_SYSTEMD_UNIT_PREFIX,
+} from "./cloudflare/connector-service.ts";
+import {
+  HUB_LAUNCHD_LABEL,
+  HUB_SYSTEMD_UNIT_NAME,
+  type ManagedUnitDeps,
+  defaultManagedUnitDeps,
+} from "./managed-unit.ts";
+import { knownServices } from "./service-spec.ts";
+
+/** systemd unit name for a module short, e.g. `vault` → `parachute-vault.service`. */
+export function moduleSystemdUnitName(short: string): string {
+  return `parachute-${short}.service`;
+}
+
+/** launchd label for a module short, e.g. `vault` → `computer.parachute.vault`. */
+export function moduleLaunchdLabel(short: string): string {
+  return `computer.parachute.${short}`;
+}
+
+/**
+ * Is this systemd unit name one the supervised model legitimately owns (and the
+ * sweep must therefore NEVER disable)? The hub unit + any cloudflared connector
+ * unit. Reuses the canonical name constants so the skip can't drift.
+ */
+function isProtectedSystemdUnit(unitName: string): boolean {
+  return unitName === HUB_SYSTEMD_UNIT_NAME || unitName.startsWith(CLOUDFLARED_SYSTEMD_UNIT_PREFIX);
+}
+
+/**
+ * Is this launchd label one the supervised model legitimately owns? The hub
+ * label + any cloudflared connector label (`computer.parachute.cloudflared.*`).
+ */
+function isProtectedLaunchdLabel(label: string): boolean {
+  return (
+    label === HUB_LAUNCHD_LABEL ||
+    label === CLOUDFLARED_LAUNCHD_LABEL_PREFIX ||
+    label.startsWith(`${CLOUDFLARED_LAUNCHD_LABEL_PREFIX}.`)
+  );
+}
+
+/**
+ * The module shorts whose stale standalone autostart units the sweep targets.
+ * Derived from `knownServices()` (the canonical FIRST_PARTY_FALLBACKS +
+ * KNOWN_MODULES list — vault / scribe / runner / surface / notes / channel), so
+ * a future module is covered automatically. `hub` is deliberately NOT in that
+ * list — the hub unit is the supervised model itself; we never disable it. As a
+ * defensive double-check we also drop any short whose derived unit name lands in
+ * the protected skip-list (so the sweep can never disable the hub / cloudflared
+ * even if a future short collided).
+ */
+export function targetModuleShorts(): string[] {
+  return knownServices().filter(
+    (short) =>
+      !isProtectedSystemdUnit(moduleSystemdUnitName(short)) &&
+      !isProtectedLaunchdLabel(moduleLaunchdLabel(short)),
+  );
+}
+
+/**
+ * systemd `is-enabled` tokens that mean "this unit will autostart" — i.e. the
+ * stale-unit problem we're disabling. `disabled` / `masked` / `not-found` (and a
+ * nonzero exit with empty stdout) mean it won't, so they're a no-op.
+ *
+ * `static` and `indirect` units have no [Install] section / are pulled in by
+ * another unit; a standalone leftover `parachute-vault.service` written by the
+ * old per-module autostall path always carried `[Install] WantedBy=…` so reads
+ * `enabled` — but we treat `static`/`indirect` as "present + active intent" too
+ * so an oddly-written leftover still gets cleaned. `linked`/`generated` likewise.
+ */
+const SYSTEMD_ENABLED_TOKENS = new Set([
+  "enabled",
+  "enabled-runtime",
+  "static",
+  "indirect",
+  "linked",
+  "linked-runtime",
+  "generated",
+  "alias",
+]);
+
+/** Outcome of one unit's detect-and-disable attempt. */
+export interface StaleUnitAction {
+  /** The module short the unit belongs to. */
+  short: string;
+  /** "launchd" | "systemd-user" | "systemd-system". */
+  kind: "launchd" | "systemd-user" | "systemd-system";
+  /** The unit/label name acted on. */
+  unit: string;
+  /**
+   * "disabled"     → we disabled it (report it; the operator sees what changed).
+   * "warn-system"  → a system-level systemd unit we can't disable without sudo;
+   *                  we warn with the manual command. Non-fatal.
+   * "failed"       → the disable command failed (perms/quirk); we warn + continue.
+   */
+  result: "disabled" | "warn-system" | "failed";
+  /** The exact line(s) the caller should surface (report / warning). */
+  messages: string[];
+}
+
+export interface DisableStaleModuleUnitsOpts {
+  /** Injectable platform deps (defaults to production). */
+  deps?: ManagedUnitDeps;
+  /** Sink for human-readable report / warning lines. */
+  log?: (line: string) => void;
+}
+
+export interface DisableStaleModuleUnitsResult {
+  /** Every unit we acted on (disabled / warned / failed). Empty = clean no-op. */
+  actions: StaleUnitAction[];
+}
+
+/**
+ * Detect + disable any STALE per-module autostart unit on this platform (#522).
+ * Idempotent + non-fatal: already-disabled/absent units are silent no-ops, and a
+ * failed disable warns + continues. Returns the list of actions taken; the caller
+ * surfaces the messages (the cutover threads them through its own `log`).
+ *
+ * Dispatch mirrors `managed-unit.ts`: darwin → launchctl, linux → systemctl.
+ * Other platforms (no per-module unit possible) → empty no-op.
+ */
+export function disableStaleModuleUnits(
+  opts: DisableStaleModuleUnitsOpts = {},
+): DisableStaleModuleUnitsResult {
+  const deps = opts.deps ?? defaultManagedUnitDeps;
+  const log = opts.log ?? (() => {});
+  const actions: StaleUnitAction[] = [];
+
+  const record = (action: StaleUnitAction): void => {
+    actions.push(action);
+    for (const m of action.messages) log(m);
+  };
+
+  if (deps.platform === "darwin") {
+    if (deps.which("launchctl") === null) return { actions };
+    const uid = deps.getuid() ?? 0;
+    for (const short of targetModuleShorts()) {
+      const label = moduleLaunchdLabel(short);
+      // Belt-and-suspenders: never touch a protected (hub / cloudflared) label.
+      if (isProtectedLaunchdLabel(label)) continue;
+      const action = disableStaleLaunchdUnit(short, label, uid, deps);
+      if (action) record(action);
+    }
+    return { actions };
+  }
+
+  if (deps.platform === "linux") {
+    if (deps.which("systemctl") === null) return { actions };
+    for (const short of targetModuleShorts()) {
+      const unit = moduleSystemdUnitName(short);
+      if (isProtectedSystemdUnit(unit)) continue;
+      const action = disableStaleSystemdUnit(short, unit, deps);
+      if (action) record(action);
+    }
+    return { actions };
+  }
+
+  // No per-platform manager (container / init-less / Windows) → nothing to do.
+  return { actions };
+}
+
+/**
+ * launchd arm: probe `launchctl print gui/<uid>/<label>`. The label is LOADED
+ * (a stale KeepAlive LaunchAgent) when the print succeeds with non-empty output;
+ * we then `launchctl bootout` it (unload + stop → KeepAlive can't resurrect it).
+ * An unloaded/absent label prints empty/nonzero → clean no-op (returns undefined).
+ */
+function disableStaleLaunchdUnit(
+  short: string,
+  label: string,
+  uid: number,
+  deps: ManagedUnitDeps,
+): StaleUnitAction | undefined {
+  let printed: { code: number; stdout: string; stderr: string };
+  try {
+    printed = deps.run(["launchctl", "print", `gui/${uid}/${label}`]);
+  } catch {
+    // launchctl threw (ENOENT between which() and run, or a quirk) — non-fatal.
+    return undefined;
+  }
+  // Not loaded → nothing to disable. `launchctl print` is nonzero + empty when
+  // the label isn't bootstrapped.
+  if (printed.stdout.trim().length === 0) return undefined;
+
+  let booted: { code: number; stdout: string; stderr: string };
+  try {
+    booted = deps.run(["launchctl", "bootout", `gui/${uid}/${label}`]);
+  } catch (err) {
+    return {
+      short,
+      kind: "launchd",
+      unit: label,
+      result: "failed",
+      messages: [
+        `  ⚠ Could not disable the stale LaunchAgent ${label} (${err instanceof Error ? err.message : String(err)}).`,
+        `    Run it yourself: launchctl bootout gui/${uid}/${label}`,
+      ],
+    };
+  }
+  if (booted.code !== 0) {
+    const detail = booted.stderr.trim() || booted.stdout.trim() || "unknown error";
+    return {
+      short,
+      kind: "launchd",
+      unit: label,
+      result: "failed",
+      messages: [
+        `  ⚠ Could not disable the stale LaunchAgent ${label} (${detail}).`,
+        `    Run it yourself: launchctl bootout gui/${uid}/${label}`,
+      ],
+    };
+  }
+  return {
+    short,
+    kind: "launchd",
+    unit: label,
+    result: "disabled",
+    messages: [
+      `  ✓ Disabled stale ${label} (it was fighting the supervised hub for ${short}'s port).`,
+    ],
+  };
+}
+
+/**
+ * systemd arm: a stale standalone module unit can live at USER scope (the common
+ * pre-supervisor leftover, no sudo to write) or SYSTEM scope (rarer). We probe
+ * both:
+ *   - USER (`systemctl --user is-enabled <unit>`): if enabled → `--user disable
+ *     --now`. This is the path migrate can actually fix.
+ *   - SYSTEM (`systemctl is-enabled <unit>`): if enabled but USER wasn't → migrate
+ *     has no sudo, so WARN with the exact `sudo systemctl disable --now …` command
+ *     (never attempt sudo).
+ * An absent/disabled unit at both scopes → clean no-op (returns undefined).
+ */
+function disableStaleSystemdUnit(
+  short: string,
+  unit: string,
+  deps: ManagedUnitDeps,
+): StaleUnitAction | undefined {
+  // --- USER scope first (what migrate can actually disable). ---
+  if (systemdUnitEnabled(unit, ["--user"], deps)) {
+    let res: { code: number; stdout: string; stderr: string };
+    try {
+      res = deps.run(["systemctl", "--user", "disable", "--now", unit]);
+    } catch (err) {
+      return {
+        short,
+        kind: "systemd-user",
+        unit,
+        result: "failed",
+        messages: [
+          `  ⚠ Could not disable the stale user unit ${unit} (${err instanceof Error ? err.message : String(err)}).`,
+          `    Run it yourself: systemctl --user disable --now ${unit}`,
+        ],
+      };
+    }
+    if (res.code !== 0) {
+      const detail = res.stderr.trim() || res.stdout.trim() || "unknown error";
+      return {
+        short,
+        kind: "systemd-user",
+        unit,
+        result: "failed",
+        messages: [
+          `  ⚠ Could not disable the stale user unit ${unit} (${detail}).`,
+          `    Run it yourself: systemctl --user disable --now ${unit}`,
+        ],
+      };
+    }
+    return {
+      short,
+      kind: "systemd-user",
+      unit,
+      result: "disabled",
+      messages: [
+        `  ✓ Disabled stale ${unit} (it was fighting the supervised hub for ${short}'s port).`,
+      ],
+    };
+  }
+
+  // --- SYSTEM scope: detect-only + warn (no sudo in migrate). ---
+  if (systemdUnitEnabled(unit, [], deps)) {
+    return {
+      short,
+      kind: "systemd-system",
+      unit,
+      result: "warn-system",
+      messages: [
+        `  ⚠ A SYSTEM-level ${unit} is enabled and may fight the supervised hub for ${short}'s port.`,
+        "    Migrate can't disable a system unit (it needs root). Disable it yourself:",
+        `      sudo systemctl disable --now ${unit}`,
+      ],
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * `systemctl [--user] is-enabled <unit>` → true iff the printed token means the
+ * unit will autostart (see `SYSTEMD_ENABLED_TOKENS`). `is-enabled` exits nonzero
+ * for non-enabled states and prints the token to stdout regardless of exit, so
+ * we classify from the stdout token. A throw (ENOENT/quirk) → treated as
+ * not-enabled (non-fatal; the sweep continues).
+ */
+function systemdUnitEnabled(unit: string, scope: string[], deps: ManagedUnitDeps): boolean {
+  let res: { code: number; stdout: string; stderr: string };
+  try {
+    res = deps.run(["systemctl", ...scope, "is-enabled", unit]);
+  } catch {
+    return false;
+  }
+  const token = res.stdout.trim() || res.stderr.trim();
+  if (token.length === 0) return false;
+  // `is-enabled` can print the token then a hint on a second line; read line 1.
+  const first = token.split("\n")[0]?.trim() ?? "";
+  return SYSTEMD_ENABLED_TOKENS.has(first);
+}