@runuai/host 0.9.13 → 0.9.42

package/lib/managed-runtime.ts

@@ -0,0 +1,3644 @@
+import { createHash, randomBytes } from "node:crypto";
+import { constants as fsConstants, lstatSync } from "node:fs";
+import {
+  access,
+  chmod,
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readFile,
+  readlink,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  symlink,
+  unlink,
+} from "node:fs/promises";
+import { homedir, release as osRelease } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import {
+  DEFAULT_RELEASE_DOWNLOAD_BASE,
+  MAX_RELEASE_ARTIFACT_BYTES,
+  MAX_RELEASE_MANIFEST_BYTES,
+  isReleasePlatform,
+  releaseArtifactFilename,
+  releaseArtifactForPlatform,
+  type PinnedReleaseManifestKey,
+  type ReleaseArtifact,
+  type ReleasePlatform,
+  verifyReleaseManifest,
+} from "./release-manifest";
+import {
+  BUNDLED_RUNTIME_CAPABILITY,
+  BUNDLED_RUNTIME_ROOT,
+  extractVerifiedRuntimeArchive,
+  readVerifiedArtifactFile,
+  type ResolvedRuntimeDescriptor,
+  type RuntimeCapabilityDescriptorV3,
+  type RuntimeAssetManifest,
+  validateRuntimeAssetManifest,
+  validateRuntimeCapabilityDescriptor,
+  validateRuntimeDescriptor,
+} from "./runtime-archive";
+import {
+  PINNED_RELEASE_MANIFEST_KEYS,
+  STABLE_RELEASE_MANIFEST_URL,
+} from "./release-trust";
+
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+const INSTALL_INTENT_NONCE = /^[a-f0-9]{64}$/;
+const OPERATION_LOCK_HELD = Symbol("managed-runtime-operation-lock-held");
+const OPERATION_LOCK_WAIT_MS = 30_000;
+const OPERATION_LOCK_POLL_MS = 100;
+export const MANAGED_MANIFEST_TIMEOUT_MS = 10_000;
+export const MANAGED_ARTIFACT_TIMEOUT_MS = 10 * 60_000;
+const MAX_OPERATION_LOCK_BYTES = 4 * 1024;
+const MAX_PACKAGE_JSON_BYTES = 64 * 1024;
+const INCOMPLETE_LOCK_STALE_MS = 5 * 60_000;
+export const MANAGED_UPDATE_RESTART_EXIT_CODE = 75;
+const REQUIRED_BUNDLED_RUNTIME_LICENSES = Object.freeze([
+  "Container-LICENSE",
+  "Kernel-GPL-2.0",
+]);
+/** Plugin directory == plugin binary name in Apple's signed pkg payload. */
+const APPLE_CONTAINER_PLUGINS = Object.freeze([
+  "container-core-images",
+  "container-network-vmnet",
+  "container-runtime-linux",
+  "k8s",
+  "machine-apiserver",
+]);
+
+export interface ManagedRuntimePaths {
+  readonly home: string;
+  readonly root: string;
+  readonly runtime: string;
+  readonly current: string;
+  readonly previous: string;
+  readonly shim: string;
+  readonly recoveryEntrypoint: string;
+  readonly recoveryShim: string;
+  readonly data: string;
+  readonly rollbackJournal: string;
+  readonly rollbackUpdateHold: string;
+  /** Monotonic compatibility floor claimed before the bundled runtime may own
+   * task state. It lives outside version generations so pruning/rollback
+   * cannot erase the evidence an older runtime must honor. */
+  readonly minimumRuntimeCapability: string;
+  /** Older Phase-B builds may have claimed provider state before publishing
+   * the durable capability marker. This preserved marker implies floor 2. */
+  readonly runtimeProviderState: string;
+  readonly operationLock: string;
+  readonly activationPending: string;
+  /**
+   * Durable task-admission gate for destructive maintenance. This deliberately
+   * lives beside `root`, not inside it: uninstall detaches/removes the whole
+   * managed tree before it may reopen admission.
+   */
+  readonly maintenancePending: string;
+  /** Deterministic holding path for a runtime whose service is already down. */
+  readonly uninstallPendingRoot: string;
+  /** End-to-end fence held by the public installer across enrollment/attach. */
+  readonly installIntent: string;
+  /** Durable ownership record for a validated legacy npm command collision. */
+  readonly legacyShimTakeover: string;
+  /** Same-directory parking preserves a relative npm symlink's resolution. */
+  readonly legacyShimBackup: string;
+}
+
+export type ManagedRuntimeRemovalStep =
+  | "service-teardown-complete"
+  | "runtime-detached"
+  | "commands-removed"
+  | "runtime-removed"
+  | "data-removed"
+  | "cleanup-complete";
+
+export interface RemoveManagedRuntimeOptions {
+  readonly home?: string;
+  readonly purgeData?: boolean;
+  /** Rechecked only after the durable admission marker has been written. */
+  readonly canRemove: () => boolean | Promise<boolean>;
+  /** Service teardown runs under the same cross-process runtime lock. */
+  readonly beforeRemove?: () => Promise<void>;
+  /** Runtime-provider teardown runs only after the service is down and before
+   * the signed generation or host data can be detached. */
+  readonly afterServiceTeardown?: () => Promise<void>;
+  /** Durable-boundary observer; an error leaves cleanup safely resumable. */
+  readonly onRemovalStep?: (
+    step: ManagedRuntimeRemovalStep,
+  ) => void | Promise<void>;
+}
+
+export interface BeginManagedRuntimeInstallOptions {
+  readonly home?: string;
+  readonly ownerPid: number;
+  /** Prove definition ownership and snapshot manager state before quiescence. */
+  readonly definitionState: (
+    managedCommand: string,
+  ) => Promise<ManagedServiceDefinitionState>;
+  /** Settle a crashed standalone definition update before classifying it. */
+  readonly reconcileStandaloneDefinition?: () => Promise<void>;
+  /** Stop the replacement and restore the prior definition without starting it. */
+  readonly prepareRecovery?: (installIntent: string) => Promise<void>;
+  /** Resume the prior service only after runtime links and commands are restored. */
+  readonly resumeRecovery?: (installIntent: string) => Promise<void>;
+  /** Restart a legacy service durably stopped before any definition journal. */
+  readonly resumeStoppedService?: (
+    installIntent: string,
+    priorManager: ManagedServiceManagerState,
+  ) => Promise<void>;
+  /** Finish an attested prior install; that commit decision cannot roll back. */
+  readonly beforeFinalize?: (installIntent?: string) => Promise<void>;
+}
+
+export interface ManagedRuntimeInstallIntent {
+  readonly nonce: string;
+  readonly legacyShim: boolean;
+  readonly serviceOwnership: "missing" | "managed" | "legacy";
+  readonly serviceQuiescence: "quiesce" | "idle";
+  readonly serviceManager: ManagedServiceManagerState;
+}
+
+/** Durable, platform-neutral service-manager state captured before conversion. */
+export interface ManagedServiceManagerState {
+  readonly loaded: boolean;
+  readonly active: boolean;
+  readonly enabled: boolean;
+}
+
+export interface ManagedServiceDefinitionState {
+  readonly ownership: "missing" | "managed" | "legacy";
+  readonly manager: ManagedServiceManagerState;
+}
+
+export interface ManagedRuntimeInstallIdentity {
+  readonly nonce: string;
+  readonly ownerPid: number;
+}
+
+export interface ManagedRuntimeOwnerIdentity {
+  readonly uid: number;
+  readonly startedAt: string;
+}
+
+export type ManagedRuntimeInstallStartupState =
+  | "none"
+  | "live"
+  | "stale"
+  | "attested"
+  | "unknown";
+
+export interface CompatibilityProbe {
+  readonly platform?: NodeJS.Platform;
+  readonly arch?: string;
+  readonly kernelVersion?: string;
+  readonly macosVersion?: string;
+  readonly glibcVersion?: string | null;
+  readonly uid?: number;
+}
+
+/**
+ * Why the activation gate is being consulted, so the caller can hold two
+ * policies. Legacy conversion takes over ANOTHER service's live workload —
+ * its tasks do not survive the takeover, so it needs every task idle. A
+ * managed version update only restarts our own service, which running tasks
+ * survive by design (durable sessions); it needs only in-flight lifecycle
+ * mutations drained. Live 2026-08-17: one strict policy for both made every
+ * update fail while any task merely EXISTED.
+ */
+export interface ActivationGateContext {
+  readonly legacyConversion: boolean;
+}
+
+export interface InstallManagedRuntimeOptions {
+  readonly archivePath: string;
+  readonly artifact: ReleaseArtifact;
+  readonly version: string;
+  readonly platform: ReleasePlatform;
+  readonly home?: string;
+  readonly allowDowngrade?: boolean;
+  readonly compatibility?: CompatibilityProbe;
+  /** Rechecked immediately before an automatic activation. */
+  readonly canActivate?: (
+    context: ActivationGateContext,
+  ) => boolean | Promise<boolean>;
+  /** Explicit operator action may release a prior rollback's auto-update hold. */
+  readonly releaseRollbackUpdateHold?: boolean;
+  /** Capability returned by `beginManagedRuntimeInstall` for public bootstrap. */
+  readonly installIntent?: string;
+}
+
+export interface UpdateManagedRuntimeOptions {
+  readonly home?: string;
+  readonly manifestUrl?: string;
+  readonly releaseBaseUrl?: string;
+  readonly trustedKeys?: ReadonlyMap<string, PinnedReleaseManifestKey>;
+  readonly fetchImpl?: typeof fetch;
+  readonly compatibility?: CompatibilityProbe;
+  readonly canActivate?: (
+    context: ActivationGateContext,
+  ) => boolean | Promise<boolean>;
+  readonly manifestTimeoutMs?: number;
+  readonly artifactTimeoutMs?: number;
+  /** Manual `uai-host update` opts in; automatic checks deliberately do not. */
+  readonly releaseRollbackUpdateHold?: boolean;
+}
+
+export type ManagedUpdateResult =
+  | { readonly status: "not-managed" }
+  | { readonly status: "deferred"; readonly version: string }
+  | { readonly status: "current"; readonly version: string }
+  | {
+      readonly status: "updated";
+      readonly fromVersion: string;
+      readonly version: string;
+    };
+
+export function managedRuntimePaths(home?: string): ManagedRuntimePaths {
+  const explicitHome = home !== undefined;
+  const resolvedHome = path.resolve(home ?? homedir());
+  if (resolvedHome === path.parse(resolvedHome).root) {
+    throw new Error("refusing to use a filesystem root as the managed host home");
+  }
+  const root = path.join(resolvedHome, ".uai-host");
+  const runtime = path.join(root, "runtime");
+  const configuredUaiHome = !explicitHome && process.env.UAI_HOME
+    ? path.resolve(expandManagedHome(process.env.UAI_HOME, resolvedHome))
+    : !explicitHome && process.env.UAI_DATA_DIR
+      ? path.dirname(path.resolve(expandManagedHome(process.env.UAI_DATA_DIR, resolvedHome)))
+      : path.join(resolvedHome, ".uai");
+  const configuredDataDir = !explicitHome && process.env.UAI_DATA_DIR
+    ? path.resolve(expandManagedHome(process.env.UAI_DATA_DIR, resolvedHome))
+    : path.join(configuredUaiHome, "data");
+  return {
+    home: resolvedHome,
+    root,
+    runtime,
+    current: path.join(runtime, "current"),
+    previous: path.join(runtime, "previous"),
+    shim: path.join(resolvedHome, ".local", "bin", "uai-host"),
+    recoveryEntrypoint: path.join(root, "bin", "uai-host-recover"),
+    recoveryShim: path.join(resolvedHome, ".local", "bin", "uai-host-recover"),
+    data: configuredUaiHome,
+    rollbackJournal: path.join(runtime, ".rollback.json"),
+    rollbackUpdateHold: path.join(runtime, ".rollback-update-hold.json"),
+    minimumRuntimeCapability: path.join(
+      configuredUaiHome,
+      ".minimum-runtime-capability.json",
+    ),
+    runtimeProviderState: path.join(configuredDataDir, "container-runtime-provider.json"),
+    // The lock must not live inside `root`: uninstall atomically renames that
+    // whole tree, and moving the lock would let another process create a new
+    // root and enter before deletion finishes.
+    operationLock: path.join(resolvedHome, ".uai-host.operation.lock"),
+    activationPending: path.join(runtime, ".activation-pending.json"),
+    maintenancePending: path.join(
+      resolvedHome,
+      ".uai-host.maintenance-pending.json",
+    ),
+    uninstallPendingRoot: path.join(
+      resolvedHome,
+      ".uai-host.uninstall-pending",
+    ),
+    installIntent: path.join(resolvedHome, ".uai-host.install-intent.json"),
+    legacyShimTakeover: path.join(
+      resolvedHome,
+      ".uai-host.legacy-shim-takeover.json",
+    ),
+    legacyShimBackup: path.join(
+      resolvedHome,
+      ".local",
+      "bin",
+      ".uai-host.legacy-backup",
+    ),
+  };
+}
+
+function expandManagedHome(value: string, home: string): string {
+  if (value === "~") return home;
+  if (value.startsWith("~/")) return path.join(home, value.slice(2));
+  return value;
+}
+
+export function nativeReleasePlatform(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): ReleasePlatform {
+  const os = platform === "darwin" ? "darwin" : platform === "linux" ? "linux" : null;
+  const cpu = arch === "arm64" ? "arm64" : arch === "x64" ? "x64" : null;
+  const value = os && cpu ? `${os}-${cpu}` : `${platform}-${arch}`;
+  if (!isReleasePlatform(value)) {
+    throw new Error(`unsupported managed host platform: ${value}`);
+  }
+  return value;
+}
+
+export function assertRuntimeCompatibility(probe: CompatibilityProbe = {}): ReleasePlatform {
+  const platform = probe.platform ?? process.platform;
+  const arch = probe.arch ?? process.arch;
+  const releasePlatform = nativeReleasePlatform(platform, arch);
+  const uid = probe.uid ?? process.getuid?.() ?? -1;
+  if (uid === 0) {
+    throw new Error("the managed host installer refuses to run with sudo or as root");
+  }
+  if (platform === "darwin") {
+    const version = probe.macosVersion ?? readMacosVersion();
+    assertMinimumVersion(version, "13.5", "macOS");
+    return releasePlatform;
+  }
+
+  assertMinimumVersion(probe.kernelVersion ?? osRelease(), "4.18", "Linux kernel");
+  const glibc = probe.glibcVersion === undefined ? readGlibcVersion() : probe.glibcVersion;
+  if (!glibc) {
+    throw new Error("managed Linux hosts require glibc 2.29 or newer; musl/Alpine is unsupported");
+  }
+  assertMinimumVersion(glibc, "2.29", "glibc");
+  return releasePlatform;
+}
+
+export function compareStableVersions(left: string, right: string): number {
+  const a = parseStableVersion(left);
+  const b = parseStableVersion(right);
+  for (let index = 0; index < a.length; index += 1) {
+    const delta = a[index]! - b[index]!;
+    if (delta !== 0) return delta < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+export async function currentManagedVersion(home?: string): Promise<string | null> {
+  const paths = managedRuntimePaths(home);
+  return readVersionLink(paths.current, paths.runtime);
+}
+
+export async function installManagedRuntimeArchive(
+  options: InstallManagedRuntimeOptions,
+): Promise<{
+  version: string;
+  previousVersion: string | null;
+  changed: boolean;
+  deferred: boolean;
+}> {
+  assertStableVersion(options.version);
+  const nativePlatform = assertRuntimeCompatibility(options.compatibility);
+  if (nativePlatform !== options.platform) {
+    throw new Error(
+      `runtime archive targets ${options.platform}, but this host is ${nativePlatform}`,
+    );
+  }
+  const paths = managedRuntimePaths(options.home);
+  const operation = async () => {
+    await reconcileInterruptedRemovalForInstall(paths);
+    const storedInstallIntent = await readInstallIntent(paths);
+    let installIntent: InstallIntentMarker | null = null;
+    if (options.installIntent) {
+      installIntent = await requireInstallIntent(
+        paths,
+        options.installIntent,
+        true,
+      );
+      if (installIntent.phase === "attested") {
+        throw new Error("managed host install is already attested and must complete");
+      }
+      if (
+        installIntent.serviceOwnership === "legacy" &&
+        installIntent.priorServiceStop !== "stopped"
+      ) {
+        throw new Error(
+          "managed host legacy service must be durably quiesced before runtime activation",
+        );
+      }
+      if (
+        installIntent.serviceOwnership === "legacy" &&
+        !options.canActivate
+      ) {
+        throw new Error(
+          "managed host legacy conversion requires a final workload-idle gate",
+        );
+      }
+    } else if (storedInstallIntent) {
+      throw new Error(
+        "managed host runtime activation requires the active install intent",
+      );
+    }
+    await ensureManagedDirectories(paths);
+    await recoverRollback(paths);
+    const currentVersion = await readVersionLink(paths.current, paths.runtime);
+    const rollbackUpdateHold = options.releaseRollbackUpdateHold
+      ? await readRollbackUpdateHold(paths)
+      : null;
+    if (
+      currentVersion &&
+      compareStableVersions(options.version, currentVersion) < 0 &&
+      !options.allowDowngrade
+    ) {
+      throw new Error(
+        `refusing to downgrade managed host ${currentVersion} to ${options.version}; use rollback or an explicit downgrade`,
+      );
+    }
+    const activationContext: ActivationGateContext = {
+      legacyConversion: installIntent?.serviceOwnership === "legacy",
+    };
+
+    // A true managed same-version rerun has no activation edge to gate. A
+    // legacy conversion is different: taking over its command/service is the
+    // activation edge, so it still needs the final workload-idle proof below.
+    // Otherwise validate the selected runtime, repair the stable shim, and
+    // keep a harmless managed rerun idempotent even while tasks are active.
+    if (currentVersion === options.version) {
+      // The rerun keeps this exact generation, so it must fully validate.
+      // Every other path below replaces current — validating the generation
+      // being abandoned would let its own corruption block the escape route.
+      const currentDescriptor = await validateInstalledRuntime(
+        path.join(paths.runtime, currentVersion),
+        currentVersion,
+        nativePlatform,
+      );
+      await assertRuntimeMeetsDurableCapabilityFloor(paths, currentDescriptor);
+      if (
+        installIntent?.serviceOwnership === "legacy" &&
+        !(await options.canActivate!({ legacyConversion: true }))
+      ) {
+        return {
+          version: options.version,
+          previousVersion: await readVersionLink(paths.previous, paths.runtime),
+          changed: false,
+          deferred: true,
+        };
+      }
+      if (installIntent) await parkLegacyShimTakeover(paths);
+      await ensureStableCommands(paths);
+      if (rollbackUpdateHold) {
+        await removeRollbackUpdateHold(paths, rollbackUpdateHold);
+      }
+      if (installIntent) {
+        await advanceInstallIntentToActivated(paths, installIntent);
+      }
+      return {
+        version: options.version,
+        previousVersion: await readVersionLink(paths.previous, paths.runtime),
+        changed: false,
+        deferred: false,
+      };
+    }
+
+    const archiveBytes = await readVerifiedArtifactFile(options.archivePath, options.artifact);
+    const work = await mkdtemp(path.join(paths.runtime, ".install-"));
+    await chmod(work, 0o700);
+    const staged = path.join(work, "payload");
+    const target = path.join(paths.runtime, options.version);
+    try {
+      const inspected = await extractVerifiedRuntimeArchive(archiveBytes, staged, {
+        version: options.version,
+        platform: options.platform,
+      });
+      await assertRuntimeMeetsDurableCapabilityFloor(paths, {
+        ...inspected.descriptor,
+        ...inspected.capabilities,
+      });
+      if (
+        options.canActivate &&
+        !(await options.canActivate(activationContext))
+      ) {
+        return {
+          version: options.version,
+          previousVersion: currentVersion,
+          changed: false,
+          deferred: true,
+        };
+      }
+      if (installIntent) await parkLegacyShimTakeover(paths);
+      await assertStableCommandsReplaceable(paths);
+      await writeAtomicJson(paths.activationPending, {
+        schemaVersion: 1,
+        fromVersion: currentVersion,
+        version: options.version,
+      });
+      let activated = false;
+      try {
+        // The durable gate makes the running service reject new taskUp calls;
+        // this second check catches work that began immediately before it.
+        if (
+        options.canActivate &&
+        !(await options.canActivate(activationContext))
+      ) {
+          return {
+            version: options.version,
+            previousVersion: currentVersion,
+            changed: false,
+            deferred: true,
+          };
+        }
+        if (await pathExists(target)) {
+          const targetDescriptor = await validateInstalledRuntime(
+            target,
+            options.version,
+            options.platform,
+          );
+          await assertRuntimeMeetsDurableCapabilityFloor(paths, targetDescriptor);
+        } else {
+          await rename(staged, target);
+          await syncDirectory(paths.runtime);
+        }
+        if (
+        options.canActivate &&
+        !(await options.canActivate(activationContext))
+      ) {
+          return {
+            version: options.version,
+            previousVersion: currentVersion,
+            changed: false,
+            deferred: true,
+          };
+        }
+        await atomicVersionLink(paths.current, options.version);
+        activated = true;
+        if (currentVersion) await atomicVersionLink(paths.previous, currentVersion);
+        await ensureStableCommands(paths);
+        await pruneRuntimeGenerations(paths);
+        if (rollbackUpdateHold) {
+          await removeRollbackUpdateHold(paths, rollbackUpdateHold);
+        }
+        if (installIntent) {
+          await advanceInstallIntentToActivated(paths, installIntent);
+        }
+        return {
+          version: options.version,
+          previousVersion: currentVersion,
+          changed: true,
+          deferred: false,
+        };
+      } finally {
+        if (
+          !activated &&
+          (await readVersionLink(paths.current, paths.runtime)) !== options.version
+        ) {
+          await removeDurably(paths.activationPending);
+        }
+      }
+    } finally {
+      await rm(work, { recursive: true, force: true });
+      await syncDirectory(paths.runtime);
+    }
+  };
+  const internal = options as InstallManagedRuntimeOptions & {
+    [OPERATION_LOCK_HELD]?: true;
+  };
+  return internal[OPERATION_LOCK_HELD]
+    ? operation()
+    : withManagedOperationLock(paths, operation);
+}
+
+export async function updateManagedRuntime(
+  options: UpdateManagedRuntimeOptions = {},
+): Promise<ManagedUpdateResult> {
+  const paths = managedRuntimePaths(options.home);
+  if (pathExistsSync(paths.installIntent)) {
+    throw new Error("managed host update is fenced by an installation intent");
+  }
+  if (!(await currentManagedVersion(paths.home))) return { status: "not-managed" };
+  const platform = assertRuntimeCompatibility(options.compatibility);
+  const trustedKeys = options.trustedKeys ?? PINNED_RELEASE_MANIFEST_KEYS;
+  if (trustedKeys.size === 0) {
+    throw new Error("managed host updates are unavailable: no release signing key is pinned");
+  }
+  return withManagedOperationLock(paths, async () => {
+    await assertNoManagedInstallIntent(paths, "update");
+    if (!(await pathExists(paths.root))) return { status: "not-managed" };
+    await ensureManagedDirectories(paths);
+    await recoverRollback(paths);
+    const current = await readVersionLink(paths.current, paths.runtime);
+    if (!current) return { status: "not-managed" };
+    const rollbackUpdateHold = await readRollbackUpdateHold(paths);
+    if (rollbackUpdateHold && !options.releaseRollbackUpdateHold) {
+      // Rollback is an explicit verdict that the newer release is unsafe on
+      // this host. Automatic checks stay completely offline until an operator
+      // explicitly runs `uai-host update` and a signed check succeeds.
+      return { status: "current", version: current };
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const manifestBytes = await fetchBounded(
+      fetchImpl,
+      options.manifestUrl ?? STABLE_RELEASE_MANIFEST_URL,
+      MAX_RELEASE_MANIFEST_BYTES,
+      checkedTimeout(options.manifestTimeoutMs, MANAGED_MANIFEST_TIMEOUT_MS, 60_000),
+    );
+    const manifest = verifyReleaseManifest(manifestBytes, {
+      trustedKeys,
+      releaseBaseUrl: options.releaseBaseUrl ?? DEFAULT_RELEASE_DOWNLOAD_BASE,
+    });
+    if (compareStableVersions(manifest.version, current) <= 0) {
+      if (rollbackUpdateHold && options.releaseRollbackUpdateHold) {
+        await removeRollbackUpdateHold(paths, rollbackUpdateHold);
+      }
+      return { status: "current", version: current };
+    }
+    const artifact = releaseArtifactForPlatform(manifest, platform);
+    const downloadDir = await mkdtemp(path.join(paths.runtime, ".download-"));
+    await chmod(downloadDir, 0o700);
+    const archivePath = path.join(
+      downloadDir,
+      releaseArtifactFilename(manifest.version, platform),
+    );
+    try {
+      await downloadArtifact(
+        fetchImpl,
+        artifact,
+        archivePath,
+        checkedTimeout(
+          options.artifactTimeoutMs,
+          MANAGED_ARTIFACT_TIMEOUT_MS,
+          30 * 60_000,
+        ),
+      );
+      const installed = await installManagedRuntimeArchive({
+        archivePath,
+        artifact,
+        version: manifest.version,
+        platform,
+        // Forward the caller's (possibly absent) home verbatim: an explicit
+        // home pins data/floor paths to `<home>/.uai` and DISABLES the
+        // UAI_HOME/UAI_DATA_DIR lookup, so substituting the resolved
+        // `paths.home` here would make the nested install read the durable
+        // capability floor from the wrong directory on env-configured hosts.
+        home: options.home,
+        compatibility: options.compatibility,
+        canActivate: options.canActivate,
+        releaseRollbackUpdateHold: options.releaseRollbackUpdateHold,
+        [OPERATION_LOCK_HELD]: true,
+      } as InstallManagedRuntimeOptions & { [OPERATION_LOCK_HELD]: true });
+      if (installed.deferred) {
+        return { status: "deferred", version: manifest.version };
+      }
+      return { status: "updated", fromVersion: current, version: manifest.version };
+    } finally {
+      await rm(downloadDir, { recursive: true, force: true });
+      await syncDirectory(paths.runtime);
+    }
+  });
+}
+
+export async function rollbackManagedRuntime(
+  home?: string,
+  compatibility?: CompatibilityProbe,
+  canActivate?: () => boolean | Promise<boolean>,
+): Promise<{ fromVersion: string; version: string }> {
+  const paths = managedRuntimePaths(home);
+  const platform = assertRuntimeCompatibility(compatibility);
+  return withManagedOperationLock(paths, async () => {
+    await assertNoManagedInstallIntent(paths, "rollback");
+    await ensureManagedDirectories(paths);
+    const recovered = await recoverRollback(paths);
+    if (recovered) {
+      await ensureStableCommands(paths);
+      return recovered;
+    }
+    const fromVersion = await readVersionLink(paths.current, paths.runtime);
+    const version = await readVersionLink(paths.previous, paths.runtime);
+    if (!fromVersion || !version || fromVersion === version) {
+      throw new Error("no previous managed host runtime is available to roll back to");
+    }
+    // Only the generation being switched TO validates (plus the capability
+    // floor below). Rollback exists precisely for a damaged current; requiring
+    // the abandoned generation to validate would block every escape route.
+    const targetDescriptor = await validateInstalledRuntime(
+      path.join(paths.runtime, version),
+      version,
+      platform,
+    );
+    await assertRuntimeMeetsDurableCapabilityFloor(paths, targetDescriptor);
+    if (canActivate && !(await canActivate())) {
+      throw new Error("refusing to roll back while host tasks are active");
+    }
+    await assertStableCommandsReplaceable(paths);
+    await writeAtomicJson(paths.activationPending, {
+      schemaVersion: 1,
+      fromVersion,
+      version,
+    });
+    let activated = false;
+    try {
+      if (canActivate && !(await canActivate())) {
+        throw new Error("refusing to roll back while host tasks are active");
+      }
+      await writeAtomicJson(paths.rollbackJournal, { schemaVersion: 1, fromVersion, version });
+      await atomicVersionLink(paths.current, version);
+      activated = true;
+      await atomicVersionLink(paths.previous, fromVersion);
+      await writeRollbackUpdateHold(paths, fromVersion, version);
+      await removeDurably(paths.rollbackJournal);
+      await ensureStableCommands(paths);
+      return { fromVersion, version };
+    } finally {
+      if (
+        !activated &&
+        (await readVersionLink(paths.current, paths.runtime)) !== version
+      ) {
+        // The journal precedes the current-link commit. If activation never
+        // committed, remove both pieces of intent; otherwise a later recovery
+        // could flip versions after admission reopened.
+        await removeDurably(paths.rollbackJournal);
+        await removeDurably(paths.activationPending);
+      }
+    }
+  });
+}
+
+/**
+ * Claim the minimum managed-runtime capability before the bundled runtime's
+ * first durable provider claim. The managed-operation lock makes this atomic
+ * with rollback:
+ * either rollback sees the floor and refuses capability 1, or the task sees the
+ * staged activation and cannot create provider state.
+ */
+export async function claimManagedRuntimeCapabilityFloor(
+  minimumCapabilityVersion = 2,
+  home?: string,
+): Promise<void> {
+  if (!Number.isSafeInteger(minimumCapabilityVersion) || minimumCapabilityVersion < 2) {
+    throw new Error("managed runtime capability floor is invalid");
+  }
+  const paths = managedRuntimePaths(home);
+  // Waiting acquisition: this runs during runtime detection, concurrently
+  // with the startup settlement's own locked read. First-collision-dies took
+  // the whole service down at boot (live 2026-08-16, launchd boots exiting 1
+  // with "another managed host install/update/rollback is already running"
+  // while no external holder existed).
+  await withManagedOperationLockWaiting(paths, async () => {
+    await assertNoManagedInstallIntent(paths, "runtime capability claim");
+    await ensureManagedDirectories(paths);
+    if (
+      pathExistsSync(paths.activationPending) ||
+      pathExistsSync(paths.rollbackJournal) ||
+      pathExistsSync(paths.maintenancePending)
+    ) {
+      throw new Error("managed runtime activation is already in progress");
+    }
+    await mkdir(path.dirname(paths.minimumRuntimeCapability), {
+      recursive: true,
+      mode: 0o700,
+    });
+    const existing = await readMinimumRuntimeCapability(paths);
+    if (existing !== null && existing >= minimumCapabilityVersion) return;
+    await writeAtomicJson(paths.minimumRuntimeCapability, {
+      schemaVersion: 1,
+      minimumRuntimeCapability: minimumCapabilityVersion,
+    });
+  });
+}
+
+/** True while `current` has changed but the supervisor has not exec'd it yet. */
+export function managedRuntimeActivationPending(home?: string): boolean {
+  return pathExistsSync(managedRuntimePaths(home).activationPending);
+}
+
+/**
+ * True while installation, activation, or destructive maintenance has closed
+ * new
+ * task admission. The maintenance marker is outside the runtime tree so
+ * uninstall cannot accidentally remove its own gate before teardown finishes.
+ * Existence is intentionally fail-closed: a malformed marker still blocks
+ * taskUp and must be repaired by a safe uninstall retry.
+ */
+export function managedRuntimeAdmissionPending(home?: string): boolean {
+  const paths = managedRuntimePaths(home);
+  return (
+    pathExistsSync(paths.activationPending) ||
+    pathExistsSync(paths.maintenancePending) ||
+    pathExistsSync(paths.installIntent)
+  );
+}
+
+/**
+ * True only after an activation marker's target has become `current` and the
+ * process asking is still running a different version. The marker is written
+ * before the link flip so task admission can close first; checking both
+ * records prevents the old service from restarting during that preparation
+ * window.
+ */
+export async function managedRuntimeRestartRequired(
+  runningVersion: string,
+  home?: string,
+): Promise<boolean> {
+  assertStableVersion(runningVersion);
+  const paths = managedRuntimePaths(home);
+  const current = await readVersionLink(paths.current, paths.runtime);
+  if (current === null || current === runningVersion) return false;
+  let marker: ActivationMarker;
+  try {
+    marker = parseActivationMarker(
+      await readBoundedRegularFile(paths.activationPending),
+    );
+  } catch (error) {
+    // The selected process may already have acknowledged and removed the
+    // marker while this older process was still alive. A `current` mismatch is
+    // independently sufficient to require a supervisor restart.
+    if (isMissing(error)) return true;
+    throw error;
+  }
+  if (current !== marker.version) {
+    throw new Error("managed host activation marker does not match the current runtime");
+  }
+  return true;
+}
+
+/** Reconcile an external activation attempt from the already-running daemon. */
+export async function reconcileManagedRuntimeActivation(
+  runningVersion: string,
+  home?: string,
+): Promise<boolean> {
+  // A provisional service runs while its public installer owns the operation
+  // lock. The install intent itself gates taskUp; leave the activation marker
+  // intact until attestation removes that intent, then acknowledge normally.
+  if (pathExistsSync(managedRuntimePaths(home).installIntent)) return false;
+  if (managedRuntimeActivationPending(home)) {
+    // A live activating process holds the operation lock, so this throws and
+    // the watcher retries. Once the owner exits, startup settlement either
+    // aborts its pre-link intent or reports that a restart is required.
+    return !(await acknowledgeManagedRuntimeActivation(runningVersion, home));
+  }
+  return managedRuntimeRestartRequired(runningVersion, home);
+}
+
+/**
+ * Prove that this process is the runtime selected by `current` without opening
+ * task admission. `cmdRun` performs this before importing the service module;
+ * the activation marker deliberately remains until that import succeeds.
+ */
+export async function validateManagedRuntimeSelection(
+  runningVersion: string,
+  home?: string,
+): Promise<boolean> {
+  return reconcileManagedRuntimeSelection(runningVersion, home, false);
+}
+
+/**
+ * Prove the generation selected for a provisional daemon without taking the
+ * operation lock held by its own service-definition installer. This never
+ * acknowledges activation: the live install intent remains the task-admission
+ * fence until shell attestation commits, after which the activation watcher
+ * performs the ordinary locked acknowledgement.
+ */
+export async function validateProvisionalManagedRuntimeSelection(
+  runningVersion: string,
+  home?: string,
+): Promise<boolean> {
+  assertStableVersion(runningVersion);
+  const paths = managedRuntimePaths(home);
+  const intent = await readInstallIntent(paths);
+  if (!intent || (intent.phase !== "activated" && intent.phase !== "attested")) {
+    throw new Error("managed host provisional service has no activated install intent");
+  }
+  const current = await readVersionLink(paths.current, paths.runtime);
+  if (current === null) {
+    throw new Error("managed host provisional service has no selected runtime");
+  }
+  let marker: ActivationMarker | null = null;
+  try {
+    marker = parseActivationMarker(
+      await readBoundedRegularFile(paths.activationPending),
+    );
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+  if (marker && marker.version !== current) {
+    throw new Error("managed host activation marker does not match the current runtime");
+  }
+  return current === runningVersion;
+}
+
+/**
+ * Settle a pending activation before `run` accepts work. `true` means this
+ * process is safe to start: it either acknowledged the selected version or
+ * recovered an abandoned pre-link intent and kept the prior version current.
+ * `false` means `current` selected another version, so this stale process must
+ * exit and let the supervisor launch the stable shim again.
+ */
+export async function acknowledgeManagedRuntimeActivation(
+  runningVersion: string,
+  home?: string,
+): Promise<boolean> {
+  return reconcileManagedRuntimeSelection(runningVersion, home, true);
+}
+
+async function reconcileManagedRuntimeSelection(
+  runningVersion: string,
+  home: string | undefined,
+  acknowledgeHealthyImport: boolean,
+): Promise<boolean> {
+  assertStableVersion(runningVersion);
+  const paths = managedRuntimePaths(home);
+  if (!(await pathExists(paths.root))) return true;
+  // Busy handling is holder-dependent. An INSTALLER-owned lock (install
+  // intent on disk) must fail fast: a provisional boot defers to the
+  // installer, and the intent-hold test pins that contract. A lock held by a
+  // SIBLING boot step (detection's capability-floor claim) is milliseconds —
+  // first-collision-dies there killed launchd boots with "already running"
+  // while no external holder existed (live 2026-08-16).
+  const deadline = Date.now() + OPERATION_LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      return await reconcileManagedRuntimeSelectionLocked(
+        runningVersion,
+        paths,
+        acknowledgeHealthyImport,
+      );
+    } catch (error) {
+      if (
+        !(error instanceof ManagedOperationBusyError) ||
+        pathExistsSync(paths.installIntent) ||
+        Date.now() >= deadline
+      ) {
+        throw error;
+      }
+      await new Promise<void>((resolve) =>
+        setTimeout(resolve, OPERATION_LOCK_POLL_MS),
+      );
+    }
+  }
+}
+
+async function reconcileManagedRuntimeSelectionLocked(
+  runningVersion: string,
+  paths: ManagedRuntimePaths,
+  acknowledgeHealthyImport: boolean,
+): Promise<boolean> {
+  return withManagedOperationLock(paths, async () => {
+    await ensureManagedDirectories(paths);
+    await recoverRollback(paths);
+    const selectedVersion = await readVersionLink(paths.current, paths.runtime);
+    if (selectedVersion !== null) {
+      const selectedDescriptor = await validateInstalledRuntime(
+        path.join(paths.runtime, selectedVersion),
+        selectedVersion,
+      );
+      await assertRuntimeMeetsDurableCapabilityFloor(paths, selectedDescriptor);
+    }
+    let marker: ActivationMarker;
+    try {
+      marker = parseActivationMarker(
+        await readBoundedRegularFile(paths.activationPending),
+      );
+    } catch (error) {
+      // Another process may have deferred and removed the marker between the
+      // caller's synchronous admission check and lock acquisition. It may also
+      // have acknowledged a newly selected runtime, so compare `current`
+      // before allowing this process to continue.
+      if (isMissing(error)) {
+        const current = await readVersionLink(paths.current, paths.runtime);
+        return current === null || current === runningVersion;
+      }
+      throw error;
+    }
+    const current = await readVersionLink(paths.current, paths.runtime);
+    if (current === marker.version) {
+      if (marker.fromVersion) {
+        // `current` is the commit point. Repair a crash between that link and
+        // `previous`, then keep admission closed until the selected binary is
+        // the process performing the acknowledgement.
+        await atomicVersionLink(paths.previous, marker.fromVersion);
+      }
+      if (marker.version !== runningVersion) return false;
+      if (acknowledgeHealthyImport) {
+        await removeDurably(paths.activationPending);
+      }
+      return true;
+    }
+    if (current === marker.fromVersion) {
+      // The activating process died before committing `current`. Its durable
+      // intent closed admission, but there is nothing to restart into. Abort
+      // the intent and continue only if this process is the still-current
+      // runtime.
+      const selected = current === null || current === runningVersion;
+      if (selected && acknowledgeHealthyImport) {
+        await removeDurably(paths.activationPending);
+      }
+      return selected;
+    }
+    throw new Error(
+      "managed host activation marker does not match the current runtime",
+    );
+  });
+}
+
+/**
+ * Bundled-installer preflight. This must run before enrollment is inspected or
+ * spent: a committed `--purge` uninstall owns the old identity directory too.
+ * `installManagedRuntimeArchive` repeats the same check under its own lock to
+ * close the preflight-to-activation race.
+ */
+export async function reconcileManagedRuntimeUninstall(
+  home?: string,
+): Promise<boolean> {
+  const paths = managedRuntimePaths(home);
+  return withManagedOperationLock(paths, () =>
+    reconcileInterruptedRemovalForInstall(paths),
+  );
+}
+
+/**
+ * Start the public install transaction before enrollment is read or attached.
+ * The external marker fences `uninstall --purge` after this function releases
+ * the short-lived filesystem lock. The legacy command is only recorded here;
+ * it remains callable until install-archive runs after service stop.
+ */
+export async function beginManagedRuntimeInstall(
+  options: BeginManagedRuntimeInstallOptions,
+): Promise<ManagedRuntimeInstallIntent> {
+  assertOwnerPid(options.ownerPid);
+  const owner = processIdentity(options.ownerPid);
+  if (!owner) {
+    throw new Error("managed host installer owner process is not running");
+  }
+  const currentUid = process.getuid?.();
+  if (currentUid !== undefined && owner.uid !== currentUid) {
+    throw new Error("managed host installer owner process belongs to another user");
+  }
+  const paths = managedRuntimePaths(options.home);
+  return withManagedOperationLock(paths, async () => {
+    await reconcileInterruptedRemovalForInstall(paths);
+    const existing = await readInstallIntent(paths);
+    if (existing) {
+      const live = installIntentOwnerIsLive(existing);
+      if (live) {
+        if (
+          existing.ownerPid !== options.ownerPid ||
+          existing.ownerStartedAt !== owner.startedAt ||
+          existing.ownerUid !== owner.uid
+        ) {
+          throw new Error("another managed host installation is already running");
+        }
+        return {
+          nonce: existing.nonce,
+          legacyShim: (await readLegacyShimTakeover(paths)) !== null,
+          serviceOwnership: existing.serviceOwnership,
+          serviceQuiescence:
+            existing.serviceOwnership === "legacy" ? "quiesce" : "idle",
+          serviceManager: existing.serviceManager,
+        };
+      }
+      if (existing.phase === "attested") {
+        // Attestation is the durable commit decision. A killed shell after it
+        // may finish, but must never restore the old definition or command.
+        if (!options.beforeFinalize) {
+          throw new Error("managed host install recovery cannot commit its service definition");
+        }
+        await options.beforeFinalize(existing.nonce);
+        await finalizeLegacyShimTakeover(paths);
+        await removeDurably(paths.installIntent);
+      } else {
+        // A prior definition may execute the legacy command. Restore it without
+        // starting first, then restore runtime selection/command ownership, and
+        // only then resume the recorded prior service. Every step is idempotent;
+        // the old intent remains fail-closed until all three have succeeded.
+        if (!options.prepareRecovery || !options.resumeRecovery) {
+          throw new Error("managed host install recovery cannot restore its prior service");
+        }
+        await options.prepareRecovery(existing.nonce);
+        await restorePreInstallRuntimeSelection(paths, existing);
+        await restoreLegacyShimTakeover(paths);
+        await options.resumeRecovery(existing.nonce);
+        if (existing.priorServiceStop !== "none") {
+          if (!options.resumeStoppedService) {
+            throw new Error(
+              "managed host install recovery cannot resume its prior service",
+            );
+          }
+          await options.resumeStoppedService(
+            existing.nonce,
+            existing.serviceManager,
+          );
+        }
+        await removeDurably(paths.installIntent);
+      }
+    }
+    // A standalone `uai-host install` can leave an owner-null definition
+    // journal. Settle it after any dead public transaction and immediately
+    // before ownership classification. A protected journal refuses this
+    // ownerless callback and therefore cannot be adopted by a new nonce.
+    await options.reconcileStandaloneDefinition?.();
+    if (await readLegacyShimTakeover(paths)) {
+      throw new Error(
+        "managed host legacy command takeover has no install intent; repair the interrupted install",
+      );
+    }
+
+    const preInstall = await capturePreInstallState(paths);
+    const service = await options.definitionState(paths.shim);
+    assertServiceDefinitionState(service);
+    if (
+      service.ownership === "missing" &&
+      (service.manager.loaded ||
+        service.manager.active ||
+        service.manager.enabled)
+    ) {
+      throw new Error(
+        "managed host service manager reports state for a missing definition",
+      );
+    }
+    const serviceOwnership = service.ownership;
+    const marker: InstallIntentMarker = {
+      schemaVersion: 1,
+      operation: "install",
+      phase: "prepared",
+      nonce: randomBytes(32).toString("hex"),
+      ownerPid: options.ownerPid,
+      ownerUid: owner.uid,
+      ownerStartedAt: owner.startedAt,
+      createdAt: Date.now(),
+      rootExisted: preInstall.rootExisted,
+      currentVersion: preInstall.currentVersion,
+      previousVersion: preInstall.previousVersion,
+      activationPending: preInstall.activationPending,
+      shimOwnership: preInstall.shimOwnership,
+      recoveryShimExisted: preInstall.recoveryShimExisted,
+      recoveryEntrypointExisted: preInstall.recoveryEntrypointExisted,
+      serviceOwnership,
+      serviceManager: service.manager,
+      priorServiceStop: "none",
+    };
+    await writeAtomicJson(paths.installIntent, marker);
+    if (marker.shimOwnership === "legacy") {
+      const legacyShim = await recordLegacyShimTakeover(paths);
+      if (!legacyShim) {
+        throw new Error("recorded legacy host command disappeared during install begin");
+      }
+    }
+    return {
+      nonce: marker.nonce,
+      legacyShim: marker.shimOwnership === "legacy",
+      serviceOwnership,
+      serviceQuiescence:
+        serviceOwnership === "legacy" ? "quiesce" : "idle",
+      serviceManager: service.manager,
+    };
+  });
+}
+
+/** A provisional daemon may connect for shell attestation only while its
+ * installer shell is still the exact live process that owns the intent. */
+export async function managedRuntimeInstallStartupState(
+  home?: string,
+  identityProbe: (pid: number) => ManagedRuntimeOwnerIdentity | null = processIdentity,
+): Promise<ManagedRuntimeInstallStartupState> {
+  const paths = managedRuntimePaths(home);
+  if (!pathExistsSync(paths.installIntent)) return "none";
+  const intent = await readInstallIntent(paths);
+  if (!intent) return "none";
+  try {
+    if (installIntentOwnerIsLive(intent, identityProbe)) return "live";
+  } catch (error) {
+    if (error instanceof ProcessIdentityUnavailableError) return "unknown";
+    throw error;
+  }
+  return intent.phase === "attested" ? "attested" : "stale";
+}
+
+export async function validateManagedRuntimeInstallIntent(
+  installIntent: string,
+  home?: string,
+): Promise<ManagedRuntimeInstallIdentity> {
+  const paths = managedRuntimePaths(home);
+  return withManagedOperationLock(paths, async () => {
+    const intent = await requireInstallIntent(paths, installIntent, true);
+    if (intent.phase !== "activated") {
+      throw new Error(
+        "managed host install intent is not ready for service definition installation",
+      );
+    }
+    return { nonce: intent.nonce, ownerPid: intent.ownerPid };
+  });
+}
+
+/** Hold the runtime fence through an intent-owned service-definition write. */
+export async function runManagedRuntimeInstallIntentMutation<T>(options: {
+  readonly home?: string;
+  readonly installIntent: string;
+  readonly mutation: (identity: ManagedRuntimeInstallIdentity) => Promise<T>;
+}): Promise<T> {
+  const paths = managedRuntimePaths(options.home);
+  return withManagedOperationLock(paths, async () => {
+    const intent = await requireInstallIntent(paths, options.installIntent, true);
+    if (intent.phase !== "activated") {
+      throw new Error(
+        "managed host install intent is not ready for service definition installation",
+      );
+    }
+    return options.mutation({ nonce: intent.nonce, ownerPid: intent.ownerPid });
+  });
+}
+
+/**
+ * Durably stop the legacy service during first conversion. The intent write is
+ * ordered before the manager call so a killed shell is recoverable even before
+ * a service-definition journal exists.
+ */
+export async function stopManagedRuntimeServiceForInstall(options: {
+  readonly home?: string;
+  readonly installIntent: string;
+  readonly stopService: (
+    installIntent: string,
+    priorManager: ManagedServiceManagerState,
+  ) => Promise<void>;
+}): Promise<void> {
+  const paths = managedRuntimePaths(options.home);
+  await withManagedOperationLock(paths, async () => {
+    let intent = await requireInstallIntent(paths, options.installIntent, true);
+    if (intent.phase !== "prepared") {
+      throw new Error("managed host prior service may only stop before activation");
+    }
+    if (intent.serviceOwnership !== "legacy") {
+      throw new Error("managed host prior service is not a proven legacy definition");
+    }
+    if (intent.priorServiceStop === "stopped") return;
+    if (intent.priorServiceStop === "none") {
+      intent = { ...intent, priorServiceStop: "requested" };
+      await writeAtomicJson(paths.installIntent, intent);
+    }
+    await options.stopService(intent.nonce, intent.serviceManager);
+    const current = await requireInstallIntent(paths, intent.nonce, true);
+    if (current.phase !== "prepared" || current.priorServiceStop !== "requested") {
+      throw new Error("managed host install intent changed while stopping its service");
+    }
+    await writeAtomicJson(paths.installIntent, {
+      ...current,
+      priorServiceStop: "stopped",
+    } satisfies InstallIntentMarker);
+  });
+}
+
+export interface ReconcileManagedRuntimeInstallLifecycleOptions {
+  readonly home?: string;
+  readonly reconcileDefinition: (installIntent?: string) => Promise<void>;
+  readonly completeDefinition: (installIntent?: string) => Promise<void>;
+  readonly prepareDefinitionRollback: (installIntent: string) => Promise<void>;
+  readonly resumeDefinitionRollback: (installIntent: string) => Promise<void>;
+  readonly resumeStoppedService: (
+    installIntent: string,
+    priorManager: ManagedServiceManagerState,
+  ) => Promise<void>;
+}
+
+/** Reconcile service/command journals before any generic lifecycle mutation. */
+export async function reconcileManagedRuntimeInstallLifecycle(
+  options: ReconcileManagedRuntimeInstallLifecycleOptions,
+): Promise<void> {
+  const paths = managedRuntimePaths(options.home);
+  await withManagedOperationLock(paths, () =>
+    reconcileManagedRuntimeInstallLifecycleLocked(paths, options),
+  );
+}
+
+/** Keep journal reconciliation and the manager mutation in one begin-proof lock. */
+export async function runManagedRuntimeInstallLifecycleMutation<T>(
+  options: ReconcileManagedRuntimeInstallLifecycleOptions & {
+    readonly mutation: () => Promise<T>;
+  },
+): Promise<T> {
+  const paths = managedRuntimePaths(options.home);
+  return withManagedOperationLock(paths, async () => {
+    await reconcileManagedRuntimeInstallLifecycleLocked(paths, options);
+    return options.mutation();
+  });
+}
+
+async function reconcileManagedRuntimeInstallLifecycleLocked(
+  paths: ManagedRuntimePaths,
+  options: ReconcileManagedRuntimeInstallLifecycleOptions,
+): Promise<void> {
+  const intent = await readInstallIntent(paths);
+  if (!intent) {
+    await options.reconcileDefinition();
+    if (await readLegacyShimTakeover(paths)) {
+      await restoreLegacyShimTakeover(paths);
+    }
+    return;
+  }
+  if (installIntentOwnerIsLive(intent)) {
+    throw new Error(
+      "managed host lifecycle mutation is fenced by a running installation",
+    );
+  }
+  if (intent.phase === "attested") {
+    await options.completeDefinition(intent.nonce);
+    await finalizeLegacyShimTakeover(paths);
+  } else {
+    await options.prepareDefinitionRollback(intent.nonce);
+    await restorePreInstallRuntimeSelection(paths, intent);
+    await restoreLegacyShimTakeover(paths);
+    await options.resumeDefinitionRollback(intent.nonce);
+    if (intent.priorServiceStop !== "none") {
+      await options.resumeStoppedService(intent.nonce, intent.serviceManager);
+    }
+  }
+  await removeDurably(paths.installIntent);
+}
+
+export async function completeManagedRuntimeInstall(options: {
+  readonly home?: string;
+  readonly installIntent: string;
+  readonly beforeFinalize: (installIntent: string) => Promise<void>;
+}): Promise<void> {
+  const paths = managedRuntimePaths(options.home);
+  await withManagedOperationLockWaiting(paths, async () => {
+    let intent = await requireInstallIntent(paths, options.installIntent, true);
+    if (intent.phase === "prepared") {
+      throw new Error("managed host install has not activated its runtime");
+    }
+    if (intent.phase !== "attested") {
+      intent = { ...intent, phase: "attested" };
+      await writeAtomicJson(paths.installIntent, intent);
+    }
+    await options.beforeFinalize(intent.nonce);
+    await finalizeLegacyShimTakeover(paths);
+    await removeDurably(paths.installIntent);
+  });
+}
+
+export async function abortManagedRuntimeInstall(options: {
+  readonly home?: string;
+  readonly installIntent: string;
+  /** Stop the replacement and restore the prior definition without starting it. */
+  readonly prepareRestore?: (installIntent: string) => Promise<void>;
+  /** Resume the prior service after its exact runtime links/command are restored. */
+  readonly resumeRestore?: (installIntent: string) => Promise<void>;
+  /** Restart a service stopped before a definition transaction existed. */
+  readonly resumeStoppedService?: (
+    installIntent: string,
+    priorManager: ManagedServiceManagerState,
+  ) => Promise<void>;
+  /** Resume an already-attested commit instead of rolling it back. */
+  readonly beforeFinalize?: (installIntent: string) => Promise<void>;
+}): Promise<void> {
+  const paths = managedRuntimePaths(options.home);
+  await withManagedOperationLockWaiting(paths, async () => {
+    const intent = await requireInstallIntent(
+      paths,
+      options.installIntent,
+      false,
+    );
+    if (intent.phase === "attested") {
+      if (!options.beforeFinalize) {
+        throw new Error("managed host install abort cannot resume its committed service");
+      }
+      await options.beforeFinalize(intent.nonce);
+      await finalizeLegacyShimTakeover(paths);
+      await removeDurably(paths.installIntent);
+      return;
+    }
+    // If definition rollback fails, retain the install intent and legacy
+    // backup so the next abort/begin can retry without starting the wrong unit.
+    if (!options.prepareRestore || !options.resumeRestore) {
+      throw new Error("managed host install abort cannot restore its prior service");
+    }
+    await options.prepareRestore(intent.nonce);
+    await restorePreInstallRuntimeSelection(paths, intent);
+    await restoreLegacyShimTakeover(paths);
+    await options.resumeRestore(intent.nonce);
+    if (intent.priorServiceStop !== "none") {
+      if (!options.resumeStoppedService) {
+        throw new Error("managed host install abort cannot resume its prior service");
+      }
+      await options.resumeStoppedService(intent.nonce, intent.serviceManager);
+    }
+    await removeDurably(paths.installIntent);
+  });
+}
+
+export async function removeManagedRuntime(
+  options: RemoveManagedRuntimeOptions,
+): Promise<void> {
+  const paths = managedRuntimePaths(options.home);
+  await withManagedOperationLock(paths, async () => {
+    await reconcileInstallIntentForUninstall(paths);
+    let marker = await readMaintenanceMarker(paths);
+    if (!marker) {
+      if (await pathEntryExists(paths.uninstallPendingRoot)) {
+        throw new Error(
+          "managed host uninstall staging exists without its durable marker",
+        );
+      }
+      marker = {
+        schemaVersion: 1,
+        operation: "uninstall",
+        phase: "checking",
+        purgeData: options.purgeData === true,
+        startedAt: Date.now(),
+      };
+      await writeAtomicJson(paths.maintenancePending, marker);
+    } else if (marker.purgeData !== (options.purgeData === true)) {
+      throw new Error(
+        `unfinished managed host uninstall must be retried ${
+          marker.purgeData ? "with" : "without"
+        } --purge`,
+      );
+    }
+
+    if (marker.phase === "cleanup") {
+      await completeManagedRuntimeRemoval(paths, marker, options.onRemovalStep);
+      return;
+    }
+
+    // Two-sided taskUp/uninstall handshake: maintenance writes its durable gate
+    // before inspecting SQLite; taskUp writes `starting` before its final gate
+    // check. Whichever arrives second observes the first, so teardown cannot
+    // begin while an unrecorded task proceeds into Docker side effects.
+    if (!(await options.canRemove())) {
+      if (marker.phase === "checking") {
+        // No teardown began, so this ordinary busy refusal may safely reopen
+        // admission. A retry of a previously-started teardown stays fail-closed.
+        await removeDurably(paths.maintenancePending);
+      }
+      throw new Error(
+        "refusing to uninstall while local task workloads are not terminal",
+      );
+    }
+
+    if (marker.phase === "checking") {
+      marker = { ...marker, phase: "teardown" };
+      await writeAtomicJson(paths.maintenancePending, marker);
+    }
+
+    // From this point onward every failure deliberately leaves the teardown
+    // marker in place. The stopped (or half-stopped) service may be retried, but
+    // no new taskUp can enter between attempts.
+    await options.beforeRemove?.();
+    await options.afterServiceTeardown?.();
+    marker = { ...marker, phase: "cleanup" };
+    await writeAtomicJson(paths.maintenancePending, marker);
+    await options.onRemovalStep?.("service-teardown-complete");
+    await completeManagedRuntimeRemoval(paths, marker, options.onRemovalStep);
+  });
+}
+
+/**
+ * The public bootstrap executes the freshly downloaded agent directly, so it
+ * remains available even if an interrupted uninstall already removed the
+ * stable commands. Only the post-service `cleanup` phase is safe to continue
+ * without calling the OS service manager again; earlier phases leave the old
+ * command intact and require an explicit uninstall retry.
+ */
+async function reconcileInterruptedRemovalForInstall(
+  paths: ManagedRuntimePaths,
+): Promise<boolean> {
+  const marker = await readMaintenanceMarker(paths);
+  if (!marker) {
+    if (await pathEntryExists(paths.uninstallPendingRoot)) {
+      throw new Error(
+        "managed host uninstall staging exists without its durable marker",
+      );
+    }
+    return false;
+  }
+  if (marker.phase !== "cleanup") {
+    throw new Error(
+      "managed host uninstall has not completed service teardown; retry `uai-host uninstall`",
+    );
+  }
+  await completeManagedRuntimeRemoval(paths, marker);
+  return true;
+}
+
+async function completeManagedRuntimeRemoval(
+  paths: ManagedRuntimePaths,
+  marker: MaintenanceMarker,
+  onRemovalStep?: RemoveManagedRuntimeOptions["onRemovalStep"],
+): Promise<void> {
+  const rootExists = await pathEntryExists(paths.root);
+  const pendingExists = await pathEntryExists(paths.uninstallPendingRoot);
+  if (rootExists && pendingExists) {
+    throw new Error(
+      "managed host runtime and uninstall staging both exist; refusing ambiguous cleanup",
+    );
+  }
+  if (rootExists) {
+    // Validate the managed tree before moving it into the only path cleanup is
+    // allowed to remove. The rename is atomic; a crash leaves the complete or
+    // partially-removed runtime at a deterministic location for bootstrap to
+    // reconcile, never in an unrecorded random directory.
+    await ensureManagedDirectories(paths);
+    await rename(paths.root, paths.uninstallPendingRoot);
+    await syncDirectory(path.dirname(paths.root));
+  }
+  await onRemovalStep?.("runtime-detached");
+
+  await removeStableCommands(paths);
+  await onRemovalStep?.("commands-removed");
+
+  await rm(paths.uninstallPendingRoot, { recursive: true, force: true });
+  await syncDirectory(path.dirname(paths.uninstallPendingRoot));
+  await onRemovalStep?.("runtime-removed");
+
+  if (marker.purgeData) {
+    await purgeManagedData(paths);
+    await syncDirectory(path.dirname(paths.data));
+    await onRemovalStep?.("data-removed");
+  }
+
+  await onRemovalStep?.("cleanup-complete");
+  await removeDurably(paths.maintenancePending);
+}
+
+/**
+ * Purge host data without deleting the operation lock that guards this
+ * transaction. In the supported installed layout `paths.data` is a child of
+ * the home directory, but an explicit UAI_HOME may intentionally make the
+ * data root equal to that home. Removing the containing directory while the
+ * lock is held changes its owner metadata and makes the unlock step fail
+ * closed. Delete children in that topology, preserving only the exact lock
+ * directory until the outer transaction releases it.
+ */
+async function purgeManagedData(paths: ManagedRuntimePaths): Promise<void> {
+  const dataRoot = path.resolve(paths.data);
+  const lockRoot = path.resolve(paths.operationLock);
+  const lockParent = path.dirname(lockRoot);
+  if (dataRoot !== lockParent && !isInside(dataRoot, lockRoot)) {
+    await rm(paths.data, { recursive: true, force: true });
+    return;
+  }
+  let entries: string[];
+  try {
+    entries = await readdir(dataRoot);
+  } catch (error) {
+    if (isMissing(error)) return;
+    throw error;
+  }
+  for (const entry of entries) {
+    const candidate = path.join(dataRoot, entry);
+    if (path.resolve(candidate) === lockRoot) continue;
+    await rm(candidate, { recursive: true, force: true });
+  }
+}
+
+async function requireInstallIntent(
+  paths: ManagedRuntimePaths,
+  nonce: string,
+  requireLiveOwner: boolean,
+): Promise<InstallIntentMarker> {
+  if (!INSTALL_INTENT_NONCE.test(nonce)) {
+    throw new Error("managed host install intent capability is invalid");
+  }
+  const intent = await readInstallIntent(paths);
+  if (!intent || intent.nonce !== nonce) {
+    throw new Error("managed host install intent does not match");
+  }
+  if (requireLiveOwner && !installIntentOwnerIsLive(intent)) {
+    throw new Error(
+      "managed host installer owner exited; begin the installation again",
+    );
+  }
+  return intent;
+}
+
+async function assertNoManagedInstallIntent(
+  paths: ManagedRuntimePaths,
+  operation: string,
+): Promise<void> {
+  if (await readInstallIntent(paths)) {
+    throw new Error(
+      `managed host ${operation} is fenced by an installation intent`,
+    );
+  }
+}
+
+async function advanceInstallIntentToActivated(
+  paths: ManagedRuntimePaths,
+  expected: InstallIntentMarker,
+): Promise<void> {
+  const current = await readInstallIntent(paths);
+  if (!current || current.nonce !== expected.nonce) {
+    throw new Error("managed host install intent changed during activation");
+  }
+  if (!installIntentOwnerIsLive(current)) {
+    throw new Error("managed host installer owner exited during activation");
+  }
+  if (current.phase !== "activated") {
+    await writeAtomicJson(paths.installIntent, {
+      ...current,
+      phase: "activated",
+    } satisfies InstallIntentMarker);
+  }
+}
+
+async function restorePreInstallRuntimeSelection(
+  paths: ManagedRuntimePaths,
+  intent: InstallIntentMarker,
+): Promise<void> {
+  if (!intent.rootExisted) {
+    if (await pathEntryExists(paths.root)) {
+      await ensureManagedDirectories(paths);
+    }
+    await removeStableCommands(paths);
+    await rm(paths.root, { recursive: true, force: true });
+    await syncDirectory(path.dirname(paths.root));
+    return;
+  }
+
+  if (!(await pathEntryExists(paths.root))) {
+    throw new Error("pre-install managed runtime disappeared during rollback");
+  }
+  await ensureManagedDirectories(paths);
+  if (intent.currentVersion) {
+    await atomicVersionLink(paths.current, intent.currentVersion);
+  } else {
+    await removeDurably(paths.current);
+  }
+  if (intent.previousVersion) {
+    await atomicVersionLink(paths.previous, intent.previousVersion);
+  } else {
+    await removeDurably(paths.previous);
+  }
+  if (intent.activationPending) {
+    await writeAtomicJson(paths.activationPending, intent.activationPending);
+  } else {
+    await removeDurably(paths.activationPending);
+  }
+
+  if (intent.shimOwnership === "missing") {
+    await removeOwnedSymlink(
+      paths.shim,
+      path.join(paths.runtime, "current", "bin", "uai-host"),
+    );
+  }
+  if (!intent.recoveryShimExisted) {
+    await removeOwnedSymlink(paths.recoveryShim, paths.recoveryEntrypoint);
+  }
+  if (!intent.recoveryEntrypointExisted) {
+    const exists = await assertRecoveryEntrypointReplaceable(paths);
+    if (exists) await removeDurably(paths.recoveryEntrypoint);
+  }
+}
+
+async function reconcileInstallIntentForUninstall(
+  paths: ManagedRuntimePaths,
+): Promise<void> {
+  const intent = await readInstallIntent(paths);
+  if (!intent) {
+    if (await readLegacyShimTakeover(paths)) {
+      throw new Error(
+        "managed host legacy command takeover has no install intent; rerun the installer",
+      );
+    }
+    return;
+  }
+  if (installIntentOwnerIsLive(intent)) {
+    throw new Error("refusing to uninstall while managed host installation is running");
+  }
+  // Service-definition recovery must precede legacy command restoration. Only
+  // the bundled begin/abort commands have that platform hook, so a dead owner
+  // remains fenced here until the public installer safely adopts the intent.
+  throw new Error(
+    "managed host installation was interrupted; rerun the installer before uninstalling",
+  );
+}
+
+export async function validateInstalledRuntime(
+  directory: string,
+  expectedVersion: string,
+  expectedPlatform?: string,
+): Promise<ResolvedRuntimeDescriptor> {
+  const root = await realpath(directory);
+  const raw = JSON.parse(await readFile(path.join(root, "runtime.json"), "utf8")) as {
+    platform?: unknown;
+  };
+  const platform = expectedPlatform ??
+    (typeof raw.platform === "string" && isReleasePlatform(raw.platform)
+      ? raw.platform
+      : null);
+  if (!platform) throw new Error("managed runtime descriptor platform is invalid");
+  const descriptor = validateRuntimeDescriptor(raw, {
+    version: expectedVersion,
+    platform,
+  });
+  const topLevel = (await readdir(root)).sort();
+  if (topLevel.join("\0") !== ["agent", "bin", "node", "runtime.json"].join("\0")) {
+    throw new Error(`managed runtime ${expectedVersion} has an invalid top-level layout`);
+  }
+  const requiredFiles: Array<readonly [string, boolean]> = [
+    ["agent/bin/uai-host.mjs", false],
+    // Host-spawned bash entrypoints: packaging once shipped these 0644
+    // (pnpm-store mode normalization) and the first installed task died with
+    // spawn EACCES. Executability is part of the validated contract now.
+    ["agent/scripts/agent/task-up.sh", true],
+    ["agent/scripts/agent/task-down.sh", true],
+    ["agent/scripts/agent/task-status.sh", true],
+    ["bin/uai-host", true],
+    ["node/bin/node", true],
+    ["runtime.json", false],
+  ];
+  const capabilities = await resolveInstalledRuntimeCapabilities(root, descriptor.platform);
+  if (capabilities.capabilitySchemaVersion === 3) {
+    const bundled = capabilities.bundledRuntime;
+    requiredFiles.push(
+      [BUNDLED_RUNTIME_CAPABILITY, false],
+      [bundled.layout.assetManifest, false],
+      [bundled.layout.containerCli, true],
+      [bundled.layout.apiserver, true],
+      ...APPLE_CONTAINER_PLUGINS.map(
+        (plugin) =>
+          [`${bundled.layout.plugins}/${plugin}/bin/${plugin}`, true] as const,
+      ),
+      [bundled.layout.kernel, false],
+      ...REQUIRED_BUNDLED_RUNTIME_LICENSES.map(
+        (license) => [`${bundled.layout.licenses}/${license}`, false] as const,
+      ),
+    );
+  }
+  for (const [relative, executable] of requiredFiles) {
+    const absolute = path.join(root, ...relative.split("/"));
+    const stat = await lstat(absolute);
+    if (!stat.isFile()) throw new Error(`managed runtime is missing regular file ${relative}`);
+    if (executable && (stat.mode & 0o111) === 0) {
+      throw new Error(`managed runtime file is not executable: ${relative}`);
+    }
+    const resolved = await realpath(absolute);
+    if (!isInside(root, resolved)) {
+      throw new Error(`managed runtime file escapes its version directory: ${relative}`);
+    }
+  }
+  if (capabilities.capabilitySchemaVersion === 3) {
+    await validateInstalledRuntimeAssets(root, capabilities);
+  }
+  return { ...descriptor, ...capabilities };
+}
+
+async function resolveInstalledRuntimeCapabilities(
+  root: string,
+  platform: string,
+): Promise<{ readonly capabilitySchemaVersion: 1 } | RuntimeCapabilityDescriptorV3> {
+  const bundledRoot = path.join(root, ...BUNDLED_RUNTIME_ROOT.split("/"));
+  let bundledMetadata;
+  try {
+    bundledMetadata = await lstat(bundledRoot);
+  } catch (error) {
+    if (isMissing(error)) return { capabilitySchemaVersion: 1 };
+    throw error;
+  }
+  if (!platform.startsWith("darwin-")) {
+    throw new Error("managed Linux runtime contains bundled Darwin assets");
+  }
+  if (!bundledMetadata.isDirectory() || bundledMetadata.isSymbolicLink()) {
+    throw new Error("managed runtime bundled capability root is invalid");
+  }
+  const capabilityPath = path.join(root, ...BUNDLED_RUNTIME_CAPABILITY.split("/"));
+  const metadata = await lstat(capabilityPath);
+  if (
+    !metadata.isFile() ||
+    metadata.isSymbolicLink() ||
+    metadata.size > MAX_OPERATION_LOCK_BYTES ||
+    !isInside(root, await realpath(capabilityPath))
+  ) {
+    throw new Error("managed runtime capability descriptor is invalid");
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await readFile(capabilityPath, "utf8"));
+  } catch {
+    throw new Error("managed runtime capability descriptor is invalid JSON");
+  }
+  return validateRuntimeCapabilityDescriptor(raw, platform);
+}
+
+async function validateInstalledRuntimeAssets(
+  root: string,
+  capabilities: RuntimeCapabilityDescriptorV3,
+): Promise<RuntimeAssetManifest> {
+  const descriptor = capabilities.bundledRuntime;
+  const manifestPath = path.join(
+    root,
+    ...descriptor.layout.assetManifest.split("/"),
+  );
+  const manifestStat = await lstat(manifestPath);
+  if (!manifestStat.isFile() || manifestStat.isSymbolicLink() || manifestStat.size > 2 * 1024 * 1024) {
+    throw new Error("managed runtime asset manifest is invalid");
+  }
+  const manifest = validateRuntimeAssetManifest(
+    JSON.parse(await readFile(manifestPath, "utf8")),
+    descriptor.assetFingerprint,
+  );
+  const sourceRoot = path.join(
+    root,
+    ...descriptor.layout.assetSourceRoot.split("/"),
+  );
+  const seen = new Set<string>();
+  for (const entry of manifest.entries) {
+    const absolute = path.join(sourceRoot, ...entry.path.split("/"));
+    const metadata = await lstat(absolute);
+    if (
+      !metadata.isFile() ||
+      metadata.isSymbolicLink() ||
+      metadata.size !== entry.size ||
+      (metadata.mode & 0o777) !== entry.mode ||
+      !isInside(root, await realpath(absolute))
+    ) {
+      throw new Error(`managed runtime asset does not match its manifest: ${entry.path}`);
+    }
+    const hash = createHash("sha256").update(await readFile(absolute)).digest("hex");
+    if (hash !== entry.sha256) {
+      throw new Error(`managed runtime asset digest does not match its manifest: ${entry.path}`);
+    }
+    seen.add(entry.path);
+  }
+  for (const selectedRoot of [
+    "apple-container",
+    "host-assets",
+    "kernel",
+    "licenses",
+  ]) {
+    async function visit(relativeDirectory: string): Promise<void> {
+      const directory = path.join(sourceRoot, ...relativeDirectory.split("/"));
+      for (const child of await readdir(directory, { withFileTypes: true })) {
+        const relative = `${relativeDirectory}/${child.name}`;
+        const absolute = path.join(sourceRoot, ...relative.split("/"));
+        const metadata = await lstat(absolute);
+        if (metadata.isDirectory() && !metadata.isSymbolicLink()) {
+          await visit(relative);
+        } else if (!metadata.isFile() || metadata.isSymbolicLink() || !seen.has(relative)) {
+          throw new Error(`managed runtime asset tree is not closed by its manifest: ${relative}`);
+        }
+      }
+    }
+    await visit(selectedRoot);
+  }
+  await validateInstalledBundledSubtreeClosure(root, capabilities, manifest);
+  return manifest;
+}
+
+async function validateInstalledBundledSubtreeClosure(
+  root: string,
+  capabilities: RuntimeCapabilityDescriptorV3,
+  manifest: RuntimeAssetManifest,
+): Promise<void> {
+  const bundled = capabilities.bundledRuntime;
+  // Every staged payload file is a manifest entry; only the two metadata
+  // documents live outside the digest closure.
+  const expected = new Set([
+    BUNDLED_RUNTIME_CAPABILITY,
+    bundled.layout.assetManifest,
+    ...manifest.entries.map(
+      (entry) => `${bundled.layout.assetSourceRoot}/${entry.path}`,
+    ),
+  ]);
+  const actual = new Set<string>();
+  const bundledRoot = path.join(root, ...BUNDLED_RUNTIME_ROOT.split("/"));
+  async function visit(relativeDirectory: string): Promise<void> {
+    for (const child of await readdir(path.join(bundledRoot, relativeDirectory), {
+      withFileTypes: true,
+    })) {
+      const relative = relativeDirectory ? `${relativeDirectory}/${child.name}` : child.name;
+      const absolute = path.join(bundledRoot, ...relative.split("/"));
+      const member = `${BUNDLED_RUNTIME_ROOT}/${relative}`;
+      const metadata = await lstat(absolute);
+      if (metadata.isDirectory() && !metadata.isSymbolicLink()) {
+        if (![...expected].some((file) => file.startsWith(`${member}/`))) {
+          throw new Error(`managed runtime bundled subtree has an unexpected directory: ${member}`);
+        }
+        await visit(relative);
+      } else if (
+        metadata.isFile() &&
+        !metadata.isSymbolicLink() &&
+        isInside(root, await realpath(absolute))
+      ) {
+        actual.add(member);
+      } else {
+        throw new Error(`managed runtime bundled subtree has an unsafe entry: ${member}`);
+      }
+    }
+  }
+  await visit("");
+  const compare = (left: string, right: string): number =>
+    Buffer.compare(Buffer.from(left), Buffer.from(right));
+  if (
+    [...actual].sort(compare).join("\0") !==
+    [...expected].sort(compare).join("\0")
+  ) {
+    throw new Error("managed runtime bundled subtree is not closed by its descriptor and manifest");
+  }
+}
+
+export interface ResolvedBundledRuntime {
+  readonly root: string;
+  readonly descriptor: ResolvedRuntimeDescriptor & RuntimeCapabilityDescriptorV3;
+  readonly containerCliPath: string;
+  readonly apiserverPath: string;
+  readonly pluginsPath: string;
+  readonly kernelPath: string;
+  readonly runtimeAssetSourceRoot: string;
+  readonly runtimeAssetManifestPath: string;
+  readonly runtimeAssetFingerprint: string;
+}
+
+export async function resolveBundledRuntimeFromEnvironment(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<ResolvedBundledRuntime | null> {
+  const configured = env.UAI_HOST_RUNTIME_ROOT;
+  if (!configured) return null;
+  if (!path.isAbsolute(configured)) {
+    throw new Error("UAI_HOST_RUNTIME_ROOT must be absolute");
+  }
+  const root = await realpath(configured);
+  const raw = JSON.parse(await readFile(path.join(root, "runtime.json"), "utf8")) as {
+    hostVersion?: unknown;
+    platform?: unknown;
+  };
+  if (typeof raw.hostVersion !== "string" || !VERSION.test(raw.hostVersion)) {
+    throw new Error("managed runtime descriptor version is invalid");
+  }
+  if (typeof raw.platform !== "string" || !isReleasePlatform(raw.platform)) {
+    throw new Error("managed runtime descriptor platform is invalid");
+  }
+  const descriptor = await validateInstalledRuntime(
+    root,
+    raw.hostVersion,
+    raw.platform,
+  );
+  if (descriptor.capabilitySchemaVersion === 1) return null;
+  const resolveInside = async (relative: string): Promise<string> => {
+    const resolved = await realpath(path.join(root, ...relative.split("/")));
+    if (!isInside(root, resolved)) {
+      throw new Error(`managed bundled runtime path escapes its generation: ${relative}`);
+    }
+    return resolved;
+  };
+  return {
+    root,
+    descriptor,
+    containerCliPath: await resolveInside(
+      descriptor.bundledRuntime.layout.containerCli,
+    ),
+    apiserverPath: await resolveInside(descriptor.bundledRuntime.layout.apiserver),
+    pluginsPath: await resolveInside(descriptor.bundledRuntime.layout.plugins),
+    kernelPath: await resolveInside(descriptor.bundledRuntime.layout.kernel),
+    runtimeAssetSourceRoot: await resolveInside(
+      descriptor.bundledRuntime.layout.assetSourceRoot,
+    ),
+    runtimeAssetManifestPath: await resolveInside(
+      descriptor.bundledRuntime.layout.assetManifest,
+    ),
+    runtimeAssetFingerprint: descriptor.bundledRuntime.assetFingerprint,
+  };
+}
+
+async function ensureManagedDirectories(paths: ManagedRuntimePaths): Promise<void> {
+  await mkdir(paths.root, { recursive: true, mode: 0o700 });
+  const rootStat = await lstat(paths.root);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new Error(`${paths.root} is not a private managed-host directory`);
+  }
+  await chmod(paths.root, 0o700);
+  await mkdir(paths.runtime, { recursive: false, mode: 0o700 }).catch((error) => {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  });
+  const runtimeStat = await lstat(paths.runtime);
+  if (!runtimeStat.isDirectory() || runtimeStat.isSymbolicLink()) {
+    throw new Error(`${paths.runtime} is not a managed runtime directory`);
+  }
+  await chmod(paths.runtime, 0o700);
+}
+
+async function capturePreInstallState(paths: ManagedRuntimePaths): Promise<
+  Pick<
+    InstallIntentMarker,
+    | "rootExisted"
+    | "currentVersion"
+    | "previousVersion"
+    | "activationPending"
+    | "shimOwnership"
+    | "recoveryShimExisted"
+    | "recoveryEntrypointExisted"
+  >
+> {
+  const rootExisted = await pathEntryExists(paths.root);
+  if (rootExisted) await ensureManagedDirectories(paths);
+  const currentVersion = await readVersionLink(paths.current, paths.runtime);
+  const previousVersion = await readVersionLink(paths.previous, paths.runtime);
+  let activationPending: ActivationMarker | null = null;
+  try {
+    activationPending = parseActivationMarker(
+      await readBoundedRegularFile(paths.activationPending),
+    );
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+
+  let shimOwnership: InstallIntentMarker["shimOwnership"] = "missing";
+  if (await pathEntryExists(paths.shim)) {
+    if (await isExactManagedShim(paths)) {
+      shimOwnership = "managed";
+    } else {
+      await proveLegacyNpmShim(paths);
+      shimOwnership = "legacy";
+    }
+  }
+
+  const recoveryShimExisted = await pathEntryExists(paths.recoveryShim);
+  if (recoveryShimExisted && !(await isExactRecoveryShim(paths))) {
+    throw new Error(
+      `refusing to replace unrelated host recovery command at ${paths.recoveryShim}`,
+    );
+  }
+  const recoveryEntrypointExisted = await assertRecoveryEntrypointReplaceable(
+    paths,
+  );
+  return {
+    rootExisted,
+    currentVersion,
+    previousVersion,
+    activationPending,
+    shimOwnership,
+    recoveryShimExisted,
+    recoveryEntrypointExisted,
+  };
+}
+
+/** Record a proven npm-owned collision without moving the still-needed CLI. */
+async function recordLegacyShimTakeover(
+  paths: ManagedRuntimePaths,
+): Promise<boolean> {
+  const existing = await readLegacyShimTakeover(paths);
+  if (existing) {
+    await validateLegacyTakeoverState(paths, existing);
+    return true;
+  }
+  if (await pathEntryExists(paths.legacyShimBackup)) {
+    throw new Error("legacy host command backup exists without its durable journal");
+  }
+  let stat;
+  try {
+    stat = await lstat(paths.shim);
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+  if (!stat.isSymbolicLink()) {
+    throw new Error(`refusing to replace non-symlink host command at ${paths.shim}`);
+  }
+  if (await isExactManagedShim(paths)) return false;
+  const proof = await proveLegacyNpmShim(paths);
+  await writeAtomicJson(paths.legacyShimTakeover, {
+    schemaVersion: 1,
+    operation: "legacy-shim-takeover",
+    phase: "recorded",
+    ...proof,
+    startedAt: Date.now(),
+  } satisfies LegacyShimTakeoverMarker);
+  return true;
+}
+
+async function parkLegacyShimTakeover(paths: ManagedRuntimePaths): Promise<void> {
+  let marker = await readLegacyShimTakeover(paths);
+  if (!marker) return;
+  if (marker.phase === "restoring" || marker.phase === "finalizing") {
+    throw new Error("legacy host command takeover is settling another outcome");
+  }
+  const backupExists = await pathEntryExists(paths.legacyShimBackup);
+  if (!backupExists) {
+    await assertExactLegacySymlink(paths.shim, marker);
+    await rename(paths.shim, paths.legacyShimBackup);
+    await syncDirectory(path.dirname(paths.shim));
+  } else {
+    await assertExactLegacySymlink(paths.legacyShimBackup, marker);
+    await assertMissingOrManagedShim(paths);
+  }
+  if (marker.phase !== "parked") {
+    marker = { ...marker, phase: "parked" };
+    await writeAtomicJson(paths.legacyShimTakeover, marker);
+  }
+}
+
+async function restoreLegacyShimTakeover(paths: ManagedRuntimePaths): Promise<void> {
+  let marker = await readLegacyShimTakeover(paths);
+  if (!marker) {
+    if (await pathEntryExists(paths.legacyShimBackup)) {
+      throw new Error("legacy host command backup exists without its durable journal");
+    }
+    return;
+  }
+  if (marker.phase === "finalizing") {
+    await finalizeLegacyShimTakeover(paths);
+    return;
+  }
+
+  const backupExists = await pathEntryExists(paths.legacyShimBackup);
+  if (!backupExists && marker.phase === "recorded") {
+    await assertExactLegacySymlink(paths.shim, marker);
+    await removeDurably(paths.legacyShimTakeover);
+    return;
+  }
+  if (marker.phase !== "restoring") {
+    marker = { ...marker, phase: "restoring" };
+    await writeAtomicJson(paths.legacyShimTakeover, marker);
+  }
+
+  if (await pathEntryExists(paths.legacyShimBackup)) {
+    await assertExactLegacySymlink(paths.legacyShimBackup, marker);
+    await assertMissingOrManagedShim(paths);
+    // Atomic replacement avoids a window where the prior service has no CLI.
+    await rename(paths.legacyShimBackup, paths.shim);
+    await syncDirectory(path.dirname(paths.shim));
+  } else {
+    // Crash after the rename but before journal deletion.
+    await assertExactLegacySymlink(paths.shim, marker);
+  }
+  await removeDurably(paths.legacyShimTakeover);
+}
+
+async function finalizeLegacyShimTakeover(paths: ManagedRuntimePaths): Promise<void> {
+  let marker = await readLegacyShimTakeover(paths);
+  if (!marker) {
+    if (await pathEntryExists(paths.legacyShimBackup)) {
+      throw new Error("legacy host command backup exists without its durable journal");
+    }
+    return;
+  }
+  if (marker.phase === "restoring") {
+    throw new Error("legacy host command restoration is incomplete");
+  }
+  if (marker.phase === "recorded") {
+    throw new Error("legacy host command was not parked by runtime activation");
+  }
+  await assertExactManagedShim(paths);
+  if (marker.phase !== "finalizing") {
+    marker = { ...marker, phase: "finalizing" };
+    await writeAtomicJson(paths.legacyShimTakeover, marker);
+  }
+  if (await pathEntryExists(paths.legacyShimBackup)) {
+    await assertExactLegacySymlink(paths.legacyShimBackup, marker);
+    await unlink(paths.legacyShimBackup);
+    await syncDirectory(path.dirname(paths.legacyShimBackup));
+  }
+  await removeDurably(paths.legacyShimTakeover);
+}
+
+async function validateLegacyTakeoverState(
+  paths: ManagedRuntimePaths,
+  marker: LegacyShimTakeoverMarker,
+): Promise<void> {
+  if (marker.phase === "recorded") {
+    if (await pathEntryExists(paths.legacyShimBackup)) {
+      await assertExactLegacySymlink(paths.legacyShimBackup, marker);
+      await assertMissingOrManagedShim(paths);
+    } else {
+      await assertExactLegacySymlink(paths.shim, marker);
+    }
+    return;
+  }
+  if (marker.phase === "parked") {
+    await assertExactLegacySymlink(paths.legacyShimBackup, marker);
+    await assertMissingOrManagedShim(paths);
+    return;
+  }
+  throw new Error("legacy host command takeover has an incomplete terminal phase");
+}
+
+async function proveLegacyNpmShim(paths: ManagedRuntimePaths): Promise<{
+  originalTarget: string;
+  resolvedTarget: string;
+  packageRoot: string;
+}> {
+  const originalTarget = await readlink(paths.shim);
+  const resolvedTarget = path.resolve(path.dirname(paths.shim), originalTarget);
+  const targetStat = await lstat(resolvedTarget);
+  if (!targetStat.isFile() || targetStat.isSymbolicLink()) {
+    throw new Error("legacy host command does not target a regular package bin");
+  }
+  const canonicalTarget = await realpath(resolvedTarget);
+  let directory = path.dirname(canonicalTarget);
+  for (;;) {
+    const packageFile = path.join(directory, "package.json");
+    let bytes: Buffer | null = null;
+    try {
+      bytes = await readBoundedRegularFile(packageFile, MAX_PACKAGE_JSON_BYTES);
+    } catch (error) {
+      if (!isMissing(error)) throw error;
+    }
+    if (bytes) {
+      let raw: unknown;
+      try {
+        raw = JSON.parse(bytes.toString("utf8"));
+      } catch {
+        throw new Error("legacy host command package.json is invalid");
+      }
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("legacy host command package.json is invalid");
+      }
+      const manifest = raw as Record<string, unknown>;
+      const bin = manifest.bin;
+      if (
+        manifest.name !== "@runuai/host" ||
+        !bin ||
+        typeof bin !== "object" ||
+        Array.isArray(bin) ||
+        typeof (bin as Record<string, unknown>)["uai-host"] !== "string"
+      ) {
+        throw new Error(
+          "host command collision is not the @runuai/host package bin",
+        );
+      }
+      const mapped = path.resolve(
+        directory,
+        (bin as Record<string, string>)["uai-host"]!,
+      );
+      if (!isInside(directory, mapped)) {
+        throw new Error("legacy host command package bin escapes its package");
+      }
+      const mappedStat = await lstat(mapped);
+      if (!mappedStat.isFile() || mappedStat.isSymbolicLink()) {
+        throw new Error("legacy host command package bin is not a regular file");
+      }
+      if ((await realpath(mapped)) !== canonicalTarget) {
+        throw new Error("legacy host command does not match its package bin mapping");
+      }
+      return { originalTarget, resolvedTarget, packageRoot: directory };
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  throw new Error("legacy host command has no owning package.json");
+}
+
+async function assertExactLegacySymlink(
+  link: string,
+  marker: LegacyShimTakeoverMarker,
+): Promise<void> {
+  const stat = await lstat(link);
+  if (!stat.isSymbolicLink()) {
+    throw new Error("legacy host command backup is not a symlink");
+  }
+  const target = await readlink(link);
+  if (
+    target !== marker.originalTarget ||
+    path.resolve(path.dirname(link), target) !== marker.resolvedTarget
+  ) {
+    throw new Error("legacy host command changed during managed takeover");
+  }
+}
+
+async function isExactManagedShim(paths: ManagedRuntimePaths): Promise<boolean> {
+  try {
+    const stat = await lstat(paths.shim);
+    if (!stat.isSymbolicLink()) return false;
+    const target = await readlink(paths.shim);
+    return (
+      path.resolve(path.dirname(paths.shim), target) ===
+      path.join(paths.runtime, "current", "bin", "uai-host")
+    );
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+async function isExactRecoveryShim(paths: ManagedRuntimePaths): Promise<boolean> {
+  try {
+    const stat = await lstat(paths.recoveryShim);
+    if (!stat.isSymbolicLink()) return false;
+    const target = await readlink(paths.recoveryShim);
+    return (
+      path.resolve(path.dirname(paths.recoveryShim), target) ===
+      paths.recoveryEntrypoint
+    );
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+async function assertExactManagedShim(paths: ManagedRuntimePaths): Promise<void> {
+  if (!(await isExactManagedShim(paths))) {
+    throw new Error("managed host command is missing during takeover settlement");
+  }
+}
+
+async function assertMissingOrManagedShim(paths: ManagedRuntimePaths): Promise<void> {
+  if (!(await pathEntryExists(paths.shim))) return;
+  if (await isExactManagedShim(paths)) return;
+  throw new Error("refusing to replace unrelated host command during takeover");
+}
+
+async function ensureStableCommands(paths: ManagedRuntimePaths): Promise<void> {
+  await assertStableCommandsReplaceable(paths);
+  await ensureRecoveryEntrypoint(paths);
+  await ensureStableShim(paths);
+  await ensureRecoveryShim(paths);
+}
+
+async function assertStableCommandsReplaceable(
+  paths: ManagedRuntimePaths,
+): Promise<void> {
+  await assertOwnedSymlinkReplaceable(
+    paths.shim,
+    path.join(paths.runtime, "current", "bin", "uai-host"),
+    "host command",
+  );
+  await assertRecoveryEntrypointReplaceable(paths);
+  await assertOwnedSymlinkReplaceable(
+    paths.recoveryShim,
+    paths.recoveryEntrypoint,
+    "host recovery command",
+  );
+}
+
+async function ensureStableShim(paths: ManagedRuntimePaths): Promise<void> {
+  await mkdir(path.dirname(paths.shim), { recursive: true, mode: 0o755 });
+  const expectedTarget = path.join(paths.runtime, "current", "bin", "uai-host");
+  await assertOwnedSymlinkReplaceable(paths.shim, expectedTarget, "host command");
+  await atomicSymlink(paths.shim, expectedTarget);
+}
+
+async function ensureRecoveryShim(paths: ManagedRuntimePaths): Promise<void> {
+  await mkdir(path.dirname(paths.recoveryShim), { recursive: true, mode: 0o755 });
+  await assertOwnedSymlinkReplaceable(
+    paths.recoveryShim,
+    paths.recoveryEntrypoint,
+    "host recovery command",
+  );
+  await atomicSymlink(paths.recoveryShim, paths.recoveryEntrypoint);
+}
+
+async function assertOwnedSymlinkReplaceable(
+  link: string,
+  expectedTarget: string,
+  description: string,
+): Promise<void> {
+  try {
+    const stat = await lstat(link);
+    if (!stat.isSymbolicLink()) {
+      throw new Error(`refusing to replace non-symlink ${description} at ${link}`);
+    }
+    const existing = await readlink(link);
+    if (path.resolve(path.dirname(link), existing) !== expectedTarget) {
+      throw new Error(`refusing to replace unrelated ${description} at ${link}`);
+    }
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+}
+
+async function ensureRecoveryEntrypoint(paths: ManagedRuntimePaths): Promise<void> {
+  const directory = path.dirname(paths.recoveryEntrypoint);
+  await mkdir(directory, { recursive: false, mode: 0o700 }).catch((error) => {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  });
+  const directoryStat = await lstat(directory);
+  if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+    throw new Error(`${directory} is not a managed recovery directory`);
+  }
+  await chmod(directory, 0o700);
+  const expected = recoveryEntrypointContents(paths);
+  const exists = await assertRecoveryEntrypointReplaceable(paths);
+  if (!exists) {
+    await writeAtomicExecutable(paths.recoveryEntrypoint, expected);
+  } else {
+    await chmod(paths.recoveryEntrypoint, 0o700);
+  }
+}
+
+/** Return true when the exact managed entrypoint already exists. */
+async function assertRecoveryEntrypointReplaceable(
+  paths: ManagedRuntimePaths,
+): Promise<boolean> {
+  try {
+    const stat = await lstat(paths.recoveryEntrypoint);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error(
+        `refusing to replace non-regular host recovery entrypoint at ${paths.recoveryEntrypoint}`,
+      );
+    }
+    const existing = await readBoundedRegularFile(paths.recoveryEntrypoint);
+    if (!existing.equals(Buffer.from(recoveryEntrypointContents(paths)))) {
+      throw new Error(
+        `refusing to replace modified host recovery entrypoint at ${paths.recoveryEntrypoint}`,
+      );
+    }
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+function recoveryEntrypointContents(paths: ManagedRuntimePaths): string {
+  const runtime = shellSingleQuote(paths.runtime);
+  const capabilityFloor = shellSingleQuote(paths.minimumRuntimeCapability);
+  const providerState = shellSingleQuote(paths.runtimeProviderState);
+  return `#!/bin/sh
+# uai-managed-host-recovery-v1
+set -eu
+
+runtime=${runtime}
+capability_floor=${capabilityFloor}
+provider_state=${providerState}
+
+fail() {
+  echo "uai-host-recover: $*" >&2
+  exit 126
+}
+
+is_stable_version() {
+  value=$1
+  case "$value" in
+    ""|*[!0-9.]*) return 1 ;;
+  esac
+  saved_ifs=$IFS
+  IFS=.
+  set -- $value
+  IFS=$saved_ifs
+  [ "$#" -eq 3 ] || return 1
+  for component in "$@"; do
+    case "$component" in
+      0|[1-9]|[1-9][0-9]*) ;;
+      *) return 1 ;;
+    esac
+  done
+}
+
+previous=$runtime/previous
+[ -L "$previous" ] || fail "no previous managed runtime is available"
+version=$(readlink "$previous") || fail "cannot read the previous runtime link"
+is_stable_version "$version" || fail "the previous runtime link is invalid"
+
+generation=$runtime/$version
+if [ ! -d "$generation" ] || [ -L "$generation" ]; then
+  fail "the previous managed runtime directory is invalid"
+fi
+floor_required=false
+if [ -e "$capability_floor" ] || [ -L "$capability_floor" ]; then
+  if [ ! -f "$capability_floor" ] || [ -L "$capability_floor" ]; then
+    fail "the managed runtime capability floor is invalid"
+  fi
+  if ! LC_ALL=C tr -d '[:space:]' < "$capability_floor" |
+    grep -Eq '^\{"schemaVersion":1,"minimumRuntimeCapability":([2-9]|[1-9][0-9]+)\}$'; then
+    fail "the managed runtime capability floor is invalid"
+  fi
+  floor_required=true
+elif [ -e "$provider_state" ] || [ -L "$provider_state" ]; then
+  if [ ! -f "$provider_state" ] || [ -L "$provider_state" ]; then
+    fail "the container runtime provider state is invalid"
+  fi
+  if ! LC_ALL=C tr -d '[:space:]' < "$provider_state" |
+    grep -Eq '^\{"schemaVersion":1,"statefulProvider":"apple-container","claimedAt":[1-9][0-9]*\}$'; then
+    fail "the container runtime provider state is invalid"
+  fi
+  # A pre-floor apple-container claim is authoritative evidence for the
+  # capability-3 floor that provider requires.
+  required_floor=3
+  floor_required=true
+fi
+if [ "$floor_required" = true ]; then
+  if [ -z "\${required_floor:-}" ]; then
+    required_floor=$(LC_ALL=C tr -d '[:space:]' < "$capability_floor" |
+      sed -n 's/^{"schemaVersion":1,"minimumRuntimeCapability":\\([0-9][0-9]*\\)}$/\\1/p')
+  fi
+  case $required_floor in
+    '' | *[!0-9]*) fail "the managed runtime capability floor is invalid" ;;
+  esac
+  capability=$generation/agent/bundled-runtime/capability.json
+  # The TypeScript rollback/install path validates the exact JSON descriptor
+  # and closed asset tree. This stable recovery guard runs only after those
+  # authenticated generation checks and compares the generation's numeric
+  # capability schema against the preserved floor, so a lower-capability
+  # generation can never be launched over provider state that outranks it.
+  if [ ! -f "$capability" ] || [ -L "$capability" ]; then
+    fail "the previous runtime predates this host's provider state"
+  fi
+  generation_capability=$(LC_ALL=C tr -d '[:space:]' < "$capability" |
+    sed -n 's/.*"capabilitySchemaVersion":\\([0-9][0-9]*\\).*/\\1/p')
+  case $generation_capability in
+    '' | *[!0-9]*) fail "the previous runtime capability descriptor is invalid" ;;
+  esac
+  if [ "$generation_capability" -lt "$required_floor" ]; then
+    fail "the previous runtime capability $generation_capability is below this host's floor $required_floor"
+  fi
+fi
+launcher_dir=$generation/bin
+if [ ! -d "$launcher_dir" ] || [ -L "$launcher_dir" ]; then
+  fail "the previous managed runtime launcher directory is invalid"
+fi
+launcher=$launcher_dir/uai-host
+if [ ! -f "$launcher" ] || [ -L "$launcher" ] || [ ! -x "$launcher" ]; then
+  fail "the previous managed runtime launcher is invalid"
+fi
+
+exec "$launcher" "$@"
+`;
+}
+
+function shellSingleQuote(value: string): string {
+  return `'${value.split("'").join(`'"'"'`)}'`;
+}
+
+async function writeAtomicExecutable(file: string, contents: string): Promise<void> {
+  const temporary = `${file}.${process.pid}.${randomBytes(6).toString("hex")}`;
+  const handle = await open(temporary, "wx", 0o700);
+  try {
+    await handle.writeFile(contents);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporary, file);
+    await syncDirectory(path.dirname(file));
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+async function removeStableCommands(paths: ManagedRuntimePaths): Promise<void> {
+  await removeOwnedSymlink(paths.recoveryShim, paths.recoveryEntrypoint);
+  await removeOwnedSymlink(
+    paths.shim,
+    path.join(paths.runtime, "current", "bin", "uai-host"),
+  );
+}
+
+async function removeOwnedSymlink(
+  link: string,
+  expectedTarget: string,
+): Promise<void> {
+  try {
+    const stat = await lstat(link);
+    if (!stat.isSymbolicLink()) return;
+    const target = await readlink(link);
+    if (path.resolve(path.dirname(link), target) === expectedTarget) {
+      await unlink(link);
+      await syncDirectory(path.dirname(link));
+    }
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+}
+
+async function atomicVersionLink(linkPath: string, version: string): Promise<void> {
+  assertStableVersion(version);
+  await atomicSymlink(linkPath, version);
+}
+
+async function atomicSymlink(linkPath: string, target: string): Promise<void> {
+  const temporary = path.join(
+    path.dirname(linkPath),
+    `.${path.basename(linkPath)}.${process.pid}.${randomBytes(6).toString("hex")}`,
+  );
+  await symlink(target, temporary);
+  try {
+    await rename(temporary, linkPath);
+    await syncDirectory(path.dirname(linkPath));
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+async function readVersionLink(linkPath: string, runtimeRoot: string): Promise<string | null> {
+  try {
+    const stat = await lstat(linkPath);
+    if (!stat.isSymbolicLink()) throw new Error(`${linkPath} is not a managed symlink`);
+    const target = await readlink(linkPath);
+    if (target.includes("/") || target.includes(path.sep) || !VERSION.test(target)) {
+      throw new Error(`${linkPath} has an invalid managed-runtime target`);
+    }
+    const targetPath = path.join(runtimeRoot, target);
+    const targetStat = await lstat(targetPath);
+    if (!targetStat.isDirectory() || targetStat.isSymbolicLink()) {
+      throw new Error(`${linkPath} does not target a managed runtime directory`);
+    }
+    return target;
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+}
+
+async function recoverRollback(
+  paths: ManagedRuntimePaths,
+): Promise<{ fromVersion: string; version: string } | null> {
+  let raw: unknown;
+  try {
+    const stat = await lstat(paths.rollbackJournal);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_OPERATION_LOCK_BYTES) {
+      throw new Error("managed-host rollback journal is invalid");
+    }
+    raw = JSON.parse(await readFile(paths.rollbackJournal, "utf8"));
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw new Error(`could not recover interrupted managed-host rollback: ${String(error)}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed-host rollback journal is invalid");
+  }
+  const journal = raw as Record<string, unknown>;
+  if (
+    Object.keys(journal).sort().join("\0") !==
+      ["fromVersion", "schemaVersion", "version"].join("\0") ||
+    journal.schemaVersion !== 1 ||
+    typeof journal.fromVersion !== "string" ||
+    typeof journal.version !== "string"
+  ) {
+    throw new Error("managed-host rollback journal is invalid");
+  }
+  assertStableVersion(journal.fromVersion);
+  assertStableVersion(journal.version);
+  // The abandoned generation is deliberately not validated: recovery must
+  // complete a rollback away from a generation that may be the corrupt one.
+  const targetDescriptor = await validateInstalledRuntime(
+    path.join(paths.runtime, journal.version),
+    journal.version,
+  );
+  await assertRuntimeMeetsDurableCapabilityFloor(paths, targetDescriptor);
+  await atomicVersionLink(paths.current, journal.version);
+  await atomicVersionLink(paths.previous, journal.fromVersion);
+  await writeRollbackUpdateHold(paths, journal.fromVersion, journal.version);
+  await removeDurably(paths.rollbackJournal);
+  return { fromVersion: journal.fromVersion, version: journal.version };
+}
+
+async function assertRuntimeMeetsDurableCapabilityFloor(
+  paths: ManagedRuntimePaths,
+  descriptor: ResolvedRuntimeDescriptor,
+): Promise<void> {
+  const minimum = await readMinimumRuntimeCapability(paths);
+  if (minimum !== null && descriptor.capabilitySchemaVersion < minimum) {
+    throw new Error(
+      `refusing runtime capability ${descriptor.capabilitySchemaVersion}; this host requires capability ${minimum} after the bundled runtime owned task state`,
+    );
+  }
+}
+
+async function readMinimumRuntimeCapability(
+  paths: ManagedRuntimePaths,
+): Promise<number | null> {
+  let raw: unknown;
+  try {
+    const stat = await lstat(paths.minimumRuntimeCapability);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.size > MAX_OPERATION_LOCK_BYTES
+    ) {
+      throw new Error("managed runtime capability floor is invalid");
+    }
+    raw = JSON.parse(await readFile(paths.minimumRuntimeCapability, "utf8"));
+  } catch (error) {
+    if (isMissing(error)) {
+      const inferred = await inferCapabilityFloorFromProviderState(paths);
+      if (inferred !== null) {
+        await mkdir(path.dirname(paths.minimumRuntimeCapability), {
+          recursive: true,
+          mode: 0o700,
+        });
+        await writeAtomicJson(paths.minimumRuntimeCapability, {
+          schemaVersion: 1,
+          minimumRuntimeCapability: inferred,
+        });
+      }
+      return inferred;
+    }
+    throw error;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed runtime capability floor is invalid");
+  }
+  const marker = raw as Record<string, unknown>;
+  if (
+    Object.keys(marker).sort().join("\0") !==
+      ["minimumRuntimeCapability", "schemaVersion"].join("\0") ||
+    marker.schemaVersion !== 1 ||
+    !Number.isSafeInteger(marker.minimumRuntimeCapability) ||
+    Number(marker.minimumRuntimeCapability) < 2
+  ) {
+    throw new Error("managed runtime capability floor is invalid");
+  }
+  return Number(marker.minimumRuntimeCapability);
+}
+
+async function inferCapabilityFloorFromProviderState(
+  paths: ManagedRuntimePaths,
+): Promise<number | null> {
+  let raw: unknown;
+  try {
+    const stat = await lstat(paths.runtimeProviderState);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_OPERATION_LOCK_BYTES) {
+      throw new Error("container runtime provider state is invalid");
+    }
+    raw = JSON.parse(await readFile(paths.runtimeProviderState, "utf8"));
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw new Error(`container runtime provider state is invalid: ${String(error)}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("container runtime provider state is invalid");
+  }
+  const marker = raw as Record<string, unknown>;
+  if (
+    Object.keys(marker).sort().join("\0") !==
+      ["claimedAt", "schemaVersion", "statefulProvider"].join("\0") ||
+    marker.schemaVersion !== 1 ||
+    marker.statefulProvider !== "apple-container" ||
+    !Number.isSafeInteger(marker.claimedAt) ||
+    Number(marker.claimedAt) <= 0
+  ) {
+    throw new Error("container runtime provider state is invalid");
+  }
+  // The apple-container marker is only writable by a capability-3 runtime.
+  return 3;
+}
+
+async function readRollbackUpdateHold(
+  paths: ManagedRuntimePaths,
+): Promise<RollbackUpdateHold | null> {
+  try {
+    return parseRollbackUpdateHold(
+      await readBoundedRegularFile(paths.rollbackUpdateHold),
+    );
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+}
+
+async function writeRollbackUpdateHold(
+  paths: ManagedRuntimePaths,
+  fromVersion: string,
+  version: string,
+): Promise<void> {
+  await writeAtomicJson(paths.rollbackUpdateHold, {
+    schemaVersion: 1,
+    fromVersion,
+    version,
+    createdAt: Date.now(),
+  });
+}
+
+async function removeRollbackUpdateHold(
+  paths: ManagedRuntimePaths,
+  expected: RollbackUpdateHold,
+): Promise<void> {
+  const current = await readRollbackUpdateHold(paths);
+  if (!current || JSON.stringify(current) !== JSON.stringify(expected)) {
+    throw new Error("managed host rollback update hold changed unexpectedly");
+  }
+  await removeDurably(paths.rollbackUpdateHold);
+}
+
+async function pruneRuntimeGenerations(paths: ManagedRuntimePaths): Promise<void> {
+  const keep = new Set(
+    (
+      await Promise.all([
+        readVersionLink(paths.current, paths.runtime),
+        readVersionLink(paths.previous, paths.runtime),
+      ])
+    ).filter((value): value is string => value !== null),
+  );
+  for (const name of await readdir(paths.runtime)) {
+    if (!VERSION.test(name) || keep.has(name)) continue;
+    const candidate = path.join(paths.runtime, name);
+    const stat = await lstat(candidate);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+      await rm(candidate, { recursive: true, force: true });
+    }
+  }
+  await syncDirectory(paths.runtime);
+}
+
+async function writeAtomicJson(file: string, value: unknown): Promise<void> {
+  const temporary = `${file}.${process.pid}.${randomBytes(6).toString("hex")}`;
+  const bytes = `${JSON.stringify(value)}\n`;
+  if (Buffer.byteLength(bytes) > MAX_OPERATION_LOCK_BYTES) {
+    throw new Error("managed-host transaction metadata exceeds its byte limit");
+  }
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporary, file);
+    await syncDirectory(path.dirname(file));
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+async function withManagedOperationLock<T>(
+  paths: ManagedRuntimePaths,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const release = await acquireManagedOperationLock(paths);
+  try {
+    return await operation();
+  } finally {
+    await release();
+  }
+}
+
+/** Signal/EXIT cleanup may arrive while its child still owns the service write. */
+async function withManagedOperationLockWaiting<T>(
+  paths: ManagedRuntimePaths,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const deadline = Date.now() + OPERATION_LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      return await withManagedOperationLock(paths, operation);
+    } catch (error) {
+      if (!(error instanceof ManagedOperationBusyError) || Date.now() >= deadline) {
+        throw error;
+      }
+      await new Promise<void>((resolve) => setTimeout(resolve, OPERATION_LOCK_POLL_MS));
+    }
+  }
+}
+
+class ManagedOperationBusyError extends Error {}
+
+async function acquireManagedOperationLock(
+  paths: ManagedRuntimePaths,
+): Promise<() => Promise<void>> {
+  const lockParent = path.dirname(paths.operationLock);
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const nonce = randomBytes(16).toString("hex");
+    try {
+      await mkdir(paths.operationLock, { mode: 0o700, recursive: false });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      if (!(await operationLockIsStale(paths.operationLock))) {
+        throw new ManagedOperationBusyError(
+          "another managed host install/update/rollback is already running",
+        );
+      }
+      const quarantine = path.join(
+        lockParent,
+        `.stale-operation-lock.${process.pid}.${randomBytes(6).toString("hex")}`,
+      );
+      try {
+        await rename(paths.operationLock, quarantine);
+        await syncDirectory(lockParent);
+      } catch (renameError) {
+        if (isMissing(renameError)) continue;
+        throw renameError;
+      }
+      await rm(quarantine, { recursive: true, force: true });
+      await syncDirectory(lockParent);
+      continue;
+    }
+
+    await syncDirectory(lockParent);
+    const ownerFile = path.join(paths.operationLock, "owner.json");
+    try {
+      await writeAtomicJson(ownerFile, {
+        schemaVersion: 1,
+        pid: process.pid,
+        startedAt: Date.now(),
+        nonce,
+      });
+    } catch (error) {
+      await rm(paths.operationLock, { recursive: true, force: true });
+      await syncDirectory(lockParent);
+      throw error;
+    }
+    return async () => {
+      let ownsLock = false;
+      try {
+        const owner = parseOperationLockOwner(await readBoundedRegularFile(ownerFile));
+        ownsLock = owner.nonce === nonce && owner.pid === process.pid;
+      } catch (error) {
+        if (!isMissing(error)) throw error;
+      }
+      if (!ownsLock) {
+        throw new Error("managed host operation lock ownership changed unexpectedly");
+      }
+      await rm(paths.operationLock, { recursive: true, force: true });
+      await syncDirectory(lockParent);
+    };
+  }
+  throw new Error("could not safely acquire the managed host operation lock");
+}
+
+async function operationLockIsStale(lockPath: string): Promise<boolean> {
+  const stat = await lstat(lockPath);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error("managed host operation lock is not a directory");
+  }
+  const ownerFile = path.join(lockPath, "owner.json");
+  try {
+    const owner = parseOperationLockOwner(await readBoundedRegularFile(ownerFile));
+    // Never steal from a live PID based on elapsed time alone: without fencing,
+    // that owner could resume and mutate links after a replacement entered.
+    // A dead PID is safe to reclaim; a future process-incarnation identifier
+    // can additionally distinguish the rare PID-reuse case.
+    return !pidIsAlive(owner.pid);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+    // A process can die between mkdir and owner.json. Only reclaim that narrow
+    // state after a conservative age; a fresh incomplete lock remains held.
+    return Date.now() - stat.mtimeMs >= INCOMPLETE_LOCK_STALE_MS;
+  }
+}
+
+interface OperationLockOwner {
+  readonly schemaVersion: 1;
+  readonly pid: number;
+  readonly startedAt: number;
+  readonly nonce: string;
+}
+
+interface ActivationMarker {
+  readonly schemaVersion: 1;
+  readonly fromVersion: string | null;
+  readonly version: string;
+}
+
+interface MaintenanceMarker {
+  readonly schemaVersion: 1;
+  readonly operation: "uninstall";
+  readonly phase: "checking" | "teardown" | "cleanup";
+  readonly purgeData: boolean;
+  readonly startedAt: number;
+}
+
+interface InstallIntentMarker {
+  readonly schemaVersion: 1;
+  readonly operation: "install";
+  readonly phase: "prepared" | "activated" | "attested";
+  readonly nonce: string;
+  readonly ownerPid: number;
+  readonly ownerUid: number;
+  readonly ownerStartedAt: string;
+  readonly createdAt: number;
+  readonly rootExisted: boolean;
+  readonly currentVersion: string | null;
+  readonly previousVersion: string | null;
+  readonly activationPending: ActivationMarker | null;
+  readonly shimOwnership: "missing" | "managed" | "legacy";
+  readonly recoveryShimExisted: boolean;
+  readonly recoveryEntrypointExisted: boolean;
+  readonly serviceOwnership: "missing" | "managed" | "legacy";
+  readonly serviceManager: ManagedServiceManagerState;
+  readonly priorServiceStop: "none" | "requested" | "stopped";
+}
+
+interface LegacyShimTakeoverMarker {
+  readonly schemaVersion: 1;
+  readonly operation: "legacy-shim-takeover";
+  readonly phase: "recorded" | "parked" | "restoring" | "finalizing";
+  readonly originalTarget: string;
+  readonly resolvedTarget: string;
+  readonly packageRoot: string;
+  readonly startedAt: number;
+}
+
+interface RollbackUpdateHold {
+  readonly schemaVersion: 1;
+  /** Release the operator rejected. */
+  readonly fromVersion: string;
+  /** Version deliberately restored by rollback. */
+  readonly version: string;
+  readonly createdAt: number;
+}
+
+function parseActivationMarker(bytes: Buffer): ActivationMarker {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("managed host activation marker is invalid");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed host activation marker is invalid");
+  }
+  const marker = raw as Record<string, unknown>;
+  if (
+    Object.keys(marker).sort().join("\0") !==
+      ["fromVersion", "schemaVersion", "version"].join("\0") ||
+    marker.schemaVersion !== 1 ||
+    (marker.fromVersion !== null && typeof marker.fromVersion !== "string") ||
+    typeof marker.version !== "string"
+  ) {
+    throw new Error("managed host activation marker is invalid");
+  }
+  if (marker.fromVersion !== null) assertStableVersion(marker.fromVersion);
+  assertStableVersion(marker.version);
+  return marker as unknown as ActivationMarker;
+}
+
+async function readMaintenanceMarker(
+  paths: ManagedRuntimePaths,
+): Promise<MaintenanceMarker | null> {
+  try {
+    return parseMaintenanceMarker(
+      await readBoundedRegularFile(paths.maintenancePending),
+    );
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+}
+
+function parseMaintenanceMarker(bytes: Buffer): MaintenanceMarker {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("managed host maintenance marker is invalid");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed host maintenance marker is invalid");
+  }
+  const marker = raw as Record<string, unknown>;
+  if (
+    Object.keys(marker).sort().join("\0") !==
+      ["operation", "phase", "purgeData", "schemaVersion", "startedAt"].join(
+        "\0",
+      ) ||
+    marker.schemaVersion !== 1 ||
+    marker.operation !== "uninstall" ||
+    (marker.phase !== "checking" &&
+      marker.phase !== "teardown" &&
+      marker.phase !== "cleanup") ||
+    typeof marker.purgeData !== "boolean" ||
+    typeof marker.startedAt !== "number" ||
+    !Number.isSafeInteger(marker.startedAt) ||
+    marker.startedAt <= 0
+  ) {
+    throw new Error("managed host maintenance marker is invalid");
+  }
+  return marker as unknown as MaintenanceMarker;
+}
+
+async function readInstallIntent(
+  paths: ManagedRuntimePaths,
+): Promise<InstallIntentMarker | null> {
+  try {
+    return parseInstallIntent(await readBoundedRegularFile(paths.installIntent));
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+}
+
+function parseInstallIntent(bytes: Buffer): InstallIntentMarker {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("managed host install intent is invalid");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed host install intent is invalid");
+  }
+  const marker = raw as Record<string, unknown>;
+  if (
+    Object.keys(marker).sort().join("\0") !==
+      [
+        "activationPending",
+        "createdAt",
+        "currentVersion",
+        "nonce",
+        "operation",
+        "ownerPid",
+        "ownerStartedAt",
+        "ownerUid",
+        "phase",
+        "previousVersion",
+        "priorServiceStop",
+        "recoveryEntrypointExisted",
+        "recoveryShimExisted",
+        "rootExisted",
+        "schemaVersion",
+        "serviceManager",
+        "serviceOwnership",
+        "shimOwnership",
+      ].join("\0") ||
+    marker.schemaVersion !== 1 ||
+    marker.operation !== "install" ||
+    (marker.phase !== "prepared" &&
+      marker.phase !== "activated" &&
+      marker.phase !== "attested") ||
+    typeof marker.nonce !== "string" ||
+    !INSTALL_INTENT_NONCE.test(marker.nonce) ||
+    typeof marker.ownerPid !== "number" ||
+    !Number.isSafeInteger(marker.ownerPid) ||
+    marker.ownerPid <= 0 ||
+    typeof marker.ownerUid !== "number" ||
+    !Number.isSafeInteger(marker.ownerUid) ||
+    marker.ownerUid < 0 ||
+    typeof marker.ownerStartedAt !== "string" ||
+    marker.ownerStartedAt.length === 0 ||
+    marker.ownerStartedAt.length > 128 ||
+    typeof marker.createdAt !== "number" ||
+    !Number.isSafeInteger(marker.createdAt) ||
+    marker.createdAt <= 0 ||
+    typeof marker.rootExisted !== "boolean" ||
+    (marker.currentVersion !== null &&
+      typeof marker.currentVersion !== "string") ||
+    (marker.previousVersion !== null &&
+      typeof marker.previousVersion !== "string") ||
+    (marker.activationPending !== null &&
+      (typeof marker.activationPending !== "object" ||
+        Array.isArray(marker.activationPending))) ||
+    !new Set(["missing", "managed", "legacy"]).has(
+      marker.shimOwnership as string,
+    ) ||
+    typeof marker.recoveryShimExisted !== "boolean" ||
+    typeof marker.recoveryEntrypointExisted !== "boolean" ||
+    !new Set(["missing", "managed", "legacy"]).has(
+      marker.serviceOwnership as string,
+    ) ||
+    !isServiceManagerState(marker.serviceManager) ||
+    !new Set(["none", "requested", "stopped"]).has(
+      marker.priorServiceStop as string,
+    )
+  ) {
+    throw new Error("managed host install intent is invalid");
+  }
+  if (marker.currentVersion !== null) {
+    assertStableVersion(marker.currentVersion as string);
+  }
+  if (marker.previousVersion !== null) {
+    assertStableVersion(marker.previousVersion as string);
+  }
+  if (marker.activationPending !== null) {
+    parseActivationMarker(Buffer.from(JSON.stringify(marker.activationPending)));
+  }
+  if (
+    marker.serviceOwnership === "missing" &&
+    ((marker.serviceManager as ManagedServiceManagerState).loaded ||
+      (marker.serviceManager as ManagedServiceManagerState).active ||
+      (marker.serviceManager as ManagedServiceManagerState).enabled)
+  ) {
+    throw new Error("managed host install intent is invalid");
+  }
+  return marker as unknown as InstallIntentMarker;
+}
+
+function isServiceManagerState(
+  value: unknown,
+): value is ManagedServiceManagerState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, unknown>;
+  return (
+    Object.keys(state).sort().join("\0") ===
+      ["active", "enabled", "loaded"].join("\0") &&
+    typeof state.loaded === "boolean" &&
+    typeof state.active === "boolean" &&
+    typeof state.enabled === "boolean" &&
+    (!state.active || state.loaded)
+  );
+}
+
+function assertServiceDefinitionState(
+  value: unknown,
+): asserts value is ManagedServiceDefinitionState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("managed host service definition state is invalid");
+  }
+  const state = value as Record<string, unknown>;
+  if (
+    Object.keys(state).sort().join("\0") !== ["manager", "ownership"].join("\0") ||
+    !new Set(["missing", "managed", "legacy"]).has(state.ownership as string) ||
+    !isServiceManagerState(state.manager)
+  ) {
+    throw new Error("managed host service definition state is invalid");
+  }
+}
+
+async function readLegacyShimTakeover(
+  paths: ManagedRuntimePaths,
+): Promise<LegacyShimTakeoverMarker | null> {
+  try {
+    return parseLegacyShimTakeover(
+      await readBoundedRegularFile(paths.legacyShimTakeover),
+    );
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+}
+
+function parseLegacyShimTakeover(bytes: Buffer): LegacyShimTakeoverMarker {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("managed host legacy command takeover is invalid");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed host legacy command takeover is invalid");
+  }
+  const marker = raw as Record<string, unknown>;
+  if (
+    Object.keys(marker).sort().join("\0") !==
+      [
+        "operation",
+        "originalTarget",
+        "packageRoot",
+        "phase",
+        "resolvedTarget",
+        "schemaVersion",
+        "startedAt",
+      ].join("\0") ||
+    marker.schemaVersion !== 1 ||
+    marker.operation !== "legacy-shim-takeover" ||
+    !new Set(["recorded", "parked", "restoring", "finalizing"]).has(
+      marker.phase as string,
+    ) ||
+    typeof marker.originalTarget !== "string" ||
+    marker.originalTarget.length === 0 ||
+    Buffer.byteLength(marker.originalTarget) > 2_048 ||
+    typeof marker.resolvedTarget !== "string" ||
+    !path.isAbsolute(marker.resolvedTarget) ||
+    typeof marker.packageRoot !== "string" ||
+    !path.isAbsolute(marker.packageRoot) ||
+    typeof marker.startedAt !== "number" ||
+    !Number.isSafeInteger(marker.startedAt) ||
+    marker.startedAt <= 0
+  ) {
+    throw new Error("managed host legacy command takeover is invalid");
+  }
+  return marker as unknown as LegacyShimTakeoverMarker;
+}
+
+function parseRollbackUpdateHold(bytes: Buffer): RollbackUpdateHold {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("managed host rollback update hold is invalid");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed host rollback update hold is invalid");
+  }
+  const hold = raw as Record<string, unknown>;
+  if (
+    Object.keys(hold).sort().join("\0") !==
+      ["createdAt", "fromVersion", "schemaVersion", "version"].join("\0") ||
+    hold.schemaVersion !== 1 ||
+    typeof hold.fromVersion !== "string" ||
+    typeof hold.version !== "string" ||
+    typeof hold.createdAt !== "number" ||
+    !Number.isSafeInteger(hold.createdAt) ||
+    hold.createdAt <= 0
+  ) {
+    throw new Error("managed host rollback update hold is invalid");
+  }
+  assertStableVersion(hold.fromVersion);
+  assertStableVersion(hold.version);
+  if (hold.fromVersion === hold.version) {
+    throw new Error("managed host rollback update hold is invalid");
+  }
+  return hold as unknown as RollbackUpdateHold;
+}
+
+function parseOperationLockOwner(bytes: Buffer): OperationLockOwner {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("managed host operation lock metadata is invalid");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed host operation lock metadata is invalid");
+  }
+  const owner = raw as Record<string, unknown>;
+  if (
+    Object.keys(owner).sort().join("\0") !==
+      ["nonce", "pid", "schemaVersion", "startedAt"].join("\0") ||
+    owner.schemaVersion !== 1 ||
+    typeof owner.pid !== "number" ||
+    !Number.isSafeInteger(owner.pid) ||
+    owner.pid <= 0 ||
+    typeof owner.startedAt !== "number" ||
+    !Number.isSafeInteger(owner.startedAt) ||
+    owner.startedAt <= 0 ||
+    typeof owner.nonce !== "string" ||
+    !/^[a-f0-9]{32}$/.test(owner.nonce)
+  ) {
+    throw new Error("managed host operation lock metadata is invalid");
+  }
+  return owner as unknown as OperationLockOwner;
+}
+
+async function readBoundedRegularFile(
+  file: string,
+  maxBytes = MAX_OPERATION_LOCK_BYTES,
+): Promise<Buffer> {
+  const handle = await open(
+    file,
+    fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW,
+  );
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || before.size > maxBytes) {
+      throw new Error("managed host operation metadata is invalid");
+    }
+    const bytes = await handle.readFile();
+    const after = await handle.stat();
+    if (
+      bytes.length > maxBytes ||
+      before.dev !== after.dev ||
+      before.ino !== after.ino ||
+      after.size !== bytes.length
+    ) {
+      throw new Error("managed host operation metadata changed while it was read");
+    }
+    return bytes;
+  } finally {
+    await handle.close();
+  }
+}
+
+function pidIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+function assertOwnerPid(pid: number): void {
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    throw new Error("managed host installer owner PID is invalid");
+  }
+}
+
+class ProcessIdentityUnavailableError extends Error {}
+
+/** UID + PID + kernel-recorded start time rejects foreign owners and PID reuse. */
+function processIdentity(pid: number): ManagedRuntimeOwnerIdentity | null {
+  assertOwnerPid(pid);
+  const result = spawnSync(
+    "/bin/ps",
+    ["-o", "uid=", "-o", "lstart=", "-p", String(pid)],
+    {
+      encoding: "utf8",
+      timeout: 2_000,
+      env: { PATH: "/usr/bin:/bin", LC_ALL: "C" },
+    },
+  );
+  if (result.status !== 0) return null;
+  const value = result.stdout.trim().replace(/\s+/g, " ");
+  const match = /^(\d+) (.+)$/.exec(value);
+  if (
+    !match ||
+    value.length > 160 ||
+    /[^\x20-\x7e]/.test(value)
+  ) {
+    throw new Error("could not identify managed host installer owner process");
+  }
+  const uid = Number(match[1]);
+  const startedAt = match[2]!;
+  if (!Number.isSafeInteger(uid) || uid < 0 || startedAt.length > 128) {
+    throw new Error("could not identify managed host installer owner process");
+  }
+  return { uid, startedAt };
+}
+
+function installIntentOwnerIsLive(
+  intent: InstallIntentMarker,
+  identityProbe: (pid: number) => ManagedRuntimeOwnerIdentity | null = processIdentity,
+): boolean {
+  if (!pidIsAlive(intent.ownerPid)) return false;
+  const identity = identityProbe(intent.ownerPid);
+  if (!identity) {
+    // kill(0) proved that the PID still exists. A transient ps failure cannot be
+    // interpreted as death or it would authorize rollback over a live install.
+    throw new ProcessIdentityUnavailableError(
+      "could not verify managed host installer owner identity",
+    );
+  }
+  return (
+    identity.uid === intent.ownerUid &&
+    identity.startedAt === intent.ownerStartedAt
+  );
+}
+
+async function removeDurably(file: string): Promise<void> {
+  await rm(file, { force: true });
+  await syncDirectory(path.dirname(file));
+}
+
+async function syncDirectory(directory: string): Promise<void> {
+  let handle;
+  try {
+    handle = await open(directory, fsConstants.O_RDONLY);
+    await handle.sync();
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    // Some filesystems/platforms do not expose directory fsync. File fsync and
+    // atomic rename still apply; these are the only portability exceptions.
+    if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR" && code !== "ENOENT") {
+      throw error;
+    }
+  } finally {
+    await handle?.close();
+  }
+}
+
+async function fetchBounded(
+  fetchImpl: typeof fetch,
+  url: string,
+  maxBytes: number,
+  timeoutMs: number,
+): Promise<Buffer> {
+  const response = await fetchImpl(url, {
+    redirect: "follow",
+    credentials: "omit",
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: { "user-agent": "uai-host-updater/1", accept: "application/json" },
+  });
+  if (!response.ok || !response.body) {
+    throw new Error(`release manifest download failed: HTTP ${response.status}`);
+  }
+  const declared = parseContentLength(response.headers.get("content-length"));
+  if (declared !== null && declared > maxBytes) {
+    throw new Error(`release manifest exceeds ${maxBytes} bytes`);
+  }
+  return readResponseBody(response, maxBytes);
+}
+
+async function downloadArtifact(
+  fetchImpl: typeof fetch,
+  artifact: ReleaseArtifact,
+  destination: string,
+  timeoutMs: number,
+): Promise<void> {
+  if (artifact.size > MAX_RELEASE_ARTIFACT_BYTES) {
+    throw new Error(`release artifact exceeds ${MAX_RELEASE_ARTIFACT_BYTES} bytes`);
+  }
+  const response = await fetchImpl(artifact.url, {
+    redirect: "follow",
+    credentials: "omit",
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: { "user-agent": "uai-host-updater/1", accept: "application/gzip" },
+  });
+  if (!response.ok || !response.body) {
+    throw new Error(`release artifact download failed: HTTP ${response.status}`);
+  }
+  const declared = parseContentLength(response.headers.get("content-length"));
+  if (declared !== null && declared !== artifact.size) {
+    throw new Error(
+      `release artifact content-length mismatch: expected ${artifact.size}, received ${declared}`,
+    );
+  }
+  const handle = await open(destination, "wx", 0o600);
+  let size = 0;
+  try {
+    const reader = response.body.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > artifact.size || size > MAX_RELEASE_ARTIFACT_BYTES) {
+        await reader.cancel("release artifact exceeds its authenticated size");
+        throw new Error("release artifact exceeds its authenticated size");
+      }
+      await handle.write(value);
+    }
+    await handle.sync();
+  } catch (error) {
+    await handle.close();
+    await rm(destination, { force: true });
+    throw error;
+  }
+  await handle.close();
+  if (size !== artifact.size) {
+    await rm(destination, { force: true });
+    throw new Error(
+      `release artifact size mismatch: expected ${artifact.size}, received ${size}`,
+    );
+  }
+}
+
+async function readResponseBody(response: Response, maxBytes: number): Promise<Buffer> {
+  const reader = response.body!.getReader();
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > maxBytes) {
+      await reader.cancel("response exceeds limit");
+      throw new Error(`response exceeds ${maxBytes} bytes`);
+    }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks, size);
+}
+
+function parseContentLength(value: string | null): number | null {
+  if (value === null) return null;
+  if (!/^(?:0|[1-9]\d*)$/.test(value)) throw new Error("invalid response content-length");
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw new Error("invalid response content-length");
+  return parsed;
+}
+
+function checkedTimeout(
+  value: number | undefined,
+  fallback: number,
+  maximum: number,
+): number {
+  const timeout = value ?? fallback;
+  if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > maximum) {
+    throw new Error("managed host update timeout is invalid");
+  }
+  return timeout;
+}
+
+function readMacosVersion(): string {
+  const result = spawnSync("/usr/bin/sw_vers", ["-productVersion"], {
+    encoding: "utf8",
+    timeout: 5_000,
+  });
+  const value = result.status === 0 ? result.stdout.trim() : "";
+  if (!/^\d+\.\d+(?:\.\d+)?$/.test(value)) {
+    throw new Error("could not determine the macOS version");
+  }
+  return value;
+}
+
+function readGlibcVersion(): string | null {
+  const report = process.report?.getReport() as
+    | { header?: { glibcVersionRuntime?: unknown } }
+    | undefined;
+  const value = report?.header?.glibcVersionRuntime;
+  return typeof value === "string" && /^\d+\.\d+$/.test(value) ? value : null;
+}
+
+function assertMinimumVersion(actual: string, minimum: string, label: string): void {
+  const parse = (value: string): number[] => {
+    const match = /^(\d+)\.(\d+)(?:\.(\d+))?/.exec(value);
+    if (!match) throw new Error(`could not determine ${label} version`);
+    return [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+  };
+  const left = parse(actual);
+  const right = parse(minimum);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index]! > right[index]!) return;
+    if (left[index]! < right[index]!) {
+      throw new Error(`${label} ${minimum} or newer is required; found ${actual}`);
+    }
+  }
+}
+
+function parseStableVersion(value: string): readonly [number, number, number] {
+  assertStableVersion(value);
+  return value.split(".").map(Number) as [number, number, number];
+}
+
+function assertStableVersion(value: string): void {
+  if (!VERSION.test(value)) throw new Error(`invalid stable host version: ${value}`);
+}
+
+function isInside(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+async function pathExists(candidate: string): Promise<boolean> {
+  try {
+    await access(candidate, fsConstants.F_OK);
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+/** Like `pathExists`, but dangling symlinks and partial cleanup trees count. */
+async function pathEntryExists(candidate: string): Promise<boolean> {
+  try {
+    await lstat(candidate);
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+function pathExistsSync(candidate: string): boolean {
+  try {
+    lstatSync(candidate);
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+function isMissing(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+}