[digit50]

Motivation & Context

closes #9482

With LocalShellTool(mode="stateless"), a timed-out command that left a background job holding stdout or stderr did not return until that job exited on its own. kill_process_tree returned early when the shell had already exited (sleep 6 &), and the psutil walk missed double-forked jobs that were reparented away from the shell, so neither was signalled and the unbounded drain in run_stateless waited for them.

Description & Review Guide

• What are the major changes?
  • kill_process_tree on POSIX now signals the process group with os.killpg(proc.pid, ...), SIGTERM first and SIGKILL after the grace period, even when the shell has already exited. The shell is started with start_new_session=True, so its pid is the group id, and that still holds after the shell has been reaped, when os.getpgid(proc.pid) would fail.
  • The psutil descendant walk is kept and still runs while the shell is alive, so a child that moved to its own session is still killed. The stdlib fallback uses the same group signalling.
  • The grace wait now also waits for the rest of the process group to exit before escalating to SIGKILL.
  • The output drain after a timeout in run_stateless is bounded, so a process that left the session and still holds the pipes cannot block the call.
  • Windows behaviour is unchanged.
• What is the impact of these changes? A stateless call that times out now returns shortly after the timeout with timed_out=True, and background and double-forked jobs started by the command are killed.
• What do you want reviewers to focus on? The group wait in _wait_for_exit, which polls os.killpg(pgid, 0) because a process group has no handle to await.

Tests:

• test_stateless_timeout_kills_background_jobs_holding_pipes (Linux only) runs sleep 5 & echo $! > <pidfile> and (sleep 5 & echo $! > <pidfile>); sleep 30 with timeout=0.5 and checks that each call returns within two seconds with timed_out=True and that the recorded background pid is gone. Both cases took 5.0 s and failed before the change.
• test_kill_via_psutil_signals_process_group_after_shell_exited checks that the group is signalled for a shell that has already exited.
• The existing killtree unit tests now mock os.killpg, and the stdlib test expects the group id to be the pid.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix); a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Abandoned drains retain pipe descriptors, and zombie-only groups unnecessarily consume the full grace period.

2 open issues

• Close abandoned pipe transports after drain timeout · New
• Ignore zombie-only process groups during grace wait · New

What changed in this PR

Addresses #9482 by improving stateless shell timeout cleanup for background jobs.

Changes:

• Signals POSIX process groups even after the shell exits.
• Bounds output draining after timeout cleanup.
• Adds background-job regression tests and updates termination tests.

File	Description
python/​packages/​tools/​tests/​test_shell_killtree.py	Tests process-group signalling after shell exit.
python/​packages/​tools/​tests/​test_local_shell_tool.py	Adds background-job timeout regressions.
python/​packages/​tools/​agent_framework_tools/​shell/​_killtree.py	Adds group signalling and grace-period polling.
python/​packages/​tools/​agent_framework_tools/​shell/​_executor.py	Limits post-timeout output draining.

_{Review effort: Balanced}

[Eduard van Valkenburg (eavanvalkenburg)]

The timeout cleanup now signals the POSIX process group after leader exit, preserves descendant termination, bounds abandoned pipe drains, closes their transports, and avoids zombie-only grace delays. The Linux regressions cover the critical lifecycle cases.