Executes one explicitly selected executable with bounded captured output.
This Linux transport owns a native helper and its ordinary finite process
tree. It never uses a shell. A worker owns the Port and observes caller
death; the helper detects pipe closure after worker or VM death.
Target environment entries travel as bytes to child execve, preserving
empty values. The helper inherits the trusted host environment; requested
target variables do not configure the helper. TMUX and TMUX_PANE are
removed from the target environment.
Limits apply per call: stdout defaults to 1 MiB, stderr to 64 KiB, and
retained chunks to 4096. max_total_bytes additionally bounds both streams
together; it defaults to their summed limits. Overload returns an error
with a bounded prefix.
Independent caller processes require admission limits at their host or
server boundary; this primitive maintains no shared request queue.
A positive timeout becomes one execution deadline. Retirement can take
up to a separate 750 ms cleanup allowance after expiry. Missing retirement
proof remains :unknown. No result authorizes replay. Helper SIGKILL,
hostile escape and uninterruptible kernel tasks are outside the ordinary
tree guarantee. Building the native helper requires a C11 compiler.
Summary
Types
Per-call input and capture limits; bytes and chunks are bounded independently.
Captured bytes and child exit status after proven owned-process retirement; nonzero exit remains a transport result.
Functions
Runs argv without a shell, retaining exit status separately from stdout and stderr.
Runs argv, raising the same structured transport error on failure.
Types
@type option() :: {:timeout, 1..600_000} | {:deadline, LibTmux.Deadline.t()} | {:cwd, String.t()} | {:env, %{optional(binary()) => binary()}} | {:max_stdout_bytes | :max_stderr_bytes, 0..16_777_216} | {:max_total_bytes, nil | 0..33_554_432} | {:max_chunks, 1..65536}
Per-call input and capture limits; bytes and chunks are bounded independently.
Timeout and deadline are exclusive. A supplied deadline must have at most 600,000 ms remaining at validation; it preserves its original cutoff.
@type result() :: %{ stdout: binary(), stderr: binary(), exit_status: non_neg_integer(), cleanup: :retired }
Captured bytes and child exit status after proven owned-process retirement; nonzero exit remains a transport result.
Functions
@spec run(binary(), [binary()], [option()]) :: {:ok, result()} | {:error, LibTmux.Error.t()}
Runs argv without a shell, retaining exit status separately from stdout and stderr.
Runs argv, raising the same structured transport error on failure.