bash tool hangs when command spawns background child processes

[tidyinfo]

Bug Description

The bash tool hangs indefinitely (until the default 2-minute timeout kicks in) when a command spawns a background child process, such as:

• npm run build &
• nohup some_cmd &
• bash -c "sleep 10 &"

During the hang, the session appears completely stuck and the LLM cannot proceed.

Root Cause

In packages/opencode/src/effect/cross-spawn-spawner.ts, the spawner uses the close event to determine when a process has finished:

proc.on("close", (...args) => {
  Deferred.doneUnsafe(signal, Exit.succeed(exit ?? args))
})

Node.js fires close only after all stdio streams are closed. When a shell spawns a background child (e.g., bash -c "sleep 10 &"), the child inherits stdout/stderr pipe file descriptors. The shell process exits immediately, but close won't fire until the background process also exits and releases those pipes.

I verified this behavior:

Command	exit fires	close fires
echo hello	1ms	1ms
bash -c "sleep 10 &"	1ms	10004ms
bash -c "nohup sleep 10 >/dev/null 2>&1 &"	2ms	7ms

For a long-running daemon, close would never fire at all.

Proposed Fix

Replace close with exit as the completion signal in the spawn callback. The exit event fires as soon as the spawned process terminates, regardless of inherited pipe descriptors.

Environment

• opencode version: latest (dev branch)
• OS: Linux (WSL2) / Windows
• Node.js / Bun: both affected

[earlzero]

I've been having the same issue on fresh install of opencode and though there is a bug, but didn't dig deep into it. Thank you for finding and filing it!

[RatmmmhSquishyRat]

still have this bug today.

[JohnXu22786]

Please finish it ASAP! I really need this function.

[markuspace]

Hey, I've been hitting this bug hard and have some real data that confirms what's been diagnosed.

The Numbers

I queried the OpenCode SQLite database for bash tool calls and holy shit:

• 9,475 total bash calls
• 145 times I had to manually interrupt because the tool got stuck
• 28 zombie calls still "running" — they never completed, never timed out, just stuck forever
• 1.5% of ALL bash calls required me to hit escape

That's not a minor inconvenience. That's me rescuing this thing 100+ times.

The Zombies

The 28 still-running calls are the real proof. From the database:

• llama-server backgrounded — still running
• node server.js backgrounded — still running
• WebSocket servers — still running
• Inline node scripts WITH timeout — STILL running

Even &, nohup, and disown don't help. The timeout catches some cases but not all. These are just... stuck.

What's Actually Happening

The close vs exit diagnosis is right — that's the core. But there's a second layer making it worse.

In bash.ts, the run function forks a stream reader on handle.all (combined stdout+stderr) using Effect.forkScoped. When the process exits, the Effect scope won't close until that stream fiber completes. But the stream won't complete because child processes are still holding the file descriptors open. So even after handle.kill(), the scope sits there waiting for a stream that'll never close.

Two bugs, one hang.

The Fix (Two Parts)

1. Spawner — swap close for exit like already proposed. Process exits = done, regardless of FDs.

2. Bash tool — once the process is dead, stop waiting for the stream. The stream fiber blocks scope cleanup for no good reason — it's just for live-updating metadata. Losing the last few bytes on kill is totally fine. Could use forkDaemon instead of forkScoped so it doesn't block cleanup.

Also: detached: process.platform !== "win32" creates process group leaders, but when killGroup fails it falls back to killOne which only kills the parent. Orphans keep the FDs open. That's how we get zombies.

Reproduce It Yourself

Run this against your own database:

SELECT json_extract(data, '$.state.input.command'), json_extract(data, '$.state.status')
FROM part
WHERE json_extract(data, '$.type') = 'tool'
  AND json_extract(data, '$.tool') = 'bash'
  AND json_extract(data, '$.state.status') = 'running'
ORDER BY id DESC;

Those are your zombies. Let's kill them.

[earlzero]

I tried to use "exit" like suggested and found out that after 2 minutes forked processes end up being killed.

When I was looking around I stumbled upon #14769 which seems to be related.

[Corosauce]

I suspect this issue is triggered by gradle as well, when it uses the daemon. Previously recal having to kill multiple java processes each taking up over a GB of system ram and right now after hitting the issue a few times again, I can see 4 java processes, 3 of them taking 1-1.5GB. In gradles case the suggested (by AI) solution is to use --no-daemon, but with a pile of projects not already configured to use this, mixing --no-daemon and daemon commands accidentally results in lock file collisions, so its a whole mess.

Issue reproduced in:
1.4.8
1.4.0
1.3.17

I think the issue will produce on the first bash of a session, but if i cancel and tell it to continue, the rest of the session goes ok, a possible predictable pattern to work with.

[mcdays94]

Confirming this same root cause manifests at a different surface — long-lived stdio MCP servers, not just bash-tool-spawned background children.

Reproducer (minimal): in opencode.json, configure any stdio MCP that keeps its process alive past tool-call return. We hit it with @modelcontextprotocol/server-everything:

{
  "mcp_servers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

Run a normal task that invokes one of the MCP's tools (e.g. everything_echo). The tool call succeeds and the agent prints its summary — but the parent opencode process never exits, because cross-spawn-spawner.ts's close listener still has open inherited stdio pipes from the npx → server-everything child.

Same diagnosis as the original bug body — close waits for stdio descriptors to release; the daemon keeps them alive forever; close never fires.

Symptom in our setup: opencode runs to logical completion (final commit pushed, message printed) at +137s. State stays "running" indefinitely; we observed 7+ minutes before manually killing. The MCP wiring itself is fine — tool calls, prompts, schema all work.

I see @earlzero tried the exit-event fix and found forked processes get killed at 2 min. For the MCP-cleanup case specifically, an explicit MCPServer.close() (per the MCP spec's transport teardown) on session end might be a more targeted fix than swapping the spawner event — closing the JSON-RPC channel should signal the server to exit normally, releasing its stdio.

Tracking from our side at mcdays94/twelve-angry-agents#9 for anyone wanting to follow the MCP angle. Happy to test any candidate fix against our reproducer.