[Bug]: Agent terminal commands inherit server process priority

[primorLee]

Is there an existing issue for the same bug?

• I searched OpenHands/software-agent-sdk; there is no same-repository issue. The original cross-repository report is [Bug]: Agent commands should run with lower priority (higher number) OpenHands#16720.

Bug Description

Agent commands launched through the SDK terminal backends inherit the agent-server process priority. CPU-heavy commands such as parallel Rust compilation can therefore starve the server event loop and make local OpenHands sessions appear locked up.

The upstream reproduction in OpenHands/OpenHands#16720 measured the same priority for the server and terminal commands. A follow-up by an OpenHands member confirmed that the required policy is platform-specific: macOS utility QoS, Linux niceness +10, and Windows Below Normal priority.

Expected Behavior

Terminal-tool child processes should run below the agent server's CPU priority by default, while an explicit terminal environment setting should allow priority-sensitive benchmarks or development servers to retain the parent priority.

Actual Behavior

Run uv run python reproduce_priority.py using the minimal SDK program below. On current main, the child reports normal Windows priority (32) or the same Unix niceness as the parent (0 in a default shell). CPU-heavy child processes consequently compete with the agent server at equal scheduling priority.

Steps to Reproduce

1. Check out OpenHands/software-agent-sdk and run uv sync --dev.
2. Save the minimal code below as reproduce_priority.py.
3. Run uv run python reproduce_priority.py.
4. Start several CPU-heavy commands through the same terminal session and observe that the agent server becomes slow or unresponsive.

Acceptance Criteria

• Linux standalone tmux, pooled tmux, and subprocess terminal children inherit niceness +10 (capped at 19).
• macOS terminal children run with taskpolicy -c utility.
• Windows terminal child commands inherit BELOW_NORMAL_PRIORITY_CLASS.
• OH_TERMINAL_PROCESS_PRIORITY=none preserves the parent priority.
• A restricted terminal PATH, or a Linux image without nice, does not make a previously valid terminal fail to start.

Installation Method

uv sync --dev from a source checkout.

If you selected "Other", please specify

Source checkout.

SDK Version

main, reproduced at dc0c8428438dde13efa422fb456adfb542fd532d.

Version Confirmation

• I confirmed this bug exists on the latest OpenHands SDK main branch before implementing the fix.

Python Version

3.13.15 locally; the scheduling behavior is not Python-version-specific.

Model Name (if applicable)

Not applicable.

Operating System

macOS, Linux, and Windows.

Logs and Error Messages

There is no exception. The failure mode is server starvation under CPU load. The full macOS/Linux throughput and latency measurements are in OpenHands/OpenHands#16720.

Minimal Code Sample

import platform
import tempfile

from openhands.tools.terminal import TerminalAction
from openhands.tools.terminal.terminal import create_terminal_session

command = (
    'python -c "import psutil; print(psutil.Process().nice())"'
    if platform.system() == "Windows"
    else "python -c 'import os; print(os.getpriority(os.PRIO_PROCESS, 0))'"
)

with tempfile.TemporaryDirectory() as work_dir:
    session = create_terminal_session(work_dir=work_dir)
    try:
        session.initialize()
        print(session.execute(TerminalAction(command=command)).text)
    finally:
        session.close()

Screenshots and Additional Context

• Original product issue and benchmark: [Bug]: Agent commands should run with lower priority (higher number) OpenHands#16720
• SDK implementation PR: fix(terminal): lower agent process priority #4573

[github-actions]

✅ ready-for-dev label applied

This issue meets the readiness criteria and is ready for contribution.
A contributor can now open a PR that links this issue (Fixes #<number>).

This is an automated check — no AI was used to generate this comment.

[primorLee]

Could a maintainer apply the bug label? The body passes .github/scripts/check_issue_readiness.py --labels bug, but GitHub silently dropped the label supplied by this non-collaborator account. Once labeled, the readiness workflow can add ready-for-dev for linked draft PR #4573.