ace-test-runner-e2e 0.38.11 → 0.40.1

data/lib/ace/test/end_to_end_runner/molecules/pipeline_sandbox_builder.rb

@@ -77,7 +77,7 @@ module Ace
           # non-mutating.
           #
           # @param sandbox_path [String]
-          # @return [void]
+          # @return [Array<String>]
           def sync_protocol_sources_into(sandbox_path)
             sync_protocol_sources(File.expand_path(sandbox_path))
           end
@@ -108,12 +108,13 @@ module Ace
           end
 
           def sync_protocol_sources(sandbox_path)
-            %w[skill wfi].each do |protocol|
+            packages = %w[skill wfi].flat_map do |protocol|
               Dir.glob(File.join(@config_root, "*", ".ace-defaults", "nav", "protocols",
-                "#{protocol}-sources", "*.yml")).sort.each do |manifest_path|
+                "#{protocol}-sources", "*.yml")).sort.filter_map do |manifest_path|
                 sync_protocol_source_manifest(protocol, manifest_path, sandbox_path)
               end
             end
+            packages.compact.uniq.sort
           end
 
           def sync_protocol_source_manifest(protocol, manifest_path, sandbox_path)
@@ -137,11 +138,12 @@ module Ace
 
             FileUtils.mkdir_p(File.dirname(target_manifest_path))
             FileUtils.cp(manifest_path, target_manifest_path) unless File.exist?(target_manifest_path)
-            return unless File.directory?(source_dir)
+            return package_name unless File.directory?(source_dir)
             return if File.exist?(target_dir)
 
             FileUtils.mkdir_p(File.dirname(target_dir))
             FileUtils.cp_r(source_dir, target_dir)
+            package_name
           rescue Psych::SyntaxError
             nil
           end
@@ -214,7 +216,7 @@ module Ace
 
             stdout, stderr, status = Open3.capture3(
               env,
-              "bash", "--noprofile", "--norc", "-c", "ace-config init && ace-handbook sync",
+              "bash", "--noprofile", "--norc", "-c", "ace-config sync ace-llm-providers-cli && ace-handbook sync",
               chdir: sandbox_path
             )
             return if status.success?

data/lib/ace/test/end_to_end_runner/molecules/report_writer.rb

@@ -217,6 +217,8 @@ module Ace
             metadata["runner_observations"] = result.metadata["runner_observations"] if result.metadata.key?("runner_observations")
             metadata["verifier_observations"] = result.observations unless result.observations.to_s.empty?
             metadata["missing_required_artifacts"] = result.metadata["missing_required_artifacts"] if result.metadata.key?("missing_required_artifacts")
+            metadata["initial_missing_required_artifacts"] = result.metadata["initial_missing_required_artifacts"] if result.metadata.key?("initial_missing_required_artifacts")
+            metadata["artifact_repair_attempted"] = result.metadata["artifact_repair_attempted"] if result.metadata.key?("artifact_repair_attempted")
             metadata["works_for_end_user"] = result.metadata["works_for_end_user"] if result.metadata.key?("works_for_end_user")
             metadata["user_friction"] = result.metadata["user_friction"] if result.metadata.key?("user_friction")
             metadata["user_feedback"] = result.metadata["user_feedback"] if result.metadata.key?("user_feedback")

data/lib/ace/test/end_to_end_runner/molecules/sandbox_runtime_builder.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "open3"
+require "digest"
 
 module Ace
   module Test
@@ -10,6 +11,9 @@ module Ace
         # Builds a sandbox-local Ruby/Bundler runtime for E2E execution.
         class SandboxRuntimeBuilder
           DEFAULT_RUBY_VERSION = "3.4.9"
