Expand description
Spawning, identifying, and reaping the detached agent and MCP children the supervisor owns.
§Spawning
spawn_supervised is the only sanctioned way to start a child. It runs
every spawn on one dedicated thread and, where the platform offers it, asks
the kernel to SIGTERM the child if this process dies, so a crash, panic,
or SIGKILL of the supervisor cannot strand an agent holding a port.
§Identity
The supervisor stamps environment markers at spawn time; shutdown,
reconciliation, and port reclamation read them back off the live process to
confirm a registry PID still names this installation’s child before
signalling it. PIDs are recycled, and group-signalling a stale PID
(kill(-pid)) could reach an unrelated session leader — so a row is only
ever signalled once both the subprocess marker and the exact
name_key=service_name pairing are found.
§Platform support
The two halves of supervision have different reach, and conflating them is what stranded ports on macOS:
- Identity and reap checks (
live_pid_is_subprocess,is_zombie) work on Linux, via/proc, and on macOS, viasysctl(KERN_PROCARGS2)andproc_pidinfo. Report the platform’s coverage withidentity_verification_supported; where it is absent the checks are fail-closed stubs that never confirm an identity, so no process is ever signalled on a guess. - Parent-death prevention is
prctl(PR_SET_PDEATHSIG)and therefore Linux-only. macOS has no equivalent that survivesexecve, and the kqueue and pipe-EOF alternatives all require cooperation from the child binary — which is an arbitrary MCP server or agent executable here. ASIGKILLed supervisor on macOS therefore leaves its children reparented tolaunchdand still holding their ports; the identity check above is what lets the next start reclaim them instead of erroring out.
Copyright (c) systemprompt.io — Business Source License 1.1. See https://systemprompt.io for licensing details.