microsandbox-rb 0.17.0 → 0.17.2

data/ext/microsandbox/src/sandbox.rs

@@ -7,6 +7,7 @@
 //! as a plain Ruby `Hash`/`Array`/`String` and shaped into value objects by the
 //! Ruby layer.
 
+use std::path::PathBuf;
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -39,6 +40,7 @@ use tokio::task::JoinHandle;
 use crate::conv;
 use crate::error;
 use crate::exec::ExecHandle;
+use crate::host_path::{self, HostPaths};
 use crate::runtime::{block_on, ruby};
 use crate::stream::{LogStream, MetricsStream};
 
@@ -75,6 +77,9 @@ impl Sandbox {
     /// Shared by `create` (blocking) and `create_with_progress` (streaming pull).
     fn build_builder(name: String, opts: RHash) -> Result<SandboxBuilder, Error> {
         let mut b = microsandbox::Sandbox::builder(name);
+        // Relative host paths are anchored to the current directory here, once,
+        // before the core persists them (see host_path.rs).
+        let host_paths = HostPaths::for_default_backend();
 
         if let Some(v) = conv::opt_string(opts, "image")? {
             if let Some(fstype) = conv::opt_string(opts, "fstype")? {
@@ -83,13 +88,17 @@ impl Sandbox {
                 // image_with(disk().fstype()). (A bare `image` string otherwise
                 // auto-detects OCI vs disk by extension.) Errors in disk()/fstype()
                 // are captured on the builder and surface at create().
-                b = b.image_with(move |i| i.disk(v).fstype(fstype));
+                let path = host_paths.pin(v, "root disk image path")?;
+                b = b.image_with(move |i| i.disk(path).fstype(fstype));
             } else {
-                b = b.image(v);
+                b = match host_paths.pin_image(v)? {
+                    host_path::Image::Text(text) => b.image(text),
+                    host_path::Image::Path(path) => b.image(path),
+                };
             }
         }
         if let Some(v) = conv::opt_string(opts, "from_snapshot")? {
-            b = b.from_snapshot(v);
+            b = b.from_snapshot(host_paths.pin_snapshot(v)?);
         }
         if let Some(v) = conv::opt_u8(opts, "cpus")? {
             b = b.cpus(v);
@@ -208,27 +217,35 @@ impl Sandbox {
             // the per-mount opt-out. Valid for bind/named-directory mounts —
             // the core rejects it elsewhere at build().
             let follow_root_symlinks = conv::opt::<bool>(m, "follow_root_symlinks")?;
-            // bind/named/disk require a source; tmpfs must not have one.
-            match kind.as_str() {
-                "bind" | "named" | "disk" if source.is_some() => {}
-                "bind" | "named" | "disk" => {
+            // bind/named/disk require a source; tmpfs must not have one. A
+            // bind or disk source is a host path; a named source is a volume
+            // name and is never resolved.
+            let backing = match (kind.as_str(), source) {
+                ("bind", Some(host)) => {
+                    MountBacking::Bind(host_paths.pin(host, "bind mount host path")?)
+                }
+                ("disk", Some(host)) => {
+                    MountBacking::Disk(host_paths.pin(host, "disk mount host path")?)
+                }
+                ("named", Some(name)) => MountBacking::Named(name),
+                ("bind" | "named" | "disk", None) => {
                     return Err(error::base_error(format!(
                         "volume mount kind {kind:?} requires a source"
                     )))
                 }
-                "tmpfs" => {}
-                other => {
+                ("tmpfs", _) => MountBacking::Tmpfs,
+                (other, _) => {
                     return Err(error::base_error(format!(
                         "unknown volume mount kind {other:?} (expected bind/named/tmpfs/disk)"
                     )))
                 }
-            }
+            };
             b = b.volume(guest, move |mut mb| {
-                mb = match kind.as_str() {
-                    "named" => mb.named(source.unwrap()),
-                    "tmpfs" => mb.tmpfs(),
-                    "disk" => mb.disk(source.unwrap()),
-                    _ => mb.bind(source.unwrap()), // "bind"
+                mb = match backing {
+                    MountBacking::Named(name) => mb.named(name),
+                    MountBacking::Tmpfs => mb.tmpfs(),
+                    MountBacking::Disk(host) => mb.disk(host),
+                    MountBacking::Bind(host) => mb.bind(host),
                 };
                 if let Some(n) = size_mib {
                     mb = mb.size(n);
@@ -272,7 +289,7 @@ impl Sandbox {
         // patches: rootfs modifications applied before boot. The Ruby layer
         // normalizes each `Microsandbox::Patch.*` into a string-keyed Hash with
         // a `kind` discriminator; mirrors the Python binding's `apply_patch`.
-        for patch in parse_patches(opts)? {
+        for patch in parse_patches(opts, host_paths)? {
             b = b.add_patch(patch);
         }
         if let Some(net) = conv::opt_string(opts, "network")? {
@@ -326,7 +343,7 @@ impl Sandbox {
         // layer maps the deprecated `oci_upper_size:` kwarg to the managed kind
         // before it reaches the wire.
         if let Some(v) = conv::opt::<Value>(opts, "root_disk")? {
-            let spec = parse_root_disk(v)?;
+            let spec = parse_root_disk(v, host_paths)?;
             b = b.root_disk_with(move |d| spec.apply(d));
         }
         // Registry connection settings, for private / non-default registries:
@@ -374,7 +391,7 @@ impl Sandbox {
             .map(parse_dns)
             .transpose()?;
         let tls = conv::opt::<RHash>(opts, "tls")?
-            .map(parse_tls)
+            .map(|t| parse_tls(t, host_paths))
             .transpose()?;
         let ipv4_pool = conv::opt_string(opts, "ipv4_pool")?
             .map(|s| {
@@ -529,7 +546,7 @@ impl Sandbox {
     /// Create and boot a sandbox. `opts` is a string-keyed options Hash.
     fn create(name: String, opts: RHash) -> Result<Sandbox, Error> {
         let b = Self::build_builder(name, opts)?;
-        let inner = block_on(b.create()).map_err(error::to_ruby)?;
+        let inner = block_on(b.create())?.map_err(error::to_ruby)?;
         Ok(Sandbox::from_inner(inner))
     }
 
@@ -542,7 +559,7 @@ impl Sandbox {
         // `create_with_pull_progress` spawns a tokio task, so it must run inside
         // the runtime context even though the call itself is synchronous.
         let (handle, join) =
-            block_on(async move { b.create_with_pull_progress() }).map_err(error::to_ruby)?;
+            block_on(async move { b.create_with_pull_progress() })?.map_err(error::to_ruby)?;
         Ok(PullSession::new(handle, join))
     }
 
@@ -552,7 +569,7 @@ impl Sandbox {
     /// the combination with `replace`.
     fn connect_or_create(name: String, opts: RHash) -> Result<Sandbox, Error> {
         let b = Self::build_builder(name, opts)?;
-        let inner = block_on(b.connect_or_create()).map_err(error::to_ruby)?;
+        let inner = block_on(b.connect_or_create())?.map_err(error::to_ruby)?;
         Ok(Sandbox::from_inner(inner))
     }
 
@@ -560,9 +577,9 @@ impl Sandbox {
     fn start(name: String, opts: RHash) -> Result<Sandbox, Error> {
         let detached = conv::opt_bool(opts, "detached")?;
         let inner = if detached {
-            block_on(microsandbox::Sandbox::start_detached(&name)).map_err(error::to_ruby)?
+            block_on(microsandbox::Sandbox::start_detached(&name))?.map_err(error::to_ruby)?
         } else {
-            block_on(microsandbox::Sandbox::start(&name)).map_err(error::to_ruby)?
+            block_on(microsandbox::Sandbox::start(&name))?.map_err(error::to_ruby)?
         };
         Ok(Sandbox::from_inner(inner))
     }
@@ -570,7 +587,7 @@ impl Sandbox {
     /// A controllable handle for a sandbox by name (running or not). Carries
     /// metadata accessors and the full lifecycle surface (see `SbHandle`).
     fn get(name: String) -> Result<SbHandle, Error> {
-        let handle = block_on(microsandbox::Sandbox::get(&name)).map_err(error::to_ruby)?;
+        let handle = block_on(microsandbox::Sandbox::get(&name))?.map_err(error::to_ruby)?;
         Ok(SbHandle::from_inner(handle))
     }
 
@@ -590,7 +607,7 @@ impl Sandbox {
     /// First page of sandboxes (default page size), as a page Hash of
     /// controllable handles.
     fn list() -> Result<RHash, Error> {
-        let page = block_on(microsandbox::Sandbox::list()).map_err(error::to_ruby)?;
+        let page = block_on(microsandbox::Sandbox::list())?.map_err(error::to_ruby)?;
         Self::page_to_hash(page)
     }
 
@@ -609,14 +626,14 @@ impl Sandbox {
                 b = b.cursor(cursor);
             }
             b.labels(labels)
-        }))
+        }))?
         .map_err(error::to_ruby)?;
         Self::page_to_hash(page)
     }
 
     /// Remove a (stopped) sandbox by name.
     fn remove(name: String) -> Result<(), Error> {
-        block_on(microsandbox::Sandbox::remove(&name)).map_err(error::to_ruby)
+        block_on(microsandbox::Sandbox::remove(&name))?.map_err(error::to_ruby)
     }
 
     //----------------------------------------------------------------------
@@ -638,7 +655,7 @@ impl Sandbox {
     /// string-keyed Hash (cwd, user, env, timeout, tty, stdin).
     fn exec(&self, cmd: String, args: Vec<String>, opts: RHash) -> Result<RHash, Error> {
         let parsed = ExecOpts::parse(args, opts)?;
-        let output = block_on(self.inner.exec_with(cmd, move |b| parsed.apply(b)))
+        let output = block_on(self.inner.exec_with(cmd, move |b| parsed.apply(b)))?
             .map_err(error::to_ruby)?;
         exec_output_to_hash(output)
     }
@@ -646,7 +663,7 @@ impl Sandbox {
     /// Run a shell script (pipes/redirects allowed).
     fn shell(&self, script: String, opts: RHash) -> Result<RHash, Error> {
         let parsed = ExecOpts::parse(Vec::new(), opts)?;
-        let output = block_on(self.inner.shell_with(script, move |b| parsed.apply(b)))
+        let output = block_on(self.inner.shell_with(script, move |b| parsed.apply(b)))?
             .map_err(error::to_ruby)?;
         exec_output_to_hash(output)
     }
@@ -659,7 +676,7 @@ impl Sandbox {
         opts: RHash,
     ) -> Result<ExecHandle, Error> {
         let parsed = ExecOpts::parse(args, opts)?;
-        let handle = block_on(self.inner.exec_stream_with(cmd, move |b| parsed.apply(b)))
+        let handle = block_on(self.inner.exec_stream_with(cmd, move |b| parsed.apply(b)))?
             .map_err(error::to_ruby)?;
         Ok(ExecHandle::from_core(handle))
     }
@@ -671,7 +688,7 @@ impl Sandbox {
     /// NoDefaultCommandError when the image resolves no executable command.
     fn exec_default(&self, opts: RHash) -> Result<RHash, Error> {
         let parsed = ExecOpts::parse(Vec::new(), opts)?;
-        let output = block_on(self.inner.exec_default_with(move |b| parsed.apply(b)))
+        let output = block_on(self.inner.exec_default_with(move |b| parsed.apply(b)))?
             .map_err(error::to_ruby)?;
         exec_output_to_hash(output)
     }
@@ -682,7 +699,7 @@ impl Sandbox {
         let handle = block_on(
             self.inner
                 .exec_default_stream_with(move |b| parsed.apply(b)),
-        )
+        )?
         .map_err(error::to_ruby)?;
         Ok(ExecHandle::from_core(handle))
     }
@@ -693,7 +710,7 @@ impl Sandbox {
         let handle = block_on(
             self.inner
                 .shell_stream_with(script, move |b| parsed.apply(b)),
-        )
+        )?
         .map_err(error::to_ruby)?;
         Ok(ExecHandle::from_core(handle))
     }
@@ -714,29 +731,29 @@ impl Sandbox {
     /// Fine-grained control — a custom timeout or fire-and-return `request_*` —
     /// lives on `SandboxHandle`, obtained via `Sandbox.get`.
     fn stop(&self) -> Result<(), Error> {
-        block_on(self.inner.stop()).map_err(error::to_ruby)
+        block_on(self.inner.stop())?.map_err(error::to_ruby)
     }
 
     /// Graceful stop, then wait for the process to exit. Returns an exit-status
     /// Hash (`exit_code`, `success`). Local backend only.
     fn stop_and_wait(&self) -> Result<RHash, Error> {
-        let status = block_on(self.inner.stop_and_wait()).map_err(error::to_ruby)?;
+        let status = block_on(self.inner.stop_and_wait())?.map_err(error::to_ruby)?;
         Ok(exit_status_to_hash(status))
     }
 
     /// Force kill (SIGKILL).
     fn kill(&self) -> Result<(), Error> {
-        block_on(self.inner.kill()).map_err(error::to_ruby)
+        block_on(self.inner.kill())?.map_err(error::to_ruby)
     }
 
     /// Trigger a graceful drain (SIGUSR1 on local).
     fn drain(&self) -> Result<(), Error> {
-        block_on(self.inner.drain()).map_err(error::to_ruby)
+        block_on(self.inner.drain())?.map_err(error::to_ruby)
     }
 
     /// Wait for the process to exit. Returns an exit-status Hash. Local only.
     fn wait(&self) -> Result<RHash, Error> {
-        let status = block_on(self.inner.wait()).map_err(error::to_ruby)?;
+        let status = block_on(self.inner.wait())?.map_err(error::to_ruby)?;
         Ok(exit_status_to_hash(status))
     }
 
@@ -745,7 +762,7 @@ impl Sandbox {
     /// `SandboxReplacedError` instead of silently redirecting the wait.
     fn wait_for_status(&self, status: String) -> Result<SbHandle, Error> {
         let status = sandbox_status_from_str(&status)?;
-        let handle = block_on(self.inner.wait_for_status(status)).map_err(error::to_ruby)?;
+        let handle = block_on(self.inner.wait_for_status(status))?.map_err(error::to_ruby)?;
         Ok(SbHandle::from_inner(handle))
     }
 
@@ -753,19 +770,19 @@ impl Sandbox {
     /// `opts` carries `force`/`timeout`/`detached`.
     fn restart(&self, opts: RHash) -> Result<Sandbox, Error> {
         let options = restart_options(opts)?;
-        let inner = block_on(self.inner.restart_with(options)).map_err(error::to_ruby)?;
+        let inner = block_on(self.inner.restart_with(options))?.map_err(error::to_ruby)?;
         Ok(Sandbox::from_inner(inner))
     }
 
     /// Stop and remove this exact sandbox. `opts` carries `force`/`timeout`.
     fn destroy(&self, opts: RHash) -> Result<(), Error> {
         let options = destroy_options(opts)?;
-        block_on(self.inner.destroy_with(options)).map_err(error::to_ruby)
+        block_on(self.inner.destroy_with(options))?.map_err(error::to_ruby)
     }
 
     /// Live status fetched from the backend (a round-trip per call).
     fn status(&self) -> Result<String, Error> {
-        let status = block_on(self.inner.status()).map_err(error::to_ruby)?;
+        let status = block_on(self.inner.status())?.map_err(error::to_ruby)?;
         Ok(sandbox_status_str(status).to_string())
     }
 
@@ -781,13 +798,13 @@ impl Sandbox {
     /// detaching a clone disarms the shared handle just the same.
     fn detach(&self) -> Result<(), Error> {
         let inner = self.inner.clone();
-        block_on(inner.detach());
+        block_on(inner.detach())?;
         Ok(())
     }
 
     /// Latest metrics snapshot as a Hash.
     fn metrics(&self) -> Result<RHash, Error> {
-        let m = block_on(self.inner.metrics()).map_err(error::to_ruby)?;
+        let m = block_on(self.inner.metrics())?.map_err(error::to_ruby)?;
         Ok(metrics_to_hash(&m))
     }
 
@@ -799,14 +816,14 @@ impl Sandbox {
     /// `{ name, latency_secs }` (round-trip latency as f64 seconds; the Ruby
     /// layer exposes both seconds and milliseconds).
     fn ping(&self) -> Result<RHash, Error> {
-        let result = block_on(self.inner.ping()).map_err(error::to_ruby)?;
+        let result = block_on(self.inner.ping())?.map_err(error::to_ruby)?;
         Ok(ping_result_to_hash(&result))
     }
 
     /// Explicitly refresh the idle-activity timer. Returns
     /// `{ name, activity_seq }`.
     fn touch(&self) -> Result<RHash, Error> {
-        let result = block_on(self.inner.touch()).map_err(error::to_ruby)?;
+        let result = block_on(self.inner.touch())?.map_err(error::to_ruby)?;
         Ok(touch_result_to_hash(&result))
     }
 
@@ -823,7 +840,7 @@ impl Sandbox {
     /// until_ms, sources (Array of "stdout"/"stderr"/"output"/"system"/"all").
     fn logs(&self, opts: RHash) -> Result<RArray, Error> {
         let log_opts = parse_log_options(opts)?;
-        let entries = block_on(self.inner.logs(&log_opts)).map_err(error::to_ruby)?;
+        let entries = block_on(self.inner.logs(&log_opts))?.map_err(error::to_ruby)?;
         rhash_array(entries.iter().map(log_entry_to_hash))
     }
 
@@ -843,7 +860,7 @@ impl Sandbox {
         // which panics ("no reactor running") unless constructed inside the
         // runtime context — so build it under `block_on`. (`log_stream` is async
         // and already runs inside `block_on`, so it needs no such wrapper.)
-        let stream = block_on(async { self.inner.metrics_stream(dur) });
+        let stream = block_on(async { self.inner.metrics_stream(dur) })?;
         Ok(MetricsStream::from_stream(stream))
     }
 
@@ -851,7 +868,7 @@ impl Sandbox {
     /// from_cursor, until_ms, follow. Returns a LogStream.
     fn log_stream(&self, opts: RHash) -> Result<LogStream, Error> {
         let log_opts = parse_log_stream_options(opts)?;
-        let stream = block_on(self.inner.log_stream(&log_opts)).map_err(error::to_ruby)?;
+        let stream = block_on(self.inner.log_stream(&log_opts))?.map_err(error::to_ruby)?;
         Ok(LogStream::from_stream(stream))
     }
 
@@ -861,13 +878,13 @@ impl Sandbox {
 
     fn fs_read(&self, path: String) -> Result<RString, Error> {
         let fs = self.inner.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 fs_read_text(&self, path: String) -> Result<String, Error> {
         let fs = self.inner.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 fs_write(&self, path: String, data: RString) -> Result<(), Error> {
@@ -875,72 +892,72 @@ impl Sandbox {
         // could be moved/freed by GC.compact once block_on releases it.
         let bytes = unsafe { data.as_slice() }.to_vec();
         let fs = self.inner.fs();
-        block_on(fs.write(&path, &bytes)).map_err(error::to_ruby)
+        block_on(fs.write(&path, &bytes))?.map_err(error::to_ruby)
     }
 
     fn fs_list(&self, path: String) -> Result<RArray, Error> {
         let fs = self.inner.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)?;
         rhash_array(entries.iter().map(fs_entry_to_hash))
     }
 
     fn fs_mkdir(&self, path: String) -> Result<(), Error> {
         let fs = self.inner.fs();
-        block_on(fs.mkdir(&path)).map_err(error::to_ruby)
+        block_on(fs.mkdir(&path))?.map_err(error::to_ruby)
     }
 
     fn fs_remove(&self, path: String) -> Result<(), Error> {
         let fs = self.inner.fs();
-        block_on(fs.remove(&path)).map_err(error::to_ruby)
+        block_on(fs.remove(&path))?.map_err(error::to_ruby)
     }
 
     fn fs_remove_dir(&self, path: String) -> Result<(), Error> {
         let fs = self.inner.fs();
-        block_on(fs.remove_dir(&path)).map_err(error::to_ruby)
+        block_on(fs.remove_dir(&path))?.map_err(error::to_ruby)
     }
 
     fn fs_copy(&self, src: String, dst: String) -> Result<(), Error> {
         let fs = self.inner.fs();
-        block_on(fs.copy(&src, &dst)).map_err(error::to_ruby)
+        block_on(fs.copy(&src, &dst))?.map_err(error::to_ruby)
     }
 
     fn fs_rename(&self, src: String, dst: String) -> Result<(), Error> {
         let fs = self.inner.fs();
-        block_on(fs.rename(&src, &dst)).map_err(error::to_ruby)
+        block_on(fs.rename(&src, &dst))?.map_err(error::to_ruby)
     }
 
     fn fs_exists(&self, path: String) -> Result<bool, Error> {
         let fs = self.inner.fs();
-        block_on(fs.exists(&path)).map_err(error::to_ruby)
+        block_on(fs.exists(&path))?.map_err(error::to_ruby)
     }
 
     fn fs_stat(&self, path: String) -> Result<RHash, Error> {
         let fs = self.inner.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))
     }
 
     fn fs_copy_from_host(&self, host_path: String, guest_path: String) -> Result<(), Error> {
         let fs = self.inner.fs();
-        block_on(fs.copy_from_host(&host_path, &guest_path)).map_err(error::to_ruby)
+        block_on(fs.copy_from_host(&host_path, &guest_path))?.map_err(error::to_ruby)
     }
 
     fn fs_copy_to_host(&self, guest_path: String, host_path: String) -> Result<(), Error> {
         let fs = self.inner.fs();
-        block_on(fs.copy_to_host(&guest_path, &host_path)).map_err(error::to_ruby)
+        block_on(fs.copy_to_host(&guest_path, &host_path))?.map_err(error::to_ruby)
     }
 
     /// Open a streaming reader over a guest file (for files too large to buffer).
     fn fs_read_stream(&self, path: String) -> Result<crate::fs_stream::FsReadStreamHandle, Error> {
         let fs = self.inner.fs();
-        let stream = block_on(fs.read_stream(&path)).map_err(error::to_ruby)?;
+        let stream = block_on(fs.read_stream(&path))?.map_err(error::to_ruby)?;
         Ok(crate::fs_stream::FsReadStreamHandle::new(stream))
     }
 
     /// Open a streaming writer to a guest file.
     fn fs_write_stream(&self, path: String) -> Result<crate::fs_stream::FsWriteSinkHandle, Error> {
         let fs = self.inner.fs();
-        let sink = block_on(fs.write_stream(&path)).map_err(error::to_ruby)?;
+        let sink = block_on(fs.write_stream(&path))?.map_err(error::to_ruby)?;
         Ok(crate::fs_stream::FsWriteSinkHandle::new(sink))
     }
 
@@ -969,7 +986,7 @@ impl Sandbox {
                 b = b.inactivity_timeout(t);
             }
             b.sftp(sftp)
-        }))
+        }))?
         .map_err(error::to_ruby)?;
         Ok(crate::ssh::SshClient::from_core(client))
     }
@@ -1000,7 +1017,7 @@ impl Sandbox {
                 b = b.inactivity_timeout(t);
             }
             b.sftp(sftp)
-        }))
+        }))?
         .map_err(error::to_ruby)?;
         Ok(crate::ssh::SshServer::from_core(server))
     }
@@ -1015,12 +1032,12 @@ impl Sandbox {
     /// cwd, user, env, detach_keys, rlimits.
     fn attach(&self, cmd: String, args: Vec<String>, opts: RHash) -> Result<i32, Error> {
         let parsed = AttachOpts::parse(args, opts)?;
-        block_on(self.inner.attach_with(cmd, move |b| parsed.apply(b))).map_err(error::to_ruby)
+        block_on(self.inner.attach_with(cmd, move |b| parsed.apply(b)))?.map_err(error::to_ruby)
     }
 
     /// Attach an interactive terminal running the sandbox's default shell.
     fn attach_shell(&self) -> Result<i32, Error> {
-        block_on(self.inner.attach_shell()).map_err(error::to_ruby)
+        block_on(self.inner.attach_shell())?.map_err(error::to_ruby)
     }
 
     /// Attach an interactive terminal to the image's resolved OCI ENTRYPOINT
@@ -1028,7 +1045,7 @@ impl Sandbox {
     /// cwd, user, env, detach_keys, rlimits.
     fn attach_default(&self, opts: RHash) -> Result<i32, Error> {
         let parsed = AttachOpts::parse(Vec::new(), opts)?;
-        block_on(self.inner.attach_default_with(move |b| parsed.apply(b))).map_err(error::to_ruby)
+        block_on(self.inner.attach_default_with(move |b| parsed.apply(b)))?.map_err(error::to_ruby)
     }
 }
 
@@ -1217,7 +1234,7 @@ fn patch_bytes(h: RHash, key: &str) -> Result<Vec<u8>, Error> {
 /// Parse the `patches` option into core `Patch` operations. The Ruby layer
 /// normalizes each `Microsandbox::Patch.*` into a string-keyed Hash carrying a
 /// `kind` discriminator plus the variant-specific fields.
-fn parse_patches(opts: RHash) -> Result<Vec<Patch>, Error> {
+fn parse_patches(opts: RHash, host_paths: HostPaths) -> Result<Vec<Patch>, Error> {
     let mut out = Vec::new();
     for h in conv::opt_hash_vec(opts, "patches")? {
         let kind = patch_str(h, "kind")?;
@@ -1241,13 +1258,13 @@ fn parse_patches(opts: RHash) -> Result<Vec<Patch>, Error> {
                 content: patch_str(h, "content")?,
             },
             "copy_file" => Patch::CopyFile {
-                src: patch_str(h, "src")?.into(),
+                src: host_paths.pin(patch_str(h, "src")?, "patch source path")?,
                 dst: patch_str(h, "dst")?,
                 mode,
                 replace,
             },
             "copy_dir" => Patch::CopyDir {
-                src: patch_str(h, "src")?.into(),
+                src: host_paths.pin(patch_str(h, "src")?, "patch source path")?,
                 dst: patch_str(h, "dst")?,
                 replace,
             },
@@ -1584,20 +1601,25 @@ struct TlsSpec {
     verify_upstream: Option<bool>,
     intercepted_ports: Option<Vec<u16>>,
     block_quic: Option<bool>,
-    upstream_ca_cert: Option<String>,
-    intercept_ca_cert: Option<String>,
-    intercept_ca_key: Option<String>,
+    upstream_ca_cert: Option<PathBuf>,
+    intercept_ca_cert: Option<PathBuf>,
+    intercept_ca_key: Option<PathBuf>,
 }
 
-fn parse_tls(t: RHash) -> Result<TlsSpec, Error> {
+fn parse_tls(t: RHash, host_paths: HostPaths) -> Result<TlsSpec, Error> {
+    let pin = |key: &str, label: &str| {
+        conv::opt_string(t, key)?
+            .map(|path| host_paths.pin(path, label))
+            .transpose()
+    };
     Ok(TlsSpec {
         bypass: conv::opt_string_vec(t, "bypass")?,
         verify_upstream: conv::opt::<bool>(t, "verify_upstream")?,
         intercepted_ports: conv::opt::<Vec<u16>>(t, "intercepted_ports")?,
         block_quic: conv::opt::<bool>(t, "block_quic")?,
-        upstream_ca_cert: conv::opt_string(t, "upstream_ca_cert")?,
-        intercept_ca_cert: conv::opt_string(t, "intercept_ca_cert")?,
-        intercept_ca_key: conv::opt_string(t, "intercept_ca_key")?,
+        upstream_ca_cert: pin("upstream_ca_cert", "upstream CA certificate path")?,
+        intercept_ca_cert: pin("intercept_ca_cert", "interception CA certificate path")?,
+        intercept_ca_key: pin("intercept_ca_key", "interception CA key path")?,
     })
 }
 
@@ -1711,6 +1733,14 @@ fn network_profile_from_str(s: &str) -> Result<NetworkProfile, Error> {
     }
 }
 
+/// What backs a volume mount, with any host path already pinned.
+enum MountBacking {
+    Bind(PathBuf),
+    Disk(PathBuf),
+    Named(String),
+    Tmpfs,
+}
+
 /// Parsed `root_disk` create option. Integer shorthand = managed upper of N
 /// MiB (mirrors Python's `root_disk=8192` and the CLI bare-size form); Hash =
 /// explicit kind. Kind/field cross-validation (size on a disk image, etc.)
@@ -1726,7 +1756,7 @@ struct RootDiskSpec {
 enum RootDiskKindSpec {
     Managed,
     Tmpfs,
-    Disk(String),
+    Disk(PathBuf),
     Flat,
 }
 
@@ -1754,7 +1784,7 @@ impl RootDiskSpec {
     }
 }
 
-fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
+fn parse_root_disk(v: Value, host_paths: HostPaths) -> Result<RootDiskSpec, Error> {
     if let Ok(mib) = u32::try_convert(v) {
         return Ok(RootDiskSpec {
             kind: RootDiskKindSpec::Managed,
@@ -1777,7 +1807,7 @@ fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
             let Some(path) = conv::opt_string(h, "path")? else {
                 return Err(error::base_error("root_disk disk kind requires path:"));
             };
-            RootDiskKindSpec::Disk(path)
+            RootDiskKindSpec::Disk(host_paths.pin(path, "root disk image path")?)
         }
         Some("flat") => RootDiskKindSpec::Flat,
         Some(other) => {
@@ -2343,7 +2373,7 @@ fn run_modify(builder: SandboxModificationBuilder, opts: RHash) -> Result<String
         } else {
             builder.apply().await
         }
-    })
+    })?
     .map_err(error::to_ruby)?;
     serde_json::to_string(&plan)
         .map_err(|e| error::base_error(format!("failed to serialize modification plan: {e}")))
@@ -2571,7 +2601,7 @@ impl PullSession {
     /// Next progress event as a Hash, or nil when the pull is finished.
     fn recv(&self) -> Result<Option<RHash>, Error> {
         let progress = Arc::clone(&self.progress);
-        let event = block_on(async move { progress.lock().await.recv().await });
+        let event = block_on(async move { progress.lock().await.recv().await })?;
         Ok(event.map(|p| pull_progress_to_hash(&p)))
     }
 
@@ -2579,9 +2609,20 @@ impl PullSession {
     /// create task). Consumes the join handle, so it is callable only once.
     fn result(&self) -> Result<Sandbox, Error> {
         let join = Arc::clone(&self.join);
-        let taken = block_on(async move { join.lock().await.take() });
-        let handle = taken.ok_or_else(|| error::base_error("pull session result already taken"))?;
-        let inner = block_on(handle)
+        // Take the join handle AND await it in ONE `block_on`. `block_on`
+        // returns `Err` when an interrupt is delivered before it starts; as two
+        // calls, an interrupt between them would drop the taken `JoinHandle`
+        // (which detaches the create task rather than cancelling it) and with
+        // it the only way to reach the sandbox that task boots.
+        let joined = block_on(async move {
+            let taken = join.lock().await.take();
+            match taken {
+                Some(handle) => Some(handle.await),
+                None => None,
+            }
+        })?;
+        let inner = joined
+            .ok_or_else(|| error::base_error("pull session result already taken"))?
             .map_err(|e| error::base_error(format!("sandbox creation task failed: {e}")))?
             .map_err(error::to_ruby)?;
         Ok(Sandbox::from_inner(inner))
@@ -2633,37 +2674,37 @@ impl SbHandle {
 
     /// Graceful stop (SIGTERM→SIGKILL escalation, 10s default) and wait.
     fn stop(&self) -> Result<(), Error> {
-        block_on(self.inner.stop()).map_err(error::to_ruby)
+        block_on(self.inner.stop())?.map_err(error::to_ruby)
     }
 
     /// Graceful stop with a custom escalation timeout (seconds).
     fn stop_with_timeout(&self, secs: f64) -> Result<(), Error> {
-        block_on(self.inner.stop_with_timeout(secs_to_duration(secs)?)).map_err(error::to_ruby)
+        block_on(self.inner.stop_with_timeout(secs_to_duration(secs)?))?.map_err(error::to_ruby)
     }
 
     /// Force kill (SIGKILL) and wait.
     fn kill(&self) -> Result<(), Error> {
-        block_on(self.inner.kill()).map_err(error::to_ruby)
+        block_on(self.inner.kill())?.map_err(error::to_ruby)
     }
 
     /// Force kill, waiting up to `secs` for the process to disappear.
     fn kill_with_timeout(&self, secs: f64) -> Result<(), Error> {
-        block_on(self.inner.kill_with_timeout(secs_to_duration(secs)?)).map_err(error::to_ruby)
+        block_on(self.inner.kill_with_timeout(secs_to_duration(secs)?))?.map_err(error::to_ruby)
     }
 
     /// Send the graceful-shutdown request and return without waiting.
     fn request_stop(&self) -> Result<(), Error> {
-        block_on(self.inner.request_stop()).map_err(error::to_ruby)
+        block_on(self.inner.request_stop())?.map_err(error::to_ruby)
     }
 
     /// Send the force-kill request and return without waiting.
     fn request_kill(&self) -> Result<(), Error> {
-        block_on(self.inner.request_kill()).map_err(error::to_ruby)
+        block_on(self.inner.request_kill())?.map_err(error::to_ruby)
     }
 
     /// Send the drain request (SIGUSR1) and return without waiting.
     fn request_drain(&self) -> Result<(), Error> {
-        block_on(self.inner.request_drain()).map_err(error::to_ruby)
+        block_on(self.inner.request_drain())?.map_err(error::to_ruby)
     }
 
     /// Connect when this exact sandbox is running, wait while it is starting,
@@ -2677,7 +2718,7 @@ impl SbHandle {
             } else {
                 self.inner.connect_or_start().await
             }
-        })
+        })?
         .map_err(error::to_ruby)?;
         Ok(Sandbox::from_inner(inner))
     }
@@ -2687,7 +2728,7 @@ impl SbHandle {
     /// `SandboxReplacedError` instead of silently redirecting the wait.
     fn wait_for_status(&self, status: String) -> Result<SbHandle, Error> {
         let status = sandbox_status_from_str(&status)?;
-        let handle = block_on(self.inner.wait_for_status(status)).map_err(error::to_ruby)?;
+        let handle = block_on(self.inner.wait_for_status(status))?.map_err(error::to_ruby)?;
         Ok(SbHandle::from_inner(handle))
     }
 
@@ -2695,20 +2736,20 @@ impl SbHandle {
     /// `opts` carries `force`/`timeout`/`detached`.
     fn restart(&self, opts: RHash) -> Result<Sandbox, Error> {
         let options = restart_options(opts)?;
-        let inner = block_on(self.inner.restart_with(options)).map_err(error::to_ruby)?;
+        let inner = block_on(self.inner.restart_with(options))?.map_err(error::to_ruby)?;
         Ok(Sandbox::from_inner(inner))
     }
 
     /// Stop and remove this exact sandbox. `opts` carries `force`/`timeout`.
     fn destroy(&self, opts: RHash) -> Result<(), Error> {
         let options = destroy_options(opts)?;
-        block_on(self.inner.destroy_with(options)).map_err(error::to_ruby)
+        block_on(self.inner.destroy_with(options))?.map_err(error::to_ruby)
     }
 
     /// Block until the sandbox reaches a terminal state; returns a stop-result
     /// Hash (name, status, exit_code, signal, observed_at_ms, source).
     fn wait_until_stopped(&self) -> Result<RHash, Error> {
-        let result = block_on(self.inner.wait_until_stopped()).map_err(error::to_ruby)?;
+        let result = block_on(self.inner.wait_until_stopped())?.map_err(error::to_ruby)?;
         Ok(stop_result_to_hash(&result))
     }
 
@@ -2725,7 +2766,7 @@ impl SbHandle {
     /// (`snapshot_to` was removed upstream in v0.6.7 — use `Snapshot.create`
     /// with `dest_dir:` for explicit placement.)
     fn snapshot(&self, name: String) -> Result<RHash, Error> {
-        let snap = block_on(self.inner.snapshot(&name)).map_err(error::to_ruby)?;
+        let snap = block_on(self.inner.snapshot(&name))?.map_err(error::to_ruby)?;
         Ok(crate::snapshot::snapshot_to_hash(&snap))
     }
 
@@ -2733,14 +2774,14 @@ impl SbHandle {
     /// sandbox raises `SandboxNotRunningError` (the handle does not start it
     /// implicitly). Returns `{ name, latency_secs }`.
     fn ping(&self) -> Result<RHash, Error> {
-        let result = block_on(self.inner.ping()).map_err(error::to_ruby)?;
+        let result = block_on(self.inner.ping())?.map_err(error::to_ruby)?;
         Ok(ping_result_to_hash(&result))
     }
 
     /// Explicitly refresh the idle-activity timer. A stopped sandbox raises
     /// `SandboxNotRunningError`. Returns `{ name, activity_seq }`.
     fn touch(&self) -> Result<RHash, Error> {
-        let result = block_on(self.inner.touch()).map_err(error::to_ruby)?;
+        let result = block_on(self.inner.touch())?.map_err(error::to_ruby)?;
         Ok(touch_result_to_hash(&result))
     }
 
@@ -2836,6 +2877,8 @@ pub(crate) fn log_entry_to_hash(entry: &LogEntry) -> RHash {
 
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let class = native.define_class("Sandbox", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<Sandbox>(ruby);
 
     class.define_singleton_method("create", function!(Sandbox::create, 2))?;
     class.define_singleton_method(
@@ -2909,6 +2952,8 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("attach_shell", method!(Sandbox::attach_shell, 0))?;
 
     let handle = native.define_class("SandboxHandle", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<SbHandle>(ruby);
     handle.define_method("name", method!(SbHandle::name, 0))?;
     handle.define_method("id", method!(SbHandle::id, 0))?;
     handle.define_method("status", method!(SbHandle::status, 0))?;
@@ -2936,6 +2981,8 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     handle.define_method("modify", method!(SbHandle::modify, 1))?;
 
     let session = native.define_class("PullSession", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<PullSession>(ruby);
     session.define_method("recv", method!(PullSession::recv, 0))?;
     session.define_method("result", method!(PullSession::result, 0))?;