Pane output revisions: race-free detection of new output over the socket API

[thomasvan]

Hi! I'd like to propose a way for socket-API clients to detect new pane output without polling.

Problem: today the only way to know whether a pane produced new output is to call pane.read repeatedly and diff the text. That's racy (there's no way to express "wait for output after point X"), wasteful for large scrollbacks, and any client-side heuristic breaks across respawn and live handoff. I hit this while driving herdr panes from an agent orchestrator that needs to wake up when a command produces output.

Idea:

• Each pane keeps a monotonic u64 output revision, bumped on PTY output
• pane.read and PaneInfo report the current revision, so any read doubles as a sync point
• A coalesced pane_output_changed { pane_id, revision } event plus a wait/subscription variant, so clients can wait for "revision > N" race-free
• Revisions stay monotonic per pane across respawn, deferred resume, and live handoff

It's purely additive — new event kind and optional fields, no cost for clients that don't subscribe.

I have a working implementation with integration tests that I can put up if the idea is accepted. (I mistakenly opened PR #1276 before reading CONTRIBUTING.md — apologies for that. Happy to follow whatever process you prefer, including splitting into smaller pieces or a different API shape.)

Would you be open to this?

[Optic00]

Independent support for this from the client side, and one thing I would like the design to leave room for.

I drive panes from a phone client and hit the same wall. Measured on 0.7.5 today: pane.read reports revision: 0 unconditionally, three reads of an actively changing pane two seconds apart, all 0 while the text grew by 73 characters. The nonzero revision in pane.list does not track content either, a working pane held the same value across 12 seconds while its text changed. So there is nothing to build on today, exactly as you say.

The follow-on: a trustworthy revision fixes detection, but it does not fix writes. My case is a human approving an agent's permission prompt from somewhere else. Read at revision N, push the prompt to a phone, the human decides seconds later, then pane.send_keys. The read and the write are separate RPCs, so the approval can still land on whatever replaced the prompt. Re-reading immediately before writing shrinks the window and cannot close it.

What closes it is an optional precondition on the write, rejected server-side: refuse unless the pane is still at N. That only becomes possible once revisions mean something, which is why I am putting it here rather than opening a competing thread. Worth designing the counter with that in mind, and it would apply to send_text and send_input as well.