@runuai/host 0.9.69 → 0.9.70

package/lib/env-schema.ts

@@ -0,0 +1,101 @@
+/**
+ * ADR-122 phase 1: a minimal, OWNED parser for the env-spec subset Uai
+ * reads — key names and the @required / @sensitive / @type decorators from
+ * comment lines above each declaration in a committed `.env.schema`.
+ *
+ * Deliberately dependency-free: this phase must stand alone even if the
+ * upstream tooling vanishes (the graduated-adoption ladder in ADR-122).
+ * Unknown decorators are preserved verbatim but unused; values in the
+ * schema file are IGNORED — a schema declares, it never supplies.
+ *
+ * First consumer: the post-task-up validation note. A project that
+ * declares `@required DATABASE_URL` with no value stored on this host gets
+ * one visible system note instead of a blank 500 hours later (the
+ * 2026-08-25 incident this phase exists to retire).
+ */
+
+export interface EnvSchemaEntry {
+  name: string;
+  required: boolean;
+  sensitive: boolean;
+  type?: string;
+  /** Decorators Uai does not interpret, kept for diagnostics. */
+  otherDecorators: string[];
+}
+
+const KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+const DECORATOR = /@([A-Za-z][A-Za-z0-9]*)(?:=((?:[^\s(]+)?(?:\([^)]*\))?))?/g;
+
+export function parseEnvSchema(content: string): EnvSchemaEntry[] {
+  const entries: EnvSchemaEntry[] = [];
+  let pending: {
+    required: boolean;
+    sensitive: boolean;
+    type?: string;
+    other: string[];
+  } = { required: false, sensitive: false, other: [] };
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith("#")) {
+      for (const match of line.matchAll(DECORATOR)) {
+        const name = match[1]!;
+        const value = match[2];
+        if (name === "required") pending.required = true;
+        else if (name === "sensitive") pending.sensitive = true;
+        else if (name === "type" && value) pending.type = value;
+        else pending.other.push(value ? `${name}=${value}` : name);
+      }
+      continue;
+    }
+    if (line === "") {
+      // A blank line ends a decorator block that never reached a key —
+      // env-spec decorators attach to the declaration directly below them.
+      pending = { required: false, sensitive: false, other: [] };
+      continue;
+    }
+    const key = KEY_LINE.exec(line);
+    if (key) {
+      entries.push({
+        name: key[1]!,
+        required: pending.required,
+        sensitive: pending.sensitive,
+        ...(pending.type !== undefined ? { type: pending.type } : {}),
+        otherDecorators: pending.other,
+      });
+    }
+    pending = { required: false, sensitive: false, other: [] };
+  }
+  return entries;
+}
+
+/** Required keys the provided value set does not cover. Presence is a
+ * KEY-level fact — an empty string is still a provided value; deciding
+ * emptiness policy belongs to later phases, not this one. */
+export function missingRequiredKeys(
+  entries: EnvSchemaEntry[],
+  providedKeys: ReadonlySet<string>,
+): string[] {
+  return entries
+    .filter((entry) => entry.required && !providedKeys.has(entry.name))
+    .map((entry) => entry.name);
+}
+
+/** Compose the one visible note for a task whose projects declare required
+ * keys this host has no values for. Null when everything is satisfied. */
+export function envSchemaNote(
+  perProject: Array<{ slug: string; missing: string[] }>,
+): string | null {
+  const affected = perProject.filter((project) => project.missing.length > 0);
+  if (affected.length === 0) return null;
+  const lines = affected.map(
+    (project) =>
+      `${project.slug}: ${project.missing.join(", ")}`,
+  );
+  return (
+    `This task's project${affected.length > 1 ? "s" : ""} declare required ` +
+    `env keys with no value set on this host — ` +
+    lines.join("; ") +
+    `. The app may fail until they are set on the project page; ` +
+    `Resume the task after setting them.`
+  );
+}

package/lib/machine-exec.ts

@@ -42,6 +42,59 @@ export interface MachineExecOptions {
   maxOutputBytes?: number;
 }
 
