@ornncompute/cli 0.2.24 → 1.0.25

package/src/mount-commands.mjs

@@ -0,0 +1,1146 @@
+import { CliApiError, computeEndpoint } from "./api-client.mjs";
+import { isRecoverableWaitFailure } from "./interaction-runtime.mjs";
+import { resolveVolume, safeVolume } from "./storage-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 DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+const DEFAULT_MOUNT_TIMEOUT = "30m";
+const TERMINAL_ATTACHMENT_PHASES = new Set(["detached", "ended", "failed"]);
+
+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 integer(value) {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+}
+
+function canonical(value, field, interaction) {
+  const candidate = text(value);
+  if (!candidate || !UUID.test(candidate)) {
+    interaction.usage(`--${field} must be one canonical identifier.`, {
+      code: "invalid_reference",
+      field,
+    });
+  }
+  return candidate;
+}
+
+function positionals(input, expected, usage, interaction) {
+  const values = Array.isArray(input.$positionals) ? input.$positionals : [];
+  if (values.length !== expected) interaction.usage(`Usage: ${usage}`, { code: "usage_error" });
+  return values;
+}
+
+function required(value, field, interaction) {
+  const candidate = text(value);
+  if (!candidate) interaction.usage(`--${field} is required.`, { code: "missing_input", field });
+  return candidate;
+}
+
+function accessMode(value, interaction) {
+  const candidate = required(value, "access", interaction).toLowerCase();
+  if (candidate !== "read-only" && candidate !== "read-write") {
+    interaction.usage("--access must be read-only or read-write.", {
+      code: "invalid_access_mode",
+      field: "access",
+    });
+  }
+  return candidate;
+}
+
+function positiveInteger(value, field, interaction) {
+  const parsed = integer(value);
+  if (parsed === null || parsed < 1) {
+    interaction.usage(`--${field} must be a positive integer.`, {
+      code: "invalid_input",
+      field,
+    });
+  }
+  return parsed;
+}
+
+function timeoutMilliseconds(value, interaction, fallback = DEFAULT_MOUNT_TIMEOUT) {
+  const candidate = text(value) ?? fallback;
+  const match = /^(\d+)(ms|s|m|h)$/.exec(candidate);
+  if (!match) {
+    interaction.usage("--timeout must be a positive duration such as 30s, 10m, or 1h.", {
+      code: "invalid_timeout",
+      field: "timeout",
+    });
+  }
+  const count = Number(match[1]);
+  const scale = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 }[match[2]];
+  if (!Number.isSafeInteger(count) || count < 1 || count * scale > 2_147_483_647) {
+    interaction.usage("--timeout is outside the supported range.", {
+      code: "invalid_timeout",
+      field: "timeout",
+    });
+  }
+  return count * scale;
+}
+
+function requireMachineMutation(input, interaction) {
+  if (!interaction.machine) return;
+  if (!text(input.idempotencyKey)) {
+    interaction.usage("Machine mutations require --idempotency-key <caller-stable-key>.", {
+      code: "missing_idempotency_key",
+      field: "idempotency-key",
+    });
+  }
+}
+
+function idempotencyHeaders(input) {
+  const key = text(input.idempotencyKey);
+  return key ? { "Idempotency-Key": key } : undefined;
+}
+
+function ownerCode(error) {
+  const top = record(error?.detail);
+  const detail = record(top.detail ?? top.error ?? top);
+  const code = text(detail.code);
+  return code && /^[a-z][a-z0-9_]*$/.test(code) ? code : null;
+}
+
+function safeFailure(
+  interaction,
+  error,
+  message,
+  { action, fallbackCode = "mount_operation_failed" } = {}
+) {
+  if (error?.name === "InteractionError" || error?.name === "StorageCommandError") throw error;
+  if (error instanceof CliApiError && (error.status === 401 || error.status === 403)) throw error;
+  const code =
+    ownerCode(error) ??
+    (error instanceof CliApiError && (error.status === undefined || error.status >= 500)
+      ? "service_unavailable"
+      : fallbackCode);
+  interaction.error(message, {
+    action,
+    code,
+    exitCode: code === "service_unavailable" ? 6 : 1,
+    retryable: code === "service_unavailable",
+  });
+}
+
+function reservationAttachmentPath(reservationId) {
+  return computeEndpoint(
+    `/nodes/reservations/${encodeURIComponent(reservationId)}/storage-attachment`
+  );
+}
+
+function reservationDeploymentPath(reservationId) {
+  return computeEndpoint(
+    `/nodes/reservations/${encodeURIComponent(reservationId)}/storage-deployment`
+  );
+}
+
+function reservationFilesystemPath(reservationId) {
+  return computeEndpoint(
+    `/nodes/reservations/${encodeURIComponent(reservationId)}/filesystem-deployment`
+  );
+}
+
+function stableAttachmentPhase(value) {
+  const state = text(value)?.toLowerCase() ?? "pending";
+  if (["attached", "ready"].includes(state)) return state;
+  if (["failed", "detached", "detaching"].includes(state)) return state;
+  if (["pre_positioning", "provisioning", "mounting", "accepted"].includes(state)) return state;
+  return "pending";
+}
+
+function stableMachineMountPhase(value) {
+  const state = text(value)?.toLowerCase() ?? "pending";
+  if (state === "mounted") return "mounted";
+  if (["mount_failed", "mount_failed_unverified", "failed", "error"].includes(state))
+    return "failed";
+  if (["release_pending", "releasing", "detached"].includes(state)) return "detaching";
+  if (["reserved", "provisioning", "mount_pending", "mounting", "pending"].includes(state))
+    return "pending";
+  return "unknown";
+}
+
+function safeMountPath(value) {
+  const candidate = text(value);
+  return candidate && candidate.startsWith("/") && !/[\p{Cc}]/u.test(candidate) ? candidate : null;
+}
+
+export function projectVolumeMount(payload, requestedReservationId) {
+  const source = record(payload);
+  const attachment = record(
+    source.attachment ??
+      source.filesystem_deployment ??
+      source.deployment ??
+      (source.id ? source : null)
+  );
+  if (!text(attachment.id)) return null;
+  const drive = record(attachment.drive ?? attachment.volume);
+  const filesystem = record(drive.nfs_backend ?? attachment.filesystem);
+  const rawMounts = Array.isArray(drive.active_mounts)
+    ? drive.active_mounts
+    : drive.active_mount
+      ? [drive.active_mount]
+      : [];
+  const machines = rawMounts.map((value) => {
+    const mount = record(value);
+    const phase = stableMachineMountPhase(mount.state);
+    return {
+      machine_id: text(mount.node_id ?? mount.instance_id),
+      machine_label: text(mount.node_label),
+      reservation_id: text(mount.reservation_id) ?? requestedReservationId,
+      phase,
+      ready: phase === "mounted",
+      mount_path: safeMountPath(mount.mount_path ?? attachment.mount_path),
+      issue: phase === "failed" ? "The machine did not confirm this volume mount." : null,
+    };
+  });
+  const expected = Math.max(integer(record(attachment.scope).node_count) ?? 0, machines.length);
+  const ready = machines.filter((machine) => machine.ready).length;
+  const failed = machines.filter((machine) => machine.phase === "failed").length;
+  const phase = stableAttachmentPhase(attachment.state);
+  const lifecycleClass =
+    ready === expected && expected > 0 && ["attached", "ready"].includes(phase)
+      ? "ready"
+      : failed > 0 || phase === "failed"
+        ? "partial"
+        : phase === "detached"
+          ? "ended"
+          : "working";
+  return {
+    id: text(attachment.id),
+    reservation_id: requestedReservationId ?? text(attachment.reservation_id),
+    volume: {
+      id: text(attachment.drive_id ?? drive.id),
+      name: text(drive.name),
+    },
+    mount_path: safeMountPath(attachment.mount_path),
+    access: ["read-only", "read-write"].includes(text(attachment.access_mode)?.toLowerCase())
+      ? text(attachment.access_mode).toLowerCase()
+      : null,
+    scope: {
+      all_nodes:
+        record(attachment.scope).all_nodes === true ||
+        record(attachment.scope).origin === "cluster",
+      machine_count: expected,
+    },
+    lifecycle: { class: lifecycleClass, phase },
+    filesystem: {
+      performance_tier: text(filesystem.performance_tier ?? attachment.performance_tier),
+      capacity_gib: integer(filesystem.capacity_gib ?? attachment.capacity_gib),
+      phase: text(filesystem.state)?.toLowerCase() ?? null,
+      mount_ready: filesystem.mount_ready === true,
+    },
+    readiness: {
+      expected,
+      ready,
+      failed,
+      pending: Math.max(0, expected - ready - failed),
+    },
+    machines,
+  };
+}
+
+function mountSatisfied(mount, goal) {
+  return Boolean(
+    mount &&
+    !["detached", "detaching", "ended"].includes(mount.lifecycle.phase) &&
+    mount.volume.id === goal.volumeId &&
+    mount.access === goal.access
+  );
+}
+
+function filesystemSatisfied(mount, performanceTier, capacityGib) {
+  return Boolean(
+    mount &&
+    mount.filesystem.performance_tier === performanceTier &&
+    mount.filesystem.capacity_gib === capacityGib
+  );
+}
+
+function mountReady(mount) {
+  return Boolean(
+    mount && mount.readiness.expected > 0 && mount.readiness.ready === mount.readiness.expected
+  );
+}
+
+function mountTerminal(mount) {
+  return Boolean(
+    mount && (mount.readiness.failed > 0 || TERMINAL_ATTACHMENT_PHASES.has(mount.lifecycle.phase))
+  );
+}
+
+export function resolvedMountPath(requestedPath, machines) {
+  const paths = new Set(
+    (Array.isArray(machines) ? machines : [])
+      .map((machine) => text(record(machine).mount_path))
+      .filter(Boolean)
+  );
+  if (paths.size === 1) return [...paths][0];
+  if (paths.size === 0) return text(requestedPath);
+  return null;
+}
+
+function mountLines(mount, reservationId) {
+  if (!mount) return [`Capacity reservation ${reservationId} has no volume mount.`];
+  const lines = [
+    `Volume mount ${mount.id}`,
+    `  Capacity reservation: ${mount.reservation_id}`,
+    `  Volume: ${mount.volume.name ?? "Managed volume"} (${mount.volume.id})`,
+    `  Path: ${resolvedMountPath(mount.mount_path, mount.machines) ?? "per machine"}`,
+    `  Access: ${mount.access ?? "pending"}`,
+    `  Ready machines: ${mount.readiness.ready} of ${mount.readiness.expected}`,
+  ];
+  for (const machine of mount.machines) {
+    lines.push(
+      `  ${machine.machine_label ?? machine.machine_id ?? "machine"}: ${machine.phase}${machine.mount_path ? ` at ${machine.mount_path}` : ""}`
+    );
+  }
+  return lines;
+}
+
+function mountResult(interaction, mount, reservationId, { replayed = false } = {}) {
+  if (!mount) {
+    return interaction.result({
+      data: { reservation_id: reservationId, volume_mount: null, replayed },
+      outcome: { class: "ended", phase: "not_attached" },
+      presentation: { lines: mountLines(null, reservationId) },
+    });
+  }
+  const partial = mount.readiness.failed > 0 || mount.lifecycle.class === "partial";
+  return interaction.result({
+    data: { reservation_id: reservationId, volume_mount: mount, replayed },
+    errors: partial
+      ? [
+          {
+            code: "volume_mount_partial",
+            message: "One or more machines did not confirm the requested volume mount.",
+            retryable: true,
+          },
+        ]
+      : [],
+    exitCode: partial ? 4 : 0,
+    outcome: partial ? { class: "partial", phase: "machine_mounts" } : mount.lifecycle,
+    resume: { kind: "volume_mount", ref: reservationId },
+    action: partial
+      ? {
+          command: `ornn volume-mounts wait ${reservationId} --timeout ${DEFAULT_MOUNT_TIMEOUT}`,
+          description: "Resume the exact per-machine mount wait.",
+          type: "command",
+        }
+      : null,
+    presentation: {
+      lines: mountLines(mount, reservationId),
+      ...(partial
+        ? { next: `ornn volume-mounts wait ${reservationId} --timeout ${DEFAULT_MOUNT_TIMEOUT}` }
+        : {}),
+    },
+  });
+}
+
+// The attachment payload carries no reservation machine count, so a mount
+// still short of its per-machine rows has no denominator of its own.
+async function reservationMachineCount(runtime, reservationId, signal) {
+  const cache = (runtime.machineCounts ??= new Map());
+  if (cache.has(reservationId)) return cache.get(reservationId);
+  let count = 0;
+  try {
+    const rows = candidateRows(
+      await runtime.fetch("/v1/cli/storage-targets", {
+        method: "GET",
+        ...(signal ? { signal } : {}),
+      })
+    );
+    const row = rows.find(
+      (candidate) =>
+        candidate.id === reservationId || candidate.reservation_ids.includes(reservationId)
+    );
+    count = row?.machine_count ?? 0;
+  } catch {
+    // A missing denominator must never fail the mount it describes.
+  }
+  cache.set(reservationId, count);
+  return count;
+}
+
+async function withMachineCount(runtime, mount, reservationId, signal) {
+  if (!mount || mount.readiness.expected > 0) return mount;
+  const expected = await reservationMachineCount(runtime, reservationId, signal);
+  if (expected < 1) return mount;
+  mount.readiness.expected = expected;
+  mount.readiness.pending = Math.max(0, expected - mount.readiness.ready - mount.readiness.failed);
+  mount.scope.machine_count = expected;
+  return mount;
+}
+
+async function fetchMount(runtime, reservationId, { preserveFailure = false, signal } = {}) {
+  try {
+    const payload = await runtime.fetch(reservationAttachmentPath(reservationId), {
+      method: "GET",
+      ...(signal ? { signal } : {}),
+    });
+    return withMachineCount(
+      runtime,
+      projectVolumeMount(payload, reservationId),
+      reservationId,
+      signal
+    );
+  } catch (error) {
+    if (error instanceof CliApiError && error.status === 404) return null;
+    if (preserveFailure) throw error;
+    safeFailure(
+      runtime.interaction,
+      error,
+      "The volume-mount relationship could not be loaded safely."
+    );
+  }
+}
+
+function shouldWait(input, interaction) {
+  if (input.noWait && input.wait) {
+    interaction.usage("Choose only one of --wait or --no-wait.", { code: "usage_error" });
+  }
+  if (interaction.machine && input.wait && !text(input.timeout)) {
+    interaction.usage("Machine waiting requires --timeout <duration>.", {
+      code: "missing_timeout",
+      field: "timeout",
+    });
+  }
+  if (!input.wait && text(input.timeout)) {
+    interaction.usage("--timeout requires --wait for a mutation command.", {
+      code: "usage_error",
+      field: "timeout",
+    });
+  }
+  return input.noWait
+    ? false
+    : input.wait
+      ? true
+      : interaction.eligibleHuman && !interaction.machine;
+}
+
+async function waitForMount(input, runtime, reservationId, initial, command) {
+  const timeout = text(input.timeout) ?? DEFAULT_MOUNT_TIMEOUT;
+  const next = `ornn volume-mounts wait ${reservationId} --timeout ${timeout}`;
+  let outcome;
+  try {
+    outcome = await runtime.interaction.waitForGoal({
+      command,
+      initial,
+      timeoutMs: timeoutMilliseconds(timeout, runtime.interaction),
+      isReady: mountReady,
+      isTerminal: mountTerminal,
+      message: (mount, elapsedMs) =>
+        mountReady(mount)
+          ? `Every requested machine has mounted the volume.`
+          : `Volume mount has ${mount?.readiness.ready ?? 0} of ${mount?.readiness.expected ?? 0} machines ready (${Math.floor(elapsedMs / 1000)}s).`,
+      projectProgress: (mount) => ({ reservation_id: reservationId, volume_mount: mount }),
+      poll: ({ signal }) => fetchMount(runtime, reservationId, { preserveFailure: true, signal }),
+    });
+  } catch (error) {
+    const status = Number(error?.status);
+    if (!isRecoverableWaitFailure(error)) throw error;
+    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 mount.",
+          type: "command",
+        }
+      : { command: next, description: "Retry the exact accepted mount wait.", type: "command" };
+    return runtime.interaction.result({
+      action,
+      data: {
+        remote_work_cancelled: false,
+        replayed: false,
+        reservation_id: reservationId,
+        volume_mount: initial,
+      },
+      errors: [
+        {
+          code: authentication
+            ? "authentication_required"
+            : authorization
+              ? "authorization_denied"
+              : "service_unavailable",
+          message: authorization
+            ? "The session could not continue waiting; the accepted remote mount continues."
+            : "The local wait lost contact with the service; the accepted remote mount continues.",
+          retryable: status !== 403,
+          resource_ref: reservationId,
+        },
+      ],
+      exitCode: authorization ? 5 : 6,
+      outcome: initial?.lifecycle ?? { class: "working", phase: "mounting" },
+      resume: { kind: "volume_mount", ref: reservationId },
+      presentation: {
+        lines: ["The accepted remote mount continues; no remote cancellation was sent."],
+        next: action.command,
+      },
+    });
+  }
+  if (outcome.kind === "ready" || outcome.kind === "terminal") {
+    return mountResult(runtime.interaction, outcome.value, reservationId);
+  }
+  const interrupted = outcome.kind === "interrupted";
+  const mount = outcome.value;
+  return runtime.interaction.result({
+    action: { command: next, description: "Resume the exact local mount wait.", type: "command" },
+    data: { reservation_id: reservationId, volume_mount: mount, replayed: false },
+    errors: [
+      {
+        code: interrupted ? "interrupted" : "wait_timeout",
+        message: interrupted
+          ? "Local waiting stopped; the remote mount continues."
+          : "Local waiting timed out; the remote mount continues.",
+        retryable: true,
+      },
+    ],
+    exitCode: interrupted ? 130 : 124,
+    outcome: mount?.lifecycle ?? { class: "working", phase: "mounting" },
+    resume: { kind: "volume_mount", ref: reservationId },
+    presentation: {
+      lines: [
+        ...mountLines(mount, reservationId),
+        interrupted
+          ? "Local waiting stopped; no remote cancellation was sent."
+          : "Local waiting timed out; no remote cancellation was sent.",
+      ],
+      next,
+    },
+  });
+}
+
+function candidateRows(payload) {
+  const source = record(payload);
+  const rows = Array.isArray(payload)
+    ? payload
+    : Array.isArray(source.targets)
+      ? source.targets
+      : [];
+  return rows
+    .flatMap((value) => {
+      const target = record(value);
+      const id = text(target.id);
+      if (!id) return [];
+      const reservationIds = Array.isArray(target.reservationIds ?? target.reservation_ids)
+        ? (target.reservationIds ?? target.reservation_ids).filter(
+            (item) => typeof item === "string"
+          )
+        : [];
+      return [
+        {
+          id,
+          label: machineWording(text(target.label)),
+          detail: text(target.detail),
+          facility: facilityLabel(target.facilityLabel ?? target.facility_label),
+          all_nodes: target.allNodes === true || target.all_nodes === true,
+          machine_count: integer(target.nodeCount ?? target.node_count) ?? 0,
+          reservation_ids: reservationIds,
+        },
+      ];
+    })
+    .sort((left, right) => (left.label ?? left.id).localeCompare(right.label ?? right.id));
+}
+
+function machineWording(value) {
+  return value?.replace(/\bnodes\b/g, "machines").replace(/\bnode\b/g, "machine") ?? null;
+}
+
+function facilityLabel(value) {
+  const candidate = text(value);
+  return candidate === "\u2014" ? null : candidate;
+}
+
+function cursorOffset(cursor, interaction) {
+  if (!text(cursor)) return 0;
+  try {
+    const decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (
+      decoded.kind === "volume-mount-candidates" &&
+      Number.isSafeInteger(decoded.offset) &&
+      decoded.offset >= 0
+    ) {
+      return decoded.offset;
+    }
+  } catch {}
+  interaction.usage("The volume-mount candidate cursor is invalid or stale.", {
+    code: "invalid_cursor",
+    field: "cursor",
+  });
+}
+
+function pageLimit(value, interaction) {
+  if (value === undefined) return DEFAULT_LIMIT;
+  const limit = integer(value);
+  if (limit === null || limit < 1 || limit > MAX_LIMIT) {
+    interaction.usage("--limit must be an integer from 1 through 500.", {
+      code: "invalid_limit",
+      field: "limit",
+    });
+  }
+  return limit;
+}
+
+async function candidates(input, runtime) {
+  positionals(
+    input,
+    0,
+    "ornn volume-mounts candidates [--limit <1-500>] [--cursor <cursor>]",
+    runtime.interaction
+  );
+  const rows = candidateRows(await runtime.fetch("/v1/cli/storage-targets", { method: "GET" }));
+  const offset = cursorOffset(input.cursor, runtime.interaction);
+  const limit = pageLimit(input.limit, runtime.interaction);
+  if (offset > rows.length) {
+    runtime.interaction.usage("The volume-mount candidate cursor is invalid or stale.", {
+      code: "invalid_cursor",
+      field: "cursor",
+    });
+  }
+  const selected = rows.slice(offset, offset + limit);
+  const next =
+    offset + limit < rows.length
+      ? Buffer.from(
+          JSON.stringify({ kind: "volume-mount-candidates", offset: offset + limit })
+        ).toString("base64url")
+      : null;
+  return runtime.interaction.result({
+    data: { candidates: selected },
+    page: { limit, returned: selected.length, next_cursor: next },
+    outcome: { class: "ready", phase: selected.length ? "listed" : "empty" },
+    presentation: {
+      lines: selected.length
+        ? selected.map(
+            (target) =>
+              `${target.label ?? `${target.machine_count} machines`} (${target.id})${target.facility ? ` in ${target.facility}` : ""}`
+          )
+        : ["No volume-mount candidates found."],
+      ...(next ? { next: `ornn volume-mounts candidates --cursor ${next}` } : {}),
+    },
+  });
+}
+
+async function show(input, runtime, command) {
+  const [rawReservation] = positionals(
+    input,
+    1,
+    `ornn ${command} <canonical-reservation-id>`,
+    runtime.interaction
+  );
+  const reservationId = canonical(rawReservation, "reservation", runtime.interaction);
+  return mountResult(runtime.interaction, await fetchMount(runtime, reservationId), reservationId);
+}
+
+export async function attachVolumeMount(input, runtime, { skipReview = false } = {}) {
+  const [rawReservation] = positionals(
+    input,
+    1,
+    "ornn volume-mounts attach <canonical-reservation-id> --volume <exact-name-or-id> --access read-only|read-write",
+    runtime.interaction
+  );
+  requireMachineMutation(input, runtime.interaction);
+  const reservationId = canonical(rawReservation, "reservation", runtime.interaction);
+  if (
+    runtime.interaction.machine &&
+    !UUID.test(required(input.volume, "volume", runtime.interaction))
+  ) {
+    runtime.interaction.usage("Automation must use a canonical managed-volume identifier.", {
+      code: "invalid_reference",
+      field: "volume",
+    });
+  }
+  const access = accessMode(input.access, runtime.interaction);
+  const wait = shouldWait(input, runtime.interaction);
+  const volume = await resolveVolume(runtime, input.volume);
+  const projectedVolume = safeVolume(volume);
+  const goal = { volumeId: projectedVolume.id, access };
+  let current = await fetchMount(runtime, reservationId);
+  if (current && ["detached", "ended"].includes(current.lifecycle.phase)) current = null;
+  if (mountSatisfied(current, goal)) {
+    return wait && !mountReady(current)
+      ? waitForMount(input, runtime, reservationId, current, "volume-mounts attach")
+      : mountResult(runtime.interaction, current, reservationId, { replayed: true });
+  }
+  if (current) {
+    runtime.interaction.error(
+      "This capacity reservation already has a different volume-mount relationship.",
+      {
+        action: {
+          command: `ornn volume-mounts detach ${reservationId}`,
+          description:
+            "Review and detach the existing relationship before choosing a different mount.",
+          type: "command",
+        },
+        code: "volume_mount_conflict",
+      }
+    );
+  }
+  if (!skipReview) {
+    const accepted = await runtime.interaction.review({
+      title: "Attach managed volume",
+      terms: [
+        { label: "Capacity reservation", value: reservationId },
+        { label: "Managed volume", value: `${projectedVolume.name} (${projectedVolume.id})` },
+        { label: "Access", value: access },
+        { label: "Machine scope", value: "Every machine in the reservation" },
+        {
+          label: "Volume lifecycle",
+          value: "The volume remains independent from this relationship",
+        },
+      ],
+      prompt: "Attach this volume?",
+    });
+    if (!accepted) {
+      return runtime.interaction.result({
+        errors: [{ code: "declined", message: "Volume attachment declined.", retryable: false }],
+        exitCode: 1,
+        outcome: { class: "ended", phase: "declined" },
+        presentation: { lines: ["Volume attachment declined. No relationship was created."] },
+      });
+    }
+    const refreshedVolume = safeVolume(await resolveVolume(runtime, projectedVolume.id));
+    if (
+      refreshedVolume.id !== projectedVolume.id ||
+      refreshedVolume.name !== projectedVolume.name
+    ) {
+      runtime.interaction.error("The selected managed volume changed after review.", {
+        code: "volume_selection_changed",
+      });
+    }
+    current = await fetchMount(runtime, reservationId);
+    if (current && ["detached", "ended"].includes(current.lifecycle.phase)) current = null;
+    if (mountSatisfied(current, goal)) {
+      return wait && !mountReady(current)
+        ? waitForMount(input, runtime, reservationId, current, "volume-mounts attach")
+        : mountResult(runtime.interaction, current, reservationId, { replayed: true });
+    }
+    if (current) {
+      runtime.interaction.error("The volume-mount relationship changed after review.", {
+        code: "volume_mount_conflict",
+      });
+    }
+  }
+
+  try {
+    const payload = await runtime.fetch(reservationDeploymentPath(reservationId), {
+      method: "POST",
+      headers: idempotencyHeaders(input),
+      body: {
+        drive_id: projectedVolume.id,
+        mount_mode: "fuse",
+        access_mode: access,
+      },
+    });
+    current = await withMachineCount(
+      runtime,
+      projectVolumeMount(payload, reservationId),
+      reservationId
+    );
+  } catch (error) {
+    if (error instanceof CliApiError && (error.status === undefined || error.status >= 500)) {
+      try {
+        current = await fetchMount(runtime, reservationId);
+        if (!mountSatisfied(current, goal)) throw error;
+      } catch {
+        throw error;
+      }
+    } else {
+      safeFailure(runtime.interaction, error, "The volume could not be attached safely.", {
+        action: {
+          command: `ornn volume-mounts show ${reservationId}`,
+          description: "Inspect the exact relationship before retrying.",
+          type: "command",
+        },
+      });
+    }
+  }
+  if (!mountSatisfied(current, goal)) {
+    runtime.interaction.error("The accepted volume mount did not match the reviewed goal.", {
+      code: "volume_mount_goal_mismatch",
+    });
+  }
+  return wait && !mountReady(current)
+    ? waitForMount(input, runtime, reservationId, current, "volume-mounts attach")
+    : mountResult(runtime.interaction, current, reservationId);
+}
+
+async function waitCommand(input, runtime, command) {
+  const [rawReservation] = positionals(
+    input,
+    1,
+    `ornn ${command} <canonical-reservation-id> --timeout <duration>`,
+    runtime.interaction
+  );
+  const reservationId = canonical(rawReservation, "reservation", runtime.interaction);
+  if (runtime.interaction.machine && !text(input.timeout)) {
+    runtime.interaction.usage("Machine waiting requires --timeout <duration>.", {
+      code: "missing_timeout",
+      field: "timeout",
+    });
+  }
+  const initial = await fetchMount(runtime, reservationId);
+  if (!initial) {
+    runtime.interaction.error(
+      "No volume-mount relationship exists for this capacity reservation.",
+      {
+        code: "volume_mount_not_found",
+      }
+    );
+  }
+  return waitForMount(
+    { ...input, timeout: text(input.timeout) ?? DEFAULT_MOUNT_TIMEOUT },
+    runtime,
+    reservationId,
+    initial,
+    command
+  );
+}
+
+export async function detachVolumeMount(input, runtime, { skipReview = false } = {}) {
+  const [rawReservation] = positionals(
+    input,
+    1,
+    "ornn volume-mounts detach <canonical-reservation-id>",
+    runtime.interaction
+  );
+  requireMachineMutation(input, runtime.interaction);
+  const reservationId = canonical(rawReservation, "reservation", runtime.interaction);
+  let current = await fetchMount(runtime, reservationId);
+  if (!current || current.lifecycle.phase === "detached") {
+    return runtime.interaction.result({
+      data: {
+        reservation_id: reservationId,
+        volume_mount: current,
+        replayed: true,
+        volume_preserved: current?.volume ?? null,
+      },
+      outcome: { class: "ended", phase: "detached" },
+      presentation: {
+        lines: [
+          `Capacity reservation ${reservationId} is already detached; no volume was deleted.`,
+        ],
+      },
+    });
+  }
+  if (!skipReview) {
+    const accepted = await runtime.interaction.review({
+      title: "Detach managed volume",
+      terms: [
+        { label: "Capacity reservation", value: reservationId },
+        {
+          label: "Managed volume",
+          value: `${current.volume.name ?? "Managed volume"} (${current.volume.id})`,
+        },
+        {
+          label: "Mounted machines",
+          value: `${current.readiness.ready} of ${current.readiness.expected}`,
+        },
+        {
+          label: "Consequence",
+          value: "Mounted access ends; the managed volume and its data remain",
+        },
+      ],
+      prompt: "Detach this volume?",
+    });
+    if (!accepted) {
+      return runtime.interaction.result({
+        errors: [{ code: "declined", message: "Volume detachment declined.", retryable: false }],
+        exitCode: 1,
+        outcome: { class: "ended", phase: "declined" },
+        presentation: { lines: ["Volume detachment declined. No relationship was changed."] },
+      });
+    }
+    const refreshed = await fetchMount(runtime, reservationId);
+    if (!refreshed || refreshed.id !== current.id || refreshed.volume.id !== current.volume.id) {
+      runtime.interaction.error("The volume-mount relationship changed after review.", {
+        code: "volume_mount_changed",
+      });
+    }
+    current = refreshed;
+  }
+  try {
+    await runtime.fetch(reservationAttachmentPath(reservationId), {
+      method: "DELETE",
+      headers: idempotencyHeaders(input),
+    });
+  } catch (error) {
+    if (error instanceof CliApiError && (error.status === undefined || error.status >= 500)) {
+      const reconciled = await fetchMount(runtime, reservationId);
+      if (reconciled && reconciled.lifecycle.phase !== "detached") throw error;
+    } else {
+      safeFailure(runtime.interaction, error, "The volume could not be detached safely.");
+    }
+  }
+  return runtime.interaction.result({
+    data: {
+      reservation_id: reservationId,
+      volume_mount: { ...current, lifecycle: { class: "ended", phase: "detaching" } },
+      replayed: false,
+      volume_preserved: current.volume,
+    },
+    outcome: { class: "working", phase: "detaching" },
+    resume: { kind: "volume_mount", ref: reservationId },
+    presentation: {
+      lines: [
+        `Volume detachment accepted for ${reservationId}.`,
+        `Managed volume ${current.volume.name ?? current.volume.id} was preserved.`,
+      ],
+      next: `ornn volume-mounts wait ${reservationId} --timeout ${DEFAULT_MOUNT_TIMEOUT}`,
+    },
+  });
+}
+
+async function deployFilesystem(input, runtime) {
+  const [rawReservation] = positionals(
+    input,
+    1,
+    "ornn filesystems deploy <canonical-reservation-id> --performance-tier <tier> --capacity-gib <gib>",
+    runtime.interaction
+  );
+  requireMachineMutation(input, runtime.interaction);
+  const reservationId = canonical(rawReservation, "reservation", runtime.interaction);
+  const performanceTier = required(input.performanceTier, "performance-tier", runtime.interaction);
+  const capacityGib = positiveInteger(input.capacityGib, "capacity-gib", runtime.interaction);
+  const wait = shouldWait(input, runtime.interaction);
+  let current = await fetchMount(runtime, reservationId);
+  if (current && ["detached", "ended"].includes(current.lifecycle.phase)) current = null;
+  if (current) {
+    const sameGoal = filesystemSatisfied(current, performanceTier, capacityGib);
+    if (!sameGoal) {
+      runtime.interaction.error(
+        "This capacity reservation already has a different managed filesystem relationship.",
+        {
+          action: {
+            command: `ornn filesystems show ${reservationId}`,
+            description:
+              "Inspect the current deployment before changing its exact capacity or performance goal.",
+            type: "command",
+          },
+          code: "filesystem_deployment_conflict",
+        }
+      );
+    }
+    return wait && !mountReady(current)
+      ? waitForMount(input, runtime, reservationId, current, "filesystems deploy")
+      : mountResult(runtime.interaction, current, reservationId, { replayed: true });
+  }
+  const accepted = await runtime.interaction.review({
+    title: "Deploy managed filesystem",
+    terms: [
+      { label: "Capacity reservation", value: reservationId },
+      { label: "Performance tier", value: performanceTier },
+      { label: "Capacity", value: `${capacityGib} GiB` },
+      { label: "Readiness", value: "Reported independently for every machine" },
+    ],
+    prompt: "Deploy this filesystem?",
+  });
+  if (!accepted) {
+    return runtime.interaction.result({
+      errors: [{ code: "declined", message: "Filesystem deployment declined.", retryable: false }],
+      exitCode: 1,
+      outcome: { class: "ended", phase: "declined" },
+      presentation: { lines: ["Filesystem deployment declined. No deployment was created."] },
+    });
+  }
+  current = await fetchMount(runtime, reservationId);
+  if (current && ["detached", "ended"].includes(current.lifecycle.phase)) current = null;
+  if (current && !filesystemSatisfied(current, performanceTier, capacityGib)) {
+    runtime.interaction.error("The managed filesystem relationship changed after review.", {
+      code: "filesystem_deployment_conflict",
+    });
+  }
+  if (!current) {
+    try {
+      current = await withMachineCount(
+        runtime,
+        projectVolumeMount(
+          await runtime.fetch(reservationFilesystemPath(reservationId), {
+            method: "POST",
+            headers: idempotencyHeaders(input),
+            body: { performance_tier: performanceTier, capacity_gib: capacityGib },
+          }),
+          reservationId
+        ),
+        reservationId
+      );
+    } catch (error) {
+      if (error instanceof CliApiError && (error.status === undefined || error.status >= 500)) {
+        current = await fetchMount(runtime, reservationId);
+        if (!filesystemSatisfied(current, performanceTier, capacityGib)) throw error;
+      } else {
+        safeFailure(runtime.interaction, error, "The filesystem could not be deployed safely.");
+      }
+    }
+  }
+  if (!filesystemSatisfied(current, performanceTier, capacityGib)) {
+    runtime.interaction.error(
+      "The accepted filesystem deployment did not match the reviewed goal.",
+      {
+        code: "filesystem_deployment_goal_mismatch",
+      }
+    );
+  }
+  return wait && !mountReady(current)
+    ? waitForMount(input, runtime, reservationId, current, "filesystems deploy")
+    : mountResult(runtime.interaction, current, reservationId);
+}
+
+function filesystemExecution(result) {
+  if (!result?.data || !Object.hasOwn(result.data, "volume_mount")) return result;
+  const { volume_mount: filesystemDeployment, ...data } = result.data;
+  return {
+    ...result,
+    data: {
+      ...data,
+      filesystem_deployment: filesystemDeployment,
+    },
+  };
+}
+
+async function deleteFilesystem(input, runtime) {
+  const [rawReservation] = positionals(
+    input,
+    1,
+    "ornn filesystems delete <canonical-reservation-id>",
+    runtime.interaction
+  );
+  requireMachineMutation(input, runtime.interaction);
+  const reservationId = canonical(rawReservation, "reservation", runtime.interaction);
+  const current = await fetchMount(runtime, reservationId);
+  if (!current || ["detached", "ended"].includes(current.lifecycle.phase)) {
+    return runtime.interaction.result({
+      data: {
+        filesystem_deployment: current,
+        replayed: true,
+        reservation_id: reservationId,
+        volume_preserved: current?.volume ?? null,
+      },
+      outcome: { class: "ended", phase: "deleted" },
+      presentation: {
+        lines: [
+          `Capacity reservation ${reservationId} already has no managed filesystem deployment.`,
+        ],
+      },
+    });
+  }
+  const accepted = await runtime.interaction.review({
+    title: "Delete managed filesystem deployment",
+    terms: [
+      { label: "Capacity reservation", value: reservationId },
+      {
+        label: "Managed volume",
+        value: `${current.volume.name ?? "Managed volume"} (${current.volume.id})`,
+      },
+      {
+        label: "Mounted machines",
+        value: `${current.readiness.ready} of ${current.readiness.expected}`,
+      },
+      {
+        label: "Consequence",
+        value: "Filesystem access ends; the managed volume and its data remain",
+      },
+    ],
+    prompt: "Delete this filesystem deployment?",
+  });
+  if (!accepted) {
+    return runtime.interaction.result({
+      data: {
+        filesystem_deployment: current,
+        reservation_id: reservationId,
+        volume_preserved: current.volume,
+      },
+      errors: [{ code: "declined", message: "Filesystem deletion declined.", retryable: false }],
+      exitCode: 1,
+      outcome: { class: "ended", phase: "declined" },
+      presentation: { lines: ["Filesystem deletion declined. No relationship was changed."] },
+    });
+  }
+  const refreshed = await fetchMount(runtime, reservationId);
+  if (!refreshed || refreshed.id !== current.id || refreshed.volume.id !== current.volume.id) {
+    runtime.interaction.error("The managed filesystem relationship changed after review.", {
+      code: "filesystem_deployment_changed",
+    });
+  }
+  let deleting;
+  try {
+    deleting = await withMachineCount(
+      runtime,
+      projectVolumeMount(
+        await runtime.fetch(reservationFilesystemPath(reservationId), {
+          headers: idempotencyHeaders(input),
+          method: "DELETE",
+        }),
+        reservationId
+      ),
+      reservationId
+    );
+  } catch (error) {
+    if (error instanceof CliApiError && (error.status === undefined || error.status >= 500)) {
+      const reconciled = await fetchMount(runtime, reservationId);
+      const deletingState = reconciled?.filesystem?.phase;
+      if (
+        reconciled &&
+        !["deleting", "deleted", "ended"].includes(deletingState) &&
+        !["detached", "ended"].includes(reconciled.lifecycle.phase)
+      ) {
+        throw error;
+      }
+      deleting = reconciled;
+    } else {
+      safeFailure(
+        runtime.interaction,
+        error,
+        "The filesystem deployment could not be deleted safely."
+      );
+    }
+  }
+  return runtime.interaction.result({
+    data: {
+      filesystem_deployment: deleting,
+      replayed: false,
+      reservation_id: reservationId,
+      volume_preserved: current.volume,
+    },
+    outcome: { class: "working", phase: "deleting" },
+    resume: { kind: "filesystem_deployment", ref: reservationId },
+    presentation: {
+      lines: [
+        `Filesystem deployment removal accepted for ${reservationId}.`,
+        `Managed volume ${current.volume.name ?? current.volume.id} was preserved.`,
+      ],
+      next: `ornn filesystems show ${reservationId}`,
+    },
+  });
+}
+
+export async function executeMountCommand(command, input, runtime) {
+  switch (command) {
+    case "storage.volume-mounts.candidates":
+      return candidates(input, runtime);
+    case "storage.volume-mounts.show":
+      return show(input, runtime, "volume-mounts show");
+    case "storage.volume-mounts.attach":
+      return attachVolumeMount(input, runtime);
+    case "storage.volume-mounts.wait":
+      return waitCommand(input, runtime, "volume-mounts wait");
+    case "storage.volume-mounts.detach":
+      return detachVolumeMount(input, runtime);
+    case "storage.filesystems.deploy":
+      return filesystemExecution(await deployFilesystem(input, runtime));
+    case "storage.filesystems.show":
+      return filesystemExecution(await show(input, runtime, "filesystems show"));
+    case "storage.filesystems.wait":
+      return filesystemExecution(await waitCommand(input, runtime, "filesystems wait"));
+    case "storage.filesystems.delete":
+      return deleteFilesystem(input, runtime);
+    default:
+      runtime.interaction.error("Unknown mount command.", { code: "unknown_command" });
+  }
+}