# `LibTmux.Control`
[🔗](https://github.com/libtmux/libtmux-elixir/blob/b72452c198917433229bdc266a68c163541b6127/lib/libtmux/control.ex#L1)

A connection handle pinned to one qualified control epoch.

`submit/3` returns a retained `LibTmux.Operation` after bounded admission.
It never retries, refreshes, attaches, creates sessions or changes transport.
`request_close/1` closes write authority for the entire pinned epoch through
reserved capacity; it does not prove retirement or roll back effects.

`start_link/1` explicitly attaches to an existing session. Its host must qualify
the server's effective hooks, aliases and stream writers for the whole lane;
a pinned handle is not authentication against unqualified command output or
arbitrary writes to internal tables. Reads and local selections never attach.

# `call_option`

```elixir
@type call_option() :: {:timeout, pos_integer()}
```

A positive millisecond budget shared by all stages of one lifecycle or submission call.

# `connection_status`

```elixir
@type connection_status() :: %{
  epoch: reference() | nil,
  generation: non_neg_integer(),
  phase: :starting | :ready | :closing | :retired | :unknown,
  instance: String.t() | nil
}
```

A pinned epoch's current phase and identity; retirement and unknown cleanup are distinct.

# `start_option`

```elixir
@type start_option() ::
  {:server, LibTmux.Server.t()}
  | {:session, {:existing, String.t()}}
  | {:lane, :host_qualified}
  | {:timeout, 1..600_000}
  | {:capacity | :metadata_capacity | :waiter_capacity, 1..256}
  | {:retention_ms, 1..600_000}
```

Explicit attachment policy and bounded startup settings; capacities count slots and timeouts use milliseconds.

# `t`

```elixir
@opaque t()
```

A handle pinned to one owner and connection epoch; it never follows a replacement.

# `child_spec`

```elixir
@spec child_spec([start_option()]) :: Supervisor.child_spec()
```

Builds a permanent supervisor child spec without attaching.

Prepares bounded detached inputs and one lifetime shared by all factory
invocations. Each invocation starts its own configured startup budget.
A restarted nonfresh lifetime returns an inert handle and never attaches
automatically. Proven retirement permits explicit `reconnect/2`; unknown
cleanup refuses it. Old handles never follow a replacement Root or Manager.

`Supervisor.start_child/2` and `Supervisor.restart_child/2` return the new
handle as their third info element. After an automatic restart, use
`Supervisor.terminate_child/2` followed by `Supervisor.restart_child/2` for
fresh info. This does not clear unknown cleanup or authorize replay.

# `close`

```elixir
@spec close(t(), [call_option()]) :: :ok | {:error, LibTmux.Error.t()}
```

Requests closure and waits for proven retirement of the pinned epoch.

`timeout` defaults to 5000ms. The original budget includes validation and
retirement waiting. Closure still happens if the bounded metadata wait cannot
be admitted. Timeout, overload or lost ownership reports unknown certainty;
it never proves cleanup. `:ok` requires known native and actor retirement.

The connection supervisor and retained records remain available for explicit
reconnect and inspection. This does not stop the supervisor or roll back
sibling effects.

# `close!`

```elixir
@spec close!(t(), [call_option()]) :: :ok
```

Waits for retirement or raises the same structured error.

# `reconnect`

```elixir
@spec reconnect(t(), [call_option()]) :: {:ok, t()} | {:error, LibTmux.Error.t()}
```

Explicitly obtains the ready epoch, starting a replacement only after retirement.

A ready epoch returns itself. Call `close/2` first to require replacement.
The default 5000ms budget covers metadata admission, retirement and startup.
A successful reply pins the acknowledged endpoint even if it becomes stale
before this caller resumes. It never follows a later view or replays work.
Errors report unknown certainty about existing effects. Attachment counts
include the control client; reconnect can attach one replacement client.

# `reconnect!`

```elixir
@spec reconnect!(t(), [call_option()]) :: t()
```

Obtains the ready epoch or raises the same structured error.

# `request_close`

```elixir
@spec request_close(t()) :: :ok | {:error, LibTmux.Error.t()}
```

Requests whole-epoch closure without claiming an operation or metadata slot.

Repeated requests for the same closing or proven-retired generation return
`:ok`. Success is a request or previously known retirement, not a cleanup
acknowledgement. A replacement Manager or epoch is never followed.

# `request_close!`

```elixir
@spec request_close!(t()) :: :ok
```

Requests epoch closure or raises the same structured error.

# `start_link`

```elixir
@spec start_link([start_option()]) :: {:ok, pid(), t()} | {:error, LibTmux.Error.t()}
```

Starts a linked connection and returns `{:ok, root, control}`.

Require `server: %LibTmux.Server{}`, `session: {:existing, "$id"}` and
`lane: :host_qualified`. No session is created. The attachment is visible in
tmux's client counts and can update session state. `no-output,ignore-size`
suppresses pane output and excludes this client from window sizing.

`timeout` defaults to 5000ms and accepts 1..600000ms. One budget covers input
preparation, Root startup, bootstrap, ready waiting and handoff. A fresh
factory returns a ready handle. Runtime failures return a structured error;
invalid trusted options raise `ArgumentError`. Ordinary OTP links remain:
an asynchronous fatal Root exit can terminate a non-trapping caller.

Failed startup fences its lifetime and requests exact-Root cleanup. Error
details distinguish observed Root exit from a kill request; unknown native
cleanup is never success. OTP can await Root exit after its initialization
timer expires, so a strict wall-clock caller-return bound remains unqualified.

Optional `capacity`, `metadata_capacity` and `waiter_capacity` default to 32
and accept 1..256. `retention_ms` defaults to 60000 and accepts 1..600000.

Ready connections buffer at most 64 KiB or 128 stdout chunks behind the
reader. Overflow closes the whole epoch with `resource_limit`; it never
replays commands. These receive limits do not cap borrowed-server memory.

# `status`

```elixir
@spec status(t()) :: {:ok, connection_status()} | {:error, LibTmux.Error.t()}
```

Reads the pinned epoch's current phase and identity without contacting tmux.

# `status!`

```elixir
@spec status!(t()) :: connection_status()
```

Reads pinned connection status or raises the same structured error.

# `submit`

```elixir
@spec submit(t(), LibTmux.Control.Request.t(), [call_option()]) ::
  {:ok, LibTmux.Operation.t()} | {:error, LibTmux.Error.t()}
```

Admits one request and returns its retained operation handle.

`timeout` defaults to 5000ms and covers validation, admission, queueing,
writes and replies under one monotonic deadline. Request binaries are
detached before publication. Invalid input, overload or stale context before
admission returns a no-write error. Every successful admission returns its
Operation, even if its context disappears before publication. Inspect that
handle for the eventual canonical result or an explicit lost-context error.

Closing the connection can affect sibling operations. Command replies do
not prove external program exit. Caller timeout does not authorize replay.

# `submit!`

```elixir
@spec submit!(t(), LibTmux.Control.Request.t(), [call_option()]) ::
  LibTmux.Operation.t()
```

Admits a request or raises the same structured error.

---

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