cli-agent-runner

agent-runner is a supervision tool for keeping autonomous coding CLIs running continuously. It restarts agent processes after each round and ships presets for Claude Code, aider, gemini, codewhale, kimi, and pi, while supporting any prompt-argument CLI through custom configuration. The tool is organized around a three-layer model: the Round (one agent invocation), the Loop (a signal-trapping restart loop), and the Witness (a monitor with 14 detectors and auto-stop). It provides 15 named defenses structured as data, including round time budgets, process group isolation, orphan stash idempotency, SHA-locked stashes, set-diff classification, and startup smoke checks. Each defense documents the historical incident it addresses and has an invariant test. The monitor component runs 14 detectors against the supervised project's local logs, covering issues such as timeout rates, hung rounds, orphan chains, disk warnings and growth, memory pressure, network failures, rate limiting, and repetitive anomalies. Two detectors can auto-stop the service when continuing would be harmful: OAuth failures that burn API quota and critical disk conditions. An optional soft-brake can cap memory usage under sustained pressure. agent-runner exposes 17 command verbs for lifecycle management (init, install, start, stop, restart, kill, upgrade, migrate) and observation (peek, watch, monitor, events, status, doctor). It supports systemd user units for serve and monitor processes, scheduled run/pause windows, JSON output for downstream consumers, and remote event relay over managed SSH connections while keeping detection on the host. The project includes extensive documentation covering quickstart, command reference, configuration schema, operator troubleshooting, and architecture. It is POSIX-only (Linux, macOS), tested with Python 3.11+ on x86_64 and aarch64, and licensed under Apache 2.0.