microsandbox-rb 0.17.2 → 0.17.4

data/ext/microsandbox/src/fs_stream.rs

@@ -16,23 +16,23 @@ use microsandbox::sandbox::{FsReadStream, FsWriteSink};
 use tokio::sync::Mutex;
 
 use crate::error;
-use crate::runtime::{block_on, ruby};
+use crate::runtime::{block_on, ruby, ForkGuarded};
 
 #[magnus::wrap(class = "Microsandbox::Native::FsReadStream", free_immediately, size)]
 pub struct FsReadStreamHandle {
-    inner: Arc<Mutex<FsReadStream>>,
+    inner: ForkGuarded<Arc<Mutex<FsReadStream>>>,
 }
 
 impl FsReadStreamHandle {
     pub fn new(stream: FsReadStream) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(stream)),
+            inner: ForkGuarded::new("Microsandbox::FsReadStream", Arc::new(Mutex::new(stream))),
         }
     }
 
     /// Next chunk of bytes (ASCII-8BIT), or nil at end of stream.
     fn recv(&self) -> Result<Option<RString>, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         match block_on(async move { inner.lock().await.recv().await })?.map_err(error::to_ruby)? {
             Some(bytes) => Ok(Some(ruby().str_from_slice(bytes.as_ref()))),
             None => Ok(None),
@@ -42,13 +42,16 @@ impl FsReadStreamHandle {
 
 #[magnus::wrap(class = "Microsandbox::Native::FsWriteSink", free_immediately, size)]
 pub struct FsWriteSinkHandle {
-    inner: Arc<Mutex<Option<FsWriteSink>>>,
+    inner: ForkGuarded<Arc<Mutex<Option<FsWriteSink>>>>,
 }
 
 impl FsWriteSinkHandle {
     pub fn new(sink: FsWriteSink) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(Some(sink))),
+            inner: ForkGuarded::new(
+                "Microsandbox::FsWriteSink",
+                Arc::new(Mutex::new(Some(sink))),
+            ),
         }
     }
 
