Debug session stop leaves orphaned child processes running on Unix and Windows

Direct Answer

The debugger should use platform-owned containment boundaries rather than signaling a single PID. On Unix, launch the debuggee in a dedicated process group (or session) and signal the group with kill(-pgid, sig). On Windows, place the debuggee in a Job Object with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE so the OS terminates all associated processes when the job handle closes. Both approaches require the IDE or its debug adapter to create the boundary at launch, not after the fact.

A configurable "force kill tree" option is reasonable as an explicit, staged escalation: normal Stop sends graceful signals (SIGINT/SIGTERM on Unix, CTRL_BREAK_EVENT or job termination on Windows) to the containment boundary; after a configurable grace period (e.g., 2–5 seconds), force kill enumerates descendants and sends SIGKILL/TerminateProcess deepest-first. Do not make force kill the default—it bypasses cleanup handlers and can corrupt state.

For remote sessions, the server-side wrapper (the process that launches the debuggee on the remote host) must own the containment boundary. The IDE sends a termination command over the debug channel; the wrapper then signals its group/job. Heartbeat timeouts should trigger the same server-side cleanup if the client disconnects ungracefully.

Why Orphans Occur

Stop reaches only the process pydevd is attached to. Children survive when they:

• Call os.setsid() or subprocess.Popen(..., start_new_session=True) on Unix, moving to a new session/PGID.
• Ignore SIGINT/SIGTERM (common in daemons or workers with custom signal handlers).
• On Windows, are created with CREATE_NEW_PROCESS_GROUP or BREAKAWAY_FROM_JOB, preventing job association.

The IDE does not currently track the full process tree, so detached children fall outside the signaled boundary.

Platform-Specific Mechanisms

Unix (Linux/macOS)

1. At launch, the debugger (or its launcher script) calls setpgid(0,0) or setsid() to create a new process group/session for the debuggee.
2. Stop sends kill(-pgid, SIGINT) then kill(-pgid, SIGTERM) after a short delay.
3. If children have escaped the group (different PGID/SID), enumerate the tree via /proc//status (PPid) or ps -o pid,ppid,pgid,sid from the debuggee root, then signal deepest descendants first.

Windows

1. At launch, create a Job Object with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE and assign the debuggee process.
2. Stop closes the job handle (or calls TerminateJobObject), which the OS propagates to all processes in the job.
3. For processes that broke away or are in another non-breakable job, enumerate via CreateToolhelp32Snapshot / Win32_Process ParentProcessId and call TerminateProcess on descendants deepest-first.

Remote Debug Cleanup

The remote debug server (or a small wrapper script) must create the containment boundary on the server machine. The IDE sends a structured "terminate" request over the debug protocol; the server signals its group/job. Implement a heartbeat: if the client misses N heartbeats, the server treats it as a disconnect and cleans up its tree. Do not rely on SSH/Docker exec teardown—SIGHUP may be ignored and container PID 1 semantics differ.

Verification Steps

Reproduce locally with a test script that spawns a detached child:

# Unix test
import os, time
if os.fork() == 0:
    os.setsid()  # escapes parent PGID
    time.sleep(300)
else:
    time.sleep(300)

Debug it, press Stop, then run:

ps -o pid,ppid,pgid,sid,stat,cmd | grep -E 'sleep|python'

On Windows, spawn a child with CREATE_NEW_PROCESS_GROUP, Stop, then check:

wmic process where "ParentProcessId=%DEBUGGEE_PID%" get ProcessId,CommandLine

For remote, disconnect the IDE while the child runs, wait for the heartbeat timeout, then inspect server-side ps or tasklist.

Missing Diagnostic Detail

Are your child processes created with explicit detachment (start_new_session=True, setsid(), CREATE_NEW_PROCESS_GROUP, or BREAKAWAY_FROM_JOB)? If yes, group/job signaling alone is insufficient and tree enumeration becomes necessary. If no, the containment boundary should catch them.

Assumptions and Uncertainty

• PyCharm/pydevd version and run configuration (local, remote, Docker, WSL) affect whether a launcher script or the IDE itself creates the process. Behavior varies across versions (tested conceptually against 2023.3+).
• Windows Job Object assignment requires the debuggee not already be in a non-breakable job; some runtimes (e.g., certain test runners) may pre-assign jobs.
• PID reuse races are possible during tree enumeration; re-validate parent/child relationships immediately before termination.
• Cooperative fallback (inherited pipe/FD that children monitor) can catch detached grandchildren but requires application changes and should not be the sole mechanism.