@spec attach(:controlling | :group_leader, session(), keyword()) ::
  {:ok, {:exited, non_neg_integer()} | {:signaled, pos_integer()} | :detached}
  | {:error, :no_local_tty | :no_process | :gl_eof | term()}

Hands the caller's terminal over to session's PTY master and pumps bytes both ways until the workload exits, then restores the terminal.

target selects how the caller's terminal is reached:

• :controlling — open /dev/tty directly. Works wherever the BEAM's controlling terminal is the user's terminal (local iex on a terminal emulator, Nerves HDMI / UART console). Refuses with {:error, :no_local_tty} when the caller is over SSH (the local-tty guard).

• :group_leader — pump through the caller's Process.group_leader/0 via Erlang's I/O protocol. Works over SSH / :remsh and anywhere else the user's terminal is an Erlang process rather than a kernel tty fd. Also works on a local terminal; it's the universal mode.

Returns the terminal event from the session — {:ok, {:exited, n}}, {:ok, {:signaled, n}} — {:ok, :detached} if the caller typed the detach sequence (see below), or {:error, _} for a setup failure or a pre-exec workload error.

Detaching (leaving the workload running)

opts[:detach_key] is a byte sequence that, when typed, ends the attach without stopping the workload: the pump returns {:ok, :detached} and the terminal is restored, but the workload keeps running, ready to be re-attached. It defaults to <<16, 17>> — Ctrl-P Ctrl-Q, docker's default. Pass detach_key: nil (or "") to disable it, in which case attach/3 returns only when the workload itself terminates.

The sequence is matched byte-for-byte across reads: a lone first byte (e.g. Ctrl-P) is held one keystroke; if the following byte does not complete the sequence, the held byte is forwarded to the workload ahead of it, so a detach prefix that is also a useful key still reaches the workload when it isn't a detach.

:group_leader mode specifics

Implementation: set :io.setopts(gl, echo: false) so :group routes input through its :dumb state (byte-oriented, no line editor); flip the driver's :prim_tty output mode from :cooked to :raw via :sys.replace_state/2 so workload output bytes pass through verbatim instead of being rendered in caret notation (without this, the workload's   backspace-erase echo arrives at the SSH client as ^( ^(); spawn a reader sub-process that loops on :io.get_chars(:standard_io, ~c"", 1) and forwards bytes to the pump's mailbox. N = 1 is intentional: :group's :dumb state runs collect_chars (non-eager), which waits for exactly N chars before returning; the eager variant (collect_chars_eager, which returns whatever's available) is gated by shell = noshell, unreachable with an iex shell attached. One byte per round-trip is sub-microsecond and invisible at interactive speeds, including paste.

Both transient state changes (echo and prim_tty output mode) are restored unconditionally on exit via try/after, even on a raise inside the pump.

Ctrl-C handling

ssh_cli intercepts byte \x03 (Ctrl-C) from the SSH stream and turns it into exit(group, interrupt) instead of passing the byte through. The pump translates that back into a literal \x03 byte to the workload's PTY in both shapes it can arrive: as {:error, :interrupted} on the reader's pending :io.get_chars (the common case), and as a direct {:EXIT, ^gl, :interrupt} to the pump's mailbox (the race case where the interrupt arrives between two reader round-trips). The workload's PTY line discipline then turns the byte into SIGINT for the foreground process group — the user-visible "Ctrl-C interrupts the running command" behaviour. pump output via :io.put_chars(gl, bytes), which sends {put_chars, :unicode, _}. The unicode encoding is mandatory here — OTP's ssh_cli has no iorequest clause for :latin1 and silently drops IO.binwrite/2's `{put_chars, :latin1, }via itsunhandled_requestcatch-all, hanging the caller. Window size is seeded from:io.columns/0+:io.rows/0and re-checked on a polling timer (default 250ms) since SSH has no SIGWINCH equivalent. The choice of polling vs an event-driven trace hook on ssh_cli is discussed at the@winsize_poll_ms` module attribute below.

Side-effects worth knowing about, all transient (restored on return, even on a raise inside the pump):

• The caller's :echo opt is flipped to false. iex's line editing (history, completion, ^A/^E, etc.) is bypassed for the duration — bytes go to the workload, not the iex readline. Expected; the workload's own shell does its editing on the other side of the PTY.
• Window-size updates lag by up to :winsize_poll_ms (default 250). Fine for shells; barely noticeable even mid-vim.

Caveat: the SSH transport keeps the line-discipline of the user's local terminal (your local ssh client puts your local terminal in raw mode by default; if it didn't, no amount of BEAM-side wrangling would deliver per-keystroke input). All observed nerves_ssh paths are fine here.

Owner requirement

attach/2 must be called from the process that owns session — the pid that received {:linx_process, :ready, _} when the session was spawned. The pump waits for {:linx_process, :pty_out, _} events in the calling process's mailbox; if they go elsewhere it blocks forever. The owner defaults to the caller of spawn/1, so the natural case ("spawn and attach from the same place") works without thought.

Restore is unconditional

The byte pump runs in the calling process and blocks until the workload terminates. The caller's terminal is restored unconditionally via try/after, even on a crash inside the loop, so a wedged terminal is structurally impossible.

@spec format_error(term()) :: binary()

Returns a human-readable description for error atoms Linx.Tty returns. Currently covers :no_local_tty (the local-tty guard's refusal); falls back to inspect/1 for any other shape so it can be safely chained at error sites without losing information.

@spec open_controlling_raw() :: {:ok, fd(), Linx.Tty.Saved.t()} | {:error, term()}

Opens /dev/tty and switches it to raw mode (cfmakeraw(3)), saving the current termios so it can be restored later.

Returns {:ok, fd, saved} on success — fd for wrapping with :erlang.open_port({:fd, fd, fd}, [...]), saved for restore_and_close/2. {:error, %Linx.Tty.Error{}} covers the failure paths (operation is one of :open, :tcgetattr, :tcsetattr); the most common case — BEAM without a controlling terminal — surfaces as {:error, %Linx.Tty.Error{operation: :open, errno: :enxio}}.

Pair every successful call with restore_and_close/2 (idiomatically in a try/after) so the user's terminal can never be left stuck in raw mode.

@spec restore_and_close(fd(), Linx.Tty.Saved.t()) :: :ok | {:error, term()}

Restores the saved termios on fd and closes the fd.

Symmetric finaliser for open_controlling_raw/0. Idempotent against already-closed fds — calling it twice (e.g. once explicitly, then again from an outer try/after) is safe.

@spec set_window_size(fd(), Linx.Tty.WindowSize.t()) :: :ok | {:error, term()}

Sets the window size of the terminal named by fd (ioctl(TIOCSWINSZ)).

The common path for setting the workload's window size goes through the agent — Linx.Process.pty_set_winsize/2. This verb is for the rare case of mutating a tty fd held directly by the caller.

@spec version() :: binary()

Returns the linx_tty NIF identifier string — sanity that the native library loaded and its ABI is reachable.

@spec window_size(fd()) :: {:ok, Linx.Tty.WindowSize.t()} | {:error, term()}

Returns the current window size of the terminal named by fd (ioctl(TIOCGWINSZ)).