chore: save WIP before removing native/wasmvm (moved to agent-os-registry)

Author: NathanFlurry

.agent/contracts/node-bridge.md

@@ -4,7 +4,7 @@
 Define bridge boundary policy, third-party module boundaries, and capability expansion controls.
 ## Requirements
 ### Requirement: Bridge Scope Is Node Built-ins Only
-Bridge implementations injected into isolated-vm MUST be limited to Node.js built-in modules and types compatible with `@types/node`.
+Bridge implementations injected into the V8 isolate MUST be limited to Node.js built-in modules and types compatible with `@types/node`.
 
 #### Scenario: Bridge request targets a third-party package
 - **WHEN** a proposed bridge module is not a Node.js built-in

CLAUDE.md

@@ -122,13 +122,10 @@
 - the goal for WasmVM is full POSIX compliance 1:1 — every command, syscall, and shell behavior should match a real Linux system exactly
 - WasmVM and Python are experimental surfaces in this repo
 - all docs for WasmVM, Python, or other experimental runtime features must live under the `Experimental` section of the docs navigation, not the main getting-started/reference sections
-- the WasmVM runtime requires standalone WASM binaries in `native/wasmvm/target/wasm32-wasip1/release/commands/`
-- build them locally: `cd native/wasmvm && make wasm` (requires Rust nightly + wasm32-wasip1 target + rust-src component + wasm-opt/binaryen)
-- the Rust toolchain is pinned in `native/wasmvm/rust-toolchain.toml` — rustup will auto-install it
-- CI builds the binaries before tests; a CI-only guard test in `packages/wasmvm/test/driver.test.ts` fails if they're missing
-- story-critical C-built Wasm fixtures also have CI-only availability guards in `packages/wasmvm/test/ci-artifact-availability.test.ts` and `packages/secure-exec/tests/kernel/ci-wasm-artifact-availability.test.ts`; if they fail, rebuild with `make -C native/wasmvm/c sysroot && make -C native/wasmvm/c programs`
+- **All WASM command source code (Rust crates and C programs) has been moved to the agent-os-registry repo at `~/agent-os-registry/`** (GitHub: `rivet-dev/agent-os-registry`). The `native/wasmvm/` directory in this repo is the original copy and should no longer be the primary source for building commands. Build from the registry instead: `cd ~/agent-os-registry && make build-wasm`.
+- the WasmVM runtime driver (`packages/wasmvm/`) still lives in this repo. It loads and executes WASM binaries but does not contain command source code.
 - tests gated behind `skipIf(!hasWasmBinaries)` or `skipUnlessWasmBuilt()` will skip locally if binaries aren't built
-- see `native/wasmvm/CLAUDE.md` for full build details and architecture
+- the `native/wasmvm/` directory remains for reference and WASI host import definitions (`crates/wasi-ext/`), patches (`patches/`), and the C sysroot build
 
 ## WasmVM Syscall Coverage
 

docs-internal/arch/active-handles.md

@@ -2,7 +2,7 @@
 
 ## Problem
 
-The sandboxed Node.js environment uses `isolated-vm` (V8 isolates) to run JavaScript code. Unlike real Node.js, isolated-vm does not have an event loop. Code runs synchronously and the sandbox exits immediately when the script finishes executing.
+The sandboxed Node.js environment uses V8 isolates to run JavaScript code. Unlike real Node.js, the V8 isolate does not have an event loop. Code runs synchronously and the sandbox exits immediately when the script finishes executing.
 
 This causes problems with async APIs that use callbacks:
 
@@ -31,7 +31,7 @@ In real Node.js:
 4. Callbacks fire as events occur
 5. Process exits when no more active handles remain
 
-In isolated-vm:
+In the V8 isolate:
 1. Script sets up event handlers
 2. Script finishes synchronous execution
 3. `exec()` returns immediately - no event loop
