microsandbox-rb 0.17.1 → 0.17.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fbc8d09d8029bef1ec00d128bf554b037c937e51ebe8b9b8a6014043fce178e
-  data.tar.gz: 626313c0471102e108793f3880bcd1f1e30ba9f48470274bf53495a86cfadff7
+  metadata.gz: f76670a6753a6503a0764ed173db3c33a1eff9a62de7a7d9343bc76f8143c1ba
+  data.tar.gz: 80d4d4f1c2bbb3f47dd8f714602e6b01a841d62971b70b5682d3ad0c7dcff904
 SHA512:
-  metadata.gz: 49461a4a9ca44f5af82d62fe30086bd4b153d3885267274fce7de8328b071cb418055f202b3b2feea3f149d76572a2a78874596c707ac094d62f7cc5171269aa
-  data.tar.gz: 929b0a19b88eb839d371899191e6a0229eded4eb616100dbd8d316352eac3bf68dcfefa91fb04c4ce41ad540deaa41233c1533d2471222bbf4772d8708451be6
+  metadata.gz: 74429f29417c1b2c2e6aeee35948d3c5201d5ac9d001beba4efceca484dbea53f0041e84f0f7fa0fef5933a89f3e317737fb134d6329267eb5e239fe56d7e297
+  data.tar.gz: d4d5072d1a68079a8bfe199e8c53e0d92e7614515e1326e81333f857c1b53b681575f8df2162abb167ea6228841ffba2631f4d2b8df38552040c946966223c2c

data/CHANGELOG.md

@@ -8,6 +8,81 @@ wraps, and the README's Versioning section keeps the full gem→runtime map.
 
 ## [Unreleased]
 
