@liquidmetal-ai/precip 1.0.0

package/src/sandbox/sandbox.ts

@@ -0,0 +1,831 @@
+/**
+ * Sandbox - Singleton QuickJS sandbox with queued execution
+ *
+ * Provides a single QuickJS context per worker to limit memory usage (64MB).
+ * Concurrent executions are queued so only one runs at a time.
+ *
+ * Key features:
+ * - Singleton pattern - one sandbox per worker (safe under concurrent await)
+ * - Execution queue - concurrent calls wait their turn
+ * - Context recreated per execution for clean state (future: reuse with global reset)
+ * - Proper cleanup - dispose() when done (e.g., actor eviction)
+ *
+ * ## Security Model
+ *
+ * The sandbox is **NOT** a hard security boundary. It provides:
+ * - **Isolation:** Untrusted code runs in a separate QuickJS context
+ * - **Memory limits:** 64MB limit per context prevents memory exhaustion attacks
+ * - **Controlled API access:** Bridges (fetch, storage, etc.) mediate access to host resources
+ *
+ * The sandbox does **NOT** provide:
+ * - Unbreakable code containment: Sandbox code can call internal helpers if it knows their names
+ * - Sandboxing against determined attackers: Code can attempt to break out via QuickJS bugs
+ * - Complete encapsulation: Internal globals are hidden but still callable (enumerable: false)
+ *
+ * For the use case of safely executing LLM-generated code with controlled resource access,
+ * this security model is sufficient. The bridges are the primary security boundary.
+ *
+ * Usage:
+ *   await Sandbox.configure({ memoryLimitBytes: 64 * 1024 * 1024 });
+ *   const sandbox = await Sandbox.getInstance();
+ *   const result = await sandbox.execute(code, globals, options);
+ *   await sandbox.dispose(); // Call when shutting down (actor eviction)
+ */
+
+import RELEASE_SYNC_NG from '@jitl/quickjs-ng-wasmfile-release-sync';
+import type { QuickJSContext, QuickJSHandle } from 'quickjs-emscripten-core';
+import { newQuickJSWASMModuleFromVariant, newVariant, isFail } from 'quickjs-emscripten-core';
+// Import the .wasm file so the build plugin (esbuild) copies it to the output.
+// In Raindrop, this resolves to a pre-compiled WebAssembly.Module.
+// In Node.js/tests, this is stubbed out (the library loads WASM from disk automatically).
+// @ts-expect-error - No type definitions for .wasm file
+import wasmModule from '@jitl/quickjs-ng-wasmfile-release-sync/wasm';
+import type {
+  SandboxResult,
+  SandboxGlobals,
+  SandboxGlobal,
+  AsyncSandboxGlobal,
+  SyncSandboxGlobal,
+  ObjectSandboxGlobal,
+  Logger,
+  SandboxOptions
+} from '../types.js';
+import {
+  createPromiseTracker,
+  installAllBridges,
+  runCleanupHandlers,
+  convertToHandle,
+  getConsoleOutput,
+  createAsyncBridge,
+  createSyncBridge
+} from './bridges/index.js';
+import type { PromiseTracker, BridgeContext, BridgeInstaller } from './bridges/types.js';
+
+/**
+ * Queued execution request
+ */
+interface QueuedExecution {
+  code: string;
+  globals: SandboxGlobals;
+  options: SandboxOptions;
+  resolve: (result: SandboxResult) => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Safely stringify a value, handling circular references and other edge cases.
+ * Returns the stringified value or a fallback string representation.
+ */
+function safeStringify(obj: any): string {
+  try {
+    return JSON.stringify(obj) ?? String(obj);
+  } catch {
+    return String(obj);
+  }
+}
+
+// Singleton module instance
+let syncModulePromise: Promise<any> | null = null;
+
+async function getSyncModule() {
+  if (!syncModulePromise) {
+    syncModulePromise = (async () => {
+      // In Raindrop, `wasmModule` is a pre-compiled WebAssembly.Module
+      // from the static import. Pass it so the runtime can instantiate it directly.
+      // In Node.js/tests, `wasmModule` is undefined (stubbed out), so we omit it
+      // and let the library locate and load the .wasm file from disk automatically.
+      const variantOptions: Record<string, unknown> = {};
+      if (wasmModule instanceof WebAssembly.Module) {
+        variantOptions.wasmModule = wasmModule;
+      }
+      const variant = newVariant(RELEASE_SYNC_NG, variantOptions);
+      return newQuickJSWASMModuleFromVariant(variant);
+    })();
+  }
+  return syncModulePromise;
+}
+
+/**
+ * Singleton QuickJS sandbox with queued execution
+ */
+export class Sandbox {
+  /** Resolved instance — checked first so steady-state calls never await a cross-request promise */
+  private static instance: Sandbox | null = null;
+
+  /** True while configure() is in-flight. Used for synchronous conflict detection. */
+  private static configuring: boolean = false;
+
+  private context: QuickJSContext | undefined;
+  private runtime: any;
+  private disposed: boolean = false;
+  private executionQueue: QueuedExecution[] = [];
+  private isExecuting: boolean = false;
+  private memoryLimitBytes: number;
+  private leakCount: number = 0;
+  private static readonly MAX_QUEUE_DEPTH = 100;
+  private static readonly MAX_LEAKS_BEFORE_RESET = 5;
+
+  /** Timeout in milliseconds (default for executions that don't specify one) */
+  private timeoutMs: number;
+
+  /** Custom bridge installers (provided at configure time, applied each execution) */
+  private bridgeInstallers: BridgeInstaller[];
+
+  private constructor(options: SandboxOptions = {}) {
+    this.timeoutMs = options.timeoutMs || 30000;
+    this.memoryLimitBytes = options.memoryLimitBytes || 64 * 1024 * 1024;
+    this.bridgeInstallers = options.bridgeInstallers || [];
+  }
+
+  /**
+   * Check whether the singleton is ready (synchronous, no promises).
+   *
+   * Use this in Raindrop to avoid awaiting cross-request promises.
+   */
+  static isConfigured(): boolean {
+    return Sandbox.instance !== null;
+  }
+
+  /**
+   * Check whether configure() is currently in-flight (synchronous).
+   */
+  static isConfiguring(): boolean {
+    return Sandbox.configuring;
+  }
+
+  /**
+   * Configure and create the singleton Sandbox instance.
+   *
+   * Must be called exactly once (typically in blockConcurrencyWhile).
+   * After this, use getInstance() to retrieve the sandbox.
+   *
+   *   state.blockConcurrencyWhile(async () => {
+   *     await Sandbox.configure({ memoryLimitBytes: 64 * 1024 * 1024 });
+   *   });
+   *
+   * @throws Error if the sandbox has already been configured
+   */
+  static async configure(options: SandboxOptions = {}): Promise<Sandbox> {
+    if (Sandbox.instance) {
+      const logger = options.logger;
+      logger?.warn?.(
+        '[Sandbox] configure() called but instance already exists. ' +
+        'Returning existing instance. Call Sandbox.reset() first to reconfigure with different options.'
+      );
+      return Sandbox.instance;
+    }
+
+    if (Sandbox.configuring) {
+      throw new Error(
+        'Sandbox is currently being configured by another caller.'
+      );
+    }
+
+    Sandbox.configuring = true;
+    try {
+      const sandbox = new Sandbox(options);
+      await sandbox.initialize();
+      Sandbox.instance = sandbox;
+      return sandbox;
+    } finally {
+      Sandbox.configuring = false;
+    }
+  }
+
+  /**
+   * Get the singleton Sandbox instance.
+   *
+   * Returns the resolved instance if configured. Never returns a pending
+   * promise from another request context — safe for Raindrop.
+   *
+   * @throws Error if the sandbox has not been configured yet
+   */
+  static async getInstance(): Promise<Sandbox> {
+    if (Sandbox.instance) {
+      return Sandbox.instance;
+    }
+
+    throw new Error(
+      'Sandbox has not been configured. Call Sandbox.configure(options) first.'
+    );
+  }
+
+  /**
+   * Initialize the QuickJS context and runtime
+   */
+  private async initialize(): Promise<void> {
+    if (this.disposed) {
+      throw new Error('Sandbox has been disposed');
+    }
+
+    const module = await getSyncModule();
+    this.runtime = module.newRuntime();
+    this.context = this.runtime.newContext();
+
+    // Set memory limit
+    this.runtime.setMemoryLimit(this.memoryLimitBytes);
+  }
+
+  /**
+   * Execute code in the sandbox with async support
+   *
+   * If another execution is in progress, this call waits in a queue.
+   * Logger is per-execution — pass it in options so each request gets its own context.
+   */
+  async execute(
+    code: string,
+    globals: SandboxGlobals = {},
+    options: SandboxOptions = {}
+  ): Promise<SandboxResult> {
+    if (this.disposed) {
+      throw new Error('Sandbox has been disposed');
+    }
+
+    if (!this.context) {
+      throw new Error('Sandbox not initialized');
+    }
+
+    // Reject if queue is full to prevent unbounded memory growth
+    if (this.executionQueue.length >= Sandbox.MAX_QUEUE_DEPTH) {
+      throw new Error(
+        `Sandbox execution queue is full (${Sandbox.MAX_QUEUE_DEPTH} pending). Too many concurrent requests.`
+      );
+    }
+
+    // Queue the execution if another is running
+    return new Promise<SandboxResult>((resolve, reject) => {
+      this.executionQueue.push({
+        code,
+        globals,
+        options,
+        resolve,
+        reject
+      });
+
+      this.processQueue();
+    });
+  }
+
+  /**
+   * Process the execution queue
+   */
+  private async processQueue(): Promise<void> {
+    if (this.isExecuting || this.executionQueue.length === 0) {
+      return;
+    }
+
+    this.isExecuting = true;
+
+    try {
+      while (this.executionQueue.length > 0) {
+        const execution = this.executionQueue.shift()!;
+
+        try {
+          const result = await this.runExecution(
+            execution.code,
+            execution.globals,
+            execution.options
+          );
+          execution.resolve(result);
+        } catch (error) {
+          execution.reject(error as Error);
+        }
+      }
+    } finally {
+      this.isExecuting = false;
+    }
+
+    // Re-check: items may have been queued between the while-loop's last
+    // check and the finally block setting isExecuting = false. Without this,
+    // the newly queued item's processQueue() call would have seen
+    // isExecuting = true and returned early — leaving it stranded.
+    if (this.executionQueue.length > 0) {
+      this.processQueue();
+    }
+  }
+
+  /**
+   * Run a single execution (internal - assumes we have exclusive access to context)
+   */
+  private async runExecution(
+    code: string,
+    asyncGlobals: SandboxGlobals,
+    options: SandboxOptions
+  ): Promise<SandboxResult> {
+    // Logger is per-execution so each request gets its own logger context
+    const logger = options.logger;
+    const startTime = Date.now();
+    const timeoutMs = options.timeoutMs || this.timeoutMs;
+    const deadline = Date.now() + timeoutMs;
+
+    // Set interrupt handler for this execution's timeout
+    this.runtime.setInterruptHandler(() => Date.now() > deadline);
+
+    // Create per-execution promise tracker
+    const tracker = createPromiseTracker();
+
+    // Cleanup handlers for bridges (abort streams, etc.)
+    const cleanupHandlers: Array<() => void | Promise<void>> = [];
+
+    try {
+      // Install all bridges (fetch, TextEncoder, TextDecoder, ReadableStream)
+      const bridgeCtx: BridgeContext = {
+        context: this.context!,
+        runtime: this.runtime,
+        tracker,
+        logger,
+        cleanupHandlers
+      };
+      installAllBridges(bridgeCtx);
+
+      // Install custom bridges (only those provided at configure time, plus per-execution ones)
+      const allBridgeInstallers = [...this.bridgeInstallers];
+      if (options.bridgeInstallers) {
+        allBridgeInstallers.push(...options.bridgeInstallers);
+      }
+
+      for (const installer of allBridgeInstallers) {
+        try {
+          const cleanup = installer(bridgeCtx);
+          if (typeof cleanup === 'function') {
+            cleanupHandlers.push(cleanup);
+          }
+        } catch (e) {
+          logger?.error?.(`[Sandbox] Bridge installer failed: ${e}`);
+          throw new Error(`Bridge installer failed: ${e}`);
+        }
+      }
+
+      // Inject async globals with promise tracking
+      for (const [key, value] of Object.entries(asyncGlobals || {})) {
+        this.injectGlobal(key, value, tracker, cleanupHandlers, logger);
+      }
+
+      // Wrap in async IIFE so they can use await
+      const wrappedCode = `
+        (async () => {
+          ${code}
+        })()
+      `;
+
+      // evalCode returns a promise handle immediately (sync call!)
+      const evalResult = this.context!.evalCode(wrappedCode);
+
+      if (isFail(evalResult)) {
+        const error = this.context!.dump(evalResult.error);
+        evalResult.error.dispose();
+        throw new Error(`Evaluation error: ${JSON.stringify(error)}`);
+      }
+
+      const promiseHandle = evalResult.value;
+
+      // Wait for the promise using Promise.race optimization
+      const result = await this.racePromise(promiseHandle, tracker, timeoutMs, logger);
+
+      const executionTime = Date.now() - startTime;
+
+      // Get console output before disposing context
+      const consoleOutput = this.context ? getConsoleOutput(this.context) : undefined;
+
+      return {
+        success: true,
+        result,
+        consoleOutput,
+        executionTime
+      };
+    } catch (error) {
+      const executionTime = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      logger?.error?.('[Sandbox] Execution failed', error);
+
+      // Get console output even on error
+      const consoleOutput = this.context ? getConsoleOutput(this.context) : undefined;
+
+      return {
+        success: false,
+        error: errorMessage,
+        executionTime,
+        consoleOutput
+      };
+    } finally {
+      await this.cleanupExecution(tracker, cleanupHandlers, logger);
+    }
+  }
+
+  /**
+   * Inject a global value into the sandbox
+   */
+  private injectGlobal(key: string, value: SandboxGlobal, tracker: PromiseTracker, cleanupHandlers: Array<() => void | Promise<void>>, logger?: Logger): void {
+    // Typed globals with explicit kind
+    if (value !== null && value !== undefined && typeof value === 'object' && 'kind' in value) {
+      const typed = value as AsyncSandboxGlobal | SyncSandboxGlobal | ObjectSandboxGlobal;
+      const bridgeCtx: BridgeContext = {
+        context: this.context!,
+        runtime: this.runtime,
+        tracker,
+        logger,
+        cleanupHandlers
+      };
+
+      if (typed.kind === 'async') {
+        using fnHandle = createAsyncBridge(bridgeCtx, key, typed.fn);
+        this.context!.setProp(this.context!.global, key, fnHandle);
+      } else if (typed.kind === 'sync') {
+        using fnHandle = createSyncBridge(bridgeCtx, key, typed.fn);
+        this.context!.setProp(this.context!.global, key, fnHandle);
+      } else if (typed.kind === 'object') {
+        using objHandle = this.context!.newObject();
+
+        // Install typed methods
+        for (const [methodName, method] of Object.entries(typed.methods)) {
+          using methodHandle = method.kind === 'async'
+            ? createAsyncBridge(bridgeCtx, methodName, method.fn)
+            : createSyncBridge(bridgeCtx, methodName, method.fn);
+          this.context!.setProp(objHandle, methodName, methodHandle);
+        }
+
+        // Install static properties
+        if (typed.properties) {
+          for (const [propName, propValue] of Object.entries(typed.properties)) {
+            using propHandle = convertToHandle(this.context!, propValue);
+            this.context!.setProp(objHandle, propName, propHandle);
+          }
+        }
+
+        this.context!.setProp(this.context!.global, key, objHandle);
+      }
+    } else {
+      // Primitive value (number, string, boolean, null, undefined) or plain array/object
+      using handle = convertToHandle(this.context!, value);
+      this.context!.setProp(this.context!.global, key, handle);
+    }
+  }
+
+  /**
+   * Race loop to wait for promise resolution
+   */
+  private async racePromise(
+    promiseHandle: QuickJSHandle,
+    tracker: PromiseTracker,
+    timeoutMs: number,
+    _logger?: Logger
+  ): Promise<any> {
+    return new Promise<any>((resolve, reject) => {
+      const startWait = Date.now();
+
+      const raceLoop = async () => {
+        try {
+          // Short-circuit if sandbox was disposed while we were awaiting
+          if (this.disposed) {
+            try { promiseHandle.dispose(); } catch { /* already disposed */ }
+            reject(new Error('Sandbox has been disposed'));
+            return;
+          }
+
+          // Check timeout
+          if (Date.now() - startWait > timeoutMs) {
+            promiseHandle.dispose();
+            reject(new Error('Execution timeout'));
+            return;
+          }
+
+          // Check if main promise is already resolved
+          this.runtime.executePendingJobs();
+
+          // Get promise state with error handling
+          let state;
+          try {
+            state = this.context!.getPromiseState(promiseHandle);
+          } catch (e) {
+            promiseHandle.dispose();
+            reject(new Error(`Failed to check promise state: ${e}`));
+            return;
+          }
+
+          if (state.type === 'fulfilled') {
+            const value = this.context!.dump(state.value);
+            state.value.dispose();
+            promiseHandle.dispose();
+            resolve(value);
+            return;
+          } else if (state.type === 'rejected') {
+            const error = this.context!.dump(state.error);
+            state.error.dispose();
+            promiseHandle.dispose();
+            const errorStr =
+              typeof error === 'string'
+                ? error
+                : error?.message || safeStringify(error) || String(error);
+            reject(new Error(`Promise rejected: ${errorStr}`));
+            return;
+          }
+
+          // Still pending - create fresh race signal
+          tracker.newPromiseSignal = new Promise<void>(resolve => {
+            tracker.notifyNewPromise = resolve;
+          });
+
+          const racers: Promise<any>[] = [
+            ...Array.from(tracker.pendingPromises),
+            tracker.newPromiseSignal,
+            new Promise(r => setTimeout(r, 100)) // Safety timeout
+          ];
+
+          await Promise.race(racers);
+
+          queueMicrotask(() => raceLoop());
+        } catch (e) {
+          // Unexpected error — dispose handle to prevent leak
+          try { promiseHandle.dispose(); } catch { /* already disposed */ }
+          reject(e instanceof Error ? e : new Error(String(e)));
+        }
+      };
+
+      raceLoop();
+    });
+  }
+
+  /**
+   * Cleanup after an execution
+   *
+   * Recreates context after each execution to ensure clean state.
+   * Future optimization: reset globals instead of full recreation.
+   */
+  private async cleanupExecution(
+    tracker: PromiseTracker,
+    cleanupHandlers: Array<() => void | Promise<void>>,
+    logger?: Logger
+  ): Promise<void> {
+    // STEP 1: Run bridge cleanup handlers
+    try {
+      await runCleanupHandlers(cleanupHandlers, logger);
+    } catch (e) {
+      logger?.warn?.('[Sandbox] Bridge cleanup failed: ' + e);
+    }
+
+    // STEP 1.5: Flush microtasks
+    try {
+      await new Promise<void>(resolve => queueMicrotask(resolve));
+      this.runtime.executePendingJobs();
+    } catch {
+      // Ignore
+    }
+
+    // STEP 2: Wait for all pending promises to settle
+    try {
+      const pendingPromises = Array.from(tracker.pendingPromises);
+
+      if (pendingPromises.length > 0) {
+        await Promise.race([
+          Promise.allSettled(pendingPromises),
+          new Promise(resolve => setTimeout(resolve, 3000))
+        ]);
+      }
+    } catch (e) {
+      logger?.warn?.('[Sandbox] Error waiting for promises: ' + e);
+    }
+
+    // STEP 2.5: Execute pending jobs after promises settle
+    try {
+      this.runtime.executePendingJobs();
+    } catch {
+      // Ignore
+    }
+
+    // STEP 3: Settle any remaining deferred promises
+    try {
+      for (const deferred of tracker.deferredPromises) {
+        try {
+          if (deferred?.handle && deferred.handle.alive) {
+            const state = this.context!.getPromiseState(deferred.handle);
+            if (state.type === 'pending') {
+              const cleanupError = this.context!.newString('Sandbox cleanup - promise cancelled');
+              deferred.reject(cleanupError);
+              cleanupError.dispose();
+              this.runtime.executePendingJobs();
+            }
+          }
+        } catch {
+          // Ignore
+        }
+      }
+    } catch (e) {
+      logger?.warn?.('[Sandbox] Error settling deferred promises: ' + e);
+    }
+
+    // STEP 4: Drain job queue
+    try {
+      let iterations = 0;
+      const maxIterations = 1000;
+      const drainDeadline = Date.now() + 1000;
+
+      while (iterations < maxIterations && Date.now() < drainDeadline) {
+        try {
+          const result = this.runtime.executePendingJobs();
+
+          if ('error' in result && result.error) {
+            logger?.warn?.('[Sandbox] Error executing pending jobs');
+            try {
+              result.error.dispose();
+            } catch {
+              // Ignore
+            }
+            break;
+          }
+
+          if ('value' in result && result.value === 0) {
+            break;
+          }
+
+          iterations++;
+        } catch {
+          break;
+        }
+      }
+    } catch (e) {
+      logger?.warn?.('[Sandbox] Error draining job queue: ' + e);
+    }
+
+    // STEP 5: Dispose deferred promise handles
+    try {
+      for (const deferred of tracker.deferredPromises) {
+        try {
+          if (deferred?.handle && deferred.handle.alive) {
+            deferred.handle.dispose();
+          }
+        } catch (e) {
+          logger?.warn?.('[Sandbox] Error disposing promise handle: ' + e);
+        }
+      }
+      tracker.deferredPromises.clear();
+    } catch (e) {
+      logger?.warn?.('[Sandbox] Error disposing promise handles: ' + e);
+    }
+
+    // STEP 6: Final job drain after handle disposal
+    try {
+      let iterations = 0;
+      const finalDrainDeadline = Date.now() + 500;
+
+      while (iterations < 100 && Date.now() < finalDrainDeadline) {
+        try {
+          const result = this.runtime.executePendingJobs();
+
+          if ('error' in result && result.error) {
+            logger?.warn?.('[Sandbox] Error in final drain');
+            try {
+              result.error.dispose();
+            } catch {
+              // Ignore
+            }
+            break;
+          }
+
+          if ('value' in result && result.value === 0) {
+            break;
+          }
+
+          iterations++;
+        } catch {
+          break;
+        }
+      }
+    } catch (e) {
+      logger?.warn?.('[Sandbox] Error in final drain: ' + e);
+    }
+
+    // STEP 7: Dispose context, reuse runtime
+    //
+    // The runtime holds the WASM instance and is expensive to recreate.
+    // We dispose only the context (cheap) and create a fresh one on the
+    // same runtime.  If lingering GC objects prevent a clean context
+    // disposal, we recycle the entire runtime rather than leaking it.
+    try {
+      this.context?.dispose();
+      this.context = undefined;
+    } catch (e) {
+      logger?.warn?.('[Sandbox] Error disposing context: ' + e);
+      this.context = undefined;
+    }
+
+    // Check if the runtime has lingering GC objects after context disposal.
+    // If so, the runtime is in a bad state — force-dispose and recreate it.
+    let needsRuntimeRecycle = false;
+    try {
+      const memUsage = this.runtime.dumpMemoryUsage();
+      const gcObjectPattern = /^\s+\d+\s+(resolve|promise)\s*$/m;
+      if (gcObjectPattern.test(memUsage)) {
+        needsRuntimeRecycle = true;
+        logger?.warn?.(
+          '[Sandbox] Lingering GC objects detected after context disposal, recycling runtime'
+        );
+      }
+    } catch {
+      // Can't inspect runtime state — recycle to be safe
+      needsRuntimeRecycle = true;
+    }
+
+    if (needsRuntimeRecycle) {
+      try {
+        this.runtime?.dispose();
+      } catch {
+        // QuickJS assertion may fire here — that's OK, memory is still reclaimed
+      }
+      this.runtime = undefined;
+    }
+
+    // STEP 8: Recreate context (and runtime if it was recycled)
+    try {
+      await this.recreateContext();
+    } catch (error) {
+      // Context recreation failed — mark as disposed so configure() creates a fresh one.
+      // Reject any remaining queued executions immediately so they don't wait
+      // for a sandbox that will never recover.
+      logger?.error?.('[Sandbox] Failed to recreate context, marking sandbox as disposed', error);
+      this.disposed = true;
+      Sandbox.instance = null;
+      Sandbox.configuring = false;
+      for (const execution of this.executionQueue) {
+        execution.reject(new Error('Sandbox has been disposed: context recreation failed'));
+      }
+      this.executionQueue = [];
+      throw error;
+    }
+  }
+
+  /**
+   * Recreate the QuickJS context for the next execution.
+   *
+   * Reuses the existing runtime when possible (fast path).
+   * If the runtime was recycled due to lingering GC objects, creates a new one.
+   */
+  private async recreateContext(): Promise<void> {
+    if (this.disposed) {
+      return;
+    }
+
+    if (!this.runtime) {
+      // Runtime was recycled — create a new one
+      const module = await getSyncModule();
+      this.runtime = module.newRuntime();
+      this.runtime.setMemoryLimit(this.memoryLimitBytes);
+    }
+
+    this.context = this.runtime.newContext();
+  }
+
+  /**
+   * Dispose the sandbox and clean up resources
+   *
+   * Call this when shutting down (e.g., actor eviction).
+   * After dispose(), configure() can create a new sandbox.
+   */
+  async dispose(): Promise<void> {
+    if (this.disposed) {
+      return;
+    }
+
+    this.disposed = true;
+
+    // Reject all queued executions
+    for (const execution of this.executionQueue) {
+      execution.reject(new Error('Sandbox has been disposed'));
+    }
+    this.executionQueue = [];
+
+    // Dispose context and runtime
+    try {
+      this.context?.dispose();
+    } catch {
+      // Ignore — best effort cleanup
+    }
+
+    try {
+      this.runtime?.dispose();
+    } catch {
+      // Ignore — best effort cleanup
+    }
+
+    // Clear singleton so configure() creates a fresh one
+    Sandbox.instance = null;
+    Sandbox.configuring = false;
+  }
+
+  /**
+   * Reset the singleton instance (for testing only)
+   *
+   * Disposes the existing instance if any, then clears the singleton.
+   */
+  static async reset(): Promise<void> {
+    if (Sandbox.instance) {
+      try {
+        await Sandbox.instance.dispose();
+      } catch {
+        // Ignore — instance may have already been disposed
+      }
+    }
+    Sandbox.instance = null;
+    Sandbox.configuring = false;
+  }
+}