fix: hold PTY_LOCK for entire Terminal lifetime on musl

Extend the musl PTY_LOCK to cover the complete Terminal session,
including I/O and background thread cleanup. Previously the lock
only covered spawn and FD cleanup, but concurrent PTY I/O also
triggers SIGSEGV in musl internals.

Key changes:
- Store MutexGuard in Terminal struct (held until drop)
- Add JoinOnDrop wrapper to join background cleanup thread before
  releasing the lock, preventing FD cleanup from racing with the
  next PTY session
- Drop order: reader/writer/child → join BG thread → release lock

https://claude.ai/code/session_011H8UR3gS6hoyQAf2x7Dfw8

Author: claude

crates/pty_terminal/src/terminal.rs

@@ -46,11 +46,42 @@ impl Clone for ChildHandle {
     }
 }
 
+/// On musl libc, concurrent PTY operations (openpty, fork, I/O, close) trigger
+/// SIGSEGV/SIGBUS in musl internals. This lock serializes the entire PTY session
+/// so that only one Terminal exists at a time, while allowing non-PTY tests to
+/// run in parallel.
+#[cfg(target_env = "musl")]
+static PTY_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+/// Wrapper that joins a thread on drop instead of detaching it.
+#[cfg(target_env = "musl")]
+struct JoinOnDrop(Option<thread::JoinHandle<()>>);
+
+#[cfg(target_env = "musl")]
+impl Drop for JoinOnDrop {
+    fn drop(&mut self) {
+        if let Some(handle) = self.0.take() {
+            let _ = handle.join();
+        }
+    }
+}
+
 /// A headless terminal consisting of a PTY reader, writer, and a child process handle.
+///
+/// On musl, fields are dropped in declaration order: reader/writer/child first,
+/// then background thread is joined, then PTY lock is released. This ensures
+/// all FD cleanup completes before the next PTY session can start.
 pub struct Terminal {
     pub pty_reader: PtyReader,
     pub pty_writer: PtyWriter,
     pub child_handle: ChildHandle,
+    /// On musl, join the background cleanup thread before releasing the PTY lock.
+    #[cfg(target_env = "musl")]
+    _bg_handle: JoinOnDrop,
+    /// On musl, holds the PTY lifecycle lock for the entire terminal session to
+    /// prevent concurrent PTY operations that trigger SIGSEGV in musl internals.
+    #[cfg(target_env = "musl")]
+    _pty_guard: std::sync::MutexGuard<'static, ()>,
 }
 
 struct Vt100Callbacks {
@@ -256,14 +287,8 @@ impl Terminal {
     ///
     /// Panics if the writer lock is poisoned when the background thread closes it.
     pub fn spawn(size: ScreenSize, cmd: CommandBuilder) -> anyhow::Result<Self> {
-        // On musl libc (Alpine Linux), concurrent PTY operations trigger
-        // SIGSEGV/SIGBUS in musl internals (sysconf, fcntl). This affects
-        // both openpty+fork and FD cleanup (close) from background threads.
-        // Serialize all PTY lifecycle operations that touch musl internals.
-        #[cfg(target_env = "musl")]
-        static PTY_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
         #[cfg(target_env = "musl")]
-        let _spawn_guard = PTY_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let pty_guard = PTY_LOCK.lock().unwrap_or_else(|e| e.into_inner());
 
         let pty_pair = portable_pty::native_pty_system().openpty(portable_pty::PtySize {
             rows: size.rows,
@@ -289,16 +314,12 @@ impl Terminal {
         // macOS then returns EIO on the master without draining the output buffer,
         // causing data loss. Holding the slave until the background thread takes
         // over guarantees the PTY stays connected while the child runs.
-        thread::spawn({
+        let bg_handle = thread::spawn({
             let writer = Arc::clone(&writer);
             let exit_status = Arc::clone(&exit_status);
             let slave = pty_pair.slave;
             move || {
                 let _ = exit_status.set(child.wait().map_err(Arc::new));
-                // On musl, serialize FD cleanup (close) with PTY spawn to
-                // prevent racing on musl-internal state.
-                #[cfg(target_env = "musl")]
-                let _cleanup_guard = PTY_LOCK.lock().unwrap_or_else(|e| e.into_inner());
                 // Close writer first, then drop slave to trigger EOF on the reader.
                 *writer.lock().unwrap() = None;
                 drop(slave);
@@ -315,10 +336,19 @@ impl Terminal {
             },
         )));
 
+        // Suppress unused-variable warning on non-musl targets where
+        // the handle is not stored in the struct.
+        #[cfg(not(target_env = "musl"))]
+        drop(bg_handle);
+
         Ok(Self {
             pty_reader: PtyReader { reader, parser: Arc::clone(&parser) },
             pty_writer: PtyWriter { writer, parser, master },
             child_handle: ChildHandle { child_killer, exit_status },
+            #[cfg(target_env = "musl")]
+            _bg_handle: JoinOnDrop(Some(bg_handle)),
+            #[cfg(target_env = "musl")]
+            _pty_guard: pty_guard,
         })
     }
 }