@moondeck/station 0.0.1 → 1.0.1

package/lib/legacy-host.ts

@@ -0,0 +1,769 @@
+/**
+ * The frozen `@runuai/host` on the same machine as a Moondeck Station
+ * (Moondeck migration plan §4: hosts move by hand, with a fresh enrollment).
+ *
+ * Two things live here:
+ *
+ * - `legacyHostRunningReason`: a station refuses to start while the old host
+ *   runs. Both drive the same container runtime, and the old host's cleanup
+ *   reaps containers it does not know, so two daemons would remove each
+ *   other's task containers.
+ * - `uninstallLegacyHost`: `moondeck-station uninstall-legacy`. It removes
+ *   the old service, runtime and `uai-host` commands, and the old host's
+ *   leftover Docker task stacks. It runs the old host's OWN `uninstall`
+ *   first (its service and Apple-runtime teardown), and falls back to
+ *   removing the known paths only with `--force`. It never touches the old
+ *   data home (`~/.uai`) unless `--purge` is given, and refuses unless
+ *   `--force` while the old host may still run tasks.
+ *
+ * What makes handing off to the old uninstall safe: a station names and
+ * labels every container, image and volume it creates differently from the
+ * old host (`io.moondeck.*`, `moondeck-*`), so the old host's teardown,
+ * which proves ownership by its own names and labels, can never select one
+ * of the station's (lib/frozen-apple-uninstall-teardown.test.ts runs 0.9.173's
+ * own teardown against a station's Apple objects). The old command runs only
+ * when it really is `@runuai/host` (symlinks resolved), and with an
+ * environment of its own, so it can't be pointed at the station's data.
+ *
+ * Everything that touches the machine goes through `LegacyHostSeams`, so the
+ * decisions are unit-tested without a second host.
+ */
+
+import path from "node:path";
+
+import { LEGACY_HOST, STATION } from "../src/station-identity";
+import { STATION_FIRST_VERSION } from "./release-feed";
+import { shellQuote } from "./machine-exec";
+import { userBusEnv, withUserBusEnv, type UserBusProbe } from "./user-bus-env";
+
+/**
+ * Docker labels the frozen host puts on what it creates outside a Compose
+ * task stack. Its Compose stacks carry no label of its own, only Compose's
+ * `com.docker.compose.project=task-<id>`.
+ */
+export const LEGACY_DOCKER_LABELS: readonly string[] = Object.freeze([
+  "com.uai.task",
+  "com.uai.maintenance",
+  "com.uai.machine",
+  "com.runuai.preview-sidecar.task",
+  "com.runuai.engine-login",
+]);
+/** Every label a station puts on what it creates starts with this. */
+export const STATION_LABEL_PREFIX = "io.moondeck.";
+const COMPOSE_PROJECT_LABEL = "com.docker.compose.project";
+/**
+ * The Compose project the old host gives a task: `task-` and the cloud's
+ * task id, a lower-case ULID (lib/ulid.ts newId; compose_project_for_task in
+ * scripts/agent/_common.sh). The shape alone proves nothing (any project can
+ * be called that): a stack is the old host's only when its id is also in the
+ * old host's own task store, or, when that store can't be read, with --force.
+ */
+const LEGACY_TASK_PROJECT = /^task-([0-7][0-9abcdefghjkmnpqrstvwxyz]{25})$/;
+
+/** The environment variables an old-host command inherits; nothing else. */
+const INHERITED_ENV = ["PATH", "USER", "LOGNAME", "LANG", "LC_ALL", "TMPDIR", "SHELL", "TERM"] as const;
+
+export interface ExecResult {
+  readonly status: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface LegacyHostSeams {
+  readonly home: string;
+  readonly platform: NodeJS.Platform;
+  readonly uid: number;
+  /** This process's environment, filtered before an old-host command sees it. */
+  readonly inheritedEnv?: NodeJS.ProcessEnv;
+  /**
+   * Finds the user's service-manager bus when the environment lacks it, for
+   * every `systemctl --user` here and the old uninstall (lib/user-bus-env.ts).
+   */
+  readonly userBus?: UserBusProbe;
+  /** `env` given: the command gets exactly that environment. */
+  exec(command: string, args: readonly string[], env?: Readonly<Record<string, string>>): ExecResult;
+  /** GET a loopback JSON endpoint with a short timeout; throws on any failure. */
+  fetchJson(url: string): Promise<unknown>;
+  exists(target: string): boolean;
+  readText(target: string): string | null;
+  /** `rm -rf`. */
+  remove(target: string): void;
+  /** The first `command` on PATH, or null. */
+  which(command: string): string | null;
+  /**
+   * The task ids in the old host's own task store (`~/.uai/data/host.sqlite`,
+   * `uai_host_tasks`), read only. Null when it is absent or can't be read.
+   */
+  readLegacyTaskIds?(): ReadonlySet<string> | null;
+  /**
+   * The npm package `command` runs, symlinks resolved: for a managed runtime
+   * launcher (`<generation>/bin/<command>`) the generation's
+   * `agent/package.json`, otherwise the nearest package.json above it.
+   */
+  packageNameOf(command: string): string | null;
+  /**
+   * The command line of a running process (`ps -o command= -p <pid>`), or
+   * null when it can't be read. How an answering daemon is identified by the
+   * package it runs, not by the port it answers on.
+   */
+  processCommandOf?(pid: number): string | null;
+  log(line: string): void;
+}
+
+export interface LegacyHostState {
+  /** launchd plist or systemd unit file of the old service, when present. */
+  readonly serviceDefinition: string | null;
+  /**
+   * The service manager has the old job loaded (launchd) or active (systemd),
+   * or gave no clear answer about an installed one (see serviceError).
+   */
+  readonly serviceActive: boolean;
+  /** The service manager's error when it gave no clear answer; the service then counts as active. */
+  readonly serviceError: string | null;
+  /** How this OS's service manager names the old service. */
+  readonly serviceName: string;
+  /** The old daemon answered on its local port. */
+  readonly daemon: {
+    readonly port: number;
+    readonly pid: number;
+    readonly version: string | null;
+    /** null: the daemon answered /api/status but its task list could not be read. */
+    readonly activeTasks: number | null;
+  } | null;
+  /** `~/.uai-host`, when present. */
+  readonly runtimeRoot: string | null;
+  /** The old managed shims in ~/.local/bin that exist. */
+  readonly shims: readonly string[];
+  /** The command to run the old host's own uninstall with, when one exists. */
+  readonly command: string | null;
+  /** `~/.uai`, when present. */
+  readonly dataHome: string | null;
+}
+
+export function legacyHostPaths(home: string) {
+  const localBin = path.join(home, ".local", "bin");
+  const runtimeRoot = path.join(home, LEGACY_HOST.runtimeDirName);
+  return {
+    runtimeRoot,
+    managedCommand: path.join(runtimeRoot, "runtime", "current", "bin", LEGACY_HOST.command),
+    shims: [
+      path.join(localBin, LEGACY_HOST.command),
+      path.join(localBin, LEGACY_HOST.recoveryCommand),
+    ],
+    dataHome: path.join(home, LEGACY_HOST.homeDirName),
+    portFile: path.join(home, LEGACY_HOST.homeDirName, "data", "host.port"),
+    launchdPlist: path.join(home, "Library", "LaunchAgents", `${LEGACY_HOST.launchdLabel}.plist`),
+    systemdUnit: path.join(home, ".config", "systemd", "user", LEGACY_HOST.systemdUnit),
+  };
+}
+
+/**
+ * Whether the service manager runs the old service. Only a clear "not
+ * running" answer counts as stopped: launchd's "could not find service", or
+ * systemd's `inactive` / `failed` / `unknown` (an unknown unit). Any other
+ * failure (an unreachable bus, access denied, a crash) leaves the state
+ * unknown, and an installed old service then counts as running (fail closed),
+ * with the manager's error kept for the refusal. Without the old service's
+ * definition the old host never ran under that manager, so an error there is
+ * no evidence (a hand-started daemon is caught by daemonState).
+ */
+function serviceState(seams: LegacyHostSeams): { definition: string | null; active: boolean; error: string | null } {
+  const paths = legacyHostPaths(seams.home);
+  const unknown = (definition: string | null, probe: ExecResult, call: string) => {
+    if (definition === null) return { definition, active: false, error: null };
+    const detail = probe.stderr.trim() || probe.stdout.trim() || (probe.status === null ? "no exit status" : `exit ${probe.status}`);
+    return { definition, active: true, error: `${call}: ${detail}` };
+  };
+  if (seams.platform === "darwin") {
+    const definition = seams.exists(paths.launchdPlist) ? paths.launchdPlist : null;
+    const target = `gui/${seams.uid}/${LEGACY_HOST.launchdLabel}`;
+    const probe = seams.exec("launchctl", ["print", target]);
+    // KeepAlive job: loaded means running, or about to be restarted.
+    if (probe.status === 0) return { definition, active: true, error: null };
+    if (probe.status === 113 || /Could not find (service|domain)/.test(probe.stderr)) {
+      return { definition, active: false, error: null };
+    }
+    return unknown(definition, probe, `launchctl print ${target}`);
+  }
+  if (seams.platform === "linux") {
+    const definition = seams.exists(paths.systemdUnit) ? paths.systemdUnit : null;
+    const probe = seams.exec("systemctl", ["--user", "is-active", LEGACY_HOST.systemdUnit], systemctlEnv(seams));
+    const state = probe.status === null ? "" : probe.stdout.trim();
+    if (["active", "activating", "deactivating", "reloading", "refreshing"].includes(state)) {
+      return { definition, active: true, error: null };
+    }
+    if (probe.status !== 0 && ["inactive", "failed", "unknown"].includes(state)) {
+      return { definition, active: false, error: null };
+    }
+    return unknown(definition, probe, `systemctl --user is-active ${LEGACY_HOST.systemdUnit}`);
+  }
+  return { definition: null, active: false, error: null };
+}
+
+/**
+ * The environment for `systemctl --user`: this process's own, with the
+ * user-bus variables filled in when it lacks them. Undefined (inherit) when
+ * the seams carry no probe.
+ */
+function systemctlEnv(seams: LegacyHostSeams): Record<string, string> | undefined {
+  return seams.userBus ? withUserBusEnv(seams.inheritedEnv ?? {}, seams.userBus) : undefined;
+}
+
+async function daemonState(seams: LegacyHostSeams): Promise<LegacyHostState["daemon"]> {
+  const raw = seams.readText(legacyHostPaths(seams.home).portFile)?.trim();
+  if (!raw || !/^\d{1,5}$/.test(raw)) return null;
+  return probeDaemon(seams, Number(raw));
+}
+
+/** The old daemon answering on `port`, or null. */
+/**
+ * Whether the host answering on the old host's port is the old host. In
+ * order:
+ * 1. It says it's a station: its status names `@moondeck/station` as its
+ *    product. The frozen host never reports a product.
+ * 2. Its process says: the package the answering pid runs (its command line,
+ *    resolved to the nearest package.json). `@moondeck/station` is a station,
+ *    `@runuai/host` the old host.
+ * 3. Neither is known: the frozen host's own numbering decides. Every
+ *    `@runuai/host` release is below 1.0.0 and no station is (the release
+ *    floor, STATION_FIRST_VERSION), so a version below it, or none at all,
+ *    is the old host, and anything else is not.
+ */
+function isLegacyDaemon(seams: LegacyHostSeams, status: { pid: number; product?: unknown }, version: string | null): boolean {
+  if (status.product === STATION.packageName) return false;
+  const owner = daemonPackage(seams, status.pid);
+  if (owner === STATION.packageName) return false;
+  if (owner === LEGACY_HOST.packageName) return true;
+  return version === null || versionBelow(version, STATION_FIRST_VERSION);
+}
+
+/** The package an answering pid runs, read from its command line. */
+function daemonPackage(seams: LegacyHostSeams, pid: number): string | null {
+  const command = seams.processCommandOf?.(pid);
+  if (!command) return null;
+  for (const token of command.split(/\s+/)) {
+    if (!path.isAbsolute(token)) continue;
+    const name = seams.packageNameOf(token);
+    if (name === STATION.packageName || name === LEGACY_HOST.packageName) return name;
+  }
+  return null;
+}
+
+/** a < b for dotted numeric versions (a pre-release or junk counts as below). */
+function versionBelow(a: string, b: string): boolean {
+  const parse = (v: string) => (/^\d+\.\d+\.\d+$/.test(v) ? v.split(".").map(Number) : null);
+  const left = parse(a);
+  const right = parse(b)!;
+  if (left === null) return true;
+  for (let i = 0; i < 3; i++) if (left[i] !== right[i]) return left[i]! < right[i]!;
+  return false;
+}
+
+async function probeDaemon(seams: LegacyHostSeams, port: number): Promise<LegacyHostState["daemon"]> {
+  if (port < 1 || port > 65_535) return null;
+  let status: unknown;
+  try {
+    status = await seams.fetchJson(`http://127.0.0.1:${port}/api/status`);
+  } catch {
+    return null;
+  }
+  // A stale port file can name an unrelated process: only a host's status
+  // shape counts (the same test the installer's probe_local_host applies).
+  if (
+    !status ||
+    typeof status !== "object" ||
+    typeof (status as { pid?: unknown }).pid !== "number" ||
+    typeof (status as { hostId?: unknown }).hostId !== "string"
+  ) {
+    return null;
+  }
+  const version = (status as { version?: unknown }).version;
+  // Blocker #3 (2026-11-03): after a migration ~/.uai/data/host.port can still
+  // name 5876, where the STATION now answers with a host's status shape, so a
+  // station counted as the old host: --check exited 78 and every installer
+  // re-run refused. Only a positively identified old host counts.
+  if (!isLegacyDaemon(seams, status as { pid: number; product?: unknown }, typeof version === "string" ? version : null)) {
+    return null;
+  }
+  let activeTasks: number | null = null;
+  try {
+    const tasks = (await seams.fetchJson(`http://127.0.0.1:${port}/api/tasks`)) as {
+      tasks?: unknown;
+    };
+    if (Array.isArray(tasks?.tasks)) activeTasks = tasks.tasks.length;
+  } catch {
+    activeTasks = null;
+  }
+  return {
+    port,
+    pid: (status as { pid: number }).pid,
+    version: typeof version === "string" ? version : null,
+    activeTasks,
+  };
+}
+
+export async function inspectLegacyHost(seams: LegacyHostSeams): Promise<LegacyHostState> {
+  const paths = legacyHostPaths(seams.home);
+  const service = serviceState(seams);
+  return {
+    serviceDefinition: service.definition,
+    serviceActive: service.active,
+    serviceError: service.error,
+    serviceName: seams.platform === "linux" ? LEGACY_HOST.systemdUnit : LEGACY_HOST.launchdLabel,
+    daemon: await daemonState(seams),
+    runtimeRoot: seams.exists(paths.runtimeRoot) ? paths.runtimeRoot : null,
+    shims: paths.shims.filter((shim) => seams.exists(shim)),
+    command: verifiedLegacyCommand(seams, paths.managedCommand) ?? legacyCommandOnPath(seams),
+    dataHome: seams.exists(paths.dataHome) ? paths.dataHome : null,
+  };
+}
+
+/**
+ * `candidate`, only when it exists and really runs `@runuai/host` (symlinks
+ * resolved). A `uai-host` that is anything else, a link to the station's own
+ * launcher above all, is not ours to run `uninstall` on.
+ */
+function verifiedLegacyCommand(seams: LegacyHostSeams, candidate: string | null): string | null {
+  if (!candidate || !seams.exists(candidate)) return null;
+  return seams.packageNameOf(candidate) === LEGACY_HOST.packageName ? candidate : null;
+}
+
+/** `uai-host` on PATH (an npm install), when it is `@runuai/host`'s. */
+function legacyCommandOnPath(seams: LegacyHostSeams): string | null {
+  return verifiedLegacyCommand(seams, seams.which(LEGACY_HOST.command));
+}
+
+/**
+ * What an old-host command runs with: the old defaults (`HOME`, and
+ * `UAI_HOME=~/.uai`) and a few neutral variables, never this process's
+ * `UAI_*`, which name the station's own home and data.
+ */
+export function legacyCommandEnv(
+  home: string,
+  inherited: NodeJS.ProcessEnv = {},
+  userBus?: UserBusProbe,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const name of INHERITED_ENV) {
+    const value = inherited[name];
+    if (value) env[name] = value;
+  }
+  // The old uninstall stops its service with `systemctl --user`, which needs
+  // the user's bus (2026-11-01 rehearsal: "Failed to connect to bus").
+  Object.assign(env, userBusEnv(inherited, userBus ?? { uid: -1, stat: () => null }));
+  env.HOME = home;
+  env.UAI_HOME = path.join(home, LEGACY_HOST.homeDirName);
+  return env;
+}
+
+export function legacyHostPresent(state: LegacyHostState): boolean {
+  return Boolean(
+    state.serviceDefinition ||
+      state.serviceActive ||
+      state.daemon ||
+      state.runtimeRoot ||
+      state.shims.length > 0 ||
+      state.command,
+  );
+}
+
+/** Why a station must not start now, or null when the old host is not running. */
+export function legacyHostRunningReason(state: LegacyHostState): string | null {
+  if (!state.serviceActive && !state.daemon) return null;
+  const what = state.daemon
+    ? `the old Uai host${state.daemon.version ? ` ${state.daemon.version}` : ""} is running on this machine (port ${state.daemon.port})`
+    : state.serviceError
+      ? `the old Uai host service (${state.serviceDefinition ?? state.serviceName}) is installed and the service manager ` +
+        `can't say it is stopped (${state.serviceError}), so it counts as running`
+      : `the old Uai host service (${state.serviceDefinition ?? state.serviceName}) is still loaded on this machine`;
+  return (
+    `${what}. Both would manage the same containers and remove each other's tasks. ` +
+    `Move this machine first: ${STATION.command} uninstall-legacy`
+  );
+}
+
+/** The old host's bundled Apple container CLI (ADR-106), in its runtime. */
+export function legacyAppleContainerCli(home: string): string {
+  return path.join(
+    legacyHostPaths(home).runtimeRoot,
+    "runtime", "current", "agent", "bundled-runtime", "apple-container", "bin", "container",
+  );
+}
+
+/** What the old host's uninstall says when its Apple teardown can't prove a
+ *  container gone (src/cli.ts there): it stops, keeping its runtime. */
+const APPLE_TEARDOWN_INCOMPLETE = /Apple container teardown is incomplete/;
+
+/**
+ * The refusal for an old-host uninstall stopped by its Apple teardown. The
+ * smoke test of 2026-11-02 hit it: a stopped maintenance container from
+ * August, under an Apple container system still running an older host's
+ * build, stayed listed after `delete` exited 0. The old uninstall stops
+ * before removing its runtime, so retrying is safe; `--force` would delete
+ * that runtime, the only CLI that tears those containers down, and leave them
+ * and their images behind for good. So the way out it names is a restart of
+ * the Apple container system and a retry, with --force last and its cost
+ * stated. Nothing here changes what the teardown does.
+ */
+function appleTeardownRemedy(command: string, detail: string, cli: string, output: string, force: string): string {
+  const ids = [...new Set([...output.matchAll(/container (\S+) could not be proven removed/g)].map((match) => match[1]!))];
+  const quoted = `'${cli.replace(/'/g, "'\\''")}'`;
+  return [
+    `${command} uninstall failed: ${detail || "Apple container teardown is incomplete"}.`,
+    "The old host could not prove one of its Apple containers removed, so its uninstall stopped before removing its runtime. " +
+      "Its service is already stopped. Retrying is safe: run the same command again, without --force.",
+    "First restart the Apple container system with the old host's own CLI, and remove the container:",
+    `  C=${quoted}`,
+    '  "$C" list --all',
+    '  "$C" system stop && "$C" system start',
+    ...(ids.length > 0 ? ids.map((id) => `  "$C" delete --force ${id}`) : ['  "$C" delete --force <container id>']),
+    `If it still won't go: ${force} removes the old host's files without that teardown. ` +
+      "Its Apple containers and images then stay behind, with no tool left that removes them.",
+  ].join("\n");
+}
+
+export interface UninstallLegacyOptions {
+  readonly purge: boolean;
+  readonly force: boolean;
+  readonly dryRun: boolean;
+  /**
+   * The command a refusal tells the operator to run to go ahead anyway. The
+   * installer passes its own pipeline (`moondeck-station` isn't on PATH
+   * yet); otherwise `moondeck-station uninstall-legacy --force [--purge]`.
+   */
+  readonly forceCommand?: string;
+}
+
+/** What a refusal tells the operator to run to remove the old host anyway. */
+export function uninstallLegacyForceCommand(options: Pick<UninstallLegacyOptions, "purge" | "forceCommand">): string {
+  return options.forceCommand ?? `${STATION.command} uninstall-legacy --force${options.purge ? " --purge" : ""}`;
+}
+
+export type UninstallLegacyResult =
+  | { readonly outcome: "absent" }
+  | { readonly outcome: "refused"; readonly reason: string }
+  | { readonly outcome: "removed"; readonly steps: readonly string[]; readonly notes: readonly string[] };
+
+const refused = (reason: string): UninstallLegacyResult => ({ outcome: "refused", reason });
+
+export async function uninstallLegacyHost(
+  seams: LegacyHostSeams,
+  options: UninstallLegacyOptions,
+): Promise<UninstallLegacyResult> {
+  const force = uninstallLegacyForceCommand(options);
+  const state = await inspectLegacyHost(seams);
+  // Nothing is removed, Docker objects included, unless the old host is
+  // installed here: a task-shaped name or label alone is no install.
+  if (!legacyHostPresent(state) && !state.dataHome) {
+    return { outcome: "absent" };
+  }
+  // Read before anything runs: the old uninstall's --purge deletes the store.
+  const taskIds = seams.readLegacyTaskIds?.() ?? null;
+  const docker = legacyDockerObjects(seams, taskIds);
+  // Tasks must be ruled out before anything is removed, unless --force.
+  if (!options.force) {
+    if (state.daemon && state.daemon.activeTasks === null) {
+      return refused(
+        "the old Uai host is running but its task list could not be read; stop its tasks in the app, " +
+          `or remove it anyway (running tasks are lost): ${force}`,
+      );
+    }
+    if (state.daemon && state.daemon.activeTasks! > 0) {
+      return refused(
+        `the old Uai host has ${state.daemon.activeTasks} running task(s); finish or stop them in the app, ` +
+          `or remove it anyway (their work is lost): ${force}`,
+      );
+    }
+    // The service manager can't say whether the old service runs, and its
+    // daemon doesn't answer: the old uninstall would hit the same error, and
+    // its tasks can't be ruled out.
+    if (state.serviceError && !state.daemon) {
+      return refused(
+        `the service manager can't say whether the old Uai host service is running (${state.serviceError}), ` +
+          `so its tasks can't be ruled out; fix that and retry, or remove it anyway (running tasks are lost): ${force}`,
+      );
+    }
+    // An active service nobody can ask: neither its daemon answers nor is
+    // there an old uninstall (which refuses on its own running tasks).
+    if (state.serviceActive && !state.daemon && !state.command) {
+      return refused(
+        "the old Uai host service is running but neither answers nor can be asked to uninstall itself, " +
+          `so its tasks can't be ruled out; to remove it anyway (running tasks are lost): ${force}`,
+      );
+    }
+    // Unverified ones included: a running task-<id> stack may be a live task.
+    const running = docker.objects.filter((object) => object.kind === "container" && object.running);
+    if (running.length > 0) {
+      return refused(
+        `${running.length} of the old Uai host's task container(s) are still running (${running.map((o) => o.name).join(", ")}); finish or stop those tasks, ` +
+          `or remove them anyway (their work is lost): ${force}`,
+      );
+    }
+  }
+
+  // A task-shaped stack the store can't vouch for goes only with --force,
+  // and is decided before anything else: once the old install and its data
+  // are gone, nothing would recognise it as the old host's any more.
+  const unverified = docker.objects.filter((o) => o.evidence === "unverified");
+  if (unverified.length > 0 && !options.force) {
+    return refused(
+      `the old Uai host's task store could not be read, so ${unverified.length} Docker object(s) named like its tasks ` +
+        `can't be confirmed as its own: ${unverified.map((o) => o.name).join(", ")}. Nothing was changed. ` +
+        `If they are the old host's, run: ${force}`,
+    );
+  }
+
+  const steps: string[] = [];
+  const notes: string[] = [];
+  const run = (command: string, args: readonly string[], env?: Record<string, string>): ExecResult | null => {
+    steps.push([command, ...args].join(" "));
+    if (options.dryRun) return null;
+    return seams.exec(command, args, env);
+  };
+  const remove = (target: string) => {
+    steps.push(`rm -rf ${target}`);
+    if (!options.dryRun) seams.remove(target);
+  };
+
+  // A daemon that answers without a service was started by hand: no
+  // uninstall stops it, and its port file (in ~/.uai) is how a station sees
+  // it. So ~/.uai is purged only once no old daemon answers (step 5).
+  const handStarted = Boolean(state.daemon && !state.serviceActive);
+
+  // 1. The old host's own uninstall: its service teardown (and, on macOS,
+  //    the Apple container runtime it provisioned) is code it already ships.
+  let delegated = false;
+  if (state.command) {
+    const purgeHere = options.purge && !handStarted;
+    const result = run(
+      state.command,
+      ["uninstall", ...(purgeHere ? ["--purge"] : [])],
+      legacyCommandEnv(seams.home, seams.inheritedEnv, seams.userBus),
+    );
+    delegated = result === null || result.status === 0;
+    if (!delegated) {
+      const detail = (result?.stderr || result?.stdout || "").trim().split("\n").at(-1) ?? "";
+      if (!options.force) {
+        const output = `${result?.stderr ?? ""}\n${result?.stdout ?? ""}`;
+        if (seams.platform === "darwin" && APPLE_TEARDOWN_INCOMPLETE.test(output)) {
+          return refused(appleTeardownRemedy(state.command, detail, legacyAppleContainerCli(seams.home), output, force));
+        }
+        return refused(
+          `${state.command} uninstall failed${detail ? `: ${detail}` : ""}. ` +
+            `Fix that and retry, or remove the old service and runtime directly: ${force}`,
+        );
+      }
+      notes.push(`the old host's own uninstall failed (${detail || "no output"}); removed its files directly`);
+    }
+  }
+
+  // 2. Whatever the old uninstall did not remove (or there was no command to
+  //    run it with): the service definition, the runtime root, the shims.
+  //    Each is checked again, because a successful delegated uninstall
+  //    already removed them.
+  const after = delegated && !options.dryRun ? await inspectLegacyHost(seams) : state;
+  if (after.serviceActive || after.serviceDefinition) {
+    if (seams.platform === "darwin") {
+      run("launchctl", ["bootout", `gui/${seams.uid}/${LEGACY_HOST.launchdLabel}`]);
+    } else if (seams.platform === "linux") {
+      run("systemctl", ["--user", "disable", "--now", LEGACY_HOST.systemdUnit], systemctlEnv(seams));
+    }
+    if (after.serviceDefinition) remove(after.serviceDefinition);
+    if (seams.platform === "linux") run("systemctl", ["--user", "daemon-reload"], systemctlEnv(seams));
+  }
+  if (after.runtimeRoot) remove(after.runtimeRoot);
+  for (const shim of after.shims) remove(shim);
+
+  // 3. The old host's Docker objects, never anything carrying a station
+  //    label. Containers first; a network goes once nothing is attached.
+  for (const object of docker.objects.filter((o) => o.kind === "container")) {
+    run("docker", ["rm", "--force", object.id]);
+  }
+  for (const object of docker.objects.filter((o) => o.kind === "network")) {
+    const result = run("docker", ["network", "rm", object.id]);
+    if (result && result.status !== 0) notes.push(`could not remove the old host's network ${object.name}`);
+  }
+  if (docker.unclaimed.length > 0) {
+    notes.push(
+      `left ${docker.unclaimed.length} task-shaped Docker object(s) the old host's task store does not name: ${docker.unclaimed.join(", ")}`,
+    );
+  }
+  if (docker.problem) notes.push(docker.problem);
+
+  // 4. Is an old daemon still answering? On its port file, or on the port it
+  //    answered on before, in case its port file is gone.
+  let still: LegacyHostState["daemon"] = null;
+  if (!options.dryRun) {
+    still = (await inspectLegacyHost(seams)).daemon ?? (state.daemon ? await probeDaemon(seams, state.daemon.port) : null);
+    if (still) {
+      notes.push(
+        `the old host process (pid ${still.pid}) still answers on port ${still.port} outside any service; stop it (kill ${still.pid}) before starting the station`,
+      );
+    }
+  }
+
+  // 5. --purge last, and never under a running old daemon.
+  const dataHome = options.dryRun ? state.dataHome : seams.exists(legacyHostPaths(seams.home).dataHome) ? legacyHostPaths(seams.home).dataHome : null;
+  if (options.purge && dataHome) {
+    if (still) {
+      notes.push(`kept ${dataHome}: the old host is still running from it; stop it, then run uninstall-legacy --purge again`);
+    } else {
+      try {
+        remove(dataHome);
+      } catch (error) {
+        // Old task containers wrote their files as uid 1000; a host user that
+        // isn't 1000 can't delete them (Linux). Say what to run; don't crash.
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "EACCES" && code !== "EPERM") throw error;
+        notes.push(
+          `could not remove all of ${dataHome}: some files belong to another user (written by the old host's task containers); remove them with: ${purgeCommand(dataHome)}`,
+        );
+      }
+    }
+  } else if (!options.purge && dataHome) {
+    notes.push(`kept ${dataHome} (the old host's data); pass --purge to remove it`);
+  }
+
+  const npmCommand = options.dryRun ? null : legacyCommandOnPath(seams);
+  if (npmCommand && !after.shims.includes(npmCommand)) {
+    notes.push(
+      `${npmCommand} is still on PATH (an npm install): remove it with npm uninstall -g ${LEGACY_HOST.packageName}`,
+    );
+  }
+  return { outcome: "removed", steps, notes };
+}
+
+/**
+ * The command a person can paste to remove what --purge couldn't. The path is
+ * one shell word whatever it holds (a space, a quote, a leading dash), and
+ * `--` ends rm's options.
+ */
+export function purgeCommand(target: string): string {
+  return `sudo rm -rf -- ${shellQuote(target)}`;
+}
+
+export interface LegacyDockerObject {
+  readonly kind: "container" | "network";
+  readonly id: string;
+  readonly name: string;
+  readonly running: boolean;
+  /**
+   * Why it is the old host's: one of its own labels (`label`), or a
+   * `task-<id>` stack whose id its task store names (`store`). `unverified`:
+   * a `task-<id>` stack while the store can't be read.
+   */
+  readonly evidence: "label" | "store" | "unverified";
+}
+
+/**
+ * The old host's Docker objects. Never anything with a station label (a
+ * station labels everything it creates `io.moondeck.*`). Positive evidence
+ * only: one of the old host's own labels, or a Compose project
+ * `task-<ULID>` whose id `taskIds` (the old host's task store) names. With no
+ * readable store (`taskIds` null) such a stack is listed `unverified`; with a
+ * store that doesn't name it, it is not listed (`unclaimed`, names only).
+ */
+export function legacyDockerObjects(
+  seams: LegacyHostSeams,
+  taskIds: ReadonlySet<string> | null = null,
+): {
+  objects: LegacyDockerObject[];
+  unclaimed: string[];
+  problem?: string;
+} {
+  if (!seams.which("docker")) return { objects: [], unclaimed: [] };
+  const objects: LegacyDockerObject[] = [];
+  const unclaimed: string[] = [];
+  const problems: string[] = [];
+  const classify = (name: string, labels: ReadonlyMap<string, string>): LegacyDockerObject["evidence"] | null => {
+    for (const key of labels.keys()) if (key.startsWith(STATION_LABEL_PREFIX)) return null;
+    if (LEGACY_DOCKER_LABELS.some((label) => labels.has(label))) return "label";
+    const project = LEGACY_TASK_PROJECT.exec(labels.get(COMPOSE_PROJECT_LABEL) ?? "");
+    if (!project) return null;
+    if (taskIds === null) return "unverified";
+    if (taskIds.has(project[1]!)) return "store";
+    unclaimed.push(name);
+    return null;
+  };
+  const containers = seams.exec("docker", [
+    "ps",
+    "--all",
+    "--no-trunc",
+    "--format",
+    "{{.ID}}\t{{.Names}}\t{{.State}}\t{{.Labels}}",
+  ]);
+  if (containers.status === 0) {
+    for (const line of containers.stdout.split("\n")) {
+      const [id, name, state, labels] = line.split("\t");
+      if (!id || !/^[a-f0-9]{12,64}$/.test(id)) continue;
+      const evidence = classify(name ?? id, parseDockerLabels(labels ?? ""));
+      if (!evidence) continue;
+      const running = state === "running" || state === "restarting" || state === "paused";
+      objects.push({ kind: "container", id, name: name ?? id, running, evidence });
+    }
+  } else {
+    problems.push("could not list Docker containers; the old host's task containers were not checked");
+  }
+  const networks = seams.exec("docker", ["network", "ls", "--no-trunc", "--format", "{{.ID}}\t{{.Name}}\t{{.Labels}}"]);
+  if (networks.status === 0) {
+    for (const line of networks.stdout.split("\n")) {
+      const [id, name, labels] = line.split("\t");
+      if (!id || !/^[a-f0-9]{12,64}$/.test(id)) continue;
+      const evidence = classify(name ?? id, parseDockerLabels(labels ?? ""));
+      if (!evidence) continue;
+      objects.push({ kind: "network", id, name: name ?? id, running: false, evidence });
+    }
+  } else {
+    problems.push("could not list Docker networks; the old host's task networks were not checked");
+  }
+  return problems.length > 0 ? { objects, unclaimed, problem: problems.join("; ") } : { objects, unclaimed };
+}
+
+/** Docker's `{{.Labels}}`: `key=value` pairs joined by commas. */
+export function parseDockerLabels(text: string): Map<string, string> {
+  const labels = new Map<string, string>();
+  for (const pair of text.split(",")) {
+    const at = pair.indexOf("=");
+    if (at > 0) labels.set(pair.slice(0, at).trim(), pair.slice(at + 1));
+  }
+  return labels;
+}
+
+/**
+ * The npm package a command runs, symlinks resolved. A managed runtime's
+ * launcher is a shell script at `<generation>/bin/<command>` beside the
+ * package copy at `<generation>/agent/`; anything else is a package's bin,
+ * owned by the nearest package.json above it. Null when unknown.
+ */
+export function packageNameOfCommand(
+  command: string,
+  fs: { realpath(target: string): string; readText(target: string): string | null },
+): string | null {
+  let real: string;
+  try {
+    real = fs.realpath(command);
+  } catch {
+    return null;
+  }
+  const nameIn = (manifest: string): string | null | undefined => {
+    const text = fs.readText(manifest);
+    if (text === null) return undefined;
+    try {
+      const name = (JSON.parse(text) as { name?: unknown }).name;
+      return typeof name === "string" ? name : null;
+    } catch {
+      return null;
+    }
+  };
+  const directory = path.dirname(real);
+  if (path.basename(directory) === "bin") {
+    const managed = nameIn(path.join(path.dirname(directory), "agent", "package.json"));
+    if (managed !== undefined) return managed;
+  }
+  for (let current = directory; ; current = path.dirname(current)) {
+    const name = nameIn(path.join(current, "package.json"));
+    if (name !== undefined) return name;
+    if (path.dirname(current) === current) return null;
+  }
+}
+