ace-test-runner-e2e 0.40.6 → 0.42.0

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

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "rubygems/version"
+
+module Ace
+  module Test
+    module EndToEndRunner
+      module Molecules
+        # Validates the frozen release installation manifest used by release
+        # verification scenarios (TS-MONO-001).
+        #
+        # The manifest is an exact-version contract: schema_version 1, a full
+        # source commit, and a nonempty package array. Every package entry
+        # carries a unique ACE gem name, one exact artifact version (never a
+        # requirement), the full source commit the artifact was built from,
+        # and an optional explicit supersession list of earlier versions of
+        # the same package.
+        #
+        # Validation is strict on purpose: unknown fields, missing fields,
+        # duplicate names, non-exact versions, malformed SHAs, and
+        # contradictory supersession entries all fail before any install
+        # attempt is made.
+        class ReleaseManifest
+          SCHEMA_VERSION = 1
+          GEM_NAME_PATTERN = /\Aace-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z/
+          SOURCE_SHA_PATTERN = /\A[0-9a-f]{40}\z/
+
+          # Raised for any manifest content or source-path failure. Setup
+          # converts this into a setup failure before installation runs.
+          class Invalid < StandardError; end
+
+          # Validate the manifest at +path+ and return its parsed content.
+          # @raise [Invalid] when the file is missing, unreadable,
+          #   malformed, or violates the schema.
+          def self.load_validated(path)
+            data = parse_json(path)
+            validate_schema!(data)
+            data
+          end
+
+          # Validate the manifest at +source_path+ and copy the exact bytes
+          # to +target_path+, creating the target directory when needed.
+          # +required_packages+ names the gems the calling scenario's proof
+          # depends on; the manifest must cover every one of them. Entries
+          # may be plain names or {name, supersedes} maps requiring an
+          # explicit supersession declaration. The buffer is read once so
+          # the validated content, the written copy, and the returned digest
+          # are the same bytes even if the source file changes mid-flight.
+          # @raise [Invalid]
+          def self.validate_and_copy(source_path:, target_path:, required_packages: nil)
+            raw = read_source(source_path)
+            data = parse_buffer(raw, source_path)
+            validate_schema!(data)
+            entries = data["packages"].to_h { |package| [package["name"], package] }
+            Array(required_packages).each do |required|
+              name, supersedes = required_packages_entry(required)
+              entry = entries[name]
+              raise Invalid, "release manifest is missing required package: #{name}" unless entry
+
+              missing = Array(supersedes) - Array(entry["supersedes"])
+              next if missing.empty?
+
+              raise Invalid,
+                "release manifest does not declare that #{name} #{entry["artifact_version"]} supersedes #{missing.join(", ")}"
+            end
+            FileUtils.mkdir_p(File.dirname(target_path))
+            File.binwrite(target_path, raw)
+            Digest::SHA256.hexdigest(raw)
+          end
+
+          class << self
+            private
+
+            def read_source(path)
+              raise Invalid, "release manifest is missing: #{path}" unless File.file?(path)
+              raise Invalid, "release manifest is not readable: #{path}" unless File.readable?(path)
+
+              raw = File.binread(path)
+              raise Invalid, "release manifest is empty: #{path}" if raw.strip.empty?
+
+              raw
+            end
+
+            def parse_buffer(raw, path)
+              data = JSON.parse(raw)
+              raise Invalid, "release manifest must be a JSON object: #{path}" unless data.is_a?(Hash)
+
+              data
+            rescue JSON::ParserError => e
+              raise Invalid, "release manifest is not valid JSON: #{path} (#{e.message})"
+            end
+
+            def parse_json(path)
+              parse_buffer(read_source(path), path)
+            end
+
+            def validate_schema!(data)
+              reject_unknown_keys!(data, %w[schema_version source_sha packages], "manifest")
+
+              schema_version = data["schema_version"]
+              unless schema_version.is_a?(Integer) && schema_version == SCHEMA_VERSION
+                raise Invalid,
+                  "unsupported schema_version: #{schema_version.inspect} (expected #{SCHEMA_VERSION})"
+              end
+
+              validate_source_sha!(data["source_sha"], "manifest source_sha")
+
+              packages = data["packages"]
+              raise Invalid, "packages must be a nonempty array" unless packages.is_a?(Array) && !packages.empty?
+
+              seen = {}
+              packages.each_with_index do |entry, index|
+                name = validate_package!(entry, index)
+                raise Invalid, "duplicate package name: #{name}" if seen.key?(name)
+
+                seen[name] = true
+              end
+            end
+
+            def validate_package!(entry, index)
+              label = "packages[#{index}]"
+              raise Invalid, "#{label} must be an object" unless entry.is_a?(Hash)
+
+              reject_unknown_keys!(entry, %w[name artifact_version source_sha supersedes], label)
+
+              name = entry["name"]
+              unless name.is_a?(String) && name.match?(GEM_NAME_PATTERN)
+                raise Invalid, "#{label} has invalid ACE gem name: #{name.inspect}"
+              end
+
+              validate_exact_version!(entry["artifact_version"], "#{label}(#{name}) artifact_version")
+              validate_source_sha!(entry["source_sha"], "#{label}(#{name}) source_sha")
+              validate_supersedes!(entry["supersedes"], entry["artifact_version"], "#{label}(#{name})")
+              name
+            end
+
+            def validate_exact_version!(raw, label)
+              unless raw.is_a?(String) && !raw.strip.empty?
+                raise Invalid, "#{label} must be an exact version string, got #{raw.inspect}"
+              end
+
+              version = begin
+                Gem::Version.new(raw)
+              rescue ArgumentError
+                raise Invalid, "#{label} is not a valid version: #{raw.inspect}"
+              end
+
+              return if version.to_s == raw
+
+              raise Invalid,
+                "#{label} must be an exact version, not a requirement or shorthand: #{raw.inspect}"
+            end
+
+            def validate_source_sha!(raw, label)
+              return if raw.is_a?(String) && raw.match?(SOURCE_SHA_PATTERN)
+
+              raise Invalid, "#{label} must be a full 40-character commit SHA, got #{raw.inspect}"
+            end
+
+            def validate_supersedes!(raw, artifact_version, label)
+              return if raw.nil?
+
+              unless raw.is_a?(Array)
+                raise Invalid, "#{label} supersedes must be an array of version strings"
+              end
+
+              artifact = Gem::Version.new(artifact_version)
+              seen = {}
+              raw.each do |entry|
+                validate_exact_version!(entry, "#{label} supersedes entry")
+                raise Invalid, "#{label} supersedes duplicates version #{entry}" if seen.key?(entry)
+
+                seen[entry] = true
+                next unless Gem::Version.new(entry) >= artifact
+
+                raise Invalid,
+                  "#{label} supersedes must list earlier versions of the same package: #{entry} >= #{artifact_version}"
+              end
+            end
+
+            def reject_unknown_keys!(hash, allowed, label)
+              unknown = hash.keys - allowed
+              return if unknown.empty?
+
+              raise Invalid, "#{label} has unknown fields: #{unknown.sort.join(", ")}"
+            end
+
+            def required_packages_entry(required)
+              case required
+              when String
+                [required, nil]
+              when Hash
+                reject_unknown_keys!(required, %w[name supersedes], "required package entry")
+                name = required["name"]
+                unless name.is_a?(String) && name.match?(GEM_NAME_PATTERN)
+                  raise Invalid, "required package entry has invalid ACE gem name: #{name.inspect}"
+                end
+
+                [name, required["supersedes"]]
+              else
+                raise Invalid, "required package entries must be names or {name, supersedes} maps"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -222,6 +222,11 @@ module Ace
             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")