+          DEFAULT_SHARED_RUNTIME_CACHE_ROOT = ".ace-local/test-e2e/runtime-cache"
+          SHARED_RUNTIME_ENV_KEY = "ACE_E2E_SHARED_RUNTIME_ROOT"
+          RUNTIME_CACHE_LAYOUT_VERSION = 1
           RESERVED_ENV_KEYS = %w[
             PROJECT_ROOT_PATH
             ACE_E2E_SOURCE_ROOT
@@ -37,14 +41,22 @@ module Ace
 
           def prepare(sandbox_root:, env: {}, tool_names: nil)
             sandbox_root = File.expand_path(sandbox_root)
-            runtime_root = File.join(sandbox_root, ".ace-local", "e2e-runtime")
-            FileUtils.mkdir_p(runtime_root)
-
-            runtime_env = build_runtime_env(sandbox_root, runtime_root, env)
+            local_runtime_root = File.join(sandbox_root, ".ace-local", "e2e-runtime")
+            runtime_root = resolve_runtime_root(local_runtime_root, env)
+            FileUtils.mkdir_p(runtime_root) unless shared_runtime_root?(env)
+
+            runtime_env = build_runtime_env(
+              sandbox_root,
+              runtime_root,
+              env,
+              mutable_runtime_root: local_runtime_root
+            )
             ensure_runtime_dirs(runtime_env)
-            write_runtime_gemfile(runtime_root)
-            write_command_shims(runtime_root, tool_names)
-            install_runtime!(runtime_root, runtime_env)
+            if shared_runtime_root?(env)
+              ensure_shared_runtime!(runtime_root, tool_names)
+            else
+              prepare_runtime_root!(runtime_root, runtime_env, tool_names)
+            end
 
             {
               runtime_root: runtime_root,
@@ -52,15 +64,23 @@ module Ace
             }
           end
 
+          def prepare_shared_runtime(cache_root: nil, tool_names: nil)
+            runtime_root = shared_runtime_root(cache_root: cache_root)
+            runtime_env = build_shared_runtime_env(runtime_root)
+            ensure_runtime_dirs(runtime_env)
+            prepare_runtime_root!(runtime_root, runtime_env, tool_names)
+            runtime_root
+          end
+
           private
 
           def capture3(env, *cmd, chdir:)
             Open3.capture3(env, *cmd, chdir: chdir, unsetenv_others: true)
           end
 
-          def build_runtime_env(sandbox_root, runtime_root, env)
+          def build_runtime_env(sandbox_root, runtime_root, env, mutable_runtime_root: runtime_root)
             merged = stringify_keys(env).reject { |key, _value| RESERVED_ENV_KEYS.include?(key) }
-            bundler_root = File.join(runtime_root, "bundler")
+            bundler_root = File.join(mutable_runtime_root, "bundler")
             gem_root = File.join(runtime_root, "gems")
             bin_root = File.join(runtime_root, "bin")
             path = merged["PATH"].to_s
@@ -87,6 +107,10 @@ module Ace
             )
           end
 
