@team-agent/installer 0.5.63 → 0.5.65

package/crates/team-agent/src/messaging/wait.rs

@@ -0,0 +1,366 @@
+use std::path::Path;
+
+use serde_json::Value;
+
+use super::MessagingError;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WaitResult {
+    pub task_id: String,
+    pub result_id: String,
+    pub waited: bool,
+}
+
+impl WaitResult {
+    pub fn to_json(&self) -> Value {
+        serde_json::json!({
+            "ok": true,
+            "status": "completed",
+            "task_id": self.task_id,
+            "result_id": self.result_id,
+            "waited": self.waited,
+        })
+    }
+}
+
+#[cfg(not(unix))]
+pub fn wait_for_result(_workspace: &Path, _task_id: &str) -> Result<WaitResult, MessagingError> {
+    Err(MessagingError::Validation(
+        "wait --task requires POSIX FIFO support".to_string(),
+    ))
+}
+
+#[cfg(unix)]
+mod unix {
+    use std::ffi::CString;
+    use std::fs::{File, OpenOptions};
+    use std::io::{self, Read};
+    use std::os::fd::{AsRawFd, RawFd};
+    use std::os::unix::fs::OpenOptionsExt;
+    use std::path::{Path, PathBuf};
+    use std::sync::atomic::{AtomicI32, Ordering};
+
+    use rusqlite::{params, OptionalExtension};
+
+    use crate::event_log::EventLog;
+    use crate::message_store::MessageStore;
+
+    use super::{MessagingError, WaitResult};
+
+    static CAUGHT_SIGNAL: AtomicI32 = AtomicI32::new(0);
+
+    enum Registration {
+        Completed(String),
+        Pending,
+    }
+
+    struct FifoEndpoints {
+        path: PathBuf,
+        reader: File,
+        _keepalive_writer: File,
+    }
+
+    impl Drop for FifoEndpoints {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_file(&self.path);
+        }
+    }
+
+    struct RegistrationCleanup {
+        db_path: PathBuf,
+        watcher_id: String,
+        active: bool,
+    }
+
+    impl RegistrationCleanup {
+        fn cleanup(&mut self) -> Result<(), MessagingError> {
+            if self.active {
+                let conn = crate::db::schema::open_db(&self.db_path)?;
+                conn.execute(
+                    "delete from result_watchers where watcher_id = ?1",
+                    params![self.watcher_id],
+                )?;
+                self.active = false;
+            }
+            Ok(())
+        }
+    }
+
+    impl Drop for RegistrationCleanup {
+        fn drop(&mut self) {
+            if self.active {
+                if let Ok(conn) = crate::db::schema::open_db(&self.db_path) {
+                    let _ = conn.execute(
+                        "delete from result_watchers where watcher_id = ?1",
+                        params![self.watcher_id],
+                    );
+                }
+            }
+        }
+    }
+
+    struct SignalGuard {
+        old_int: libc::sigaction,
+        old_term: libc::sigaction,
+    }
+
+    impl SignalGuard {
+        fn install() -> io::Result<Self> {
+            CAUGHT_SIGNAL.store(0, Ordering::SeqCst);
+            let mut action: libc::sigaction = unsafe { std::mem::zeroed() };
+            action.sa_sigaction = record_signal as *const () as libc::sighandler_t;
+            action.sa_flags = 0;
+            unsafe {
+                libc::sigemptyset(&mut action.sa_mask);
+            }
+            let mut old_int: libc::sigaction = unsafe { std::mem::zeroed() };
+            let mut old_term: libc::sigaction = unsafe { std::mem::zeroed() };
+            if unsafe { libc::sigaction(libc::SIGINT, &action, &mut old_int) } != 0 {
+                return Err(io::Error::last_os_error());
+            }
+            if unsafe { libc::sigaction(libc::SIGTERM, &action, &mut old_term) } != 0 {
+                let error = io::Error::last_os_error();
+                unsafe {
+                    libc::sigaction(libc::SIGINT, &old_int, std::ptr::null_mut());
+                }
+                return Err(error);
+            }
+            Ok(Self { old_int, old_term })
+        }
+    }
+
+    impl Drop for SignalGuard {
+        fn drop(&mut self) {
+            unsafe {
+                libc::sigaction(libc::SIGINT, &self.old_int, std::ptr::null_mut());
+                libc::sigaction(libc::SIGTERM, &self.old_term, std::ptr::null_mut());
+            }
+        }
+    }
+
+    extern "C" fn record_signal(signal: libc::c_int) {
+        CAUGHT_SIGNAL.store(signal, Ordering::SeqCst);
+    }
+
+    pub fn wait_for_result(workspace: &Path, task_id: &str) -> Result<WaitResult, MessagingError> {
+        if task_id.trim().is_empty() {
+            return Err(MessagingError::Validation(
+                "wait --task requires a non-empty task id".to_string(),
+            ));
+        }
+        let _signals = SignalGuard::install()?;
+        let store = MessageStore::open(workspace)?;
+        let workspace = std::fs::canonicalize(workspace)?;
+        let watcher_id = format!("wait-{}", random_suffix()?);
+        let fifo_path = fifo_path(&workspace, task_id, &watcher_id)?;
+        let fifo = create_fifo(&fifo_path)?;
+        let conn = crate::db::schema::open_db(store.db_path())?;
+        let registration = register(&conn, &watcher_id, task_id, &fifo_path)?;
+        if let Registration::Completed(result_id) = registration {
+            return Ok(WaitResult {
+                task_id: task_id.to_string(),
+                result_id,
+                waited: false,
+            });
+        }
+
+        let mut cleanup = RegistrationCleanup {
+            db_path: store.db_path().to_path_buf(),
+            watcher_id: watcher_id.clone(),
+            active: true,
+        };
+        EventLog::new(&workspace).write(
+            "result_wake.registered",
+            serde_json::json!({
+                "task_id": task_id,
+                "watcher_id": watcher_id,
+                "recipient": fifo_path,
+            }),
+        )?;
+        let result_id = read_wake_line(fifo.reader.as_raw_fd())?;
+        cleanup.cleanup()?;
+        Ok(WaitResult {
+            task_id: task_id.to_string(),
+            result_id,
+            waited: true,
+        })
+    }
+
+    fn register(
+        conn: &rusqlite::Connection,
+        watcher_id: &str,
+        task_id: &str,
+        fifo_path: &Path,
+    ) -> Result<Registration, MessagingError> {
+        conn.execute_batch("BEGIN IMMEDIATE")?;
+        let operation = (|| -> Result<Registration, MessagingError> {
+            let completed = conn
+                .query_row(
+                    "select result_id from results
+                     where task_id = ?1 order by created_at, result_id limit 1",
+                    params![task_id],
+                    |row| row.get::<_, String>(0),
+                )
+                .optional()?;
+            if let Some(result_id) = completed {
+                return Ok(Registration::Completed(result_id));
+            }
+            conn.execute(
+                "insert into result_watchers(
+                     watcher_id, owner_team_id, task_id, agent_id, message_id,
+                     leader_id, recipient, status, created_at
+                 ) values (?1, null, ?2, null, null, 'team-agent', ?3, 'pending', ?4)",
+                params![
+                    watcher_id,
+                    task_id,
+                    fifo_path.to_string_lossy().as_ref(),
+                    chrono::Utc::now().to_rfc3339(),
+                ],
+            )?;
+            Ok(Registration::Pending)
+        })();
+        match operation {
+            Ok(registration) => match conn.execute_batch("COMMIT") {
+                Ok(()) => Ok(registration),
+                Err(error) => {
+                    let _ = conn.execute_batch("ROLLBACK");
+                    Err(error.into())
+                }
+            },
+            Err(error) => {
+                let _ = conn.execute_batch("ROLLBACK");
+                Err(error)
+            }
+        }
+    }
+
+    fn fifo_path(
+        workspace: &Path,
+        task_id: &str,
+        watcher_id: &str,
+    ) -> Result<PathBuf, MessagingError> {
+        let dir = workspace.join(".team/runtime/wake");
+        std::fs::create_dir_all(&dir)?;
+        let task = task_id
+            .chars()
+            .map(|ch| {
+                if ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_') {
+                    ch
+                } else {
+                    '_'
+                }
+            })
+            .take(80)
+            .collect::<String>();
+        let task = if task.is_empty() { "task" } else { &task };
+        Ok(dir.join(format!("{task}-{watcher_id}.fifo")))
+    }
+
+    fn random_suffix() -> Result<String, MessagingError> {
+        let mut bytes = [0_u8; 16];
+        File::open("/dev/urandom")?.read_exact(&mut bytes)?;
+        Ok(bytes.iter().map(|byte| format!("{byte:02x}")).collect())
+    }
+
+    fn create_fifo(path: &Path) -> Result<FifoEndpoints, MessagingError> {
+        let c_path = CString::new(path.as_os_str().as_encoded_bytes())
+            .map_err(|_| MessagingError::Validation("FIFO path contains a NUL byte".to_string()))?;
+        if unsafe { libc::mkfifo(c_path.as_ptr(), 0o600) } != 0 {
+            return Err(io::Error::last_os_error().into());
+        }
+        let reader = match OpenOptions::new()
+            .read(true)
+            .custom_flags(libc::O_NONBLOCK)
+            .open(path)
+        {
+            Ok(reader) => reader,
+            Err(error) => {
+                let _ = std::fs::remove_file(path);
+                return Err(error.into());
+            }
+        };
+        let keepalive_writer = match OpenOptions::new()
+            .write(true)
+            .custom_flags(libc::O_NONBLOCK)
+            .open(path)
+        {
+            Ok(writer) => writer,
+            Err(error) => {
+                let _ = std::fs::remove_file(path);
+                return Err(error.into());
+            }
+        };
+        set_blocking(reader.as_raw_fd())?;
+        Ok(FifoEndpoints {
+            path: path.to_path_buf(),
+            reader,
+            _keepalive_writer: keepalive_writer,
+        })
+    }
+
+    fn set_blocking(fd: RawFd) -> io::Result<()> {
+        let flags = unsafe { libc::fcntl(fd, libc::F_GETFL) };
+        if flags < 0 {
+            return Err(io::Error::last_os_error());
+        }
+        if unsafe { libc::fcntl(fd, libc::F_SETFL, flags & !libc::O_NONBLOCK) } < 0 {
+            return Err(io::Error::last_os_error());
+        }
+        Ok(())
+    }
+
+    fn read_wake_line(fd: RawFd) -> Result<String, MessagingError> {
+        let mut line = Vec::new();
+        loop {
+            if let Some(signal) = caught_signal() {
+                return Err(interrupted(signal).into());
+            }
+            let mut bytes = [0_u8; 256];
+            let count =
+                unsafe { libc::read(fd, bytes.as_mut_ptr().cast::<libc::c_void>(), bytes.len()) };
+            if count > 0 {
+                line.extend_from_slice(&bytes[..count as usize]);
+                if let Some(newline) = line.iter().position(|byte| *byte == b'\n') {
+                    line.truncate(newline);
+                    let result_id = String::from_utf8(line).map_err(|error| {
+                        MessagingError::Validation(format!("invalid FIFO wake line: {error}"))
+                    })?;
+                    let result_id = result_id.trim().to_string();
+                    if result_id.is_empty() {
+                        return Err(MessagingError::Validation(
+                            "FIFO wake line did not contain a result id".to_string(),
+                        ));
+                    }
+                    return Ok(result_id);
+                }
+                continue;
+            }
+            if count == 0 {
+                continue;
+            }
+            let error = io::Error::last_os_error();
+            if error.kind() == io::ErrorKind::Interrupted {
+                if let Some(signal) = caught_signal() {
+                    return Err(interrupted(signal).into());
+                }
+                continue;
+            }
+            return Err(error.into());
+        }
+    }
+
+    fn caught_signal() -> Option<i32> {
+        let signal = CAUGHT_SIGNAL.load(Ordering::SeqCst);
+        (signal != 0).then_some(signal)
+    }
+
+    fn interrupted(signal: i32) -> io::Error {
+        io::Error::new(
+            io::ErrorKind::Interrupted,
+            format!("wait interrupted by signal {signal}"),
+        )
+    }
+}
+
+#[cfg(unix)]
+pub use unix::wait_for_result;

