process_executer 4.0.4 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 326f0746501479260d59d78579f9ff9e049a516a7b76e177e7ade04b90f0eece
-  data.tar.gz: 7352423248b6d8d7b1785e450ff0aae1c836fa1dfcc2a4e6b791d29d8a3d386c
+  metadata.gz: 63acfcf3541790f98d140feac5a9badc901f8b4e475b3c97d125f6b549556bfc
+  data.tar.gz: 7c42a5cfa8b66fea530be0821443a974c1fabc1002fc2b3f2f35e533812c9c6e
 SHA512:
-  metadata.gz: 2147f37dc71f48a5c8a525103bc517d4be9bf4fde29f1a7d4d12952cf42976c96567256c5eea8ffe101d409829f63011093828551bc30fc779627978df7219c7
-  data.tar.gz: 175fe9b38d29b3b6c7441293ca837344231019f22d0cb815013cd766f606487873ebb062134e00a493f3a5c41a7f1f5b6c2d3e152ea51ab800f12536aa695d50
+  metadata.gz: b8d54aa2b9c5e1c153a4c92dbaeec6d96c3b80f31f6517ad2026519d070eff6d6c5b6fdc447cfbff481a6c15599c06ace734068f784e1f1ca8ba78831e84e0d7
+  data.tar.gz: fef70d1e6342139152e498dd72572f591f5f330f8617e7ad0603898638c08db8e2ec09aeb302e486949432d80a7635611654959869314946df13c1bf87ed4dd0

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.0"
 }

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,48 @@ 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.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,9 +21,29 @@ 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 an internal hash that is combined with the
+    # user's options only when `Process.spawn` is called. 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
+      # Create a new Run instance
+      #
+      # @example
+      #   options = ProcessExecuter::Options::RunOptions.new(raise_errors: true)
+      #   result = ProcessExecuter::Commands::Run.new('echo hello', options).call
+      #   result.success? # => true
+      #
+      # @param command [Array<String>] The command to run in the subprocess
+      # @param options [ProcessExecuter::Options::RunOptions] The options to use when running the command
+      #
+      def initialize(command, options)
+        super
+        @redirection_overrides = {}
+      end
+
       # Run a command and return the result
       #
       # Wrap the stdout and stderr redirection destinations in pipes and then execute
@@ -44,35 +66,130 @@ 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 = {}
+        wrap_stdout_stderr(opened_pipes)
         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(opened_pipes, $ERROR_INFO)
       end
 
       private
 
-      # Wrap the stdout and stderr redirection options with a MonitoredPipe
-      # @return [Hash<Object, ProcessExecuter::MonitoredPipe>] The opened pipes (the Object is the option key)
-      def wrap_stdout_stderr
-        options.each_with_object({}) do |key_value, opened_pipes|
-          key, value = key_value
+      # Redirection options to apply on top of the user's options at spawn time
+      #
+      # Holds the {MonitoredPipe} wrappers created by {#wrap_stdout_stderr} (and
+      # the capture redirections added by subclasses) keyed by the redirection
+      # option key. Keeping them here instead of writing them into {#options}
+      # leaves the caller's options object unmodified.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      attr_reader :redirection_overrides
 
+      # 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
+      #
+      # The wrapper pipes are recorded in {#redirection_overrides} instead of
+      # being written into {#options} so the caller's options object is not
+      # modified.
+      #
+      # Each pipe is added to `opened_pipes` as soon as it is created so that,
+      # if creating a later pipe raises, the caller's ensure block can close the
+      # pipes created so far.
+      #
+      # @param opened_pipes [Hash<Object, ProcessExecuter::MonitoredPipe>] an
+      #   accumulator for the opened pipes (the Object is the option key)
+      #
+      # @return [Hash<Object, ProcessExecuter::MonitoredPipe>] the given `opened_pipes`
+      #
+      def wrap_stdout_stderr(opened_pipes)
+        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
+        opened_pipes
+      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 given 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 opened_pipes [Hash<Object, ProcessExecuter::MonitoredPipe>] the pipes to close
+      #
+      # @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(opened_pipes, in_flight_error)
+        close_error = close_pipes(opened_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 given 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?}.
+      #
+      # @param opened_pipes [Hash<Object, ProcessExecuter::MonitoredPipe>] the pipes to close
+      #
+      # @return [StandardError, nil] the first error raised while closing, or nil if none was raised
+      #
+      def close_pipes(opened_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
@@ -119,6 +236,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,7 +50,7 @@ module ProcessExecuter
         @stderr_buffer = StringIO.new
         stderr_buffer.set_encoding(options.effective_stderr_encoding)
 
-        update_capture_options
+        add_capture_redirections
 
         begin
           super
@@ -89,15 +89,52 @@ module ProcessExecuter
         )
       end
 
-      # Updates {options} to include the stdout and stderr capture options
+      # Add the stdout and stderr capture redirections to {#redirection_overrides}
+      #
+      # The capture redirections are not written into {options} so the caller's
+      # options object is not modified.
+      #
+      # 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 [Void]
+      #
+      def add_capture_redirections
+        if options.combined_stdout_and_stderr_redirection?
+          add_combined_capture_redirection
+        else
+          add_stdout_and_stderr_capture_redirections
+        end
+      end
+
+      # Add a single capture redirection for a combined stdout/stderr key
+      #
+      # Both streams are interleaved into {#stdout_buffer}; {#stderr_buffer} is
+      # left empty.
+      #
+      # @return [Void]
+      #
+      def add_combined_capture_redirection
+        redirection_overrides.merge!(
+          capture_option(:out, stdout_redirection_source, stdout_redirection_destination, stdout_buffer)
+        )
+      end
+
+      # Add 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 [Void]
       #
-      def update_capture_options
+      def add_stdout_and_stderr_capture_redirections
         out = stdout_buffer
         err = options.merge_output ? [:child, 1] : stderr_buffer
 
-        options.merge!(
+        redirection_overrides.merge!(
           capture_option(:out, stdout_redirection_source, stdout_redirection_destination, out),
           capture_option(:err, stderr_redirection_source, stderr_redirection_destination, err)
         )

data/lib/process_executer/commands/spawn_with_timeout.rb

@@ -48,7 +48,7 @@ module ProcessExecuter
       #
       def call
         begin
-          @pid = Process.spawn(*command, **options.spawn_options)
+          @pid = Process.spawn(*command, **spawn_options)
         rescue StandardError => e
           raise ProcessExecuter::SpawnError, "Failed to spawn process: #{e.message}"
         end
@@ -80,10 +80,14 @@ module ProcessExecuter
 
       # The status returned by Process.wait2
       #
+      # nil when the timeout was delivered after the wait had already reaped
+      # the subprocess: the status was lost to the raise and {#timed_out?} is
+      # true.
+      #
       # @example
       #   spawn.status #=> #<Process::Status: pid 12345 exit 0>
       #
-      # @return [Process::Status]
+      # @return [Process::Status, nil]
       #
       attr_reader :status
 
@@ -118,6 +122,47 @@ module ProcessExecuter
 
       private
 
+      # The options to pass to Process.spawn
+      #
+      # Subclasses may override this method to combine internal redirections
+      # with the user's options without modifying the options object the
+      # caller gave.
+      #
+      # @return [Hash]
+      #
+      def spawn_options = options.spawn_options.merge(process_group_options)
+
+      # Spawn options that place the subprocess into its own process group
+      #
+      # When `timeout_after` is set to a value that can fire (`nil` and `0`
+      # mean "no timeout"), the subprocess is made the leader of a new process
+      # group so that a timeout can kill the whole group -- including
+      # descendants that inherited the redirections -- instead of just the
+      # direct child. Empty when no timeout can fire or when the caller gave a
+      # `pgroup`/`new_pgroup` option themselves (their setting is honored).
+      #
+      # A new process group is a background group for any terminal the
+      # subprocess inherits, so an interactive subprocess that reads the
+      # terminal is stopped by `SIGTTIN` and then killed when the timeout
+      # fires -- which is the bound `timeout_after` promises. A caller who
+      # needs an interactive subprocess to stay in the foreground process
+      # group can pass their own `pgroup` option.
+      #
+      # @return [Hash]
+      #
+      def process_group_options
+        return {} unless options.timeout_after&.positive?
+        return {} unless options.pgroup == :not_set && options.new_pgroup == :not_set
+
+        windows? ? { new_pgroup: true } : { pgroup: true }
+      end
+
+      # Whether the current platform is Windows
+      #
+      # @return [Boolean]
+      #
+      def windows? = Gem.win_platform?
+
       # Wait for process to terminate
       #
       # If a `:timeout_after` is specified in options, terminate the process after the
@@ -142,21 +187,145 @@ module ProcessExecuter
 
       # Wait for a process to terminate returning the status and timed out flag
       #
-      # @return [Array<Process::Status, Boolean>] an array containing the process status and a boolean
-      #   indicating whether the process timed out
+      # An exception other than the timeout (an `Interrupt` from Ctrl-C, for
+      # example) abandons the wait; {#kill_and_reap_abandoned_subprocess} then
+      # cleans up a subprocess this class isolated into its own process group
+      # before the exception propagates.
+      #
+      # @return [Array(Process::Status, Boolean), Array(nil, Boolean)] an array containing
+      #   the process status (nil when the timeout raced the wait and the status was lost,
+      #   see {#wait_with_timeout}) and a boolean indicating whether the process timed out
       def wait_for_process_raw
-        timed_out = false
-
-        process_status =
-          begin
-            Timeout.timeout(options.timeout_after) { Process.wait2(pid).last }
-          rescue Timeout::Error
-            Process.kill('KILL', pid)
-            timed_out = true
-            Process.wait2(pid).last
-          end
-
-        [process_status, timed_out]
+        wait_with_timeout
+      rescue Exception # rubocop:disable Lint/RescueException
+        kill_and_reap_abandoned_subprocess
+        raise
+      end
+
+      # Wait for the process, killing it when `timeout_after` expires first
+      #
+      # The timeout can be delivered after the timed wait has already reaped
+      # the subprocess but before it returns. In that race the subprocess's
+      # status was lost to the raise, so the status is nil and the timed out
+      # flag is still set.
+      #
+      # @return [Array(Process::Status, Boolean), Array(nil, Boolean)] an array containing
+      #   the process status (nil when the timeout raced the wait and the status was lost)
+      #   and a boolean indicating whether the process timed out
+      def wait_with_timeout
+        process_status = Timeout.timeout(options.timeout_after) { Process.wait2(pid).last }
+        [process_status, false]
+      rescue Timeout::Error
+        kill_subprocess
+        begin
+          [Process.wait2(pid).last, true]
+        rescue Errno::ECHILD
+          # the interrupted wait already reaped the subprocess; its status was
+          # lost to the raise
+          [nil, true]
+        end
+      end
+
+      # Kill and reap the subprocess when its wait was abandoned by an exception
+      #
+      # Only applies to a subprocess this class isolated into its own process
+      # group: such a subprocess no longer receives terminal-generated signals
+      # (Ctrl-C sends `SIGINT` to the caller's foreground group, not to the
+      # new group), so an exception that abandons the wait would otherwise
+      # leave it and its descendants running unsupervised and unreaped. A
+      # subprocess whose process group came from the caller's own options
+      # keeps its pre-existing signal semantics and is left alone.
+      #
+      # Rescues `Exception` (not just `StandardError`) so that a second async
+      # exception delivered during this best-effort cleanup cannot replace
+      # the exception already being re-raised by the caller.
+      #
+      # @return [void]
+      #
+      def kill_and_reap_abandoned_subprocess
+        return unless isolated_in_new_process_group?
+
+        kill_subprocess
+        Process.wait2(pid)
+      rescue Exception # rubocop:disable Lint/RescueException
+        # the subprocess may already be dead and reaped; the wait's exception
+        # is what must propagate
+      end
+
+      # Forcibly terminate the timed out subprocess and (if possible) its descendants
+      #
+      # When the subprocess was spawned as the leader of its own process
+      # group, the whole group is killed so that descendants that would
+      # otherwise survive the timeout (and keep any inherited redirection
+      # file descriptors open) are terminated too, falling back to killing
+      # the direct child if the group kill fails. A group signal reaches only
+      # the processes still in that group: a descendant that started its own
+      # session or joined another process group (a daemon, for example) is
+      # not killed. Otherwise the subprocess is in a process group this
+      # object did not create, so only the direct child is killed, matching
+      # the pre-process-group behavior.
+      #
+      # Killing a process group is only possible on POSIX platforms. On
+      # Windows, `Process.kill` cannot signal a process group (a negative pid
+      # raises an error), so the group kill always falls back to the direct
+      # child and descendants may survive the timeout; the bounded
+      # {MonitoredPipe#close} keeps such descendants from blocking
+      # {ProcessExecuter.run} indefinitely.
+      #
+      # A subprocess that already exited and was reaped before the signal is
+      # sent (the timeout racing the wait) leaves nothing to kill; that is not
+      # an error. In that same microsecond window the freed pid could in
+      # principle be recycled to an unrelated process, a hazard inherent to
+      # signaling by pid: Ruby exposes no race-free process handle (such as
+      # Linux's pidfd) that would eliminate it, and reuse would require the OS
+      # to cycle through its entire pid space within the window.
+      #
+      # @return [void]
+      #
+      def kill_subprocess
+        return if process_group_leader? && kill_process_group
+
+        Process.kill('KILL', pid)
+      rescue Errno::ESRCH
+        # the subprocess already exited and was reaped between the interrupted
+        # wait and the kill; there is nothing left to kill
+      end
+
+      # Whether the spawn options made the subprocess a new process group leader
+      #
+      # True when the process group option -- added by {#process_group_options}
+      # or given by the caller -- asks for a new process group with the
+      # subprocess as its leader (`pgroup: true`, `pgroup: 0`, or
+      # `new_pgroup: true`). False when there is no process group option or
+      # when `pgroup` places the subprocess in an existing process group.
+      #
+      # @return [Boolean]
+      #
+      def process_group_leader?
+        [true, 0].include?(spawn_options[:pgroup]) || spawn_options[:new_pgroup] == true
+      end
+
+      # Whether this class isolated the subprocess into its own process group
+      #
+      # True when the subprocess is a new process group leader and that came
+      # from {#process_group_options} rather than from a `pgroup`/`new_pgroup`
+      # option the caller supplied.
+      #
+      # @return [Boolean]
+      #
+      def isolated_in_new_process_group?
+        process_group_leader? && options.pgroup == :not_set && options.new_pgroup == :not_set
+      end
+
+      # Send SIGKILL to the subprocess's process group
+      #
+      # @return [Boolean] true if the signal was sent, false if doing so raised an error
+      #
+      def kill_process_group
+        Process.kill('KILL', -pid)
+        true
+      rescue StandardError
+        false
       end
     end
   end