+            metadata["failure_category"] = result.metadata["failure_category"] if result.metadata.key?("failure_category")
+            metadata["failure_phase"] = result.metadata["failure_phase"] if result.metadata.key?("failure_phase")
+            metadata["uncertain_execution"] = result.metadata["uncertain_execution"] if result.metadata.key?("uncertain_execution")
+            metadata["execution_evidence"] = result.metadata["execution_evidence"] if result.metadata.key?("execution_evidence")
+            metadata["incomplete_verdict_set"] = result.metadata["incomplete_verdict_set"] if result.metadata.key?("incomplete_verdict_set")
 
             if test_case
               metadata["scenario-id"] = scenario.test_id

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

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
+require "digest"
 require "fileutils"
+require "json"
 require "open3"
 require "shellwords"
+require "time"
+
+require_relative "release_manifest"
 
 module Ace
   module Test
@@ -12,7 +17,8 @@ module Ace
         #
         # Processes the setup array from scenario.yml, running each action
         # via Ruby system calls (no LLM involved). Supports: git-init,
-        # copy-fixtures, run, write-file, agent-env, and tmux-session actions.
+        # copy-fixtures, run, write-file, agent-env, runtime-session, and
+        # release-manifest actions.
         #
         # Note: This is a Molecule because it performs filesystem I/O and
         # system calls via Open3 and FileUtils.
