hive.terminal-tools-troubleshooting

Empty stdout usually means output went to stderr, was truncated by a small max_output_kb limit, or the process buffered output without flushing. Check the stderr field and stdout_truncated_bytes, or add stdbuf -oL to force line buffering.

A null exit_code means the process did not exit normally: it was auto-backgrounded, killed by a hard timeout, failed before spawning, or is still running. Check companion fields like auto_backgrounded, timed_out, error, or status to identify which case applies.

Output handles have a 5-minute TTL and can also be evicted under memory pressure from the 64 MB LRU store. Re-run the command and paginate the handle immediately, or use terminal_job tools whose 4 MB ring buffer has no expiry.

The job cap defaults to 32; list running jobs with terminal_job_manage and signal_term abandoned ones, or wait for jobs to exit. Session busy means a PTY session handles one call at a time, so wait for the prior call or open a second session.

Many commands use exit 1 for legitimate non-error states: grep finds no matches, diff finds differences, test evaluates false. The semantic_status field accounts for these conventions, so trust it over the raw exit_code.

No, terminal-tools is bash-only on POSIX and returns an error for shell="/bin/zsh". Use the default bash shell or omit the shell parameter to exec commands directly, and remember globstar and other zsh-isms do not apply.