Skip to content

[Bug]: un-cursored terminal read reports limited: false and nextCursor === latestCursor while hundreds of transcript lines are withheld (regression from #9081) #12333

Open

Description

@pablontiv

Operating system

macOS

Orca version

Observed on v1.4.164. Source verified at tag v1.4.167 (all line numbers below are v1.4.167).

Details

Short summary

An un-cursored orca terminal read against a full-screen TUI can return two lines while latestCursor is in the hundreds, and report limited: false with nextCursor === latestCursor. Both of those mean "you are caught up", so a caller following the shipped pagination rule stops reading and concludes the terminal produced nothing.

The un-cursored branch returns preview-derived content and flags alongside transcript-derived cursor fields. Those two describe different buffers.

What happened

Reading a stuck agent terminal returned returnedLineCount: 1 with the text 5, while latestCursor was 308. Nothing in the response indicated 307 lines were being withheld. That produced a confident and completely wrong diagnosis — "the agents never started" — and a healthy worker was stopped on the strength of it. Only --cursor 0 --limit 1000 showed the real buffer.

This has now caused the same inverted diagnosis in two independent sessions.

One correction up front

This is not a default-limit problem. DEFAULT_TERMINAL_READ_LIMIT = 120 (src/main/runtime/orca-runtime.ts:33512), applied at :34878. A single-line result is a buffer-selection consequence — slice(-120) of a one-element array is that array. A fix framed as "raise the default limit" would change nothing.

Root cause

The two read modes draw from two different buffers — orca-runtime.ts:15840-15850 (leaf path) and :30103-30113 (live-PTY path), both funnelling into readTerminalTail at :34829:

  • un-cursored → previewLines: leaf.tailBuffer, a rendered-screen model with a live cursor (appendNormalizedToTailBuffer, :34031) that rewrites and deletes rows in place on CUU/EL redraws
  • cursored → completedLines: leaf.tailTranscriptBuffer, a monotonic append-only transcript (appendCompletedTerminalTranscript, :34696) that never rewrites on redraw

latestCursor and oldestCursor are both derived from the transcript (:34840-34841, from tailLinesTotal).

But the un-cursored branch computes its content and its truncation flags against the preview buffer only — :34877-34902:

const allLines = buildTailLines(args.previewLines, args.partialLine)
const lineBoundedTail = allLines.slice(-limit)
...
limited: lineBoundedTail.length < allLines.length || charBoundedTail.limited,
oldestCursor: String(oldestCursor),   // transcript
nextCursor: String(latestCursor),     // transcript

For a TUI redrawing in place, tailBuffer collapses to a couple of rows while tailLinesTotal keeps climbing. Nothing was dropped relative to the preview buffer, so limited stays false; nextCursor is set to latestCursor, so the caller reads as caught up; and truncated is about buffer eviction, not about the preview/transcript gap.

The shipped guide's stop condition collapses exactly here

skill-guides/orca-cli.md:204, embedded verbatim into src/cli/bundled-skill-guides.ts:

For long output, use cursor reads. After a limited tail preview, page from oldestCursor; after a cursor read, continue with nextCursor while limited is true and nextCursor !== latestCursor.

Both documented stop conditions are satisfied simultaneously in the defect case. An agent following the guide exactly stops reading.

The visible-snapshot fallback does not rescue it

shouldFallbackToVisibleTerminalSnapshot (:34905-34918) requires every returned line to be whitespace-only (:34917); a tail with any non-blank content returns false.

Its caller withVisibleSnapshotFallback (:11165-11211) does have extra triggers — knownAlternateScreen (:11182), providerModeUnknown, recoveredWorkerFallback, headlessTerminals (:11190) — so alt-screen TUIs are partially rescued. That does not help here for three reasons:

  1. The failure mode is an in-place-redraw TUI on the normal screen (CUU + EL, no \x1b[?1049h), so knownAlternateScreen is false and none of the extra triggers fire.
  2. Even when the fallback does fire, buildVisibleSnapshotReadFallback (:34924-34942) spreads ...read and overrides only tail, limited, returnedLineCount. nextCursor and latestCursor pass through unchanged, so the "caught up" signal survives.
  3. The substitute is the visible screen (≤ rows), again strictly smaller than the transcript — one under-report swapped for another.

Regression provenance

git log -S "tailTranscriptBuffer" --reverse identifies a single introducing commit: cbdd750f7 — fix(terminal): keep redraw transcript cursors stable (#9081), merged 2026-07-17, one day before #8745 was closed as completed.

+  previewLines: string[]
   completedLines: string[]
...
-  const allLines = buildTailLines(args.completedLines, args.partialLine)
+  const allLines = buildTailLines(args.previewLines, args.partialLine)

Before #9081 there was one buffer, so the un-cursored flags and the cursor fields were at least mutually consistent. #9081 correctly moved the cursored branch onto the new monotonic transcript and deliberately re-pointed the un-cursored branch at the preview buffer — but left oldestCursor, nextCursor and latestCursor transcript-derived. The mixed response shape at :34892-34902 is the direct residue.

This is a regression introduced by the fix for #8745, and it falls outside that issue's own scope (cursored branch).

Why it shipped green

No test performs an un-cursored readTerminal after a CUU redraw and asserts limited / nextCursor. The existing CUU regression tests assert the cursored branch only — orca-runtime.test.ts:16550 (keeps cursor pagination stable across a CUU redraw of the live screen) asserts {cursor: 0} and {cursor: 2}; :16590 asserts {cursor: 0}.

The repo's own fixture at :16550 is enough to reproduce: after the redraw, an un-cursored readTerminal(handle) returns limited: false and nextCursor === latestCursor while tailLinesTotal exceeds returnedLineCount.

Expected

An un-cursored read whose preview covers far fewer lines than latestCursor - oldestCursor should say so — by setting limited, or by adding an explicit field for the preview/transcript gap. nextCursor should not equal latestCursor while unread completed lines exist below the returned window.

Whichever is chosen, the corrected semantics belong in readTerminalTail itself, before any host-specific fallback, so the leaf path, the live-PTY path, SSH/remote and headless hosts all get the same contract. withVisibleSnapshotFallback behaves differently per host (renderer serializer under Electron vs HeadlessEmulator at :11213-11234 vs nothing), so a fix that leans on it would not hold on headless or remote runtimes.

Note that a naive "use the transcript for un-cursored reads too" would revert #9081's intent that an un-cursored read is a live-screen preview, and would break :16550, :16590 and :15466. The signalling is what is wrong, not the choice of buffer.

Actual

returnedLineCount: 1, limited: false, truncated: false, nextCursor === latestCursor === 308. A correctly-paginating caller stops.

Related

Impact

This is what makes a stuck agent look dead rather than stuck. In the sessions above it sent the operator toward re-dispatching — risking double execution — instead of the safe recovery, and in one case a healthy worker was stopped. It also feeds bad evidence into other bug reports: an empty terminal read is routinely cited as proof that an agent produced no output, and on this path it is not.

Activity

  1. pablontiv commented on Aug 3, 2026

    @pablontiv
    Author

    Cross-link: this defect is what made #9976's stuck workers read back as dead rather than stuck. Evidence for that case is in #9976 (comment) — an un-cursored read there returned a single line while 308 transcript lines were buffered, and the resulting "the agents never started" reading sent the diagnosis in the wrong direction for roughly 25 minutes.

    Worth fixing independently of #9976: the two are unrelated in cause, but this one silently corrupts the evidence used to triage the other.

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

Metadata

Metadata

Assignees

Labels

os:macosIssues affecting macOS

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions