Skip to content

fix(terminal): report limited when an un-cursored read withholds transcript lines - #15269

Open
artile wants to merge 1 commit into
stablyai:mainfrom
artile:fix/terminal-read-window-is-honest
Open

artile wants to merge 1 commit into
stablyai:mainfrom
artile:fix/terminal-read-window-is-honest

Conversation

@artile

@artile artile commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Behaviour change

An un-cursored orca terminal read now sets limited: true when the retained transcript holds more completed lines than the response returned. Cursor semantics, the default limit, and which buffer the read draws from are all unchanged.

Fixes #12333.

Evidence

Reproduced on upstream/main against a live pane, using the released CLI:

$ orca terminal send --terminal $H --text "seq 1 20" --enter
$ orca terminal read --terminal $H --json
returned 21  limited False  truncated False  oldest 0  latest 21     # honest

$ orca terminal send --terminal $H --text "seq 1 40 | less" --enter
$ orca terminal read --terminal $H --json
returned 24  limited False  truncated False  oldest 0  latest 61     # withholds 37 lines
tail begins: ['17', '18', '19', '20']

$ orca terminal read --terminal $H --cursor 0 --limit 200 --json
returned 61  limited False  oldest 0  latest 61
tail begins: ['', '1', '2', '3', '4', '5']

The bare read returned 24 of 61 retained lines and reported limited: false with nextCursor === latestCursor. Both of those mean "you are caught up".

The repo's own CUU fixture reproduces the same thing without a live pane. After A\r\nB\r\nC\r\n\x1b[2A\x1b[2K\x1b[1GB2\r\n, an un-cursored read returns 2 rows while latestCursor is 4, and before this change reported limited: false.

Why it matters

This is not a cosmetic flag. skill-guides/orca-cli.md tells callers to keep paging "while limited is true and nextCursor !== latestCursor". On this path both stop conditions are satisfied at once, so a caller following the shipped rule exactly stops reading and concludes the pane produced nothing.

We watched that happen. An agent-driven probe sent echo RDY5 into a pane every four seconds and read the pane back with a bare terminal read --terminal <h> --json. Eighteen probes in a row appeared to execute nothing and the operator concluded the pane was dead for ninety seconds. The pane was fine — a cursor read showed 28 retained lines, 12 of them the RDY5 output the earlier reads had not returned. Two independent agents reached the same wrong diagnosis within an hour, and in both cases the wrong diagnosis came from the tool's response, not from the system under test. #12333 reports the same inversion from a different pair of sessions, where a healthy worker was stopped on the strength of it.

The change

readTerminalTail computes its content and its limited flag against the preview buffer, but derives oldestCursor / nextCursor / latestCursor from the transcript. Those are two different buffers: the preview is a live-screen model that in-place redraws rewrite and delete rows from, while the transcript is monotonic. Nothing was dropped relative to the preview, so limited stayed false while the transcript kept growing.

One added condition in the un-cursored branch of readTerminalTail, plus the --help line that says a bare read is a bounded window.

Per #12333's analysis, this sits in readTerminalTail rather than in withVisibleSnapshotFallback, so the leaf path, the live-PTY path, SSH/remote hosts and headless hosts get the same contract — the fallback behaves differently per host and a fix leaning on it would not hold on headless or remote. It is deliberately the signalling fix only: #12333 also proposes that nextCursor should stop equalling latestCursor while unread lines exist, which changes cursor semantics and belongs in its own PR.

Compatibility

limited is an existing optional boolean on RuntimeTerminalRead; no wire shape changes, so no capability negotiation is needed and mixed client/host versions stay fine. The change is host-independent and platform-independent — no path handling, no provider-specific branches.

The direction of the change is conservative: a caller that ignores limited sees identical output, and a caller that honours it now pages where it previously stopped. The human formatter already renders this as warning: output limited; page retained output with --cursor <n> --limit <count>, so no formatter change was needed.

Adjacent work: #10231 touches alt-screen scrollback restore near withVisibleSnapshotFallback; this PR does not modify that function, so they should not conflict. #7433 asks for the --json result schema in --help — the one help line here names the window and points at limited, but does not document the full schema, so #7433 stays open.

Test plan

Two tests added next to the existing CUU redraw tests in src/main/runtime/orca-runtime.test.ts:

  • an un-cursored read after a CUU redraw returns 2 rows with latestCursor: '4' and now reports limited: true
  • an un-cursored read whose preview covers every retained line still reports limited: false, so the flag does not become noise

Run on this branch:

pnpm vitest run src/main/runtime      258 files passed, 3860 passed | 6 skipped
pnpm vitest run src/cli                58 files passed,  754 passed
pnpm typecheck                         clean
pnpm lint                              clean

The second test fails without the production change; the first fails without it too.


Moved from #13672, same commits, same head SHA. That pull request was opened from an organisation-owned fork, and GitHub refuses maintainer pushes on org-owned forks even when maintainer_can_modify reports true — so a maintainer could not push a fixup to it, only ask or rewrite. This one is on a personal fork, where a maintainer push works.

The review history stays readable on #13672: #13672

…script lines

An un-cursored `terminal read` returns the preview buffer, a live-screen model
that in-place redraws collapse, but it derives `oldestCursor`, `nextCursor` and
`latestCursor` from the append-only transcript. When a TUI redraws, the preview
holds a couple of rows while the transcript keeps growing, and the response
still reports `limited: false` with `nextCursor === latestCursor`. Both mean
"you are caught up", so a caller paginating by the documented rule stops
reading and concludes the terminal produced nothing.

Set `limited` when the retained transcript holds more completed lines than the
response returned. Cursor semantics are unchanged; this only stops the flags
from contradicting the cursors. Also name the window in `terminal read --help`,
which never stated that a bare read is bounded.
@coderabbitai

coderabbitai Bot commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e9c5c1f6-879f-4ade-b109-8db5c94cc9b4

📥 Commits

Reviewing files that changed from the base of the PR and between 545b3fb and cbe1a69.

📒 Files selected for processing (3)
  • src/cli/specs/core.ts
  • src/main/runtime/orca-runtime.test.ts
  • src/main/runtime/orca-runtime.ts

Included review availability: Your plan includes up to 10 reviews per rolling hour; 2 remain after this review.


📝 Walkthrough

Walkthrough

The terminal read specification now documents bounded output, including the default 120-row limit, visible-screen behavior for full-screen TUIs, and the limited indicator. Runtime logic now marks un-cursored reads as limited when retained transcript lines are omitted from the live preview. Tests cover redraws that reduce the preview and reads that include all retained lines.

Merge Risk: ⚪ Minimal · up to cbe1a

The PR corrects the limited-output signal for un-cursored terminal reads so callers can continue paging retained lines; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the terminal read bug and the specific limited-flag fix.
Description check ✅ Passed The description provides the behavior change, rationale, linked issue, implementation scope, compatibility notes, evidence, and test results.
Linked Issues check ✅ Passed The implementation satisfies #12333 by reporting limited transcript output in readTerminalTail without changing preview selection or cursor semantics.
Out of Scope Changes check ✅ Passed The help text and regression tests directly support the linked issue, and no unrelated code changes are identified.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant