microsandbox-rb 0.17.1 → 0.17.3

data/ext/microsandbox/src/snapshot.rs

@@ -110,7 +110,7 @@ fn create(name: String, opts: RHash) -> Result<RHash, Error> {
         b = b.resumable();
     }
 
-    let snap = block_on(b.create()).map_err(error::to_ruby)?;
+    let snap = block_on(b.create())?.map_err(error::to_ruby)?;
     Ok(snapshot_to_hash(&snap))
 }
 
@@ -119,14 +119,14 @@ fn create(name: String, opts: RHash) -> Result<RHash, Error> {
 /// Hash — the only way to inspect an artifact addressed by path (`get`/`list`
 /// read the local index, which path-addressed artifacts are absent from).
 fn open(path_or_name: String) -> Result<RHash, Error> {
-    let snap = block_on(Snapshot::open(&path_or_name)).map_err(error::to_ruby)?;
+    let snap = block_on(Snapshot::open(&path_or_name))?.map_err(error::to_ruby)?;
     Ok(snapshot_to_hash(&snap))
 }
 
 /// Walk `dir` and parse each subdirectory's `snapshot.json` without touching
 /// the local index — for enumerating external/un-imported snapshot collections.
 fn list_dir(dir: String) -> Result<RArray, Error> {
-    let snaps = block_on(Snapshot::list_dir(Path::new(&dir))).map_err(error::to_ruby)?;
+    let snaps = block_on(Snapshot::list_dir(Path::new(&dir)))?.map_err(error::to_ruby)?;
     let arr = ruby().ary_new();
     for snap in &snaps {
         arr.push(snapshot_to_hash(snap))?;
@@ -140,24 +140,27 @@ fn list_dir(dir: String) -> Result<RArray, Error> {
 fn reindex(dir: Option<String>) -> Result<u64, Error> {
     let dir: PathBuf = match dir {
         Some(d) => PathBuf::from(d),
-        None => microsandbox::default_backend()
-            .as_local()
-            .map(|l| l.snapshots_dir())
-            .unwrap_or_else(|| PathBuf::from(".")),
+        None => {
+            crate::backend::ensure_this_process_backend()?;
+            microsandbox::default_backend()
+                .as_local()
+                .map(|l| l.snapshots_dir())
+                .unwrap_or_else(|| PathBuf::from("."))
+        }
     };
-    let n = block_on(Snapshot::reindex(&dir)).map_err(error::to_ruby)?;
+    let n = block_on(Snapshot::reindex(&dir))?.map_err(error::to_ruby)?;
     Ok(n as u64)
 }
 
 /// Metadata for one snapshot by name or digest.
 fn get(name_or_digest: String) -> Result<RHash, Error> {
-    let handle = block_on(Snapshot::get(&name_or_digest)).map_err(error::to_ruby)?;
+    let handle = block_on(Snapshot::get(&name_or_digest))?.map_err(error::to_ruby)?;
     Ok(handle_to_hash(&handle))
 }
 
 /// All snapshots as metadata hashes.
 fn list() -> Result<RArray, Error> {
-    let handles = block_on(Snapshot::list()).map_err(error::to_ruby)?;
+    let handles = block_on(Snapshot::list())?.map_err(error::to_ruby)?;
     let arr = ruby().ary_new();
     for h in &handles {
         arr.push(handle_to_hash(h))?;
@@ -167,7 +170,7 @@ fn list() -> Result<RArray, Error> {
 
 /// Remove a snapshot artifact by name or path.
 fn remove(name_or_path: String, force: bool) -> Result<(), Error> {
-    block_on(Snapshot::remove(&name_or_path, force)).map_err(error::to_ruby)
+    block_on(Snapshot::remove(&name_or_path, force))?.map_err(error::to_ruby)
 }
 
 /// Verify a snapshot's recorded upper-layer integrity. Returns
@@ -176,8 +179,14 @@ fn remove(name_or_path: String, force: bool) -> Result<(), Error> {
 /// "verified" (mismatches raise SnapshotIntegrityError), snapshots without
 /// recorded integrity report "not_recorded" with no algorithm/digest keys.
 fn verify(name_or_path: String) -> Result<RHash, Error> {
-    let snap = block_on(Snapshot::open(&name_or_path)).map_err(error::to_ruby)?;
-    let report = block_on(snap.verify()).map_err(error::to_ruby)?;
+    // Open AND verify in ONE `block_on`, so the opened snapshot never sits in
+    // this frame between two calls (`block_on` returns `Err` when an interrupt
+    // is delivered before it starts; one call leaves no such in-between state).
+    let report = block_on(async move {
+        let snap = Snapshot::open(&name_or_path).await?;
+        snap.verify().await
+    })?
+    .map_err(error::to_ruby)?;
     Ok(verify_report_to_hash(&report))
 }
 
@@ -193,7 +202,7 @@ fn save(name_or_path: String, out_path: String, opts: RHash) -> Result<(), Error
         &name_or_path,
         std::path::Path::new(&out_path),
         save_opts,
-    ))
+    ))?
     .map_err(error::to_ruby)
 }
 
@@ -204,7 +213,7 @@ fn load(archive_path: String, dest: Option<String>) -> Result<RHash, Error> {
     let handle = block_on(Snapshot::load(
         std::path::Path::new(&archive_path),
         dest_path.as_deref(),
-    ))
+    ))?
     .map_err(error::to_ruby)?;
     Ok(handle_to_hash(&handle))
 }

data/ext/microsandbox/src/ssh.rs

@@ -21,7 +21,7 @@ use tokio::io::AsyncWriteExt;
 use tokio::sync::Mutex;
 
 use crate::error;
-use crate::runtime::{block_on, ruby};
+use crate::runtime::{block_on, ruby, ForkGuarded};
 
 /// A core error for a session whose value was already taken (closed). Built
 /// inside `block_on`, so it must be a plain Rust error, not a Ruby one.
@@ -35,31 +35,31 @@ fn consumed() -> MicrosandboxError {
 
 #[magnus::wrap(class = "Microsandbox::Native::SshClient", free_immediately, size)]
 pub struct SshClient {
-    inner: Arc<Mutex<Option<CoreSshClient>>>,
+    inner: ForkGuarded<Arc<Mutex<Option<CoreSshClient>>>>,
 }
 
 impl SshClient {
     pub fn from_core(inner: CoreSshClient) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(Some(inner))),
+            inner: ForkGuarded::new("Microsandbox::SshClient", Arc::new(Mutex::new(Some(inner)))),
         }
     }
 
     /// Run a command over SSH and collect {status, stdout, stderr}.
     fn exec(&self, command: String, tty: bool) -> Result<RHash, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: MicrosandboxResult<SshOutput> = block_on(async move {
             let guard = inner.lock().await;
             let client = guard.as_ref().ok_or_else(consumed)?;
             client.exec_with(command, |b| b.tty(tty)).await
-        });
+        })?;
         Ok(ssh_output_to_hash(result.map_err(error::to_ruby)?))
     }
 
     /// Attach the local terminal to an interactive SSH shell; returns the exit
     /// status. Host-TTY coupled (raw mode); not meaningful without a real tty.
     fn attach(&self, term: Option<String>, detach_keys: Option<String>) -> Result<i32, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: MicrosandboxResult<i32> = block_on(async move {
             let guard = inner.lock().await;
             let client = guard.as_ref().ok_or_else(consumed)?;
@@ -74,24 +74,24 @@ impl SshClient {
                     b
                 })
                 .await
-        });
+        })?;
         result.map_err(error::to_ruby)
     }
 
     /// Open an SFTP session over this SSH connection.
     fn sftp(&self) -> Result<SftpClient, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: MicrosandboxResult<CoreSftp> = block_on(async move {
             let guard = inner.lock().await;
             let client = guard.as_ref().ok_or_else(consumed)?;
             client.sftp().await
-        });
+        })?;
         Ok(SftpClient::from_core(result.map_err(error::to_ruby)?))
     }
 
     /// Close the SSH client session. Idempotent.
     fn close(&self) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: MicrosandboxResult<()> = block_on(async move {
             let client = {
                 let mut guard = inner.lock().await;
@@ -101,7 +101,7 @@ impl SshClient {
                 Some(c) => c.close().await,
                 None => Ok(()),
             }
-        });
+        })?;
         result.map_err(error::to_ruby)
     }
 }
