@ornncompute/cli 1.0.121 → 1.0.123

package/src/vm-commands.mjs

@@ -1,3 +1,4 @@
+import * as orchestrator from "../vendor/api-client/orchestrator.js";
 import * as gatewayApi from "../vendor/api-client/gateway.js";
 import { getReservation } from "../vendor/api-client/commerce.js";
 import { spawn as spawnProcessDefault } from "node:child_process";
@@ -63,20 +64,27 @@ function machineState(value) {
   ).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.provisioningType)?.toLowerCase() ?? null;
   return mode === "virtual-machine" ? "vm" : mode;
 }
 
+function directAccessMode(node, virtualMachine) {
+  if (virtualMachine) return "vm";
+  if (node.pending_access_mode === "virtual-machine") return "vm";
+  if (node.pending_access_mode === "bare-metal") return "bare-metal";
+  return node.status === "bare-metal" &&
+    node.keys_pushed_at &&
+    node.authorized_key_fingerprints?.length
+    ? "bare-metal"
+    : null;
+}
+
+function directAccess(node, virtualMachine) {
+  return virtualMachine ?? (node.pending_access_mode === "virtual-machine" ? null : node);
+}
+
 function isDirectReservation(value) {
   const mode = reservationAccessMode(value);
   return mode === "vm" || mode === "bare-metal";
@@ -85,10 +93,10 @@ function isDirectReservation(value) {
 function machineIsReady(value) {
   const machine = record(value);
   if (machine.health_readiness?.ready === false) return false;
+  if (machine.ready_at === null) return false;
   return (
     READY_MACHINE_STATES.has(machineState(machine)) ||
-    (["bare-metal", "virtual-machine"].includes(machineState(machine)) &&
-      machine.health_readiness?.ready === true)
+    (machineState(machine) === "bare-metal" && machine.health_readiness?.ready === true)
   );
 }
 
@@ -99,18 +107,24 @@ function machineLifecycle(value) {
   return { class: "working", phase: state };
 }
 
-export function machineReachability(value) {
+export function machineReachability(value, access = 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))) {
+  if (
+    TERMINAL_MACHINE_STATES.has(machineState(machine)) ||
+    TERMINAL_MACHINE_STATES.has(machineState(access))
+  ) {
     return { class: "failed", phase: "machine_terminal" };
   }
-  if (!machineIsReady(machine)) {
+  if (machine.pending_access_mode || ["pending", "rebooting"].includes(machine.cleanup_state)) {
+    return { class: "working", phase: "access_pending" };
+  }
+  if (!machineIsReady(machine) || !machineIsReady(access)) {
     return { class: "working", phase: "machine_not_ready" };
   }
-  if (!sshInvocation(machine)) return { class: "working", phase: "ssh_pending" };
+  if (!sshInvocation(access)) 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" };
@@ -253,17 +267,18 @@ function projectKey(value) {
   };
 }
 
-function projectMachine(value) {
+function projectMachine(value, virtualMachine = undefined) {
   const machine = record(value);
-  const reachability = machineReachability(machine);
+  const access = virtualMachine === undefined ? machine : virtualMachine;
+  const reachability = machineReachability(machine, access);
   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),
+    access_mode: directAccessMode(machine, virtualMachine),
+    network_mode: text(record(access).network_mode),
+    lifecycle: machineLifecycle(access),
     operation: {
       state: text(machine.customer_lifecycle_state),
       intent: Object.keys(lifecycleIntent).length > 0 ? lifecycleIntent : null,
@@ -271,9 +286,9 @@ function projectMachine(value) {
     },
     reachability,
     ssh: {
-      host: reachability.class === "ready" ? machineHost(machine) : null,
-      port: machinePort(machine),
-      user: machineUsername(machine),
+      host: reachability.class === "ready" ? machineHost(access) : null,
+      port: machinePort(access),
+      user: machineUsername(access),
     },
   };
 }
@@ -665,11 +680,7 @@ export async function materializeKey(context, plan, interaction, idempotencyKey)
 
 async function fetchAssignedKeys(context, reservationId) {
   return activeKeys(
-    keysFromPayload(
-      await context.fetch(
-        `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/ssh-keys`
-      )
-    )
+    keysFromPayload(await orchestrator.listReservationSshKeys(context.fetch, reservationId))
   );
 }
 
@@ -679,13 +690,11 @@ async function ensureAssignment(context, reservationId, key, idempotencyKey, int
   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 },
-      }
+    await orchestrator.addReservationSshKey(
+      context.fetch,
+      reservationId,
+      { ssh_key_id: keyId },
+      { headers: { "Idempotency-Key": idempotencyKey } }
     )
   );
   if (resourceId(created) !== keyId) {
@@ -699,13 +708,29 @@ async function ensureAssignment(context, reservationId, key, idempotencyKey, int
 async function fetchMachines(context, reservationId) {
   return activeMachines(
     machinesFromPayload(
-      await context.fetch(
-        `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/machines`
-      )
+      await orchestrator.listNodes(context.fetch, { reservation_id: reservationId })
     )
   );
 }
 
+function virtualMachinesForNode(payload, node) {
+  const virtualMachines = record(payload).virtual_machines;
+  if (!Array.isArray(virtualMachines)) throw new Error("Ornn returned invalid VM data.");
+  return virtualMachines.filter(
+    (vm) => vm.node_id === machineId(node) && !["deleted", "terminated"].includes(vm.status)
+  );
+}
+
+function virtualMachineForNode(payload, node, interaction) {
+  const matches = virtualMachinesForNode(payload, node);
+  if (matches.length > 1) {
+    interaction.error("This machine hosts multiple VMs; an exact VM is required for SSH.", {
+      code: "machine_ambiguous",
+    });
+  }
+  return matches[0] ?? null;
+}
+
 function keyDeliveryForMachine(key, machine) {
   const keyId = resourceId(key);
   const metadata = Array.isArray(machine.authorized_key_metadata)
@@ -745,8 +770,8 @@ function assignmentStatus(reservationId, keys, machines) {
   };
 }
 
-function isSshReady(machine, key) {
-  if (machineReachability(machine).class !== "ready") return false;
+function isSshReady(machine, key, access = machine) {
+  if (machineReachability(machine, access).class !== "ready") return false;
   const fingerprints = Array.isArray(machine.authorized_key_fingerprints)
     ? machine.authorized_key_fingerprints
     : null;
@@ -864,7 +889,7 @@ function isPreassignedUnlaunchedCapacity(machines, assignedKeys, reviewedKey) {
     ? machine.authorized_key_metadata
     : [];
   return (
-    machineAccessMode(machine) === "bare-metal" &&
+    machine.status === "bare-metal" &&
     fingerprints.length === 0 &&
     !text(machine.keys_pushed_at) &&
     delivery.length === 0
@@ -887,7 +912,7 @@ function withAuthoritativeUsername(input, _machines, interaction) {
 const UNSUPPORTED_USERNAME_MESSAGE =
   "--username cannot choose the Linux login; the machine reports its own login.";
 
-function validatedMachine(machines, key, input, interaction, expectedMode = "vm") {
+function validatedMachine(machines, key, input, interaction, expectedMode, reservation) {
   if (!machines.length) return null;
   if (machines.length !== 1) {
     interaction.error(
@@ -898,7 +923,7 @@ function validatedMachine(machines, key, input, interaction, expectedMode = "vm"
     );
   }
   const machine = machines[0];
-  if (machineAccessMode(machine) !== expectedMode) {
+  if (reservationAccessMode(reservation) !== expectedMode) {
     interaction.error(
       "The existing machine has a different access mode than the reviewed launch.",
       {
@@ -925,25 +950,29 @@ function validatedMachine(machines, key, input, interaction, expectedMode = "vm"
   return machine;
 }
 
-function machineReplayState(machines, key, input, interaction, expectedMode = "vm") {
-  const existing = validatedMachine(machines, key, input, interaction, expectedMode);
+function machineReplayState(machines, key, input, interaction, expectedMode, reservation, access) {
+  const existing = validatedMachine(machines, key, input, interaction, expectedMode, reservation);
   // 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,
+    machine:
+      existing && machineReachability(existing, access).class !== "working" ? existing : null,
     replayed: Boolean(existing),
   };
 }
 
-function launchData(reservationId, machine, key, waitPolicy, replayed) {
-  const invocation = sshInvocation(machine);
+function launchData(reservation, machine, key, waitPolicy, replayed, virtualMachine) {
+  const reservationId = text(reservation.reservationId);
+  const invocation = isSshReady(machine, key, virtualMachine)
+    ? sshInvocation(virtualMachine)
+    : null;
   return {
     mode: "vm",
     replayed,
     capacity_reservation: { id: reservationId, status: ACTIVE_RESERVATION },
-    machine: projectMachine(machine),
+    machine: projectMachine(machine, virtualMachine),
     ssh_key: projectKey(key),
     wait: waitPolicy,
     ssh_command: invocation ? commandText(invocation) : null,
@@ -1033,6 +1062,53 @@ function uncertainMutationFailure(
   });
 }
 
+function waitForMachine(
+  context,
+  interaction,
+  { node, virtualMachine, reservation, key, timeout, command, requireVirtualMachine = false, mode }
+) {
+  const access = (current) =>
+    requireVirtualMachine
+      ? current.virtualMachine
+      : directAccess(current.node, current.virtualMachine);
+  const isReady = (current) =>
+    (!mode || directAccessMode(current.node, current.virtualMachine) === mode) &&
+    isSshReady(current.node, key, access(current));
+  return interaction.waitForGoal({
+    command,
+    initial: { node, virtualMachine },
+    timeoutMs: timeoutMilliseconds(timeout, interaction),
+    isReady,
+    isTerminal: (current) =>
+      TERMINAL_MACHINE_STATES.has(machineState(current.node)) ||
+      TERMINAL_MACHINE_STATES.has(machineState(access(current))),
+    message: (current, elapsedMs) =>
+      isReady(current)
+        ? "The selected machine is SSH-ready."
+        : `The selected machine is ${machineState(access(current))}; waiting for SSH (${Math.floor(elapsedMs / 1000)}s).`,
+    projectProgress: (current) => ({
+      machine: projectMachine(
+        current.node,
+        access(current) === current.node ? undefined : current.virtualMachine
+      ),
+    }),
+    poll: async ({ signal }) => {
+      const [current, payload] = await Promise.all([
+        orchestrator.getNode(context.fetch, machineId(node), signal),
+        orchestrator.listReservationVirtualMachines(
+          context.fetch,
+          reservation.reservationId,
+          signal
+        ),
+      ]);
+      return {
+        node: current,
+        virtualMachine: virtualMachineForNode(payload, current, interaction),
+      };
+    },
+  });
+}
+
 export const vmLaunchModeHandler = {
   mode: "vm",
   async launch({ context, input, interaction }) {
@@ -1105,11 +1181,13 @@ export const vmLaunchModeHandler = {
       );
     }
     const idempotencyKey = text(input.idempotencyKey) ?? interaction.idempotencyKey();
-    const [existingAssigned, projectedMachines, currentRelationships] = await Promise.all([
-      fetchAssignedKeys(context, reservationId),
-      fetchMachines(context, reservationId),
-      bareMetalRelationships(context, reservationId),
-    ]);
+    const [existingAssigned, projectedMachines, currentRelationships, currentVirtualMachines] =
+      await Promise.all([
+        fetchAssignedKeys(context, reservationId),
+        fetchMachines(context, reservationId),
+        bareMetalRelationships(context, reservationId),
+        orchestrator.listReservationVirtualMachines(context.fetch, reservationId),
+      ]);
     const currentOwner = launchOwnerSnapshot(projectedMachines);
     if (
       JSON.stringify(currentOwner) !== JSON.stringify(reviewedOwner) ||
@@ -1136,7 +1214,20 @@ export const vmLaunchModeHandler = {
       );
     }
     const key = await materializeKey(context, keyPlan, interaction, idempotencyKey);
-    const replay = machineReplayState(existingMachines, key, input, interaction, "vm");
+    let virtualMachine = virtualMachineForNode(
+      currentVirtualMachines,
+      existingMachines[0],
+      interaction
+    );
+    const replay = machineReplayState(
+      existingMachines,
+      key,
+      input,
+      interaction,
+      "vm",
+      currentReservation,
+      virtualMachine
+    );
     let machine = replay.machine;
     if (
       replay.existing &&
@@ -1149,26 +1240,20 @@ export const vmLaunchModeHandler = {
     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",
-              disk_id: null,
-              machine_count: 1,
-              request_id: idempotencyKey,
-              ssh_key_ids: [resourceId(key)],
-              zone: null,
-            },
-          }
-        );
+        launch = await orchestrator.launchReservation(context.fetch, reservationId, {
+          access_mode: "virtual-machine",
+          network_mode: "public",
+          disk_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 active = activeMachines(discovered);
+        const candidate = active.length === 1 ? active[0] : null;
         const retryCommand = [
           "ornn",
           "launch",
@@ -1184,7 +1269,7 @@ export const vmLaunchModeHandler = {
         return uncertainMutationFailure(interaction, error, {
           data: {
             capacity_reservation: { id: reservationId },
-            machine: candidate ? projectMachine(candidate) : null,
+            machine: candidate ? projectMachine(candidate, null) : null,
             ssh_key: projectKey(key),
             wait: { enabled: shouldWait, timeout: text(input.timeout) ?? "10m" },
           },
@@ -1203,7 +1288,32 @@ export const vmLaunchModeHandler = {
           retryable: true,
         });
       }
-      machine = validatedMachine(launched, key, input, interaction, "vm");
+      machine = validatedMachine(launched, key, input, interaction, "vm", currentReservation);
+      try {
+        virtualMachine = virtualMachineForNode(
+          await orchestrator.listReservationVirtualMachines(context.fetch, reservationId),
+          machine,
+          interaction
+        );
+      } catch (error) {
+        return acceptedWaitFailure(interaction, error, {
+          data: launchData(
+            currentReservation,
+            machine,
+            key,
+            {
+              enabled: shouldWait,
+              timeout: shouldWait ? (text(input.timeout) ?? "10m") : null,
+            },
+            replay.replayed,
+            null
+          ),
+          label: "VM launch",
+          phase: "provisioning",
+          resume: { kind: "machine", ref: machineId(machine) },
+          retryCommand: `ornn connect ${machineId(machine)}`,
+        });
+      }
     }
 
     const waitPolicy = shouldWait
@@ -1211,9 +1321,16 @@ export const vmLaunchModeHandler = {
       : { enabled: false, timeout: null };
     const resume = { kind: "machine", ref: machineId(machine) };
     if (!shouldWait) {
-      const ready = isSshReady(machine, key);
+      const ready = isSshReady(machine, key, virtualMachine);
       return interaction.result({
-        data: launchData(reservationId, machine, key, waitPolicy, replay.replayed),
+        data: launchData(
+          currentReservation,
+          machine,
+          key,
+          waitPolicy,
+          replay.replayed,
+          virtualMachine
+        ),
         outcome: ready
           ? { class: "ready", phase: "ssh_ready" }
           : { class: "working", phase: "provisioning" },
@@ -1231,33 +1348,41 @@ export const vmLaunchModeHandler = {
 
     let waitOutcome;
     try {
-      waitOutcome = await interaction.waitForGoal({
+      waitOutcome = await waitForMachine(context, interaction, {
+        requireVirtualMachine: true,
+        node: machine,
+        virtualMachine,
+        reservation: currentReservation,
+        key,
+        timeout: input.timeout,
         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),
+        data: launchData(
+          currentReservation,
+          machine,
+          key,
+          waitPolicy,
+          replay.replayed,
+          virtualMachine
+        ),
         label: "VM launch",
         phase: "provisioning",
         resume,
         retryCommand: `ornn connect ${machineId(machine)}`,
       });
     }
-    machine = waitOutcome.value;
-    const data = launchData(reservationId, machine, key, waitPolicy, replay.replayed);
+    machine = waitOutcome.value.node;
+    virtualMachine = waitOutcome.value.virtualMachine;
+    const data = launchData(
+      currentReservation,
+      machine,
+      key,
+      waitPolicy,
+      replay.replayed,
+      virtualMachine
+    );
     if (waitOutcome.kind === "ready") {
       return interaction.result({
         data,
@@ -1997,25 +2122,26 @@ async function launchDurableBareMetalWorkspace({
   step = "bare_metal_machine";
   try {
     const existingMachines = await fetchMachines(context, reservationId);
-    const replay = machineReplayState(existingMachines, key, input, interaction, "bare-metal");
+    const replay = machineReplayState(
+      existingMachines,
+      key,
+      input,
+      interaction,
+      "bare-metal",
+      currentReservation
+    );
     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",
-            disk_id: null,
-            machine_count: 1,
-            network_mode: "private",
-            request_id: `${id}:machine`,
-            ssh_key_ids: [resourceId(key)],
-            zone: null,
-          },
-        }
-      );
+      const launch = await orchestrator.launchReservation(context.fetch, reservationId, {
+        access_mode: "bare-metal",
+        disk_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.", {
@@ -2023,7 +2149,14 @@ async function launchDurableBareMetalWorkspace({
           retryable: true,
         });
       }
-      machine = validatedMachine(launched, key, input, interaction, "bare-metal");
+      machine = validatedMachine(
+        launched,
+        key,
+        input,
+        interaction,
+        "bare-metal",
+        currentReservation
+      );
     }
     states.bare_metal_machine = {
       state: replayed ? "replayed" : "satisfied",
@@ -2092,9 +2225,7 @@ async function launchDurableBareMetalWorkspace({
       }),
       poll: async ({ signal }) => {
         const [currentMachine, currentMount] = await Promise.all([
-          context.fetch(`/v1/workflows/compute/nodes/${encodeURIComponent(machineId(machine))}`, {
-            signal,
-          }),
+          orchestrator.getNode(context.fetch, machineId(machine), signal),
           executeWorkspaceCapability(
             context,
             interaction,
@@ -2389,7 +2520,14 @@ export const bareMetalLaunchModeHandler = {
       );
     }
     const key = await materializeKey(context, keyPlan, interaction, idempotencyKey);
-    const replay = machineReplayState(existingMachines, key, input, interaction, "bare-metal");
+    const replay = machineReplayState(
+      existingMachines,
+      key,
+      input,
+      interaction,
+      "bare-metal",
+      currentReservation
+    );
     let machine = replay.machine;
     if (
       replay.existing &&
@@ -2414,15 +2552,12 @@ export const bareMetalLaunchModeHandler = {
           ssh_key_ids: [resourceId(key)],
           zone: null,
         };
-        launch = await context.fetch(
-          `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(reservationId)}/launch`,
-          { method: "POST", body: launchBody }
-        );
+        launch = await orchestrator.launchReservation(context.fetch, reservationId, 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 active = activeMachines(discovered);
+        const candidate = active.length === 1 ? active[0] : null;
         const retryCommand = [
           "ornn",
           "launch",
@@ -2461,7 +2596,14 @@ export const bareMetalLaunchModeHandler = {
           retryable: true,
         });
       }
-      machine = validatedMachine(launched, key, input, interaction, "bare-metal");
+      machine = validatedMachine(
+        launched,
+        key,
+        input,
+        interaction,
+        "bare-metal",
+        currentReservation
+      );
     }
 
     const waitPolicy = shouldWait
@@ -2507,10 +2649,7 @@ export const bareMetalLaunchModeHandler = {
             ? "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,
-          }),
+        poll: async ({ signal }) => orchestrator.getNode(context.fetch, machineId(machine), signal),
       });
     } catch (error) {
       return acceptedWaitFailure(interaction, error, {
@@ -2635,18 +2774,33 @@ async function spawnSsh(invocation, spawnProcess) {
 const directConnectResolutionCache = new WeakMap();
 const directConnectCandidatesCache = new WeakMap();
 
+function cachedDirectConnectCandidates(context, interaction) {
+  let candidates = directConnectCandidatesCache.get(context);
+  if (!candidates) {
+    candidates = listActiveDirectReservations(context, interaction).then(async (reservations) => {
+      const [machines, virtualMachines] = await Promise.all([
+        listOwnedActiveMachines(context, interaction, reservations),
+        Promise.all(
+          reservations.map((reservation) =>
+            orchestrator.listReservationVirtualMachines(context.fetch, reservation.reservationId)
+          )
+        ),
+      ]);
+      return { machines, reservations, virtualMachines };
+    });
+    directConnectCandidatesCache.set(context, candidates);
+  }
+  return candidates;
+}
+
 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(
+  const { machines } = await cachedDirectConnectCandidates(context, interaction);
+  const matches = machines.filter(
     (candidate) =>
       (text(candidate.reservation_id) ?? text(candidate.commerce_reservation_id)) === reference
   );
@@ -2663,7 +2817,7 @@ async function resolveDirectConnectMachine(reference, context, interaction) {
   const answer = await interaction.ask({
     label: "Machine",
     choices: matches.map((candidate) => ({
-      label: `${machineHostname(candidate) ?? "Unnamed machine"} · ${machineAccessMode(candidate) ?? "direct"} · ${machineState(candidate)}`,
+      label: `${machineHostname(candidate) ?? "Unnamed machine"} · direct · ${machineState(candidate)}`,
       value: machineId(candidate),
     })),
   });
@@ -2677,26 +2831,48 @@ async function resolveDirectConnectMachine(reference, context, interaction) {
   return selected;
 }
 
-function cachedDirectConnectMachine(reference, context, interaction) {
+function cachedDirectConnectTarget(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;
+  if (cached?.reference === reference) return cached.target;
+  const target = resolveDirectConnectMachine(reference, context, interaction).then(
+    async (machine) => {
+      if (!machine) 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, virtualMachines] = await Promise.all([
+        getReservation(context.fetch, reservationId),
+        orchestrator.listReservationVirtualMachines(context.fetch, reservationId),
+      ]);
+      return {
+        machine,
+        reservation,
+        virtualMachine: virtualMachineForNode(virtualMachines, machine, interaction),
+      };
+    }
+  );
+  directConnectResolutionCache.set(context, { reference, target });
+  return target;
 }
 
 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)
-      )
-    )
+  const { machines, reservations, virtualMachines } = await cachedDirectConnectCandidates(
+    context,
+    interaction
+  );
+  return machines
+    .filter((machine) => {
+      const index = reservations.findIndex(
+        (reservation) => reservation.reservationId === machine.reservation_id
+      );
+      if (index < 0) return false;
+      const guests = virtualMachinesForNode(virtualMachines[index], machine);
+      const mode = guests.length ? "vm" : directAccessMode(machine);
+      return acceptedModes.includes(mode === "vm" ? "virtual-machine" : mode);
+    })
     .map((machine) => ({
       label: `${machineHostname(machine) ?? "Unnamed machine"} · ${label} · ${machineState(machine)}`,
       reference: machineId(machine),
@@ -2715,36 +2891,32 @@ function createDirectMachineConnectModeHandler({
       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 target = await cachedDirectConnectTarget(reference, context, interaction);
+      if (!target) return null;
+      const { machine, reservation, virtualMachine } = target;
       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 getReservation(context.fetch, reservationId);
-      if (!isDirectReservation(reservation)) return null;
-      const privateTransportRequired = text(machine.network_mode) === "private";
+      const accessMode = directAccessMode(machine, virtualMachine);
+      if (accessMode ? accessMode !== mode : mode !== "bare-metal") return null;
+      const access = directAccess(machine, virtualMachine);
+      const privateTransportRequired = text(virtualMachine?.network_mode) === "private";
       return {
         context,
         input,
         interaction,
         machine,
+        access,
         mode,
         privateTransportRequired,
+        reservation,
         reservationId,
         targetReference: reference,
       };
     },
     matches(state) {
-      return state.mode === mode || acceptedModes.includes(text(state.machine?.access_mode));
+      return state.mode === mode;
     },
     async connect(state) {
-      const { input, interaction, machine } = state;
+      const { input, interaction, machine, access } = state;
       if (input.output || input.overwrite) {
         interaction.usage(
           `${label} connect uses native SSH and does not write a kubeconfig or other output file.`,
@@ -2754,8 +2926,8 @@ function createDirectMachineConnectModeHandler({
           }
         );
       }
-      const reachability = machineReachability(machine);
-      const invocation = reachability.class === "ready" ? sshInvocation(machine, input) : null;
+      const reachability = machineReachability(machine, access);
+      const invocation = reachability.class === "ready" ? sshInvocation(access, input) : null;
       const resume = { kind: "machine", ref: machineId(machine) };
       const displayName = machineHostname(machine) || "the selected machine";
       const waitTarget = machineHostname(machine)
@@ -2786,7 +2958,7 @@ function createDirectMachineConnectModeHandler({
             type: "command",
           },
           data: {
-            machine: projectMachine(machine),
+            machine: projectMachine(machine, mode === "vm" ? access : undefined),
             private_transport: privateTransport,
             ssh_command: null,
           },
@@ -2817,7 +2989,7 @@ function createDirectMachineConnectModeHandler({
       }
       const command = commandText(invocation);
       const data = {
-        machine: projectMachine(machine),
+        machine: projectMachine(machine, mode === "vm" ? access : undefined),
         private_transport: privateTransport,
         ssh_command: command,
       };
@@ -3058,7 +3230,10 @@ async function resolveMachineCommandTarget(input, context, interaction, usage) {
       code: "machine_correlation_failed",
     });
   }
-  const reservation = await getReservation(context.fetch, reservationId);
+  const [reservation, virtualMachines] = await Promise.all([
+    getReservation(context.fetch, reservationId),
+    orchestrator.listReservationVirtualMachines(context.fetch, reservationId),
+  ]);
   if (!isDirectReservation(reservation)) {
     interaction.error(
       "The selected machine belongs to a cluster rather than the direct-machine lifecycle.",
@@ -3067,13 +3242,16 @@ async function resolveMachineCommandTarget(input, context, interaction, usage) {
       }
     );
   }
-  return machine;
+  return {
+    machine,
+    reservation,
+    virtualMachines,
+  };
 }
 
-function machineLines(machine) {
-  const projected = projectMachine(machine);
+function machineLines(projected) {
   return [
-    `${projected.access_mode === "bare-metal" ? "Bare Metal" : "VM"} ${projected.hostname ?? projected.id}`,
+    `${projected.access_mode === "bare-metal" ? "Bare Metal" : projected.access_mode === "vm" ? "VM" : "Machine"} ${projected.hostname ?? projected.id}`,
     `  ID: ${projected.id}`,
     `  Capacity reservation: ${projected.reservation_id ?? "unreported"}`,
     `  Lifecycle: ${projected.lifecycle.class} / ${projected.lifecycle.phase}`,
@@ -3087,36 +3265,15 @@ function shouldWaitForMutation(input, interaction) {
   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 }
+  { acceptedPhase = "accepted", data = {}, recoveryCommand, successLines, virtualMachine, failure }
 ) {
   const id = machineId(machine);
   const resume = { kind: "machine", ref: id };
-  const resultData = { ...data, machine: projectMachine(machine) };
+  const resultData = { ...data, machine: projectMachine(machine, virtualMachine) };
   if (waitOutcome.kind === "ready") {
     return interaction.result({
       data: resultData,
@@ -3193,8 +3350,9 @@ function waitExecution(
     data: resultData,
     errors: [
       {
-        code: "machine_failed",
+        code: failure?.code ?? "machine_failed",
         message:
+          failure?.message ??
           text(machine.customer_lifecycle_error) ??
           "The machine operation failed before SSH became ready.",
         retryable: Boolean(recoveryCommand),
@@ -3221,18 +3379,36 @@ async function listMachines(input, context, interaction) {
     "ornn machines list [--limit <1-500>] [--cursor <opaque-cursor>]",
     interaction
   );
-  const rows = (await listOwnedActiveMachines(context, interaction))
+  const { machines, reservations, virtualMachines } = await cachedDirectConnectCandidates(
+    context,
+    interaction
+  );
+  const guests = new Map(
+    reservations.map((reservation, index) => [reservation.reservationId, virtualMachines[index]])
+  );
+  const rows = machines
     .filter((machine) => machineId(machine))
     .sort((left, right) => machineId(left).localeCompare(machineId(right)));
   const selected = machineCursorPage(rows, input, interaction);
+  const projected = selected.items.map((machine) => {
+    const matching = virtualMachinesForNode(guests.get(machine.reservation_id), machine);
+    const guest = matching.length === 1 ? matching[0] : null;
+    const result = projectMachine(
+      machine,
+      matching.length > 1 || directAccess(machine, guest) !== machine ? guest : undefined
+    );
+    // A host can be listed without choosing one of its guests for access.
+    if (matching.length > 1) result.access_mode = "vm";
+    return result;
+  });
   return interaction.result({
-    data: { machines: selected.items.map(projectMachine) },
+    data: {
+      machines: projected,
+    },
     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."],
+      lines: projected.length ? projected.flatMap(machineLines) : ["No direct machines found."],
       ...(selected.page.next_cursor
         ? { next: `ornn machines list --cursor ${selected.page.next_cursor}` }
         : {}),
@@ -3241,19 +3417,26 @@ async function listMachines(input, context, interaction) {
 }
 
 async function showMachine(input, context, interaction) {
-  const machine = await resolveMachineCommandTarget(
+  const { machine, virtualMachines } = await resolveMachineCommandTarget(
     input,
     context,
     interaction,
     "ornn machines show <canonical-machine-id|exact-hostname> [--guided]"
   );
+  const guests = virtualMachinesForNode(virtualMachines, machine);
+  const virtualMachine = guests.length === 1 ? guests[0] : null;
+  const access = guests.length > 1 ? null : directAccess(machine, virtualMachine);
+  const projected = projectMachine(machine, access === machine ? undefined : virtualMachine);
+  if (guests.length > 1) projected.access_mode = "vm";
   return interaction.result({
-    data: { machine: projectMachine(machine) },
-    outcome: machineLifecycle(machine),
+    data: { machine: projected },
+    outcome: machine.pending_access_mode
+      ? machineReachability(machine, access)
+      : machineLifecycle(access),
     resume: { kind: "machine", ref: machineId(machine) },
     presentation: {
-      lines: machineLines(machine),
-      ...(machineReachability(machine).class === "ready"
+      lines: machineLines(projected),
+      ...(machineReachability(machine, access).class === "ready"
         ? { next: "ornn connect" }
         : { next: "ornn machines wait --guided" }),
     },
@@ -3262,20 +3445,35 @@ async function showMachine(input, context, interaction) {
 
 async function waitMachine(input, context, interaction) {
   validateWaitInput(input, interaction, { waitCommand: true });
-  const machine = await resolveMachineCommandTarget(
+  const { machine, reservation, virtualMachines } = await resolveMachineCommandTarget(
     input,
     context,
     interaction,
     "ornn machines wait <canonical-machine-id|exact-hostname> [--guided] [--timeout <duration>]"
   );
+  const initialVirtualMachine = virtualMachineForNode(virtualMachines, machine, interaction);
   const timeout = text(input.timeout) ?? "10m";
   let waitOutcome;
+  let virtualMachine =
+    directAccess(machine, initialVirtualMachine) === machine ? undefined : initialVirtualMachine;
   try {
-    waitOutcome = await waitForMachine(context, interaction, machine, timeout, "machines wait");
+    waitOutcome = await waitForMachine(context, interaction, {
+      node: machine,
+      virtualMachine: initialVirtualMachine,
+      reservation,
+      timeout,
+      command: "machines wait",
+    });
+    virtualMachine =
+      directAccess(waitOutcome.value.node, waitOutcome.value.virtualMachine) ===
+      waitOutcome.value.node
+        ? undefined
+        : waitOutcome.value.virtualMachine;
+    waitOutcome = { ...waitOutcome, value: waitOutcome.value.node };
   } catch (error) {
     return acceptedWaitFailure(interaction, error, {
       data: {
-        machine: projectMachine(machine),
+        machine: projectMachine(machine, virtualMachine),
         wait: { enabled: true, timeout },
       },
       label: "machine readiness",
@@ -3286,23 +3484,27 @@ async function waitMachine(input, context, interaction) {
   }
   return waitExecution(interaction, waitOutcome.value, waitOutcome, {
     acceptedPhase: "ssh_pending",
+    virtualMachine,
     recoveryCommand: failedOperationRecoveryCommand(waitOutcome.value, interaction),
     data: { wait: { enabled: true, timeout } },
   });
 }
 
-function directMachineSnapshot(machines, relationships, keys) {
+function directMachineSnapshot(machines, relationships, keys, virtualMachine) {
   return JSON.stringify({
     keys: keys.map(resourceId).sort(),
     machines: machines
       .map((machine) => ({
         id: machineId(machine),
-        mode: machineAccessMode(machine),
-        network: text(machine.network_mode),
+        reservation_id: machine.reservation_id,
+        pending_access_mode: machine.pending_access_mode,
         username: machineUsername(machine),
       }))
       .sort((left, right) => left.id.localeCompare(right.id)),
     relationships,
+    virtualMachine: virtualMachine
+      ? { id: virtualMachine.id, network_mode: virtualMachine.network_mode }
+      : null,
   });
 }
 
@@ -3373,10 +3575,11 @@ async function switchMachine(input, context, interaction) {
       code: "reservation_not_direct",
     });
   }
-  const [machines, relationships, keys] = await Promise.all([
+  const [machines, relationships, keys, virtualMachines] = await Promise.all([
     fetchMachines(context, reservationId),
     bareMetalRelationships(context, reservationId),
     fetchAssignedKeys(context, reservationId),
+    orchestrator.listReservationVirtualMachines(context.fetch, reservationId),
   ]);
   if (machines.length !== 1) {
     interaction.error(
@@ -3391,13 +3594,14 @@ async function switchMachine(input, context, interaction) {
       code: "ssh_key_assignment_missing",
     });
   }
-  const currentMode = machineAccessMode(machines[0]);
+  const virtualMachine = virtualMachineForNode(virtualMachines, machines[0], interaction);
+  const currentMode = directAccessMode(machines[0], virtualMachine);
   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 currentNetwork = text(virtualMachine?.network_mode);
   const targetMode = requestedMode ?? currentMode;
   const targetNetwork = requestedNetwork ?? currentNetwork;
   const erasesLocalData = targetMode !== currentMode;
@@ -3411,97 +3615,89 @@ async function switchMachine(input, context, interaction) {
     enabled: shouldWaitForMutation(input, interaction),
     timeout: shouldWaitForMutation(input, interaction) ? (text(input.timeout) ?? "10m") : null,
   };
-  if (targetMode === currentMode && targetNetwork === currentNetwork) {
+  const idempotencyKey = text(input.idempotencyKey) ?? interaction.idempotencyKey();
+  let savedOperation = null;
+  if (requestedMode && !requestedNetwork && text(input.idempotencyKey)) {
+    try {
+      savedOperation = await orchestrator.getReservationAccessSwitch(
+        context.fetch,
+        reservationId,
+        idempotencyKey
+      );
+    } catch (error) {
+      if (Number(error?.status) !== 404) throw error;
+    }
+  }
+  if (!savedOperation && requestedMode === currentMode && !requestedNetwork) {
+    const pendingMode = machines[0].pending_access_mode;
+    if (pendingMode && pendingMode !== (targetMode === "vm" ? "virtual-machine" : targetMode)) {
+      interaction.error("A different access mode change is pending; wait for it to finish.", {
+        code: "access_mode_pending",
+      });
+    }
+    const access = directAccess(machines[0], virtualMachine);
+    const reachability = machineReachability(machines[0], access);
+    const data = {
+      mode: currentMode,
+      network_mode: currentNetwork,
+      retained_ssh_keys: keys.map(projectKey),
+      relationships,
+      erased_local_data: false,
+      replayed: false,
+      wait,
+    };
+    if (wait.enabled && reachability.class !== "ready") {
+      let waitOutcome;
+      try {
+        waitOutcome = await waitForMachine(context, interaction, {
+          node: machines[0],
+          virtualMachine,
+          reservation,
+          timeout: wait.timeout,
+          command: "machines switch",
+          mode: targetMode,
+        });
+      } catch (error) {
+        return acceptedWaitFailure(interaction, error, {
+          data,
+          label: "machine readiness",
+          phase: "ssh_pending",
+          resume: { kind: "machine", ref: machineId(machines[0]) },
+          retryCommand: `ornn machines switch ${reservationId} --mode ${targetMode} --wait --timeout ${wait.timeout} --idempotency-key ${shellQuote(idempotencyKey)}`,
+        });
+      }
+      return waitExecution(interaction, waitOutcome.value.node, waitOutcome, {
+        acceptedPhase: "ssh_pending",
+        data,
+        virtualMachine: targetMode === "vm" ? waitOutcome.value.virtualMachine : undefined,
+      });
+    }
     return interaction.result({
       data: {
-        machine: projectMachine(machines[0]),
-        mode: targetMode,
-        network_mode: targetNetwork,
-        retained_ssh_keys: keys.map(projectKey),
-        relationships,
-        replayed: true,
-        wait,
+        ...data,
+        machine: projectMachine(machines[0], access === machines[0] ? undefined : virtualMachine),
       },
-      outcome:
-        machineReachability(machines[0]).class === "ready"
-          ? { class: "ready", phase: "ssh_ready" }
-          : { class: "working", phase: "switch_accepted" },
+      outcome: reachability,
+      exitCode: reachability.class === "failed" ? 1 : 0,
       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",
+        lines: [`Current access mode is ${currentMode}.`],
+        next: reachability.class === "ready" ? "ornn connect" : "ornn machines wait --guided",
       },
-    ],
-    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([
-      getReservation(context.fetch, reservationId),
-      fetchMachines(context, reservationId),
-      bareMetalRelationships(context, reservationId),
-      fetchAssignedKeys(context, reservationId),
-    ]);
-  const currentReservation = assertActiveReservation(
-    currentReservationValue,
-    reservationId,
-    interaction
-  );
-  const reservationLabel = await reservationLabeler(context.fetch);
-  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",
-    });
+  if (!savedOperation && !targetNetwork) {
+    interaction.usage(
+      "Specify --network public or private when switching a machine whose current network mode is unreported.",
+      { code: "network_mode_required", field: "network" }
+    );
   }
-  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 } : {}),
+    network_mode: targetNetwork,
+    ...(input.eraseLocalData ? { erase_local_data: true } : {}),
     machine_count: machines.length,
     request_id: idempotencyKey,
     ssh_key_ids: keys.map(resourceId),
@@ -3510,38 +3706,115 @@ async function switchMachine(input, context, interaction) {
     "ornn machines switch",
     shellQuote(reservationId),
     requestedMode ? `--mode ${requestedMode}` : null,
-    requestedNetwork ? `--network ${requestedNetwork}` : null,
-    erasesLocalData ? "--erase-local-data" : null,
+    !savedOperation && targetNetwork ? `--network ${targetNetwork}` : null,
+    input.eraseLocalData ? "--erase-local-data" : null,
     "--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,
+  let response = { nodes: machines };
+  if (!savedOperation) {
+    const snapshot = directMachineSnapshot(machines, relationships, keys, virtualMachine);
+    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 ?? "unreported"} to ${targetNetwork}`
+            : `${currentNetwork ?? "unreported"} (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,
+      currentVirtualMachines,
+    ] = await Promise.all([
+      getReservation(context.fetch, reservationId),
+      fetchMachines(context, reservationId),
+      bareMetalRelationships(context, reservationId),
+      fetchAssignedKeys(context, reservationId),
+      orchestrator.listReservationVirtualMachines(context.fetch, reservationId),
+    ]);
+    const currentReservation = assertActiveReservation(
+      currentReservationValue,
+      reservationId,
+      interaction
+    );
+    const reservationLabel = await reservationLabeler(context.fetch);
+    if (
+      reservationLabel(currentReservation) !== reservationLabel(reservation) ||
+      directMachineSnapshot(
+        currentMachines,
+        currentRelationships,
+        currentKeys,
+        virtualMachineForNode(currentVirtualMachines, currentMachines[0], interaction)
+      ) !== snapshot
+    ) {
+      interaction.error(
+        "Machine access, network, volume, or SSH-key intent changed after review.",
+        {
+          code: "machine_switch_stale",
+        }
+      );
+    }
+    try {
+      response = await orchestrator.switchReservationAccess(context.fetch, reservationId, 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)
+    Array.isArray(responseSource.nodes)
+      ? responseSource.nodes.map(record)
+      : 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.", {
@@ -3550,27 +3823,50 @@ async function switchMachine(input, context, interaction) {
     });
   }
   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 targetReference = machineId(machine);
   const data = {
     mode: targetMode,
-    network_mode: targetNetwork,
+    network_mode: savedOperation
+      ? currentMode === targetMode
+        ? currentNetwork
+        : null
+      : targetNetwork,
     retained_ssh_keys: keys.map(projectKey),
     relationships,
     erased_local_data: erasesLocalData,
-    replayed: false,
+    replayed: Boolean(savedOperation),
     request_id: idempotencyKey,
     wait,
   };
+  const initial = {
+    node: machine,
+    virtualMachine: savedOperation ? virtualMachine : null,
+    operation: savedOperation,
+  };
+  const switchReady = ({ node, virtualMachine, operation }) =>
+    operation?.status === "succeeded" &&
+    directAccessMode(node, virtualMachine) === targetMode &&
+    machineReachability(node, targetMode === "vm" ? virtualMachine : node).class === "ready";
+  if (savedOperation && (savedOperation.status === "failed" || switchReady(initial))) {
+    return waitExecution(
+      interaction,
+      machine,
+      { kind: savedOperation.status === "failed" ? "terminal" : "ready", value: initial },
+      {
+        acceptedPhase: "switch_accepted",
+        data,
+        virtualMachine: targetMode === "vm" ? virtualMachine : undefined,
+        failure: savedOperation.detail,
+      }
+    );
+  }
   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" },
+      data: {
+        ...data,
+        machine: projectMachine(machine, targetMode === "vm" ? null : undefined),
+      },
+      outcome: { class: "working", phase: "switch_accepted" },
       resume: { kind: "machine", ref: targetReference },
       presentation: {
         lines: ["Machine switch accepted."],
@@ -3578,75 +3874,67 @@ async function switchMachine(input, context, interaction) {
       },
     });
   }
-  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"
-    );
+    waitOutcome = await interaction.waitForGoal({
+      command: "machines switch",
+      initial,
+      timeoutMs: timeoutMilliseconds(wait.timeout, interaction),
+      isReady: switchReady,
+      isTerminal: ({ node, virtualMachine, operation }) =>
+        operation?.status === "failed" ||
+        machineReachability(node, targetMode === "vm" ? virtualMachine : node).class === "failed",
+      message: ({ operation }) => `Machine switch is ${operation?.status ?? "accepted"}.`,
+      projectProgress: ({ node, virtualMachine, operation }) => ({
+        machine: projectMachine(node, targetMode === "vm" ? virtualMachine : undefined),
+        switch: operation,
+      }),
+      poll: async ({ signal }) => {
+        const [node, operation, guests] = await Promise.all([
+          orchestrator.getNode(context.fetch, targetReference, signal),
+          orchestrator.getReservationAccessSwitch(
+            context.fetch,
+            reservationId,
+            idempotencyKey,
+            signal
+          ),
+          orchestrator.listReservationVirtualMachines(context.fetch, reservationId, signal),
+        ]);
+        return {
+          node,
+          operation,
+          virtualMachine: guests ? virtualMachineForNode(guests, node, interaction) : null,
+        };
+      },
+    });
   } catch (error) {
     return acceptedWaitFailure(interaction, error, {
-      data: { ...data, machine: projectMachine(waiting) },
+      data: {
+        ...data,
+        machine: projectMachine(machine, targetMode === "vm" ? null : undefined),
+      },
       label: "machine switch",
       phase: "switch_accepted",
-      resume: { kind: "machine", ref: machineId(waiting) },
-      retryCommand: `ornn machines wait ${machineId(waiting)} --timeout ${wait.timeout}`,
+      resume: { kind: "machine", ref: targetReference },
+      retryCommand,
     });
   }
-  machine = waitOutcome.value;
+  machine = waitOutcome.value.node;
   const finalRelationships = await bareMetalRelationships(context, reservationId);
   const failedRecoveryCommand = [
     "ornn machines switch",
     shellQuote(reservationId),
     `--mode ${targetMode}`,
-    `--network ${targetNetwork}`,
-    erasesLocalData ? "--erase-local-data" : null,
+    targetNetwork ? `--network ${targetNetwork}` : null,
+    input.eraseLocalData ? "--erase-local-data" : null,
     `--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",
+    virtualMachine: targetMode === "vm" ? waitOutcome.value.virtualMachine : undefined,
+    failure: waitOutcome.value.operation?.detail,
     data: { ...data, relationships: finalRelationships },
     recoveryCommand: failedRecoveryCommand,
     successLines: [
@@ -3658,17 +3946,23 @@ async function switchMachine(input, context, interaction) {
 async function maintainMachine(command, input, context, interaction) {
   const destructive = command === "reset";
   requireMachineMutationSafety(input, interaction, { destructive });
-  const machine = await resolveMachineCommandTarget(
+  const { machine, reservation, virtualMachines } = await resolveMachineCommandTarget(
     input,
     context,
     interaction,
     `ornn machines ${command} <canonical-machine-id|exact-hostname>${destructive ? " --erase-local-data" : ""} [--no-wait]`
   );
+  const virtualMachine = virtualMachineForNode(virtualMachines, machine, interaction);
   if (TERMINAL_MACHINE_STATES.has(machineState(machine))) {
     interaction.error("A terminal machine cannot be rebooted or reset.", {
       code: "machine_terminal",
     });
   }
+  if (machine.pending_access_mode) {
+    interaction.error("Wait for the machine's access mode to become ready before maintenance.", {
+      code: "machine_not_ready",
+    });
+  }
   const accepted = await interaction.review({
     title: destructive ? "Machine reset review" : "Machine reboot review",
     terms: [
@@ -3676,7 +3970,7 @@ async function maintainMachine(command, input, context, interaction) {
         label: "Machine",
         value: `${machineHostname(machine) || "unnamed"} (${machineId(machine)})`,
       },
-      { label: "Access mode", value: machineAccessMode(machine) ?? "unreported" },
+      { label: "Access mode", value: directAccessMode(machine, virtualMachine) ?? "unreported" },
       { label: "Access", value: "SSH will be interrupted until the machine is ready again" },
       {
         label: "Local data",
@@ -3713,12 +4007,17 @@ async function maintainMachine(command, input, context, interaction) {
       },
     });
   }
-  const current = await context.fetch(
-    `/v1/workflows/compute/nodes/${encodeURIComponent(machineId(machine))}`
-  );
+  const [current, currentGuests] = await Promise.all([
+    orchestrator.getNode(context.fetch, machineId(machine)),
+    orchestrator.listReservationVirtualMachines(context.fetch, reservation.reservationId),
+  ]);
+  const currentGuest = virtualMachineForNode(currentGuests, current, interaction);
   if (
     machineId(current) !== machineId(machine) ||
-    machineAccessMode(current) !== machineAccessMode(machine) ||
+    current.reservation_id !== machine.reservation_id ||
+    current.pending_access_mode ||
+    currentGuest?.id !== virtualMachine?.id ||
+    directAccessMode(current, currentGuest) !== directAccessMode(machine, virtualMachine) ||
     machineState(current) !== machineState(machine)
   ) {
     interaction.error("The machine changed after review; maintenance was not submitted.", {
@@ -3726,29 +4025,37 @@ async function maintainMachine(command, input, context, interaction) {
     });
   }
   const idempotencyKey = text(input.idempotencyKey) ?? interaction.idempotencyKey();
-  const maintenanceRetryCommand = [
-    `ornn machines ${command}`,
-    shellQuote(machineId(machine)),
-    destructive ? "--erase-local-data" : null,
-    "--no-wait",
-    `--idempotency-key ${shellQuote(idempotencyKey)}`,
-  ]
-    .filter(Boolean)
-    .join(" ");
+  const maintenanceRetryCommand =
+    virtualMachine && !destructive
+      ? `ornn machines wait ${shellQuote(machineId(machine))} --timeout 10m`
+      : [
+          `ornn machines ${command}`,
+          shellQuote(machineId(machine)),
+          destructive ? "--erase-local-data" : null,
+          "--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,
-          },
-        }
-      )
+      virtualMachine && !destructive
+        ? await orchestrator.rebootVirtualMachine(
+            context.fetch,
+            machineId(machine),
+            virtualMachine.id,
+            { mode: "reboot" }
+          )
+        : await orchestrator.rebootNode(
+            context.fetch,
+            virtualMachine ? virtualMachine.id : machineId(machine),
+            {
+              mode: destructive ? "hard_reset" : "reboot",
+              request_id: idempotencyKey,
+              erase_local_data: destructive,
+            }
+          )
     );
   } catch (error) {
     return uncertainMutationFailure(interaction, error, {
@@ -3767,10 +4074,14 @@ async function maintainMachine(command, input, context, interaction) {
     enabled: shouldWaitForMutation(input, interaction),
     timeout: shouldWaitForMutation(input, interaction) ? (text(input.timeout) ?? "10m") : null,
   };
+  const acceptedReboot = record(response.reboot);
+  const acceptedVirtualMachine = text(response.operation_id) ? response : null;
+  const packetId =
+    text(acceptedReboot.packet_id) ?? text(response.packet_id) ?? text(response.operation_id);
   const data = {
     operation: destructive ? "reset" : "reboot",
     request_id: idempotencyKey,
-    packet_id: text(response.packet_id),
+    packet_id: packetId,
     erased_local_data: destructive,
     preserved: {
       external_volume_relationship: true,
@@ -3782,7 +4093,10 @@ async function maintainMachine(command, input, context, interaction) {
   const resume = { kind: "machine", ref: machineId(machine) };
   if (!wait.enabled) {
     return interaction.result({
-      data: { ...data, machine: projectMachine(machine) },
+      data: {
+        ...data,
+        machine: projectMachine(machine, acceptedVirtualMachine ?? undefined),
+      },
       outcome: {
         class: "working",
         phase: destructive ? "reset_accepted" : "reboot_accepted",
@@ -3794,44 +4108,102 @@ async function maintainMachine(command, input, context, interaction) {
       },
     });
   }
-  const waiting = {
-    ...record(machine),
-    state: destructive ? "resetting" : "rebooting",
-    status: destructive ? "resetting" : "rebooting",
-    ssh_endpoint: null,
+  let cleanupObserved = false;
+  const operationStatus = ({ node, virtualMachine }) => {
+    if (acceptedVirtualMachine) {
+      return virtualMachine?.operation_id === acceptedVirtualMachine.operation_id
+        ? virtualMachine.operation_status
+        : "in_progress";
+    }
+    if (destructive) {
+      return cleanupObserved && node.cleanup_state === "completed"
+        ? "succeeded"
+        : cleanupObserved && node.cleanup_state === "failed"
+          ? "failed"
+          : "in_progress";
+    }
+    return node.reboot?.packet_id === packetId ? node.reboot.status : "in_progress";
   };
   let waitOutcome;
   try {
-    waitOutcome = await waitForMachine(
-      context,
-      interaction,
-      waiting,
-      wait.timeout,
-      `machines ${command}`
-    );
+    waitOutcome = await interaction.waitForGoal({
+      command: `machines ${command}`,
+      initial: { node: machine, virtualMachine: acceptedVirtualMachine },
+      timeoutMs: timeoutMilliseconds(wait.timeout, interaction),
+      isReady: (current) =>
+        operationStatus(current) === "succeeded" &&
+        machineReachability(
+          current.node,
+          acceptedVirtualMachine ? current.virtualMachine : current.node
+        ).class === "ready",
+      isTerminal: (current) =>
+        operationStatus(current) === "failed" ||
+        machineReachability(
+          current.node,
+          acceptedVirtualMachine ? current.virtualMachine : current.node
+        ).class === "failed",
+      message: (current) => `Machine ${command} is ${operationStatus(current)}.`,
+      projectProgress: (current) => ({
+        machine: projectMachine(
+          current.node,
+          acceptedVirtualMachine ? current.virtualMachine : undefined
+        ),
+        reboot: current.node.reboot,
+      }),
+      poll: async ({ signal }) => {
+        const [node, guests] = await Promise.all([
+          orchestrator.getNode(context.fetch, machineId(machine), signal),
+          acceptedVirtualMachine
+            ? orchestrator.listReservationVirtualMachines(
+                context.fetch,
+                reservation.reservationId,
+                signal
+              )
+            : null,
+        ]);
+        cleanupObserved ||=
+          ["pending", "rebooting"].includes(node.cleanup_state) ||
+          (node.cleanup_state === "failed" && machine.cleanup_state !== "failed") ||
+          Boolean(node.keys_pushed_at && node.keys_pushed_at !== machine.keys_pushed_at);
+        return {
+          node,
+          virtualMachine: guests ? virtualMachineForNode(guests, node, interaction) : null,
+        };
+      },
+    });
   } catch (error) {
     return acceptedWaitFailure(interaction, error, {
-      data: { ...data, machine: projectMachine(waiting) },
+      data: {
+        ...data,
+        machine: projectMachine(machine, acceptedVirtualMachine ?? undefined),
+      },
       label: `machine ${destructive ? "reset" : "reboot"}`,
       phase: destructive ? "reset_accepted" : "reboot_accepted",
       resume,
-      retryCommand: `ornn machines wait ${machineId(waiting)} --timeout ${wait.timeout}`,
+      retryCommand: `ornn machines wait ${machineId(machine)} --timeout ${wait.timeout}`,
     });
   }
+  const completedNode = waitOutcome.value.node;
   const failedRecoveryCommand = [
     `ornn machines ${command}`,
-    shellQuote(machineId(waitOutcome.value)),
+    shellQuote(machineId(completedNode)),
     destructive ? "--erase-local-data" : null,
     `--idempotency-key ${shellQuote(interaction.idempotencyKey())}`,
   ]
     .filter(Boolean)
     .join(" ");
-  return waitExecution(interaction, waitOutcome.value, waitOutcome, {
+  return waitExecution(interaction, completedNode, waitOutcome, {
     acceptedPhase: destructive ? "reset_accepted" : "reboot_accepted",
+    virtualMachine: acceptedVirtualMachine ? waitOutcome.value.virtualMachine : undefined,
+    failure: acceptedVirtualMachine
+      ? waitOutcome.value.virtualMachine?.failure
+      : destructive
+        ? undefined
+        : completedNode.reboot?.detail,
     data,
     recoveryCommand: failedRecoveryCommand,
     successLines: [
-      `Machine ${destructive ? "reset" : "reboot"} completed; SSH is ready: ${machineHostname(waitOutcome.value) || machineId(waitOutcome.value)}`,
+      `Machine ${destructive ? "reset" : "reboot"} completed; SSH is ready: ${machineHostname(completedNode) || machineId(completedNode)}`,
     ],
   });
 }
@@ -4166,12 +4538,9 @@ export async function executeSshKeyCommand(command, input, context, interaction)
       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),
-            },
+          await orchestrator.pushNodeKeys(context.fetch, id, {
+            request_id: requestId,
+            ssh_key_ids: keys.map(resourceId),
           })
         );
         deliveries.set(id, {