@runuai/host 0.9.14 → 0.9.42

package/lib/keyed-promise-tail.ts

@@ -0,0 +1,23 @@
+/**
+ * Serialize asynchronous maintenance while coalescing callers for the same
+ * requested configuration. A different key always queues a distinct pass;
+ * this is stronger than a plain in-flight memo, which can let configuration C
+ * accidentally join an older B operation and then be declared reconciled.
+ */
+export class KeyedPromiseTail<T> {
+  private tail: { key: string; promise: Promise<T> } | null = null;
+
+  run(key: string, operation: () => Promise<T>): Promise<T> {
+    if (this.tail?.key === key) return this.tail.promise;
+    const predecessor = this.tail?.promise;
+    let running!: Promise<T>;
+    running = (predecessor
+      ? predecessor.catch(() => undefined)
+      : Promise.resolve()
+    ).then(operation).finally(() => {
+      if (this.tail?.promise === running) this.tail = null;
+    });
+    this.tail = { key, promise: running };
+    return running;
+  }
+}

package/lib/legacy-runtime-v1.fixture.ts

@@ -0,0 +1,627 @@
+/**
+ * Intentionally frozen compatibility oracle copied from
+ * f2d638d52c641282db8e01430c3196364b2d2d3f before ADR-101 Phase B.
+ *
+ * Do not update this parser to understand new runtime capabilities. The
+ * rolling-bridge regression executes new artifacts through these exact legacy
+ * archive bytes/layout checks. Only the imports below were widened so the
+ * verbatim legacy installed-layout validator can live in the same fixture.
+ */
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  realpath,
+  symlink,
+} from "node:fs/promises";
+import path from "node:path";
+import { gzipSync, gunzipSync } from "node:zlib";
+
+import {
+  MAX_RELEASE_ARTIFACT_BYTES,
+  isReleasePlatform,
+  type ReleaseArtifact,
+  verifyReleaseArtifactIntegrity,
+} from "./release-manifest";
+
+const BLOCK_SIZE = 512;
+const MAX_UNCOMPRESSED_BYTES = 1024 * 1024 * 1024;
+const MAX_ARCHIVE_MEMBERS = 100_000;
+const MAX_MEMBER_PATH_BYTES = 4096;
+const MAX_PAX_BYTES = 64 * 1024;
+const ZERO_BLOCK = Buffer.alloc(BLOCK_SIZE);
+const EXPECTED_TOP_LEVEL = Object.freeze(["agent", "bin", "node", "runtime.json"]);
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+
+export interface RuntimeDescriptor {
+  readonly schemaVersion: 1;
+  readonly hostVersion: string;
+  readonly platform: string;
+  readonly node: {
+    readonly version: string;
+    readonly modules: string;
+  };
+  readonly requirements: Readonly<Record<string, string>>;
+  readonly layout: {
+    readonly agent: "agent";
+    readonly launcher: "bin/uai-host";
+    readonly node: "node";
+  };
+}
+
+interface ArchiveEntry {
+  readonly memberPath: string;
+  readonly type: "0" | "2" | "5";
+  readonly mode: number;
+  readonly data: Buffer;
+  readonly linkTarget: string;
+  readonly resolvedLinkTarget: string | null;
+}
+
+export interface InspectedRuntimeArchive {
+  readonly descriptor: RuntimeDescriptor;
+  readonly memberCount: number;
+}
+
+/**
+ * Read, count and hash one already-downloaded regular file through one open
+ * descriptor. Extraction consumes the exact returned bytes; there is no
+ * verify-by-name/reopen window in which the pathname could be swapped.
+ */
+export async function readVerifiedArtifactFile(
+  archivePath: string,
+  artifact: ReleaseArtifact,
+): Promise<Buffer> {
+  const noFollow = fsConstants.O_NOFOLLOW ?? 0;
+  const handle = await open(archivePath, fsConstants.O_RDONLY | noFollow);
+  try {
+    const before = await handle.stat();
+    if (!before.isFile()) throw new Error("runtime archive must be a regular file");
+    if (before.size > MAX_RELEASE_ARTIFACT_BYTES) {
+      throw new Error(`runtime archive exceeds ${MAX_RELEASE_ARTIFACT_BYTES} bytes`);
+    }
+
+    const hash = createHash("sha256");
+    const chunks: Buffer[] = [];
+    let size = 0;
+    for await (const raw of handle.createReadStream({ autoClose: false })) {
+      const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+      size += chunk.length;
+      if (size > MAX_RELEASE_ARTIFACT_BYTES) {
+        throw new Error(`runtime archive exceeds ${MAX_RELEASE_ARTIFACT_BYTES} bytes`);
+      }
+      hash.update(chunk);
+      chunks.push(chunk);
+    }
+    const after = await handle.stat();
+    if (
+      before.dev !== after.dev ||
+      before.ino !== after.ino ||
+      before.size !== after.size ||
+      size !== after.size
+    ) {
+      throw new Error("runtime archive changed while it was being verified");
+    }
+    verifyReleaseArtifactIntegrity(artifact, {
+      size,
+      sha256: hash.digest(),
+    });
+    return Buffer.concat(chunks, size);
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function extractVerifiedRuntimeArchive(
+  archiveBytes: Buffer,
+  destination: string,
+  expected: { version: string; platform: string },
+): Promise<InspectedRuntimeArchive> {
+  const { entries, descriptor } = inspectRuntimeArchive(archiveBytes, expected);
+  // The caller gives us a fresh, private staging path. `recursive: false`
+  // refuses to merge archive contents into any pre-existing tree.
+  await mkdir(destination, { mode: 0o700, recursive: false });
+  const directories = [destination];
+
+  for (const entry of entries) {
+    const output = path.join(destination, ...entry.memberPath.split("/"));
+    if (entry.type === "5") {
+      await mkdir(output, { mode: 0o755, recursive: false });
+      await chmod(output, 0o755);
+      directories.push(output);
+    } else if (entry.type === "0") {
+      const handle = await open(output, "wx", entry.mode);
+      try {
+        await handle.writeFile(entry.data);
+        await handle.chmod(entry.mode);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+    }
+  }
+  // Create links only after every regular target exists. Archive validation
+  // has already rejected absolute/escaping targets and any child below a link.
+  for (const entry of entries) {
+    if (entry.type !== "2") continue;
+    const output = path.join(destination, ...entry.memberPath.split("/"));
+    await symlink(entry.linkTarget, output);
+  }
+  // Persist children before parents so activation never points at a directory
+  // whose archive contents only existed in the page cache at power loss.
+  for (const directory of directories.reverse()) {
+    await syncDirectory(directory);
+  }
+  return { descriptor, memberCount: entries.length };
+}
+
+export function inspectRuntimeArchive(
+  archiveBytes: Buffer,
+  expected: { version: string; platform: string },
+): { entries: readonly ArchiveEntry[]; descriptor: RuntimeDescriptor } {
+  assertCanonicalGzipHeader(archiveBytes);
+  const tar = gunzipSync(archiveBytes, { maxOutputLength: MAX_UNCOMPRESSED_BYTES });
+  // The release builder emits a single deterministic gzip stream. Rebuilding
+  // it under the packaged, exactly-pinned Node rejects concatenated streams,
+  // trailing bytes and alternate encodings before any filesystem mutation.
+  // Modern Node always writes a zero gzip mtime (the option was removed from
+  // its public typings); the builder runs the same pinned Node patch.
+  const canonical = gzipSync(tar, { level: 9 });
+  canonical[9] = 255;
+  if (!archiveBytes.equals(canonical)) {
+    throw new Error("runtime archive gzip stream is not canonical");
+  }
+
+  const entries: ArchiveEntry[] = [];
+  const byPath = new Map<string, ArchiveEntry>();
+  let offset = 0;
+  let pendingPax: { path?: string; linkpath?: string } | null = null;
+  let previousMember: string | null = null;
+  let terminated = false;
+
+  while (offset + BLOCK_SIZE <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK_SIZE);
+    if (header.equals(ZERO_BLOCK)) {
+      if (
+        offset + 2 * BLOCK_SIZE !== tar.length ||
+        !tar.subarray(offset + BLOCK_SIZE).equals(ZERO_BLOCK)
+      ) {
+        throw new Error("runtime archive has trailing bytes or an invalid terminator");
+      }
+      offset += 2 * BLOCK_SIZE;
+      terminated = true;
+      break;
+    }
+
+    validateHeaderChecksum(header);
+    if (parseString(header, 257, 6) !== "ustar") {
+      throw new Error("runtime archive is not ustar");
+    }
+    const name = parseString(header, 0, 100);
+    const prefix = parseString(header, 345, 155);
+    const headerPath = prefix ? `${prefix}/${name}` : name;
+    const mode = parseOctal(header, 100, 8, "mode");
+    const uid = parseOctal(header, 108, 8, "uid");
+    const gid = parseOctal(header, 116, 8, "gid");
+    const size = parseOctal(header, 124, 12, "size");
+    const mtime = parseOctal(header, 136, 12, "mtime");
+    const type = (parseString(header, 156, 1) || "0") as string;
+    const rawLinkTarget = parseString(header, 157, 100);
+    if (
+      uid !== 0 ||
+      gid !== 0 ||
+      mtime !== 0 ||
+      parseString(header, 265, 32) !== "root" ||
+      parseString(header, 297, 32) !== "root" ||
+      parseOctal(header, 329, 8, "devmajor") !== 0 ||
+      parseOctal(header, 337, 8, "devminor") !== 0
+    ) {
+      throw new Error("runtime archive metadata is not canonical");
+    }
+    if (!Number.isSafeInteger(size) || size < 0 || size > MAX_UNCOMPRESSED_BYTES) {
+      throw new Error("runtime archive member size is invalid");
+    }
+    const dataStart = offset + BLOCK_SIZE;
+    const dataEnd = dataStart + size;
+    const paddedEnd = dataStart + Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+    if (dataEnd > tar.length || paddedEnd > tar.length) {
+      throw new Error("runtime archive member exceeds input");
+    }
+    if (tar.subarray(dataEnd, paddedEnd).some((byte) => byte !== 0)) {
+      throw new Error(`runtime archive member padding is not zero: ${headerPath}`);
+    }
+    const data = tar.subarray(dataStart, dataEnd);
+    offset = paddedEnd;
+
+    if (type === "x") {
+      if (pendingPax) throw new Error("runtime archive has consecutive pax headers");
+      if (size > MAX_PAX_BYTES || mode !== 0o644) {
+        throw new Error("runtime archive pax header is invalid");
+      }
+      pendingPax = parsePax(data);
+      continue;
+    }
+    if (type !== "0" && type !== "2" && type !== "5") {
+      throw new Error(`unsupported runtime archive member type: ${type}`);
+    }
+    const rawMemberPath = pendingPax?.path ?? headerPath;
+    if ((type === "5") !== rawMemberPath.endsWith("/")) {
+      throw new Error(`runtime archive member path/type mismatch: ${rawMemberPath}`);
+    }
+    const memberPath = safeMemberPath(rawMemberPath);
+    if (
+      previousMember !== null &&
+      Buffer.compare(Buffer.from(previousMember), Buffer.from(memberPath)) >= 0
+    ) {
+      throw new Error(`runtime archive members are not strictly sorted: ${memberPath}`);
+    }
+    previousMember = memberPath;
+    if (byPath.has(memberPath)) {
+      throw new Error(`duplicate runtime archive member: ${memberPath}`);
+    }
+    if (entries.length >= MAX_ARCHIVE_MEMBERS) {
+      throw new Error(`runtime archive exceeds ${MAX_ARCHIVE_MEMBERS} members`);
+    }
+    if (type !== "0" && size !== 0) {
+      throw new Error(`non-file runtime archive member carries data: ${memberPath}`);
+    }
+    const expectedMode = type === "5" ? 0o755 : type === "2" ? 0o777 : mode;
+    if (
+      mode !== expectedMode ||
+      (type === "0" && mode !== 0o644 && mode !== 0o755)
+    ) {
+      throw new Error(`runtime archive member mode is invalid: ${memberPath}`);
+    }
+    const linkTarget = pendingPax?.linkpath ?? rawLinkTarget;
+    const resolvedLinkTarget =
+      type === "2" ? safeLinkTarget(memberPath, linkTarget) : null;
+    const entry: ArchiveEntry = {
+      memberPath,
+      type,
+      mode,
+      data,
+      linkTarget,
+      resolvedLinkTarget,
+    };
+    entries.push(entry);
+    byPath.set(memberPath, entry);
+    pendingPax = null;
+  }
+
+  if (!terminated || offset !== tar.length || pendingPax) {
+    throw new Error("runtime archive is truncated");
+  }
+  validateEntryGraph(entries, byPath);
+  const descriptorEntry = byPath.get("runtime.json");
+  if (!descriptorEntry || descriptorEntry.data.length > MAX_PAX_BYTES) {
+    throw new Error("runtime archive descriptor is missing or too large");
+  }
+  let rawDescriptor: unknown;
+  try {
+    rawDescriptor = JSON.parse(descriptorEntry.data.toString("utf8"));
+  } catch {
+    throw new Error("runtime archive descriptor is invalid JSON");
+  }
+  const descriptor = validateRuntimeDescriptor(rawDescriptor, expected);
+  return { entries, descriptor };
+}
+
+function validateEntryGraph(
+  entries: readonly ArchiveEntry[],
+  byPath: ReadonlyMap<string, ArchiveEntry>,
+): void {
+  const topLevel = new Set(entries.map((entry) => entry.memberPath.split("/")[0]!));
+  if (
+    [...topLevel].sort().join("\0") !== [...EXPECTED_TOP_LEVEL].sort().join("\0")
+  ) {
+    throw new Error("runtime archive top-level layout is invalid");
+  }
+  for (const entry of entries) {
+    const parts = entry.memberPath.split("/");
+    for (let length = 1; length < parts.length; length += 1) {
+      const ancestor = parts.slice(0, length).join("/");
+      const parent = byPath.get(ancestor);
+      if (!parent || parent.type !== "5") {
+        throw new Error(`runtime archive parent is not a directory: ${ancestor}`);
+      }
+    }
+    if (
+      entry.type === "2" &&
+      (!entry.resolvedLinkTarget || !byPath.has(entry.resolvedLinkTarget))
+    ) {
+      throw new Error(`runtime archive symlink target does not exist: ${entry.memberPath}`);
+    }
+  }
+  for (const required of [
+    "agent/bin/uai-host.mjs",
+    "bin/uai-host",
+    "node/bin/node",
+    "runtime.json",
+  ]) {
+    if (byPath.get(required)?.type !== "0") {
+      throw new Error(`runtime archive is missing regular file ${required}`);
+    }
+  }
+  for (const required of ["agent", "bin", "node"]) {
+    if (byPath.get(required)?.type !== "5") {
+      throw new Error(`runtime archive is missing directory ${required}`);
+    }
+  }
+  for (const executable of ["bin/uai-host", "node/bin/node"]) {
+    if (byPath.get(executable)?.mode !== 0o755) {
+      throw new Error(`runtime archive executable mode is invalid: ${executable}`);
+    }
+  }
+}
+
+export function validateRuntimeDescriptor(
+  value: unknown,
+  expected: { version: string; platform: string },
+): RuntimeDescriptor {
+  const object = strictObject(
+    value,
+    ["schemaVersion", "hostVersion", "platform", "node", "requirements", "layout"],
+    "runtime descriptor",
+  );
+  if (object.schemaVersion !== 1) throw new Error("unsupported runtime descriptor schema");
+  if (object.hostVersion !== expected.version || !VERSION.test(expected.version)) {
+    throw new Error("runtime descriptor version does not match the authenticated release");
+  }
+  if (object.platform !== expected.platform) {
+    throw new Error("runtime descriptor platform does not match this host");
+  }
+  const node = strictObject(object.node, ["version", "modules"], "runtime descriptor node");
+  if (typeof node.version !== "string" || !VERSION.test(node.version)) {
+    throw new Error("runtime descriptor Node version is invalid");
+  }
+  if (typeof node.modules !== "string" || !/^\d+$/.test(node.modules)) {
+    throw new Error("runtime descriptor Node ABI is invalid");
+  }
+  const layout = strictObject(
+    object.layout,
+    ["agent", "launcher", "node"],
+    "runtime descriptor layout",
+  );
+  if (
+    layout.agent !== "agent" ||
+    layout.launcher !== "bin/uai-host" ||
+    layout.node !== "node"
+  ) {
+    throw new Error("runtime descriptor layout is invalid");
+  }
+  const requirements = strictStringObject(object.requirements, "runtime requirements");
+  validateRequirements(expected.platform, requirements);
+  return {
+    schemaVersion: 1,
+    hostVersion: expected.version,
+    platform: expected.platform,
+    node: { version: node.version, modules: node.modules },
+    requirements,
+    layout: { agent: "agent", launcher: "bin/uai-host", node: "node" },
+  };
+}
+
+function validateRequirements(platform: string, value: Readonly<Record<string, string>>): void {
+  const [os, arch] = platform.split("-");
+  if (value.os !== os || value.arch !== arch) {
+    throw new Error("runtime descriptor requirements do not match its platform");
+  }
+  const keys = Object.keys(value).sort().join("\0");
+  if (os === "darwin") {
+    if (keys !== ["arch", "minVersion", "os"].join("\0") || value.minVersion !== "13.5") {
+      throw new Error("runtime descriptor macOS requirements are invalid");
+    }
+  } else if (
+    os !== "linux" ||
+    keys !== ["arch", "libc", "minKernel", "minLibcVersion", "os"].join("\0") ||
+    value.libc !== "glibc" ||
+    value.minKernel !== "4.18" ||
+    value.minLibcVersion !== "2.29"
+  ) {
+    throw new Error("runtime descriptor Linux requirements are invalid");
+  }
+}
+
+function strictObject(
+  value: unknown,
+  expectedKeys: readonly string[],
+  label: string,
+): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const object = value as Record<string, unknown>;
+  if (Object.getPrototypeOf(object) !== Object.prototype) {
+    throw new Error(`${label} must be a plain object`);
+  }
+  if (Object.keys(object).sort().join("\0") !== [...expectedKeys].sort().join("\0")) {
+    throw new Error(`${label} fields are invalid`);
+  }
+  return object;
+}
+
+function strictStringObject(value: unknown, label: string): Readonly<Record<string, string>> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const output: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== "string") throw new Error(`${label}.${key} must be a string`);
+    output[key] = item;
+  }
+  return output;
+}
+
+function assertCanonicalGzipHeader(bytes: Buffer): void {
+  if (
+    bytes.length < 18 ||
+    bytes[0] !== 0x1f ||
+    bytes[1] !== 0x8b ||
+    bytes[2] !== 8 ||
+    bytes[3] !== 0 ||
+    bytes.readUInt32LE(4) !== 0 ||
+    bytes[8] !== 2 ||
+    bytes[9] !== 255
+  ) {
+    throw new Error("runtime archive gzip header is not canonical");
+  }
+}
+
+function validateHeaderChecksum(header: Buffer): void {
+  const expected = parseOctal(header, 148, 8, "checksum");
+  const copy = Buffer.from(header);
+  copy.fill(0x20, 148, 156);
+  const actual = copy.reduce((sum, byte) => sum + byte, 0);
+  if (actual !== expected) throw new Error("runtime archive header checksum mismatch");
+}
+
+function parseString(block: Buffer, offset: number, length: number): string {
+  const end = block.indexOf(0, offset);
+  const stop = end === -1 || end > offset + length ? offset + length : end;
+  const bytes = block.subarray(offset, stop);
+  const decoded = bytes.toString("utf8");
+  if (!Buffer.from(decoded, "utf8").equals(bytes)) {
+    throw new Error("runtime archive header contains invalid UTF-8");
+  }
+  return decoded;
+}
+
+function parseOctal(block: Buffer, offset: number, length: number, label: string): number {
+  const raw = parseString(block, offset, length).trim();
+  if (!/^[0-7]+$/.test(raw)) throw new Error(`runtime archive has invalid ${label}`);
+  const value = Number.parseInt(raw, 8);
+  if (!Number.isSafeInteger(value)) throw new Error(`runtime archive has invalid ${label}`);
+  return value;
+}
+
+function parsePax(body: Buffer): { path?: string; linkpath?: string } {
+  const values: { path?: string; linkpath?: string } = {};
+  let offset = 0;
+  while (offset < body.length) {
+    const space = body.indexOf(0x20, offset);
+    if (space === -1) throw new Error("runtime archive pax record has no length");
+    const rawLength = body.subarray(offset, space).toString("ascii");
+    if (!/^[1-9]\d*$/.test(rawLength)) throw new Error("runtime archive pax length is invalid");
+    const length = Number.parseInt(rawLength, 10);
+    if (!Number.isSafeInteger(length) || offset + length > body.length) {
+      throw new Error("runtime archive pax boundary is invalid");
+    }
+    const record = body.subarray(space + 1, offset + length);
+    if (record.at(-1) !== 0x0a) throw new Error("runtime archive pax terminator is invalid");
+    const text = record.subarray(0, -1).toString("utf8");
+    const equals = text.indexOf("=");
+    if (equals <= 0) throw new Error("runtime archive pax record is invalid");
+    const key = text.slice(0, equals);
+    const value = text.slice(equals + 1);
+    if ((key !== "path" && key !== "linkpath") || Object.hasOwn(values, key)) {
+      throw new Error(`unsupported or duplicate runtime archive pax key: ${key}`);
+    }
+    values[key] = value;
+    offset += length;
+  }
+  return values;
+}
+
+function safeMemberPath(value: string): string {
+  const normalizedValue = value.endsWith("/") ? value.slice(0, -1) : value;
+  if (
+    !normalizedValue ||
+    Buffer.byteLength(normalizedValue) > MAX_MEMBER_PATH_BYTES ||
+    normalizedValue.startsWith("/") ||
+    /[\x00-\x1f\x7f]/.test(normalizedValue) ||
+    normalizedValue
+      .split("/")
+      .some((part) => !part || part === "." || part === "..") ||
+    path.posix.normalize(normalizedValue) !== normalizedValue
+  ) {
+    throw new Error(`unsafe runtime archive member path: ${JSON.stringify(value)}`);
+  }
+  return normalizedValue;
+}
+
+function safeLinkTarget(memberPath: string, target: string): string {
+  if (
+    !target ||
+    Buffer.byteLength(target) > MAX_MEMBER_PATH_BYTES ||
+    target.startsWith("/") ||
+    /[\x00-\x1f\x7f]/.test(target)
+  ) {
+    throw new Error(`unsafe runtime archive symlink target: ${JSON.stringify(target)}`);
+  }
+  const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(memberPath), target));
+  if (resolved === ".." || resolved.startsWith("../") || resolved.startsWith("/")) {
+    throw new Error(`runtime archive symlink escapes the payload: ${memberPath}`);
+  }
+  return resolved;
+}
+
+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;
+    if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR") {
+      throw error;
+    }
+  } finally {
+    await handle?.close();
+  }
+}
+
+
+/**
+ * Frozen verbatim body of the pre-Phase-B validateInstalledRuntime path.
+ * It deliberately knows only the schema-v1 envelope and four top-level names.
+ */
+export async function validateLegacyInstalledRuntime(
+  directory: string,
+  expectedVersion: string,
+  expectedPlatform?: string,
+): Promise<RuntimeDescriptor> {
+  const root = await realpath(directory);
+  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`);
+  }
+  for (const [relative, executable] of [
+    ["agent/bin/uai-host.mjs", false],
+    ["bin/uai-host", true],
+    ["node/bin/node", true],
+    ["runtime.json", false],
+  ] as const) {
+    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}`);
+    }
+  }
+  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");
+  return validateRuntimeDescriptor(raw, {
+    version: expectedVersion,
+    platform,
+  });
+}
+
+function isInside(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}