@@ -122,7 +122,7 @@ fn ssh_output_to_hash(output: SshOutput) -> RHash {
 
 #[magnus::wrap(class = "Microsandbox::Native::SftpClient", free_immediately, size)]
 pub struct SftpClient {
-    inner: Arc<Mutex<Option<CoreSftp>>>,
+    inner: ForkGuarded<Arc<Mutex<Option<CoreSftp>>>>,
 }
 
 /// Format an SFTP-layer error as a plain string inside `block_on`; the Ruby
@@ -134,23 +134,26 @@ fn sftp_str(e: impl std::fmt::Display) -> String {
 impl SftpClient {
     pub fn from_core(inner: CoreSftp) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(Some(inner))),
+            inner: ForkGuarded::new(
+                "Microsandbox::SftpClient",
+                Arc::new(Mutex::new(Some(inner))),
+            ),
         }
     }
 
     fn read(&self, path: String) -> Result<RString, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<Vec<u8>, String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
             sftp.read(path).await.map_err(sftp_str)
-        });
+        })?;
         Ok(ruby().str_from_slice(&result.map_err(error::base_error)?))
     }
 
     fn write(&self, path: String, data: RString) -> Result<(), Error> {
         let bytes = unsafe { data.as_slice() }.to_vec();
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<(), String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
@@ -158,82 +161,82 @@ impl SftpClient {
             file.write_all(&bytes).await.map_err(sftp_str)?;
             file.shutdown().await.map_err(sftp_str)?;
             Ok(())
-        });
+        })?;
         result.map_err(error::base_error)
     }
 
     fn mkdir(&self, path: String) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<(), String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
             sftp.create_dir(path).await.map_err(sftp_str)
