[nvdorman]

Summary

• add terminal(background=true) which returns a stable process_id immediately
• add a session-scoped process tool with list, poll, log, wait, and kill actions
• preserve incremental stdout/stderr using absolute offsets, pagination, and a bounded rolling buffer
• track explicit running/completed/failed/cancelled/timed_out states and exit codes
• terminate whole process groups on kill, timeout, dashboard Stop, session close, and server shutdown
• allow legitimate repeated process waits through the agent repetition guard
• expose the companion process tool anywhere terminal is enabled, including custom roles

Motivation

Long-running work currently forces the model to guess durations with shell commands such as sleep 90; ps ...; tail .... That waits too long when work finishes early and gives no completion proof when it runs longer. Managed handles provide state-driven monitoring instead:

terminal(command=..., background=true) -> process_id
process(wait, process_id, timeout=30)   -> running or terminal status + new output
process(poll/log/kill, process_id)

The wait timeout is only an upper bound on how long a tool call blocks; completion is always determined by the child process lifecycle.

Verification

• make check
• go test -race ./internal/tools
• go test ./internal/agent
• Windows cross-compile of internal/tools tests
• regression coverage for incremental output, exactly-once concurrent polls, log offsets/pagination/retention, completion/non-zero exits, bounded wait, runtime timeout, process-group cancellation, session isolation, custom toolsets, dashboard-stop lifecycle, and terminal start handles