package/crates/team-agent/src/messaging/watchers.rs

@@ -2,6 +2,13 @@
 
 use std::path::Path;
 
+#[cfg(unix)]
+use std::fs::OpenOptions;
+#[cfg(unix)]
+use std::io::Write as _;
+#[cfg(unix)]
+use std::os::unix::fs::OpenOptionsExt;
+
 use rusqlite::{params, OptionalExtension};
 
 use crate::event_log::EventLog;
@@ -119,6 +126,128 @@ fn watcher_matches(
     task_matches && agent_matches
 }
 
+pub(crate) fn notify_fifo_result_watchers(
+    conn: &rusqlite::Connection,
+    event_log: &EventLog,
+    task_id: &str,
+    result_id: &str,
+) -> Result<(), MessagingError> {
+    let mut stmt = conn.prepare(
+        "select watcher_id, recipient from result_watchers
+         where task_id = ?1 and status = 'pending' and recipient is not null
+         order by created_at, watcher_id",
+    )?;
+    let rows = stmt
+        .query_map(params![task_id], |row| {
+            Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
+        })?
+        .collect::<Result<Vec<_>, _>>()?;
+    drop(stmt);
+    for (watcher_id, recipient) in rows {
+        let _ = notify_fifo_waiter(conn, event_log, &watcher_id, task_id, result_id, &recipient)?;
+    }
+    Ok(())
+}
+
+#[cfg(unix)]
+fn notify_fifo_waiter(
+    conn: &rusqlite::Connection,
+    event_log: &EventLog,
+    watcher_id: &str,
+    task_id: &str,
+    result_id: &str,
+    recipient: &str,
+) -> Result<WatcherNotice, MessagingError> {
+    let write = (|| -> std::io::Result<()> {
+        let mut fifo = OpenOptions::new()
+            .write(true)
+            .custom_flags(libc::O_NONBLOCK)
+            .open(recipient)?;
+        fifo.write_all(format!("{result_id}\n").as_bytes())
+    })();
+    match write {
+        Ok(()) => {
+            event_log.write(
+                "result_wake.notified",
+                serde_json::json!({
+                    "task_id": task_id,
+                    "result_id": result_id,
+                    "watcher_id": watcher_id,
+                    "recipient": recipient,
+                }),
+            )?;
+            Ok(WatcherNotice {
+                watcher_id: watcher_id.to_string(),
+                result_id: Some(result_id.to_string()),
+                ok: true,
+                status: Some("notified".to_string()),
+                notified_message_id: None,
+                primary_watcher_id: None,
+                prior_state: None,
+                error: None,
+            })
+        }
+        Err(error)
+            if matches!(
+                error.raw_os_error(),
+                Some(code) if code == libc::ENXIO || code == libc::ENOENT
+            ) =>
+        {
+            let reason = if error.raw_os_error() == Some(libc::ENXIO) {
+                "ENXIO"
+            } else {
+                "ENOENT"
+            };
+            conn.execute(
+                "delete from result_watchers where watcher_id = ?1",
+                params![watcher_id],
+            )?;
+            event_log.write(
+                "result_wake.notify_failed",
+                serde_json::json!({
+                    "task_id": task_id,
+                    "result_id": result_id,
+                    "watcher_id": watcher_id,
+                    "recipient": recipient,
+                    "reason": reason,
+                }),
+            )?;
+            Ok(WatcherNotice {
+                watcher_id: watcher_id.to_string(),
+                result_id: Some(result_id.to_string()),
+                ok: false,
+                status: Some("removed".to_string()),
+                notified_message_id: None,
+                primary_watcher_id: None,
+                prior_state: None,
+                error: Some(reason.to_string()),
+            })
+        }
+        Err(error) => Err(error.into()),
+    }
+}
+
+#[cfg(not(unix))]
+fn notify_fifo_waiter(
+    _conn: &rusqlite::Connection,
+    _event_log: &EventLog,
+    watcher_id: &str,
+    _task_id: &str,
+    result_id: &str,
+    _recipient: &str,
+) -> Result<WatcherNotice, MessagingError> {
+    Ok(WatcherNotice {
+        watcher_id: watcher_id.to_string(),
+        result_id: Some(result_id.to_string()),
+        ok: false,
+        status: Some("unsupported".to_string()),
+        notified_message_id: None,
+        primary_watcher_id: None,
+        prior_state: None,
+        error: Some("POSIX FIFO support unavailable".to_string()),
+    })
+}
+
 fn deliver_primary_watcher(
     workspace: &Path,
     conn: &rusqlite::Connection,
@@ -143,6 +272,20 @@ fn deliver_primary_watcher(
             "missing_result_id",
         );
     };
