@runuai/host 0.9.147 → 0.9.149

package/lib/machine-project-env-loader.ts

@@ -0,0 +1,152 @@
+import { lstatSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { TaskEnvironmentHandle } from "./task-environment/types";
+
+const STEP_TIMEOUT_MS = 60_000;
+const STEP_OUTPUT_BYTES = 256 * 1024;
+
+const INSTALL_ROOT_ASSET_SCRIPT = String.raw`set -eu
+destination=$1
+mode=$2
+case "$destination:$mode" in
+  /usr/local/share/uai/env-hook.sh:0555|/usr/local/bin/uai-env-exec:0555|/usr/local/share/uai/uai-task-forwarder.mjs:0444) ;;
+  *) exit 1 ;;
+esac
+directory=${"$"}{destination%/*}
+[ ! -L "$directory" ] || exit 1
+[ ! -e "$directory" ] || [ -d "$directory" ] || exit 1
+/usr/bin/install -d -o root -g root -m 0755 "$directory"
+[ ! -L "$destination" ] || exit 1
+[ ! -e "$destination" ] || [ -f "$destination" ] || exit 1
+temporary=$(/usr/bin/mktemp "$directory/.uai-loader.XXXXXX")
+trap '/bin/rm -f -- "$temporary"' EXIT
+/bin/cat > "$temporary"
+/bin/chown root:root "$temporary"
+/bin/chmod "$mode" "$temporary"
+/bin/mv -f -- "$temporary" "$destination"
+trap - EXIT`;
+
+const INSTALL_MACHINE_ENV_STUBS_SCRIPT = String.raw`set -eu
+ensure_block() {
+  file=$1
+  line=$2
+  case "$file" in
+    /etc/bash.bashrc | /etc/profile.d/uai-env.sh) ;;
+    *) exit 1 ;;
+  esac
+  [ ! -L "$file" ] || exit 1
+  [ ! -e "$file" ] || [ -f "$file" ] || exit 1
+  directory=${"$"}{file%/*}
+  [ -d "$directory" ] && [ ! -L "$directory" ] || exit 1
+  temporary=$(/usr/bin/mktemp "$directory/.uai-env-stub.XXXXXX")
+  trap '/bin/rm -f -- "$temporary"' EXIT
+  if [ -f "$file" ]; then
+    /usr/bin/awk '
+      $0 == "# >>> uai env loader >>>" { skipping = 1; next }
+      $0 == "# <<< uai env loader <<<" { skipping = 0; next }
+      !skipping { print }
+    ' "$file" > "$temporary"
+  fi
+  {
+    printf '%s\n' '# >>> uai env loader >>>'
+    printf '%s\n' "$line"
+    printf '%s\n' '# <<< uai env loader <<<'
+  } >> "$temporary"
+  /bin/chown root:root "$temporary"
+  /bin/chmod 0644 "$temporary"
+  /bin/mv -f -- "$temporary" "$file"
+  trap - EXIT
+}
+
+ensure_block /etc/bash.bashrc '[ "${"$"}{UAI_ENV_HOOK-0}" != 1 ] || { . /usr/local/share/uai/env-hook.sh; __uai_env_sync; __uai_env_install_bash_preexec; }'
+ensure_block /etc/profile.d/uai-env.sh '[ "${"$"}{UAI_ENV_HOOK-0}" != 1 ] || { . /usr/local/share/uai/env-hook.sh; if [ -z "${"$"}{BASH_EXECUTION_STRING-}" ] || [ -z "${"$"}{BASH_ENV-}" ]; then __uai_env_sync; fi; }'`;
+
+function packagedLoaderAsset(relativePath: readonly string[]): Buffer {
+  const path = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    ...relativePath,
+  );
+  const metadata = lstatSync(path);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new Error(`packaged task env loader asset is unsafe: ${path}`);
+  }
+  return readFileSync(path);
+}
+
+async function installRootLoaderAsset(
+  handle: Pick<TaskEnvironmentHandle<unknown>, "exec">,
+  destination: string,
+  mode: "0444" | "0555",
+  bytes: Uint8Array,
+): Promise<void> {
+  const result = await handle.exec({
+    argv: [
+      "/bin/sh",
+      "-c",
+      INSTALL_ROOT_ASSET_SCRIPT,
+      "uai-loader-install",
+      destination,
+      mode,
+    ],
+    user: "root",
+    projectEnvProfile: "maintenance",
+    stdin: bytes,
+    timeoutMs: STEP_TIMEOUT_MS,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `task env loader asset install failed for ${destination}: ${Buffer.from(result.stderr).toString("utf8").trim()}`,
+    );
+  }
+}
+
+/** Root-owned, idempotent loader bootstrap for machine and fixed-sidecar tasks. */
+export async function installMachineProjectEnvLoader(
+  handle: Pick<TaskEnvironmentHandle<unknown>, "exec">,
+): Promise<void> {
+  await installRootLoaderAsset(
+    handle,
+    "/usr/local/share/uai/env-hook.sh",
+    "0555",
+    packagedLoaderAsset(["scripts", "agent", "env-hook.sh"]),
+  );
+  await installRootLoaderAsset(
+    handle,
+    "/usr/local/bin/uai-env-exec",
+    "0555",
+    packagedLoaderAsset(["scripts", "agent", "uai-env-exec.sh"]),
+  );
+  const stubs = await handle.exec({
+    argv: ["/bin/sh", "-c", INSTALL_MACHINE_ENV_STUBS_SCRIPT],
+    user: "root",
+    projectEnvProfile: "maintenance",
+    timeoutMs: STEP_TIMEOUT_MS,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  if (stubs.exitCode !== 0) {
+    throw new Error(
+      `task env shell hook install failed: ${Buffer.from(stubs.stderr).toString("utf8").trim()}`,
+    );
+  }
+}
+
+/** Refresh the process asset before a direct-machine launch or recovery. */
+export function installMachineTaskForwarderAsset(
+  handle: Pick<TaskEnvironmentHandle<unknown>, "exec">,
+): Promise<void> {
+  return installRootLoaderAsset(
+    handle,
+    "/usr/local/share/uai/uai-task-forwarder.mjs",
+    "0444",
+    packagedLoaderAsset([
+      "images",
+      "standard",
+      "container",
+      "uai-task-forwarder.mjs",
+    ]),
+  );
+}

package/lib/managed-runtime.ts

@@ -35,11 +35,14 @@ import {
 import {
   BUNDLED_RUNTIME_CAPABILITY,
   BUNDLED_RUNTIME_ROOT,
+  MANAGED_RUNTIME_CAPABILITY,
   extractVerifiedRuntimeArchive,
   readVerifiedArtifactFile,
   type ResolvedRuntimeDescriptor,
+  type ResolvedRuntimeCapabilities,
   type RuntimeCapabilityDescriptorV3,
   type RuntimeAssetManifest,
+  validateManagedRuntimeCapabilityDescriptor,
   validateRuntimeAssetManifest,
   validateRuntimeCapabilityDescriptor,
   validateRuntimeDescriptor,
@@ -57,6 +60,7 @@ 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_RECOVERY_ENTRYPOINT_BYTES = 16 * 1024;
 const MAX_PACKAGE_JSON_BYTES = 64 * 1024;
 const INCOMPLETE_LOCK_STALE_MS = 5 * 60_000;
 export const MANAGED_UPDATE_RESTART_EXIT_CODE = 75;
@@ -760,9 +764,7 @@ 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");
-  }
+  assertManagedRuntimeCapabilityFloor(minimumCapabilityVersion);
   const paths = managedRuntimePaths(home);
   // Waiting acquisition: this runs during runtime detection, concurrently
   // with the startup settlement's own locked read. First-collision-dies took
@@ -779,16 +781,47 @@ export async function claimManagedRuntimeCapabilityFloor(
     ) {
       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,
-    });
+    await persistManagedRuntimeCapabilityFloor(
+      paths,
+      minimumCapabilityVersion,
+    );
+  });
+}
+
+function assertManagedRuntimeCapabilityFloor(
+  minimumCapabilityVersion: number,
+): void {
+  if (
+    !Number.isSafeInteger(minimumCapabilityVersion) ||
+    minimumCapabilityVersion < 2
+  ) {
+    throw new Error("managed runtime capability floor is invalid");
+  }
+}
+
+/** Persist a floor while the caller holds the managed-operation lock. */
+async function persistManagedRuntimeCapabilityFloor(
+  paths: ManagedRuntimePaths,
+  minimumCapabilityVersion: number,
+): Promise<void> {
+  // The recovery entrypoint is a second rollback path, independent of this
+  // TypeScript process. A 0.9.148 updater leaves its exact v1 entrypoint in
+  // place when it boots the first capability-4 generation. Upgrade that
+  // owned file before making the floor durable, so standalone recovery can
+  // recognize the new cross-platform capability marker immediately.
+  const recoveryEntrypoint = await assertRecoveryEntrypointReplaceable(paths);
+  if (recoveryEntrypoint === "legacy-v1") {
+    await ensureRecoveryEntrypoint(paths);
+  }
+  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,
   });
 }
 