@@ -22,7 +28,22 @@ module Ace
           STRIPPED_ENV_KEYS = %w[RUBYOPT RUBYLIB].freeze
           RESERVED_ENV_KEYS = Molecules::SandboxRuntimeBuilder::RESERVED_ENV_KEYS + %w[
             PATH HOME TMPDIR XDG_RUNTIME_DIR TMUX_TMPDIR ACE_TMUX_SESSION
+            ACE_RUNTIME HERDR_SESSION HERDR_PANE HERDR_WORKSPACE_ID
           ]
+          RELEASE_MANIFEST_DEFAULT_PATH = File.join(".ace-local", "release", "installation-manifest.json")
+          # Retry trust state lives in the report directory — host-side,
+          # outside the runner-writable sandbox. A marker inside the sandbox
+          # would let a compromised runner forge reuse state, redirect
+          # manifest copies outside the sandbox, or skip revalidation.
+          SETUP_STATE_FILE = ".ace-e2e-setup-state.json"
+          # Only the sandbox runtime contract is persisted for reuse. The
+          # merged setup environment inherits the host process environment,
+          # which can carry secrets that must never land in a state file.
+          PERSISTED_ENV_KEYS = (
+            Molecules::SandboxRuntimeBuilder::RESERVED_ENV_KEYS + %w[
+              PATH ACE_E2E_SANDBOX_RUNTIME_ROOT ACE_E2E_SANDBOX_RUBY_VERSION ACE_E2E_SANDBOX_RUBY_ROOT
+            ]
+          ).freeze
 
           def initialize(command_runner: nil, system_runner: nil, time_source: nil, sandbox_backend: nil)
             @command_runner = command_runner || method(:capture3)
@@ -36,20 +57,45 @@ module Ace
           # @param setup_steps [Array] Setup steps from scenario.yml
           # @param sandbox_dir [String] Path to the sandbox directory
           # @param fixture_source [String, nil] Path to the fixtures/ directory
-          # @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
+          # @param scenario_name [String, nil] Test ID for runtime session naming (e.g., "TS-OVERSEER-001")
+          # @param run_id [String, nil] Unique run ID for deterministic runtime session naming
+          # @param release_manifest_path [String, nil] Explicit absolute manifest path carried
+          #   from the invoking process (ACE_RELEASE_MANIFEST). When nil, the release-manifest
+          #   step falls back to the default path under ACE_E2E_SOURCE_ROOT.
+          # @param state_file [String, nil] Host-side path (report directory) for retry
+          #   state. When nil, no retry state is recorded and the sandbox is never reused.
+          # @return [Hash] Result with :success, :steps_completed, :error, :env, :runtime_session keys
           def execute(setup_steps:, sandbox_dir:, fixture_source: nil, scenario_name: nil, run_id: nil, initial_env: {},
-            git_excludes: [])
+            git_excludes: [], release_manifest_path: nil, state_file: nil)
+            # Initialized before any filesystem operation: an early failure
+            # must reach the rescue as a clean setup failure, not as a
+            # secondary error from nil state.
+            env = {}
+            steps_completed = 0
+            @runtime_session = nil
+            @teardown_env = nil
             FileUtils.mkdir_p(sandbox_dir)
+            # A rerun invalidates any earlier success up front: state is
+            # recreated only after every step and the persisted env succeed.
+            if state_file
+              FileUtils.rm_f(state_file)
+              # The prior attempt's completion record must never bless a
+              # retried run that fails before rewriting it.
+              FileUtils.rm_f(File.join(File.dirname(state_file), "metadata.yml"))
+            end
+            # Prior-attempt goal evidence must never survive into a retried
+            # run: the goals rebuild results/ from scratch.
+            FileUtils.rm_rf(File.join(sandbox_dir, "results"))
             env = if @sandbox_backend
               @sandbox_backend.prepared_env(initial_env.dup)
             else
               initial_env.dup
             end
             @git_excludes = normalize_git_excludes(git_excludes)
+            @release_manifest_input = release_manifest_path
+            @release_manifest_state = nil
             steps_completed = 0
-            @tmux_session = nil
+            @runtime_session = nil
             @scenario_name = scenario_name
             @run_id = run_id
             @teardown_env = nil
@@ -58,13 +104,41 @@ module Ace
               execute_step(step, sandbox_dir, env, fixture_source)
               steps_completed += 1
             end