+    if let Some(recipient) = watcher
+        .get("recipient")
+        .and_then(|value| value.as_str())
+        .filter(|recipient| Path::new(recipient).is_absolute())
+    {
+        return notify_fifo_waiter(
+            conn,
+            event_log,
+            watcher_id,
+            result_task.unwrap_or_default(),
+            result_id,
+            recipient,
+        );
+    }
     if let Some(existing) = delivered_result_message(
         store,
         result_id,
@@ -196,7 +339,10 @@ fn deliver_primary_watcher(
             .get("leader_id")
             .and_then(|v| v.as_str())
             .unwrap_or("team-agent"),
-        "leader",
+        watcher
+            .get("recipient")
+            .and_then(|value| value.as_str())
+            .unwrap_or("leader"),
         &content,
         None,
         false,
@@ -332,7 +478,7 @@ pub fn retry_result_deliveries(
     // delivery path with dedupe/attempt bounds); a watcher is never flipped to
     // `notified` without a delivery. Missing result rows are skipped (still retryable).
     let mut stmt = conn.prepare(
-        "select watcher_id, owner_team_id, task_id, agent_id, leader_id, status, created_at,
+        "select watcher_id, owner_team_id, task_id, agent_id, leader_id, recipient, status, created_at,
                 result_id, notified_message_id
          from result_watchers
          where status in ('pending', 'notify_failed')
@@ -346,10 +492,11 @@ pub fn retry_result_deliveries(
                 "task_id": row.get::<_, Option<String>>(2)?,
                 "agent_id": row.get::<_, Option<String>>(3)?,
                 "leader_id": row.get::<_, Option<String>>(4)?,
-                "status": row.get::<_, Option<String>>(5)?,
-                "created_at": row.get::<_, Option<String>>(6)?,
-                "result_id": row.get::<_, Option<String>>(7)?,
-                "notified_message_id": row.get::<_, Option<String>>(8)?,
+                "recipient": row.get::<_, Option<String>>(5)?,
+                "status": row.get::<_, Option<String>>(6)?,
+                "created_at": row.get::<_, Option<String>>(7)?,
+                "result_id": row.get::<_, Option<String>>(8)?,
+                "notified_message_id": row.get::<_, Option<String>>(9)?,
             }))
         })?
         .collect::<Result<Vec<_>, _>>()?;

