A bidirectional stdin/stdout session with an external process.

For interactive CLIs driven over stdin (agent CLIs in stream-json mode). The owner writes lines in and receives lines out; the child runs in its own process group and dies with the session.

{:ok, session} = Forcola.Duplex.open(["claude", "--input-format", "stream-json"], [])
:ok = Forcola.Duplex.send_line(session, json)
receive do
  {:forcola_line, ^session, line} -> line
end
:ok = Forcola.Duplex.close(session)

Messages

The process that called open/2 (the owner) receives:

• {:forcola_line, session, line} - a stdout line, without its trailing newline. A partial line held across frames is delivered once its newline arrives; a final partial line is delivered before the exit message.
• {:forcola_stderr, session, line} - a stderr line, unless merge_stderr: true routed stderr into :forcola_line. Under pty: true a terminal carries a single stream, so stderr is always merged into :forcola_line and no :forcola_stderr messages arrive.
• {:forcola_exit, session, status} - the child exited on its own; status is the exit code, {:signal, n} for death by signal, {:signal, :unconfirmed} when bounded teardown could not prove every process was gone, {:spawn_error, reason} if it never started, or :shim_exited if the shim died without reporting. The session is over; close/1 is not required (but is harmless).

Bounded pull delivery

delivery: :pull replaces owner line messages with recv/2. Each call demands one stdout or stderr line. Both native output pumps start with zero read credit, so an idle or slow consumer stops the pumps, then the child's OS pipes fill and its writes block. At most one recv/2 caller may wait at a time. A pending demand grants at most :max_pending_bytes to each stream; no further credit is granted while complete lines wait in the session queue. The queue and partial-line buffers are therefore bounded by two credit windows plus two partial-line limits and frames already in transit. The native pumps forward at most 8192 bytes per frame. OS pipe capacity is platform-dependent and lies outside the BEAM memory bound.

A line exceeding :max_line_bytes or cumulative output exceeding :max_output_bytes kills the child group. recv/2 returns typed limit evidence in Terminal.output; its status and cleanup confirmation remain separate. An intentional shutdown that discards unread output reports output: :truncated. A transport loss reports output: :unknown. After child exit the pumps stay gated until the caller drains output or calls shutdown/1; await_terminal/2 can therefore wait for a pull consumer that has not finished reading.

Pull mode uses separate stdout and stderr pipes. merge_stderr: true with pipes is rejected because it would hide which pump consumed credit; a pty remains a single merged stream and needs only stdout credit.

Kill discipline

close/1 kills the child's process group (SIGTERM, then SIGKILL after the kill grace) and blocks for the shim's confirmation. shutdown/1 does the same and returns a Forcola.Duplex.Terminal with the observed status, confirmation, and active cleanup scope. await_terminal/2 retrieves that evidence after a spontaneous exit, including after the session process dies. The owner may call forget_terminal/1 when it no longer needs the result; otherwise the small terminal record lives until the owner exits. terminal_recipient: pid also sends {:forcola_terminal, session, terminal} to another process, so an owner supervisor can retain the evidence if the owner dies. The session monitors its owner: owner death takes the same path. If the session process itself is killed brutally, or the whole BEAM dies, the port closes, the shim sees stdin EOF, and the group is killed anyway.

For CLIs that exit when their stdin closes, send_eof/1 closes the child's stdin without killing anything; the child's own exit then arrives as a :forcola_exit message.

Pseudo-terminal

open/2 with pty: true runs the child under a pseudo-terminal instead of pipes. CLIs that detect a tty behave as they do in a real terminal: line buffering rather than block buffering, color output, progress rendering, and interactive prompts (password entry, pagers, REPLs, TUIs).

A terminal carries one bidirectional stream, so a pty merges the child's stdout and stderr: all output arrives as {:forcola_line, ...} and no :forcola_stderr messages are produced. merge_stderr: false contradicts this and raises ArgumentError. An initial window size can be set with :pty_rows and :pty_cols; there is no dynamic resize yet.