The supervisor

The supervisor owns the lifecycle of every agent process. It spawns each CLI in its own process group, tracks it, and kills it cleanly — including any children the CLI spawned.

Process groups

An agent CLI often spawns subprocesses of its own. The supervisor starts each agent as a detached process group, so a stop signals the whole group, not just the top process. On Windows the group is backed by a job object, so a subprocess that outlives its parent still goes down with the agent. Nothing is left running behind a stopped agent.

Suspending idle sessions

Each live session is a CLI plus its own subprocesses, so an open session costs real memory. The supervisor keeps 6 sessions live, and never more than 10. Past that it suspends the least recently used one — including one you have open, but never one running a turn.

A suspended session is not lost: its transcript and session id are intact, and your next message resumes it. The chat says so rather than showing a dead process.

Reclaiming orphans on boot

If the daemon stops while agents are running — a crash, a hard quit — those child processes could outlive it. On startup, the supervisor reclaims orphans before the server serves any request, so a fresh boot never inherits ghost agents from a prior run.

Stopping is clean

When you stop an agent, the in-flight turn is cancelled and the process group is terminated. The dashboard reflects the stop immediately. A confirmation names the consequence before anything destructive happens — for example, that an in-flight turn will be cancelled.

Events

State transitions flow onto a central event bus: working, needs input, exited, error. Chimes, attention counts, and activity views all read from that one bus, and the dashboard receives it over a single event stream.