pane read --lines has an undocumented hard cap of 1000 lines (confirmed unchanged in 0.8.0)

[daviddwlee84]

What I'm seeing

herdr pane read --source recent --lines N appears to have a hard, undocumented ceiling of 1000 lines per call — any N above 1000 still returns exactly 1000 lines, and there's no offset/pagination flag to reach further back.

Reproduction

$ herdr pane run <pane> "clear; seq 1 3000"
$ herdr pane get <pane> | jq .result.pane.scroll.max_offset_from_bottom
2956

$ for n in 80 500 1000 1900 2956 5000; do
    echo -n "--lines $n -> "
    herdr pane read <pane> --source recent --format text --lines "$n" | wc -l
  done
--lines 80   -> 80
--lines 500  -> 500
--lines 1000 -> 1000
--lines 1900 -> 1000
--lines 2956 -> 1000
--lines 5000 -> 1000

Confirmed on both 0.7.5 and 0.8.0 (stable) — same cap, unchanged by the 0.8.0 upgrade.

Where I looked for this being documented

• herdr.dev/docs/agent-automation — documents the 80-line default when --lines is omitted, but no maximum.
• herdr.dev/docs/socket-api and herdr.dev/docs/cli-reference — no mention of a cap either.
• herdr api schema --json — PaneReadParams.properties.lines is declared as integer|null, minimum: 0, with no maximum.

So as far as I can tell this cap exists but isn't documented anywhere, and there's no way to page past it to reach earlier scrollback in a single pane.

Why I care

I built a small wrapper script that copies a pane's full scrollback to the clipboard on a keybind. Without an explicit --lines, it silently fell back to the 80-line default (that part's my bug, and it's documented — my fault for not reading closely). But once I fixed that to pass a large --lines, I discovered the real ceiling is 1000, not "however much the pane retains." For a pane with a few thousand lines of retained scrollback, that means only the most recent ~1000 lines are ever reachable via pane read.

Question

Is the 1000-line cap intentional (e.g. a deliberate protection against huge single-call payloads)? If so:

• Could it be documented alongside the 80-line default in the agent-automation docs?
• Is there (or could there be) a way to page through scrollback beyond the most recent 1000 lines — an --offset/--before style flag, similar in spirit to how herdr's own TUI can scroll back further than that?

Related but distinct issues I found while searching, for context: #1717 (truncated: false was dishonest — fixed in 0.8.0, though that flag is only in the raw socket-API JSON response, not surfaced through pane read's CLI text output) and #1718 (alt-screen TUI panes losing scrollback — different root cause, closed as expected behavior).

Environment: herdr 0.8.0 (stable channel), Ubuntu 24.04, pane read --format text.