process_executer 4.0.4 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 326f0746501479260d59d78579f9ff9e049a516a7b76e177e7ade04b90f0eece
-  data.tar.gz: 7352423248b6d8d7b1785e450ff0aae1c836fa1dfcc2a4e6b791d29d8a3d386c
+  metadata.gz: a6dbea0ce77694bd73783f7191fc9b32957fefda87f9db6108d97ebf26bb1a9f
+  data.tar.gz: e710378f301c56c649063d6bfef0525f0c0c8dcf6adf6329e12184ec24d02894
 SHA512:
-  metadata.gz: 2147f37dc71f48a5c8a525103bc517d4be9bf4fde29f1a7d4d12952cf42976c96567256c5eea8ffe101d409829f63011093828551bc30fc779627978df7219c7
-  data.tar.gz: 175fe9b38d29b3b6c7441293ca837344231019f22d0cb815013cd766f606487873ebb062134e00a493f3a5c41a7f1f5b6c2d3e152ea51ab800f12536aa695d50
+  metadata.gz: 756a9aacc5d173fa2cedd68f178c9e321e141d3ef75f61ddcfe7e3ebe67f236a0603192f24c49aaedbc0dcf209d61dd16b593477f67d974fa1f2e875ec17dd7d
+  data.tar.gz: a9ce354984f37839c54abfb453eef726d6467467dc529aaa2108643c2e153005022b097b9a1ecfea368391ff9ebbf8ba20b32b9cd73db11c5076394824d81528

data/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.0.4"
+  ".": "4.1.1"
 }

data/.rubocop.yml

@@ -5,3 +5,16 @@ AllCops:
   # Pin this project to Ruby 3.1 in case the shared config above is upgraded to 3.2
   # or later.
   TargetRubyVersion: 3.1
+
+# The default `native` style expects CRLF on Windows, but this project's files
+# are LF everywhere. Pin the style so RuboCop gives the same result on Windows
+# as it does on Linux and macOS.
+Layout/EndOfLine:
+  EnforcedStyle: lf
+
+# MonitoredPipe grew past the default limit when the close deadline handling
+# was added for issue #164. Its pipe lifecycle logic (open, monitor, drain,
+# close) is cohesive and would not be clearer split across classes.
+Metrics/ClassLength:
+  Exclude:
+    - "lib/process_executer/monitored_pipe.rb"

data/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["editorconfig.editorconfig"]
+}

data/CHANGELOG.md

