class LittleGhost::Sandbox::ProcessRunner
Runs one bounded child process from trusted application code and terminates its entire process group when the Run is cancelled or the command exceeds its timeout.
ProcessRunner is for setup work the application itself decides to run, such as preparing a workspace or unpacking a cache. It applies no isolation beyond the process group; send model-selected commands through a Sandbox instead.
result = LittleGhost::Sandbox::ProcessRunner.capture( ["git", "fetch", "--prune"], timeout: 120, chdir: workspace.root, environment: {"GIT_TERMINAL_PROMPT" => "0"}, inherit_environment: true, context: ) raise "fetch failed: #{result.stderr}" unless result.success?
The command is an Array of arguments. Its first element names the executable, which is found through PATH, and no shell ever interprets it, even when the Array holds a single String.
The child starts with an empty environment unless inherit_environment is true; environment is merged on top either way. Each output stream is captured up to max_output_bytes (or without a limit when nil), and the rest is discarded while the stream is still drained so the child cannot block on a full pipe. Standard input is written while the command runs, so a child that never reads it still stops at its timeout.
#capture reports a timeout in its Result. Cancellation through context raises CancelledError or DeadlineExceededError after the process group is stopped. When the group or its output cannot be stopped, CleanupError is raised instead.
Public Class Methods
# File lib/little_ghost/sandbox/process_runner.rb, line 123 def self.capture(command, timeout:, context: nil, environment: {}, inherit_environment: false, chdir: nil, stdin_data: nil, binmode: false, max_output_bytes: 1_000_000, wait_for_group: true) new( command:, timeout:, context:, environment:, inherit_environment:, chdir:, stdin_data:, binmode:, max_output_bytes:, wait_for_group: ).capture end
Runs command and returns a Result. See the class documentation for environment, output, timeout, and cancellation behavior.
stdin_data is written to the child’s standard input, which is then closed; a child that exits without reading it is not an error. With binmode, standard output is returned as binary data instead of scrubbed UTF-8.
By default the command is finished only when the leader has exited and every other member of its process group has gone, so a backgrounded child cannot outlive a successful result. Pass wait_for_group as false to finish once the leader has exited and its output is closed, leaving any background members running.
A missing executable returns exit code 127 with a message on standard error. A missing chdir raises Errno::ENOENT. Raises ToolError for an empty command and ArgumentError for a non-positive timeout or output limit.