From 26590c21c48658e6ca15d9c2f309c2795a9e44f2 Mon Sep 17 00:00:00 2001
From: robobun <117481402+robobun@users.noreply.github.com>
Date: Wed, 16 Sep 2026 13:38:53 +0000
Subject: [PATCH 1/5] shell: reuse the parse arena between scripts

A `bun_alloc::Arena` is a whole mimalloc heap. Every `Bun.$` script made
one for its tokens and AST, destroyed it and made a second one when the
script finished, and destroyed that one in the finalizer. `memory_cost`
walked the heap two more times. The heap create/destroy pairs cost more
than a shell builtin takes to run.

A finished script now parks its arena on the VM (`RareData`), and the
next script parses into it. The slot keeps one arena, and only while the
dead ASTs in it are under 256 KiB. `ShellArgs` measures the arena once,
after the parse, and reports the part the script added as its memory
cost. A script that never finishes, and the shell of `bun run`, drop
their arena as before.
---
 src/jsc/rare_data.rs                      | 22 ++++++
 src/runtime/shell/ParsedShellScript.rs    |  9 +--
 src/runtime/shell/interpreter.rs          | 84 +++++++++++++++--------
 test/js/bun/shell/shell-leak-args.test.ts | 29 ++++++++
 4 files changed, 111 insertions(+), 33 deletions(-)

