feat(sandbox): guest-native /opt/agentos granular tar mounts

Serve packages directly from package.tar via a tar-backed read-only VFS
(mmap + digest index, no extraction), compose /opt/agentos from granular
leaf mounts (tar per pkg-version + single-symlink per bin/<cmd> and current),
resolve symlinks across mounts, and move exec bits to pack time. Carries
in-progress sandbox-multiline-prompt work (registry/software + doc cleanup).

Author: NathanFlurry

BROWSER-CONVERGENCE-ARCHITECTURE.md

@@ -45,6 +45,7 @@ Every bound that protects a shared resource — memory/heap, CPU/wall-clock, fd/
 - **No expensive objects per-call.** Build once, reuse via a pool/persistent worker. Never construct per-operation: Tokio runtime, OS thread, V8 isolate/snapshot, DNS resolver, HTTP client, connection pool. Construct-then-teardown every call IS the bug.
 - **No serialize→deserialize in-process.** Pass the typed struct directly; wire encoding is for the wire only. Don't encode a frame to bytes only to re-parse it into a command.
 - **No whole-buffer copies per I/O.** Use chunked `Vec<u8>` + `extend_from_slice`, not byte-by-byte fills; move/`Arc`/slice payloads — never clone a record that carries its full buffer on each read/write.
+- **Zero host-disk writes on VM start (mount, don't extract).** Mounting read-only packaged content (the `agentos_packages` tar projection, or any archive/content mount) MUST NOT extract the archive to host disk or write physical symlinks at VM/session start. Back content by byte-range reads over the source archive (mmap/seek into the uncompressed tar, digest-keyed and shared across VMs), and serve derived symlinks (the `/opt/agentos/bin` farm, `<pkg>/current`) as **in-memory synthetic mounts**, never on-disk nodes. Extraction/staging is redundant work + state (full unpack, ~32k inodes, symlink farm, temp cleanup, double on-disk copy) for bytes the archive already holds at a known offset — reintroducing it is the bug. The only writes VM start may incur are cheap in-RAM overlay mountpoint dirs materialized by the mount table; host-disk materialization is zero. Any code that "helpfully" extracts must be reverted; the tar reader and projection carry doc comments saying why.
 - **No per-call allocs/locks/clones** on the sync hot path.
 - **Avoid polling**, prefer readiness/event-driven. But a read-probe can be load-bearing for protocol correctness — measure before removing one, and keep its semantic test.
 - **No baseline, no merge.** Capture native + unoptimized numbers BEFORE touching code, gate every change on a measured before/after delta, and keep it measure-gated.

BROWSER-CONVERGENCE-HARDENING.md

@@ -46,6 +46,7 @@ const NODE_IMPORT_CACHE_LOADER_PATH_ENV: &str = "AGENTOS_NODE_IMPORT_CACHE_LOADE
 const NODE_IMPORT_CACHE_PATH_ENV: &str = "AGENTOS_NODE_IMPORT_CACHE_PATH";
 const NODE_KEEP_STDIN_OPEN_ENV: &str = "SECURE_EXEC_KEEP_STDIN_OPEN";
 const NODE_GUEST_ENTRYPOINT_ENV: &str = "AGENTOS_GUEST_ENTRYPOINT";
+const NODE_GUEST_ENTRYPOINT_MODULE_MODE_ENV: &str = "AGENTOS_GUEST_ENTRYPOINT_MODULE_MODE";
 const NODE_GUEST_PATH_MAPPINGS_ENV: &str = "AGENTOS_GUEST_PATH_MAPPINGS";
 const NODE_VIRTUAL_PROCESS_EXEC_PATH_ENV: &str = "AGENTOS_VIRTUAL_PROCESS_EXEC_PATH";
 const NODE_VIRTUAL_PROCESS_PID_ENV: &str = "AGENTOS_VIRTUAL_PROCESS_PID";
@@ -274,6 +275,7 @@ const RESERVED_NODE_ENV_KEYS: &[&str] = &[
     NODE_SANDBOX_ROOT_ENV,
     NODE_FROZEN_TIME_ENV,
     NODE_GUEST_ENTRYPOINT_ENV,
+    NODE_GUEST_ENTRYPOINT_MODULE_MODE_ENV,
     NODE_GUEST_ARGV_ENV,
     NODE_GUEST_PATH_MAPPINGS_ENV,
     NODE_VIRTUAL_PROCESS_EXEC_PATH_ENV,
@@ -2278,6 +2280,22 @@ impl JavascriptExecutionEngine {
         let host_entrypoint = translator.resolve_host_entrypoint(&request.cwd, &request.argv[0]);
         let guest_entrypoint = if request.argv[0] == "-e" || request.argv[0] == "--eval" {
             request.argv[0].clone()
+        } else if let Some(explicit_guest_entrypoint) = request
+            .env
+            .get(NODE_GUEST_ENTRYPOINT_ENV)
+            .filter(|value| value.starts_with('/'))
+        {
+            // Part B (guest-VFS adapter launch): the sidecar already resolved the
+            // GUEST entrypoint path (AGENTOS_GUEST_ENTRYPOINT). Use it directly as
+            // the sourceURL / module-resolution base instead of translating the
+            // host entrypoint — `host_to_guest_string` misses for guest-native
+            // mounts (`agentos_packages`, whose host staging dir is not in the
+            // translation map) and falls back to `/unknown/<cmd>`, which then
+            // poisons the adapter's own relative/bare imports. For host-backed
+            // mounts the two values are equal, so this is a no-op there. Applies
+            // to child launches too (they set AGENTOS_GUEST_ENTRYPOINT as well),
+            // which is the child-process `/unknown` case.
+            explicit_guest_entrypoint.clone()
         } else {
             translator.host_to_guest_string(&host_entrypoint)
         };
@@ -2295,7 +2313,11 @@ impl JavascriptExecutionEngine {
             .inline_code
             .clone()
             .map(|inline_code| strip_javascript_hashbang(&inline_code));
-        let use_module_mode = host_entrypoint_uses_module_mode(&host_entrypoint)
+        let use_module_mode = request
+            .env
+            .get(NODE_GUEST_ENTRYPOINT_MODULE_MODE_ENV)
+            .is_some_and(|value| value == "1" || value.eq_ignore_ascii_case("true"))
+            || host_entrypoint_uses_module_mode(&host_entrypoint)
             || inline_code
                 .as_deref()
                 .is_some_and(inline_code_uses_module_mode);

CLAUDE.md

@@ -3355,6 +3355,12 @@ impl<F: VirtualFileSystem + 'static> KernelVm<F> {
         } else {
             normalize_path(&format!("{cwd}/{command}"))
         };
+        // exec(2) follows symlinks, and a symlink target may live in a different
+        // mount (e.g. `/opt/agentos/bin/<cmd>` is its own single-symlink mount
+        // pointing into a package tar mount). Resolve the real path before
+        // stat-ing / reading the executable so cross-mount symlinked commands
+        // exec their real target instead of failing to read the symlink node.
+        let path = self.filesystem.realpath(&path).unwrap_or(path);
         let stat = self.filesystem.stat(&path)?;
         if stat.is_directory {
             return Err(KernelError::new(