alknet/docs/research/alknet-tty/phase-0-findings.md

status, last_updated

status	last_updated
draft	2026-07-03

alknet-tty — Phase 0 Research Findings

This document captures Phase 0 (Exploration) findings for the alknet-tty crate. The objective of Phase 0 per docs/sdd_process.md is: "Capture vision and guiding principles; research options; validate approaches; converge on a recommended approach." It is the input to Phase 1 (Architecture), where the Architect will produce docs/architecture/crates/tty/*.md specs, ADRs, and open questions.

This document was drafted 2026-07-03, immediately after the alknet-docker POC (docs/research/alknet-docker/poc-summary.md) validated that bollard's container attach maps cleanly onto a framed bidi stream with a 1-byte stream-type multiplexer. The POC's raw chunk format is the seed of alknet-tty's wire format.

Vision Recap

alknet-tty is a terminal session protocol handler for the ALPN-as-service architecture (ADR-001). It registers the alknet/tty ALPN on the shared AlknetEndpoint and implements the ProtocolHandler trait (ADR-002, ADR-007).

The guiding insight, surfaced during the alknet-docker POC and recognized in the conversation that followed:

A terminal session is not an SSH concern, or a Docker concern — it is a terminal concern. SSH and Docker are just two backends that can allocate a PTY.

The alknet-docker POC proved that the hard part of interactive attach — bidirectional byte pumping over a framed stream with a multiplexing header — is the same problem regardless of whether the backend is bollard::attach_container() or russh's pty_request + session channel. The POC's raw chunk format ([stream_type: u8][length: u32 be][payload bytes], with stream_type 0=stdin, 1=stdout, 2=stderr) is a deliberately impoverished version of SSH's channel multiplexer: fixed set of channel types, no negotiation, no open/close handshake, no windowing (QUIC provides flow control on the bidi stream). That impoverishment is the feature — a terminal session needs exactly those channels and no more.

alknet-tty extracts that pattern into its own crate and ALPN. The backends (Docker, SSH, local process) implement a TtyBackend trait; the alknet/tty handler is backend-agnostic. This dissolves the PTY hedge in the alknet-ssh research (docs/research/alknet-ssh/phase-0-findings.md DP-5: "shell_request and pty_request default-reject; interactive shell is an explicit opt-in") — PTY is not an SSH feature, it's a tty feature that SSH happens to be able to provide.

Beyond terminals, the same wire format and backend trait support a general "runner" pattern: a process (local std::process::Command, docker container, SSH exec) whose stdin/stdout/stderr/exit-code are streamed over a framed bidi connection. The dispatch project (/workspace/@alkdev/dispatch/) is a reverse runner that currently requires an SSH server on the remote end; with alknet-tty and a local-process backend, the same runner pattern works without SSH at all — the endpoint runs the process directly and streams its I/O back. This is the same shape as GitHub/Gitea Actions runners, just over alknet's transport instead of HTTP polling.

Sources Investigated

Source	Path	Note
alknet-docker POC	/workspace/alknet-docker-poc/	Validated raw chunk format, two-carriage model, bidirectional pumping against live docker. The POC's src/raw.rs is the seed of alknet-tty's wire format.
alknet-docker POC summary	docs/research/alknet-docker/poc-summary.md	Documents the two-carriage model (JSON negotiation → raw bytes), the three validated targets, the open unknowns.
alknet-ssh phase-0 findings	docs/research/alknet-ssh/phase-0-findings.md	DP-5 hedges PTY as an SSH concern; the channel decomposition (Layers 1-7) treats PTY as part of Layer 4 (Session/exec). This document dissolves that hedge.
alknet-core types	crates/alknet-core/src/types.rs	ProtocolHandler, Connection, SendStream, RecvStream — the handler interface alknet-tty implements.
alknet-call wire format	crates/alknet-call/src/protocol/wire.rs	EventEnvelope, FrameFramedReader/Writer — the JSON carriage layer alknet-tty uses for the initial call.requested negotiation frame.
alknet-call dispatch	crates/alknet-call/src/protocol/dispatch.rs	handle_stream (:295), pump_stream (:340) — the streaming pump pattern. alknet-tty's raw-carriage path is a sibling to this, not a consumer of it.
bollard source	/workspace/bollard/src/	container.rs (attach_container :540, LogOutput :96, AttachContainerResults :80), read.rs (NewlineLogOutputDecoder :32 — the 8-byte header format our chunk format mirrors), exec.rs (StartExecResults enum :99)
bollard examples	/workspace/bollard/examples/attach_container.rs	Reliable attach + TTY passthrough.
dispatch project	/workspace/@alkdev/dispatch/	The "reverse runner" — axum + russh SSH client for exec/forwarding/sync over Docker/vast.ai. src/handlers.rs (start_job, job_status, job_logs) is the runner pattern alknet-tty generalizes. Currently requires SSH on the remote; alknet-tty with a local-process backend removes that requirement.
russh source	/workspace/russh/	server::Handler — pty_request (allocates PTY), window_change (resize), signal (signal forwarding), shell_request/exec_request. These are the SSH-side operations a SshTtyBackend wraps.
alknet-runtime research	docs/research/alknet-runtime/summary.md	The "operation host" pattern — a node that exposes ops on a registry. alknet-tty is the same pattern for process execution: a node that can run a process and stream its I/O.
Rust std::process	stdlib	Command, Stdio (piped stdin/stdout/stderr), Child::wait (exit code). The local-process backend. The threading/deadlock caveat (must read stdout/stderr concurrently with writing stdin to avoid pipe-buffer deadlock) is handled by the bidirectional pump, same as docker attach.

The Wire Format: From POC to Spec

What the alknet-docker POC validated

The POC's src/raw.rs defines a chunk format for raw carriage on a bidi stream:

[stream_type: u8][length: u32 be][payload bytes]

• stream_type mirrors bollard's NewlineLogOutputDecoder header byte (/workspace/bollard/src/read.rs:46): 0=stdin, 1=stdout, 2=stderr.
• length is the payload length in bytes (u32 big-endian, max 16 MiB).
• A zero-length chunk is a sentinel (used for completion notification).

The POC proved this format works for:

• server→client stdout/stderr: each LogOutput from bollard's attach stream becomes a chunk with the matching stream_type.
• client→server stdin: ChunkWriter::write_stdin(bytes) writes a type-0 chunk; the server reads it and writes the bytes to bollard's container_input (AsyncWrite).
• completion: when bollard's output stream ends (container exited), the server sends a zero-length type-1 chunk as a "drained" sentinel.

What alknet-tty adds

A terminal session needs two things the docker attach POC didn't:

1. Control messages during the raw phase. Window resize (SIGWINCH) and signal forwarding (Ctrl-C → SIGINT) must ride during the byte stream, not as a new request. The chunk format handles this by reserving a 4th stream_type:

   stream_type	channel	direction	payload
   0	data-in (stdin)	client→server	raw bytes
   1	data-out (stdout)	server→client	raw bytes
   2	data-err (stderr)	server→client	raw bytes
   3	control	bidirectional	JSON control message

   Control chunks carry a small JSON payload:

   • {"type":"resize","cols":80,"rows":24,"pixel_width":0,"pixel_height":0} — window resize (maps to SSH window-change, docker exec resize, or ioctl(TIOCSWINSZ) on a local PTY).
   • {"type":"signal","name":"INT"} — signal forwarding (maps to SSH signal, docker exec signal, or kill(pid, sig) on a local process).
   • {"type":"eof"} — client signals no more stdin (maps to SSH channel EOF, docker stdin close, or ChildStdin::drop).
   • {"type":"exit","code":0} — server signals process exit (terminal, no more data chunks follow; the stream then closes).

2. Terminal parameters at negotiation time. The initial call.requested frame (JSON carriage, same as the POC) carries the terminal attributes that the backend needs to allocate the PTY:

   {
     "operationId": "/tty/open",
     "carriage": "raw",
     "backend": "docker",
     "container": "abc123",
     "tty": {
       "term": "xterm-256color",
       "cols": 80,
       "rows": 24,
       "pixel_width": 0,
       "pixel_height": 0,
       "modes": {}
     },
     "cmd": ["/bin/bash"]
   }
   

   The tty block maps directly to SSH's pty_request parameters (term, cols, rows, pixel_width, pixel_height, modes) and to docker's CreateExecOptions { tty: true }. A local-process backend passes them to portable_pty::PtySystem::openpty (or equivalent).

Why fixed channel set, not extensible

SSH's channels are ChannelId(u32) with string-named types negotiated per channel. alknet-tty's channels are a fixed u8 set with no negotiation. This is a one-way door (adding a 5th channel type is a wire-format change), and it's the right one-way door:

• The use cases are bounded. A terminal session has stdin, stdout, stderr, and control. If something genuinely new appears (say, a sideband file-transfer channel alongside the terminal), that's a different ALPN, not a 5th tty channel type. The ALPN model handles extensibility at the protocol level — a new ALPN is cheap, a wire-format change is not.
• 1 byte vs length-prefixed string + negotiation round-trip. The fixed set is faster, simpler, and the demuxing is a match instead of a hash lookup. For a terminal session where every chunk is hot, this matters.
• The comparison to SSH channels is the justification, not the constraint. SSH needs dynamic channels because it multiplexes arbitrary services (forwarding, SFTP, agent, X11) over one connection. alknet-tty multiplexes one service (a terminal session) with a fixed channel structure. The impoverishment is the feature.

The Backend Trait

The TtyBackend trait is the inversion point that keeps alknet-tty decoupled from its backends:

#[async_trait]
pub trait TtyBackend: Send + Sync {
    async fn allocate(&self, params: &TtyParams) -> Result<TtyHandle, TtyError>;
}

pub struct TtyParams {
    pub backend_params: BackendParams,  // backend-specific (container id, ssh host, command)
    pub terminal: TerminalParams,        // term, cols, rows, modes
    pub cmd: Vec<String>,
}

pub enum BackendParams {
    Docker { container: String },
    Ssh { channel: SshChannelRef },
    Local { cwd: Option<PathBuf>, env: HashMap<String, String> },
}

pub struct TtyHandle {
    pub stdin: Box<dyn AsyncWrite + Send + Unpin>,
    pub stdout: Pin<Box<dyn Stream<Item = Bytes> + Send>>,
    pub stderr: Option<Pin<Box<dyn Stream<Item = Bytes> + Send>>>,  // None if PTY (merged into stdout)
    pub exit_code: BoxFuture<'static, Result<i32, TtyError>>,
    pub control: Box<dyn TtyControl + Send + Unpin>,  // resize, signal
}

The TtyAdapter (the ProtocolHandler for alknet/tty) receives the Connection, reads the call.requested frame, selects the backend by the backend field, calls allocate(), and pumps bytes bidirectionally using the chunk format. Control chunks are dispatched to TtyHandle::control. When exit_code resolves, the server sends a {"type":"exit","code":N} control chunk and closes the stream.

Three implementations, each in its own crate (the no-handler-depends-on- another-handler rule from ADR-003 is preserved — backends depend on alknet-tty for the trait, alknet-tty doesn't depend on them):

• DockerTtyBackend (in alknet-docker, or a thin adapter): wraps bollard::attach_container() → AttachContainerResults { output, input } for interactive attach, or bollard::exec::start_exec with tty: true for exec-with-PTY. The POC's drive_attach_raw is this backend, inlined; with the trait, it becomes impl TtyBackend for DockerTtyBackend. control.resize() calls bollard::exec::resize_exec or bollard::container::resize_container.

• SshTtyBackend (in alknet-ssh): wraps russh's pty_request + shell_request (or exec_request with a PTY) on a session channel. channel.into_stream() gives (AsyncRead, AsyncWrite) — the stream is the PTY; russh handles kernel PTY allocation on the server side. control.resize() sends a window_change channel request; control.signal() sends a signal channel request. stdout and stderr are merged (PTY property), so TtyHandle.stderr is None.

• LocalTtyBackend (in alknet-tty or a sibling crate): wraps std::process::Command with Stdio::piped() for stdin/stdout/stderr, OR portable_pty for a real PTY (needed for terminal escape sequences, signal delivery, window resize). Without a PTY, it's a "runner" (piped process); with a PTY, it's a terminal. control.resize() calls ioctl(TIOCSWINSZ) on the PTY master; control.signal() calls kill(child.pid, sig). The threading/deadlock caveat (must read stdout/stderr concurrently with writing stdin to avoid pipe-buffer deadlock) is handled by the bidirectional pump — the same pattern as docker attach, where tokio::spawn runs the two directions concurrently.

The runner generalization

The LocalTtyBackend without a PTY is the "runner" pattern: a process whose stdin/stdout/stderr/exit-code are streamed over a framed bidi connection. This is functionally identical to GitHub/Gitea Actions runners, just over alknet's transport instead of HTTP polling:

• A coordinator sends {"backend":"local","cmd":["cargo","test"],"tty":null} — no terminal, just a command.
• The endpoint runs cargo test with piped stdio, streams stdout/stderr chunks back, sends {"type":"exit","code":N} when it finishes.
• The coordinator gets reliable completion notification (the exit control chunk + stream close) — the same stopgap property as the docker logs subscription.

The dispatch project (/workspace/@alkdev/dispatch/) is a reverse runner that currently requires an SSH server on the remote end (it uses russh to exec commands and stream output). With LocalTtyBackend, the same pattern works without SSH — the endpoint runs the process directly. SSH becomes one transport option (for reaching hosts that don't run alknet), not a requirement. This is "discuss afterwards" territory per the conversation, but the trait shape preserves the option.

What This Dissolves in alknet-ssh

DP-5's PTY hedge

The alknet-ssh research (phase-0-findings.md DP-5) says:

shell_request and pty_request default-reject; exec_request permitted (gated by ACL). This keeps alknet-ssh a focused forwarding/exec appliance rather than a general-purpose interactive login server. Interactive shell is an explicit opt-in (two-way door).

With alknet-tty, PTY is not an SSH feature — it's a tty feature. alknet-ssh implements TtyBackend for SSH session channels; alknet-tty owns the terminal session lifecycle. alknet-ssh's session channel (Layer 4) still does exec (structured, JSON carriage, exit code on completion) but delegates PTY to alknet-tty. The "default-reject" stance stays for the SSH channel policy (alknet-ssh still rejects pty_request on its own session channels — it doesn't serve terminals directly), but the PTY capability is provided by a separate crate via a separate ALPN, not hedged inside alknet-ssh.

Layer 4 simplifies

The alknet-ssh build order was "1-4 first (SSH+exec), then 5 (forwarding), then 6/7 (SOCKS5/SFTP)." PTY was a deferred wart on Layer 4. With alknet-tty, Layer 4 is just exec (one-shot command, JSON carriage, exit code on completion) — clean and complete. PTY is a different ALPN (alknet/tty) that happens to use SSH as its backend.

The browser case gets a terminal for free

The alknet-ssh research notes the browser runs a WASM SSH client over WebTransport (ADR-040). But a browser terminal (xterm.js) doesn't want SSH — it wants a terminal. With alknet/tty as an ALPN, xterm.js connects via WebTransport to /alknet/tty, negotiates a session (docker container, SSH PTY, or local process), and gets raw bytes. The browser doesn't need to implement SSH at all for the terminal use case — it only needs SSH if it wants SSH-specific features (port forwarding, SFTP). This is a cleaner browser story than "run a WASM SSH client."

Straightforward Parts

These are settled by the POC, existing ADRs, and the wire format above. Phase 1 should document them as spec rather than re-litigate.

1. alknet-tty is a ProtocolHandler on alknet/tty

Same pattern as every other handler: TtyAdapter implements ProtocolHandler::handle(&self, connection: Connection, auth: &AuthContext) with alpn() = b"alknet/tty". The handler owns the entire Connection lifecycle (ADR-006) and accepts one bidi stream per terminal session.

2. The two-carriage model is inherited from the POC

The initial call.requested frame is JSON (length-prefixed EventEnvelope, identical to alknet-call's FrameFramedReader/Writer). After the request, the stream switches to raw chunks. The carriage field in the request payload is "raw" for terminal sessions. This is the same mechanism the POC validated; no new wire-format invention.

3. Raw chunk format is POC-validated

The [stream_type: u8][length: u32 be][payload] format, the ChunkReader/ ChunkWriter types, and the bidirectional pump pattern are all directly from the POC's src/raw.rs. The only addition is stream_type: 3 for control messages, which is a 1-byte extension to a validated format.

4. Backend trait is the inversion point

alknet-tty defines TtyBackend; the backend crates (alknet-docker, alknet-ssh, local) implement it. The TtyAdapter is backend-agnostic. This preserves ADR-003's no-handler-depends-on-another-handler rule: alknet-tty depends on alknet-core; the backend crates depend on alknet-tty (for the trait); alknet-tty doesn't depend on any backend.

5. Completion notification is free

The exit control chunk ({"type":"exit","code":N}) + stream close gives the coordinator deterministic completion notification — the same stopgap property the docker POC validated for logs subscriptions. No plugin state, no polling. The container/process exiting is the signal.

Less Straightforward Parts (Decision Points)

DP-1: Local-process backend in alknet-tty or a sibling crate?

(Recommended: two-way door — start in alknet-tty, extract if warranted)

The LocalTtyBackend (std::process::Command / portable_pty) is the simplest backend and the one that enables the runner pattern. It has no heavy dependencies (no bollard, no russh — just std + optionally portable_pty). Two options:

• (a) In alknet-tty: the crate ships with the local backend built-in. Pro: zero-config runner, one crate gets you a terminal/process-streaming endpoint. Con: alknet-tty pulls in portable_pty even for deployments that only use docker/ssh backends.
• (b) In a sibling crate (alknet-tty-local): alknet-tty defines the trait; the local backend is a separate crate. Pro: alknet-tty stays dependency-light; consumers opt into the local backend explicitly. Con: one extra crate for the common case.

Recommendation: (b) sibling crate, behind a feature flag on alknet-tty for the common case (features = ["local"] → re-export from alknet-tty-local). This keeps alknet-tty's default dependency surface minimal while making the local backend a one-feature opt-in. The local backend is where the portable_pty dependency lives; alknet-tty itself depends only on alknet-core and the frame/raw codec. Extraction is cheap because the trait is the seam.

DP-2: PTY vs pipe for the local backend

(Recommended: two-way door — support both, PTY is opt-in)

std::process::Command with Stdio::piped() gives pipes (no terminal semantics — no signal delivery, no window resize, no escape-sequence handling). portable_pty gives a real PTY (terminal semantics, resize, signals, escape sequences). The TtyParams.terminal field distinguishes: if terminal is Some(TerminalParams { ... }), the backend allocates a PTY; if None, it uses pipes (the runner case).

Recommendation: support both. The TtyHandle.stderr field is None for PTY (stdout/stderr merged) and Some for pipes (separate streams). The control field is a no-op impl for pipes (resize/signal don't apply without a PTY — though kill(pid, sig) still works for signal forwarding). The decision is per-session, not per-deployment.

DP-3: Control message format — JSON vs binary

(Recommended: two-way door — JSON first, binary if hot)

Control chunks (stream_type 3) carry a JSON payload ({"type":"resize", "cols":80,"rows":24}). This is consistent with the call protocol's JSON-everything stance and easy to extend. A binary format ([control_type: u8][params...]) would be faster but harder to extend and inconsistent with the negotiation layer.

Recommendation: JSON first. Control messages are rare (resize happens on window drag, signal on Ctrl-C) — the serialization cost is negligible compared to the data chunks. If a hot control path appears (unlikely for terminals), a binary format can be added as a control_type extension without breaking the chunk format.

DP-4: The threading/deadlock caveat for piped processes

(Recommended: acknowledged constraint — the bidirectional pump handles it)

std::process::Command with piped stdio can deadlock if stdin writes block while stdout/stderr buffers fill — the classic pipe-buffer deadlock. The fix is concurrent reads on stdout/stderr alongside stdin writes, which is exactly what the bidirectional pump does (the POC's drive_attach_raw runs the two directions as concurrent tokio::spawn tasks). The same pattern works for LocalTtyBackend: spawn one task pumping stdin→process, one task pumping process→stdout-chunks, one for stderr if piped.

Recommendation: Phase 1 records this as a known constraint with a known solution (concurrent pumping). No design decision needed — the POC already proved the pattern. The spec notes that LocalTtyBackend must use the concurrent-pump pattern, not sequential read-then-write.

DP-5: Exit code propagation — control chunk vs final data chunk

(Recommended: one-way door — control chunk)

The alknet-docker POC validated exit-code-on-final-call.responded for the JSON carriage path (exec with exit code). The raw carriage path needs a different mechanism because there's no call.responded after the raw phase begins. Two options:

• (a) Control chunk: {"type":"exit","code":N} as the last chunk before stream close. Clean, explicit, carries the code as structured data.
• (b) Final data chunk with exit code: a special stdout chunk with an exit-code payload. Hacky — overloads the data channel for metadata.

Recommendation: (a) control chunk. The exit code is control metadata, not data. The control channel (stream_type 3) exists for exactly this. The chunk is the last thing before stream close; the client reads it and knows the process exited with code N. This is a one-way door because clients will depend on the "exit chunk is last" invariant.

DP-6: Multiple sessions per connection

(Recommended: two-way door — one session per stream, multiple streams per connection)

A Connection (ADR-007) can open/accept multiple bidi streams. Should one alknet/tty connection host multiple terminal sessions (one per stream), or one session per connection?

Recommendation: one session per bidi stream, multiple streams per connection. This matches the call protocol's model (one operation per stream, multiple operations per connection) and is the natural fit for QUIC's stream multiplexing. A coordinator opens one connection to an endpoint and launches multiple sessions (one stream each) for parallel tasks. The TtyAdapter::handle accepts the connection and loops accept_bi, dispatching each stream to a session — same pattern as alknet-call's Dispatcher::run_loop (protocol/dispatch.rs:369).

Recommended Approach

Crate

alknet-tty, depends on alknet-core (for ProtocolHandler, Connection). Defines the TtyBackend trait, the wire format (chunk codec + control messages), and the TtyAdapter (ProtocolHandler for alknet/tty). Does not depend on bollard, russh, or portable_pty — those are in the backend crates.

Build order

Step 1: Wire format + TtyAdapter + mock backend.

• Extract raw.rs from the POC into alknet-tty's wire format module.
• Add stream_type: 3 (control) and the control message types (resize, signal, eof, exit).
• Implement TtyAdapter with a mock backend (in-memory pipes) to validate the full protocol: negotiate → pump → control → exit → close.
• Result: a working alknet/tty handler with no real backends, but the wire format and session lifecycle are proven.

Step 2: LocalTtyBackend (runner).

• alknet-tty-local crate (or feature): impl TtyBackend for LocalTtyBackend using std::process::Command with piped stdio.
• Validate the runner pattern: cargo test as the command, stream stdout/stderr/exit over alknet/tty.
• Add portable_pty for the PTY case (terminal semantics, resize, signals).
• Result: a working runner/terminal endpoint with no docker or SSH dependency.

Step 3: DockerTtyBackend.

• In alknet-docker: impl TtyBackend for DockerTtyBackend wrapping bollard::attach_container / exec with tty:true.
• The POC's drive_attach_raw becomes this backend; the TtyAdapter calls it via the trait.
• Result: docker containers as terminal sessions via alknet/tty.

Step 4: SshTtyBackend.

• In alknet-ssh: impl TtyBackend for SshTtyBackend wrapping russh's pty_request + shell_request/exec_request on a session channel.
• control.resize() → window_change channel request; control.signal() → signal channel request.
• Result: SSH PTYs as terminal sessions via alknet/tty. alknet-ssh's DP-5 hedge dissolves — PTY is delegated to alknet-tty.

De-risk POC (extending the alknet-docker POC)

The alknet-docker POC already validated targets 1 (attach round-trip), 2 (logs completion), and 3 (exec exit code). Two extensions validate the alknet-tty additions:

1. Control message during raw phase — add stream_type: 3 to the POC's chunk format, send a resize control chunk mid-session, prove the backend receives it. For docker this requires tty: true on the exec and bollard::exec::resize_exec. Small POC, validates the control channel mechanism.

2. PTY allocation via docker exec with TTY — CreateExecOptions { tty: true } allocates a real PTY. Validate that stdout/stderr merge (stream_type always 1) and that resize works. Proves the docker-as-PTY- backend path.

Both are extensions to the existing POC, not new POCs. The wire format and bidirectional pump are already proven; these just confirm the control channel and PTY-specific paths.

Open Questions to Carry into Phase 1

• OQ-TTY-01 (backend trait shape): the exact TtyHandle field set — is control a separate trait object or are resize/signal methods on TtyHandle directly? Does exit_code belong on the handle or is it a separate Future the adapter awaits? Resolved by Phase 1 spec; the POC extension informs the decision.
• OQ-TTY-02 (terminal modes): SSH's pty_request carries TTY modes (echo, raw, canonical, etc.) as a packed bitmask. Does alknet-tty support these, or defer to the backend's defaults? Likely defer for v1 (the common case is "default terminal modes"); the modes field in TerminalParams is reserved for future use.
• OQ-TTY-03 (flow control): the chunk format has no windowing (QUIC provides flow control on the bidi stream). Is this sufficient for high-throughput stdout (e.g., cargo build output)? QUIC's per-stream flow control should handle it, but a POC with real high-volume output would confirm. Low risk — the docker POC's logs subscription handled multi-line output without issue.
• OQ-TTY-04 (local backend crate placement): confirm alknet-tty-local as a sibling crate vs a feature flag on alknet-tty. DP-1 recommends sibling + feature re-export; Phase 1 confirms.
• OQ-TTY-05 (runner API surface): the "runner" generalization (local-process backend without PTY) is noted as "discuss afterwards" in the conversation. Phase 1 should at minimum preserve the option (TtyParams.terminal = None → pipe mode) even if the runner-specific API surface (job management, log persistence, task graph integration) is deferred to a later crate.

Next Steps (Phase 0 → Phase 1)

1. POC extension: extend /workspace/alknet-docker-poc with stream_type: 3 (control) and tty: true exec to validate the control channel and PTY allocation. Timeboxed; the wire format is already proven, these are extensions.
2. You decide on the DP recommendations (or amend them). DP-1 (local backend placement) and DP-5 (exit code on control chunk) are the load-bearing choices. DP-2, DP-3, DP-4, DP-6 are defaults recommended as-is.
3. Phase 1 (Architect): produce docs/architecture/crates/tty/README.md
   • component specs (tty-wire.md for the chunk format + control messages, tty-backend.md for the TtyBackend trait + TtyHandle, tty-adapter.md for the ProtocolHandler + session lifecycle, tty-local.md for the local backend / runner), ADRs for the accepted DPs (wire format + fixed channel set, backend trait as inversion point, local backend placement, exit code on control chunk), and the OQs above in open-questions.md. Update docs/architecture/README.md index and ADR table.

References

• docs/research/alknet-docker/poc-summary.md — the POC that seeded this crate. Raw chunk format, two-carriage model, three validated targets.
• /workspace/alknet-docker-poc/src/raw.rs — the chunk codec (ChunkReader, ChunkWriter, stream_type 0/1/2) that alknet-tty extends with stream_type 3.
• /workspace/alknet-docker-poc/src/ops.rs — drive_attach_raw (the bidirectional pump pattern, the session lifecycle) that the TtyAdapter generalizes.
• docs/research/alknet-ssh/phase-0-findings.md — DP-5 (PTY hedge, dissolved by this crate), the channel decomposition (Layers 1-7, PTY moves out of Layer 4), the browser case (xterm.js over WebTransport to /alknet/tty).
• docs/architecture/decisions/001-alpn-protocol-dispatch.md — ALPN dispatch
• docs/architecture/decisions/002-protocol-handler-trait.md — ProtocolHandler
• docs/architecture/decisions/007-bistream-type-definition.md — Connection, SendStream, RecvStream
• docs/architecture/decisions/003-crate-decomposition.md — no-handler-depends- on-another-handler (alknet-tty depends on alknet-core; backends depend on alknet-tty for the trait)
• docs/architecture/decisions/040-webtransport-alpn-stream-proxy.md — WebTransport stream → Connection (the browser terminal path)
• /workspace/bollard/src/read.rs — NewlineLogOutputDecoder (the 8-byte header format our chunk format mirrors)
• /workspace/russh/ — server::Handler (pty_request, window_change, signal) — the SSH operations a SshTtyBackend wraps
• /workspace/@alkdev/dispatch/ — the reverse runner that currently requires SSH; LocalTtyBackend removes that requirement
• docs/research/alknet-runtime/summary.md — the "operation host" pattern (alknet-tty is the same pattern for process execution)