agent-harness 0.5.8 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93f5a11872f464b3eb9834c849f076d9f393f9e1174bc9824952f4c217c9278f
-  data.tar.gz: 25bbd835fd6739f84597d0d5653443ecd238b0e89f20f5e0b20029cb5d8bb119
+  metadata.gz: f476f6224ed25cc79c7bc9c8fb239c1df9f787cd59ff279b8c509b7d515d2727
+  data.tar.gz: c0faee9c6d5c139db019707b9174d2d25a4a2fc4a85684ce55eb7baede9fd3be
 SHA512:
-  metadata.gz: '081955132b518b5d94498bfeb54ddd7641f1d6968fcb53debf143f7762a666edd40dde6a1369553a42c0dc4985cbff9cb41d7ade8dd727fa80572e7a7293cd2f'
-  data.tar.gz: 0345fc32a87b27ba001ae0a6cd26c5b1cc2765f64d7d81bad025b461182cdb0a814c8cdd031478b4e7dcf8bbe1f6b2638e3814cbf3c9537e038dc8bca1255a1f
+  metadata.gz: 113c0d8afbf5e77c6abcb1f78f0793646b72137e48a9776bfd951ee98c5412d3606628ea19ce4b105a6d8c05d1143a12a5607e1bad82462c629f6bdf3907985b
+  data.tar.gz: 4cc2f012c75314a2d096147e4bae9afbed565181878a907339410f7cfdb3ea0cff03e96704a6d3d93cd4f3825eb9f21a97d5351b852d72ec4e09b21a3359df68

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.8"
+  ".": "0.5.9"
 }

data/AUDIT_DISPOSITION.md

