microsandbox-rb 0.17.1 → 0.17.3

data/docs/releasing.md

@@ -7,54 +7,105 @@ or credential setup is needed.
 
 ## Each release
 
-1. Bump the gem's **own** version — `Microsandbox::VERSION` and the matching
-   `[package] version` in `ext/microsandbox/Cargo.toml` (they must stay equal) —
-   on its independent semver track (see the
+1. Bump the gem's **own** version on its independent semver track (see the
    [Versioning](../README.md#versioning) section of the README); **don't** pick
-   the number to mirror the upstream tag. If the release also adopts a new
-   upstream runtime, bump the `tag = "vX.Y.Z"` on **all three** upstream git
-   deps (`microsandbox`, `microsandbox-network`, `microsandbox-runtime`), update
-   `Microsandbox::RUNTIME_VERSION` to match, commit the release's
-   `checksums.sha256` as `binaries/checksums/<tag>.sha256`, and add a row to the
-   Versioning table. Also bump `Microsandbox::Binaries::VERSION` (and, on a
-   runtime adoption, `::RUNTIME_VERSION`) in
-   `binaries/lib/microsandbox/binaries.rb` — the companion gem ships in
-   lockstep and the specs assert both. Update `CHANGELOG.md`.
-2. Push a `vX.Y.Z` tag. CI builds the **source gem** and pushes it to RubyGems
-   via `rubygems/configure-rubygems-credentials` (OIDC, `id-token: write`) — no
+   the number to mirror the upstream tag. The version is written in three
+   files that must stay equal (`spec/unit/version_spec.rb` asserts it), and
+   recorded in the lockfile:
+   - `lib/microsandbox/version.rb` — `Microsandbox::VERSION`;
+   - `ext/microsandbox/Cargo.toml` — the `[package] version`;
+   - `binaries/lib/microsandbox/binaries.rb` — `Microsandbox::Binaries::VERSION`
+     (the companion gem ships in lockstep);
+   - `Cargo.lock` — committed and packed into the gem, and it records the
+     extension crate's version, so a version bump must commit the regenerated
+     lock (`bundle exec rake compile` rewrites it).
+
+   If the release also adopts a new upstream runtime, move the runtime tag
+   everywhere it is named:
+   - `ext/microsandbox/Cargo.toml` — the `tag = "vX.Y.Z"` on **all three**
+     upstream git deps (`microsandbox`, `microsandbox-network`,
+     `microsandbox-runtime`);
+   - `lib/microsandbox/version.rb` — `Microsandbox::RUNTIME_VERSION`;
+   - `binaries/lib/microsandbox/binaries.rb` —
+     `Microsandbox::Binaries::RUNTIME_VERSION`;
+   - `binaries/checksums/<tag>.sha256` — the release's `checksums.sha256`,
+     committed (vendoring fails closed without it);
+   - `Cargo.lock` — regenerated again, since it pins the git deps to the new
+     tag's commit.
+
+   Then add a row to the Versioning table in the README and update
+   `CHANGELOG.md`.
+2. Push a `vX.Y.Z` tag. Once the [release preflight](#release-preflight)
+   passes, CI pushes the **source gem** to RubyGems via
+   `rubygems/configure-rubygems-credentials` (OIDC, `id-token: write`) — no
    `RUBYGEMS_API_KEY` secret required — then creates the GitHub Release.
 
+## Release preflight
+
+`release.yml`'s `preflight` job runs `.github/scripts/release_preflight.sh
+<tag>` and the `publish` job needs it, so nothing reaches RubyGems unless:
+
+- the tag is `vX.Y.Z` and the three version constants **in the tagged commit**
+  — `Microsandbox::VERSION`, `[package] version` in
+  `ext/microsandbox/Cargo.toml`, `Microsandbox::Binaries::VERSION` — all equal
+  `X.Y.Z`;
+- the tagged commit is on `main`;
+- the `CI` workflow's push run for that exact commit concluded `success`.
+
+Pushing `main` and the tag together is fine: the preflight **waits** for that
+CI run to appear and finish (polling every 30 s, up to 45 min —
+`PREFLIGHT_CI_WAIT_SECONDS` / `PREFLIGHT_CI_POLL_SECONDS`), so a release
+publishes only after CI, including the real-microVM integration lanes, is
+green. A failed or timed-out preflight leaves the tag unpublished. How to
+recover depends on whether the tag has to move:
+
+- **The tagged commit is right** (CI flaked, or was still red): re-run the
+  `CI` run for that commit until it is green, then re-run the failed `Release`
+  run.
+- **The tag must point at a different commit** (wrong version constants, not
+  on `main`): delete the tag, fix the commit, and push the tag again — that
+  starts a new `Release` run. Never re-run the old run after retagging: a
+  re-run keeps the commit it was started for, so it checks the old commit
+  again and fails the same way.
+
+Dry-run it against an existing tag — nothing is published on a manual
+dispatch — or run the script locally from a full clone:
+
+```bash
+gh workflow run release.yml --ref main -f preflight_ref=vX.Y.Z
+GH_TOKEN=$(gh auth token) .github/scripts/release_preflight.sh vX.Y.Z
+```
+
+It is a workflow-level gate; branch protection and a protected environment for
+the trusted publisher are separate repository settings.
+
+CI's `lint` job also runs `cargo deny check advisories` against `Cargo.lock`;
+the exceptions (advisories with no fixed release at the pinned runtime) are in
+`deny.toml` at the repository root — re-check them on every runtime adoption.
+
 ## Precompiled per-platform gems
 
-Precompiled *extension* gems are built best-effort by the `cross-gems` job,
-gated to manual `workflow_dispatch` so you can iterate
-(`gh workflow run release.yml`) without failing tag releases. They are not
-auto-published on tags yet: a gem that *compiles but can't boot a microVM*
-would be served to users ahead of the source gem, and CI can't boot a VM to
-prove otherwise — so promotion is manual after validating the artifact on each
-platform. A precompiled gem ships the compiled extension (with the guest
-`agentd` baked in by *target* arch); the host-side `msb` + `libkrunfw` runtime
-is **not** in it — that comes from the companion `microsandbox-rb-binaries`
-gem, or, when that isn't installed, is fetched into `~/.microsandbox` on first
-use by `Microsandbox.ensure_runtime!` (libkrunfw is `dlopen`'d by `msb` at
-runtime, never linked into the gem). The real cross-compile work is linking the
-*target* native libraries — `libcap-ng` on Linux (handled via Debian multiarch
-in the workflow) and the Hypervisor + Security frameworks on macOS (via
-osxcross; the one platform left to confirm). Until promoted, users install the
-source gem (which compiles via `rb_sys`).
+Precompiled *extension* gems are not built or published. Users install the
+source gem, which compiles the extension via `rb_sys` at install time (so a
+stable Rust toolchain is required on the installing host). The companion
+`microsandbox-rb-binaries` gems below are unaffected: they carry the host
+runtime, not the extension.
 
 ## Runtime binaries gems
 
 `microsandbox-rb-binaries` (source in `binaries/`) is a *separate* artifact from
-the precompiled extension gems above: it carries no Ruby extension, only the
+the SDK gem: it carries no Ruby extension, only the
 upstream `msb` + `libkrunfw` for one platform, verified against the release's
 published `checksums.sha256` when vendored. CI's `binaries` job vendors and
 builds all three (`arm64-darwin`, `x86_64-linux-gnu`, `aarch64-linux-gnu`) on
 every run and smoke-tests the host one; `release.yml`'s `binaries-gems` job
 does the same on a tag and a separate `publish-binaries` job pushes them after
-the SDK gem is live (a companion failure is its own red job and never blocks
-the SDK release). They use their own RubyGems trusted-publisher entry (same
-repo + workflow, gem name `microsandbox-rb-binaries`). To build them by hand:
+the SDK gem is live. The SDK `publish` job needs `binaries-gems`, so a
+companion **build** failure blocks the SDK publish as well. A companion
+**push** failure is its own red job once the SDK gem is live: the release is
+then incomplete until `publish-binaries` is re-run. They use their own RubyGems
+trusted-publisher entry (same repo + workflow, gem name
+`microsandbox-rb-binaries`). To build them by hand:
 
 ```bash
 rake -C binaries vendor[arm64-darwin]   # download + sha256-verify into binaries/vendor

data/docs/runtime.md

@@ -85,7 +85,9 @@ Microsandbox.set_default_backend(:cloud, url: "https://api.example.com", api_key
 Microsandbox.set_default_backend(:cloud, profile: "prod")
 
 # Scoped override (restored afterward, even on error):
-Microsandbox.with_backend(:local) { Microsandbox::Sandbox.create("box", image: "alpine") { |sb| ... } }
+Microsandbox.with_backend(:local) do
+  Microsandbox::Sandbox.create("box", image: "alpine") { |sb| puts sb.shell("uname -a").stdout }
+end
 ```
 
 Resolution order when no backend is set programmatically: `MSB_BACKEND`
@@ -102,6 +104,91 @@ operations (create/start/stop/remove/get/list, one-shot exec, follow log
 streaming); unsupported operations raise `Microsandbox::UnsupportedError`
 (with `#operation` and `#hint`).
 
+## Forking (Puma, Resque, Solid Queue)
+
+Forking a process that has already used the SDK is supported: preload the
+application, use the SDK in the master, fork workers, use it in the workers.
+The first SDK call in a child sets up its own runtime threads and its own
+backend (a new catalog connection pool, or a new HTTP client for the cloud
+backend), chosen the same way as the parent's: an explicit
+`set_default_backend`, an enclosing `with_backend` block, or — when neither
+was used — the environment and config file as the child sees them at that
+call. Everything addressed by name works in the child from then on:
+`Sandbox.create`/`get`/`list`/`start`, `Volume`, `Image`, `Snapshot`.
+
+If the parent's choice cannot be made again in the child (say the child's
+environment now selects the cloud backend without credentials), SDK calls
+there raise the configuration error until that is repaired. Selecting a
+backend in the child — `set_default_backend`, or entering `with_backend` —
+does not depend on the inherited choice and works regardless.
+
+```ruby
+Microsandbox::Sandbox.list             # the parent has used the SDK
+
+pid = fork do
+  Microsandbox::Sandbox.create("job-#{Process.pid}", image: "alpine") do |sb|
+    puts sb.exec("echo", ["hello from the worker"]).stdout
+  end
+end
+Process.wait(pid)
+```
+
+What does **not** cross a fork is an object created before it. A `Sandbox`,
+`SandboxHandle`, `ExecHandle`, `ExecStdin`, `PullSession`, log/metrics/file
+stream, `SshClient`/`SftpClient`/`SshServer`, `AgentClient` or `VolumeFs`
+belongs to the process that created it. In a forked child, any call that acts
+on one raises `Microsandbox::ForkedHandleError` (the message names both
+pids); the original keeps working in the parent. Reading `name` or `id` — and
+the snapshot fields of a `SandboxHandle` — still works, so a child can open
+its own handle:
+
+```ruby
+sandbox = Microsandbox::Sandbox.create("shared", image: "alpine")
+
+pid = fork do
+  begin
+    sandbox.exec("true")                 # the parent's handle
+  rescue Microsandbox::ForkedHandleError => e
+    warn e.message
+  end
+  mine = Microsandbox::Sandbox.get(sandbox.name).connect_or_start
+  puts mine.exec("echo", ["hello"]).stdout
+end
+Process.wait(pid)
+sandbox.stop
+```
+
+Things to know:
+
+- **Cleanup code inherited by the child.** The block forms
+  (`Sandbox.create(...) { }`, `connect_or_create`) swallow the
+  `ForkedHandleError` their teardown hits when a forked child leaves the
+  block, so the child does not stop the parent's sandbox. An `ensure
+  sandbox.stop` of your own raises it in the child; rescue it there, or run
+  the cleanup only in the process that created the sandbox.
+- **Leaving a `with_backend` block in the child.** When the backend to
+  restore was the parent's — the child was forked inside the block, or the
+  block is the child's first use of the SDK — leaving the block installs a
+  backend chosen the way that one had been. The block's own temporary backend
+  is not needed for that: if only it can no longer be chosen in the child (a
+  cloud profile that is gone there), leaving the block still restores the
+  previous backend. If the choice to restore no longer resolves in the child,
+  the block is closed anyway and its temporary selection stays in effect.
+  `with_backend` then raises the configuration error — unless the block
+  itself raised, in which case the block's exception propagates and the
+  restore failure is reported as a warning.
+- **A child keeps the parent's sandboxes alive.** A child inherits the
+  parent's open file descriptors, among them the pipe through which a sandbox
+  notices that its owner is gone. If the parent exits while such a child is
+  still running, the sandbox is not torn down until that child exits as well.
+  Fork before creating sandboxes, or create them in the children.
+- **Do not fork while another thread is inside an SDK call.** That thread
+  does not exist in the child, and a lock it held at that instant stays
+  locked there.
+- **Memory.** A child leaks, once, the native state it inherited (the
+  parent's runtime, backend and whichever inherited handles it collects)
+  instead of destroying it — destroying it is what used to crash.
+
 ## One runtime line per home
 
 The runtime home (`MSB_HOME`, default `~/.microsandbox`) belongs to one

data/docs/surface.md

@@ -23,8 +23,10 @@ counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
   `write_stream`.
 - **Observability** — per-sandbox `metrics`, `Microsandbox.all_sandbox_metrics`,
   streaming `metrics_stream`/`log_stream`, `logs`, `ping`/`touch`.
-- **Live modification** — `modify` with `dry_run:`, `policy:`, CPU/memory
-  resize, root-disk growth, env/labels/workdir, secret rotation.
+- **Live modification** — `modify` with `dry_run:` and `policy:`: CPU/memory
+  resize (`cpus`/`max_cpus`/`memory`/`max_memory`), root-disk growth
+  (`root_disk_size`, MiB), `env`/`remove_env`, `labels`/`remove_labels`,
+  `workdir`, and secret rotation (`secrets`/`remove_secrets`).
 - **OCI image cache** — `Image.get`/`list`/`inspect`/`remove`/`prune`, image
   archives (`Image.load`/`Image.save`), streaming pull progress
   (`Sandbox.create_with_progress` → `PullSession`).
@@ -35,14 +37,16 @@ counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
 - **Rootfs patches** — `Microsandbox::Patch` (text/file/append/copy_file/
   copy_dir/symlink/mkdir/remove) via `create(patches:)`.
 - **Root disk** — structured `root_disk:` (managed / tmpfs / disk / flat via
-  `Microsandbox::RootDisk`), `follow_root_symlinks:`.
+  `Microsandbox::RootDisk`), `follow_root_symlinks:`; `oci_upper_size:` is the
+  deprecated alias for a managed `root_disk:` size.
 - **Network configuration** — composable profiles, custom per-rule
-  `Microsandbox::NetworkPolicy`/`Rule`/`Destination`, DNS, TLS interception,
-  IPv4/IPv6 pools, `max_connections`, `trust_host_cas`, `strict` hostname mode,
+  `Microsandbox::NetworkPolicy`/`Rule`/`Destination`, custom DNS (`dns:`),
+  TLS-interception tuning (`tls:`), guest address pools (`ipv4_pool:`/
+  `ipv6_pool:`), `max_connections`, `trust_host_cas`, `strict` hostname mode,
   outbound SOCKS4/SOCKS5 `proxy:` (`OutboundProxy`/`SecretSource`),
   `rate_limiter:`, `vsock:`.
 - **Secrets** — multi-host / wildcard allow-lists, injection toggles,
-  per-secret and sandbox-level violation policy.
+  per-secret `on_violation:` and sandbox-level `on_secret_violation:` policy.
 - **SSH** — `Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`, with
   `inactivity_timeout:`.
 - **Raw agent client** — `Microsandbox::AgentClient` → `AgentStream`/
@@ -53,11 +57,15 @@ counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
 - **Registries** — `registry_auth`/`registry_insecure`/`registry_ca_certs` on
   `create`.
 - **Errors** — the typed hierarchy in [errors.md](errors.md).
+- **Process model** — the SDK may be used before and after `fork`; objects
+  created before a fork are refused in the child with `ForkedHandleError`
+  (see [runtime.md](runtime.md#forking-puma-resque-solid-queue)).
 
 Create options span resources (`cpus`/`memory`/`max_cpus`/`max_memory`),
-`env`/`workdir`/`labels`/`user`/`hostname`/`shell`, `init`/`ephemeral`,
+`env`/`workdir`/`labels`/`user`/`hostname`/`shell`, named `scripts`, the image
+`entrypoint`/`cmd` overrides, `init`/`ephemeral`,
 disk-image `fstype`, `ports`/`ports_udp`, network policy + config,
-`log_level`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches`/`volumes`
+`log_level`/`quiet_logs`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches`/`volumes`
 (bind/named/tmpfs/disk with mount policies, `uid`/`gid`, `quota_mib`),
 `idle_timeout`/`max_duration`, `from_snapshot`, `detached`, and
 `replace`/`replace_with_timeout`.

data/ext/microsandbox/Cargo.toml

@@ -6,8 +6,9 @@ name = "microsandbox_rb"
 description = "Ruby SDK native extension for microsandbox — secure, fast microVM-based sandboxing."
 # Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
-# The core-crate dependency below stays pinned at its own tag (v0.6.16).
-version = "0.17.1"
+# The core-crate dependencies below stay on their own tag, which is
+# Microsandbox::RUNTIME_VERSION and moves independently of this version.
+version = "0.17.3"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -22,9 +23,12 @@ name = "microsandbox_rb"
 crate-type = ["cdylib"]
 
 [dependencies]
-magnus = "0.8"
-# Low-level Ruby C API — used directly for rb_thread_call_without_gvl (GVL release
-# during blocking sandbox calls). Kept in lock-step with magnus's own rb-sys.
+# "rb-sys" exposes `magnus::rb_sys::protect` (rb_protect), which the GVL bridge
+# uses to check interrupts without letting Ruby longjmp over Rust frames.
+magnus = { version = "0.8", features = ["rb-sys"] }
+# Low-level Ruby C API — used directly for rb_thread_call_without_gvl2 (GVL
+# release during blocking sandbox calls) and rb_thread_check_ints. Kept in
+# lock-step with magnus's own rb-sys.
 rb-sys = "0.9"
 
 # The microsandbox core runtime, wrapped via FFI exactly like the official

data/ext/microsandbox/src/agent.rs

@@ -14,7 +14,7 @@ use microsandbox::agent::AgentClient as CoreAgentClient;
 use microsandbox::{AgentBridge, BridgeFrame, MicrosandboxError};
 
 use crate::error;
-use crate::runtime::{block_on, ruby};
+use crate::runtime::{block_on, ruby, ForkGuarded};
 
 /// Map an agent-client error onto the Ruby exception hierarchy (via the core
 /// `MicrosandboxError::AgentClient` wrapper, exactly like the Python binding).
@@ -24,13 +24,13 @@ fn to_ruby_agent(err: microsandbox::AgentClientError) -> Error {
 
 #[magnus::wrap(class = "Microsandbox::Native::AgentClient", free_immediately, size)]
 pub struct AgentClient {
-    inner: Arc<AgentBridge>,
+    inner: ForkGuarded<Arc<AgentBridge>>,
 }
 
 impl AgentClient {
     fn from_bridge(bridge: AgentBridge) -> Self {
         Self {
-            inner: Arc::new(bridge),
+            inner: ForkGuarded::new("Microsandbox::AgentClient", Arc::new(bridge)),
         }
     }
 
@@ -41,8 +41,8 @@ impl AgentClient {
     /// Connect to a running sandbox by name. `timeout` is optional seconds.
     fn connect_sandbox(name: String, timeout: Option<f64>) -> Result<AgentClient, Error> {
         let bridge = match dur(timeout)? {
-            Some(t) => block_on(AgentBridge::connect_sandbox_with_timeout(&name, t)),
-            None => block_on(AgentBridge::connect_sandbox(&name)),
+            Some(t) => block_on(AgentBridge::connect_sandbox_with_timeout(&name, t))?,
+            None => block_on(AgentBridge::connect_sandbox(&name))?,
         }
         .map_err(to_ruby_agent)?;
         Ok(AgentClient::from_bridge(bridge))
@@ -51,8 +51,8 @@ impl AgentClient {
     /// Connect to an agentd relay socket by path. `timeout` is optional seconds.
     fn connect_path(path: String, timeout: Option<f64>) -> Result<AgentClient, Error> {
         let bridge = match dur(timeout)? {
-            Some(t) => block_on(AgentBridge::connect_path_with_timeout(&path, t)),
-            None => block_on(AgentBridge::connect_path(&path)),
+            Some(t) => block_on(AgentBridge::connect_path_with_timeout(&path, t))?,
+            None => block_on(AgentBridge::connect_path(&path))?,
         }
         .map_err(to_ruby_agent)?;
         Ok(AgentClient::from_bridge(bridge))
@@ -60,6 +60,9 @@ impl AgentClient {
 
     /// Resolve a sandbox's agent relay socket path without connecting.
     fn socket_path(name: String) -> Result<String, Error> {
+        // Synchronous, and the core derives the path from the default
+        // backend's config.
+        crate::backend::ensure_this_process_backend()?;
         let path = CoreAgentClient::socket_path(&name).map_err(error::to_ruby)?;
         Ok(path.to_string_lossy().into_owned())
     }
@@ -71,18 +74,18 @@ impl AgentClient {
     /// Send one frame and await a single response frame ({id, flags, body}).
     fn request(&self, flags: u8, body: RString) -> Result<RHash, Error> {
         let body = unsafe { body.as_slice() }.to_vec();
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let frame =
-            block_on(async move { inner.request(flags, body).await }).map_err(to_ruby_agent)?;
+            block_on(async move { inner.request(flags, body).await })?.map_err(to_ruby_agent)?;
         Ok(frame_to_hash(frame))
     }
 
     /// Open a streaming session; returns {id, handle}.
     fn stream_open(&self, flags: u8, body: RString) -> Result<RHash, Error> {
         let body = unsafe { body.as_slice() }.to_vec();
-        let inner = Arc::clone(&self.inner);
-        let (id, handle) =
-            block_on(async move { inner.stream_open(flags, body).await }).map_err(to_ruby_agent)?;
+        let inner = Arc::clone(self.inner.get()?);
+        let (id, handle) = block_on(async move { inner.stream_open(flags, body).await })?
+            .map_err(to_ruby_agent)?;
         let hash = ruby().hash_new();
         hash.aset("id", id)?;
         hash.aset("handle", handle)?;
@@ -91,36 +94,36 @@ impl AgentClient {
 
     /// Pull the next frame from a stream; nil at end-of-stream.
     fn stream_next(&self, handle: u64) -> Result<Option<RHash>, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let frame =
-            block_on(async move { inner.stream_next(handle).await }).map_err(to_ruby_agent)?;
+            block_on(async move { inner.stream_next(handle).await })?.map_err(to_ruby_agent)?;
         Ok(frame.map(frame_to_hash))
     }
 
     /// Close a stream handle. Idempotent.
     fn stream_close(&self, handle: u64) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
-        block_on(async move { inner.stream_close(handle).await });
+        let inner = Arc::clone(self.inner.get()?);
+        block_on(async move { inner.stream_close(handle).await })?;
         Ok(())
     }
 
     /// Send a follow-up frame on an existing correlation id.
     fn send(&self, id: u32, flags: u8, body: RString) -> Result<(), Error> {
         let body = unsafe { body.as_slice() }.to_vec();
-        let inner = Arc::clone(&self.inner);
-        block_on(async move { inner.send(id, flags, body).await }).map_err(to_ruby_agent)
+        let inner = Arc::clone(self.inner.get()?);
+        block_on(async move { inner.send(id, flags, body).await })?.map_err(to_ruby_agent)
     }
 
     /// Cached handshake `core.ready` frame body bytes (CBOR).
     fn ready_bytes(&self) -> Result<RString, Error> {
-        let bytes = self.inner.ready_bytes().map_err(to_ruby_agent)?;
+        let bytes = self.inner.get()?.ready_bytes().map_err(to_ruby_agent)?;
         Ok(ruby().str_from_slice(&bytes))
     }
 
     /// Close the connection. Idempotent.
     fn close(&self) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
-        block_on(async move { inner.close().await });
+        let inner = Arc::clone(self.inner.get()?);
+        block_on(async move { inner.close().await })?;
         Ok(())
     }
 }
@@ -157,6 +160,8 @@ fn frame_to_hash(frame: BridgeFrame) -> RHash {
 
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let class = native.define_class("AgentClient", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<AgentClient>(ruby);
 
     class.define_singleton_method(
         "connect_sandbox",