package/crates/team-agent/src/tmux_backend.rs

@@ -1723,8 +1723,8 @@ pub fn worker_provider_exit_marker(provider_label: &str) -> String {
 /// as a CHILD of a long-lived shell so provider exit does NOT collapse the
 /// worker pane (which under upstream tmux 3.6a private-server bugs can
 /// cascade into whole-server death). When the provider exits, the worker
-/// pane returns to an interactive shell with an explicit worker exit
-/// marker, matching manual `tmux new-window` then `<provider>` behaviour.
+/// pane remains alive with an explicit worker exit marker, then runs an
+/// inert `sh` tail that does not read terminal input.
 pub fn worker_shell_wrapper_command(
     argv: &[String],
     cwd: &Path,
@@ -1758,23 +1758,21 @@ pub fn worker_shell_wrapper_command(
         worker_provider_exit_marker(provider_label)
     )));
     parts.push("\"$rc\";".to_string());
-    parts.push("exec".to_string());
-    parts.push("\"${SHELL:-/bin/zsh}\"".to_string());
-    parts.push("-l".to_string());
+    parts.push(inert_pane_tail_command());
     parts.join(" ")
 }
 
 /// 0.4.x (CR C-2): leader shell wrapper — provider runs as a CHILD of a
 /// long-lived shell, not as the pane's primary process. When the provider