@@ -915,6 +948,31 @@ export async function reconcileManagedRuntimeActivation(
   return managedRuntimeRestartRequired(runningVersion, home);
 }
 
+/**
+ * Provisional installs settle after their install intent disappears, through
+ * the activation watcher rather than cmdRun's immediate acknowledgement.
+ * Preserve the same floor-before-unfence transaction on that path.
+ */
+export async function reconcileManagedRuntimeActivationWithCapabilityFloor(
+  runningVersion: string,
+  minimumCapabilityVersion: number,
+  onCapabilityFloorPersisted: () => void,
+  home?: string,
+): Promise<boolean> {
+  if (pathExistsSync(managedRuntimePaths(home).installIntent)) return false;
+  if (managedRuntimeActivationPending(home)) {
+    return !(
+      await acknowledgeManagedRuntimeActivationWithCapabilityFloor(
+        runningVersion,
+        minimumCapabilityVersion,
+        onCapabilityFloorPersisted,
+        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;
@@ -924,7 +982,7 @@ export async function validateManagedRuntimeSelection(
   runningVersion: string,
   home?: string,
 ): Promise<boolean> {
-  return reconcileManagedRuntimeSelection(runningVersion, home, false);
+  return reconcileManagedRuntimeSelection(runningVersion, home, false, null);
 }
 
 /**
@@ -932,7 +990,7 @@ export async function validateManagedRuntimeSelection(
  * 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.
+ * performs the capability-aware locked acknowledgement.
  */
 export async function validateProvisionalManagedRuntimeSelection(
   runningVersion: string,
@@ -973,17 +1031,50 @@ export async function acknowledgeManagedRuntimeActivation(
   runningVersion: string,
   home?: string,
 ): Promise<boolean> {
-  return reconcileManagedRuntimeSelection(runningVersion, home, true);
+  return reconcileManagedRuntimeSelection(runningVersion, home, true, null);
+}
+
+/**
+ * Acknowledge a healthy first boot without opening task admission between the
+ * irreversible floor and its in-process capability state. The callback must
+ * synchronously publish only local state: it runs after the floor is durable
+ * and while activationPending still fences every TaskUp.
+ */
+export async function acknowledgeManagedRuntimeActivationWithCapabilityFloor(
+  runningVersion: string,
+  minimumCapabilityVersion: number,
+  onCapabilityFloorPersisted: () => void,
+  home?: string,
+): Promise<boolean> {
+  assertManagedRuntimeCapabilityFloor(minimumCapabilityVersion);
+  if (typeof onCapabilityFloorPersisted !== "function") {
+    throw new Error("managed runtime capability callback is invalid");
+  }
+  return reconcileManagedRuntimeSelection(runningVersion, home, true, {
+    minimumCapabilityVersion,
+    onCapabilityFloorPersisted,
+  });
+}
+
+interface ManagedRuntimeCapabilityAcknowledgement {
+  readonly minimumCapabilityVersion: number;
+  readonly onCapabilityFloorPersisted: () => void;
 }
 
 async function reconcileManagedRuntimeSelection(
   runningVersion: string,
   home: string | undefined,
   acknowledgeHealthyImport: boolean,
+  capabilityAcknowledgement: ManagedRuntimeCapabilityAcknowledgement | null,
 ): Promise<boolean> {
   assertStableVersion(runningVersion);
   const paths = managedRuntimePaths(home);
-  if (!(await pathExists(paths.root))) return true;
+  if (!(await pathExists(paths.root))) {
+    if (capabilityAcknowledgement !== null) {
+      throw new Error("managed runtime capability acknowledgement has no runtime");
+    }
+    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
@@ -997,6 +1088,7 @@ async function reconcileManagedRuntimeSelection(
         runningVersion,
         paths,
         acknowledgeHealthyImport,
+        capabilityAcknowledgement,
       );
     } catch (error) {
       if (
@@ -1017,18 +1109,54 @@ async function reconcileManagedRuntimeSelectionLocked(
   runningVersion: string,
   paths: ManagedRuntimePaths,
   acknowledgeHealthyImport: boolean,
+  capabilityAcknowledgement: ManagedRuntimeCapabilityAcknowledgement | null,
 ): Promise<boolean> {
   return withManagedOperationLock(paths, async () => {
     await ensureManagedDirectories(paths);
     await recoverRollback(paths);
     const selectedVersion = await readVersionLink(paths.current, paths.runtime);
+    let selectedDescriptor: ResolvedRuntimeDescriptor | null = null;
     if (selectedVersion !== null) {
-      const selectedDescriptor = await validateInstalledRuntime(
+      selectedDescriptor = await validateInstalledRuntime(
         path.join(paths.runtime, selectedVersion),
         selectedVersion,
       );
       await assertRuntimeMeetsDurableCapabilityFloor(paths, selectedDescriptor);
     }
+    const persistAcknowledgedCapabilityFloor = async (): Promise<void> => {
+      if (capabilityAcknowledgement === null) return;
+      if (
+        selectedVersion !== runningVersion ||
+        selectedDescriptor === null
+      ) {
+        throw new Error(
+          "managed runtime capability acknowledgement has no selected runtime",
+        );
+      }
+      if (
+        selectedDescriptor.runtimeCapabilityVersion <
+        capabilityAcknowledgement.minimumCapabilityVersion
+      ) {
+        throw new Error(
+          `refusing runtime capability ${selectedDescriptor.runtimeCapabilityVersion}; activation requires capability ${capabilityAcknowledgement.minimumCapabilityVersion}`,
+        );
+      }
+      await assertNoManagedInstallIntent(
+        paths,
+        "runtime capability acknowledgement",
+      );
+      if (pathExistsSync(paths.maintenancePending)) {
+        throw new Error("managed runtime maintenance is already in progress");
+      }
+      await persistManagedRuntimeCapabilityFloor(
+        paths,
+        capabilityAcknowledgement.minimumCapabilityVersion,
+      );
+      const callbackResult = capabilityAcknowledgement.onCapabilityFloorPersisted();
+      if (callbackResult !== undefined) {
+        throw new Error("managed runtime capability callback must be synchronous");
+      }
+    };
     let marker: ActivationMarker;
     try {
       marker = parseActivationMarker(
@@ -1041,7 +1169,11 @@ async function reconcileManagedRuntimeSelectionLocked(
       // before allowing this process to continue.
       if (isMissing(error)) {
         const current = await readVersionLink(paths.current, paths.runtime);
-        return current === null || current === runningVersion;
+        const selected = current === null || current === runningVersion;
+        if (selected && acknowledgeHealthyImport) {
+          await persistAcknowledgedCapabilityFloor();
+        }
+        return selected;
       }
       throw error;
     }
@@ -1055,6 +1187,7 @@ async function reconcileManagedRuntimeSelectionLocked(
       }
       if (marker.version !== runningVersion) return false;
       if (acknowledgeHealthyImport) {
+        await persistAcknowledgedCapabilityFloor();
         await removeDurably(paths.activationPending);
       }
       return true;
@@ -1066,6 +1199,7 @@ async function reconcileManagedRuntimeSelectionLocked(
       // runtime.
       const selected = current === null || current === runningVersion;
       if (selected && acknowledgeHealthyImport) {
+        await persistAcknowledgedCapabilityFloor();
         await removeDurably(paths.activationPending);
       }
       return selected;
@@ -1733,8 +1867,8 @@ async function restorePreInstallRuntimeSelection(
     await removeOwnedSymlink(paths.recoveryShim, paths.recoveryEntrypoint);
   }
   if (!intent.recoveryEntrypointExisted) {
-    const exists = await assertRecoveryEntrypointReplaceable(paths);
-    if (exists) await removeDurably(paths.recoveryEntrypoint);
+    const state = await assertRecoveryEntrypointReplaceable(paths);
+    if (state !== "missing") await removeDurably(paths.recoveryEntrypoint);
   }
 }
 
@@ -1834,6 +1968,22 @@ export async function validateInstalledRuntime(
 async function resolveInstalledRuntimeCapabilities(
   root: string,
   platform: string,
+): Promise<ResolvedRuntimeCapabilities> {
+  const platformCapabilities = await resolveInstalledPlatformCapabilities(
+    root,
+    platform,
+  );
+  const runtimeCapabilityVersion =
+    await resolveInstalledManagedRuntimeCapability(
+      root,
+      platformCapabilities.capabilitySchemaVersion,
+    );
+  return { ...platformCapabilities, runtimeCapabilityVersion };
+}
+
+async function resolveInstalledPlatformCapabilities(
+  root: string,
+  platform: string,
 ): Promise<{ readonly capabilitySchemaVersion: 1 } | RuntimeCapabilityDescriptorV3> {
   const bundledRoot = path.join(root, ...BUNDLED_RUNTIME_ROOT.split("/"));
   let bundledMetadata;
@@ -1868,6 +2018,39 @@ async function resolveInstalledRuntimeCapabilities(
   return validateRuntimeCapabilityDescriptor(raw, platform);
 }
 
+async function resolveInstalledManagedRuntimeCapability(
+  root: string,
+  legacyCapabilityVersion: 1 | 3,
+): Promise<1 | 3 | 4> {
+  const capabilityPath = path.join(
+    root,
+    ...MANAGED_RUNTIME_CAPABILITY.split("/"),
+  );
+  let metadata;
+  try {
+    metadata = await lstat(capabilityPath);
+  } catch (error) {
+    if (isMissing(error)) return legacyCapabilityVersion;
+    throw error;
+  }
+  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 validateManagedRuntimeCapabilityDescriptor(raw)
+    .capabilitySchemaVersion;
+}
+
 async function validateInstalledRuntimeAssets(
   root: string,
   capabilities: RuntimeCapabilityDescriptorV3,
@@ -2106,9 +2289,8 @@ async function capturePreInstallState(paths: ManagedRuntimePaths): Promise<
       `refusing to replace unrelated host recovery command at ${paths.recoveryShim}`,
     );
   }
-  const recoveryEntrypointExisted = await assertRecoveryEntrypointReplaceable(
-    paths,
-  );
+  const recoveryEntrypointExisted =
+    (await assertRecoveryEntrypointReplaceable(paths)) !== "missing";
   return {
     rootExisted,
     currentVersion,
@@ -2456,18 +2638,20 @@ async function ensureRecoveryEntrypoint(paths: ManagedRuntimePaths): Promise<voi
   }
   await chmod(directory, 0o700);
   const expected = recoveryEntrypointContents(paths);
-  const exists = await assertRecoveryEntrypointReplaceable(paths);
-  if (!exists) {
+  const state = await assertRecoveryEntrypointReplaceable(paths);
+  if (state !== "current") {
     await writeAtomicExecutable(paths.recoveryEntrypoint, expected);
   } else {
     await chmod(paths.recoveryEntrypoint, 0o700);
   }
 }
 
-/** Return true when the exact managed entrypoint already exists. */
+type RecoveryEntrypointState = "missing" | "legacy-v1" | "current";
+
+/** Classify only entrypoints this release owns exactly. */
 async function assertRecoveryEntrypointReplaceable(
   paths: ManagedRuntimePaths,
-): Promise<boolean> {
+): Promise<RecoveryEntrypointState> {
   try {
     const stat = await lstat(paths.recoveryEntrypoint);
     if (!stat.isFile() || stat.isSymbolicLink()) {
@@ -2475,25 +2659,71 @@ async function assertRecoveryEntrypointReplaceable(
         `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}`,
-      );
+    const existing = await readBoundedRegularFile(
+      paths.recoveryEntrypoint,
+      MAX_RECOVERY_ENTRYPOINT_BYTES,
+    );
+    if (existing.equals(Buffer.from(recoveryEntrypointContents(paths)))) {
+      return "current";
     }
-    return true;
+    if (existing.equals(Buffer.from(recoveryEntrypointContents(paths, 1)))) {
+      return "legacy-v1";
+    }
+    throw new Error(
+      `refusing to replace modified host recovery entrypoint at ${paths.recoveryEntrypoint}`,
+    );
   } catch (error) {
-    if (isMissing(error)) return false;
+    if (isMissing(error)) return "missing";
     throw error;
   }
 }
 
-function recoveryEntrypointContents(paths: ManagedRuntimePaths): string {
+function recoveryEntrypointContents(
+  paths: ManagedRuntimePaths,
+  revision: 1 | 2 = 2,
+): string {
   const runtime = shellSingleQuote(paths.runtime);
   const capabilityFloor = shellSingleQuote(paths.minimumRuntimeCapability);
   const providerState = shellSingleQuote(paths.runtimeProviderState);
+  const capabilityProbe =
+    revision === 1
+      ? `  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')
+`
+      : `  managed_capability=$generation/agent/managed-runtime-capability.json
+  capability=$generation/agent/bundled-runtime/capability.json
+  # The TypeScript rollback/install path validates the exact JSON descriptor
+  # and (on Darwin) the closed asset tree. The cross-platform managed marker
+  # was added compatibly at capability 4; older generations derive their
+  # effective capability from the Darwin-only bundled descriptor.
+  if [ -e "$managed_capability" ] || [ -L "$managed_capability" ]; then
+    if [ ! -f "$managed_capability" ] || [ -L "$managed_capability" ]; then
+      fail "the previous runtime capability descriptor is invalid"
+    fi
+    if ! LC_ALL=C tr -d '[:space:]' < "$managed_capability" |
+      grep -Eq '^\\{"capabilitySchemaVersion":4\\}$'; then
+      fail "the previous runtime capability descriptor is invalid"
+    fi
+    generation_capability=4
+  else
+    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')
+  fi
+`;
   return `#!/bin/sh
-# uai-managed-host-recovery-v1
+# uai-managed-host-recovery-v${revision}
 set -eu
 
 runtime=${runtime}
@@ -2563,18 +2793,7 @@ if [ "$floor_required" = true ]; then
   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
+${capabilityProbe}  case $generation_capability in
     '' | *[!0-9]*) fail "the previous runtime capability descriptor is invalid" ;;
   esac
   if [ "$generation_capability" -lt "$required_floor" ]; then
@@ -2729,9 +2948,9 @@ async function assertRuntimeMeetsDurableCapabilityFloor(
   descriptor: ResolvedRuntimeDescriptor,
 ): Promise<void> {
   const minimum = await readMinimumRuntimeCapability(paths);
-  if (minimum !== null && descriptor.capabilitySchemaVersion < minimum) {
+  if (minimum !== null && descriptor.runtimeCapabilityVersion < minimum) {
     throw new Error(
-      `refusing runtime capability ${descriptor.capabilitySchemaVersion}; this host requires capability ${minimum} after the bundled runtime owned task state`,
+      `refusing runtime capability ${descriptor.runtimeCapabilityVersion}; this host requires capability ${minimum} after the bundled runtime owned task state`,
     );
   }
 }