Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Extend child commands with session and descriptor controls (#47604)

Charlie Marshb8d365b18ec2
diff --git a/codex-rs/exec-server/src/fs_sandbox.rs b/codex-rs/exec-server/src/fs_sandbox.rs
index db4c4872f4..eee175c0cf 100644
--- a/codex-rs/exec-server/src/fs_sandbox.rs
+++ b/codex-rs/exec-server/src/fs_sandbox.rs
@@ -531,7 +531,7 @@ pub(crate) fn spawn_command(
command.fallback(SpawnFallback::ReturnError);
// macOS cannot receive passed fds with close-on-exec set atomically.
#[cfg(target_os = "macos")]
- command.descriptor_policy(DescriptorPolicy::StdioOnly);
+ command.descriptor_policy(DescriptorPolicy::Explicit);
command.spawn().map_err(io_error)
}
diff --git a/codex-rs/rmcp-client/src/stdio_server_launcher.rs b/codex-rs/rmcp-client/src/stdio_server_launcher.rs
index 65ba1f0c5a..84db78081e 100644
--- a/codex-rs/rmcp-client/src/stdio_server_launcher.rs
+++ b/codex-rs/rmcp-client/src/stdio_server_launcher.rs
@@ -284,10 +284,10 @@ impl LocalStdioServerLauncher {
command.process_mode(ProcessMode::NewGroup);
// MCP uses only stdio; unrelated orchestrator descriptors must not
// propagate into the server or commands it launches.
- // StdioOnly is currently Unix-only. Windows can still inherit unrelated
+ // Descriptor allowlisting is Unix-only. Windows can still inherit unrelated
// handles and needs a handle allowlist in the shared spawn backend.
#[cfg(unix)]
- command.descriptor_policy(DescriptorPolicy::StdioOnly);
+ command.descriptor_policy(DescriptorPolicy::Explicit);
command
};
#[cfg(windows)]
diff --git a/codex-rs/utils/pty/src/child_command.rs b/codex-rs/utils/pty/src/child_command.rs
index 01a010e1af..0f549c3719 100644
--- a/codex-rs/utils/pty/src/child_command.rs
+++ b/codex-rs/utils/pty/src/child_command.rs
@@ -2,8 +2,8 @@
//!
//! The wrapped Tokio command is private: callers cannot install callbacks or
//! change settings that the native backend cannot inspect. Children receive only
-//! explicitly supplied environment variables and default to kill-on-drop. Stdio, descriptor
-//! inheritance, and compatibility fallbacks are configured independently.
+//! explicitly supplied environment variables and default to kill-on-drop. Stdio,
+//! descriptor inheritance, and compatibility fallbacks are configured independently.
use std::ffi::OsStr;
#[cfg(unix)]
@@ -15,18 +15,29 @@ use std::process::Stdio as TokioStdio;
use crate::child::Child;
use crate::child::ChildKind;
-/// Relationship between a child and its parent's process group.
+/// Relationship between a child and its parent's session and process group.
+///
+/// These settings apply only on Unix; other platforms use their default behavior.
#[derive(Clone, Copy)]
pub enum ProcessMode {
+ /// Keep the parent's session, process group, and controlling terminal.
Inherit,
+ /// Create a process group led by the child, keeping the parent's session and
+ /// controlling terminal. This allows signaling the child's group separately.
NewGroup,
+ /// Create a session and process group led by the child, detaching from the
+ /// parent's controlling terminal.
+ ///
+ /// Native spawning is an optimization; compatibility fallbacks may fork.
+ NewSession,
}
-/// Descriptors visible to a Unix child beyond its explicit stdio.
+/// Whether Unix children inherit ambient descriptors or only explicit stdio and
+/// the descriptors selected by `Command::preserve_fds`.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum DescriptorPolicy {
Inherit,
- StdioOnly,
+ Explicit,
}
/// Whether a native launch may use Command's executable-text and PATH fallbacks.
@@ -52,6 +63,7 @@ pub(crate) enum ChildDropPolicy {
/// An explicit child stdin, including a socket used for bidirectional fd transfer.
pub enum ChildStdin {
Piped,
+ Null,
#[cfg(unix)]
File(std::os::fd::OwnedFd),
}
@@ -65,6 +77,10 @@ pub struct Command {
pub(crate) stdin: ChildStdin,
pub(crate) drop_policy: ChildDropPolicy,
#[cfg(unix)]
+ pub(crate) inherited_fds: Vec<std::os::fd::RawFd>,
+ #[cfg(target_os = "linux")]
+ parent_pid: Option<libc::pid_t>,
+ #[cfg(unix)]
pub(crate) arg0: Option<OsString>,
}
@@ -85,6 +101,10 @@ impl Command {
stdin: ChildStdin::Piped,
drop_policy: ChildDropPolicy::KillAndReap,
#[cfg(unix)]
+ inherited_fds: Vec::new(),
+ #[cfg(target_os = "linux")]
+ parent_pid: None,
+ #[cfg(unix)]
arg0: None,
}
}
@@ -152,6 +172,32 @@ impl Command {
self
}
+ /// Preserve live inheritable descriptors at their existing numbers.
+ /// The caller must keep them open until spawning returns. We do not duplicate
+ /// or close them: closing even a duplicate releases the parent's POSIX record
+ /// locks. Closed and CLOEXEC descriptors remain excluded.
+ #[cfg(unix)]
+ pub fn preserve_fds(&mut self, fds: &[std::os::fd::RawFd]) -> &mut Self {
+ self.inherited_fds = fds
+ .iter()
+ .copied()
+ .filter(|fd| {
+ // SAFETY: fcntl reports invalid descriptors without dereferencing memory.
+ let flags = unsafe { libc::fcntl(*fd, libc::F_GETFD) };
+ *fd > libc::STDERR_FILENO && flags >= 0 && flags & libc::FD_CLOEXEC == 0
+ })
+ .collect();
+ self
+ }
+
+ /// Keep the existing Linux pipe behavior when the spawning parent exits.
+ #[cfg(target_os = "linux")]
+ pub fn terminate_on_parent_death(&mut self) -> &mut Self {
+ // SAFETY: getpid has no preconditions.
+ self.parent_pid = Some(unsafe { libc::getpid() });
+ self
+ }
+
#[cfg(unix)]
pub fn arg0(&mut self, arg0: impl AsRef<OsStr>) -> &mut Self {
self.inner.arg0(arg0.as_ref());
@@ -176,8 +222,10 @@ impl Command {
let command = self.inner.as_std();
let program = command.get_program();
if (Path::new(program).is_relative()
- || self.descriptor_policy == DescriptorPolicy::StdioOnly
- || self.fallback == SpawnFallback::ReturnError)
+ || self.descriptor_policy == DescriptorPolicy::Explicit
+ || self.fallback == SpawnFallback::ReturnError
+ || matches!(self.process_mode, ProcessMode::NewSession)
+ || !self.inherited_fds.is_empty())
&& !program.is_empty()
&& let Some(child) = crate::child::macos::NativeChild::spawn(&self)?
{
@@ -186,17 +234,37 @@ impl Command {
}
self.inner.stdin(match self.stdin {
ChildStdin::Piped => TokioStdio::piped(),
+ ChildStdin::Null => TokioStdio::null(),
#[cfg(unix)]
ChildStdin::File(fd) => TokioStdio::from(fd),
});
#[cfg(unix)]
- if self.descriptor_policy == DescriptorPolicy::StdioOnly {
- // SAFETY: This preserves the existing Unix descriptor cleanup before exec.
- unsafe {
- self.inner.pre_exec(|| {
- crate::pty::close_inherited_fds_except(&[]);
- Ok(())
- });
+ {
+ let new_session = matches!(self.process_mode, ProcessMode::NewSession);
+ let explicit_fds = self.descriptor_policy == DescriptorPolicy::Explicit;
+ let targets = self.inherited_fds;
+ #[cfg(target_os = "linux")]
+ let parent_pid = self.parent_pid;
+ #[cfg(not(target_os = "linux"))]
+ let parent_pid: Option<i32> = None;
+ if new_session || explicit_fds || !targets.is_empty() || parent_pid.is_some() {
+ // SAFETY: Keep the existing Unix pre-exec setup in the fallback
+ // backend. The caller keeps the selected descriptors open, and
+ // this callback only changes the child's descriptor table.
+ unsafe {
+ self.inner.pre_exec(move || {
+ if new_session {
+ crate::process_group::detach_from_tty()?;
+ }
+ if let Some(parent_pid) = parent_pid {
+ crate::process_group::set_parent_death_signal(parent_pid)?;
+ }
+ if explicit_fds {
+ crate::pty::close_inherited_fds_except(&targets);
+ }
+ Ok(())
+ });
+ }
}
}
#[cfg(unix)]
diff --git a/codex-rs/utils/pty/src/child_tests.rs b/codex-rs/utils/pty/src/child_tests.rs
index 0fd28e8360..b3dedb376e 100644
--- a/codex-rs/utils/pty/src/child_tests.rs
+++ b/codex-rs/utils/pty/src/child_tests.rs
@@ -1,4 +1,4 @@
-//! Regression coverage for output-pipe lifetimes and runtime-independent reaping.
+//! Regression coverage for child descriptors, process modes, and runtime-independent reaping.
use std::future::Future;
use std::future::poll_fn;
@@ -161,3 +161,171 @@ fn wait_until_reaped(pid: u32) -> anyhow::Result<()> {
}
Ok(())
}
+
+#[tokio::test]
+async fn preserved_descriptor_can_use_the_last_slot_below_the_limit() -> anyhow::Result<()> {
+ use std::os::fd::AsRawFd;
+ use std::os::fd::FromRawFd;
+ if std::env::var_os("CODEX_TEST_ISOLATED_FD_LIMIT").is_none() {
+ let output = std::process::Command::new(std::env::current_exe()?)
+ .args([
+ "--exact",
+ "child::tests::preserved_descriptor_can_use_the_last_slot_below_the_limit",
+ "--nocapture",
+ ])
+ .env("CODEX_TEST_ISOLATED_FD_LIMIT", "1")
+ .output()?;
+ assert!(output.status.success(), "{output:?}");
+ return Ok(());
+ }
+ // Use a known, small limit without changing other tests' process-wide limit.
+ let mut limit = std::mem::MaybeUninit::<libc::rlimit>::uninit();
+ // SAFETY: getrlimit initializes writable storage.
+ assert_eq!(
+ unsafe { libc::getrlimit(libc::RLIMIT_NOFILE, limit.as_mut_ptr()) },
+ 0
+ );
+ // SAFETY: getrlimit succeeded.
+ let mut limit = unsafe { limit.assume_init() };
+ limit.rlim_cur = limit.rlim_cur.min(256);
+ // SAFETY: Only this isolated test process's soft limit is lowered.
+ assert_eq!(unsafe { libc::setrlimit(libc::RLIMIT_NOFILE, &limit) }, 0);
+ let last = i32::try_from(limit.rlim_cur - 1)?;
+ let root = tempfile::tempdir()?;
+ let path = root.path().join("input");
+ std::fs::write(&path, "preserved")?;
+ let source = std::fs::File::open(path)?;
+ let fd = unsafe { libc::fcntl(source.as_raw_fd(), libc::F_DUPFD_CLOEXEC, last) };
+ anyhow::ensure!(fd == last, "could not reserve the last descriptor slot");
+ let fd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fd) };
+ assert_eq!(unsafe { libc::fcntl(fd.as_raw_fd(), libc::F_SETFD, 0) }, 0);
+ let mut command = crate::Command::new("/bin/cat");
+ command
+ .arg(format!("/dev/fd/{last}"))
+ .stdin(crate::ChildStdin::Null)
+ .descriptor_policy(crate::DescriptorPolicy::Explicit)
+ .preserve_fds(&[last]);
+ let output = command.spawn()?.wait_with_output().await?;
+ assert!(output.status.success(), "{output:?}");
+ assert_eq!(output.stdout, b"preserved");
+ Ok(())
+}
+
+#[tokio::test]
+async fn process_mode_is_preserved_by_both_backends() -> anyhow::Result<()> {
+ use crate::ProcessMode;
+ use std::os::unix::fs::PermissionsExt;
+ let root = tempfile::tempdir()?;
+ std::os::unix::fs::symlink("/bin/cat", root.path().join("server"))?;
+ let script = root.path().join("executable-text");
+ std::fs::write(&script, "exec /bin/cat\n")?;
+ std::fs::set_permissions(&script, std::fs::Permissions::from_mode(/*mode*/ 0o755))?;
+ for program in ["./server", "/bin/cat", "./executable-text"] {
+ for mode in [
+ ProcessMode::Inherit,
+ ProcessMode::NewGroup,
+ ProcessMode::NewSession,
+ ] {
+ let mut command = Command::new(program);
+ command.current_dir(root.path()).process_mode(mode);
+ let mut child = match command.spawn() {
+ Ok(child) => child,
+ Err(error) if program == "./executable-text" => {
+ // Executable-text fallback depends on both libc and std's
+ // spawn backend. Compare the same mode with std directly.
+ let mut baseline = tokio::process::Command::new(program);
+ baseline
+ .current_dir(root.path())
+ .env_clear()
+ .kill_on_drop(true);
+ match mode {
+ ProcessMode::Inherit => {}
+ ProcessMode::NewGroup => {
+ baseline.process_group(/*pgroup*/ 0);
+ }
+ ProcessMode::NewSession => {
+ // SAFETY: Session setup is async-signal-safe.
+ unsafe {
+ baseline.pre_exec(crate::process_group::detach_from_tty);
+ }
+ }
+ }
+ let expected = baseline
+ .spawn()
+ .expect_err("legacy spawn must also reject executable text");
+ assert_eq!(error.raw_os_error(), expected.raw_os_error());
+ continue;
+ }
+ Err(error) => return Err(error.into()),
+ };
+ let pid = child.id().expect("live PID") as libc::pid_t;
+ // SAFETY: These calls only inspect the current process.
+ let (parent_group, parent_session) = unsafe { (libc::getpgrp(), libc::getsid(0)) };
+ let expected = match mode {
+ ProcessMode::Inherit => (parent_group, parent_session),
+ ProcessMode::NewGroup => (pid, parent_session),
+ ProcessMode::NewSession => (pid, pid),
+ };
+ // SAFETY: The child is still owned and blocked on its stdin pipe.
+ assert_eq!(unsafe { (libc::getpgid(pid), libc::getsid(pid)) }, expected);
+ child.kill().await?;
+ }
+ }
+ Ok(())
+}
+
+#[tokio::test]
+async fn preserving_descriptors_keeps_parent_record_locks() -> anyhow::Result<()> {
+ use std::io::Read;
+ if let Some(path) = std::env::var_os("CODEX_TEST_RECORD_LOCK") {
+ // Wait until spawn has returned and dropped the parent's command.
+ std::io::stdin().read_exact(&mut [0])?;
+ let file = std::fs::OpenOptions::new().write(true).open(path)?;
+ // SAFETY: A zeroed flock with these fields describes the whole file.
+ let mut lock: libc::flock = unsafe { std::mem::zeroed() };
+ lock.l_type = libc::F_WRLCK as _;
+ lock.l_whence = libc::SEEK_SET as _;
+ assert_eq!(
+ unsafe { libc::fcntl(file.as_raw_fd(), libc::F_SETLK, &lock) },
+ -1
+ );
+ assert!(matches!(
+ std::io::Error::last_os_error().raw_os_error(),
+ Some(libc::EACCES | libc::EAGAIN)
+ ));
+ return Ok(());
+ }
+ let file = tempfile::NamedTempFile::new()?;
+ // SAFETY: The descriptor remains owned and open throughout the launch.
+ assert_eq!(
+ unsafe { libc::fcntl(file.as_raw_fd(), libc::F_SETFD, 0) },
+ 0
+ );
+ let mut lock: libc::flock = unsafe { std::mem::zeroed() };
+ lock.l_type = libc::F_WRLCK as _;
+ lock.l_whence = libc::SEEK_SET as _;
+ assert_eq!(
+ unsafe { libc::fcntl(file.as_raw_fd(), libc::F_SETLK, &lock) },
+ 0
+ );
+ let mut command = Command::new(std::env::current_exe()?);
+ command
+ .args([
+ "--exact",
+ "child::tests::preserving_descriptors_keeps_parent_record_locks",
+ "--nocapture",
+ ])
+ .env("CODEX_TEST_RECORD_LOCK", file.path())
+ .descriptor_policy(crate::DescriptorPolicy::Explicit)
+ .preserve_fds(&[file.as_raw_fd()]);
+ let mut child = command.spawn()?;
+ child
+ .stdin
+ .take()
+ .expect("piped stdin")
+ .write_all(b"x")
+ .await?;
+ let output = child.wait_with_output().await?;
+ assert!(output.status.success(), "{output:?}");
+ Ok(())
+}
diff --git a/codex-rs/utils/pty/src/macos_child.rs b/codex-rs/utils/pty/src/macos_child.rs
index 5a0158b848..7d3f5a34d0 100644
--- a/codex-rs/utils/pty/src/macos_child.rs
+++ b/codex-rs/utils/pty/src/macos_child.rs
@@ -27,6 +27,10 @@ use crate::child_command::ChildDropPolicy;
use crate::child::reaper;
+// Apple's spawn.h defines this extension on our minimum macOS 12, but libc
+// does not expose it. A new session also creates a new process group.
+const POSIX_SPAWN_SETSID: libc::c_int = 0x0400;
+
// libc does not expose this Apple extension. It is available since macOS 10.15,
// before Codex's minimum supported macOS version (12).
unsafe extern "C" {
@@ -96,6 +100,7 @@ impl NativeChild {
Some(ChildStdin::from_std(OwnedFd::from(writer).into())?),
)
}
+ crate::ChildStdin::Null => (std::fs::File::open("/dev/null")?.into(), None),
crate::ChildStdin::File(fd) => (fd.try_clone()?, None),
};
let (stdout_read, stdout_write) = io::pipe()?;
@@ -129,8 +134,19 @@ impl NativeChild {
target as i32,
))?;
}
+ for target in &request.inherited_fds {
+ let result =
+ libc::posix_spawn_file_actions_adddup2(&mut actions.0, *target, *target);
+ // macOS file actions can reject valid high descriptors below
+ // RLIMIT_NOFILE. The existing dup2 fallback supports them.
+ if result == libc::EBADF && request.fallback == crate::SpawnFallback::Compatible {
+ return Ok(None);
+ }
+ cvt(result)?;
+ }
let group_flags = match request.process_mode {
crate::ProcessMode::Inherit => 0,
+ crate::ProcessMode::NewSession => POSIX_SPAWN_SETSID,
crate::ProcessMode::NewGroup => {
cvt(libc::posix_spawnattr_setpgroup(
&mut attrs.0,
@@ -145,7 +161,7 @@ impl NativeChild {
cvt(libc::posix_spawnattr_setsigdefault(&mut attrs.0, &defaults))?;
let descriptor_flags = match request.descriptor_policy {
crate::DescriptorPolicy::Inherit => 0,
- crate::DescriptorPolicy::StdioOnly => libc::POSIX_SPAWN_CLOEXEC_DEFAULT,
+ crate::DescriptorPolicy::Explicit => libc::POSIX_SPAWN_CLOEXEC_DEFAULT,
};
cvt(libc::posix_spawnattr_setflags(
&mut attrs.0,
diff --git a/codex-rs/utils/pty/src/macos_child_tests.rs b/codex-rs/utils/pty/src/macos_child_tests.rs
index 921a71bfa7..b2a29876ff 100644
--- a/codex-rs/utils/pty/src/macos_child_tests.rs
+++ b/codex-rs/utils/pty/src/macos_child_tests.rs
@@ -296,26 +296,3 @@ fn dropping_after_runtime_shutdown_kills_and_reaps_child() -> anyhow::Result<()>
);
Ok(())
}
-
-#[tokio::test]
-async fn process_mode_is_preserved_by_both_backends() -> anyhow::Result<()> {
- let root = tempfile::tempdir()?;
- symlink("/bin/cat", root.path().join("server"))?;
- for program in ["./server", "/bin/cat"] {
- for mode in [ProcessMode::Inherit, ProcessMode::NewGroup] {
- let mut command = Command::new(program);
- command.current_dir(root.path()).process_mode(mode);
- let mut child = command.spawn()?;
- let pid = child.id().expect("live PID") as libc::pid_t;
- let expected = match mode {
- // SAFETY: getpgrp only inspects the current process.
- ProcessMode::Inherit => unsafe { libc::getpgrp() },
- ProcessMode::NewGroup => pid,
- };
- // SAFETY: The child is still owned and blocked on its stdin pipe.
- assert_eq!(unsafe { libc::getpgid(pid) }, expected);
- child.kill().await?;
- }
- }
- Ok(())
-}
diff --git a/codex-rs/utils/pty/src/macos_descriptor_tests.rs b/codex-rs/utils/pty/src/macos_descriptor_tests.rs
index 405c14b852..7b4da64645 100644
--- a/codex-rs/utils/pty/src/macos_descriptor_tests.rs
+++ b/codex-rs/utils/pty/src/macos_descriptor_tests.rs
@@ -3,6 +3,7 @@
use super::*;
use pretty_assertions::assert_eq;
use std::fs;
+use std::io::Seek;
use std::os::fd::AsRawFd;
use std::os::fd::FromRawFd;
use std::os::fd::OwnedFd;
@@ -34,7 +35,7 @@ async fn explicit_stdio_excludes_inheritable_descriptors_without_changing_parent
let mut command = Command::new("/bin/sh");
command
.args(["-c", &script])
- .descriptor_policy(DescriptorPolicy::StdioOnly);
+ .descriptor_policy(DescriptorPolicy::Explicit);
let output = command.spawn()?.wait_with_output().await?;
assert_eq!(
(output.status.success(), output.stdout, output.stderr),
@@ -59,7 +60,7 @@ async fn socket_stdin_preserves_bidirectional_io_and_custom_argv0() -> anyhow::R
.arg0("helper")
.env("FS_TEST", "literal ; $value")
.stdin(ChildStdin::File(socket.into()))
- .descriptor_policy(DescriptorPolicy::StdioOnly)
+ .descriptor_policy(DescriptorPolicy::Explicit)
.fallback(SpawnFallback::ReturnError);
let child = command.spawn()?;
assert!(child.stdin.is_none());
@@ -92,3 +93,44 @@ async fn native_launch_can_reject_executable_text_without_shell_fallback() -> an
assert_eq!(error.raw_os_error(), Some(libc::ENOEXEC));
Ok(())
}
+
+#[tokio::test]
+async fn inherited_descriptors_survive_native_and_executable_text_spawns() -> anyhow::Result<()> {
+ let directory = tempfile::tempdir()?;
+ let data = directory.path().join("data");
+ fs::write(&data, "captured descriptor")?;
+ let mut file = fs::File::open(&data)?;
+ for native in [true, false] {
+ file.rewind()?;
+ // SAFETY: Duplicate this live file into a new inheritable descriptor.
+ let raw = unsafe { libc::fcntl(file.as_raw_fd(), libc::F_DUPFD, 100) };
+ assert!(raw >= 100);
+ // SAFETY: fcntl returned a newly owned descriptor.
+ let _original = unsafe { OwnedFd::from_raw_fd(raw) };
+ let descriptor = format!("/dev/fd/{raw}");
+ let mut command = if native {
+ let mut command = Command::new("/bin/cat");
+ command.arg(&descriptor);
+ command
+ } else {
+ let script = directory.path().join("executable-text");
+ fs::write(&script, format!("/bin/cat {descriptor}\n"))?;
+ fs::set_permissions(&script, fs::Permissions::from_mode(/*mode*/ 0o755))?;
+ Command::new(script)
+ };
+ command
+ .descriptor_policy(DescriptorPolicy::Explicit)
+ .preserve_fds(&[raw]);
+ let child = command.spawn()?;
+ assert_eq!(
+ matches!(child.inner, crate::child::ChildKind::Native(_)),
+ native
+ );
+ let output = child.wait_with_output().await?;
+ assert_eq!(
+ (output.status.code(), output.stdout, output.stderr),
+ (Some(0), b"captured descriptor".to_vec(), vec![])
+ );
+ }
+ Ok(())
+}