Job lifecycle

run creates a persisted job and normally observes it briefly. The returned job_id identifies that same job for every later operation.

1. Start. Run a command and retain the job_id.
2. Inspect. Use status for current state without waiting.
3. Observe. Use wait for a bounded observation window and the terminal exit code when available.
4. Read. Use tail for bounded, repeatable log excerpts and retained log paths.
5. Control. Use kill only to explicitly cancel a running job, or restart to start a new execution from its definition.

An observation deadline ending does not stop the managed command.

Default observation

run waits for up to 10 seconds by default. This catches many immediate startup failures in one agent turn. Use --no-wait when the caller must return immediately.

Reconnect later

agent-exec status "$JOB_ID"
agent-exec wait "$JOB_ID"
agent-exec tail "$JOB_ID"

Review every CLI command