diff --git a/src/jsc/rare_data.rs b/src/jsc/rare_data.rs
index d9bf6f6bd4d6..45d876ab3a33 100644
--- a/src/jsc/rare_data.rs
+++ b/src/jsc/rare_data.rs
@@ -273,6 +273,8 @@ pub struct RareData {
     websocket_inflate_scratch: Option<Vec<u8>>,
     /// One libdeflate handle for every JS-thread one-shot inflate; see [`Self::libdeflate_decompressor`].
     libdeflate_decompressor: Option<libdeflate::OwnedDecompressor>,
+    /// Arena of the last finished `Bun.$` script and its `allocated_bytes()`; see [`Self::take_shell_arena`].
+    shell_arena: Option<(bun_alloc::Arena, usize)>,
 
     // There is intentionally no `aws_signature_cache` field — storage lives in
     // `bun_s3_signing::credentials::AWS_SIGNATURE_CACHE` (process static; it
@@ -334,6 +336,7 @@ impl Default for RareData {
             compression_scratch: None,
             websocket_inflate_scratch: None,
             libdeflate_decompressor: None,
+            shell_arena: None,
             s3_default_client: Strong::empty(),
             node_quic_callbacks: Strong::empty(),
             default_csrf_secret: Box::default(),
@@ -678,6 +681,25 @@ impl RareData {
         }
     }
 
+    /// Arena for the tokens and AST of one `Bun.$` script, and the `allocated_bytes()` it
+    /// already holds. A `bun_alloc::Arena` is a whole mimalloc heap, and one create/destroy
+    /// pair costs more than a shell builtin takes to run, so a finished script parks its arena
+    /// here and the next script parses into it. By value: scripts overlap, and one that finds
+    /// the slot empty gets a fresh arena.
+    pub fn take_shell_arena(&mut self) -> (bun_alloc::Arena, usize) {
+        self.shell_arena.take().unwrap_or_default()
+    }
+
+    /// Hand a taken arena back with its current `allocated_bytes()`. An arena frees nothing
+    /// until it is destroyed, so the slot keeps the first one returned only while the dead
+    /// ASTs in it are small, and lets a larger one go.
+    pub fn put_back_shell_arena(&mut self, arena: bun_alloc::Arena, allocated_bytes: usize) {
+        const KEEP: usize = 256 * 1024;
+        if self.shell_arena.is_none() && allocated_bytes <= KEEP {
+            self.shell_arena = Some((arena, allocated_bytes));
+        }
+    }
+
     /// libdeflate keeps no state between calls, so one handle serves every one-shot inflate on
     /// this thread. `None` when libdeflate cannot allocate it; callers fall back to zlib.
     pub fn libdeflate_decompressor(&mut self) -> Option<&mut libdeflate::Decompressor> {
diff --git a/src/runtime/shell/ParsedShellScript.rs b/src/runtime/shell/ParsedShellScript.rs
index 7381674211b1..f9541160def7 100644
--- a/src/runtime/shell/ParsedShellScript.rs
+++ b/src/runtime/shell/ParsedShellScript.rs
@@ -204,10 +204,6 @@ fn create_parsed_shell_script_impl(
     callframe: &CallFrame,
     marked_argument_buffer: &mut MarkedArgumentBuffer,
 ) -> JsResult<JSValue> {
-    // Box<ShellArgs> drops automatically on every early `return`/`?` below,
-    // so no scopeguard is needed.
-    let mut shargs: Box<ShellArgs> = ShellArgs::init();
-
     let arguments = callframe.arguments();
     if arguments.len() < 2 {
         return Err(global.throw_not_enough_arguments("Bun.$", 2, arguments.len()));
@@ -233,6 +229,11 @@ fn create_parsed_shell_script_impl(
         marked_argument_buffer,
     )?;
 
+    // Box<ShellArgs> drops automatically on every early `return` below, so no
+    // scopeguard is needed.
+    let (arena, arena_bytes) = global.bun_vm().as_mut().rare_data().take_shell_arena();
+    let mut shargs: Box<ShellArgs> = ShellArgs::init(arena, arena_bytes);
+
     // Reshaped for borrowck — `out_parser`/`out_lex_result` borrow
     // `shargs.__arena`, so they're scoped to a block that ends before
     // `shargs.script_ast = script` below. The arena reference is taken via raw
diff --git a/src/runtime/shell/interpreter.rs b/src/runtime/shell/interpreter.rs
index 1835df18b470..fdba8c8cdb9d 100644
--- a/src/runtime/shell/interpreter.rs
+++ b/src/runtime/shell/interpreter.rs
@@ -355,18 +355,38 @@ impl ShellArgs {
     /// Heap-allocated (returned as `Box`) because the interpreter stores
     /// `Box<ShellArgs>` and state nodes hold `*const ast::*` into the arena;
     /// the box must not move once `parse()` has filled `script_ast`.
-    pub(crate) fn init() -> Box<ShellArgs> {
+    ///
+    /// `arena_bytes` is what `arena.allocated_bytes()` reports: 0 for a new
+    /// arena, or the count `RareData::take_shell_arena` returned with it.
+    pub(crate) fn init(arena: bun_alloc::Arena, arena_bytes: usize) -> Box<ShellArgs> {
         Box::new(ShellArgs {
-            __arena: bun_alloc::Arena::new(),
+            __arena: Some(arena),
+            arena_bytes,
+            ast_bytes: 0,
             // Overwritten by `parse()` before `run()`. An empty stmt list is
             // a safe placeholder.
             script_ast: ast::Script { stmts: &[] },
         })
     }
 
+    /// For the parse only: nothing allocates from the arena after
+    /// [`Self::set_script_ast`] has measured it.
     #[inline]
     pub(crate) fn arena(&self) -> &bun_alloc::Arena {
-        &self.__arena
+        self.__arena
+            .as_ref()
+            .expect("the arena is taken after the script has finished")
+    }
+
+    /// Give up the arena, and the AST with it, once the script has finished.
+    /// Returns the arena with its `allocated_bytes()`, the pair
+    /// `RareData::put_back_shell_arena` takes.
+    pub(crate) fn take_arena(&mut self) -> Option<(bun_alloc::Arena, usize)> {
+        self.script_ast = ast::Script { stmts: &[] };
+        self.ast_bytes = 0;
+        let arena = self.__arena.take()?;
+        debug_assert_eq!(arena.allocated_bytes(), self.arena_bytes);
+        Some((arena, self.arena_bytes))
     }
 
     /// Store the parsed AST root alongside its owning arena. This is the single
@@ -394,14 +414,18 @@ impl ShellArgs {
         let stmts: &'static [ast::Stmt] =
             unsafe { core::slice::from_raw_parts(stmts.as_ptr().cast::<ast::Stmt>(), stmts.len()) };
         self.script_ast = ast::Script { stmts };
+        // `allocated_bytes()` walks the heap's pages, so it runs once per script.
+        let arena_bytes = self.arena().allocated_bytes();
+        self.ast_bytes = arena_bytes.saturating_sub(self.arena_bytes);
+        self.arena_bytes = arena_bytes;
     }
 
-    /// Reports the arena's `allocated_bytes()` (a superset — tokens + strpool
+    /// Reports what the parse added to the arena (a superset — tokens + strpool
     /// + AST nodes). This is for GC `estimatedSize` reporting only, where
     /// over-approximation is preferable to a tree walk on a lifetime-erased
     /// AST mirror.
     pub(crate) fn memory_cost(&self) -> usize {
-        core::mem::size_of::<ShellArgs>() + self.__arena.allocated_bytes()
+        core::mem::size_of::<ShellArgs>() + self.ast_bytes
     }
 }
 
@@ -678,7 +702,7 @@ impl Interpreter {
         // We are the script's shell (`bun run <script>`, `bun exec`, `bun x.sh`).
         bun_spawn::ctrl_c::install();
 
-        let mut shargs = ShellArgs::init();
+        let mut shargs = ShellArgs::init(bun_alloc::Arena::new(), 0);
 
         // ── parse ──────────────────────────────────────────────────────────
         // `out_parser`/`out_lex_result` borrow `shargs.__arena`, so they're
@@ -1484,27 +1508,23 @@ impl Interpreter {
             self.root_shell.with_mut(|rs| rs.deinit_embedded(false));
         }
 
-        // Note: free the parse arena eagerly. `bun_alloc::Arena` is
-        // a `MimallocArena` (a full `mi_heap_t`): every shell parse pulls
-        // several fresh 64 KiB pages, and with `MI_DEBUG=3` each page-init
-        // runs `mi_assert_expensive(mi_mem_is_zero(page, 64 KiB))`. Under the
-        // shell-load.test.ts fixture (30 000 back-to-back `$\`...\`` calls)
-        // those pages are held until JSC finalizes the wrapper, so RSS grows
-        // ~220 KiB per pending interpreter and >50 % of CPU is spent
-        // re-scanning freshly-mmap'd zero pages. Resetting here returns the
-        // pages to mimalloc's pool immediately so subsequent parses reuse them
-        // (`memid.initially_zero == false` → the expensive scan is skipped)
-        // and memory stays flat. The new heap created by `reset()` allocates
-        // no pages until first use, so the per-interpreter footprint left for
-        // the finalizer is just the bare `mi_heap_t`. `script_ast` is cleared
-        // first because every node it references lives in the arena being
-        // destroyed; nothing dereferences it after this point (the only
-        // remaining reader is `memory_cost()`, which queries
-        // `__arena.allocated_bytes()` and never touches the AST).
-        self.args.with_mut(|a| {
-            a.script_ast = ast::Script { stmts: &[] };
-            a.__arena.reset();
-        });
+        // Give the parse arena up now, not when JSC finalizes the wrapper: a
+        // pending interpreter would otherwise hold a whole `mi_heap_t` and its
+        // 64 KiB pages (shell-load.test.ts runs 30 000 back-to-back scripts).
+        // It goes back to the VM so the next script parses into it, because a
+        // heap create/destroy pair per script costs more than a builtin takes
+        // to run. `take_arena` empties `script_ast` first: every node it
+        // references lives in that arena, and nothing dereferences it after
+        // this point.
+        if let Some((arena, arena_bytes)) = self.args.with_mut(|a| a.take_arena())
+            && let Some(global) = self.global_this_ref()
+        {
+            global
+                .bun_vm()
+                .as_mut()
+                .rare_data()
+                .put_back_shell_arena(arena, arena_bytes);
+        }
 
         self.this_jsvalue.set(crate::jsc::JSValue::ZERO);
         self.cleanup_state.set(CleanupState::RuntimeCleaned);
@@ -2156,8 +2176,14 @@ impl ShellExecEnv {
 // ────────────────────────────────────────────────────────────────────────────
 
 pub struct ShellArgs {
-    /// Arena owning the parsed AST nodes, tokens, and string pool.
-    pub(crate) __arena: bun_alloc::Arena,
+    /// Arena owning the parsed AST nodes, tokens, and string pool. `None` once
+    /// [`Self::take_arena`] gave it away; `script_ast` is empty from then on.
+    __arena: Option<bun_alloc::Arena>,
+    /// `allocated_bytes()` of `__arena` after the parse. The arena can come
+    /// with the dead ASTs of earlier scripts (`RareData::take_shell_arena`), so
+    /// `ast_bytes` is the part of it that this script added.
+    arena_bytes: usize,
+    ast_bytes: usize,
     /// Root AST node. State nodes hold `*const ast::*` into this arena.
     pub(crate) script_ast: ast::Script,
 }
diff --git a/test/js/bun/shell/shell-leak-args.test.ts b/test/js/bun/shell/shell-leak-args.test.ts
index f3334a2c4bd4..7bf19a1cf17a 100644
--- a/test/js/bun/shell/shell-leak-args.test.ts
+++ b/test/js/bun/shell/shell-leak-args.test.ts
@@ -1,7 +1,12 @@
 import { $ } from "bun";
+import { heapStats } from "bun:jsc";
 import { expect, test } from "bun:test";
 import { isASAN, rss } from "harness";
 
+// The arena a script is parsed into is a whole mimalloc heap, so this counts
+// the scripts that had to create one.
+const mimallocHeapsCreated = (): number => heapStats().mimalloc.heaps.total;
+
 test("shell parsing error does not leak emmory", async () => {
   const buffer = Buffer.alloc(1024 * 1024, "A").toString();
   for (let i = 0; i < 5; i++) {
@@ -82,3 +87,27 @@ test("non-awaited shell command does not leak argv", async () => {
   // original 250 MiB threshold elsewhere.
   expect(after - before).toBeLessThan(isASAN ? 450 : 250);
 });
+
+test("a finished script gives its parse arena to the next script", async () => {
+  await $`echo warmup`.quiet();
+  const before = mimallocHeapsCreated();
+  for (let i = 0; i < 100; i++) {
+    expect(await $`echo ${i} && true`.text()).toBe(`${i}\n`);
+  }
+  // Two heaps per script when every script creates and destroys its own.
+  expect(mimallocHeapsCreated() - before).toBeLessThan(10);
+});
+
+test("a script larger than the parked arena's cap does not stay in it", async () => {
+  const big = `echo ${Buffer.alloc(1024 * 1024, "bun!").toString()}`;
+  await $`${{ raw: big }}`.quiet();
+  const before = mimallocHeapsCreated();
+  for (let i = 0; i < 10; i++) {
+    await $`${{ raw: big }}`.quiet();
+  }
+  const created = mimallocHeapsCreated() - before;
+  // Each one leaves more than the cap behind, so its arena is destroyed and
+  // the next script starts a new one.
+  expect(created).toBeGreaterThanOrEqual(10);
+  expect(created).toBeLessThan(20);
+});

From fb75bbb890ae349d4a39637069de5ec97c82534b Mon Sep 17 00:00:00 2001
From: robobun <117481402+robobun@users.noreply.github.com>
Date: Wed, 16 Sep 2026 14:52:28 +0000
Subject: [PATCH 2/5] shell: keep the parked arena by what its pages hold

The slot compared the bytes in use with its cap. A script whose lexer
grew and freed large buffers left those free blocks in the parked heap
too: a 100 KiB quoted word left 161 KiB in use and 384 KiB in pages.

`MimallocArena::usage()` reports both numbers from the one walk that
`allocated_bytes()` already did. `ShellArgs` keeps the pair, the memory
cost still comes from the bytes in use, and the slot keeps an arena only
while its pages hold at most 256 KiB.

The comments on `set_script_ast` said that the arena stays with the
interpreter for its whole life. They now say what holds: it stays until
`take_arena` empties `script_ast`.
---
 src/bun_alloc/MimallocArena.rs            | 27 +++++++---
 src/bun_alloc/lib.rs                      |  2 +-
 src/jsc/rare_data.rs                      | 22 +++-----
 src/runtime/shell/ParsedShellScript.rs    |  7 ++-
 src/runtime/shell/interpreter.rs          | 66 +++++++++--------------
 test/js/bun/shell/shell-leak-args.test.ts | 15 +++---
 6 files changed, 67 insertions(+), 72 deletions(-)

diff --git a/src/bun_alloc/MimallocArena.rs b/src/bun_alloc/MimallocArena.rs
index 699c11163438..608e933d627f 100644
--- a/src/bun_alloc/MimallocArena.rs
+++ b/src/bun_alloc/MimallocArena.rs
@@ -50,6 +50,15 @@ fn debug_thread_stamp() -> u64 {
     ID.with(|id| *id)
 }
 
+/// What [`MimallocArena::usage`] measures.
+#[derive(Clone, Copy, Default, Debug, PartialEq, Eq)]
+pub struct ArenaUsage {
+    /// Bytes of the blocks in use.
+    pub allocated: usize,
+    /// Bytes of the blocks, in use or free, that the heap's pages have made available.
+    pub committed: usize,
+}
+
 /// A mimalloc heap. Owns a `mi_heap_t`; all allocations are bulk-freed on
 /// `Drop` via `mi_heap_destroy`.
 ///
@@ -277,6 +286,11 @@ impl MimallocArena {
     /// in this heap. Walks the heap's areas (not its individual blocks); cost
     /// is O(areas), which is cheap. Intended for GC `estimatedSize` reporting.
     pub fn allocated_bytes(&self) -> usize {
+        self.usage().allocated
+    }
+
+    /// One walk of the heap's areas: [`Self::allocated_bytes`] and what the pages hold for it.
+    pub fn usage(&self) -> ArenaUsage {
         extern "C" fn visit(
             _heap: *const mimalloc::Heap,
             area: *const mimalloc::mi_heap_area_t,
@@ -285,24 +299,25 @@ impl MimallocArena {
             arg: *mut c_void,
         ) -> bool {
             // SAFETY: mimalloc passes a valid `area` for each heap area when
-            // `visit_all_blocks == false`; `arg` is the `&mut usize` we passed.
+            // `visit_all_blocks == false`; `arg` is the `&mut ArenaUsage` we passed.
             unsafe {
-                let total = &mut *arg.cast::<usize>();
-                *total += (*area).used.saturating_mul((*area).full_block_size);
+                let usage = &mut *arg.cast::<ArenaUsage>();
+                usage.allocated += (*area).used.saturating_mul((*area).full_block_size);
+                usage.committed += (*area).committed;
             }
             true
         }
-        let mut total: usize = 0;
+        let mut usage = ArenaUsage::default();
         // SAFETY: `self.heap` is live; `visit` upholds the callback contract.
         unsafe {
             mimalloc::mi_heap_visit_blocks(
                 self.heap_ptr(),
                 false,
                 Some(visit),
-                (&raw mut total).cast(),
+                (&raw mut usage).cast(),
             );
         }
-        total
+        usage
     }
 
     /// `mi_heap_malloc[_aligned]` on this
diff --git a/src/bun_alloc/lib.rs b/src/bun_alloc/lib.rs
index 64a4a3b40677..4b716d4e514e 100644
--- a/src/bun_alloc/lib.rs
+++ b/src/bun_alloc/lib.rs
@@ -125,7 +125,7 @@ pub use baby_vec::BabyVec;
 /// through `<&MimallocArena as Allocator>` (= `mi_heap_realloc_aligned` /
 /// `mi_free`); reclaimed on arena `reset`/`Drop`.
 pub type ArenaVec<'a, T> = BabyVec<'a, T>;
-pub use mimalloc_arena::{ArenaString, ArenaVecExt};
+pub use mimalloc_arena::{ArenaString, ArenaUsage, ArenaVecExt};
 
 /// `bumpalo::collections::Vec::from_iter_in` parity for [`ArenaVec`].
 #[inline]
diff --git a/src/jsc/rare_data.rs b/src/jsc/rare_data.rs
index 45d876ab3a33..4a37e38ed758 100644
--- a/src/jsc/rare_data.rs
+++ b/src/jsc/rare_data.rs
@@ -273,8 +273,8 @@ pub struct RareData {
     websocket_inflate_scratch: Option<Vec<u8>>,
     /// One libdeflate handle for every JS-thread one-shot inflate; see [`Self::libdeflate_decompressor`].
     libdeflate_decompressor: Option<libdeflate::OwnedDecompressor>,
-    /// Arena of the last finished `Bun.$` script and its `allocated_bytes()`; see [`Self::take_shell_arena`].
-    shell_arena: Option<(bun_alloc::Arena, usize)>,
+    /// Arena of the last finished `Bun.$` script and its `usage()`; see [`Self::take_shell_arena`].
+    shell_arena: Option<(bun_alloc::Arena, bun_alloc::ArenaUsage)>,
 
     // There is intentionally no `aws_signature_cache` field — storage lives in
     // `bun_s3_signing::credentials::AWS_SIGNATURE_CACHE` (process static; it
@@ -681,22 +681,16 @@ impl RareData {
         }
     }
 
-    /// Arena for the tokens and AST of one `Bun.$` script, and the `allocated_bytes()` it
-    /// already holds. A `bun_alloc::Arena` is a whole mimalloc heap, and one create/destroy
-    /// pair costs more than a shell builtin takes to run, so a finished script parks its arena
-    /// here and the next script parses into it. By value: scripts overlap, and one that finds
-    /// the slot empty gets a fresh arena.
-    pub fn take_shell_arena(&mut self) -> (bun_alloc::Arena, usize) {
+    /// Arena for one `Bun.$` script's parse, with its `usage()`: an arena is a whole mimalloc heap, too costly per script.
+    pub fn take_shell_arena(&mut self) -> (bun_alloc::Arena, bun_alloc::ArenaUsage) {
         self.shell_arena.take().unwrap_or_default()
     }
 
-    /// Hand a taken arena back with its current `allocated_bytes()`. An arena frees nothing
-    /// until it is destroyed, so the slot keeps the first one returned only while the dead
-    /// ASTs in it are small, and lets a larger one go.
-    pub fn put_back_shell_arena(&mut self, arena: bun_alloc::Arena, allocated_bytes: usize) {
+    /// Keeps the first arena returned, and only while its pages (dead ASTs, free blocks) hold at most `KEEP`.
+    pub fn put_back_shell_arena(&mut self, arena: bun_alloc::Arena, usage: bun_alloc::ArenaUsage) {
         const KEEP: usize = 256 * 1024;
-        if self.shell_arena.is_none() && allocated_bytes <= KEEP {
-            self.shell_arena = Some((arena, allocated_bytes));
+        if self.shell_arena.is_none() && usage.committed <= KEEP {
+            self.shell_arena = Some((arena, usage));
         }
     }
 
diff --git a/src/runtime/shell/ParsedShellScript.rs b/src/runtime/shell/ParsedShellScript.rs
index f9541160def7..781883b4f0c6 100644
--- a/src/runtime/shell/ParsedShellScript.rs
+++ b/src/runtime/shell/ParsedShellScript.rs
@@ -229,10 +229,9 @@ fn create_parsed_shell_script_impl(
         marked_argument_buffer,
     )?;
 
-    // Box<ShellArgs> drops automatically on every early `return` below, so no
-    // scopeguard is needed.
-    let (arena, arena_bytes) = global.bun_vm().as_mut().rare_data().take_shell_arena();
-    let mut shargs: Box<ShellArgs> = ShellArgs::init(arena, arena_bytes);
+    // Box<ShellArgs> drops on every early `return` below, so no scopeguard is needed.
+    let (arena, arena_usage) = global.bun_vm().as_mut().rare_data().take_shell_arena();
+    let mut shargs: Box<ShellArgs> = ShellArgs::init(arena, arena_usage);
 
     // Reshaped for borrowck — `out_parser`/`out_lex_result` borrow
     // `shargs.__arena`, so they're scoped to a block that ends before
diff --git a/src/runtime/shell/interpreter.rs b/src/runtime/shell/interpreter.rs
index fdba8c8cdb9d..3e645eecb633 100644
--- a/src/runtime/shell/interpreter.rs
+++ b/src/runtime/shell/interpreter.rs
@@ -355,13 +355,13 @@ impl ShellArgs {
     /// Heap-allocated (returned as `Box`) because the interpreter stores
     /// `Box<ShellArgs>` and state nodes hold `*const ast::*` into the arena;
     /// the box must not move once `parse()` has filled `script_ast`.
-    ///
-    /// `arena_bytes` is what `arena.allocated_bytes()` reports: 0 for a new
-    /// arena, or the count `RareData::take_shell_arena` returned with it.
-    pub(crate) fn init(arena: bun_alloc::Arena, arena_bytes: usize) -> Box<ShellArgs> {
+    pub(crate) fn init(
+        arena: bun_alloc::Arena,
+        arena_usage: bun_alloc::ArenaUsage,
+    ) -> Box<ShellArgs> {
         Box::new(ShellArgs {
             __arena: Some(arena),
-            arena_bytes,
+            arena_usage,
             ast_bytes: 0,
             // Overwritten by `parse()` before `run()`. An empty stmt list is
             // a safe placeholder.
@@ -369,8 +369,7 @@ impl ShellArgs {
         })
     }
 
-    /// For the parse only: nothing allocates from the arena after
-    /// [`Self::set_script_ast`] has measured it.
+    /// For the parse only: [`Self::set_script_ast`] measures the arena, and nothing allocates from it after.
     #[inline]
     pub(crate) fn arena(&self) -> &bun_alloc::Arena {
         self.__arena
@@ -378,22 +377,18 @@ impl ShellArgs {
             .expect("the arena is taken after the script has finished")
     }
 
-    /// Give up the arena, and the AST with it, once the script has finished.
-    /// Returns the arena with its `allocated_bytes()`, the pair
-    /// `RareData::put_back_shell_arena` takes.
-    pub(crate) fn take_arena(&mut self) -> Option<(bun_alloc::Arena, usize)> {
+    /// Gives up the arena, with its `usage()`, and the AST in it: for a script that has finished.
+    pub(crate) fn take_arena(&mut self) -> Option<(bun_alloc::Arena, bun_alloc::ArenaUsage)> {
         self.script_ast = ast::Script { stmts: &[] };
         self.ast_bytes = 0;
         let arena = self.__arena.take()?;
-        debug_assert_eq!(arena.allocated_bytes(), self.arena_bytes);
-        Some((arena, self.arena_bytes))
+        debug_assert_eq!(arena.allocated_bytes(), self.arena_usage.allocated);
+        Some((arena, self.arena_usage))
     }
 
     /// Store the parsed AST root alongside its owning arena. This is the single
     /// self-referential lifetime-erasure point: `script` borrows `self.__arena`
-    /// for `'a`, but `ShellArgs` is heap-allocated and the arena is never moved
-    /// or dropped while the interpreter (and thus every state node holding
-    /// `*const ast::*`) is live. Widening `'a` → `'static` here is therefore
+    /// for `'a`, and the arena stays here until [`Self::take_arena`] empties `script_ast`, so widening to `'static` is
     /// sound — every later dereference happens through raw pointers under
     /// `unsafe`, which is where the real invariant is checked.
     ///
@@ -405,19 +400,17 @@ impl ShellArgs {
     pub(crate) fn set_script_ast(&mut self, script: bun_shell_parser::ast::Script<'_>) {
         // `ast::Script` is `bun_shell_parser::ast::Script<'static>` — identical
         // type, only the lifetime parameter differs. `self.__arena` owns every
-        // node `script.stmts` references and is dropped only when this
-        // `ShellArgs` is, so the widened references remain valid for the
-        // interpreter's lifetime. Re-construct field-by-field via a slice
+        // node `script.stmts` references until `take_arena`, after the last state node is done. Re-construct via a slice
         // pointer cast (`Stmt<'a>` and `Stmt<'static>` are layout-identical).
         let stmts = script.stmts;
-        // SAFETY: lifetime-only widen; arena outlives `self` (see above).
+        // SAFETY: lifetime-only widen; `take_arena` empties `script_ast` before the arena leaves `self`.
         let stmts: &'static [ast::Stmt] =
             unsafe { core::slice::from_raw_parts(stmts.as_ptr().cast::<ast::Stmt>(), stmts.len()) };
         self.script_ast = ast::Script { stmts };
-        // `allocated_bytes()` walks the heap's pages, so it runs once per script.
-        let arena_bytes = self.arena().allocated_bytes();
-        self.ast_bytes = arena_bytes.saturating_sub(self.arena_bytes);
-        self.arena_bytes = arena_bytes;
+        // `usage()` walks the heap's pages, so it runs once per script.
+        let usage = self.arena().usage();
+        self.ast_bytes = usage.allocated.saturating_sub(self.arena_usage.allocated);
+        self.arena_usage = usage;
     }
 
     /// Reports what the parse added to the arena (a superset — tokens + strpool
@@ -702,7 +695,7 @@ impl Interpreter {
         // We are the script's shell (`bun run <script>`, `bun exec`, `bun x.sh`).
         bun_spawn::ctrl_c::install();
 
-        let mut shargs = ShellArgs::init(bun_alloc::Arena::new(), 0);
+        let mut shargs = ShellArgs::init(bun_alloc::Arena::new(), bun_alloc::ArenaUsage::default());
 
         // ── parse ──────────────────────────────────────────────────────────
         // `out_parser`/`out_lex_result` borrow `shargs.__arena`, so they're
@@ -1508,22 +1501,15 @@ impl Interpreter {
             self.root_shell.with_mut(|rs| rs.deinit_embedded(false));
         }
 
-        // Give the parse arena up now, not when JSC finalizes the wrapper: a
-        // pending interpreter would otherwise hold a whole `mi_heap_t` and its
-        // 64 KiB pages (shell-load.test.ts runs 30 000 back-to-back scripts).
-        // It goes back to the VM so the next script parses into it, because a
-        // heap create/destroy pair per script costs more than a builtin takes
-        // to run. `take_arena` empties `script_ast` first: every node it
-        // references lives in that arena, and nothing dereferences it after
-        // this point.
-        if let Some((arena, arena_bytes)) = self.args.with_mut(|a| a.take_arena())
+        // Nothing dereferences the AST after this point: the arena goes to the VM now, not when JSC finalizes the wrapper.
+        if let Some((arena, usage)) = self.args.with_mut(|a| a.take_arena())
             && let Some(global) = self.global_this_ref()
         {
             global
                 .bun_vm()
                 .as_mut()
                 .rare_data()
-                .put_back_shell_arena(arena, arena_bytes);
+                .put_back_shell_arena(arena, usage);
         }
 
         self.this_jsvalue.set(crate::jsc::JSValue::ZERO);
@@ -2176,13 +2162,11 @@ impl ShellExecEnv {
 // ────────────────────────────────────────────────────────────────────────────
 
 pub struct ShellArgs {
-    /// Arena owning the parsed AST nodes, tokens, and string pool. `None` once
-    /// [`Self::take_arena`] gave it away; `script_ast` is empty from then on.
+    /// Arena owning the parsed AST nodes, tokens, and string pool. `None` after [`Self::take_arena`].
     __arena: Option<bun_alloc::Arena>,
-    /// `allocated_bytes()` of `__arena` after the parse. The arena can come
-    /// with the dead ASTs of earlier scripts (`RareData::take_shell_arena`), so
-    /// `ast_bytes` is the part of it that this script added.
-    arena_bytes: usize,
+    /// `__arena.usage()` after the parse; a parked arena comes with the dead ASTs of earlier scripts.
+    arena_usage: bun_alloc::ArenaUsage,
+    /// The part of `arena_usage.allocated` that this script's parse added.
     ast_bytes: usize,
     /// Root AST node. State nodes hold `*const ast::*` into this arena.
     pub(crate) script_ast: ast::Script,
diff --git a/test/js/bun/shell/shell-leak-args.test.ts b/test/js/bun/shell/shell-leak-args.test.ts
index 7bf19a1cf17a..66977f30c301 100644
--- a/test/js/bun/shell/shell-leak-args.test.ts
+++ b/test/js/bun/shell/shell-leak-args.test.ts
@@ -98,16 +98,19 @@ test("a finished script gives its parse arena to the next script", async () => {
   expect(mimallocHeapsCreated() - before).toBeLessThan(10);
 });
 
-test("a script larger than the parked arena's cap does not stay in it", async () => {
-  const big = `echo ${Buffer.alloc(1024 * 1024, "bun!").toString()}`;
-  await $`${{ raw: big }}`.quiet();
+// The cap is on what the arena's pages hold. The second script's AST is under it,
+// but the buffers its lexer grew and freed are not.
+test.each([
+  ["with an AST over the cap", `echo ${Buffer.alloc(1024 * 1024, "bun!").toString()}`],
+  ["that leaves large free blocks", `echo '${Buffer.alloc(100 * 1024, "x").toString()}'`],
+])("the arena of a script %s is not kept", async (_, script) => {
+  await $`${{ raw: script }}`.quiet();
   const before = mimallocHeapsCreated();
   for (let i = 0; i < 10; i++) {
-    await $`${{ raw: big }}`.quiet();
+    await $`${{ raw: script }}`.quiet();
   }
   const created = mimallocHeapsCreated() - before;
-  // Each one leaves more than the cap behind, so its arena is destroyed and
-  // the next script starts a new one.
+  // Its arena is destroyed at finish, and the next script starts a new one.
   expect(created).toBeGreaterThanOrEqual(10);
   expect(created).toBeLessThan(20);
 });

From e5cf7397c28d6435c963e1f08c7943084986e441 Mon Sep 17 00:00:00 2001
From: robobun <117481402+robobun@users.noreply.github.com>
Date: Wed, 16 Sep 2026 15:22:49 +0000
Subject: [PATCH 3/5] test: put the parse arena tests in their own file

The tests in shell-leak-args.test.ts each take seconds on a debug build. The arena tests take 1.3 s together and do not need them.
---
 test/js/bun/shell/shell-leak-args.test.ts   | 32 -------------------
 test/js/bun/shell/shell-parse-arena.test.ts | 34 +++++++++++++++++++++
 2 files changed, 34 insertions(+), 32 deletions(-)
 create mode 100644 test/js/bun/shell/shell-parse-arena.test.ts

diff --git a/test/js/bun/shell/shell-leak-args.test.ts b/test/js/bun/shell/shell-leak-args.test.ts
index 66977f30c301..f3334a2c4bd4 100644
--- a/test/js/bun/shell/shell-leak-args.test.ts
+++ b/test/js/bun/shell/shell-leak-args.test.ts
@@ -1,12 +1,7 @@
 import { $ } from "bun";
-import { heapStats } from "bun:jsc";
 import { expect, test } from "bun:test";
 import { isASAN, rss } from "harness";
 
-// The arena a script is parsed into is a whole mimalloc heap, so this counts
-// the scripts that had to create one.
-const mimallocHeapsCreated = (): number => heapStats().mimalloc.heaps.total;
-
 test("shell parsing error does not leak emmory", async () => {
   const buffer = Buffer.alloc(1024 * 1024, "A").toString();
   for (let i = 0; i < 5; i++) {
@@ -87,30 +82,3 @@ test("non-awaited shell command does not leak argv", async () => {
   // original 250 MiB threshold elsewhere.
   expect(after - before).toBeLessThan(isASAN ? 450 : 250);
 });
-
-test("a finished script gives its parse arena to the next script", async () => {
-  await $`echo warmup`.quiet();
-  const before = mimallocHeapsCreated();
-  for (let i = 0; i < 100; i++) {
-    expect(await $`echo ${i} && true`.text()).toBe(`${i}\n`);
-  }
-  // Two heaps per script when every script creates and destroys its own.
-  expect(mimallocHeapsCreated() - before).toBeLessThan(10);
-});
-
-// The cap is on what the arena's pages hold. The second script's AST is under it,
-// but the buffers its lexer grew and freed are not.
-test.each([
-  ["with an AST over the cap", `echo ${Buffer.alloc(1024 * 1024, "bun!").toString()}`],
-  ["that leaves large free blocks", `echo '${Buffer.alloc(100 * 1024, "x").toString()}'`],
-])("the arena of a script %s is not kept", async (_, script) => {
-  await $`${{ raw: script }}`.quiet();
-  const before = mimallocHeapsCreated();
-  for (let i = 0; i < 10; i++) {
-    await $`${{ raw: script }}`.quiet();
-  }
-  const created = mimallocHeapsCreated() - before;
-  // Its arena is destroyed at finish, and the next script starts a new one.
-  expect(created).toBeGreaterThanOrEqual(10);
-  expect(created).toBeLessThan(20);
-});
diff --git a/test/js/bun/shell/shell-parse-arena.test.ts b/test/js/bun/shell/shell-parse-arena.test.ts
new file mode 100644
index 000000000000..268ec657e7ad
--- /dev/null
+++ b/test/js/bun/shell/shell-parse-arena.test.ts
@@ -0,0 +1,34 @@
+import { $ } from "bun";
+import { heapStats } from "bun:jsc";
+import { expect, test } from "bun:test";
+
+// The arena a script is parsed into is a whole mimalloc heap, so this counts
+// the scripts that had to create one.
+const mimallocHeapsCreated = (): number => heapStats().mimalloc.heaps.total;
+
+test("a finished script gives its parse arena to the next script", async () => {
+  await $`echo warmup`.quiet();
+  const before = mimallocHeapsCreated();
+  for (let i = 0; i < 100; i++) {
+    expect(await $`echo ${i} && true`.text()).toBe(`${i}\n`);
+  }
+  // Two heaps per script when every script creates and destroys its own.
+  expect(mimallocHeapsCreated() - before).toBeLessThan(10);
+});
+
+// The cap is on what the arena's pages hold. The second script's AST is under it,
+// but the buffers its lexer grew and freed are not.
+test.each([
+  ["with an AST over the cap", `echo ${Buffer.alloc(1024 * 1024, "bun!").toString()}`],
+  ["that leaves large free blocks", `echo '${Buffer.alloc(100 * 1024, "x").toString()}'`],
+])("the arena of a script %s is not kept", async (_, script) => {
+  await $`${{ raw: script }}`.quiet();
+  const before = mimallocHeapsCreated();
+  for (let i = 0; i < 10; i++) {
+    await $`${{ raw: script }}`.quiet();
+  }
+  const created = mimallocHeapsCreated() - before;
+  // Its arena is destroyed at finish, and the next script starts a new one.
+  expect(created).toBeGreaterThanOrEqual(10);
+  expect(created).toBeLessThan(20);
+});

From 296c9e7d520d1b01b20ac88ea2f5e6e739a3179c Mon Sep 17 00:00:00 2001
From: robobun <117481402+robobun@users.noreply.github.com>
Date: Wed, 16 Sep 2026 15:48:06 +0000
Subject: [PATCH 4/5] test: keep the parse arena tests in
 shell-leak-args.test.ts

That file holds the other tests for what a parsed script keeps in memory.
---
 test/js/bun/shell/shell-leak-args.test.ts   | 32 +++++++++++++++++++
 test/js/bun/shell/shell-parse-arena.test.ts | 34 ---------------------
 2 files changed, 32 insertions(+), 34 deletions(-)
 delete mode 100644 test/js/bun/shell/shell-parse-arena.test.ts

diff --git a/test/js/bun/shell/shell-leak-args.test.ts b/test/js/bun/shell/shell-leak-args.test.ts
index f3334a2c4bd4..66977f30c301 100644
--- a/test/js/bun/shell/shell-leak-args.test.ts
+++ b/test/js/bun/shell/shell-leak-args.test.ts
@@ -1,7 +1,12 @@
 import { $ } from "bun";
+import { heapStats } from "bun:jsc";
 import { expect, test } from "bun:test";
 import { isASAN, rss } from "harness";
 
+// The arena a script is parsed into is a whole mimalloc heap, so this counts
+// the scripts that had to create one.
+const mimallocHeapsCreated = (): number => heapStats().mimalloc.heaps.total;
+
 test("shell parsing error does not leak emmory", async () => {
   const buffer = Buffer.alloc(1024 * 1024, "A").toString();
   for (let i = 0; i < 5; i++) {
@@ -82,3 +87,30 @@ test("non-awaited shell command does not leak argv", async () => {
   // original 250 MiB threshold elsewhere.
   expect(after - before).toBeLessThan(isASAN ? 450 : 250);
 });
+
+test("a finished script gives its parse arena to the next script", async () => {
+  await $`echo warmup`.quiet();
+  const before = mimallocHeapsCreated();
+  for (let i = 0; i < 100; i++) {
+    expect(await $`echo ${i} && true`.text()).toBe(`${i}\n`);
+  }
+  // Two heaps per script when every script creates and destroys its own.
+  expect(mimallocHeapsCreated() - before).toBeLessThan(10);
+});
+
+// The cap is on what the arena's pages hold. The second script's AST is under it,
+// but the buffers its lexer grew and freed are not.
+test.each([
+  ["with an AST over the cap", `echo ${Buffer.alloc(1024 * 1024, "bun!").toString()}`],
+  ["that leaves large free blocks", `echo '${Buffer.alloc(100 * 1024, "x").toString()}'`],
+])("the arena of a script %s is not kept", async (_, script) => {
+  await $`${{ raw: script }}`.quiet();
+  const before = mimallocHeapsCreated();
+  for (let i = 0; i < 10; i++) {
+    await $`${{ raw: script }}`.quiet();
+  }
+  const created = mimallocHeapsCreated() - before;
+  // Its arena is destroyed at finish, and the next script starts a new one.
+  expect(created).toBeGreaterThanOrEqual(10);
+  expect(created).toBeLessThan(20);
+});
diff --git a/test/js/bun/shell/shell-parse-arena.test.ts b/test/js/bun/shell/shell-parse-arena.test.ts
deleted file mode 100644
index 268ec657e7ad..000000000000
--- a/test/js/bun/shell/shell-parse-arena.test.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import { $ } from "bun";
-import { heapStats } from "bun:jsc";
-import { expect, test } from "bun:test";
-
-// The arena a script is parsed into is a whole mimalloc heap, so this counts
-// the scripts that had to create one.
-const mimallocHeapsCreated = (): number => heapStats().mimalloc.heaps.total;
-
-test("a finished script gives its parse arena to the next script", async () => {
-  await $`echo warmup`.quiet();
-  const before = mimallocHeapsCreated();
-  for (let i = 0; i < 100; i++) {
-    expect(await $`echo ${i} && true`.text()).toBe(`${i}\n`);
-  }
-  // Two heaps per script when every script creates and destroys its own.
-  expect(mimallocHeapsCreated() - before).toBeLessThan(10);
-});
-
-// The cap is on what the arena's pages hold. The second script's AST is under it,
-// but the buffers its lexer grew and freed are not.
-test.each([
-  ["with an AST over the cap", `echo ${Buffer.alloc(1024 * 1024, "bun!").toString()}`],
-  ["that leaves large free blocks", `echo '${Buffer.alloc(100 * 1024, "x").toString()}'`],
-])("the arena of a script %s is not kept", async (_, script) => {
-  await $`${{ raw: script }}`.quiet();
-  const before = mimallocHeapsCreated();
-  for (let i = 0; i < 10; i++) {
-    await $`${{ raw: script }}`.quiet();
-  }
-  const created = mimallocHeapsCreated() - before;
-  // Its arena is destroyed at finish, and the next script starts a new one.
-  expect(created).toBeGreaterThanOrEqual(10);
-  expect(created).toBeLessThan(20);
-});

From 5beed9ad03ab7a638a1ea82d6ca0e53b21b83efa Mon Sep 17 00:00:00 2001
From: robobun <117481402+robobun@users.noreply.github.com>
Date: Wed, 16 Sep 2026 16:07:20 +0000
Subject: [PATCH 5/5] test: a script that fails to parse does not keep the
 arena

---
 test/js/bun/shell/shell-leak-args.test.ts | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/test/js/bun/shell/shell-leak-args.test.ts b/test/js/bun/shell/shell-leak-args.test.ts
index 66977f30c301..e67759dc2a56 100644
--- a/test/js/bun/shell/shell-leak-args.test.ts
+++ b/test/js/bun/shell/shell-leak-args.test.ts
@@ -114,3 +114,16 @@ test.each([
   expect(created).toBeGreaterThanOrEqual(10);
   expect(created).toBeLessThan(20);
 });
+
+test("the arena of a script that fails to parse is not kept", async () => {
+  await $`echo warmup`.quiet();
+  const before = mimallocHeapsCreated();
+  for (let i = 0; i < 10; i++) {
+    expect(() => $`echo ${i} <!INVALID ==== SYNTAX!>`).toThrow("Redirection with no file");
+    await $`echo ${i}`.quiet();
+  }
+  const created = mimallocHeapsCreated() - before;
+  // The failed parse destroys the arena it took, and the script after it starts a new one.
+  expect(created).toBeGreaterThanOrEqual(10);
+  expect(created).toBeLessThan(20);
+});