Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Serialize signal receipt with foreground child admission (#4596)
Maximilian Roos057037a69f5a
diff --git a/src/main.rs b/src/main.rsindex fa1c32c4f..2dfe7e8ac 100644--- a/src/main.rs+++ b/src/main.rs@@ -1161,7 +1161,8 @@ fn main() {// WORKTRUNK_TEST_MOCK_CONFIG_DIR; see `worktrunk::testing::mock_stub`.worktrunk::testing::mock_stub::maybe_run();- // Capture startup state before anything else: the working directory+ // Initialize the Unix signal-receiving process owner before other threads+ // exist, and capture startup state: the working directory// (used by shell_exec to resolve relative `GIT_*` path variables// inherited from a parent `git` — e.g. when invoked via `git wt ...`// with `alias.wt = "!wt"` — against a stable reference, rather than@@ -1173,7 +1174,13 @@ fn main() {// `init_rayon_thread_pool`, `force_color_output`, `parse_cli` — isn't// attributed. If startup itself becomes the suspect, capture it as// wall-clock minus the sum of post-init spans.- worktrunk::shell_exec::init_startup();+ if let Err(error) = worktrunk::shell_exec::init_startup() {+ handle_command_failure(+ anyhow::Error::new(error).context("Failed to initialize process execution"),+ 0,+ "wt",+ );+ }// Shell completion answers and exits without running a command, and no// code it reaches uses rayon — so it returns before the pool below isdiff --git a/src/shell_exec.rs b/src/shell_exec.rsindex 4879bc3a3..f906be893 100644--- a/src/shell_exec.rs+++ b/src/shell_exec.rs@@ -11,10 +11,16 @@//! ## Spawning children//!//! Worktrunk's command spawns use [`spawn`] or [`spawn_shared_child`]. Their-//! shared lock covers descriptor setup and process creation, never child waits:-//! children still execute concurrently. On macOS, the standard library creates-//! pipes and sockets before marking them close-on-exec. Serializing their setup-//! with spawns prevents a child from retaining another command's output or wake.+//! Unix process owner receives INT/TERM and runs process creation and foreground+//! admission on the same thread. [`init_startup`] establishes that owner before+//! application threads exist; workers inherit blocked signals, while the owner+//! and its children retain the caller's original mask. Requests serialize+//! creation, never child waits, so children still execute concurrently.+//!+//! On macOS, the standard library creates pipes and sockets before marking them+//! close-on-exec. A separate lock serializes descriptor setup with raw spawns,+//! preventing children from retaining unrelated output or wake endpoints. That+//! lock is never held while a caller waits for the process owner.//!//! ## Process groups and signal handling (Unix, `Cmd::stream`)//!@@ -89,6 +95,8 @@ use crate::trace::CommandTrace;#[cfg(unix)]pub mod pipe;+#[cfg(unix)]+mod process_owner;/// Prepare complete input before spawning, with no producer that can block.///@@ -132,17 +140,36 @@ pub(crate) fn with_process_creation_guard<T>(/// Spawn a child under the shared process-creation guard.pub fn spawn(command: &mut Command) -> std::io::Result<std::process::Child> {- with_process_creation_guard(|| command.spawn()).map_err(|error| spawn_error(command, error))+ let spawned = with_process_owner(command, |command| {+ with_process_creation_guard(|| command.spawn())+ })?;+ spawned.map_err(|error| spawn_error(command, error))}/// Spawn a shared child under the same process-creation lock as [`spawn`].pub fn spawn_shared_child(command: &mut Command) -> std::io::Result<SharedChild> {+ with_process_owner(command, spawn_shared_child_here)?+}++/// Raw creation on the process owner, also used inside foreground admission.+pub(crate) fn spawn_shared_child_here(command: &mut Command) -> std::io::Result<SharedChild> {// SharedChild::new calls try_wait and can reap a short-lived child here.// Keep SharedChild::spawn's unreaped ownership for process-tree cleanup.with_process_creation_guard(|| SharedChild::spawn(command)).map_err(|error| spawn_error(command, error))}+/// Run process creation and any admission checks on the signal-receiving owner.+pub(crate) fn with_process_owner<T: Send + 'static>(+ command: &mut Command,+ create: impl FnOnce(&mut Command) -> T + Send + 'static,+) -> std::io::Result<T> {+ #[cfg(unix)]+ return process_owner::with_command(command, create);+ #[cfg(not(unix))]+ Ok(create(command))+}+/// Create wakeup endpoints under the same guard as process creation.#[cfg(unix)]pub fn socket_pair() -> std::io::Result<(@@ -359,17 +386,19 @@ pub const INHERITED_GIT_PATH_VARS: &[&str] = &["GIT_OBJECT_DIRECTORY",];-/// Record process-startup facts: the current working directory (so relative-/// `GIT_*` path variables inherited from a parent process can later be-/// resolved to absolute paths by [`Cmd`]'s env setup) and the calling thread-/// (the foreground thread, exempt from the command semaphore —-/// see `CMD_SEMAPHORE`).+/// Initialize the Unix process owner and record startup facts: the current+/// directory (so [`Cmd`] can resolve inherited relative `GIT_*` paths) and the+/// calling thread (exempt from `CMD_SEMAPHORE`).////// Call once from `main()`, before any code changes the process's working-/// directory and before spawning threads. Subsequent calls are no-ops.-pub fn init_startup() {+/// directory or spawns threads. Workers inherit blocked INT/TERM; the process+/// owner and its children retain the original mask. Subsequent calls are no-ops.+pub fn init_startup() -> std::io::Result<()> {+ #[cfg(unix)]+ process_owner::init()?;STARTUP_CWD.get_or_init(|| std::env::current_dir().ok());FOREGROUND_THREAD.get_or_init(|| std::thread::current().id());+ Ok(())}fn startup_cwd() -> Option<&'static PathBuf> {@@ -2925,9 +2954,9 @@ print(*counts)/// set-once): with it unset, `is_foreground_thread()` is false everywhere,/// which is the state every other test runs under.#[test]- fn test_foreground_thread_exempt_after_init() {+ fn test_foreground_thread_exempt() {assert!(!is_foreground_thread());- init_startup();+ FOREGROUND_THREAD.get_or_init(|| std::thread::current().id());assert!(is_foreground_thread());// Threads other than the initializing one stay capped.let from_spawned = std::thread::spawn(is_foreground_thread).join().unwrap();diff --git a/src/shell_exec/process_owner.rs b/src/shell_exec/process_owner.rsnew file mode 100644index 000000000..2aedaa1d6--- /dev/null+++ b/src/shell_exec/process_owner.rs@@ -0,0 +1,146 @@+//! One thread receives command interrupts and creates child processes.+//!+//! Startup creates this owner with the original signal mask, then blocks+//! INT/TERM on the initializing thread before application workers exist. Those+//! workers inherit the blocked mask; the owner's children inherit the original+//! mask. A signal cannot be dequeued to an unrelated worker while the owner+//! admits a child. If spawn temporarily blocks signals, restoring its mask runs+//! the pending handler before the admission check.+//!+//! Requests cover creation and admission, never child waits. Commands return to+//! their callers for reuse. The descriptor-creation lock remains inside each raw+//! spawn: callers must not hold it while waiting for an owner request.+//! Library users that do not initialize process startup keep direct spawning;+//! establishing inherited masks after arbitrary threads exist would be unsafe.++use std::io;+use std::panic::{AssertUnwindSafe, catch_unwind, resume_unwind};+use std::process::Command;+use std::sync::mpsc;++use nix::sys::signal::{SigSet, Signal};+use once_cell::sync::OnceCell;++type Request = Box<dyn FnOnce() + Send>;+static OWNER: OnceCell<mpsc::Sender<Request>> = OnceCell::new();++pub(super) fn init() -> io::Result<()> {+ OWNER.get_or_try_init(start).map(|_| ())+}++fn start() -> io::Result<mpsc::Sender<Request>> {+ let mut blocked = SigSet::thread_get_mask()?;+ blocked.add(Signal::SIGINT);+ blocked.add(Signal::SIGTERM);++ let (sender, receiver) = mpsc::channel::<Request>();+ std::thread::Builder::new()+ .name("wt-process-owner".into())+ .spawn(move || {+ for request in receiver {+ request();+ }+ })?;+ // No requests or application workers exist until initialization returns.+ // Spawn failure leaves our mask intact; mask failure drops the sender and+ // lets the unpublished owner exit.+ blocked.thread_set_mask()?;+ Ok(sender)+}++pub(super) fn with_command<T: Send + 'static>(+ command: &mut Command,+ create: impl FnOnce(&mut Command) -> T + Send + 'static,+) -> io::Result<T> {+ let Some(owner) = OWNER.get() else {+ return Ok(create(command));+ };+ let mut owned = std::mem::replace(command, Command::new(""));+ let (sender, receiver) = mpsc::channel();+ owner+ .send(Box::new(move || {+ // Keep the signal owner alive if a request panics, and put the+ // reusable command back before propagating that panic to its caller.+ let result = catch_unwind(AssertUnwindSafe(|| create(&mut owned)));+ let _ = sender.send((owned, result));+ }))+ .map_err(|error| io::Error::other(error.to_string()))?;+ let (returned, result) = receiver+ .recv()+ .map_err(|error| io::Error::other(error.to_string()))?;+ *command = returned;+ match result {+ Ok(result) => Ok(result),+ Err(panic) => resume_unwind(panic),+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use std::os::unix::process::CommandExt;+ use std::process::Stdio;++ #[test]+ #[allow(unsafe_code)]+ fn panicking_request_restores_command_and_keeps_owner() {+ const CHILD_ENV: &str = "WORKTRUNK_TEST_PROCESS_OWNER_PANIC_CHILD";+ let mut signals = SigSet::empty();+ signals.add(Signal::SIGINT);+ signals.add(Signal::SIGTERM);+ if std::env::var_os(CHILD_ENV).is_none() {+ let mut command = Command::new(std::env::current_exe().unwrap());+ command+ .args([+ "--exact",+ "shell_exec::process_owner::tests::panicking_request_restores_command_and_keeps_owner",+ ])+ .env(CHILD_ENV, "1")+ .stdout(Stdio::piped())+ .stderr(Stdio::piped());+ // Keep the child's libtest harness thread out of signal delivery.+ // SAFETY: pthread_sigmask is async-signal-safe and only accesses+ // the signal set constructed before fork.+ unsafe {+ command.pre_exec(move || signals.thread_block().map_err(Into::into));+ }+ let output = crate::shell_exec::spawn(&mut command)+ .unwrap()+ .wait_with_output()+ .unwrap();+ let stdout = String::from_utf8_lossy(&output.stdout);+ let stderr = String::from_utf8_lossy(&output.stderr);+ assert!(output.status.success(), "{stdout}\n{stderr}");+ assert!(stdout.contains(" 1 passed;"), "{stdout}");+ return;+ }++ signals.thread_unblock().unwrap();+ crate::shell_exec::init_startup().unwrap();+ let mut command = Command::new("sh");+ command.args(["-c", "test \"$1\" = after-panic", "owner-probe"]);+ let panic = catch_unwind(AssertUnwindSafe(|| {+ with_command(&mut command, |command| {+ command.arg("after-panic");+ std::panic::panic_any(std::thread::current().id());+ })+ .unwrap();+ }))+ .unwrap_err();+ let owner = *panic.downcast::<std::thread::ThreadId>().unwrap();+ assert_ne!(owner, std::thread::current().id());+ assert_eq!(+ with_command(&mut command, |_| std::thread::current().id()).unwrap(),+ owner+ );+ // The request's changes return even when it panics, and the same owner+ // still creates children with that reusable command.+ assert!(+ crate::shell_exec::spawn(&mut command)+ .unwrap()+ .wait()+ .unwrap()+ .success()+ );+ }+}diff --git a/src/signal_forwarder.rs b/src/signal_forwarder.rsindex 20d253499..2600ce5f3 100644--- a/src/signal_forwarder.rs+++ b/src/signal_forwarder.rs@@ -14,6 +14,8 @@//! SharedChild serializes those deliveries with reaping. No caller group is killed.//! A group-wide TERM may also reach a child through this PID forwarding;//! repeated TERM deliveries never trigger escalation here.+//! The process owner receives signals and performs foreground admission on the+//! same thread, so a handler cannot lag behind a spawn on a different thread.//! Spawn return commits admission. Startup cancellation retires an uncommitted//! child with TERM; its cleanup is best effort, while admitted children finish//! native-key cleanup. TERM is cooperative, with no escalation.@@ -247,15 +249,20 @@ impl Drop for Registration {pub struct ForegroundSignals {signals: Signals,+ admission: Admission,+ terminal_interrupt: TerminalInterrupt,+ lease: Lease,+ registration: Registration,+}++#[derive(Clone)]+struct Admission {terminated: Arc<AtomicBool>,/// SIGINT received since install. A `Cancels` scope shares the operation's/// flag and keeps observing it while children run; a `ChildInput` scope/// consults its own flag only until spawn commits admission.interrupted: Arc<AtomicBool>,- terminal_interrupt: TerminalInterrupt,scope: Arc<Interruption>,- lease: Lease,- registration: Registration,}/// Physical child status and independent foreground cancellation.@@ -318,65 +325,24 @@ impl ForegroundSignals {drop(activity);Ok(Self {signals,- terminated,- interrupted,+ admission: Admission {+ terminated,+ interrupted,+ scope,+ },terminal_interrupt,- scope,registration,lease: Lease(state),})}- /// Synchronously latched startup cancellation, before a listener exists.- pub fn interrupt_signal(&self) -> Option<i32> {- if self.terminated.load(Ordering::SeqCst) {- Some(SIGTERM)- } else {- self.scope- .signal()- .or_else(|| self.interrupted.load(Ordering::SeqCst).then_some(SIGINT))- }- }-/// Admission commits when spawn returns. A cancelled in-flight child may/// have missed the native key; retire only that uncommitted child with TERM./// Earlier admitted children finish native-key cleanup. Publish the admission/// origin before its teardown can report a different physical child signal.pub fn spawn(&self, command: &mut std::process::Command) -> anyhow::Result<SharedChild> {- if let Some(signal) = self.interrupt_signal() {- self.cancel_admission(signal);- return Err(crate::git::WorktrunkError::Interrupted { signal, hint: None }.into());- }- match crate::shell_exec::spawn_shared_child(command) {- Ok(child) => {- if let Some(signal) = self.interrupt_signal() {- self.cancel_admission(signal);- let _ = child.send_signal(SIGTERM);- let _ = child.send_signal(SIGCONT);- } else if tracing::enabled!(target: crate::trace::WT_TRACE_TARGET, tracing::Level::DEBUG)- {- crate::trace::instant(&format!("Foreground admitted:{}", child.id()));- }- Ok(child)- }- Err(error) => {- if let Some(signal) = self.interrupt_signal() {- self.cancel_admission(signal);- return Err(- crate::git::WorktrunkError::Interrupted { signal, hint: None }.into(),- );- }- Err(error.into())- }- }- }-- fn cancel_admission(&self, signal: i32) {- let _ =- self.scope- .admission- .compare_exchange(0, signal, Ordering::SeqCst, Ordering::SeqCst);- cancel_foreground(signal);+ let admission = self.admission.clone();+ crate::shell_exec::with_process_owner(command, move |command| admission.spawn(command))?}/// Wait for the owned direct child and stop its signal listener on every path.@@ -403,10 +369,13 @@ impl ForegroundSignals {let handle = self.signals.handle();let Self {mut signals,- terminated,- interrupted,+ admission:+ Admission {+ terminated,+ interrupted,+ scope,+ },terminal_interrupt,- scope,registration,lease,} = self;@@ -440,6 +409,55 @@ impl ForegroundSignals {}}+impl Admission {+ fn interrupt_signal(&self) -> Option<i32> {+ if self.terminated.load(Ordering::SeqCst) {+ Some(SIGTERM)+ } else {+ self.scope+ .signal()+ .or_else(|| self.interrupted.load(Ordering::SeqCst).then_some(SIGINT))+ }+ }++ fn spawn(&self, command: &mut std::process::Command) -> anyhow::Result<SharedChild> {+ if let Some(signal) = self.interrupt_signal() {+ self.cancel(signal);+ return Err(crate::git::WorktrunkError::Interrupted { signal, hint: None }.into());+ }+ match crate::shell_exec::spawn_shared_child_here(command) {+ Ok(child) => {+ if let Some(signal) = self.interrupt_signal() {+ self.cancel(signal);+ let _ = child.send_signal(SIGTERM);+ let _ = child.send_signal(SIGCONT);+ } else if tracing::enabled!(target: crate::trace::WT_TRACE_TARGET, tracing::Level::DEBUG)+ {+ crate::trace::instant(&format!("Foreground admitted:{}", child.id()));+ }+ Ok(child)+ }+ Err(error) => {+ if let Some(signal) = self.interrupt_signal() {+ self.cancel(signal);+ return Err(+ crate::git::WorktrunkError::Interrupted { signal, hint: None }.into(),+ );+ }+ Err(error.into())+ }+ }+ }++ fn cancel(&self, signal: i32) {+ let _ =+ self.scope+ .admission+ .compare_exchange(0, signal, Ordering::SeqCst, Ordering::SeqCst);+ cancel_foreground(signal);+ }+}+pub struct ActiveForwarder {handle: Handle,listener: Option<thread::JoinHandle<()>>,@@ -519,6 +537,171 @@ mod tests {use crate::git::ErrorExt;use crate::shell_exec::Cmd;+ /// Delay receipt before the flag callbacks, as when the kernel dequeues+ /// SIGINT onto a thread that is then descheduled. Admission must wait for+ /// that receipt instead of starting a child that missed the terminal key.+ #[test]+ #[allow(unsafe_code)]+ fn signal_receipt_and_child_admission_have_one_owner() {+ use nix::sys::signal::{SigSet, Signal, kill};+ use nix::unistd::Pid;+ use std::os::unix::process::CommandExt;+ use std::sync::mpsc;+ use std::time::{Duration, Instant};++ const CHILD_ENV: &str = "WORKTRUNK_TEST_SIGNAL_OWNER_CHILD";+ let mut signals = SigSet::empty();+ signals.add(Signal::SIGINT);+ signals.add(Signal::SIGTERM);+ if std::env::var_os(CHILD_ENV).is_none() {+ let mut command = std::process::Command::new(std::env::current_exe().unwrap());+ command+ .args([+ "--exact",+ "signal_forwarder::tests::signal_receipt_and_child_admission_have_one_owner",+ ])+ .env(CHILD_ENV, "1")+ .stdout(std::process::Stdio::piped())+ .stderr(std::process::Stdio::piped());+ // The child libtest harness also creates a thread before entering+ // this test. Keep that harness thread out of signal delivery.+ // SAFETY: pthread_sigmask is async-signal-safe and uses only the+ // already-built signal set after fork.+ unsafe {+ command.pre_exec(move || signals.thread_block().map_err(Into::into));+ }+ let output = crate::shell_exec::spawn(&mut command)+ .unwrap()+ .wait_with_output()+ .unwrap();+ let stdout = String::from_utf8_lossy(&output.stdout);+ let stderr = String::from_utf8_lossy(&output.stderr);+ assert!(output.status.success(), "{stdout}\n{stderr}");+ assert!(stdout.contains(" 1 passed;"), "{stdout}");+ return;+ }++ // This test thread stands in for main before it starts any workers.+ signals.thread_unblock().unwrap();+ crate::shell_exec::init_startup().unwrap();+ let operation = CommandOperation::start().unwrap();+ let entered = Arc::new(AtomicBool::new(false));+ let release = Arc::new(AtomicBool::new(false));+ struct Release(Arc<AtomicBool>);+ impl Drop for Release {+ fn drop(&mut self) {+ self.0.store(true, Ordering::SeqCst);+ }+ }+ let release_on_panic = Release(release.clone());+ let received = entered.clone();+ let released = release.clone();+ // SAFETY: the callback performs only lock-free atomic operations.+ let delayed = unsafe {+ signal_hook::low_level::register(SIGINT, move || {+ received.store(true, Ordering::SeqCst);+ while !released.load(Ordering::SeqCst) {+ std::hint::spin_loop();+ }+ })+ }+ .unwrap();+ let foreground = ForegroundSignals::install(TerminalInterrupt::Cancels).unwrap();+ kill(Pid::this(), Signal::SIGINT).unwrap();+ let deadline = Instant::now() + Duration::from_secs(20);+ while !entered.load(Ordering::SeqCst) {+ assert!(Instant::now() < deadline, "signal receiver did not run");+ thread::yield_now();+ }++ let temp = tempfile::tempdir().unwrap();+ let marker = temp.path().join("late-child");+ let child_marker = marker.clone();+ let (starting, started) = mpsc::channel();+ let admission = thread::spawn(move || {+ starting.send(()).unwrap();+ let mut command = std::process::Command::new("sh");+ command.args(["-c", "touch \"$1\"", "sh"]).arg(child_marker);+ let result = foreground.spawn(&mut command);+ // Always reap a child if the admission regression returns one.+ match result {+ Ok(child) => {+ child.wait().unwrap();+ None+ }+ Err(error) => error.interrupt_signal(),+ }+ });+ started.recv_timeout(Duration::from_secs(20)).unwrap();+ // Keep receipt delayed while the other thread attempts admission.+ thread::sleep(crate::testing::SLEEP_FOR_ABSENCE_CHECK);+ assert!(+ !marker.exists(),+ "child started before signal receipt finished"+ );+ drop(release_on_panic);+ assert_eq!(admission.join().unwrap(), Some(SIGINT));+ assert_eq!(operation.interrupt_signal(), Some(SIGINT));+ assert!(!marker.exists());+ signal_hook::low_level::unregister(delayed);++ // Plain captures share the owner too: their children must inherit the+ // original mask, and a reusable Command keeps its builder state.+ let mut command = std::process::Command::new("python3");+ command.args(["-c", "import signal; mask = signal.pthread_sigmask(signal.SIG_BLOCK, []); assert signal.SIGINT not in mask and signal.SIGTERM not in mask"]);+ for _ in 0..2 {+ assert!(+ crate::shell_exec::spawn(&mut command)+ .unwrap()+ .wait()+ .unwrap()+ .success()+ );+ }++ drop(operation);+ // A signal during spawn must retire an uncommitted child, or take+ // precedence over its exec error. Send TERM from pre_exec so receipt+ // falls between the owner's two admission checks in both cases.+ use std::os::unix::process::ExitStatusExt;+ let parent = Pid::this();+ for executable in [std::path::Path::new("sleep"), &temp.path().join("missing")] {+ let operation = CommandOperation::start().unwrap();+ let foreground = ForegroundSignals::install(TerminalInterrupt::Cancels).unwrap();+ assert_eq!(foreground.admission.interrupt_signal(), None);+ let mut command = std::process::Command::new(executable);+ command.arg("30");+ // SAFETY: kill is async-signal-safe; parent was captured before fork.+ unsafe {+ command.pre_exec(move || kill(parent, Signal::SIGTERM).map_err(Into::into));+ }+ match foreground.spawn(&mut command) {+ Ok(child) => {+ assert_eq!(executable, std::path::Path::new("sleep"));+ // No listener forwards TERM here: admission itself must+ // retire this child, which missed the signal sent to wt.+ assert_eq!(child.wait().unwrap().signal(), Some(SIGTERM));+ }+ Err(error) => {+ assert_eq!(executable, temp.path().join("missing"));+ assert_eq!(error.interrupt_signal(), Some(SIGTERM));+ }+ }+ assert_eq!(+ foreground.admission.scope.admission.load(Ordering::SeqCst),+ SIGTERM+ );+ assert_eq!(operation.interrupt_signal(), Some(SIGTERM));+ assert_eq!(+ foreground+ .spawn(&mut command)+ .unwrap_err()+ .interrupt_signal(),+ Some(SIGTERM)+ );+ }+ }+#[test]fn operation_cancellation_survives_scope_retirement_and_resets() {const CHILD_ENV: &str = "WORKTRUNK_OPERATION_LIFETIME_TEST_CHILD";