alktty/docs/architecture/decisions/004-exit-code-on-control-chunk.md

# ADR-004: Exit Code on a Control Chunk (the Last Chunk Before Stream Close)

## Status

Accepted (ported from alknet ADR-055 2026-08-17; cross-references
renumbered to alktty's ADR range: ADR-052→001, ADR-053→002,
ADR-054→003, ADR-055→004, ADR-056→005, ADR-057→006, ADR-077→007,
ADR-093→008. The alknet ADR referenced by alknet number (052, 053) is
not ported into alktty's ADR range as a separate ADR; it is ADR-001
and ADR-002 here. The alknet originals at
`/workspace/@alkdev/alknet/docs/architecture/decisions/` remain
authoritative for any ADR not yet ported.)

## Context

The alknet-docker POC validated exit-code propagation for the JSON
carriage path: exec with an exit code rides on a final `call.responded`
frame `{ "exitCode": N }` before `call.completed`. That works because
the JSON carriage path is the call protocol: `call.responded` and
`call.completed` exist and carry the result.

The raw-carriage path (ADR-001) has no `call.responded` and no
`call.completed`; after the negotiation frame, the stream is raw
chunks. The exit code must ride on the chunk format itself. Two options:

- **(a) Control chunk**: `{"type":"exit","code":N}` as the last control
  chunk (`STREAM_CTRL_OUT`, stream_type 4) before stream close. Clean,
  explicit, carries the code as structured data on the channel that
  already exists for control metadata.
- **(b) Final data chunk with exit code**: a special stdout chunk with
  an exit-code payload. Overloads the data channel for metadata: a
  client parsing stdout chunks would have to special-case "this stdout
  chunk is actually an exit code," conflating data and control.

