Module subprocess 

Process supervision for the agent and MCP children this installation owns, and for its API server: the one place that spawns, identifies, probes and stops them.

Spawning

spawn_supervised is the only sanctioned way to start a child, and mark_child stamps it with the environment markers that later prove it is ours. Every spawn runs on one dedicated thread, which on Linux also arms the parent-death signal.

Control

is_running, owns, pids_listening_on, terminate_gracefully, terminate_group_gracefully and stop_owned are async and never block a runtime worker. A stop signals only a pid that is provably ours: the pid the registry recorded and a matching ChildKind marker read back from the live process. Outcomes are typed (Termination, StopOutcome); failures are SupervisionError.

Identity

The environment markers and the pure parsers that read them back live in systemprompt_models::subprocess; the platform probes here (live_pid_is_subprocess, is_zombie) execute them against /proc or sysctl. They are blocking primitives; async callers use owns and is_running.

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, via sysctl(KERN_PROCARGS2) and proc_pidinfo. Report the platform’s coverage with identity_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 survives execve, and the kqueue and pipe-EOF alternatives all require cooperation from the child binary — which is an arbitrary MCP server or agent executable here. A SIGKILLed supervisor on macOS therefore leaves its children reparented to launchd and 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.

Enums

ApiServerStamp

How stamp_api_server returned instead of re-executing.

ChildKind

Which kind of supervised process a pid is claimed to be; selects the marker variable that names it. Api is the API server, stamped by stamp_api_server rather than spawned.

StopOutcome

How a stop of a recorded, marker-verified child ended.

SupervisionError

Why a supervision call could not establish or change a process’s state.

Termination

How a termination request ended.

Functions

api_server_service

is_running

is_zombie

live_pid_is_subprocess

mark_child

owns

parse_lsof_pids

parse_netstat_listeners

pids_listening_on

place_in_own_process_group

process_group

spawn_owned_supervised

spawn_supervised

stamp_api_server

stop_owned

terminate_gracefully

terminate_group_gracefully