@@ -5,6 +5,62 @@ All notable changes to the process_executer gem will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.1](https://github.com/main-branch/process_executer/compare/v4.1.0...v4.1.1) (2026-08-31)
+
+
+### Other Changes
+
+* Characterize validation ordering when unknown and invalid options are given together ([#192](https://github.com/main-branch/process_executer/issues/192)) ([15d6e06](https://github.com/main-branch/process_executer/commit/15d6e063170484f309efd30867238b867484288b))
+* Collapse encoding validators and clarify capture-redirection assembly ([#194](https://github.com/main-branch/process_executer/issues/194)) ([bab8610](https://github.com/main-branch/process_executer/commit/bab86101ac4cdbd3747e72d0d7f841623a6e9b20))
+* Contribute subclass redirections via an internal_redirections hook ([#190](https://github.com/main-branch/process_executer/issues/190)) ([8ecbda5](https://github.com/main-branch/process_executer/commit/8ecbda54874de933ab07a64d91e0a07e17f7ece0))
+* Derive the process-group isolation decision from a single source ([#191](https://github.com/main-branch/process_executer/issues/191)) ([5d8ac7d](https://github.com/main-branch/process_executer/commit/5d8ac7dc38a369a7fe6d6cf3d05bd1eec799f3dc))
+* Describe every source of MonitoredPipe#exception ([#193](https://github.com/main-branch/process_executer/issues/193)) ([333b7bd](https://github.com/main-branch/process_executer/commit/333b7bd4c552c246d7d7505b5aa3e1a123ac5f9b))
+* Extract shared validate! from Options::Base#initialize and #merge! ([#192](https://github.com/main-branch/process_executer/issues/192)) ([422956a](https://github.com/main-branch/process_executer/commit/422956acaab46e29ecc1373d017d719ea6eb497f))
+* Remove the release-as 4.1.0 override from the release-please config ([65de5b8](https://github.com/main-branch/process_executer/commit/65de5b8b4a7f926c4e71b094ead5ff9abc6ff102))
+* Track opened pipes as per-call instance state instead of an out-parameter ([#190](https://github.com/main-branch/process_executer/issues/190)) ([f279f1e](https://github.com/main-branch/process_executer/commit/f279f1e0672b91b966ee73cbadf00749522e488d))
+
+## [4.1.0](https://github.com/main-branch/process_executer/compare/v4.0.4...v4.1.0) (2026-08-30)
+
+
+### Bug Fixes
+
+* Make timeout_after bound execution even when descendants hold stdout/stderr open ([a1298d3](https://github.com/main-branch/process_executer/commit/a1298d3f98fd8e57f58f50a0566dd3be78079189))
+* **monitored_pipe:** Close acquired resources when #initialize fails partway ([8f10a86](https://github.com/main-branch/process_executer/commit/8f10a86b42c4d72f0f34004071cfeb91116d6bd4)), closes [#178](https://github.com/main-branch/process_executer/issues/178)
+* **monitored_pipe:** Do not hold the mutex while writing to the pipe ([91d7fe8](https://github.com/main-branch/process_executer/commit/91d7fe88b9950d24f8c28ccbea400be0063ec99a)), closes [#165](https://github.com/main-branch/process_executer/issues/165)
+* **monitored_pipe:** Handle a destination raising a non-StandardError ([a7de23b](https://github.com/main-branch/process_executer/commit/a7de23b5699ef4d32518e988ac76dd6a957277e3)), closes [#170](https://github.com/main-branch/process_executer/issues/170)
+* Replace the monitor thread's 1ms poll with an event-driven wakeup pipe ([44068a3](https://github.com/main-branch/process_executer/commit/44068a35f4f87de9b7b46ce1deffda636f7c1138))
+* Return a timed out result when the timeout races Process.wait2 reaping the child ([84a6a11](https://github.com/main-branch/process_executer/commit/84a6a11df7d736f26d98700e90a76f5d65e2d35c)), closes [#171](https://github.com/main-branch/process_executer/issues/171)
+* **run_with_capture:** Capture combined [:out, :err] redirection into stdout ([17199b8](https://github.com/main-branch/process_executer/commit/17199b8ea332278680c46accce072763f0d67a4a)), closes [#167](https://github.com/main-branch/process_executer/issues/167)
+* **run:** Close created pipes and keep the original error when pipe creation fails ([909eaa1](https://github.com/main-branch/process_executer/commit/909eaa177fa53ee4cd4e773595a8658ea94ca6a4)), closes [#166](https://github.com/main-branch/process_executer/issues/166)
+* **run:** Stop mutating caller options and closing caller-owned pipes ([96d922b](https://github.com/main-branch/process_executer/commit/96d922b4bff5586189b30d9a1f83b0d47159710f)), closes [#169](https://github.com/main-branch/process_executer/issues/169)
+* Validate options merged via Options::Base#merge! ([#173](https://github.com/main-branch/process_executer/issues/173)) ([da0a956](https://github.com/main-branch/process_executer/commit/da0a956bcb085378b1315dafb87351174500c966))
+
+
+### Other Changes
+
+* Add failing tests for merge! bypassing option validation ([#173](https://github.com/main-branch/process_executer/issues/173)) ([325f16e](https://github.com/main-branch/process_executer/commit/325f16e589821571f3250e86a82f51f0e6b70f9a))
+* Add failing tests for the monitor thread 1ms polling loop ([#172](https://github.com/main-branch/process_executer/issues/172)) ([e202909](https://github.com/main-branch/process_executer/commit/e202909f99074a8ceb331f13290c224c35904e7a))
+* Add failing tests for the timeout vs Process.wait2 reap race ([#171](https://github.com/main-branch/process_executer/issues/171)) ([647739a](https://github.com/main-branch/process_executer/commit/647739ad7233059aafb54dad70eef14998892c5d))
+* Add failing tests for timeout_after not bounding execution ([#164](https://github.com/main-branch/process_executer/issues/164)) ([8e5115c](https://github.com/main-branch/process_executer/commit/8e5115c9236347e77ba6e6d0631f5f1bfe826b26))
+* **coverage:** Only enforce code coverage on MRI builds not on Windows ([160815e](https://github.com/main-branch/process_executer/commit/160815ecb091d1f155406f9a1b37f73e13690627))
+* Enforce LF line endings on all platforms ([e94bfea](https://github.com/main-branch/process_executer/commit/e94bfeaf4bd93506090277b4020859cd23dfc625))
+* Explain stdin redirection via the in: option ([f7bded7](https://github.com/main-branch/process_executer/commit/f7bded743a204a99c7f6e272b0330d4ba1e4a037)), closes [#159](https://github.com/main-branch/process_executer/issues/159)
+* **monitored_pipe:** Accept the documented IOError and confine failures ([002274d](https://github.com/main-branch/process_executer/commit/002274d421afc84c7c441c6f56dbbc32506e1de2)), closes [#182](https://github.com/main-branch/process_executer/issues/182)
+* **monitored_pipe:** Add a failing test for the #write deadlock ([9826558](https://github.com/main-branch/process_executer/commit/9826558035b03fe7becdc729053519141ba8d00d))
+* **monitored_pipe:** Add failing tests for a destination raising a non-StandardError ([0177329](https://github.com/main-branch/process_executer/commit/0177329fb47f3c185d9ea768f9f80028c54fb7ab))
+* **monitored_pipe:** Add failing tests for resource leaks when #initialize fails ([b2e3151](https://github.com/main-branch/process_executer/commit/b2e31519ea7a38f774b90f6e9e1f17fa0b31baa3)), closes [#178](https://github.com/main-branch/process_executer/issues/178)
+* **monitored_pipe:** Make the writer-exception race deterministic ([c72f1e4](https://github.com/main-branch/process_executer/commit/c72f1e400ef3d78e4b092ecde0d0704cf79ebc36)), closes [#182](https://github.com/main-branch/process_executer/issues/182)
+* **monitored_pipe:** Stub the monitor loop on the class, not the live instance ([799177f](https://github.com/main-branch/process_executer/commit/799177f6046d661013ce6b68b19c6b220294d00f))
+* **process-spawn:** Check exit status and blocking, and add a subspawn backend ([99021d2](https://github.com/main-branch/process_executer/commit/99021d2144a21210f793b7ae94d36875eef504e6))
+* **process-spawn:** Run the spawn tests against the subspawn backend ([573086f](https://github.com/main-branch/process_executer/commit/573086f194e790f25d916de32bb5e94437a5ae86))
+* **rake:** Skip RuboCop in the default task on TruffleRuby ([3d2a118](https://github.com/main-branch/process_executer/commit/3d2a1186d65e76f170f5428d611822d95d8fdc2d))
+* Release the hardening changes as v4.1.0 instead of v4.0.5 ([70b6327](https://github.com/main-branch/process_executer/commit/70b63278f334bd8b714c2fc28ded1520921add09))
+* **run_with_capture:** Add failing tests for combined [:out, :err] redirection ([61e97cb](https://github.com/main-branch/process_executer/commit/61e97cb09c816cbe30d81dc33f268accf76ab396))
+* **run:** Add failing tests for options mutation and caller-owned pipe closing ([cf32615](https://github.com/main-branch/process_executer/commit/cf326156381fe81562597906d43134a08ebbef17))
+* **run:** Add failing tests for pipe creation failure in Run#call ([21521d9](https://github.com/main-branch/process_executer/commit/21521d9a9b5141d9bb6d22fb5fd3e7de0e497ca2))
+* **run:** Update the JRuby expectation for an invalid chdir path ([2712f0b](https://github.com/main-branch/process_executer/commit/2712f0bdf060fa1831edb428183283dec5f2727a))
+* Use RbConfig.ruby to locate the Ruby interpreter ([82e65e2](https://github.com/main-branch/process_executer/commit/82e65e202a4f884a3283b4af00fcd2b5eda3a394))
+
 ## [4.0.4](https://github.com/main-branch/process_executer/compare/v4.0.3...v4.0.4) (2026-04-24)
 
 

data/README.md

@@ -26,6 +26,7 @@ then click the "Documentation" link.
 - [Usage](#usage)
   - [Key methods](#key-methods)
   - [ProcessExecuter::MonitoredPipe](#processexecutermonitoredpipe)
+  - [Redirecting stdin](#redirecting-stdin)
   - [Encoding](#encoding)
     - [Encoding summary](#encoding-summary)
     - [Encoding details](#encoding-details)
@@ -119,6 +120,25 @@ supports these additional types of destinations:
   be any value that `MonitoredPipe` itself supports (including another tee or
   MonitoredPipe).
 
+### Redirecting stdin
+
+The `in:` option is passed directly to `Process.spawn` and is not wrapped in a
+`MonitoredPipe`. It accepts any stdin redirection value that `Process.spawn`
+supports, such as a filename (`in: 'input.txt'`) or an IO object with a file
+descriptor. Unlike `out:` and `err:`, redirecting stdin from a `StringIO` is not
+supported and will raise `ProcessExecuter::SpawnError`. To feed in-memory data
+to a command's stdin, write it to a `Tempfile` and pass that:
+
+```ruby
+require 'tempfile'
+
+Tempfile.create do |file|
+  file.write("HEAD\n")
+  file.rewind
+  result = ProcessExecuter.run('git cat-file --batch-check', in: file)
+end
+```
+
 ### Encoding
 
 #### Encoding summary

data/Rakefile

@@ -6,6 +6,9 @@ desc 'Run the same tasks that the CI build will run'
 
 if RUBY_PLATFORM == 'java'
   task default: %w[spec rubocop bundle:audit build]
+elsif RUBY_ENGINE == 'truffleruby'
+  # RuboCop raises internal errors when run on TruffleRuby, so skip it there
+  task default: %w[spec yard bundle:audit build]
 else
   task default: %w[spec rubocop yard bundle:audit build]
 end

data/lib/process_executer/commands/run.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'English'
+
 require_relative '../errors'
 require_relative 'spawn_with_timeout'
 
@@ -19,6 +21,13 @@ module ProcessExecuter
     # destination. This means that you can redirect to a StringIO which is not possible
     # with `Process.spawn`.
     #
+    # The wrapper pipes are kept in internal per-call state that is combined
+    # with the user's options only when `Process.spawn` is called. Subclasses
+    # contribute additional redirections by overriding `#internal_redirections`.
+    # The options object the caller gave is never modified, so it can be reused
+    # for another run and `result.options` returns the destinations as the user
+    # configured them.
+    #
     # @api private
     #
     class Run < SpawnWithTimeout
@@ -44,37 +53,157 @@ module ProcessExecuter
       # @raise [ProcessExecuter::TimeoutError] If the command timed out
       #
       # @raise [ProcessExecuter::ProcessIOError] If there was an exception while
-      #   collecting subprocess output
+      #   collecting subprocess output, or the output was truncated because it
+      #   could not be fully collected before the close timeout
       #
       # @return [ProcessExecuter::Result] The result of the completed subprocess
       #
       def call
-        opened_pipes = wrap_stdout_stderr
+        @opened_pipes = {}
+        @redirection_overrides = internal_redirections
+        wrap_stdout_stderr
         super.tap do
           log_result
           raise_errors if options.raise_errors
         end
       ensure
-        opened_pipes.each_value(&:close)
-        opened_pipes.each { |option_key, pipe| raise_pipe_error(option_key, pipe) }
+        close_pipes_and_check_errors($ERROR_INFO)
       end
 
       private
 
+      # Redirection options to apply on top of the user's options at spawn time
+      #
+      # Reset at the start of each {#call}: seeded with
+      # {#internal_redirections} and then updated by {#wrap_stdout_stderr},
+      # which replaces each eligible destination with its {MonitoredPipe}
+      # wrapper. Keeping these here instead of writing them into {#options}
+      # leaves the caller's options object unmodified.
+      #
+      # Unlike {#opened_pipes}, this hash may hold values that are not
+      # {MonitoredPipe}s (for example, the `[:child, 1]` redirection a subclass
+      # adds for merged output).
+      #
+      # @return [Hash<Object, Object>]
+      #
+      attr_reader :redirection_overrides
+
+      # Redirections this class adds on top of the user's options
+      #
+      # Called once at the start of each {#call} to seed
+      # {#redirection_overrides}, before {#wrap_stdout_stderr} runs. Returns an
+      # empty hash; subclasses override this method to contribute their own
+      # redirections (such as {RunWithCapture}'s capture redirections) instead
+      # of mutating this object's state.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def internal_redirections = {}
+
+      # The wrapper pipes created by {#wrap_stdout_stderr}
+      #
+      # Keyed by the redirection option key. Reset at the start of each {#call}. By construction this hash contains
+      # exactly the pipes this object created during the current call -- never
+      # a destination supplied by the caller -- so `#call`'s ensure block can
+      # close everything in it without ever closing a caller-owned pipe (a
+      # caller's own {MonitoredPipe} destination is wrapped like any other
+      # destination, and only the wrapper is recorded here).
+      #
+      # @return [Hash<Object, ProcessExecuter::MonitoredPipe>]
+      #
+      attr_reader :opened_pipes
+
+      # The options to pass to Process.spawn
+      #
+      # The user's spawn options with the redirection destinations replaced by
+      # their internal {MonitoredPipe} wrappers.
+      #
+      # @return [Hash]
+      #
+      def spawn_options = super.merge(redirection_overrides)
+
       # Wrap the stdout and stderr redirection options with a MonitoredPipe
-      # @return [Hash<Object, ProcessExecuter::MonitoredPipe>] The opened pipes (the Object is the option key)
+      #
+      # Each wrapper pipe is recorded in two collections with different roles:
+      # {#opened_pipes}, the pipes this object owns and must close, and
+      # {#redirection_overrides}, the destinations to hand `Process.spawn`.
+      # Neither is written into {#options}, so the caller's options object is
+      # not modified.
+      #
+      # Each pipe is recorded as soon as it is created so that, if creating a
+      # later pipe raises, `#call`'s ensure block can close the pipes created
+      # so far.
+      #
+      # @return [void]
+      #
       def wrap_stdout_stderr
-        options.each_with_object({}) do |key_value, opened_pipes|
-          key, value = key_value
-
+        effective_redirections.each do |key, value|
           next unless should_wrap?(key, value)
 
           wrapped_destination = ProcessExecuter::MonitoredPipe.new(value)
           opened_pipes[key] = wrapped_destination
-          options.merge!({ key => wrapped_destination })
+          redirection_overrides[key] = wrapped_destination
         end
       end
 
+      # The options as given by the user with {#redirection_overrides} applied
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def effective_redirections = options.to_h.merge(redirection_overrides)
+
+      # Close the opened pipes and raise any pipe error unless already unwinding
+      #
+      # When `in_flight_error` is set, `#call` is unwinding from an exception
+      # and that exception (not a pipe destination error or a pipe cleanup
+      # error) must be the one the caller sees, so nothing is raised here.
+      #
+      # @param in_flight_error [Exception, nil] the exception `#call` is unwinding from, if any
+      #
+      # @raise [ProcessExecuter::ProcessIOError] if a pipe recorded a destination
+      #   exception or gave up draining before reaching EOF (truncated output)
+      #
+      # @raise [StandardError] the first error raised while closing the pipes
+      #
+      # @return [void]
+      #
+      def close_pipes_and_check_errors(in_flight_error)
+        close_error = close_pipes
+        return if in_flight_error
+
+        opened_pipes.each do |option_key, pipe|
+          raise_pipe_error(option_key, pipe)
+          raise_truncation_error(option_key, pipe)
+        end
+        raise close_error if close_error
+      end
+
+      # Close the opened pipes, continuing if closing one of them raises
+      #
+      # Closing continues past a failure so that one pipe's error does not leak
+      # the monitoring threads and file descriptors of the pipes after it.
+      #
+      # All pipes share a single close deadline so that this method -- called
+      # from `#call`'s ensure block -- returns in bounded time even when a
+      # process outside this object's control (such as an orphaned descendant
+      # of a timed out command) still holds a pipe's write fd open. A pipe
+      # whose drain is cut short by the deadline records it via
+      # {MonitoredPipe#truncated?}.
+      #
+      # @return [StandardError, nil] the first error raised while closing, or nil if none was raised
+      #
+      def close_pipes
+        first_close_error = nil
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + MonitoredPipe::DEFAULT_CLOSE_TIMEOUT
+        opened_pipes.each_value do |pipe|
+          remaining_time = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          pipe.close(timeout: [remaining_time, 0].max)
+        rescue StandardError => e
+          first_close_error ||= e
+        end
+        first_close_error
+      end
+
       # Should the redirection option be wrapped by a MonitoredPipe
       # @param key [Object] The option key
       # @param value [Object] The option value
@@ -119,6 +248,31 @@ module ProcessExecuter
         error = ProcessExecuter::ProcessIOError.new("Pipe Exception for #{command}: #{option_key.inspect}")
         raise(error, cause: pipe.exception)
       end
+
+      # Raises a ProcessIOError if the given pipe's output was truncated
+      #
+      # Truncation means the pipe gave up draining before reaching EOF
+      # ({MonitoredPipe#truncated?}): output the subprocess (or a descendant
+      # holding the inherited write fd) produced was discarded instead of
+      # being written to the destination. Raising makes that data loss loud
+      # rather than letting the command appear to succeed with silently
+      # incomplete output.
+      #
+      # @param option_key [Object] The redirection option key
+      #
+      # @param pipe [ProcessExecuter::MonitoredPipe] The pipe whose output was truncated
+      #
+      # @raise [ProcessExecuter::ProcessIOError] If the pipe's output was truncated
+      #
+      # @return [void]
+      #
+      def raise_truncation_error(option_key, pipe)
+        return unless pipe.truncated?
+
+        raise ProcessExecuter::ProcessIOError,
+              "Output truncated for #{command}: #{option_key.inspect} " \
+              'could not be fully collected before the close timeout'
+      end
     end
   end
 end

data/lib/process_executer/commands/run_with_capture.rb

@@ -50,8 +50,6 @@ module ProcessExecuter
         @stderr_buffer = StringIO.new
         stderr_buffer.set_encoding(options.effective_stderr_encoding)
 
-        update_capture_options
-
         begin
           super
         ensure
@@ -89,54 +87,110 @@ module ProcessExecuter
         )
       end
 
-      # Updates {options} to include the stdout and stderr capture options
+      # The stdout and stderr capture redirections
       #
-      # @return [Void]
+      # Called by {Run#call} to seed the redirection overrides, so the capture
+      # redirections are layered on top of the user's options at spawn time
+      # without writing into {#options} or mutating the parent's state.
+      #
+      # When the user gives a combined redirection whose key covers both stdout
+      # and stderr (e.g. `[:out, :err] => destination`), a single capture
+      # redirection is built for that key so both streams are interleaved into
+      # {#stdout_buffer} and {#stderr_buffer} is left empty, mirroring the
+      # `merge_output: true` contract.
+      #
+      # @return [Hash<Object, Object>]
       #
-      def update_capture_options
-        out = stdout_buffer
-        err = options.merge_output ? [:child, 1] : stderr_buffer
+      def internal_redirections
+        if options.combined_stdout_and_stderr_redirection?
+          combined_capture_redirection
+        else
+          stdout_and_stderr_capture_redirections
+        end
+      end
 
-        options.merge!(
-          capture_option(:out, stdout_redirection_source, stdout_redirection_destination, out),
-          capture_option(:err, stderr_redirection_source, stderr_redirection_destination, err)
+      # A single capture redirection for a combined stdout/stderr key
+      #
+      # Both streams are interleaved into {#stdout_buffer}; {#stderr_buffer} is
+      # left empty.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def combined_capture_redirection
+        tee_capture_redirection(
+          options.stdout_redirection_source, options.stdout_redirection_destination, stdout_buffer
         )
       end
 
-      # The source for stdout redirection
-      # @return [Object]
-      def stdout_redirection_source = options.stdout_redirection_source
+      # Separate capture redirections for stdout and stderr
+      #
+      # If `merge_output: true` was given, stderr is redirected into stdout so
+      # both streams are interleaved into {#stdout_buffer}.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def stdout_and_stderr_capture_redirections
+        stdout_capture_redirection.merge(stderr_capture_redirection)
+      end
+
+      # The redirection that captures stdout into {#stdout_buffer}
+      #
+      # Tees the buffer onto the user's stdout redirection if one was given;
+      # otherwise installs the plain default capture redirection.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def stdout_capture_redirection
+        source = options.stdout_redirection_source
+        return default_capture_redirection(:out, stdout_buffer) unless source
 
-      # The source for stderr redirection
-      # @return [Object]
-      def stderr_redirection_source = options.stderr_redirection_source
+        tee_capture_redirection(source, options.stdout_redirection_destination, stdout_buffer)
+      end
 
-      # The destination for stdout redirection
-      # @return [Object]
-      def stdout_redirection_destination = options.stdout_redirection_destination
+      # The redirection that captures stderr
+      #
+      # Stderr is captured into {#stderr_buffer}, or into stdout (and thereby
+      # {#stdout_buffer}) if `merge_output: true` was given. Tees the capture
+      # destination onto the user's stderr redirection if one was given;
+      # otherwise installs the plain default capture redirection.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def stderr_capture_redirection
+        capture_destination = options.merge_output ? [:child, 1] : stderr_buffer
+        source = options.stderr_redirection_source
+        return default_capture_redirection(:err, capture_destination) unless source
 
-      # The destination for stderr redirection
-      # @return [Object]
-      def stderr_redirection_destination = options.stderr_redirection_destination
+        tee_capture_redirection(source, options.stderr_redirection_destination, capture_destination)
+      end
 
-      # Add the capture redirection to existing options (if any)
-      # @param redirection_source [Symbol, Integer] The source of the redirection (e.g., :out, :err)
-      # @param given_source [Symbol, Integer, nil] The source provided by the user (if any)
-      # @param given_destination [Object, nil] The destination provided by the user (if any)
+      # Tee the capture destination onto the redirection the user gave
+      #
+      # If the user's destination is already a tee, the capture destination is
+      # added to it; otherwise the user's destination and the capture
+      # destination are wrapped in a new tee.
+      #
+      # @param source [Symbol, Integer, Array] The redirection source the user gave
+      # @param destination [Object] The redirection destination the user gave
       # @param capture_destination [Object] The additional destination to capture output to
-      # @return [Hash] The option (including the capture_destination) to merge into options
-      def capture_option(redirection_source, given_source, given_destination, capture_destination)
-        if given_source
-          if Destinations::Tee.handles?(given_destination)
-            { given_source => given_destination + [capture_destination] }
-          else
-            { given_source => [:tee, given_destination, capture_destination] }
-          end
+      # @return [Hash] The redirection to merge into options
+      def tee_capture_redirection(source, destination, capture_destination)
+        if Destinations::Tee.handles?(destination)
+          { source => destination + [capture_destination] }
         else
-          { redirection_source => capture_destination }
+          { source => [:tee, destination, capture_destination] }
         end
       end
 
+      # The plain capture redirection used when the user gave no redirection
+      #
+      # @param source [Symbol] The redirection source (:out or :err)
+      # @param capture_destination [Object] The destination to capture output to
+      # @return [Hash] The redirection to merge into options
+      def default_capture_redirection(source, capture_destination)
+        { source => capture_destination }
+      end
+
       # Log the captured command output to the given logger at debug level
       # @return [Void]
       def log_command_output