The local-PTY POC validated option (a) end-to-end: the
`{"type":"exit","code":N}` chunk fires after the child is reaped (the
waiter thread's `oneshot::Receiver<i32>` resolves) and is the last
control chunk before the stream closes. The POC's `session.rs`
`pump_exit` task awaits `pty.exit_code`, serializes the result as
`ControlMessage::Exit { code }`, enqueues it as a control chunk, and
the drainer writes it to the client before the writer closes.

### Why this is a one-way door

Clients will depend on the **"exit chunk is last"** invariant: after
the exit control chunk, no more data chunks follow, and the stream
closes. This is the deterministic completion notification the docker
POC identified as the stopgap coordination property: a coordinator
spawns a process, streams its output, and gets a reliable "it exited
with code N" signal without polling or plugin state. Changing the
ordering after clients exist would break every consumer that reads
stdout until the exit chunk and then stops.

## Decision

### 1. The exit code rides on a control chunk, not a data chunk

The exit code is control metadata (the process's termination status),
not data (process output). It rides on the control channel
(`STREAM_CTRL_OUT`, stream_type 4, ADR-001) as:

```json
{"type":"exit","code":0}
```

The `code` is an `i32` in this crate's exit-status convention:
`ExitStatus::code()` on normal exit; on Unix, the negative signal
number on signal-terminated exit (e.g., `-9` for SIGKILL), which is the same
convention as Python's `subprocess.Popen.returncode`. It is **not**
`ExitStatus::code()`'s behavior, which returns `None` for signal
termination. Both local backends encode it: the pipe path via
`ExitStatusExt::signal()` (`src/local/pipe.rs::exit_code_from`), the
PTY path via a direct `libc::waitpid` reap decoded to `WEXITSTATUS` /
`-WTERMSIG` (`src/local/pty.rs::wait_exit_code`); portable-pty 0.9.0's
`ExitStatus` would flatten a signal death to `code = 1` with the signal
only as a strsignal name string, so the waiter reaps by pid and skips
the conversion (review #004). The chunk is the last control chunk
before stream close.

### 2. The "exit chunk is last" invariant

After the `{"type":"exit","code":N}` control chunk:

- The server sends no more data chunks (stdout/stderr) and no more
  control chunks.
- The server closes the write half of the bidi stream.

A client reads stdout/stderr/control chunks until it sees the exit
chunk, records the exit code, and treats subsequent stream close as the
session end. The exit chunk is the deterministic completion signal.

### 3. The adapter owns the exit-chunk ordering, not the backend

Per ADR-002 assumption 3, the backend resolves `exit_code` (a
`BoxFuture<'static, Result<i32, TtyError>>`); the adapter awaits it,
sends the exit control chunk, and closes the stream. The backend does
not write to the wire: it produces handles; the adapter pumps. This
keeps the wire-format logic (including the "exit is last" invariant) in
one place (the adapter's session driver) and the backend focused on its
allocation target.

The adapter's session driver (see `tty-adapter.md`) runs three
concurrent pumps:

1. **stdout → client**: backend stdout → stdout chunks (and stderr
   chunks if `TtyHandle.stderr` is `Some`).
2. **client → backend**: stdin chunks → backend stdin; control chunks →
   `TtyControl::resize`/`signal`/`eof`.
3. **exit → exit chunk**: await `TtyHandle.exit_code`; on resolve,
   enqueue `{"type":"exit","code":N}` as a control chunk; after the
   drainer writes it, close the write half.

The exit-chunk task coordinates with the stdout pump: the stdout pump
completes (backend stdout EOF) before or concurrently with the exit
resolve, and the exit chunk is enqueued only after the exit resolves.
The drainer writes chunks in arrival order; the exit chunk is last
because the exit is the last thing to resolve (the child must exit
before its stdout drains, but the exit chunk is sent only after
`exit_code` resolves, which is after `Child::wait()` returns, i.e.,
after the child is reaped).

### 4. Error exit codes

A backend `TtyError` during `allocate()` (the PTY couldn't be
allocated, the docker exec failed to start, the SSH channel request was
rejected) is handled before the raw-carriage phase begins; the adapter
sends a JSON error response to the negotiation frame and closes the
stream without entering raw mode. See `tty-adapter.md` §"Negotiation
errors".

A `TtyError` from the `exit_code` future (the child couldn't be reaped,
or the backend's wait path failed) is serialized as an exit code of
`-1` (`ControlMessage::Exit { code: -1 }`) and the stream closes. The
client treats `-1` as "the backend reported an exit error, not a real
exit code." This is a best-effort signal; a backend that cannot
determine the exit code still sends the exit chunk so the client gets
the completion notification.

## Consequences

**Positive:**

- The exit code is structured data on the control channel, not a hacky
  overload of the data channel. Clients parse it as a
  `ControlMessage::Exit`, not as a special-cased stdout chunk.
- The "exit chunk is last" invariant gives coordinators deterministic
  completion notification: the same stopgap property the docker POC
  validated for logs subscriptions. No polling, no plugin state; the
  process exiting is the signal.
- The adapter owns the ordering, so the invariant is enforced in one
  place; backends don't have to know the wire format's completion
  semantics.
- The error-exit `-1` fallback keeps the completion notification
  reliable even when the backend can't determine the real code, so the
  client still knows the session ended.

**Negative:**

- The "exit chunk is last" invariant is a one-way door: clients depend
  on it. Reversing it (allowing data chunks after the exit chunk, or
  moving the exit code to a data chunk) would break every consumer.
  This is the intended commitment: the invariant is the value.
- A client that doesn't read until the exit chunk (e.g., a runner that
  cancels mid-stream by closing the write half) won't see the exit
  code. That's correct: a cancelled stream doesn't have a
  deterministic exit; the client that cancels already knows it
  cancelled. The exit chunk is for the client that reads to completion.
- The `-1` sentinel collides with a real SIGHUP termination on the
  Unix pipe path: signal-terminated children are encoded `-N`, so
  SIGHUP (signal 1) encodes as exactly `-1`, the same value the
  adapter sends for a backend wait failure. A client can't
  distinguish a real SIGHUP termination from a backend wait failure
  from the code alone. The collision is narrow in practice (the usual
  way a pipe-mode child receives SIGHUP is a client-sent
  `Signal { name: "HUP" }` control chunk, which the client knows it
  sent), but it is real for any other SIGHUP source. Note
  `std::process::ExitStatus::code()` cannot itself cause the
  collision (it returns `None` for signal termination), so this
  conflation exists only through this crate's `-N` encoding. If
  distinguishing becomes load-bearing, a future control message type
  (`{"type":"exit_error","message":"..."}`) can carry the distinction
  additively (the `type`-tagged enum is the extension seam per
  ADR-001).

## Door type

**One-way.** The "exit chunk is last" invariant is what clients depend
on for deterministic completion. Changing it after clients exist breaks
every consumer. The `{"type":"exit","code":N}` shape is also one-way
(clients parse it as a `ControlMessage::Exit`), though the
`type`-tagged enum (ADR-001) makes adding *new* control message types
additive.

## Assumptions

1. **The child exits before its stdout fully drains, and the exit chunk
   is sent after `exit_code` resolves.** On Unix, `Child::wait()`
   blocks until the child is reaped, which happens after the child
   exits and its stdout pipe/PTY buffer drains. The POC validated this
   ordering: the reader thread sees EOF (buffer drained), the waiter
   thread reaps (exit code available), and the exit chunk is enqueued
   after the exit resolves. There is no race where stdout chunks arrive
   after the exit chunk.

2. **`exit_code` resolving implies the stdout pump is done or will be
   soon.** The adapter's session driver waits for both the stdout pump
   to complete (backend stdout EOF) and the exit to resolve before
   sending the exit chunk and closing. If a backend's stdout outlives
   the exit resolve (a hypothetical backend where the process exits but
   a buffer flush is still in flight), the adapter waits for the stdout
   pump before the exit chunk. The `TtyHandle.stderr` (if `Some`) is
   pumped concurrently with stdout and also drains before the exit
   chunk.

## References

- [ADR-001](001-wire-format-and-two-carriage.md): the wire format
  (control channel, `STREAM_CTRL_OUT` stream_type 4) this ADR's exit
  chunk rides on
- [ADR-002](002-ttybackend-trait-and-ttyhandle.md): the
  `TtyHandle.exit_code` field (the `Future` the adapter awaits) this
  ADR's ordering consumes
- [ADR-005](005-backend-cleanup-on-session-cancel.md): the cancel path
  that bypasses this ADR's happy-path ordering (no exit chunk is sent
  on cancel, since the stream is gone)
- [ADR-008](008-channels-pure-channel-multiplexing.md): the
  exit-chunk-is-last invariant generalizes to channels mode (the exit
  chunk is the last `STREAM_CTRL_OUT` chunk before the channel closes)
- Spec: [tty-adapter.md](../tty-adapter.md) (the session driver that
  enforces the ordering)
- Port origin: alknet ADR-055 at
  `/workspace/@alkdev/alknet/docs/architecture/decisions/055-exit-code-on-control-chunk.md`