2dd9158f

docs: copy/paste discovery — measured, and it reorders the work

a73x 2026-08-15 13:07

Commit message

docs: copy/paste discovery — measured, and it reorders the work

Three escapes and an OSC 52 emitted by a session, none of them reaching
the host tty; the same capture proving itself live on ?1049 and ?2026.
Then the inbound half, which turned out to already work: paste brackets
typed at the client arrive at the session's pty byte for byte.

So bracketed paste is not a paste feature, it is one direction of a
missing mode mirror — and that mirror is also the whole of mouse support.
Filed as ee062dd9 (mirror), 7c777ec6 (OSC 52, with the query direction
refused on purpose), 063cec67 (scrollback copy, which the mirror's mouse
half will make necessary by taking the host's own selection away).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/decisions.md

@@ @@ -3564,3 +3564,59 @@ so they still pin the fallbacks they were written for. @@
+answers from `pgid`/`settle` and carries no exit code. That is legible
+rather than silent — every reply already names its `mechanism`, and
+`marks` simply stops being the one you get by default.
+## 2026-08-15 (copy/paste discovery — what the instrument showed)
+Discovery only: no product code changed, three issues filed (`ee062dd9`
+mode mirror, `7c777ec6` OSC 52, `063cec67` scrollback copy). The point was
+to stop reasoning about copy/paste from the source and measure it.
+**The rig.** `muxd --shell /bin/sh`, a real `mux` client on a pty via
+`test/ptyclient --out`, and the capture file read as "what the host
+terminal would have received". `--out` already existed for convergence;
+pointed at this question it is a passthrough oscilloscope.
+**Outbound: nothing gets through.** The session emitted `ESC[?2004h`,
+`ESC[?1000h`, `ESC[?1006h` and an OSC 52 clipboard set, then a visible
+marker. In the host capture: marker present (1), `ESC[?1049h` present (1),
+`ESC[?2026h` present (1) — so the capture was live and the session really
+ran — and `?2004h`, `?1000h`, `?1006h`, `]52;` all **zero**. The marker was
+also in `muxd dump`, so the daemon's engine had every one of them and the
+client simply never forwards any.
+**Inbound: already transparent, and this was the surprise.** Same rig,
+session running `cat -v`, client sent a literal `ESC[200~pasted line
+oneESC[201~`. `cat -v` echoed `^[[200~pasted line one^[[201~`. Paste
+brackets reach the session's pty byte for byte. **The inbound half needs no
+work at all** — the defect is entirely that the host terminal is never told
+to *produce* them.
+That is the finding that reorders the work. "Bracketed paste is broken"
+sounded like a paste-path feature; it is one direction of one missing
+mirror, and the same mirror is the whole of mouse support. Two symptoms,
+one mechanism, and the daemon already holds the state (ghostty-vt tracks
+`bracketed_paste`, `mouse_event_*`, `mouse_format_*`; `term.modes.get`
+reads them).
+**Three rules extracted.**
+**Measure the direction, not the feature.** Reading the code would have
+said "no bracketed paste" and a fix would have been designed for both
+halves. One `cat -v` said half of it already works.
+**A repainting client is not a passthrough client, and the difference is
+exactly the side channels.** Modes and OSC escapes are what a two-engine
+design silently drops, because neither is grid state and neither survives
+"paint what the daemon has". That class — not this instance — is what to
+audit next: title (already carried), bell, hyperlinks, colour queries.
+**The mode mirror trades a working path for an unbuilt one.** No mouse
+reporting is why your terminal's own selection works over a mux screen
+today. Mirroring the session's mouse modes takes that away the moment an
+app asks for the mouse — correct, and what every terminal does under tmux,
+but it means mux needs a copy mechanism of its own landing with, or before,
+the mouse half. Bracketed paste carries no such coupling and can ship
+alone. The claim that native selection works is reasoned plus confirmed in
+the negative (the escapes are absent); nobody has dragged a mouse across a
+real mux screen to check wide chars and trailing spaces, and that is named
+as unverified in `063cec67` rather than assumed.