@@ -0,0 +1,111 @@
+# PR Review Audit Disposition (Issue #91)
+
+Audit of PRs merged before review completion in `viamin/agent-harness`.
+
+## P1 PRs
+
+### PR #55 — Per-request provider runtime overrides
+
+| Finding | Disposition |
+| ------- | ----------- |
+| env stringifies only keys, not values | Fixed in PR #55 itself |
+| Token tracking uses config model instead of runtime model | Fixed in PR #55 itself |
+| nil env/metadata raises NoMethodError | Fixed in PR #55 itself |
+| flags values not validated as Strings | Fixed in PR #55 itself |
+| Adapter Hash-to-ProviderRuntime docs misleading | Fixed in PR #55 itself |
+| `Array(flags)` freezes caller's array | Fixed in PR #55 itself |
+| freezes caller-provided metadata Hash | Fixed in PR #55 itself |
+| env type validation missing | Fixed in PR #55 itself |
+| `.from_hash` no input type check | Fixed in PR #55 itself |
+| flags accepts single String silently | Fixed in PR #55 itself |
+| Cursor never normalizes/uses provider_runtime | Fixed in PR #55 itself |
+| Cursor reimplements build_env instead of calling super | Fixed in PR #55 itself |
+| runtime.model CLI vs telemetry mismatch | Fixed in PR #55 itself |
+| Missing precedence spec | Fixed in PR #55 itself |
+| `.wrap` kwargs bug on Ruby >= 3.2 | Fixed in PR #55 itself |
+| runtime.model precedence unclear | Fixed in PR #55 itself |
+| **base_url/model/api_provider not type-validated** | **Fixed forward in this PR** |
+| **`.from_hash` treats `false` same as missing** | **Fixed forward in this PR** (hash_value helper) |
+| Cursor not mentioned in PR description | Accepted (docs-only, no code impact) |
+
+### PR #81 — Kilocode CLI installation contract
+
+| Finding | Disposition |
+| ------- | ----------- |
+| `installation_contract` can raise NoMethodError for non-Adapter providers | Fixed in PR #81 itself |
+| `provider_installation_contract` doesn't forward `version:` | Fixed in PR #81 itself |
+| Default `installation_contract` doesn't accept `**options` | Fixed in PR #81 itself |
+| Registry forwards `**options` unconditionally | Fixed in PR #81 itself |
+| **`install_command` doesn't handle `version: nil`** | Accepted (produces clear error message via Gem::Version coercion) |
+| **`validate_install_version!` gives generic error for bad input** | **Fixed forward in this PR** |
+
+### PR #57 — Provider configuration capabilities
+
+| Finding | Disposition |
+| ------- | ----------- |
+| All 19 findings (schema field removal, auth_modes derivation, model hints, accepts_arbitrary alignment) | All fixed in PR #57 itself across 5 review rounds |
+
+### PR #42 — Gemini and Codex health/auth checks
+
+| Finding | Disposition |
+| ------- | ----------- |
+| Temp dir from Dir.mktmpdir never cleaned up | Fixed in PR #42 itself |
+| Config-file API key not validated for sk- prefix | Fixed in PR #42 itself |
+| Error message hardcodes ~/.codex/config.json | Fixed in PR #42 itself |
+| default_flags assumed to be Array, no guard | Fixed in PR #42 itself |
+| Error message only mentions GEMINI_API_KEY | Fixed in PR #42 itself |
+| validate_config doesn't check model/flags types | Fixed in PR #42 itself |
+| JSON parse error leaks credential file contents | Fixed in PR #42 itself |
+| Blank GEMINI_API_KEY doesn't fall back | Fixed in PR #42 itself |
+| validate_config validates default_flags but build_command never uses them | Fixed in PR #42 itself |
+| build_command raises if default_flags is non-Array | Fixed in PR #42 itself |
+| auth_status assumes parsed JSON is Hash | Fixed in PR #42 itself |
+| **auth_status returns inconsistent hash shape (missing auth_method)** | **Fixed forward in this PR** (both Codex and Gemini) |
+| **Numeric status-code regexes can match unrelated numbers** | **Fixed forward in this PR** (added `\b` word boundaries) |
+
+## P2 PRs
+
+### PR #16 — DockerCommandExecutor
+
+| Finding | Disposition |
+| ------- | ----------- |
+| Duplicated `normalize_command` method | Already resolved (inherits from protected parent) |
+| `which` missing timeout | Already resolved (timeout: 5 added) |
+| **container_id not validated for whitespace-only** | **Fixed forward in this PR** |
+| Test stubs don't assert command arguments | Accepted (test quality, not a runtime defect) |
+
+### PR #83 — OpenCode CLI installation contract
+
+| Finding | Disposition |
+| ------- | ----------- |
+| No unresolved review comments | No action needed |
+
+### PR #80 — Gemini CLI installation contract
+
+| Finding | Disposition |
+| ------- | ----------- |
+| `install_contract` signature mismatch between base adapter and callers | Already resolved in current adapter.rb |
+| No guard for providers without `install_contract` | Already resolved in registry.rb |
+| **Malformed version strings not handled gracefully** | Already resolved (Gemini rescues ArgumentError from Gem::Version) |
+| Missing test coverage for edge cases | Accepted (test quality, not a runtime defect) |
+
+### PR #1 — Initial extraction
+
+| Finding | Disposition |
+| ------- | ----------- |
+| `timecop` gem not declared in Gemfile | Already resolved (timecop removed from codebase) |
+| Missing YamlLoader/EnvLoader files | Already resolved (references removed) |
+| README binary name for Cursor incorrect | Already resolved (README says cursor-agent, matches code) |
+| README binary name for GitHub Copilot incorrect | Already resolved (README updated) |
+| bin/ excluded from gemspec | Accepted (intentional for gem packaging) |
+
+## Summary of fixes in this PR
+
+1. **ProviderRuntime**: Added type validation for `model`, `base_url`, `api_provider` (must be String or nil)
+2. **ProviderRuntime**: Replaced `||`-based hash key lookup in `.from_hash` with `hash_value` helper that distinguishes nil from missing keys
+3. **Codex auth_status**: Added consistent `auth_method` key to all return paths
+4. **Gemini auth_status**: Added consistent `auth_method` key to all return paths
+5. **Codex error_patterns**: Added `\b` word boundaries to `/401/` regex
+6. **Gemini error_patterns**: Added `\b` word boundaries to `/429/` and `/503/` regexes
+7. **Kilocode**: `validate_install_version!` now rescues malformed version strings with a provider-specific error message
+8. **DockerCommandExecutor**: Validates whitespace-only `container_id` values

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.5.9](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.8...agent-harness/v0.5.9) (2026-04-12)
+
+
+### Bug Fixes
+
+* 91: audit and fix-forward defects from PRs merged before review completion ([ec0af12](https://github.com/viamin/agent-harness/commit/ec0af12728f6524b651ebc9b552c477059a2adac))
+* **providers:** close path traversal bypass in env-var-prefixed preparation paths ([493bf55](https://github.com/viamin/agent-harness/commit/493bf55be088a8bde39d143791f3f9b0c90d9c0c))
+* **providers:** harden preparation path validation against env value traversal and command substitution ([ed4b92b](https://github.com/viamin/agent-harness/commit/ed4b92b8760ec4dfa1f50d69b0736563140905b4))
+* **providers:** harden preparation path validation against injection and traversal ([9cb0faf](https://github.com/viamin/agent-harness/commit/9cb0fafbf63c908c7ef7b465bf541ceb5dbf58bb))
+* **providers:** preserve docker idle timeouts ([adde6b4](https://github.com/viamin/agent-harness/commit/adde6b4491023c8baf37249147770cddeff1b0ee))
+
 ## [0.5.8](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.7...agent-harness/v0.5.8) (2026-04-07)
 
 

data/lib/agent_harness/command_executor.rb

@@ -3,6 +3,10 @@
 require "open3"
 require "timeout"
 require "shellwords"
+require "fileutils"
+require "tempfile"
+require "tmpdir"
+require "digest"
 
 module AgentHarness
   # Executes shell commands with timeout support
@@ -18,6 +22,10 @@ module AgentHarness
   # @example With timeout
   #   result = executor.execute("claude --print", timeout: 300)
   class CommandExecutor
+    PREPARATION_LOCK_POLL_INTERVAL = 0.01
+    PREPARATION_CLEANUP_GRACE_PERIOD = 5
+    PREPARATION_LOCK_ROOT = File.join(Dir.tmpdir, "agent-harness-preparation-locks")
+
     # Result of a command execution
     Result = Struct.new(:stdout, :stderr, :exit_code, :duration, keyword_init: true) do
       def success?
@@ -42,6 +50,8 @@ module AgentHarness
     # @param idle_timeout [Integer, Float, nil] idle timeout in seconds based on output activity
     # @param env [Hash] environment variables
     # @param stdin_data [String, nil] data to send to stdin
+    # @param preparation [ExecutionPreparation, nil] request-scoped bootstrap
+    #   work for the runtime environment
     # @param on_stdout_chunk [Proc, nil] callback for stdout chunks as they are produced
     # @param on_stderr_chunk [Proc, nil] callback for stderr chunks as they are produced
     # @param on_heartbeat [Proc, nil] callback invoked periodically while the command is running
@@ -51,7 +61,7 @@ module AgentHarness
     # @return [Result] execution result
     # @raise [TimeoutError] if the command times out
     # @raise [IdleTimeoutError] if the command exceeds the idle timeout
-    def execute(command, timeout: nil, idle_timeout: nil, env: {}, stdin_data: nil,
+    def execute(command, timeout: nil, idle_timeout: nil, env: {}, stdin_data: nil, preparation: nil,
       on_stdout_chunk: nil, on_stderr_chunk: nil, on_heartbeat: nil,
       heartbeat_interval: 1.0, observer: nil)
       validate_duration!(timeout, name: :timeout, allow_nil: true)
@@ -60,28 +70,70 @@ module AgentHarness
 
       cmd_array = normalize_command(command)
       cmd_string = cmd_array.shelljoin
+      command_name = cmd_array.first
+      start_time = current_time
+      deadline = timeout_deadline(timeout)
+      applied_preparation = []
+      held_preparation_locks = []
+      background_cleanup_scheduled = false
 
       log_debug("Executing command",
         command: cmd_string,
         timeout: timeout,
         idle_timeout: idle_timeout)
 
-      start_time = Time.now
-
-      stdout, stderr, status = execute_streaming(
-        cmd_array,
+      held_preparation_locks = acquire_preparation_locks(
+        preparation,
+        env: env,
         timeout: timeout,
-        idle_timeout: idle_timeout,
+        deadline: deadline,
+        command_name: command_name
+      )
+      apply_preparation(
+        preparation,
         env: env,
-        stdin_data: stdin_data,
-        on_stdout_chunk: on_stdout_chunk,
-        on_stderr_chunk: on_stderr_chunk,
-        on_heartbeat: on_heartbeat,
-        heartbeat_interval: heartbeat_interval,
-        observer: observer
+        timeout: timeout,
+        deadline: deadline,
+        command_name: command_name,
+        applied_preparation: applied_preparation
       )
 
-      duration = Time.now - start_time
+      begin
+        stdout, stderr, status = execute_streaming(
+          cmd_array,
+          timeout: remaining_timeout(deadline, timeout:, command_name: command_name),
+          idle_timeout: idle_timeout,
+          env: env,
+          stdin_data: stdin_data,
+          on_stdout_chunk: on_stdout_chunk,
+          on_stderr_chunk: on_stderr_chunk,
+          on_heartbeat: on_heartbeat,
+          heartbeat_interval: heartbeat_interval,
+          observer: observer
+        )
+      rescue TimeoutError => e
+        raise e if e.is_a?(IdleTimeoutError)
+
+        raise TimeoutError, "Command timed out after #{timeout} seconds: #{command_name}"
+      end
+
+      begin
+        cleanup_preparation(
+          applied_preparation,
+          command_name: command_name,
+          timeout: timeout,
+          deadline: cleanup_deadline(deadline, timeout:)
+        )
+      rescue TimeoutError
+        schedule_cleanup_preparation(
+          applied_preparation,
+          held_preparation_locks,
+          command_name: command_name
+        )
+        background_cleanup_scheduled = true
+        held_preparation_locks = []
+      end
+      duration = current_time - start_time
 
       Result.new(
         stdout: stdout,
@@ -89,6 +141,46 @@ module AgentHarness
         exit_code: status.exitstatus,
         duration: duration
       )
+    ensure
+      pending_exception = $!
+      unless background_cleanup_scheduled || applied_preparation.nil? || applied_preparation.empty?
+        begin
+          cleanup_preparation(
+            applied_preparation,
+            command_name: command_name,
+            timeout: timeout,
+            deadline: cleanup_deadline(deadline, timeout:)
+          )
+        rescue TimeoutError => e
+          raise e if pending_exception.nil?
+
+          if pending_exception.is_a?(TimeoutError)
+            schedule_cleanup_preparation(
+              applied_preparation,
+              held_preparation_locks,
+              command_name: command_name
+            )
+            background_cleanup_scheduled = true
+            held_preparation_locks = []
+          else
+            # Preserve the original non-timeout exception; surface that
+            # cleanup also timed out so callers know bootstrap state may
+            # have leaked.
+            raise pending_exception.class,
+              "#{pending_exception.message} (cleanup also failed: #{e.message})"
+          end
+        rescue => e
+          raise e if pending_exception.nil?
+
+          # Surface cleanup failures even when unwinding from another exception,
+          # so callers know request-scoped bootstrap state may have leaked.
+          raise pending_exception.class,
+            "#{pending_exception.message} (cleanup also failed: #{e.message})"
+        end
+      end
+      unless background_cleanup_scheduled || held_preparation_locks.nil? || held_preparation_locks.empty?
+        release_preparation_locks(held_preparation_locks)
+      end
     end
 
     # Check if a binary exists in PATH
@@ -126,6 +218,351 @@ module AgentHarness
 
     private
 
+    def acquire_preparation_locks(preparation, env:, timeout:, deadline:, command_name:)
+      return [] if preparation.nil? || preparation.empty?
+
+      preparation.file_writes.each { |write| validate_preparation_path_security!(write.path) }
+
+      acquired_locks = []
+
+      preparation_lock_keys(preparation, env).each do |key|
+        acquired_locks << acquire_preparation_lock(key, timeout:, deadline:, command_name:)
+      end
+      acquired_locks
+    rescue
+      release_preparation_locks(acquired_locks) if acquired_locks && !acquired_locks.empty?
+      raise
+    end
+
+    def acquire_preparation_lock(key, timeout:, deadline:, command_name:)
+      lock_path = preparation_lock_path(key)
+      FileUtils.mkdir_p(File.dirname(lock_path), mode: 0o700)
+      lock_file = File.open(lock_path, File::RDWR | File::CREAT, 0o600)
+
+      begin
+        if timeout.nil?
+          lock_file.flock(File::LOCK_EX)
+        else
+          until lock_file.flock(File::LOCK_EX | File::LOCK_NB)
+            sleep([PREPARATION_LOCK_POLL_INTERVAL, remaining_timeout(deadline, timeout:, command_name:)].min)
+          end
+        end
+      rescue
+        lock_file.close unless lock_file.closed?
+        raise
+      end
+
+      {key: key, file: lock_file}
+    end
+
+    def release_preparation_locks(held_preparation_locks)
+      held_preparation_locks.reverse_each do |lock|
+        file = lock[:file]
+        next if file.nil? || file.closed?
+
+        file.flock(File::LOCK_UN)
+        file.close
+      end
+    end
+
+    def preparation_lock_keys(preparation, env)
+      preparation.file_writes.map do |write|
+        "#{preparation_lock_scope}:#{expand_preparation_path(write.path, env)}"
+      end.uniq.sort
+    end
+
+    def preparation_lock_scope
+      "host"
+    end
+
+    def preparation_lock_path(key)
+      File.join(PREPARATION_LOCK_ROOT, "#{Digest::SHA256.hexdigest(key)}.lock")
+    end
+
+    def apply_preparation(preparation, env:, timeout:, deadline:, command_name:, applied_preparation:)
+      return if preparation.nil? || preparation.empty?
+
+      preparation.file_writes.each do |write|
+        validate_preparation_path_security!(write.path)
+        validate_preparation_path_env!(write.path, env)
+        validate_home_relative_preparation_path!(write.path, env)
+        resolved_path = expand_preparation_path(write.path, env)
+        created_directories = missing_parent_directories(resolved_path)
+        snapshot = within_timeout(deadline, timeout:, command_name:) do
+          snapshot_file_state(resolved_path)
+        end
+        applied_preparation << {
+          path: resolved_path,
+          snapshot: snapshot,
+          created_directories: created_directories
+        }
+
+        within_timeout(deadline, timeout:, command_name:) do
+          FileUtils.mkdir_p(File.dirname(resolved_path))
+          delete_preparation_path(resolved_path) if snapshot[:type] == :symlink
+          File.binwrite(resolved_path, write.content)
+          File.chmod(write.mode, resolved_path) if write.mode
+        end
+      rescue => e
+        begin
+          cleanup_preparation(
+            applied_preparation,
+            command_name: command_name,
+            timeout: timeout,
+            deadline: cleanup_deadline(deadline, timeout:)
+          )
+        rescue => cleanup_error
+          log_debug("Failed to clean up runtime preparation", error: cleanup_error.message)
+        end
+        raise e
+      end
+    end
+
+    def cleanup_preparation(applied_preparation, command_name:, timeout: nil, deadline: nil)
+      applied_preparation.reverse_each do |entry|
+        within_timeout(deadline, timeout:, command_name:) do
+          unless entry[:restored]
+            restore_file_state(entry[:path], entry[:snapshot])
+            entry[:restored] = true
+          end
+          cleanup_created_directories(entry[:created_directories])
+        end
+      end
+      applied_preparation.clear
+    end
+
+    def missing_parent_directories(path)
+      directories = []
+      current = File.dirname(path)
+
+      until current == File.dirname(current) || File.exist?(current) || File.symlink?(current)
+        directories << current
+        current = File.dirname(current)
+      end
+
+      directories
+    end
+
+    def cleanup_created_directories(directories)
+      directories.each do |directory|
+        next unless File.directory?(directory) && !File.symlink?(directory)
+
+        Dir.rmdir(directory)
+      rescue Errno::ENOENT
+        next
+      rescue Errno::ENOTEMPTY, Errno::EEXIST
+        break
+      end
+    end
+
+    def schedule_cleanup_preparation(applied_preparation, held_preparation_locks, command_name:)
+      cleanup_deadline = timeout_deadline(PREPARATION_CLEANUP_GRACE_PERIOD)
+      Thread.new(applied_preparation, held_preparation_locks, cleanup_deadline, command_name) do |entries, locks, deadline_at, cleanup_command_name|
+        Thread.current.report_on_exception = false if Thread.current.respond_to?(:report_on_exception=)
+
+        begin
+          cleanup_preparation(
+            entries,
+            command_name: cleanup_command_name,
+            timeout: PREPARATION_CLEANUP_GRACE_PERIOD,
+            deadline: deadline_at
+          )
+        rescue => e
+          log_debug("Failed to clean up runtime preparation after timeout", error: e.message)
+        ensure
+          release_preparation_locks(locks) unless locks.nil? || locks.empty?
+        end
+      end
+    end
+
+    def expand_preparation_path(path, env)
+      expanded_path = path.gsub(/\$(\w+)|\$\{([^}]+)\}/) do
+        key = Regexp.last_match(1) || Regexp.last_match(2)
+        resolve_preparation_path_env_var(key, env)
+      end
+
+      if expanded_path == "~"
+        return File.expand_path(resolve_preparation_home(env))
+      end
+
+      if expanded_path.start_with?("~/")
+        return File.expand_path(File.join(resolve_preparation_home(env), expanded_path.delete_prefix("~/")))
+      end
+
+      File.expand_path(expanded_path)
+    end
+
+    def validate_preparation_path_env!(path, env)
+      path.scan(/\$(\w+)|\$\{([^}]+)\}/) do |match|
+        key = match.compact.first
+        resolve_preparation_path_env_var(key, env)
+      end
+    end
+
+    def validate_preparation_path_security!(path)
+      if path.include?("\x00")
+        raise ArgumentError, "preparation path must not contain null bytes"
+      end
+
+      if path.include?("\n")
+        raise ArgumentError, "preparation path must not contain newline characters"
+      end
+
+      if path.include?("\r")
+        raise ArgumentError, "preparation path must not contain carriage return characters"
+      end
+
+      if path.include?("`")
+        raise ArgumentError, "preparation path must not contain backtick characters"
+      end
+
+      if path.include?(";")
+        raise ArgumentError, "preparation path must not contain semicolon characters"
+      end
+
+      if path.include?("|")
+        raise ArgumentError, "preparation path must not contain pipe characters"
+      end
+
+      if path.include?("$(")
+        raise ArgumentError, "preparation path must not contain command substitution"
+      end
+
+      if path.include?("..")
+        raise ArgumentError, "preparation path must not contain path traversal"
+      end
+    end
+
+    def validate_home_relative_preparation_path!(path, env)
+      return unless path == "~" || path.start_with?("~/")
+      return unless env.key?("HOME")
+
+      home = env["HOME"]
+      raise ArgumentError, "HOME cannot be nil or empty for home-relative preparation paths" if home.nil? || home.empty?
+      raise ArgumentError, "HOME must not contain path traversal" if home.include?("..")
+    end
+
+    def resolve_preparation_path_env_var(key, env)
+      unless env.key?(key)
+        raise ArgumentError, "#{key} cannot be nil or empty for env-backed preparation paths"
+      end
+
+      value = env[key]
+      raise ArgumentError, "#{key} cannot be nil or empty for env-backed preparation paths" if value.nil? || value.empty?
+      raise ArgumentError, "#{key} must not contain path traversal" if value.include?("..")
+
+      value
+    end
+
+    def resolve_preparation_home(env)
+      if env.key?("HOME")
+        home = env["HOME"]
+        raise ArgumentError, "HOME cannot be nil or empty for home-relative preparation paths" if home.nil? || home.empty?
+        raise ArgumentError, "HOME must not contain path traversal" if home.include?("..")
+
+        return home
+      end
+
+      ENV["HOME"] || Dir.home
+    end
+
+    def snapshot_file_state(path)
+      stat = File.lstat(path)
+
+      if stat.symlink?
+        {
+          existed: true,
+          type: :symlink,
+          target: File.readlink(path)
+        }
+      elsif stat.file?
+        backup_file = Tempfile.new("agent-harness-preparation")
+        backup_path = backup_file.path
+        backup_file.close!
+        FileUtils.cp(path, backup_path, preserve: true)
+
+        {
+          existed: true,
+          type: :file,
+          backup_path: backup_path
+        }
+      else
+        raise ArgumentError, "preparation target must be a regular file or symlink: #{path}"
+      end
+    rescue Errno::ENOENT
+      {existed: false}
+    rescue
+      FileUtils.rm_f(backup_path) if defined?(backup_path) && backup_path
+      raise
+    end
+
+    def restore_file_state(path, snapshot)
+      if snapshot[:type] == :symlink
+        delete_preparation_path(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.symlink(snapshot[:target], path)
+      elsif snapshot[:existed]
+        backup_path = snapshot.fetch(:backup_path)
+        raise ArgumentError, "missing runtime preparation backup: #{backup_path}" unless File.exist?(backup_path)
+
+        delete_preparation_path(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        FileUtils.cp(backup_path, path, preserve: true)
+      else
+        delete_preparation_path(path)
+      end
+
+      # Only remove the backup after restore succeeds. If restore fails (e.g. the
+      # prepared path was replaced by a directory), the backup must survive so
+      # later cleanup retries can still restore the original user file.
+      FileUtils.rm_f(snapshot[:backup_path]) if snapshot[:type] == :file && snapshot[:backup_path]
+    end
+
+    def delete_preparation_path(path)
+      return unless File.exist?(path) || File.symlink?(path)
+
+      raise ArgumentError, "preparation target changed into a directory during execution: #{path}" if File.directory?(path) && !File.symlink?(path)
+
+      File.delete(path)
+    end
+
+    def timeout_deadline(timeout)
+      return nil if timeout.nil?
+
+      current_time + timeout
+    end
+
+    def cleanup_deadline(deadline, timeout:)
+      return nil if timeout.nil?
+
+      # Keep synchronous cleanup within the caller's original timeout budget.
+      # If cleanup overruns after a successful command or after a timeout/error,
+      # execute schedules bounded background cleanup instead of extending execute.
+      deadline
+    end
+
+    def remaining_timeout(deadline, timeout:, command_name:)
+      return nil if deadline.nil?
+
+      remaining = deadline - current_time
+      raise TimeoutError, "Command timed out after #{timeout} seconds: #{command_name}" if remaining <= 0
+
+      remaining
+    end
+
+    def within_timeout(deadline, timeout:, command_name:)
+      remaining = remaining_timeout(deadline, timeout:, command_name:)
+      return yield if remaining.nil?
+
+      Timeout.timeout(remaining) { yield }
+    rescue Timeout::Error
+      raise TimeoutError, "Command timed out after #{timeout} seconds: #{command_name}"
+    end
+
+    def current_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     def execute_streaming(cmd_array, timeout:, idle_timeout:, env:, stdin_data:,
       on_stdout_chunk:, on_stderr_chunk:, on_heartbeat:, heartbeat_interval:, observer:)
       stdout = +""