@@ -137,7 +137,7 @@ Active handles: [
 
 | Feature | Node.js | secure-exec |
 |---------|---------|----------------|
-| Event loop | Built-in libuv | None (isolated-vm) |
+| Event loop | Built-in libuv | None (V8 isolate) |
 | Handle tracking | Automatic via libuv | Manual via `_registerHandle` |
 | `ref()`/`unref()` | Per-handle methods | Not implemented (all handles keep alive) |
 | Debugging | `process._getActiveHandles()` | `_getActiveHandles()` |

docs-internal/arch/kernel-integration.md

@@ -87,10 +87,10 @@ All kernel operations run on the **main thread** (the event loop). Each runtime'
 | Runtime | Execution Context | Sync Mechanism |
 |---------|------------------|----------------|
 | WasmVM  | Web Worker (WASM instance) | SharedArrayBuffer + Atomics.wait |
-| Node    | V8 Isolate (isolated-vm) | ivm.Reference (applySyncPromise) |
+| Node    | V8 Isolate | Reference (applySyncPromise) |
 | Python  | Node Worker (Pyodide) | Worker postMessage |
 
-The main thread services all runtimes via the event loop. When a WasmVM Worker needs a file, it posts a message and blocks on `Atomics.wait`. The main thread handles the request and calls `Atomics.notify`. When a V8 isolate needs a file, the `ivm.Reference` suspends the isolate, the main thread resolves the promise, and the isolate resumes. No dedicated kernel worker needed.
+The main thread services all runtimes via the event loop. When a WasmVM Worker needs a file, it posts a message and blocks on `Atomics.wait`. The main thread handles the request and calls `Atomics.notify`. When a V8 isolate needs a file, the Reference suspends the isolate, the main thread resolves the promise, and the isolate resumes. No dedicated kernel worker needed.
 
 ---
 
@@ -1031,7 +1031,7 @@ WasmVM internal docs stay with WasmVM. Only cross-project docs go to the top lev
 2. Build instructions — `wasm32-wasip1`, nightly Rust, `-Z build-std`
 3. Key decisions — brush-shell, uutils/sed, awk-rs, ripgrep, jaq, custom find
 4. Dependency patching — three-tier: direct dep → vendor+patch → full fork
-5. Why not Wasmtime/WASIX/Component Model
+5. Why not native WASM runtimes/Component Model
 6. Naming — `wasmvm/crates/`, `wasmvm/stubs/`, `wasmvm/patches/`
 7. Deferred items → `wasmvm/notes/todo.md`
 

docs-internal/attack-vectors.md

@@ -11,7 +11,7 @@ Catalog of known attack vectors against the sandbox runtime.
 
 | Vector                              | Layer   | Mitigated? | Notes                                                                                        |
 | ----------------------------------- | ------- | ---------- | -------------------------------------------------------------------------------------------- |
-| Infinite loop in sandbox code       | Runtime | Partial    | isolated-vm timeout via `cpuTimeLimitMs`. Gap: optional, no default; unset = no limit        |
+| Infinite loop in sandbox code       | Runtime | Partial    | V8 isolate timeout via `cpuTimeLimitMs`. Gap: optional, no default; unset = no limit        |
 | ReDoS (catastrophic regex)          | Runtime | Partial    | Caught by same CPU timeout. Gap: same; no per-regex complexity limit                         |
 | Crypto cost abuse (pbkdf2/scrypt)   | Runtime | No         | No caps on iterations/N/r/p parameters. Burns host CPU outside isolate timeout               |
 | JSON.parse bomb on host             | Runtime | No         | 8 host-side JSON.parse calls, no size check. Runs in host process; isolate limits don't help |
@@ -20,7 +20,7 @@ Catalog of known attack vectors against the sandbox runtime.
 
 | Vector                              | Layer   | Mitigated? | Notes                                                                                   |
 | ----------------------------------- | ------- | ---------- | --------------------------------------------------------------------------------------- |
-| Isolate heap exhaustion             | Runtime | Yes        | isolated-vm `memoryLimit` (default 128MB). OOM kills isolate, not host process          |
+| Isolate heap exhaustion             | Runtime | Yes        | V8 isolate `memoryLimit` (default 128MB). OOM kills isolate, not host process          |
 | Base64 amplification on host        | Runtime | No         | 50MB file → 67MB base64 on host heap. No transfer size cap; host OOM possible           |
 | Timer/interval bombing              | Runtime | No         | Bridge timer map grows unbounded. No limit on count of active timers                    |
 | stdout/stderr accumulation          | Runtime | No         | Output arrays grow unbounded on host. No cap on captured output size                    |
@@ -37,7 +37,7 @@ Catalog of known attack vectors against the sandbox runtime.
 
 | Vector                              | Layer   | Mitigated? | Notes                                                                                   |
 | ----------------------------------- | ------- | ---------- | --------------------------------------------------------------------------------------- |
-| Prototype pollution across boundary | Runtime | Likely safe | isolated-vm copies values, no shared prototypes. Needs verification test               |
+| Prototype pollution across boundary | Runtime | Likely safe | V8 isolate copies values, no shared prototypes. Needs verification test               |
 | Reference argument type confusion   | Runtime | No         | Host References don't validate argument types. String expected, object passed → UB      |
 | Bridge global overwriting           | Runtime | No         | `_fs`, `_registerHandle` etc. are writable. Impact: self-sabotage / host hang, not escape |
 | Module resolution path traversal    | Driver  | Partial    | VirtualFileSystem abstracts scope. Gap: no path canonicalization before permission check |

docs-internal/comarison.mdx

@@ -42,7 +42,7 @@
 1. **[resolved]** `NodeRuntime` constructor ownership drifted between driver and direct adapter options.
    - Symptom: runtime capability and config ownership was split across `NodeRuntime` fallbacks and `createNodeDriver`, which made permission defaults and runtime injection behavior harder to reason about.
    - Fix: `NodeRuntime` now requires a `driver`, reads `processConfig`/`osConfig` from `driver.runtime`, and no longer accepts direct constructor adapters/permissions.
-   - Follow-up: a dedicated pass should continue moving remaining `isolated-vm` execution internals from `NodeRuntime` into the Node driver implementation.
+   - Follow-up: a dedicated pass should continue moving remaining V8 isolate execution internals from `NodeRuntime` into the Node driver implementation.
 2. **[resolved]** Browser runtime surface needed temporary de-scope during driver boundary refactor.
    - Symptom: maintaining Worker/browser runtime paths during Node driver ownership changes increased refactor risk and cross-runtime drift.
    - Fix: browser package exports were removed for this phase and browser entrypoints now return deterministic unsupported errors until follow-up restoration.
@@ -142,7 +142,7 @@
    - Symptom: requests reached the sandbox server but responded `400`; root cause was `instanceof http2.Http2ServerRequest` checks throwing when `http2` constructors were undefined.
    - Fix: added built-in `http2` compatibility stubs (`Http2ServerRequest`/`Http2ServerResponse`) and routed `require('http2')` / ESM `import 'http2'` to that stub module.
 
-5. **[resolved]** Direct cloning of ESM module namespace objects failed in `isolated-vm`.
+5. **[resolved]** Direct cloning of ESM module namespace objects failed in the V8 isolate layer.
    - Symptom: using `entryModule.namespace.copy()` for `run()` exports failed with `[object Module] could not be cloned`.
    - Fix: after ESM evaluation, bind the namespace in isolate scope and copy `Object.fromEntries(Object.entries(namespace))` to the host.
 

docs-internal/friction.md

@@ -4,4 +4,4 @@
 - **Runtime** — the full `secure-exec` execution environment including the isolate, bridge, and resource controls. `NodeRuntime` and `PythonRuntime` are the public entry points.
 - **Bridge** — the narrow layer between the isolate and the host that mediates all privileged operations. Untrusted code can only reach host capabilities through the bridge.
 - **SystemDriver** — config object that bundles what the isolate can access (filesystem, network, command executor, permissions). Deny-by-default. Built by `createNodeDriver()` or `createBrowserDriver()`.
-- **Execution Driver** — host-side engine that owns the isolate lifecycle. `NodeExecutionDriver` (V8 via `isolated-vm`), `BrowserRuntimeDriver` (Web Worker), `PyodideRuntimeDriver` (Pyodide in a Node worker).
+- **Execution Driver** — host-side engine that owns the isolate lifecycle. `NodeExecutionDriver` (V8 isolate), `BrowserRuntimeDriver` (Web Worker), `PyodideRuntimeDriver` (Pyodide in a Node worker).

docs-internal/glossary.md

@@ -89,9 +89,9 @@ A comparison of tools that run Node.js-compatible code in browsers or sandboxed
 
 ### libsandbox (secure-exec)
 
-**What it is:** A driver-based sandboxed Node.js runtime with two backends: `isolated-vm` for Node.js (V8 isolate-level isolation) and Web Workers for browsers. Designed for executing code snippets with controlled API access.
+**What it is:** A driver-based sandboxed Node.js runtime with two backends: V8 isolates for Node.js (isolate-level isolation) and Web Workers for browsers. Designed for executing code snippets with controlled API access.
 
-**Architecture:** A unified bridge layer provides Node.js APIs (fs, process, child_process, network, os) that work identically across both drivers. The Node driver uses `isolated-vm` to create V8 isolates with explicit `Reference`-based bridges. The browser driver uses Web Workers with `postMessage` communication. A permission system gates access to filesystem, network, child process, and environment operations.
+**Architecture:** A unified bridge layer provides Node.js APIs (fs, process, child_process, network, os) that work identically across both drivers. The Node driver uses V8 isolates with explicit `Reference`-based bridges. The browser driver uses Web Workers with `postMessage` communication. A permission system gates access to filesystem, network, child process, and environment operations.
 
 **Strengths:**
 - Strong isolation on Node.js (V8 isolate — separate heap)
@@ -108,7 +108,7 @@ A comparison of tools that run Node.js-compatible code in browsers or sandboxed
 - Browser driver isolation is weaker (Worker global scope is accessible)
 - No npm package installation
 - No real `node_modules` resolution (polyfills via node-stdlib-browser)
-- `isolated-vm` is a native addon (complicates deployment)
+- The V8 isolate package is a native addon (complicates deployment)
 - Single-threaded execution per isolate/Worker
 
 **Node API coverage:** Targeted. Covers fs (full CRUD), path, process, child_process (spawn, exec, spawnSync, execSync, fork), http/https, fetch, dns, os, Buffer, URL, stream, events, timers, console, and modules via node-stdlib-browser polyfills.
@@ -119,7 +119,7 @@ A comparison of tools that run Node.js-compatible code in browsers or sandboxed
 
 | Feature | WebContainers | Sandpack/Nodebox | almostnode | libsandbox |
 |---|---|---|---|---|
-| **Architecture** | WASM OS | Worker + bundler | In-memory JS | isolated-vm / Worker |
+| **Architecture** | WASM OS | Worker + bundler | In-memory JS | V8 Isolate / Worker |
 | **Bundle size** | ~10MB+ | ~2MB (Sandpack) | ~250KB target | ~500KB (with bridge) |
 | **Startup time** | 2-5s | 500ms-2s | <10ms | <10ms |
 | **Node API coverage** | High | Moderate | Partial | Targeted |
@@ -138,7 +138,7 @@ A comparison of tools that run Node.js-compatible code in browsers or sandboxed
 
 libsandbox occupies a distinct niche: **fast, secure, dual-environment code execution** rather than full development environment simulation. Key differentiators:
 
-1. **Security-first**: libsandbox is the only option with real memory isolation (via isolated-vm) and a structured permission system. WebContainers relies on browser sandboxing; almostnode has no isolation.
+1. **Security-first**: libsandbox is the only option with real memory isolation (via V8 isolates) and a structured permission system. WebContainers relies on browser sandboxing; almostnode has no isolation.
 
 2. **Node.js as primary target**: libsandbox is designed to run on Node.js servers (for AI agent backends, code execution APIs) with browser as a secondary target. WebContainers and Sandpack are browser-first.
 

docs-internal/research/comparison/browser-node-runtimes.md

@@ -50,11 +50,11 @@ Cascading defense:
 
 ## Comparison with libsandbox
 
-libsandbox uses `isolated-vm` (also V8 isolates) and shares some of the same principles.
+libsandbox uses V8 isolates and shares some of the same principles.
 
 | Aspect | Cloudflare Workers | libsandbox |
 |---|---|---|
-| Isolate tech | V8 (custom workerd) | V8 (isolated-vm) |
+| Isolate tech | V8 (custom workerd) | V8 isolate |
 | Default posture | Zero capabilities | Zero capabilities |
 | Permission model | Capability bindings in config | Function-based permission checks |
 | FS access | Blocked at syscall level | No FS unless VirtualFileSystem provided |
@@ -65,7 +65,7 @@ libsandbox uses `isolated-vm` (also V8 isolates) and shares some of the same pri
 | OS-level sandbox | seccomp + namespaces | **None** |
 | Spectre mitigations | Frozen clocks, perf counters, process isolation | Default frozen timing mode + `SharedArrayBuffer` removed (`timingMitigation: "freeze"`) |
 | eval/dynamic code | Blocked during request handling | **Not restricted** |
-| Native code | Blocked (JS/Wasm only) | Blocked (isolated-vm limitation) |
+| Native code | Blocked (JS/Wasm only) | Blocked (V8 isolate limitation) |
 
 ### What libsandbox does well
 
@@ -91,10 +91,10 @@ libsandbox uses `isolated-vm` (also V8 isolates) and shares some of the same pri
 
 ### 2. No OS-level sandboxing (MEDIUM-HIGH)
 
-The host Node.js process has full OS access. If there is ever an isolated-vm escape (V8 bug), the attacker owns the host process with all its permissions. Cloudflare wraps everything in seccomp + empty namespaces.
+The host Node.js process has full OS access. If there is ever a V8 isolate escape (V8 bug), the attacker owns the host process with all its permissions. Cloudflare wraps everything in seccomp + empty namespaces.
 
 **Recommendation:**
-- Document that isolated-vm alone is not sufficient for running untrusted code from the internet
+- Document that V8 isolates alone are not sufficient for running untrusted code from the internet
 - Provide guidance for users to run the host process in a container with minimal capabilities (`--cap-drop=ALL`)
 - Consider optional integration with Linux namespaces or seccomp for the host process
 
@@ -117,7 +117,7 @@ The host Node.js process has full OS access. If there is ever an isolated-vm esc
 
 Cloudflare blocks these during request handling because they make forensic analysis of exploits harder and expand the attack surface for V8 bugs.
 
-**Recommendation:** Add an option to disable dynamic code generation in the isolate. `isolated-vm` may support this via V8 flags or by overriding these globals in the bridge.
+**Recommendation:** Add an option to disable dynamic code generation in the isolate. The V8 isolate package may support this via V8 flags or by overriding these globals in the bridge.
 
 ### 5. No resource limits on child processes/network (LOW-MEDIUM)