-/// exits, the pane returns to an interactive shell with an explicit exit
-/// marker, matching manual `tmux new-session` then `claude` behaviour.
+/// exits, the pane remains alive with an explicit exit marker, then runs an
+/// inert `sh` tail that does not read terminal input.
 ///
 /// Four required envelope sections (CR C-2):
 ///   1. cd <cwd>                    — same as `shell_command`
 ///   2. unset <KEY> ...             — provider env_unset block
 ///   3. KEY=val ... <provider>      — env exports + provider invocation
 ///                                    (NO `exec` — runs as child)
-///   4. printf exit marker; exec shell -l
+///   4. printf exit marker; exec inert sh tail
 ///
 /// `provider_label` is a human-readable provider name (e.g. "claude",
 /// "codex") embedded in the exit marker for diagnostics.
@@ -1809,7 +1807,7 @@ pub fn leader_shell_wrapper_command(
     }
     parts.extend(argv.iter().map(|arg| shell_quote(arg)));
     parts.push(";".to_string());
-    // 4. exit marker + fall back to interactive shell
+    // 4. exit marker + inert shell tail
     parts.push("rc=$?;".to_string());
     parts.push("printf".to_string());
     // CR R6: marker text comes from single-source `leader_provider_exit_marker`.
@@ -1818,12 +1816,18 @@ pub fn leader_shell_wrapper_command(
         leader_provider_exit_marker(provider_label)
     )));
     parts.push("\"$rc\";".to_string());
