Skip to main content

muse_code_sdk/spawn/
child.rs

1use std::future::{Future, poll_fn};
2use std::io;
3use std::path::{Path, PathBuf};
4use std::process::{ExitStatus, Stdio};
5use std::task::Poll;
6use std::thread;
7use std::time::Duration;
8
9use tokio::process::{Child, ChildStdin, ChildStdout, Command};
10use tokio::sync::oneshot;
11
12use super::exit::{StderrTailBuffer, classify_status, drain_stderr, raw_exit};
13use super::{
14    CloseAttribution, ExitClassification, SIGTERM_GRACE, STDERR_DRAIN_TIMEOUT, SpawnError,
15    SpawnOptions, classify_exit, launch_error,
16};
17
18pub(super) fn launch(binary: PathBuf, options: SpawnOptions) -> Result<MuseChild, SpawnError> {
19    let (stderr_reader, stderr_writer) =
20        io::pipe().map_err(|source| launch_error(&binary, source))?;
21    let stderr_tail = StderrTailBuffer::default();
22    let drain_tail = stderr_tail.clone();
23    let (stderr_drained_tx, stderr_drained_rx) = oneshot::channel();
24    thread::Builder::new()
25        .name("muse-sdk-stderr".to_owned())
26        .spawn(move || {
27            drain_stderr(stderr_reader, drain_tail);
28            let _ = stderr_drained_tx.send(());
29        })
30        .map_err(|source| launch_error(&binary, source))?;
31
32    let mut command = Command::new(&binary);
33    command
34        .args(options.args)
35        .stdin(Stdio::piped())
36        .stdout(Stdio::piped())
37        .stderr(Stdio::from(stderr_writer))
38        .kill_on_drop(true);
39
40    if let Some(cwd) = options.cwd {
41        command.current_dir(cwd);
42    }
43    if let Some(environment) = options.env {
44        command.envs(environment);
45    }
46
47    let child = command
48        .spawn()
49        .map_err(|source| launch_error(&binary, source))?;
50    Ok(MuseChild {
51        binary,
52        child,
53        stderr_tail,
54        stderr_drained: Some(stderr_drained_rx),
55        close_attribution: None,
56        sent_signals: SentSignals::default(),
57        shutdown_timeout: options.shutdown_timeout,
58    })
59}
60
61/// The SDK-owned host process and its stdio handles.
62#[derive(Debug)]
63pub struct MuseChild {
64    binary: PathBuf,
65    child: Child,
66    stderr_tail: StderrTailBuffer,
67    stderr_drained: Option<oneshot::Receiver<()>>,
68    close_attribution: Option<CloseAttribution>,
69    sent_signals: SentSignals,
70    shutdown_timeout: Duration,
71}
72
73impl MuseChild {
74    /// The explicit or discovered binary used for this child.
75    #[must_use]
76    pub fn binary(&self) -> &Path {
77        &self.binary
78    }
79
80    /// OS process identifier, while the platform exposes one.
81    #[must_use]
82    pub fn id(&self) -> Option<u32> {
83        self.child.id()
84    }
85
86    /// Take the host's stdin for the connection transport.
87    pub fn take_stdin(&mut self) -> Option<ChildStdin> {
88        self.child.stdin.take()
89    }
90
91    /// Take the host's stdout for the connection transport.
92    pub fn take_stdout(&mut self) -> Option<ChildStdout> {
93        self.child.stdout.take()
94    }
95
96    /// Ask the OS to end the owned child without awaiting it.
97    pub fn start_kill(&mut self) -> io::Result<()> {
98        start_kill_lifecycle(
99            &mut self.child,
100            &mut self.close_attribution,
101            &mut self.sent_signals,
102        )
103        .map(|_| ())
104    }
105
106    /// End the owned child and wait until it has been reaped.
107    pub async fn kill(&mut self) -> io::Result<()> {
108        self.start_kill()?;
109        let exit = self.child.wait().await.map(raw_exit)?;
110        attribute_reaped_exit(&mut self.close_attribution, self.sent_signals, exit);
111        Ok(())
112    }
113
114    /// Read an already-observed host-initiated exit without blocking.
115    ///
116    /// Stderr evidence is best-effort because this synchronous path cannot
117    /// await the background drain's completion.
118    pub fn try_wait(&mut self) -> io::Result<Option<ExitClassification>> {
119        let Some(status) = self.child.try_wait()? else {
120            return Ok(None);
121        };
122        let attribution = attribute_reaped_exit(
123            &mut self.close_attribution,
124            self.sent_signals,
125            raw_exit(status),
126        );
127        Ok(Some(self.classify(status, attribution)))
128    }
129
130    /// Wait for a host-initiated exit and classify it with drained stderr.
131    pub async fn wait(&mut self) -> io::Result<ExitClassification> {
132        let status = self.child.wait().await?;
133        let attribution = attribute_reaped_exit(
134            &mut self.close_attribution,
135            self.sent_signals,
136            raw_exit(status),
137        );
138        self.wait_for_stderr_drain_until(tokio::time::Instant::now() + STDERR_DRAIN_TIMEOUT)
139            .await;
140        Ok(self.classify(status, attribution))
141    }
142
143    /// Close with the bounded ladder: end stdin, wait `shutdown_timeout` for
144    /// the host's own exit, `SIGTERM`, wait [`SIGTERM_GRACE`], `SIGKILL`, and
145    /// resolve only on the observed exit; then bound the post-exit stderr
146    /// drain by [`STDERR_DRAIN_TIMEOUT`]. Off Unix the first escalation is the
147    /// platform kill, the grace only spaces its repeat, and the reap stays
148    /// unbounded. Escalation reaches an exit and never classifies one: the
149    /// row is a function of the observed `(code, signal)`.
150    pub async fn close(&mut self) -> io::Result<ExitClassification> {
151        // A stdin the transport took is the transport's to end (the client
152        // closes its connection before the host); an untaken one ends here.
153        drop(self.child.stdin.take());
154        let (exit, attribution) = close_lifecycle(
155            &mut self.child,
156            &mut self.close_attribution,
157            &mut self.sent_signals,
158            tokio::time::sleep(self.shutdown_timeout),
159            || tokio::time::sleep(SIGTERM_GRACE),
160        )
161        .await?;
162        self.wait_for_stderr_drain_until(tokio::time::Instant::now() + STDERR_DRAIN_TIMEOUT)
163            .await;
164        let stderr_tail = self.stderr_tail.snapshot();
165        Ok(classify_exit(exit.0, exit.1, stderr_tail, attribution))
166    }
167
168    async fn wait_for_stderr_drain_until(&mut self, deadline: tokio::time::Instant) {
169        let Some(stderr_drained) = self.stderr_drained.as_mut() else {
170            return;
171        };
172        if wait_until_exit_or_deadline(stderr_drained, tokio::time::sleep_until(deadline))
173            .await
174            .is_some()
175        {
176            self.stderr_drained = None;
177        }
178    }
179
180    fn classify(&self, status: ExitStatus, attribution: CloseAttribution) -> ExitClassification {
181        classify_status(status, self.stderr_tail.snapshot(), attribution)
182    }
183}
184
185type RawExit = (Option<i32>, Option<i32>);
186
187#[cfg(unix)]
188const SDK_TERMINATE_SIGNAL: i32 = 15;
189#[cfg(unix)]
190const SDK_KILL_SIGNAL: i32 = 9;
191
192/// Which escalation signals the SDK has sent to the child. On Unix, `Ours`
193/// attribution needs the observed exit to carry one of them; elsewhere any
194/// accepted request counts, conservatively.
195#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
196struct SentSignals {
197    term: bool,
198    kill: bool,
199}
200
201trait ChildLifecycle {
202    fn try_wait_raw(&mut self) -> io::Result<Option<RawExit>>;
203    fn start_terminate(&mut self) -> io::Result<()>;
204    fn start_kill(&mut self) -> io::Result<()>;
205    async fn wait_raw(&mut self) -> io::Result<RawExit>;
206}
207
208impl ChildLifecycle for Child {
209    fn try_wait_raw(&mut self) -> io::Result<Option<RawExit>> {
210        self.try_wait().map(|status| status.map(raw_exit))
211    }
212
213    fn start_terminate(&mut self) -> io::Result<()> {
214        #[cfg(unix)]
215        {
216            use nix::errno::Errno;
217            use nix::sys::signal::{Signal, kill};
218            use nix::unistd::Pid;
219
220            // No pid means the child was already reaped; its exit is already
221            // observable, so there is nothing left to signal.
222            let Some(pid) = self.id() else {
223                return Ok(());
224            };
225            let pid = Pid::from_raw(i32::try_from(pid).map_err(io::Error::other)?);
226            match kill(pid, Signal::SIGTERM) {
227                // ESRCH: the process is gone between the pid read and the
228                // signal; the reap below observes its exit.
229                Ok(()) | Err(Errno::ESRCH) => Ok(()),
230                Err(errno) => Err(io::Error::from(errno)),
231            }
232        }
233        #[cfg(not(unix))]
234        {
235            // No SIGTERM on this platform: the first escalation is the kill.
236            Child::start_kill(self)
237        }
238    }
239
240    fn start_kill(&mut self) -> io::Result<()> {
241        Child::start_kill(self)
242    }
243
244    async fn wait_raw(&mut self) -> io::Result<RawExit> {
245        Child::wait(self).await.map(raw_exit)
246    }
247}
248
249fn start_terminate_lifecycle(
250    child: &mut impl ChildLifecycle,
251    attribution: &mut Option<CloseAttribution>,
252    sent: &mut SentSignals,
253) -> io::Result<Option<RawExit>> {
254    if let Some(exit) = child.try_wait_raw()? {
255        attribute_reaped_exit(attribution, *sent, exit);
256        return Ok(Some(exit));
257    }
258    child.start_terminate()?;
259    sent.term = true;
260    Ok(None)
261}
262
263fn start_kill_lifecycle(
264    child: &mut impl ChildLifecycle,
265    attribution: &mut Option<CloseAttribution>,
266    sent: &mut SentSignals,
267) -> io::Result<Option<RawExit>> {
268    if let Some(exit) = child.try_wait_raw()? {
269        attribute_reaped_exit(attribution, *sent, exit);
270        return Ok(Some(exit));
271    }
272    child.start_kill()?;
273    sent.kill = true;
274    Ok(None)
275}
276
277async fn wait_until_exit_or_deadline<T>(
278    wait: impl Future<Output = T>,
279    deadline: impl Future<Output = ()>,
280) -> Option<T> {
281    let mut wait = std::pin::pin!(wait);
282    let mut deadline = std::pin::pin!(deadline);
283    poll_fn(move |context| {
284        if let Poll::Ready(exit) = wait.as_mut().poll(context) {
285            return Poll::Ready(Some(exit));
286        }
287        if deadline.as_mut().poll(context).is_ready() {
288            return Poll::Ready(None);
289        }
290        Poll::Pending
291    })
292    .await
293}
294
295/// The close ladder: the host's own exit inside `drain_deadline`, else
296/// `SIGTERM`, the host's exit inside `grace`, else `SIGKILL` and the reap.
297/// Every rung ends on the child's real exit; a signal is a way to reach one.
298async fn close_lifecycle<Grace: Future<Output = ()>>(
299    child: &mut impl ChildLifecycle,
300    attribution: &mut Option<CloseAttribution>,
301    sent: &mut SentSignals,
302    drain_deadline: impl Future<Output = ()>,
303    grace: impl FnOnce() -> Grace,
304) -> io::Result<(RawExit, CloseAttribution)> {
305    if let Some(exit) = child.try_wait_raw()? {
306        return Ok((exit, attribute_reaped_exit(attribution, *sent, exit)));
307    }
308    if let Some(exit) = wait_until_exit_or_deadline(child.wait_raw(), drain_deadline).await {
309        let exit = exit?;
310        return Ok((exit, attribute_reaped_exit(attribution, *sent, exit)));
311    }
312    if let Some(exit) = start_terminate_lifecycle(child, attribution, sent)? {
313        return Ok((exit, attribute_reaped_exit(attribution, *sent, exit)));
314    }
315    if let Some(exit) = wait_until_exit_or_deadline(child.wait_raw(), grace()).await {
316        let exit = exit?;
317        return Ok((exit, attribute_reaped_exit(attribution, *sent, exit)));
318    }
319    if let Some(exit) = start_kill_lifecycle(child, attribution, sent)? {
320        return Ok((exit, attribute_reaped_exit(attribution, *sent, exit)));
321    }
322    let exit = child.wait_raw().await?;
323    Ok((exit, attribute_reaped_exit(attribution, *sent, exit)))
324}
325
326fn attribute_reaped_exit(
327    stored: &mut Option<CloseAttribution>,
328    sent: SentSignals,
329    exit: RawExit,
330) -> CloseAttribution {
331    #[cfg(unix)]
332    {
333        // A sent signal alone is not evidence that it won the race: the exit
334        // must carry one of the SDK's own signals, else it belongs to the host.
335        let ours = (sent.term && exit.1 == Some(SDK_TERMINATE_SIGNAL))
336            || (sent.kill && exit.1 == Some(SDK_KILL_SIGNAL));
337        let observed = if ours {
338            CloseAttribution::Ours
339        } else {
340            CloseAttribution::Theirs
341        };
342        remember(stored, observed)
343    }
344    #[cfg(not(unix))]
345    {
346        attribute_non_unix_reaped_exit(stored, sent, exit)
347    }
348}
349
350#[cfg(any(test, not(unix)))]
351fn attribute_non_unix_reaped_exit(
352    stored: &mut Option<CloseAttribution>,
353    sent: SentSignals,
354    _exit: RawExit,
355) -> CloseAttribution {
356    let observed = if sent.term || sent.kill {
357        CloseAttribution::Ours
358    } else {
359        CloseAttribution::Theirs
360    };
361    remember(stored, observed)
362}
363
364fn remember(stored: &mut Option<CloseAttribution>, observed: CloseAttribution) -> CloseAttribution {
365    *stored.get_or_insert(observed)
366}
367
368#[cfg(test)]
369mod tests {
370    use std::collections::VecDeque;
371    use std::future::{Future, pending, poll_fn, ready};
372    use std::io;
373    use std::task::{Context, Poll, Waker};
374
375    #[cfg(unix)]
376    use super::attribute_reaped_exit;
377    use super::{
378        ChildLifecycle, CloseAttribution, RawExit, SentSignals, StderrTailBuffer,
379        attribute_non_unix_reaped_exit, close_lifecycle, drain_stderr, remember,
380        start_kill_lifecycle,
381    };
382    use crate::spawn::STDERR_TAIL_LIMIT;
383
384    #[derive(Default)]
385    struct FakeChild {
386        try_waits: VecDeque<Option<RawExit>>,
387        waits: VecDeque<RawExit>,
388        /// The host runs until a signal reaches it; `ignores_terminate` makes
389        /// only the kill count.
390        pending_until_signal: bool,
391        ignores_terminate: bool,
392        terminate_error: Option<io::ErrorKind>,
393        kill_error: Option<io::ErrorKind>,
394        terminate_calls: usize,
395        kill_calls: usize,
396    }
397
398    impl FakeChild {
399        fn signalled(&self) -> bool {
400            if self.ignores_terminate {
401                self.kill_calls > 0
402            } else {
403                self.terminate_calls > 0 || self.kill_calls > 0
404            }
405        }
406    }
407
408    impl ChildLifecycle for FakeChild {
409        fn try_wait_raw(&mut self) -> io::Result<Option<RawExit>> {
410            Ok(self.try_waits.pop_front().flatten())
411        }
412
413        fn start_terminate(&mut self) -> io::Result<()> {
414            self.terminate_calls += 1;
415            if let Some(kind) = self.terminate_error.take() {
416                return Err(io::Error::from(kind));
417            }
418            Ok(())
419        }
420
421        fn start_kill(&mut self) -> io::Result<()> {
422            self.kill_calls += 1;
423            if let Some(kind) = self.kill_error.take() {
424                return Err(io::Error::from(kind));
425            }
426            Ok(())
427        }
428
429        async fn wait_raw(&mut self) -> io::Result<RawExit> {
430            poll_fn(|_| {
431                if self.pending_until_signal && !self.signalled() {
432                    return Poll::Pending;
433                }
434                let Some(exit) = self.waits.pop_front() else {
435                    return Poll::Pending;
436                };
437                Poll::Ready(Ok(exit))
438            })
439            .await
440        }
441    }
442
443    fn block_on_ready<F: Future>(future: F) -> Option<F::Output> {
444        let mut future = std::pin::pin!(future);
445        let mut context = Context::from_waker(Waker::noop());
446        match future.as_mut().poll(&mut context) {
447            Poll::Ready(output) => Some(output),
448            Poll::Pending => None,
449        }
450    }
451
452    fn settled_close(
453        result: Option<io::Result<(RawExit, CloseAttribution)>>,
454    ) -> Result<(RawExit, CloseAttribution), String> {
455        match result {
456            Some(Ok(pair)) => Ok(pair),
457            other => Err(format!("close did not settle causally: {other:?}")),
458        }
459    }
460
461    #[test]
462    fn drain_deadline_sends_sigterm_and_the_sigterm_exit_is_ours() -> Result<(), String> {
463        let mut child = FakeChild {
464            waits: VecDeque::from([(None, Some(15))]),
465            pending_until_signal: true,
466            ..FakeChild::default()
467        };
468        let mut stored_attribution = None;
469        let mut sent = SentSignals::default();
470        let (exit, attribution) = settled_close(block_on_ready(close_lifecycle(
471            &mut child,
472            &mut stored_attribution,
473            &mut sent,
474            ready(()),
475            pending,
476        )))?;
477        assert_eq!(exit, (None, Some(15)));
478        assert_eq!(attribution, CloseAttribution::Ours);
479        assert_eq!(stored_attribution, Some(CloseAttribution::Ours));
480        assert_eq!(child.terminate_calls, 1);
481        assert_eq!(child.kill_calls, 0);
482        assert!(sent.term);
483        assert!(!sent.kill);
484        Ok(())
485    }
486
487    #[cfg(unix)]
488    #[test]
489    fn close_deadline_accepted_kill_then_normal_exit_is_theirs() -> Result<(), String> {
490        // Both deadlines pass and the SDK reaches the kill rung, but the host
491        // exits normally: the accepted signals do not make that exit ours.
492        let exit = (Some(4), None);
493        let mut child = FakeChild {
494            waits: VecDeque::from([exit]),
495            pending_until_signal: true,
496            ignores_terminate: true,
497            ..FakeChild::default()
498        };
499        let mut stored_attribution = None;
500        let mut sent = SentSignals::default();
501
502        let (observed_exit, attribution) = settled_close(block_on_ready(close_lifecycle(
503            &mut child,
504            &mut stored_attribution,
505            &mut sent,
506            ready(()),
507            || ready(()),
508        )))?;
509
510        assert_eq!(observed_exit, exit);
511        assert_eq!(attribution, CloseAttribution::Theirs);
512        assert_eq!(stored_attribution, Some(CloseAttribution::Theirs));
513        assert!(sent.term);
514        assert!(sent.kill);
515        assert_eq!(child.terminate_calls, 1);
516        assert_eq!(child.kill_calls, 1);
517        Ok(())
518    }
519
520    #[test]
521    fn grace_deadline_escalates_to_sigkill_when_sigterm_is_ignored() -> Result<(), String> {
522        let mut child = FakeChild {
523            waits: VecDeque::from([(None, Some(9))]),
524            pending_until_signal: true,
525            ignores_terminate: true,
526            ..FakeChild::default()
527        };
528        let mut stored_attribution = None;
529        let mut sent = SentSignals::default();
530        let (exit, attribution) = settled_close(block_on_ready(close_lifecycle(
531            &mut child,
532            &mut stored_attribution,
533            &mut sent,
534            ready(()),
535            || ready(()),
536        )))?;
537        assert_eq!(exit, (None, Some(9)));
538        assert_eq!(attribution, CloseAttribution::Ours);
539        assert_eq!(stored_attribution, Some(CloseAttribution::Ours));
540        assert_eq!(child.terminate_calls, 1);
541        assert_eq!(child.kill_calls, 1);
542        assert!(sent.term);
543        assert!(sent.kill);
544        Ok(())
545    }
546
547    #[test]
548    fn host_that_catches_sigterm_and_exits_keeps_its_own_row_as_theirs() -> Result<(), String> {
549        let mut child = FakeChild {
550            waits: VecDeque::from([(Some(3), None)]),
551            pending_until_signal: true,
552            ..FakeChild::default()
553        };
554        let mut stored_attribution = None;
555        let mut sent = SentSignals::default();
556        let (exit, attribution) = settled_close(block_on_ready(close_lifecycle(
557            &mut child,
558            &mut stored_attribution,
559            &mut sent,
560            ready(()),
561            pending,
562        )))?;
563        assert_eq!(exit, (Some(3), None));
564        assert_eq!(attribution, CloseAttribution::Theirs);
565        assert_eq!(stored_attribution, Some(CloseAttribution::Theirs));
566        assert_eq!(child.terminate_calls, 1);
567        assert_eq!(child.kill_calls, 0);
568        Ok(())
569    }
570
571    #[test]
572    fn escalation_is_pending_until_reap() {
573        let mut child = FakeChild {
574            pending_until_signal: true,
575            ignores_terminate: true,
576            ..FakeChild::default()
577        };
578        let mut attribution = None;
579        let mut sent = SentSignals::default();
580
581        assert!(
582            block_on_ready(close_lifecycle(
583                &mut child,
584                &mut attribution,
585                &mut sent,
586                ready(()),
587                || ready(()),
588            ))
589            .is_none()
590        );
591
592        assert_eq!(attribution, None);
593        assert!(sent.term);
594        assert!(sent.kill);
595        assert_eq!(child.terminate_calls, 1);
596        assert_eq!(child.kill_calls, 1);
597    }
598
599    #[test]
600    fn already_exited_child_is_attributed_theirs_without_signals() -> Result<(), String> {
601        let mut child = FakeChild {
602            try_waits: VecDeque::from([Some((Some(3), None))]),
603            ..FakeChild::default()
604        };
605        let mut stored_attribution = None;
606        let mut sent = SentSignals::default();
607        let (exit, attribution) = settled_close(block_on_ready(close_lifecycle(
608            &mut child,
609            &mut stored_attribution,
610            &mut sent,
611            ready(()),
612            || ready(()),
613        )))?;
614        assert_eq!(exit.0, Some(3));
615        assert_eq!(attribution, CloseAttribution::Theirs);
616        assert_eq!(stored_attribution, Some(CloseAttribution::Theirs));
617        assert_eq!(child.terminate_calls, 0);
618        assert_eq!(child.kill_calls, 0);
619        Ok(())
620    }
621
622    #[cfg(unix)]
623    #[test]
624    fn external_sigkill_without_sdk_kill_request_is_theirs() -> Result<(), String> {
625        let exit = (None, Some(9));
626        let mut child = FakeChild {
627            try_waits: VecDeque::from([Some(exit)]),
628            ..FakeChild::default()
629        };
630        let mut stored_attribution = None;
631        let mut sent = SentSignals::default();
632
633        let (observed_exit, attribution) = settled_close(block_on_ready(close_lifecycle(
634            &mut child,
635            &mut stored_attribution,
636            &mut sent,
637            pending(),
638            || ready(()),
639        )))?;
640
641        assert_eq!(observed_exit, exit);
642        assert_eq!(attribution, CloseAttribution::Theirs);
643        assert_eq!(stored_attribution, Some(CloseAttribution::Theirs));
644        assert_eq!(sent, SentSignals::default());
645        assert_eq!(child.terminate_calls, 0);
646        assert_eq!(child.kill_calls, 0);
647        Ok(())
648    }
649
650    #[test]
651    fn start_kill_does_not_claim_an_already_exited_child() -> Result<(), String> {
652        let mut child = FakeChild {
653            try_waits: VecDeque::from([Some((Some(3), None))]),
654            ..FakeChild::default()
655        };
656        let mut attribution = None;
657        let mut sent = SentSignals::default();
658
659        start_kill_lifecycle(&mut child, &mut attribution, &mut sent)
660            .map_err(|error| format!("start_kill failed: {error}"))?;
661
662        assert_eq!(attribution, Some(CloseAttribution::Theirs));
663        assert!(!sent.kill);
664        assert_eq!(child.kill_calls, 0);
665        Ok(())
666    }
667
668    #[cfg(unix)]
669    #[test]
670    fn accepted_kill_of_normal_exit_uses_reaped_attribution() -> Result<(), String> {
671        let exit = (Some(4), None);
672        let mut child = FakeChild {
673            try_waits: VecDeque::from([None]),
674            waits: VecDeque::from([exit]),
675            ..FakeChild::default()
676        };
677        let mut attribution = None;
678        let mut sent = SentSignals::default();
679
680        let observed_before_reap = start_kill_lifecycle(&mut child, &mut attribution, &mut sent)
681            .map_err(|error| format!("start_kill failed: {error}"))?;
682        let Some(observed_after_reap) = block_on_ready(child.wait_raw()) else {
683            return Err("child did not expose its accepted normal exit".to_owned());
684        };
685        let observed_after_reap =
686            observed_after_reap.map_err(|error| format!("wait failed: {error}"))?;
687        let observed_attribution =
688            attribute_reaped_exit(&mut attribution, sent, observed_after_reap);
689
690        assert_eq!(observed_before_reap, None);
691        assert_eq!(observed_after_reap, exit);
692        assert_eq!(observed_attribution, CloseAttribution::Theirs);
693        assert_eq!(attribution, Some(CloseAttribution::Theirs));
694        assert!(sent.kill);
695        assert_eq!(child.kill_calls, 1);
696        Ok(())
697    }
698
699    #[cfg(unix)]
700    #[test]
701    fn only_a_signal_the_sdk_sent_is_attributed_ours() {
702        let term_only = SentSignals {
703            term: true,
704            kill: false,
705        };
706        let both = SentSignals {
707            term: true,
708            kill: true,
709        };
710        assert_eq!(
711            attribute_reaped_exit(&mut None, term_only, (None, Some(15))),
712            CloseAttribution::Ours
713        );
714        assert_eq!(
715            attribute_reaped_exit(&mut None, term_only, (None, Some(9))),
716            CloseAttribution::Theirs
717        );
718        assert_eq!(
719            attribute_reaped_exit(&mut None, both, (None, Some(15))),
720            CloseAttribution::Ours
721        );
722        assert_eq!(
723            attribute_reaped_exit(&mut None, both, (None, Some(9))),
724            CloseAttribution::Ours
725        );
726        assert_eq!(
727            attribute_reaped_exit(&mut None, both, (Some(3), None)),
728            CloseAttribution::Theirs
729        );
730        assert_eq!(
731            attribute_reaped_exit(&mut None, SentSignals::default(), (None, Some(15))),
732            CloseAttribution::Theirs
733        );
734    }
735
736    #[test]
737    fn non_unix_accepted_kill_uses_conservative_attribution() -> Result<(), String> {
738        let exit = (Some(4), None);
739        let mut child = FakeChild {
740            try_waits: VecDeque::from([None]),
741            waits: VecDeque::from([exit]),
742            ..FakeChild::default()
743        };
744        let mut attribution = None;
745        let mut sent = SentSignals::default();
746
747        let observed_before_reap = start_kill_lifecycle(&mut child, &mut attribution, &mut sent)
748            .map_err(|error| format!("start_kill failed: {error}"))?;
749        let Some(observed_after_reap) = block_on_ready(child.wait_raw()) else {
750            return Err("child did not expose its accepted non-Unix exit".to_owned());
751        };
752        let observed_after_reap =
753            observed_after_reap.map_err(|error| format!("wait failed: {error}"))?;
754        let observed_attribution =
755            attribute_non_unix_reaped_exit(&mut attribution, sent, observed_after_reap);
756
757        assert_eq!(observed_before_reap, None);
758        assert_eq!(observed_after_reap, exit);
759        assert_eq!(observed_attribution, CloseAttribution::Ours);
760        assert_eq!(attribution, Some(CloseAttribution::Ours));
761        assert!(sent.kill);
762        assert_eq!(child.kill_calls, 1);
763        Ok(())
764    }
765
766    #[test]
767    fn non_unix_exit_without_kill_is_attributed_theirs() {
768        let mut attribution = None;
769
770        let observed = attribute_non_unix_reaped_exit(
771            &mut attribution,
772            SentSignals::default(),
773            (Some(4), None),
774        );
775
776        assert_eq!(observed, CloseAttribution::Theirs);
777        assert_eq!(attribution, Some(CloseAttribution::Theirs));
778    }
779
780    #[test]
781    fn rejected_kill_keeps_attribution_unset_and_does_not_reap() {
782        let mut child = FakeChild {
783            try_waits: VecDeque::from([None, Some((Some(4), None))]),
784            waits: VecDeque::from([(Some(4), None)]),
785            kill_error: Some(io::ErrorKind::PermissionDenied),
786            ..FakeChild::default()
787        };
788        let mut attribution = None;
789        let mut sent = SentSignals::default();
790
791        let error = start_kill_lifecycle(&mut child, &mut attribution, &mut sent);
792
793        assert!(error.is_err_and(|error| error.kind() == io::ErrorKind::PermissionDenied));
794        assert_eq!(attribution, None);
795        assert!(!sent.kill);
796        assert_eq!(child.try_waits.len(), 1);
797        assert_eq!(child.waits.len(), 1);
798        assert_eq!(child.kill_calls, 1);
799    }
800
801    #[test]
802    fn rejected_sigterm_surfaces_the_error_without_escalating() {
803        let mut child = FakeChild {
804            try_waits: VecDeque::from([None, None]),
805            pending_until_signal: true,
806            terminate_error: Some(io::ErrorKind::PermissionDenied),
807            ..FakeChild::default()
808        };
809        let mut attribution = None;
810        let mut sent = SentSignals::default();
811
812        let result = block_on_ready(close_lifecycle(
813            &mut child,
814            &mut attribution,
815            &mut sent,
816            ready(()),
817            || ready(()),
818        ));
819
820        assert!(
821            matches!(result, Some(Err(error)) if error.kind() == io::ErrorKind::PermissionDenied)
822        );
823        assert_eq!(attribution, None);
824        assert!(!sent.term);
825        assert!(!sent.kill);
826        assert_eq!(child.terminate_calls, 1);
827        assert_eq!(child.kill_calls, 0);
828    }
829
830    #[test]
831    fn exit_after_drain_window_before_sigterm_is_theirs_without_signals() -> Result<(), String> {
832        let mut child = FakeChild {
833            try_waits: VecDeque::from([None, Some((Some(4), None))]),
834            pending_until_signal: true,
835            ..FakeChild::default()
836        };
837        let mut stored_attribution = None;
838        let mut sent = SentSignals::default();
839        let (exit, attribution) = settled_close(block_on_ready(close_lifecycle(
840            &mut child,
841            &mut stored_attribution,
842            &mut sent,
843            ready(()),
844            || ready(()),
845        )))?;
846
847        assert_eq!(exit, (Some(4), None));
848        assert_eq!(attribution, CloseAttribution::Theirs);
849        assert_eq!(stored_attribution, Some(CloseAttribution::Theirs));
850        assert_eq!(child.terminate_calls, 0);
851        assert_eq!(child.kill_calls, 0);
852        Ok(())
853    }
854
855    #[test]
856    fn late_sigterm_exit_seen_at_the_kill_rung_is_ours_without_a_kill() -> Result<(), String> {
857        let mut child = FakeChild {
858            try_waits: VecDeque::from([None, None, Some((None, Some(15)))]),
859            pending_until_signal: true,
860            ignores_terminate: true,
861            ..FakeChild::default()
862        };
863        let mut stored_attribution = None;
864        let mut sent = SentSignals::default();
865        let (exit, attribution) = settled_close(block_on_ready(close_lifecycle(
866            &mut child,
867            &mut stored_attribution,
868            &mut sent,
869            ready(()),
870            || ready(()),
871        )))?;
872
873        assert_eq!(exit, (None, Some(15)));
874        assert_eq!(attribution, CloseAttribution::Ours);
875        assert_eq!(stored_attribution, Some(CloseAttribution::Ours));
876        assert_eq!(child.terminate_calls, 1);
877        assert_eq!(child.kill_calls, 0);
878        assert!(sent.term);
879        assert!(!sent.kill);
880        Ok(())
881    }
882
883    #[test]
884    fn exit_inside_the_drain_window_sends_no_signal() -> Result<(), String> {
885        let mut child = FakeChild {
886            waits: VecDeque::from([(Some(0), None)]),
887            ..FakeChild::default()
888        };
889        let mut stored_attribution = None;
890        let mut sent = SentSignals::default();
891        let (exit, attribution) = settled_close(block_on_ready(close_lifecycle(
892            &mut child,
893            &mut stored_attribution,
894            &mut sent,
895            pending(),
896            || ready(()),
897        )))?;
898        assert_eq!(exit, (Some(0), None));
899        assert_eq!(attribution, CloseAttribution::Theirs);
900        assert_eq!(stored_attribution, Some(CloseAttribution::Theirs));
901        assert_eq!(child.terminate_calls, 0);
902        assert_eq!(child.kill_calls, 0);
903        Ok(())
904    }
905
906    #[test]
907    fn first_close_actor_remains_attributed() {
908        let mut attribution = None;
909        assert_eq!(
910            remember(&mut attribution, CloseAttribution::Ours),
911            CloseAttribution::Ours
912        );
913        assert_eq!(
914            remember(&mut attribution, CloseAttribution::Theirs),
915            CloseAttribution::Ours
916        );
917    }
918
919    #[test]
920    fn stderr_drain_keeps_only_the_bounded_tail() {
921        let bytes = [b"discarded-prefix".as_slice(), &vec![b'x'; 16 * 1024]].concat();
922        let buffer = StderrTailBuffer::default();
923
924        drain_stderr(io::Cursor::new(bytes), buffer.clone());
925
926        assert_eq!(buffer.len(), STDERR_TAIL_LIMIT);
927        assert_eq!(buffer.snapshot(), vec!["x".repeat(16 * 1024)]);
928    }
929}