Per-pane session recording + replay

[AnandSundar]

First-time contributor here, working through your contribution flow per CONTRIBUTING.md.

The thing I keep reaching for in herdr: durable recording of what an agent did in a pane, so I can play it back after it exits or wanders off-course. tmux scrollback is lossy and dies with the session; herdr currently has nothing equivalent.

I had in mind splitting this into 2-3 narrow PRs, scoped like this:

PR 1 — server-side recording (foundation)

• Config-driven opt-in toggle (default off), per pane
• Recorder taps PTY output from the existing actor pattern in src/pty/actor/; writes happen off the PTY hot path so live-display latency is unchanged
• Append-only line-delimited JSON, schema-versioned first line
• Rotation cap (configurable, default 100MB) with atomic segment rename
• New src/persist/recording/ module; no new top-level dependencies

PR 2 — replay surface

• herdr replay <pane-id> and herdr recording list CLI subcommands
• JSON API endpoints under src/api/recordings.rs
• Schema addition to docs/next/api/herdr-api.schema.json
• Reader does mmap past ~10MB; round-trip integration test in tests/recording_roundtrip.rs

PR 3 — TUI scrubber

• Modal reusing the existing UI pattern (the ?-bindings help is my reference)
• ctrl+b then r to open; arrows to scrub, enter to seek; click-drag on the timeline
• Pure presentation state in src/app/state.rs; server-runtime stays clean per your runtime/client boundary in AGENTS.md

Alignment
Sits next to src/agent_resume.rs — recording is the runtime-level layer the metadata layer orchestrates. The vendored libghostty-vt is reused for replay rendering, no parallel parser.

Test surface
Just just check and just ci. No new deps. Unit tests next to the new code, integration test in tests/recording_roundtrip.rs. Round-trip + replay-fidelity tests cover the new behavior.

Two open questions to start:

1. Default rotation cap — 100MB OK, or smaller?
2. Storage path — happy with ~/.local/share/herdr/recordings/<pane-id>/ (XDG) or do you have a per-platform convention?

(I'll save the input-vs-output and PR-split-vs-single questions for after you signal this lands.)

If this is something you'd accept, I'll go through your approval flow per CONTRIBUTING.md.

— AnandSundar

[thomaswitt]

Adding a concrete consumer for this, with a use case that only the PR 1 half solves — recording at the PTY tap, before the parser. Putting the measurements here because they say something specific about where the tap has to be, and because I don't think the read-side APIs can be extended to cover it.

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 / and act on each exactly once. On tmux that's pipe-pane to a file plus a byte offset: every poll reads exactly the bytes that arrived since the last one, once. That's the primitive this proposal would give me, and it's why I care about "durable" more than about "replay".

Measured on 0.8.0 (protocol 19, schema_version 1) against an isolated server, in case it helps scope PR 1:

• Reads are viewport-bounded for a full-screen agent. All four sources (visible, recent,
  recent_unwrapped, detection) returned 54 rows at lines: 100000 — exactly viewport_rows, with max_offset_from_bottom: 0. The agent paints on the alternate screen, so evicted rows never reach host scrollback. Anything that scrolled past while I wasn't looking is gone, and one iteration of my loop legitimately takes ≥59s.
• What comes back is a re-serialisation of the cell grid, not the byte stream: format: "ansi"
  gave 102 SGR sequences and zero CHA/CUP/EL/ED/OSC on the same pane. So an ESC]0;…BEL title — the one structured, unambiguous signal the agent emits — cannot survive a read at any format.
• truncated reports only that my own lines cap clipped the result (true at 1/5/50, false
  at 200/100000), so "nothing happened" and "I went blind" are indistinguishable.

Which is the argument for your tap point being the load-bearing decision in PR 1, more than the storage format: the PTY actor is the only place where bytes still exist. A recorder fed from the grid would inherit all three limits above and be no better than pane.read with a longer memory.

Two asks from the consumer side, both cheap, both about being able to trust the file:

1. Make loss explicit, in-stream. If rotation drops a segment, or the recorder sheds under
   backpressure, I'd like a record saying so rather than a gap I have to infer. A reader holding an offset can handle "you lost N bytes here" — fail closed, re-sync, escalate. It cannot handle silence that might equally mean nothing happened. That's the one property no current surface gives me, and the one I'd trade features for.
2. Output alone is enough for me. Input capture is useful for auditing, but leaving it out of
   PR 1 also sidesteps the "does this file contain what the human typed, including a pasted secret" question. If it does land later, an opt-in separate from output would let me keep it off.

On your two open questions, for what one data point is worth: 100MB is generous for my case (a day of one agent's output is single-digit MB), and I'd take a smaller default with the rotation marker over a larger one without it. ~/.local/share/herdr/recordings/<pane-id>/ is exactly where I'd look for it.

One scoping note that might help this land: PR 1 is fully useful on its own to programmatic consumers. herdr replay and the TUI scrubber serve a human watching a pane; nothing in my case needs either. If the split is a review-cost question, the foundation is the piece with the users waiting on it.

Related threads, since they keep converging on this one: #1277 (race-free change detection — a moving revision tells you that something changed; this is the only proposal that gives you what), #1270 (subscribe replay semantics), #2577 (a CLI verb for the event stream).

Happy to run a build of PR 1 against a 24/7 workload and report back specifically on rotation and the loss path — those only misbehave after days, which is awkward to cover in a round-trip test.