-        });
+        })?;
         result.map_err(error::base_error)
     }
 
     fn remove_file(&self, path: String) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<(), String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
             sftp.remove_file(path).await.map_err(sftp_str)
-        });
+        })?;
         result.map_err(error::base_error)
     }
 
     fn remove_dir(&self, path: String) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<(), String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
             sftp.remove_dir(path).await.map_err(sftp_str)
-        });
+        })?;
         result.map_err(error::base_error)
     }
 
     fn rename(&self, old_path: String, new_path: String) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<(), String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
             sftp.rename(old_path, new_path).await.map_err(sftp_str)
-        });
+        })?;
         result.map_err(error::base_error)
     }
 
     fn symlink(&self, target: String, link_path: String) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<(), String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
             sftp.symlink(target, link_path).await.map_err(sftp_str)
-        });
+        })?;
         result.map_err(error::base_error)
     }
 
     fn real_path(&self, path: String) -> Result<String, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<String, String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
             sftp.canonicalize(path).await.map_err(sftp_str)
-        });
+        })?;
         result.map_err(error::base_error)
     }
 
     fn read_link(&self, path: String) -> Result<String, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<String, String> = block_on(async move {
             let guard = inner.lock().await;
             let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
             sftp.read_link(path).await.map_err(sftp_str)
-        });
+        })?;
         result.map_err(error::base_error)
     }
 
     fn close(&self) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: Result<(), String> = block_on(async move {
             let sftp = {
                 let mut guard = inner.lock().await;
@@ -243,7 +246,7 @@ impl SftpClient {
                 Some(s) => s.close().await.map_err(sftp_str),
                 None => Ok(()),
             }
-        });
+        })?;
         result.map_err(error::base_error)
     }
 }
