Troubleshooting terminal-tools

Recipes for surprising results. Match the symptom to the section.

Empty stdout despite the command "should have" produced output

Possible causes:

1. Output went to stderr instead. Check stderr in the envelope (or use merge_stderr=True for jobs).
2. Output was fully truncated because max_output_kb is too small. Check stdout_truncated_bytes > 0. Bump max_output_kb or paginate via output_handle.
3. Command produced no output (correct, just unexpected, silent flags, no matches).
4. Pipeline issue: the last stage of a pipe ran but stdout went elsewhere (> /dev/null, redirected via 2>&1).
5. Process is buffering its output and didn't flush before exit. Add stdbuf -oL (line-buffered) or unbuffer to the command.

exit_code: null

Cause	Other field
Auto-backgrounded	auto_backgrounded: true, job_id: <X>
Hard timeout, process killed	timed_out: true
Pre-spawn failure (command not found)	error: ... set, pid: null
Still running (in terminal_job_logs)	status: "running"

output_handle returned expired: true

5-minute TTL. Either (a) you waited too long, or (b) the store evicted it under memory pressure (64 MB total cap, LRU eviction). Re-run the command.

To reduce risk: paginate the handle as soon as you receive it, or use terminal_job_* for huge outputs (4 MB ring buffer with offsets, no expiry).

"too many jobs" / JobLimitExceeded

TERMINAL_TOOLS_MAX_JOBS (default 32) hit. Either:

• Wait for jobs to exit (poll with terminal_job_logs(wait_until_exit=True))
• Kill old jobs: terminal_job_manage(action="list") to see what's running, then signal_term the abandoned ones
• Raise the cap via env (rare)

"session busy"

A terminal_pty_run was issued while another _run is in flight on the same session. PTY sessions are single-threaded conversations. Wait for the prior call to return, or open a second session.

"PTY cap reached"