+          def build_shared_runtime_env(runtime_root)
+            build_runtime_env(@source_root, runtime_root, {}, mutable_runtime_root: runtime_root)
+          end
+
           def ensure_runtime_dirs(env)
             [
               env.fetch("ACE_CONFIG_PATH"),
@@ -169,6 +193,74 @@ module Ace
               .uniq
           end
 
+          def resolve_runtime_root(local_runtime_root, env)
+            shared_root = shared_runtime_root_from_env(env)
+            return shared_root if shared_root
+
+            local_runtime_root
+          end
+
+          def shared_runtime_root?(env)
+            !shared_runtime_root_from_env(env).nil?
+          end
+
+          def shared_runtime_root_from_env(env)
+            merged = stringify_keys(ENV.to_h).merge(stringify_keys(env))
+            raw = merged[SHARED_RUNTIME_ENV_KEY].to_s.strip
+            return nil if raw.empty?
+
+            File.expand_path(raw)
+          end
+
+          def shared_runtime_root(cache_root: nil)
+            base = if cache_root
+              File.expand_path(cache_root)
+            else
+              File.join(@source_root, DEFAULT_SHARED_RUNTIME_CACHE_ROOT)
+            end
+
+            File.join(base, runtime_cache_key)
+          end
+
+          def runtime_cache_key
+            @runtime_cache_key ||= begin
+              digest = Digest::SHA256.new
+              digest.update("layout:#{RUNTIME_CACHE_LAYOUT_VERSION}\n")
+              digest.update("ruby:#{@ruby_version}\n")
+              digest.update(File.read(File.join(@source_root, "Gemfile")))
+              lockfile_path = File.join(@source_root, "Gemfile.lock")
+              digest.update(File.read(lockfile_path)) if File.file?(lockfile_path)
+              digest.hexdigest[0, 16]
+            end
+          end
+
+          def ensure_shared_runtime!(runtime_root, tool_names)
+            runtime_env = build_shared_runtime_env(runtime_root)
+            ensure_runtime_dirs(runtime_env)
+            prepare_runtime_root!(runtime_root, runtime_env, tool_names)
+          end
+
+          def prepare_runtime_root!(runtime_root, env, tool_names)
+            with_runtime_lock(runtime_root) do
+              marker_path = File.join(runtime_root, ".bootstrapped")
+              return if File.exist?(marker_path)
+
+              FileUtils.mkdir_p(runtime_root)
+              write_runtime_gemfile(runtime_root)
+              write_command_shims(runtime_root, tool_names)
+              install_runtime!(runtime_root, env)
+            end
+          end
+
+          def with_runtime_lock(runtime_root)
+            lock_path = "#{runtime_root}.lock"
+            FileUtils.mkdir_p(File.dirname(lock_path))
+            File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lock_file|
+              lock_file.flock(File::LOCK_EX)
+              yield
+            end
+          end
+
           def install_runtime!(runtime_root, env)
             marker_path = File.join(runtime_root, ".bootstrapped")
             return if File.exist?(marker_path)

data/lib/ace/test/end_to_end_runner/molecules/scenario_loader.rb

@@ -256,27 +256,39 @@ module Ace
 
           def declared_artifacts_for(scenario_dir, tc_id, runner_content, verify_content)
             scenario_frontmatter = parse_scenario_yml(File.join(scenario_dir, "scenario.yml"))
-            required_artifacts = []
-            optional_artifacts = []
-
-            required_artifacts.concat(
+            scenario_references = Atoms::ArtifactContractValidator.references_from_paths(
               Array((scenario_frontmatter["sandbox-layout"] || {}).keys).select do |path|
                 declared_artifact_matches_tc?(path, tc_id)
-              end
+              end,
+              source: File.join(scenario_dir, "scenario.yml")
+            )
+            runner_references = Atoms::ArtifactContractValidator.extract(
+              runner_content,
+              source: File.join(scenario_dir, "#{tc_id}.runner.md")
+            )
+            verifier_references = Atoms::ArtifactContractValidator.extract(
+              verify_content,
+              source: File.join(scenario_dir, "#{tc_id}.verify.md")
             )
 
-            [runner_content, verify_content].each do |content|
-              extract_declared_artifacts(content).each do |entry|
-                if entry[:optional]
-                  optional_artifacts << entry[:path]
-                else
-                  required_artifacts << entry[:path]
-                end
-              end
-            end
+            Atoms::ArtifactContractValidator.validate!(
+              tc_id: tc_id,
+              scenario_dir: scenario_dir,
+              runner_references: runner_references,
+              verifier_references: verifier_references,
+              scenario_references: scenario_references
+            )
 
-            required = required_artifacts.map { |path| normalize_declared_artifact(path) }.compact.uniq
-            optional = optional_artifacts.map { |path| normalize_declared_artifact(path) }.compact.uniq
+            required = (scenario_references + runner_references)
+              .reject(&:optional)
+              .map(&:path)
+              .compact
+              .uniq
+            optional = runner_references
+              .select(&:optional)
+              .map(&:path)
+              .compact
+              .uniq
             optional = optional.reject { |path| required.include?(path) }
 
             [required.sort, optional.sort]
@@ -300,20 +312,6 @@ module Ace
             match ? match[1].to_i : nil
           end
 
-          def extract_declared_artifacts(markdown)
-            markdown.to_s.scan(%r{(?:`|"|')?(results/tc/\d{2}/[^\s`)"']+|results/tc/\d{2}/)(?:`|"|')?(\s*\(optional\))?}i).map do |match|
-              path, optional = match
-              {path: path, optional: !optional.to_s.empty?}
-            end
-          end
-
-          def normalize_declared_artifact(path)
-            value = path.to_s.strip
-            return nil unless value.start_with?("results/tc/")
-
-            value.sub(%r{/+\z}, "")
-          end
-
           # Infer package name from scenario directory path
           #
           # @param scenario_dir [String] Path to scenario directory

data/lib/ace/test/end_to_end_runner/molecules/setup_executor.rb

@@ -39,13 +39,15 @@ module Ace
           # @param scenario_name [String, nil] Test ID for tmux session naming (e.g., "TS-OVERSEER-001")
           # @param run_id [String, nil] Unique run ID for deterministic tmux session naming
           # @return [Hash] Result with :success, :steps_completed, :error, :env, :tmux_session keys
-          def execute(setup_steps:, sandbox_dir:, fixture_source: nil, scenario_name: nil, run_id: nil, initial_env: {})
+          def execute(setup_steps:, sandbox_dir:, fixture_source: nil, scenario_name: nil, run_id: nil, initial_env: {},
+            git_excludes: [])
             FileUtils.mkdir_p(sandbox_dir)
             env = if @sandbox_backend
               @sandbox_backend.prepared_env(initial_env.dup)
             else
               initial_env.dup
             end
+            @git_excludes = normalize_git_excludes(git_excludes)
             steps_completed = 0
             @tmux_session = nil
             @scenario_name = scenario_name
@@ -162,6 +164,7 @@ module Ace
             run_command("git", "init", "-b", "main", chdir: sandbox_dir, env: env)
             run_command("git", "config", "user.name", "Test User", chdir: sandbox_dir, env: env)
             run_command("git", "config", "user.email", "test@example.com", chdir: sandbox_dir, env: env)
+            seed_git_excludes(sandbox_dir)
           end
 
           # Copy fixture files into sandbox
@@ -245,6 +248,26 @@ module Ace
             Open3.capture3(*args, **kwargs)
           end
 
+          def seed_git_excludes(sandbox_dir)
+            patterns = (default_git_excludes + @git_excludes).uniq
+            return if patterns.empty?
+
+            exclude_path = File.join(sandbox_dir, ".git", "info", "exclude")
+            existing = File.exist?(exclude_path) ? File.readlines(exclude_path, chomp: true) : []
+            additions = patterns.reject { |pattern| existing.include?(pattern) }
+            return if additions.empty?
+
+            File.write(exclude_path, (existing + additions).join("\n") + "\n")
+          end
+
+          def normalize_git_excludes(git_excludes)
+            Array(git_excludes).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+          end
+
+          def default_git_excludes
+            [".ace-local/", "reports/", "results/"]
+          end
+
           def sanitized_process_environment
             ENV.to_h.each_with_object({}) do |(key, value), env|
               if AMBIENT_TMUX_ENV_VARS.include?(key) || STRIPPED_ENV_KEYS.include?(key) ||

data/lib/ace/test/end_to_end_runner/molecules/suite_report_writer.rb

@@ -27,7 +27,8 @@ module Ace
 
           REPORT_KINDS = {
             package: ->(timestamp, package) { "#{timestamp}-#{package}-report.md" },
-            suite: ->(timestamp, _package) { "#{timestamp}-suite-report.md" }
+            suite: ->(timestamp, _package) { "#{timestamp}-suite-report.md" },
+            suite_final: ->(timestamp, _package) { "#{timestamp}-suite-final-report.md" }
           }.freeze
 
           # Write an aggregated report
@@ -68,6 +69,44 @@ module Ace
             report_path
           end
 
+          # Write a deterministic wrapper report for a two-attempt suite run.
+          #
+          # Preserves first-pass failure evidence while reflecting the final retry outcome.
+          def write_retry_summary(initial_results:, retry_results:, timestamp:, base_dir:, package: "suite")
+            cache_dir = File.join(base_dir, ".ace-local", "test-e2e")
+            FileUtils.mkdir_p(cache_dir)
+
+            report_path = File.join(cache_dir, report_filename(:suite_final, timestamp, package))
+            initial_entries = flatten_attempt_results(initial_results, base_dir: base_dir)
+            retry_entries = flatten_attempt_results(retry_results, base_dir: base_dir)
+            retry_by_test = retry_entries.each_with_object({}) { |entry, memo| memo[entry[:test_id]] = entry }
+
+            flaky_entries = initial_entries.filter_map do |entry|
+              next if entry[:status] == "pass"
+
+              retry_entry = retry_by_test[entry[:test_id]]
+              next unless retry_entry && retry_entry[:status] == "pass"
+
+              entry.merge(retry_entry: retry_entry)
+            end.sort_by { |entry| entry[:test_id] }
+            remaining_entries = retry_entries.reject { |entry| entry[:status] == "pass" }.sort_by { |entry| entry[:test_id] }
+            final_status = compute_retry_summary_status(retry_entries)
+
+            content = build_retry_summary_content(
+              timestamp: timestamp,
+              initial_results: initial_results,
+              retry_results: retry_results,
+              initial_entries: initial_entries,
+              flaky_entries: flaky_entries,
+              remaining_entries: remaining_entries,
+              final_status: final_status,
+              base_dir: base_dir
+            )
+
+            File.write(report_path, content)
+            report_path
+          end
+
           private
 
           def report_filename(report_kind, timestamp, package)
@@ -77,6 +116,148 @@ module Ace
             builder.call(timestamp, package)
           end
 
+          def flatten_attempt_results(results, base_dir:)
+            results.fetch(:packages, {}).values.flatten.map do |result|
+              report_dir = result[:report_dir]
+              metadata = read_retry_metadata(report_dir)
+              report_frontmatter = read_report_frontmatter(report_dir)
+              test_name = result[:test_name] || result[:test_id] || ""
+              test_id = metadata["test-id"] || canonical_retry_test_id(test_name)
+              failed_entries = Array(metadata["failed"]).filter_map do |entry|
+                next unless entry.is_a?(Hash)
+
+                {
+                  tc: entry["tc"] || entry[:tc],
+                  category: entry["category"] || entry[:category] || "runner-error",
+                  evidence: entry["evidence"] || entry[:evidence] || "See attempt report for details"
+                }
+              end
+              if failed_entries.empty? && result[:status] != "pass"
+                failed_entries << {
+                  tc: nil,
+                  category: result[:status] || "runner-error",
+                  evidence: result[:summary] || result[:error] || "See attempt report for details"
+                }
+              end
+
+              {
+                test_id: test_id,
+                title: report_frontmatter["title"] || test_id,
+                status: result[:status],
+                report_dir: report_dir,
+                report_dir_display: display_path(report_dir, base_dir),
+                report_dir_name: report_dir ? File.basename(report_dir) : nil,
+                failed_entries: failed_entries,
+                passed_cases: result[:passed_cases] || metadata["tcs-passed"] || metadata.dig("results", "passed") || 0,
+                total_cases: result[:total_cases] || metadata["tcs-total"] || metadata.dig("results", "total") || 0
+              }
+            end
+          end
+
+          def read_retry_metadata(report_dir)
+            return {} unless report_dir
+
+            path = File.join(report_dir, "metadata.yml")
+            return {} unless File.exist?(path)
+
+            YAML.safe_load_file(path, permitted_classes: [Time, Date]) || {}
+          rescue
+            {}
+          end
+
+          def canonical_retry_test_id(test_name)
+            match = test_name.to_s.match(/\A(TS-[A-Z0-9]+-\d+[a-z]*)/i)
+            match ? match[1].upcase : test_name
+          end
+
+          def display_path(path, base_dir)
+            return nil if path.nil?
+
+            path.start_with?(base_dir) ? path.delete_prefix("#{base_dir}/") : path
+          end
+
+          def compute_retry_summary_status(entries)
+            executed = entries.reject { |entry| entry[:status] == "skip" }
+            return "skip" if executed.empty?
+            return "pass" if executed.all? { |entry| entry[:status] == "pass" }
+            return "partial" if executed.any? { |entry| entry[:status] == "pass" }
+
+            "fail"
+          end
+
+          def build_retry_summary_content(timestamp:, initial_results:, retry_results:, initial_entries:, flaky_entries:, remaining_entries:, final_status:, base_dir:)
+            total_initial_failures = initial_entries.count { |entry| entry[:status] != "pass" }
+            lines = []
+            lines << "---"
+            lines << "suite-id: #{timestamp}"
+            lines << "package: suite"
+            lines << "status: #{final_status}"
+            lines << "retry-attempted: true"
+            lines << "flaky-scenarios: #{flaky_entries.length}"
+            lines << "remaining-failures: #{remaining_entries.length}"
+            lines << "attempt-1-report: #{display_path(initial_results[:report_path], base_dir)}"
+            lines << "attempt-2-report: #{display_path(retry_results[:report_path], base_dir)}"
+            lines << "---"
+            lines << ""
+            lines << "# E2E Final Suite Report: `suite`"
+            lines << ""
+            lines << "## Attempt Summary"
+            lines << ""
+            lines << "| Attempt | Report | Status | Scenarios | Failures |"
+            lines << "|---|---|---:|---:|---:|"
+            lines << "| 1 | `#{display_path(initial_results[:report_path], base_dir)}` | #{initial_results[:failed].to_i > 0 || initial_results[:errors].to_i > 0 ? "Fail" : "Pass"} | #{initial_results[:total]} | #{initial_results[:failed].to_i + initial_results[:errors].to_i} |"
+            lines << "| 2 | `#{display_path(retry_results[:report_path], base_dir)}` | #{retry_results[:failed].to_i > 0 || retry_results[:errors].to_i > 0 ? "Fail" : "Pass"} | #{retry_results[:total]} | #{retry_results[:failed].to_i + retry_results[:errors].to_i} |"
+            lines << ""
+            lines << "First-pass failing scenarios: #{total_initial_failures}"
+            lines << "Recovered on retry (flaky): #{flaky_entries.length}"
+            lines << "Remaining failures after retry: #{remaining_entries.length}"
+            lines << ""
+            lines << "## Flaky Recoveries"
+            lines << ""
+            if flaky_entries.empty?
+              lines << "None."
+            else
+              flaky_entries.each do |entry|
+                lines << "### #{entry[:test_id]}"
+                lines << ""
+                lines << "- Title: #{entry[:title]}"
+                lines << "- Attempt 1 status: `#{entry[:status]}`"
+                lines << "- Attempt 1 report directory: `#{entry[:report_dir_display]}`"
+                lines << "- Attempt 2 report directory: `#{entry[:retry_entry][:report_dir_display]}`"
+                entry[:failed_entries].each do |failure|
+                  lines << "- #{format_failure_entry(failure)}"
+                end
+                lines << ""
+              end
+            end
+            lines << "## Remaining Failures"
+            lines << ""
+            if remaining_entries.empty?
+              lines << "None."
+            else
+              remaining_entries.each do |entry|
+                lines << "### #{entry[:test_id]}"
+                lines << ""
+                lines << "- Title: #{entry[:title]}"
+                lines << "- Attempt 2 status: `#{entry[:status]}`"
+                lines << "- Attempt 2 report directory: `#{entry[:report_dir_display]}`"
+                entry[:failed_entries].each do |failure|
+                  lines << "- #{format_failure_entry(failure)}"
+                end
+                lines << ""
+              end
+            end
+
+            lines.join("\n")
+          end
+
+          def format_failure_entry(failure)
+            tc = failure[:tc] || failure["tc"]
+            category = failure[:category] || failure["category"] || "runner-error"
+            evidence = failure[:evidence] || failure["evidence"] || "See attempt report for details"
+            tc ? "`#{tc}` (`#{category}`) - #{evidence}" : "`#{category}` - #{evidence}"
+          end
+
           # Attempt LLM synthesis for narrative sections only, falling back to
           # deterministic defaults when the model is unavailable or malformed.
           def synthesize_narrative_sections(results_data, package:, timestamp:, overall_status:, executed_at:)

data/lib/ace/test/end_to_end_runner/organisms/suite_orchestrator.rb

@@ -31,7 +31,8 @@ module Ace
           # @param timestamp_generator Timestamp generator (injectable)
           def initialize(max_parallel: 4, base_dir: nil, discoverer: nil, affected_detector: nil,
             failure_finder: nil, output: $stdout, use_color: nil, progress: false,
-            suite_report_writer: nil, scenario_loader: nil, timestamp_generator: nil)
+            suite_report_writer: nil, scenario_loader: nil, timestamp_generator: nil,
+            runtime_builder: nil, shared_runtime_cache_root: nil)
             @max_parallel = max_parallel
             @base_dir = base_dir || Dir.pwd
             @discoverer = discoverer || Molecules::TestDiscoverer.new
@@ -44,6 +45,14 @@ module Ace
             @suite_report_writer = suite_report_writer || Molecules::SuiteReportWriter.new(config: config)
             @loader = scenario_loader || Molecules::ScenarioLoader.new
             @timestamp_generator = timestamp_generator || method(:default_timestamp)
+            @runtime_builder = runtime_builder || Molecules::SandboxRuntimeBuilder.new(
+              source_root: @base_dir,
+              ruby_version: config.dig("sandbox", "ruby_version") || Molecules::ConfigLoader.default_sandbox_ruby_version
+            )
+            @shared_runtime_cache_root = File.expand_path(
+              shared_runtime_cache_root || File.join(@base_dir, Molecules::SandboxRuntimeBuilder::DEFAULT_SHARED_RUNTIME_CACHE_ROOT)
+            )
+            @shared_runtime_root = nil
           end
 
           # Run E2E tests across all packages
@@ -124,6 +133,7 @@ module Ace
 
             total_tests = package_tests.values.flatten.size
             pkg_count = package_tests.keys.size
+            prepare_shared_runtime_cache if total_tests > 0
 
             # Pre-compute column widths for aligned output
             compute_column_widths(package_tests)
@@ -330,7 +340,7 @@ module Ace
             cmd_array = build_test_command(package, test_file, options, run_id: run_id)
 
             # Spawn process with array form (no shell invocation)
-            stdin, stdout, stderr, thread = Open3.popen3(*cmd_array, chdir: @base_dir)
+            stdin, stdout, stderr, thread = Open3.popen3(suite_subprocess_env, *cmd_array, chdir: @base_dir)
 
             {pid: thread.pid, thread: thread, stdout: stdout, stderr: stderr,
              stdin: stdin, package: package, test_file: test_file, output: String.new}
@@ -395,6 +405,18 @@ module Ace
             File.executable?(local) ? local : "ace-test-e2e"
           end
 
+          def prepare_shared_runtime_cache
+            @shared_runtime_root = @runtime_builder.prepare_shared_runtime(
+              cache_root: @shared_runtime_cache_root
+            )
+          end
+
+          def suite_subprocess_env
+            return {} if @shared_runtime_root.to_s.empty?
+
+            {Molecules::SandboxRuntimeBuilder::SHARED_RUNTIME_ENV_KEY => @shared_runtime_root}
+          end
+
           # Extract test ID from file path
           #
           # @param test_file [String] Path to scenario.yml file
@@ -864,7 +886,7 @@ module Ace
           # @return [Hash] Test result
           def run_single_test(package, test_file, options, run_id: nil)
             cmd_array = build_test_command(package, test_file, options, run_id: run_id)
-            output, stderr, status = Open3.capture3(*cmd_array, chdir: @base_dir)
+            output, stderr, status = Open3.capture3(suite_subprocess_env, *cmd_array, chdir: @base_dir)
 
             # Combine stdout and stderr for parsing
             combined_output = output + stderr