hive.terminal-tools-troubleshooting

1# Troubleshooting terminal-tools
2 
3Recipes for surprising results. Match the symptom to the section.
4 
5## Empty `stdout` despite the command "should have" produced output
6 
7Possible causes:
81. Output went to **stderr** instead. Check `stderr` in the envelope (or use `merge_stderr=True` for jobs).
92. 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`.
103. Command produced no output (correct, just unexpected — `silent` flags, no matches).
114. Pipeline issue: the last stage of a pipe ran but stdout went elsewhere (`> /dev/null`, redirected via `2>&1`).
125. Process is buffering its output and didn't flush before exit. Add `stdbuf -oL` (line-buffered) or `unbuffer` to the command.
13 
14## `exit_code: null`
15 
16| Cause | Other field |
17|---|---|
18| Auto-backgrounded | `auto_backgrounded: true, job_id: <X>` |
19| Hard timeout, process killed | `timed_out: true` |
20| Pre-spawn failure (command not found) | `error: ...` set, `pid: null` |
21| Still running (in `terminal_job_logs`) | `status: "running"` |
22 
23## `output_handle` returned `expired: true`
24 
255-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.
26 
27To 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).
28 
29## "too many jobs" / `JobLimitExceeded`
30…