@@ -27,6 +27,7 @@ replay, and explicit lifecycle state.
2727- Promotion, canonical resize, and input are one ordered actor command.
2828- Subscription replay and live events cross one ordered actor boundary.
2929- OSC 0/2 title changes update authoritative terminal metadata and publish ordered subscription events.
30+ - A user title set by rename takes precedence over OSC titles; title changes publish only when the effective title changes.
3031- The deepest TTY-attached process in the foreground process group updates authoritative process metadata.
3132- Controller delivery applies backpressure; observers tolerate bounded output bursts and are disconnected when their backlog remains full.
3233- Adjacent output is coalesced before fanout, flushing at 8 KiB, after 1 ms, or before the next non-output event.
@@ -57,7 +58,7 @@ A snapshot is built on the actor thread and contains owned values only:
5758- Plain parsed screen text
5859- VT checkpoint synthesized by libghostty formatter
5960- Raw replay head and tail offsets
60- - Current title derived from libghostty state
61+ - Current effective title and user title
6162- Current foreground process derived from PTY process state
6263
6364No borrowed libghostty object crosses a thread boundary.
@@ -88,6 +89,24 @@ bounded. Results exceeding that budget fail rather than truncate. Complete
8889responses remain subject to the transport's 8 MiB frame limit. Protocol 7
8990supports ` read_rows ` alongside the existing snapshot and replay operations.
9091
92+ ## Titles
93+
94+ ` TerminalInfo.title ` is the effective title: the user title, else the latest
95+ OSC 0/2 title, else the title given at creation. An empty OSC title (a program
96+ resetting it) or an empty user title counts as unset. ` TerminalInfo.user_title `
97+ is always serialized, as ` null ` when unset.
98+
99+ ` Request::Rename { id, title: Option<String> } ` (` op: "rename" ` ) sets the user
100+ title, or clears it when ` title ` is null or empty, and returns ` Response::Ok ` .
101+ The terminal actor handles it as one command, so it is ordered with output.
102+ OSC titles keep being tracked while a user title is set and show through again
103+ once it is cleared.
104+
105+ Rename and OSC updates publish ` TitleChanged ` with the effective title only
106+ when it changes; an OSC change hidden behind a user title publishes nothing.
107+
108+ ` list ` returns terminals in creation order.
109+
91110## Failure Boundary
92111
93112Losing the owning server connection stops ` opencode-pty ` and its terminals.
@@ -108,11 +127,19 @@ only observe or operate an existing daemon and never start one.
108127Protocol v7 uses four-byte big-endian framing with bounded UTF-8 JSON control
109128frames and tagged raw binary output frames. It supports ping, create, list,
110129write, resize, atomic interaction promotion, snapshot, read_rows, replay, replay-to-live
111- subscriptions, title updates, controller takeover, terminate, and destructive service
130+ subscriptions, title updates, rename, controller takeover, terminate, and destructive service
112131shutdown, ownership acquisition, and restart handoff preparation.
113132
133+ ` Pong ` and the registration carry ` features ` , the daemon's additive
134+ capabilities (currently ` ["rename"] ` ). Additive changes, such as a new request
135+ or field older clients can ignore, extend ` features ` and keep the protocol
136+ version; clients check ` features ` before sending a new request, since a daemon
137+ that cannot parse one drops the connection. Only breaking changes bump
138+ ` PROTOCOL_VERSION ` , which clients reject on mismatch. A missing ` features `
139+ means none.
140+
114141Registration is written atomically with private permissions and contains an
115- instance ID, PID, protocol version, socket path, and random credential. A
142+ instance ID, PID, protocol version, features, socket path, and random credential. A
116143service lock elects one process and protects stale socket cleanup. On Unix, the
117144socket uses a fixed-length hash of the canonical runtime path
118145under a private per-user ` /tmp ` directory to stay below platform path limits.
0 commit comments