@moondeck/station 0.0.1 → 1.0.1

package/src/cli.ts

@@ -0,0 +1,2585 @@
+#!/usr/bin/env tsx
+/**
+ * `uai-host` CLI (ADR-028). Hand-rolled argv switch — no argparser dependency.
+ *
+ *   run | install | uninstall | start | stop | restart
+ *   status | logs [--follow] | runtime recheck
+ *   enroll <token> | pair <token> | open
+ *
+ * `run` boots the service in-process; the install/start/... family dispatches
+ * to the per-OS installer (scripts/install/{darwin,linux,win}.ts) by
+ * process.platform. `status`/`open` read the local UI's own JSON API.
+ */
+
+// MUST be first: load-env populates process.env from .env.local before any
+// import below pulls in lib/env, which freezes its config snapshot (uaiHome,
+// dataDir, hostKeyPath, …) at module-eval. `./paths` imports lib/env, so
+// without this the `run` path boots before UAI_DATA_DIR/UAI_HOME are loaded and
+// resolves the data dir — and the master key that decrypts every secret store
+// — from the wrong base. (main.ts loads it too, but `await import("./main")`
+// runs far too late.)
+import "./load-env";
+
+import {
+  spawn,
+  spawnSync,
+  type SpawnSyncReturns,
+} from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import Database from "better-sqlite3";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import { parse as parseDotenv } from "dotenv";
+import { ulid } from "ulid";
+
+import {
+  commitPendingEnrollment,
+  discardPendingEnrollment,
+  enrollmentTokenSha256,
+  ensurePendingEnrollment,
+  pendingEnrollmentMatches,
+  pendingEnrollmentPath,
+  removeCommittedPendingEnrollment,
+  writeEnvValuesAtomic,
+  type PendingEnrollment,
+} from "../lib/enrollment-state";
+import { parseHostCloudEndpoint } from "../lib/host-cloud-url";
+import { env } from "../lib/env";
+import {
+  persistTelemetryDisclosure,
+  telemetryNoticeIfActive,
+} from "../lib/obs";
+import {
+  abortManagedRuntimeInstall,
+  acknowledgeManagedRuntimeActivation,
+  acknowledgeManagedRuntimeActivationWithCapabilityFloor,
+  beginManagedRuntimeInstall,
+  completeManagedRuntimeInstall,
+  installManagedRuntimeArchive,
+  managedRuntimeInstallStartupState,
+  managedRuntimePaths,
+  nativeReleasePlatform,
+  reconcileManagedRuntimeActivationWithCapabilityFloor,
+  reconcileManagedRuntimeInstallLifecycle,
+  reconcileManagedRuntimeUninstall,
+  removeManagedRuntime,
+  resolveBundledRuntimeFromEnvironment,
+  rollbackManagedRuntime,
+  runManagedRuntimeInstallIntentMutation,
+  runManagedRuntimeInstallLifecycleMutation,
+  stopManagedRuntimeServiceForInstall,
+  updateManagedRuntime,
+  validateManagedRuntimeSelection,
+  validateProvisionalManagedRuntimeSelection,
+  MANAGED_UPDATE_RESTART_EXIT_CODE,
+  type ManagedServiceDefinitionState,
+  type ManagedServiceManagerState,
+  type ReconcileManagedRuntimeInstallLifecycleOptions,
+} from "../lib/managed-runtime";
+import { PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY } from "../lib/project-env-feature";
+import { teardownAppleRuntimeStateForUninstall } from "../lib/apple-uninstall-teardown";
+import {
+  readRuntimeProviderState,
+  runtimeProviderStatePath,
+} from "../lib/runtime-provider-state";
+import { ManagedActivationWatcher } from "../lib/managed-activation-watcher";
+import { ManagedInstallOwnerWatcher } from "../lib/managed-install-owner-watcher";
+import { ManagedUpdateScheduler } from "../lib/managed-update-scheduler";
+import { PINNED_RELEASE_MANIFEST_KEYS } from "../lib/release-trust";
+import { sidecarMode } from "../lib/sidecar";
+import { systemUserBusProbe } from "../lib/user-bus-env";
+import { LEGACY_HOST, STATION, STATION_DEFAULT_CLOUD_URL } from "./station-identity";
+import { enrollmentNextSteps } from "./enrollment-next-steps";
+import {
+  inspectLegacyHost,
+  legacyHostRunningReason,
+  packageNameOfCommand,
+  uninstallLegacyHost,
+  type LegacyHostSeams,
+} from "../lib/legacy-host";
+
+/**
+ * `run`/`install`/`start` refused because the old host runs here: EX_CONFIG.
+ * Never 3, which a sidecar exits with when its lease is denied (main.ts) and
+ * its unit treats as "stay down" (RestartPreventExitStatus=3).
+ */
+const LEGACY_HOST_RUNNING_EXIT_CODE = 78;
+import {
+  hasActiveHostTasks,
+  hasInFlightHostTaskLifecycle,
+  hasNonTerminalHostTasks,
+} from "../lib/runtime-state";
+import {
+  ENROLLMENT_REPLAY_PROTOCOL_HEADER,
+  ENROLLMENT_REPLAY_PROTOCOL_VERSION,
+} from "./protocol";
+import {
+  envLocalPath,
+  packageVersion,
+  readPersistedHostId,
+  serviceLogPath,
+  uaiHome,
+  uiPortFilePath,
+} from "./paths";
+import {
+  CloudResponse,
+  ContainerRuntimeResponse,
+  StatusResponse,
+  TasksResponse,
+} from "./ui/types";
+import type { InstallContext, Installer } from "../scripts/install/types";
+import { PAYLOAD_AMI_REGIONS } from "../lib/machine-provider-aws";
+
+// --- tiny ANSI (no chalk) ---------------------------------------------------
+
+const useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const paint =
+  (code: number) =>
+  (s: string): string =>
+    useColor ? `\x1b[${code}m${s}\x1b[0m` : s;
+const bold = paint(1);
+const dim = paint(2);
+const red = paint(31);
+const green = paint(32);
+const yellow = paint(33);
+const cyan = paint(36);
+
+// --- dispatch ---------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const dryRun = rest.includes("--dry-run");
+  const follow = rest.includes("--follow") || rest.includes("-f");
+  switch (cmd) {
+    case "run":
+      return cmdRun(rest);
+    case "status":
+      return cmdStatus();
+    case "open":
+      return cmdOpen();
+    case "logs":
+      return cmdLogs(follow);
+    case "runtime":
+      return cmdRuntime(rest);
+    case "tune":
+      return cmdTune();
+    case "aws":
+      if (rest[0] === "setup") return cmdAwsSetup(rest.slice(1));
+      console.error(red("usage: moondeck-station aws setup [--region <region>] [--rotate]"));
+      process.exitCode = 1;
+      return;
+    case "update":
+      return cmdUpdate(rest);
+    case "rollback":
+      return cmdRollback(rest);
+    case "enrollment":
+      return cmdEnrollmentStatus(rest);
+    case "setup":
+      return cmdSetup(rest);
+    case "enroll":
+      return cmdEnroll(rest);
+    case "pair":
+      return cmdPair(rest[0]);
+    case "install":
+      if (!rest.includes("--dry-run") && (await refuseWhileLegacyHostRuns())) return;
+      return cmdInstall(rest);
+    case "start":
+    case "restart":
+      if (!dryRun && (await refuseWhileLegacyHostRuns())) return;
+      return cmdInstaller(cmd, dryRun);
+    case "stop":
+      return cmdInstaller(cmd, dryRun);
+    case "uninstall-legacy":
+      return cmdUninstallLegacy(rest);
+    case "uninstall":
+      return cmdUninstall(rest);
+    case "version":
+    case "-v":
+    case "--version":
+      // A bare version line: the sidecar's prepare step compares it with the
+      // pinned runner version, and any other flag prints the usage instead.
+      console.log(packageVersion());
+      return;
+    case undefined:
+    case "help":
+    case "-h":
+    case "--help":
+      return printHelp();
+    default:
+      console.error(red(`unknown command: ${cmd}`));
+      printHelp();
+      process.exitCode = 1;
+  }
+}
+
+// --- run --------------------------------------------------------------------
+
+function timestampServiceLogs(): void {
+  const stamp = (): string => new Date().toISOString().slice(0, 19);
+  for (const level of ["log", "warn", "error"] as const) {
+    const original = console[level].bind(console);
+    console[level] = (...args: unknown[]) => original(`[${stamp()}]`, ...args);
+  }
+}
+
+async function cmdRun(rest: string[] = []): Promise<void> {
+  // ADR-133 sidecar mode: `uai-host run --task <id>` on the task's own
+  // machine. The flag becomes the environment the rest of the process asks
+  // (lib/sidecar.ts) — set before main.ts loads, since its boot reads it.
+  const sidecarTask = flagValue(rest, "--task");
+  if (sidecarTask) process.env.UAI_SIDECAR_TASK = sidecarTask;
+  // ADR-136 sign-in box: `uai-host run --signin-box` on the small always-on
+  // machine behind the "Uai Cloud" row. Same package, one flag
+  // (lib/signin-box.ts); set before main.ts loads for the same reason.
+  if (rest.includes("--signin-box")) process.env.UAI_SIGNIN_BOX = "1";
+  // A station never runs beside the old host (plan §4). Task-machine and
+  // warm-pool sidecars (UAI_SIDECAR_POOL) and the sign-in box run on cloud
+  // machines, never beside one.
+  if (!sidecarMode() && !rest.includes("--signin-box") && (await refuseWhileLegacyHostRuns())) {
+    return;
+  }
+  // Timestamped service logs: the ADR-106 live smoke burned an hour dating
+  // undated scrollback. Applies to the service process only, not one-shot CLI
+  // commands.
+  timestampServiceLogs();
+  let installState = await managedRuntimeInstallStartupState();
+  if (installState === "attested") {
+    // Attestation is the durable commit decision. A supervisor restart after
+    // that point finishes the service/command journals; it must never enter the
+    // pre-attestation recovery gate or restore the old installation.
+    await reconcileInstallLifecycle(await loadInstaller());
+    installState = "none";
+  }
+  if (installState === "stale") {
+    const outcome = await waitForManagedInstaller();
+    if (outcome === "stopped") return;
+    if (outcome === "restart") {
+      process.exitCode = MANAGED_UPDATE_RESTART_EXIT_CODE;
+      return;
+    }
+    installState = "live";
+  }
+  const runningVersion = packageVersion();
+  const managedPaths = managedRuntimePaths();
+  const provisionalInstall =
+    installState === "live" || installState === "unknown";
+  if (
+    existsSync(managedPaths.runtime) &&
+    !(provisionalInstall
+      ? await validateProvisionalManagedRuntimeSelection(runningVersion)
+      : await validateManagedRuntimeSelection(runningVersion))
+  ) {
+    throw new Error(
+      `managed runtime activation is still in progress; refusing to start stale runtime ${runningVersion}`,
+    );
+  }
+  // Boot the service in-process: main.ts's top-level code starts the WSS
+  // client + local UI server and keeps the event loop alive.
+  const host = await import("./main");
+  // Close the none→intent race while the comparatively expensive service
+  // module imported. This is one lock-free marker read, not a steady-state
+  // poller; only a provisional install arms the recurring watcher.
+  try {
+    installState = await managedRuntimeInstallStartupState();
+  } catch (error) {
+    host.requestManagedHostRestart();
+    throw error;
+  }
+  if (installState === "stale" || installState === "attested") {
+    host.requestManagedHostRestart();
+    return;
+  }
+  if (installState === "live" || installState === "unknown") {
+    watchManagedInstaller(host.requestManagedHostRestart);
+  }
+  if (
+    existsSync(managedPaths.runtime) &&
+    installState !== "live" &&
+    installState !== "unknown"
+  ) {
+    const activationWasPending = existsSync(managedPaths.activationPending);
+    try {
+      const acknowledged = activationWasPending
+        ? await acknowledgeManagedRuntimeActivationWithCapabilityFloor(
+            runningVersion,
+            PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY,
+            host.completeProjectEnvBindingsAfterManagedRuntimeFloor,
+          )
+        : await acknowledgeManagedRuntimeActivation(runningVersion);
+      if (!acknowledged) {
+        // Selection changed while the service module was loading. Its task
+        // admission remains closed by the marker; drain and let the supervisor
+        // start the newly selected stable command.
+        host.requestManagedHostRestart();
+        return;
+      }
+      if (activationWasPending) {
+        host.advertiseProjectEnvBindingsAfterManagedRuntimeActivation();
+        console.log(
+          `[host-agent] managed runtime ${runningVersion} activated (pending activation acknowledged)`,
+        );
+        await logLaunchdJobAfterActivation();
+      }
+    } catch (error) {
+      // A malformed or concurrently changed marker must not leave an imported
+      // service running indefinitely. Admission is still closed, so request a
+      // graceful stop before surfacing the settlement failure.
+      host.requestManagedHostRestart();
+      throw error;
+    }
+  }
+  let localManagedUpdateRunning = false;
+  if (existsSync(managedPaths.current)) {
+    new ManagedActivationWatcher({
+      restartRequired: async () => {
+        if (localManagedUpdateRunning) return false;
+        let capabilityCompleted = false;
+        const restartRequired =
+          await reconcileManagedRuntimeActivationWithCapabilityFloor(
+            runningVersion,
+            PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY,
+            () => {
+              host.completeProjectEnvBindingsAfterManagedRuntimeFloor();
+              capabilityCompleted = true;
+            },
+          );
+        if (capabilityCompleted) {
+          host.advertiseProjectEnvBindingsAfterManagedRuntimeActivation();
+        }
+        return restartRequired;
+      },
+      isIdle: host.isIdleForManagedHostUpdate,
+      onReady: host.requestManagedHostRestart,
+      onError: (error) =>
+        console.warn(
+          `[host-agent] managed runtime activation check failed: ${error instanceof Error ? error.message : String(error)}`,
+        ),
+    }).start();
+  }
+  if (managedAutoupdateEnabled()) {
+    new ManagedUpdateScheduler({
+      isIdle: host.isIdleForManagedHostUpdate,
+      check: async () => {
+        localManagedUpdateRunning = true;
+        try {
+          const result = await updateManagedRuntime({
+            canActivate: host.isIdleForManagedHostUpdate,
+          });
+          if (result.status === "deferred") return "busy";
+          return result.status;
+        } finally {
+          localManagedUpdateRunning = false;
+        }
+      },
+      onUpdated: host.requestManagedHostRestart,
+      onError: (error) =>
+        console.warn(
+          `[host-agent] managed runtime update check failed: ${error instanceof Error ? error.message : String(error)}`,
+        ),
+    }).start();
+  }
+}
+
+/**
+ * The boot after an activation is the moment a launchd respawn problem is
+ * visible — `last exit code = 75: EX_TEMPFAIL` with a `pended nondemand
+ * spawn` is what the 2026-09-06 stalls looked like in `launchctl print`, and
+ * nothing in the service log said so. Read-only, macOS, and only when launchd
+ * actually spawned this process (pid 1 is its parent): a terminal `uai-host
+ * run`, the desktop supervisor, or a test spawning the CLI never runs
+ * `launchctl` here.
+ */
+async function logLaunchdJobAfterActivation(): Promise<void> {
+  if (process.platform !== "darwin" || process.ppid !== 1) return;
+  try {
+    const { describeLaunchdJob, formatLaunchdJobState, launchdJobTarget } =
+      await import("../scripts/install/darwin");
+    console.log(
+      `[host-agent] launchd job ${launchdJobTarget()} after activation: ${formatLaunchdJobState(describeLaunchdJob())}`,
+    );
+  } catch (error) {
+    console.warn(
+      `[host-agent] could not read the launchd job state after activation: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+async function waitForManagedInstaller(): Promise<"live" | "restart" | "stopped"> {
+  console.error(
+    red(
+      "managed host installation was interrupted; rerun the installer to resume safely",
+    ),
+  );
+  return new Promise((resolve) => {
+    let stopped = false;
+    let timer: NodeJS.Timeout | undefined;
+    const finish = (state: "live" | "restart" | "stopped") => {
+      if (stopped) return;
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      process.off("SIGTERM", onSignal);
+      process.off("SIGINT", onSignal);
+      resolve(state);
+    };
+    const onSignal = () => finish("stopped");
+    const poll = async () => {
+      try {
+        const state = await managedRuntimeInstallStartupState();
+        if (state === "live") {
+          finish("live");
+          return;
+        }
+        if (state === "none" || state === "attested") {
+          // Another CLI settled the stale transaction. Exit nonzero so a
+          // Restart=on-failure supervisor launches a fresh process that can
+          // either boot normally or finish the attested commit before import.
+          finish("restart");
+          return;
+        }
+      } catch (error) {
+        console.error(
+          red(
+            `managed host install gate could not be checked: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          ),
+        );
+      }
+      if (!stopped) timer = setTimeout(poll, 1_000);
+    };
+    process.once("SIGTERM", onSignal);
+    process.once("SIGINT", onSignal);
+    timer = setTimeout(poll, 1_000);
+  });
+}
+
+function watchManagedInstaller(onStale: () => void): void {
+  new ManagedInstallOwnerWatcher({
+    check: () => managedRuntimeInstallStartupState(),
+    onRestart: (state) => {
+      console.error(
+        red(
+          state === "attested"
+            ? "managed host install attested; draining so the supervisor can finalize it"
+            : "managed host installer exited before attestation; draining into the recovery gate",
+        ),
+      );
+      onStale();
+    },
+    onUnsafe: (error) => {
+      console.error(
+        red(
+          `managed host install intent became unreadable; draining safely: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        ),
+      );
+      onStale();
+    },
+  }).start();
+}
+
+// --- status -----------------------------------------------------------------
+
+async function cmdStatus(): Promise<void> {
+  const port = readPort();
+  if (port == null) {
+    console.log(
+      dim("service not running (no host.port). Start it: moondeck-station start  (or: moondeck-station run)"),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  let status, cloud, tasks;
+  try {
+    const [rawStatus, rawCloud, rawTasks] = await Promise.all([
+      api(port, "/api/status"),
+      api(port, "/api/cloud"),
+      api(port, "/api/tasks"),
+    ]);
+    status = StatusResponse.parse(rawStatus);
+    cloud = CloudResponse.parse(rawCloud);
+    tasks = TasksResponse.parse(rawTasks);
+  } catch (err) {
+    console.log(dim(localApiFailure(port, err)));
+    process.exitCode = 1;
+    return;
+  }
+
+  const stateColor =
+    cloud.state === "connected"
+      ? green
+      : cloud.state === "reconnecting"
+        ? yellow
+        : red;
+  console.log(bold("Moondeck Station") + dim(` — ${status.hostName} · v${status.version}`));
+  console.log(
+    `  cloud    ${stateColor(cloud.state)} ${dim(status.cloudUrl)}` +
+      (cloud.reconnectCount ? dim(`  (reconnects: ${cloud.reconnectCount})`) : ""),
+  );
+  if (cloud.lastError) console.log(`           ${dim("last error: " + cloud.lastError)}`);
+  console.log(`  service  ${dim(`pid ${status.pid} · up ${fmtDuration(status.uptime * 1000)}`)}`);
+  // Only worth a line when it's the surprising answer. A mock host looks
+  // identical to a real one everywhere else — connected, tasks running, output
+  // streaming — so this is the only place it can be caught before the work is.
+  if (status.agentMode === "mock") {
+    console.log(`  agents   ${yellow("mock")} ${dim("— echo only, no real CLI runs")}`);
+    console.log(`           ${dim("unset UAI_AGENTS in " + envLocalPath() + ", then: moondeck-station restart")}`);
+  }
+  if (status.containerRuntime) {
+    const runtime = status.containerRuntime;
+    const label =
+      runtime.status === "ready"
+        ? green(runtime.provider)
+        : runtime.status === "checking"
+          ? yellow("checking")
+          : red("unavailable");
+    console.log(`  runtime  ${label} ${dim(`(${runtime.preference})`)}`);
+    if (runtime.status === "checking" && runtime.detail) {
+      console.log(`           ${dim(runtime.detail)}`);
+    }
+    if (runtime.status === "no-runtime") {
+      console.log(`           ${dim(runtime.message)}`);
+    }
+  }
+  console.log(`  ui       ${dim(`http://127.0.0.1:${port}`)}`);
+  console.log(`  log      ${dim(status.logPath)}`);
+  console.log(`  tasks    ${tasks.tasks.length === 0 ? dim("none") : tasks.tasks.length}`);
+  for (const t of tasks.tasks) {
+    const slugs = t.projectSlugs.length ? t.projectSlugs.join(",") : "scratchpad";
+    const age = t.ageMs != null ? fmtDuration(t.ageMs) : "—";
+    const mem = t.memoryBytes != null ? fmtBytes(t.memoryBytes) : "—";
+    console.log(
+      `    ${cyan((t.ownerEmail ?? "unknown").padEnd(22))} ${dim(slugs.padEnd(16))} ` +
+        `${(t.status ?? "—").padEnd(9)} ${dim(`up ${age}`.padEnd(11))} ${dim(mem)}`,
+    );
+    console.log(`      ${dim(t.taskId)}`);
+  }
+}
+
+/** What `uai-host status` gives each local endpoint. A healthy runner
+ *  answers in well under a second; one second was too tight once
+ *  `/api/tasks` waited on `docker stats` (2026-10-30). */
+const LOCAL_API_TIMEOUT_MS = 5_000;
+
+/** A local endpoint that did not answer in time: the service is there. */
+class LocalApiTimeout extends Error {}
+/** Nothing accepted the connection: the service is not there. */
+class LocalApiUnreachable extends Error {}
+
+async function api(port: number, path: string): Promise<unknown> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}${path}`, {
+      signal: AbortSignal.timeout(LOCAL_API_TIMEOUT_MS),
+    });
+    if (!res.ok) throw new Error(`${path} → ${res.status}`);
+    return (await res.json()) as unknown;
+  } catch (err) {
+    if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
+      throw new LocalApiTimeout(
+        `${path} did not answer within ${String(LOCAL_API_TIMEOUT_MS / 1000)}s`,
+      );
+    }
+    const code = (err as { cause?: { code?: unknown } } | null)?.cause?.code;
+    if (code === "ECONNREFUSED") {
+      throw new LocalApiUnreachable(`${path}: connection refused`);
+    }
+    throw err;
+  }
+}
+
+/** One line for a status read that failed: no service, a slow one, or one
+ *  that answered wrong are three different things to the operator. */
+function localApiFailure(port: number, err: unknown): string {
+  const detail = err instanceof Error ? err.message : String(err);
+  if (err instanceof LocalApiUnreachable) {
+    return `service unreachable on 127.0.0.1:${port} (${detail}). Start it: moondeck-station start`;
+  }
+  if (err instanceof LocalApiTimeout) {
+    return `service on 127.0.0.1:${port} is up but slow to answer (${detail}); try again, or check its log`;
+  }
+  return `service on 127.0.0.1:${port} answered unexpectedly (${detail})`;
+}
+
+async function boundedResponseJson(
+  response: Response,
+  maxBytes = 16 * 1024,
+): Promise<unknown> {
+  const declared = response.headers.get("content-length");
+  if (declared !== null) {
+    if (!/^(?:0|[1-9]\d*)$/.test(declared) || Number(declared) > maxBytes) {
+      throw new Error("cloud response exceeds its byte limit");
+    }
+  }
+  if (!response.body) throw new Error("cloud response has no body");
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel("cloud response exceeds its byte limit");
+        throw new Error("cloud response exceeds its byte limit");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return JSON.parse(new TextDecoder().decode(bytes)) as unknown;
+}
+
+// --- runtime ---------------------------------------------------------------
+
+// --- aws setup (ADR-125 BYO-AWS: mint the host's scoped AWS identity) --------
+
+/** Mirrors scripts/machine-ami/byo-aws-quickcreate.yaml — keep in sync. */
+const AWS_MACHINE_POLICY = {
+  Version: "2012-10-17",
+  Statement: [
+    {
+      Sid: "UaiMachines",
+      Effect: "Allow",
+      Action: [
+        "ec2:RunInstances",
+        "ec2:StartInstances",
+        "ec2:StopInstances",
+        "ec2:TerminateInstances",
+        "ec2:CreateTags",
+        "ec2:DescribeInstances",
+        "ec2:DescribeImages",
+        "ec2:DescribeSubnets",
+        "ec2:DescribeVpcs",
+        "ec2:DescribeSecurityGroups",
+        "ec2:CreateSecurityGroup",
+        "ec2:AuthorizeSecurityGroupIngress",
+        "ec2:CreateSnapshot",
+        "ec2:DeleteSnapshot",
+        "ec2:CreateVolume",
+        "ec2:DescribeSnapshots",
+        "ec2:DescribeVolumes",
+      ],
+      Resource: "*",
+    },
+  ],
+};
+const AWS_SETUP_USER = "uai-host";
+
+/** Run the aws CLI with the operator's AMBIENT (admin) credentials: any
+ * AWS_* that load-env pulled from .env.local is a previously-minted SCOPED
+ * key that cannot administer IAM, and letting it shadow the shell's admin
+ * credentials makes every failure read as a permissions mystery. */
+function awsAdmin(
+  args: string[],
+  region: string | null,
+): SpawnSyncReturns<string> {
+  const env = { ...process.env };
+  const fromFile = (() => {
+    try {
+      return parseDotenv(readFileSync(envLocalPath(), "utf8"));
+    } catch {
+      return {} as Record<string, string>;
+    }
+  })();
+  if (
+    env.AWS_ACCESS_KEY_ID &&
+    env.AWS_ACCESS_KEY_ID === fromFile.AWS_ACCESS_KEY_ID
+  ) {
+    delete env.AWS_ACCESS_KEY_ID;
+    delete env.AWS_SECRET_ACCESS_KEY;
+    delete env.AWS_SESSION_TOKEN;
+  }
+  return spawnSync(
+    "aws",
+    [...(region ? ["--region", region] : []), "--output", "json", ...args],
+    { encoding: "utf8", env },
+  );
+}
+
+async function cmdAwsSetup(rest: string[]): Promise<void> {
+  const rotate = rest.includes("--rotate");
+  const regionFlagAt = rest.indexOf("--region");
+  let region = regionFlagAt >= 0 ? (rest[regionFlagAt + 1] ?? "") : "";
+
+  const version = spawnSync("aws", ["--version"], { encoding: "utf8" });
+  if (version.status !== 0) {
+    console.error(red("the aws CLI is not installed (or not on PATH)"));
+    console.error("install it: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html");
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!region) {
+    const configured = spawnSync("aws", ["configure", "get", "region"], {
+      encoding: "utf8",
+    });
+    region = (configured.stdout ?? "").trim();
+  }
+  if (!region) {
+    console.error(red("no AWS region — pass --region <region> (e.g. --region us-west-2)"));
+    process.exitCode = 1;
+    return;
+  }
+  if (!PAYLOAD_AMI_REGIONS.includes(region)) {
+    console.error(
+      red(`task machines are not available in ${region} yet — Moondeck's machine image is published in ${PAYLOAD_AMI_REGIONS.join(", ")}`),
+    );
+    console.error(dim("pass --region with one of those; more regions are coming."));
+    process.exitCode = 1;
+    return;
+  }
+
+  const identity = awsAdmin(["sts", "get-caller-identity"], region);
+  if (identity.status !== 0) {
+    console.error(red("no working AWS admin credentials in this shell"));
+    console.error(
+      "sign in first (aws configure, aws sso login, or exported AWS_* vars), then re-run",
+    );
+    console.error(dim((identity.stderr ?? "").trim().slice(0, 200)));
+    process.exitCode = 1;
+    return;
+  }
+  const account = (() => {
+    try {
+      return (JSON.parse(identity.stdout) as { Account?: string }).Account ?? "?";
+    } catch {
+      return "?";
+    }
+  })();
+
+  const existingEnv = (() => {
+    try {
+      return parseDotenv(readFileSync(envLocalPath(), "utf8"));
+    } catch {
+      return {} as Record<string, string>;
+    }
+  })();
+  if (existingEnv.AWS_ACCESS_KEY_ID && !rotate) {
+    console.log(
+      `already configured (key ${existingEnv.AWS_ACCESS_KEY_ID.slice(0, 8)}…, region ${existingEnv.UAI_AWS_REGION ?? "?"})`,
+    );
+    console.log(`re-run with ${bold("--rotate")} to mint a fresh key`);
+    return;
+  }
+
+  console.log(`account ${account}, region ${region} — creating the ${AWS_SETUP_USER} identity`);
+
+  const created = awsAdmin(
+    ["iam", "create-user", "--user-name", AWS_SETUP_USER],
+    region,
+  );
+  if (
+    created.status !== 0 &&
+    !(created.stderr ?? "").includes("EntityAlreadyExists")
+  ) {
+    console.error(red(`could not create the ${AWS_SETUP_USER} IAM user: ${(created.stderr ?? "").trim().slice(0, 300)}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  // put-user-policy overwrites: re-running upgrades the policy in place.
+  const policy = awsAdmin(
+    [
+      "iam",
+      "put-user-policy",
+      "--user-name",
+      AWS_SETUP_USER,
+      "--policy-name",
+      "uai-machines",
+      "--policy-document",
+      JSON.stringify(AWS_MACHINE_POLICY),
+    ],
+    region,
+  );
+  if (policy.status !== 0) {
+    console.error(red(`could not attach the machine policy: ${(policy.stderr ?? "").trim().slice(0, 300)}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const keyResult = awsAdmin(
+    ["iam", "create-access-key", "--user-name", AWS_SETUP_USER],
+    region,
+  );
+  if (keyResult.status !== 0) {
+    console.error(red(`could not create an access key: ${(keyResult.stderr ?? "").trim().slice(0, 300)}`));
+    if ((keyResult.stderr ?? "").includes("LimitExceeded")) {
+      console.error(
+        `the user already has two keys — list them with: aws iam list-access-keys --user-name ${AWS_SETUP_USER}\n` +
+          `and delete one with: aws iam delete-access-key --user-name ${AWS_SETUP_USER} --access-key-id <id>`,
+      );
+    }
+    process.exitCode = 1;
+    return;
+  }
+  let keyId = "";
+  let secret = "";
+  try {
+    const parsed = JSON.parse(keyResult.stdout) as {
+      AccessKey?: { AccessKeyId?: string; SecretAccessKey?: string };
+    };
+    keyId = parsed.AccessKey?.AccessKeyId ?? "";
+    secret = parsed.AccessKey?.SecretAccessKey ?? "";
+  } catch {
+    // handled below
+  }
+  if (!keyId || !secret) {
+    console.error(red("create-access-key returned no key material"));
+    process.exitCode = 1;
+    return;
+  }
+
+  writeEnvValuesAtomic(envLocalPath(), {
+    UAI_MACHINE_TASKS: "1",
+    UAI_MACHINE_PROVIDER: "aws",
+    UAI_AWS_REGION: region,
+    AWS_ACCESS_KEY_ID: keyId,
+    AWS_SECRET_ACCESS_KEY: secret,
+  });
+
+  // Rotation hygiene: the key the env file carried before this run belongs
+  // to the scoped user; a minted replacement leaves it orphaned AND holding
+  // the 2-key limit. Best-effort delete, loudly skippable.
+  const previousKey = existingEnv.AWS_ACCESS_KEY_ID;
+  if (rotate && previousKey && previousKey !== keyId) {
+    const deleted = awsAdmin(
+      [
+        "iam",
+        "delete-access-key",
+        "--user-name",
+        AWS_SETUP_USER,
+        "--access-key-id",
+        previousKey,
+      ],
+      region,
+    );
+    if (deleted.status === 0) {
+      console.log(`rotated: deleted the previous key ${previousKey.slice(0, 8)}…`);
+    } else {
+      console.log(
+        yellow(`minted a new key but could not delete ${previousKey.slice(0, 8)}… — remove it manually if unused`),
+      );
+    }
+  }
+
+  console.log(`${bold("done")} — scoped credentials written to ${envLocalPath()}`);
+  console.log(`  UAI_MACHINE_PROVIDER=aws  UAI_AWS_REGION=${region}  (machine tasks enabled)`);
+  console.log(`restart the host to activate: ${cyan("moondeck-station restart")}`);
+}
+
+// --- tune (ADR-118 follow-up: vnode/file-table ceilings) ---------------------
+
+const TUNE_DAEMON_LABEL = STATION.tuneDaemonLabel;
+const TUNE_DAEMON_PLIST = `/Library/LaunchDaemons/${TUNE_DAEMON_LABEL}.plist`;
+/** Floors, not targets — an operator-raised ceiling is never lowered. Each
+ * apple-container task VM pins host vnodes for its life (~12k after ADR-118,
+ * far more during dependency churn), and the boot defaults sit low enough
+ * that two heavy tasks have filled the table live (2026-08-25). ~2M vnodes
+ * is roughly half a GB of kernel memory IF fully populated. */
+const TUNE_MAXVNODES_FLOOR = 2_097_152;
+const TUNE_MAXFILES_FLOOR = 2_097_152;
+const TUNE_MAXFILESPERPROC_FLOOR = 1_048_576;
+
+function readSysctlNumber(name: string): number | null {
+  const res = spawnSync("/usr/sbin/sysctl", ["-n", name], {
+    encoding: "utf8",
+  });
+  const value = Number((res.stdout ?? "").trim());
+  return res.status === 0 && Number.isFinite(value) ? value : null;
+}
+
+function tunePlistContent(settings: Array<[string, number]>): string {
+  const args = ["/usr/sbin/sysctl", ...settings.map(([k, v]) => `${k}=${v}`)]
+    .map((a) => `    <string>${a}</string>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${TUNE_DAEMON_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+
+async function cmdTune(): Promise<void> {
+  if (process.platform !== "darwin") {
+    console.error(red("tune is macOS-only (apple-container task VMs)"));
+    process.exitCode = 1;
+    return;
+  }
+  const current = {
+    maxvnodes: readSysctlNumber("kern.maxvnodes"),
+    maxfiles: readSysctlNumber("kern.maxfiles"),
+    maxfilesperproc: readSysctlNumber("kern.maxfilesperproc"),
+  };
+  if (
+    current.maxvnodes === null ||
+    current.maxfiles === null ||
+    current.maxfilesperproc === null
+  ) {
+    console.error(red("could not read the current kernel limits via sysctl"));
+    process.exitCode = 1;
+    return;
+  }
+  // Order matters at apply time: maxfilesperproc must stay <= maxfiles.
+  const settings: Array<[string, number]> = [
+    ["kern.maxfiles", Math.max(current.maxfiles, TUNE_MAXFILES_FLOOR)],
+    [
+      "kern.maxfilesperproc",
+      Math.max(current.maxfilesperproc, TUNE_MAXFILESPERPROC_FLOOR),
+    ],
+    ["kern.maxvnodes", Math.max(current.maxvnodes, TUNE_MAXVNODES_FLOOR)],
+  ];
+  const desiredPlist = tunePlistContent(settings);
+  const plistCurrent = existsSync(TUNE_DAEMON_PLIST)
+    ? readFileSync(TUNE_DAEMON_PLIST, "utf8")
+    : null;
+  const changes = settings.filter(
+    ([key, value]) => value !== current[key.slice("kern.".length) as keyof typeof current],
+  );
+  if (changes.length === 0 && plistCurrent === desiredPlist) {
+    const summary = settings.map(([k, v]) => `${k}=${v}`).join(" ");
+    console.log(`already tuned (${summary}); boot persistence in place`);
+    return;
+  }
+
+  if (typeof process.getuid !== "function" || process.getuid() !== 0) {
+    console.log(`${bold("moondeck-station tune")} will (needs sudo):`);
+    for (const [key, value] of changes) {
+      console.log(
+        `  raise ${key}: ${current[key.slice("kern.".length) as keyof typeof current]} -> ${value}`,
+      );
+    }
+    console.log(
+      `  install ${TUNE_DAEMON_PLIST} so the limits survive reboots`,
+    );
+    console.log(`\nrun: ${cyan("sudo moondeck-station tune")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  for (const [key, value] of settings) {
+    const res = spawnSync("/usr/sbin/sysctl", [`${key}=${value}`], {
+      encoding: "utf8",
+    });
+    if (res.status !== 0) {
+      console.error(
+        red(`sysctl ${key}=${value} failed: ${(res.stderr ?? "").trim()}`),
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
+  writeFileSync(TUNE_DAEMON_PLIST, desiredPlist, { mode: 0o644 });
+  spawnSync("/usr/sbin/chown", ["root:wheel", TUNE_DAEMON_PLIST]);
+  // Re-bootstrap so launchd owns the daemon under its current definition.
+  spawnSync("/bin/launchctl", ["bootout", `system/${TUNE_DAEMON_LABEL}`]);
+  const bootstrap = spawnSync(
+    "/bin/launchctl",
+    ["bootstrap", "system", TUNE_DAEMON_PLIST],
+    { encoding: "utf8" },
+  );
+  if (bootstrap.status !== 0) {
+    console.error(
+      red(
+        `limits applied, but launchctl bootstrap failed (${(bootstrap.stderr ?? "").trim()}) — they will not survive a reboot`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const summary = settings.map(([k, v]) => `${k}=${v}`).join(" ");
+  console.log(`tuned: ${summary} (persisted via ${TUNE_DAEMON_PLIST})`);
+}
+
+async function cmdRuntime(rest: string[]): Promise<void> {
+  if (rest[0] === "begin-install") {
+    return cmdBeginRuntimeInstall(rest.slice(1));
+  }
+  if (rest[0] === "complete-install") {
+    return cmdCompleteRuntimeInstall(rest.slice(1));
+  }
+  if (rest[0] === "abort-install") {
+    return cmdAbortRuntimeInstall(rest.slice(1));
+  }
+  if (rest[0] === "stop-service") {
+    return cmdStopRuntimeInstallService(rest.slice(1));
+  }
+  if (rest.length === 1 && rest[0] === "reconcile-uninstall") {
+    await reconcileManagedRuntimeUninstall();
+    return;
+  }
+  if (rest[0] === "install-archive") {
+    return cmdInstallRuntimeArchive(rest.slice(1));
+  }
+  if (rest.length !== 1 || rest[0] !== "recheck") {
+    console.error(
+      red(
+        "usage: moondeck-station runtime recheck\n       moondeck-station runtime install-archive --archive <file> --version <x.y.z> --size <bytes> --sha256 <hex>",
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const port = readPort();
+  if (port == null) {
+    console.error(
+      red("service not running — start it before rechecking"),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/runtime/recheck`, {
+      method: "POST",
+      signal: AbortSignal.timeout(30_000),
+      headers: {
+        "x-uai-local-control": "runtime-recheck-v1",
+      },
+    });
+    if (!res.ok) throw new Error(`runtime recheck → ${res.status}`);
+    const runtime = ContainerRuntimeResponse.parse(
+      await boundedResponseJson(res),
+    );
+    if (runtime.status === "ready") {
+      console.log(
+        green("container runtime ready") + dim(` — ${runtime.provider}`),
+      );
+      return;
+    }
+    if (runtime.status === "checking") {
+      console.log(
+        yellow("container runtime detected") +
+          dim(" — preparing images and recovering tasks; check status shortly"),
+      );
+      return;
+    }
+    console.error(red(runtime.message ?? "container runtime unavailable"));
+    process.exitCode = 1;
+  } catch (err) {
+    console.error(
+      red(err instanceof Error ? err.message : "runtime recheck failed"),
+    );
+    process.exitCode = 1;
+  }
+}
+
+async function cmdBeginRuntimeInstall(rest: string[]): Promise<void> {
+  if (rest.length !== 0) {
+    throw new Error("usage: moondeck-station runtime begin-install");
+  }
+  const installer = await loadInstaller();
+  const result = await beginManagedRuntimeInstall({
+    // The installer invokes this command directly with output redirection. Its
+    // parent is therefore the long-lived compound shell, not a short-lived
+    // command-substitution process. PID start identity protects against reuse.
+    ownerPid: process.ppid,
+    reconcileStandaloneDefinition: () => reconcileDefinitionInstall(installer),
+    definitionState: (managedCommand) =>
+      serviceDefinitionState(installer, managedCommand),
+    prepareRecovery: (installIntent) =>
+      prepareDefinitionInstallRollback(installer, installIntent),
+    resumeRecovery: (installIntent) =>
+      resumeDefinitionInstallRollback(installer, installIntent),
+    resumeStoppedService: (installIntent, priorManager) =>
+      resumeServiceForInstall(installer, installIntent, priorManager),
+    beforeFinalize: (installIntent) =>
+      completeDefinitionInstall(installer, installIntent),
+  });
+  console.log(
+    [
+      result.nonce,
+      result.legacyShim ? "legacy" : "none",
+      result.serviceOwnership,
+      result.serviceQuiescence,
+      result.serviceManager.loaded ? "loaded" : "unloaded",
+      result.serviceManager.active ? "active" : "inactive",
+      result.serviceManager.enabled ? "enabled" : "disabled",
+    ].join(" "),
+  );
+}
+
+async function cmdStopRuntimeInstallService(rest: string[]): Promise<void> {
+  const installIntent = exactFlagValue(rest, "--install-intent");
+  if (!installIntent) {
+    throw new Error(
+      "usage: moondeck-station runtime stop-service --install-intent <nonce>",
+    );
+  }
+  const installer = await loadInstaller();
+  await stopManagedRuntimeServiceForInstall({
+    installIntent,
+    stopService: (intent, priorManager) =>
+      stopServiceForInstall(installer, intent, priorManager),
+  });
+}
+
+async function cmdCompleteRuntimeInstall(rest: string[]): Promise<void> {
+  const installIntent = exactFlagValue(rest, "--install-intent");
+  if (!installIntent) {
+    throw new Error(
+      "usage: moondeck-station runtime complete-install --install-intent <nonce>",
+    );
+  }
+  const installer = await loadInstaller();
+  await completeManagedRuntimeInstall({
+    installIntent,
+    beforeFinalize: (intent) => completeDefinitionInstall(installer, intent),
+  });
+}
+
+async function cmdAbortRuntimeInstall(rest: string[]): Promise<void> {
+  const installIntent = exactFlagValue(rest, "--install-intent");
+  if (!installIntent) {
+    throw new Error(
+      "usage: moondeck-station runtime abort-install --install-intent <nonce>",
+    );
+  }
+  const installer = await loadInstaller();
+  await abortManagedRuntimeInstall({
+    installIntent,
+    prepareRestore: (intent) =>
+      prepareDefinitionInstallRollback(installer, intent),
+    resumeRestore: (intent) =>
+      resumeDefinitionInstallRollback(installer, intent),
+    resumeStoppedService: (intent, priorManager) =>
+      resumeServiceForInstall(installer, intent, priorManager),
+    beforeFinalize: (intent) => completeDefinitionInstall(installer, intent),
+  });
+}
+
+async function cmdInstallRuntimeArchive(rest: string[]): Promise<void> {
+  const parsed = parseRuntimeInstallArgs(rest);
+  if (!parsed) {
+    console.error(
+      red(
+        "usage: moondeck-station runtime install-archive --archive <file> --version <x.y.z> --size <bytes> --sha256 <hex>",
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const platform = nativeReleasePlatform();
+  const result = await installManagedRuntimeArchive({
+    archivePath: parsed.archive,
+    artifact: {
+      // Bootstrap authenticated the tuple in the cloud-rendered script. The
+      // local installer consumes only size/hash; update URLs come from the
+      // separately verified signed manifest.
+      url: "bootstrap-authenticated-artifact",
+      size: parsed.size,
+      sha256: parsed.sha256,
+    },
+    version: parsed.version,
+    platform,
+    allowDowngrade: parsed.allowDowngrade,
+    // Legacy conversion takes over the old service's live tasks, so it needs
+    // every task idle. A managed version update restarts only our own
+    // service, which running tasks survive (durable sessions) — it drains
+    // only in-flight lifecycle mutations.
+    canActivate: (context) =>
+      context.legacyConversion
+        ? !hasActiveHostTasks()
+        : !hasInFlightHostTaskLifecycle(),
+    releaseRollbackUpdateHold: true,
+    installIntent: parsed.installIntent,
+  });
+  if (result.deferred) {
+    console.error(red("runtime activation deferred because host tasks are active"));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(
+    green(result.changed ? `installed host runtime ${result.version}` : `host runtime ${result.version} is already installed`),
+  );
+}
+
+interface RuntimeInstallArgs {
+  archive: string;
+  version: string;
+  size: number;
+  sha256: string;
+  allowDowngrade: boolean;
+  installIntent?: string;
+}
+
+function parseRuntimeInstallArgs(rest: string[]): RuntimeInstallArgs | null {
+  const values = new Map<string, string>();
+  let allowDowngrade = false;
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index]!;
+    if (arg === "--allow-downgrade") {
+      if (allowDowngrade) return null;
+      allowDowngrade = true;
+      continue;
+    }
+    if (
+      ![
+        "--archive",
+        "--version",
+        "--size",
+        "--sha256",
+        "--install-intent",
+      ].includes(arg)
+    ) {
+      return null;
+    }
+    if (values.has(arg)) return null;
+    const value = rest[index + 1];
+    if (!value || value.startsWith("--")) return null;
+    values.set(arg, value);
+    index += 1;
+  }
+  const archive = values.get("--archive");
+  const version = values.get("--version");
+  const sizeValue = values.get("--size");
+  const sha256 = values.get("--sha256");
+  const installIntent = values.get("--install-intent");
+  if (!archive || !version || !sizeValue || !sha256) return null;
+  if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(version)) {
+    return null;
+  }
+  if (!/^[1-9]\d*$/.test(sizeValue) || !/^[a-f0-9]{64}$/.test(sha256)) {
+    return null;
+  }
+  const size = Number(sizeValue);
+  if (!Number.isSafeInteger(size)) return null;
+  if (installIntent && !/^[a-f0-9]{64}$/.test(installIntent)) return null;
+  return { archive, version, size, sha256, allowDowngrade, installIntent };
+}
+
+async function cmdUpdate(rest: string[]): Promise<void> {
+  if (rest.length !== 0) {
+    console.error(red("usage: moondeck-station update"));
+    process.exitCode = 1;
+    return;
+  }
+  // Running tasks survive the service restart (durable sessions); only a
+  // task mid-lifecycle blocks, and only until it drains.
+  if (hasInFlightHostTaskLifecycle()) {
+    console.error(red("refusing to update while a task is still starting; retry in a moment"));
+    process.exitCode = 1;
+    return;
+  }
+  const result = await updateManagedRuntime({
+    canActivate: () => !hasInFlightHostTaskLifecycle(),
+    releaseRollbackUpdateHold: true,
+  });
+  if (result.status === "not-managed") {
+    console.error(red("this host is not installed as a managed runtime"));
+    process.exitCode = 1;
+    return;
+  }
+  if (result.status === "current") {
+    console.log(green(`host runtime ${result.version} is current`));
+    return;
+  }
+  if (result.status === "deferred") {
+    console.error(red("host runtime update was deferred because the host became busy"));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(
+    green(`updated host runtime ${result.fromVersion} → ${result.version}`) +
+      dim(" — activation staged; the service will restart after in-flight work drains"),
+  );
+}
+
+async function cmdRollback(rest: string[]): Promise<void> {
+  if (rest.length !== 0) {
+    console.error(red("usage: moondeck-station rollback"));
+    process.exitCode = 1;
+    return;
+  }
+  if (hasActiveHostTasks()) {
+    console.error(red("refusing to roll back while host tasks are active"));
+    process.exitCode = 1;
+    return;
+  }
+  const idle = () => !hasActiveHostTasks();
+  const result = await rollbackManagedRuntime(undefined, undefined, idle);
+  console.log(
+    green(`rolled back host runtime ${result.fromVersion} → ${result.version}`) +
+      dim(" — activation staged; the service will restart after in-flight work drains"),
+  );
+  console.log(
+    yellow("automatic runtime updates are paused; run `moondeck-station update` to resume them"),
+  );
+}
+
+function cmdEnrollmentStatus(rest: string[]): void {
+  if (rest.length !== 1 || rest[0] !== "status") {
+    console.error(red("usage: moondeck-station enrollment status"));
+    process.exitCode = 2;
+    return;
+  }
+  const identity = hostIdentity();
+  if (identity.kind === "complete") {
+    console.log("enrolled");
+    return;
+  }
+  if (identity.kind === "partial") {
+    console.error(red("incomplete host identity"));
+    process.exitCode = 2;
+    return;
+  }
+  console.log("unenrolled");
+  process.exitCode = 1;
+}
+
+function managedAutoupdateEnabled(): boolean {
+  return (
+    process.env.UAI_HOST_AUTOUPDATE !== "0" &&
+    PINNED_RELEASE_MANIFEST_KEYS.size > 0 &&
+    existsSync(managedRuntimePaths().current)
+  );
+}
+
+// --- open -------------------------------------------------------------------
+
+async function cmdOpen(): Promise<void> {
+  const port = readPort();
+  if (port == null) {
+    console.error(red("no host.port — is the service running?"));
+    process.exitCode = 1;
+    return;
+  }
+  const url = `http://127.0.0.1:${port}`;
+  if (process.platform === "darwin") detach("open", [url]);
+  else if (process.platform === "win32") detach("cmd", ["/c", "start", "", url]);
+  else detach("xdg-open", [url]);
+  console.log(`opening ${url}`);
+}
+
+function detach(cmd: string, args: string[]): void {
+  const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+  child.on("error", (err) => console.error(red(`could not run ${cmd}: ${err.message}`)));
+  child.unref();
+}
+
+// --- logs -------------------------------------------------------------------
+
+async function cmdLogs(follow: boolean): Promise<void> {
+  const log = serviceLogPath();
+  if (log.startsWith("journald")) {
+    const args = ["--user", "-u", STATION.command];
+    if (follow) args.push("-f");
+    inherit("journalctl", args);
+    return;
+  }
+  if (!existsSync(log)) {
+    console.error(red(`log not found: ${log}`));
+    console.error(dim("(install + start the service first, or run in the foreground)"));
+    process.exitCode = 1;
+    return;
+  }
+  inherit("tail", follow ? ["-f", log] : ["-n", "200", log]);
+}
+
+function inherit(cmd: string, args: string[]): void {
+  const child = spawn(cmd, args, { stdio: "inherit" });
+  child.on("error", (err) => {
+    console.error(red(`could not run ${cmd}: ${err.message}`));
+    process.exitCode = 1;
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+// --- setup (enrollment, ADR-031) --------------------------------------------
+
+/** Read a `--name value` or `--name=value` flag from argv. */
+function flagValue(rest: string[], name: string): string | undefined {
+  const i = rest.indexOf(name);
+  if (i >= 0 && rest[i + 1]) return rest[i + 1];
+  const eq = rest.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
+function exactFlagValue(rest: string[], name: string): string | undefined {
+  return rest.length === 2 && rest[0] === name && rest[1]
+    ? rest[1]
+    : undefined;
+}
+
+type EnrollArgs =
+  | { ok: true; token: string; cloud?: string }
+  | { ok: false };
+
+/** `enroll` spends a one-time token, so reject malformed/ambiguous argv
+ * instead of silently falling back to persisted configuration. */
+function parseEnrollArgs(rest: string[]): EnrollArgs {
+  let token: string | undefined;
+  let cloud: string | undefined;
+  let sawCloud = false;
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index]!;
+    if (arg === "--cloud") {
+      if (sawCloud) return { ok: false };
+      sawCloud = true;
+      const value = rest[index + 1];
+      if (!value || value.startsWith("-")) return { ok: false };
+      cloud = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--cloud=")) {
+      if (sawCloud) return { ok: false };
+      sawCloud = true;
+      cloud = arg.slice("--cloud=".length);
+      if (!cloud) return { ok: false };
+      continue;
+    }
+    if (arg.startsWith("-") || token) return { ok: false };
+    token = arg;
+  }
+
+  return token ? { ok: true, token, ...(cloud ? { cloud } : {}) } : { ok: false };
+}
+
+type HostIdentity =
+  | { kind: "none" }
+  | { kind: "partial" }
+  | { kind: "complete"; hostId: string; hostToken: string };
+
+/** Resolve both modern env identities and legacy `pair` identities whose id
+ * lives in `$UAI_DATA_DIR/host-id`. Exactly one unresolved half fails closed. */
+function hostIdentity(): HostIdentity {
+  const hostToken = process.env.UAI_HOST_TOKEN;
+  const hostId = process.env.UAI_HOST_ID ?? (hostToken ? readPersistedHostId() : null);
+  if (!hostId && !hostToken) return { kind: "none" };
+  if (!hostId || !hostToken) return { kind: "partial" };
+  return { kind: "complete", hostId, hostToken };
+}
+
+function rejectPartialIdentity(): void {
+  console.error(
+    red("incomplete host identity — refusing to replace an existing enrollment"),
+  );
+  console.error(
+    dim("restore UAI_HOST_ID/UAI_HOST_TOKEN, or use `moondeck-station setup --force` for a deliberate reset."),
+  );
+  process.exitCode = 1;
+}
+
+/** The bridge credential is durable, so its destination trust anchor must be
+ * durable too. Process env is intentionally NOT consulted here: a pasted
+ * command can override it before load-env reads the host's real config. */
+function persistedCloudUrl(): string | undefined {
+  for (const path of [envLocalPath(), join(uaiHome(), ".env")]) {
+    if (!existsSync(path)) continue;
+    try {
+      const value = parseDotenv(readFileSync(path)).UAI_CLOUD_URL;
+      if (value) return value;
+    } catch {
+      // The normal env loader already reports malformed/unreadable files. A
+      // missing trust anchor is handled by the caller without leaking secrets.
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Claim this machine as a host: redeem a one-time enrollment token (minted in
+ * the web app) for a permanent bridge credential, then write the config. The
+ * bridge secret is generated HERE and never leaves — only its hash is sent
+ * (ADR-015/ADR-031).
+ *
+ *   uai-host setup --cloud wss://app.runuai.com/host --enroll uaienroll_…
+ */
+async function cmdSetup(rest: string[]): Promise<void> {
+  const enroll = flagValue(rest, "--enroll");
+  const cloud = flagValue(rest, "--cloud");
+  if (!enroll || !cloud) {
+    console.error(
+      red("usage: moondeck-station setup --cloud <wss-url> --enroll <token>"),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let cloudEndpoint: ReturnType<typeof parseHostCloudEndpoint>;
+  try {
+    cloudEndpoint = parseHostCloudEndpoint(cloud);
+  } catch (error) {
+    console.error(
+      red(
+        `invalid --cloud URL: ${error instanceof Error ? error.message : String(error)}`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const normalizedCloud = cloudEndpoint.bridgeUrl;
+
+  // An already-claimed machine ATTACHES the token to its existing identity
+  // (ADR-098) — pasting a second org's enroll command Just Works, no new host
+  // row, no --force. --force still re-enrolls from scratch (new identity,
+  // orphans the old row) for the rare deliberate reset.
+  const identity = hostIdentity();
+  if (identity.kind === "partial" && !rest.includes("--force")) {
+    rejectPartialIdentity();
+    return;
+  }
+  if (identity.kind === "complete" && !rest.includes("--force")) {
+    try {
+      removeCommittedPendingEnrollment(pendingEnrollmentPath(uaiHome()), {
+        hostId: identity.hostId,
+        hostSecret: identity.hostToken,
+      });
+    } catch (err) {
+      console.error(
+        red(
+          `cannot verify pending enrollment state: ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      );
+      process.exitCode = 1;
+      return;
+    }
+    console.log(
+      dim("already enrolled — attaching this machine to the token's workspace instead."),
+    );
+    return attachToOrg(enroll, normalizedCloud, identity);
+  }
+
+  const pendingFile = pendingEnrollmentPath(uaiHome());
+  if (rest.includes("--force")) discardPendingEnrollment(pendingFile);
+
+  const redeemUrl = `${cloudEndpoint.apiOrigin}/api/hosts/enroll/redeem`;
+
+  // Persist this host's proposed identity BEFORE spending the one-time token.
+  // A retry after a lost response reuses the exact id/secret, and the cloud's
+  // same-host replay returns the already-completed result without new access.
+  const candidate: PendingEnrollment = {
+    schemaVersion: 1,
+    enrollmentTokenSha256: enrollmentTokenSha256(enroll),
+    hostId: ulid().toLowerCase(),
+    hostSecret: randomBytes(32).toString("hex"),
+    cloudUrl: normalizedCloud,
+    hostName: hostname(),
+    createdAt: Date.now(),
+  };
+  let pending: PendingEnrollment;
+  try {
+    pending = ensurePendingEnrollment(pendingFile, candidate).pending;
+  } catch (err) {
+    console.error(
+      red(
+        `could not persist pending enrollment: ${err instanceof Error ? err.message : String(err)}`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!pendingEnrollmentMatches(pending, enroll, normalizedCloud)) {
+    console.error(red("another enrollment is already pending on this machine"));
+    console.error(
+      dim(
+        "retry the original enrollment command, or use `moondeck-station setup --force` for a deliberate reset.",
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const hostId = pending.hostId;
+  const secret = pending.hostSecret;
+  const tokenHash = createHash("sha256").update(secret).digest("hex");
+  const name = pending.hostName;
+
+  console.log(
+    dim(`enrolling ${name} (${hostId}) with ${cloudEndpoint.displayHost}…`),
+  );
+  let res: Response;
+  try {
+    res = await fetch(redeemUrl, {
+      method: "POST",
+      redirect: "error",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ enrollToken: enroll, hostId, tokenHash, name }),
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (err) {
+    console.error(
+      red(`could not reach the cloud: ${err instanceof Error ? err.message : String(err)}`),
+    );
+    console.error(dim("the proposed identity is saved locally; retry this exact command."));
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`;
+    try {
+      const j = (await boundedResponseJson(res)) as {
+        error?: { message?: string };
+      };
+      if (j.error?.message) detail = j.error.message;
+    } catch {
+      /* keep the HTTP status */
+    }
+    console.error(red(`enrollment failed: ${detail}`));
+    const definitiveUnclaimed =
+      (res.status === 404 || res.status === 410) &&
+      res.headers.get(ENROLLMENT_REPLAY_PROTOCOL_HEADER) ===
+        ENROLLMENT_REPLAY_PROTOCOL_VERSION;
+    if (definitiveUnclaimed) {
+      // A same-host-v1 cloud checks `redeemedAt` before expiry, so these are
+      // proven unclaimed. Old/rolled-back handlers carry no header and may
+      // return 410 after committing a response that was lost in transit.
+      discardPendingEnrollment(pendingFile);
+      console.error(dim("mint a fresh enrollment command in the web app and retry."));
+    } else {
+      // USED is intentionally retained for rolling compatibility: an older
+      // cloud may have completed the first request but lack same-host replay.
+      console.error(dim("the proposed identity is saved locally; retry this exact command."));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  let success: unknown;
+  try {
+    success = await boundedResponseJson(res);
+  } catch (error) {
+    console.error(
+      red(
+        `enrollment outcome could not be verified: ${error instanceof Error ? error.message : String(error)}`,
+      ),
+    );
+    console.error(dim("the proposed identity is saved locally; retry this exact command."));
+    process.exitCode = 1;
+    return;
+  }
+  // ADR-136 step 4: a replace-machine enrollment answers with the EXISTING
+  // row's id — this machine adopts it instead of its own proposal, so the
+  // runner keeps its identity (and every task created against it).
+  const outcome =
+    success && typeof success === "object" && !Array.isArray(success)
+      ? (success as Record<string, unknown>)
+      : null;
+  const replacedHostId =
+    outcome?.replaced === true && typeof outcome.hostId === "string" && outcome.hostId.length > 0
+      ? outcome.hostId
+      : null;
+  if (
+    !outcome ||
+    outcome.ok !== true ||
+    (replacedHostId === null && outcome.hostId !== pending.hostId)
+  ) {
+    console.error(red("enrollment outcome did not match the proposed host identity"));
+    console.error(dim("the proposed identity is saved locally; retry this exact command."));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Atomically commit all three values. The pending file is removed only after
+  // the replacement is durable; a crash can leave both files, never neither.
+  try {
+    commitPendingEnrollment(pendingFile, envLocalPath(), pending);
+  } catch (err) {
+    console.error(
+      red(
+        `enrolled, but could not write ${envLocalPath()}: ${err instanceof Error ? err.message : String(err)}`,
+      ),
+    );
+    console.error(
+      dim("the identity remains in protected pending state — retry this exact enrollment command."),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (replacedHostId !== null) {
+    // The pending commit wrote the proposed id; the row this machine now
+    // answers as is the replaced one. Same secret, so the bridge admits it.
+    try {
+      writeEnvValuesAtomic(envLocalPath(), { UAI_HOST_ID: replacedHostId });
+    } catch (err) {
+      console.error(
+        red(
+          `replaced, but could not record the station id in ${envLocalPath()}: ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      );
+      console.error(dim(`set UAI_HOST_ID=${replacedHostId} there by hand before starting.`));
+      process.exitCode = 1;
+      return;
+    }
+    console.log(
+      green("✓ replaced") + dim(` — this machine now answers as station ${replacedHostId}; config written to ${envLocalPath()}`),
+    );
+  } else {
+    console.log(green("✓ enrolled") + dim(` — config written to ${envLocalPath()}`));
+  }
+  printTelemetryNotice();
+  const steps = enrollmentNextSteps();
+  if (steps.length > 0) console.log("");
+  for (const step of steps) {
+    console.log(step.command ? cyan(step.command) + dim(step.note ?? "") : step.text);
+  }
+}
+
+// --- enroll (attach an org, ADR-098) -----------------------------------------
+
+/**
+ * Enroll this machine. Without an identity this delegates to fresh setup; with
+ * one, it spends the token against the existing host rather than minting a new
+ * identity. The bridge secret authenticates attach (same credential the WSS
+ * bridge presents) and may only be sent over TLS or to a loopback dev cloud.
+ *
+ *   uai-host enroll <token> [--cloud <wss-url>]
+ */
+async function cmdEnroll(rest: string[]): Promise<void> {
+  const parsed = parseEnrollArgs(rest);
+  if (!parsed.ok) {
+    console.error(red("usage: moondeck-station enroll <token> [--cloud <wss-url>]"));
+    process.exitCode = 1;
+    return;
+  }
+  const identity = hostIdentity();
+  if (identity.kind === "partial") {
+    rejectPartialIdentity();
+    return;
+  }
+  // A fresh station enrolls with moondeck.io unless told otherwise; an
+  // enrolled one stays on the cloud it already belongs to.
+  const cloud =
+    parsed.cloud ??
+    (identity.kind === "complete"
+      ? persistedCloudUrl()
+      : process.env.UAI_CLOUD_URL || STATION_DEFAULT_CLOUD_URL);
+  if (!cloud) {
+    console.error(
+      red(
+        identity.kind === "complete"
+          ? "no persisted cloud URL — restore UAI_CLOUD_URL in the host config"
+          : "no cloud URL — pass --cloud <wss-url>",
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (identity.kind === "none") {
+    return cmdSetup(["--cloud", cloud, "--enroll", parsed.token]);
+  }
+  return attachToOrg(parsed.token, cloud, identity);
+}
+
+/** Shared by `enroll` and `setup`-on-an-enrolled-machine. */
+async function attachToOrg(
+  enrollToken: string,
+  cloud: string,
+  identity: Extract<HostIdentity, { kind: "complete" }>,
+): Promise<void> {
+  const { hostId, hostToken } = identity;
+
+  let cloudEndpoint: ReturnType<typeof parseHostCloudEndpoint>;
+  try {
+    cloudEndpoint = parseHostCloudEndpoint(cloud);
+  } catch (error) {
+    console.error(
+      red(
+        `invalid cloud URL: ${error instanceof Error ? error.message : String(error)}`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const configuredCloud = persistedCloudUrl();
+  if (!configuredCloud) {
+    console.error(
+      red("cannot verify the enrollment destination — UAI_CLOUD_URL is not persisted"),
+    );
+    console.error(dim("restore the original cloud URL before attaching this host."));
+    process.exitCode = 1;
+    return;
+  }
+  let configuredEndpoint: ReturnType<typeof parseHostCloudEndpoint>;
+  try {
+    configuredEndpoint = parseHostCloudEndpoint(configuredCloud);
+  } catch (error) {
+    console.error(
+      red(
+        `invalid configured UAI_CLOUD_URL: ${error instanceof Error ? error.message : String(error)}`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (cloudEndpoint.apiOrigin !== configuredEndpoint.apiOrigin) {
+    console.error(
+      red("refusing to send the host credential to a different cloud origin"),
+    );
+    console.error(dim(`configured cloud: ${configuredEndpoint.displayHost}`));
+    process.exitCode = 1;
+    return;
+  }
+  const attachUrl = `${cloudEndpoint.apiOrigin}/api/hosts/enroll/attach`;
+
+  console.log(
+    dim(`attaching ${hostname()} (${hostId}) via ${cloudEndpoint.displayHost}…`),
+  );
+  let res: Response;
+  try {
+    res = await fetch(attachUrl, {
+      method: "POST",
+      redirect: "error",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ enrollToken, hostId, token: hostToken }),
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (err) {
+    console.error(
+      red(`could not reach the cloud: ${err instanceof Error ? err.message : String(err)}`),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`;
+    try {
+      const j = (await boundedResponseJson(res)) as {
+        error?: { message?: string };
+      };
+      if (j.error?.message) detail = j.error.message;
+    } catch {
+      /* keep the HTTP status */
+    }
+    console.error(red(`attach failed: ${detail}`));
+    console.error(
+      dim("the token may be expired or already used — mint a fresh one in the web app."),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  let body: unknown;
+  try {
+    body = await boundedResponseJson(res);
+  } catch (error) {
+    console.error(
+      red(
+        `attach outcome could not be verified: ${error instanceof Error ? error.message : String(error)}`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const result = body as Record<string, unknown> | null;
+  if (
+    !result ||
+    Array.isArray(result) ||
+    result.ok !== true ||
+    result.hostId !== hostId ||
+    typeof result.orgId !== "string" ||
+    result.orgId.length === 0 ||
+    result.orgId.length > 128 ||
+    (result.orgName !== null &&
+      result.orgName !== undefined &&
+      typeof result.orgName !== "string")
+  ) {
+    console.error(red("attach outcome did not match this host identity"));
+    process.exitCode = 1;
+    return;
+  }
+  const where = result.orgName ? ` to ${result.orgName}` : "";
+  console.log(green(`✓ enrolled${where}`) + dim(" — no restart needed."));
+}
+
+// --- pair -------------------------------------------------------------------
+
+async function cmdPair(token: string | undefined): Promise<void> {
+  if (!token) {
+    console.error(red("usage: moondeck-station pair <token>"));
+    process.exitCode = 1;
+    return;
+  }
+  // v1 "pairing" = persist the host token to .env.local (load-env.ts reads it).
+  // The cloud-issued-pairing-token -> host-token handshake is a future flow
+  // (hosted-architecture.md, "what we don't do now"); this stores what you paste.
+  upsertEnvLocal("UAI_HOST_TOKEN", token);
+  console.log(green("paired") + dim(` — wrote UAI_HOST_TOKEN to ${envLocalPath()}`));
+  console.log(dim("apply it: moondeck-station restart  (or start the service)"));
+  printTelemetryNotice();
+}
+
+function upsertEnvLocal(key: string, value: string): void {
+  writeEnvValuesAtomic(envLocalPath(), { [key]: value });
+}
+
+// --- install dispatch -------------------------------------------------------
+
+async function cmdInstall(rest: string[]): Promise<void> {
+  const parsed = parseInstallArgs(rest);
+  if (!parsed) {
+    console.error(
+      red(
+        "usage: moondeck-station install [--no-start] [--dry-run] [--install-intent <nonce>]",
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const { dryRun, startOnInstall, installIntent } = parsed;
+  // Disclosure BEFORE activation (review): install starts the service, and
+  // the notice must precede the first telemetry-armed run.
+  if (!dryRun) printTelemetryNotice();
+  if (!dryRun) mkdirSync(uaiHome(), { recursive: true, mode: 0o700 });
+  const installer = await loadInstaller();
+  if (dryRun) {
+    await installer.install(installContext(true, startOnInstall));
+  } else if (installIntent) {
+    await runManagedRuntimeInstallIntentMutation({
+      installIntent,
+      mutation: (identity) =>
+        installer.install(installContext(false, startOnInstall, identity)),
+    });
+  } else {
+    await runInstallLifecycleMutation(installer, () =>
+      installer.install(installContext(false, startOnInstall)),
+    );
+  }
+  if (!dryRun) {
+    console.log(
+      green("installed") +
+        dim(
+          startOnInstall
+            ? " — service registered and started"
+            : " — service registered but not started; start it: moondeck-station start",
+        ),
+    );
+  }
+}
+
+function parseInstallArgs(rest: string[]): {
+  dryRun: boolean;
+  startOnInstall: boolean;
+  installIntent?: string;
+} | null {
+  let dryRun = false;
+  let noStart = false;
+  let installIntent: string | undefined;
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index]!;
+    if (arg === "--dry-run") {
+      if (dryRun) return null;
+      dryRun = true;
+      continue;
+    }
+    if (arg === "--no-start") {
+      if (noStart) return null;
+      noStart = true;
+      continue;
+    }
+    if (arg === "--install-intent") {
+      if (installIntent) return null;
+      const value = rest[index + 1];
+      if (!value || !/^[a-f0-9]{64}$/.test(value)) return null;
+      installIntent = value;
+      index += 1;
+      continue;
+    }
+    return null;
+  }
+  if (dryRun && installIntent) return null;
+  return { dryRun, startOnInstall: !noStart, installIntent };
+}
+
+/**
+ * ADR-071 default-on disclosure at the surfaces an operator actually SEES:
+ * the service's own start line only reaches host.out.log/journald, so the
+ * interactive commands (install/pair/setup/start/restart) print it — and
+ * PERSIST the shown-once marker that gates the baked default (a silently
+ * upgraded service stays off until one of these runs).
+ */
+function printTelemetryNotice(): void {
+  const notice = telemetryNoticeIfActive();
+  if (notice) {
+    console.log(yellow("telemetry: ") + notice);
+    persistTelemetryDisclosure();
+  }
+}
+
+async function cmdInstaller(
+  action: "start" | "stop" | "restart",
+  dryRun: boolean,
+): Promise<void> {
+  // Upgrade path (review finding): operators of EXISTING installs meet
+  // default-on telemetry through start/restart — disclose BEFORE the
+  // service action activates anything, and persist the gate marker.
+  if (!dryRun && (action === "start" || action === "restart")) {
+    printTelemetryNotice();
+  }
+  const installer = await loadInstaller();
+  if (dryRun) {
+    await installer[action](true);
+  } else {
+    await runInstallLifecycleMutation(installer, () => installer[action](false));
+  }
+}
+
+async function cmdUninstall(rest: string[]): Promise<void> {
+  const dryRun = rest.includes("--dry-run");
+  const purge = rest.includes("--purge");
+  if (
+    rest.some((arg) => arg !== "--dry-run" && arg !== "--purge") ||
+    rest.filter((arg) => arg === "--dry-run").length > 1 ||
+    rest.filter((arg) => arg === "--purge").length > 1
+  ) {
+    console.error(red("usage: moondeck-station uninstall [--purge] [--dry-run]"));
+    process.exitCode = 1;
+    return;
+  }
+  const installer = await loadInstaller();
+  const paths = managedRuntimePaths();
+  if (dryRun) {
+    await installer.uninstall(true);
+    console.log(`$ rm -rf ${paths.root}`);
+    if (purge) console.log(`$ rm -rf ${paths.data}`);
+    return;
+  }
+  await reconcileInstallLifecycle(installer);
+  await removeManagedRuntime({
+    purgeData: purge,
+    canRemove: () => !hasNonTerminalHostTasks(),
+    beforeRemove: () => installer.uninstall(false),
+    afterServiceTeardown: () => teardownBundledRuntimeForUninstall(purge),
+  });
+  console.log(
+    green("uninstalled") +
+      (purge
+        ? dim(" — host runtime and ~/.moondeck data removed")
+        : dim(" — ~/.moondeck data preserved (use --purge to remove it)")),
+  );
+}
+
+/**
+ * The service is already down, but the active signed generation and purge
+ * target are still attached here — the last moment the bundled CLI exists to
+ * clean up what Uai provisioned through it. Ownership-proven and fail-closed
+ * (see lib/apple-uninstall-teardown.ts): an incomplete teardown THROWS, which
+ * deliberately leaves the managed-removal transaction's teardown marker and
+ * the signed runtime in place for a retry — never remove the escape route
+ * while Uai resources may remain.
+ */
+async function teardownBundledRuntimeForUninstall(purge: boolean): Promise<void> {
+  if (process.platform !== "darwin") return;
+  // The durable provider claim marker is the authority for whether Apple
+  // state can exist at all: it is written BEFORE any apple task provisioning
+  // (runtime-provider-state.ts). Absent marker = nothing was ever
+  // provisioned = nothing to tear down. A malformed marker throws from the
+  // reader — uncertainty keeps the uninstall retryable. With the marker
+  // present, a corrupt bundle must THROW rather than skip (review
+  // 2026-08-18 round 3: the old `.catch(() => null)` silently removed the
+  // signed runtime while Apple state remained — the escape-route failure).
+  const providerState = readRuntimeProviderState(
+    runtimeProviderStatePath(env.dataDir),
+  );
+  if (providerState?.statefulProvider !== "apple-container") return;
+  let bundle: Awaited<ReturnType<typeof resolveBundledRuntimeFromEnvironment>>;
+  try {
+    bundle = await resolveBundledRuntimeFromEnvironment();
+  } catch (error) {
+    throw new Error(
+      "Apple container state exists but the bundled runtime failed " +
+        `verification (${error instanceof Error ? error.message : String(error)}); ` +
+        "uninstall was left retryable — repair or reinstall the host runtime, then retry",
+    );
+  }
+  const cliPath = bundle?.containerCliPath;
+  if (!cliPath) {
+    throw new Error(
+      "Apple container state exists but no bundled CLI is available to tear it down; uninstall was left retryable",
+    );
+  }
+  const cli = (args: string[], timeoutMs: number) =>
+    new Promise<{ code: number | null; stdout: string; stderr: string }>(
+      (resolveCli) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const child = spawn(cliPath, args, {
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        const settle = (code: number | null): void => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolveCli({ code, stdout, stderr });
+        };
+        const timer = setTimeout(() => {
+          child.kill("SIGKILL");
+          const backstop = setTimeout(() => settle(null), 1_000);
+          backstop.unref();
+        }, timeoutMs);
+        timer.unref();
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk: string) => {
+          stdout += chunk;
+        });
+        child.stderr?.on("data", (chunk: string) => {
+          stderr += chunk;
+        });
+        child.on("error", () => settle(null));
+        child.on("close", (code) => settle(code));
+      },
+    );
+  const result = await teardownAppleRuntimeStateForUninstall({ cli, purge });
+  for (const removed of result.removedContainers) {
+    console.log(dim(`removed container ${removed}`));
+  }
+  for (const removed of result.removedImages) {
+    console.log(dim(`removed image ${removed}`));
+  }
+  if (result.problems.length > 0) {
+    throw new Error(
+      `Apple container teardown is incomplete — uninstall was left retryable: ${result.problems.join("; ")}`,
+    );
+  }
+}
+
+async function loadInstaller(): Promise<Installer> {
+  const name =
+    process.platform === "darwin"
+      ? "darwin"
+      : process.platform === "win32"
+        ? "win"
+        : "linux";
+  try {
+    const mod = (await import(`../scripts/install/${name}`)) as {
+      installer: Installer;
+    };
+    return mod.installer;
+  } catch (err) {
+    throw new Error(
+      `no installer available for ${process.platform}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+async function reconcileDefinitionInstall(
+  installer: Installer,
+  installIntent?: string,
+): Promise<void> {
+  const reconcile = (
+    installer as Installer & {
+      reconcileDefinitionInstall?: (installIntent?: string) => Promise<void>;
+    }
+  ).reconcileDefinitionInstall;
+  if (!reconcile) {
+    throw new Error(
+      "service installer cannot reconcile an interrupted definition update",
+    );
+  }
+  await reconcile.call(installer, installIntent);
+}
+
+async function completeDefinitionInstall(
+  installer: Installer,
+  installIntent?: string,
+): Promise<void> {
+  const complete = (
+    installer as Installer & {
+      completeDefinitionInstall?: (installIntent?: string) => Promise<void>;
+    }
+  ).completeDefinitionInstall;
+  if (!complete) {
+    throw new Error(
+      "service installer cannot complete its durable definition update",
+    );
+  }
+  await complete.call(installer, installIntent);
+}
+
+async function prepareDefinitionInstallRollback(
+  installer: Installer,
+  installIntent: string,
+): Promise<void> {
+  const prepare = (
+    installer as Installer & {
+      prepareDefinitionInstallRollback?: (installIntent: string) => Promise<void>;
+    }
+  ).prepareDefinitionInstallRollback;
+  if (!prepare) {
+    throw new Error(
+      "service installer cannot prepare durable definition rollback",
+    );
+  }
+  await prepare.call(installer, installIntent);
+}
+
+async function resumeDefinitionInstallRollback(
+  installer: Installer,
+  installIntent: string,
+): Promise<void> {
+  const resume = (
+    installer as Installer & {
+      resumeDefinitionInstallRollback?: (installIntent: string) => Promise<void>;
+    }
+  ).resumeDefinitionInstallRollback;
+  if (!resume) {
+    throw new Error(
+      "service installer cannot resume durable definition rollback",
+    );
+  }
+  await resume.call(installer, installIntent);
+}
+
+async function serviceDefinitionState(
+  installer: Installer,
+  managedCommand: string,
+): Promise<ManagedServiceDefinitionState> {
+  const inspect = (
+    installer as Installer & {
+      definitionState?: (
+        managedCommand: string,
+      ) => Promise<ManagedServiceDefinitionState>;
+    }
+  ).definitionState;
+  if (!inspect) {
+    throw new Error("service installer cannot inspect definition lifecycle state");
+  }
+  return inspect.call(installer, managedCommand);
+}
+
+async function stopServiceForInstall(
+  installer: Installer,
+  installIntent: string,
+  priorManager: ManagedServiceManagerState,
+): Promise<void> {
+  const stop = (
+    installer as Installer & {
+      stopForInstall?: (
+        installIntent: string,
+        priorManager: ManagedServiceManagerState,
+      ) => Promise<void>;
+    }
+  ).stopForInstall;
+  if (!stop) {
+    throw new Error("service installer cannot stop an install-owned service");
+  }
+  await stop.call(installer, installIntent, priorManager);
+}
+
+async function resumeServiceForInstall(
+  installer: Installer,
+  installIntent: string,
+  priorManager: ManagedServiceManagerState,
+): Promise<void> {
+  const resume = (
+    installer as Installer & {
+      resumeServiceForInstall?: (
+        installIntent: string,
+        priorManager: ManagedServiceManagerState,
+      ) => Promise<void>;
+    }
+  ).resumeServiceForInstall;
+  if (!resume) {
+    throw new Error("service installer cannot resume an install-owned service");
+  }
+  await resume.call(installer, installIntent, priorManager);
+}
+
+async function reconcileInstallLifecycle(installer: Installer): Promise<void> {
+  await reconcileManagedRuntimeInstallLifecycle(
+    installLifecycleCallbacks(installer),
+  );
+}
+
+async function runInstallLifecycleMutation<T>(
+  installer: Installer,
+  mutation: () => Promise<T>,
+): Promise<T> {
+  return runManagedRuntimeInstallLifecycleMutation({
+    ...installLifecycleCallbacks(installer),
+    mutation,
+  });
+}
+
+function installLifecycleCallbacks(
+  installer: Installer,
+): ReconcileManagedRuntimeInstallLifecycleOptions {
+  return {
+    reconcileDefinition: (installIntent) =>
+      reconcileDefinitionInstall(installer, installIntent),
+    completeDefinition: (installIntent) =>
+      completeDefinitionInstall(installer, installIntent),
+    prepareDefinitionRollback: (installIntent) =>
+      prepareDefinitionInstallRollback(installer, installIntent),
+    resumeDefinitionRollback: (installIntent) =>
+      resumeDefinitionInstallRollback(installer, installIntent),
+    resumeStoppedService: (installIntent, priorManager) =>
+      resumeServiceForInstall(installer, installIntent, priorManager),
+  };
+}
+
+function installContext(
+  dryRun: boolean,
+  startOnInstall = true,
+  definitionInstallIntent?: { nonce: string; ownerPid: number },
+): InstallContext {
+  const run = resolveRunCommand();
+  const currentPath = process.env.PATH ?? "";
+  const managedBin = pathForManagedCommand(run.execPath);
+  const envPath = managedBin
+    ? [managedBin, ...currentPath.split(":").filter((entry) => entry !== managedBin)].join(":")
+    : currentPath;
+  const context: InstallContext & {
+    definitionInstallIntent?: { nonce: string; ownerPid: number };
+  } = {
+    execPath: run.execPath,
+    args: run.args,
+    cwd: uaiHome(),
+    dryRun,
+    envPath,
+    startOnInstall,
+    definitionInstallIntent,
+  };
+  return context;
+}
+
+/** The command that runs `uai-host run`: the installed binary if on PATH,
+ *  else `pnpm host-agent` from the repo (dev). */
+function resolveRunCommand(): { execPath: string; args: string[] } {
+  const managed = managedRuntimePaths();
+  if (existsSync(managed.current) && existsSync(managed.shim)) {
+    return { execPath: managed.shim, args: ["run"] };
+  }
+  const uaiHost = which(STATION.command);
+  if (uaiHost) return { execPath: uaiHost, args: ["run"] };
+  return { execPath: which("pnpm") ?? "pnpm", args: ["host-agent"] };
+}
+
+function pathForManagedCommand(execPath: string): string | null {
+  const managed = managedRuntimePaths();
+  return resolve(execPath) === managed.shim ? dirname(managed.shim) : null;
+}
+
+function which(cmd: string): string | null {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const res = spawnSync(finder, [cmd], { encoding: "utf8" });
+  if (res.status !== 0 || !res.stdout) return null;
+  return res.stdout.split("\n")[0]?.trim() || null;
+}
+
+// --- helpers ----------------------------------------------------------------
+
+function readPort(): number | null {
+  const p = uiPortFilePath();
+  if (!existsSync(p)) return null;
+  const n = Number(readFileSync(p, "utf8").trim());
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+function fmtDuration(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  return `${Math.floor(h / 24)}d ${h % 24}h`;
+}
+
+function fmtBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let v = n / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i += 1;
+  }
+  return `${v.toFixed(1)} ${units[i]}`;
+}
+
+function printHelp(): void {
+  console.log(`${bold("moondeck-station")} — Moondeck Station: runs Moondeck tasks on this machine (ADR-028)
+
+  run                  run the service in the foreground (debug)
+  install [--dry-run]  install as a per-user service for this OS
+    [--no-start]       register the service without launching it
+  uninstall [--purge]  remove service/runtime; preserve ~/.moondeck unless --purge
+  uninstall-legacy [--purge] [--force] [--dry-run]
+                       remove the old Uai host from this machine: its service,
+                       runtime, uai-host commands and task containers; keeps
+                       ~/.uai unless --purge; refuses while it runs tasks
+                       unless --force (their work is lost)
+  start | stop         control the installed service
+  restart              stop + start
+  update                accept signed updates (also resumes after rollback)
+  rollback              reactivate previous runtime; pause automatic updates
+  moondeck-station-recover rollback
+                        roll back via previous runtime if current cannot start
+  enrollment status     report whether this machine has a complete identity
+  status               connection, service info, active tasks (same as the UI)
+  logs [--follow]      tail the service log
+  runtime recheck      probe Docker again and refresh cloud capabilities
+  tune                 (macOS, sudo) raise kernel vnode/file-table ceilings for
+                       apple-container task VMs and persist them across boots
+  aws setup [--region <r>] [--rotate]
+                       enable machine-backed tasks in YOUR AWS account: uses
+                       the admin credentials already in this shell to mint a
+                       scoped uai-host IAM key and writes the host config
+  setup --cloud <wss-url> --enroll <token>
+                       claim this machine via an enrollment token from the web
+                       app (mints + writes the host credential); on an
+                       already-enrolled machine, attaches the token's workspace
+  enroll <token> [--cloud <wss-url>]
+                       first-time setup, or attach this machine to another
+                       workspace (token minted on that workspace's Hosts page)
+  pair <token>         store a host token directly (manual fallback)
+  open                 open the local UI in your browser
+`);
+}
+
+main().catch((err) => {
+  console.error(red(err instanceof Error ? err.message : String(err)));
+  process.exitCode = 1;
+});
+
+// --- the old @runuai/host on this machine (Moondeck migration plan §4) ------
+
+function legacyHostSeams(): LegacyHostSeams {
+  return {
+    home: homedir(),
+    platform: process.platform,
+    uid: process.getuid?.() ?? 0,
+    inheritedEnv: process.env,
+    userBus: systemUserBusProbe(),
+    exec: (command, args, commandEnv) => {
+      const result = spawnSync(command, [...args], {
+        encoding: "utf8",
+        timeout: 120_000,
+        ...(commandEnv ? { env: { ...commandEnv } } : {}),
+      });
+      return {
+        status: result.error ? null : result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? (result.error ? String(result.error) : ""),
+      };
+    },
+    fetchJson: async (url) => {
+      const response = await fetch(url, { signal: AbortSignal.timeout(2_000) });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      return response.json();
+    },
+    exists: (target) => existsSync(target),
+    readText: (target) => {
+      try {
+        return readFileSync(target, "utf8");
+      } catch {
+        return null;
+      }
+    },
+    remove: (target) => rmSync(target, { recursive: true, force: true }),
+    which,
+    readLegacyTaskIds: () => {
+      // The old host's default store (its env is pinned to its defaults the
+      // same way: legacyCommandEnv). Read only; anything wrong reads as null.
+      const file = join(homedir(), LEGACY_HOST.homeDirName, "data", "host.sqlite");
+      if (!existsSync(file)) return null;
+      try {
+        const db = new Database(file, { readonly: true, fileMustExist: true });
+        try {
+          const rows = db.prepare("SELECT task_id FROM uai_host_tasks").all() as Array<{ task_id: unknown }>;
+          return new Set(rows.flatMap((row) => (typeof row.task_id === "string" ? [row.task_id] : [])));
+        } finally {
+          db.close();
+        }
+      } catch {
+        return null;
+      }
+    },
+    processCommandOf: (pid) => {
+      if (!Number.isInteger(pid) || pid <= 0) return null;
+      const result = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 5_000 });
+      const command = result.status === 0 ? (result.stdout ?? "").trim() : "";
+      return command || null;
+    },
+    packageNameOf: (command) =>
+      packageNameOfCommand(command, {
+        realpath: (target) => realpathSync(target),
+        readText: (target) => {
+          try {
+            return readFileSync(target, "utf8");
+          } catch {
+            return null;
+          }
+        },
+      }),
+    log: (line) => console.log(line),
+  };
+}
+
+/** True (and explains why) when the old host runs here, so the caller must stop. */
+async function refuseWhileLegacyHostRuns(): Promise<boolean> {
+  const reason = legacyHostRunningReason(await inspectLegacyHost(legacyHostSeams()));
+  if (!reason) return false;
+  console.error(red(reason));
+  process.exitCode = LEGACY_HOST_RUNNING_EXIT_CODE;
+  return true;
+}
+
+/** `moondeck-station uninstall-legacy [--purge] [--force] [--dry-run] [--check]` */
+async function cmdUninstallLegacy(rest: string[]): Promise<void> {
+  const known = new Set(["--purge", "--force", "--dry-run", "--check"]);
+  if (rest.some((arg) => !known.has(arg)) || new Set(rest).size !== rest.length) {
+    console.error(red("usage: moondeck-station uninstall-legacy [--purge] [--force] [--dry-run]"));
+    process.exitCode = 1;
+    return;
+  }
+  const seams = legacyHostSeams();
+  if (rest.includes("--check")) {
+    // For the installer: exit LEGACY_HOST_RUNNING_EXIT_CODE with the reason
+    // when the old host runs, 0 otherwise. Changes nothing.
+    await refuseWhileLegacyHostRuns();
+    return;
+  }
+  // Run by the installer, the retry is the installer's own pipeline:
+  // moondeck-station is not on PATH yet (scripts/host-runtime/install.sh).
+  const installerRetry = process.env.UAI_UNINSTALL_LEGACY_FORCE_COMMAND?.trim();
+  const result = await uninstallLegacyHost(seams, {
+    purge: rest.includes("--purge"),
+    force: rest.includes("--force"),
+    dryRun: rest.includes("--dry-run"),
+    ...(installerRetry ? { forceCommand: installerRetry } : {}),
+  });
+  if (result.outcome === "absent") {
+    console.log(dim("no old Uai host found on this machine"));
+    return;
+  }
+  if (result.outcome === "refused") {
+    console.error(red(result.reason));
+    process.exitCode = 1;
+    return;
+  }
+  for (const step of result.steps) console.log(dim(`$ ${step}`));
+  for (const note of result.notes) console.log(yellow(note));
+  console.log(
+    rest.includes("--dry-run")
+      ? dim("dry run: nothing was changed")
+      : green("old Uai host removed") +
+          dim(` — next: ${STATION.command} install && ${STATION.command} enroll <token from app.moondeck.io>`),
+  );
+}
+