# `LibTmux.Transport.OneShot`
[🔗](https://github.com/libtmux/libtmux-elixir/blob/b72452c198917433229bdc266a68c163541b6127/lib/libtmux/transport/oneshot.ex#L1)

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.

# `option`

```elixir
@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.

# `result`

```elixir
@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.

# `run`

```elixir
@spec run(binary(), [binary()], [option()]) ::
  {:ok, result()} | {:error, LibTmux.Error.t()}
```

Runs argv without a shell, retaining exit status separately from stdout and stderr.

# `run!`

```elixir
@spec run!(binary(), [binary()], [option()]) :: result()
```

Runs argv, raising the same structured transport error on failure.

---

*Consult [api-reference.md](api-reference.md) for complete listing*