@runuai/host 0.9.13 → 0.9.42

package/src/cli.ts

@@ -3,7 +3,8 @@
  * `uai-host` CLI (ADR-028). Hand-rolled argv switch — no argparser dependency.
  *
  *   run | install | uninstall | start | stop | restart
- *   status | logs [--follow] | pair <token> | open
+ *   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
@@ -21,18 +22,88 @@ import "./load-env";
 
 import { spawn, spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { hostname } from "node:os";
-import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync } 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 { envLocalPath, serviceLogPath, uaiHome, uiPortFilePath } from "./paths";
-import { CloudResponse, StatusResponse, TasksResponse } from "./ui/types";
+import {
+  abortManagedRuntimeInstall,
+  acknowledgeManagedRuntimeActivation,
+  beginManagedRuntimeInstall,
+  completeManagedRuntimeInstall,
+  installManagedRuntimeArchive,
+  managedRuntimeInstallStartupState,
+  managedRuntimePaths,
+  nativeReleasePlatform,
+  reconcileManagedRuntimeActivation,
+  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 { 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 {
+  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";
 
 // --- tiny ANSI (no chalk) ---------------------------------------------------
@@ -64,17 +135,28 @@ async function main(): Promise<void> {
       return cmdOpen();
     case "logs":
       return cmdLogs(follow);
+    case "runtime":
+      return cmdRuntime(rest);
+    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":
-      return cmdInstall(dryRun);
-    case "uninstall":
+      return cmdInstall(rest);
     case "start":
     case "stop":
     case "restart":
       return cmdInstaller(cmd, dryRun);
+    case "uninstall":
+      return cmdUninstall(rest);
     case undefined:
     case "help":
     case "-h":
@@ -89,10 +171,202 @@ async function main(): Promise<void> {
 
 // --- 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(): Promise<void> {
+  // 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.
-  await import("./main");
+  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"
+  ) {
+    try {
+      if (!(await acknowledgeManagedRuntimeActivation(runningVersion))) {
+        // 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;
+      }
+    } 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;
+        return reconcileManagedRuntimeActivation(runningVersion);
+      },
+      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();
+  }
+}
+
+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 -----------------------------------------------------------------
@@ -108,9 +382,14 @@ async function cmdStatus(): Promise<void> {
   }
   let status, cloud, tasks;
   try {
-    status = StatusResponse.parse(await api(port, "/api/status"));
-    cloud = CloudResponse.parse(await api(port, "/api/cloud"));
-    tasks = TasksResponse.parse(await api(port, "/api/tasks"));
+    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(
@@ -141,6 +420,22 @@ async function cmdStatus(): Promise<void> {
     console.log(`  agents   ${yellow("mock")} ${dim("— echo only, no real CLI runs")}`);
     console.log(`           ${dim("unset UAI_AGENTS in " + envLocalPath() + ", then: uai-host 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}`);
@@ -157,11 +452,395 @@ async function cmdStatus(): Promise<void> {
 }
 
 async function api(port: number, path: string): Promise<unknown> {
-  const res = await fetch(`http://127.0.0.1:${port}${path}`);
+  const res = await fetch(`http://127.0.0.1:${port}${path}`, {
+    signal: AbortSignal.timeout(1_000),
+  });
   if (!res.ok) throw new Error(`${path} → ${res.status}`);
   return (await res.json()) as unknown;
 }
 
+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 ---------------------------------------------------------------
+
+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: uai-host runtime recheck\n       uai-host 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: uai-host 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: uai-host 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: uai-host 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: uai-host 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: uai-host 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: uai-host 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: uai-host 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 `uai-host update` to resume them"),
+  );
+}
+
+function cmdEnrollmentStatus(rest: string[]): void {
+  if (rest.length !== 1 || rest[0] !== "status") {
+    console.error(red("usage: uai-host 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> {
@@ -222,6 +901,90 @@ function flagValue(rest: string[], name: string): string | undefined {
   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 `uai-host 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
@@ -241,48 +1004,102 @@ async function cmdSetup(rest: string[]): Promise<void> {
     return;
   }
 
-  let cloudUrl: URL;
+  let cloudEndpoint: ReturnType<typeof parseHostCloudEndpoint>;
   try {
-    cloudUrl = new URL(cloud);
-  } catch {
-    console.error(red(`invalid --cloud URL: ${cloud}`));
+    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;
 
-  // Don't silently re-enroll an already-claimed machine (would orphan the old
-  // host row + steal its slot).
-  const existing = existsSync(envLocalPath())
-    ? readFileSync(envLocalPath(), "utf8")
-    : "";
-  if (/^UAI_HOST_TOKEN=/m.test(existing) && !rest.includes("--force")) {
-    console.error(red("this machine is already enrolled (UAI_HOST_TOKEN set)."));
+  // 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(
-      dim("re-enrolling creates a new host + orphans the old one — pass --force to proceed."),
+      red(
+        `could not persist pending enrollment: ${err instanceof Error ? err.message : String(err)}`,
+      ),
     );
     process.exitCode = 1;
     return;
   }
-
-  const proto =
-    cloudUrl.protocol === "wss:"
-      ? "https:"
-      : cloudUrl.protocol === "ws:"
-        ? "http:"
-        : cloudUrl.protocol;
-  const redeemUrl = `${proto}//${cloudUrl.host}/api/hosts/enroll/redeem`;
-
-  // This host's identity + bridge secret. Secret stays local; cloud gets the hash.
-  const hostId = ulid().toLowerCase();
-  const secret = randomBytes(32).toString("hex");
+  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 `uai-host 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 = hostname();
+  const name = pending.hostName;
 
-  console.log(dim(`enrolling ${name} (${hostId}) with ${cloudUrl.host}…`));
+  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),
@@ -291,32 +1108,70 @@ async function cmdSetup(rest: string[]): Promise<void> {
     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 res.json()) as { error?: { message?: string } };
+      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(
-      dim("the token may be expired or already used — mint a fresh one in the web app."),
+      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;
+  }
+  if (
+    !success ||
+    typeof success !== "object" ||
+    Array.isArray(success) ||
+    (success as Record<string, unknown>).ok !== true ||
+    (success as Record<string, unknown>).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;
   }
 
-  // The host is already created on the cloud and the token is spent. If the
-  // local write fails, don't lose the secret — print it so it can be saved by
-  // hand rather than forcing the user to mint a fresh token.
+  // 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 {
-    upsertEnvLocal("UAI_HOST_ID", hostId);
-    upsertEnvLocal("UAI_HOST_TOKEN", secret);
-    upsertEnvLocal("UAI_CLOUD_URL", cloud);
+    commitPendingEnrollment(pendingFile, envLocalPath(), pending);
   } catch (err) {
     console.error(
       red(
@@ -324,11 +1179,8 @@ async function cmdSetup(rest: string[]): Promise<void> {
       ),
     );
     console.error(
-      dim("the host exists on the cloud — save these into that file manually, then `uai-host start`:"),
+      dim("the identity remains in protected pending state — retry this exact enrollment command."),
     );
-    console.error(`  UAI_HOST_ID=${hostId}`);
-    console.error(`  UAI_HOST_TOKEN=${secret}`);
-    console.error(`  UAI_CLOUD_URL=${cloud}`);
     process.exitCode = 1;
     return;
   }
@@ -340,6 +1192,171 @@ async function cmdSetup(rest: string[]): Promise<void> {
   console.log(cyan("  uai-host restart") + dim("                     (already installed)"));
 }
 
+// --- 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: uai-host enroll <token> [--cloud <wss-url>]"));
+    process.exitCode = 1;
+    return;
+  }
+  const identity = hostIdentity();
+  if (identity.kind === "partial") {
+    rejectPartialIdentity();
+    return;
+  }
+  const cloud =
+    parsed.cloud ??
+    (identity.kind === "complete"
+      ? persistedCloudUrl()
+      : process.env.UAI_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> {
@@ -358,30 +1375,85 @@ async function cmdPair(token: string | undefined): Promise<void> {
 }
 
 function upsertEnvLocal(key: string, value: string): void {
-  const path = envLocalPath();
-  // UAI_HOME (~/.uai on a fresh install) may not exist yet — create it before
-  // the first write, or writeFileSync ENOENTs (which on `setup` would orphan a
-  // just-redeemed host + burn the one-time token).
-  mkdirSync(dirname(path), { recursive: true });
-  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
-  const kept = existing
-    .split("\n")
-    .filter((l) => !l.startsWith(`${key}=`) && l.trim() !== "");
-  kept.push(`${key}=${value}`);
-  writeFileSync(path, kept.join("\n") + "\n", { mode: 0o600 });
+  writeEnvValuesAtomic(envLocalPath(), { [key]: value });
 }
 
 // --- install dispatch -------------------------------------------------------
 
-async function cmdInstall(dryRun: boolean): Promise<void> {
+async function cmdInstall(rest: string[]): Promise<void> {
+  const parsed = parseInstallArgs(rest);
+  if (!parsed) {
+    console.error(
+      red(
+        "usage: uai-host 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();
-  await installer.install(installContext(dryRun));
+  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(" — start it: uai-host start"));
+    console.log(
+      green("installed") +
+        dim(
+          startOnInstall
+            ? " — service registered and started"
+            : " — service registered but not started; start it: uai-host 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 };
 }
 
 /**
@@ -400,7 +1472,7 @@ function printTelemetryNotice(): void {
 }
 
 async function cmdInstaller(
-  action: "uninstall" | "start" | "stop" | "restart",
+  action: "start" | "stop" | "restart",
   dryRun: boolean,
 ): Promise<void> {
   // Upgrade path (review finding): operators of EXISTING installs meet
@@ -410,8 +1482,132 @@ async function cmdInstaller(
     printTelemetryNotice();
   }
   const installer = await loadInstaller();
-  await installer[action](dryRun);
-  if (!dryRun && action === "uninstall") console.log(green("uninstalled"));
+  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: uai-host 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 ~/.uai data removed")
+        : dim(" — ~/.uai 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> {
@@ -433,19 +1629,204 @@ async function loadInstaller(): Promise<Installer> {
   }
 }
 
-function installContext(dryRun: boolean): InstallContext {
+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();
-  return { execPath: run.execPath, args: run.args, cwd: uaiHome(), dryRun };
+  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("uai-host");
   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" });
@@ -489,14 +1870,25 @@ function printHelp(): void {
 
   run                  run the service in the foreground (debug)
   install [--dry-run]  install as a per-user service for this OS
-  uninstall            remove the service
+    [--no-start]       register the service without launching it
+  uninstall [--purge]  remove service/runtime; preserve ~/.uai unless --purge
   start | stop         control the installed service
   restart              stop + start
+  update                accept signed updates (also resumes after rollback)
+  rollback              reactivate previous runtime; pause automatic updates
+  uai-host-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
   setup --cloud <wss-url> --enroll <token>
                        claim this machine via an enrollment token from the web
-                       app (mints + writes the host credential)
+                       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
 `);