Rust review sweep + runtime fixes, reconciled onto main

.gitignore

@@ -74,3 +74,7 @@ packages/browser/.cache/
 # Vendored V8 bridge bundles staged at release time for crates.io publishing
 crates/execution/assets/generated/
 crates/v8-runtime/assets/generated/
+
+# Transient repro scratch files and Vite/Vitest config timestamp artifacts
+.tmp-*
+*.timestamp-*.mjs

CLAUDE.md

@@ -39,6 +39,7 @@ Agent OS is a **fully virtualized operating system**. The kernel, written as a R
 - **Base filesystem rebuild flow:** `pnpm --dir packages/core snapshot:alpine-defaults` writes `alpine-defaults.json`, then `pnpm --dir packages/core build:base-filesystem` rewrites AgentOs-specific values and emits `base-filesystem.json`.
 - **The default VM filesystem model should be Docker-like.** Layered overlay view with one writable upper layer on top of one or more immutable lower snapshot layers.
 - **Everything runs inside the VM.** Agent processes, servers, network requests -- all spawned inside the Agent OS kernel, never on the host. This is a hard rule with no exceptions.
+- **Present normal Linux semantics to tools.** Never bend agent SDKs, shell tools, or adapters around Agent OS quirks when the correct fix is implementing standard Linux/Node/POSIX behavior in the runtime. Agent-specific patches are acceptable only for explicit product policy, configuration, or upstream SDK bugs.
 
 ## Native Binary Distribution
 
@@ -145,11 +146,17 @@ When the user asks to track something in a note, store it in `~/.agents/notes/`
 ## Error Handling
 
 - Always return anyhow errors from failable Rust functions. Do not glob-import from anyhow. Prefer `.context()` over the `anyhow!` macro.
+- A failing fallback path must rethrow the original error with the fallback's failure attached as context. Never let the fallback's error replace the original.
+
+## Runtime Limits
+
+- **Every new limit-shaped constant must be classified.** Any `MAX_*` / `*_LIMIT` / `*_CAPACITY` / retention / sizing constant added under the scanned roots must get an entry in `crates/sidecar/tests/fixtures/limits-inventory.json`: either `policy` (wired through `VmLimits` with a `wired` field naming its config field) or `invariant`/`policy-deferred` with a one-line rationale. The `cargo test -p agent-os-sidecar --test limits_audit` audit fails when a qualifying constant is unclassified.
 
 ## Fail-By-Default Runtime
 
 - Avoid silent no-ops for required runtime behavior. If a capability is required, validate it and throw an explicit error with actionable context instead of returning early.
 - Do not use optional chaining for required lifecycle and bridge operations. Optional chaining is acceptable only for best-effort diagnostics and cleanup paths (logging hooks, dispose/release cleanup).
+- Never land a public callback, stream, or event API without a wired delivery source. If the source is not wired yet, the doc comment must say so explicitly so callers do not wait on a stream that never yields.
 
 ## Async Rust Locks
 
@@ -167,6 +174,9 @@ When the user asks to track something in a note, store it in `~/.agents/notes/`
 - Reserve `tokio::time::sleep` for per-call timeouts, retry/reconnect backoff, deliberate debounce windows, or `sleep_until(deadline)` arms in an event-select loop. A `loop { check; sleep }` body is polling and should be event-driven instead.
 - `scc` async methods do not hold locks across `.await` points. Use `entry_async` for atomic read-then-write.
 - Never add unexplained wall-clock defers like `sleep(1ms)` to decouple a spawn from its caller. Use `tokio::task::yield_now().await` or rely on the spawn itself.
+- Polling is forbidden in every language and layer, not just Rust. Never wait for a state change by re-checking in a loop in TypeScript, tests, or shell. Wait on an event: a Notify/watch channel, promise, callback, process exit, or stream EOF. If an external system genuinely offers no event signal, bound the poll with a deadline and justify it in a comment.
+- Never block while holding a lock. No bounded-channel sends, thread joins, or IO under any lock guard. Remove or copy the needed state under the lock, release it, then do the blocking work.
+- Code that registers a waiter or pending entry in a shared queue must remove it on every exit path: success, early drain, timeout, and error.
 
 ## Memory Leaks
 