+## [0.17.2] - 2026-10-12
+
+Gem-only fix and release-pipeline hardening release; the embedded runtime
+stays at **`v0.6.18`**. One behaviour change is visible: under
+`Thread.handle_interrupt(X => :on_blocking)` a native call now raises an
+already-deferred exception before it starts instead of after it finishes,
+except in the four sandbox-acquisition methods, which deliver it after the
+acquisition (see the first Fixed entry).
+
+### Added
+
+- Two contract specs keep the hand-maintained parts honest:
+  `spec/unit/rbs_contract_spec.rb` compares `sig/microsandbox.rbs` with the
+  loaded gem, and `spec/unit/docs_contract_spec.rb` checks the docs against
+  the code (version table, CHANGELOG links, error table, option list,
+  examples, release checklist). CI also runs `rbs -I sig validate`.
+
+### Changed
+
+- **Release pipeline hardened** (no change to the gem's code or API). A tag
+  now publishes only after a preflight passes — the tag equals the three
+  version constants, its commit is on `main`, and CI is green for that exact
+  commit — and after the companion `microsandbox-rb-binaries` gems have built
+  (a companion build failure now blocks the SDK publish; a companion push
+  failure still needs a re-run of `publish-binaries`). The published gem is built
+  with plain `gem build`, every workflow action is pinned to a commit SHA
+  (kept current by Dependabot), and CI checks `Cargo.lock` against the RustSec
+  advisory database with `cargo deny`. See [docs/releasing.md](docs/releasing.md).
+- **The precompiled-extension release job is removed.** The manual-dispatch
+  `cross-gems` job never produced a gem. Precompiled extension gems are not
+  built or published; every platform installs the source gem (compiled via
+  `rb_sys`), exactly as before. The `microsandbox-rb-binaries` gems are
+  unaffected.
+
+### Fixed
+
+- **An interrupted call no longer leaks what it produced.** A `Timeout.timeout`
+  (or any `Thread#raise`), a `Thread#kill` or a Ctrl-C that arrived while a
+  native call was in flight used to discard the call's result without
+  releasing it: `Timeout.timeout { Sandbox.create(...) }` raised
+  `Timeout::Error` and left the sandbox running with no Ruby object owning it
+  until the process exited, an interrupted `exec_stream` left its guest
+  session open with nothing able to kill it, and an interrupted `exec` kept
+  its collected output in memory. The result now always reaches Ruby, and
+  what happens to it depends on the interrupt:
+  - **`Timeout`/`Thread#raise` and `Thread#kill`** during `Sandbox.create`,
+    `Sandbox.connect_or_create`, `Sandbox.start` or `PullSession#sandbox`: the
+    sandbox is stopped before the exception propagates — only one the call
+    owns; a sandbox `connect_or_create` merely connected to is left running.
+    The stop is best-effort: if it fails, the interrupt is still what you
+    see, and the sandbox is torn down when its object is garbage-collected.
+  - **Ctrl-C (`SIGINT`)** during those four, and **any interrupt** during
+    every other call (`exec_stream`, streams, SSH clients, …): nothing is
+    stopped at once; the result is released — and a sandbox torn down — when
+    its unreferenced object is garbage-collected.
+
+  Native calls are still uninterruptible, so the exception is raised once the
+  call has finished, and in the first case only after the cleanup stop as well
+  (a timed-out create therefore returns later than before). One visible
+  difference for `Thread.handle_interrupt(X => :on_blocking)`: a native call
+  now raises an exception that is already deferred *before* it starts, where
+  it used to raise it after finishing. The four acquisition methods above are
+  the exception — they hold every queued interrupt back until the sandbox is
+  in the caller's hands, so there a deferred exception is delivered after the
+  acquisition (at the thread's next blocking operation), not before it.
+- **RBS: `Klass.new` now type-checks with its real arguments.** 24 classes
+  whose constructor takes arguments had no `initialize` declaration, so RBS
+  synthesized a zero-argument `new` for them.
+- **Docs:** `docs/surface.md` now lists every `create`/`modify` keyword;
+  `DESIGN.md` no longer names a runtime tag the gem stopped pinning long ago;
+  the `with_backend` example in `docs/runtime.md` is valid Ruby. `0.9.3`
+  (never tagged or published) is folded into `0.10.0`, both in this file and
+  in the README's Versioning table, and this file now defines the compare
+  links for `0.9.1`–`0.13.0`.
+
 ## [0.17.1] - 2026-10-12
 
 Gem-only security and hardening release; the embedded runtime stays at
@@ -659,8 +734,10 @@ could make a later CLI copy-out overwrite an arbitrary host file — the SDK
 
 Ruby bindings for the additive `v0.6.6` SDK surface (upstream #1099 / #1128),
 bringing the gem to parity with the Python and Node SDKs, which already ship
-this API. The embedded runtime tag is unchanged (`v0.6.6`); this is a pure
-binding addition with no breaking change.
+this API. This release also adopts the upstream runtime **`v0.6.3` →
+`v0.6.6`**: that work was prepared as `0.9.3`, which was never tagged or
+published, so the runtime bump and the bindings for its new surface first
+shipped together here. Neither part is a breaking change.
 
 ### Added
 
@@ -693,16 +770,18 @@ Deliberately **not** exposed, matching the Python and Node SDKs (both surface
 these only through the CLI): `modify`'s `oci_upper_size` overlay-grow field, and
 the `SandboxMetricsReport` / per-sandbox metrics-report helpers.
 
-## [0.9.3] - 2026-07-09
+### Runtime adoption v0.6.3 → v0.6.6 (prepared as 0.9.3, first released in 0.10.0)
+
+`0.9.3` was never tagged or published; everything below shipped in `0.10.0`.
 
 Adopts upstream runtime **`v0.6.3` → `v0.6.6`** (spanning upstream `v0.6.4` and
 `v0.6.6`; `v0.6.5` was yanked upstream — its GitHub release was pulled and the
 type-model refactor it shipped, #1014, was reverted in `v0.6.6`, #1143). The
 upstream SDK crate's public API grew only *additive* surface (live
-modify/resize, ping/touch — Ruby bindings for these land in the next minor),
-so this is a pure runtime bump with no Ruby API change.
+modify/resize, ping/touch). The Ruby bindings for it are the `### Added`
+entries above.
 
-### Fixed
+#### Fixed
 
 - **Snapshot restore survives upstream tag republishes** (upstream #1130):
   restore now pulls the OCI image by its pinned manifest digest
@@ -722,7 +801,7 @@ so this is a pure runtime bump with no Ruby API change.
 - **Filesystem snapshot `readdir` streams entries** (upstream #1133), fixing
   unbounded memory growth (RSS leak) when listing very large directories.
 
-### Changed
+#### Changed
 
 - **Embedded runtime is now `v0.6.6`** (`Microsandbox::RUNTIME_VERSION` /
   `Microsandbox.runtime_version`). Also inherited:
@@ -1391,12 +1470,19 @@ microsandbox runtime, aligned with the official Python/Node/Go SDKs.
   core crate has Apple-native deps). Until precompiled gems are published,
   installing from source requires a Rust toolchain (stable >= 1.91).
 
-[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.1...HEAD
+[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.2...HEAD
+[0.17.2]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.1...v0.17.2
 [0.17.1]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.0...v0.17.1
 [0.17.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.9.2...v0.10.0
+[0.9.2]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.9.1...v0.9.2
+[0.9.1]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.8.2...v0.9.0
 [0.8.2]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.8.0...v0.8.1

data/Cargo.lock

@@ -3660,7 +3660,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.17.1"
+version = "0.17.2"
 dependencies = [
  "chrono",
  "futures",

data/DESIGN.md

@@ -50,7 +50,7 @@ multi-threaded tokio runtime via `runtime.block_on(fut)`.
 
 ### GVL release
 
-`block_on` is wrapped in `nogvl` (`rb_thread_call_without_gvl`) so the Ruby
+`block_on` is wrapped in `nogvl` (`rb_thread_call_without_gvl2`) so the Ruby
 Global VM Lock is **released** while a sandbox operation is in flight. Without
 this, a long-running `exec` would freeze every other Ruby thread/fiber in the
 process (a real problem under Rails/Puma). The `nogvl` closure runs pure Rust
@@ -59,21 +59,81 @@ captured and re-raised *after* the GVL is re-acquired rather than unwinding
 across the C frame (which would be UB).
 
 **The *calling* thread is not preemptible during the call.** `nogvl` passes a
-null unblock-function to `rb_thread_call_without_gvl`, and Ruby only checks
-pending interrupts *before* and *after* the GVL-released region — so while a
-native call blocks, the thread that issued it cannot be interrupted:
-`Timeout::timeout` (which relies on `Thread#raise`), `Thread#kill`, and `SIGINT`
-(Ctrl-C) are all deferred until the call returns on its own. The GVL release
-keeps *other* threads live; it does **not** make the calling thread
-cancelable. This is harmless for the bounded calls (`exec`/`shell` with a
-`timeout:`, `AgentClient` with a `timeout:`) because the deadline fires inside
-the future, but the unbounded/streaming paths — `exec`/`shell` with
-`timeout: nil`, `ExecHandle#recv`/`#wait`, `log_stream`/`metrics_stream` `recv`
-(especially `follow: true`), `Sandbox#wait`/`SandboxHandle#wait_until_stopped`,
-and `AgentClient#request` with no timeout — can block their caller indefinitely
-if the guest wedges or a relay drops. **Bound such calls with the explicit
-`timeout:` knobs rather than wrapping them in `Timeout::timeout`**, which will
-not fire while the native call is in flight.
+null unblock-function, so while a native call blocks, the thread that issued it
+cannot be interrupted: `Timeout::timeout` (which relies on `Thread#raise`),
+`Thread#kill`, and `SIGINT` (Ctrl-C) are all deferred until the call returns on
+its own. The GVL release keeps *other* threads live; it does **not** make the
+calling thread cancelable. This is harmless for the bounded calls
+(`exec`/`shell` with a `timeout:`, `AgentClient` with a `timeout:`) because the
+deadline fires inside the future, but the unbounded/streaming paths —
+`exec`/`shell` with `timeout: nil`, `ExecHandle#recv`/`#wait`,
+`log_stream`/`metrics_stream` `recv` (especially `follow: true`),
+`Sandbox#wait`/`SandboxHandle#wait_until_stopped`, and `AgentClient#request`
+with no timeout — can block their caller indefinitely if the guest wedges or a
+relay drops. **Bound such calls with the explicit `timeout:` knobs rather than
+wrapping them in `Timeout::timeout`**, which will not fire while the native
+call is in flight.
+
+### Interrupts never lose a result
+
+An interrupt that arrives during a native call is delivered **after the call
+returns**, and the call's result is not lost. Ruby delivers `Thread#raise`,
+`Thread#kill` and `SIGINT` with a `longjmp`, which skips Rust frames without
+running destructors; if that happened while the value a call had just produced
+(a booted sandbox, a guest exec session, megabytes of output) lived only in a
+Rust frame, it would be neither returned to Ruby nor dropped. The plain
+`rb_thread_call_without_gvl` does exactly that — it checks interrupts once more
+after the callback, before returning — which is why it is not used. Two rules
+in `runtime.rs` replace it:
+
+1. `nogvl` checks interrupts itself, under `rb_protect`, **only before the work
+   starts**: once up front, and again whenever `rb_thread_call_without_gvl2`
+   declined to run the callback because an interrupt was pending at entry. A
+   raise or kill there is an ordinary `Err` that unwinds the Rust frames
+   normally — nothing has happened yet. After the callback has run, nothing is
+   checked. (`nogvl` and `block_on` therefore return `Result`, and every call
+   site propagates it with `?`. A bound method that needs two awaits does both
+   in one `block_on`, so no value sits between two entry checks.)
+2. Between `block_on` returning and the bound method returning its value, the
+   binding does not call into Ruby: no `funcall` (the VM checks interrupts
+   after every one), only C-level Hash/Array/String construction and
+   `TypedData` wrapping. The class lookup magnus would otherwise do with
+   `const_get` on a type's first wrap is resolved at extension load instead.
+
+So the next interrupt checkpoint after a native call is the Ruby VM's own,
+reached once the result is a Ruby object. What happens to it then:
+
+- **`Sandbox.create`, `Sandbox.connect_or_create`, `Sandbox.start`, and
+  `PullSession#sandbox`** mask interrupts (`Thread.handle_interrupt(Object =>
+  :never)`) around the native call plus the wrap, and an `ensure` **stops the
+  sandbox** when an exception or a kill cuts in before the caller has the
+  object — but only a sandbox the call owns (`Sandbox#owns_lifecycle?`, the
+  same predicate as `connect_or_create`'s block form): one that was already
+  running for someone else is left running. A `SIGINT` cannot be masked this
+  way; it can arrive before the wrapper is assigned, and then the next case
+  applies.
+- **Every other wrapper** (`ExecHandle`, streams, SSH clients, write sinks, …)
+  and every plain result simply becomes garbage; GC frees the wrapper and the
+  Rust value's `Drop` closes the session or connection.
+
+The calls themselves remain uninterruptible, so `Timeout.timeout { Sandbox.create(...) }`
+still waits for the create to finish — and now also for the stop that cleans
+it up — before `Timeout::Error` surfaces. That stop is best-effort (a failure
+is swallowed so the interrupt is what the caller sees; GC then tears the
+sandbox down).
+
+`Thread.handle_interrupt(X => :on_blocking)` treats a native call as the
+blocking point at its *start*: the bridge raises an exception that is already
+deferred before the call begins, and one that arrives during the call waits
+for the thread's next blocking operation. The four acquisition methods are
+the exception: their own `Object => :never` mask sits on top of the caller's,
+so a deferred exception is not raised at the native call's entry there — the
+sandbox is returned and the exception is delivered at the next blocking
+operation after the acquisition.
+
+`spec/fake_runtime/interrupt_safety_spec.rb` pins all of this against the real
+extension, driving it with a fake `msb` (`spec/support/fake_runtime/`) whose
+log shows whether a sandbox was stopped, dropped, or left attached.
 
 ## Error mapping
 
@@ -185,7 +245,7 @@ extension.
 `ext/microsandbox/Cargo.toml` depends on the core crate via a **pinned git tag**
 (`microsandbox` / `microsandbox-network`, pinned to the same tag as
 `Microsandbox::RUNTIME_VERSION` — currently `v0.6.18`), so the gem builds anywhere
-— CI, `rake-compiler-dock` release containers, and end-user source installs —
+— CI and end-user source installs —
 without an adjacent checkout. For fast local development against a sibling
 microsandbox checkout, copy `.cargo/config.toml.example` to `.cargo/config.toml`
 (gitignored); its `paths` override builds against the local crates instead of
@@ -195,25 +255,13 @@ git. The override must never be committed — it would break container builds.
 
 * **Source gem**: compiles the extension via `extconf.rb` (rb-sys
   `create_rust_makefile`); requires a Rust toolchain (MSRV below).
-* **Precompiled platform gems**: built best-effort by the `cross-gems` job
-  (`.github/workflows/release.yml`) with `oxidize-rb/cross-gem-action`
-  (`rake-compiler-dock`) per `Gem::Platform`, shipping multi-ABI
-  `lib/microsandbox/<ruby_abi>/` native artifacts — the same model Node uses with
-  per-platform packages. End users then install with no Rust toolchain, and the
-  host runtime comes from the `microsandbox-rb-binaries` gem — or, without it, is
-  fetched on first use (see above). The guest `agentd` is baked into
-  the extension by *target* arch (`filesystem/build.rs` uses
-  `CARGO_CFG_TARGET_ARCH` + `include_bytes!`), so it cross-compiles correctly;
-  the real cross work is linking the *target* native libs — `libcap-ng` on Linux
-  (via Debian multiarch for `aarch64-linux`) and the Hypervisor + Security
-  frameworks on macOS (via osxcross; `arm64-darwin` is the platform still to
-  confirm — if osxcross can't link them, move it to a native `macos-14` runner).
-  The job is gated to `workflow_dispatch` and **not** auto-published on tags:
-  since CI can't boot a microVM to prove a built gem actually works, gems are
-  promoted to the publish path manually after per-platform validation. Published
-  to RubyGems via Trusted Publishing (OIDC). See [docs/releasing.md](docs/releasing.md).
+* **Precompiled platform gems**: not built or published. Every platform
+  installs the source gem, which compiles the extension via `rb_sys` at install
+  time; the host runtime comes from the `microsandbox-rb-binaries` gem — or,
+  without it, is fetched on first use (see above). The companion binaries gems
+  below are unaffected. See [docs/releasing.md](docs/releasing.md).
 * **Runtime binaries gems** (`microsandbox-rb-binaries`): a distinct artifact
-  from the precompiled *extension* gems above — no Ruby code beyond a small
+  from the SDK gem — no Ruby code beyond a small
   locator module, just the verified upstream `msb` + `libkrunfw` for one
   platform. CI's `binaries` job vendors and builds all three platforms on every
   run and smoke-tests the host one; the `package` job installs the source gem
@@ -269,7 +317,8 @@ create options, full mount options (tmpfs/disk + stat-virtualization/
 host-permissions), and snapshot inspection (`open`/`list_dir`/`reindex`).
 
 A few **secondary** upstream knobs remain unexposed (a genuine binding gap, not
-upstream-gated — they exist at the pinned `v0.6.2` runtime): per-published-port host
+upstream-gated — they exist at the pinned runtime,
+`Microsandbox::RUNTIME_VERSION`): per-published-port host
 **bind address** (ports always bind loopback), network **interface overrides**,
 and inline **named-volume create-mode** (pre-create with `Volume.create`, then
 mount with `{ named: }`). These slot in module-by-module exactly as the existing

data/README.md

@@ -40,7 +40,7 @@ gem compiles the Rust extension, so the first install takes a few minutes.
 - Linux with KVM enabled, or macOS on Apple Silicon. Cloud-only users
   (`MSB_BACKEND=cloud`) need neither.
 - A stable Rust toolchain (1.91 or newer) on `PATH` to compile the source gem.
-  Precompiled extension gems require no Rust but are not yet auto-published; see
+  Precompiled extension gems are not published; see
   [docs/releasing.md](docs/releasing.md).
 - The `msb` runtime and `libkrunfw` firmware, from the companion gem above or
   downloaded on first use. Provision ahead of time (a Docker layer, an
@@ -170,7 +170,7 @@ See [docs/observability.md](docs/observability.md).
 | Runtime binaries gem, `msb` resolution order, backends, environment variables | [docs/runtime.md](docs/runtime.md) |
 | Error classes and stable codes | [docs/errors.md](docs/errors.md) |
 | Complete supported surface and what is not yet exposed | [docs/surface.md](docs/surface.md) |
-| Release process, precompiled and binaries gems | [docs/releasing.md](docs/releasing.md) |
+| Release process, release preflight, binaries gems | [docs/releasing.md](docs/releasing.md) |
 | Architecture: native extension, sync bridge, GVL, error mapping | [DESIGN.md](DESIGN.md) |
 | Companion runtime gem internals | [binaries/README.md](https://github.com/ya-luotao/microsandbox-rb/blob/main/binaries/README.md) |
 
@@ -209,7 +209,7 @@ share the upstream tag, but the numbers have diverged since and the gem version
 is **not** an indicator of the embedded runtime. Ask the build instead:
 
 ```ruby
-Microsandbox::VERSION          # => "0.17.1"  (the gem's own version)
+Microsandbox::VERSION          # => "0.17.2"  (the gem's own version)
 Microsandbox.runtime_version   # => "v0.6.18" (the embedded upstream runtime tag)
 ```
 
@@ -237,8 +237,7 @@ constants against this gem's. Every release records its runtime in
 | `0.9.0`  | `v0.6.1` | adopts upstream `v0.6.0`+`v0.6.1` (zombie-runtime wait fix, secret substitution through CONNECT proxies, stale-sandbox cleanup); upstream public API is additive — no Ruby surface change |
 | `0.9.1`  | `v0.6.2` | adopts upstream `v0.6.2` (faster image loads/pulls via early cache gate + zlib-rs); upstream API unchanged — no Ruby surface change |
 | `0.9.2`  | `v0.6.3` | adopts upstream `v0.6.3` (v4-only sandboxes stop advertising AAAA DNS answers — fixes guest gRPC/c-ares preferring unreachable IPv6; scoped upstream TLS verification); glue moves to `*_local` SDK variants — no Ruby surface change |
-| `0.9.3`  | `v0.6.6` | adopts upstream `v0.6.4`+`v0.6.6` (`v0.6.5` was yanked upstream): snapshot restore by pinned digest — fixes fatal restore-after-tag-republish bug, fragmented-UDP/PMTU relay fixes, exec kills the whole process group, ephemeral stop-wait tolerance, readdir RSS-leak fix; upstream API growth is additive-only — no Ruby surface change |
-| `0.10.0` | `v0.6.6` | `v0.6.6` API parity: live `modify`/resize, `ping`/`touch`, create `max_cpus`/`max_memory` |
+| `0.10.0` | `v0.6.6` | adopts upstream `v0.6.4`+`v0.6.6` (`v0.6.5` was yanked upstream): snapshot restore by pinned digest — fixes fatal restore-after-tag-republish bug, fragmented-UDP/PMTU relay fixes, exec kills the whole process group, ephemeral stop-wait tolerance, readdir RSS-leak fix; plus `v0.6.6` API parity: live `modify`/resize, `ping`/`touch`, create `max_cpus`/`max_memory` |
 | `0.11.0` | `v0.6.7` | adopts upstream `v0.6.7` (**breaking**): network profiles replace `public_only`/`non_local`, structured `root_disk:` replaces `oci_upper_size:` (deprecated alias kept), snapshot descriptor contract (`create` re-keyed by name, `save`/`load` rename, `snapshot_to` removed, on-disk auto-migration), `Image.load`/`Image.save`, `follow_root_symlinks:`; runtime carries the GHSA-4vq3-cjpp-v7fg `msb copy` fix |
 | `0.12.0` | `v0.6.8` | adopts upstream `v0.6.8` (**breaking**): `Sandbox.list`/`.list_with` return a cursor-paginated `SandboxPage` (`limit:`/`cursor:` keywords), `UnsupportedError` re-keyed by structured operations with `#operation`/`#hint`; runtime adds a shared log registry for followed streams and cloud exec/ssh reconnects |
 | `0.13.0` | `v0.6.9` | adopts upstream `v0.6.9` (**breaking**): a bare `MSB_API_KEY` no longer selects the cloud backend (explicit `MSB_BACKEND=cloud` or a cloud profile required; invalid cloud config fails closed with `InvalidConfigError`); snapshot payload integrity becomes opt-in (`record_integrity:`, `verify` can report `:not_recorded`). Parity: default-workload execution (`exec_default`/`exec_default_stream`/`attach_default`, `cmd:`), flat root disks (`RootDisk.flat`), `modify(root_disk_size:)`, `rate_limiter:`, `vsock:`, `default_backend_info`, `Volume.get_default` |
@@ -247,13 +246,14 @@ constants against this gem's. Every release records its runtime in
 | `0.16.0` | `v0.6.16` | adopts upstream `v0.6.15`+`v0.6.16` step by step: mount fallback ownership, readonly-mount write-probe fix, log retrieval rerouted through the SDK backends, config overlaid by field presence, network-slot recycling. Parity: per-mount `uid:`/`gid:`, and the convergent lifecycle — `Sandbox.connect_or_create`, `#id`, `#wait_for_status`, `#restart`, `#destroy`, `SandboxHandle#connect_or_start`, `SandboxReplacedError` |
 | `0.17.0` | `v0.6.18` | adopts upstream `v0.6.17`+`v0.6.18` step by step: outbound SOCKS4/SOCKS5 proxies (SOCKS5 UDP + credentials), migration-order fix for databases last opened by a `v0.6.15` `msb`, security hardening — plain-HTTP `Host`/`:authority` now checked against domain-rule policies even in non-strict mode, plus fail-closed strict hostname mode. Parity: `proxy:` (`Microsandbox::OutboundProxy` / `SecretSource`), `strict:` |
 | `0.17.1` | `v0.6.18` | gem-only security and hardening release: relative host paths pinned at create time (GHSA-mcw9-9rf6-p4rm), `Volume.fs` path validation, `Cargo.lock` advisory updates, argument-guard and cleanup fixes, `SECURITY.md` |
+| `0.17.2` | `v0.6.18` | gem-only fix and release-pipeline hardening release: an interrupted native call no longer loses its result (a sandbox the call owns is stopped on `Timeout`/`Thread#kill`), release preflight, SHA-pinned workflow actions and `cargo deny` advisory checks, RBS and docs contract specs |
 
 ## Development
 
 ```bash
 bin/setup                                  # bundle install + compile the native extension
 bundle exec rake compile                   # rebuild the extension (debug); compile:release for optimized
-bundle exec rake spec                      # unit specs (no runtime needed)
+bundle exec rake spec                      # unit + fake-runtime specs (no runtime needed)
 MICROSANDBOX_INTEGRATION=1 bundle exec rspec spec/integration   # boot real microVMs (KVM / Apple Silicon)
 bundle exec standardrb                     # Ruby lint
 cargo fmt --check --manifest-path ext/microsandbox/Cargo.toml

data/SECURITY.md

@@ -32,7 +32,7 @@ entry in some of them refers to the upstream project's own Ruby gem, not to
 
 | Advisory | Severity | Affected `microsandbox-rb` | Status |
 |---|---|---|---|
-| [GHSA-mcw9-9rf6-p4rm](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-mcw9-9rf6-p4rm) — relative bind-mount paths re-resolved against the working directory on restart | High | `<= 0.17.0` | Fixed in `0.17.1` for sandboxes created through this gem (paths are pinned at create time in the binding). Sandboxes created earlier with a relative path keep it: recreate them. The `msb` CLI this gem installs is still runtime `v0.6.18`, so a sandbox created with `msb` directly is not covered: use absolute paths there. |
+| [GHSA-mcw9-9rf6-p4rm](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-mcw9-9rf6-p4rm) — relative bind-mount paths re-resolved against the working directory on restart | High | `<= 0.17.0` | Fixed in `0.17.1` for sandboxes created through this gem (paths are pinned at create time in the binding). Sandboxes created earlier with a relative path keep it: recreate them. The `msb` CLI this gem installs is still runtime `v0.6.18`, so a sandbox created with `msb` directly is not covered: use absolute paths there. Tracked for this gem as [GHSA-qrhv-m6hf-9cmg](https://github.com/ya-luotao/microsandbox-rb/security/advisories/GHSA-qrhv-m6hf-9cmg). |
 | [GHSA-cg9x-2vfm-3j58](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-cg9x-2vfm-3j58) — NAT64 addresses can bypass destination-group network policy | High | all versions (runtime `< v0.7.5`) | **Not fixed in this gem yet**; needs the runtime fix. Only exploitable where the host network routes a NAT64 prefix. Mitigate by denying the prefix explicitly (see below) or blocking it at the host. |
 | [GHSA-3mpp-52gc-935r](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-3mpp-52gc-935r) — hostname allowlist bypass via mismatched HTTP `Host` / `:authority` | High | `<= 0.16.0` | Runtime fix included from `0.17.0`. If you rely on a hostname allowlist for HTTPS without TLS interception, also pass `strict: true` (off by default in this gem). |
 | [GHSA-gj24-29j2-3x78](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-gj24-29j2-3x78) — egress allowlist bypass on malformed HTTP/1 request lines | Medium | `<= 0.12.0` | Runtime fix included from `0.13.0`. |

data/docs/execution.md

@@ -76,7 +76,14 @@ Don't share one handle across threads.
 The GVL is released during sandbox calls, so *other* Ruby threads keep
 running. The *calling* thread blocks uninterruptibly until the call returns:
 `Timeout::timeout`, `Thread#kill`, and Ctrl-C cannot interrupt a blocked native
-call. Bound long-running work with a real deadline where one exists:
+call — they are delivered once it has returned. Its result is not lost when
+that happens: an interrupted `exec_stream` handle, stream or SSH client is
+closed when the unreferenced object is garbage-collected, and a
+`Sandbox.create` interrupted by a `Timeout`/`Thread#raise` or a `Thread#kill`
+stops the sandbox it booted (after a Ctrl-C it is torn down by garbage
+collection instead; see
+[lifecycle.md](lifecycle.md#timeouts-and-interrupts-around-a-create)). Bound
+long-running work with a real deadline where one exists:
 
 - `exec(timeout:)` / `shell(timeout:)` kill the guest command after N seconds.
 - `AgentClient.connect_sandbox` / `connect_path` take a `timeout:` that bounds

data/docs/lifecycle.md

@@ -57,6 +57,39 @@ Microsandbox::Sandbox.remove("box")   # remove a stopped sandbox
 `ENTRYPOINT`/`CMD`. See [execution.md](execution.md#default-workload) for
 `exec_default`.
 
+### Timeouts and interrupts around a create
+
+A create cannot be interrupted while it runs, so `Timeout.timeout(5) {
+Sandbox.create(...) }` does not return after 5 seconds: `Timeout::Error` is
+raised only once the create has finished. When that happens the sandbox is
+**stopped before the exception reaches you** — the call returns only after the
+create *and* that cleanup stop have completed, so it takes longer than the
+create alone — and nothing is left running without an owner. The same holds
+for `Thread#raise` and `Thread#kill`, and for `Sandbox.connect_or_create`,
+`Sandbox.start` and `PullSession#sandbox`. Two details:
+
+- The sandbox is stopped, not removed. Like any stopped sandbox it keeps its
+  name until you `Sandbox.remove` it (or pass `ephemeral: true`), so retrying
+  the create under the same name raises `SandboxAlreadyExistsError`.
+- Only a sandbox the interrupted call owns is stopped. `connect_or_create`
+  that merely connected to a sandbox already running for someone else leaves
+  it running, exactly as its block form does.
+
+The cleanup stop is best-effort: if it fails, the interrupt is still the
+exception you get, and the sandbox is torn down when its now unreferenced
+object is garbage-collected.
+
+A Ctrl-C (`SIGINT`) is the one interrupt that cannot be held back until the
+sandbox is in your hands: one that lands during the create is raised the
+moment the create returns, before anything can stop the sandbox, which is then
+torn down when the unreferenced object is garbage-collected instead of
+immediately.
+
+These methods hold queued interrupts back while they acquire the sandbox, so
+an exception you deferred with `Thread.handle_interrupt(X => :on_blocking)` is
+not raised by them: you get the sandbox, and the exception arrives at the
+thread's next blocking operation.
+
 ## Convergent lifecycle
 
 Idempotent operations that take a name to the state you want, whatever state

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`