@@ -254,19 +257,19 @@ impl SftpClient {
 
 #[magnus::wrap(class = "Microsandbox::Native::SshServer", free_immediately, size)]
 pub struct SshServer {
-    inner: Arc<Mutex<Option<CoreSshServer>>>,
+    inner: ForkGuarded<Arc<Mutex<Option<CoreSshServer>>>>,
 }
 
 impl SshServer {
     pub fn from_core(inner: CoreSshServer) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(Some(inner))),
+            inner: ForkGuarded::new("Microsandbox::SshServer", Arc::new(Mutex::new(Some(inner)))),
         }
     }
 
     /// Serve one SSH connection over this process's stdin/stdout.
     fn serve_connection(&self) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result: MicrosandboxResult<()> = block_on(async move {
             let server = {
                 let guard = inner.lock().await;
@@ -276,28 +279,32 @@ impl SshServer {
                 Some(s) => s.serve_connection(SshStdioStream::new()).await,
                 None => Err(consumed()),
             }
-        });
+        })?;
         result.map_err(error::to_ruby)
     }
 
     /// Release the prepared server endpoint. Idempotent.
     fn close(&self) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         block_on(async move {
             inner.lock().await.take();
-        });
+        })?;
         Ok(())
     }
 }
 
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let client = native.define_class("SshClient", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<SshClient>(ruby);
     client.define_method("exec", method!(SshClient::exec, 2))?;
     client.define_method("attach", method!(SshClient::attach, 2))?;
     client.define_method("sftp", method!(SshClient::sftp, 0))?;
     client.define_method("close", method!(SshClient::close, 0))?;
 
     let sftp = native.define_class("SftpClient", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<SftpClient>(ruby);
     sftp.define_method("read", method!(SftpClient::read, 1))?;
     sftp.define_method("write", method!(SftpClient::write, 2))?;
     sftp.define_method("mkdir", method!(SftpClient::mkdir, 1))?;
@@ -310,6 +317,8 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     sftp.define_method("close", method!(SftpClient::close, 0))?;
 
     let server = native.define_class("SshServer", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<SshServer>(ruby);
     server.define_method("serve_connection", method!(SshServer::serve_connection, 0))?;
     server.define_method("close", method!(SshServer::close, 0))?;
 

data/ext/microsandbox/src/stream.rs

@@ -18,14 +18,14 @@ use microsandbox::MicrosandboxResult;
 use tokio::sync::Mutex;
 
 use crate::error;
-use crate::runtime::block_on;
+use crate::runtime::{block_on, ForkGuarded};
 use crate::sandbox::{log_entry_to_hash, metrics_to_hash};
 
 type BoxStream<T> = Pin<Box<dyn Stream<Item = MicrosandboxResult<T>> + Send>>;
 
 #[magnus::wrap(class = "Microsandbox::Native::LogStream", free_immediately, size)]
 pub struct LogStream {
-    inner: Arc<Mutex<BoxStream<LogEntry>>>,
+    inner: ForkGuarded<Arc<Mutex<BoxStream<LogEntry>>>>,
 }
 
 impl LogStream {
@@ -33,15 +33,18 @@ impl LogStream {
         stream: impl Stream<Item = MicrosandboxResult<LogEntry>> + Send + 'static,
     ) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(Box::pin(stream))),
+            inner: ForkGuarded::new(
+                "Microsandbox::LogStream",
+                Arc::new(Mutex::new(Box::pin(stream))),
+            ),
         }
     }
 
     /// Next log entry as a Hash, or nil when the stream ends.
     fn recv(&self) -> Result<Option<RHash>, Error> {
         use futures::StreamExt;
-        let inner = Arc::clone(&self.inner);
-        match block_on(async move { inner.lock().await.next().await }) {
+        let inner = Arc::clone(self.inner.get()?);
+        match block_on(async move { inner.lock().await.next().await })? {
             Some(Ok(entry)) => Ok(Some(log_entry_to_hash(&entry))),
             Some(Err(e)) => Err(error::to_ruby(e)),
             None => Ok(None),
@@ -51,7 +54,7 @@ impl LogStream {
 
 #[magnus::wrap(class = "Microsandbox::Native::MetricsStream", free_immediately, size)]
 pub struct MetricsStream {
-    inner: Arc<Mutex<BoxStream<SandboxMetrics>>>,
+    inner: ForkGuarded<Arc<Mutex<BoxStream<SandboxMetrics>>>>,
 }
 
 impl MetricsStream {
@@ -59,15 +62,18 @@ impl MetricsStream {
         stream: impl Stream<Item = MicrosandboxResult<SandboxMetrics>> + Send + 'static,
     ) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(Box::pin(stream))),
+            inner: ForkGuarded::new(
+                "Microsandbox::MetricsStream",
+                Arc::new(Mutex::new(Box::pin(stream))),
+            ),
         }
     }
 
     /// Next metrics snapshot as a Hash, or nil when the stream ends.
     fn recv(&self) -> Result<Option<RHash>, Error> {
         use futures::StreamExt;
-        let inner = Arc::clone(&self.inner);
-        match block_on(async move { inner.lock().await.next().await }) {
+        let inner = Arc::clone(self.inner.get()?);
+        match block_on(async move { inner.lock().await.next().await })? {
             Some(Ok(metrics)) => Ok(Some(metrics_to_hash(&metrics))),
             Some(Err(e)) => Err(error::to_ruby(e)),
             None => Ok(None),
@@ -77,9 +83,13 @@ impl MetricsStream {
 
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let logs = native.define_class("LogStream", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<LogStream>(ruby);
     logs.define_method("recv", method!(LogStream::recv, 0))?;
 
     let metrics = native.define_class("MetricsStream", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<MetricsStream>(ruby);
     metrics.define_method("recv", method!(MetricsStream::recv, 0))?;
 
     Ok(())

data/ext/microsandbox/src/volume.rs

@@ -12,7 +12,7 @@ use microsandbox::{Backend, MicrosandboxError};
 
 use crate::conv;
 use crate::error;
-use crate::runtime::{block_on, ruby};
+use crate::runtime::{block_on, ruby, ForkGuarded};
 use crate::sandbox::{fs_entry_to_hash, fs_metadata_to_hash};
 
 fn handle_to_hash(h: &VolumeHandle) -> RHash {
@@ -68,7 +68,7 @@ fn create(name: String, opts: RHash) -> Result<RHash, Error> {
         builder = builder.label(k, v);
     }
 
-    let vol = block_on(builder.create()).map_err(error::to_ruby)?;
+    let vol = block_on(builder.create())?.map_err(error::to_ruby)?;
     let hash = ruby().hash_new();
     hash.aset("name", vol.name().to_string())?;
     // `path()` is fallible as of v0.5.8 (returns `Unsupported` for cloud
@@ -81,19 +81,19 @@ fn create(name: String, opts: RHash) -> Result<RHash, Error> {
 }
 
 fn get(name: String) -> Result<RHash, Error> {
-    let handle = block_on(microsandbox::Volume::get(&name)).map_err(error::to_ruby)?;
+    let handle = block_on(microsandbox::Volume::get(&name))?.map_err(error::to_ruby)?;
     Ok(handle_to_hash(&handle))
 }
 
 /// The backend's default volume (v0.6.9). Cloud-backend only — the local
 /// backend rejects it (Unsupported) to avoid accidental host access.
 fn get_default() -> Result<RHash, Error> {
-    let handle = block_on(microsandbox::Volume::get_default()).map_err(error::to_ruby)?;
+    let handle = block_on(microsandbox::Volume::get_default())?.map_err(error::to_ruby)?;
     Ok(handle_to_hash(&handle))
 }
 
 fn list() -> Result<RArray, Error> {
-    let handles = block_on(microsandbox::Volume::list()).map_err(error::to_ruby)?;
+    let handles = block_on(microsandbox::Volume::list())?.map_err(error::to_ruby)?;
     let arr = ruby().ary_new();
     for h in handles.iter() {
         arr.push(handle_to_hash(h))?;
@@ -102,7 +102,7 @@ fn list() -> Result<RArray, Error> {
 }
 
 fn remove(name: String) -> Result<(), Error> {
-    block_on(microsandbox::Volume::remove(&name)).map_err(error::to_ruby)
+    block_on(microsandbox::Volume::remove(&name))?.map_err(error::to_ruby)
 }
 
 /// Volume paths are relative to the volume root and never need a `..` segment,
@@ -128,7 +128,9 @@ fn contained(path: &str) -> Result<&str, Error> {
 /// each operation rebuilds it from the stored backend + name.
 #[magnus::wrap(class = "Microsandbox::Native::VolumeFs", free_immediately, size)]
 pub struct VolumeFs {
-    backend: Arc<dyn Backend>,
+    /// The backend this view is bound to — a clone of the creating process's
+    /// default backend, so it must not cross a fork.
+    backend: ForkGuarded<Arc<dyn Backend>>,
     name: String,
 }
 
@@ -138,41 +140,45 @@ impl VolumeFs {
     /// trait, which yields precise per-operation `Unsupported` errors on
     /// backends that can't serve it — no local-only downcast needed here.
     fn for_volume(name: String) -> Result<VolumeFs, Error> {
+        crate::backend::ensure_this_process_backend()?;
         Ok(VolumeFs {
-            backend: microsandbox::default_backend(),
+            backend: ForkGuarded::new("Microsandbox::VolumeFs", microsandbox::default_backend()),
             name,
         })
     }
 
-    fn fs(&self) -> microsandbox::volume::VolumeFs<'_> {
-        microsandbox::volume::VolumeFs::with_backend(self.backend.clone(), &self.name)
+    fn fs(&self) -> Result<microsandbox::volume::VolumeFs<'_>, Error> {
+        let backend = self.backend.get()?.clone();
+        Ok(microsandbox::volume::VolumeFs::with_backend(
+            backend, &self.name,
+        ))
     }
 
     fn read(&self, path: String) -> Result<RString, Error> {
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        let bytes = block_on(fs.read(path)).map_err(error::to_ruby)?;
+        let bytes = block_on(fs.read(path))?.map_err(error::to_ruby)?;
         Ok(ruby().str_from_slice(bytes.as_ref()))
     }
 
     fn read_text(&self, path: String) -> Result<String, Error> {
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        block_on(fs.read_to_string(path)).map_err(error::to_ruby)
+        block_on(fs.read_to_string(path))?.map_err(error::to_ruby)
     }
 
     fn write(&self, path: String, data: RString) -> Result<(), Error> {
         // Copy the bytes out while the GVL is held (GC.compact could move them).
         let bytes = unsafe { data.as_slice() }.to_vec();
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        block_on(fs.write(path, &bytes)).map_err(error::to_ruby)
+        block_on(fs.write(path, &bytes))?.map_err(error::to_ruby)
     }
 
     fn list(&self, path: String) -> Result<RArray, Error> {
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        let entries = block_on(fs.list(path)).map_err(error::to_ruby)?;
+        let entries = block_on(fs.list(path))?.map_err(error::to_ruby)?;
         let arr = ruby().ary_new();
         for entry in &entries {
             arr.push(fs_entry_to_hash(entry))?;
@@ -181,47 +187,47 @@ impl VolumeFs {
     }
 
     fn mkdir(&self, path: String) -> Result<(), Error> {
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        block_on(fs.mkdir(path)).map_err(error::to_ruby)
+        block_on(fs.mkdir(path))?.map_err(error::to_ruby)
     }
 
     fn remove_file(&self, path: String) -> Result<(), Error> {
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        block_on(fs.remove(path)).map_err(error::to_ruby)
+        block_on(fs.remove(path))?.map_err(error::to_ruby)
     }
 
     fn remove_dir(&self, path: String) -> Result<(), Error> {
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        block_on(fs.remove_dir(path)).map_err(error::to_ruby)
+        block_on(fs.remove_dir(path))?.map_err(error::to_ruby)
     }
 
     fn exists(&self, path: String) -> Result<bool, Error> {
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        block_on(fs.exists(path)).map_err(error::to_ruby)
+        block_on(fs.exists(path))?.map_err(error::to_ruby)
     }
 
     fn copy(&self, from: String, to: String) -> Result<(), Error> {
+        let fs = self.fs()?;
         let from = contained(&from)?;
         let to = contained(&to)?;
-        let fs = self.fs();
-        block_on(fs.copy(from, to)).map_err(error::to_ruby)
+        block_on(fs.copy(from, to))?.map_err(error::to_ruby)
     }
 
     fn rename(&self, from: String, to: String) -> Result<(), Error> {
+        let fs = self.fs()?;
         let from = contained(&from)?;
         let to = contained(&to)?;
-        let fs = self.fs();
-        block_on(fs.rename(from, to)).map_err(error::to_ruby)
+        block_on(fs.rename(from, to))?.map_err(error::to_ruby)
     }
 
     fn stat(&self, path: String) -> Result<RHash, Error> {
+        let fs = self.fs()?;
         let path = contained(&path)?;
-        let fs = self.fs();
-        let meta = block_on(fs.stat(path)).map_err(error::to_ruby)?;
+        let meta = block_on(fs.stat(path))?.map_err(error::to_ruby)?;
         Ok(fs_metadata_to_hash(&meta))
     }
 }
@@ -241,6 +247,8 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_singleton_method("fs", function!(fs, 1))?;
 
     let vfs = native.define_class("VolumeFs", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<VolumeFs>(ruby);
     vfs.define_method("read", method!(VolumeFs::read, 1))?;
     vfs.define_method("read_text", method!(VolumeFs::read_text, 1))?;
     vfs.define_method("write", method!(VolumeFs::write, 2))?;