Improve Orca CLI terminal read pagination (#2553)

Co-authored-by: Orca <help@stably.ai>

src/cli/format.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { RuntimeRpcFailureError } from './runtime-client'
-import { formatCliError, formatWorktreeList } from './format'
+import { formatCliError, formatTerminalRead, formatWorktreeList } from './format'
 import type { RuntimeWorktreeRecord } from '../shared/runtime-types'
 
 function worktree(overrides: Partial<RuntimeWorktreeRecord> = {}): RuntimeWorktreeRecord {
@@ -89,3 +89,43 @@ describe('formatWorktreeList', () => {
     expect(output).toContain('childWorktreeIds: []')
   })
 })
+
+describe('formatTerminalRead', () => {
+  it('prints cursor metadata and limit warnings when the runtime returns them', () => {
+    const output = formatTerminalRead({
+      terminal: {
+        handle: 'term_1',
+        status: 'running',
+        tail: ['line 1'],
+        truncated: false,
+        limited: true,
+        oldestCursor: '0',
+        nextCursor: '50',
+        latestCursor: '150',
+        returnedLineCount: 1
+      }
+    })
+
+    expect(output).toContain('cursor: 50')
+    expect(output).toContain('oldest cursor: 0')
+    expect(output).toContain('latest cursor: 150')
+    expect(output).toContain('warning: output limited; read again with the returned cursor')
+  })
+
+  it('keeps older runtime read responses readable', () => {
+    const output = formatTerminalRead({
+      terminal: {
+        handle: 'term_1',
+        status: 'running',
+        tail: ['old server output'],
+        truncated: true,
+        nextCursor: '12'
+      }
+    })
+
+    expect(output).toContain('cursor: 12')
+    expect(output).toContain('warning: older output is no longer retained')
+    expect(output).toContain('old server output')
+    expect(output).not.toContain('undefined')
+  })
+})

src/cli/format.ts

@@ -174,10 +174,18 @@ export function formatTerminalShow(result: { terminal: RuntimeTerminalShow }): s
 
 export function formatTerminalRead(result: { terminal: RuntimeTerminalRead }): string {
   const terminal = result.terminal
+  const oldestCursor =
+    typeof terminal.oldestCursor === 'string' ? [`oldest cursor: ${terminal.oldestCursor}`] : []
+  const latestCursor =
+    typeof terminal.latestCursor === 'string' ? [`latest cursor: ${terminal.latestCursor}`] : []
   const header = [
     `handle: ${terminal.handle}`,
     `status: ${terminal.status}`,
-    ...(terminal.nextCursor !== null ? [`cursor: ${terminal.nextCursor}`] : [])
+    ...(terminal.nextCursor !== null ? [`cursor: ${terminal.nextCursor}`] : []),
+    ...oldestCursor,
+    ...latestCursor,
+    ...(terminal.truncated ? ['warning: older output is no longer retained'] : []),
+    ...(terminal.limited ? ['warning: output limited; read again with the returned cursor'] : [])
   ]
   return [...header, '', ...terminal.tail].join('\n')
 }

src/cli/handlers/terminal.ts

@@ -75,7 +75,8 @@ export const TERMINAL_HANDLERS: Record<string, CommandHandler> = {
     }
     const result = await client.call<{ terminal: RuntimeTerminalRead }>('terminal.read', {
       terminal: await getTerminalHandle(flags, cwd, client),
-      ...(cursor !== undefined ? { cursor } : {})
+      ...(cursor !== undefined ? { cursor } : {}),
+      limit: getOptionalPositiveIntegerFlag(flags, 'limit')
     })
     printResult(result, json, formatTerminalRead)
   },

src/cli/help.ts

@@ -169,7 +169,7 @@ Common Commands:
   orca worktree ps [--limit <n>] [--json]
   orca terminal list [--worktree <selector>] [--limit <n>] [--json]
   orca terminal show [--terminal <handle>] [--json]
-  orca terminal read [--terminal <handle>] [--json]
+  orca terminal read [--terminal <handle>] [--cursor <n>] [--limit <n>] [--json]
   orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--json]
   orca terminal wait [--terminal <handle>] --for exit|tui-idle [--timeout-ms <ms>] [--json]
   orca terminal stop --worktree <selector> [--json]

src/cli/specs/core.ts

@@ -162,16 +162,17 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [
   {
     path: ['terminal', 'read'],
     summary: 'Read bounded terminal output',
-    usage: 'orca terminal read [--terminal <handle>] [--cursor <n>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'terminal', 'cursor'],
+    usage: 'orca terminal read [--terminal <handle>] [--cursor <n>] [--limit <n>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'terminal', 'cursor', 'limit'],
     notes: [
       'Omit --terminal to target the active terminal in the current worktree.',
       'Use --cursor with the nextCursor value from a previous read to get only new output since that read.',
+      'Use --limit to request more retained lines for long agent responses; output reports oldestCursor when older lines were dropped.',
       'Useful for capturing the response to a command: read before sending, then read --cursor <prev> after waiting.'
     ],
     examples: [
       'orca terminal read --json',
-      'orca terminal read --terminal term_abc123 --cursor 42 --json'
+      'orca terminal read --terminal term_abc123 --cursor 42 --limit 1000 --json'
     ]
   },
   {