@@ -176,6 +186,11 @@ When the user asks to track something in a note, store it in `~/.agents/notes/`
 - `std::mem::forget` is only acceptable when an FFI handle cannot be dropped in the current context; document the constraint inline, prove the leak is bounded, and prefer routing cleanup through an Env-bearing owner.
 - Spawned futures that capture JS callbacks or other heavy resources must have a guaranteed completion path (e.g. a `CancellationToken` whose clones are guaranteed to drop). A `spawn_local(async move { token.cancelled().await; ... })` only drains if every clone of the token is dropped or cancelled.
 
+## Untrusted Input
+
+- Write parser bounds checks in subtraction form after an explicit minimum-length guard (`len >= off && len - off >= n`), never `off + n > len`, which wraps on 32-bit targets.
+- Cap any allocation whose size derives from untrusted input before allocating.
+
 ## Testing
 
 - **Never use `vi.mock`, `jest.mock`, or module-level mocking.** Write tests against real infrastructure (real kernel, real filesystems, real processes). For LLM calls, use `@copilotkit/llmock` to run a mock LLM server. For protocol-level test doubles (e.g., ACP adapters), write hand-written scripts that run as real processes. `vi.fn()` for simple callback tracking is acceptable.
@@ -186,10 +201,15 @@ When the user asks to track something in a note, store it in `~/.agents/notes/`
 
 - This repo uses jj (Jujutsu) on top of git. **jj's workflow is inverted from git:** the working copy is itself a revision that auto-tracks edits, so you create a new revision *before* making changes (with `jj new`) rather than committing *after* (`git commit`). The description is set separately via `jj describe`. There is no staging step.
 - Before making changes, check whether jj is initialized by running `jj status`. If it fails (e.g. "There is no jj repo in '.'"), run `jj git init --colocate` from the repo root so jj lives alongside the existing `.git` directory. Do NOT run `jj git init` without `--colocate` — that creates a standalone jj repo and breaks the git workflow.
-- **MUST run `jj new` before making any file edits for a new task.** This is the first step of any task that touches files. Run it before reading, before planning, before editing. The only exception is when you are directly fixing or finishing the change at `@` that you just made in this same session. In that case use `jj squash --into <rev>` or `jj edit <rev>`. If you already started editing without running `jj new`, stop and split the changes with `JJ_EDITOR=true jj split <paths>` before continuing. Each revision must be one self-contained change reviewable on its own. Never mix unrelated work into one revision.
+- **One revision = one self-contained change. MUST run `jj new` before starting each change**, before reading, planning, or editing. The unit is the *change*, not the *task*, *request*, or *session*. A single user request routinely contains several unrelated changes (a fix here, a refactor there, a test update); each one is its own revision, so run `jj new` again the moment you move on to the next change. Do not let edits pile up in one revision just because they came from one prompt or one work session.
+- **Heuristic for "is this one revision or several?"** If a single `jj describe` line cannot honestly describe the whole diff without the word "and", or the diff spans unrelated subsystems/concerns (e.g. a test fix plus a build change plus an adapter tweak), it is more than one revision. Err toward more, smaller revisions. A revision touching a dozen files across many subsystems under a vague message like "triage failed tests" is the anti-pattern, not the goal.
+- Run it before reading, before planning, before editing. The only exception is when you are directly fixing or finishing the change at `@` that you just made in this same session. In that case use `jj squash --into <rev>` or `jj edit <rev>`. If you already started editing and find the working copy now mixes unrelated changes, stop immediately and split them apart with `JJ_EDITOR=true jj split <paths>` before continuing. Never mix unrelated work into one revision.
 - Set the revision description with `jj describe -m "[SLOP({full-model-id}-{reasoning})] {conventional commit message}"`. Use conventional commits (`feat`, `fix`, `chore`, `docs`, `refactor`, etc.) with a single-line message. `{full-model-id}` is the canonical model ID (e.g. `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`). `{reasoning}` is the reasoning effort (`high`, `medium`, `low`, `off`) — include it only if the runtime exposes it; otherwise omit the `-{reasoning}` suffix entirely.
 - Examples: `[SLOP(claude-opus-4-7-high)] feat(metrics): record depot sqlite phase timings` or, when reasoning is not known, `[SLOP(claude-opus-4-7)] fix(pegboard): handle empty ack batch`.
 - **Never add a co-author trailer** (no `Co-Authored-By: ...` line). Descriptions are single-line only.
+- **A revision description must describe its actual diff.** Check the message against `jj diff -r <rev> --stat` before running `jj describe`.
+- Abandon stray empty undescribed revisions before ending a session. Do not leave `jj new` artifacts in the branch.
+- Never commit fetched or vendored source trees. Add the ignore entry before fetching.
 - **Never push to `main` unless explicitly specified by the user.**
 - **Safety:** Never run destructive jj or git commands (`jj git push`, `jj abandon`, `jj squash` into a non-current revision, `jj op restore`, `jj op undo` past your own work, `jj rebase -d main`, `git push --force`, `git reset --hard`) unless the user explicitly requests it.
 
@@ -207,3 +227,4 @@ pnpm lint         # biome check
 - CI and release automation must install the pnpm workspace with `--frozen-lockfile` before Cargo builds that generate V8 bridge assets into `OUT_DIR`. Fork pull requests should run the same `pnpm test` command without `AGENTOS_E2E_NETWORK=1`.
 - When changing V8 bridge registration or snapshot bootstrap code under `crates/v8-runtime/`, rebuild `agent-os-v8-runtime` before rerunning sidecar V8 integration tests. `cargo test -p agent-os-sidecar` can otherwise reuse stale embedded-runtime objects from `target/`.
 - The `crates/v8-runtime` snapshot test (`snapshot::tests::snapshot_consolidated_tests`) currently has to run in isolation: use `cargo test -p agent-os-v8-runtime -- --test-threads=1` for the main suite and `cargo test -p agent-os-v8-runtime snapshot::tests::snapshot_consolidated_tests -- --exact --ignored` separately until the shared test binary teardown SIGSEGV is fixed.
+- Biome honors `.gitignore` (`vcs.useIgnoreFile`), and the core-dump patterns (`**/core`) match `packages/core`, so `pnpm lint` silently skips that entire package. Do not treat a green lint as proof those files were checked. Fixing the pattern requires first cleaning up the package's accumulated lint debt (tracked in `~/.agents/todo/`).

README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  A portable open-source operating system for AI agents.<br/>Near-zero cold starts (~6 ms), up to 32x cheaper than sandboxes.<br/>Powered by WebAssembly and V8 isolates.<br/><br/>Supports Pi, Claude Code*, Codex*, Amp*, and OpenCode*<br/><sub>* coming soon</sub>
+  A portable open-source operating system for AI agents.<br/>Near-zero cold starts (~6 ms), up to 32x cheaper than sandboxes.<br/>Built-in ACP agents: Pi, Claude Code, and OpenCode
 </p>
 
 <p align="center">
