ace-test-runner 0.26.0 → 0.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fe8e1df02be6272e1ba2297d8316feef7e962e0ca1982be28e11bab4d23e1b0
-  data.tar.gz: bf3feac3f566d4def3de575cbaf3d620edfbb3c9354c5f1e771b432ba879506e
+  metadata.gz: 8b9e68c09f883cccd0d324be3b33f54de394293a8b0a4e7421ed697b8dffff7e
+  data.tar.gz: 92f8e49cccbf575821c3195bcdc92b7cf393c728474d7d116f77f3f94ad3fcae
 SHA512:
-  metadata.gz: 59d649278ab5cd98deed1b3444f2d4afb9eaccd1dd612486df2317cb622234eecc17d4e250b747bf8e111acf7fc55bc08cafd6e4131c6f3b90b9470fad092980
-  data.tar.gz: ae8e02f75588bf6406e00d1a34c3d028f0e367c437d280b47cbbcec7f80450431317760e11eeef040e99654d414f5561b59e6a7f57017cfb5510db17182b2f29
+  metadata.gz: 0dd0f2a17a9bf8f99bc4fd6c3a7004d293a0f43a1838c0654bd98743e2277d734f42043cb2a56a3c7e0e994aa863c4ab3fac0771ae7709f28dadb7ed3ebd46fb
+  data.tar.gz: cca845831f57a5b706dd547560c351ea30d19e17b99d838a8f0e1f7fadb157fd14eb35aa08a60715a49d3a24e02193e638135c075ecbb79e52fa23e493a4a9ac

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.1] - 2026-09-29
+
+### Fixed
+- Suite children now launch with the suite's own Ruby binary plus `-rbundler/setup`, so bundler discovers the checkout Gemfile by walking up from each package directory. This gives hermetic children a deterministic source-of-truth dependency surface instead of silently relying on PATH-resolved interpreters (which can fail through manager shims under fixture HOME/XDG overrides) or on globally installed ace gems. Closes the runner-level workspace LOAD_PATH follow-up from the hermetic-tests line.
+
+## [0.27.0] - 2026-09-28
+
+### Added
+- Hermetic test environments by default: deterministic `ace-test` and `ace-test-suite` runs launch every test child (serial, parallel, nested, in-process, suite workers) from a documented minimal environment allowlist with fixture-owned `HOME`/XDG directories, never inheriting ambient `LAB_*`, ACE/runtime/provider, or user configuration.
+- Fixture override configuration (`environment.preserve`/`overrides`/`require` in runner or suite configuration) with deterministic setup errors naming missing keys without exposing values. Suite-level `test_suite.environment` configuration propagates to package workers; package-level configuration wins for the same key.
+- Deterministic/live mode labeling in CLI output; live integration remains opt-in through E2E entrypoints.
+
+### Fixed
+- Test subprocess launching used environment merging, so ambient `LAB_*`/`ACE_*`/provider variables leaked into test children; child environments are now the hermetic fixture environment exactly (`unsetenv_others`).
+- `ace-test-suite` resolves `ace-test` co-located with the suite itself instead of an ambient PATH selection.
+- Rake task integration loads in a fresh process without the runner preloaded.
+- Failed fixture environment builds clean up their temporary root before raising.
+
 ## [0.26.0] - 2026-09-27
 
 ### Added

data/README.md

@@ -26,6 +26,17 @@
 2. Execute the matching tests with failure-oriented output and optional profiling of the slowest cases.
 3. Persist structured run reports for historical debugging and searchable triage across runs.
 
