ctx.subprocess.spawn() hangs on Windows when the spawned process has its own nested subprocess children (ctx.shell.run works)

[MauricioPerera]

Summary

ctx.subprocess.spawn() (from @deepseek-ai/dsh-subprocess-local) hangs indefinitely — until whatever graceMs/outer timeout kills it — when the spawned process itself spawns further nested subprocesses (grandchildren), on Windows. The identical command run through ctx.shell.run() (the service backing dsh-tool-pwsh/dsh-tool-bash, which also ultimately calls ctx.subprocess.spawn() internally) completes normally.

Repro

Environment: @deepseek-ai/dsh 0.1.1-rc.2, Windows 11, Node v24.16.0.

A profile plugin (Cordis composition entry, inject: ['subprocess']) that does:

const handle = subprocess.spawn({
  argv: [pythonExe, 'scripts/preflight.py'],
  cwd: repoRoot,
  stdio: { stdin: 'ignore', stdout: { maxBytes: 262144 }, stderr: { maxBytes: 131072 } },
  graceMs: 3000,
  signal: exec.signal,
})

— where scripts/preflight.py itself runs ~19 further subprocess calls (each a short-lived python some_gate.py invocation via Python's own subprocess.run) — never completes. It sits until the caller's own outer deadline fires and force-terminates the tree; the direct child (python.exe) shows no forward progress in that time (confirmed via Get-Process -Id <pid> | Select CPU sampled repeatedly: CPU time stops climbing).

The exact same command, run through the agent's own pwsh tool (ctx.shell.resolve({command: 'python scripts\\preflight.py', workdir: repoRoot}) → ctx.shell.run(...)), completes normally — 8.2s wall time — same repo, same working directory, same process tree shape (one parent, ~19 short-lived grandchildren).

Tools with a single level of subprocess (the plugin's own direct child does no further spawning) do not exhibit this — they return normally via ctx.subprocess.spawn() in the same plugin, same session.

What differs between the two paths

Both ctx.subprocess.spawn() (used directly) and ctx.shell.run() (used by dsh-tool-pwsh, via @deepseek-ai/dsh-pwsh-local's PwshLocalExecutor.runArgv) ultimately call the identical spawnSubprocess() in dsh-subprocess-local/lib/index.js — plain child_process.spawn(program, args, {cwd, env, stdio: [...], detached: platform !== "win32"}), no shell, stdout/stderr as anonymous pipes drained via stream.on('data', ...).

The difference I can identify without access to the private path is the invocation shape:

• Hangs: direct argv: [pythonExe, 'scripts/preflight.py'] — no intermediate shell.
• Works: argv: [pwshPath, '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '<preamble><command>'] — pwsh interprets spec.command as script text, which resolves to the same python scripts\preflight.py invocation, but with pwsh itself as the direct child instead of python.

I could not find a second variable that differs; env construction, stdio disposition, and stdin ('ignore' in both) are the same in both call sites' resolved spec. Wrapping the direct call in cmd.exe /d /s /c "python scripts\preflight.py" (still no pwsh) did not fix the hang — so it is not simply "no shell at all" vs "any shell"; something specific to how the eventual python.exe process is parented differs between "direct child of the Node harness process" and "child of a pwsh process that is itself a child of the harness process."

Impact

Any profile-level plugin that wraps a script performing further subprocess calls of its own (a orchestrator/runner pattern — this is common for gate/lint/test-runner scripts) via ctx.subprocess.spawn() directly is affected on Windows. The workaround is to route such calls through ctx.shell.run() instead (inject 'shell'), which is what I did — but that service is intended for dsh-tool-pwsh/dsh-tool-bash's own use, so this may not be the intended public surface for it, and I'm not confident it's meant to be a general substitute for ctx.subprocess.spawn().

Environment

• @deepseek-ai/dsh 0.1.1-rc.2, @deepseek-ai/dsh-subprocess-local (bundled), @deepseek-ai/dsh-pwsh-local (bundled)
• Node.js v24.16.0, Windows 11
• Reproduced consistently across many runs (dozens, over one debugging session) — not intermittent for the "direct spawn + nested children" shape specifically; always hangs. The reverse (via ctx.shell) always completes.

[liyangbing]

I would not treat ctx.shell.run() succeeding as proof that the shell API is the intended general replacement here. It changes the intermediary process, console/handle topology, environment and quoting; the fact that cmd.exe /c still hangs makes a simple “any shell fixes it” explanation unlikely.

The useful first split is:

1. Is the direct Python child still alive when progress stops?
2. Or has it emitted exit while handle.done is waiting for close because a descendant still owns stdout/stderr?
3. After abort, does the direct child disappear while a descendant remains?

The rc.2 local subprocess implementation already bounds case 2: after direct-child exit, collected pipes can delay settlement only for graceMs, then the collected streams are destroyed and done settles. On Windows, however, tree liveness falls back to the direct child and termination is best-effort through taskkill /T /F. I compared current 0.1.2-alpha.1 source as well: the relevant spawn.ts boundary is unchanged, and the grandchild process-group regression test is POSIX-only, so I do not see source evidence that alpha.1 has fixed this Windows workload.

For a disposable reproduction, I would capture this matrix with identical argv/cwd/env/input/deadline:

runner                 stdio               direct exit   close/done   descendant PIDs
python.exe + argv      collected           timestamp     timestamp    states
cmd.exe /d /s /c ...   collected           timestamp     timestamp    states
powershell + command   collected           timestamp     timestamp    states
python.exe + argv      inherit/ignore*     timestamp     timestamp    states

* The last row is diagnostic only. If it releases the run, inspect inherited handles and pipe backpressure in the Python children; it is not a production fix. Also record the last nested-child start/exit and whether each child explicitly consumes/closes stdin/stdout/stderr.

A sufficient upstream Windows test should prove direct parent + multiple grandchildren, collected output preservation, handle.done settlement, timeout/cancel tree termination, and no orphan after grace. Until then, PowerShell can be an explicit trusted-command workaround, but it should stay Windows-specific and must not concatenate model/user input.

I wrote up the source references, decision table, evidence matrix, and acceptance gates here: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/plugin-development/async-subprocess-tools.md#route-a-windows-nested-child-hang-before-changing-executors