-    parts.push("exec".to_string());
-    parts.push("\"${SHELL:-/bin/zsh}\"".to_string());
-    parts.push("-l".to_string());
+    parts.push(inert_pane_tail_command());
     parts.join(" ")
 }
 
+fn inert_pane_tail_command() -> String {
+    // `sh` is deliberate: provider-exit health checks use the shell basename
+    // to reach the exit-marker branch. `sh -c` does not read commands from
+    // stdin; disabling echo also prevents input from appearing accepted.
+    let script = r#"trap '' INT QUIT; stty -echo 2>/dev/null; printf "%s\n" "[team-agent] Provider exited; this pane no longer accepts input. Restart from another pane with the appropriate team-agent start command."; while :; do sleep 3600 & wait "$!"; done"#;
+    format!("exec /bin/sh -c {}", shell_quote(script))
+}
+
 fn shell_quote(raw: &str) -> String {
     if raw.is_empty() {
         return "''".to_string();

package/crates/team-agent/src/transport.rs

@@ -613,11 +613,11 @@ pub trait Transport: Send + Sync {
     /// variant that reuses the leader-wrapper mechanism so worker provider
     /// exit does not collapse the pane into `[exited]` (which under
     /// upstream tmux 3.6a private-server bugs can cascade into server
-    /// death). When the provider exits, the worker pane returns to an
-    /// interactive shell with an explicit worker exit marker — matching
-    /// manual `tmux new-window` then `<provider>` behaviour. Default falls
-    /// back to plain `spawn_first_with_env_unset` for backends that have
-    /// no shell layer (test-only `OfflineTransport`).
+    /// death). When the provider exits, the worker pane keeps an explicit
+    /// worker exit marker and runs the inert `/bin/sh -c` tail: it ignores
+    /// INT/QUIT and does not read pane stdin. Default falls back to plain
+    /// `spawn_first_with_env_unset` for backends that have no shell layer
+    /// (test-only `OfflineTransport`).
     fn spawn_first_with_worker_shell_wrapper(
         &self,
         session: &SessionName,
@@ -650,12 +650,12 @@ pub trait Transport: Send + Sync {
     /// 0.4.x (CR C-2): leader-specific spawn variant. Instead of `exec <cmd>`
     /// (which makes the provider the pane's primary process and turns the
     /// pane into `[exited]` when the provider exits), build a shell line
-    /// that runs the provider as a CHILD of a long-lived shell:
-    /// `cd ... && unset ... && KEY=val ... <cmd>; rc=$?; printf '\n[team-agent] <provider> exited with %s\n' "$rc"; exec "${SHELL:-/bin/zsh}" -l`.
-    /// When the provider exits, the pane returns to an interactive shell with
-    /// an explicit exit marker — matching manual `tmux new-session` then
-    /// `claude` behaviour. Default falls back to plain `spawn_first_with_env_unset`
-    /// for backends that have no shell layer (test-only `OfflineTransport`).
+    /// that runs the provider as a CHILD of a long-lived shell. When the
+    /// provider exits, the wrapper records the exit code and marker, then
+    /// execs an inert `/bin/sh -c` tail that ignores INT/QUIT and does not
+    /// read pane stdin. Default falls back to plain
+    /// `spawn_first_with_env_unset` for backends that have no shell layer
+    /// (test-only `OfflineTransport`).
     fn spawn_first_with_leader_shell_wrapper(
         &self,
         session: &SessionName,