+            merged = merged_environment(env)
+            if state_file
+              FileUtils.mkdir_p(File.dirname(state_file))
+              persisted = merged.slice(*PERSISTED_ENV_KEYS).compact
+              # The live value may be relative (agent-env PROJECT_ROOT_PATH: .);
+              # the persisted contract must be absolute so a reused sandbox is
+              # recognized as prepared by the pipeline.
+              if persisted["PROJECT_ROOT_PATH"] && !persisted["PROJECT_ROOT_PATH"].start_with?("/")
+                persisted["PROJECT_ROOT_PATH"] = File.expand_path(persisted["PROJECT_ROOT_PATH"], sandbox_dir)
+              end
+              generated_gemfile = File.join(sandbox_dir, "Gemfile")
+              source_root = env["ACE_E2E_SOURCE_ROOT"].to_s
+              source_gemfile = source_root.empty? ? nil : File.join(source_root, "Gemfile")
+              File.write(state_file, JSON.generate({
+                "completed_at" => Time.now.utc.iso8601,
+                "sandbox_dir" => sandbox_dir,
+                "setup_steps" => self.class.normalize_state_steps(setup_steps),
+                "release_manifest" => @release_manifest_state,
+                "env" => persisted,
+                "gemfile" => {
+                  # The sandbox Gemfile is derived from the source root's
+                  # Gemfile; a retry must regenerate it when either changes.
+                  "source_root" => source_root,
+                  "source_digest" => source_gemfile && File.file?(source_gemfile) ? Digest::SHA256.file(source_gemfile).hexdigest : nil,
+                  "generated_digest" => File.file?(generated_gemfile) ? Digest::SHA256.file(generated_gemfile).hexdigest : nil
+                }
+              }))
+            end
 
             {
               success: true,
               steps_completed: steps_completed,
               error: nil,
-              env: merged_environment(env),
-              tmux_session: @tmux_session
+              env: merged,
+              runtime_session: @runtime_session
             }
           rescue => e
             {
@@ -72,24 +146,24 @@ module Ace
               steps_completed: steps_completed,
               error: e.message,
               env: merged_environment(env),
-              tmux_session: @tmux_session
+              runtime_session: @runtime_session
             }
           end
 
-          # Clean up resources created during setup (e.g. tmux session)
+          # Clean up resources created during setup (e.g. tmux runtime session)
           def teardown
-            return unless @tmux_session
+            return unless @runtime_session
 
             if @sandbox_backend
               @sandbox_backend.capture3(
-                ["tmux", "kill-session", "-t", @tmux_session],
+                ["tmux", "kill-session", "-t", @runtime_session],
                 chdir: @teardown_env&.fetch("PROJECT_ROOT_PATH", Dir.pwd) || Dir.pwd,
                 env: @teardown_env || {}
               )
             else
-              @system_runner.call("tmux", "kill-session", "-t", @tmux_session, out: File::NULL, err: File::NULL)
+              @system_runner.call("tmux", "kill-session", "-t", @runtime_session, out: File::NULL, err: File::NULL)
             end
-            @tmux_session = nil
+            @runtime_session = nil
           end
 
           private
@@ -106,8 +180,8 @@ module Ace
               handle_git_init(sandbox_dir, env)
             when "copy-fixtures"
               handle_copy_fixtures(sandbox_dir, fixture_source)
-            when "tmux-session"
-              handle_tmux_session(env)
+            when "runtime-session"
+              handle_runtime_session(env)
             when Hash
               execute_hash_step(step, sandbox_dir, env)
             else
@@ -127,15 +201,31 @@ module Ace
               handle_write_file(value["path"], value["content"], sandbox_dir)
             when "agent-env"
               handle_env(value, env)
-            when "tmux-session"
-              handle_tmux_session(env, value)
+            when "runtime-session"
+              handle_runtime_session(env, value)
+            when "release-manifest"
+              handle_release_manifest(value, sandbox_dir, env)
             else
               raise ArgumentError, "Unknown setup step type: #{key.inspect}"
             end
           end
 
