Table of Contents
Background shell jobs
Source snapshot: 2026-10-25 18:22 UTC, commit bc8adfe6a032429c9a3726d81e912e91ceedb6e3. Live availability follows the pinned rollout receipt.
Start and inspect
Use Bash directly for a long noninteractive command:
{"command":"ctest --test-dir build --output-on-failure -j2","cwd":"/path/to/project","run_in_background":true,"description":"Run the test suite"}
The result gives job_id, tmux session/service identifiers, working directory, and durable definition, output and receipt paths. starting acknowledges launch; launch_unknown leaves the execution outcome unresolved. ShellJobStatus accepts:
{"job_id":"<returned job UUID>"}
ShellJobOutput reads a bounded tail:
{"job_id":"<returned job UUID>","max_bytes":8192}
The maximum is 65536 raw bytes. The complete binary file preserves received stdout/stderr; invalid UTF-8 display bytes appear as \xHH. output_error and output_complete describe capture separately from the command's exit status. These tools poll; this feature does not inject an automatic completion message into a conversation.
Lifetime and stopping
ShellJobStop takes the same job_id object and requests cancellation of that job's process group. Its acknowledgement is a request receipt; the final status records what happened.
On Linux, a separate user systemd service owns tmux, so an engine restart with KillMode=control-group leaves accepted jobs alive. The receipt records the verified service/cgroup. Missing tmux or user-manager support fails launch before the command runs.
Host reboot ends tmux. An unfinished prior-boot job reports interrupted / host_reboot, retains its files, and is not rerun automatically. manual_restart supplies a fresh invocation for an explicit decision to start over. It cannot resume a vanished process.
Background jobs default to unlimited runtime; positive timeout seconds or timeout_ms set a deadline. Foreground Bash keeps its configured default, normally 120 seconds.
Sources and memory
Source: docs/managed-shell-jobs.md, src/tools/bash/ShellJobs.cpp, src/tools/ShellJobTool.cpp, and tests/unit/test_shell_jobs.cpp at bc8adfe6a032429c9a3726d81e912e91ceedb6e3. Job records default to ~/.batbox/shell-jobs/<job_id>/.
A saved result can cite its receipt/output file, job ID, source commit and observation time. An accepted launch is not a successful test result; retain unresolved status when recording it. See source and time.
Installed code observation: 2026-10-25T18:36:38.457052+00:00, native release d6949e909ffa08af7951. This page describes the verified repair rollout; live activity and later changes need fresh observations.