@ornncompute/cli 0.2.24 → 1.0.34

package/src/kubernetes-commands.mjs

@@ -0,0 +1,2235 @@
+import { createHash } from "node:crypto";
+
+import {
+  assertAtomicOutputAvailable,
+  AtomicOutputExistsError,
+  writeAtomicOutput,
+} from "./atomic-output.mjs";
+import { isRecoverableWaitFailure } from "./interaction-runtime.mjs";
+import { waitForGoal as waitForReadGoal } from "./wait-runtime.mjs";
+import { gpuLabeler } from "./gpu-catalog.mjs";
+import { reservationLabeler } from "./machine-reference.mjs";
+import { keyInputShapePreflight, keyPlanFromInput, materializeKey } from "./vm-commands.mjs";
+
+const UUID = /^[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 CLUSTERS_PATH = "/v1/workflows/compute/clusters";
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+const DEFAULT_WAIT_SECONDS = 600;
+const POLL_INTERVAL_MS = 5_000;
+const TERMINAL_FAILURE_STATES = new Set(["error", "failed"]);
+const TERMINAL_ENDED_STATES = new Set(["deleted", "torn_down"]);
+const clusterCache = new WeakMap();
+
+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 shellQuote(value) {
+  const rendered = String(value);
+  return /^[A-Za-z0-9_./:@%+=,-]+$/.test(rendered)
+    ? rendered
+    : `'${rendered.replaceAll("'", `'\\''`)}'`;
+}
+
+function integer(value) {
+  return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+
+function cleanState(value) {
+  return text(value)?.toLowerCase().replaceAll("-", "_") ?? "unknown";
+}
+
+function clusterModeLabel(accessMode) {
+  return accessMode === "slurm" ? "Slurm" : "Kubernetes";
+}
+
+function clusterNativeAccess(accessMode) {
+  return accessMode === "slurm" ? "SSH login" : "kubeconfig";
+}
+function reservationAccessMode(value) {
+  const mode = cleanState(record(value).access_mode ?? record(value).accessMode);
+  return mode === "virtual-machine" ? "vm" : mode;
+}
+
+function clusterConnectCommand(cluster) {
+  return cluster.access_mode === "slurm" ? "ornn connect" : "ornn connect --guided";
+}
+
+function lifecycleForCluster(source, members) {
+  const state = cleanState(source.state);
+  const credentialState = cleanState(source.credential_state);
+  const failedMembers = members.filter((member) => member.lifecycle.class === "failed");
+  if (TERMINAL_ENDED_STATES.has(state)) return { class: "ended", phase: "torn_down" };
+  if (state === "deleting") return { class: "working", phase: "tearing_down" };
+  if (TERMINAL_FAILURE_STATES.has(state)) {
+    return { class: members.length ? "partial" : "failed", phase: "provisioning_failed" };
+  }
+  if (failedMembers.length) return { class: "partial", phase: "member_failed" };
+  if (state === "active" && ["ready", "active", "available"].includes(credentialState)) {
+    return { class: "ready", phase: "access_ready" };
+  }
+  if (state === "active") return { class: "working", phase: "credentials_pending" };
+  if (["provisioning", "creating", "pending"].includes(state)) {
+    return { class: "working", phase: "provisioning" };
+  }
+  return { class: "pending", phase: state };
+}
+
+function memberLifecycle(value) {
+  const state = cleanState(value);
+  if (["ready", "active", "running", "joined", "member"].includes(state)) {
+    return { class: "ready", phase: "member" };
+  }
+  if (["failed", "error", "cleanup_failed", "join_failed"].includes(state)) {
+    return { class: "failed", phase: "member_failed" };
+  }
+  if (["deleted", "removed", "detached"].includes(state)) {
+    return { class: "ended", phase: "removed" };
+  }
+  return { class: "working", phase: state };
+}
+
+function projectCluster(value) {
+  const source = record(value);
+  const rawMembers = Array.isArray(source.machines)
+    ? source.machines
+    : Array.isArray(source.members)
+      ? source.members
+      : [];
+  const members = rawMembers.flatMap((value) => {
+    const member = record(value);
+    const id = text(member.id) ?? text(member.node_id);
+    if (!id) return [];
+    const state = text(member.state) ?? text(member.membership_state);
+    return [{ id, hostname: text(member.hostname), lifecycle: memberLifecycle(state) }];
+  });
+  const cluster = {
+    id: text(source.id),
+    reservation_id: text(source.reservation_id),
+    access_mode: cleanState(source.access_mode),
+    lifecycle: null,
+    network_mode: text(source.network_mode),
+    membership_count: integer(source.node_count) ?? members.length,
+    gpu_count: integer(source.gpu_count),
+    gpu_type: text(source.gpu_type),
+    credential_state: cleanState(source.credential_state),
+    created_at: text(source.created_at),
+    updated_at: text(source.updated_at),
+    machines: members,
+  };
+  cluster.lifecycle = lifecycleForCluster(source, members);
+  return cluster;
+}
+
+function clusterLines(cluster) {
+  return [
+    `${cluster.access_mode === "kubernetes" ? "Kubernetes" : "Slurm"} cluster ${cluster.id}`,
+    `  Capacity reservation: ${cluster.reservation_id}`,
+    `  State: ${cluster.lifecycle.class} (${cluster.lifecycle.phase})`,
+    `  Membership: ${cluster.membership_count}`,
+    `  Network: ${cluster.network_mode ?? "unknown"}`,
+  ];
+}
+
+function eligibilityPath(reservationId, accessMode = "kubernetes") {
+  const query = new URLSearchParams({ access_mode: accessMode });
+  return `/v1/workflows/compute/tenants/me/reservations/${encodeURIComponent(reservationId)}/cluster-eligible-machines?${query}`;
+}
+
+function clusterPath(cluster, suffix) {
+  return `/v1/workflows/compute/${cluster.access_mode}/reservations/${encodeURIComponent(cluster.reservation_id)}/${suffix}`;
+}
+
+async function fetchClusters(fetch) {
+  const payload = await fetch(CLUSTERS_PATH, { method: "GET" });
+  const rows = Array.isArray(payload)
+    ? payload
+    : Array.isArray(record(payload).clusters)
+      ? payload.clusters
+      : null;
+  if (!rows) throw new Error("The gateway returned an invalid cluster collection.");
+  return rows.map(projectCluster).sort((left, right) => {
+    const byReservation = String(left.reservation_id).localeCompare(String(right.reservation_id));
+    return byReservation || String(left.id).localeCompare(String(right.id));
+  });
+}
+
+function requireValidCluster(runtime, cluster) {
+  if (!UUID.test(cluster.id ?? "") || !UUID.test(cluster.reservation_id ?? "")) {
+    runtime.error("The gateway returned a cluster without canonical identifiers.", {
+      code: "invalid_cluster_response",
+    });
+  }
+  const machineIds = cluster.machines.map((machine) => machine.id);
+  if (machineIds.some((id) => !UUID.test(id)) || new Set(machineIds).size !== machineIds.length) {
+    runtime.error("The gateway returned a cluster with invalid machine membership.", {
+      code: "invalid_cluster_response",
+    });
+  }
+  if (!["kubernetes", "slurm"].includes(cluster.access_mode)) {
+    runtime.error("The gateway returned a cluster with an unsupported access mode.", {
+      code: "invalid_cluster_response",
+    });
+  }
+  return cluster;
+}
+
+async function resolveCluster(fetch, runtime, input) {
+  const positionals = input.$positionals ?? [];
+  if (positionals.length > 1) runtime.usage("Supply one cluster reference, or use --guided.");
+  const reference = text(positionals[0]);
+  if (runtime.machine && !UUID.test(reference ?? "")) {
+    runtime.usage("Machine mode requires a canonical cluster ID.", {
+      code: "canonical_cluster_id_required",
+      field: "cluster",
+    });
+  }
+  if (reference && !UUID.test(reference)) {
+    runtime.usage(
+      "Clusters are referenced only by canonical ID or an invocation-local guided choice.",
+      {
+        code: "canonical_cluster_id_required",
+        field: "cluster",
+      }
+    );
+  }
+  if (!reference && input.guided !== true) {
+    runtime.usage("A canonical cluster ID is required unless --guided is supplied.", {
+      code: "cluster_reference_required",
+      field: "cluster",
+    });
+  }
+  if (!reference && !runtime.eligibleHuman) {
+    runtime.usage("--guided requires an eligible interactive terminal.", {
+      code: "guided_requires_terminal",
+      field: "guided",
+    });
+  }
+  const clusters = await fetchClusters(fetch);
+  if (reference) {
+    const matches = clusters.filter((cluster) => cluster.id === reference);
+    if (matches.length === 0)
+      runtime.error(`Cluster not found: ${reference}.`, { code: "cluster_not_found" });
+    if (matches.length > 1) {
+      runtime.error("The gateway returned more than one cluster with the same canonical ID.", {
+        code: "cluster_ambiguous",
+      });
+    }
+    return requireValidCluster(runtime, matches[0]);
+  }
+  if (clusters.length === 0)
+    runtime.error("No clusters are available in this organization.", { code: "cluster_not_found" });
+  if (clusters.length === 1) return requireValidCluster(runtime, clusters[0]);
+  const selected = await runtime.ask({
+    label: "Cluster",
+    choices: clusters.map((cluster) => ({
+      label: `${cluster.access_mode} · reservation ${cluster.reservation_id} · ${cluster.membership_count} nodes · ${cluster.lifecycle.class}`,
+      value: cluster.id,
+    })),
+  });
+  const matches = clusters.filter((cluster) => cluster.id === selected);
+  if (matches.length !== 1)
+    runtime.usage("Choose one exact cluster.", { code: "cluster_ambiguous" });
+  return requireValidCluster(runtime, matches[0]);
+}
+
+async function fetchClusterDetail(fetch, runtime, cluster, { allowMissing = false, signal } = {}) {
+  let payload;
+  try {
+    payload = await fetch(clusterPath(cluster, "cluster"), {
+      method: "GET",
+      ...(signal ? { signal } : {}),
+    });
+  } catch (error) {
+    if (allowMissing && error?.status === 404) return null;
+    throw error;
+  }
+  const current = requireValidCluster(runtime, projectCluster(payload));
+  if (
+    current.id !== cluster.id ||
+    current.reservation_id !== cluster.reservation_id ||
+    current.access_mode !== cluster.access_mode
+  ) {
+    runtime.error("The exact cluster identity changed while it was being read.", {
+      code: "cluster_identity_changed",
+    });
+  }
+  return current;
+}
+
+async function fetchEligibility(fetch, runtime, reservationId, accessMode = "kubernetes") {
+  const payload = record(
+    await fetch(eligibilityPath(reservationId, accessMode), { method: "GET" })
+  );
+  if (
+    text(payload.reservation_id) !== reservationId ||
+    cleanState(payload.access_mode) !== accessMode
+  ) {
+    runtime.error("The gateway returned eligibility for a different reservation or access mode.", {
+      code: "invalid_cluster_eligibility",
+    });
+  }
+  if (!Array.isArray(payload.machines)) {
+    runtime.error("The gateway returned an invalid eligible-machine projection.", {
+      code: "invalid_cluster_eligibility",
+    });
+  }
+  const machines = payload.machines.map((value) => {
+    const machine = record(value);
+    const id = text(machine.id);
+    const hostname = text(machine.hostname);
+    const keys = Object.keys(machine).sort();
+    if (!UUID.test(id ?? "") || !hostname || keys.join(",") !== "hostname,id") {
+      runtime.error("The gateway returned an unsafe eligible-machine projection.", {
+        code: "invalid_cluster_eligibility",
+      });
+    }
+    return { id, hostname };
+  });
+  const ids = new Set();
+  for (const machine of machines) {
+    if (ids.has(machine.id)) {
+      runtime.error("The eligible-machine projection contains a duplicate canonical ID.", {
+        code: "cluster_eligibility_ambiguous",
+      });
+    }
+    ids.add(machine.id);
+  }
+  return machines.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function eligibilitySignature(machines) {
+  return machines
+    .map((machine) => `${machine.id}\u0000${machine.hostname}`)
+    .sort()
+    .join("\u0001");
+}
+
+function memberIds(cluster) {
+  const ids = cluster.machines.map((machine) => machine.id).sort();
+  if (new Set(ids).size !== ids.length)
+    throw new Error("The cluster contains duplicate member identities.");
+  return ids;
+}
+
+function sameMembers(left, right) {
+  const a = [...left].sort();
+  const b = [...right].sort();
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+function parsePositiveInteger(runtime, value, option) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    runtime.usage(`${option} must be a positive integer.`, { field: option.slice(2) });
+  }
+  return parsed;
+}
+
+function parseTimeoutSeconds(runtime, raw, { required = false } = {}) {
+  if (raw === undefined || raw === null || raw === "") {
+    if (required)
+      runtime.usage("--wait requires an explicit --timeout <duration> in machine mode.", {
+        code: "timeout_required",
+        field: "timeout",
+      });
+    return DEFAULT_WAIT_SECONDS;
+  }
+  const match = String(raw)
+    .trim()
+    .match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/i);
+  if (!match)
+    runtime.usage("--timeout must be a positive duration such as 30s or 10m.", {
+      field: "timeout",
+    });
+  const quantity = Number(match[1]);
+  const multiplier = { ms: 0.001, s: 1, m: 60, h: 3_600 }[(match[2] ?? "s").toLowerCase()];
+  const seconds = quantity * multiplier;
+  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 86_400) {
+    runtime.usage("--timeout must be greater than zero and at most 24h.", { field: "timeout" });
+  }
+  return seconds;
+}
+
+function requireWaitShape(runtime, input) {
+  const timeoutSupplied =
+    input.timeout !== undefined && input.timeout !== null && input.timeout !== "";
+  if (timeoutSupplied) parseTimeoutSeconds(runtime, input.timeout);
+  if (input.wait === true && input.noWait === true) {
+    runtime.usage("Choose only one of --wait or --no-wait.", { code: "conflicting_wait_options" });
+  }
+  if (input.noWait === true && timeoutSupplied) {
+    runtime.usage("--timeout cannot be combined with --no-wait.", {
+      code: "conflicting_wait_options",
+      field: "timeout",
+    });
+  }
+  if (runtime.machine && input.wait !== true && timeoutSupplied) {
+    runtime.usage("Machine --timeout requires explicit --wait.", {
+      code: "timeout_requires_wait",
+      field: "timeout",
+    });
+  }
+  if (runtime.machine && input.wait === true && !timeoutSupplied) {
+    parseTimeoutSeconds(runtime, input.timeout, { required: true });
+  }
+  if (runtime.machine && input.noWait === true) {
+    runtime.usage("Machine mutations already return after durable acceptance; omit --no-wait.", {
+      code: "redundant_no_wait",
+      field: "noWait",
+    });
+  }
+}
+
+function requireMutationKey(runtime, input) {
+  const supplied = text(input.idempotencyKey);
+  if (runtime.machine && !supplied) {
+    runtime.usage(
+      "Machine mutations require --idempotency-key <caller-stable-key> before API I/O.",
+      {
+        code: "idempotency_key_required",
+        field: "idempotencyKey",
+      }
+    );
+  }
+  return supplied ?? runtime.idempotencyKey();
+}
+
+function shouldWait(runtime, input) {
+  return runtime.machine ? input.wait === true : input.noWait !== true;
+}
+
+function clusterResume(cluster) {
+  return { kind: "cluster", ref: cluster.id };
+}
+
+function clusterInspectionAction(cluster) {
+  return {
+    command: `ornn clusters show ${cluster.id}`,
+    description: "Inspect the exact cluster without changing remote work.",
+    type: "command",
+  };
+}
+
+function localWaitExecution(runtime, cluster, kind, lastCluster, accepted = {}) {
+  const timeout = kind === "timeout";
+  return runtime.result({
+    action: clusterInspectionAction(cluster),
+    data: {
+      ...accepted,
+      cluster: lastCluster ?? cluster,
+      remote_work_cancelled: false,
+    },
+    errors: [
+      {
+        code: timeout ? "local_timeout" : "local_interruption",
+        message: timeout
+          ? "The local wait timed out; accepted cluster work was not cancelled."
+          : "The local wait was interrupted; accepted cluster work was not cancelled.",
+        retryable: true,
+        resource_ref: cluster.id,
+      },
+    ],
+    exitCode: timeout ? 124 : 130,
+    outcome: { class: "working", phase: timeout ? "local_timeout" : "local_interruption" },
+    resume: clusterResume(cluster),
+    presentation: {
+      lines: [
+        timeout
+          ? "The local wait timed out; accepted cluster work continues."
+          : "The local wait was interrupted; accepted cluster work continues.",
+      ],
+      next: "ornn clusters wait --guided",
+    },
+  });
+}
+
+function failedClusterWaitExecution(runtime, cluster, error, lastCluster, accepted) {
+  if (!isRecoverableWaitFailure(error)) throw error;
+  const status = Number(error?.status);
+  const authorization = status === 401 || status === 403;
+  const authentication = status === 401;
+  const action = authorization
+    ? {
+        command: "ornn login",
+        description: "Restore an authorized session, then resume the exact accepted cluster.",
+        type: "command",
+      }
+    : clusterInspectionAction(cluster);
+  return runtime.result({
+    action,
+    data: {
+      ...accepted,
+      cluster: lastCluster ?? cluster,
+      remote_work_cancelled: false,
+    },
+    errors: [
+      {
+        code: authentication
+          ? "authentication_required"
+          : authorization
+            ? "authorization_denied"
+            : "service_unavailable",
+        message: authorization
+          ? "The session could not continue waiting; accepted cluster work continues."
+          : "The local wait lost contact with the service; accepted cluster work continues.",
+        retryable: status !== 403,
+        resource_ref: cluster.id,
+      },
+    ],
+    exitCode: authorization ? 5 : 6,
+    outcome: { class: "working", phase: "cluster_accepted" },
+    resume: clusterResume(cluster),
+    presentation: {
+      lines: ["Accepted cluster work continues; no remote cancellation was sent."],
+      next: action.command,
+    },
+  });
+}
+
+function partialClusterExecution(runtime, cluster, accepted = {}) {
+  const failures = cluster.machines.filter((machine) => machine.lifecycle.class === "failed");
+  return runtime.result({
+    action: clusterInspectionAction(cluster),
+    data: {
+      ...accepted,
+      cluster,
+      capacity_reservation: {
+        id: cluster.reservation_id,
+        retained: true,
+        charges_continue: true,
+      },
+    },
+    errors: (failures.length ? failures : [{ id: cluster.id }]).map((failure) => ({
+      code: failures.length ? "cluster_member_failed" : "cluster_provisioning_failed",
+      message: failures.length
+        ? `Cluster member ${failure.id} failed to reach its requested goal.`
+        : "The cluster failed before all requested members became usable.",
+      retryable: true,
+      resource_ref: failure.id,
+    })),
+    exitCode: 4,
+    outcome: { class: "partial", phase: "member_failures" },
+    resume: clusterResume(cluster),
+    presentation: {
+      lines: [
+        failures.length
+          ? `${failures.length} cluster member${failures.length === 1 ? "" : "s"} failed to reach the requested goal.`
+          : "The cluster failed before all requested members became usable.",
+      ],
+      next: "ornn clusters show --guided",
+    },
+  });
+}
+
+async function clusterAccessIsReady(fetch, cluster, signal) {
+  try {
+    const credentials = record(
+      await fetch(clusterPath(cluster, "credentials"), {
+        method: "GET",
+        ...(signal ? { signal } : {}),
+      })
+    );
+    if (cluster.access_mode === "slurm") {
+      return Boolean(text(credentials.login_host));
+    }
+    return Boolean(text(credentials.kubeconfig));
+  } catch (error) {
+    if (error?.status === 404 || error?.retryable === true || Number(error?.status) >= 500)
+      return false;
+    throw error;
+  }
+}
+
+async function fallbackWaitForGoal(spec, deps, runtime) {
+  return waitForReadGoal(spec, {
+    format: runtime.machine ? "json" : "human",
+    now: deps.now,
+    signal: deps.signal,
+    sleep: deps.sleep,
+    stderr: deps.stderr ?? { write() {} },
+    stdout: deps.stdout ?? { write() {} },
+  });
+}
+
+async function waitForClusterGoal({
+  accepted = {},
+  cluster,
+  deps,
+  goalIds,
+  input,
+  requireAccess = false,
+  teardown = false,
+}) {
+  const { fetch, interaction: runtime } = deps;
+  const timeoutSeconds = parseTimeoutSeconds(runtime, input.timeout, {
+    required: runtime.machine,
+  });
+  let lastCluster = cluster;
+  let lastObservation = { access_ready: false, cluster };
+  const poll = async ({ signal } = {}) => {
+    let current;
+    try {
+      current = await fetchClusterDetail(fetch, runtime, cluster, {
+        allowMissing: teardown,
+        signal,
+      });
+    } catch (error) {
+      const status = Number(error?.status);
+      if (error?.retryable !== true && !(Number.isFinite(status) && status >= 500)) throw error;
+      return lastObservation;
+    }
+    const accessReady = Boolean(
+      current &&
+      (current.lifecycle.class === "ready" || current.lifecycle.phase === "credentials_pending") &&
+      (await clusterAccessIsReady(fetch, current, signal))
+    );
+    if (accessReady && current.lifecycle.class !== "ready") {
+      current = {
+        ...current,
+        lifecycle: { class: "ready", phase: "access_ready" },
+      };
+    }
+    if (current) lastCluster = current;
+    lastObservation = { access_ready: accessReady, cluster: current };
+    return lastObservation;
+  };
+  const wait =
+    typeof runtime.waitForGoal === "function"
+      ? runtime.waitForGoal.bind(runtime)
+      : (spec) => fallbackWaitForGoal(spec, deps, runtime);
+  let result;
+  try {
+    result = await wait({
+      command: `ornn clusters wait ${cluster.id}`,
+      initial: lastObservation,
+      timeoutMs: timeoutSeconds * 1_000,
+      intervalMs: POLL_INTERVAL_MS,
+      poll,
+      pollImmediately: true,
+      isReady: (observation) => {
+        const current = observation.cluster;
+        if (teardown) return current === null || current.lifecycle.class === "ended";
+        if (!current) return false;
+        if (goalIds) {
+          return (
+            sameMembers(memberIds(current), goalIds) &&
+            current.machines.every((member) => member.lifecycle.class === "ready") &&
+            (!requireAccess || observation.access_ready)
+          );
+        }
+        return (
+          observation.access_ready &&
+          !["partial", "failed", "ended"].includes(current.lifecycle.class)
+        );
+      },
+      isTerminal: (observation) => {
+        const current = observation.cluster;
+        return Boolean(
+          current &&
+          (current.lifecycle.class === "partial" ||
+            current.lifecycle.class === "failed" ||
+            (!teardown && current.lifecycle.class === "ended"))
+        );
+      },
+      message: (observation) =>
+        `Waiting for the selected ${clusterModeLabel(cluster.access_mode)} cluster: ${observation.cluster?.lifecycle.phase ?? "not found yet"}.`,
+      projectProgress: (observation) => ({
+        access_ready: observation.access_ready,
+        cluster: observation.cluster,
+      }),
+    });
+  } catch (error) {
+    return failedClusterWaitExecution(runtime, cluster, error, lastCluster, accepted);
+  }
+  const current = result.value?.cluster ?? lastCluster;
+  if (result.kind === "timeout" || result.kind === "interrupted") {
+    return localWaitExecution(runtime, cluster, result.kind, current, accepted);
+  }
+  if (result.kind === "terminal") {
+    return partialClusterExecution(runtime, current, accepted);
+  }
+  if (teardown) {
+    const ended = result.value?.cluster ?? {
+      ...cluster,
+      lifecycle: { class: "ended", phase: "torn_down" },
+    };
+    return runtime.result({
+      action: clusterInspectionAction(cluster),
+      data: {
+        ...accepted,
+        cluster: ended,
+        capacity_reservation: {
+          id: cluster.reservation_id,
+          retained: true,
+          charges_continue: true,
+        },
+      },
+      outcome: ended.lifecycle,
+      resume: clusterResume(cluster),
+      presentation: {
+        lines: [
+          `Cluster ${cluster.id} is torn down.`,
+          `Capacity reservation ${cluster.reservation_id} remains active and charges continue.`,
+        ],
+      },
+    });
+  }
+  if (goalIds && !requireAccess) {
+    return runtime.result({
+      action: clusterInspectionAction(current),
+      data: { ...accepted, cluster: current, membership_goal: goalIds },
+      outcome: { class: "ready", phase: "membership_reconciled" },
+      resume: clusterResume(current),
+      presentation: {
+        lines: ["The cluster membership goal is reconciled."],
+        next: "ornn clusters show --guided",
+      },
+    });
+  }
+  return runtime.result({
+    action: clusterInspectionAction(current),
+    data: { ...accepted, cluster: current },
+    outcome: { class: "ready", phase: "access_ready" },
+    resume: clusterResume(current),
+    presentation: {
+      lines: [
+        ...clusterLines(current),
+        `${clusterModeLabel(current.access_mode)} ${clusterNativeAccess(current.access_mode)} is ready.`,
+      ],
+      next: clusterConnectCommand(current),
+    },
+  });
+}
+
+async function fetchReservation(fetch, runtime, reservationId, accessMode = "kubernetes") {
+  const reservation = record(
+    await fetch(`/v1/workflows/commerce/reservations/${encodeURIComponent(reservationId)}`, {
+      method: "GET",
+    })
+  );
+  if (text(reservation.id) !== reservationId) {
+    runtime.error("The gateway returned a different capacity reservation.", {
+      code: "reservation_identity_changed",
+    });
+  }
+  const status = cleanState(reservation.status ?? reservation.state);
+  if (reservationAccessMode(reservation) !== accessMode) {
+    runtime.error(
+      `The selected capacity reservation is not reserved for ${clusterModeLabel(accessMode)}.`,
+      {
+        code: "reservation_access_mode_mismatch",
+      }
+    );
+  }
+  if (status !== "active") {
+    runtime.error(
+      `${clusterModeLabel(accessMode)} launch requires an active capacity reservation.`,
+      {
+        code: "reservation_not_active",
+      }
+    );
+  }
+  return reservation;
+}
+
+async function fetchActiveReservations(fetch, runtime) {
+  const reservations = [];
+  const seen = new Set();
+  let cursor;
+  for (let page = 0; page < 20; page += 1) {
+    const query = new URLSearchParams({ limit: "500", state: "active" });
+    if (cursor) query.set("cursor", cursor);
+    const payload = await fetch(`/v1/workflows/commerce/reservations?${query}`, {
+      method: "GET",
+    });
+    const source = record(payload);
+    const rows = Array.isArray(payload)
+      ? payload
+      : Array.isArray(source.reservations)
+        ? source.reservations
+        : null;
+    if (!rows) {
+      runtime.error("Capacity reservations returned an unsafe response.", {
+        code: "reservation_projection_invalid",
+      });
+    }
+    reservations.push(
+      ...rows.filter((value) => {
+        const reservation = record(value);
+        return (
+          UUID.test(text(reservation.id) ?? "") &&
+          cleanState(reservation.status ?? reservation.state) === "active"
+        );
+      })
+    );
+    const next = text(source.next_cursor);
+    if (!next) return reservations;
+    if (seen.has(next))
+      runtime.error("Capacity-reservation pagination did not advance.", {
+        code: "reservation_pagination_invalid",
+      });
+    seen.add(next);
+    cursor = next;
+  }
+  runtime.error("Capacity-reservation pagination exceeded its safety bound.", {
+    code: "reservation_pagination_invalid",
+  });
+}
+
+async function resolveLaunchReservation(context, runtime, input, accessMode) {
+  const positionals = input.$positionals ?? [];
+  if (positionals.length > 1) {
+    runtime.usage(
+      `Usage: ornn launch --mode ${accessMode} --reservation <reservation-id> --nodes <count>`
+    );
+  }
+  const optionReference = text(input.reservation) ?? text(input.reservationId);
+  const positionalReference = text(positionals[0]);
+  if (optionReference && positionalReference && optionReference !== positionalReference) {
+    runtime.usage("Supply the capacity reservation only once.", { field: "reservation" });
+  }
+  const reference = optionReference ?? positionalReference;
+  if (reference) {
+    if (runtime.machine && !UUID.test(reference)) {
+      runtime.usage("Machine launch requires a canonical capacity-reservation ID.", {
+        code: "canonical_reservation_id_required",
+        field: "reservation",
+      });
+    }
+    return fetchReservation(context.fetch, runtime, reference, accessMode);
+  }
+  if (!runtime.eligibleHuman) {
+    runtime.usage("--reservation <canonical-id> is required outside an interactive terminal.", {
+      code: "reservation_required",
+      field: "reservation",
+    });
+  }
+  const active = (await fetchActiveReservations(context.fetch, runtime)).filter(
+    (reservation) => reservationAccessMode(reservation) === accessMode
+  );
+  if (active.length === 0) {
+    runtime.error(
+      `No active capacity reservation is available for ${clusterModeLabel(accessMode)} launch.`,
+      {
+        code: "active_reservation_not_found",
+      }
+    );
+  }
+  if (active.length === 1) {
+    return fetchReservation(context.fetch, runtime, text(record(active[0]).id), accessMode);
+  }
+  const reservationLabel = await reservationLabeler(context.fetch);
+  const selected = await runtime.ask({
+    label: "Capacity reservation",
+    choices: active.flatMap((value) => {
+      const reservation = record(value);
+      const id = text(reservation.id);
+      return id ? [{ label: reservationLabel(reservation), value: id }] : [];
+    }),
+  });
+  if (!selected)
+    runtime.usage("Choose one exact active capacity reservation.", {
+      code: "reservation_required",
+    });
+  return fetchReservation(context.fetch, runtime, selected, accessMode);
+}
+
+async function selectedOrganization(context, input, runtime) {
+  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) && runtime.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 runtime.ask({ label: "Organization", choices });
+      if (!answer)
+        runtime.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) {
+    runtime.usage("Select one approved organization before launch.", {
+      code: "organization_required",
+      field: "organization",
+    });
+  }
+  return { id, name };
+}
+
+function clusterMachineLaunchPreflight(runtime, input, membershipCount) {
+  const positionals = input.$positionals ?? [];
+  if (positionals.length > 1) {
+    runtime.usage("Supply exactly one capacity reservation.", { field: "reservation" });
+  }
+  const optionReference = text(input.reservation) ?? text(input.reservationId);
+  const positionalReference = text(positionals[0]);
+  if (optionReference && positionalReference) {
+    runtime.usage("Supply the capacity reservation only once.", { field: "reservation" });
+  }
+  const reservationReference = optionReference ?? positionalReference;
+  if (reservationReference && !UUID.test(reservationReference)) {
+    runtime.usage("Cluster launch requires a canonical capacity-reservation ID.", {
+      code: "canonical_reservation_id_required",
+      field: "reservation",
+    });
+  }
+  if (!reservationReference && !runtime.eligibleHuman) {
+    runtime.usage("--reservation <canonical-id> is required outside an interactive terminal.", {
+      code: "reservation_required",
+      field: "reservation",
+    });
+  }
+  if (text(input.machine) && text(input.machines)) {
+    runtime.usage("Choose only one of --machine or --machines.", {
+      code: "conflicting_machine_options",
+      field: "machines",
+    });
+  }
+  if (runtime.eligibleHuman) return;
+  if (!UUID.test(text(input.organization) ?? "")) {
+    runtime.usage("Automation requires a canonical organization ID.", {
+      code: "canonical_organization_id_required",
+      field: "organization",
+    });
+  }
+  if (input.yes !== true) {
+    runtime.usage("--yes is required for automation after reviewing the exact intent.", {
+      code: "consent_required",
+      field: "yes",
+    });
+  }
+  const references = requestedMachineReferences(input);
+  if (membershipCount === null || references.length !== membershipCount) {
+    runtime.usage("Automation requires --machines with exactly the --nodes membership count.", {
+      code: "membership_count_mismatch",
+      field: "machines",
+    });
+  }
+  if (references.some((reference) => !UUID.test(reference))) {
+    runtime.usage("Automation requires canonical machine IDs.", {
+      code: "canonical_machine_id_required",
+      field: "machines",
+    });
+  }
+  if (new Set(references).size !== references.length) {
+    runtime.usage("Each selected machine must be unique.", {
+      code: "duplicate_machine_selection",
+      field: "machines",
+    });
+  }
+}
+
+function requestedMachineReferences(input) {
+  const raw = text(input.machines) ?? text(input.machine) ?? text(input.machineIds);
+  return raw
+    ? raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean)
+    : [];
+}
+
+function exactEligibleMachine(runtime, machines, reference) {
+  if (UUID.test(reference)) {
+    const matches = machines.filter((machine) => machine.id === reference);
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1)
+      runtime.error("Eligible machine identity is ambiguous.", {
+        code: "cluster_eligibility_ambiguous",
+      });
+    runtime.error(`Machine ${reference} is not currently eligible.`, {
+      code: "machine_not_eligible",
+    });
+  }
+  if (runtime.machine) {
+    runtime.usage("Machine mode requires canonical machine IDs.", {
+      code: "canonical_machine_id_required",
+      field: "machines",
+    });
+  }
+  const normalized = reference.toLowerCase();
+  const matches = machines.filter((machine) => machine.hostname.toLowerCase() === normalized);
+  if (matches.length === 0)
+    runtime.error(`Eligible machine hostname not found: ${reference}.`, {
+      code: "machine_not_eligible",
+    });
+  if (matches.length > 1)
+    runtime.usage(`Eligible hostname ${reference} is ambiguous; use a canonical machine ID.`, {
+      code: "cluster_eligibility_ambiguous",
+      field: "machines",
+    });
+  return matches[0];
+}
+
+async function selectLaunchMachines(runtime, input, eligibility, membershipCount, existing) {
+  const references = requestedMachineReferences(input);
+  if (references.length) {
+    if (references.length !== membershipCount) {
+      runtime.usage("--machines must contain exactly the membership count supplied by --nodes.", {
+        code: "membership_count_mismatch",
+        field: "machines",
+      });
+    }
+    const selected = references.map((reference) =>
+      exactEligibleMachine(runtime, eligibility, reference)
+    );
+    if (new Set(selected.map((machine) => machine.id)).size !== selected.length) {
+      runtime.usage("Each selected machine must be unique.", {
+        code: "duplicate_machine_selection",
+      });
+    }
+    return selected;
+  }
+  if (runtime.machine) {
+    runtime.usage("Machine launch requires --machines with exact canonical IDs.", {
+      code: "canonical_machine_id_required",
+      field: "machines",
+    });
+  }
+  if (existing && existing.machines.length === membershipCount) {
+    return existing.machines.map((member) => exactEligibleMachine(runtime, eligibility, member.id));
+  }
+  if (eligibility.length < membershipCount) {
+    runtime.error(
+      `Only ${eligibility.length} machines are eligible for a ${membershipCount}-node cluster.`,
+      {
+        code: "insufficient_eligible_machines",
+      }
+    );
+  }
+  if (eligibility.length === membershipCount) return eligibility;
+  if (!runtime.eligibleHuman || runtime.machine) {
+    runtime.usage(
+      "More eligible machines exist than requested; supply --machines with exact canonical IDs.",
+      {
+        code: "cluster_eligibility_ambiguous",
+        field: "machines",
+      }
+    );
+  }
+  const selected = [];
+  let remaining = eligibility;
+  while (selected.length < membershipCount) {
+    const chosen = await runtime.ask({
+      label: `Machine ${selected.length + 1} of ${membershipCount}`,
+      choices: remaining.map((machine) => ({
+        label: `${machine.hostname} · ${machine.id}`,
+        value: machine.id,
+      })),
+    });
+    const machine = remaining.find((candidate) => candidate.id === chosen);
+    if (!machine)
+      runtime.usage("Choose one exact eligible machine.", { code: "machine_not_eligible" });
+    selected.push(machine);
+    remaining = remaining.filter((candidate) => candidate.id !== machine.id);
+  }
+  return selected;
+}
+
+async function existingReservationCluster(fetch, runtime, reservationId, accessMode) {
+  const matches = (await fetchClusters(fetch)).filter(
+    (cluster) => cluster.reservation_id === reservationId && cluster.access_mode === accessMode
+  );
+  if (matches.length > 1) {
+    runtime.error(
+      `More than one ${clusterModeLabel(accessMode)} cluster exists for this reservation.`,
+      {
+        code: "cluster_ambiguous",
+      }
+    );
+  }
+  return matches.length ? requireValidCluster(runtime, matches[0]) : null;
+}
+
+function launchAccepted(runtime, cluster, requested, replayed) {
+  const label = clusterModeLabel(cluster.access_mode);
+  return runtime.result({
+    action: clusterInspectionAction(cluster),
+    data: { cluster, replayed, requested },
+    outcome: replayed ? cluster.lifecycle : { class: "working", phase: "accepted" },
+    resume: clusterResume(cluster),
+    presentation: {
+      lines: [
+        replayed
+          ? `${label} cluster already satisfies this launch goal.`
+          : `${label} cluster was accepted for provisioning.`,
+        `Membership goal: ${requested.membership_count}`,
+      ],
+      next: "ornn clusters wait --guided",
+    },
+  });
+}
+
+export async function launchClusterMode(
+  { context, input, interaction: runtime },
+  accessMode = "kubernetes"
+) {
+  if (!["kubernetes", "slurm"].includes(accessMode)) {
+    throw new TypeError(`Unsupported cluster launch mode: ${accessMode}`);
+  }
+  const label = clusterModeLabel(accessMode);
+  requireWaitShape(runtime, input);
+  const membershipValue = input.nodes ?? input.nodeCount;
+  let membershipCount =
+    membershipValue === undefined || membershipValue === null
+      ? null
+      : parsePositiveInteger(runtime, membershipValue, "--nodes");
+  if (membershipCount === null && !runtime.eligibleHuman) {
+    runtime.usage("--nodes is required outside an interactive terminal.", {
+      code: "missing_input",
+      field: "nodes",
+    });
+  }
+  let networkMode = text(input.network) ?? text(input.networkMode);
+  if (!networkMode && !runtime.eligibleHuman) {
+    runtime.usage("--network public|private is required for automation.", {
+      code: "missing_input",
+      field: "network",
+    });
+  }
+  if (!networkMode) {
+    networkMode = await runtime.ask({
+      label: "Network mode",
+      choices: [
+        { label: "Public", value: "public" },
+        { label: "Private", value: "private" },
+      ],
+    });
+  }
+  if (!["public", "private"].includes(networkMode)) {
+    runtime.usage("--network must be public or private.", { field: "network" });
+  }
+  clusterMachineLaunchPreflight(runtime, input, membershipCount);
+  if (accessMode === "slurm") keyInputShapePreflight(input, runtime);
+  const idempotencyKey = requireMutationKey(runtime, input);
+  const organization = await selectedOrganization(context, input, runtime);
+  const keyPlan = accessMode === "slurm" ? await keyPlanFromInput(context, input, runtime) : null;
+  const reservation = await resolveLaunchReservation(context, runtime, input, accessMode);
+  const reservationId = text(reservation.id);
+  const initialExisting = await existingReservationCluster(
+    context.fetch,
+    runtime,
+    reservationId,
+    accessMode
+  );
+  const initialEligibility = await fetchEligibility(
+    context.fetch,
+    runtime,
+    reservationId,
+    accessMode
+  );
+  const requestedReferences = requestedMachineReferences(input);
+  const emptyProvisioningReplay =
+    Boolean(initialExisting) &&
+    initialExisting.lifecycle.phase === "provisioning" &&
+    memberIds(initialExisting).length === 0 &&
+    membershipCount !== null &&
+    requestedReferences.length === membershipCount &&
+    requestedReferences.every((reference) => UUID.test(reference));
+  if (initialEligibility.length === 0 && !emptyProvisioningReplay) {
+    runtime.error(`No machines are currently eligible for ${label} launch.`, {
+      code: "no_eligible_machines",
+    });
+  }
+  if (membershipCount === null) {
+    const answer = await runtime.ask({
+      label: "Cluster size",
+      choices: initialEligibility.map((_, index) => {
+        const count = index + 1;
+        return {
+          label: `${count} machine${count === 1 ? "" : "s"}`,
+          value: String(count),
+        };
+      }),
+    });
+    membershipCount = parsePositiveInteger(runtime, answer, "--nodes");
+  }
+  const selected = emptyProvisioningReplay
+    ? requestedReferences.map((id) => ({ id, hostname: id }))
+    : await selectLaunchMachines(
+        runtime,
+        input,
+        initialEligibility,
+        membershipCount,
+        initialExisting
+      );
+  const selectedIds = selected.map((machine) => machine.id).sort();
+  const reviewedKey = record(keyPlan?.key);
+  const requested = {
+    reservation_id: reservationId,
+    access_mode: accessMode,
+    network_mode: networkMode,
+    membership_count: membershipCount,
+    machine_ids: selectedIds,
+    idempotency_key: idempotencyKey,
+    organization,
+    ...(keyPlan
+      ? {
+          ssh_key: {
+            id: text(reviewedKey.id),
+            label: text(reviewedKey.label),
+            fingerprint: text(reviewedKey.fingerprint),
+          },
+        }
+      : {}),
+  };
+  if (initialExisting) {
+    const current = await fetchClusterDetail(context.fetch, runtime, initialExisting);
+    if (current.network_mode && current.network_mode !== networkMode) {
+      runtime.error(
+        `This reservation already has a ${label} cluster with a different network goal.`,
+        { code: "cluster_launch_goal_conflict" }
+      );
+    }
+    const currentIds = memberIds(current);
+    if (currentIds.length === 0) {
+      if (current.lifecycle.phase !== "provisioning") {
+        runtime.error(
+          `This reservation already has a ${label} cluster with an empty non-recoverable membership.`,
+          { code: "cluster_launch_goal_conflict" }
+        );
+      }
+    } else {
+      if (!sameMembers(currentIds, selectedIds)) {
+        runtime.error(
+          `This reservation already has a ${label} cluster with a different membership goal.`,
+          { code: "cluster_launch_goal_conflict" }
+        );
+      }
+      if (
+        accessMode !== "slurm" &&
+        current.lifecycle.class === "ready" &&
+        current.network_mode === networkMode
+      ) {
+        return shouldWait(runtime, input)
+          ? waitForClusterGoal({
+              accepted: { replayed: true, requested },
+              cluster: current,
+              deps: {
+                fetch: context.fetch,
+                interaction: runtime,
+                now: runtime.now,
+                signal: runtime.signal,
+                sleep: runtime.sleep,
+              },
+              goalIds: selectedIds,
+              input,
+              requireAccess: true,
+            })
+          : launchAccepted(runtime, current, requested, true);
+      }
+    }
+  }
+  const reviewEligibility = await fetchEligibility(
+    context.fetch,
+    runtime,
+    reservationId,
+    accessMode
+  );
+  if (eligibilitySignature(reviewEligibility) !== eligibilitySignature(initialEligibility)) {
+    runtime.error(`${label} eligibility changed before review; no cluster was created.`, {
+      code: "cluster_eligibility_changed",
+    });
+  }
+  const confirmed = await runtime.review({
+    title: `Launch ${label} cluster`,
+    terms: [
+      { label: "Organization", value: `${organization.name} (${organization.id})` },
+      { label: "Capacity reservation", value: reservationId },
+      { label: "Access mode", value: label },
+      { label: "Network", value: networkMode },
+      ...(keyPlan
+        ? [
+            {
+              label: "SSH key",
+              value: `${text(reviewedKey.label) ?? "SSH key"} (${text(reviewedKey.fingerprint) ?? text(reviewedKey.id) ?? "new key"})`,
+            },
+          ]
+        : []),
+      { label: "Cluster membership", value: String(membershipCount) },
+      ...selected.map((machine, index) => ({
+        label: `Machine ${index + 1}`,
+        value: `${machine.hostname} (${machine.id})`,
+      })),
+    ],
+  });
+  if (!confirmed) {
+    return runtime.result({
+      data: { created: false, requested },
+      exitCode: 1,
+      outcome: { class: "ended", phase: "declined" },
+      presentation: { lines: ["No cluster was created."] },
+    });
+  }
+  const currentOrganization = await selectedOrganization(
+    context,
+    { organization: organization.id },
+    runtime
+  );
+  if (currentOrganization.id !== organization.id) {
+    runtime.error("The selected organization changed after review; no cluster was created.", {
+      code: "organization_changed",
+      exitCode: 2,
+    });
+  }
+  await fetchReservation(context.fetch, runtime, reservationId, accessMode);
+  const racedExisting = await existingReservationCluster(
+    context.fetch,
+    runtime,
+    reservationId,
+    accessMode
+  );
+  if (racedExisting) {
+    const current = await fetchClusterDetail(context.fetch, runtime, racedExisting);
+    if (current.network_mode && current.network_mode !== networkMode) {
+      runtime.error(`A different ${label} network goal was accepted after review.`, {
+        code: "cluster_launch_goal_conflict",
+      });
+    }
+    const currentIds = memberIds(current);
+    if (currentIds.length === 0) {
+      if (current.lifecycle.phase !== "provisioning") {
+        runtime.error(`A non-recoverable empty ${label} cluster appeared after review.`, {
+          code: "cluster_launch_goal_conflict",
+        });
+      }
+    } else {
+      if (!sameMembers(currentIds, selectedIds)) {
+        runtime.error(`A different ${label} membership goal was accepted after review.`, {
+          code: "cluster_launch_goal_conflict",
+        });
+      }
+      if (
+        accessMode !== "slurm" &&
+        current.lifecycle.class === "ready" &&
+        current.network_mode === networkMode
+      ) {
+        return shouldWait(runtime, input)
+          ? waitForClusterGoal({
+              accepted: { replayed: true, requested },
+              cluster: current,
+              deps: { fetch: context.fetch, interaction: runtime },
+              goalIds: selectedIds,
+              input,
+              requireAccess: true,
+            })
+          : launchAccepted(runtime, current, requested, true);
+      }
+    }
+  }
+  const createEligibility = await fetchEligibility(
+    context.fetch,
+    runtime,
+    reservationId,
+    accessMode
+  );
+  if (eligibilitySignature(createEligibility) !== eligibilitySignature(reviewEligibility)) {
+    runtime.error(`${label} eligibility changed after review; no cluster was created.`, {
+      code: "cluster_eligibility_changed",
+    });
+  }
+  const selectedKey = keyPlan
+    ? await materializeKey(context, keyPlan, runtime, idempotencyKey)
+    : null;
+  const selectedKeyId = text(record(selectedKey).id);
+  if (selectedKey && !UUID.test(selectedKeyId ?? "")) {
+    runtime.error("The selected SSH key did not resolve to a canonical organization key.", {
+      code: "ssh_key_correlation_changed",
+    });
+  }
+  if (selectedKeyId && requested.ssh_key) requested.ssh_key.id = selectedKeyId;
+  const response = await context.fetch(
+    `/v1/workflows/compute/${accessMode}/reservations/${encodeURIComponent(reservationId)}/cluster/launch`,
+    {
+      method: "POST",
+      headers: { "Idempotency-Key": idempotencyKey },
+      body: {
+        network_mode: networkMode,
+        node_count: membershipCount,
+        node_ids: selectedIds,
+        ...(selectedKeyId ? { ssh_key_ids: [selectedKeyId] } : {}),
+      },
+    }
+  );
+  let cluster = projectCluster(response);
+  if (!UUID.test(cluster.id ?? "")) {
+    cluster = await existingReservationCluster(context.fetch, runtime, reservationId, accessMode);
+  }
+  if (!cluster) {
+    runtime.error(
+      "Cluster launch was accepted but its durable cluster could not be rediscovered.",
+      {
+        code: "accepted_cluster_not_found",
+        exitCode: 4,
+        outcomeClass: "partial",
+        retryable: true,
+      }
+    );
+  }
+  requireValidCluster(runtime, cluster);
+  const replayed = Boolean(initialExisting || racedExisting);
+  if (runtime.eligibleHuman && runtime.stderr) {
+    runtime.stderr.write(`${label} cluster ${cluster.id} accepted.\n`);
+  }
+  if (!shouldWait(runtime, input)) return launchAccepted(runtime, cluster, requested, replayed);
+  return waitForClusterGoal({
+    accepted: { replayed, requested },
+    cluster,
+    deps: {
+      fetch: context.fetch,
+      interaction: runtime,
+      now: runtime.now,
+      signal: runtime.signal,
+      sleep: runtime.sleep,
+      stderr: runtime.stderr,
+    },
+    goalIds: selectedIds,
+    input,
+    requireAccess: true,
+  });
+}
+
+function encodeCursor(command, offset) {
+  return Buffer.from(JSON.stringify({ command, offset }), "utf8").toString("base64url");
+}
+
+function decodeCursor(runtime, command, cursor) {
+  if (!cursor) return 0;
+  if (typeof cursor !== "string" || cursor.length > 512) {
+    runtime.usage("The pagination cursor is invalid or belongs to another command.", {
+      code: "invalid_cursor",
+      field: "cursor",
+    });
+  }
+  try {
+    const parsed = record(JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")));
+    if (
+      Object.keys(parsed).sort().join(",") === "command,offset" &&
+      parsed.command === command &&
+      Number.isInteger(parsed.offset) &&
+      parsed.offset >= 0
+    ) {
+      return parsed.offset;
+    }
+  } catch {
+    // The stable usage error below intentionally keeps cursor internals opaque.
+  }
+  runtime.usage("The pagination cursor is invalid or belongs to another command.", {
+    code: "invalid_cursor",
+    field: "cursor",
+  });
+}
+
+function boundedPage(runtime, command, rows, input) {
+  const limit = input.limit === undefined ? DEFAULT_LIMIT : Number(input.limit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    runtime.usage(`--limit must be an integer from 1 to ${MAX_LIMIT}.`, { field: "limit" });
+  }
+  const offset = decodeCursor(runtime, command, input.cursor);
+  const items = rows.slice(offset, offset + limit);
+  const nextOffset = offset + items.length;
+  return {
+    items,
+    page: {
+      limit,
+      returned: items.length,
+      next_cursor: nextOffset < rows.length ? encodeCursor(command, nextOffset) : null,
+    },
+  };
+}
+
+async function listClusters(input, deps) {
+  if ((input.$positionals ?? []).length > 0) {
+    deps.interaction.usage("Usage: ornn clusters list [--limit <1-500>] [--cursor <opaque>]", {
+      code: "clusters_list_arguments",
+    });
+  }
+  const clusters = (await fetchClusters(deps.fetch)).map((cluster) =>
+    requireValidCluster(deps.interaction, cluster)
+  );
+  const selected = boundedPage(deps.interaction, "clusters list", clusters, input);
+  return deps.interaction.result({
+    data: { clusters: selected.items },
+    page: selected.page,
+    presentation: {
+      lines: selected.items.length ? selected.items.flatMap(clusterLines) : ["No clusters found."],
+      ...(selected.page.next_cursor
+        ? { next: `ornn clusters list --cursor ${selected.page.next_cursor}` }
+        : {}),
+    },
+  });
+}
+
+async function showCluster(input, deps) {
+  const selected = await resolveCluster(deps.fetch, deps.interaction, input);
+  const cluster = await fetchClusterDetail(deps.fetch, deps.interaction, selected);
+  return deps.interaction.result({
+    action: clusterInspectionAction(cluster),
+    data: { cluster },
+    outcome: cluster.lifecycle,
+    resume: clusterResume(cluster),
+    presentation: { lines: clusterLines(cluster) },
+  });
+}
+
+async function waitCluster(input, deps) {
+  if (input.noWait === true || input.wait === true) {
+    deps.interaction.usage("clusters wait already waits; supply only an optional --timeout.");
+  }
+  if (deps.interaction.machine && input.timeout === undefined) {
+    deps.interaction.usage("Machine clusters wait requires --timeout <duration>.", {
+      code: "timeout_required",
+      field: "timeout",
+    });
+  }
+  const selected = await resolveCluster(deps.fetch, deps.interaction, input);
+  return waitForClusterGoal({ cluster: selected, deps, input });
+}
+
+async function eligibleMachines(input, deps) {
+  const cluster = await resolveCluster(deps.fetch, deps.interaction, input);
+  const machines = await fetchEligibility(
+    deps.fetch,
+    deps.interaction,
+    cluster.reservation_id,
+    cluster.access_mode
+  );
+  const selected = boundedPage(deps.interaction, "clusters eligible-machines", machines, input);
+  return deps.interaction.result({
+    data: { cluster, machines: selected.items },
+    page: selected.page,
+    presentation: {
+      lines: selected.items.length
+        ? selected.items.map((machine) => `${machine.hostname} (${machine.id})`)
+        : ["No machines are currently eligible."],
+      ...(selected.page.next_cursor
+        ? {
+            next: `ornn clusters eligible-machines --guided --cursor ${selected.page.next_cursor}`,
+          }
+        : {}),
+    },
+  });
+}
+
+async function clusterForMutation(input, deps) {
+  requireWaitShape(deps.interaction, input);
+  const idempotencyKey = requireMutationKey(deps.interaction, input);
+  const positionals = input.$positionals ?? [];
+  if (positionals.length < 1 || positionals.length > 2) {
+    if (input.guided !== true)
+      deps.interaction.usage("Supply a cluster and machine reference, or use --guided.");
+  }
+  const clusterInput = { ...input, $positionals: positionals.slice(0, 1) };
+  const cluster = await resolveCluster(deps.fetch, deps.interaction, clusterInput);
+  const current = await fetchClusterDetail(deps.fetch, deps.interaction, cluster);
+  return {
+    cluster: current,
+    idempotencyKey,
+    machineReference: text(positionals[1]) ?? text(input.machine),
+  };
+}
+
+async function addNode(input, deps) {
+  const prepared = await clusterForMutation(input, deps);
+  const initialMembers = memberIds(prepared.cluster);
+  const initialEligibility = await fetchEligibility(
+    deps.fetch,
+    deps.interaction,
+    prepared.cluster.reservation_id,
+    prepared.cluster.access_mode
+  );
+  const candidates = initialEligibility.filter((machine) => !initialMembers.includes(machine.id));
+  let machine;
+  if (prepared.machineReference) {
+    const requested = exactEligibleMachine(
+      deps.interaction,
+      initialEligibility,
+      prepared.machineReference
+    );
+    if (initialMembers.includes(requested.id)) {
+      return deps.interaction.result({
+        action: clusterInspectionAction(prepared.cluster),
+        data: {
+          cluster: prepared.cluster,
+          membership_goal: initialMembers,
+          replayed: true,
+        },
+        outcome: { class: "ready", phase: "membership_reconciled" },
+        resume: clusterResume(prepared.cluster),
+      });
+    }
+    machine = requested;
+  } else {
+    if (input.guided !== true || !deps.interaction.eligibleHuman) {
+      deps.interaction.usage(
+        "A canonical eligible machine ID is required unless --guided is supplied.",
+        {
+          field: "machine",
+        }
+      );
+    }
+    if (candidates.length === 0)
+      deps.interaction.error("No additional machine is currently eligible.", {
+        code: "no_eligible_machines",
+      });
+    if (candidates.length === 1) machine = candidates[0];
+    else {
+      const selected = await deps.interaction.ask({
+        label: "Eligible machine",
+        choices: candidates.map((candidate) => ({
+          label: `${candidate.hostname} · ${candidate.id}`,
+          value: candidate.id,
+        })),
+      });
+      machine = candidates.find((candidate) => candidate.id === selected);
+    }
+  }
+  if (!machine)
+    deps.interaction.usage("Choose one exact eligible machine.", { code: "machine_not_eligible" });
+  const goalIds = [...initialMembers, machine.id].sort();
+  const confirmed = await deps.interaction.review({
+    title: `Add ${clusterModeLabel(prepared.cluster.access_mode)} cluster node`,
+    terms: [
+      { label: "Cluster", value: prepared.cluster.id },
+      { label: "Machine", value: `${machine.hostname} (${machine.id})` },
+      { label: "Membership goal", value: String(goalIds.length) },
+    ],
+  });
+  if (!confirmed)
+    return deps.interaction.result({
+      data: { changed: false, cluster: prepared.cluster },
+      exitCode: 1,
+      outcome: { class: "ended", phase: "declined" },
+      presentation: { lines: ["Cluster membership was not changed."] },
+    });
+  const current = await fetchClusterDetail(deps.fetch, deps.interaction, prepared.cluster);
+  const currentIds = memberIds(current);
+  if (sameMembers(currentIds, goalIds)) {
+    return deps.interaction.result({
+      data: { cluster: current, membership_goal: goalIds, replayed: true },
+      outcome: { class: "ready", phase: "membership_reconciled" },
+      resume: clusterResume(current),
+    });
+  }
+  if (!sameMembers(currentIds, initialMembers)) {
+    deps.interaction.error("Cluster membership changed after review; no node was added.", {
+      code: "cluster_membership_changed",
+    });
+  }
+  const currentEligibility = await fetchEligibility(
+    deps.fetch,
+    deps.interaction,
+    current.reservation_id,
+    current.access_mode
+  );
+  if (eligibilitySignature(currentEligibility) !== eligibilitySignature(initialEligibility)) {
+    deps.interaction.error("Eligible machines changed after review; no node was added.", {
+      code: "cluster_eligibility_changed",
+    });
+  }
+  await deps.fetch(
+    `/v1/workflows/compute/clusters/reservations/${encodeURIComponent(current.reservation_id)}/cluster/nodes`,
+    {
+      method: "POST",
+      headers: { "Idempotency-Key": prepared.idempotencyKey },
+      body: { node_id: machine.id },
+    }
+  );
+  const accepted = { membership_goal: goalIds, replayed: false };
+  if (!shouldWait(deps.interaction, input))
+    return deps.interaction.result({
+      action: clusterInspectionAction(current),
+      data: { ...accepted, cluster: current },
+      outcome: { class: "working", phase: "membership_accepted" },
+      resume: clusterResume(current),
+    });
+  return waitForClusterGoal({ accepted, cluster: current, deps, goalIds, input });
+}
+
+async function removeNode(input, deps) {
+  const prepared = await clusterForMutation(input, deps);
+  const initialMembers = memberIds(prepared.cluster);
+  const eligibility = await fetchEligibility(
+    deps.fetch,
+    deps.interaction,
+    prepared.cluster.reservation_id,
+    prepared.cluster.access_mode
+  );
+  const labels = new Map(eligibility.map((machine) => [machine.id, machine.hostname]));
+  const members = initialMembers.map((id) => ({ id, hostname: labels.get(id) ?? id }));
+  let machine;
+  if (prepared.machineReference) {
+    if (
+      UUID.test(prepared.machineReference) &&
+      !initialMembers.includes(prepared.machineReference)
+    ) {
+      return deps.interaction.result({
+        action: clusterInspectionAction(prepared.cluster),
+        data: {
+          cluster: prepared.cluster,
+          membership_goal: initialMembers,
+          replayed: true,
+        },
+        outcome: { class: "ready", phase: "membership_reconciled" },
+        resume: clusterResume(prepared.cluster),
+      });
+    }
+    machine = exactEligibleMachine(deps.interaction, members, prepared.machineReference);
+  } else {
+    if (input.guided !== true || !deps.interaction.eligibleHuman) {
+      deps.interaction.usage(
+        "A canonical member machine ID is required unless --guided is supplied.",
+        {
+          field: "machine",
+        }
+      );
+    }
+    if (members.length === 0)
+      deps.interaction.error("This cluster has no members to remove.", {
+        code: "cluster_member_not_found",
+      });
+    if (members.length === 1) machine = members[0];
+    else {
+      const selected = await deps.interaction.ask({
+        label: "Cluster member",
+        choices: members.map((member) => ({
+          label: `${member.hostname} · ${member.id}`,
+          value: member.id,
+        })),
+      });
+      machine = members.find((member) => member.id === selected);
+    }
+  }
+  if (!machine)
+    deps.interaction.usage("Choose one exact cluster member.", {
+      code: "cluster_member_not_found",
+    });
+  const goalIds = initialMembers.filter((id) => id !== machine.id);
+  const confirmed = await deps.interaction.review({
+    title: `Remove ${clusterModeLabel(prepared.cluster.access_mode)} cluster node`,
+    terms: [
+      { label: "Cluster", value: prepared.cluster.id },
+      { label: "Machine", value: `${machine.hostname} (${machine.id})` },
+      { label: "Membership goal", value: String(goalIds.length) },
+      { label: "Consequence", value: "Workloads and native access on this member stop." },
+    ],
+  });
+  if (!confirmed)
+    return deps.interaction.result({
+      data: { changed: false, cluster: prepared.cluster },
+      exitCode: 1,
+      outcome: { class: "ended", phase: "declined" },
+      presentation: { lines: ["Cluster membership was not changed."] },
+    });
+  const current = await fetchClusterDetail(deps.fetch, deps.interaction, prepared.cluster);
+  const currentIds = memberIds(current);
+  if (sameMembers(currentIds, goalIds)) {
+    return deps.interaction.result({
+      data: { cluster: current, membership_goal: goalIds, replayed: true },
+      outcome: { class: "ready", phase: "membership_reconciled" },
+      resume: clusterResume(current),
+    });
+  }
+  if (!sameMembers(currentIds, initialMembers)) {
+    deps.interaction.error("Cluster membership changed after review; no node was removed.", {
+      code: "cluster_membership_changed",
+    });
+  }
+  await deps.fetch(
+    `/v1/workflows/compute/clusters/reservations/${encodeURIComponent(current.reservation_id)}/cluster/nodes/${encodeURIComponent(machine.id)}`,
+    {
+      method: "DELETE",
+      headers: { "Idempotency-Key": prepared.idempotencyKey },
+    }
+  );
+  const accepted = { membership_goal: goalIds, replayed: false };
+  if (!shouldWait(deps.interaction, input))
+    return deps.interaction.result({
+      action: clusterInspectionAction(current),
+      data: { ...accepted, cluster: current },
+      outcome: { class: "working", phase: "membership_accepted" },
+      resume: clusterResume(current),
+    });
+  return waitForClusterGoal({ accepted, cluster: current, deps, goalIds, input });
+}
+
+async function teardownCluster(input, deps) {
+  requireWaitShape(deps.interaction, input);
+  const idempotencyKey = requireMutationKey(deps.interaction, input);
+  const selected = await resolveCluster(deps.fetch, deps.interaction, input);
+  const reviewed = await fetchClusterDetail(deps.fetch, deps.interaction, selected);
+  if (reviewed.lifecycle.class === "ended") {
+    return deps.interaction.result({
+      action: clusterInspectionAction(reviewed),
+      data: {
+        cluster: reviewed,
+        replayed: true,
+        capacity_reservation: {
+          id: reviewed.reservation_id,
+          retained: true,
+          charges_continue: true,
+        },
+      },
+      outcome: reviewed.lifecycle,
+      resume: clusterResume(reviewed),
+      presentation: {
+        lines: [
+          `Cluster ${reviewed.id} is already torn down.`,
+          `Capacity reservation ${reviewed.reservation_id} remains active and charges continue.`,
+        ],
+      },
+    });
+  }
+  if (reviewed.lifecycle.class === "working" && reviewed.lifecycle.phase === "tearing_down") {
+    return shouldWait(deps.interaction, input)
+      ? waitForClusterGoal({
+          accepted: { replayed: true },
+          cluster: reviewed,
+          deps,
+          input,
+          teardown: true,
+        })
+      : deps.interaction.result({
+          action: clusterInspectionAction(reviewed),
+          data: {
+            cluster: reviewed,
+            replayed: true,
+            capacity_reservation: {
+              id: reviewed.reservation_id,
+              retained: true,
+              charges_continue: true,
+            },
+          },
+          outcome: reviewed.lifecycle,
+          resume: clusterResume(reviewed),
+        });
+  }
+  const reviewedMembers = memberIds(reviewed);
+  const confirmed = await deps.interaction.review({
+    title: `Tear down ${clusterModeLabel(reviewed.access_mode)} cluster`,
+    terms: [
+      { label: "Cluster", value: reviewed.id },
+      { label: "Members", value: String(reviewedMembers.length) },
+      {
+        label: "Native access",
+        value: `${clusterNativeAccess(reviewed.access_mode)} access ends.`,
+      },
+      { label: "Capacity reservation", value: `${reviewed.reservation_id} remains active.` },
+      { label: "Charges", value: "Capacity charges continue after cluster teardown." },
+    ],
+  });
+  if (!confirmed)
+    return deps.interaction.result({
+      data: { changed: false, cluster: reviewed },
+      exitCode: 1,
+      outcome: { class: "ready", phase: "unchanged" },
+      presentation: { lines: ["The cluster remains active. Capacity charges continue."] },
+    });
+  const current = await fetchClusterDetail(deps.fetch, deps.interaction, reviewed);
+  if (!sameMembers(memberIds(current), reviewedMembers)) {
+    deps.interaction.error("Cluster membership changed after review; teardown was not submitted.", {
+      code: "cluster_membership_changed",
+    });
+  }
+  await deps.fetch(clusterPath(current, "cluster/teardown"), {
+    method: "POST",
+    headers: { "Idempotency-Key": idempotencyKey },
+  });
+  const accepted = {
+    replayed: false,
+    capacity_reservation: { id: current.reservation_id, retained: true, charges_continue: true },
+  };
+  if (!shouldWait(deps.interaction, input))
+    return deps.interaction.result({
+      action: clusterInspectionAction(current),
+      data: { ...accepted, cluster: current },
+      outcome: { class: "working", phase: "teardown_accepted" },
+      resume: clusterResume(current),
+      presentation: {
+        lines: [
+          `Cluster ${current.id} teardown was accepted.`,
+          `Capacity reservation ${current.reservation_id} remains active and charges continue.`,
+        ],
+      },
+    });
+  return waitForClusterGoal({ accepted, cluster: current, deps, input, teardown: true });
+}
+
+export async function executeKubernetesClusterCommand(command, input, deps) {
+  const handlers = {
+    "clusters.add_node": addNode,
+    "clusters.eligible_machines": eligibleMachines,
+    "clusters.list": listClusters,
+    "clusters.remove_node": removeNode,
+    "clusters.show": showCluster,
+    "clusters.teardown": teardownCluster,
+    "clusters.wait": waitCluster,
+  };
+  const handler = handlers[command];
+  if (!handler) throw new Error(`Unsupported cluster command: ${command}`);
+  return handler(input, deps);
+}
+
+function projectReservationFacts(value, expectedId, runtime) {
+  const reservation = record(value);
+  const id = text(reservation.id);
+  if (id !== expectedId) {
+    runtime.error("The gateway returned facts for a different capacity reservation.", {
+      code: "reservation_identity_changed",
+    });
+  }
+  return {
+    id,
+    facility:
+      text(reservation.facility_name) ??
+      text(reservation.site_nickname) ??
+      text(reservation.facility),
+    hardware: text(reservation.gpu_type) ?? text(reservation.hardware),
+    machine_count: integer(reservation.node_count) ?? integer(reservation.machines),
+    region: text(reservation.region),
+  };
+}
+
+export async function reservationFactsForCluster(fetch, runtime, cluster) {
+  const payload = await fetch(
+    `/v1/workflows/commerce/reservations/${encodeURIComponent(cluster.reservation_id)}`,
+    { method: "GET" }
+  );
+  return projectReservationFacts(payload, cluster.reservation_id, runtime);
+}
+
+export function clusterFactLabel(cluster, reservation, gpuLabel) {
+  const location = reservation.facility ?? reservation.region ?? "location unknown";
+  const gpu = reservation.hardware ?? cluster.gpu_type;
+  const hardware = gpu ? gpuLabel(gpu) : "hardware unknown";
+  const nodeCount =
+    integer(cluster.membership_count) ??
+    integer(cluster.node_count) ??
+    (Array.isArray(cluster.machines) ? cluster.machines.length : 0);
+  const lifecycle = text(record(cluster.lifecycle).class) ?? text(cluster.state) ?? "unknown";
+  return `${location} · ${clusterModeLabel(cluster.access_mode)} · ${hardware} · ${nodeCount} nodes · ${lifecycle}`;
+}
+const clusterConnectCandidatesCache = new WeakMap();
+
+export async function clusterModeConnectCandidates(state, accessMode) {
+  const { context, interaction: runtime } = state;
+  let clusters = clusterConnectCandidatesCache.get(context);
+  if (!clusters) {
+    clusters = fetchClusters(context.fetch);
+    clusterConnectCandidatesCache.set(context, clusters);
+  }
+  const available = (await clusters)
+    .filter((cluster) => cluster.access_mode === accessMode && cluster.lifecycle.class !== "ended")
+    .map((cluster) => requireValidCluster(runtime, cluster));
+  const gpuLabel = await gpuLabeler(context.fetch);
+  return Promise.all(
+    available.map(async (cluster) => ({
+      label: clusterFactLabel(
+        cluster,
+        await reservationFactsForCluster(context.fetch, runtime, cluster),
+        gpuLabel
+      ),
+      reference: cluster.id,
+    }))
+  );
+}
+
+export async function resolveClusterModeConnectTarget(state, accessMode) {
+  const { context, interaction: runtime } = state;
+  const reference = text(state.reference);
+  const available = (await fetchClusters(context.fetch))
+    .filter((cluster) => cluster.access_mode === accessMode && cluster.lifecycle.class !== "ended")
+    .map((cluster) => requireValidCluster(runtime, cluster));
+  let selected = null;
+  if (reference) {
+    const byId = available.filter((cluster) => cluster.id === reference);
+    if (byId.length > 1) {
+      runtime.error("The gateway returned duplicate canonical cluster identities.", {
+        code: "cluster_ambiguous",
+      });
+    }
+    if (byId.length === 1) {
+      selected = byId[0];
+    } else {
+      const byReservation = available.filter((cluster) => cluster.reservation_id === reference);
+      if (byReservation.length > 1) {
+        runtime.error(
+          `More than one ${clusterModeLabel(accessMode)} cluster matches this capacity reservation.`,
+          {
+            code: "cluster_ambiguous",
+          }
+        );
+      }
+      if (byReservation.length === 1) selected = byReservation[0];
+    }
+    if (!selected) return null;
+  } else {
+    if (runtime.machine) return null;
+    if (available.length === 0) return null;
+    if (available.length === 1) {
+      selected = available[0];
+    } else {
+      const choices = [];
+      const gpuLabel = await gpuLabeler(context.fetch);
+      for (const cluster of available) {
+        const reservation = await reservationFactsForCluster(context.fetch, runtime, cluster);
+        choices.push({
+          label: clusterFactLabel(cluster, reservation, gpuLabel),
+          value: cluster.id,
+        });
+      }
+      const selectedId = await runtime.ask({
+        label: `${clusterModeLabel(accessMode)} cluster`,
+        choices,
+      });
+      selected = available.find((cluster) => cluster.id === selectedId) ?? null;
+      if (!selected) {
+        runtime.usage("Choose one exact cluster from the current reservation and node facts.", {
+          code: "cluster_reference_required",
+          field: "cluster",
+        });
+      }
+    }
+  }
+  const current = await fetchClusterDetail(context.fetch, runtime, selected);
+  const capacityReservation = await reservationFactsForCluster(context.fetch, runtime, current);
+  return {
+    capacityReservation,
+    cluster: current,
+    context,
+    input: state.input,
+    interaction: runtime,
+    mode: accessMode,
+    privateTransportRequired: current.network_mode === "private",
+    reservationId: current.reservation_id,
+    targetReference: reference,
+  };
+}
+
+export async function readClusterModeConnectContext(state, accessMode) {
+  const runtime = state.interaction;
+  let cluster =
+    state.cluster?.access_mode === accessMode ? requireValidCluster(runtime, state.cluster) : null;
+  if (!cluster) {
+    const matches = (await fetchClusters(state.context.fetch)).filter(
+      (candidate) =>
+        candidate.access_mode === accessMode &&
+        candidate.reservation_id === state.reservationId &&
+        candidate.lifecycle.class !== "ended"
+    );
+    if (matches.length > 1) {
+      runtime.error(
+        `More than one ${clusterModeLabel(accessMode)} cluster matches this capacity reservation.`,
+        {
+          code: "cluster_ambiguous",
+        }
+      );
+    }
+    if (matches.length === 0) return null;
+    cluster = requireValidCluster(runtime, matches[0]);
+  }
+  const current = await fetchClusterDetail(state.context.fetch, runtime, cluster);
+  const capacityReservation =
+    state.capacityReservation ??
+    (await reservationFactsForCluster(state.context.fetch, runtime, current));
+  let credentials = {};
+  let credentialError = null;
+  try {
+    credentials = record(
+      await state.context.fetch(clusterPath(current, "credentials"), { method: "GET" })
+    );
+  } catch (error) {
+    const status = Number(error?.status);
+    if (status === 404) {
+      credentialError = "pending";
+    } else if (error?.retryable === true || (Number.isFinite(status) && status >= 500)) {
+      credentialError = "unavailable";
+    } else {
+      throw error;
+    }
+  }
+  const nativeAccessReady =
+    accessMode === "slurm"
+      ? Boolean(text(credentials.login_host))
+      : Boolean(text(credentials.kubeconfig));
+  const resolved =
+    nativeAccessReady && !["partial", "failed", "ended"].includes(current.lifecycle.class)
+      ? { ...current, lifecycle: { class: "ready", phase: "access_ready" } }
+      : current;
+  return {
+    action: clusterInspectionAction(resolved),
+    capacityReservation,
+    cluster: resolved,
+    credentials,
+    credentialError,
+    resume: clusterResume(resolved),
+  };
+}
+
+async function exportKubeconfig(runtime, outputPath, overwrite, content) {
+  try {
+    await assertAtomicOutputAvailable(outputPath, { overwrite });
+  } catch (error) {
+    if (error instanceof AtomicOutputExistsError) {
+      runtime.error(
+        `Refusing to overwrite existing kubeconfig: ${outputPath}. Add --overwrite to replace it deliberately.`,
+        { code: "output_exists", field: "output" }
+      );
+    }
+    throw error;
+  }
+  let written;
+  try {
+    written = await writeAtomicOutput(outputPath, content, { mode: 0o600, overwrite });
+  } catch (error) {
+    if (error instanceof AtomicOutputExistsError) {
+      runtime.error(
+        `Refusing to overwrite existing kubeconfig: ${outputPath}. Add --overwrite to replace it deliberately.`,
+        { code: "output_exists", field: "output" }
+      );
+    }
+    throw error;
+  }
+  return {
+    fingerprint: `sha256:${createHash("sha256").update(content).digest("hex")}`,
+    mode: `0${(written.mode & 0o777).toString(8).padStart(3, "0")}`,
+    path: written.path,
+  };
+}
+
+export const kubernetesConnectModeHandler = {
+  mode: "kubernetes",
+  candidates: (state) => clusterModeConnectCandidates(state, "kubernetes"),
+  resolve: (state) => resolveClusterModeConnectTarget(state, "kubernetes"),
+  async matches(state) {
+    const runtime = state.interaction;
+    if (state.mode && state.mode !== "kubernetes") return false;
+    if (state.cluster?.access_mode === "kubernetes") {
+      clusterCache.set(state, requireValidCluster(runtime, state.cluster));
+      return true;
+    }
+    const matches = (await fetchClusters(state.context.fetch)).filter(
+      (cluster) =>
+        cluster.access_mode === "kubernetes" &&
+        cluster.reservation_id === state.reservationId &&
+        cluster.lifecycle.class !== "ended"
+    );
+    if (matches.length > 1)
+      runtime.error("More than one Kubernetes cluster matches this capacity reservation.", {
+        code: "cluster_ambiguous",
+      });
+    if (matches.length === 0) return false;
+    clusterCache.set(state, requireValidCluster(runtime, matches[0]));
+    return true;
+  },
+  async connect(state) {
+    const runtime = state.interaction;
+    if (state.input.identityFile || state.input.user) {
+      runtime.usage(
+        "Kubernetes connect writes a kubeconfig and does not accept SSH identity or user options.",
+        {
+          code: "kubernetes_ssh_options_unsupported",
+          field: state.input.identityFile ? "identityFile" : "user",
+        }
+      );
+    }
+    const cluster = clusterCache.get(state);
+    if (!cluster)
+      runtime.error("The selected Kubernetes cluster could not be rediscovered.", {
+        code: "cluster_not_found",
+      });
+    if (state.input.print === true) {
+      runtime.usage(
+        "Kubernetes connect writes only to an explicit --output path; ordinary output never contains credential bytes.",
+        {
+          code: "kubeconfig_output_required",
+          field: "output",
+        }
+      );
+    }
+    const outputPath = text(state.input.output);
+    if (!outputPath)
+      runtime.usage("Kubernetes connect requires --output <path>.", {
+        code: "kubeconfig_output_required",
+        field: "output",
+      });
+    try {
+      await assertAtomicOutputAvailable(outputPath, { overwrite: state.input.overwrite === true });
+    } catch (error) {
+      if (error instanceof AtomicOutputExistsError) {
+        runtime.error(
+          `Refusing to overwrite existing kubeconfig: ${outputPath}. Add --overwrite to replace it deliberately.`,
+          { code: "output_exists", field: "output" }
+        );
+      }
+      throw error;
+    }
+    const current = await fetchClusterDetail(state.context.fetch, runtime, cluster);
+    if (current.lifecycle.class !== "ready") {
+      runtime.error("Kubernetes access is not ready yet.", {
+        action: clusterInspectionAction(current),
+        code: "kubernetes_access_not_ready",
+        retryable: true,
+      });
+    }
+    const credentials = record(
+      await state.context.fetch(clusterPath(current, "credentials"), { method: "GET" })
+    );
+    const kubeconfig =
+      typeof credentials.kubeconfig === "string" && credentials.kubeconfig.trim()
+        ? credentials.kubeconfig
+        : null;
+    if (
+      !kubeconfig ||
+      (text(credentials.credential_type) && credentials.credential_type !== "kubeconfig")
+    ) {
+      runtime.error("Kubernetes credentials are not ready yet.", {
+        action: clusterInspectionAction(current),
+        code: "kubernetes_access_not_ready",
+        retryable: true,
+      });
+    }
+    const exported = await exportKubeconfig(
+      runtime,
+      outputPath,
+      state.input.overwrite === true,
+      kubeconfig
+    );
+    return {
+      data: { cluster: current, kubeconfig: exported },
+      outcome: { class: "ready", phase: "kubeconfig_written" },
+      presentation: {
+        lines: [
+          `Kubeconfig written to ${exported.path} (${exported.mode}).`,
+          `Fingerprint: ${exported.fingerprint}`,
+        ],
+        next: `KUBECONFIG=${shellQuote(exported.path)} kubectl get pods`,
+      },
+      resume: clusterResume(current),
+    };
+  },
+};
+
+export const kubernetesLaunchModeHandler = {
+  mode: "kubernetes",
+  launch: (state) => launchClusterMode(state, "kubernetes"),
+};