A session end to end, and proving it locally

The agent interprets exactly three control messages and one byte stream. This unit walks a session from open to close, then reproduces the whole relay on your own machine with no Diyar broker involved.

The wire protocol

Every hop - operator to broker, broker to agent - carries the same two message kinds, symmetric on both sides of the broker:

WS Text = control JSON: {"t":"open"}, {"t":"resize","cols":100,"rows":30}, {"t":"close"}.
WS Binary = raw terminal bytes. Operator→agent is what you type (PTY stdin); agent→operator is what the shell prints (PTY stdout).

The broker itself only ever pipes frames between the two sides; it does not interpret them. The agent is what owns the PTY and reacts to control, which is what makes the broker replaceable - massar-broker-dev in this unit and the real Diyar broker both speak the exact same protocol to the agent.

What happens at each stage

Open. open_session allocates a fresh PTY (native_pty_system().openpty), sized to whatever cols/rows came with the request or defaulting to 80x24, then spawns the platform's own default shell on it:

rust

fn default_shell() -> String {
    if cfg!(windows) {
        std::env::var("COMSPEC").unwrap_or_else(|_| "powershell.exe".into())
    } else {
        std::env::var("SHELL").unwrap_or_else(|_| "/bin/bash".into())
    }
}

The shell is started with TERM=xterm-256color and, when HOME/USERPROFILE is available, with that as its working directory. A dedicated OS thread blocks on reading the PTY's master side and forwards every chunk it reads to the broker as a Binary frame; a second thread drains a channel fed by incoming Binary frames and writes them to the PTY's stdin. Both are ordinary blocking reads and writes on their own threads, deliberately kept off the async runtime.

Resize. A resize control message with cols/rows calls the PTY master's own resize directly - no restart of the shell, no new session.

Close. An operator-initiated close kills the child process outright. Independently, when the shell itself exits - the user typed exit, or the process died - the PTY reader thread hits EOF, and the agent sends {"t":"exit"} back over the control channel so the operator side learns the session ended instead of just going silent.

There is nothing outside of this lifecycle: the agent holds no standing shell. README is explicit about it: "a PTY exists only for the duration of an explicitly-opened, TTL-bounded session." It is torn down on an operator close, on the shell exiting on its own, or on the broker connection dropping - whichever comes first.

Proving it locally

The full path - operator client, broker, agent, a real PTY, a real shell - runs on one machine with no Diyar account, no network beyond loopback, using the dev-tools feature:

bash

cargo build --features dev-tools
massar-broker-dev &                          # listens 127.0.0.1:8088
MASSAR_BROKER_URL=ws://127.0.0.1:8088/agent MASSAR_DEVICE_ID=dev MASSAR_AGENT_TOKEN=dev massar-agent &
MASSAR_DEVICE_ID=dev massar-op-test          # PASS = sentinel round-tripped through the PTY

massar-broker-dev is an axum server exposing GET /agent (where massar-agent dials in and registers itself by device_id) and GET /op (where an operator attaches; the broker tells the registered agent to open, then pipes frames both ways verbatim). Its own doc comment is explicit about what it is not: "NOT for production (no Vent RBAC, no audit, no session recording, no TLS) - those land when this moves into diyar."
massar-agent here is the identical binary you would install on a real device - it does not need the dev-tools feature to build or run; only the dev broker and the test client require it.
massar-op-test attaches to /op the same way a browser-based terminal would: it sends a resize, types echo MASSAR_PROOF_OK\r followed by exit\r, and requires the sentinel MASSAR_PROOF_OK to appear twice in the transcript - once as the command it typed, once as the shell's own echo of the result - before printing PASS and exiting 0. Fewer than two hits is a FAIL, exit 1.

TIP

On Windows, ConPTY sends a cursor-position query (ESC[6n, a Device Status Report) the moment the shell starts, and stalls rendering until it gets an answer. A real terminal - the xterm.js web terminal on the operator side - answers this automatically. massar-op-test does the same thing (replying ESC[1;1R), which is why the automated relay test passes on Windows as well as Linux rather than only on one of them.

What you'll see if it's working

Both massar-broker-dev and massar-agent log at info level by default (no RUST_LOG needed). Across the three processes you should see, in order: the broker logging agent registered as massar-agent dials in, the agent logging connected to console broker and then session opened once massar-op-test attaches, the broker logging operator attached, and finally massar-op-test printing the relayed transcript followed by PASS: sentinel round-tripped through the relayed PTY (2x).

Control message	Direction	Carries
`open`	broker → agent	nothing (agent defaults to 80×24)
`resize`	operator → agent	`cols`, `rows`
`close`	operator → agent	nothing
`exit`	agent → operator	nothing (shell exited on its own)

This is the Day-0 proof that actually runs end to end in this repository: the local massar-broker-dev / massar-op-test harness, not a production Diyar deployment. It's the automated cross-platform relay test the project keeps green (ADR-0002), and it's what you can reproduce yourself before ever pointing a real agent at a real broker URL.