-          # Create an isolated detached tmux session and store its name in env
-          def handle_tmux_session(env, config = nil)
+          # Establish a live terminal runtime context for the scenario.
+          # runtime "tmux" (default) creates an isolated detached tmux
+          # session and exports ACE_TMUX_SESSION + ACE_RUNTIME=tmux.
+          # runtime "herdr" requires the caller's live HERDR_SESSION and
+          # HERDR_PANE (herdr workspaces are operator-owned; the runner
+          # never fabricates one) and exports ACE_RUNTIME=herdr. An absent
+          # herdr context fails the step explicitly — no scripted stand-in.
+          def handle_runtime_session(env, config = nil)
+            runtime = config.is_a?(Hash) ? config["runtime"].to_s.strip : ""
+            runtime = "tmux" if runtime.empty?
+            unless %w[tmux herdr].include?(runtime)
+              raise ArgumentError, "runtime-session supports runtimes: tmux, herdr (got '#{runtime}')"
+            end
+
+            return handle_herdr_session(env) if runtime == "herdr"
+
             name_source = config.is_a?(Hash) ? config["name-source"] : nil
             session_name = if name_source == "run-id" && @run_id && !@run_id.to_s.empty?
               @run_id
@@ -154,8 +244,23 @@ module Ace
             end
             raise "Failed to create tmux session '#{session_name}': #{stderr.strip}" unless status.success?
 
-            @tmux_session = session_name
+            @runtime_session = session_name
             env["ACE_TMUX_SESSION"] = session_name
+            env["ACE_RUNTIME"] = "tmux"
+            @teardown_env = merged_environment(env)
+          end
+
+          def handle_herdr_session(env)
+            merged = merged_environment(env)
+            herdr_session = merged["HERDR_SESSION"].to_s.strip
+            herdr_pane = merged["HERDR_PANE"].to_s.strip
+            if herdr_session.empty? || herdr_pane.empty?
+              raise "runtime-session herdr requires a live herdr context (HERDR_SESSION and HERDR_PANE); run this scenario inside herdr"
+            end
+
+            env["HERDR_SESSION"] = herdr_session
+            env["HERDR_PANE"] = herdr_pane
+            env["ACE_RUNTIME"] = "herdr"
             @teardown_env = merged_environment(env)
           end
 
@@ -219,6 +324,180 @@ module Ace
             end
           end
 
