Module subprocess 

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 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 and reconciliation read them back from /proc/<pid>/environ 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

Child supervision is Linux-only, matching where the server actually runs. Both the identity check (live_pid_is_subprocess) and the reap check (is_zombie) read /proc, and the parent-death signal is prctl(PR_SET_PDEATHSIG). Elsewhere they degrade to fail-closed stubs that never confirm an identity, so no child is ever signalled and orphans must be cleared by hand. The code compiles and runs on other platforms; it does not supervise on them.

Copyright (c) systemprompt.io — Business Source License 1.1. See https://systemprompt.io for licensing details.

Constants

AGENT_NAME_ENV

MCP_SERVICE_ID_ENV

SUBPROCESS_MARKER_ENV

Functions

environ_identifies_child

is_zombie

Reports whether pid is a zombie — terminated but not yet reaped.

live_pid_is_subprocess

Confirm a live PID still names this installation’s child by reading its /proc/<pid>/environ and matching the spawn markers.

signalable_pid

Convert an OS process id into the signed form kill(2) expects, rejecting any value that would target more than that single process.

spawn_supervised

Spawns cmd as a detached child that the kernel terminates if this process dies, and returns its PID.