Merge d16b6413db into 09be5d45d5

docs/gateway/background-process.md

@@ -38,6 +38,7 @@ Environment overrides:
 
 Config (preferred):
 - `tools.exec.backgroundMs` (default 10000)
+- `tools.exec.backgroundRunner` (default `"process"`; Linux-only `"systemd"` supported)
 - `tools.exec.timeoutSec` (default 1800)
 - `tools.exec.cleanupMs` (default 1800000)
  - `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.

docs/gateway/configuration.md

@@ -1934,6 +1934,7 @@ of `every`, keep `HEARTBEAT.md` tiny, and/or choose a cheaper `model`.
 
 `tools.exec` configures background exec defaults:
 - `backgroundMs`: time before auto-background (ms, default 10000)
+- `backgroundRunner`: `"process"` (default) or `"systemd"` (Linux only). When `"systemd"`, background jobs started with `background=true` run via `systemd-run --user` so long-running tasks (tmux/codex) don’t stay in the gateway cgroup.
 - `timeoutSec`: auto-kill after this runtime (seconds, default 1800)
 - `cleanupMs`: how long to keep finished sessions in memory (ms, default 1800000)
 - `notifyOnExit`: enqueue a system event + request heartbeat when backgrounded exec exits (default true)

docs/tools/exec.md

@@ -48,6 +48,7 @@ Notes:
 - `tools.exec.node` (default: unset)
 - `tools.exec.pathPrepend`: list of directories to prepend to `PATH` for exec runs.
 - `tools.exec.safeBins`: stdin-only safe binaries that can run without explicit allowlist entries.
+- `tools.exec.backgroundRunner` (default: `"process"`): when set to `"systemd"` (Linux only), background jobs started with `background=true` run in a systemd user unit via `systemd-run --user`, so long-running tasks (tmux/codex) don’t stay in the gateway cgroup.
 
 Example:
 ```json5