Background Process Lifecycle in Hermes

Long commands should not disappear into shell-level backgrounding. Hermes tracks processes started through the terminal tool so an operator can inspect output, wait for completion, send input, or stop them cleanly.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/features/tools/#background-process-management

Pick the right execution mode

Use foreground execution for bounded commands that should complete within the tool timeout. Use tracked background execution for long builds, deploys, batch jobs, servers, and watchers. Use PTY mode only when the program is genuinely interactive, such as a coding CLI or prompt-driven installer.

Lifecycle checklist

[ ] Start the command in the correct workdir.
[ ] Use background mode for long-running work instead of nohup, &, or disown.
[ ] Request completion notification for bounded jobs.
[ ] Record the returned process session ID.
[ ] Verify server readiness with a health check or log signal.
[ ] Read logs when output is partial or the exit status is unexpected.
[ ] Stop obsolete servers and watchers.
[ ] Confirm bounded jobs actually exited before reporting success.

Process actions

The process interface can list sessions, poll for new output, wait, retrieve logs, send input, submit input with Enter, close stdin, or kill a process. Choose the least disruptive action. Polling is useful for progress; waiting is better when the result is now required; killing is cleanup or recovery, not the first response to slow work.

Servers versus bounded jobs

A server may never exit, so readiness is the gate: start it, verify a health endpoint or startup log, then run tests from a separate command. A build or deploy has a defined end, so completion and exit code are the gate. Do not use a generic “started” message for both cases.

Pitfalls

Starting a bounded build silently and forgetting to inspect the result.
Running a server in foreground with shell background syntax.
Using PTY for every command and making output harder to parse.
Killing a slow process without reading its newest logs.
Reporting success from a startup banner before the health endpoint responds.
Leaving test servers and watchers running after QA.

Verification steps

Confirm the process appears in the tracked list.
Inspect incremental output for the expected startup or progress marker.
For a server, call its health or target route from another command.
For a bounded job, wait for completion and inspect the exit code.
Read the final log when output was truncated.
Kill or close any process that should not remain active.