+          # Validate the frozen release manifest and copy its exact bytes into
+          # the sandbox. The source is the explicitly allowed input carried
+          # from the invoking process (ACE_RELEASE_MANIFEST, absolute path);
+          # without it, the default path under ACE_E2E_SOURCE_ROOT is used.
+          # Any missing, unreadable, malformed, or conflicting manifest raises
+          # here so setup fails before any install goal can run.
+          def handle_release_manifest(config, sandbox_dir, env)
+            target = config.is_a?(Hash) ? config["to"] : config
+            raise ArgumentError, "release-manifest step requires a target path" if target.to_s.strip.empty?
+
+            required = config.is_a?(Hash) ? Array(config["require"]) : []
+            source = release_manifest_source(env)
+            # The scenario declares the destination; the copy itself is still
+            # confined to the sandbox with no symlinked path components.
+            target_path = self.class.validated_manifest_target(sandbox_dir, target)
+            raise ArgumentError, "release-manifest target escapes the sandbox: #{target}" unless target_path
+
+            FileUtils.mkdir_p(File.dirname(target_path))
+            digest = Molecules::ReleaseManifest.validate_and_copy(
+              source_path: source,
+              target_path: target_path,
+              required_packages: required
+            )
+            @release_manifest_state = {
+              "source" => File.expand_path(source),
+              "target" => target,
+              "digest" => digest
+            }
+          end
+
+          def release_manifest_source(env)
+            self.class.release_manifest_source_for(env, @release_manifest_input)
+          end
+
+          class << self
+            # Retry state for a completed setup. Returns nil when there is no
+            # usable state (no file, unreadable, from another sandbox, or
+            # recorded for different setup steps).
+            def setup_state_for(state_file, sandbox_dir, setup_steps: nil)
+              return nil unless state_file && File.file?(state_file)
+
+              state = JSON.parse(File.read(state_file))
+              return nil unless state.is_a?(Hash)
+              return nil unless state["sandbox_dir"] &&
+                File.expand_path(state["sandbox_dir"]) == File.expand_path(sandbox_dir)
+              return nil if setup_steps && state["setup_steps"] != normalize_state_steps(setup_steps)
+
+              state
+            rescue JSON::ParserError, SystemCallError
+              nil
+            end
+
+            def normalize_state_steps(setup_steps)
+              Array(setup_steps).map { |step| step.is_a?(Hash) ? [step.keys.first, step.values.first] : step }
+            end
+
+            # The manifest copy destination comes from trusted setup state,
+            # but the runner controls the sandbox filesystem in between: a
+            # symlinked path component could redirect the host-side write
+            # outside the sandbox. Parent components must be real
+            # directories; the final component may be an existing regular
+            # file (the previous validated copy).
+            def validated_manifest_target(sandbox_dir, target)
+              sandbox_root = File.expand_path(sandbox_dir)
+              # A symlinked sandbox root would redirect every confinement
+              # check below it.
+              return nil if File.lstat(sandbox_root).symlink?
+              relative = target.to_s.split("/")
+              current = sandbox_root
+              components = relative.reject { |part| part.empty? || part == "." }
+              components.each_with_index do |part, index|
+                current = File.join(current, part)
+                # lstat every component: File.exist? follows symlinks, so a
+                # dangling symlink would slip past an existence check and the
+                # write would create its target outside the sandbox. ENOENT
+                # means the component is genuinely absent (created fresh by
+                # mkdir_p); any other stat failure rejects reuse.
+                lstat = begin
+                  File.lstat(current)
+                rescue Errno::ENOENT
+                  next
+                rescue SystemCallError
+                  return nil
+                end
+                return nil if lstat.symlink?
+
+                last = index == components.size - 1
+                if last
+                  return nil if lstat.directory?
+                elsif !lstat.directory?
+                  return nil
+                end
+              end
+              resolved = File.expand_path(current)
+              return nil unless resolved.start_with?(sandbox_root + File::SEPARATOR)
+
+              resolved
+            rescue SystemCallError
+              nil
+            end
+
+            # Revalidate the current manifest input against a completed
+            # sandbox before it is reused: the validated copy in the sandbox
+            # must still match the invoking process's manifest. Returns true
+            # when reuse may proceed (no manifest gate recorded, or the
+            # current input hashes to the recorded digest); false when the
+            # sandbox must be set up again.
+            def revalidate_release_manifest(state_file:, sandbox_dir:, explicit: nil, setup_steps: nil)
+              state = setup_state_for(state_file, sandbox_dir, setup_steps: setup_steps)
+              return false unless state
+
+              recorded = state["release_manifest"]
+              return true if recorded.nil?
+
+              target_path = validated_manifest_target(sandbox_dir, recorded["target"])
+              return false unless target_path
+
+              source = begin
+                release_manifest_source_for(state["env"] || {}, explicit)
+              rescue Molecules::ReleaseManifest::Invalid
+                return false
+              end
+
+              # The source path itself must be the recorded one: an identical
+              # copy at a different path would be rejected by finalization's
+              # recorded-source binding, so reuse must not accept it either.
+              return false unless File.expand_path(source) == File.expand_path(recorded["source"].to_s)
+
+              # Read once: the digest check and the copy must see the same
+              # bytes even if the source changes mid-revalidation.
+              raw = begin
+                File.binread(source)
+              rescue SystemCallError
+                return false
+              end
+              return false if Digest::SHA256.hexdigest(raw) != recorded["digest"]
+
+              FileUtils.mkdir_p(File.dirname(target_path))
+              File.binwrite(target_path, raw)
+              true
+            end
+
+            # Retry reuse rebuilds the environment from the allow-listed
+            # runtime keys only (same boundary as initial setup), overlaid
+            # with the recorded sandbox runtime paths. Host secrets — even
+            # ones present in the current process — never reach the runner.
+            def build_reuse_env(state_env)
+              (PERSISTED_ENV_KEYS | %w[HOME PATH TMPDIR]).each_with_object({}) do |key, env|
+                value = state_env[key]
+                env[key] = value unless value.nil?
+              end
+            end
+
+            def release_manifest_source_for(env, explicit)
+              explicit = explicit.to_s.strip
+              if explicit.empty?
+                source_root = env["ACE_E2E_SOURCE_ROOT"].to_s.strip
+                if source_root.empty?
+                  raise Molecules::ReleaseManifest::Invalid,
+                    "no release manifest input and no ACE_E2E_SOURCE_ROOT to derive the default path"
+                end
+                return File.join(source_root, RELEASE_MANIFEST_DEFAULT_PATH)
+              end
+
+              unless explicit.start_with?("/")
+                raise Molecules::ReleaseManifest::Invalid,
+                  "ACE_RELEASE_MANIFEST must be an absolute JSON file path, got: #{explicit}"
+              end
+
+              explicit
+            end
+          end
+
+
           # Merge custom env vars with the process environment
           #
           # @param env [Hash] Custom environment variables