Skip to content

fix(terminal): preserve remote alt-screen scrollback on restore - #10231

Closed
rodboev wants to merge 3 commits into
stablyai:mainfrom
rodboev:pr/remote-snapshot-alt-scrollback-parity
Closed

rodboev wants to merge 3 commits into
stablyai:mainfrom
rodboev:pr/remote-snapshot-alt-scrollback-parity

Conversation

@rodboev

@rodboev rodboev commented Jul 23, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Preserve pre-TUI shell scrollback when a remote alternate-screen terminal is hidden and restored.
  • Root cause: the requested remote snapshot path folded scrollback into data and dropped the alt-screen metadata that the renderer restore path already uses locally.
  • Carry requested-snapshot alt-screen metadata through the remote snapshot frame, re-split the folded payload on the multiplexer boundary, and let the renderer take the same scrollback-preserving branch it already uses for local restores. Keep subscribe and mobile snapshot frames unchanged, and preserve the local alt-screen contract when remote scrollback is unavailable.

Closes #6106.

Screenshots

No visual change.

Testing

  • pnpm lint
  • pnpm typecheck
  • pnpm test
  • pnpm build
  • Added or updated high-quality tests that would catch regressions, or explained why tests were not needed

Focused validation to run:

  • pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/rpc/terminal-multiplex-escape-tail.test.ts
  • pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts
  • pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/terminal-pane/pty-connection.test.ts
  • pnpm run typecheck:node
  • pnpm run typecheck:web

Focused validation completed:

  • pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/rpc/terminal-multiplex-escape-tail.test.ts: passed, Test Files 1 passed (1), Tests 2 passed (2).
  • pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts: passed, Test Files 1 passed (1), Tests 15 passed (15).
  • pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/terminal-pane/pty-connection.test.ts: passed, Test Files 1 passed (1), Tests 471 passed (471).
  • pnpm run typecheck:node: passed, tsc --noEmit -p config/tsconfig.node.json.
  • pnpm run typecheck:web: passed, tsc --noEmit -p config/tsconfig.tc.web.json.
  • pnpm exec oxlint src/main/runtime/rpc/methods/terminal.ts src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts src/renderer/src/components/terminal-pane/pty-connection.test.ts src/main/runtime/rpc/terminal-multiplex-escape-tail.test.ts src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts: passed, no diagnostics.
  • pnpm exec oxfmt --check src/main/runtime/rpc/methods/terminal.ts src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts src/renderer/src/components/terminal-pane/pty-connection.test.ts src/main/runtime/rpc/terminal-multiplex-escape-tail.test.ts src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts: passed, All matched files use the correct format.
  • Dependency setup: pnpm install --frozen-lockfile completed successfully before validation.

The generic pnpm lint, pnpm typecheck, pnpm test, and pnpm build commands were not run; their template boxes remain unchecked. The targeted changed-file checks above passed.

Security Audit

This change adds no new auth, filesystem, network, or command surface. It threads metadata through an existing remote terminal snapshot frame and re-splits it in the renderer transport.

Notes

Scope is limited to remote snapshot metadata parity. It does not widen into the broader visible-TUI-output work.

ELI5

Hiding and restoring a remote terminal running a full-screen TUI could drop the shell scrollback from before the TUI. Remote snapshots now carry alt-screen metadata so restore keeps that history like local does.

@coderabbitai

coderabbitai Bot commented Jul 23, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Terminal snapshots now transmit alternate-screen state and scrollback ANSI length. The renderer decodes these fields and separates preserved scrollback from alternate-screen content when resolving snapshot requests. Pane restoration tests cover alternate-screen snapshots with and without preserved scrollback, including terminal escape sequences and snapshot writes. Multiplex and resynchronization tests validate metadata serialization and manual snapshot behavior.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The required AI Review Report section is missing, including the explicit cross-platform compatibility confirmation. Add the AI Review Report with risks reviewed, what was changed or verified, and explicit macOS/Linux/Windows/Electron checks.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The changes add remote alternate-screen metadata, resplit folded snapshot data, and restore preserved scrollback, matching #6106's goal.
Out of Scope Changes check ✅ Passed The diff stays focused on terminal snapshot metadata, restore logic, and regression tests, with no unrelated changes.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check ✅ Passed Clear, concise, and aligned with the main change: preserving remote alternate-screen scrollback on restore.

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.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/main/runtime/rpc/terminal-multiplex-escape-tail.test.ts (1)

145-158: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Mock doesn't model the "folded" payload contract, so the test can't catch a folding regression.

The mock returns data: 'alternate frame' without the scrollbackAnsi: 'history\r\n' prefix concatenated in, yet the assertion only checks the SnapshotStart metadata JSON (alternateScreen, scrollbackAnsiLength), not the actual SnapshotChunk payload bytes. Contrast with remote-runtime-terminal-frame-drop-resync.test.ts's FakeMultiplexServer.setSnapshot, which correctly sets snapshotData to the full concatenated string ('shell history\ralternate frame') to simulate the real wire contract. If the production serializeTerminalBuffer return value is expected to already fold scrollback into data (as the client-side split logic assumes), this test's mock misrepresents that contract and would not fail even if the folding step were broken. Consider aligning the mock's data with the folded contract, or add an assertion against the actual SnapshotChunk payload content.

Also applies to: 248-252


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ebb33b32-381c-4f01-a698-9ab53b244465

📥 Commits

Reviewing files that changed from the base of the PR and between 94d3db4 and c7fdde21346955dd0c428bd7cc717557745087e7.

📒 Files selected for processing (5)
  • src/main/runtime/rpc/methods/terminal.ts
  • src/main/runtime/rpc/terminal-multiplex-escape-tail.test.ts
  • src/renderer/src/components/terminal-pane/pty-connection.test.ts
  • src/renderer/src/runtime/remote-runtime-terminal-frame-drop-resync.test.ts
  • src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts

@rodboev

rodboev commented Sep 5, 2026

Copy link
Copy Markdown
Contributor Author

Current main preserves and prefers alternate-screen scrollback during restore, as carried by merged PR #17952. This PR is superseded on current main.

@rodboev rodboev closed this Sep 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SSH terminal loses pre-TUI shell output after Codex tab restore

3 participants