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.