@ornncompute/cli 0.2.24 → 1.0.25

package/src/vm-commands.mjs

@@ -0,0 +1,4273 @@
+import { spawn as spawnProcessDefault } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isIP } from "node:net";
+import { isRecoverableWaitFailure } from "./interaction-runtime.mjs";
+import { resolvedMountPath } from "./mount-commands.mjs";
+import {
+  isReferenceMiss,
+  listActiveDirectReservations,
+  listOwnedActiveMachines,
+  reservationChoiceLabel as reservationLabel,
+  resolveMachineReference,
+} from "./machine-reference.mjs";
+
+const CANONICAL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const ACTIVE_RESERVATION = "active";
+const TERMINAL_MACHINE_STATES = new Set([
+  "deleted",
+  "destroyed",
+  "failed",
+  "rejected",
+  "revoked",
+  "terminated",
+  "torn_down",
+]);
+const READY_MACHINE_STATES = new Set(["active", "online", "provisioned", "ready", "running"]);
+
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function text(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function resourceId(value) {
+  const item = record(value);
+  return text(item.id) ?? text(item.reservation_id) ?? text(item.reservationId);
+}
+
+function machineId(value) {
+  const machine = record(value);
+  return (
+    text(machine.id) ??
+    text(machine.machine_id) ??
+    text(machine.instance_id) ??
+    text(machine.node_id)
+  );
+}
+
+function machineState(value) {
+  const machine = record(value);
+  return (
+    text(machine.state) ??
+    text(machine.status) ??
+    text(machine.actual_state) ??
+    "unknown"
+  ).toLowerCase();
+}
+
+function machineAccessMode(value) {
+  const node = record(value);
+  const mode =
+    text(node.access_mode) ??
+    (["bare-metal", "virtual-machine"].includes(node.status) ? node.status : null);
+  return mode === "virtual-machine" ? "vm" : mode;
+}
+
+function reservationAccessMode(value) {
+  const reservation = record(value);
+  const mode =
+    (text(reservation.access_mode) ?? text(reservation.accessMode))?.toLowerCase() ?? null;
+  return mode === "virtual-machine" ? "vm" : mode;
+}
+
+function isDirectReservation(value) {
+  const mode = reservationAccessMode(value);
+  return !mode || mode === "vm" || mode === "bare-metal";
+}
+
+function machineIsReady(value) {
+  const machine = record(value);
+  if (machine.health_readiness?.ready === false) return false;
+  return (
+    READY_MACHINE_STATES.has(machineState(machine)) ||
+    (["bare-metal", "virtual-machine"].includes(machineState(machine)) &&
+      machine.health_readiness?.ready === true)
+  );
+}
+
+function machineLifecycle(value) {
+  const state = machineState(value);
+  if (TERMINAL_MACHINE_STATES.has(state)) return { class: "failed", phase: state };
+  if (machineIsReady(value)) return { class: "ready", phase: state };
+  return { class: "working", phase: state };
+}
+
+export function machineReachability(value) {
+  const machine = record(value);
+  if (text(machine.customer_lifecycle_state)?.toLowerCase() === "failed") {
+    return { class: "failed", phase: "operation_failed" };
+  }
+  if (TERMINAL_MACHINE_STATES.has(machineState(machine))) {
+    return { class: "failed", phase: "machine_terminal" };
+  }
+  if (!machineIsReady(machine)) {
+    return { class: "working", phase: "machine_not_ready" };
+  }
+  if (!sshInvocation(machine)) return { class: "working", phase: "ssh_pending" };
+  const fingerprints = machine.authorized_key_fingerprints;
+  if (Array.isArray(fingerprints) && fingerprints.length === 0) {
+    return { class: "working", phase: "key_delivery_pending" };
+  }
+  return { class: "ready", phase: "ssh_ready" };
+}
+
+function sshText(value) {
+  if (value == null || value === "") return null;
+  if (typeof value !== "string" || /[\s\u0000-\u001f\u007f]/.test(value)) {
+    throw new Error("SSH connection details contain invalid whitespace or control characters.");
+  }
+  return value;
+}
+
+function safeSshHost(host) {
+  const literal = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  if (literal.includes(":")) {
+    return /^[A-Za-z0-9:._%-]+$/.test(literal) && isIP(literal) === 6;
+  }
+  return /^[A-Za-z0-9][A-Za-z0-9.-]*$/.test(host);
+}
+
+function machineHostname(value) {
+  return text(record(value).hostname) ?? "";
+}
+
+function machineUsername(value) {
+  const machine = record(value);
+  const endpoint = sshText(machine.ssh_endpoint);
+  const at = endpoint?.indexOf("@") ?? -1;
+  return at > 0
+    ? endpoint.slice(0, at)
+    : (sshText(machine.linux_username) ??
+        sshText(machine.tenant_username) ??
+        sshText(machine.username));
+}
+
+function machineHost(value) {
+  const machine = record(value);
+  const endpoint = sshText(machine.ssh_endpoint);
+  if (endpoint) {
+    const at = endpoint.indexOf("@");
+    return at >= 0 ? endpoint.slice(at + 1) : endpoint;
+  }
+  return (
+    sshText(machine.ssh_host) ??
+    sshText(machine.public_ip) ??
+    sshText(machine.external_ip) ??
+    sshText(machine.ip_address) ??
+    sshText(machine.ip) ??
+    sshText(machine.access_host) ??
+    (machineIsReady(machine) ? sshText(machine.hostname) : null)
+  );
+}
+
+function machinePort(value) {
+  const raw = record(value).ssh_port ?? record(value).port ?? 22;
+  const port =
+    typeof raw === "number" || (typeof raw === "string" && /^\d+$/.test(raw)) ? Number(raw) : NaN;
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error("The gateway returned an invalid SSH port.");
+  }
+  return port;
+}
+
+function shellQuote(value) {
+  const raw = String(value);
+  return /^[A-Za-z0-9_./:@%+=,-]+$/.test(raw)
+    ? raw
+    : `\u0027${raw.replace(/\u0027/g, "\u0027\\\u0027\u0027")}\u0027`;
+}
+
+function sshInvocation(machine, input = {}) {
+  const host = machineHost(machine);
+  if (host) {
+    const user = sshText(input.user) ?? machineUsername(machine) ?? "root";
+    if (!safeSshHost(host) || !/^[A-Za-z_][A-Za-z0-9_.-]*[$]?$/.test(user)) {
+      throw new Error("SSH host or login name is invalid.");
+    }
+    if (input.identityFile && /[\u0000-\u001f\u007f]/.test(input.identityFile)) {
+      throw new Error("SSH identity file contains control characters.");
+    }
+    const args = [];
+    if (text(input.identityFile)) args.push("-i", expandPath(input.identityFile));
+    const port = machinePort(machine);
+    if (port !== 22) args.push("-p", String(port));
+    args.push("--", `${user}@${host}`);
+    return { command: "ssh", args };
+  }
+  const raw = text(record(machine).ssh_command) ?? text(record(machine).iap_ssh_command);
+  return raw ? { raw } : null;
+}
+
+function commandText(invocation) {
+  return invocation.raw ?? [invocation.command, ...invocation.args].map(shellQuote).join(" ");
+}
+
+function expandPath(path) {
+  const raw = String(path);
+  return raw === "~" ? homedir() : raw.startsWith("~/") ? `${homedir()}/${raw.slice(2)}` : raw;
+}
+
+function keysFromPayload(payload) {
+  if (Array.isArray(payload)) return payload.map(record);
+  const data = record(payload);
+  const keys = Array.isArray(data.ssh_keys)
+    ? data.ssh_keys
+    : Array.isArray(data.keys)
+      ? data.keys
+      : null;
+  if (!keys) throw new Error("Ornn returned invalid SSH-key data.");
+  return keys.map(record);
+}
+
+function machinesFromPayload(payload) {
+  if (Array.isArray(payload)) return payload.map(record);
+  const machines = record(payload).nodes ?? record(payload).machines;
+  if (!Array.isArray(machines)) throw new Error("Ornn returned invalid machine data.");
+  return machines.map(record);
+}
+
+function activeKeys(keys) {
+  return keys.filter(
+    (key) => (text(key.status) ?? "active").toLowerCase() === "active" && !key.revoked_at
+  );
+}
+
+function activeMachines(machines) {
+  return machines.filter((machine) => !TERMINAL_MACHINE_STATES.has(machineState(machine)));
+}
+
+function projectKey(value) {
+  const key = record(value);
+  return {
+    id: resourceId(key),
+    label: text(key.label),
+    fingerprint: text(key.fingerprint) ?? fingerprint(text(key.public_key) ?? ""),
+    status: text(key.status) ?? "active",
+  };
+}
+
+function projectMachine(value) {
+  const machine = record(value);
+  const reachability = machineReachability(machine);
+  const lifecycleIntent = record(machine.customer_lifecycle_intent);
+  return {
+    id: machineId(machine),
+    hostname: machineHostname(machine) || null,
+    reservation_id: text(machine.reservation_id) ?? text(machine.commerce_reservation_id),
+    access_mode: machineAccessMode(machine),
+    network_mode: text(machine.network_mode),
+    lifecycle: machineLifecycle(machine),
+    operation: {
+      state: text(machine.customer_lifecycle_state),
+      intent: Object.keys(lifecycleIntent).length > 0 ? lifecycleIntent : null,
+      error: text(machine.customer_lifecycle_error),
+    },
+    reachability,
+    ssh: {
+      host: reachability.class === "ready" ? machineHost(machine) : null,
+      port: machinePort(machine),
+      user: machineUsername(machine),
+    },
+  };
+}
+
+function failedOperationRecoveryCommand(value, interaction) {
+  const machine = record(value);
+  if (text(machine.customer_lifecycle_state)?.toLowerCase() !== "failed") return null;
+  const intent = record(machine.customer_lifecycle_intent);
+  const operation = text(intent.operation)?.toLowerCase();
+  if (operation === "launch") {
+    const reservationId = text(intent.reservation_id) ?? text(machine.reservation_id);
+    return reservationId
+      ? `ornn launch ${shellQuote(reservationId)} --guided`
+      : "ornn launch --guided";
+  }
+  const requestId = shellQuote(interaction.idempotencyKey());
+  if (operation === "switch") {
+    const reservationId = text(intent.reservation_id) ?? text(machine.reservation_id);
+    const rawAccessMode = text(intent.target_access_mode)?.toLowerCase();
+    const accessMode = rawAccessMode === "virtual-machine" ? "vm" : rawAccessMode;
+    const rawSourceMode = text(intent.source_access_mode)?.toLowerCase();
+    const sourceMode = rawSourceMode === "virtual-machine" ? "vm" : rawSourceMode;
+    const networkMode = text(intent.target_network_mode)?.toLowerCase();
+    if (!reservationId || !["vm", "bare-metal"].includes(accessMode)) return null;
+    if (!["public", "private"].includes(networkMode)) return null;
+    return [
+      "ornn machines switch",
+      shellQuote(reservationId),
+      `--mode ${accessMode}`,
+      `--network ${networkMode}`,
+      accessMode !== sourceMode ? "--erase-local-data" : null,
+      "--yes",
+      `--idempotency-key ${requestId}`,
+    ]
+      .filter(Boolean)
+      .join(" ");
+  }
+  if (operation === "maintenance") {
+    const command = text(intent.mode) === "hard_reset" ? "reset" : "reboot";
+    const id = text(intent.instance_id) ?? machineId(machine);
+    if (!id) return null;
+    return [
+      `ornn machines ${command}`,
+      shellQuote(id),
+      command === "reset" ? "--erase-local-data" : null,
+      "--yes",
+      `--idempotency-key ${requestId}`,
+    ]
+      .filter(Boolean)
+      .join(" ");
+  }
+  return null;
+}
+
+function fingerprint(publicKey) {
+  const parts = String(publicKey).trim().split(/\s+/);
+  if (parts.length < 2) return null;
+  try {
+    return `SHA256:${createHash("sha256").update(Buffer.from(parts[1], "base64")).digest("base64").replace(/=/g, "")}`;
+  } catch {
+    return null;
+  }
+}
+
+function isPublicKey(value) {
+  return /^(?:ssh-(?:ed25519|rsa|dss)|ecdsa-sha2-\S+|sk-(?:ssh-ed25519|ecdsa-sha2-\S+)@\S+)\s+[A-Za-z0-9+/=]+(?:\s|$)/i.test(
+    String(value).trim()
+  );
+}
+
+async function publicKeyFromValue(value) {
+  const raw = text(value);
+  if (!raw) throw new Error("SSH public key is required.");
+  if (/PRIVATE KEY/.test(raw)) {
+    throw new Error(
+      "Refusing to upload private SSH-key material. Pass the matching public key file."
+    );
+  }
+  if (isPublicKey(raw)) return raw;
+  const path = expandPath(raw);
+  let contents;
+  try {
+    contents = (await readFile(path, "utf8")).trim();
+  } catch {
+    throw new Error("Could not read the selected SSH public-key file.");
+  }
+  if (isPublicKey(contents)) return contents;
+  if (!path.endsWith(".pub")) {
+    try {
+      const sibling = (await readFile(`${path}.pub`, "utf8")).trim();
+      if (isPublicKey(sibling)) return sibling;
+    } catch {
+      // The public-key validation below supplies the customer-facing result.
+    }
+  }
+  if (/PRIVATE KEY/.test(contents)) {
+    throw new Error(
+      "Refusing to upload private SSH-key material. Pass the matching public key file."
+    );
+  }
+  throw new Error("File does not contain a supported SSH public key.");
+}
+
+function requireCanonical(interaction, value, field, label) {
+  const ref = text(value);
+  if (!ref || !CANONICAL_ID.test(ref)) {
+    interaction.usage(`${label} must be a canonical identifier.`, {
+      code: "invalid_reference",
+      field,
+    });
+  }
+  return ref;
+}
+
+function positional(input, expected, usage, interaction) {
+  const values = Array.isArray(input.$positionals) ? input.$positionals : [];
+  if (values.length !== expected) interaction.usage(`Usage: ${usage}`);
+  return values;
+}
+
+function machineMutationPreflight(input, interaction, { requireYes = true } = {}) {
+  if (!interaction.machine) return;
+  if (!text(input.idempotencyKey)) {
+    interaction.usage("--idempotency-key is required for automation.", {
+      code: "idempotency_key_required",
+      field: "idempotencyKey",
+    });
+  }
+  if (requireYes && input.yes !== true) {
+    interaction.usage("--yes is required for automation after reviewing the exact intent.", {
+      code: "consent_required",
+      field: "yes",
+    });
+  }
+}
+
+async function selectedOrganization(context, input, interaction) {
+  const session = context.cli?.session;
+  if (!session) throw new Error("The current organization session is unavailable.");
+  let result = record(await session("context", { organization: input.organization }));
+  let data = record(result.data);
+  let selected = record(data.selected_organization);
+  if (!text(selected.id) && interaction.eligibleHuman) {
+    const choices = (Array.isArray(data.organizations) ? data.organizations : [])
+      .map(record)
+      .filter(
+        (organization) =>
+          organization.approved === true && text(organization.id) && text(organization.name)
+      )
+      .map((organization) => ({ label: text(organization.name), value: text(organization.id) }));
+    if (choices.length > 1) {
+      const answer = await interaction.ask({ label: "Organization", choices });
+      if (!answer)
+        interaction.usage("Choose an approved organization before launch.", {
+          code: "organization_required",
+        });
+      result = record(await session("context", { organization: answer }));
+      data = record(result.data);
+      selected = record(data.selected_organization);
+    }
+  }
+  const id = text(selected.id);
+  const name = text(selected.name);
+  if (!id || !name || selected.approved !== true) {
+    interaction.usage("Select one approved organization before launch.", {
+      code: "organization_required",
+      field: "organization",
+    });
+  }
+  return { id, name };
+}
+
+function assertActiveReservation(value, expectedRef, interaction, expectedMode = null) {
+  const reservation = record(value);
+  const ref = resourceId(reservation);
+  if (!ref || ref !== expectedRef) {
+    interaction.error("The gateway returned an unrelated capacity reservation.", {
+      code: "reservation_correlation_changed",
+    });
+  }
+  if ((text(reservation.status) ?? "").toLowerCase() !== ACTIVE_RESERVATION) {
+    interaction.error("The selected capacity reservation is no longer active and cannot launch.", {
+      code: "reservation_not_active",
+      exitCode: 1,
+    });
+  }
+  if (expectedMode && reservationAccessMode(reservation) !== expectedMode) {
+    interaction.error(
+      `The selected capacity reservation is for ${reservationAccessMode(reservation) ?? "another access mode"}, not ${expectedMode}.`,
+      {
+        code: "reservation_access_mode_mismatch",
+        exitCode: 2,
+      }
+    );
+  }
+  return reservation;
+}
+
+async function resolveReservation(context, input, interaction, expectedMode = null) {
+  const positionals = Array.isArray(input.$positionals) ? input.$positionals : [];
+  if (positionals.length > 1 || (positionals.length === 1 && input.reservation)) {
+    interaction.usage(
+      "Use one capacity-reservation target in either the positional argument or --reservation.",
+      {
+        code: "target_conflict",
+        field: "reservation",
+      }
+    );
+  }
+  const supplied = text(input.reservation) ?? text(positionals[0]);
+  if (supplied) {
+    const ref = requireCanonical(interaction, supplied, "reservation", "Capacity reservation");
+    return assertActiveReservation(
+      await context.fetch(`/v1/workflows/commerce/reservations/${encodeURIComponent(ref)}`),
+      ref,
+      interaction,
+      expectedMode
+    );
+  }
+  if (!interaction.eligibleHuman || interaction.machine) {
+    interaction.usage("A canonical capacity-reservation target is required for automation.", {
+      code: "missing_input",
+      field: "reservation",
+    });
+  }
+  const payload = await context.fetch("/v1/workflows/commerce/reservations?status=active&limit=50");
+  const requestedMode = expectedMode ?? text(input.mode)?.toLowerCase() ?? null;
+  const candidates = (Array.isArray(payload) ? payload : (record(payload).reservations ?? []))
+    .map(record)
+    .filter(
+      (reservation) =>
+        (text(reservation.status) ?? "").toLowerCase() === ACTIVE_RESERVATION &&
+        resourceId(reservation) &&
+        (!requestedMode || reservationAccessMode(reservation) === requestedMode)
+    );
+  if (!candidates.length) {
+    interaction.error("No active capacity reservation is eligible for launch.", {
+      code: "no_active_reservation",
+    });
+  }
+  let ref = resourceId(candidates[0]);
+  if (candidates.length > 1) {
+    ref = await interaction.ask({
+      label: "Capacity reservation",
+      choices: candidates.map((reservation) => ({
+        label: reservationLabel(reservation),
+        value: resourceId(reservation),
+      })),
+    });
+  }
+  if (!ref)
+    interaction.usage("Choose one active capacity reservation before launch.", {
+      code: "missing_input",
+    });
+  return assertActiveReservation(
+    await context.fetch(`/v1/workflows/commerce/reservations/${encodeURIComponent(ref)}`),
+    ref,
+    interaction,
+    expectedMode
+  );
+}
+
+async function fetchOrganizationKeys(context) {
+  return activeKeys(
+    keysFromPayload(await context.fetch("/v1/workflows/compute/nodes/organizations/me/ssh-keys"))
+  );
+}
+
+export function keyInputShapePreflight(input, interaction) {
+  const selectors = [input.key, input.keyId, input.publicKey, input.publicKeyFile].filter((value) =>
+    text(value)
+  );
+  if (selectors.length > 1) {
+    interaction.usage(
+      "Select one SSH key with --key, --key-id, --public-key, or --public-key-file.",
+      {
+        code: "key_selector_conflict",
+        field: "key",
+      }
+    );
+  }
+  if (text(input.label) && !text(input.publicKey) && !text(input.publicKeyFile)) {
+    interaction.usage("--label is only valid when adding a new public key.", {
+      code: "key_label_without_new_key",
+      field: "label",
+    });
+  }
+  const reference = text(input.keyId) ?? text(input.key);
+  if (reference && interaction.machine && !CANONICAL_ID.test(reference)) {
+    interaction.usage("Automation must select a canonical SSH-key identifier.", {
+      code: "invalid_reference",
+      field: "key",
+    });
+  }
+}
+
+export async function keyPlanFromInput(context, input, interaction) {
+  keyInputShapePreflight(input, interaction);
+  const keys = await fetchOrganizationKeys(context);
+  const reference = text(input.keyId) ?? text(input.key);
+  if (reference) {
+    const matches = keys.filter(
+      (key) =>
+        resourceId(key) === reference || (!interaction.machine && text(key.label) === reference)
+    );
+    if (matches.length !== 1) {
+      interaction.error(
+        matches.length
+          ? `More than one SSH key has the exact label ${reference}.`
+          : `SSH key not found: ${reference}.`,
+        { code: matches.length ? "ssh_key_ambiguous" : "ssh_key_not_found" }
+      );
+    }
+    return { kind: "existing", key: matches[0] };
+  }
+
+  let publicKeyInput = text(input.publicKey) ?? text(input.publicKeyFile);
+  if (!publicKeyInput && interaction.eligibleHuman) {
+    if (keys.length === 1) return { kind: "existing", key: keys[0] };
+    if (keys.length > 1) {
+      const selected = await interaction.ask({
+        label: "SSH key",
+        choices: keys.map((key) => ({
+          label: `${text(key.label) ?? "SSH key"} (${text(key.fingerprint) ?? resourceId(key)})`,
+          value: resourceId(key),
+        })),
+      });
+      const key = keys.find((candidate) => resourceId(candidate) === selected);
+      if (key) return { kind: "existing", key };
+    }
+    publicKeyInput = await interaction.ask({ label: "SSH public key file or value" });
+  }
+  if (!publicKeyInput) {
+    interaction.usage("Select or add an SSH key before launch.", {
+      code: "ssh_key_required",
+      field: "key",
+    });
+  }
+  const publicKey = await publicKeyFromValue(publicKeyInput);
+  const existing = keys.find((key) => text(key.public_key) === publicKey);
+  if (existing) {
+    const requestedLabel = text(input.label);
+    if (requestedLabel && text(existing.label) !== requestedLabel) {
+      interaction.usage(
+        "This public key already exists under a different label; select the existing key instead.",
+        {
+          code: "ssh_key_label_conflict",
+          field: "label",
+        }
+      );
+    }
+    return { kind: "existing", key: existing };
+  }
+  let label = text(input.label);
+  if (!label && interaction.eligibleHuman)
+    label = await interaction.ask({ label: "SSH key label" });
+  if (!label) {
+    interaction.usage("--label is required when adding a new SSH key.", {
+      code: "missing_input",
+      field: "label",
+    });
+  }
+  return {
+    kind: "create",
+    key: {
+      id: null,
+      label,
+      fingerprint: fingerprint(publicKey),
+      public_key: publicKey,
+      status: "active",
+    },
+  };
+}
+
+export async function materializeKey(context, plan, interaction, idempotencyKey) {
+  const keys = await fetchOrganizationKeys(context);
+  if (plan.kind === "existing") {
+    const ref = resourceId(plan.key);
+    const current = keys.find((key) => resourceId(key) === ref);
+    if (!current) {
+      interaction.error("The selected SSH key changed before launch.", {
+        code: "ssh_key_changed",
+      });
+    }
+    return current;
+  }
+  const publicKey = text(plan.key.public_key);
+  const replay = keys.find((key) => text(key.public_key) === publicKey);
+  if (replay) return replay;
+  const created = record(
+    await context.fetch("/v1/workflows/compute/nodes/organizations/me/ssh-keys", {
+      method: "POST",
+      headers: { "Idempotency-Key": idempotencyKey },
+      body: { label: text(plan.key.label), public_key: publicKey },
+    })
+  );
+  if (!resourceId(created) || text(created.public_key) !== publicKey) {
+    interaction.error("The saved SSH key did not match the reviewed public key.", {
+      code: "ssh_key_correlation_changed",
+    });
+  }
+  return created;
+}
+
+async function fetchAssignedKeys(context, reservationId) {
+  return activeKeys(
+    keysFromPayload(
+      await context.fetch(
+        `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/ssh-keys`
+      )
+    )
+  );
+}
+
+async function ensureAssignment(context, reservationId, key, idempotencyKey, interaction) {
+  const keyId = resourceId(key);
+  const assigned = await fetchAssignedKeys(context, reservationId);
+  const existing = assigned.find((candidate) => resourceId(candidate) === keyId);
+  if (existing) return { created: false, key: existing };
+  const created = record(
+    await context.fetch(
+      `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/ssh-keys`,
+      {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey },
+        body: { ssh_key_id: keyId },
+      }
+    )
+  );
+  if (resourceId(created) !== keyId) {
+    interaction.error("The SSH-key assignment did not match the reviewed key.", {
+      code: "ssh_key_assignment_changed",
+    });
+  }
+  return { created: true, key: created };
+}
+
+async function fetchMachines(context, reservationId) {
+  return activeMachines(
+    machinesFromPayload(
+      await context.fetch(
+        `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/machines`
+      )
+    )
+  );
+}
+
+function keyDeliveryForMachine(key, machine) {
+  const keyId = resourceId(key);
+  const metadata = Array.isArray(machine.authorized_key_metadata)
+    ? machine.authorized_key_metadata
+        .map(record)
+        .find(
+          (item) =>
+            text(item.ssh_key_id) === keyId || text(item.fingerprint) === text(key.fingerprint)
+        )
+    : null;
+  const fingerprints = Array.isArray(machine.authorized_key_fingerprints)
+    ? machine.authorized_key_fingerprints
+    : [];
+  const installed =
+    text(key.fingerprint) && fingerprints.includes(text(key.fingerprint)) && machine.keys_pushed_at;
+  return {
+    machine_id: machineId(machine),
+    hostname: machineHostname(machine) || null,
+    machine_state: machineState(machine),
+    status: text(metadata?.status) ?? (installed ? "installed" : "associated"),
+    queued_at: text(metadata?.queued_at),
+    pushed_at: text(metadata?.pushed_at) ?? (installed ? text(machine.keys_pushed_at) : null),
+    failed_at: text(metadata?.failed_at),
+    failure_reason: text(metadata?.failure_reason),
+    request_id: text(metadata?.request_id),
+  };
+}
+
+function assignmentStatus(reservationId, keys, machines) {
+  return {
+    reservation_id: reservationId,
+    machine_count: machines.length,
+    keys: keys.map((key) => ({
+      ...projectKey(key),
+      machines: machines.map((machine) => keyDeliveryForMachine(key, machine)),
+    })),
+  };
+}
+
+function isSshReady(machine, key) {
+  if (machineReachability(machine).class !== "ready") return false;
+  const fingerprints = Array.isArray(machine.authorized_key_fingerprints)
+    ? machine.authorized_key_fingerprints
+    : null;
+  const keyFingerprint = text(key?.fingerprint);
+  return !fingerprints || !keyFingerprint || fingerprints.includes(keyFingerprint);
+}
+
+function launchInputPreflight(input, interaction) {
+  const positionals = Array.isArray(input.$positionals) ? input.$positionals : [];
+  if (positionals.length > 1 || (positionals.length === 1 && text(input.reservation))) {
+    interaction.usage(
+      "Use one capacity-reservation target in either the positional argument or --reservation.",
+      {
+        code: "target_conflict",
+        field: "reservation",
+      }
+    );
+  }
+  const selectors = [input.key, input.keyId, input.publicKey, input.publicKeyFile].filter((value) =>
+    text(value)
+  );
+  if (selectors.length > 1) {
+    interaction.usage(
+      "Select one SSH key with --key, --key-id, --public-key, or --public-key-file.",
+      {
+        code: "key_selector_conflict",
+        field: "key",
+      }
+    );
+  }
+  if (input.wait && input.noWait) {
+    interaction.usage("--wait and --no-wait cannot be combined.", {
+      code: "wait_conflict",
+      field: "wait",
+    });
+  }
+  if (input.noWait && text(input.timeout)) {
+    interaction.usage("--timeout cannot be combined with --no-wait.", {
+      code: "wait_conflict",
+      field: "timeout",
+    });
+  }
+  if (text(input.timeout)) timeoutMilliseconds(input.timeout, interaction);
+
+  const target = text(input.reservation) ?? text(positionals[0]);
+  if (interaction.eligibleHuman && !interaction.machine) return;
+  requireCanonical(interaction, target, "reservation", "Capacity reservation");
+  requireCanonical(interaction, input.organization, "organization", "Organization");
+  const keyRef = text(input.keyId) ?? text(input.key);
+  const suppliedPublicKey = text(input.publicKey) ?? text(input.publicKeyFile);
+  if (!keyRef && !suppliedPublicKey) {
+    interaction.usage("--key or an explicit public key is required for automation.", {
+      code: "ssh_key_required",
+      field: "key",
+    });
+  }
+  if (keyRef) requireCanonical(interaction, keyRef, "key", "SSH key");
+  if (suppliedPublicKey && !text(input.label)) {
+    interaction.usage("--label is required when adding a new SSH key.", {
+      code: "missing_input",
+      field: "label",
+    });
+  }
+  if (input.yes !== true) {
+    interaction.usage("--yes is required for automation after reviewing the launch intent.", {
+      code: "consent_required",
+      field: "yes",
+    });
+  }
+  if (!text(input.idempotencyKey)) {
+    interaction.usage("--idempotency-key is required for automation.", {
+      code: "idempotency_key_required",
+      field: "idempotencyKey",
+    });
+  }
+  if (input.wait && !text(input.timeout)) {
+    interaction.usage("--wait requires a bounded --timeout for automation.", {
+      code: "timeout_required",
+      field: "timeout",
+    });
+  }
+  if (!input.wait && text(input.timeout)) {
+    interaction.usage("--timeout requires --wait for automation.", {
+      code: "wait_required",
+      field: "wait",
+    });
+  }
+}
+
+function timeoutMilliseconds(value, interaction) {
+  if (!text(value)) return 600_000;
+  const match = /^([0-9]+(?:\.[0-9]+)?)([smh]?)$/i.exec(text(value));
+  if (!match)
+    interaction.usage("--timeout must be a positive duration such as 60s, 10m, or 1h.", {
+      field: "timeout",
+    });
+  const multiplier = { "": 1_000, s: 1_000, m: 60_000, h: 3_600_000 }[match[2].toLowerCase()];
+  const result = Number(match[1]) * multiplier;
+  if (!Number.isFinite(result) || result <= 0)
+    interaction.usage("--timeout must be a positive duration.", { field: "timeout" });
+  return result;
+}
+
+async function normalizePublicKeyInput(input) {
+  const source = text(input.publicKey) ?? text(input.publicKeyFile);
+  if (!source) return input;
+  return {
+    ...input,
+    publicKey: await publicKeyFromValue(source),
+    publicKeyFile: undefined,
+  };
+}
+function isPreassignedUnlaunchedCapacity(machines, assignedKeys, reviewedKey) {
+  if (machines.length !== 1) return false;
+  const reviewedKeyId = resourceId(reviewedKey);
+  if (assignedKeys.some((key) => resourceId(key) !== reviewedKeyId)) return false;
+  const machine = machines[0];
+  const fingerprints = Array.isArray(machine.authorized_key_fingerprints)
+    ? machine.authorized_key_fingerprints.filter(text)
+    : [];
+  const delivery = Array.isArray(machine.authorized_key_metadata)
+    ? machine.authorized_key_metadata
+    : [];
+  return (
+    machineAccessMode(machine) === "bare-metal" &&
+    fingerprints.length === 0 &&
+    !text(machine.keys_pushed_at) &&
+    delivery.length === 0
+  );
+}
+
+function launchOwnerSnapshot(machines) {
+  if (machines.length !== 1) return null;
+  return [machineId(machines[0]), machineUsername(machines[0])];
+}
+
+function withAuthoritativeUsername(input, _machines, interaction) {
+  const requested = text(input.username);
+  if (requested && requested !== "tenant") {
+    interaction.usage("Linux login is always tenant; --username cannot request another name.", {
+      code: "launch_username_unsupported",
+    });
+  }
+  return { ...input, username: "tenant" };
+}
+
+function validatedMachine(machines, key, input, interaction, expectedMode = "vm") {
+  if (!machines.length) return null;
+  if (machines.length !== 1) {
+    interaction.error(
+      "The capacity reservation already has multiple active machines; launch cannot choose one.",
+      {
+        code: "machine_ambiguous",
+      }
+    );
+  }
+  const machine = machines[0];
+  if (machineAccessMode(machine) !== expectedMode) {
+    interaction.error(
+      "The existing machine has a different access mode than the reviewed launch.",
+      {
+        code: "launch_input_changed",
+      }
+    );
+  }
+  const username = text(input.username);
+  if (username && username !== "tenant") {
+    interaction.usage("Linux login is always tenant; --username cannot request another name.", {
+      code: "launch_username_unsupported",
+    });
+  }
+  const fingerprintValue = text(key.fingerprint);
+  const assigned = Array.isArray(machine.authorized_key_fingerprints)
+    ? machine.authorized_key_fingerprints
+    : [];
+  if (fingerprintValue && assigned.length && !assigned.includes(fingerprintValue)) {
+    interaction.error(
+      "The existing machine has a different SSH-key intent than the reviewed launch.",
+      {
+        code: "launch_input_changed",
+      }
+    );
+  }
+  return machine;
+}
+
+function machineReplayState(machines, key, input, interaction, expectedMode = "vm") {
+  const existing = validatedMachine(machines, key, input, interaction, expectedMode);
+  // A projected machine is not proof that its owner packet was durably
+  // completed. Re-submit the stable request while provisioning so the owner
+  // can reconstruct a packet lost with an orchestrator instance restart.
+  return {
+    existing,
+    machine: existing && machineReachability(existing).class !== "working" ? existing : null,
+    replayed: Boolean(existing),
+  };
+}
+
+function launchData(reservationId, machine, key, waitPolicy, replayed) {
+  const invocation = sshInvocation(machine);
+  return {
+    mode: "vm",
+    replayed,
+    capacity_reservation: { id: reservationId, status: ACTIVE_RESERVATION },
+    machine: projectMachine(machine),
+    ssh_key: projectKey(key),
+    wait: waitPolicy,
+    ssh_command: invocation ? commandText(invocation) : null,
+    created_resources: { private_network: false, volume: false },
+  };
+}
+
+function acceptedWaitFailure(interaction, error, { data, label, phase, resume, retryCommand }) {
+  const status = Number(error?.status);
+  const authorization = status === 401 || status === 403;
+  if (!isRecoverableWaitFailure(error)) throw error;
+  const authentication = status === 401;
+  const command = authorization ? "ornn login" : retryCommand;
+  return interaction.result({
+    action: {
+      command,
+      description: authorization
+        ? "Restore an authorized session, then resume the exact accepted resource."
+        : "Retry the exact accepted resource wait.",
+      type: "command",
+    },
+    data: { ...data, remote_work_cancelled: false },
+    errors: [
+      {
+        code: authentication
+          ? "authentication_required"
+          : authorization
+            ? "authorization_denied"
+            : "service_unavailable",
+        message: authorization
+          ? `The session could not continue waiting for ${label}; accepted remote work continues.`
+          : `The local wait for ${label} lost contact with the service; accepted remote work continues.`,
+        retryable: status !== 403,
+        resource_ref: resume.ref,
+      },
+    ],
+    exitCode: authorization ? 5 : 6,
+    outcome: { class: "working", phase },
+    resume,
+    presentation: {
+      lines: [`Accepted ${label} work continues; no remote cancellation was sent.`],
+      next: command,
+    },
+  });
+}
+
+function uncertainMutationFailure(
+  interaction,
+  error,
+  { data, label, phase, resume, retryCommand }
+) {
+  if (!isRecoverableWaitFailure(error)) throw error;
+  const status = Number(error?.status);
+  const authentication = status === 401;
+  const authorization = status === 403;
+  const command = authentication ? "ornn login" : retryCommand;
+  return interaction.result({
+    action: {
+      command,
+      description: authentication
+        ? "Sign in, then resume the preserved exact operation."
+        : "Reconcile the same exact reviewed operation.",
+      type: "command",
+    },
+    data: { ...data, remote_work_cancelled: false },
+    errors: [
+      {
+        code: authentication
+          ? "authentication_required"
+          : authorization
+            ? "authorization_denied"
+            : "service_unavailable",
+        message: authorization
+          ? `Authorization ended while reconciling ${label}; no cancellation was sent.`
+          : `The response for ${label} was lost or unavailable; its remote outcome must be reconciled.`,
+        retryable: status !== 403,
+        resource_ref: resume.ref,
+      },
+    ],
+    exitCode: authorization ? 5 : 6,
+    outcome: { class: "working", phase },
+    resume,
+    presentation: {
+      lines: [`The exact ${label} intent is preserved; its remote outcome is not yet known.`],
+      next: command,
+    },
+  });
+}
+
+export const vmLaunchModeHandler = {
+  mode: "vm",
+  async launch({ context, input, interaction }) {
+    launchInputPreflight(input, interaction);
+    input = await normalizePublicKeyInput(input);
+    const organization = await selectedOrganization(context, input, interaction);
+    const reservation = await resolveReservation(context, input, interaction, "vm");
+    const reservationId = resourceId(reservation);
+    const keyPlan = await keyPlanFromInput(context, input, interaction);
+    const [reviewedMachines, reviewedRelationships] = await Promise.all([
+      fetchMachines(context, reservationId),
+      bareMetalRelationships(context, reservationId),
+    ]);
+    input = withAuthoritativeUsername(input, reviewedMachines, interaction);
+    const reviewedOwner = launchOwnerSnapshot(reviewedMachines);
+    const reviewedRelationshipSnapshot = JSON.stringify(reviewedRelationships);
+    const waitByDefault = interaction.eligibleHuman && !interaction.machine;
+    const shouldWait = input.noWait ? false : input.wait ? true : waitByDefault;
+    const reviewAccepted = await interaction.review({
+      title: "VM launch review",
+      terms: [
+        { label: "Organization", value: organization.name },
+        {
+          label: "Capacity reservation",
+          value: `${reservationLabel(reservation)} (${reservationId})`,
+        },
+        { label: "Access mode", value: "VM" },
+        {
+          label: "SSH key",
+          value: `${text(keyPlan.key.label) ?? "SSH key"} (${text(keyPlan.key.fingerprint) ?? resourceId(keyPlan.key)})`,
+        },
+        { label: "SSH user", value: text(input.username) ?? "Owner default" },
+        { label: "Machine count", value: "1" },
+        { label: "Network", value: relationshipLabel(reviewedRelationships, "network") },
+        { label: "Storage", value: relationshipLabel(reviewedRelationships, "storage") },
+        {
+          label: "Wait",
+          value: shouldWait ? "Until SSH is usable" : "Return after durable acceptance",
+        },
+      ],
+      prompt: "Launch this VM?",
+    });
+    if (!reviewAccepted) {
+      return interaction.result({
+        data: null,
+        errors: [{ code: "declined", message: "VM launch declined.", retryable: false }],
+        exitCode: 1,
+        outcome: { class: "ended", phase: "declined" },
+        presentation: {
+          lines: ["VM launch declined. No machine was created."],
+          next: "ornn launch --mode vm",
+        },
+      });
+    }
+
+    const currentReservation = assertActiveReservation(
+      await context.fetch(
+        `/v1/workflows/commerce/reservations/${encodeURIComponent(reservationId)}`
+      ),
+      reservationId,
+      interaction,
+      "vm"
+    );
+    if (reservationLabel(currentReservation) !== reservationLabel(reservation)) {
+      interaction.error(
+        "Capacity eligibility changed after review; launch stopped before mutation.",
+        {
+          code: "reservation_eligibility_changed",
+        }
+      );
+    }
+    const idempotencyKey = text(input.idempotencyKey) ?? interaction.idempotencyKey();
+    const [existingAssigned, projectedMachines, currentRelationships] = await Promise.all([
+      fetchAssignedKeys(context, reservationId),
+      fetchMachines(context, reservationId),
+      bareMetalRelationships(context, reservationId),
+    ]);
+    const currentOwner = launchOwnerSnapshot(projectedMachines);
+    if (
+      JSON.stringify(currentOwner) !== JSON.stringify(reviewedOwner) ||
+      JSON.stringify(currentRelationships) !== reviewedRelationshipSnapshot
+    ) {
+      interaction.error(
+        "The reservation owner, network, or volume intent changed after review; launch stopped before mutation.",
+        { code: "reservation_eligibility_changed" }
+      );
+    }
+    const existingMachines = isPreassignedUnlaunchedCapacity(
+      projectedMachines,
+      existingAssigned,
+      keyPlan.key
+    )
+      ? []
+      : projectedMachines;
+    if (existingMachines.length && keyPlan.kind === "create") {
+      interaction.error(
+        "The existing machine has a different SSH-key intent than the reviewed launch.",
+        {
+          code: "launch_input_changed",
+        }
+      );
+    }
+    const key = await materializeKey(context, keyPlan, interaction, idempotencyKey);
+    const replay = machineReplayState(existingMachines, key, input, interaction, "vm");
+    let machine = replay.machine;
+    if (
+      replay.existing &&
+      !existingAssigned.some((candidate) => resourceId(candidate) === resourceId(key))
+    ) {
+      interaction.error("The existing machine does not use the reviewed SSH-key assignment.", {
+        code: "launch_input_changed",
+      });
+    }
+    if (!machine) {
+      let launch;
+      try {
+        launch = await context.fetch(
+          `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/launch`,
+          {
+            method: "POST",
+            body: {
+              access_mode: "virtual-machine",
+              network_mode: "public",
+              image_id: null,
+              machine_count: 1,
+              request_id: idempotencyKey,
+              ssh_key_ids: [resourceId(key)],
+              zone: null,
+            },
+          }
+        );
+      } catch (error) {
+        if (!isRecoverableWaitFailure(error)) throw error;
+        const discovered = await fetchMachines(context, reservationId).catch(() => []);
+        const candidate =
+          activeMachines(discovered).find((row) => machineAccessMode(row) === "vm") ?? null;
+        const retryCommand = [
+          "ornn",
+          "launch",
+          reservationId,
+          "--mode",
+          "vm",
+          "--key",
+          resourceId(key),
+          "--idempotency-key",
+          idempotencyKey,
+          ...(interaction.machine
+            ? ["--organization", resourceId(organization), "--yes", "--no-wait", "--format", "json"]
+            : []),
+        ].join(" ");
+        return uncertainMutationFailure(interaction, error, {
+          data: {
+            capacity_reservation: { id: reservationId },
+            machine: candidate ? projectMachine(candidate) : null,
+            ssh_key: projectKey(key),
+            wait: { enabled: shouldWait, timeout: text(input.timeout) ?? "10m" },
+          },
+          label: "VM launch",
+          phase: "launch_reconciliation",
+          resume: candidate
+            ? { kind: "machine", ref: machineId(candidate) }
+            : { kind: "reservation", ref: reservationId },
+          retryCommand,
+        });
+      }
+      const launched = activeMachines(machinesFromPayload(launch));
+      if (launched.length !== 1) {
+        interaction.error("Launch did not return one durable machine reference.", {
+          code: "machine_correlation_failed",
+          retryable: true,
+        });
+      }
+      machine = validatedMachine(launched, key, input, interaction, "vm");
+    }
+
+    const waitPolicy = shouldWait
+      ? { enabled: true, timeout: text(input.timeout) ?? "10m" }
+      : { enabled: false, timeout: null };
+    const resume = { kind: "machine", ref: machineId(machine) };
+    if (!shouldWait) {
+      const ready = isSshReady(machine, key);
+      return interaction.result({
+        data: launchData(reservationId, machine, key, waitPolicy, replay.replayed),
+        outcome: ready
+          ? { class: "ready", phase: "ssh_ready" }
+          : { class: "working", phase: "provisioning" },
+        resume,
+        presentation: {
+          lines: [
+            ready
+              ? `VM is SSH-ready: ${machineHostname(machine) || "selected VM"}`
+              : "VM launch accepted; provisioning continues.",
+          ],
+          next: "ornn connect",
+        },
+      });
+    }
+
+    let waitOutcome;
+    try {
+      waitOutcome = await interaction.waitForGoal({
+        command: "launch",
+        initial: machine,
+        timeoutMs: timeoutMilliseconds(input.timeout, interaction),
+        isReady: (current) => isSshReady(current, key),
+        isTerminal: (current) => TERMINAL_MACHINE_STATES.has(machineState(current)),
+        message: (current, elapsedMs) =>
+          isSshReady(current, key)
+            ? "The selected VM is SSH-ready."
+            : `The selected VM is ${machineState(current)}; waiting for SSH (${Math.floor(elapsedMs / 1000)}s).`,
+        projectProgress: (current) => ({ machine: projectMachine(current) }),
+        poll: async ({ signal }) =>
+          context.fetch(`/v1/workflows/compute/nodes/${encodeURIComponent(machineId(machine))}`, {
+            signal,
+          }),
+      });
+    } catch (error) {
+      return acceptedWaitFailure(interaction, error, {
+        data: launchData(reservationId, machine, key, waitPolicy, replay.replayed),
+        label: "VM launch",
+        phase: "provisioning",
+        resume,
+        retryCommand: `ornn connect ${machineId(machine)}`,
+      });
+    }
+    machine = waitOutcome.value;
+    const data = launchData(reservationId, machine, key, waitPolicy, replay.replayed);
+    if (waitOutcome.kind === "ready") {
+      return interaction.result({
+        data,
+        outcome: { class: "ready", phase: "ssh_ready" },
+        resume,
+        presentation: {
+          lines: [`VM is SSH-ready: ${machineHostname(machine) || "selected VM"}`],
+          next: "ornn connect",
+        },
+      });
+    }
+    if (waitOutcome.kind === "timeout") {
+      return interaction.result({
+        action: {
+          command: `ornn connect ${machineId(machine)}`,
+          description: "Retry the exact machine connection",
+          type: "command",
+        },
+        data,
+        errors: [
+          {
+            code: "wait_timeout",
+            message: "Local wait ended before SSH was ready; the remote launch continues.",
+            retryable: true,
+          },
+        ],
+        exitCode: 124,
+        outcome: { class: "working", phase: "provisioning" },
+        resume,
+        presentation: {
+          lines: [
+            `VM remains ${machineState(machine)}. Local wait timed out; remote launch continues.`,
+          ],
+          next: "ornn connect",
+        },
+      });
+    }
+    if (waitOutcome.kind === "interrupted") {
+      return interaction.result({
+        action: {
+          command: `ornn connect ${machineId(machine)}`,
+          description: "Resume from the exact machine",
+          type: "command",
+        },
+        data,
+        errors: [
+          {
+            code: "interrupted",
+            message: "Local wait was interrupted; the remote launch continues.",
+            retryable: true,
+          },
+        ],
+        exitCode: 130,
+        outcome: { class: "working", phase: "provisioning" },
+        resume,
+        presentation: {
+          lines: [
+            `VM remains ${machineState(machine)}. Local wait stopped; remote launch continues.`,
+          ],
+          next: "ornn connect",
+        },
+      });
+    }
+    return interaction.result({
+      data,
+      errors: [
+        {
+          code: "machine_failed",
+          message: "The machine entered a terminal state before SSH was ready.",
+          retryable: false,
+        },
+      ],
+      exitCode: 1,
+      outcome: { class: "failed", phase: machineState(machine) },
+      resume,
+      presentation: { lines: ["The VM failed before SSH was ready."] },
+    });
+  },
+};
+
+function reservationAllocationContext(value) {
+  const reservation = record(value);
+  return {
+    term: {
+      start: text(reservation.start_at) ?? text(reservation.start),
+      end: text(reservation.end_at) ?? text(reservation.end),
+    },
+    machine_count: Number.isSafeInteger(reservation.node_count)
+      ? reservation.node_count
+      : Number.isSafeInteger(reservation.machine_count)
+        ? reservation.machine_count
+        : null,
+    gpu_count: Number.isSafeInteger(reservation.gpu_count) ? reservation.gpu_count : null,
+  };
+}
+
+function projectOrganizationNetwork(value) {
+  const network = record(record(value).network);
+  return {
+    scope: "organization",
+    available: Boolean(text(network.status)),
+    private_network: {
+      id: "shared",
+      name: "Organization private network",
+      status: text(network.status),
+    },
+  };
+}
+
+function projectVolumeMount(value, reservationId) {
+  const attachment = record(record(value).attachment);
+  const id = resourceId(attachment);
+  const drive = record(attachment.drive);
+  return {
+    reservation_id: text(attachment.reservation_id) ?? reservationId,
+    attached: Boolean(id),
+    volume_mount: id
+      ? {
+          id,
+          volume_id: text(attachment.drive_id),
+          volume_name: text(drive.name),
+          mount_path: resolvedMountPath(attachment.mount_path, drive.active_mounts),
+          mount_mode: text(attachment.mount_mode),
+          state: text(attachment.state),
+        }
+      : null,
+  };
+}
+
+async function bareMetalRelationships(context, reservationId) {
+  const encoded = encodeURIComponent(reservationId);
+  const missingAttachment = (error) => {
+    if (!isReferenceMiss(error)) throw error;
+    return null;
+  };
+  const [network, storage] = await Promise.all([
+    context.fetch(`/v1/workflows/compute/networks/shared?overlay=true`),
+    context
+      .fetch(`/v1/workflows/compute/nodes/reservations/${encoded}/storage-attachment`)
+      .catch(missingAttachment),
+  ]);
+  return {
+    network: projectOrganizationNetwork(network),
+    storage: projectVolumeMount(storage, reservationId),
+  };
+}
+
+function bareMetalIntentSignature(reservation, relationships) {
+  return JSON.stringify({
+    allocation: reservationAllocationContext(reservation),
+    network: relationships.network,
+    storage: relationships.storage,
+  });
+}
+
+function bareMetalLaunchData(reservation, machine, key, relationships, waitPolicy, replayed) {
+  const reservationId = resourceId(reservation);
+  const invocation = isSshReady(machine, key) ? sshInvocation(machine) : null;
+  return {
+    mode: "bare-metal",
+    capacity_reservation: {
+      id: reservationId,
+      status: ACTIVE_RESERVATION,
+      allocation_context: reservationAllocationContext(reservation),
+    },
+    machine: projectMachine(machine),
+    ssh_key: projectKey(key),
+    organization_network: relationships.network,
+    volume_mount: relationships.storage,
+    wait: waitPolicy,
+    ssh_command: invocation ? commandText(invocation) : null,
+    replayed,
+    created_resources: { private_network: false, volume: false },
+  };
+}
+
+function relationshipLabel(relationships, kind) {
+  if (kind === "network") {
+    const network = relationships.network.private_network;
+    return network
+      ? `${network.name ?? "Private network"} (${network.id}); available to the organization`
+      : "Organization networking is not ready";
+  }
+  const mount = relationships.storage.volume_mount;
+  return mount
+    ? `${mount.volume_name ?? "Volume"} (${mount.volume_id}) at ${mount.mount_path ?? "owner-provided mount path"}; existing mount retained`
+    : "No existing volume mount; none will be created";
+}
+
+function workspaceIntentRequested(input) {
+  return [input.network, input.volume, input.mountAccess, input.resume].some(
+    (value) => value !== undefined
+  );
+}
+
+function workspaceId(input, interaction) {
+  const idempotencyKey = text(input.idempotencyKey);
+  const resume = text(input.resume);
+  if (idempotencyKey && resume && idempotencyKey !== resume) {
+    interaction.usage("--resume must match --idempotency-key when both are supplied.", {
+      code: "workspace_identity_conflict",
+      field: "resume",
+    });
+  }
+  const value = resume ?? idempotencyKey;
+  if (!value) {
+    interaction.usage(
+      "A caller-stable --idempotency-key is required for a durable Bare Metal workspace.",
+      {
+        code: "idempotency_key_required",
+        field: "idempotencyKey",
+      }
+    );
+  }
+  if (value.length > 115 || /\p{Cc}/u.test(value)) {
+    interaction.usage("The workspace idempotency key is invalid.", {
+      code: "invalid_idempotency_key",
+      field: resume ? "resume" : "idempotencyKey",
+    });
+  }
+  return value;
+}
+
+function workspaceMountAccess(value, interaction) {
+  const access = text(value)?.toLowerCase();
+  if (access !== "read-only" && access !== "read-write") {
+    interaction.usage("--mount-access must be read-only or read-write.", {
+      code: "invalid_access_mode",
+      field: "mountAccess",
+    });
+  }
+  return access;
+}
+
+function durableWorkspaceAllocation(reservation, interaction) {
+  const allocation = reservationAllocationContext(reservation);
+  const start = allocation.term.start;
+  const end = allocation.term.end;
+  const startMilliseconds = Date.parse(start ?? "");
+  const endMilliseconds = Date.parse(end ?? "");
+  const duration = endMilliseconds - startMilliseconds;
+  const machineCount = allocation.machine_count;
+  const gpusPerMachine = Number.isSafeInteger(reservation.gpus_per_node)
+    ? reservation.gpus_per_node
+    : Number.isSafeInteger(reservation.gpus_per_machine)
+      ? reservation.gpus_per_machine
+      : null;
+  const gpuCount = Number.isSafeInteger(allocation.gpu_count)
+    ? allocation.gpu_count
+    : Number.isSafeInteger(machineCount) && Number.isSafeInteger(gpusPerMachine)
+      ? machineCount * gpusPerMachine
+      : null;
+  if (
+    !start ||
+    !end ||
+    !Number.isFinite(startMilliseconds) ||
+    !Number.isFinite(endMilliseconds) ||
+    duration <= 0 ||
+    !Number.isSafeInteger(machineCount) ||
+    machineCount < 1 ||
+    !Number.isSafeInteger(gpuCount) ||
+    gpuCount < 1
+  ) {
+    interaction.error("The active capacity reservation does not contain valid allocation facts.", {
+      code: "reservation_allocation_incomplete",
+    });
+  }
+  const hours = duration / 3_600_000;
+  return {
+    term: { start, end, hours },
+    quantity: {
+      machine_count: machineCount,
+      gpu_count: gpuCount,
+      gpus_per_machine: gpusPerMachine,
+    },
+  };
+}
+
+function workspaceStepContext(context, interaction, signal) {
+  const stepInteraction = Object.create(interaction);
+  stepInteraction.review = async () => true;
+  stepInteraction.options = { ...interaction.options, yes: true };
+  return {
+    ...context,
+    fetch: (path, init = {}) =>
+      context.fetch(path, init.signal === undefined && signal ? { ...init, signal } : init),
+    cli: {
+      ...context.cli,
+      interaction: stepInteraction,
+    },
+  };
+}
+
+async function executeWorkspaceCapability(
+  context,
+  interaction,
+  capabilityId,
+  input,
+  { signal } = {}
+) {
+  const capability = context.cli?.catalog?.find((candidate) => candidate.id === capabilityId);
+  if (!capability) {
+    interaction.error("A required durable workspace capability is unavailable.", {
+      code: "workspace_capability_unavailable",
+    });
+  }
+  const execution = await capability.execute(
+    workspaceStepContext(context, interaction, signal),
+    input
+  );
+  if (execution?.exitCode && ![0, 3, 4].includes(execution.exitCode)) {
+    interaction.error("A durable workspace step did not complete.", {
+      code: "workspace_step_failed",
+      retryable: execution.errors?.some((error) => error?.retryable === true) === true,
+    });
+  }
+  return execution;
+}
+
+async function workspaceResourceFacts(context, interaction, input, reservationId) {
+  const [network, volume, volumeMount] = await Promise.all([
+    context.fetch("/v1/workflows/compute/networks/shared?overlay=true"),
+    executeWorkspaceCapability(context, interaction, "storage.volumes.show", {
+      $positionals: [input.volume],
+    }),
+    executeWorkspaceCapability(context, interaction, "storage.volume-mounts.show", {
+      $positionals: [reservationId],
+    }),
+  ]);
+  return {
+    network: {
+      ...projectOrganizationNetwork(network).private_network,
+      lifecycle: {
+        class: ["ready", "active"].includes(record(record(network).network).status)
+          ? "ready"
+          : "working",
+        phase: text(record(record(network).network).status) ?? "unknown",
+      },
+    },
+    volume: volume.data.volume,
+    volumeMount: volumeMount.data.volume_mount,
+  };
+}
+
+function workspaceRelationshipConflict(facts, goal, interaction) {
+  if (
+    facts.volumeMount &&
+    (facts.volumeMount.volume?.id !== facts.volume.id ||
+      facts.volumeMount.access !== goal.mountAccess)
+  ) {
+    interaction.error("The capacity reservation has a different managed-volume mount intent.", {
+      action: {
+        command: `ornn volume-mounts detach ${goal.reservationId}`,
+        description: "Review and detach the existing volume relationship before resuming.",
+        type: "command",
+      },
+      code: "workspace_volume_mount_conflict",
+    });
+  }
+}
+
+function durableWorkspaceSignature(reservation, key, facts, goal, interaction) {
+  return JSON.stringify({
+    capacity_reservation: {
+      id: resourceId(reservation),
+      status: text(reservation.status),
+      allocation: durableWorkspaceAllocation(reservation, interaction),
+    },
+    ssh_key: {
+      id: resourceId(key),
+      fingerprint: text(key.fingerprint),
+    },
+    ssh_user: goal.username,
+    private_network: facts.network,
+    managed_volume: facts.volume,
+    mount: {
+      access: goal.mountAccess,
+    },
+  });
+}
+
+function workspaceResumeCommand(input, goal, facts, id, interaction, localResume = false) {
+  if (localResume) return "ornn launch --mode bare-metal --resume";
+  const parts = [
+    "ornn",
+    "launch",
+    goal.reservationId,
+    "--mode",
+    "bare-metal",
+    "--organization",
+    goal.organizationId,
+    "--key",
+    goal.keyId,
+    "--network",
+    facts.network.id,
+    "--volume",
+    facts.volume.id,
+    "--mount-access",
+    goal.mountAccess,
+    "--resume",
+    id,
+  ];
+  if (goal.username) parts.push("--username", goal.username);
+  if (input.noWait) parts.push("--no-wait");
+  if (input.wait) parts.push("--wait", "--timeout", text(input.timeout));
+  if (interaction.machine) parts.push("--yes", "--format", interaction.format);
+  return parts.map(shellQuote).join(" ");
+}
+
+async function clearWorkspaceResume(interaction, id) {
+  try {
+    await interaction.workspaceResume?.clear(id);
+  } catch {
+    // The remote workspace is ready even if local recovery cleanup fails.
+  }
+}
+
+function workspaceSteps(overrides = {}) {
+  return [
+    { name: "ssh_key_assignment", state: "pending", ref: null },
+    { name: "organization_network", state: "pending", ref: null },
+    { name: "managed_volume_mount", state: "pending", ref: null },
+    { name: "bare_metal_machine", state: "pending", ref: null },
+  ].map((step) => ({ ...step, ...(overrides[step.name] ?? {}) }));
+}
+
+function workspaceData({ allocation, facts, goal, id, machine, steps }) {
+  const mount = facts.volumeMount;
+  return {
+    mode: "bare-metal",
+    workflow: { id, durable: true },
+    capacity_reservation: {
+      id: goal.reservationId,
+      status: ACTIVE_RESERVATION,
+      allocation_context: allocation,
+    },
+    ssh_key: projectKey(goal.key),
+    private_network: facts.network,
+    managed_volume: facts.volume,
+    volume_mount: mount,
+    machine: machine ? projectMachine(machine) : null,
+    steps,
+    source_writeback: false,
+    created_resources: { private_network: false, volume: false },
+  };
+}
+
+function safeWorkspaceError(error, step) {
+  const supplied = text(error?.code);
+  const code = supplied && /^[a-z][a-z0-9_]*$/.test(supplied) ? supplied : `${step}_failed`;
+  return {
+    code,
+    message: `The ${step.replaceAll("_", " ")} step did not reach a confirmed durable result.`,
+    retryable: error?.retryable === true || error?.status === undefined || error?.status >= 500,
+  };
+}
+
+function partialWorkspaceResult({
+  allocation,
+  error,
+  facts,
+  goal,
+  id,
+  interaction,
+  machine,
+  resumeCommand,
+  step,
+  steps,
+}) {
+  return interaction.result({
+    action: {
+      command: resumeCommand,
+      description: "Re-read every owner fact and resume only unsatisfied workspace steps.",
+      type: "command",
+    },
+    data: workspaceData({ allocation, facts, goal, id, machine, steps }),
+    errors: [safeWorkspaceError(error, step)],
+    exitCode: 4,
+    outcome: { class: "partial", phase: step },
+    resume: { kind: "bare_metal_workspace", ref: id },
+    presentation: {
+      lines: [
+        `Bare Metal workspace ${id} is durable but incomplete.`,
+        `Completed resources remain attached to capacity reservation ${goal.reservationId}.`,
+      ],
+      next: resumeCommand,
+    },
+  });
+}
+
+function workspaceMountReady(mount) {
+  return Boolean(
+    mount && mount.readiness?.expected > 0 && mount.readiness.ready === mount.readiness.expected
+  );
+}
+
+function durableWorkspaceInputPreflight(input, interaction) {
+  if (!text(input.network) || !text(input.volume) || !text(input.mountAccess)) {
+    interaction.usage(
+      "A durable Bare Metal workspace requires --network, --volume, and --mount-access.",
+      { code: "workspace_input_incomplete" }
+    );
+  }
+  if (input.network !== "shared")
+    interaction.usage("Durable Bare Metal uses organization networking; pass --network shared.", {
+      code: "invalid_network",
+      field: "network",
+    });
+  if (interaction.machine) {
+    requireCanonical(interaction, input.volume, "volume", "Managed volume");
+  }
+  return { mountAccess: workspaceMountAccess(input.mountAccess, interaction) };
+}
+
+async function launchDurableBareMetalWorkspace({
+  context,
+  input,
+  interaction,
+  organization,
+  reservation,
+  keyPlan,
+}) {
+  const id = workspaceId(input, interaction);
+  const reservationId = resourceId(reservation);
+  if (keyPlan.kind !== "existing") {
+    interaction.usage("A durable Bare Metal workspace requires a declared existing SSH key.", {
+      code: "workspace_ssh_key_required",
+      field: "key",
+    });
+  }
+  const mountAccess = input.mountAccess;
+  const key = keyPlan.key;
+  const goal = {
+    key,
+    keyId: resourceId(key),
+    mountAccess,
+    organizationId: organization.id,
+    reservationId,
+    username: text(input.username),
+  };
+  let facts = await workspaceResourceFacts(context, interaction, input, reservationId);
+  workspaceRelationshipConflict(facts, goal, interaction);
+  const allocation = durableWorkspaceAllocation(reservation, interaction);
+  const shouldWait = input.noWait
+    ? false
+    : input.wait
+      ? true
+      : interaction.eligibleHuman && !interaction.machine;
+  const accepted = await interaction.review({
+    title: "Durable Bare Metal workspace review",
+    terms: [
+      { label: "Organization", value: organization.name },
+      { label: "Active capacity", value: `${reservationLabel(reservation)} (${reservationId})` },
+      { label: "SSH key", value: `${text(key.label) ?? "SSH key"} (${resourceId(key)})` },
+      { label: "SSH user", value: goal.username ?? "Owner default" },
+      { label: "Private network", value: `${facts.network.name} (${facts.network.id})` },
+      { label: "Managed volume", value: `${facts.volume.name} (${facts.volume.id})` },
+      {
+        label: "Mount",
+        value: `${mountAccess}; every machine in the reservation`,
+      },
+      {
+        label: "Term",
+        value: `${allocation.term.start} to ${allocation.term.end} (${allocation.term.hours} hours)`,
+      },
+      {
+        label: "GPU quantity",
+        value: `${allocation.quantity.gpu_count} GPUs across ${allocation.quantity.machine_count} machine${allocation.quantity.machine_count === 1 ? "" : "s"}`,
+      },
+      {
+        label: "Creation",
+        value: "Use the declared resources only; create no network, volume, or source writeback",
+      },
+      {
+        label: "Wait",
+        value: shouldWait
+          ? "Until SSH and every requested mount are ready"
+          : "Return after durable acceptance",
+      },
+    ],
+    prompt: "Build this durable Bare Metal workspace?",
+  });
+  if (!accepted) {
+    return interaction.result({
+      errors: [
+        { code: "declined", message: "Durable Bare Metal workspace declined.", retryable: false },
+      ],
+      exitCode: 1,
+      outcome: { class: "ended", phase: "declined" },
+      presentation: {
+        lines: ["Durable Bare Metal workspace declined. No resource or relationship was created."],
+        next: "ornn launch --mode bare-metal",
+      },
+    });
+  }
+
+  const [currentReservationValue, currentKeyPlan, currentFacts] = await Promise.all([
+    context.fetch(`/v1/workflows/commerce/reservations/${encodeURIComponent(reservationId)}`),
+    keyPlanFromInput(context, input, interaction),
+    workspaceResourceFacts(context, interaction, input, reservationId),
+  ]);
+  const currentReservation = assertActiveReservation(
+    currentReservationValue,
+    reservationId,
+    interaction,
+    "bare-metal"
+  );
+  workspaceRelationshipConflict(currentFacts, goal, interaction);
+  if (
+    currentKeyPlan.kind !== "existing" ||
+    durableWorkspaceSignature(
+      currentReservation,
+      currentKeyPlan.key,
+      currentFacts,
+      goal,
+      interaction
+    ) !== durableWorkspaceSignature(reservation, key, facts, goal, interaction)
+  ) {
+    interaction.error("The durable workspace intent changed after review.", {
+      code: "workspace_intent_changed",
+    });
+  }
+  facts = currentFacts;
+  let localResume = false;
+  if (interaction.eligibleHuman && !interaction.machine) {
+    if (!interaction.workspaceResume) {
+      interaction.error(
+        "Local Bare Metal recovery could not be recorded; no owner mutation was sent.",
+        {
+          code: "local_resume_write_failed",
+          exitCode: 6,
+          retryable: true,
+        }
+      );
+    }
+    try {
+      localResume = await interaction.workspaceResume.save({
+        id,
+        organizationId: goal.organizationId,
+        reservationId: goal.reservationId,
+        keyId: goal.keyId,
+        networkId: facts.network.id,
+        volumeId: facts.volume.id,
+        mountAccess: goal.mountAccess,
+        username: goal.username,
+      });
+    } catch {
+      localResume = false;
+    }
+    if (!localResume) {
+      interaction.error(
+        "Local Bare Metal recovery could not be recorded; no owner mutation was sent.",
+        {
+          code: "local_resume_write_failed",
+          exitCode: 6,
+          retryable: true,
+        }
+      );
+    }
+  }
+  const resumeCommand = workspaceResumeCommand(input, goal, facts, id, interaction, localResume);
+  const states = {};
+  let machine = null;
+  let step = "ssh_key_assignment";
+
+  try {
+    const assignment = await executeWorkspaceCapability(
+      context,
+      interaction,
+      "access.ssh_key_assignments.assign",
+      {
+        $positionals: [reservationId],
+        key: resourceId(key),
+        idempotencyKey: `${id}:ssh-key`,
+        yes: true,
+      }
+    );
+    states.ssh_key_assignment = {
+      state: assignment.data.replayed ? "replayed" : "satisfied",
+      ref: resourceId(key),
+    };
+  } catch (error) {
+    return partialWorkspaceResult({
+      allocation,
+      error,
+      facts,
+      goal,
+      id,
+      interaction,
+      machine,
+      resumeCommand,
+      step,
+      steps: workspaceSteps(states),
+    });
+  }
+
+  states.organization_network = { state: "satisfied", ref: "shared" };
+
+  step = "managed_volume_mount";
+  try {
+    const mount = await executeWorkspaceCapability(
+      context,
+      interaction,
+      "storage.volume-mounts.attach",
+      {
+        $positionals: [reservationId],
+        access: mountAccess,
+        idempotencyKey: `${id}:volume-mount`,
+        noWait: true,
+        volume: facts.volume.id,
+        yes: true,
+      }
+    );
+    facts.volumeMount = mount.data.volume_mount;
+    states.managed_volume_mount = {
+      state: mount.data.replayed ? "replayed" : "satisfied",
+      ref: facts.volumeMount.id,
+    };
+    if (mount.exitCode === 4) {
+      return partialWorkspaceResult({
+        allocation,
+        error: { code: "volume_mount_partial", retryable: true },
+        facts,
+        goal,
+        id,
+        interaction,
+        machine,
+        resumeCommand,
+        step,
+        steps: workspaceSteps(states),
+      });
+    }
+  } catch (error) {
+    return partialWorkspaceResult({
+      allocation,
+      error,
+      facts,
+      goal,
+      id,
+      interaction,
+      machine,
+      resumeCommand,
+      step,
+      steps: workspaceSteps(states),
+    });
+  }
+
+  step = "bare_metal_machine";
+  try {
+    const existingMachines = await fetchMachines(context, reservationId);
+    const replay = machineReplayState(existingMachines, key, input, interaction, "bare-metal");
+    machine = replay.machine;
+    const replayed = replay.replayed;
+    if (!machine) {
+      const launch = await context.fetch(
+        `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/launch`,
+        {
+          method: "POST",
+          body: {
+            access_mode: "bare-metal",
+            image_id: null,
+            machine_count: 1,
+            network_mode: "private",
+            request_id: `${id}:machine`,
+            ssh_key_ids: [resourceId(key)],
+            zone: null,
+          },
+        }
+      );
+      const launched = activeMachines(machinesFromPayload(launch));
+      if (launched.length !== 1) {
+        interaction.error("Launch did not return one durable Bare Metal machine reference.", {
+          code: "machine_correlation_failed",
+          retryable: true,
+        });
+      }
+      machine = validatedMachine(launched, key, input, interaction, "bare-metal");
+    }
+    states.bare_metal_machine = {
+      state: replayed ? "replayed" : "satisfied",
+      ref: machineId(machine),
+    };
+  } catch (error) {
+    return partialWorkspaceResult({
+      allocation,
+      error,
+      facts,
+      goal,
+      id,
+      interaction,
+      machine,
+      resumeCommand,
+      step,
+      steps: workspaceSteps(states),
+    });
+  }
+
+  const resume = { kind: "bare_metal_workspace", ref: id };
+  if (!shouldWait) {
+    const ready = isSshReady(machine, key) && workspaceMountReady(facts.volumeMount);
+    if (ready) await clearWorkspaceResume(interaction, id);
+    return interaction.result({
+      data: workspaceData({
+        allocation,
+        facts,
+        goal,
+        id,
+        machine,
+        steps: workspaceSteps(states),
+      }),
+      outcome: ready
+        ? { class: "ready", phase: "workspace_ready" }
+        : { class: "working", phase: "workspace_accepted" },
+      resume,
+      presentation: {
+        lines: [
+          ready
+            ? `Durable Bare Metal workspace is ready: ${machineHostname(machine) || machineId(machine)}`
+            : `Durable Bare Metal workspace accepted: ${id}`,
+        ],
+        next: ready ? "ornn connect" : resumeCommand,
+      },
+    });
+  }
+
+  let waitOutcome;
+  try {
+    waitOutcome = await interaction.waitForGoal({
+      command: "launch",
+      initial: { machine, mount: facts.volumeMount },
+      timeoutMs: timeoutMilliseconds(input.timeout, interaction),
+      isReady: (current) => isSshReady(current.machine, key) && workspaceMountReady(current.mount),
+      isTerminal: (current) =>
+        TERMINAL_MACHINE_STATES.has(machineState(current.machine)) ||
+        current.mount?.readiness?.failed > 0 ||
+        current.mount?.lifecycle?.class === "ended",
+      message: (current, elapsedMs) =>
+        `Bare Metal is ${machineState(current.machine)}; ${current.mount?.readiness?.ready ?? 0} of ${current.mount?.readiness?.expected ?? 0} mounts ready (${Math.floor(elapsedMs / 1000)}s).`,
+      projectProgress: (current) => ({
+        machine: projectMachine(current.machine),
+        volume_mount: current.mount,
+        workflow_id: id,
+      }),
+      poll: async ({ signal }) => {
+        const [currentMachine, currentMount] = await Promise.all([
+          context.fetch(`/v1/workflows/compute/nodes/${encodeURIComponent(machineId(machine))}`, {
+            signal,
+          }),
+          executeWorkspaceCapability(
+            context,
+            interaction,
+            "storage.volume-mounts.show",
+            {
+              $positionals: [reservationId],
+            },
+            { signal }
+          ),
+        ]);
+        return { machine: currentMachine, mount: currentMount.data.volume_mount };
+      },
+    });
+  } catch (error) {
+    return acceptedWaitFailure(interaction, error, {
+      data: workspaceData({
+        allocation,
+        facts,
+        goal,
+        id,
+        machine,
+        steps: workspaceSteps(states),
+      }),
+      label: "durable Bare Metal workspace",
+      phase: "workspace_accepted",
+      resume,
+      retryCommand: resumeCommand,
+    });
+  }
+  machine = waitOutcome.value.machine;
+  facts.volumeMount = waitOutcome.value.mount;
+  const data = workspaceData({
+    allocation,
+    facts,
+    goal,
+    id,
+    machine,
+    steps: workspaceSteps(states),
+  });
+  if (waitOutcome.kind === "ready") {
+    await clearWorkspaceResume(interaction, id);
+    return interaction.result({
+      data,
+      outcome: { class: "ready", phase: "workspace_ready" },
+      resume,
+      presentation: {
+        lines: [
+          `Durable Bare Metal workspace is ready: ${machineHostname(machine) || machineId(machine)}`,
+        ],
+        next: "ornn connect",
+      },
+    });
+  }
+  if (waitOutcome.kind === "timeout" || waitOutcome.kind === "interrupted") {
+    const interrupted = waitOutcome.kind === "interrupted";
+    return interaction.result({
+      action: {
+        command: resumeCommand,
+        description: "Resume the exact durable workspace from current owner facts.",
+        type: "command",
+      },
+      data,
+      errors: [
+        {
+          code: interrupted ? "interrupted" : "wait_timeout",
+          message: interrupted
+            ? "Local waiting stopped; the remote workspace was not changed."
+            : "Local waiting timed out; the remote workspace continues.",
+          retryable: true,
+        },
+      ],
+      exitCode: interrupted ? 130 : 124,
+      outcome: { class: "working", phase: "workspace_accepted" },
+      resume,
+      presentation: {
+        lines: [
+          interrupted
+            ? "Local waiting stopped; no remote cancellation was sent."
+            : "Local waiting timed out; no remote cancellation was sent.",
+        ],
+        next: resumeCommand,
+      },
+    });
+  }
+  return partialWorkspaceResult({
+    allocation,
+    error: { code: "workspace_readiness_partial", retryable: true },
+    facts,
+    goal,
+    id,
+    interaction,
+    machine,
+    resumeCommand,
+    step: "workspace_readiness",
+    steps: workspaceSteps(states),
+  });
+}
+
+export const bareMetalLaunchModeHandler = {
+  mode: "bare-metal",
+  async launch({ context, input, interaction }) {
+    const durableWorkspace = workspaceIntentRequested(input);
+    if (durableWorkspace && input.resume === true) {
+      if (!interaction.eligibleHuman || interaction.machine) {
+        interaction.usage("--resume without a value requires an eligible interactive terminal.", {
+          code: "workspace_resume_reference_required",
+          field: "resume",
+        });
+      }
+      const hasConflictingIntent =
+        (input.$positionals?.length ?? 0) > 0 ||
+        [
+          input.organization,
+          input.reservation,
+          input.reservationId,
+          input.key,
+          input.keyId,
+          input.label,
+          input.publicKey,
+          input.publicKeyFile,
+          input.network,
+          input.volume,
+          input.mountAccess,
+          input.username,
+          input.machine,
+          input.machines,
+          input.nodes,
+          input.idempotencyKey,
+        ].some((value) => value !== undefined);
+      if (hasConflictingIntent) {
+        interaction.usage("--resume without a value cannot be combined with workspace intent.", {
+          code: "workspace_resume_conflict",
+          field: "resume",
+        });
+      }
+      let remembered;
+      try {
+        remembered = await interaction.workspaceResume?.load();
+      } catch {
+        interaction.error("The locally remembered Bare Metal workspace could not be read.", {
+          code: "workspace_resume_unavailable",
+          exitCode: 6,
+          retryable: true,
+        });
+      }
+      if (!remembered) {
+        interaction.usage("No locally remembered Bare Metal workspace is available to resume.", {
+          code: "workspace_resume_not_found",
+          field: "resume",
+        });
+      }
+      input = {
+        ...input,
+        $positionals: [remembered.reservationId],
+        idempotencyKey: remembered.id,
+        key: remembered.keyId,
+        mountAccess: remembered.mountAccess,
+        network: remembered.networkId,
+        organization: remembered.organizationId,
+        resume: remembered.id,
+        username: remembered.username ?? undefined,
+        volume: remembered.volumeId,
+      };
+    } else if (
+      durableWorkspace &&
+      interaction.eligibleHuman &&
+      !interaction.machine &&
+      !text(input.idempotencyKey) &&
+      !text(input.resume)
+    ) {
+      input = { ...input, idempotencyKey: interaction.idempotencyKey() };
+    } else if (durableWorkspace && !text(input.idempotencyKey) && text(input.resume)) {
+      input = { ...input, idempotencyKey: text(input.resume) };
+    }
+    if (durableWorkspace) {
+      input = { ...input, ...durableWorkspaceInputPreflight(input, interaction) };
+    }
+    launchInputPreflight(input, interaction);
+    input = await normalizePublicKeyInput(input);
+    const organization = await selectedOrganization(context, input, interaction);
+    const reservation = await resolveReservation(context, input, interaction, "bare-metal");
+    const reservationId = resourceId(reservation);
+    const keyPlan = await keyPlanFromInput(context, input, interaction);
+    if (durableWorkspace) {
+      return launchDurableBareMetalWorkspace({
+        context,
+        input,
+        interaction,
+        keyPlan,
+        organization,
+        reservation,
+      });
+    }
+    const [relationships, reviewedMachines] = await Promise.all([
+      bareMetalRelationships(context, reservationId),
+      fetchMachines(context, reservationId),
+    ]);
+    input = withAuthoritativeUsername(input, reviewedMachines, interaction);
+    const reviewedOwner = launchOwnerSnapshot(reviewedMachines);
+    const shouldWait = input.noWait
+      ? false
+      : input.wait
+        ? true
+        : interaction.eligibleHuman && !interaction.machine;
+    const allocation = reservationAllocationContext(reservation);
+    const reviewAccepted = await interaction.review({
+      title: "Bare Metal launch review",
+      terms: [
+        { label: "Organization", value: organization.name },
+        {
+          label: "Capacity reservation",
+          value: `${reservationLabel(reservation)} (${reservationId})`,
+        },
+        { label: "Access mode", value: "Bare Metal" },
+        {
+          label: "SSH key",
+          value: `${text(keyPlan.key.label) ?? "SSH key"} (${text(keyPlan.key.fingerprint) ?? resourceId(keyPlan.key)})`,
+        },
+        { label: "SSH user", value: text(input.username) ?? "Owner default" },
+        { label: "Private network", value: relationshipLabel(relationships, "network") },
+        { label: "Volume mount", value: relationshipLabel(relationships, "storage") },
+        {
+          label: "Term",
+          value: `${allocation.term.start ?? "unreported"} to ${allocation.term.end ?? "unreported"}`,
+        },
+        {
+          label: "Wait",
+          value: shouldWait
+            ? "Until SSH and the selected key are usable"
+            : "Return after durable acceptance",
+        },
+      ],
+      prompt: "Launch this Bare Metal machine?",
+    });
+    if (!reviewAccepted) {
+      return interaction.result({
+        errors: [{ code: "declined", message: "Bare Metal launch declined.", retryable: false }],
+        exitCode: 1,
+        outcome: { class: "ended", phase: "declined" },
+        presentation: {
+          lines: ["Bare Metal launch declined. No machine or relationship was created."],
+          next: "ornn launch --mode bare-metal",
+        },
+      });
+    }
+
+    const [currentReservationValue, currentRelationships, existingAssigned, projectedMachines] =
+      await Promise.all([
+        context.fetch(`/v1/workflows/commerce/reservations/${encodeURIComponent(reservationId)}`),
+        bareMetalRelationships(context, reservationId),
+        fetchAssignedKeys(context, reservationId),
+        fetchMachines(context, reservationId),
+      ]);
+    const currentReservation = assertActiveReservation(
+      currentReservationValue,
+      reservationId,
+      interaction,
+      "bare-metal"
+    );
+    if (
+      reservationLabel(currentReservation) !== reservationLabel(reservation) ||
+      bareMetalIntentSignature(currentReservation, currentRelationships) !==
+        bareMetalIntentSignature(reservation, relationships)
+    ) {
+      interaction.error("Bare Metal eligibility or a declared relationship changed after review.", {
+        code: "reservation_eligibility_changed",
+      });
+    }
+    const currentOwner = launchOwnerSnapshot(projectedMachines);
+    if (JSON.stringify(currentOwner) !== JSON.stringify(reviewedOwner)) {
+      interaction.error(
+        "The reservation owner assignment changed after review; launch stopped before mutation.",
+        { code: "reservation_eligibility_changed" }
+      );
+    }
+    const existingMachines = isPreassignedUnlaunchedCapacity(
+      projectedMachines,
+      existingAssigned,
+      keyPlan.key
+    )
+      ? []
+      : projectedMachines;
+    const idempotencyKey = text(input.idempotencyKey) ?? interaction.idempotencyKey();
+    if (existingMachines.length && keyPlan.kind === "create") {
+      interaction.error(
+        "The existing machine has a different SSH-key intent than the reviewed launch.",
+        {
+          code: "launch_input_changed",
+        }
+      );
+    }
+    const key = await materializeKey(context, keyPlan, interaction, idempotencyKey);
+    const replay = machineReplayState(existingMachines, key, input, interaction, "bare-metal");
+    let machine = replay.machine;
+    if (
+      replay.existing &&
+      !existingAssigned.some((candidate) => resourceId(candidate) === resourceId(key))
+    ) {
+      interaction.error("The existing machine does not use the reviewed SSH-key assignment.", {
+        code: "launch_input_changed",
+      });
+    }
+    const replayed = replay.replayed;
+
+    if (!machine) {
+      let launch;
+      try {
+        await ensureAssignment(context, reservationId, key, idempotencyKey, interaction);
+        const launchBody = {
+          access_mode: "bare-metal",
+          network_mode: "public",
+          image_id: null,
+          machine_count: 1,
+          request_id: idempotencyKey,
+          ssh_key_ids: [resourceId(key)],
+          zone: null,
+        };
+        launch = await context.fetch(
+          `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/launch`,
+          { method: "POST", body: launchBody }
+        );
+      } catch (error) {
+        if (!isRecoverableWaitFailure(error)) throw error;
+        const discovered = await fetchMachines(context, reservationId).catch(() => []);
+        const candidate =
+          activeMachines(discovered).find((row) => machineAccessMode(row) === "bare-metal") ?? null;
+        const retryCommand = [
+          "ornn",
+          "launch",
+          reservationId,
+          "--mode",
+          "bare-metal",
+          "--key",
+          resourceId(key),
+          "--idempotency-key",
+          idempotencyKey,
+          ...(interaction.machine
+            ? ["--organization", resourceId(organization), "--yes", "--no-wait", "--format", "json"]
+            : []),
+        ].join(" ");
+        return uncertainMutationFailure(interaction, error, {
+          data: {
+            capacity_reservation: {
+              id: reservationId,
+              label: reservationLabel(currentReservation),
+            },
+            machine: candidate ? projectMachine(candidate) : null,
+            relationships: currentRelationships,
+            ssh_key: projectKey(key),
+            wait: { enabled: shouldWait, timeout: text(input.timeout) ?? "10m" },
+          },
+          label: "Bare Metal launch",
+          phase: "launch_reconciliation",
+          resume: candidate
+            ? { kind: "machine", ref: machineId(candidate) }
+            : { kind: "reservation", ref: reservationId },
+          retryCommand,
+        });
+      }
+      const launched = activeMachines(machinesFromPayload(launch));
+      if (launched.length !== 1) {
+        interaction.error("Launch did not return one durable Bare Metal machine reference.", {
+          code: "machine_correlation_failed",
+          retryable: true,
+        });
+      }
+      machine = validatedMachine(launched, key, input, interaction, "bare-metal");
+    }
+
+    const waitPolicy = shouldWait
+      ? { enabled: true, timeout: text(input.timeout) ?? "10m" }
+      : { enabled: false, timeout: null };
+    const resume = { kind: "machine", ref: machineId(machine) };
+    if (!shouldWait) {
+      const ready = isSshReady(machine, key);
+      return interaction.result({
+        data: bareMetalLaunchData(
+          currentReservation,
+          machine,
+          key,
+          currentRelationships,
+          waitPolicy,
+          replayed
+        ),
+        outcome: ready
+          ? { class: "ready", phase: "ssh_ready" }
+          : { class: "working", phase: "provisioning" },
+        resume,
+        presentation: {
+          lines: [
+            ready
+              ? `Bare Metal is SSH-ready: ${machineHostname(machine) || "selected machine"}`
+              : "Bare Metal launch accepted; provisioning continues.",
+          ],
+          next: "ornn connect",
+        },
+      });
+    }
+
+    let waitOutcome;
+    try {
+      waitOutcome = await interaction.waitForGoal({
+        command: "launch",
+        initial: machine,
+        timeoutMs: timeoutMilliseconds(input.timeout, interaction),
+        isReady: (current) => isSshReady(current, key),
+        isTerminal: (current) => TERMINAL_MACHINE_STATES.has(machineState(current)),
+        message: (current, elapsedMs) =>
+          isSshReady(current, key)
+            ? "The selected Bare Metal machine is SSH-ready."
+            : `The selected Bare Metal machine is ${machineState(current)}; waiting for SSH and key delivery (${Math.floor(elapsedMs / 1000)}s).`,
+        projectProgress: (current) => ({ machine: projectMachine(current) }),
+        poll: async ({ signal }) =>
+          context.fetch(`/v1/workflows/compute/nodes/${encodeURIComponent(machineId(machine))}`, {
+            signal,
+          }),
+      });
+    } catch (error) {
+      return acceptedWaitFailure(interaction, error, {
+        data: bareMetalLaunchData(
+          currentReservation,
+          machine,
+          key,
+          currentRelationships,
+          waitPolicy,
+          replayed
+        ),
+        label: "Bare Metal launch",
+        phase: "provisioning",
+        resume,
+        retryCommand: `ornn machines wait ${machineId(machine)} --timeout ${waitPolicy.timeout}`,
+      });
+    }
+    machine = waitOutcome.value;
+    const data = bareMetalLaunchData(
+      currentReservation,
+      machine,
+      key,
+      currentRelationships,
+      waitPolicy,
+      replayed
+    );
+    if (waitOutcome.kind === "ready") {
+      return interaction.result({
+        data,
+        outcome: { class: "ready", phase: "ssh_ready" },
+        resume,
+        presentation: {
+          lines: [`Bare Metal is SSH-ready: ${machineHostname(machine) || "selected machine"}`],
+          next: "ornn connect",
+        },
+      });
+    }
+    if (waitOutcome.kind === "timeout") {
+      return interaction.result({
+        action: {
+          command: `ornn machines wait ${machineId(machine)} --timeout ${waitPolicy.timeout}`,
+          description: "Resume the exact Bare Metal readiness wait",
+          type: "command",
+        },
+        data,
+        errors: [
+          {
+            code: "wait_timeout",
+            message: "Local wait ended before SSH was ready; the remote launch continues.",
+            retryable: true,
+          },
+        ],
+        exitCode: 124,
+        outcome: { class: "working", phase: "provisioning" },
+        resume,
+        presentation: {
+          lines: [
+            `Bare Metal remains ${machineState(machine)}. Local wait timed out; remote launch continues.`,
+          ],
+          next: "ornn connect",
+        },
+      });
+    }
+    if (waitOutcome.kind === "interrupted") {
+      return interaction.result({
+        action: {
+          command: `ornn machines wait ${machineId(machine)} --timeout ${waitPolicy.timeout}`,
+          description: "Resume from the exact Bare Metal machine",
+          type: "command",
+        },
+        data,
+        errors: [
+          {
+            code: "interrupted",
+            message: "Local wait was interrupted; the remote launch continues.",
+            retryable: true,
+          },
+        ],
+        exitCode: 130,
+        outcome: { class: "working", phase: "provisioning" },
+        resume,
+        presentation: {
+          lines: [
+            `Bare Metal remains ${machineState(machine)}. Local wait stopped; remote launch continues.`,
+          ],
+          next: "ornn connect",
+        },
+      });
+    }
+    return interaction.result({
+      data,
+      errors: [
+        {
+          code: "machine_failed",
+          message: "The Bare Metal machine entered a terminal state before SSH was ready.",
+          retryable: false,
+        },
+      ],
+      exitCode: 1,
+      outcome: { class: "failed", phase: machineState(machine) },
+      resume,
+      presentation: { lines: ["Bare Metal failed before SSH was ready."] },
+    });
+  },
+};
+
+async function spawnSsh(invocation, spawnProcess) {
+  if (invocation.raw) return { code: 0, rendered: true, signal: null };
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess(invocation.command, invocation.args, { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("exit", (code, signal) =>
+      resolve({
+        code: signal ? 130 : (code ?? 0),
+        rendered: false,
+        signal: signal ?? null,
+      })
+    );
+  });
+}
+
+const directConnectResolutionCache = new WeakMap();
+const directConnectCandidatesCache = new WeakMap();
+
+async function resolveDirectConnectMachine(reference, context, interaction) {
+  const machine = await resolveMachineReference(reference, context, interaction, {
+    allowMiss: true,
+  });
+  if (machine || !CANONICAL_ID.test(text(reference) ?? "")) return machine;
+
+  let machines = directConnectCandidatesCache.get(context);
+  if (!machines) {
+    machines = listOwnedActiveMachines(context, interaction);
+    directConnectCandidatesCache.set(context, machines);
+  }
+  const matches = (await machines).filter(
+    (candidate) =>
+      (text(candidate.reservation_id) ?? text(candidate.commerce_reservation_id)) === reference
+  );
+  if (matches.length <= 1) return matches[0] ?? null;
+  if (!interaction.eligibleHuman) {
+    interaction.usage(
+      "This capacity reservation has multiple active machines; supply one canonical machine ID.",
+      {
+        code: "machine_reservation_ambiguous",
+        field: "machine",
+      }
+    );
+  }
+  const answer = await interaction.ask({
+    label: "Machine",
+    choices: matches.map((candidate) => ({
+      label: `${machineHostname(candidate) ?? "Unnamed machine"} · ${machineAccessMode(candidate) ?? "direct"} · ${machineState(candidate)}`,
+      value: machineId(candidate),
+    })),
+  });
+  const selected = matches.find((candidate) => machineId(candidate) === answer);
+  if (!selected) {
+    interaction.usage("Choose one exact machine from the capacity reservation.", {
+      code: "machine_reservation_ambiguous",
+      field: "machine",
+    });
+  }
+  return selected;
+}
+
+function cachedDirectConnectMachine(reference, context, interaction) {
+  const cached = directConnectResolutionCache.get(context);
+  if (cached?.reference === reference) return cached.machine;
+  const machine = resolveDirectConnectMachine(reference, context, interaction);
+  directConnectResolutionCache.set(context, { reference, machine });
+  return machine;
+}
+
+async function directConnectCandidates(context, interaction, acceptedModes, label) {
+  let machines = directConnectCandidatesCache.get(context);
+  if (!machines) {
+    machines = listOwnedActiveMachines(context, interaction);
+    directConnectCandidatesCache.set(context, machines);
+  }
+  return (await machines)
+    .filter((machine) =>
+      acceptedModes.includes(
+        machineAccessMode(machine) === "vm" ? "virtual-machine" : machineAccessMode(machine)
+      )
+    )
+    .map((machine) => ({
+      label: `${machineHostname(machine) ?? "Unnamed machine"} · ${label} · ${machineState(machine)}`,
+      reference: machineId(machine),
+    }));
+}
+
+function createDirectMachineConnectModeHandler({
+  acceptedModes,
+  label,
+  mode,
+  spawnProcess = spawnProcessDefault,
+}) {
+  return {
+    mode,
+    candidates({ context, interaction }) {
+      return directConnectCandidates(context, interaction, acceptedModes, label);
+    },
+    async resolve({ context, input, interaction, reference }) {
+      const machine = await cachedDirectConnectMachine(reference, context, interaction);
+      if (!machine) return null;
+      const accessMode =
+        machineAccessMode(machine) === "vm" ? "virtual-machine" : machineAccessMode(machine);
+      if (!acceptedModes.includes(accessMode)) return null;
+      const reservationId = text(machine.reservation_id) ?? text(machine.commerce_reservation_id);
+      if (!reservationId) {
+        interaction.error("The machine is missing its capacity-reservation reference.", {
+          code: "machine_correlation_failed",
+        });
+      }
+      const reservation = await context.fetch(
+        `/v1/workflows/commerce/reservations/${encodeURIComponent(reservationId)}`
+      );
+      if (!isDirectReservation(reservation)) return null;
+      const privateTransportRequired = text(machine.network_mode) === "private";
+      return {
+        context,
+        input,
+        interaction,
+        machine,
+        mode,
+        privateTransportRequired,
+        reservationId,
+        targetReference: reference,
+      };
+    },
+    matches(state) {
+      return state.mode === mode || acceptedModes.includes(text(state.machine?.access_mode));
+    },
+    async connect(state) {
+      const { input, interaction, machine } = state;
+      if (input.output || input.overwrite) {
+        interaction.usage(
+          `${label} connect uses native SSH and does not write a kubeconfig or other output file.`,
+          {
+            code: "direct_machine_output_unsupported",
+            field: "output",
+          }
+        );
+      }
+      const reachability = machineReachability(machine);
+      const invocation = reachability.class === "ready" ? sshInvocation(machine, input) : null;
+      const resume = { kind: "machine", ref: machineId(machine) };
+      const displayName = machineHostname(machine) || "the selected machine";
+      const waitTarget = machineHostname(machine)
+        ? shellQuote(machineHostname(machine))
+        : "--guided";
+      const privateTransport = state.privateNetwork
+        ? {
+            private_network: {
+              id: resourceId(state.privateNetwork),
+              name: text(state.privateNetwork.name) ?? text(state.privateNetwork.label),
+            },
+            vpn_connection: state.vpnConnection
+              ? {
+                  id: resourceId(state.vpnConnection),
+                  name: text(state.vpnConnection.name) ?? text(state.vpnConnection.label),
+                  status:
+                    text(state.vpnConnection.lifecycle?.class) ?? text(state.vpnConnection.status),
+                }
+              : null,
+          }
+        : null;
+      if (!invocation) {
+        const keyPending = reachability.phase === "key_delivery_pending";
+        return {
+          action: {
+            command: `ornn machines wait ${machineId(machine)} --timeout 10m`,
+            description: "Wait for the exact machine to become SSH-ready",
+            type: "command",
+          },
+          data: {
+            machine: projectMachine(machine),
+            private_transport: privateTransport,
+            ssh_command: null,
+          },
+          errors: [
+            {
+              code: keyPending ? "ssh_key_delivery_pending" : "ssh_not_ready",
+              message: keyPending
+                ? "The machine lifecycle is ready, but SSH-key delivery is still pending."
+                : "The machine exists, but SSH is not usable yet.",
+              retryable: true,
+            },
+          ],
+          exitCode: 4,
+          outcome: {
+            class: "working",
+            phase: keyPending ? "key_delivery_pending" : "ssh_pending",
+          },
+          resume,
+          presentation: {
+            lines: [
+              keyPending
+                ? `${label} ${displayName} is running; SSH-key delivery is pending.`
+                : `${label} ${displayName} is not SSH-ready yet.`,
+            ],
+            next: `ornn machines wait ${waitTarget}`,
+          },
+        };
+      }
+      const command = commandText(invocation);
+      const data = {
+        machine: projectMachine(machine),
+        private_transport: privateTransport,
+        ssh_command: command,
+      };
+      if (interaction.eligibleHuman && !interaction.machine && input.print !== true) {
+        interaction.stderr?.write(
+          `Opening SSH to ${displayName}.\nRun: ${command}\nWaiting for SSH to exit. Press Ctrl-C to stop only local SSH; the remote machine keeps running.\n`
+        );
+        const launched = await spawnSsh(invocation, spawnProcess);
+        if (launched.rendered) {
+          return {
+            data,
+            outcome: { class: "ready", phase: "ssh_ready" },
+            presentation: { lines: [`Run: ${command}`] },
+            resume,
+          };
+        }
+        if (launched.code === 130) {
+          return {
+            data,
+            errors: [
+              {
+                code: "interrupted",
+                message:
+                  "The local SSH process was interrupted; the remote machine was not changed.",
+                retryable: true,
+              },
+            ],
+            exitCode: 130,
+            outcome: { class: "ended", phase: "interrupted" },
+            resume,
+            presentation: { lines: [`SSH session interrupted for ${displayName}.`] },
+          };
+        }
+        if (launched.code !== 0) {
+          return {
+            data,
+            errors: [
+              {
+                code: "ssh_failed",
+                message: `SSH exited with status ${launched.code}.`,
+                retryable: false,
+              },
+            ],
+            exitCode: 1,
+            outcome: { class: "failed", phase: "ssh_failed" },
+            resume,
+            presentation: {
+              lines: [`SSH session for ${displayName} exited with status ${launched.code}.`],
+            },
+          };
+        }
+      }
+      return {
+        data,
+        outcome: { class: "ready", phase: "ssh_ready" },
+        presentation: {
+          lines: [
+            input.print === true || !interaction.eligibleHuman
+              ? `Run: ${command}`
+              : `SSH session ended for ${displayName}.`,
+          ],
+        },
+        resume,
+      };
+    },
+  };
+}
+
+export function createVmConnectModeHandler(options = {}) {
+  return createDirectMachineConnectModeHandler({
+    ...options,
+    acceptedModes: ["virtual-machine", "vm"],
+    label: "VM",
+    mode: "vm",
+  });
+}
+
+export function createBareMetalConnectModeHandler(options = {}) {
+  return createDirectMachineConnectModeHandler({
+    ...options,
+    acceptedModes: ["bare-metal"],
+    label: "Bare Metal",
+    mode: "bare-metal",
+  });
+}
+
+function directMode(value, interaction, { optional = false } = {}) {
+  const mode = text(value)?.toLowerCase() ?? null;
+  if (!mode && optional) return null;
+  if (!mode || !["vm", "bare-metal"].includes(mode)) {
+    interaction.usage("--mode must be vm or bare-metal.", {
+      code: "invalid_access_mode",
+      field: "mode",
+    });
+  }
+  return mode;
+}
+
+function networkMode(value, interaction, { optional = false } = {}) {
+  const network = text(value)?.toLowerCase() ?? null;
+  if (!network && optional) return null;
+  if (!network || !["public", "private"].includes(network)) {
+    interaction.usage("--network must be public or private.", {
+      code: "invalid_network_mode",
+      field: "network",
+    });
+  }
+  return network;
+}
+
+function validateWaitInput(input, interaction, { waitCommand = false } = {}) {
+  if (input.wait && input.noWait) {
+    interaction.usage("--wait and --no-wait cannot be combined.", {
+      code: "wait_conflict",
+      field: "wait",
+    });
+  }
+  if (input.noWait && text(input.timeout)) {
+    interaction.usage("--timeout cannot be combined with --no-wait.", {
+      code: "wait_conflict",
+      field: "timeout",
+    });
+  }
+  if (text(input.timeout)) timeoutMilliseconds(input.timeout, interaction);
+  const noninteractive = interaction.machine || !interaction.eligibleHuman;
+  if (!waitCommand && noninteractive && input.wait && !text(input.timeout)) {
+    interaction.usage("--wait requires a bounded --timeout outside an eligible terminal.", {
+      code: "timeout_required",
+      field: "timeout",
+    });
+  }
+  if (waitCommand && interaction.machine && !text(input.timeout)) {
+    interaction.usage("Automation must bound machines wait with --timeout <duration>.", {
+      code: "timeout_required",
+      field: "timeout",
+    });
+  }
+}
+
+function requireMachineMutationSafety(input, interaction, { destructive = false } = {}) {
+  validateWaitInput(input, interaction);
+  if (destructive && input.eraseLocalData !== true) {
+    interaction.usage(
+      "machines reset requires --erase-local-data; --yes cannot infer destructive scope.",
+      {
+        code: "erase_local_data_required",
+        field: "eraseLocalData",
+      }
+    );
+  }
+  if (interaction.machine || !interaction.eligibleHuman) {
+    if (input.yes !== true) {
+      interaction.usage(
+        "--yes is required outside an eligible terminal after reviewing the exact intent.",
+        {
+          code: "consent_required",
+          field: "yes",
+        }
+      );
+    }
+    if (!text(input.idempotencyKey)) {
+      interaction.usage("--idempotency-key is required outside an eligible terminal.", {
+        code: "idempotency_key_required",
+        field: "idempotencyKey",
+      });
+    }
+  }
+}
+
+function targetPosition(input, interaction, usage) {
+  const values = Array.isArray(input.$positionals) ? input.$positionals : [];
+  if (input.guided && !interaction.eligibleHuman) {
+    interaction.usage("--guided requires an eligible interactive terminal.", {
+      code: "guided_unavailable",
+      field: "guided",
+    });
+  }
+  if (values.length > 1 || (values.length === 0 && input.guided !== true)) {
+    interaction.usage(`Usage: ${usage}`, {
+      code: values.length > 1 ? "target_conflict" : "missing_input",
+      field: "machine",
+    });
+  }
+  const reference = text(values[0]);
+  return reference;
+}
+
+function machineCursorPage(items, input, interaction) {
+  const limit = Number.isSafeInteger(input.limit) ? input.limit : 50;
+  const cursor = text(input.cursor);
+  let offset = 0;
+  if (cursor) {
+    let after;
+    try {
+      if (!/^[A-Za-z0-9_-]+$/.test(cursor)) throw new Error("invalid cursor");
+      const decoded = record(JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")));
+      if (decoded.version !== 1 || decoded.kind !== "machines") throw new Error("invalid cursor");
+      after = text(decoded.after);
+    } catch {
+      interaction.usage("The machine cursor is invalid or stale.", {
+        code: "invalid_cursor",
+        field: "cursor",
+      });
+    }
+    const index = items.findIndex((item) => machineId(item) === after);
+    if (index === -1) {
+      interaction.usage("The machine cursor is invalid or stale.", {
+        code: "invalid_cursor",
+        field: "cursor",
+      });
+    }
+    offset = index + 1;
+  }
+  const selected = items.slice(offset, offset + limit);
+  const last = selected.at(-1);
+  return {
+    items: selected,
+    page: {
+      limit,
+      returned: selected.length,
+      next_cursor:
+        offset + selected.length < items.length && last
+          ? Buffer.from(
+              JSON.stringify({
+                version: 1,
+                kind: "machines",
+                after: machineId(last),
+              })
+            ).toString("base64url")
+          : null,
+    },
+  };
+}
+
+async function resolveMachineCommandTarget(input, context, interaction, usage) {
+  const reference = targetPosition(input, interaction, usage);
+  const machine = await resolveMachineReference(reference, context, interaction);
+  const reservationId = text(machine.reservation_id) ?? text(machine.commerce_reservation_id);
+  if (!reservationId) {
+    interaction.error("The machine is missing its capacity-reservation reference.", {
+      code: "machine_correlation_failed",
+    });
+  }
+  const reservation = await context.fetch(
+    `/v1/workflows/commerce/reservations/${encodeURIComponent(reservationId)}`
+  );
+  if (!isDirectReservation(reservation)) {
+    interaction.error(
+      "The selected machine belongs to a cluster rather than the direct-machine lifecycle.",
+      {
+        code: "machine_not_direct",
+      }
+    );
+  }
+  return machine;
+}
+
+function machineLines(machine) {
+  const projected = projectMachine(machine);
+  return [
+    `${projected.access_mode === "bare-metal" ? "Bare Metal" : "VM"} ${projected.hostname ?? projected.id}`,
+    `  ID: ${projected.id}`,
+    `  Capacity reservation: ${projected.reservation_id ?? "unreported"}`,
+    `  Lifecycle: ${projected.lifecycle.class} / ${projected.lifecycle.phase}`,
+    `  Reachability: ${projected.reachability.class} / ${projected.reachability.phase}`,
+  ];
+}
+
+function shouldWaitForMutation(input, interaction) {
+  if (input.noWait) return false;
+  if (input.wait) return true;
+  return !interaction.machine && interaction.eligibleHuman;
+}
+
+async function waitForMachine(context, interaction, machine, timeout, command) {
+  return interaction.waitForGoal({
+    command,
+    initial: machine,
+    timeoutMs: timeoutMilliseconds(timeout, interaction),
+    isReady: (current) => machineReachability(current).class === "ready",
+    isTerminal: (current) => machineReachability(current).class === "failed",
+    message: (current, elapsedMs) => {
+      const reachability = machineReachability(current);
+      return reachability.class === "ready"
+        ? `Machine ${machineId(current)} is SSH-ready.`
+        : `Machine ${machineId(current)} is ${machineState(current)}; ${reachability.phase.replaceAll("_", " ")} (${Math.floor(elapsedMs / 1000)}s).`;
+    },
+    projectProgress: (current) => ({ machine: projectMachine(current) }),
+    poll: async ({ signal }) =>
+      context.fetch(`/v1/workflows/compute/nodes/${encodeURIComponent(machineId(machine))}`, {
+        signal,
+      }),
+  });
+}
+
+function waitExecution(
+  interaction,
+  machine,
+  waitOutcome,
+  { acceptedPhase = "accepted", data = {}, recoveryCommand, successLines }
+) {
+  const id = machineId(machine);
+  const resume = { kind: "machine", ref: id };
+  const resultData = { ...data, machine: projectMachine(machine) };
+  if (waitOutcome.kind === "ready") {
+    return interaction.result({
+      data: resultData,
+      outcome: { class: "ready", phase: "ssh_ready" },
+      resume,
+      presentation: {
+        lines: [
+          ...(successLines ?? [
+            `Machine is SSH-ready: ${machineHostname(machine) || "selected machine"}`,
+          ]),
+        ],
+        next: "ornn connect",
+      },
+    });
+  }
+  if (waitOutcome.kind === "timeout") {
+    return interaction.result({
+      action: {
+        command: `ornn machines wait ${id} --timeout 10m`,
+        description: "Resume the exact machine readiness wait",
+        type: "command",
+      },
+      data: resultData,
+      errors: [
+        {
+          code: "wait_timeout",
+          message: "The local wait timed out; remote work was not canceled.",
+          retryable: true,
+        },
+      ],
+      exitCode: 124,
+      outcome: { class: "working", phase: acceptedPhase },
+      resume,
+      presentation: {
+        lines: ["The selected machine is not SSH-ready yet. Remote work continues."],
+        next: "ornn machines wait --guided",
+      },
+    });
+  }
+  if (waitOutcome.kind === "interrupted") {
+    return interaction.result({
+      action: {
+        command: `ornn machines wait ${id} --timeout 10m`,
+        description: "Resume the exact machine readiness wait",
+        type: "command",
+      },
+      data: resultData,
+      errors: [
+        {
+          code: "interrupted",
+          message: "The local wait was interrupted; remote work was not canceled.",
+          retryable: true,
+        },
+      ],
+      exitCode: 130,
+      outcome: { class: "working", phase: acceptedPhase },
+      resume,
+      presentation: {
+        lines: ["Stopped waiting for the selected machine. Remote work continues."],
+        next: "ornn machines wait --guided",
+      },
+    });
+  }
+  return interaction.result({
+    ...(recoveryCommand
+      ? {
+          action: {
+            command: recoveryCommand,
+            description: "Retry the failed machine operation with a new idempotency key",
+            type: "command",
+          },
+        }
+      : {}),
+    data: resultData,
+    errors: [
+      {
+        code: "machine_failed",
+        message:
+          text(machine.customer_lifecycle_error) ??
+          "The machine operation failed before SSH became ready.",
+        retryable: Boolean(recoveryCommand),
+      },
+    ],
+    exitCode: 1,
+    outcome: { class: "failed", phase: "operation_failed" },
+    resume,
+    presentation: {
+      lines: [
+        text(machine.customer_lifecycle_error)
+          ? `Machine operation failed: ${text(machine.customer_lifecycle_error)}.`
+          : `The selected machine entered ${machineState(machine)}.`,
+      ],
+      ...(recoveryCommand ? { next: recoveryCommand } : {}),
+    },
+  });
+}
+
+async function listMachines(input, context, interaction) {
+  positional(
+    input,
+    0,
+    "ornn machines list [--limit <1-500>] [--cursor <opaque-cursor>]",
+    interaction
+  );
+  const rows = (await listOwnedActiveMachines(context, interaction))
+    .filter((machine) => machineId(machine))
+    .sort((left, right) => machineId(left).localeCompare(machineId(right)));
+  const selected = machineCursorPage(rows, input, interaction);
+  return interaction.result({
+    data: { machines: selected.items.map(projectMachine) },
+    outcome: { class: "ready", phase: selected.items.length ? "listed" : "empty" },
+    page: selected.page,
+    presentation: {
+      lines: selected.items.length
+        ? selected.items.flatMap(machineLines)
+        : ["No direct machines found."],
+      ...(selected.page.next_cursor
+        ? { next: `ornn machines list --cursor ${selected.page.next_cursor}` }
+        : {}),
+    },
+  });
+}
+
+async function showMachine(input, context, interaction) {
+  const machine = await resolveMachineCommandTarget(
+    input,
+    context,
+    interaction,
+    "ornn machines show <canonical-machine-id|exact-hostname> [--guided]"
+  );
+  return interaction.result({
+    data: { machine: projectMachine(machine) },
+    outcome: machineLifecycle(machine),
+    resume: { kind: "machine", ref: machineId(machine) },
+    presentation: {
+      lines: machineLines(machine),
+      ...(machineReachability(machine).class === "ready"
+        ? { next: "ornn connect" }
+        : { next: "ornn machines wait --guided" }),
+    },
+  });
+}
+
+async function waitMachine(input, context, interaction) {
+  validateWaitInput(input, interaction, { waitCommand: true });
+  const machine = await resolveMachineCommandTarget(
+    input,
+    context,
+    interaction,
+    "ornn machines wait <canonical-machine-id|exact-hostname> [--guided] [--timeout <duration>]"
+  );
+  const timeout = text(input.timeout) ?? "10m";
+  let waitOutcome;
+  try {
+    waitOutcome = await waitForMachine(context, interaction, machine, timeout, "machines wait");
+  } catch (error) {
+    return acceptedWaitFailure(interaction, error, {
+      data: {
+        machine: projectMachine(machine),
+        wait: { enabled: true, timeout },
+      },
+      label: "machine readiness",
+      phase: "ssh_pending",
+      resume: { kind: "machine", ref: machineId(machine) },
+      retryCommand: `ornn machines wait ${machineId(machine)} --timeout ${timeout}`,
+    });
+  }
+  return waitExecution(interaction, waitOutcome.value, waitOutcome, {
+    acceptedPhase: "ssh_pending",
+    recoveryCommand: failedOperationRecoveryCommand(waitOutcome.value, interaction),
+    data: { wait: { enabled: true, timeout } },
+  });
+}
+
+function directMachineSnapshot(machines, relationships, keys) {
+  return JSON.stringify({
+    keys: keys.map(resourceId).sort(),
+    machines: machines
+      .map((machine) => ({
+        id: machineId(machine),
+        mode: machineAccessMode(machine),
+        network: text(machine.network_mode),
+        username: machineUsername(machine),
+      }))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    relationships,
+  });
+}
+
+async function guidedSwitchReservation(context, interaction) {
+  const reservations = await listActiveDirectReservations(context, interaction);
+  if (!reservations.length) {
+    interaction.error("No active direct-machine reservation is available to switch.", {
+      code: "no_active_reservation",
+    });
+  }
+  let reference = resourceId(reservations[0]);
+  if (reservations.length > 1) {
+    reference = await interaction.ask({
+      label: "Capacity reservation",
+      choices: reservations.map((reservation) => ({
+        label: reservationLabel(reservation),
+        value: resourceId(reservation),
+      })),
+    });
+  }
+  return assertActiveReservation(
+    await context.fetch(`/v1/workflows/commerce/reservations/${encodeURIComponent(reference)}`),
+    reference,
+    interaction
+  );
+}
+
+async function switchMachine(input, context, interaction) {
+  requireMachineMutationSafety(input, interaction);
+  const values = Array.isArray(input.$positionals) ? input.$positionals : [];
+  if (input.guided && !interaction.eligibleHuman) {
+    interaction.usage("--guided requires an eligible interactive terminal.", {
+      code: "guided_unavailable",
+      field: "guided",
+    });
+  }
+  if (values.length > 1 || (values.length === 0 && input.guided !== true)) {
+    interaction.usage(
+      "Usage: ornn machines switch <canonical-reservation-id> [--mode vm|bare-metal] [--network public|private] [--erase-local-data]",
+      { code: values.length > 1 ? "target_conflict" : "missing_input", field: "reservation" }
+    );
+  }
+  const suppliedReservation = text(values[0]);
+  if (interaction.machine && suppliedReservation && !CANONICAL_ID.test(suppliedReservation)) {
+    interaction.usage("Automation must use a canonical capacity-reservation identifier.", {
+      code: "invalid_reference",
+      field: "reservation",
+    });
+  }
+  const requestedMode = directMode(input.mode, interaction, { optional: true });
+  const requestedNetwork = networkMode(input.network, interaction, { optional: true });
+  if (!requestedMode && !requestedNetwork) {
+    interaction.usage("machines switch requires --mode, --network, or both.", {
+      code: "switch_goal_required",
+    });
+  }
+  const reservation = suppliedReservation
+    ? assertActiveReservation(
+        await context.fetch(
+          `/v1/workflows/commerce/reservations/${encodeURIComponent(suppliedReservation)}`
+        ),
+        suppliedReservation,
+        interaction
+      )
+    : await guidedSwitchReservation(context, interaction);
+  const reservationId = resourceId(reservation);
+  if (!isDirectReservation(reservation)) {
+    interaction.error("machines switch accepts only a direct VM or Bare Metal reservation.", {
+      code: "reservation_not_direct",
+    });
+  }
+  const [machines, relationships, keys] = await Promise.all([
+    fetchMachines(context, reservationId),
+    bareMetalRelationships(context, reservationId),
+    fetchAssignedKeys(context, reservationId),
+  ]);
+  if (machines.length !== 1) {
+    interaction.error(
+      "machines switch requires exactly one active direct machine on the capacity reservation.",
+      {
+        code: machines.length ? "machine_ambiguous" : "machine_not_found",
+      }
+    );
+  }
+  if (!keys.length) {
+    interaction.error("The capacity reservation has no SSH-key assignment to preserve.", {
+      code: "ssh_key_assignment_missing",
+    });
+  }
+  const currentMode = machineAccessMode(machines[0]);
+  if (!["vm", "bare-metal"].includes(currentMode)) {
+    interaction.error("The selected resource is not a direct VM or Bare Metal machine.", {
+      code: "invalid_access_mode",
+    });
+  }
+  const currentNetwork = text(machines[0].network_mode) ?? "public";
+  const targetMode = requestedMode ?? currentMode;
+  const targetNetwork = requestedNetwork ?? currentNetwork;
+  const erasesLocalData = targetMode !== currentMode;
+  if (erasesLocalData && input.eraseLocalData !== true) {
+    interaction.usage(
+      "Changing between VM and Bare Metal permanently erases source-local data and requires --erase-local-data; --yes cannot infer destructive scope.",
+      { code: "erase_local_data_required", field: "eraseLocalData" }
+    );
+  }
+  const wait = {
+    enabled: shouldWaitForMutation(input, interaction),
+    timeout: shouldWaitForMutation(input, interaction) ? (text(input.timeout) ?? "10m") : null,
+  };
+  if (targetMode === currentMode && targetNetwork === currentNetwork) {
+    return interaction.result({
+      data: {
+        machine: projectMachine(machines[0]),
+        mode: targetMode,
+        network_mode: targetNetwork,
+        retained_ssh_keys: keys.map(projectKey),
+        relationships,
+        replayed: true,
+        wait,
+      },
+      outcome:
+        machineReachability(machines[0]).class === "ready"
+          ? { class: "ready", phase: "ssh_ready" }
+          : { class: "working", phase: "switch_accepted" },
+      resume: { kind: "machine", ref: machineId(machines[0]) },
+      presentation: {
+        lines: ["The machine already satisfies the requested switch goal."],
+        next: "ornn connect",
+      },
+    });
+  }
+  const snapshot = directMachineSnapshot(machines, relationships, keys);
+  const accepted = await interaction.review({
+    title: "Machine switch review",
+    terms: [
+      { label: "Capacity reservation", value: reservationId },
+      {
+        label: "Access mode",
+        value: requestedMode ? `${currentMode} to ${targetMode}` : `${currentMode} (unchanged)`,
+      },
+      {
+        label: "Network",
+        value: requestedNetwork
+          ? `${currentNetwork} to ${targetNetwork}`
+          : `${currentNetwork} (unchanged)`,
+      },
+      {
+        label: "SSH keys",
+        value: `${keys.length} assigned key${keys.length === 1 ? "" : "s"} retained`,
+      },
+      { label: "Volume mount", value: relationshipLabel(relationships, "storage") },
+      {
+        label: "Local data",
+        value: erasesLocalData
+          ? "ERASED permanently under explicit --erase-local-data scope"
+          : "Preserved",
+      },
+      {
+        label: "Consequence",
+        value: "SSH is interrupted until the requested goal is ready",
+      },
+    ],
+    prompt: "Apply this machine switch?",
+  });
+  if (!accepted) {
+    return interaction.result({
+      errors: [{ code: "declined", message: "Machine switch declined.", retryable: false }],
+      exitCode: 1,
+      outcome: { class: "ended", phase: "declined" },
+      presentation: { lines: ["Machine switch declined. No change was submitted."] },
+    });
+  }
+  const [currentReservationValue, currentMachines, currentRelationships, currentKeys] =
+    await Promise.all([
+      context.fetch(`/v1/workflows/commerce/reservations/${encodeURIComponent(reservationId)}`),
+      fetchMachines(context, reservationId),
+      bareMetalRelationships(context, reservationId),
+      fetchAssignedKeys(context, reservationId),
+    ]);
+  const currentReservation = assertActiveReservation(
+    currentReservationValue,
+    reservationId,
+    interaction
+  );
+  if (
+    reservationLabel(currentReservation) !== reservationLabel(reservation) ||
+    directMachineSnapshot(currentMachines, currentRelationships, currentKeys) !== snapshot
+  ) {
+    interaction.error("Machine access, network, volume, or SSH-key intent changed after review.", {
+      code: "machine_switch_stale",
+    });
+  }
+  const idempotencyKey = text(input.idempotencyKey) ?? interaction.idempotencyKey();
+  const body = {
+    ...(requestedMode
+      ? { access_mode: requestedMode === "vm" ? "virtual-machine" : "bare-metal" }
+      : {}),
+    ...(requestedNetwork ? { network_mode: requestedNetwork } : {}),
+    ...(erasesLocalData ? { erase_local_data: true } : {}),
+    machine_count: machines.length,
+    request_id: idempotencyKey,
+    ssh_key_ids: keys.map(resourceId),
+  };
+  const retryCommand = [
+    "ornn machines switch",
+    shellQuote(reservationId),
+    requestedMode ? `--mode ${requestedMode}` : null,
+    requestedNetwork ? `--network ${requestedNetwork}` : null,
+    erasesLocalData ? "--erase-local-data" : null,
+    "--yes",
+    "--no-wait",
+    `--idempotency-key ${shellQuote(idempotencyKey)}`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  let response;
+  try {
+    response = await context.fetch(
+      `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/switch-access`,
+      { method: "POST", body }
+    );
+  } catch (error) {
+    return uncertainMutationFailure(interaction, error, {
+      data: {
+        mode: targetMode,
+        network_mode: targetNetwork,
+        erased_local_data: erasesLocalData,
+        request_id: idempotencyKey,
+      },
+      label: "machine switch",
+      phase: "switch_submission_unknown",
+      resume: { kind: "machine", ref: machineId(machines[0]) },
+      retryCommand,
+    });
+  }
+  const responseSource = record(response);
+  const switched = activeMachines(
+    Array.isArray(responseSource.machines)
+      ? responseSource.machines.map(record)
+      : await fetchMachines(context, reservationId)
+  );
+  if (switched.length !== 1) {
+    interaction.error("The switch response did not preserve one exact machine.", {
+      code: "machine_correlation_failed",
+      retryable: true,
+    });
+  }
+  let machine = switched[0];
+  const operation = record(
+    Array.isArray(responseSource.operations) ? responseSource.operations[0] : null
+  );
+  const targetReference = text(operation.node_id) ?? text(machine.node_id) ?? machineId(machine);
+  const data = {
+    mode: targetMode,
+    network_mode: targetNetwork,
+    retained_ssh_keys: keys.map(projectKey),
+    relationships,
+    erased_local_data: erasesLocalData,
+    replayed: false,
+    request_id: idempotencyKey,
+    wait,
+  };
+  if (!wait.enabled) {
+    return interaction.result({
+      data: { ...data, machine: projectMachine(machine) },
+      outcome:
+        machineReachability(machine).class === "ready"
+          ? { class: "ready", phase: "ssh_ready" }
+          : { class: "working", phase: "switch_accepted" },
+      resume: { kind: "machine", ref: targetReference },
+      presentation: {
+        lines: ["Machine switch accepted."],
+        next: "ornn machines wait --guided",
+      },
+    });
+  }
+  const waiting = {
+    ...record(machine),
+    id: targetReference,
+    instance_id: targetReference,
+    node_id: text(operation.node_id) ?? text(machine.node_id),
+    state: "switching",
+    status: "switching",
+    ssh_endpoint: null,
+  };
+  let waitOutcome;
+  try {
+    waitOutcome = await waitForMachine(
+      context,
+      interaction,
+      waiting,
+      wait.timeout,
+      "machines switch"
+    );
+  } catch (error) {
+    return acceptedWaitFailure(interaction, error, {
+      data: { ...data, machine: projectMachine(waiting) },
+      label: "machine switch",
+      phase: "switch_accepted",
+      resume: { kind: "machine", ref: machineId(waiting) },
+      retryCommand: `ornn machines wait ${machineId(waiting)} --timeout ${wait.timeout}`,
+    });
+  }
+  machine = waitOutcome.value;
+  const finalRelationships = await bareMetalRelationships(context, reservationId);
+  const failedRecoveryCommand = [
+    "ornn machines switch",
+    shellQuote(reservationId),
+    `--mode ${targetMode}`,
+    `--network ${targetNetwork}`,
+    erasesLocalData ? "--erase-local-data" : null,
+    "--yes",
+    `--idempotency-key ${shellQuote(interaction.idempotencyKey())}`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  if (
+    machineAccessMode(machine) !== targetMode ||
+    text(machine.network_mode)?.toLowerCase() !== targetNetwork
+  ) {
+    return interaction.result({
+      action: {
+        command: failedRecoveryCommand,
+        description: "Retry the switch with a new idempotency key.",
+        type: "command",
+      },
+      data: { ...data, machine: projectMachine(machine), relationships: finalRelationships },
+      errors: [
+        {
+          code: "switch_goal_not_applied",
+          message: "The machine became reachable without the reviewed access and network goal.",
+          retryable: true,
+          resource_ref: reservationId,
+        },
+      ],
+      exitCode: 4,
+      outcome: { class: "failed", phase: "switch_goal_not_applied" },
+      presentation: {
+        lines: ["Machine is reachable, but the reviewed switch goal is not applied."],
+        next: failedRecoveryCommand,
+      },
+      resume: { kind: "machine", ref: machineId(machine) },
+    });
+  }
+  return waitExecution(interaction, machine, waitOutcome, {
+    acceptedPhase: "switch_accepted",
+    data: { ...data, relationships: finalRelationships },
+    recoveryCommand: failedRecoveryCommand,
+    successLines: [
+      `Machine switch is SSH-ready: ${machineHostname(machine) || machineId(machine)}`,
+    ],
+  });
+}
+
+async function maintainMachine(command, input, context, interaction) {
+  const destructive = command === "reset";
+  requireMachineMutationSafety(input, interaction, { destructive });
+  const machine = await resolveMachineCommandTarget(
+    input,
+    context,
+    interaction,
+    `ornn machines ${command} <canonical-machine-id|exact-hostname>${destructive ? " --erase-local-data" : ""} [--no-wait]`
+  );
+  if (TERMINAL_MACHINE_STATES.has(machineState(machine))) {
+    interaction.error("A terminal machine cannot be rebooted or reset.", {
+      code: "machine_terminal",
+    });
+  }
+  const accepted = await interaction.review({
+    title: destructive ? "Machine reset review" : "Machine reboot review",
+    terms: [
+      {
+        label: "Machine",
+        value: `${machineHostname(machine) || "unnamed"} (${machineId(machine)})`,
+      },
+      { label: "Access mode", value: machineAccessMode(machine) ?? "unreported" },
+      { label: "Access", value: "SSH will be interrupted until the machine is ready again" },
+      {
+        label: "Local data",
+        value: destructive
+          ? "ERASED permanently under explicit --erase-local-data scope"
+          : "Preserved",
+      },
+      {
+        label: "SSH keys",
+        value: destructive ? "Restored after the machine reconnects" : "Preserved",
+      },
+      {
+        label: "External volume",
+        value: destructive
+          ? "Relationship preserved; local data is still erased"
+          : "Relationship preserved",
+      },
+    ],
+    prompt: destructive ? "Erase local data and reset this machine?" : "Reboot this machine?",
+  });
+  if (!accepted) {
+    return interaction.result({
+      errors: [
+        {
+          code: "declined",
+          message: destructive ? "Machine reset declined." : "Machine reboot declined.",
+          retryable: false,
+        },
+      ],
+      exitCode: 1,
+      outcome: { class: "ended", phase: "declined" },
+      presentation: {
+        lines: [`Machine ${destructive ? "reset" : "reboot"} declined. No change was submitted.`],
+      },
+    });
+  }
+  const current = await context.fetch(
+    `/v1/workflows/compute/nodes/${encodeURIComponent(machineId(machine))}`
+  );
+  if (
+    machineId(current) !== machineId(machine) ||
+    machineAccessMode(current) !== machineAccessMode(machine) ||
+    machineState(current) !== machineState(machine)
+  ) {
+    interaction.error("The machine changed after review; maintenance was not submitted.", {
+      code: "machine_maintenance_stale",
+    });
+  }
+  const idempotencyKey = text(input.idempotencyKey) ?? interaction.idempotencyKey();
+  const maintenanceRetryCommand = [
+    `ornn machines ${command}`,
+    shellQuote(machineId(machine)),
+    destructive ? "--erase-local-data" : null,
+    "--yes",
+    "--no-wait",
+    `--idempotency-key ${shellQuote(idempotencyKey)}`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  let response;
+  try {
+    response = record(
+      await context.fetch(
+        `/v1/workflows/compute/nodes/${encodeURIComponent(machineId(machine))}/reboot`,
+        {
+          method: "POST",
+          body: {
+            mode: destructive ? "hard_reset" : "reboot",
+            request_id: idempotencyKey,
+            erase_local_data: destructive,
+          },
+        }
+      )
+    );
+  } catch (error) {
+    return uncertainMutationFailure(interaction, error, {
+      data: {
+        operation: destructive ? "reset" : "reboot",
+        erased_local_data: destructive,
+        request_id: idempotencyKey,
+      },
+      label: `machine ${destructive ? "reset" : "reboot"}`,
+      phase: destructive ? "reset_submission_unknown" : "reboot_submission_unknown",
+      resume: { kind: "machine", ref: machineId(machine) },
+      retryCommand: maintenanceRetryCommand,
+    });
+  }
+  const wait = {
+    enabled: shouldWaitForMutation(input, interaction),
+    timeout: shouldWaitForMutation(input, interaction) ? (text(input.timeout) ?? "10m") : null,
+  };
+  const data = {
+    operation: destructive ? "reset" : "reboot",
+    request_id: idempotencyKey,
+    packet_id: text(response.packet_id),
+    erased_local_data: destructive,
+    preserved: {
+      external_volume_relationship: true,
+      network_relationship: true,
+      ssh_keys: true,
+    },
+    wait,
+  };
+  const resume = { kind: "machine", ref: machineId(machine) };
+  if (!wait.enabled) {
+    return interaction.result({
+      data: { ...data, machine: projectMachine(machine) },
+      outcome: {
+        class: "working",
+        phase: destructive ? "reset_accepted" : "reboot_accepted",
+      },
+      resume,
+      presentation: {
+        lines: [`Machine ${destructive ? "reset" : "reboot"} accepted.`],
+        next: "ornn machines wait --guided",
+      },
+    });
+  }
+  const waiting = {
+    ...record(machine),
+    state: destructive ? "resetting" : "rebooting",
+    status: destructive ? "resetting" : "rebooting",
+    ssh_endpoint: null,
+  };
+  let waitOutcome;
+  try {
+    waitOutcome = await waitForMachine(
+      context,
+      interaction,
+      waiting,
+      wait.timeout,
+      `machines ${command}`
+    );
+  } catch (error) {
+    return acceptedWaitFailure(interaction, error, {
+      data: { ...data, machine: projectMachine(waiting) },
+      label: `machine ${destructive ? "reset" : "reboot"}`,
+      phase: destructive ? "reset_accepted" : "reboot_accepted",
+      resume,
+      retryCommand: `ornn machines wait ${machineId(waiting)} --timeout ${wait.timeout}`,
+    });
+  }
+  const failedRecoveryCommand = [
+    `ornn machines ${command}`,
+    shellQuote(machineId(waitOutcome.value)),
+    destructive ? "--erase-local-data" : null,
+    "--yes",
+    `--idempotency-key ${shellQuote(interaction.idempotencyKey())}`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return waitExecution(interaction, waitOutcome.value, waitOutcome, {
+    acceptedPhase: destructive ? "reset_accepted" : "reboot_accepted",
+    data,
+    recoveryCommand: failedRecoveryCommand,
+    successLines: [
+      `Machine ${destructive ? "reset" : "reboot"} completed; SSH is ready: ${machineHostname(waitOutcome.value) || machineId(waitOutcome.value)}`,
+    ],
+  });
+}
+
+export async function executeMachineCommand(command, input, context, interaction) {
+  if (command === "list") return listMachines(input, context, interaction);
+  if (command === "show") return showMachine(input, context, interaction);
+  if (command === "wait") return waitMachine(input, context, interaction);
+  if (command === "switch") return switchMachine(input, context, interaction);
+  if (command === "reboot" || command === "reset") {
+    return maintainMachine(command, input, context, interaction);
+  }
+  throw new Error(`Unsupported machine command: ${command}`);
+}
+
+function cursorPage(items, input, interaction) {
+  const limit = Number.isSafeInteger(input.limit) ? input.limit : 50;
+  const cursor = text(input.cursor);
+  let offset = 0;
+  if (cursor) {
+    let after;
+    try {
+      if (!/^[A-Za-z0-9_-]+$/.test(cursor)) throw new Error("invalid cursor");
+      const decoded = record(JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")));
+      if (decoded.version !== 1) throw new Error("unsupported cursor");
+      after = text(decoded.after);
+    } catch {
+      interaction.usage("The SSH-key cursor is invalid or stale.", {
+        code: "invalid_cursor",
+        field: "cursor",
+      });
+    }
+    const index = items.findIndex((item) => resourceId(item) === after);
+    if (index === -1)
+      interaction.usage("The SSH-key cursor is invalid or stale.", {
+        code: "invalid_cursor",
+        field: "cursor",
+      });
+    offset = index + 1;
+  }
+  const pageItems = items.slice(offset, offset + limit);
+  const last = pageItems.at(-1);
+  return {
+    items: pageItems,
+    page: {
+      limit,
+      returned: pageItems.length,
+      next_cursor:
+        offset + limit < items.length && last
+          ? Buffer.from(JSON.stringify({ version: 1, after: resourceId(last) })).toString(
+              "base64url"
+            )
+          : null,
+    },
+  };
+}
+
+function keyLines(keys, heading) {
+  return [
+    heading,
+    ...(keys.length
+      ? keys.map((key) =>
+          `  ${text(key.label) ?? "SSH key"} (${resourceId(key)}) ${text(key.fingerprint) ?? ""}`.trimEnd()
+        )
+      : ["  none"]),
+  ];
+}
+
+async function resolveExistingKey(
+  context,
+  input,
+  interaction,
+  { absentCanonicalIsSuccess = false } = {}
+) {
+  const reference = text(input.keyId) ?? text(input.key) ?? text(input.$positionals?.[0]);
+  if (!reference)
+    interaction.usage("An SSH-key reference is required.", { code: "missing_input", field: "key" });
+  if (interaction.machine && !CANONICAL_ID.test(reference)) {
+    interaction.usage("Automation must use a canonical SSH-key identifier.", {
+      code: "invalid_reference",
+      field: "key",
+    });
+  }
+  const matches = (await fetchOrganizationKeys(context)).filter(
+    (key) =>
+      resourceId(key) === reference || (!interaction.machine && text(key.label) === reference)
+  );
+  if (!matches.length && absentCanonicalIsSuccess && CANONICAL_ID.test(reference)) return null;
+  if (matches.length !== 1) {
+    interaction.error(
+      matches.length
+        ? `More than one SSH key has the exact label "${reference}".`
+        : `SSH key not found: ${reference}.`,
+      { code: matches.length ? "ssh_key_ambiguous" : "ssh_key_not_found" }
+    );
+  }
+  return matches[0];
+}
+
+function reservationPosition(input, interaction) {
+  const [reservationId] = positional(
+    input,
+    1,
+    "ornn ssh-keys assignments <list|assign|sync|status> <canonical-reservation-id>",
+    interaction
+  );
+  return requireCanonical(interaction, reservationId, "reservation", "Capacity reservation");
+}
+
+export async function executeSshKeyCommand(command, input, context, interaction) {
+  if (command === "list") {
+    positional(input, 0, "ornn ssh-keys list [--limit <1-500>] [--cursor <cursor>]", interaction);
+    const keys = fetchOrganizationKeys(context).then((rows) =>
+      rows.sort((left, right) => String(resourceId(left)).localeCompare(String(resourceId(right))))
+    );
+    const page = cursorPage(await keys, input, interaction);
+    return interaction.result({
+      data: { ssh_keys: page.items.map(projectKey) },
+      page: page.page,
+      presentation: { lines: keyLines(page.items, "Organization SSH keys") },
+    });
+  }
+
+  if (command === "add") {
+    positional(input, 0, "ornn ssh-keys add --public-key-file <path> --label <label>", interaction);
+    machineMutationPreflight(input, interaction, { requireYes: false });
+    if (interaction.machine && !text(input.publicKey) && !text(input.publicKeyFile)) {
+      interaction.usage("--public-key or --public-key-file is required for automation.", {
+        code: "missing_input",
+        field: "publicKey",
+      });
+    }
+    if (interaction.machine && !text(input.label)) {
+      interaction.usage("--label is required when adding an SSH key in automation.", {
+        code: "missing_input",
+        field: "label",
+      });
+    }
+    input = await normalizePublicKeyInput(input);
+    const plan = await keyPlanFromInput(context, input, interaction);
+    if (plan.kind === "existing") {
+      return interaction.result({
+        data: { ssh_key: projectKey(plan.key), replayed: true },
+        presentation: {
+          lines: [`SSH key already exists: ${text(plan.key.label) ?? resourceId(plan.key)}`],
+        },
+      });
+    }
+    const key = await materializeKey(
+      context,
+      plan,
+      interaction,
+      text(input.idempotencyKey) ?? interaction.idempotencyKey()
+    );
+    return interaction.result({
+      data: { ssh_key: projectKey(key), replayed: false },
+      presentation: { lines: [`SSH key added: ${text(key.label) ?? resourceId(key)}`] },
+    });
+  }
+
+  if (command === "delete") {
+    const values = positional(
+      input,
+      1,
+      "ornn ssh-keys delete <exact-key-id-or-label>",
+      interaction
+    );
+    machineMutationPreflight(input, interaction);
+    const key = await resolveExistingKey(context, { ...input, $positionals: values }, interaction, {
+      absentCanonicalIsSuccess: interaction.machine,
+    });
+    if (!key) {
+      return interaction.result({
+        data: {
+          replayed: true,
+          ssh_key: { fingerprint: null, id: values[0], label: null, status: "revoked" },
+        },
+        outcome: { class: "ended", phase: "deleted" },
+        presentation: { lines: [`SSH key is already absent: ${values[0]}`] },
+      });
+    }
+    const accepted = await interaction.review({
+      title: "Delete SSH key",
+      terms: [
+        { label: "SSH key", value: `${text(key.label) ?? "SSH key"} (${resourceId(key)})` },
+        {
+          label: "Consequence",
+          value: "Future machine access using this organization key may end",
+        },
+      ],
+      prompt: "Delete this SSH key?",
+    });
+    if (!accepted) {
+      return interaction.result({
+        errors: [{ code: "declined", message: "SSH-key deletion declined.", retryable: false }],
+        exitCode: 1,
+        outcome: { class: "ended", phase: "declined" },
+        presentation: { lines: ["SSH-key deletion declined."] },
+      });
+    }
+    await context.fetch(
+      `/v1/workflows/compute/nodes/organizations/me/ssh-keys/${encodeURIComponent(resourceId(key))}`,
+      {
+        method: "DELETE",
+        headers: { "Idempotency-Key": text(input.idempotencyKey) ?? interaction.idempotencyKey() },
+      }
+    );
+    return interaction.result({
+      data: { ssh_key: projectKey(key) },
+      outcome: { class: "ended", phase: "deleted" },
+      presentation: { lines: [`SSH key deleted: ${text(key.label) ?? resourceId(key)}`] },
+    });
+  }
+
+  const reservationId = reservationPosition(input, interaction);
+  if (command === "assignments.list") {
+    const keys = (await fetchAssignedKeys(context, reservationId)).sort((left, right) =>
+      String(resourceId(left)).localeCompare(String(resourceId(right)))
+    );
+    const page = cursorPage(keys, input, interaction);
+    return interaction.result({
+      data: { reservation_id: reservationId, ssh_keys: page.items.map(projectKey) },
+      page: page.page,
+      presentation: { lines: keyLines(page.items, `SSH keys assigned to ${reservationId}`) },
+    });
+  }
+
+  if (command === "assignments.status") {
+    const [keys, machines] = await Promise.all([
+      fetchAssignedKeys(context, reservationId),
+      fetchMachines(context, reservationId),
+    ]);
+    keys.sort((left, right) => String(resourceId(left)).localeCompare(String(resourceId(right))));
+    const page = cursorPage(keys, input, interaction);
+    const status = assignmentStatus(reservationId, page.items, machines);
+    const lines = [`SSH-key delivery for ${reservationId}`];
+    for (const key of status.keys) {
+      lines.push(`  ${key.label ?? key.id}`);
+      for (const machine of key.machines)
+        lines.push(`    ${machine.hostname ?? machine.machine_id}: ${machine.status}`);
+    }
+    if (!status.keys.length) lines.push("  no assigned SSH keys");
+    return interaction.result({ data: status, page: page.page, presentation: { lines } });
+  }
+
+  machineMutationPreflight(input, interaction);
+  const idempotencyKey = text(input.idempotencyKey) ?? interaction.idempotencyKey();
+  if (command === "assignments.assign") {
+    const key = await resolveExistingKey(context, { ...input, $positionals: [] }, interaction);
+    const accepted = await interaction.review({
+      title: "Assign SSH key",
+      terms: [
+        { label: "Capacity reservation", value: reservationId },
+        { label: "SSH key", value: `${text(key.label) ?? "SSH key"} (${resourceId(key)})` },
+        {
+          label: "Delivery",
+          value: "Assignment is durable; installation on each machine may be delayed",
+        },
+      ],
+      prompt: "Assign this SSH key?",
+    });
+    if (!accepted) {
+      return interaction.result({
+        errors: [{ code: "declined", message: "SSH-key assignment declined.", retryable: false }],
+        exitCode: 1,
+        outcome: { class: "ended", phase: "declined" },
+        presentation: { lines: ["SSH-key assignment declined."] },
+      });
+    }
+    const assignment = await ensureAssignment(
+      context,
+      reservationId,
+      key,
+      idempotencyKey,
+      interaction
+    );
+    const machines = await fetchMachines(context, reservationId);
+    return interaction.result({
+      data: {
+        ...assignmentStatus(reservationId, [assignment.key], machines),
+        replayed: !assignment.created,
+      },
+      outcome: {
+        class: machines.length ? "working" : "ready",
+        phase: machines.length ? "delivery_pending" : "associated",
+      },
+      presentation: {
+        lines: [
+          `SSH key ${assignment.created ? "assigned" : "already assigned"}: ${text(key.label) ?? resourceId(key)}`,
+        ],
+        next: `ornn ssh-keys assignments status ${reservationId}`,
+      },
+    });
+  }
+
+  if (command === "assignments.sync") {
+    const [keys, machines] = await Promise.all([
+      fetchAssignedKeys(context, reservationId),
+      fetchMachines(context, reservationId),
+    ]);
+    if (!keys.length) {
+      interaction.error("No SSH keys are assigned to this capacity reservation.", {
+        code: "ssh_key_assignment_missing",
+      });
+    }
+    const accepted = await interaction.review({
+      title: "Synchronize SSH keys",
+      terms: [
+        { label: "Capacity reservation", value: reservationId },
+        { label: "SSH keys", value: String(keys.length) },
+        { label: "Active machines", value: String(machines.length) },
+        { label: "Delivery", value: "Queued delivery remains distinct from installed state" },
+      ],
+      prompt: "Queue SSH-key synchronization?",
+    });
+    if (!accepted) {
+      return interaction.result({
+        errors: [
+          { code: "declined", message: "SSH-key synchronization declined.", retryable: false },
+        ],
+        exitCode: 1,
+        outcome: { class: "ended", phase: "declined" },
+        presentation: { lines: ["SSH-key synchronization declined."] },
+      });
+    }
+    const deliveries = new Map();
+    for (const machine of machines) {
+      const id = machineId(machine);
+      const requestId = `${idempotencyKey}:${id}`;
+      try {
+        const queued = record(
+          await context.fetch(`/v1/workflows/compute/nodes/${encodeURIComponent(id)}/push-keys`, {
+            method: "POST",
+            body: {
+              request_id: requestId,
+              ssh_key_ids: keys.map(resourceId),
+            },
+          })
+        );
+        deliveries.set(id, {
+          failure_reason: null,
+          packet_id: text(queued.packet_id),
+          request_id: requestId,
+          status: "queued",
+        });
+      } catch {
+        deliveries.set(id, {
+          failure_reason: "SSH-key delivery could not be queued.",
+          packet_id: null,
+          request_id: requestId,
+          status: "failed",
+        });
+      }
+    }
+    const status = assignmentStatus(reservationId, keys, machines);
+    for (const key of status.keys) {
+      for (const machine of key.machines)
+        Object.assign(machine, deliveries.get(machine.machine_id));
+    }
+    const failed = [...deliveries.values()].filter(
+      (delivery) => delivery.status === "failed"
+    ).length;
+    const queued = deliveries.size - failed;
+    return interaction.result({
+      data: status,
+      errors: failed
+        ? [
+            {
+              code: "ssh_key_delivery_partial",
+              message: `SSH-key delivery could not be queued for ${failed} machine${failed === 1 ? "" : "s"}.`,
+              retryable: true,
+            },
+          ]
+        : [],
+      exitCode: failed ? 4 : 0,
+      outcome: failed
+        ? {
+            class: queued ? "partial" : "failed",
+            phase: queued ? "delivery_partial" : "delivery_failed",
+          }
+        : {
+            class: machines.length ? "working" : "ready",
+            phase: machines.length ? "delivery_queued" : "associated",
+          },
+      presentation: {
+        lines: [
+          `SSH-key synchronization queued for ${queued} machine${queued === 1 ? "" : "s"}${failed ? `; ${failed} failed` : ""}.`,
+        ],
+        next: `ornn ssh-keys assignments status ${reservationId}`,
+      },
+    });
+  }
+
+  throw new Error(`Unsupported SSH-key command: ${command}`);
+}