Experimental mirror wire contract

All integers in binary packets are unsigned big-endian. A packet is length:u32, then kind:u8, then payload. Length includes kind, excludes the four-byte prefix, and must be 1…8,388,608. Unknown kinds, malformed UTF-8, missing required fields and invalid payloads close the connection. This revision has no compatibility negotiation.

Sequence starts at 1. VT grid dimensions are 1…1000. Text dimensions allow zero for an unspecified test/source grid; production Ghostty sources supply actual sizes. Truncated is exactly 0 or 1. Empty text is a replacement. JSON frame/textFrame cases are rejected: frames must use their binary encoding. No Base64 frame content is sent.

Control JSON follows Swift Codable’s associated-value enum shape: no-payload list is {"list":{}}; a subscribe is {"subscribe":{"_0":{"paneID":"UUID", "representation":"text-v1","intent":"ifFree"}}}. The enum and payload structs in MirrorProtocol.swift define required fields. Both repositories verify identical fixed-byte vectors, independent of encode/decode round-trip tests.

Controls: challenge, authenticate, pair, paired, authenticated; list, panes; subscribe, subscribed, acknowledge, input, refresh; history, historyPage; command, commandResult, commandReceipt; failure, ended, ping, pong. There is no private Agent-state or private submission control. Command envelopes preserve the public CLI JSON and UUID request ID. See the feature documentation for command scope.

The launch-profile capability permits Profile-backed background tab creation. launch-shell additionally permits a background create tab with no launch field. Neither capability permits arbitrary initial Shell input. Mac clients gate Shell creation on launch-shell; existing Profile requests remain unchanged. The remote list command result adds optional data.worktrees, using the same worktree fields as data.items[].worktree, to include known worktrees without terminal panes. Clients without that field can still use worktrees from items.

Authentication and lifecycle#

TLS uses ECDHE-PSK with ChaCha20-Poly1305. Enrollment uses identity pair and the normalized temporary code. Runtime connections use the device UUID identity and 32 random secret bytes. No plain-PSK legacy suite is enabled.

TLS PSK membership alone is not treated as a device identity. Host sends its stable hostID and a fresh 32-byte nonce. Device proves its secret using HMAC-SHA256 over UTF-8 device:HOST_UUID:DEVICE_UUID: followed by nonce bytes. Enrollment proves the code over pair:HOST_UUID:DEVICE_NAME: plus nonce. UUID strings use the Foundation uppercase canonical spelling. Proofs are Base64 Data fields in control JSON. Different purpose, Host, identity or nonce cannot reuse a proof.

Before proof validation only authentication/enrollment and connection heartbeats are accepted. Enrollment persists Host-generated device ID/key before replying; the window is consumed before another peer can enroll. Client saves before closing the enrollment connection and reconnecting with its device credential. Host names are display metadata, never identity. Authentication has a five-second deadline. Failure accounting and pending TLS pools are bounded. No secret is logged.

A subscribed connection has exactly one lease. Every input, ACK, history request, refresh and targeted command must match it. Takeover revokes the previous connection. Delayed commands recheck authorization immediately before delivery. A command result is not a terminal/frame acknowledgement. One unacknowledged frame per subscriber bounds backpressure; an ACK must exactly match its outstanding sequence.

History ID/offset refer to one frozen snapshot, with fixed total and capture time. Pages cannot overlap, skip or exceed the total byte budget. Heartbeats run every two seconds; eight seconds without inbound traffic ends an established connection.