====== 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:

<code json>
{"command":"ctest --test-dir build --output-on-failure -j2","cwd":"/path/to/project","run_in_background":true,"description":"Run the test suite"}
</code>

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:

<code json>
{"job_id":"<returned job UUID>"}
</code>

''ShellJobOutput'' reads a bounded tail:

<code json>
{"job_id":"<returned job UUID>","max_bytes":8192}
</code>

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 [[memory:provenance-time|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.

[[https://github.com/Xananthium/batbox/blob/bc8adfe6a032429c9a3726d81e912e91ceedb6e3/docs/wiki/seed/runtime/background-shell-jobs.txt|Pinned source snapshot]]