OpenHands / OpenHands/software-agent-sdk

[Bug]: ACP subprocess leaf process orphaned on shutdown on POSIX systems

Open
#4,910 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

acp bug priority:medium ready-for-dev
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_server spawns with start_new_session=True on POSIX systems.
  • ACPAgent._shutdown_runtime terminates the entire process group via os.killpg(pgid, signal.SIGTERM) before waiting and falling back to signal.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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.