hive.terminal-tools-job-control

1# Background job control
2 
3Background jobs are how you do things that take time without blocking your conversation. Three tools cover the surface: `terminal_job_start`, `terminal_job_logs`, `terminal_job_manage`.
4 
5## When to use a job
6 
7- Builds, deploys, long tests
8- Processes you want to monitor (streaming a log file, a dev server)
9- Anything that auto-backgrounded from `terminal_exec` (you have a `job_id`; pivot to this skill's idioms)
10 
11For one-shot work expected to finish quickly, `terminal_exec` is simpler. The auto-promotion mechanic in `terminal_exec` is your safety net — start with `terminal_exec`, take over with this skill if needed.
12 
13## Lifecycle
14 
15```
16terminal_job_start(command, ...)
17  → { job_id, pid, started_at }
18 
19terminal_job_logs(job_id, since_offset=0, max_bytes=64000)
20  → { data, offset, next_offset, status: "running"|"exited", exit_code, ... }
21 
22# Repeat with since_offset = previous next_offset until status == "exited"
23# Or, better when you have nothing else to do, wait once with wait_until_exit=True:
24terminal_job_logs(job_id, since_offset=N, wait_until_exit=True)
25  → waits until exit, a new message for you, or wait_timeout_sec (at most 600, the default)
26```
27 
28After exit, the job is retained for inspection (`terminal_job_manage(action="list")`) until evicted by FIFO (50 most recent exits kept).
29 
30## Offset bookkeeping — the only rule that matters
31 
32The job's output lives in a 4 MB ring buffer per stream. Each call to `terminal_job_logs` returns:
33…