systemprompt_models/subprocess/
mod.rs

1//! Spawning, identifying, and reaping the detached agent and MCP children the
2//! supervisor owns.
3//!
4//! # Spawning
5//!
6//! [`spawn_supervised`] is the only sanctioned way to start a child. It runs
7//! every spawn on one dedicated thread and, where the platform offers it, asks
8//! the kernel to `SIGTERM` the child if this process dies, so a crash, panic,
9//! or `SIGKILL` of the supervisor cannot strand an agent holding a port.
10//!
11//! # Identity
12//!
13//! The supervisor stamps environment markers at spawn time; shutdown,
14//! reconciliation, and port reclamation read them back off the live process to
15//! confirm a registry PID still names *this* installation's child before
16//! signalling it. PIDs are recycled, and group-signalling a stale PID
17//! (`kill(-pid)`) could reach an unrelated session leader — so a row is only
18//! ever signalled once both the subprocess marker and the exact
19//! `name_key=service_name` pairing are found.
20//!
21//! # Platform support
22//!
23//! The two halves of supervision have different reach, and conflating them is
24//! what stranded ports on macOS:
25//!
26//! - **Identity and reap checks** ([`live_pid_is_subprocess`], [`is_zombie`])
27//!   work on Linux, via `/proc`, and on macOS, via `sysctl(KERN_PROCARGS2)` and
28//!   `proc_pidinfo`. Report the platform's coverage with
29//!   [`identity_verification_supported`]; where it is absent the checks are
30//!   fail-closed stubs that never confirm an identity, so no process is ever
31//!   signalled on a guess.
32//! - **Parent-death prevention** is `prctl(PR_SET_PDEATHSIG)` and therefore
33//!   Linux-only. macOS has no equivalent that survives `execve`, and the kqueue
34//!   and pipe-EOF alternatives all require cooperation from the child binary —
35//!   which is an arbitrary MCP server or agent executable here. A `SIGKILL`ed
36//!   supervisor on macOS therefore leaves its children reparented to `launchd`
37//!   and still holding their ports; the identity check above is what lets the
38//!   next start reclaim them instead of erroring out.
39//!
40//! Copyright (c) systemprompt.io — Business Source License 1.1.
41//! See <https://systemprompt.io> for licensing details.
42
43use std::process::Command;
44use std::sync::OnceLock;
45use std::sync::mpsc::{Sender, channel};
46
47#[cfg(target_os = "linux")]
48mod linux;
49#[cfg(target_os = "linux")]
50pub use linux::{is_zombie, live_pid_is_subprocess};
51
52#[cfg(target_os = "macos")]
53mod darwin;
54#[cfg(target_os = "macos")]
55pub use darwin::{is_zombie, live_pid_is_subprocess};
56
57#[cfg(not(any(target_os = "linux", target_os = "macos")))]
58mod unsupported;
59#[cfg(not(any(target_os = "linux", target_os = "macos")))]
60pub use unsupported::{is_zombie, live_pid_is_subprocess};
61
62pub const SUBPROCESS_MARKER_ENV: &str = "SYSTEMPROMPT_SUBPROCESS";
63pub const AGENT_NAME_ENV: &str = "AGENT_NAME";
64pub const MCP_SERVICE_ID_ENV: &str = "MCP_SERVICE_ID";
65
66type SpawnReply = Sender<std::io::Result<u32>>;
67
68pub fn spawn_supervised(cmd: Command) -> std::io::Result<u32> {
69    let sender = spawner()
70        .as_ref()
71        .map_err(|e| std::io::Error::other(e.clone()))?;
72
73    let (reply_tx, reply_rx) = channel();
74    sender
75        .send((cmd, reply_tx))
76        .map_err(|disconnected| std::io::Error::other(disconnected.to_string()))?;
77    reply_rx
78        .recv()
79        .map_err(|disconnected| std::io::Error::other(disconnected.to_string()))?
80}
81
82fn spawner() -> &'static Result<Sender<(Command, SpawnReply)>, String> {
83    static SPAWNER: OnceLock<Result<Sender<(Command, SpawnReply)>, String>> = OnceLock::new();
84    SPAWNER.get_or_init(|| {
85        let (tx, rx) = channel::<(Command, SpawnReply)>();
86        std::thread::Builder::new()
87            .name("subprocess-spawner".to_owned())
88            .spawn(move || {
89                while let Ok((mut cmd, reply)) = rx.recv() {
90                    let outcome = spawn_on_this_thread(&mut cmd);
91                    if reply.send(outcome).is_err() {
92                        tracing::warn!(
93                            "Spawn requester vanished before collecting the child pid; the child \
94                             is unregistered and will only be cleaned up by its parent-death signal"
95                        );
96                    }
97                }
98            })
99            .map(|_handle| tx)
100            .map_err(|e| format!("could not start the subprocess spawner thread: {e}"))
101    })
102}
103
104fn spawn_on_this_thread(cmd: &mut Command) -> std::io::Result<u32> {
105    #[cfg(target_os = "linux")]
106    linux::arm_parent_death_signal(cmd);
107
108    let child = cmd.spawn()?;
109    let pid = child.id();
110    #[expect(
111        clippy::mem_forget,
112        reason = "detached child: skip Child's drop-time wait so it keeps running after this \
113                  returns; reaping is the caller's business via is_zombie"
114    )]
115    std::mem::forget(child);
116    Ok(pid)
117}
118
119// Why: pgid 0 makes the child its own group leader (pgid == pid), so the
120// supervisor can signal the whole group on shutdown and reach any helper
121// processes the child spawns, not just the child itself.
122#[cfg(unix)]
123pub fn place_in_own_process_group(command: &mut Command) {
124    use std::os::unix::process::CommandExt;
125    command.process_group(0);
126}
127
128#[cfg(windows)]
129pub fn place_in_own_process_group(command: &mut Command) {
130    use std::os::windows::process::CommandExt;
131    const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
132    command.creation_flags(CREATE_NEW_PROCESS_GROUP);
133}
134
135#[must_use]
136pub const fn identity_verification_supported() -> bool {
137    cfg!(any(target_os = "linux", target_os = "macos"))
138}
139
140#[must_use]
141pub fn signalable_pid(pid: u32) -> Option<i32> {
142    if pid == 0 {
143        return None;
144    }
145    i32::try_from(pid).ok()
146}
147
148#[must_use]
149pub fn environ_identifies_child(environ: &[u8], name_key: &str, service_name: &str) -> bool {
150    let marker = format!("{SUBPROCESS_MARKER_ENV}=1");
151    let expected_name = format!("{name_key}={service_name}");
152
153    let mut has_marker = false;
154    let mut has_name = false;
155    for entry in environ.split(|&b| b == 0) {
156        if entry == marker.as_bytes() {
157            has_marker = true;
158        } else if entry == expected_name.as_bytes() {
159            has_name = true;
160        }
161    }
162
163    has_marker && has_name
164}
165
166// Why: a `KERN_PROCARGS2` blob is `argc`, the exec path, NUL padding, `argc`
167// argv entries, then the environment — all NUL-delimited in one buffer. The
168// argv entries have to be skipped by count rather than searched past: an entry
169// is matched whole by `environ_identifies_child`, so a command line such as
170// `env MCP_SERVICE_ID=files …` would otherwise read as a marked environment and
171// get an unrelated process signalled. Kept here rather than in `darwin` so the
172// parse is unit-testable on every platform.
173#[must_use]
174pub fn environ_from_procargs2(blob: &[u8]) -> Option<&[u8]> {
175    const ARGC_LEN: usize = size_of::<i32>();
176
177    let argc_bytes: [u8; ARGC_LEN] = blob.get(..ARGC_LEN)?.try_into().ok()?;
178    let argc = usize::try_from(i32::from_ne_bytes(argc_bytes)).ok()?;
179
180    let mut rest = blob.get(ARGC_LEN..)?;
181    let exec_path_end = rest.iter().position(|&b| b == 0)?;
182    rest = rest.get(exec_path_end + 1..)?;
183
184    let argv_start = rest.iter().position(|&b| b != 0)?;
185    rest = rest.get(argv_start..)?;
186
187    for _ in 0..argc {
188        let entry_end = rest.iter().position(|&b| b == 0)?;
189        rest = rest.get(entry_end + 1..)?;
190    }
191
192    Some(rest)
193}
systemprompt_models/subprocess/mod.rs

systemprompt_models/subprocess/
mod.rs
