fix(sandbox): stop blocking bash commands (e.g. servers) from hanging the turn

[hetaoBackend]

Problem

Starting a server through the host bash tool — e.g. python -m http.server — could hang the entire turn for the full 600s timeout.

LocalSandbox.execute_command ran commands via subprocess.run(capture_output=True, timeout=600). The captured stdout/stderr pipes are inherited by every process the command spawns, so:

• A backgrounded long-lived process (server &) keeps the read end open → communicate() blocks until the timeout fires, even though the foreground command already returned and the user correctly backgrounded it.
• A command that reads stdin (read x) blocked until the timeout because stdin was inherited rather than /dev/null.
• On timeout, only the direct child was killed, leaving orphaned process groups (the server kept running).

Fix

1. Code (execute_command, POSIX path). Run commands with stdin from /dev/null, a dedicated session/process group, and bounded pipe-drain capture:

Scenario	Before	After
server > log 2>&1 & (backgrounded)	hangs 600s	returns immediately, server keeps running
server & without redirect	hangs 600s	returns immediately; output is drained with bounded capture so it does not grow anonymous temp files
server (foreground, no &)	hangs 600s, then a generic error	bounded by timeout, whole group killed, clear notice to background long-lived processes
read x (reads stdin)	blocks to timeout	returns immediately (EOF)

The wall-clock timeout is configurable via sandbox.bash_command_timeout (default 600, unchanged default behavior). Timeout notices now format fractional/singular values correctly.

2. Windows timeout path. Windows still uses the existing subprocess.run(...) call shape, but TimeoutExpired is now caught so lowered bash_command_timeout values produce the same explanatory timeout notice instead of bubbling into the generic unexpected-error path.

3. Prompt/docs. The bash tool description still instructs the model to background long-lived processes (e.g. servers) with output redirected, so logs stay inspectable and the tool returns immediately. README.md, backend/AGENTS.md, and config.example.yaml describe the timeout/backgrounding behavior.

Tests

• backend/tests/test_local_sandbox_command_timeout.py covers backgrounded prompt return, unredirected background stdout not inheriting deleted temp capture on Linux, foreground timeout notice, whole-process-group kill, stdin EOF, ordinary stdout/stderr/exit-code behavior, config default, bash-tool guidance, Windows TimeoutExpired, and fractional/singular timeout wording.
• Updated backend/tests/test_local_sandbox_provider_mounts.py for the Popen-based path.
• Local verification:
  • cd backend && make format
  • cd backend && make lint
  • cd backend && PYTHONPATH=. uv run pytest tests/test_local_sandbox_command_timeout.py tests/test_local_sandbox_provider_mounts.py tests/test_local_sandbox_encoding.py tests/test_local_sandbox_virtual_path_contract.py -q
  • cd backend && make test → 5199 passed, 20 skipped

Docs

Updated README.md, backend/AGENTS.md, and config.example.yaml.

🤖 Generated with Claude Code

[willem-bd]

Solid fix for the pipe-inheritance hang — temp-file capture + start_new_session + group kill is the right shape for POSIX. Three inline notes below, the first (silent /tmp leak for un-redirected backgrounded processes) is the one I'd most want discussed before merge since it sits on the PR's headline use case.

[willem-bd]

Heads-up on a latent leak: these temp files are dup2'd into the child's fd 1/2, so a backgrounded process (python -m http.server &) inherits them. tempfile.TemporaryFile() on POSIX is anonymous (mkstemp + immediate unlink), so when the surrounding with block closes, the parent's fd is dropped but the background process still holds its dup — every byte it writes thereafter lands in an unnamed /tmp inode that can't be read, truncated, or discovered until the process exits.

That's a silent, unbounded disk leak on exactly the long-running-background case this PR enables, whenever the model omits the > log 2>&1 redirect (the tool docstring nudges it, but nothing enforces it). The old pipe behavior hung the turn; this trades it for a leak. Worth either calling the redirect out as load-bearing in the AGENTS.md note, or making the capture bounded — at minimum flagging it so it's a conscious tradeoff rather than a surprise.

[willem-bd]

On Windows this still calls subprocess.run(..., timeout=timeout), which raises TimeoutExpired uncaught on timeout — timed_out stays False, so the explanatory notice is never produced and the process group is never killed.

The PR now flows bash_command_timeout into this path (via command_timeout in bash_tool), so the contract here did change: a Windows user who lowers it (e.g. bash_command_timeout: 30) gets a raw TimeoutExpired → bash_tool's generic except Exception → "Error: Unexpected error executing command: …" instead of the bounded-with-notice behavior advertised for POSIX. The body says "Windows path is intentionally unchanged," but the knob now reaches it. Either don't pass command_timeout on Windows (keep the hardcoded 600), or catch TimeoutExpired and set timed_out=True to mirror the POSIX path.

[willem-bd]

Minor: execute_command accepts float | None, but the notice does int(timeout), so a non-integral timeout renders truncated and mispluralized — e.g. timeout=1.5 → "Command timed out after 1 seconds and was terminated.". If float timeouts are meant to be supported (the tests pass 1), round it and handle the singular; otherwise document timeout as integral.

[willem-bd]

Solid fix for the pipe-inheritance hang — temp-file capture + start_new_session + group kill is the right shape for POSIX. Three inline notes below, the first (silent /tmp leak for un-redirected backgrounded processes) is the one I'd most want discussed before merge since it sits on the PR's headline use case.