+## Hermetic by Default
+
+Package tests are deterministic: every test child starts from a documented minimal environment, never from ambient `LAB_*`, ACE/runtime/provider configuration, or user configuration. Output labels the mode (`Test mode: deterministic (hermetic environment)`). Live integration remains opt-in through the E2E entrypoints with explicit target configuration.
+
+- Preserved from the parent: `PATH`, `LANG`, `LC_ALL`, `TMPDIR`, `TMP`, `TEMP`.
+- Replaced with test-owned fixture directories: `HOME`, `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, `XDG_DATA_HOME`.
+- Everything else (ambient Lab/runtime sockets, provider credentials, proxy and project-selection variables) never reaches tests.
+- Fixture-specific values are supplied explicitly through runner configuration (`environment.overrides` in `.ace/test/runner.yml`); required values that are missing produce a setup error naming the key. The invoking environment is never mutated.
+
+See the [usage guide](docs/usage.md#hermetic-environment-contract) for the full contract and configuration examples.
+
 ## Use Cases
 
 **Run package tests from anywhere in the monorepo** - execute [`ace-test [package]`](docs/usage.md) by name without changing directories, keeping outputs consistent across local and CI environments.

data/lib/ace/test_runner/atoms/environment_sanitizer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Ace
+  module TestRunner
+    module Atoms
+      # Pure allowlist filter from a parent environment snapshot to the
+      # deterministic child base environment.
+      #
+      # Copies only policy-preserved keys into a fresh hash. Fixture-home
+      # replacements and fixture overrides are applied later by
+      # Molecules::FixtureEnvironment. Never mutates ENV or the input hash.
+      module EnvironmentSanitizer
+        module_function
+
+        # @param parent_env [Hash] snapshot of the parent environment (not modified)
+        # @param policy [Models::EnvironmentPolicy] hermetic environment contract
+        # @return [Hash] new child base environment containing only preserved keys
+        def sanitize(parent_env, policy)
+          parent_env.each_with_object({}) do |(key, value), child|
+            next if value.nil?
+
+            child[key] = value if policy.preserved_key?(key)
+          end
+        end
+
+        # Names of parent keys dropped by the policy (diagnostics only).
+        def dropped_keys(parent_env, policy)
+          parent_env.keys.reject { |key| policy.preserved_key?(key) }
+        end
+      end
+    end
+  end
+end

data/lib/ace/test_runner/cli/commands/test.rb

@@ -147,6 +147,11 @@ module Ace
               raise Ace::Support::Cli::Error.new(e.message)
             end
 
+            # Label the execution mode: package tests are always deterministic
+            # (hermetic fixture environment). Live integration runs only through
+            # the E2E entrypoints with explicit target configuration.
+            display_deterministic_mode(test_options)
+
             # Run tests with special exit! handling for Minitest compatibility
             run_tests_with_exit_handling(test_options)
           rescue Ace::TestRunner::Error => e
@@ -311,6 +316,12 @@ module Ace
             exit_code
           end
 
+          def display_deterministic_mode(options)
+            return if options[:quiet]
+
+            puts "Test mode: deterministic (hermetic environment)"
+          end
+
           def display_config_summary(options)
             return if options[:quiet]
 

data/lib/ace/test_runner/models/environment_policy.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module TestRunner
+    # Deterministic setup failure: names the missing or invalid key, never its value.
+    class EnvironmentSetupError < Error; end
+
+    module Models
+      # Immutable declaration of the hermetic subprocess environment contract.
+      #
+      # Deterministic test children start from an empty environment and receive only:
+      # - preserved toolchain/process keys (PATH, locale, temp directories)
+      # - fixture-owned HOME/XDG replacements (applied by Molecules::FixtureEnvironment)
+      # - explicit fixture overrides supplied through runner configuration
+      #
+      # Everything else - ambient LAB_* and ACE_* runtime/provider configuration,
+      # credentials, sockets, proxy and project-selection variables - never reaches
+      # a deterministic test child.
+      class EnvironmentPolicy
+        # Runner-internal channel for ace-test-suite to propagate its suite-level
+        # fixture configuration into package workers. Consumed by the runner when
+        # building the package policy; never passed to test children (the blocked
+        # ACE_ prefix keeps it out of every sanitized child environment).
+        SUITE_CHANNEL_KEY = "ACE_TEST_FIXTURE_ENVIRONMENT"
+
+        # Toolchain/process keys preserved from the parent environment.
+        PRESERVED_KEYS = %w[PATH LANG LC_ALL TMPDIR TMP TEMP].freeze
+
+        # Key prefixes never allowed in deterministic children or preserve lists.
+        BLOCKED_PREFIXES = %w[
+          ACE_ ANTHROPIC_ AWS_ AZURE_ BUNDLE_ COHERE_ DEEPSEEK_ FIREWORKS_ GEM_
+          GEMINI_ GLM_ GOOGLE_ GROQ_ HF_ HUGGINGFACE_ LAB_ MISTRAL_ MOONSHOT_
+          OPENAI_ OPENROUTER_ TOGETHER_ XAI_ ZAI_ ZHIPU_
+        ].freeze
+
+        # Exact keys never allowed in deterministic children or preserve lists.
+        BLOCKED_KEYS = %w[
+          ALL_PROXY BASH_ENV DATABASE_URL DOCKER_HOST ENV GITHUB_TOKEN
+          GITLAB_TOKEN HTTP_PROXY HTTPS_PROXY NO_PROXY PYTHONPATH
+          PYTHONSTARTUP RUBYLIB RUBYOPT SSH_AUTH_SOCK
+          all_proxy http_proxy https_proxy no_proxy
+        ].freeze
+
+        # Keys replaced with fixture-owned directories instead of parent values.
+        FIXTURE_HOME_KEYS = %w[HOME XDG_CONFIG_HOME XDG_CACHE_HOME XDG_DATA_HOME].freeze
+
+        attr_reader :preserved_keys, :blocked_prefixes, :blocked_keys,
+          :fixture_home_keys, :overrides, :required_keys
+
+        def initialize(preserved_keys: PRESERVED_KEYS, blocked_prefixes: BLOCKED_PREFIXES,
+          blocked_keys: BLOCKED_KEYS, fixture_home_keys: FIXTURE_HOME_KEYS,
+          overrides: {}, required_keys: [])
+          @preserved_keys = preserved_keys.map(&:to_s).freeze
+          @blocked_prefixes = blocked_prefixes.map(&:to_s).freeze
+          @blocked_keys = blocked_keys.map(&:to_s).freeze
+          @fixture_home_keys = fixture_home_keys.map(&:to_s).freeze
+          @overrides = overrides.each_with_object({}) { |(key, value), hash| hash[key.to_s] = value.to_s }.freeze
+          @required_keys = required_keys.map(&:to_s).freeze
+          validate_contract!
+        end
+
+        # Build a policy from runner or suite configuration:
+        #
+        #   environment:
+        #     preserve: [EXTRA_TOOLCHAIN_KEY]
+        #     overrides:
+        #       MY_ENDPOINT: "http://127.0.0.1:1"
+        #     require: [MY_ENDPOINT]
+        def self.from_config(config)
+          normalized = (config || {}).transform_keys(&:to_sym)
+          new(
+            preserved_keys: PRESERVED_KEYS + Array(normalized[:preserve]),
+            overrides: normalized[:overrides] || {},
+            required_keys: Array(normalized[:require])
+          )
+        end
+
+        # Build a policy from the suite propagation channel payload.
+        def self.from_channel(raw)
+          from_config(JSON.parse(raw, symbolize_names: true))
+        rescue JSON::ParserError => e
+          raise EnvironmentSetupError, "Invalid #{SUITE_CHANNEL_KEY} payload: #{e.message}"
+        end
+
+        # Combine this (broader, e.g. suite-level) policy with a more specific one
+        # (e.g. package runner configuration). Specific overrides win; preserve and
+        # require lists union.
+        def merge_with(more_specific)
+          self.class.new(
+            preserved_keys: (preserved_keys + more_specific.preserved_keys).uniq,
+            overrides: overrides.merge(more_specific.overrides),
+            required_keys: (required_keys + more_specific.required_keys).uniq
+          )
+        end
+
+        # Channel payload for propagating this policy's configuration extras.
+        def channel_payload
+          JSON.generate(
+            overrides: overrides,
+            require: required_keys,
+            preserve: preserved_keys - PRESERVED_KEYS
+          )
+        end
+
+        def preserved_key?(key)
+          @preserved_keys.include?(key)
+        end
+
+        def blocked_key?(key)
+          @blocked_keys.include?(key) || @blocked_prefixes.any? { |prefix| key.start_with?(prefix) }
+        end
+
+        def credential_like?(key)
+          key.match?(/token|secret|password|passwd|credential|api_?key|_key\z|private_?key|_sock(?:et)?\z|_url\z|_endpoint\z/i)
+        end
+
+        # Diagnostic-safe value for a key; credential-like values are never exposed.
+        def redacted_value(key, value)
+          credential_like?(key) ? "[redacted]" : value
+        end
+
+        private
+
+        def validate_contract!
+          @preserved_keys.each do |key|
+            next unless blocked_key?(key)
+
+            raise EnvironmentSetupError,
+              "Environment policy: cannot preserve blocked ambient key '#{key}'"
+          end
+
+          @required_keys.each do |key|
+            next unless key.empty?
+
+            raise EnvironmentSetupError, "Environment policy: required key names must not be empty"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/test_runner/models/test_configuration.rb

@@ -9,7 +9,7 @@ module Ace
           :verbose, :filter, :fix_deprecations, :patterns,
           :timeout, :parallel, :color, :per_file, :targets,
           :target, :config_path, :failure_limits, :profile,
-          :execution, :files, :run_in_single_batch
+          :execution, :files, :run_in_single_batch, :environment
 
         def initialize(attributes = {})
           @format = attributes[:format] || "progress"  # Default to per-test progress
@@ -32,6 +32,7 @@ module Ace
           @execution = attributes[:execution] || {}
           @files = attributes[:files]  # Specific files to test (overrides target/patterns)
           @run_in_single_batch = attributes[:run_in_single_batch] || false
+          @environment = attributes[:environment] || {}  # Hermetic fixture environment configuration
         end
 
         def valid_format?
@@ -94,7 +95,8 @@ module Ace
             profile: profile,
             execution: execution,
             files: files,
-            run_in_single_batch: run_in_single_batch
+            run_in_single_batch: run_in_single_batch,
+            environment: environment
           }
         end
 

data/lib/ace/test_runner/molecules/config_loader.rb

@@ -149,6 +149,7 @@ module Ace
           config[:defaults] ||= {}
           config[:failure_limits] ||= {}
           config[:execution] ||= {}
+          config[:environment] ||= {}
 
           config
         end

data/lib/ace/test_runner/molecules/fixture_environment.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Ace
+  module TestRunner
+    module Molecules
+      # Builds a launch-ready hermetic environment for deterministic test children.
+      #
+      # The fixture environment:
+      # - starts from the sanitized allowlisted base (Atoms::EnvironmentSanitizer)
+      # - replaces HOME and XDG locations with test-owned directories
+      # - applies explicit fixture overrides after sanitization
+      # - validates required explicit configuration, naming missing keys not values
+      #
+      # Cleanup owns only the temporary root created here; the parent home,
+      # project directories, and system temp locations are never touched.
+      class FixtureEnvironment
+        attr_reader :policy, :root, :env
+
+        def initialize(policy:, parent_env:, root_factory: Dir.method(:mktmpdir))
+          @policy = policy
+          @parent_env = parent_env
+          @root_factory = root_factory
+          @root = nil
+          @env = nil
+        end
+
+        # Build the fixture environment. Returns self for chaining.
+        # A failed build cleans up the temporary root it created before raising.
+        def build
+          @root = @root_factory.call("ace-test-fixture-")
+          @env = build_environment
+          self
+        rescue StandardError
+          cleanup
+          raise
+        end
+
+        # Remove the test-owned fixture root. Safe to call multiple times.
+        def cleanup
+          return unless @root
+
+          FileUtils.rm_rf(@root)
+          @root = nil
+          @env = nil
+        end
+
+        private
+
+        def build_environment
+          env = Atoms::EnvironmentSanitizer.sanitize(@parent_env, @policy)
+          env["MT_NO_AUTORUN"] = "1"
+          apply_fixture_homes(env)
+          @policy.overrides.each { |key, value| env[key] = value }
+          validate_required_keys!(env)
+          env
+        end
+
+        def apply_fixture_homes(env)
+          home = File.join(@root, "home")
+          config_home = File.join(home, ".config")
+          cache_home = File.join(home, ".cache")
+          data_home = File.join(home, ".local", "share")
+
+          [home, config_home, cache_home, data_home].each { |dir| FileUtils.mkdir_p(dir) }
+
+          @policy.fixture_home_keys.each do |key|
+            env[key] = case key
+            when "HOME" then home
+            when "XDG_CONFIG_HOME" then config_home
+            when "XDG_CACHE_HOME" then cache_home
+            when "XDG_DATA_HOME" then data_home
+            end
+          end
+        end
+
+        def validate_required_keys!(env)
+          missing = @policy.required_keys.select { |key| env[key].to_s.empty? }
+          return if missing.empty?
+
+          raise EnvironmentSetupError,
+            "Missing required fixture environment for deterministic test mode: #{missing.join(", ")}." \
+            " Supply the listed keys via runner configuration environment.overrides."
+        end
+      end
+    end
+  end
+end

data/lib/ace/test_runner/molecules/in_process_runner.rb

@@ -10,8 +10,10 @@ module Ace
       # Runs tests directly in the current Ruby process without spawning subprocesses
       # This provides significantly faster execution for unit tests that don't need isolation
       class InProcessRunner
-        def initialize(timeout: nil)
+        def initialize(timeout: nil, launch_env:)
           @timeout = timeout
+          @launch_env = launch_env  # Hermetic fixture environment applied for the test run
+          @saved_env = nil
         end
 
         def execute_tests(files, options = {})
@@ -27,15 +29,16 @@ module Ace
 
           # Store original verbose setting
           original_verbose = $VERBOSE
-          original_mt_no_autorun = ENV["MT_NO_AUTORUN"]
 
           begin
             $stdout = stdout_io
             $stderr = stderr_io
             $VERBOSE = nil if options[:suppress_warnings]
 
-            # Prevent Minitest from auto-running
-            ENV["MT_NO_AUTORUN"] = "1"
+            # Apply the hermetic fixture environment for the duration of the run:
+            # test code reads sanitized, fixture-owned environment state, and any
+            # subprocess the tests spawn inherits the same hermetic environment.
+            apply_launch_env
 
             # Add test directory to load path if not already there
             test_dir = File.expand_path("test")
@@ -145,12 +148,9 @@ module Ace
             $stderr = original_stderr
             $VERBOSE = original_verbose
 
-            # Restore original MT_NO_AUTORUN value
-            if original_mt_no_autorun
-              ENV["MT_NO_AUTORUN"] = original_mt_no_autorun
-            else
-              ENV.delete("MT_NO_AUTORUN")
-            end
+            # Restore the exact parent environment, including keys removed or
+            # added by test code during the run
+            restore_launch_env
           end
 
           end_time = Time.now
@@ -195,6 +195,23 @@ module Ace
 
         private
 
+        # Swap the process environment to the hermetic fixture environment.
+        # Keys absent from the fixture environment (ambient configuration,
+        # credentials) are removed for the duration of the run.
+        def apply_launch_env
+          @saved_env = ENV.to_h
+          @launch_env.each { |key, value| ENV[key] = value }
+          (@saved_env.keys - @launch_env.keys).each { |key| ENV.delete(key) }
+        end
+
+        def restore_launch_env
+          return unless @saved_env
+
+          ENV.clear
+          @saved_env.each { |key, value| ENV[key] = value }
+          @saved_env = nil
+        end
+
         def empty_result
           {
             stdout: "",

data/lib/ace/test_runner/molecules/smart_test_executor.rb

@@ -9,9 +9,9 @@ module Ace
     module Molecules
       # Intelligently chooses between subprocess and in-process execution based on test type
       class SmartTestExecutor
-        def initialize(command_builder: nil, timeout: nil, force_mode: nil)
-          @subprocess_executor = TestExecutor.new(command_builder: command_builder, timeout: timeout)
-          @in_process_runner = InProcessRunner.new(timeout: timeout)
+        def initialize(command_builder: nil, timeout: nil, force_mode: nil, launch_env:)
+          @subprocess_executor = TestExecutor.new(command_builder: command_builder, timeout: timeout, launch_env: launch_env)
+          @in_process_runner = InProcessRunner.new(timeout: timeout, launch_env: launch_env)
           @test_type_detector = Atoms::TestTypeDetector.new
           @force_mode = force_mode  # :subprocess, :direct, or nil for auto
         end

data/lib/ace/test_runner/molecules/test_executor.rb

@@ -9,9 +9,10 @@ module Ace
     module Molecules
       # Executes test commands and captures output
       class TestExecutor
-        def initialize(command_builder: nil, timeout: nil)
+        def initialize(command_builder: nil, timeout: nil, launch_env:)
           @command_builder = command_builder || Atoms::CommandBuilder.new
           @timeout = timeout  # In seconds, nil = no timeout
+          @launch_env = launch_env  # Hermetic fixture environment for every child
         end
 
         def execute_tests(files, options = {})
@@ -32,25 +33,21 @@ module Ace
           stderr = ""
           status = nil
 
-          # Set environment to prevent Minitest autorun at_exit hook
-          # Also strip assignment context vars to prevent tests from resolving to wrong assignments
-          # Inherit parent environment and override specific vars (nil unsets at exec time)
-          env = ENV.to_h.merge({
-            "MT_NO_AUTORUN" => "1",
-            "ACE_ASSIGN_ID" => nil,
-            "ACE_ASSIGN_FORK_ROOT" => nil
-          })
-
-          # Remove MT_NO_AUTORUN=1 from command if it's there
+          # Launch from the hermetic fixture environment: ambient LAB_*, ACE_*,
+          # provider and user configuration never reaches the test child.
+          # unsetenv_others makes the fixture environment the entire child
+          # environment (Process.spawn merges onto the parent by default).
+          # MT_NO_AUTORUN is part of the fixture environment.
+          env = @launch_env
           command = command.sub(/^MT_NO_AUTORUN=1\s+/, "")
 
           begin
             if @timeout
               Timeout.timeout(@timeout) do
-                stdout, stderr, status = Open3.capture3(env, command)
+                stdout, stderr, status = Open3.capture3(env, command, unsetenv_others: true)
               end
             else
-              stdout, stderr, status = Open3.capture3(env, command)
+              stdout, stderr, status = Open3.capture3(env, command, unsetenv_others: true)
             end
           rescue Timeout::Error
             stderr = "Test execution timed out after #{@timeout} seconds"

data/lib/ace/test_runner/organisms/test_orchestrator.rb

@@ -51,6 +51,9 @@ module Ace
         ensure
           # Restore original directory if we changed it
           Dir.chdir(@original_dir) if @package_dir && Dir.pwd != @original_dir
+
+          # The fixture environment (and its temp root) belongs to this run only
+          @fixture_environment&.cleanup
         end
 
         def run_with_package_context
@@ -63,6 +66,8 @@ module Ace
             puts "Running tests in #{File.basename(@package_dir)}..."
           end
 
+          report_fixture_environment if @configuration.verbose
+
           # Check if sequential target execution should be used
           if should_execute_sequentially?
             # Use default "fast" target if no target specified in by-target mode
@@ -179,6 +184,17 @@ module Ace
           @pattern_resolver = Molecules::PatternResolver.new(@configuration)
           @test_detector = Atoms::TestDetector.new(patterns: @configuration.patterns)
 
+          # Hermetic fixture environment: every test child (subprocess or in-process)
+          # is launched from the sanitized allowlisted environment with fixture-owned
+          # HOME/XDG directories. Ambient LAB_*/ACE_*/provider/user configuration
+          # never reaches deterministic tests. Suite-level fixture configuration is
+          # merged under this package's own runner configuration (specific wins).
+          @environment_policy = build_environment_policy
+          @fixture_environment = Molecules::FixtureEnvironment.new(
+            policy: @environment_policy,
+            parent_env: ENV.to_h
+          ).build
+
           # Use SmartTestExecutor for intelligent subprocess/direct execution choice
           require_relative "../molecules/smart_test_executor"
           force_mode = if @options[:direct]
@@ -188,7 +204,8 @@ module Ace
           end
           @test_executor = Molecules::SmartTestExecutor.new(
             timeout: @configuration.timeout,
-            force_mode: force_mode
+            force_mode: force_mode,
+            launch_env: @fixture_environment.env
           )
           @result_parser = Atoms::ResultParser.new
           @failure_analyzer = Molecules::FailureAnalyzer.new
@@ -367,10 +384,29 @@ module Ace
             profile: options[:profile],
             execution: config_with_options.execution || {},
             files: options[:files],
-            run_in_single_batch: options[:run_in_single_batch]
+            run_in_single_batch: options[:run_in_single_batch],
+            environment: config_with_options.environment
           )
         end
 
+        # Verbose diagnostics on stderr: fixture root and override key names only.
+        # Override values (potentially credential-like) are never printed.
+        def report_fixture_environment
+          warn "fixture home: #{@fixture_environment.root}"
+          override_names = @environment_policy.overrides.keys.join(", ")
+          warn "fixture overrides: #{override_names.empty? ? "none" : override_names}"
+        end
+
+        # Package policy from runner configuration, merged with suite-level
+        # fixture configuration propagated by ace-test-suite (specific wins).
+        def build_environment_policy
+          policy = Models::EnvironmentPolicy.from_config(@configuration.environment)
+          channel = ENV[Models::EnvironmentPolicy::SUITE_CHANNEL_KEY]
+          return policy unless channel
+
+          Models::EnvironmentPolicy.from_channel(channel).merge_with(policy)
+        end
+
         def validate_configuration!
           @configuration.validate!
         rescue ArgumentError => e

data/lib/ace/test_runner/rake_task.rb

@@ -3,6 +3,11 @@
 require "rake"
 require "rake/tasklib"
 
+# Rakefiles load this file directly in a fresh process; load the runner
+# namespace explicitly (models, molecules, atoms, error classes) instead of
+# relying on another entrypoint having required it first.
+require_relative "../test_runner"
+
 module Ace
   module TestRunner
     # Custom Rake task that uses ace-test instead of standard Minitest runner
@@ -40,17 +45,22 @@ module Ace
         # Build ace-test command
         command = build_command
 
-        # Execute ace-test with sanitized environment
-        # Strip assignment context vars to prevent tests from resolving to wrong assignments
         puts command if verbose
-        env = ENV.to_h.merge({
-          "ACE_ASSIGN_ID" => nil,
-          "ACE_ASSIGN_FORK_ROOT" => nil
-        })
-        success = system(env, command)
+
+        # Launch ace-test from a hermetic fixture environment: ambient LAB_*,
+        # ACE_*/provider and user configuration never reaches the test run.
+        fixture_environment = Molecules::FixtureEnvironment.new(
+          policy: Models::EnvironmentPolicy.new,
+          parent_env: ENV.to_h
+        ).build
+        # unsetenv_others makes the fixture environment the entire child
+        # environment (system merges onto the parent by default).
+        success = system(fixture_environment.env, command, unsetenv_others: true)
 
         # Exit with proper code for CI/CD
         exit(1) unless success
+      ensure
+        fixture_environment&.cleanup
       end
 
       def build_command

data/lib/ace/test_runner/suite/orchestrator.rb

@@ -28,6 +28,8 @@ module Ace
 
         def run
           validate_packages!
+          puts "Test mode: deterministic (hermetic environment)"
+
           test_options = (@config.dig("test_suite", "test_options") || {}).dup
           report_root = normalize_report_root(test_options["report_dir"])
           test_options["report_dir"] = report_root if report_root
@@ -35,7 +37,8 @@ module Ace
           display_manager = create_display_manager
           process_monitor = ProcessMonitor.new(
             @config.dig("test_suite", "max_parallel") || 10,
-            package_timeout: @config.dig("test_suite", "timeout")
+            package_timeout: @config.dig("test_suite", "timeout"),
+            environment_policy: environment_policy
           )
 
           # Enrich packages with historical duration data for scheduling
@@ -89,6 +92,12 @@ module Ace
 
         private
 
+        # Hermetic environment policy from suite configuration
+        # (test_suite.environment: preserve/overrides/require).
+        def environment_policy
+          Models::EnvironmentPolicy.from_config(@config.dig("test_suite", "environment"))
+        end
+
         def validate_packages!
           @packages.each do |package|
             unless Dir.exist?(package["path"])

data/lib/ace/test_runner/suite/process_monitor.rb

@@ -10,10 +10,12 @@ module Ace
       class ProcessMonitor
         attr_reader :processes, :max_parallel
 
-        def initialize(max_parallel = 10, package_timeout: nil, termination_grace_period: 1.0, clock: nil)
+        def initialize(max_parallel = 10, package_timeout: nil, termination_grace_period: 1.0, clock: nil,
+          environment_policy: Models::EnvironmentPolicy.new)
           @max_parallel = max_parallel
           @package_timeout = package_timeout
           @termination_grace_period = termination_grace_period
+          @environment_policy = environment_policy
           @clock = clock || -> { Time.now }
           @processes = {}
           @queue = []
@@ -31,14 +33,22 @@ module Ace
           # Build command
           cmd = build_command(package, test_options)
 
-          # Start the process
-          # Strip assignment context vars to prevent tests from resolving to wrong assignments
-          env = ENV.to_h.merge({
-            "ACE_ASSIGN_ID" => nil,
-            "ACE_ASSIGN_FORK_ROOT" => nil
-          })
+          # Launch each package from its own hermetic fixture environment so
+          # parallel workers never share (or leak) ambient Lab/ACE/user state.
+          # Suite-level fixture configuration propagates to the package worker
+          # through the runner-internal channel; the worker merges it under its
+          # own runner configuration and the channel never reaches test children.
+          fixture_environment = Molecules::FixtureEnvironment.new(
+            policy: @environment_policy,
+            parent_env: ENV.to_h
+          ).build
+          fixture_environment.env[Models::EnvironmentPolicy::SUITE_CHANNEL_KEY] =
+            @environment_policy.channel_payload
+
           start_time = now
-          stdin, stdout, stderr, thread = Open3.popen3(env, *cmd, chdir: package["path"], pgroup: true)
+          stdin, stdout, stderr, thread = Open3.popen3(
+            fixture_environment.env, *cmd, chdir: package["path"], pgroup: true, unsetenv_others: true
+          )
 
           @processes[package["name"]] = {
             package: package,
@@ -48,6 +58,7 @@ module Ace
             stdin: stdin,
             start_time: start_time,
             callback: callback,
+            fixture_environment: fixture_environment,
             output: +"",
             stderr_output: +"",
             report_root: test_options["report_dir"],
@@ -99,6 +110,7 @@ module Ace
               collect_remaining_output(process_info)
               results = build_results(process_info, elapsed, exit_status)
               close_streams(process_info)
+              process_info[:fixture_environment]&.cleanup
 
               # Final callback
               if callback
@@ -164,6 +176,7 @@ module Ace
             end
 
             close_streams(process_info)
+            process_info[:fixture_environment]&.cleanup
           end
 
           @processes.clear
@@ -180,7 +193,15 @@ module Ace
         private
 
         def build_command(package, options)
-          cmd_parts = ["ace-test"]
+          # Run the child with this suite's own Ruby binary and a bundler
+          # bootstrap: the hermetic fixture env blocks RUBYOPT/BUNDLE_/GEM_ and
+          # redirects HOME/XDG, so a PATH-resolved interpreter can fail through
+          # manager shims and children have no dependency surface beyond the
+          # Ruby install's default gem dir. -rbundler/setup makes bundler
+          # discover the checkout Gemfile by walking up from the package cwd,
+          # giving every child the same source-of-truth dependency set without
+          # ambient env or globally installed gems.
+          cmd_parts = [RbConfig.ruby, "-rbundler/setup", ace_test_executable]
 
           # Suite package execution intentionally bypasses grouped mode so each
           # package runs its full target scope as one batch under suite orchestration.
@@ -207,6 +228,10 @@ module Ace
           cmd_parts
         end
 
+        def ace_test_executable
+          File.expand_path("../../../../exe/ace-test", __dir__)
+        end
+
         def now
           @clock.call
         end

data/lib/ace/test_runner/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module TestRunner
-    VERSION = "0.26.0"
+    VERSION = "0.27.1"
   end
 end

data/lib/ace/test_runner.rb

@@ -15,6 +15,12 @@ require "time"
 
 require_relative "test_runner/version"
 
+module Ace
+  module TestRunner
+    class Error < StandardError; end
+  end
+end
+
 # CLI and commands
 require_relative "test_runner/cli"
 
@@ -23,6 +29,7 @@ require_relative "test_runner/models/test_result"
 require_relative "test_runner/models/test_failure"
 require_relative "test_runner/models/test_configuration"
 require_relative "test_runner/models/test_report"
+require_relative "test_runner/models/environment_policy"
 
 # Atoms - Basic utilities (always needed)
 require_relative "test_runner/atoms/test_detector"
@@ -32,8 +39,10 @@ require_relative "test_runner/atoms/timestamp_generator"
 require_relative "test_runner/atoms/lazy_loader"
 require_relative "test_runner/atoms/report_path_resolver"
 require_relative "test_runner/atoms/report_directory_resolver"
+require_relative "test_runner/atoms/environment_sanitizer"
 
 # Molecules - Core operations (always needed for basic test running)
+require_relative "test_runner/molecules/fixture_environment"
 require_relative "test_runner/molecules/test_executor"
 require_relative "test_runner/molecules/failure_analyzer"
 require_relative "test_runner/molecules/report_storage"
@@ -54,8 +63,6 @@ require_relative "test_runner/organisms/report_generator"
 
 module Ace
   module TestRunner
-    class Error < StandardError; end
-
     # Define module namespaces
     module Commands; end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-test-runner
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-27 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -171,6 +171,7 @@ files:
 - exe/ace-test-suite
 - lib/ace/test_runner.rb
 - lib/ace/test_runner/atoms/command_builder.rb
+- lib/ace/test_runner/atoms/environment_sanitizer.rb
 - lib/ace/test_runner/atoms/lazy_loader.rb
 - lib/ace/test_runner/atoms/line_number_resolver.rb
 - lib/ace/test_runner/atoms/report_directory_resolver.rb
@@ -187,6 +188,7 @@ files:
 - lib/ace/test_runner/formatters/markdown_formatter.rb
 - lib/ace/test_runner/formatters/progress_file_formatter.rb
 - lib/ace/test_runner/formatters/progress_formatter.rb
+- lib/ace/test_runner/models/environment_policy.rb
 - lib/ace/test_runner/models/test_configuration.rb
 - lib/ace/test_runner/models/test_failure.rb
 - lib/ace/test_runner/models/test_report.rb
@@ -197,6 +199,7 @@ files:
 - lib/ace/test_runner/molecules/deprecation_fixer.rb
 - lib/ace/test_runner/molecules/failed_package_reporter.rb
 - lib/ace/test_runner/molecules/failure_analyzer.rb
+- lib/ace/test_runner/molecules/fixture_environment.rb
 - lib/ace/test_runner/molecules/in_process_runner.rb
 - lib/ace/test_runner/molecules/package_resolver.rb
 - lib/ace/test_runner/molecules/pattern_resolver.rb