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.

[0cv]

I maintain https://github.com/0cv/herdr-mobile-relay which lets users control Herdr agents from a phone. Terminal output currently requires repeated pane.read calls, producing up to several seconds of visible delay or wasteful polling.

A fixed output revision and pane_output_changed events would let us get sub seconds update.

Strong support for this proposal from a real client integration.

[thomaswitt]

Third integrator here with the same problem, arriving from a slightly different angle — I think the ask is one step wider than a change signal.

I run an unattended supervisor around a coding agent. It has to notice one-shot things in the agent's output: a login prompt, a rate-limit message, a crash banner. Each of those is an edge, not a state — reacting twice tears down a healthy worker, and missing one leaves a dead worker reported healthy. On tmux this is boring: pipe-pane tees the pane to a file and I keep a byte offset. Each poll reads exactly what arrived since last time, once.

I can't express that against pane.read. It hands back a window with no position, so two polls overlap and I have to guess which part I already handled, and if more arrives between polls than the window holds, the event is simply gone and nothing tells me so. truncated doesn't help — it only reports that my own lines cap clipped the result, so "nothing happened" and "I went blind" look identical. The other surfaces don't close it either: wait_for_output matches what's already on screen, so a stale line from a previous run re-fires; pane.output_matched latches on false→true, so a catch-all pattern fires once and then never again; and events.subscribe events carry no id to resume from.

So a revision that moves — the ask in this thread — is necessary but not sufficient for me. It tells me that something changed; I still can't get what changed. What I actually need is one of:

• a way to ask for output after a position I hand back ("everything since N"), with an
  explicit signal when you can't serve from there because it aged out; or
• an opt-in durable per-pane transcript on disk that I hold my own offset into — which is what
  Per-pane session recording + replay #908 proposed at the PTY tap point, and is the shape I'd personally bet on. It needs no new socket method and no commitment that the grid or the revision semantics become API.

Two measurements worth adding to the thread, because together they changed my mind about which of those two matters.

First: for a full-screen agent, reads cap at the viewport (54 rows here, at lines: 100000, max_offset_from_bottom: 0) and the evicted rows never reach scrollback. And format: "ansi" gives back a re-serialisation of the cell grid — 102 SGR sequences, zero OSC — so signals that aren't cell data can't survive a read at any format.

Second, and this is the one I'd flag: herdr terminal session observe already does most of what this thread asks for. On a throwaway server it streams NDJSON frames with a monotonic seq, full: true on the first frame and deltas after. So the sequencing machinery exists — the ask isn't "build sequencing", it's "sequence something append-only". Because those are frames, they coalesce: I ran a generator emitting 200 numbered lines, 200 OSC titles and a 5,000-char newline-free run into a 23-row pane, and got 5 frames — 0 of the 200 lines, 0 of the 200 titles, and none of the long run survived. Only the last line still on screen came through. Which is the same shape as pane.read, just streamed.

That's why I lean toward the transcript rather than a read-side parameter: both existing output surfaces are projections of the grid, so no parameter on either can return bytes the grid never kept.

Related threads for whoever picks this up: #2577 (a CLI verb for the event stream), #908 (per-pane recording and replay), #1270 (subscribe replay semantics — a resumable position would settle that one too).

Happy to test anything against a long-running unattended workload; that's the case where the duplicate-vs-dropped distinction actually bites.