OpenHands / OpenHands/software-agent-sdk
[Bug]: ACP subprocess leaf process orphaned on shutdown on POSIX systems
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 539
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 137
Description
Problem Description
On POSIX systems (Linux/macOS), when ACPAgent._shutdown_runtime terminates an ACP subprocess via process.terminate(), it only signals the top PID (e.g. npx). Because the command was spawned without start_new_session=True, deeper descendant processes (such as sh -c -> node -> claude) survive shutdown as orphaned processes reparented to init, consuming memory and file handles indefinitely.
This addresses the gap reported in issue 4901.
Steps to Reproduce
Run OpenHands with an ACP provider on Linux:
uv run python -c "from openhands.sdk.agent.acp_agent import ACPAgent; agent = ACPAgent(acp_command=['npx', '-y', '@agentclientprotocol/claude-agent-acp']); agent.close()"
Actual Behavior
When running uv run python to create and close the ACP agent, leaf descendant processes (node, claude) remain alive in ps -ef after agent.close() completes.
Expected Behavior
Closing the agent tears down the entire spawned process group on POSIX, cleanly terminating all descendant processes.
Acceptance Criteria
-
ACPAgent._start_acp_serverspawns withstart_new_session=Trueon POSIX systems. -
ACPAgent._shutdown_runtimeterminates the entire process group viaos.killpg(pgid, signal.SIGTERM)before waiting and falling back tosignal.SIGKILL. - Orphaned grandchild processes are cleaned up even if the parent PID already exited.
- All unit tests pass under
uv run pytest tests/sdk/agent/test_acp_agent.py.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with ACPAgent._start_acp_server and ACPAgent._shutdown_runtime, then run tests/sdk/agent/test_acp_agent.py. Check the POSIX process-group behavior described in the acceptance criteria and verify that closing the agent terminates descendant processes, including when the parent has already exited; all listed tests should pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend, operating-systems
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 75/100