@@ -28,11 +28,11 @@ You don't have to choose: agentOS works with sandboxes through the [sandbox exte
 ## Quick start
 
 ```bash
-npm install @rivet-dev/agent-os @rivet-dev/agent-os-common @rivet-dev/agent-os-pi
+npm install @rivet-dev/agent-os-core @rivet-dev/agent-os-common @rivet-dev/agent-os-pi
 ```
 
 ```ts
-import { AgentOs } from "@rivet-dev/agent-os";
+import { AgentOs } from "@rivet-dev/agent-os-core";
 import common from "@rivet-dev/agent-os-common";
 import pi from "@rivet-dev/agent-os-pi";
 
@@ -107,13 +107,13 @@ All benchmarks compare agentOS against the fastest/cheapest mainstream sandbox p
 ## Features
 
 ### Agents
-- **Multi-agent support**: Run Claude Code, Codex, OpenCode, Amp, Pi, and more with a unified API
+- **Multi-agent support**: Run built-in Pi, Claude Code, and OpenCode agents with a unified API, plus install registry command packages such as Codex as VM software
 - **[Sessions via ACP](https://rivet.dev/docs/agent-os/sessions)**: Create, manage, and resume agent sessions over the [Agent Communication Protocol](https://agentclientprotocol.com)
 - **Universal transcript format**: One transcript format across all agents for debugging, auditing, and comparison
 - **[Automatic persistence](https://rivet.dev/docs/agent-os/persistence)**: Every conversation is saved and replayable without extra code
 
 ### Infrastructure
-- **[Mount anything as a filesystem](https://rivet.dev/docs/agent-os/filesystem)**: S3, Google Drive, SQLite, host directories, or custom backends
+- **[Mount external storage as a filesystem](https://rivet.dev/docs/agent-os/filesystem)**: S3-compatible storage, Google Drive, host directories, overlay filesystems, or custom backends
 - **[Host tools](https://rivet.dev/docs/agent-os/tools)**: Define JavaScript functions that agents call as CLI commands inside the VM
 - **[Cron](https://rivet.dev/docs/agent-os/cron), [webhooks](https://rivet.dev/docs/agent-os/webhooks), and [queues](https://rivet.dev/docs/agent-os/queues)**: Schedule tasks, receive external events, and serialize work with built-in primitives
 - **[Sandbox extension](https://rivet.dev/docs/agent-os/sandbox)**: Pair with full sandboxes (E2B, Daytona, etc.) for heavy workloads like browsers or native compilation
@@ -128,16 +128,11 @@ All benchmarks compare agentOS against the fastest/cheapest mainstream sandbox p
 - **[Deny-by-default permissions](https://rivet.dev/docs/agent-os/security)**: Granular control over filesystem, network, process, and environment access
 - **[Programmatic network control](https://rivet.dev/docs/agent-os/networking)**: Allow, deny, or proxy any outbound connection
 - **[Resource limits](https://rivet.dev/docs/agent-os/security)**: Set precise CPU and memory limits per agent
-- **[V8 + WebAssembly isolation](https://rivet.dev/docs/agent-os/architecture)**: Each agent runs in its own isolate with no shared state
+- **[VM isolation](https://rivet.dev/docs/agent-os/architecture)**: Each agent runs in its own VM with no shared state
 
 ## Architecture
 
-agentOS is built on an in-process operating system kernel written in JavaScript. Three runtimes mount into the kernel:
-
-- **WebAssembly**: POSIX utilities (coreutils, grep, sed, etc.) compiled to WASM
-- **V8 isolates**: JavaScript/TypeScript agent code runs in sandboxed V8 contexts
-
-The kernel manages a virtual filesystem, process table, pipes, PTYs, and a virtual network stack. Everything runs inside the kernel -- nothing executes on the host.
+agentOS is built on an in-process operating system kernel. The kernel manages a virtual filesystem, process table, pipes, PTYs, and a virtual network stack. Everything runs inside the kernel -- nothing executes on the host.
 
 See the [Architecture docs](https://rivet.dev/docs/agent-os/architecture) for details.
 
@@ -146,11 +141,11 @@ See the [Architecture docs](https://rivet.dev/docs/agent-os/architecture) for de
 Browse pre-built agents, tools, filesystems, and software packages at the [agentOS Registry](https://rivet.dev/agent-os/registry).
 
 <!-- BEGIN PACKAGE TABLE -->
-### WASM Command Packages
+### VM Command Packages
 
 | Package | apt Equivalent | Description | Source | Combined Size | Gzipped |
 |---------|---------------|-------------|--------|---------------|---------|
-| `@rivet-dev/agent-os-codex` | codex | OpenAI Codex integration (codex, codex-exec) | rust | - | - |
+| `@rivet-dev/agent-os-codex` | codex | OpenAI Codex command package (codex, codex-exec) | rust | - | - |
 | `@rivet-dev/agent-os-coreutils` | coreutils | GNU coreutils: sh, cat, ls, cp, sort, and 80+ commands | rust | - | - |
 | `@rivet-dev/agent-os-curl` | curl | curl HTTP client | c | - | - |
 | `@rivet-dev/agent-os-diffutils` | diffutils | GNU diffutils (diff) | rust | - | - |
@@ -177,8 +172,8 @@ Browse pre-built agents, tools, filesystems, and software packages at the [agent
 
 | Package | Description | Includes |
 |---------|-------------|----------|
-| `@rivet-dev/agent-os-build-essential` | Build-essential WASM command set (standard + make + git + curl) | standard, make, git, curl |
-| `@rivet-dev/agent-os-common` | Common WASM command set (coreutils + sed + grep + gawk + findutils + diffutils + tar + gzip) | coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip |
+| `@rivet-dev/agent-os-build-essential` | Build-essential VM command set (standard + make + git + curl) | standard, make, git, curl |
+| `@rivet-dev/agent-os-common` | Common VM command set (coreutils + sed + grep + gawk + findutils + diffutils + tar + gzip) | coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip |
 <!-- END PACKAGE TABLE -->
 
 ## License