fix(terminal): reduce tmux session viewport

[serejaris]

• A human has tested these changes.

---

Why

Fixes #2806. The tmux backend currently creates sessions with a 1000x1000 viewport. That gives each detached session a million-cell virtual terminal grid, which the issue reporter traced to high kernel CPU while tmux processes PTY output.

Summary

• Reduce tmux session dimensions from 1000x1000 to 256x200.
• Keep HISTORY_LIMIT unchanged so scrollback retention remains controlled by history, not viewport height.
• Add a regression test that prevents returning to an oversized viewport while preserving scrollback.

Issue Number

Fixes #2806

How to Test

Pre-fix regression proof:

uv run pytest tests/tools/terminal/test_tmux_pane_pool.py::test_tmux_session_viewport_is_smaller_than_scrollback -q

Before the fix, this failed with:

assert 1000 <= 256

Post-fix validation:

uv run pytest tests/tools/terminal/test_tmux_pane_pool.py::test_tmux_session_viewport_is_smaller_than_scrollback -q
# 1 passed

uv run pytest tests/tools/terminal/test_tmux_pane_pool.py tests/tools/terminal/test_observation_truncation.py tests/tools/terminal/test_ps1_corruption.py tests/tools/terminal/test_heredoc_chunked_send.py -q
# 44 passed

uv run pytest tests/tools/terminal -q
# 285 passed, 9 skipped

uv run pre-commit run --files openhands-tools/openhands/tools/terminal/constants.py tests/tools/terminal/test_tmux_pane_pool.py
# Passed: ruff format, ruff lint, pycodestyle, pyright, import dependency rules, tool registration

Manual tmux smoke after the fix:

tmux_size=256x200
session_history-limit 10000

Note: uv run printed an existing warning while parsing pyproject.toml (exclude-newer = "7 days"), but the commands completed successfully.

Video/Screenshots

Not applicable; terminal backend change.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

I did not change the history limit. The fix only reduces the visible tmux viewport size used when creating sessions.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

🟢 Good taste. No code issues found in this small constants/test update.

Leaving this as COMMENT rather than APPROVE because it changes terminal/tmux behavior, which repo guidance treats as eval-sensitive; a human maintainer should decide after any lightweight eval/manual validation.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟡 MEDIUM
  Small, well-scoped terminal backend change, but viewport sizing can affect output wrapping and agent observations.

VERDICT: ✅ Worth merging after human maintainer validation.

Reviewed by an AI agent (OpenHands) on behalf of the user.

---

Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/software-agent-sdk/actions/runs/26501778228

[all-hands-bot]

Good targeted fix for #2806 — shrinking the 1,000,000-cell viewport (1000x1000) to 51,200 cells (256x200) is a clean, minimal change with clear motivation. One substantive concern about the regression test should be addressed before merge; a secondary note on the constants comment is advisory only.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[VascoSch92]

hey @serejaris

thanks for the contribution.

It looks fine to me, but I would like to run an eval just to be sure nothing is breaking ;-).

[github-actions]

Evaluation Triggered

• Trigger: Label 'run-eval-50' on PR fix(terminal): reduce tmux session viewport #3394
• SDK: 241b601
• Eval limit: 50
• Models: claude-sonnet-4-5-20250929

[serejaris]

Follow-up pushed in 3c8eae7 to address the review feedback.

What changed:

• changed the regression from exact-value pinning to a bounded viewport invariant (<= 256x200);
• removed the unrelated HISTORY_LIMIT == 10_000 assertion from the viewport test;
• renamed the test to match the actual invariant;
• added a comment documenting the accepted wrapping trade-off.

Small note: I did not use the suggested TMUX_SESSION_WIDTH * TMUX_SESSION_HEIGHT < HISTORY_LIMIT assertion because with the current intended values it is false (256 * 200 = 51200, while HISTORY_LIMIT = 10000). The test now checks the bounded viewport contract directly.

Validation after rebasing onto the latest fork branch:

uv run pytest tests/tools/terminal/test_tmux_pane_pool.py::test_tmux_session_viewport_is_bounded -q
uv run pre-commit run --files openhands-tools/openhands/tools/terminal/constants.py tests/tools/terminal/test_tmux_pane_pool.py

Both passed locally. uv still prints the existing exclude-newer = "7 days" warning during setup, but the commands complete successfully.