@@ -56,7 +59,7 @@ impl FsWriteSinkHandle {
     fn write(&self, data: RString) -> Result<(), Error> {
         // Copy out while the GVL is held (GC.compact could move the buffer).
         let bytes = unsafe { data.as_slice() }.to_vec();
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result = block_on(async move {
             let guard = inner.lock().await;
             match guard.as_ref() {
@@ -72,7 +75,7 @@ impl FsWriteSinkHandle {
 
     /// Flush and close the sink. Idempotent.
     fn close(&self) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         // Take AND close 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 sink the first one took without ever

data/ext/microsandbox/src/host_path.rs

@@ -47,10 +47,11 @@ pub struct HostPaths {
 
 impl HostPaths {
     /// Capture which backend the create call is about to dispatch to.
-    pub fn for_default_backend() -> Self {
-        Self {
+    pub fn for_default_backend() -> Result<Self, Error> {
+        crate::backend::ensure_this_process_backend()?;
+        Ok(Self {
             local: matches!(microsandbox::default_backend().kind(), BackendKind::Local),
-        }
+        })
     }
 
     /// Anchor a relative host path to the current directory. Absolute paths

data/ext/microsandbox/src/lib.rs

@@ -46,8 +46,10 @@ fn all_sandbox_metrics() -> Result<RHash, Error> {
 }
 
 /// Download and install the `msb` runtime + `libkrunfw` into `~/.microsandbox`.
+/// Never touches the backend, so a forked child does not take the inherited
+/// one over here (see `runtime::block_on_runtime_install`).
 fn install() -> Result<(), Error> {
-    runtime::block_on(microsandbox::setup::install())?.map_err(error::to_ruby)
+    runtime::block_on_runtime_install(microsandbox::setup::install())?.map_err(error::to_ruby)
 }
 
 /// Customizable install via the core `Setup` builder. `opts`: base_dir (install
@@ -84,7 +86,8 @@ fn setup(opts: RHash) -> Result<(), Error> {
             .force(force)
             .build(),
     };
-    runtime::block_on(setup.install())?.map_err(error::to_ruby)
+    // Backend-free, like `install`.
+    runtime::block_on_runtime_install(setup.install())?.map_err(error::to_ruby)
 }
 
 /// Whether the `msb` runtime + `libkrunfw` are installed and resolvable.
@@ -108,6 +111,7 @@ fn set_runtime_libkrunfw_path(path: String) {
 /// no async) — runs on the Ruby thread; resolves the path from the local
 /// backend's config.
 fn resolved_msb_path() -> Result<String, Error> {
+    backend::ensure_this_process_backend()?;
     let backend = microsandbox::default_backend();
     // Shim-only entry point with no SDK `Operation` — report the Ruby-facing
     // name (`Microsandbox.runtime_path`), like Python's name-based local_only.
@@ -118,10 +122,52 @@ fn resolved_msb_path() -> Result<String, Error> {
     Ok(path.to_string_lossy().into_owned())
 }
 
+/// This process's fork generation (see `runtime::ProcessIdentity`): how many
+/// `fork`s led from the process that loaded the extension to this one. A
+/// diagnostic for the fork specs, not part of the Ruby API (nothing in
+/// `lib/` calls it, and `Native` is the extension's internal namespace).
+fn fork_generation() -> u32 {
+    runtime::ProcessIdentity::current().generation()
+}
+
+/// Whether two given identities are the same process, by the two comparisons
+/// every ownership decision uses: `PartialEq` (the runtime cell, handles,
+/// `with_backend` scopes) and the packed word (the backend record). Returns
+/// `[equal, same_bits]`. A spec-only diagnostic, like `fork_generation`:
+/// pid reuse cannot be staged on demand, so this is where the specs pin that
+/// both the pid and the generation take part. Pure: no state is read or
+/// changed.
+fn fork_identity_equal(pid_a: u32, gen_a: u32, pid_b: u32, gen_b: u32) -> (bool, bool) {
+    let a = runtime::ProcessIdentity::from_parts(pid_a, gen_a);
+    let b = runtime::ProcessIdentity::from_parts(pid_b, gen_b);
+    (a == b, a.to_bits() == b.to_bits())
+}
+
+/// Run a handle's real ownership check (`ForkGuarded::get_in`) for a handle
+/// created by the process (`born_pid`, `born_gen`) and used in (`cur_pid`,
+/// `cur_gen`): `nil` when it is allowed, the `ForkedHandleError` that `get`
+/// would raise otherwise — including the equal-pid wording. Spec-only and
+/// pure, like `fork_identity_equal`; the guard holds no payload.
+fn fork_identity_guard(
+    born_pid: u32,
+    born_gen: u32,
+    cur_pid: u32,
+    cur_gen: u32,
+) -> Result<(), Error> {
+    let born = runtime::ProcessIdentity::from_parts(born_pid, born_gen);
+    let cur = runtime::ProcessIdentity::from_parts(cur_pid, cur_gen);
+    let guard = runtime::ForkGuarded::owned_by(born, "Microsandbox::VolumeFs", ());
+    guard.get_in(cur).map(|_| ())
+}
+
 /// magnus entry point. RubyGems loads this via `require "microsandbox/microsandbox_rb"`,
 /// which calls `Init_microsandbox_rb` (matching the cdylib `[lib] name`).
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
+    // Before anything can fork: from here on every fork's child gets a fork
+    // generation one higher than its parent's (see `runtime::ProcessIdentity`).
+    runtime::register_fork_handler();
+
     let module = ruby.define_module("Microsandbox")?;
     let native = module.define_module("Native")?;
 
@@ -136,6 +182,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     )?;
     native.define_singleton_method("resolved_msb_path", function!(resolved_msb_path, 0))?;
     native.define_singleton_method("all_sandbox_metrics", function!(all_sandbox_metrics, 0))?;
+    native.define_singleton_method("fork_generation", function!(fork_generation, 0))?;
+    native.define_singleton_method("fork_identity_equal", function!(fork_identity_equal, 4))?;
+    native.define_singleton_method("fork_identity_guard", function!(fork_identity_guard, 4))?;
 
     backend::define(ruby, &native)?;
     sandbox::define(ruby, &native)?;

data/ext/microsandbox/src/runtime.rs

@@ -41,23 +41,125 @@
 
 use std::ffi::c_void;
 use std::future::Future;
+use std::mem::ManuallyDrop;
 use std::panic::{catch_unwind, AssertUnwindSafe};
 use std::sync::atomic::{AtomicPtr, AtomicU32, Ordering};
-use std::sync::Mutex;
 
 use magnus::{Error, Ruby, TypedData};
 use tokio::runtime::Runtime;
 
 use crate::error;
 
-/// The current Ruby handle. Safe to call from any bound method or value
-/// conversion: we always hold the GVL there (conversions run after `block_on`
-/// returns and re-acquires it).
+/// The current Ruby handle. Safe to call from any bound method, value
+/// conversion or error construction (`error::*`): we always hold the GVL there
+/// (both run after `block_on` returns and re-acquires it).
+///
+/// Panics when the calling thread does not hold the GVL (a `nogvl` callback, a
+/// tokio worker): `Ruby::get` checks that in release builds too, so a misplaced
+/// call fails loudly instead of touching Ruby without the lock.
 pub fn ruby() -> Ruby {
-    Ruby::get().expect("microsandbox: not on a Ruby thread")
+    Ruby::get().expect("microsandbox: not on a Ruby thread holding the GVL")
+}
+
+//--------------------------------------------------------------------------------------------------
+// Process identity
+//--------------------------------------------------------------------------------------------------
+
+/// Which process this is, for fork safety: the pid plus a fork generation.
+///
+/// Everything fork-aware in the extension — the runtime cell below, the
+/// backend record in `backend.rs`, [`ForkGuarded`] — tags what it builds with
+/// the identity of the process that built it and compares that against
+/// [`ProcessIdentity::current`] before use. Both halves are compared:
+///
+/// * The pid alone is not enough. A descendant can end up with the pid of an
+///   ancestor whose state it inherited, if the pid counter wraps onto exactly
+///   that value and no SDK call happened in between; it would then pass for
+///   that ancestor.
+/// * The generation alone is not enough either. It counts the `fork`s that
+///   ran this library's atfork child handler, and a process can be created
+///   without running it — `vfork`, a raw `clone` — in which case only the pid
+///   tells the child apart.
+///
+/// Every `fork(2)` that runs atfork handlers (which `Kernel#fork` /
+/// `Process.fork` always do: Ruby calls libc's `fork`) gives the child a
+/// generation one higher than its parent's, so parent and child differ even
+/// when their pids are equal.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct ProcessIdentity {
+    pub pid: u32,
+    generation: u32,
+}
+
+/// How many `fork`s, counted from the process that loaded the extension, led
+/// to this process. Incremented only by [`on_fork_child`], in a child, and
+/// inherited (as plain memory) by every child. 32 bits: it would take four
+/// billion nested forks in one lineage to wrap, and a wrap matters only if
+/// the pid matches as well.
+static FORK_GENERATION: AtomicU32 = AtomicU32::new(0);
+
+/// The `pthread_atfork` child handler. It runs in the new child before `fork`
+/// returns there, while the child is single-threaded, and must be
+/// async-signal-safe: one lock-free atomic add, nothing else (no allocation,
+/// no lock, no Ruby). `Relaxed` is enough: the only thread that exists to read
+/// the counter is this one, and threads started later see it through the
+/// spawn's own synchronization. The parent never changes its counter.
+extern "C" fn on_fork_child() {
+    FORK_GENERATION.fetch_add(1, Ordering::Relaxed);
+}
+
+/// Register [`on_fork_child`]. Called once, from the extension's init.
+///
+/// Ruby never unloads (`dlclose`s) an extension, so the handler's code stays
+/// mapped for the life of the process, as `pthread_atfork` requires — handlers
+/// cannot be unregistered. If registration fails (`ENOMEM`), the generation
+/// stays 0 and identity degrades to the pid alone, which is how the extension
+/// behaved before the generation existed; that is not worth refusing to load
+/// over. Platforms without `pthread_atfork` (the gem ships for macOS and
+/// Linux only) get the same pid-only identity.
+pub fn register_fork_handler() {
+    static ONCE: std::sync::Once = std::sync::Once::new();
+    ONCE.call_once(|| {
+        #[cfg(unix)]
+        // SAFETY: `on_fork_child` is an `extern "C" fn()` that stays valid for
+        // the life of the process (see above) and is async-signal-safe.
+        unsafe {
+            let _ = libc::pthread_atfork(None, None, Some(on_fork_child));
+        }
+    });
 }
 
-// The process-wide tokio runtime, guarded by the pid it was built under. A
+impl ProcessIdentity {
+    /// This process's identity. The single `std::process::id()` call site.
+    pub fn current() -> Self {
+        Self {
+            pid: std::process::id(),
+            generation: FORK_GENERATION.load(Ordering::Relaxed),
+        }
+    }
+
+    /// An identity from its two halves — ONLY for the fork-identity
+    /// diagnostics in `lib.rs`, which let the specs compare identities that no
+    /// real fork can produce on demand (an equal pid with another generation).
+    pub fn from_parts(pid: u32, generation: u32) -> Self {
+        Self { pid, generation }
+    }
+
+    /// The fork generation, for `Native.fork_generation` (a diagnostic the
+    /// fork specs read; not part of the Ruby API).
+    pub fn generation(self) -> u32 {
+        self.generation
+    }
+
+    /// Both halves in one word, for a lock-free atomic record. `0` is never a
+    /// real identity (no user process has pid 0), so it can mean "none".
+    pub fn to_bits(self) -> u64 {
+        (u64::from(self.pid) << 32) | u64::from(self.generation)
+    }
+}
+
+// The process-wide tokio runtime, tagged with the identity of the process it
+// was built under (see `ProcessIdentity`). A
 // multi-threaded runtime owns worker + I/O-driver threads, and `fork(2)` copies
 // ONLY the calling thread — so a child that inherits this runtime has a runtime
 // whose threads are gone: `block_on` can still drive the current thread, but the
@@ -65,16 +167,16 @@ pub fn ruby() -> Ruby {
 // connections stall/drop mid-use. This is hit in practice by forking job servers
 // (Solid Queue, Resque) and clustered web servers (Puma workers).
 //
-// Fix: store the runtime behind a leaked raw pointer tagged with the building
-// pid. If `runtime()` is called in a process whose pid differs (we forked), build
-// a FRESH runtime for this process and swap the pointer. The stale runtime is
-// LEAKED, never dropped — dropping a tokio runtime whose worker threads vanished
-// across fork can hang on the shutdown thread-join. One runtime is leaked per
-// process that uses the SDK (bounded; equivalent to the old set-once behavior in
-// the common no-fork case).
-static RUNTIME_PTR: AtomicPtr<Runtime> = AtomicPtr::new(std::ptr::null_mut());
-static RUNTIME_PID: AtomicU32 = AtomicU32::new(0);
-static RUNTIME_LOCK: Mutex<()> = Mutex::new(());
+// The runtime and its process identity live in ONE heap cell behind ONE atomic
+// pointer, so a reader sees either a whole cell or none: there is no window in
+// which the pointer is new and the identity old (or the reverse), and no mutex
+// that a fork could capture locked or that a panic could poison.
+struct RuntimeCell {
+    owner: ProcessIdentity,
+    rt: Runtime,
+}
+
+static RUNTIME: AtomicPtr<RuntimeCell> = AtomicPtr::new(std::ptr::null_mut());
 
 fn build_runtime() -> Runtime {
     tokio::runtime::Builder::new_multi_thread()
@@ -85,32 +187,126 @@ fn build_runtime() -> Runtime {
 }
 
 /// The multi-threaded tokio runtime for THIS process, built on first use and
-/// rebuilt after a `fork(2)` (fork-safe — see the note above).
+/// rebuilt after a `fork(2)` (see the note above).
 pub fn runtime() -> &'static Runtime {
-    let cur = std::process::id();
-    let ptr = RUNTIME_PTR.load(Ordering::Acquire);
-    if !ptr.is_null() && RUNTIME_PID.load(Ordering::Acquire) == cur {
-        // SAFETY: ptr was produced by Box::leak (valid for 'static) and matches
-        // this process's pid, so its runtime threads are live in this process.
-        return unsafe { &*ptr };
+    let cur = ProcessIdentity::current();
+    let mut observed = RUNTIME.load(Ordering::Acquire);
+    // SAFETY (every dereference below): a non-null pointer in `RUNTIME` came
+    // from `Box::into_raw` and is never freed once published, so it is valid
+    // for `'static`.
+    if let Some(cell) = unsafe { observed.as_ref() } {
+        if cell.owner == cur {
+            // Built in this process: its threads are alive here.
+            return &cell.rt;
+        }
     }
 
-    let _guard = RUNTIME_LOCK
-        .lock()
-        .expect("microsandbox: runtime lock poisoned");
-    // Re-check under the lock (another thread may have just built it).
-    let ptr = RUNTIME_PTR.load(Ordering::Acquire);
-    if !ptr.is_null() && RUNTIME_PID.load(Ordering::Acquire) == cur {
-        return unsafe { &*ptr };
+    // Slow path: no runtime yet, or the one we see was built by a parent
+    // process. Build ours and publish it with a compare-exchange.
+    let fresh = Box::into_raw(Box::new(RuntimeCell {
+        owner: cur,
+        rt: build_runtime(),
+    }));
+    loop {
+        match RUNTIME.compare_exchange(observed, fresh, Ordering::AcqRel, Ordering::Acquire) {
+            // Published. The cell we replaced (if any) belonged to a parent
+            // process and is LEAKED on purpose, never dropped: its worker
+            // threads did not survive the fork, and `Runtime`'s `Drop` joins
+            // them. One runtime is leaked per forked process that uses the
+            // SDK.
+            Ok(_) => return unsafe { &(*fresh).rt },
+            Err(winner) => {
+                if let Some(cell) = unsafe { winner.as_ref() } {
+                    if cell.owner == cur {
+                        // Another thread of THIS process won the race. Our
+                        // cell was never published and its threads are alive
+                        // here, so dropping it is safe (and joins them).
+                        drop(unsafe { Box::from_raw(fresh) });
+                        return &cell.rt;
+                    }
+                }
+                observed = winner;
+            }
+        }
     }
+}
 
-    // Build a fresh runtime for this process and publish it. The previous pointer
-    // (if any) belonged to a parent process and is intentionally leaked, not
-    // dropped (its threads are gone post-fork; Drop would block on join).
-    let rt: &'static Runtime = Box::leak(Box::new(build_runtime()));
-    RUNTIME_PTR.store(rt as *const Runtime as *mut Runtime, Ordering::Release);
-    RUNTIME_PID.store(cur, Ordering::Release);
-    rt
+/// The Rust payload of a wrapped Ruby object, bound to the process that
+/// created it.
+///
+/// A handle that crosses a `fork(2)` is useless in the child and dangerous to
+/// destroy there: it owns tasks, channels and connections of the parent's
+/// runtime, clones of the parent's backend, the parent-watchdog pipe of a
+/// sandbox. So every `#[magnus::wrap]` type keeps its payload in one of these:
+///
+/// * [`get`](Self::get) — the only way to the payload for anything that acts
+///   on it — fails with `Microsandbox::ForkedHandleError` in any process other
+///   than the one that built the value. `Deref` is deliberately not
+///   implemented: an access that skips the check should not compile.
+/// * `Drop` runs the payload's destructor only in that same process. A forked
+///   child that garbage-collects an inherited handle — at the latest when it
+///   exits: Ruby frees every `T_DATA` object in `rb_objspace_call_finalizer` —
+///   leaks it instead.
+pub struct ForkGuarded<T> {
+    owner: ProcessIdentity,
+    /// The Ruby class users know the handle by, for the error message.
+    class: &'static str,
+    inner: ManuallyDrop<T>,
+}
+
+impl<T> ForkGuarded<T> {
+    pub fn new(class: &'static str, inner: T) -> Self {
+        Self {
+            owner: ProcessIdentity::current(),
+            class,
+            inner: ManuallyDrop::new(inner),
+        }
+    }
+
+    /// A guard owned by `owner` instead of this process — ONLY for the
+    /// fork-identity diagnostic in `lib.rs`, which runs the real ownership
+    /// decision ([`get_in`](Self::get_in)) on identities given by a spec.
+    pub fn owned_by(owner: ProcessIdentity, class: &'static str, inner: T) -> Self {
+        Self {
+            owner,
+            class,
+            inner: ManuallyDrop::new(inner),
+        }
+    }
+
+    /// The payload, or `ForkedHandleError` when this is not the process that
+    /// created it.
+    pub fn get(&self) -> Result<&T, Error> {
+        self.get_in(ProcessIdentity::current())
+    }
+
+    /// [`get`](Self::get) as decided in the process identified by `cur`.
+    pub fn get_in(&self, cur: ProcessIdentity) -> Result<&T, Error> {
+        if self.owner == cur {
+            Ok(&self.inner)
+        } else {
+            Err(error::forked_handle(self.class, self.owner.pid, cur.pid))
+        }
+    }
+
+    /// The payload without the process check — ONLY for accessors that copy
+    /// plain data out of the value's own memory (a name, an id, a cached
+    /// status). Those stay readable in a forked child, which needs e.g. the
+    /// name to open its own handle. Never use this for anything that takes a
+    /// lock, touches a file descriptor, or reaches the runtime or the backend.
+    pub fn peek(&self) -> &T {
+        &self.inner
+    }
+}
+
+impl<T> Drop for ForkGuarded<T> {
+    fn drop(&mut self) {
+        if self.owner == ProcessIdentity::current() {
+            // SAFETY: dropped exactly once, here; `inner` is not used again.
+            unsafe { ManuallyDrop::drop(&mut self.inner) };
+        }
+        // Otherwise: inherited across a fork. Leak it (see the type docs).
+    }
 }
 
 /// Resolve the Ruby class of a `#[magnus::wrap]` type now, at extension load.
@@ -123,6 +319,13 @@ pub fn runtime() -> &'static Runtime {
 /// Every module's `define` calls this for each type it wraps, right after
 /// defining the class, so wrapping a value afterwards is `TypedData::class`
 /// reading a resolved static plus `rb_data_typed_object_wrap`.
+///
+/// Doing it at load also keeps that first resolution away from concurrent
+/// callers, which matters since magnus 0.9: the static is a magnus `Lazy`, an
+/// `OnceLock` whose initializer (the `const_get`) runs while holding the lock.
+/// That `funcall` can switch Ruby threads, and a second thread reaching the
+/// same lock would block on it while holding the GVL the first one needs to
+/// finish.
 pub fn preload_class<T: TypedData>(ruby: &Ruby) {
     let _ = T::class(ruby);
 }
@@ -301,10 +504,44 @@ where
 
 /// Drive a future to completion on the shared runtime with the GVL released.
 ///
-/// `Err` means the future was never polled (see [`nogvl`]); propagate it with
-/// `?` before looking at the future's own output:
+/// `Err` means the future was never polled (see [`nogvl`], and the fork check
+/// below); propagate it with `?` before looking at the future's own output:
 /// `block_on(fut)?.map_err(error::to_ruby)?`.
+///
+/// Every native call goes through this, with one deliberate exception: the
+/// runtime installer, see [`block_on_runtime_install`].
 pub fn block_on<F>(fut: F) -> Result<F::Output, Error>
+where
+    F: Future,
+{
+    // Many core operations resolve the process-wide default backend while they
+    // run. After a fork that backend is the parent's; replace it now, while we
+    // still hold the GVL (the check takes a mutex and may build a Ruby
+    // exception — neither is allowed once the GVL is released).
+    crate::backend::ensure_this_process_backend()?;
+    nogvl(|| runtime().block_on(fut))
+}
+
+/// [`block_on`] without its backend check, for the runtime installer ONLY:
+/// `Native.install` and `Native.setup` (`microsandbox::setup`).
+///
+/// The check at the top of [`block_on`] is deliberate and stays there: it is
+/// what makes every other native call safe after a fork. This entry is not a
+/// cheaper alternative to it. It exists because the installer never touches
+/// the default backend or the catalog — `Setup::install` creates the
+/// `bin`/`lib` directories, runs the installed `msb --version`, copies a CI
+/// build or downloads and unpacks the release bundle, and checks that the two
+/// files exist, all under the base directory it resolves from `MSB_HOME` —
+/// so in a forked child the check would only rebuild (and leak) a backend
+/// nothing uses, or fail the install when the inherited backend selection no
+/// longer resolves there. Skipping it leaves the backend record as it was:
+/// the child's next call that does reach the backend is the one that takes
+/// it over.
+///
+/// Before adding a caller, trace its core path and confirm it never reaches
+/// `microsandbox::default_backend()` (directly or through a `Sandbox`,
+/// `Volume`, `Image`, `Snapshot` or agent function that resolves it).
+pub fn block_on_runtime_install<F>(fut: F) -> Result<F::Output, Error>
 where
     F: Future,
 {