+/** POSIX single-quote escaping. The ONLY safe way to carry an arbitrary
+ * argv element through the remote login shell ssh interposes: everything
+ * between single quotes is literal, and an embedded quote becomes '\''. */
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Build the remote command for a TaskEnvironment-style request. SSH has no
+ * --workdir/--env/--user flags — cwd and env must be materialized INTO the
+ * remote command, each element quoted, and the user rides the ssh login
+ * instead (`-l`). Env values therefore appear in the machine-side process
+ * table; the machine is a single-task trust domain, and hardening to sshd
+ * SetEnv acceptlists is recorded ADR-121 follow-up work, not silently
+ * skipped.
+ */
+export function buildRemoteCommand(request: {
+  argv: readonly string[];
+  cwd?: string;
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  detached?: boolean;
+}): string {
+  const parts: string[] = [];
+  if (request.cwd) {
+    parts.push(`cd ${shellQuote(request.cwd)} &&`);
+  }
+  const env: string[] = [];
+  for (const name of request.inheritEnv ?? []) {
+    const value = process.env[name];
+    if (value !== undefined) env.push(`${name}=${value}`);
+  }
+  for (const [name, value] of Object.entries(request.env ?? {}).sort(
+    ([left], [right]) => left.localeCompare(right),
+  )) {
+    env.push(`${name}=${value}`);
+  }
+  const envPrefix =
+    env.length > 0 ? `env ${env.map(shellQuote).join(" ")} ` : "";
+  const command = request.argv.map(shellQuote).join(" ");
+  if (request.detached) {
+    // Detached durable sessions manage their own transcript IO (runner.mjs);
+    // the launch just needs the process to survive this ssh connection:
+    // setsid detaches the controlling terminal, streams are severed, and the
+    // remote shell exits immediately with the launch verdict.
+    parts.push(`${envPrefix}setsid ${command} </dev/null >/dev/null 2>&1 &`);
+    parts.push("exit 0");
+    return parts.join(" ");
+  }
+  parts.push(`exec ${envPrefix}${command}`);
+  return parts.join(" ");
+}
+
 export function machineSshArgs(
   target: MachineExecTarget,
   argv: string[],
@@ -71,6 +124,42 @@ export function machineExec(
   return runSsh(machineSshArgs(target, argv), opts);
 }
 
+/**
+ * Full ssh argv for a TaskEnvironment-style request: base transport options,
+ * the request's user as the ssh login, and the quoted remote command as the
+ * single trailing argument. Shared by captured, streaming, and detached
+ * paths so quoting can never diverge between them.
+ */
+export function machineEnvironmentSshArgs(
+  target: Omit<MachineExecTarget, "user">,
+  request: {
+    argv: readonly string[];
+    cwd?: string;
+    user?: string;
+    inheritEnv?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+  },
+  mode: "interactive" | "detached",
+): string[] {
+  return [
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "StrictHostKeyChecking=accept-new",
+    "-o",
+    "ConnectTimeout=10",
+    "-i",
+    target.keyPath,
+    "-p",
+    String(target.port ?? 22),
+    "-l",
+    request.user ?? "node",
+    target.address,
+    "--",
+    buildRemoteCommand({ ...request, detached: mode === "detached" }),
+  ];
+}
+
 function runSsh(
   args: string[],
   opts: MachineExecOptions,

package/lib/machine-keys.ts

@@ -0,0 +1,65 @@
+/**
+ * ADR-121: per-machine SSH identity. Minted host-side at provision, the
+ * public half rides the machine spec (user-data / entrypoint env), the
+ * private half lives in the task's control tree — task lifetime, deleted
+ * with the task dir, never shared between tasks. `ssh-keygen` is used
+ * rather than a JS implementation: the host already shells out for every
+ * other crypto-bearing operation, and OpenSSH's own keygen is the one
+ * implementation `ssh` is guaranteed to agree with.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface MachineKeyPair {
+  privateKeyPath: string;
+  publicKey: string;
+}
+
+export function machineKeyDir(taskControlDir: string): string {
+  return resolve(taskControlDir, "machine");
+}
+
+/**
+ * Mint (or reuse) the task's machine keypair. Reuse is deliberate: a
+ * re-provision after a crash must produce the same identity the persisted
+ * locator's machine may already authorize.
+ */
+export async function ensureMachineKeyPair(
+  taskControlDir: string,
+): Promise<MachineKeyPair> {
+  const dir = machineKeyDir(taskControlDir);
+  const privateKeyPath = resolve(dir, "id_ed25519");
+  const publicKeyPath = `${privateKeyPath}.pub`;
+  if (existsSync(privateKeyPath) && existsSync(publicKeyPath)) {
+    return {
+      privateKeyPath,
+      publicKey: readFileSync(publicKeyPath, "utf8").trim(),
+    };
+  }
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  rmSync(privateKeyPath, { force: true });
+  rmSync(publicKeyPath, { force: true });
+  await new Promise<void>((resolveKeygen, reject) => {
+    const child = spawn(
+      "ssh-keygen",
+      ["-t", "ed25519", "-N", "", "-C", "uai-machine", "-f", privateKeyPath],
+      { stdio: ["ignore", "ignore", "pipe"] },
+    );
+    let stderr = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.once("error", (error) => reject(error));
+    child.once("close", (code) => {
+      if (code === 0) resolveKeygen();
+      else reject(new Error(`ssh-keygen failed (${code}): ${stderr.trim()}`));
+    });
+  });
+  return {
+    privateKeyPath,
+    publicKey: readFileSync(publicKeyPath, "utf8").trim(),
+  };
+}

package/lib/machine-provider-aws.ts

@@ -0,0 +1,437 @@
+/**
+ * ADR-121: the `aws` MachineProvider — task machines as EC2 instances.
+ *
+ * Shell-out to the `aws` CLI with strict JSON parsing, matching every other
+ * backend integration (docker, container, ssh): no SDK dependency rides the
+ * OTA channel, and tests inject the runner.
+ *
+ * Identity model: EC2 invents instance ids, but the environment layer's
+ * locator-first invariant needs a DERIVED id. The machine id is therefore
+ * the logical `uai-machine-<taskId>`; the provider resolves it internally
+ * through the `com.uai.machine` tag on every call, and `--client-token`
+ * makes launch idempotent so a crashed provision retried cannot mint a
+ * second instance. Two live instances carrying one machine's tag is a
+ * confusing answer and maps to `unknown` — never to either instance.
+ *
+ * Absence: a SUCCESSFUL tag query with zero non-terminated matches proves
+ * absence (the filter asked AWS directly and AWS answered "none");
+ * `terminated` counts as absent — the id is unreachable and its disk is
+ * gone. A failed query proves nothing.
+ */
+
+import { spawn } from "node:child_process";
+
+import type { DockerResult } from "./docker-exec";
+import type {
+  MachineInfo,
+  MachineProvider,
+  MachineSpec,
+  MachineState,
+} from "./machine-provider";
+
+export const AWS_MACHINE_TAG = "com.uai.machine";
+
+export interface AwsMachineConfig {
+  region: string;
+  /** AMI id used when the spec's image is not already an ami-*. */
+  subnetId?: string;
+  securityGroupId?: string;
+  iamInstanceProfileArn?: string;
+  /** Override the size ladder; the default picks the smallest Graviton
+   * type satisfying both cpu and memory. */
+  instanceType?: (spec: MachineSpec) => string;
+}
+
+type Runner = (args: string[]) => Promise<DockerResult>;
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+function defaultRunner(region: string): Runner {
+  return (args) =>
+    new Promise<DockerResult>((resolve) => {
+      let stdout = "";
+      let stderr = "";
+      let settled = false;
+      const child = spawn(
+        "aws",
+        ["--region", region, "--output", "json", ...args],
+        { stdio: ["ignore", "pipe", "pipe"] },
+      );
+      const settle = (status: number | null): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ status, stdout, stderr });
+      };
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        const grace = setTimeout(() => settle(null), 2_000);
+        grace.unref?.();
+      }, DEFAULT_TIMEOUT_MS);
+      timer.unref?.();
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk: string) => (stdout += chunk));
+      child.stderr.on("data", (chunk: string) => (stderr += chunk));
+      child.once("error", () => settle(null));
+      child.once("close", (code) => settle(code));
+    });
+}
+
+export function awsMachineName(taskId: string): string {
+  return `uai-machine-${taskId.toLowerCase()}`;
+}
+
+/** Smallest Graviton type satisfying both dimensions. */
+export function defaultInstanceType(spec: MachineSpec): string {
+  const ladder: Array<[string, number, number]> = [
+    ["m7g.medium", 1, 4096],
+    ["m7g.large", 2, 8192],
+    ["m7g.xlarge", 4, 16384],
+    ["m7g.2xlarge", 8, 32768],
+    ["m7g.4xlarge", 16, 65536],
+  ];
+  for (const [type, cpus, memoryMiB] of ladder) {
+    if (spec.cpus <= cpus && spec.memoryMiB <= memoryMiB) return type;
+  }
+  return "m7g.4xlarge";
+}
+
+/** cloud-init: install the orchestrator key for node (and root for the
+ * provisioning path), creating the node user when the AMI lacks it. */
+export function awsUserData(authorizedPublicKey: string): string {
+  const script = [
+    "#!/bin/sh",
+    "set -e",
+    "id node >/dev/null 2>&1 || useradd -m -u 1000 -s /bin/bash node",
+    "for account in node root; do",
+    '  home=$(getent passwd "$account" | cut -d: -f6)',
+    '  mkdir -p "$home/.ssh"',
+    `  printf '%s\\n' '${authorizedPublicKey.replace(/'/g, "")}' > "$home/.ssh/authorized_keys"`,
+    '  chown -R "$account" "$home/.ssh"',
+    '  chmod 700 "$home/.ssh"',
+    '  chmod 600 "$home/.ssh/authorized_keys"',
+    "done",
+    "",
+  ].join("\n");
+  return Buffer.from(script, "utf8").toString("base64");
+}
+
+type LiveInstance = {
+  instanceId: string;
+  state: string;
+  privateIp: string | null;
+  taskLabel: string | null;
+};
+
+/** Strict reservations parse. Any malformed instance voids the answer. */
+function parseReservations(stdout: string): LiveInstance[] | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  const reservations = (parsed as { Reservations?: unknown }).Reservations;
+  if (!Array.isArray(reservations)) return null;
+  const instances: LiveInstance[] = [];
+  for (const reservation of reservations) {
+    const list = (reservation as { Instances?: unknown }).Instances;
+    if (!Array.isArray(list)) return null;
+    for (const instance of list) {
+      if (typeof instance !== "object" || instance === null) return null;
+      const record = instance as {
+        InstanceId?: unknown;
+        State?: { Name?: unknown };
+        PrivateIpAddress?: unknown;
+        Tags?: Array<{ Key?: unknown; Value?: unknown }>;
+      };
+      if (typeof record.InstanceId !== "string") return null;
+      const state = record.State?.Name;
+      if (typeof state !== "string") return null;
+      let taskLabel: string | null = null;
+      if (record.Tags !== undefined) {
+        if (!Array.isArray(record.Tags)) return null;
+        for (const tag of record.Tags) {
+          if (tag?.Key === AWS_MACHINE_TAG) {
+            if (typeof tag.Value !== "string") return null;
+            taskLabel = tag.Value;
+          }
+        }
+      }
+      instances.push({
+        instanceId: record.InstanceId,
+        state,
+        privateIp:
+          typeof record.PrivateIpAddress === "string"
+            ? record.PrivateIpAddress
+            : null,
+        taskLabel,
+      });
+    }
+  }
+  return instances;
+}
+
+function stateFromAws(state: string): MachineState {
+  switch (state) {
+    case "running":
+      return "running";
+    case "pending":
+      return "pending";
+    case "stopping":
+    case "stopped":
+      return "stopped";
+    case "shutting-down":
+    case "terminated":
+      return "absent";
+    default:
+      return "unknown";
+  }
+}
+
+function unknown(id: string, detail: string): MachineInfo {
+  return { id, taskLabel: null, state: "unknown", address: null, detail };
+}
+
+export function createAwsMachineProvider(
+  config: AwsMachineConfig,
+  runner: Runner = defaultRunner(config.region),
+): MachineProvider {
+  const taskIdOf = (machineId: string): string => {
+    if (!machineId.startsWith("uai-machine-")) {
+      throw new Error(`not a uai machine id: ${machineId}`);
+    }
+    return machineId.slice("uai-machine-".length);
+  };
+
+  /** Resolve the logical machine id to its live instances via the tag. */
+  async function resolveLive(
+    machineId: string,
+  ): Promise<{ instances: LiveInstance[] } | { failure: string }> {
+    const res = await runner([
+      "ec2",
+      "describe-instances",
+      "--filters",
+      `Name=tag:${AWS_MACHINE_TAG},Values=${taskIdOf(machineId)}`,
+      "Name=instance-state-name,Values=pending,running,stopping,stopped",
+    ]);
+    if (res.status !== 0) {
+      return {
+        failure: res.stderr.trim() || `describe exited ${res.status ?? "killed"}`,
+      };
+    }
+    const instances = parseReservations(res.stdout);
+    if (instances === null) {
+      return { failure: "describe answered with a confusing shape" };
+    }
+    return { instances };
+  }
+
+  async function describe(machineId: string): Promise<MachineInfo> {
+    let resolved: Awaited<ReturnType<typeof resolveLive>>;
+    try {
+      resolved = await resolveLive(machineId);
+    } catch (error) {
+      return unknown(
+        machineId,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    if ("failure" in resolved) return unknown(machineId, resolved.failure);
+    if (resolved.instances.length === 0) {
+      // A successful tag query answering "none live" IS the absence proof.
+      return { id: machineId, taskLabel: null, state: "absent", address: null };
+    }
+    if (resolved.instances.length > 1) {
+      return unknown(
+        machineId,
+        `multiple live instances carry this machine's tag`,
+      );
+    }
+    const instance = resolved.instances[0]!;
+    const state = stateFromAws(instance.state);
+    return {
+      id: machineId,
+      taskLabel: instance.taskLabel,
+      state,
+      address: state === "running" ? instance.privateIp : null,
+    };
+  }
+
+  return {
+    kind: "aws",
+
+    async launch(spec: MachineSpec): Promise<MachineInfo> {
+      const machineId = awsMachineName(spec.taskId);
+      const type = (config.instanceType ?? defaultInstanceType)(spec);
+      const args = [
+        "ec2",
+        "run-instances",
+        "--image-id",
+        spec.image,
+        "--instance-type",
+        type,
+        "--count",
+        "1",
+        // Idempotency across crashed/retried provisions: the same token can
+        // never mint a second instance.
+        "--client-token",
+        machineId,
+        "--tag-specifications",
+        `ResourceType=instance,Tags=[{Key=${AWS_MACHINE_TAG},Value=${spec.taskId}},{Key=Name,Value=${machineId}}]`,
+        ...(spec.authorizedPublicKey
+          ? ["--user-data", awsUserData(spec.authorizedPublicKey)]
+          : []),
+        ...(config.subnetId ? ["--subnet-id", config.subnetId] : []),
+        ...(config.securityGroupId
+          ? ["--security-group-ids", config.securityGroupId]
+          : []),
+        ...(config.iamInstanceProfileArn
+          ? ["--iam-instance-profile", `Arn=${config.iamInstanceProfileArn}`]
+          : []),
+      ];
+      const res = await runner(args);
+      if (res.status !== 0) {
+        throw new Error(
+          `machine launch failed for ${machineId}: ${
+            res.stderr.trim() || `exit ${res.status ?? "killed"}`
+          }`,
+        );
+      }
+      const info = await describe(machineId);
+      if (info.state === "absent" || info.state === "unknown") {
+        throw new Error(
+          `machine ${machineId} launched but could not be described (${info.state}${
+            info.detail ? `: ${info.detail}` : ""
+          })`,
+        );
+      }
+      return info;
+    },
+
+    async stop(machineId: string): Promise<void> {
+      const instance = await requireSingleLive(machineId);
+      const res = await runner([
+        "ec2",
+        "stop-instances",
+        "--instance-ids",
+        instance.instanceId,
+      ]);
+      if (res.status !== 0) {
+        throw new Error(
+          `machine stop failed for ${machineId}: ${
+            res.stderr.trim() || `exit ${res.status ?? "killed"}`
+          }`,
+        );
+      }
+    },
+
+    async start(machineId: string): Promise<MachineInfo> {
+      const instance = await requireSingleLive(machineId);
+      const res = await runner([
+        "ec2",
+        "start-instances",
+        "--instance-ids",
+        instance.instanceId,
+      ]);
+      if (res.status !== 0) {
+        throw new Error(
+          `machine start failed for ${machineId}: ${
+            res.stderr.trim() || `exit ${res.status ?? "killed"}`
+          }`,
+        );
+      }
+      return describe(machineId);
+    },
+
+    async terminate(machineId: string): Promise<void> {
+      const resolved = await resolveLive(machineId);
+      if ("failure" in resolved) {
+        throw new Error(
+          `machine ${machineId} could not be resolved for terminate: ${resolved.failure}`,
+        );
+      }
+      // Terminate EVERY live instance carrying the tag: a duplicate from a
+      // pathological double-launch must not survive its sibling's teardown.
+      for (const instance of resolved.instances) {
+        const res = await runner([
+          "ec2",
+          "terminate-instances",
+          "--instance-ids",
+          instance.instanceId,
+        ]);
+        if (res.status !== 0) {
+          throw new Error(
+            `machine terminate failed for ${machineId} (${instance.instanceId}): ${
+              res.stderr.trim() || `exit ${res.status ?? "killed"}`
+            }`,
+          );
+        }
+      }
+      // Absence is not best-effort: poll until the tag query answers "none
+      // live" (shutting-down/terminated fall out of the live filter).
+      const deadline = Date.now() + 120_000;
+      for (;;) {
+        const after = await describe(machineId);
+        if (after.state === "absent") return;
+        if (Date.now() >= deadline) {
+          throw new Error(
+            `machine ${machineId} could not be proven absent after terminate (${after.state}${
+              after.detail ? `: ${after.detail}` : ""
+            })`,
+          );
+        }
+        await new Promise<void>((resolve) => setTimeout(resolve, 5_000));
+      }
+    },
+
+    describe,
+
+    async list(): Promise<MachineInfo[]> {
+      const res = await runner([
+        "ec2",
+        "describe-instances",
+        "--filters",
+        `Name=tag-key,Values=${AWS_MACHINE_TAG}`,
+        "Name=instance-state-name,Values=pending,running,stopping,stopped",
+      ]);
+      if (res.status !== 0) {
+        throw new Error(
+          `machine listing failed: ${
+            res.stderr.trim() || `exit ${res.status ?? "killed"}`
+          }`,
+        );
+      }
+      const instances = parseReservations(res.stdout);
+      if (instances === null) {
+        throw new Error("machine inventory was unparseable");
+      }
+      return instances.map((instance) => {
+        const state = stateFromAws(instance.state);
+        return {
+          id:
+            instance.taskLabel !== null
+              ? awsMachineName(instance.taskLabel)
+              : instance.instanceId,
+          taskLabel: instance.taskLabel,
+          state,
+          address: state === "running" ? instance.privateIp : null,
+        };
+      });
+    },
+  };
+
+  async function requireSingleLive(machineId: string): Promise<LiveInstance> {
+    const resolved = await resolveLive(machineId);
+    if ("failure" in resolved) {
+      throw new Error(`machine ${machineId} could not be resolved: ${resolved.failure}`);
+    }
+    if (resolved.instances.length !== 1) {
+      throw new Error(
+        `machine ${machineId} resolution expected one live instance, found ${resolved.instances.length}`,
+      );
+    }
+    return resolved.instances[0]!;
+  }
+}