# Class LittleGhost::Sandbox::ProcessRunner

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Sandbox/ProcessRunner.html

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.

## Inheritance

`LittleGhost::Sandbox::ProcessRunner < Object`

## Class methods

<a id="method-c-capture"></a>
### `.capture`

```ruby
.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)
```

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.
