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

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/operator-token.ts

@@ -30,7 +30,12 @@ import type { Database } from "bun:sqlite";
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { configDir } from "./config.ts";
+import { EXPOSE_STATE_PATH, readExposeState } from "./expose-state.ts";
+import { validateHostAdminToken } from "./host-admin-token-validation.ts";
+import { readHubPort } from "./hub-control.ts";
+import { HUB_UNIT_DEFAULT_PORT } from "./hub-unit.ts";
 import { recordTokenMint, signAccessToken, validateAccessToken } from "./jwt-sign.ts";
+import { buildHubBoundOrigins } from "./origin-check.ts";
 import { isLoopbackOrigin } from "./vault-hub-origin-env.ts";
 
 export const OPERATOR_TOKEN_FILENAME = "operator.token";
@@ -279,7 +284,14 @@ export class OperatorTokenExpiredError extends Error {
 }
 
 export interface UseOperatorTokenOpts {
-  /** Hub origin used as `iss` validator. Required. */
+  /**
+   * Hub origin the caller resolved. Required. As of hub#516 this is a SEED of
+   * the known-issuer SET the token's `iss` is validated against
+   * ({@link buildKnownIssuersForOperatorToken}), not the sole `iss` validator —
+   * so a caller that resolves loopback (`status`) still accepts a public-`iss`
+   * operator token from `expose-state.json`, and vice versa. It also remains
+   * the `iss` stamped on an auto-rotated re-mint.
+   */
   issuer: string;
   /** configDir override (where operator.token lives). Defaults to `configDir()`. */
   configDir?: string;
@@ -345,9 +357,78 @@ export interface UsedOperatorToken {
   status: RotationStatus;
 }
 
+/**
+ * Compose the Fly.io default public origin from `FLY_APP_NAME`, mirroring the
+ * server-side `flyDefaultOrigin` (hub-server.ts) so the client-side
+ * known-issuer set matches the origin the hub stamps tokens with on Fly. Kept
+ * local (a one-liner) rather than imported to avoid pulling hub-server.ts /
+ * serve.ts into the CLI auth path. Fly slugs never contain `/`; anything with
+ * one is spoofed or malformed.
+ */
+function flyDefaultOrigin(env: NodeJS.ProcessEnv): string | undefined {
+  const app = env.FLY_APP_NAME;
+  if (typeof app !== "string" || app.length === 0 || app.includes("/")) return undefined;
+  return `https://${app}.fly.dev`;
+}
+
+/**
+ * Assemble the SET of origins this hub legitimately answers on, from on-disk
+ * client state — the client-side mirror of hub-server.ts's per-request
+ * `buildHubBoundOrigins` call (hub#516). The operator token's `iss` is
+ * validated against this set rather than a single issuer, so a token whose
+ * `iss` is the hub's PUBLIC origin (stamped after `parachute expose`) is
+ * accepted even when the CLI command resolved a loopback `issuer` (the
+ * `status` case) — and vice versa.
+ *
+ * The set is:
+ *   - `seedIssuer` — the issuer the caller resolved (loopback for `status`,
+ *     `r.hubOrigin` / public for lifecycle). Kept as a seed so callers that
+ *     pass a value still contribute it; never the sole gate.
+ *   - loopback aliases — `http://127.0.0.1:<port>` AND `http://localhost:<port>`
+ *     for the hub's port (`readHubPort(configDir) ?? HUB_UNIT_DEFAULT_PORT`),
+ *     matching the hub's own loopback alias set (`buildHubBoundOrigins`).
+ *   - the expose-state public origin — `expose-state.json`'s `hubOrigin`, the
+ *     public URL the hub stamps on tokens once exposed.
+ *   - the platform/env public origin — `PARACHUTE_HUB_ORIGIN` ∪
+ *     `RENDER_EXTERNAL_URL` ∪ the composed Fly default — for container deploys
+ *     where the public origin comes from the platform, not expose-state.
+ *
+ * Provenance is NOT established here: `validateHostAdminToken` runs the JWKS
+ * signature check FIRST and unconditionally. This set is the belt-and-suspenders
+ * `iss` allowlist layered on top — a foreign `iss` (not loopback / expose /
+ * env) is rejected, and an empty set fails closed.
+ */
+export function buildKnownIssuersForOperatorToken(
+  configDirOverride: string | undefined,
+  seedIssuer: string,
+): readonly string[] {
+  const dir = configDirOverride ?? configDir();
+  const loopbackPort = readHubPort(dir) ?? HUB_UNIT_DEFAULT_PORT;
+  let exposeHubOrigin: string | undefined;
+  try {
+    exposeHubOrigin = readExposeState(join(dir, "expose-state.json"))?.hubOrigin;
+  } catch {
+    // A malformed expose-state.json must never lock the operator out of the
+    // CLI — the seed issuer + loopback aliases already cover legitimate
+    // loopback access; treat it as "no public origin known."
+    exposeHubOrigin = undefined;
+  }
+  const platformOrigin =
+    process.env.PARACHUTE_HUB_ORIGIN ??
+    process.env.RENDER_EXTERNAL_URL ??
+    flyDefaultOrigin(process.env);
+  return buildHubBoundOrigins({
+    issuer: seedIssuer,
+    loopbackPort,
+    ...(exposeHubOrigin !== undefined ? { exposeHubOrigin } : {}),
+    ...(platformOrigin !== undefined ? { platformOrigin } : {}),
+  });
+}
+
 /**
  * The canonical "use the operator token in a CLI flow" helper. Reads
- * `~/.parachute/operator.token`, validates against `db` + `issuer`, and:
+ * `~/.parachute/operator.token`, validates against `db` + the hub's
+ * known-issuer SET, and:
  *
  *   - If the token has fully expired: throws `OperatorTokenExpiredError`
  *     with an actionable message. Does NOT auto-rotate from a dead token —
@@ -397,9 +478,19 @@ export async function useOperatorTokenWithAutoRotate(
   if (!token) return null;
   const now = opts.now ?? (() => new Date());
 
-  // Validation failures (signature mismatch, wrong issuer, missing kid,
-  // expired-by-jose) bubble out for the caller to render the right message.
-  const validated = await validateAccessToken(db, token, opts.issuer);
+  // Validate against the hub's KNOWN-ISSUER SET, not a single `opts.issuer`
+  // (hub#516). The operator token is the hub's OWN self-issued credential; its
+  // `iss` is the hub's loopback origin before `expose` and its PUBLIC origin
+  // after. Callers resolve `opts.issuer` inconsistently — `status` hardcodes
+  // loopback, lifecycle uses `r.hubOrigin` (public when exposed) — so a single
+  // per-issuer check rejected the public-`iss` operator token on `status` even
+  // though `restart` worked. `validateHostAdminToken` (the #517 helper) gates
+  // on the JWKS SIGNATURE first+unconditionally (provenance), then accepts the
+  // `iss` if it's ANY origin the hub legitimately answers on. Validation
+  // failures (signature mismatch, missing kid, expired-by-jose, revoked, or an
+  // `iss` foreign to the whole set) bubble out for the caller to render.
+  const knownIssuers = buildKnownIssuersForOperatorToken(opts.configDir, opts.issuer);
+  const validated = await validateHostAdminToken(db, token, knownIssuers);
   const { payload } = validated;
 
   const exp = typeof payload.exp === "number" ? payload.exp : 0;

package/src/origin-check.ts

@@ -74,6 +74,16 @@ export function buildHubBoundOrigins(opts: {
       // Malformed URL — skip.
     }
   };
+  // `opts.issuer` is the PER-REQUEST issuer, which `resolveIssuer` derives
+  // from the request's Host header (hub-server.ts, "closes #245"). Including a
+  // Host-derived value in the known-issuers set is SAFE — it is NOT a
+  // forged-`iss` bypass. Token provenance is signature-gated: the JWKS verify
+  // in `validateAccessToken` / `validateHostAdminToken` runs UNCONDITIONALLY
+  // FIRST, before `iss` is ever checked against this set. So a token whose
+  // `iss` matches an attacker-injected Host (and thus lands in this set) but
+  // which isn't signed by THIS hub's key is still rejected at the signature
+  // step. The known-issuers membership check is belt-and-suspenders layered on
+  // top of the signature gate, never a substitute for it.
   add(opts.issuer);
   add(opts.exposeHubOrigin);
   add(opts.platformOrigin);

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